feat(client): sell cosmetic packs as store bundles

Client side of the cosmetic-packs handoff (API #564 catalog, #567 purchase):
parse `packs` from cosmetics.json, resolve each pack's items and ownership
(any owned item blocks the purchase, matching the server's 409), add a
Bundles tab to the store, and buy through POST /shop/purchase/pack with
every documented response mapped to a player-facing outcome.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: evanpelle

resources/lang/en.json

@@ -455,6 +455,8 @@
     "free": "+{numFree} BONUS!",
     "hard": "Plutonium",
     "legendary": "Legendary",
+    "pack_includes": "Includes:",
+    "pack_more_items": "+{count} more",
     "per_day": "/day",
     "public_lobbies": "Public lobbies",
     "public_lobbies_info": "Host custom lobbies that are publicly listed for anyone to join.",
@@ -1608,6 +1610,7 @@
   },
   "store": {
     "already_subscribed": "Already subscribed.",
+    "bundles": "Bundles",
     "change_tier_failed": "Couldn't update your subscription. Please try again.",
     "change_tier_rate_limited": "You just changed tiers. Please wait a minute before changing again.",
     "change_tier_success": "Switched to {tier}.",
@@ -1630,13 +1633,19 @@
     "merch_blurb": "Get OpenFront merch shipped to your door!",
     "merch_visit_store": "Visit Store",
     "no_affiliate_items": "No affiliate items available. Check back later for new items.",
+    "no_bundles": "No bundles available. Check back later for new items.",
     "no_crowns": "No crowns available. Check back later for new items.",
     "no_effects": "No effects available. Check back later for new items.",
     "no_flags": "No flags available. Check back later for new items.",
     "no_packs": "No packs available. Check back later for new items.",
     "no_skins": "No skins available. Check back later for new items.",
     "no_subscriptions": "No subscriptions available. Check back later for new items.",
     "no_tribes": "You haven't bought any tribe names yet.",
+    "pack_already_owned": "You already own {items}. Nothing was charged.",
+    "pack_debt": "Your Plutonium balance is {debt} in debt. Settle it before buying.",
+    "pack_owned": "Owned",
+    "pack_partially_owned": "Already own {items}",
+    "pack_unavailable": "This bundle is no longer available.",
     "packs": "Packs",
     "patterns": "Skins",
     "plutonium_amount": "Plutonium amount",

src/client/Api.ts

@@ -20,6 +20,8 @@ import {
   PostTribeNameResponseSchema,
   PublicPlayerGamesResponse,
   PublicPlayerGamesResponseSchema,
+  PurchasePackResponse,
+  PurchasePackResponseSchema,
   PutUsernameResponse,
   PutUsernameResponseSchema,
   RankedLeaderboardResponse,
@@ -647,6 +649,99 @@ export async function purchaseWithCurrency(
   }
 }
 
+export type PurchaseCosmeticPackResult =
+  | { ok: true; data: PurchasePackResponse }
+  // 400 "Insufficient balance": the balance moved since the client's
+  // pre-check. Nothing charged.
+  | { ok: false; code: "insufficient_balance" }
+  // 400 insufficient_balance_debt: a refund/chargeback left the wallet
+  // negative; `debt` (bigint string) must be settled before anything is
+  // spendable. Nothing charged.
+  | { ok: false; code: "debt"; debt: string }
+  // 400 for a stale listing: pack not found / not for sale / zero price /
+  // all items deleted.
+  | { ok: false; code: "unavailable" }
+  // 409: the player already owns one or more items (`ownedFlareNames` says
+  // which). Also what a retry after a timed-out success returns — treat it as
+  // "already bought" and refetch /users/@me. Nothing charged.
+  | { ok: false; code: "already_owned"; ownedFlareNames: string[] }
+  | { ok: false; code: "failed" };
+
+const PACK_UNAVAILABLE_REASONS = [
+  "Pack not found",
+  "Pack is not for sale",
+  "Pack not available for hard currency",
+  "Pack has no items",
+];
+
+// POST /shop/purchase/pack — buy a cosmetic pack (see CosmeticPackSchema) for
+// its hard-currency price, granting every item's flare in one transaction.
+// Any error means no debit and no grants.
+export async function purchaseCosmeticPack(
+  packName: string,
+): Promise<PurchaseCosmeticPackResult> {
+  try {
+    const response = await fetch(`${getApiBase()}/shop/purchase/pack`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: await getAuthHeader(),
+      },
+      body: JSON.stringify({ packName }),
+    });
+    if (response.status === 401) {
+      await logOut();
+      return { ok: false, code: "failed" };
+    }
+    if (response.status === 400) {
+      const body = await response.json().catch(() => null);
+      const reason = typeof body?.reason === "string" ? body.reason : "";
+      if (reason === "Insufficient balance") {
+        return { ok: false, code: "insufficient_balance" };
+      }
+      if (reason === "insufficient_balance_debt") {
+        return { ok: false, code: "debt", debt: String(body.debt ?? "") };
+      }
+      if (PACK_UNAVAILABLE_REASONS.includes(reason)) {
+        return { ok: false, code: "unavailable" };
+      }
+      console.error("purchaseCosmeticPack: bad request", body);
+      return { ok: false, code: "failed" };
+    }
+    if (response.status === 409) {
+      const body = await response.json().catch(() => null);
+      const owned: unknown = body?.ownedFlareNames;
+      return {
+        ok: false,
+        code: "already_owned",
+        ownedFlareNames: Array.isArray(owned)
+          ? owned.filter((f): f is string => typeof f === "string")
+          : [],
+      };
+    }
+    if (!response.ok) {
+      console.error(
+        "purchaseCosmeticPack: request failed",
+        response.status,
+        response.statusText,
+      );
+      return { ok: false, code: "failed" };
+    }
+    const parsed = PurchasePackResponseSchema.safeParse(await response.json());
+    if (!parsed.success) {
+      console.error(
+        "purchaseCosmeticPack: Zod validation failed",
+        parsed.error,
+      );
+      return { ok: false, code: "failed" };
+    }
+    return { ok: true, data: parsed.data };
+  } catch (e) {
+    console.error("purchaseCosmeticPack: request failed", e);
+    return { ok: false, code: "failed" };
+  }
+}
+
 // POST /rewards/:rewardId/claim — claims a single unclaimed reward and
 // credits the balance atomically. "not_found" covers unknown, already-claimed
 // and other players' rewards (indistinguishable by design); the usual cause is

src/client/Cosmetics.ts

@@ -2,6 +2,8 @@ import { assetUrl } from "src/core/AssetUrls";
 import { UserMeResponse } from "../core/ApiSchemas";
 import {
   ColorPalette,
+  CosmeticPack,
+  CosmeticPackItem,
   Cosmetics,
   CosmeticsSchema,
   Crown,
@@ -26,6 +28,7 @@ import {
   getApiBase,
   getUserMe,
   invalidateUserMe,
+  purchaseCosmeticPack,
   purchaseWithCurrency,
 } from "./Api";
 import { showInGameAlert, showInGameConfirm } from "./InGameModal";
@@ -158,15 +161,17 @@ export async function purchaseCosmetic(
     }
   }
 
+  if (resolved.type === "cosmeticPack") {
+    return purchasePack(c as CosmeticPack, method);
+  }
+
   if (method === "dollar") {
-    if (!c.product) {
+    const product = "product" in c ? c.product : null;
+    if (!product) {
       await showInGameAlert(translateText("store.checkout_failed"));
       return;
     }
-    const url = await createCheckoutSession(
-      c.product.priceId,
-      colorPaletteName,
-    );
+    const url = await createCheckoutSession(product.priceId, colorPaletteName);
     if (url === false) {
       await showInGameAlert(translateText("store.checkout_failed"));
       return;
@@ -248,6 +253,87 @@ export async function purchaseCosmetic(
   window.location.reload();
 }
 
+/**
+ * Buys a cosmetic pack (plutonium only). Mirrors the single-cosmetic currency
+ * flow: a local balance pre-check surfaces the insufficient-funds dialog
+ * before any request; a success reloads so every granted item shows as owned.
+ */
+async function purchasePack(
+  pack: CosmeticPack,
+  method: PaymentMethod,
+): Promise<PurchaseResult> {
+  if (method !== "hard") {
+    console.error("purchaseCosmetic: packs are only sold for hard currency");
+    return;
+  }
+  const userMe = await getUserMe();
+  if (userMe === false) {
+    alert(translateText("store.login_required"));
+    return;
+  }
+  const insufficient = (balance: number): InsufficientCurrency => ({
+    currency: translateText("cosmetics.hard"),
+    shortfall: pack.priceHard - balance,
+    item: pack.displayName,
+    canTopUp: true,
+  });
+  const balance = userMe.player.currency?.hard ?? 0;
+  if (balance < pack.priceHard) {
+    return insufficient(balance);
+  }
+
+  const result = await purchaseCosmeticPack(pack.name);
+  if (result.ok) {
+    alert(translateText("store.purchase_success", { name: pack.displayName }));
+    invalidateUserMe();
+    window.location.reload();
+    return;
+  }
+  switch (result.code) {
+    case "insufficient_balance": {
+      // The balance moved since the pre-check: re-read it for the shortfall.
+      invalidateUserMe();
+      const fresh = await getUserMe();
+      return insufficient(
+        fresh === false ? 0 : (fresh.player.currency?.hard ?? 0),
+      );
+    }
+    case "debt":
+      alert(translateText("store.pack_debt", { debt: result.debt }));
+      return;
+    case "already_owned":
+      // Either a genuine conflict or a retry of a purchase that did go
+      // through: both mean the local ownership state is stale, so refetch.
+      alert(
+        translateText("store.pack_already_owned", {
+          items: result.ownedFlareNames.map(flareDisplayName).join(", "),
+        }),
+      );
+      invalidateUserMe();
+      window.location.reload();
+      return;
+    case "unavailable":
+      alert(translateText("store.pack_unavailable"));
+      return;
+    default:
+      alert(translateText("store.purchase_failed"));
+      return;
+  }
+}
+
+/** The translated name of the cosmetic a flare ("<type>:<name>") refers to. */
+function flareDisplayName(flare: string): string {
+  const [type, name] = flare.split(":", 2);
+  const prefix = {
+    pattern: "territory_patterns.pattern",
+    skin: "territory_patterns.pattern",
+    flag: "flags",
+    crown: "crowns",
+    effect: "effects",
+  }[type];
+  return prefix && name ? translateCosmetic(prefix, name) : flare;
+}
+
 function simpleHash(str: string): string {
   let hash = 0;
   for (let i = 0; i < str.length; i++) {
@@ -465,6 +551,43 @@ export function effectRelationship(
   );
 }
 
+/** The flare a pack item's purchase grants, e.g. "pattern:camo". */
+export function packItemFlare(item: CosmeticPackItem): string {
+  return `${item.type}:${item.name}`;
+}
+
+/**
+ * The pack's items the player already owns — by the item's own flare or the
+ * type wildcard. Any owned item blocks buying the pack (the server answers
+ * 409; there is no partial grant), so callers use this to explain why.
+ */
+export function ownedPackItems(
+  pack: CosmeticPack,
+  userMeResponse: UserMeResponse | false,
+): CosmeticPackItem[] {
+  const flares =
+    userMeResponse === false ? [] : (userMeResponse.player.flares ?? []);
+  return pack.items.filter(
+    (item) =>
+      flares.includes(packItemFlare(item)) || flares.includes(`${item.type}:*`),
+  );
+}
+
+export function cosmeticPackRelationship(
+  pack: CosmeticPack,
+  userMeResponse: UserMeResponse | false,
+  affiliateCode: string | null,
+): "owned" | "purchasable" | "blocked" {
+  if (pack.items.length === 0) return "blocked";
+  const owned = ownedPackItems(pack, userMeResponse).length;
+  if (owned === pack.items.length) return "owned";
+  // Pack revenue isn't attributed to affiliates: hidden in affiliate mode.
+  if (affiliateCode !== null) return "blocked";
+  // Partially owned packs can't be bought (see ownedPackItems).
+  if (owned > 0) return "blocked";
+  return pack.priceHard > 0 ? "purchasable" : "blocked";
+}
+
 export type ResolvedCosmetic = {
   type:
     | "pattern"
@@ -473,14 +596,30 @@ export type ResolvedCosmetic = {
     | "crown"
     | "effect"
     | "pack"
+    | "cosmeticPack"
     | "subscription";
-  cosmetic: Pattern | Skin | Flag | Crown | Effect | Pack | Subscription | null;
+  cosmetic:
+    | Pattern
+    | Skin
+    | Flag
+    | Crown
+    | Effect
+    | Pack
+    | CosmeticPack
+    | Subscription
+    | null;
   colorPalette: ColorPalette | null;
   relationship: "owned" | "purchasable" | "blocked";
   /** Unique key for selection/identity, e.g. "pattern:hearts:red" or "skin:mountain" */
   key: string;
   /** For effects only: the effectType (also the catalog's outer key). */
   effectType?: string;
+  /**
+   * For cosmetic packs only: the pack's items resolved against this catalog,
+   * in pack order. An item whose cosmetic is no longer in the catalog is
+   * skipped (the server still sells whatever remains in the pack).
+   */
+  packItems?: ResolvedCosmetic[];
 };
 
 /**
@@ -596,6 +735,33 @@ export function resolveCosmetics(
     });
   }
 
+  // Cosmetic packs. Items reference cosmetics resolved above by (type, name);
+  // a pattern item is its uncoloured entry — the "pattern:<key>" one, with
+  // no palette segment — since the pack grants "pattern:<name>".
+  for (const [packKey, pack] of Object.entries(cosmetics.packs ?? {})) {
+    const packItems = pack.items.flatMap((item) => {
+      const found = result.find(
+        (r) =>
+          r.type === item.type &&
+          r.cosmetic?.name === item.name &&
+          (item.type !== "pattern" || r.key.split(":").length === 2),
+      );
+      return found ? [found] : [];
+    });
+    result.push({
+      type: "cosmeticPack",
+      cosmetic: pack,
+      colorPalette: null,
+      relationship: cosmeticPackRelationship(
+        pack,
+        userMeResponse,
+        affiliateCode,
+      ),
+      key: `cosmeticPack:${packKey}`,
+      packItems,
+    });
+  }
+
   // Subscriptions
   const flares =
     userMeResponse === false ? [] : (userMeResponse.player.flares ?? []);