@idosgames/mcp 0.1.0

package/registry/skills/marketplace-system.json

@@ -0,0 +1,11 @@
+{
+  "name": "marketplace-system",
+  "description": "Build a player-to-player marketplace in a game on the iDosGames TypeScript SDK (@idosgames/core) via client.marketplace (MarketplaceService): browse offers grouped/by item, create and buy fixed-price listings, create auctions and place bids and claim settlement, create/cancel/fill buy orders, create/accept/decline/cancel direct trades (P2P gifts/swaps), read my-state (my offers, leading bids, incoming/outgoing trades, claimables), page through trade history, and claim back escrow from expired or unsettled offers. Use this whenever the user is working in the iDosGames TS SDK or its game templates (board-game, idle-rpg) and wants an auction house, player market, trading post, buy-order/limit-order board, gifting/trading between players, or otherwise touches client.marketplace, MarketplaceService, MarketplaceOfferView, MarketOfferType, MarketplaceAuctionState, or MarketplaceSettlementResponse — even if they don't name the module explicitly.",
+  "content": "---\nname: marketplace-system\ndescription: >-\n  Build a player-to-player marketplace in a game on the iDosGames TypeScript\n  SDK (@idosgames/core) via client.marketplace (MarketplaceService): browse\n  offers grouped/by item, create and buy fixed-price listings, create\n  auctions and place bids and claim settlement, create/cancel/fill buy\n  orders, create/accept/decline/cancel direct trades (P2P gifts/swaps), read\n  my-state (my offers, leading bids, incoming/outgoing trades, claimables),\n  page through trade history, and claim back escrow from expired or\n  unsettled offers. Use this whenever the user is working in the iDosGames\n  TS SDK or its game templates (board-game, idle-rpg) and wants an\n  auction house, player market, trading post, buy-order/limit-order board,\n  gifting/trading between players, or otherwise touches client.marketplace,\n  MarketplaceService, MarketplaceOfferView, MarketOfferType,\n  MarketplaceAuctionState, or MarketplaceSettlementResponse — even if they\n  don't name the module explicitly.\n---\n\n# Marketplace system (iDosGames TS SDK)\n\nThe Marketplace module is a full player-to-player trading economy: players list\nitems for sale, auction them off, post buy orders for items they want, or trade\ndirectly with a specific player. Everything is **server-authoritative and\nescrow-based**: creating an offer locks the goods (and/or a listing fee) in\nescrow immediately, and settlement — releasing goods to the buyer and proceeds\nto the seller, minus any commission — happens server-side when a matching\naction occurs (a buy, a winning claim, a filled buy order, an accepted trade).\nYou never move goods or currency yourself; you call a method, check the\nresult, and render from the mirrored cache.\n\nThis skill is for **using** the production `MarketplaceService`, not for\nporting or extending it. If a call is rejected, that's the backend enforcing a\nrule (gate closed, tradability policy, rate limit, insufficient escrow) —\nsurface the error, don't try to reproduce the check client-side.\n\nItem/inventory vocabulary (item instances, stackable vs unstackable, catalogs)\nis the item-system skill's territory — read it first if you need the shape of\n`GoodsInstances`/`ItemInstanceIDs`. Cost/reward objects\n(`ResourceBundle`/`ResourceConsume`/`ResourceGrant`/`ResourceOperation`) are the\ncurrency-system skill's territory. This skill cross-links to both rather than\nre-explaining them.\n\n## The four listing types\n\nOne offer model (`MarketplaceOfferView`, `MarketOfferType`) covers four\ndifferent trading mechanics — know which one you're building before you pick\nmethods:\n\n| Type          | What it is                                                              | Who initiates settlement                                             |\n| ------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------- |\n| `Listing`     | Fixed-price sale: seller escrows goods, names a price.                  | Buyer calls `buy` — instant settlement.                              |\n| `Auction`     | Goods escrowed, players bid up a single comparable axis (a VC or item). | Either party calls `claimAuction` after it ends (lazy finalization). |\n| `BuyOrder`    | Inverted listing: buyer escrows payment, names what they want to buy.   | A seller calls `fillBuyOrder` — instant settlement.                  |\n| `DirectTrade` | A gift or targeted swap aimed at one specific player (`TargetUserID`).  | Target calls `respondDirectTrade(offerID, accept)`.                  |\n\nA `Listing`/`BuyOrder`/`DirectTrade` settles **immediately** on the matching\naction — you get a `Settlement` (or `Resources`, for a plain gift) back in the\nsame call. An `Auction` is **lazy**: nothing settles when bidding ends — the\nwinner and the seller each separately call `claimAuction` to pull their side\n(goods vs net proceeds) whenever they next check in; there's no server-side\npush the instant the timer expires. Offer status itself flips to `\"Expired\"`\nlazily too — a browsing/read call may still show `\"Active\"` for an offer past\nits `ExpiresAt` until it's next touched by a claim/finalize path.\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any auth.* method\n\nconst marketplace = client.marketplace; // the MarketplaceService\n```\n\nEvery method requires an authenticated session. Without one they return\n`{ ok: false, reason: \"unauthorized\" }` — they do not throw. There is one\n`client` per player; don't share it across sessions.\n\n## Methods\n\nAll methods return `Promise<OperationResult<T>>`: a discriminated union that is\neither `{ ok: true, data }` or `{ ok: false, reason, error }`. Always branch on\n`result.ok` before touching `result.data`. `reason` is one of `\"client\"` (bad\nlocal args), `\"unauthorized\"`, `\"throttled\"` (fired the same endpoint again\ninside the client-side throttle window, default 600ms), `\"connection\"`\n(transient, offer Retry), `\"validation\"` (response/schema drift), or\n`\"server\"` (backend rejected it —\n`error` carries the human-readable reason straight from the backend, e.g.\n`\"Marketplace is disabled.\"`, `\"Item is not tradable (ItemDefinition.IsTradable=false).\"`,\n`\"Auction has not ended yet.\"`, insufficient funds).\n\n### Reading / browsing\n\n| Method                                                                     | Purpose                                                                             | `data` on success                   |\n| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------- |\n| `getDefinitions()`                                                         | Load the title's marketplace config (policies, per-type settings).                  | `MarketplaceGetDefinitionsResponse` |\n| `getGroupedOffers()`                                                       | Browse the storefront grouped by item (one row per item + count).                   | `MarketplaceGroupedOffersResponse`  |\n| `getOffersByItem(itemID, offerTypeFilter?, continuationToken?, pageSize?)` | Page through all offers for one item, optionally filtered by type.                  | `MarketplaceBrowseResponse`         |\n| `getOffer(offerID)`                                                        | Load one offer's full detail (e.g. before bidding/buying).                          | `MarketplaceOfferResponse`          |\n| `getBuyOrders(itemID?, continuationToken?, pageSize?)`                     | Page through active buy orders, optionally for one item.                            | `MarketplaceBrowseResponse`         |\n| `getMyState()`                                                             | My offers, leading bids, incoming/outgoing trades, claimables, rate-limit counters. | `MarketplaceMyStateResponse`        |\n| `getHistory(continuationToken?, pageSize?)`                                | Page through my completed trade history.                                            | `MarketplaceHistoryResponse`        |\n\n`getGroupedOffers()` returns only `{ GoodsCatalogID, GoodsItemID, OfferCount }`\nper row — no price is included in the grouped view; drill into\n`getOffersByItem` to see actual prices. A `DirectTrade` offer is only visible\nvia `getOffer`/`getMyState` to its creator or target — a third party reading it\ngets `\"Offer not found.\"`, the same error as a truly missing offer.\n\n### Fixed-price listings\n\n| Method                                                                                        | Purpose                                      | `data` on success                |\n| --------------------------------------------------------------------------------------------- | -------------------------------------------- | -------------------------------- |\n| `createListing(itemID, catalogID, goodsAmount, priceBundle, durationHours, itemInstanceIDs?)` | List goods for sale at a fixed price.        | `MarketplaceCreateOfferResponse` |\n| `cancelListing(offerID)`                                                                      | Cancel my own active listing; goods return.  | `MarketplaceSettlementResponse`  |\n| `buy(offerID)`                                                                                | Buy a listing outright — instant settlement. | `MarketplaceSettlementResponse`  |\n\n### Auctions\n\n| Method                                                                                             | Purpose                                                                  | `data` on success                |\n| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------- |\n| `createAuction(itemID, catalogID, goodsAmount, bidAxisType, startingBid, durationHours, options?)` | Escrow goods and open bidding on a single VC/item axis.                  | `MarketplaceCreateOfferResponse` |\n| `placeBid(offerID, bidAmount)`                                                                     | Bid on an active auction (escrows the bid amount).                       | `MarketplacePlaceBidResponse`    |\n| `claimAuction(offerID)`                                                                            | After the auction ends: winner claims goods, seller claims net proceeds. | `MarketplaceSettlementResponse`  |\n\n`options` on `createAuction` is `{ bidCurrencyID?, bidCatalogID?, bidItemID?,\nitemInstanceIDs? }` — set the fields matching `bidAxisType` (a currency id for\na VC axis, or catalog+item id for an item axis).\n\n### Buy orders\n\n| Method                                                                       | Purpose                                                  | `data` on success                |\n| ---------------------------------------------------------------------------- | -------------------------------------------------------- | -------------------------------- |\n| `createBuyOrder(itemID, catalogID, goodsAmount, priceBundle, durationHours)` | Escrow payment, post an order for goods you want to buy. | `MarketplaceCreateOfferResponse` |\n| `cancelBuyOrder(offerID)`                                                    | Cancel my own active buy order; payment returns.         | `MarketplaceSettlementResponse`  |\n| `fillBuyOrder(offerID)`                                                      | Sell into someone's buy order — instant settlement.      | `MarketplaceSettlementResponse`  |\n\nA buy order is filled **in full only** — there's no partial-quantity fill. The\nseller supplies fresh (pristine) units of `GoodsItemID`/`GoodsCatalogID`; for\nunstackable goods the buy order carries no specific instance identity, so\n`fillBuyOrder` does not take `itemInstanceIDs`.\n\n### Direct trades (P2P gifts / targeted swaps)\n\n| Method                                                                                   | Purpose                                                                                   | `data` on success                |\n| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------- |\n| `createDirectTrade(targetUserID, catalogID, itemID, itemInstanceIDs?, requestedBundle?)` | Send a specific player an offer: goods only (gift) or goods-for-`requestedBundle` (swap). | `MarketplaceCreateOfferResponse` |\n| `respondDirectTrade(offerID, accept)`                                                    | Target accepts or declines an incoming trade.                                             | `MarketplaceSettlementResponse`  |\n| `cancelDirectTrade(offerID)`                                                             | Sender cancels a still-pending outgoing trade; goods return.                              | `MarketplaceSettlementResponse`  |\n\nOmit `requestedBundle` to send a pure gift (no `Settlement`, just a `Resources`\ngrant to the target on accept). Provide it to require the target to pay a\nprice for the goods (dual-party `Settlement` on accept). The backend also\nsupports offering a stackable resource bundle as the _offered_ side of a\ndirect trade, but the SDK's `createDirectTrade(targetUserID, catalogID,\nitemID, itemInstanceIDs?, requestedBundle?)` only wires up the\n`itemInstanceIDs` path — there's no parameter to pass a stackable offered\nbundle from this method today. In practice: send unstackable goods via\n`itemInstanceIDs`; for a stackable item you want to give away, use a\n`Listing`/gift-priced `BuyOrder` instead of a direct trade. Targeting\nyourself is rejected server-side (`\"Cannot target yourself.\"`).\n\n### Escrow claims\n\n| Method                | Purpose                                                                                                             | `data` on success               |\n| --------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------- |\n| `claimBack(offerID?)` | With an `offerID`: reclaim escrow from one expired offer. Without: drain all pending unsettled bid refunds at once. | `MarketplaceSettlementResponse` |\n\n`claimBack`/decline/cancel are **never blocked by the marketplace's Gate or\nSchedule** — frozen escrow must always be returnable, even if the marketplace\nis later disabled or closed for a segment. Create/buy/bid/fill/accept\n(the actual trading actions) are gated.\n\n## Reading state and reacting to changes\n\nOn success, write methods **mirror the confirmed change into the cache** —\nyou don't apply anything by hand. Which cache slice updates depends on the\nshape of the response:\n\n- **Dual-party settlements** (`buy`, `fillBuyOrder`, `respondDirectTrade`\n  accept-with-price): the SDK reads `Settlement.FromUserID`/`ToUserID` and\n  applies **only the current player's side** (`FromResult` or `ToResult`) to\n  the cached balances — it never touches the other party's data.\n- **Single-party resource grants** (`createListing`/`createAuction`/\n  `createBuyOrder`/`createDirectTrade`, `cancelListing`/`cancelBuyOrder`/\n  `cancelDirectTrade`, `placeBid`, `claimAuction`, `claimBack`,\n  `respondDirectTrade` accept-gift or decline): the `Resources`\n  (`ResourceOperation`) field is applied directly.\n- **Rate-limit counters**: `getMyState()` mirrors `Limits` into\n  `client.data.user.state?.Marketplace` and is the _only_ call that fires\n  `user:marketplaceUpdated`.\n\n```ts\n// Rate-limit counters (only present after getMyState()):\nconst limits = client.data.user.state?.Marketplace;\nlimits?.Create?.DailyCount;\nlimits?.Buy?.DailyCount;\n\n// Config (cached after getDefinitions()):\nimport type { MarketplaceDefinitions } from \"@idosgames/core\";\nconst cfg =\n  client.data.config.getSection<MarketplaceDefinitions>(\"Marketplace\");\n```\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn:\n\n- `marketplace:definitionsLoaded` → `MarketplaceGetDefinitionsResponse`\n- `marketplace:groupedOffersLoaded` → `MarketplaceGroupedOffersResponse`\n- `marketplace:offersByItemLoaded` → `MarketplaceBrowseResponse`\n- `marketplace:offerLoaded` → `MarketplaceOfferResponse`\n- `marketplace:buyOrdersLoaded` → `MarketplaceBrowseResponse`\n- `marketplace:myStateLoaded` → `MarketplaceMyStateResponse`\n- `marketplace:historyLoaded` → `MarketplaceHistoryResponse`\n- `marketplace:listingCreated` / `marketplace:auctionCreated` /\n  `marketplace:buyOrderCreated` / `marketplace:directTradeCreated` →\n  `MarketplaceCreateOfferResponse`\n- `marketplace:listingCancelled` / `marketplace:buyOrderCancelled` /\n  `marketplace:directTradeCancelled` → `MarketplaceSettlementResponse`\n- `marketplace:bought` → `MarketplaceSettlementResponse`\n- `marketplace:bidPlaced` → `MarketplacePlaceBidResponse`\n- `marketplace:auctionClaimed` → `MarketplaceSettlementResponse`\n- `marketplace:buyOrderFilled` → `MarketplaceSettlementResponse`\n- `marketplace:directTradeResponded` → `MarketplaceSettlementResponse`\n- `marketplace:claimedBack` → `MarketplaceSettlementResponse`\n\n**Note on the umbrella events**: unlike most modules, there is no\n`marketplace:*` write path that fires a matching `user:marketplaceUpdated` —\nthat coarse event is reserved for `getMyState()`'s rate-limit snapshot. The\nactual balance/inventory changes from buying, bidding, claiming, etc. instead\nfire the generic `user:inventoryUpdated` / `user:virtualCurrencyUpdated` (+\n`user:anyUpdated`), same as any other resource-moving call. Listen for those\nif you want a \"my balances changed\" hook.\n\n```ts\nconst off = client.on(\"marketplace:bought\", (r) => {\n  console.log(`Offer ${r.OfferID} settled: ${r.Status}`);\n});\n// later: off();\n```\n\n## Recipes\n\n### Browse and buy a fixed-price offer\n\n```ts\n// storefront summary (one row per item + how many offers exist):\nconst grouped = await client.marketplace.getGroupedOffers();\nif (!grouped.ok) return showError(grouped.error);\ngrouped.data.Groups; // [{ GoodsCatalogID, GoodsItemID, OfferCount }, ...]\n\n// drill into one item's actual offers to buy from:\nconst page = await client.marketplace.getOffersByItem(\"sword-01\", \"Listing\");\nif (!page.ok) return showError(page.error);\n\nconst offer = page.data.Offers?.[0];\nif (!offer?.OfferID) return;\n\nconst res = await client.marketplace.buy(offer.OfferID);\nif (!res.ok) return showError(res.error); // e.g. \"Offer is already Completed.\"\nres.data.Settlement; // dual-party result; your side already applied to cache\nres.data.CommissionTaken; // fee taken out, if the title charges commission\n```\n\n### Create a fixed-price listing, then cancel it\n\n```ts\nconst create = await client.marketplace.createListing(\n  \"sword-01\",\n  \"weapons\",\n  1,\n  { Entries: [{ Type: \"VirtualCurrency\", CurrencyID: \"gold\", Amount: 500 }] },\n  24, // durationHours — must be one of Listings.AllowedDurationsHours (default {24,72,168})\n);\nif (!create.ok) return showError(create.error);\nconst offerID = create.data.OfferID!;\n\n// changed your mind before anyone bought it:\nconst cancel = await client.marketplace.cancelListing(offerID);\nif (!cancel.ok) return showError(cancel.error); // e.g. \"Offer is already Completed.\"\n// escrowed goods (and listing fee, if RefundListingFeeOnCancel) are back in your inventory\n```\n\nThe `gold` currency must itself be marked tradable\n(`VirtualCurrencyDefinition.Permissions.IsTradable === true`) or any create\ncall pricing in it is rejected with `\"Currency 'gold' is not tradable between\nplayers (Permissions.IsTradable=false).\"` — this is a per-currency title\nsetting, not something the marketplace config controls directly.\n\n### Create an auction, bid, then claim\n\n```ts\nconst create = await client.marketplace.createAuction(\n  \"shield-02\",\n  \"armor\",\n  1,\n  \"VirtualCurrency\",\n  100, // startingBid\n  48, // durationHours\n  { bidCurrencyID: \"gold\" },\n);\nif (!create.ok) return showError(create.error);\nconst offerID = create.data.OfferID!;\n\n// another player bids:\nconst bid = await client.marketplace.placeBid(offerID, 150);\nif (!bid.ok) return showError(bid.error); // e.g. \"Bid must be at least 105.\"\nbid.data.CurrentBid;\nbid.data.ExpiresAt; // may have moved out if anti-snipe extended it\n\n// after the auction ends, EACH side claims separately:\nconst winnerClaim = await client.marketplace.claimAuction(offerID); // called by the winning bidder\nconst sellerClaim = await client.marketplace.claimAuction(offerID); // called by the seller\n```\n\nThere's no push notification the instant an auction ends — poll `getOffer`,\n`getMyState` (`MyLeadingBids`/`Claimables`), or your own reminder logic, then\ncall `claimAuction`. The minimum acceptable bid is computed server-side (see\n[the auction bid-step formula](references/data-model.md#auction-bid-step-formula))\nand echoed in the rejection message so you can show it without hardcoding the\nmath. An auction that ends with zero bids is claimed with `claimBack`, not\n`claimAuction` (`\"Auction ended with no bids — use ClaimBack.\"`).\n\n### Create a buy order, then cancel it\n\n```ts\nconst create = await client.marketplace.createBuyOrder(\n  \"potion-05\",\n  \"consumables\",\n  10,\n  { Entries: [{ Type: \"VirtualCurrency\", CurrencyID: \"gold\", Amount: 5 }] },\n  24,\n);\nif (!create.ok) return showError(create.error);\nconst offerID = create.data.OfferID!;\n\n// no seller filled it yet:\nconst cancel = await client.marketplace.cancelBuyOrder(offerID);\nif (!cancel.ok) return showError(cancel.error);\n// escrowed payment is refunded\n```\n\nA seller fills it with `fillBuyOrder(offerID)` — instant settlement, same\ndual-party `Settlement` shape as `buy`. A seller can't fill their own order\n(`\"You cannot fill your own buy order.\"`).\n\n### Send and respond to a direct trade\n\n```ts\n// gift, no price:\nconst gift = await client.marketplace.createDirectTrade(\n  \"friend-user-id\",\n  \"weapons\",\n  \"sword-01\",\n  [\"inst-abc123\"], // itemInstanceIDs — required for unstackable goods\n);\nif (!gift.ok) return showError(gift.error);\n\n// friend's client:\nconst accept = await client.marketplace.respondDirectTrade(\n  gift.data.OfferID!,\n  true,\n);\nif (!accept.ok) return showError(accept.error);\n// gift path: accept.data.Resources credits the accepter; no Settlement\n```\n\nTo ask for something back instead of a pure gift, pass `requestedBundle` —\naccepting then produces a dual-party `Settlement` instead of a plain\n`Resources` grant. If the title's `DirectTrades.AllowGifts` is `false`, an\nomitted/empty `requestedBundle` is rejected with `\"Gifts are disabled.\"`.\n\n### Reclaim escrow from an expired offer\n\n```ts\n// after ExpiresAt has passed and nobody bought/bid/filled it:\nconst back = await client.marketplace.claimBack(offerID);\nif (!back.ok) return showError(back.error); // \"Offer has not expired yet — use cancel.\"\n// escrow (goods/payment) is returned to you\n\n// sweep every pending outbid-refund across all your auctions at once:\nawait client.marketplace.claimBack();\n```\n\nCalling `claimBack` before an offer's `ExpiresAt` is rejected — use\n`cancelListing`/`cancelBuyOrder`/`cancelDirectTrade` for a still-active offer\ninstead. An auction that already has bids can't be cancelled or claimed-back\nby the seller at all (`\"Auction with bids cannot be cancelled.\"` /\n`\"Auction has bids — use ClaimAuction.\"`) — once bidding starts, the only path\nto close it out is waiting for `ExpiresAt` and calling `claimAuction`.\n\n## Gotchas\n\n- **Auctions settle lazily — nothing happens automatically when they end.**\n  Both the winner and the seller must independently call `claimAuction` to\n  pull their side (goods vs net proceeds). Build a \"claimables\" reminder off\n  `getMyState().Claimables` rather than assuming completion.\n- **Escrow can strand resources — that's what `claimBack` is for.** If an\n  offer expires unclaimed, or a bid gets outbid and its refund wasn't drained\n  automatically, call `claimBack(offerID)` for one offer or `claimBack()`\n  (no id) to sweep every pending refund at once. `claimBack`/cancel/decline\n  are never gated by `Enabled`/`Gate`/`Schedule` — only the trading actions\n  (create/buy/bid/fill/accept) are.\n- **Declining a direct trade does NOT credit you.** On\n  `respondDirectTrade(offerID, false)`, the response's `Resources` credits the\n  **offer's creator** (their escrowed goods/payment coming back to them), not\n  the decliner. The SDK intentionally does not apply that grant to your own\n  cache — don't expect your balance to change after declining.\n  `respondDirectTrade(offerID, true)` on the other hand is applied per the\n  dual-party or gift rule above.\n- **`user:marketplaceUpdated` is narrower than it looks.** It fires only from\n  `getMyState()`'s rate-limit snapshot, not from any buy/bid/claim/cancel\n  action — those instead emit the generic `user:inventoryUpdated` /\n  `user:virtualCurrencyUpdated` (+ `user:anyUpdated`). Don't gate a \"my\n  marketplace data changed\" UI refresh on `user:marketplaceUpdated` alone.\n- **Guard against double-submit — for two independent reasons.** Each call\n  mints a fresh idempotency key, so two separate calls are two real\n  operations (a double-clicked \"Buy\" or \"Bid\" can charge twice); disable the\n  control while a call is in flight. Separately, every offer-mutating action\n  (`buy`, `placeBid`, `claimAuction`, `fillBuyOrder`, `respondDirectTrade`,\n  cancel\\*, `claimBack`) also takes a short **per-offer server-side lock** —\n  a near-simultaneous second call on the _same offer_ (from you or another\n  player) can come back with `\"This offer is being processed, try again.\"` or\n  `\"Too many requests for this offer, try again.\"`; treat both as transient\n  and safe to retry once, not as a sign the first call failed.\n- **Commission can reduce what the seller nets.** When the title's\n  `Commission` policy applies (always for `buy`/`fillBuyOrder`; for direct\n  trades only if `ApplyToDirectTrades` is true), the fee is computed\n  per price position as `min(amount, max(ceil(amount * Percent),\nMinPerPosition))` and the seller's side of `Settlement` already has it\n  deducted — `CommissionTaken` on the response is informational (for a\n  receipt/history line), don't subtract it again in the UI. The rate is\n  snapshotted onto the offer at creation, so a later config change never\n  affects an already-listed offer. See\n  [the commission formula](references/data-model.md#commission-model) for the\n  full per-catalog-override behavior.\n- **Tradability and pricing are policy-gated server-side.** `Tradability`\n  (allowed/denied catalogs and items, `ItemDefinition.IsTradable`) and\n  `PricePolicy` (which resource kinds and how many \"positions\" a price can\n  mix) are enforced on create — a rejected `createListing`/`createAuction`/\n  `createBuyOrder` is usually one of these, not a client bug. Two rules are\n  easy to miss: a virtual currency used as a price must itself have\n  `Permissions.IsTradable === true`, and **unstackable items can never be\n  used as a price position** (only as the goods side) — both are enforced\n  unconditionally, not just when a whitelist is configured.\n- **Item/inventory concepts live in the item-system skill.** `GoodsInstances`\n  on an offer view and `itemInstanceIDs` params are the same\n  `UnstackableItemInstanceState` / stackable-vs-unstackable model documented\n  there — this skill doesn't re-derive it.\n\n## Full reference\n\n[references/data-model.md](references/data-model.md) — every config and\nresponse field (policies, per-listing-type settings, the auction state block,\noffer view, history entry, request shape), the commission and bid-step\nformulas transcribed from the backend, and the settlement/escrow model in\ndetail. Read it when building config-driven UI (price/commission previews,\nduration pickers, rate-limit displays) or when an error message points at a\nconfig rule you need to understand.\n",
+  "references": [
+    {
+      "path": "data-model.md",
+      "content": "# Marketplace data model — reference\n\nFull shape of the config (`MarketplaceDefinitions`), the offer/state views the\nclient actually sees, the request shape, and the escrow/settlement/commission\nmodel in detail. All of these are **strictly typed in the SDK** —\n`MarketplaceDefinitions` and every nested block, `MarketplaceOfferView`,\n`MarketplaceAuctionState`, the various response types — are exported from\n`@idosgames/core`, so `getDefinitions()` /\n`getSection<MarketplaceDefinitions>(\"Marketplace\")` and every service call give\nyou concrete types, not `unknown`. The schemas keep `.passthrough()`, so a\nfield the backend adds later still round-trips. Field names are PascalCase\n(straight from the backend JSON).\n\n## Contents\n\n- [What the client never sees](#what-the-client-never-sees)\n- [Config: MarketplaceDefinitions](#config-marketplacedefinitions)\n- [Per-listing-type settings](#per-listing-type-settings)\n- [Offer view: MarketplaceOfferView](#offer-view-marketplaceofferview)\n- [Auction state](#auction-state)\n- [Auction bid-step formula](#auction-bid-step-formula)\n- [User state: UserMarketplaceState (rate limits)](#user-state-usermarketplacestate-rate-limits)\n- [Responses](#responses)\n- [Request shape](#request-shape)\n- [Settlement & escrow model](#settlement--escrow-model)\n- [Commission model](#commission-model)\n- [Server-side limits, locking, and idempotency](#server-side-limits-locking-and-idempotency)\n\n---\n\n## What the client never sees\n\nThe backend's internal `MarketplaceOfferDocument` (raw escrow bookkeeping,\ncommission snapshot) and the `MarketplaceTradeLogDocument` /\n`MarketplaceLedgerDocument` never reach the client. Everything documented here\nis the **public projection**: `MarketplaceOfferView` (what browsing/my-state/\nhistory return instead of the raw document) and `MarketplaceHistoryEntryView`.\nOne exception: `MarketplaceAuctionState` is shared **verbatim** between the\ninternal document and the public view — the backend assigns the same object to\nboth (`MarketplaceHelpers.BuildOfferView`, `Auction = doc.Auction`) — so what's\nbelow is exactly what's stored.\n\n---\n\n## Config: MarketplaceDefinitions\n\nReturned by `getDefinitions()`; cached via\n`client.data.config.getSection<MarketplaceDefinitions>(\"Marketplace\")`.\n\n```ts\ninterface MarketplaceDefinitions {\n  Enabled?: boolean; // master switch; default false — must be enabled explicitly\n  Gate?: SegmentGate; // segment-based access gate (see other modules' Gate usage)\n  Schedule?: ScheduleSpec; // time-window the marketplace is open; null = always open\n  PricePolicy?: MarketplacePricePolicy;\n  Commission?: MarketplaceCommissionPolicy;\n  Tradability?: MarketplaceTradabilityPolicy;\n  Listings?: MarketplaceListingSettings;\n  Auctions?: MarketplaceAuctionSettings;\n  BuyOrders?: MarketplaceBuyOrderSettings;\n  DirectTrades?: MarketplaceDirectTradeSettings;\n}\n```\n\n`getDefinitions()`'s response also carries two computed flags alongside\n`Definitions`:\n\n```ts\ninterface MarketplaceGetDefinitionsResponse {\n  Definitions?: MarketplaceDefinitions | null;\n  IsOpenNow?: boolean | null; // Enabled && Schedule evaluated against server time\n  GatePassed?: boolean | null; // Gate evaluated against this player's segment\n}\n```\n\nCheck both before showing \"create offer\" UI — `Enabled` alone doesn't account\nfor the schedule window or the segment gate. **`Gate`/`Schedule` are only\nenforced on trading actions** (create/buy/bid/fill/accept) — `claimBack`,\ncancels, and a decline are never blocked by either, confirmed in\n`MarketplaceV2.CheckTradeGate`'s call sites (`Marketplace.cs`): it's invoked\nfrom `CreateSellOffer`, `Buy`, `PlaceBid`, `CreateBuyOrder`, `FillBuyOrder`,\n`CreateDirectTrade`, and the accept branch of `RespondDirectTrade` — never\nfrom `CancelOffer`, `ClaimBack`, or the decline branch.\n\n`SegmentGate`, `ScheduleSpec`, and `LimitSpec` (used throughout the per-type\nsettings below) are generic cross-module shapes shared with other live-ops\nsystems (segment/schedule gating, anti-farm counters) — this reference only\nlists the fields Marketplace itself reads.\n\n---\n\n## Per-listing-type settings\n\n### PricePolicy — what a price/bid can be made of\n\n```ts\ninterface MarketplacePricePolicy {\n  AllowVirtualCurrency?: boolean; // default true; ignored when Allowed is non-empty\n  AllowItems?: boolean; // default false; ignored when Allowed is non-empty\n  AllowEventTokens?: boolean; // default false; ignored when Allowed is non-empty\n  Allowed?: EntryResourceRule[]; // authoritative whitelist when non-empty (kind + id + min/max amount)\n  MaxPositions?: number; // default 5; cap on distinct resource entries + event tokens in one price; 0 = unlimited\n}\n```\n\nMirrors the entry-policy pattern from the Match module (`MatchEntrySettings`) —\nsame `EntryResourceRule` shape (`Kind`, `CurrencyID`/`CatalogID`/`ItemID`,\n`TokenType`/`EntityID`, `MinAmount`/`MaxAmount`). A `createListing`/\n`createAuction`/`createBuyOrder`/`createDirectTrade`'s price (or an auction's\nstarting-bid axis) is validated against this policy on create\n(`MarketplaceHelpers.ValidatePricePolicy`, `Marketplace.cs`):\n\nTwo rules apply **unconditionally**, regardless of whitelist/flags\n(`MarketplaceHelpers.cs`):\n\n- A virtual-currency price position is rejected unless that currency's own\n  `VirtualCurrencyDefinition.Permissions.IsTradable === true` — error:\n  `\"Currency '{id}' is not tradable between players (Permissions.IsTradable=false).\"`\n- An **unstackable item can never be used as a price position** (only as\n  goods) — error: `\"Unstackable items cannot be used as a price.\"` — because\n  granting it back would have to re-mint a new instance identity.\n\nWhen `Allowed` is non-empty it is authoritative — every price position must\nmatch one of its rules (including `MinAmount`/`MaxAmount`); the\n`AllowVirtualCurrency`/`AllowItems`/`AllowEventTokens` flags are only consulted\nwhen `Allowed` is empty.\n\n### Commission — the cut taken at settlement\n\n```ts\ninterface MarketplaceCommissionPolicy {\n  Percent?: number; // default 0.05 (5%)\n  MinPerPosition?: number; // floor per priced resource entry; default 0 (no minimum)\n  Sink?: \"Burn\" | \"Ledger\"; // default \"Burn\"\n  LedgerAccountID?: string; // target account when Sink === \"Ledger\"; empty falls back to \"default\"\n  PerCatalogOverrides?: Record<string, MarketplaceCommissionOverride>;\n  ApplyToDirectTrades?: boolean; // default false — gifts/trades are commission-exempt by default\n}\n\ninterface MarketplaceCommissionOverride {\n  Percent?: number;\n  MinPerPosition?: number;\n}\n```\n\n`PerCatalogOverrides` is keyed by the **goods'** `CatalogID` (not the price's) —\na catalog present here replaces the top-level `Percent`/`MinPerPosition` for\noffers whose goods come from that catalog\n(`MarketplaceHelpers.ResolveCommission`). See\n[Commission model](#commission-model) below for the exact per-position fee\nformula.\n\n### Tradability — what's allowed on the market at all\n\n```ts\ninterface MarketplaceTradabilityPolicy {\n  AllowedCatalogIDs?: string[]; // null/absent = no catalog allow-list (all allowed unless denied)\n  DeniedCatalogIDs?: string[];\n  DeniedItemIDs?: string[];\n  AllowUnstackableWithState?: boolean; // default true; allow listing instances with state (Level>1, RemainingUses>1, CustomData)\n}\n```\n\nBase requirement, checked first regardless of policy:\n`ItemDefinition.IsTradable` must be `true`\n(`MarketplaceHelpers.ResolveTradableItem`) — error:\n`\"Item '{itemID}' is not tradable (ItemDefinition.IsTradable=false).\"` The item\nis resolved with the same strict→fallback catalog resolver used elsewhere\n(self-heals `CatalogID` if the item moved catalogs), so the response's\n`GoodsCatalogID` can differ from what you originally passed as `catalogID`.\n\nWhen `AllowUnstackableWithState` is `false`, only \"pristine\" instances\n(`Level <= 1`, `RemainingUses <= 1`, no `CustomData`) may be escrowed as goods\n— error: `\"Instance '{id}' has state (level/custom data) — selling stateful\ninstances is disabled.\"` Equipped or expired instances are always rejected\nregardless of this flag (`\"Instance '{id}' is equipped — unequip it\nfirst.\"` / `\"Instance '{id}' has expired.\"`).\n\n### Listings\n\n```ts\ninterface MarketplaceListingSettings {\n  Enabled?: boolean; // default true (when the module itself is enabled)\n  AllowedDurationsHours?: number[]; // empty/null = default {24, 72, 168}\n  MaxActiveListings?: number; // default 10; per-player cap counting Listing+Auction together; 0 = unlimited\n  CreateLimits?: LimitSpec;\n  BuyLimits?: LimitSpec;\n  ListingFee?: ResourceConsume; // charged in addition to escrowing the goods; only the Standard part is used\n  RefundListingFeeOnCancel?: boolean; // default false — fee is forfeit on cancel; never refunded on expiry either way\n}\n```\n\n`MaxActiveListings` is checked against a single count query across **both**\n`Listing` and `Auction` offer types created by the player\n(`MarketplaceDBService.CountActiveByCreatorAsync(..., Listing, Auction)`) — a\ntitle with `MaxActiveListings: 10` caps the player at 10 combined open\nlistings+auctions, not 10 of each.\n\n### Auctions\n\n```ts\ninterface MarketplaceAuctionSettings {\n  Enabled?: boolean; // default true\n  MinDurationHours?: number; // default 1\n  MaxDurationHours?: number; // default 168\n  AntiSnipeWindowSeconds?: number; // default 120; 0 = disabled\n  AntiSnipeExtensionSeconds?: number; // default 120\n  MaxAntiSnipeExtensions?: number; // default 10\n  MinBidStepPercent?: number; // default 0.05 (5%)\n  MinBidStepAbsolute?: number; // default 1\n  BidLimits?: LimitSpec;\n}\n```\n\nAnti-snipe: a bid placed within `AntiSnipeWindowSeconds` of the auction's\ncurrent `ExpiresAt` pushes the deadline out by `AntiSnipeExtensionSeconds`,\nup to `MaxAntiSnipeExtensions` times total per auction —\n`MarketplaceAuctionState.ExtensionCount` tracks how many have already\nhappened (`Marketplace.cs`, `PlaceBid`). See\n[Auction bid-step formula](#auction-bid-step-formula) for the minimum-bid math.\n\n### Buy orders\n\n```ts\ninterface MarketplaceBuyOrderSettings {\n  Enabled?: boolean; // default true\n  MaxActiveOrders?: number; // default 5; per-player cap; 0 = unlimited\n  AllowedDurationsHours?: number[]; // empty/null = default {24, 72, 168}\n  CreateLimits?: LimitSpec;\n  FillLimits?: LimitSpec;\n}\n```\n\n### Direct trades\n\n```ts\ninterface MarketplaceDirectTradeSettings {\n  Enabled?: boolean; // default true\n  OfferExpirationHours?: number; // default 168\n  MaxPendingOutgoing?: number; // default 10; caps my own not-yet-responded-to outgoing trades; 0 = unlimited\n  AllowGifts?: boolean; // default true; false = requestedBundle becomes mandatory\n  CreateLimits?: LimitSpec;\n}\n```\n\n---\n\n## Offer view: MarketplaceOfferView\n\nWhat browsing, my-state, and single-offer reads return — the public\nprojection of an offer, regardless of type:\n\n```ts\ninterface MarketplaceOfferView {\n  OfferID?: string;\n  OfferType?: MarketOfferType; // \"Listing\" | \"Auction\" | \"BuyOrder\" | \"DirectTrade\"\n  Status?: MarketOfferStatus; // \"Active\" | \"Completed\" | \"Cancelled\" | \"Declined\" | \"Expired\"\n  CreatorUserID?: string;\n  CreatorPublicData?: UserPublicDataModel; // display name/avatar for storefront rendering\n  TargetUserID?: string; // set only for DirectTrade\n  GoodsCatalogID?: string;\n  GoodsItemID?: string;\n  GoodsAmount?: number;\n  GoodsInstances?: UnstackableItemInstanceState[]; // populated when the goods are specific unstackable instances\n  Price?: ResourceBundle; // Listing/BuyOrder asking price, or DirectTrade's requestedBundle\n  Auction?: MarketplaceAuctionState; // populated only for OfferType === \"Auction\"\n  CreatedAt?: string; // ISO timestamp\n  ExpiresAt?: string;\n}\n```\n\n`Status: \"Expired\"` is set **lazily** on the read path itself\n(`MarketplaceHelpers.BuildOfferView`): an `Active` document whose `ExpiresAt`\nhas passed is projected as `\"Expired\"` in the view without writing anything to\nthe database — the authoritative DB flip only happens when the offer is\nactually claimed/finalized. Don't assume an offer past its `ExpiresAt` has\nalready flipped in storage just because a read showed `\"Expired\"`.\n\n`GoodsInstances` is `null` for `BuyOrder` offers even if the eventual goods\nwill be unstackable (a buy order names an `ItemID`/`CatalogID`, not specific\ninstances — the filler supplies fresh ones). For the other three offer types\nit's populated when the goods are unstackable, using the same\n`UnstackableItemInstanceState` shape as `InventoryV2.UnstackableItems` (see the\nitem-system skill) — `ItemInstanceID`, `Level`, `ExpiresAt`, `EquippedSlot`\n(always `null` in escrow), etc.\n\n---\n\n## Auction state\n\n```ts\ninterface MarketplaceAuctionState {\n  BidAxisType?: ResourceEntryType; // \"VirtualCurrency\" | \"Item\" — see currency-system skill\n  BidCurrencyID?: string; // set when BidAxisType is a currency\n  BidCatalogID?: string; // set when BidAxisType is an item\n  BidItemID?: string;\n  StartingBid?: number;\n  CurrentBid?: number; // 0 = no bids yet\n  CurrentBidderID?: string;\n  BidCount?: number;\n  ExtensionCount?: number; // anti-snipe extensions used so far\n  PendingRefunds?: MarketplaceBidRefund[]; // outbid players awaiting refund\n}\n\ninterface MarketplaceBidRefund {\n  BidIndex?: number;\n  UserID?: string;\n  Amount?: number;\n  Settled?: boolean; // false = still owed; drained by claimBack, getMyState, or a later bid/claim on the same offer\n  SettledAt?: string;\n}\n```\n\nBidding uses a **single comparable axis** — exactly one VC or one stackable\nitem type — so bids can be strictly ordered. `PendingRefunds` is the outbox of\nplayers who were outbid: `Settled: false` entries are what `claimBack()` (no\n`offerID`) drains across all of a player's auctions in one call. The backend\nalso opportunistically drains refunds on `getMyState()` (for the calling\nplayer's own refunds) and after any `placeBid`/`claimAuction` on the same\noffer (for all pending refunds on it) — so a stale refund is retried on the\nvery next interaction with that auction, not just via an explicit\n`claimBack`.\n\n## Auction bid-step formula\n\nTranscribed from `MarketplaceV2.PlaceBid` (`Marketplace.cs`):\n\n- **First bid** on an auction (`CurrentBid <= 0`) must be\n  `>= max(1, StartingBid)`.\n- **Every subsequent bid** must be at least\n  `CurrentBid + step`, where\n  `step = max(stepFromPercent, max(1, MinBidStepAbsolute))` and\n  `stepFromPercent = ceil(CurrentBid * MinBidStepPercent)` when\n  `MinBidStepPercent > 0`, else `1`.\n\nA rejected bid's error message already contains the computed minimum —\n`\"Bid must be at least {minAcceptable}.\"` — so a client doesn't need to\nreimplement this to show a useful error, only to build a live \"next valid bid\"\npreview in the UI.\n\nA bid within `AntiSnipeWindowSeconds` of the current `ExpiresAt` (and under\n`MaxAntiSnipeExtensions`) also pushes `ExpiresAt` out by\n`AntiSnipeExtensionSeconds` — reflected in `MarketplacePlaceBidResponse.ExpiresAt`\nfor that call, so re-render your countdown from the response rather than a\nvalue computed before the bid.\n\n---\n\n## User state: UserMarketplaceState (rate limits)\n\nReturned inside `getMyState()`'s `Limits` field and mirrored to\n`client.data.user.state?.Marketplace`:\n\n```ts\ninterface UserMarketplaceState {\n  Create?: MarketplaceActionCounter; // listings + auctions + buy orders + direct trades created\n  Buy?: MarketplaceActionCounter; // Buy, and the buyer/creator side of FillBuyOrder\n  Sell?: MarketplaceActionCounter; // the seller/filler side of Buy and FillBuyOrder\n  Bid?: MarketplaceActionCounter;\n}\n\ninterface MarketplaceActionCounter {\n  LastAt?: string; // ISO timestamp of the last action\n  DailyCount?: number;\n  DailyResetUtc?: string; // when DailyCount next resets (next UTC midnight after LastAt)\n}\n```\n\nThese mirror whichever `CreateLimits`/`BuyLimits`/`FillLimits`/`BidLimits`\n(`LimitSpec` — `CooldownSeconds` + `DailyCap`) the relevant per-type settings\nconfigured — use them to grey out a \"Create listing\" button once `DailyCount`\nhits the config's `DailyCap`. `Sell` is incremented for whichever party ends\nup supplying goods (the listing seller on `Buy`, the filler on\n`FillBuyOrder`) even though the action that triggered it was initiated by the\ncounterparty — read the two counters as \"goods flowed out\" (`Sell`) vs\n\"goods flowed in\" (`Buy`), not \"I clicked buy\" vs \"I clicked sell\".\n\n---\n\n## Responses\n\n### MarketplaceGroupedOffersResponse / MarketplaceBrowseResponse\n\n```ts\ninterface MarketplaceGroupedOfferView {\n  GoodsCatalogID?: string;\n  GoodsItemID?: string;\n  OfferCount?: number;\n}\ninterface MarketplaceGroupedOffersResponse {\n  Groups?: MarketplaceGroupedOfferView[];\n}\n\ninterface MarketplaceBrowseResponse {\n  Offers?: MarketplaceOfferView[];\n  ContinuationToken?: string; // pass back in to page further\n}\n```\n\n`getGroupedOffers()` is a storefront summary (one row per item + how many\n`Listing`/`Auction` offers exist) — it carries **no price field at all** (not\neven a min/max), confirmed against\n`MarketplaceDBService.GetGroupedActiveOffersAsync`'s aggregation, which\nprojects only the count. Drill into a specific item with `getOffersByItem` to\nget the actual `MarketplaceOfferView[]` (with `Price`/`Auction`) to buy/bid\nfrom.\n\n### MarketplaceCreateOfferResponse\n\n```ts\ninterface MarketplaceCreateOfferResponse {\n  OfferID?: string;\n  Offer?: MarketplaceOfferView;\n  Resources?: ResourceOperation; // the creator's own escrow charge (goods/payment + listing fee)\n}\n```\n\n### MarketplaceSettlementResponse\n\nReturned by cancel/buy/claimAuction/fillBuyOrder/respondDirectTrade/claimBack.\n**Exactly one** of `Settlement` or `Resources` is populated, depending on the\naction:\n\n```ts\ninterface MarketplaceSettlementResponse {\n  OfferID?: string;\n  Status?: MarketOfferStatus;\n  Settlement?: ResourceDualPartyResult; // dual-party: buy, fillBuyOrder, respondDirectTrade accept-with-price\n  Resources?: ResourceOperation; // single-party: cancel*, claimBack, claimAuction, respondDirectTrade accept-gift/decline\n  CommissionTaken?: ResourceBundle; // populated when the Commission policy took a cut\n}\n```\n\n`CommissionTaken` is populated on `buy`, `fillBuyOrder`,\n`respondDirectTrade` (commission-applicable swap), and the **seller's**\n`claimAuction` call — it is `null` on the **winner's** `claimAuction` call\n(the winner's `Resources` is a pure goods grant with nothing to report a\ncommission on), confirmed in `MarketplaceV2.ClaimAuction`:\n`CommissionTaken = isSeller ? fee : null`.\n\nSee [Settlement & escrow model](#settlement--escrow-model) below for exactly\nwhich branch each caller sees, including the direct-trade-decline special\ncase.\n\n### MarketplacePlaceBidResponse\n\n```ts\ninterface MarketplacePlaceBidResponse {\n  OfferID?: string;\n  CurrentBid?: number;\n  BidCount?: number;\n  ExpiresAt?: string; // may have moved out due to anti-snipe\n  Resources?: ResourceOperation; // the caller's own bid-escrow charge\n}\n```\n\n### MarketplaceMyStateResponse\n\n```ts\ninterface MarketplaceMyStateResponse {\n  MyOffers?: MarketplaceOfferView[]; // my active listings/auctions (Status === \"Active\" only)\n  MyLeadingBids?: MarketplaceOfferView[]; // active auctions where I'm currently winning\n  MyBuyOrders?: MarketplaceOfferView[];\n  IncomingTrades?: MarketplaceOfferView[]; // direct trades targeting me, awaiting my response\n  OutgoingTrades?: MarketplaceOfferView[]; // direct trades I sent, awaiting their response\n  Claimables?: MarketplaceOfferView[]; // ended auctions / expired offers with escrow to claim\n  DrainedRefunds?: MarketplaceBidRefund[]; // refunds settled by THIS call, if any were pending\n  Limits?: UserMarketplaceState;\n}\n```\n\n`Claimables` is a de-duplicated union (by `OfferID`) of five server-side\nchecks (`MarketplaceV2.GetMyState`): my expired listings/auctions with no\nbidder and unreturned escrow, my ended auctions with a bidder whose proceeds\naren't claimed yet, my expired buy orders with unreturned escrow, my expired\noutgoing direct trades with unreturned escrow, and auctions I'm leading whose\n`ExpiresAt` has passed but I haven't claimed goods on yet. It's the list to\ndrive a \"you have items/currency to collect\" badge — the direct signal for\nwhen to prompt `claimAuction`/`claimBack`. `DrainedRefunds` reflects only\nrefunds this specific call happened to settle (a side effect of `getMyState`\nopportunistically draining the caller's own outbox) — it is not a running\nhistory of all past refunds.\n\n### MarketplaceHistoryResponse\n\n```ts\ninterface MarketplaceHistoryEntryView {\n  OfferID?: string;\n  OfferType?: MarketOfferType;\n  FinalStatus?: MarketOfferStatus;\n  SellerUserID?: string;\n  BuyerUserID?: string;\n  GoodsCatalogID?: string;\n  GoodsItemID?: string;\n  GoodsAmount?: number;\n  PricePaid?: ResourceBundle;\n  CommissionTaken?: ResourceBundle;\n  CompletedAt?: string;\n}\ninterface MarketplaceHistoryResponse {\n  Entries?: MarketplaceHistoryEntryView[];\n  ContinuationToken?: string;\n}\n```\n\nA read-only settled-trade ledger, one entry per completed/cancelled/declined/\nexpired offer that reached a terminal write — this is the source for a \"trade\nhistory\" screen, distinct from `MyOffers` (which is current/active state).\nEntries come from an append-only log with a deterministic `LogID`\n(`\"log_{status}_{offerID}\"`), so a transaction retry can never duplicate a\nhistory row.\n\n---\n\n## Request shape\n\nEvery method builds a shared `MarketplaceRequest` internally (extends\n`BaseRequest`); you don't construct this yourself, but it's useful to know\nwhich params round-trip together on the wire:\n\n```ts\ninterface MarketplaceRequest extends BaseRequest {\n  OfferID?: string;\n  ItemID?: string;\n  CatalogID?: string;\n  GoodsAmount?: number;\n  ItemInstanceIDs?: string[];\n  PriceBundle?: ResourceBundle;\n  RequestedBundle?: ResourceBundle;\n  DurationHours?: number;\n  BidAxisType?: ResourceEntryType;\n  BidCurrencyID?: string;\n  BidCatalogID?: string;\n  BidItemID?: string;\n  StartingBid?: number;\n  BidAmount?: number;\n  TargetUserID?: string;\n  Accept?: boolean;\n  PageSize?: number;\n  ContinuationToken?: string;\n  OfferTypeFilter?: MarketOfferType;\n}\n```\n\nOne field name is reused across two different roles depending on the action:\n`ItemInstanceIDs` on a create call means \"escrow these specific instances as\nthe goods\"; it's absent on read/bid/response calls. `PageSize` is clamped\nserver-side to `1..100` regardless of what the client sends\n(`MarketplaceDBService.FindHistoryAsync` and friends).\n\n`MarketplaceAction` enumerates the 20 backend action names this request shape\ndispatches on (`GetDefinitions`, `GetGroupedOffers`, `GetOffersByItem`,\n`GetOffer`, `GetBuyOrders`, `GetMyState`, `GetHistory`, `CreateListing`,\n`CancelListing`, `Buy`, `CreateAuction`, `PlaceBid`, `ClaimAuction`,\n`CreateBuyOrder`, `CancelBuyOrder`, `FillBuyOrder`, `CreateDirectTrade`,\n`RespondDirectTrade`, `CancelDirectTrade`, `ClaimBack`) — one more than the 19\npublic `MarketplaceService` methods because `getOffersByItem`/`getBuyOrders`\nboth exist as distinct client methods but the action list also separately\nnames every read; you won't call this directly, it's internal routing.\n\n---\n\n## Settlement & escrow model\n\nEvery create call escrows something immediately, in the same transaction as\nthe offer's insert:\n\n| Create call         | What gets escrowed                                                                           |\n| ------------------- | -------------------------------------------------------------------------------------------- |\n| `createListing`     | The goods (`itemInstanceIDs` or `goodsAmount` of `itemID`), plus `ListingFee` if configured. |\n| `createAuction`     | The goods, same as a listing (no separate fee field on auctions).                            |\n| `createBuyOrder`    | The `priceBundle` (payment), not goods — inverted from a listing.                            |\n| `createDirectTrade` | The offered side (instances and/or bundle) — nothing from the target until they accept.      |\n| `placeBid`          | The bid amount — refunded to the previous leader via `PendingRefunds` when outbid.           |\n\nSettlement then plays out one of three ways:\n\n1. **Instant dual-party** — `buy`, `fillBuyOrder`, and\n   `respondDirectTrade(offerID, true)` when a `requestedBundle` was set: the\n   backend computes both sides in one atomic step\n   (`ResourceService.ApplyDualPartyAtomicAsync`) and returns\n   `ResourceDualPartyResult` (`FromUserID`/`ToUserID` +\n   `FromResult`/`ToResult`, each a `ResourceOperation`). The SDK applies\n   **only the calling player's side** — it checks which of `FromUserID`/\n   `ToUserID` matches the current session and applies that result, ignoring\n   the other party's (there is no way to see the counterparty's resulting\n   balances from this call).\n2. **Instant single-party grant** — `respondDirectTrade(offerID, true)` on a\n   pure gift (no `requestedBundle`): only `Resources` is populated, applied\n   directly to the accepter.\n3. **Lazy per-side claim** — auctions never auto-settle. After\n   `ExpiresAt`, the winning bidder and the seller each call `claimAuction`\n   independently; each call returns that caller's own `Resources` (goods to\n   the winner — the bid amount was already paid at `placeBid` time; net\n   proceeds to the seller). Nothing forces both sides to claim promptly — an\n   unclaimed auction just sits in `Claimables`.\n\n**The direct-trade-decline special case**: `respondDirectTrade(offerID,\nfalse)` returns a `Resources` grant, but it is the **escrow being returned to\nthe offer's `CreatorUserID`** (the sender getting their goods back), not a\ngrant to the decliner. Confirmed against the backend source\n(`Marketplace.cs`): decline calls `ReturnEscrowToInitiatorAsync`, which runs\n`ResourceService.ApplyResourceOperationAtomicAsync` with\n`userID: offer.CreatorUserID` — never `service.UserID` (the caller). The SDK\nintentionally does **not** apply this `Resources` to the local cache in that\nbranch — applying it would incorrectly credit the decliner's own balances with\nresources that were actually returned to someone else's account. If you need\nto reflect \"trade declined\" in the decliner's UI, do it by removing the trade\nfrom `IncomingTrades`/showing `Status: \"Declined\"` — not by expecting a\nbalance change.\n\n`cancelListing`/`cancelBuyOrder`/`cancelDirectTrade` and `claimBack` are all\nsingle-party grants (`Resources` only) refunding the **caller's own** escrow —\nstraightforward `applyResourceOperation` cases, no dual-party ambiguity. A\ncancel is only legal on an offer the caller created, while it's still\n`Active`; an auction that already has a bidder cannot be cancelled at all\n(bids are already in escrow — the only exit is `claimAuction` after\n`ExpiresAt`).\n\n---\n\n## Commission model\n\nComputed per price position (each `ResourceEntry` and each `EventTokenOperation`\nin the price bundle independently) at settlement, transcribed verbatim from\n`MarketplaceHelpers.ComputeFee`/`SplitCommission` (`MarketplaceHelpers.cs`):\n\n```\nfee = min(amount, max(ceil(amount * Percent), MinPerPosition))\nnet = amount - fee\n```\n\n- `ceil` rounds the percentage cut up to the next whole unit.\n- `MinPerPosition` is a floor, not an addition — it only raises `fee` when the\n  percentage cut would be smaller than the minimum.\n- `fee` is clamped to never exceed `amount` itself (so a price position with a\n  huge `MinPerPosition` can zero out the seller's net for that position, but\n  never make it negative).\n- A position where the resulting `net` is `0` is dropped entirely from the\n  net bundle; likewise a `fee` of `0` is dropped from the fee bundle — so\n  `CommissionTaken` only lists positions that actually had something taken.\n\nThe effective `(Percent, MinPerPosition)` pair is resolved once, at **offer\ncreation time**, and snapshotted onto the offer\n(`CommissionPercentSnapshot`/`CommissionMinSnapshot`/`CommissionSinkSnapshot`)\n— `PerCatalogOverrides[GoodsCatalogID]` if present, else the top-level\n`Percent`/`MinPerPosition` (`MarketplaceHelpers.ResolveCommission`). This\nmeans a later change to the title's commission config **never** affects an\nalready-listed offer; only new offers pick up the new rate. For a\n`DirectTrade`, the snapshot is `(0, 0)` unless\n`Commission.ApplyToDirectTrades` was `true` **and** the trade was a\nswap (not a gift) at creation time.\n\n`Sink`: `\"Burn\"` (default) destroys the commission outright — it's simply the\ndifference between what the buyer/payer consumed and what the seller was\ngranted, with no corresponding write anywhere. `\"Ledger\"` additionally credits\n`LedgerAccountID` (default `\"default\"` if empty) in the title's\n`MarketplaceLedgerDocument`, in the same transaction as the settlement — an\naccounting/reporting concept internal to the title's economy, with no\nclient-visible effect beyond `CommissionTaken` on the response. Either way,\nwhat the trading parties themselves receive is identical — the sink only\nchanges whether the fee is destroyed or recorded for the title's own\nbookkeeping.\n\n---\n\n## Server-side limits, locking, and idempotency\n\nVerified against `Marketplace.cs`/`MarketplaceHelpers.cs`/`MarketplaceDefinitions.cs`:\n\n- **Per-endpoint rate limit**: every `MarketplaceV2` action shares a 500ms\n  IP-level rate limit (`RateLimitMilliseconds = 500` in `Marketplace.cs`,\n  enforced by `ClientRun.Execute`) — a repeat call inside that window surfaces\n  to the SDK as `reason: \"throttled\"`.\n- **Per-offer mutation lock**: `buy`, `placeBid`, `claimAuction`,\n  `fillBuyOrder`, `respondDirectTrade`, every `cancel*`, and `claimBack(offerID)`\n  additionally take a short-lived Redis lock keyed on the specific `OfferID`\n  (200ms rate window, 5000ms hold, `Marketplace.cs`'s `AcquireOfferLockAsync`)\n  — this is on top of the per-endpoint rate limit and is scoped to that one\n  offer, not the whole action. A concurrent second call on the same offer\n  (yours or another player racing you for the same listing) fails with either\n  `\"Too many requests for this offer, try again.\"` or `\"This offer is being\nprocessed, try again.\"` — both are safe to retry. The Mongo-side\n  precondition (`PatchOfferInSessionAsync`'s optimistic-concurrency filter) is\n  the actual source of truth against double-sell/double-claim; the Redis lock\n  is only a latency optimization, so correctness doesn't depend on the client\n  handling this perfectly.\n- **Per-player anti-abuse caps** (checked before escrow, in addition to\n  `LimitSpec` cooldown/daily-cap pairs): `MaxActiveListings` (Listing+Auction\n  combined), `MaxActiveOrders` (BuyOrder), `MaxPendingOutgoing` (DirectTrade,\n  counts only the sender's still-`Active` outgoing offers). Each rejection\n  names the current count and the cap, e.g. `\"You have too many open offers\n(10/10).\"`\n- **Dedup / atomicity**: there is no batch/multi-item marketplace action —\n  every method operates on exactly one offer per call, so there's no\n  partial-success array to interpret (contrast with modules that expose\n  `BatchItemResult[]`). Every create is one atomic operation (escrow debit +\n  offer insert + limit-counter patch in a single transaction via\n  `ResourceService.ApplyResourceOperationAtomicAsync`); every settlement is\n  one atomic operation touching both parties via\n  `ResourceService.ApplyDualPartyAtomicAsync`. Resources for a create call\n  live on `MarketplaceCreateOfferResponse.Resources`; for a settlement, on\n  `MarketplaceSettlementResponse.Settlement` (dual-party) or `.Resources`\n  (single-party) — there is no separate top-level resources field to check.\n- **Idempotency**: create calls (`createListing`/`createAuction`/\n  `createBuyOrder`/`createDirectTrade`) resolve their idempotency key via\n  `ResourceService.ResolveRelatedEntityID(args.RelatedEntityID, \"mp_create_{userID}\" | \"mp_order_{userID}\" | \"mp_trade_{userID}\")`\n  — passing a stable `relatedEntityID` on repeated client-side retries of the\n  _same_ create prevents a duplicate offer/charge; omitting it means every\n  call is treated as a new create. Settlement actions key off the offer\n  itself (e.g. `\"MpBuy:{offerID}\"`, `\"MpBid:{offerID}:{bidIndex}\"`,\n  `\"MpAuctionGoods:{offerID}\"`), so retrying the exact same settlement call is\n  naturally idempotent without the client needing to supply anything.\n"
+    }
+  ]
+}

package/registry/skills/match-system.json

@@ -0,0 +1,11 @@
+{
+  "name": "match-system",
+  "description": "Build a PvP match system in a game on the iDosGames TypeScript SDK (@idosgames/core) via client.match (MatchService): create/update/cancel an open PvP match offer with an entry cost, resolve an instant server-side battle, save a client-side battle strategy (attack/defense zone picks per round), and list/paginate the player's own matches or matches available to join. Use this whenever the user is working in the iDosGames TS SDK or its game templates (board-game, idle-rpg) and wants PvP matchmaking, duel/arena screens, entry-cost battles, attack-zone strategy pickers, battle logs, or otherwise touches client.match, MatchService, MatchModels, PvPMatch, BattleStepConfig, InstantBattleResponse, or BattleResult — even if they don't name the module explicitly.",
+  "content": "---\nname: match-system\ndescription: >-\n  Build a PvP match system in a game on the iDosGames TypeScript SDK\n  (@idosgames/core) via client.match (MatchService): create/update/cancel an\n  open PvP match offer with an entry cost, resolve an instant server-side\n  battle, save a client-side battle strategy (attack/defense zone picks per\n  round), and list/paginate the player's own matches or matches available to\n  join. Use this whenever the user is working in the iDosGames TS SDK or its\n  game templates (board-game, idle-rpg) and wants PvP matchmaking, duel/arena\n  screens, entry-cost battles, attack-zone strategy pickers, battle logs, or\n  otherwise touches client.match, MatchService, MatchModels, PvPMatch,\n  BattleStepConfig, InstantBattleResponse, or BattleResult — even if they\n  don't name the module explicitly.\n---\n\n# Match system (iDosGames TS SDK)\n\nThe Match module is the SDK's PvP layer: one player creates a match offer\ncommitting an entry cost (currency, stackable items, and/or event tokens), an\nopponent joins (or is targeted directly), and the battle is resolved\n**instantly, server-side** — there's no live turn exchange over the wire. The\nclient's only pre-battle input is a `BattleStrategy`: a fixed sequence of\nattack/defense zone picks (Head/Torso/Legs) that both fighters' stats and gear\nfeed into a server-owned combat formula. You never compute damage, hit\nchance, or a winner yourself — you call a method, check the result, and\nrender the returned `BattleResult` (or the error).\n\nThis skill is for **using** the production `MatchService`, not for porting or\nreimplementing the combat engine. If a call is rejected, that's the backend\nenforcing a rule (entry policy, anti-abuse limit, rate limit) — surface the\nerror, don't try to reproduce the check client-side.\n\n## Mental model\n\n- A **match** (`PvPMatch`) is an offer: creator commits an `Entry` cost,\n  picks a `RuleID` (which combat/economy config applies) and optionally a\n  `CharacterID` and `BattleStrategy`, and optionally targets one opponent\n  (`TargetUserID`) or leaves it public. Status moves\n  `Open → Completed` (or `Cancelled`) — there is no persisted `InProgress`\n  step; a join and its battle resolve in the same call.\n- **Instant battle** is the resolution step: given a `MatchID` plus your\n  `CharacterID` and `BattleStrategy`, the server runs the fight immediately\n  and returns a `BattleResult` — winner, loser, entry/reward bundles, and a\n  full round-by-round `BattleLog`. This is the \"PvP\" combat resolution;\n  nothing about it is real-time/turn-based on the client.\n- **Battle strategy** (`BattleStepConfig[]`) is the only player-authored\n  combat input: a list of `{ AttackTarget, DefenseTarget }` picks (each a\n  `\"Head\" | \"Torso\" | \"Legs\"`), one per round, capped at 10 steps server-side\n  (extra steps are silently dropped) and cycled by index if the battle runs\n  longer. You can attach a strategy inline to\n  `createMatch`/`updateMatch`/`instantBattle`, or persist a default one\n  independently with `saveStrategy` (cached at\n  `client.data.user.state?.Match?.PvPBattleStrategy`). **If neither a request\n  strategy nor a saved one is available, the server generates a random\n  3-step strategy** — don't assume a battle without an explicit strategy\n  fails; it just fights randomly.\n- Rewards can be **single-party** (`Resources: ResourceOperation`, e.g. on\n  `createMatch`/`cancelMatch` where only your own balance moves, and on a\n  **draw**, which refunds the creator) or **dual-party**\n  (`ResourcesDual: ResourceDualPartyResult`, on a **decisive** `instantBattle`,\n  since both fighters' balances change from one call). The SDK always\n  applies only **your** side to the local cache — see Gotchas.\n- Terminology note: the SDK and backend deliberately use **Entry** (the cost\n  to participate) and **NetReward** (the winner's payout after burn) — not\n  \"stake\"/\"wager\". Mirror that vocabulary in your own UI copy.\n\nFor the full config shape (entry whitelists, creation costs/limits, the\ncombat stat-mapping and formula blocks) and the full response/state shapes\n(`PvPMatch`, `BattleResult`, `PlayerBattleProfile`), see\n[references/data-model.md](references/data-model.md).\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any auth.* method\n\nconst match = client.match; // the MatchService\n```\n\nEvery match method requires an authenticated session. Without one they return\n`{ ok: false, reason: \"unauthorized\" }` — they do not throw.\n\n## Methods\n\nAll methods return `Promise<OperationResult<T>>`: either `{ ok: true, data }`\nor `{ ok: false, reason, error }`. Always branch on `result.ok` before\ntouching `result.data`. `reason` is one of `\"client\"` (bad local args, e.g.\nmissing `matchID`), `\"unauthorized\"`, `\"throttled\"` (fired the same endpoint\nagain inside the default throttle window), `\"connection\"` (transient, offer\nRetry), `\"validation\"` (response/schema drift), or `\"server\"` (backend\nrejected it — `error` carries the human-readable reason straight from the\nbackend, e.g. `\"Entry is required.\"`, `\"Unknown entry currency 'gems'.\"`,\n`\"You have too many open matches (3/3).\"`).\n\n| Method                                                                     | Purpose                                                                                       | `data` on success                                                  |\n| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |\n| `createMatch(entry, ruleID, characterID?, battleStrategy?, targetUserID?)` | Open a new match: commit `entry`, pick a rule/character, optionally target one opponent.      | `CreateMatchResponse` (`MatchID`, `Status`, `Entry`, `Resources`)  |\n| `updateMatch(matchID, fields?)`                                            | Edit an **open** match's own fields (privacy, rule, character, strategy) before anyone joins. | `UpdateMatchResponse` (`Match`)                                    |\n| `cancelMatch(matchID)`                                                     | Cancel your own open match; refunds the entry cost (+ creation cost, if configured).          | `CancelMatchResponse` (`Status`, `Resources`)                      |\n| `instantBattle(matchID, ruleID, characterID?, battleStrategy?)`            | Join an open match and resolve it immediately server-side.                                    | `InstantBattleResponse` (`Battle`, `Resources` or `ResourcesDual`) |\n| `saveStrategy(battleStrategy)`                                             | Persist a default battle strategy independent of any specific match.                          | `SuccessResponse`                                                  |\n| `getMyMatches(page?, pageSize?, statuses?)`                                | Paged list of matches you created or joined, optionally filtered by status.                   | `MatchesPageResponse`                                              |\n| `getAvailableMatches(page?, pageSize?, onlyPublic?)`                       | Paged list of open matches you could join.                                                    | `MatchesPageResponse`                                              |\n| `getDefinitions()`                                                         | Load the title's Match config (rules, entry whitelist, combat formulas).                      | `GetMatchDefinitionsResponse` (`MatchDefinitions`)                 |\n\n`updateMatch`'s `fields` is `{ targetUserID?, clearTargetUser?, ruleID?,\ncharacterID?, battleStrategy? }` — all optional, only the fields you pass are\nchanged; the entry cost itself can never be edited (cancel and recreate to\nchange it). `clearTargetUser: true` makes a private match public again and\ntakes priority over `targetUserID` if both are set. `getMyMatches`/\n`getAvailableMatches` default to `page = 0, pageSize = 20` (server clamps\n`pageSize` to 50); `statuses` filters `getMyMatches` to specific\n`MatchStatus` values (`\"Open\" | \"InProgress\" | \"Cancelled\" | \"Completed\"` —\n`\"InProgress\"` is defined but never actually persisted by this backend);\n`onlyPublic` restricts `getAvailableMatches` to untargeted matches (targeted\nmatches you're the target of are included by default).\n\n`entry` for `createMatch` is a `ResourceBundle` (`{ Entries?, EventTokens? }`)\n— the exact shape shared with Currency/Store, not a bare number. `ruleID`\nmust exist in the title's `MatchDefinitions` (or be the built-in\n`\"InstantBattle1v1\"`, always available even with no title config). Passing a\n`ruleID` to `instantBattle` that doesn't match the offer's own `RuleID` fails\nwith `\"RuleID mismatch.\"` — always read `ruleID` off the listing you're\njoining, don't hardcode it.\n\nOn success, `createMatch`/`cancelMatch`/`instantBattle` also **mirror the\nconfirmed resource change into the cache** (balances update immediately —\nread them from `client.data`), and every method emits an event. `saveStrategy`\nmirrors the strategy into `client.data.user.state?.Match?.PvPBattleStrategy`.\n`getDefinitions()` mirrors into\n`client.data.config.getSection<MatchDefinitions>(\"Match\")`.\n\n## Events\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn:\n\n- `match:created` → `CreateMatchResponse`\n- `match:updated` → `UpdateMatchResponse`\n- `match:cancelled` → `CancelMatchResponse`\n- `match:instantBattleCompleted` → `InstantBattleResponse`\n- `match:strategySaved` → `BattleStepConfig[]`\n- `match:myMatchesLoaded` → `MatchesPageResponse`\n- `match:availableMatchesLoaded` → `MatchesPageResponse`\n- `match:definitionsLoaded` → `GetMatchDefinitionsResponse`\n\nThe coarse `user:matchUpdated` (and umbrella `user:anyUpdated`) also fire\nwhenever `saveStrategy` patches the cache — handy for a \"re-render everything\"\nhook. Note it does **not** fire on `createMatch`/`cancelMatch`/`instantBattle`;\nthose only touch the resource-balance cache (which fires its own\n`user:inventoryUpdated`/`user:virtualCurrencyUpdated`/`user:anyUpdated`) and\ntheir own `match:*` event above — there's no cached `PvPMatch` list kept in\nsync automatically, so re-fetch with `getMyMatches`/`getAvailableMatches`\nafter acting instead of assuming the list you already loaded is current.\n\n```ts\nconst off = client.on(\"match:instantBattleCompleted\", (r) => {\n  console.log(r.Battle?.WinnerUserID === myUserID ? \"Won!\" : \"Lost.\");\n});\n// later: off();\n```\n\n## Recipes\n\n### Save a default battle strategy\n\n```ts\nconst res = await client.match.saveStrategy([\n  { AttackTarget: \"Head\", DefenseTarget: \"Torso\" },\n  { AttackTarget: \"Legs\", DefenseTarget: \"Head\" },\n]);\nif (!res.ok) return showError(res.error);\n\n// cached immediately:\nclient.data.user.state?.Match?.PvPBattleStrategy;\n```\n\nEach entry is one round's picks (max 10; extras are dropped server-side).\nThis is independent of any match — a good default to fall back to when the\nplayer hasn't set a per-match strategy. Skipping this entirely is valid too:\nthe server falls back to a random strategy when a battle needs one and none\nwas ever saved or passed inline.\n\n### Create an open match, then let someone join and resolve it\n\n```ts\nconst created = await client.match.createMatch(\n  { Entries: [{ Type: \"VirtualCurrency\", CurrencyID: \"coins\", Amount: 100 }] },\n  \"InstantBattle1v1\",\n  \"Knight\",\n  [{ AttackTarget: \"Head\", DefenseTarget: \"Torso\" }],\n);\nif (!created.ok) return showError(created.error); // e.g. can't afford, over MaxOpenMatches\nconst matchID = created.data.MatchID; // Status is \"Open\"\n\n// ...opponent joins out-of-band (server flow)...\n\nconst battle = await client.match.instantBattle(\n  matchID,\n  \"InstantBattle1v1\",\n  \"Knight\",\n  [{ AttackTarget: \"Head\", DefenseTarget: \"Torso\" }],\n);\nif (!battle.ok) return showError(battle.error);\nbattle.data.Battle?.WinnerUserID;\nbattle.data.Battle?.BattleLog; // round-by-round hits, for a replay UI\n```\n\nOmit `targetUserID` to leave the match open to anyone; pass it to challenge a\nspecific player directly. Creating a match requires you to already have an\nactivated character to fight with — `createMatch` fails up front with\n`\"You don't have a character to create a match with.\"` rather than letting\nyou open a match nobody (including you) could ever resolve.\n\n### Cancel an open match\n\n```ts\nconst res = await client.match.cancelMatch(matchID);\nif (!res.ok) return showError(res.error); // e.g. \"Only an open match can be cancelled.\"\n// entry cost (and creation cost, if the rule refunds it) is already refunded in the cache\n```\n\nOnly works while the match is still `\"Open\"` (nobody has joined). Once a\nmatch is claimed by a joiner and resolved, cancelling is rejected with\n`\"Only an open match can be cancelled.\"` — there's a race window (someone can\njoin between your UI showing \"Open\" and your cancel landing); treat that\nrejection as \"too late,\" not a bug.\n\n### Update a match's privacy before anyone joins\n\n```ts\n// make a public match private, targeting one player:\nawait client.match.updateMatch(matchID, { targetUserID: \"player-42\" });\n\n// make it public again:\nawait client.match.updateMatch(matchID, { clearTargetUser: true });\n```\n\nOnly fields you pass are changed; this only succeeds while the match is\nstill open and yours (`\"Only the match creator can edit it.\"` /\n`\"Only an open match can be edited.\"` otherwise).\n\n### List matches to join, then list my own history\n\n```ts\nconst available = await client.match.getAvailableMatches(0, 20, true); // public only\nif (available.ok) {\n  for (const m of available.data.Matches ?? []) {\n    // m.Entry, m.RuleID, m.CreatorID — render as a joinable card\n  }\n  available.data.HasMore; // paginate: getAvailableMatches(page + 1, ...)\n}\n\nconst mine = await client.match.getMyMatches(0, 20, [\"Open\", \"InProgress\"]);\n```\n\n### Reading a dual-party instant-battle result\n\n```ts\nconst battle = await client.match.instantBattle(matchID, \"InstantBattle1v1\");\nif (battle.ok) {\n  const d = battle.data;\n  if (d.Resources) {\n    // single-party shape — this was a draw: only the creator's refund moved.\n  } else if (d.ResourcesDual) {\n    // decisive result; both sides changed. The SDK already applied only\n    // *your* half to the cache (matched against your userID). Read the\n    // other side purely for display, e.g. an opponent summary — don't\n    // apply it yourself.\n    const mine =\n      d.ResourcesDual.FromUserID === myUserID\n        ? d.ResourcesDual.FromResult\n        : d.ResourcesDual.ToResult;\n  }\n  d.Battle?.NetReward; // winner's payout bundle after burn (null on a draw)\n}\n```\n\n## Gotchas\n\n- **Instant battle resolves immediately — there's no live turn exchange.**\n  `BattleStrategy` is submitted up front (per-round zone picks); the server\n  runs every round in one call and hands back the full `BattleLog`. Build a\n  \"replay\" animation client-side off the log rather than expecting a\n  round-by-round network exchange.\n- **No strategy set is not an error — it's a random fighter.** If you call\n  `instantBattle`/`createMatch` without `battleStrategy` and the player never\n  called `saveStrategy`, the server rolls a random 3-step strategy for that\n  side. Don't rely on this for a real match — always send a real strategy (or\n  save a default) once your UI has one, but don't treat its absence as a\n  client-side validation error either.\n- **`ResourcesDual` only applies your own side.** `instantBattle` matches\n  `FromUserID`/`ToUserID` (the loser/winner respectively) against the logged-in\n  user and applies only the matching `FromResult`/`ToResult` to the cache —\n  the other fighter's balance change is informational only (e.g. for a\n  results screen), not something you apply locally. On a **draw**, only\n  `Resources` is set (a refund to the creator) and `ResourcesDual` is null.\n- **No auto-synced match list.** There's no cached `Record<MatchID, PvPMatch>`\n  kept current by events — `match:created`/`match:updated`/`match:cancelled`\n  just report that one call's result. Re-fetch `getMyMatches`/\n  `getAvailableMatches` to refresh a list view after any mutation.\n- **`UserMatchState` (`client.data.user.state?.Match`) is thin.** It only\n  holds `PvPBattleStrategy` and `CreationLimits` — there is no cached list of\n  the player's matches there; use `getMyMatches` for that. Also note this\n  slot is only ever written by `saveStrategy` in this SDK — nothing hydrates\n  it from the login bootstrap, so until the player calls `saveStrategy` (or\n  `createMatch`/`updateMatch` with an inline strategy) once this session,\n  `PvPBattleStrategy` reads as `undefined` even if the backend has a\n  previously-saved strategy for them. `CreationLimits` is populated by the\n  backend on `createMatch` but nothing in this SDK reads it back into the\n  cache yet — treat it as informational/future.\n- **Guard against double-submit.** Each call mints a fresh idempotency key, so\n  two separate calls are two real operations — a double-clicked \"Create\n  match\" or \"Fight\" can charge/resolve twice. Disable the control while a\n  call is in flight.\n- **Anti-abuse is server-enforced, not just a UI nicety.** A title can cap\n  simultaneously open offers (`MaxOpenMatches`), rate-limit creation\n  (cooldown + daily cap via `Limits`), and cap completed matches against the\n  same opponent per day (`MaxMatchesPerOpponentPerDay`, an anti win-trading\n  measure). All three surface as ordinary `reason: \"server\"` rejections —\n  show the message, don't try to pre-count client-side.\n- **`CharacterID` is optional but rule-dependent.** Whether a character (and\n  its stats/gear) feeds the combat formula depends on the rule's\n  `StatMapping`/`Formula` config — see\n  [references/data-model.md](references/data-model.md). Character combat\n  math and equipment are documented in\n  `.claude/skills/character-system/SKILL.md`; don't re-derive Power/stat\n  formulas here.\n- **Entry/reward bundles use the shared resource types.** `Entry`,\n  `Resources`, `ResourcesDual` all build on `ResourceBundle`/\n  `ResourceOperation`/`ResourceConsume` — fully documented in\n  `.claude/skills/currency-system/SKILL.md`; cross-link rather than\n  re-deriving.\n\n## Full reference\n\n[references/data-model.md](references/data-model.md) — the full\n`MatchDefinitions` config shape (entry whitelist, creation cost/limits, combat\nstat-mapping and formula blocks), the `PvPMatch`/`BattleResult`/\n`PlayerBattleProfile` response shapes, the net-reward/burn formula, and the\nbattle-log entry shape. Read it when building config-driven UI (entry\npickers, cost previews) or a battle-log replay screen.\n",
+  "references": [
+    {
+      "path": "data-model.md",
+      "content": "# Match data model — reference\n\nFull shape of the config (`MatchDefinitions`), the match/battle state, and the\nrequest/response types. All of these are **strictly typed in the SDK** —\n`MatchDefinitions` and every nested block (`InstantBattleRule`,\n`MatchEntrySettings`, `MatchStatFormula`, …) are exported from\n`@idosgames/core`, so `getDefinitions()` and\n`getSection<MatchDefinitions>(\"Match\")` give you concrete types, not\n`unknown`. The schemas keep `.passthrough()`, so a field the backend adds\nlater still round-trips. Field names are PascalCase (straight from the\nbackend JSON).\n\nTerminology: the backend consistently calls the cost to participate **Entry**\nand the winner's payout **NetReward** — there is no \"stake\"/\"wager\" anywhere\nin the Match model. Use that vocabulary in any UI copy you generate.\n\n## Contents\n\n- [Player state](#player-state) — `UserMatchState`\n- [Match (offer)](#match-offer) — `PvPMatch`\n- [Battle result](#battle-result) — `BattleResult`, `BattleLogEntry`, `PlayerBattleProfile`, `FighterStats`\n- [Config: MatchDefinitions](#config-matchdefinitions) — what `getDefinitions()` returns\n- [InstantBattleRule](#instantbattlerule)\n- [Combat formulas](#combat-formulas) — `CombatStatMapping`, `MatchStatFormula`, `FormulaTerm`/`FormulaFactor`, the stat-calculation layers\n- [Entry & creation settings](#entry--creation-settings) — whitelist, anti-abuse limits\n- [Net reward / burn formula](#net-reward--burn-formula)\n- [Battle strategy resolution](#battle-strategy-resolution) — random fallback, step cap\n- [Request shape](#request-shape)\n\n---\n\n## Player state\n\nCached at `client.data.user.state?.Match` as `UserMatchState`. Populated\n**only** by `saveStrategy` in this SDK (see Gotchas in SKILL.md) — nothing\nhydrates it at login.\n\n```ts\ninterface UserMatchState {\n  PvPBattleStrategy?: BattleStepConfig[];\n  CreationLimits?: UserMatchCreationLimitState | null;\n}\n\ninterface UserMatchCreationLimitState {\n  LastCreatedAt?: string; // ISO timestamp of the last createMatch call\n  DailyCreations?: number; // counter toward Limits in MatchCreationSettings\n  DailyResetUtc?: string; // next UTC midnight reset\n}\n\ninterface BattleStepConfig {\n  AttackTarget: \"Head\" | \"Torso\" | \"Legs\";\n  DefenseTarget: \"Head\" | \"Torso\" | \"Legs\";\n}\n```\n\n`CreationLimits` mirrors the cooldown/daily-cap counters the backend keeps\nserver-side (`Match.CreationLimits` on the player document, written by\n`MatchHelpers.BuildCreationLimitPatches` inside the `createMatch` transaction)\nfor a rule's `Creation.Limits` (a `LimitSpec`). It's exposed on the wire type\nfor a client to eventually show \"next match available in…\" UI, but nothing in\n`MatchService` currently reads it back into this cache slot — treat it as\ninformational/future until a response actually populates it for you.\n\n---\n\n## Match (offer)\n\n`PvPMatch` — one open/resolved match, returned inside `MatchesPageResponse`\nand `UpdateMatchResponse`.\n\n```ts\ninterface PvPMatch {\n  MatchID: string;\n  TitleID?: string;\n  RuleID?: string;\n  CreatedAt?: string;\n  CreatorID?: string;\n  CreatorCharacterID?: string;\n  CreatorStrategy?: BattleStepConfig[]; // stripped from GetAvailableMatches listings\n  TargetUserID?: string; // set = private/targeted challenge; absent = public\n  Entry?: ResourceBundle; // the creator's entry cost\n  CreationCostPaid?: ResourceBundle; // separate from Entry — the fee to open the match\n  RefundCreationCostOnCancel?: boolean;\n  JoinedByUserID?: string;\n  JoinedByCharacterID?: string;\n  JoinedAt?: string;\n  Status?: \"Open\" | \"InProgress\" | \"Cancelled\" | \"Completed\";\n  WinnerUserID?: string; // absent/null on a draw\n  CompletedAt?: string;\n  IsRewardDistributed?: boolean;\n  RewardDistributedAt?: string;\n}\n```\n\n`Entry` (the cost to participate) and `CreationCostPaid` (the fee to list the\nmatch) are tracked separately — cancelling refunds the entry cost always, and\nthe creation fee only when `RefundCreationCostOnCancel` is true.\n\n`Status` never actually passes through `\"InProgress\"` in this backend: a join\nresolves the battle synchronously in the same call, so a match goes directly\n`Open → Completed` (backend: `MatchDatabase.TryFinalizeOpenMatchInSessionAsync`\nsets `Completed` straight from an `Open` filter). `\"InProgress\"` exists in the\nenum for forward-compat / other match modes, not for instant-battle.\n\n`GetAvailableMatches` listings project out `CreatorStrategy` (backend:\n`MatchDatabase.ReadAvailableMatchesPagedAsync` excludes it) — you only see a\nmatch's strategy from `getMyMatches` or after you've fetched the match some\nother way; it isn't needed to join, since your own strategy is what you send\nto `instantBattle`.\n\n---\n\n## Battle result\n\nReturned inside `InstantBattleResponse.Battle`.\n\n```ts\ninterface BattleResult {\n  WinnerUserID?: string; // absent on a draw\n  LoserUserID?: string; // absent on a draw\n  Entry?: ResourceBundle; // one side's entry cost that was in play\n  NetReward?: ResourceBundle; // winner's payout after burn; null on a draw\n  BattleLog?: BattleLogEntry[]; // full round-by-round hit list\n  IsDraw?: boolean;\n  P1BattleProfile?: PlayerBattleProfile; // the match creator\n  P2BattleProfile?: PlayerBattleProfile; // the joiner (the caller of instantBattle)\n}\n\ninterface BattleLogEntry {\n  RoundIndex?: number; // 1-based\n  AttackerID?: string;\n  DefenderID?: string;\n  AttackZone?: \"Head\" | \"Torso\" | \"Legs\";\n  DefenseZone?: \"Head\" | \"Torso\" | \"Legs\";\n  HitType?: \"Hit\" | \"Critical\" | \"Block\" | \"Dodge\";\n  DamageDealt?: number; // 0 on Dodge; reduced (BlockDamageMultiplier) on Block\n  DefenderHpRemaining?: number; // floored at 0\n}\n\ninterface PlayerBattleProfile {\n  UserID?: string;\n  SelectedCharacterID?: string;\n  SelectedCharacter?: CharacterModel; // see character-system skill\n  BattleStrategy?: BattleStepConfig[]; // the strategy actually used (inline, saved, or random)\n  UnstackableItems?: Record<string, UnstackableItemInstanceState>; // always null on the wire in practice\n  Stats?: FighterStats; // final computed combat stats used for this fight\n}\n\ninterface FighterStats {\n  MaxHp?: number; // starting HP, for a results-screen HP bar\n  CurrentHp?: number; // HP at the end of the fight\n  Damage?: number;\n  AttackSpeed?: number; // higher acts first each round; a tie coin-flips\n  CritChance?: number; // 0..MaxCritChance\n  CritMultiplier?: number;\n  Armor?: number; // flat damage reduction\n  DodgeChance?: number; // 0..MaxDodgeChance\n}\n```\n\nEach round, both fighters act in `AttackSpeed` order (ties broken by a random\ncoin flip — backend `PvPBattleEngine.SimulateBattle`); if the first attacker's\nhit drops the defender to 0 HP, the defender does not get to act that round.\n`AttackZone`/`DefenseZone` per log entry come from each side's\n`BattleStrategy`, indexed `(RoundIndex - 1) % strategy.length` — a\nstrategy shorter than the battle simply repeats from the top.\n\nPer-hit resolution order (backend `PvPBattleEngine.PerformAttack`):\n\n1. Roll crit: `isCrit = random() < attacker.CritChance`.\n2. `rawDamage = isCrit ? attacker.Damage * attacker.CritMultiplier : attacker.Damage`.\n3. `potentialDamage = max(MinHitDamage, rawDamage - defender.Armor)`.\n4. If `AttackZone === DefenseZone` → **Block**: `DamageDealt = round(potentialDamage * BlockDamageMultiplier, 2)`.\n5. Else if `random() < defender.DodgeChance` → **Dodge**: `DamageDealt = 0`.\n6. Else → **Hit** (or **Critical** if step 1 rolled true): `DamageDealt = potentialDamage`.\n\nThe battle ends when a fighter's HP hits 0, or after `MaxRounds` (default 50)\n— on timeout, higher remaining HP wins; exactly equal HP is a draw.\n\n`PlayerBattleProfile.UnstackableItems` is documented as an **input-only**\nlevel-scaling snapshot the engine used internally — the backend\n(`PvPBattleEngine.TrimProfile`) always strips it before the response reaches\nthe client, so expect it to read as `null`/absent in practice. Don't build UI\nthat depends on it being populated.\n\n`FighterStats` is the resolved combat stats each fighter fought with — read\nthese for a \"stat comparison\" results screen, but they are a snapshot of that\none fight, not a live/cached character stat.\n\n---\n\n## Config: MatchDefinitions\n\nReturned by `getDefinitions()`; cached via\n`client.data.config.getSection<MatchDefinitions>(\"Match\")`.\n\n```ts\ninterface MatchDefinitions {\n  InstantBattle?: InstantBattleDefinitions;\n}\n\ninterface InstantBattleDefinitions {\n  Rules?: Record<string, InstantBattleRule>; // key = RuleID\n  Defaults?: InstantBattleSettings; // title-wide combat fallback\n  EntryDefaults?: MatchEntrySettings; // title-wide entry-whitelist fallback\n  CreationDefaults?: MatchCreationSettings; // title-wide creation cost/limits fallback\n}\n```\n\nCurrently `MatchDefinitions` has a single mode container, `InstantBattle` —\nthere's no other battle mode in the model today. If the title hasn't\nconfigured `Match` at all, `getDefinitions()` still returns a synthesized\nconfig with one rule, `\"InstantBattle1v1\"`, built from engine defaults\n(backend: `Match.GetDefinitions` / `MatchConfigResolver.BuiltInInstantBattle1v1`)\n— so there is always at least one valid `RuleID` to pass.\n\nResolution order for every block is **rule's own → title `Defaults` (or\n`EntryDefaults`/`CreationDefaults`) → engine built-in default** — the same\ninline-over-preset pattern the character module uses. `StatMapping` resolves\nper-field (each role can come from a different layer); `Combat`, `Entry`,\n`Creation` resolve as whole blocks (a rule that sets `Entry` gets none of the\ntitle's `EntryDefaults`, even for fields it left unset).\n\n---\n\n## InstantBattleRule\n\nOne entry in `InstantBattleDefinitions.Rules`, keyed by `RuleID` (the string\nyou pass as `ruleID` to `createMatch`/`updateMatch`/`instantBattle`).\n\n```ts\ninterface InstantBattleRule {\n  RuleID?: string;\n  DisplayName?: string;\n  Description?: string;\n  Economy?: MatchEconomySettings;\n  Entry?: MatchEntrySettings;\n  Creation?: MatchCreationSettings;\n  Settings?: InstantBattleSettings;\n}\n\ninterface MatchEconomySettings {\n  BurnRate?: number; // fraction of the *reward* burned when paid to the winner; default 0.05 (5%)\n}\n```\n\n---\n\n## Combat formulas\n\n`InstantBattleSettings` (a rule's `Settings`, or the title-wide `Defaults`)\nconfigures how a fighter's `FighterStats` are derived for a battle.\n\n```ts\ninterface InstantBattleSettings {\n  StatMapping?: CombatStatMapping;\n  Combat?: MatchCombatSettings;\n  Formula?: MatchStatFormula;\n}\n\ninterface CombatStatMapping {\n  HealthStatID?: string; // which character StatID feeds MaxHp. Default: \"Health\"\n  DamageStatID?: string; // Default: \"Damage\"\n  ArmorStatID?: string; // Default: \"Armor\"\n  AttackSpeedStatID?: string; // Default: \"AttackSpeed\"\n  CritChanceStatID?: string; // Default: \"CritChance\"\n  CritDamageStatID?: string; // Default: \"CritDamage\"\n  DodgeStatID?: string; // Default: \"Speed\"\n  AllMightStatID?: string; // overall percent multiplier stat. Default: \"AllMight\"\n}\n\ninterface MatchCombatSettings {\n  MaxRounds?: number; // default 50; timeout winner = higher HP, tie = draw\n  BlockDamageMultiplier?: number; // damage fraction on a block (zones match); default 0.01 (1%)\n  MinHitDamage?: number; // floor for a hit after armor; default 1\n  DefaultCritMultiplier?: number; // used when CritMultiplier resolves to <= 0; default 1.5\n  MaxCritChance?: number; // clamp; default 0.6\n  MaxDodgeChance?: number; // clamp; default 0.4\n}\n\ninterface MatchStatFormula {\n  Health?: CombatRoleFormula;\n  Damage?: CombatRoleFormula;\n  Armor?: CombatRoleFormula;\n  AttackSpeed?: CombatRoleFormula;\n  CritChance?: CombatRoleFormula;\n  CritDamage?: CombatRoleFormula;\n  Dodge?: CombatRoleFormula;\n}\n\ninterface CombatRoleFormula {\n  Terms?: FormulaTerm[]; // the role's value = sum of terms\n}\n\ninterface FormulaTerm {\n  Coefficient?: number; // default 1; term = Coefficient * product(Factors); no Factors = the Coefficient itself\n  Factors?: FormulaFactor[];\n}\n\ninterface FormulaFactor {\n  Source?:\n    | \"Constant\"\n    | \"Stat\"\n    | \"RankMultiplier\"\n    | \"AllMight\"\n    | \"GearFlat\"\n    | \"GearPercent\";\n  StatID?: string; // used for Stat/GearFlat/GearPercent; empty string for Stat = \"this role's own mapped stat\"\n  Value?: number; // used for Constant\n  OnePlus?: boolean; // when true, factor contributes as (1 + value) — e.g. (1 + AllMight)\n}\n```\n\nThis is a **data-driven formula DSL**, not a fixed equation: each combat role\n(Health, Damage, Armor, …) is a sum of terms, each term a product of factors\npulled from a stat, a rank multiplier, gear flat/percent bonuses, or a plain\nconstant. `CombatStatMapping` is what ties an abstract role (\"Damage\") back to\na concrete character `StatID` so the character's `StatLevels` (see\n`character-system` skill) feed into it — the same `StatID`s also key\nequipment flat/percent bonuses, so a remap automatically covers gear too.\nFactors reference base per-stat values and multipliers, never another role's\n_final_ value, so there are no formula cycles.\n\n**When a role has no custom formula** (`Formula` unset for that role), the\nengine falls back to its built-in default (backend\n`PvPBattleEngine.CalculateStats`), which is useful context for previews:\n\n- `MaxHp = (Stat(Health) * RankMultiplier + GearFlat(Health)) * (1 + AllMight)`\n- `Damage = (Stat(Damage) * RankMultiplier + GearFlat(Damage)) * (1 + AllMight)`\n- `Armor = Stat(Armor) * RankMultiplier + GearFlat(Armor)` (no AllMight)\n- `AttackSpeed = (Stat(AttackSpeed) + GearFlat(AttackSpeed)) * (1 + GearPercent(AttackSpeed))` (no rank/AllMight)\n- `CritChance = Stat(CritChance) + GearFlat(CritChance) + GearPercent(CritChance)`, then clamped to `MaxCritChance`\n- `CritDamage = Stat(CritDamage) + GearFlat(CritDamage) + GearPercent(CritDamage)`, or `DefaultCritMultiplier` if ≤ 0\n- `Dodge = Stat(Dodge) + GearFlat(Dodge) + GearPercent(Dodge)`, then clamped to `MaxDodgeChance`\n\nWhere `Stat(role)` is the character's Layer-1 stat value (base + per-level\nscaling + character-rank scaling — see `character-system`\n`references/data-model.md`), `RankMultiplier` is the character's current\nrank's `GlobalStatMultiplier`, `AllMight` is the raw (un-offset) AllMight\ncontribution from level + gear, and `GearFlat`/`GearPercent` are the\nequipped-item bonuses for that `StatID` (scaled by the item instance's\nupgrade level). **This is config for building previews/tooltips, not\nsomething to execute client-side to predict a battle outcome** — the server\nevaluates it; treat any client-side evaluation as an estimate only.\n\n---\n\n## Entry & creation settings\n\n```ts\ninterface MatchEntrySettings {\n  AllowVirtualCurrency?: boolean; // default true; any title VC, no amount bound. Ignored if Allowed is non-empty\n  AllowItems?: boolean; // default false; any stackable catalog item. Unstackable items are always rejected regardless\n  AllowEventTokens?: boolean; // default false\n  Allowed?: EntryResourceRule[]; // non-empty = authoritative whitelist; type flags above are then ignored\n  MaxPositions?: number; // cap on distinct entry positions (Entries + EventTokens combined); default 10; 0 = unlimited\n}\n\ninterface EntryResourceRule {\n  Kind?: \"VirtualCurrency\" | \"Item\" | \"EventToken\";\n  CurrencyID?: string; // when Kind === \"VirtualCurrency\"\n  CatalogID?: string; // when Kind === \"Item\"\n  ItemID?: string; // when Kind === \"Item\"\n  TokenType?: EventTokenType; // when Kind === \"EventToken\" (\"TimedEvent\"|\"Quest\"|\"Leaderboard\"|\"CoopEvent\"|\"Season\")\n  EntityID?: string; // event/entity scoping for EventToken rules; empty = any entity of that TokenType\n  MinAmount?: number; // 0 = no lower bound\n  MaxAmount?: number; // 0 = no upper bound\n}\n\ninterface MatchCreationSettings {\n  Cost?: ResourceConsume; // flat fee to open a match, separate from Entry; only .Standard is honored (no premium discount)\n  RefundCostOnCancel?: boolean; // default false — creation fee is sunk on cancel unless true\n  MaxOpenMatches?: number; // cap on this player's simultaneous Open matches; 0 = no limit\n  Limits?: LimitSpec; // only CooldownSeconds and DailyCap are enforced here; other LimitSpec axes are ignored\n  AllowPrivateMatches?: boolean; // default true; whether TargetUserID is permitted at all\n  MaxMatchesPerOpponentPerDay?: number; // anti win-trading cap vs one opponent, both directions, per UTC day; 0 = no limit\n}\n```\n\nUse `Allowed` + the `Allow*` booleans to build the entry-cost picker: only\noffer currencies/items/event tokens the rule permits, and clamp the amount\ninput to `MinAmount`/`MaxAmount` per matched rule. Unstackable items can never\nbe an entry position (backend rejects with `\"Unstackable items cannot be used\nas an entry.\"` regardless of policy) — refunding/awarding would have to\nrecreate the item instance and lose its upgrade level. Duplicate positions\n(same currency, or same catalog+item, or same event-token address) submitted\nin one `Entry` are merged server-side before validation, so you don't need to\ndedupe client-side.\n\n`Cost` (creation fee) is distinct from the `Entry` you pass to `createMatch`\n— both can be charged on creation (merged into one `Consume.Standard` charge),\nand `RefundCostOnCancel` (on `MatchCreationSettings`) /\n`RefundCreationCostOnCancel` (the matching flag snapshotted onto `PvPMatch` at\ncreation time) control only the creation fee on cancel; the entry cost itself\nis always refunded on a successful cancel. The creation fee is **always**\nsunk once a match is actually played (win, loss, or draw), regardless of the\nrefund flag. Don't assume what was refunded — read it off\n`CancelMatchResponse.Resources`, which reflects what the server actually\nreturned.\n\n`MaxMatchesPerOpponentPerDay` is checked twice: a courtesy pre-check on\n`createMatch` when targeting a specific opponent, and the authoritative check\non `instantBattle` (both directions of the pair, UTC calendar day, counting\n`Completed` matches) — a private challenge can still be rejected at battle\ntime even if it passed at creation time if the pair played other matches in\nbetween.\n\n---\n\n## Net reward / burn formula\n\nOn a decisive `instantBattle` (not a draw), the winner's `NetReward` doubles\neach of the loser's-and-winner's-combined entry positions and burns a share\nof virtual-currency positions only (backend `MatchHelpers.BuildNetRewardBundle`\n/ `CalculateNetReward`):\n\n- For each **VirtualCurrency** entry of amount `a`: `doubled = a * 2`,\n  `burn = floor(doubled * BurnRate)`, reward amount = `doubled - burn`.\n  `BurnRate` is clamped to `[0, 1]` and defaults to `0.05` (5%) when the\n  rule's `Economy` is unset.\n- For each **Item** or **EventToken** entry: reward amount = `amount * 2`\n  exactly — no burn (items are indivisible; burning progress-style event\n  tokens would be meaningless).\n\nExample: entry of 100 coins, default 5% burn → doubled = 200, burn =\n`floor(200 * 0.05) = 10`, `NetReward` = 190 coins.\n\nSettlement by outcome (backend `MatchHelpers.BuildInstantBattleDualOps`):\n\n- **Creator wins**: joiner (loser) has `Consume.Standard = Entry` (their entry\n  leaves their balance and joins the pool); creator (winner) has\n  `Grant.Standard = NetReward` (their own entry was already committed at\n  `createMatch`, so only the reward is granted now).\n- **Joiner wins**: creator (loser) gets an **empty** operation (their entry\n  was already spent at `createMatch`, nothing more to take); joiner (winner)\n  has both `Consume.Standard = Entry` (their entry is taken now, at battle\n  time) **and** `Grant.Standard = NetReward` in the same operation.\n- **Draw**: no dual-party op at all. The creator is refunded their `Entry`\n  via a single-party `Grant` (`Resources`, not `ResourcesDual`); the joiner\n  never paid anything, so there's nothing to refund on their side. The\n  creation fee is not refunded on a draw (it's sunk once played, per above).\n\nThis is why `InstantBattleResponse` carries **either** `Resources` (draw) **or**\n`ResourcesDual` (decisive) — never both — and why the SDK's cache-application\nlogic branches on which one is present (see `MatchService.instantBattle` in\nSKILL.md's Gotchas).\n\n---\n\n## Battle strategy resolution\n\nBoth `createMatch` (for the creator's strategy) and `instantBattle` (for\nwhichever side's profile is being built) resolve the strategy to use with the\nsame precedence (backend `Match.ResolveStrategyOrRandom`):\n\n1. The `battleStrategy` passed in that specific request, if non-empty.\n2. Otherwise the player's saved `PvPBattleStrategy` (from `saveStrategy`), if\n   non-empty.\n3. Otherwise a **freshly randomized** 3-step strategy (random\n   `AttackTarget`/`DefenseTarget` per step, generated server-side per battle\n   — not persisted).\n\nAny strategy longer than 10 steps is truncated to the first 10 wherever it's\naccepted (`createMatch`, `updateMatch`, `saveStrategy`).\n\n---\n\n## Request shape\n\nEvery method builds a `MatchRequest` (extends the SDK's `BaseRequest`)\ninternally — useful context for reading error messages, not something you\nconstruct by hand:\n\n```ts\ninterface MatchRequest extends BaseRequest {\n  MatchID?: string;\n  TargetUserID?: string;\n  Entry?: ResourceBundle;\n  BattleStrategy?: BattleStepConfig[];\n  CharacterID?: string;\n  RuleID?: string;\n  ClearTargetUser?: boolean; // UpdateMatch only; wins over TargetUserID\n  Page?: number;\n  PageSize?: number;\n  Statuses?: string[]; // GetMyMatches filter\n  OnlyPublic?: boolean; // GetAvailableMatches filter\n}\n```\n\n`createMatch` and `instantBattle` both set `RelatedEntityID` to a fresh\n`pvp_create_*`/`pvp_battle_*` UUID-suffixed string for backend idempotency/\ncorrelation — informational, not something you need to read or set yourself.\n"
+    }
+  ]
+}

package/registry/skills/multiplayer-realtime.json

@@ -0,0 +1,11 @@
+{
+  "name": "multiplayer-realtime",
+  "description": "Build realtime peer-to-peer multiplayer in a game on the iDosGames TypeScript SDK (@idosgames/core) via client.multiplayer (MultiplayerService): create/join/leave/close rooms, list public rooms, relay WebRTC SDP offer/answer + ICE candidates between room members, long-poll for signals/chat/presence envelopes, send server-relayed chat, and publish member ready/lobby state. This is a signaling and room-lifecycle relay for WebRTC — not a gameplay/economy module. Use this whenever the user is working in the iDosGames TS SDK or its game templates and wants realtime multiplayer rooms/lobbies, WebRTC signaling, peer-to-peer connection setup, a poll loop for realtime events, in-room chat, or ready-check/lobby-state UIs, or otherwise touches client.multiplayer, MultiplayerService, MultiplayerModels, RoomSnapshotResponse, RealtimeEnvelope, or EnvelopeType — even if they don't name the module explicitly.",
+  "content": "---\nname: multiplayer-realtime\ndescription: >-\n  Build realtime peer-to-peer multiplayer in a game on the iDosGames\n  TypeScript SDK (@idosgames/core) via client.multiplayer\n  (MultiplayerService): create/join/leave/close rooms, list public rooms,\n  relay WebRTC SDP offer/answer + ICE candidates between room members,\n  long-poll for signals/chat/presence envelopes, send server-relayed chat, and\n  publish member ready/lobby state. This is a signaling and room-lifecycle\n  relay for WebRTC — not a gameplay/economy module. Use this whenever the user\n  is working in the iDosGames TS SDK or its game templates and wants realtime\n  multiplayer rooms/lobbies, WebRTC signaling, peer-to-peer connection setup,\n  a poll loop for realtime events, in-room chat, or ready-check/lobby-state\n  UIs, or otherwise touches client.multiplayer, MultiplayerService,\n  MultiplayerModels, RoomSnapshotResponse, RealtimeEnvelope, or EnvelopeType —\n  even if they don't name the module explicitly.\n---\n\n# Multiplayer realtime signaling (iDosGames TS SDK)\n\nMultiplayer is a **realtime WebRTC signaling relay**, not a gameplay or\neconomy module. It gives you room lifecycle (create/join/leave/list/close) and\na message relay for two things peer-to-peer games need: SDP offer/answer + ICE\ncandidate exchange (so browsers/clients can establish a direct WebRTC\nconnection), and optional server-relayed chat/presence. The actual game state\nsync between players happens over the WebRTC connection you establish\nyourself — this module only gets players into the same room and helps them\nfind each other.\n\n**No currency/item coupling, no per-player cache mirror.** Unlike every other\nmodule in this SDK, no Multiplayer action ever returns a `ResourceOperation`\nor writes to `client.data.user.state` — there is nothing to mirror into a\nlocal player-state cache. Room state itself is ephemeral (Redis, TTL-based, no\nMongo document), so the SDK surface here is pure transport + event-emission:\ncall a method, get a response, emit an event, done. There is no\n`user:multiplayerUpdated` event and no `client.data.user.state.Multiplayer` —\ndon't look for either. The one piece of _config_ this module does expose —\n`MultiplayerDefinitions` (feature switch, topology/chat defaults, room-size\ncap, TTL, payload limits, ICE servers) — rides in on the title's public\nconfig bundle rather than a dedicated fetch call; see\n[Reading limits from config](#reading-limits-from-config).\n\nThis skill is for **using** the production `MultiplayerService`, not for\nporting or extending it, and not for implementing WebRTC itself — you still\nown the `RTCPeerConnection` on each client; this module only relays the\nsignaling payloads between them. Server rejections (room full, wrong join\ncode, not the owner, payload too large) are backend rules — surface them,\ndon't try to pre-validate every one of them client-side.\n\n## Mental model\n\n1. One player **creates a room** (picks topology/chat mode/visibility/max\n   players, optionally a join code); others **join** by room id (+ join code\n   if private). **A player can only be in one room at a time** — creating or\n   joining while already in a live room fails; leave first.\n2. Each member **polls** the room on a cursor (`LastSeq`) to receive a stream\n   of envelopes: other members' signals, chat, presence changes\n   (join/leave/host-migration), and room-closed notices. Polling is also the\n   heartbeat — it's what keeps your presence and the room's Redis TTL alive.\n3. To establish a direct connection, members exchange SDP offer/answer and ICE\n   candidates by calling **`sendSignal`** — the server just relays the\n   `payload` string to a specific `targetUserID`; it never inspects or\n   validates WebRTC semantics.\n4. Optional **`sendChat`** (only meaningful when the room's `ChatMode` is\n   `ServerRelay` — under `P2P` chat should go over your own DataChannel\n   instead) and **`setMemberState`** (ready flags + a free-form string map)\n   round out lobby UX.\n5. Someone **leaves**, or the owner/host **closes** the room; on host\n   departure the server may migrate to a `NewHostUserID` if members remain.\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any auth.* method\n\nconst mp = client.multiplayer; // the MultiplayerService\n```\n\nEvery method requires an authenticated session. Without one they return\n`{ ok: false, reason: \"unauthorized\" }` — they do not throw. There is one\n`client` per player; don't share it across sessions.\n\n## Methods\n\nAll methods return `Promise<OperationResult<T>>`: a discriminated union that is\neither `{ ok: true, data }` or `{ ok: false, reason, error }`. Always branch on\n`result.ok` before touching `result.data`. `reason` is one of `\"client\"` (bad\nlocal args — missing room id/name/target/kind), `\"unauthorized\"`,\n`\"throttled\"` (fired the same endpoint again inside the transport's throttle\nwindow), `\"connection\"` (transient, offer Retry), `\"validation\"`\n(response/schema drift), or `\"server\"` (the backend rejected it — `error`\ncarries a human-readable reason; see the verbatim strings below).\n\n| Method                                                  | Purpose                                                                                  | `data` on success      |\n| ------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------- |\n| `createRoom(roomName, options?)`                        | Create a room; caller becomes owner/host.                                                | `RoomSnapshotResponse` |\n| `joinRoom(roomID, joinCode?)`                           | Join an existing room.                                                                   | `RoomSnapshotResponse` |\n| `leaveRoom(roomID)`                                     | Leave a room (may trigger host migration or close it if empty).                          | `LeaveRoomResponse`    |\n| `listRooms(page?, pageSize?)`                           | Page through public rooms (default `page=0, pageSize=20`, server caps `pageSize` at 50). | `RoomsPageResponse`    |\n| `getRoom(roomID)`                                       | Fetch a fresh snapshot of one room.                                                      | `RoomSnapshotResponse` |\n| `closeRoom(roomID)`                                     | Owner/host-only: force-close a room.                                                     | `LeaveRoomResponse`    |\n| `poll(roomID, lastSeq)`                                 | Long-poll cursor: get every envelope with `Seq > lastSeq`.                               | `PollResponse`         |\n| `sendSignal(roomID, targetUserID, signalKind, payload)` | Relay an SDP offer/answer/ICE candidate to one member.                                   | `PublishResponse`      |\n| `sendChat(roomID, chatText)`                            | Server-relayed chat message (only when `ChatMode: ServerRelay`).                         | `PublishResponse`      |\n| `setMemberState(roomID, ready?, memberState?)`          | Publish this member's ready flag / free-form lobby state.                                | `PublishResponse`      |\n\n`createRoom`'s `options`: `{ topology?: MultiplayerTopology (\"Mesh\"|\"Host\"),\nchatMode?: MultiplayerChatMode (\"ServerRelay\"|\"P2P\"), maxPlayers?: number,\nvisibility?: RoomVisibility (\"Public\"|\"Private\"), joinCode?: string }`. Any\nfield you omit falls back to the title's configured defaults\n(`MultiplayerDefinitions.DefaultTopology`/`DefaultChatMode`), and an override\nis only honored if the title allows it\n(`AllowCreatorTopologyOverride`/`AllowCreatorChatOverride`) — otherwise the\ncall fails server-side with `\"Topology override is not allowed for this\ntitle.\"` / `\"Chat mode override is not allowed for this title.\"`.\n`maxPlayers` is clamped down to the title's `MaxPlayersPerRoom` hard cap; you\ncan only ask for _fewer_, never more.\n\n`closeRoom` succeeds for either the room's `OwnerUserID` **or** its current\n`HostUserID` (these can diverge after a host migration) — anyone else gets\n`\"Only the room owner or host can close the room.\"`.\n\nEvery method still emits its event on success even though nothing is cached —\nevents are your only hook here, there's no cache to read afterward.\n\n### Server error strings (verbatim)\n\nThese are exact `error` text from the backend (`RoomService.cs` /\n`SignalingService.cs`) — match on substrings if you need to branch, but the\nsafe default is just to display `result.error` as-is:\n\n- `\"Multiplayer is disabled for this title.\"` — title-wide kill switch is off.\n- `\"You are already in room {roomId}. Leave it first.\"` — one-active-room rule,\n  on both `createRoom` and `joinRoom`.\n- `\"RoomID is required.\"` / `\"TargetUserID is required.\"` / `\"SignalKind is\nrequired.\"` — same validation the SDK does client-side; you'll only see\n  these from a raw/bypassed call.\n- `\"Invalid or missing join code.\"` — private room join code mismatch.\n- `\"Room not found.\"` — unknown room id, or a **private** room you aren't a\n  member of (privacy is enforced by returning the same not-found error, not a\n  distinct \"forbidden\").\n- `\"Room is closed.\"` / `\"Room is full.\"` — join-time rejections.\n- `\"Only the room owner or host can close the room.\"`\n- `\"Room no longer exists.\"` / `\"You are not a member of this room.\"` — from\n  `poll`, `sendSignal`, `sendChat`, `setMemberState` once you've dropped out of\n  the member hash (TTL expiry, or someone else removed you).\n- `\"Target user is not in this room.\"` — `sendSignal` to a non-member.\n- `\"Cannot signal yourself.\"`\n- `` `Signal payload exceeds {N} bytes.` `` — `MaxSignalPayloadBytes` (default 16384) exceeded.\n- `` `Chat text exceeds {N} characters.` `` — `MaxChatTextLength` (default 500)\n  exceeded.\n- `\"Chat is peer-to-peer in this room; send it over the DataChannel.\"` —\n  called `sendChat` while `ChatMode` is `P2P`.\n- `\"Corrupted member record.\"` — internal deserialization failure on\n  `setMemberState`; treat as transient/report.\n\n## Reading limits from config\n\nThere's no `getMultiplayerDefinitions()` call — `MultiplayerDefinitions`\ntravels as part of the title's public config bundle, not a per-module\ndefinitions fetch. It's populated by `client.title.getTitlePublicConfiguration()`\n(or already present after login, since the bootstrap `ClientState` includes\nthe title config):\n\n```ts\nimport type { MultiplayerDefinitions } from \"@idosgames/core\";\n\nawait client.title.getTitlePublicConfiguration(); // if not already loaded\nconst cfg = client.data.config.titlePublicConfiguration?.Multiplayer as\n  MultiplayerDefinitions | undefined;\n\ncfg?.MaxPlayersPerRoom; // hard cap enforced server-side\ncfg?.MaxChatTextLength;\ncfg?.MaxSignalPayloadBytes;\ncfg?.HeartbeatIntervalMs; // recommended poll cadence, not enforced\ncfg?.MemberTimeoutMs; // client-side presumed-offline threshold\n```\n\nRead it for building config-driven UI (create-room forms that pre-fill/clamp\n`maxPlayers`, a chat box that disables itself when `ChatMode` will be `P2P`,\netc.) — the server enforces the real limits regardless of what you show.\n\n## Events\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn. There is no\ncoarse `user:*Updated`/`user:anyUpdated` companion for any of these — they\ndon't touch the shared cache.\n\n- `multiplayer:roomCreated` → `RoomSnapshotResponse`\n- `multiplayer:roomJoined` → `RoomSnapshotResponse`\n- `multiplayer:roomLeft` → `LeaveRoomResponse`\n- `multiplayer:roomsListed` → `RoomsPageResponse`\n- `multiplayer:roomLoaded` → `RoomSnapshotResponse`\n- `multiplayer:roomClosed` → `LeaveRoomResponse`\n- `multiplayer:polled` → `PollResponse`\n- `multiplayer:signalSent` → `PublishResponse`\n- `multiplayer:chatSent` → `PublishResponse`\n- `multiplayer:memberStateSet` → `PublishResponse`\n\n```ts\nconst off = client.on(\"multiplayer:roomClosed\", (r) => {\n  if (r.Closed) navigateToLobbyList();\n});\n// later: off();\n```\n\nFor the full shape of `RoomSnapshotResponse`, `RealtimeEnvelope`,\n`RoomMemberView`, and `MultiplayerDefinitions`, see\n[references/data-model.md](references/data-model.md).\n\n## Recipes\n\n### Create or join a room\n\n```ts\nconst created = await client.multiplayer.createRoom(\"Match 42\", {\n  topology: \"Mesh\",\n  chatMode: \"ServerRelay\",\n  maxPlayers: 4,\n  visibility: \"Private\",\n  joinCode: \"AB12\",\n});\nif (!created.ok) return showError(created.error);\nconst { RoomID, Seq, IceServers, Members } = created.data;\n\n// another player:\nconst joined = await client.multiplayer.joinRoom(RoomID, \"AB12\");\nif (!joined.ok) return showError(joined.error); // e.g. wrong code, room full\n```\n\n`IceServers` on the snapshot is the STUN/TURN config for your `RTCPeerConnection`\n— pass it straight through (if the title has none configured, the backend\nfalls back to public Google STUN servers, so this array is never empty).\n`Seq` is your starting poll cursor. Remember the one-active-room rule: a\nsecond `createRoom`/`joinRoom` call while already in a room fails with\n`\"You are already in room {roomId}. Leave it first.\"` — call `leaveRoom` (or\ncheck your own app state) before switching rooms.\n\n### The polling loop (signals, chat, presence)\n\nPoll is a cursor-based long-poll: pass the last `Seq` you've seen, get back\neverything newer, and each response's `MaxSeq` becomes your next cursor. Each\npoll call also renews your presence heartbeat and the room's TTL server-side\n— an idle client that stops polling will eventually look disconnected to\nothers and the room itself can expire.\n\n```ts\nlet lastSeq = created.data.Seq ?? 0;\nlet polling = true;\n\nasync function pollLoop(roomID: string) {\n  while (polling) {\n    const res = await client.multiplayer.poll(roomID, lastSeq);\n    if (!res.ok) {\n      if (res.reason === \"connection\") continue; // transient, retry\n      break; // unauthorized/server error (\"Room no longer exists.\", etc) — stop and surface it\n    }\n    for (const env of res.data.Envelopes ?? []) {\n      switch (env.Type) {\n        case \"Signal\":\n          // env.Kind: \"offer\" | \"answer\" | \"candidate\"; env.FromUserID, env.Payload\n          handleSignal(env.FromUserID, env.Kind, env.Payload);\n          break;\n        case \"Chat\":\n          appendChatMessage(env.FromUserID, env.Payload);\n          break;\n        case \"PlayerJoined\":\n        case \"PlayerLeft\":\n        case \"MemberState\":\n          refreshRoomMembers(roomID);\n          break;\n        case \"HostChanged\":\n          break; // env.Payload / a follow-up getRoom() carries new host\n        case \"RoomClosed\":\n          polling = false;\n          break;\n      }\n    }\n    lastSeq = res.data.MaxSeq ?? lastSeq;\n  }\n}\n```\n\nThere's no push/websocket transport here — polling cadence is your call. The\ntitle's `MultiplayerDefinitions.HeartbeatIntervalMs` (default 1000ms) is a\n_recommended_ interval only, not enforced — poll too fast and you risk\n`reason: \"throttled\"` at the transport layer; too slow and signaling feels\nlaggy, and other members' `LastSeenMs` will look stale to you. Use the\nrecommended interval as your default; back off on `\"connection\"` errors\nrather than hot-looping.\n\n### Exchange a WebRTC offer/answer\n\n```ts\n// caller side, after creating an RTCPeerConnection and an offer:\nconst offer = await pc.createOffer();\nawait pc.setLocalDescription(offer);\nawait client.multiplayer.sendSignal(\n  roomID,\n  targetUserID,\n  \"offer\",\n  JSON.stringify(offer),\n);\n\n// callee side, from the poll loop's \"Signal\"/\"offer\" case:\nconst offer = JSON.parse(env.Payload);\nawait pc.setRemoteDescription(offer);\nconst answer = await pc.createAnswer();\nawait pc.setLocalDescription(answer);\nawait client.multiplayer.sendSignal(\n  roomID,\n  env.FromUserID,\n  \"answer\",\n  JSON.stringify(answer),\n);\n\n// both sides, as ICE candidates trickle in:\npc.onicecandidate = (e) => {\n  if (e.candidate) {\n    client.multiplayer.sendSignal(\n      roomID,\n      targetUserID,\n      \"candidate\",\n      JSON.stringify(e.candidate),\n    );\n  }\n};\n```\n\n`signalKind` is a free-form string (`\"offer\"`/`\"answer\"`/`\"candidate\"` by\nconvention) and `payload` is an opaque string — the server relays both without\ninspecting them, so encoding is entirely up to you (JSON-stringify is the\nobvious choice). Keep the serialized payload under the title's\n`MaxSignalPayloadBytes` (default 16384) — an oversized payload is rejected\nwith `` `Signal payload exceeds {N} bytes.` `` before it's ever relayed, and\nyou can't signal yourself (`\"Cannot signal yourself.\"`) or a user who isn't\ncurrently a room member (`\"Target user is not in this room.\"`).\n\n### Lobby ready-check and leaving\n\n```ts\nawait client.multiplayer.setMemberState(roomID, true, { loadout: \"red\" });\n// other members see this via a \"MemberState\" envelope on their next poll,\n// then re-fetch with getRoom(roomID) to read updated Members[].Ready/State.\n\nconst left = await client.multiplayer.leaveRoom(roomID);\nif (left.ok && left.data.Closed) {\n  // room was empty/owner left with no migration target — it's gone\n} else if (left.ok && left.data.NewHostUserID) {\n  // host migrated; that member is now authoritative for Host topology\n}\n```\n\n## Gotchas\n\n- **Nothing here touches `client.data.user.state`.** Don't look for a cached\n  room state or resource balances changing — read everything from method\n  responses and poll envelopes, and keep your own local room/member state in\n  your app layer. The one thing that _is_ cached is the title-wide\n  `MultiplayerDefinitions` config, and only after you fetch the title config\n  (see [Reading limits from config](#reading-limits-from-config)).\n- **One room per player, enforced server-side.** `createRoom` and `joinRoom`\n  both reject with `\"You are already in room {roomId}. Leave it first.\"` if\n  you're already a live member elsewhere — there's no implicit \"leave old,\n  join new.\"\n- **Room state is ephemeral.** No persistent document backs a room — it's\n  Redis, TTL-based (`RoomTtlSeconds`, default 3600s, renewed on every\n  interaction including `poll`). A room can disappear if nobody interacts\n  with it; don't assume a `RoomID` is valid indefinitely.\n- **`sendChat` only works under `ChatMode: ServerRelay`.** Under `P2P` chat\n  mode, send chat over your own WebRTC DataChannel instead — calling\n  `sendChat` in `P2P` mode fails with `\"Chat is peer-to-peer in this room;\nsend it over the DataChannel.\"` (check the room snapshot's `ChatMode`\n  before wiring a chat send button to it).\n- **`closeRoom` works for the owner or the current host, not just the\n  original creator.** After a host migration the new host can also close the\n  room; anyone else gets `\"Only the room owner or host can close the room.\"`.\n  Regular non-host, non-owner members only have `leaveRoom` (which itself may\n  close the room if it empties out).\n- **Private rooms 404 instead of 403.** `getRoom`/`poll`/etc. on a private\n  room you're not a member of returns the same `\"Room not found.\"` as a\n  genuinely unknown id — the backend doesn't leak room existence to\n  non-members.\n- **No server-side member timeout/eviction.** `RoomMemberView.LastSeenMs` is a\n  last-heartbeat timestamp for clients to compare against\n  `MultiplayerDefinitions.MemberTimeoutMs` themselves (e.g. to gray out a\n  presumed-disconnected member) — the server does not auto-evict stale\n  members; your poll loop or UI must apply that timeout logic.\n- **Poll cadence is uncapped by the SDK — you own the rate.** There's no\n  built-in backoff or interval; hitting the same endpoint faster than the\n  transport's throttle window returns `reason: \"throttled\"` rather than\n  duplicating work. `HeartbeatIntervalMs` is the title's _recommended_\n  interval, not an enforced one. Design your loop's interval deliberately\n  rather than polling in a tight `while(true)`.\n- **`Payload`/`signalKind` are opaque strings.** The server does not validate\n  WebRTC SDP/ICE structure — malformed payloads only fail on the _receiving_\n  client when it tries to parse/apply them, not at the relay. It does,\n  however, enforce a byte-size ceiling (`MaxSignalPayloadBytes`) before\n  relaying at all.\n- **Guard against double-submit** on room actions (create/join/close): each\n  call is a distinct request, so two separate calls are two real operations\n  server-side (e.g. two `createRoom` calls can both succeed as two different\n  rooms if the first response is slow). Disable the control while a call is\n  in flight.\n\n## Full reference\n\n[references/data-model.md](references/data-model.md) — full shape of\n`RoomSnapshotResponse`, `RoomMemberView`, `RealtimeEnvelope`/`EnvelopeType`,\n`MultiplayerDefinitions`, and the request/action surface, plus the room\nlifecycle state machine (Open → Closed, host migration, TTL expiry). Read it\nwhen building richer room/lobby UI or wiring up the poll loop's envelope\nhandling in detail.\n",
+  "references": [
+    {
+      "path": "data-model.md",
+      "content": "# Multiplayer data model — reference\n\nFull shape of the config (`MultiplayerDefinitions`), the room/member view\nmodels, the realtime envelope union, and the request/action surface. All of\nthese are **strictly typed in the SDK** and exported from `@idosgames/core`.\nThe zod schemas keep `.passthrough()`, so a field the backend adds later still\nround-trips as `unknown` extra data rather than being stripped. Field names\nare PascalCase (straight from the backend JSON).\n\nThere is no player-state shape to document here — Multiplayer has none. Every\nmodel below is either title-wide config or an ephemeral, per-room view.\n\n## Contents\n\n- [Config: MultiplayerDefinitions](#config-multiplayerdefinitions) — what rides in on the title's public config\n- [Room lifecycle state machine](#room-lifecycle-state-machine)\n- [RoomSnapshotResponse](#roomsnapshotresponse)\n- [RoomMemberView](#roommemberview)\n- [RoomListItem](#roomlistitem--roomspageresponse)\n- [RealtimeEnvelope + EnvelopeType](#realtimeenvelope--envelopetype)\n- [LeaveRoomResponse / PublishResponse / PollResponse](#other-responses)\n- [Request + actions](#request--actions)\n\n---\n\n## Config: MultiplayerDefinitions\n\nBackend: `MultiplayerDefinitions.cs`, stored at\n`TitlePublicConfigurationModel.Multiplayer`. Public-only data — no secrets.\nThere is no dedicated `getMultiplayerDefinitions()` fetch; this arrives with\nthe full title config (`client.title.getTitlePublicConfiguration()`, or\nalready present after the login bootstrap). See\n[Reading limits from config](../SKILL.md#reading-limits-from-config) in the\nmain skill.\n\n```ts\ninterface MultiplayerDefinitions {\n  SystemState?: { Enabled?: boolean }; // title-wide feature switch\n  DefaultTopology?: MultiplayerTopology; // \"Mesh\" | \"Host\"; default \"Mesh\"\n  AllowCreatorTopologyOverride?: boolean; // default true\n  DefaultChatMode?: MultiplayerChatMode; // \"ServerRelay\" | \"P2P\"; default \"ServerRelay\"\n  AllowCreatorChatOverride?: boolean; // default true\n  MaxPlayersPerRoom?: number; // hard cap; default 8\n  RoomTtlSeconds?: number; // Redis key TTL, renewed on every interaction; default 3600\n  HeartbeatIntervalMs?: number; // recommended client poll interval; default 1000 — NOT enforced\n  MemberTimeoutMs?: number; // client-side \"presumed offline\" threshold; default 15000 — no server auto-eviction\n  MaxSignalPayloadBytes?: number; // default 16384\n  MaxChatTextLength?: number; // characters; default 500\n  RoomLogCap?: number; // how many broadcast envelopes the room-log tail keeps; default 500\n  IceServers?: IceServer[]; // empty/absent -> server falls back to public Google STUN\n}\n\ninterface IceServer {\n  Urls?: string; // e.g. \"stun:stun.l.google.com:19302\" or \"turn:turn.example.com:3478\"\n  Username?: string; // TURN only\n  Credential?: string; // TURN only\n}\n```\n\n`MultiplayerTopology`: `\"Mesh\"` (every player connects to every other —\nsmall rooms) | `\"Host\"` (star topology, everyone connects only to the host).\n\n`MultiplayerChatMode`: `\"ServerRelay\"` (chat broadcast through the room-log,\nworks in lobby and as a fallback) | `\"P2P\"` (server does not process chat at\nall — send it over your own DataChannel).\n\n`RoomVisibility`: `\"Public\"` (appears in `listRooms`) | `\"Private\"` (not\nlisted; join by `RoomID` + join code only).\n\n---\n\n## Room lifecycle state machine\n\nA room's `Status` (surfaced as `RoomSnapshotResponse.Status`) is a plain\nstring, driven by these transitions (backend: `RoomService.cs` +\n`RedisService.Realtime.cs`):\n\n- **created** → `\"Open\"`. `createRoom` sets it; the caller becomes both\n  `OwnerUserID` and `HostUserID`.\n- **join** — allowed only while `Open` and under `MaxPlayers`; rejected with\n  `\"Room is closed.\"` / `\"Room is full.\"` otherwise. A private room additionally\n  requires the join code to match (SHA-256 hash comparison server-side —\n  the raw code is never stored).\n- **leave** — if the leaving member was the last one, the room is deleted\n  outright (`Closed: true` in the `LeaveRoomResponse`, no `RoomClosed`\n  envelope is published — there's nobody left to receive it). If members\n  remain and the leaver was the host, a new host is picked from the\n  remaining members (`NewHostUserID`) and a `HostChanged` envelope is\n  broadcast; the room stays `Open`.\n- **close** (`closeRoom`, owner or current host only) → a `RoomClosed`\n  envelope is broadcast _before_ the room is marked `Closed`, so in-flight\n  pollers still receive the notice; the room's keys then live out their\n  remaining TTL rather than being deleted immediately (so late polls still\n  resolve cleanly instead of hitting \"gone\").\n- **idle expiry** — every interaction (`poll`, `sendSignal`, `sendChat`,\n  `setMemberState`, join/leave) renews the room's Redis TTL\n  (`RoomTtlSeconds`). Stop interacting and the room silently disappears; a\n  subsequent `poll` on it fails with `\"Room no longer exists.\"` (internally\n  the `\"gone\"` code) rather than describing expiry explicitly.\n\nThere is no separate \"starting\"/\"in-progress\" server-tracked status — once\npeers have exchanged signals and opened their DataChannel, that phase is\nentirely off the server's radar. If your game needs a \"match started\" state,\nmodel it yourself via `setMemberState`'s free-form `MemberState` map or your\nown signaling payloads.\n\n---\n\n## RoomSnapshotResponse\n\nReturned by `createRoom`, `joinRoom`, and `getRoom`.\n\n```ts\ninterface RoomSnapshotResponse {\n  RoomID?: string;\n  Name?: string;\n  HostUserID?: string; // current host; may differ from OwnerUserID after migration\n  OwnerUserID?: string; // original creator; fixed for the room's lifetime\n  Topology?: MultiplayerTopology;\n  ChatMode?: MultiplayerChatMode;\n  Visibility?: RoomVisibility;\n  Status?: string; // \"Open\" | \"Closed\"\n  MaxPlayers?: number;\n  Members?: RoomMemberView[]; // ordered by JoinedAt ascending\n  IceServers?: IceServer[]; // resolved (title config, or Google STUN fallback)\n  Seq?: number; // starting poll cursor for this room\n}\n```\n\n`JoinCode` is deliberately never returned in any response — only its SHA-256\nhash is stored server-side, checked against what `joinRoom` submits.\n\n---\n\n## RoomMemberView\n\nOne room member: static public profile fields plus mutable lobby state.\n\n```ts\ninterface RoomMemberView {\n  UserID?: string;\n  Username?: string;\n  AvatarUrl?: string;\n  Level?: number; // snapshotted from the player's public profile at join time\n  Power?: number; // snapshotted from the player's public profile at join time\n  Ready?: boolean; // mutated via setMemberState\n  State?: Record<string, string>; // free-form lobby metadata, mutated via setMemberState\n  JoinedAt?: number; // unix ms\n  IsHost?: boolean; // computed on read: UserID === room's current HostUserID\n  LastSeenMs?: number; // unix ms of last heartbeat (poll); compare against MemberTimeoutMs yourself\n}\n```\n\n`Level`/`Power` are a snapshot taken from the player's public profile\n(`UserPublicDataModel`) at the moment they joined — they do **not** live-update\nif the player's Character Power changes mid-room. Re-`joinRoom` (or a fresh\n`getRoom`) is the only way to refresh them; there's no push for profile\nchanges into an existing member record.\n\n`IsHost` and `LastSeenMs` are computed server-side on every read (from\n`hostUserId` in room meta and the presence Sorted Set respectively) — they\nare not stored on the member record itself.\n\n---\n\n## RoomListItem + RoomsPageResponse\n\nReturned by `listRooms`. A deliberately thin projection — no `Members`, no\njoin code, no `Seq` — for cheap listing pages.\n\n```ts\ninterface RoomListItem {\n  RoomID?: string;\n  Name?: string;\n  HostUserID?: string;\n  Topology?: MultiplayerTopology;\n  ChatMode?: MultiplayerChatMode;\n  MaxPlayers?: number;\n  MemberCount?: number;\n  CreatedAt?: number; // unix ms\n}\n\ninterface RoomsPageResponse {\n  Rooms?: RoomListItem[];\n  Page?: number;\n  PageSize?: number; // server-echoed; clamped to <= 50 regardless of what you requested\n  HasMore?: boolean;\n}\n```\n\nOnly `Public`-visibility, currently-`Open` rooms ever appear here — private\nrooms and closed rooms are excluded at the index level, not filtered\nclient-side.\n\n---\n\n## RealtimeEnvelope + EnvelopeType\n\nThe unified delivery item returned by `poll`. `Seq` is a per-room, strictly\nincreasing counter shared by both the broadcast log and every member's\ndirected inbox — that's what makes a single `lastSeq` cursor sufficient to\ndrain all of it.\n\n```ts\ntype EnvelopeType =\n  | \"Signal\" // directed: SDP offer/answer or ICE candidate\n  | \"Chat\" // broadcast: ChatMode=ServerRelay message\n  | \"PlayerJoined\" // broadcast: someone joined\n  | \"PlayerLeft\" // broadcast: someone left\n  | \"HostChanged\" // broadcast: host migrated\n  | \"RoomClosed\" // broadcast: room closed by owner/host\n  | \"MemberState\"; // broadcast: someone's Ready/State changed\n\ninterface RealtimeEnvelope {\n  Seq?: number;\n  Type?: EnvelopeType;\n  FromUserID?: string;\n  ToUserID?: string; // present only on directed \"Signal\" envelopes\n  Kind?: string; // \"Signal\" only: \"offer\" | \"answer\" | \"candidate\" (free-form, by convention)\n  Payload?: string; // opaque string; meaning depends on Type (see below)\n  Ts?: number; // unix ms, server-assigned\n}\n```\n\n`Payload` by `Type`:\n\n- `\"Signal\"` → whatever string you passed to `sendSignal` (typically\n  JSON-stringified `RTCSessionDescriptionInit` or `RTCIceCandidateInit`).\n- `\"Chat\"` → the raw chat text from `sendChat`.\n- `\"PlayerJoined\"` / `\"PlayerLeft\"` → the affected user's `UserID` (also\n  duplicated in `FromUserID`).\n- `\"HostChanged\"` → the new host's `UserID`.\n- `\"RoomClosed\"` → the `RoomID` that was closed.\n- `\"MemberState\"` → a JSON string of `{ Ready, State }` — the changed\n  member's new ready flag and state map (parse it, or just treat the\n  envelope as a signal to re-`getRoom`).\n\nEnvelopes are delivered **at most once** per `poll` call (they're consumed by\nbeing read above `lastSeq`, not re-sent), but nothing deduplicates _across_\noverlapping poll calls if you mismanage your cursor — always advance\n`lastSeq` to the response's `MaxSeq`, never roll it back.\n\n---\n\n## Other responses\n\n```ts\ninterface LeaveRoomResponse {\n  Closed?: boolean; // true if the room was closed/removed as a result\n  NewHostUserID?: string; // set only when the host left and members remain\n}\n\ninterface PollResponse {\n  Envelopes?: RealtimeEnvelope[]; // ordered by Seq ascending\n  MaxSeq?: number; // max Seq among returned envelopes, or the sent LastSeq if none — always your next cursor\n}\n\ninterface PublishResponse {\n  Seq?: number; // the seq assigned to the envelope you just published, for tracing/debugging\n}\n```\n\n---\n\n## Request + actions\n\nEvery call funnels through one `MultiplayerRequest` shape and a 10-value\n`MultiplayerAction` enum (`CreateRoom`, `JoinRoom`, `LeaveRoom`, `ListRooms`,\n`GetRoom`, `CloseRoom`, `Poll`, `SendSignal`, `SendChat`, `SetMemberState`) —\nyou never construct either yourself; `MultiplayerService` builds the request\nand picks the action per method. Listed here only so error messages and field\nnames in server logs/network tabs are recognizable:\n\n```ts\ninterface MultiplayerRequest {\n  RoomID?: string;\n  RoomName?: string; // CreateRoom\n  Topology?: MultiplayerTopology; // CreateRoom\n  ChatMode?: MultiplayerChatMode; // CreateRoom\n  MaxPlayers?: number; // CreateRoom\n  Visibility?: RoomVisibility; // CreateRoom\n  JoinCode?: string; // CreateRoom (sets it) / JoinRoom (submits it)\n  TargetUserID?: string; // SendSignal\n  SignalKind?: string; // SendSignal: \"offer\" | \"answer\" | \"candidate\"\n  Payload?: string; // SendSignal\n  ChatText?: string; // SendChat\n  Ready?: boolean; // SetMemberState\n  MemberState?: Record<string, string>; // SetMemberState\n  LastSeq?: number; // Poll cursor\n  Page?: number; // ListRooms\n  PageSize?: number; // ListRooms\n}\n```\n\nPer-action rate limiting (server-side, not SDK-visible as distinct reasons —\nall surface as `reason: \"throttled\"` from the transport, or a plain\n`\"server\"` failure if you exceed the backend's own request lock): `Poll`,\n`SendSignal`, `SendChat`, and `SetMemberState` are treated as high-frequency\nrealtime traffic with a short per-user lock; `ListRooms`/`GetRoom` are\nread-only with a medium lock; `CreateRoom`/`JoinRoom`/`LeaveRoom`/`CloseRoom`\n(room lifecycle mutations) use the strictest lock. You don't need the exact\nnumbers to use the SDK correctly — just don't hot-loop any of these calls,\nand expect lifecycle actions (create/join/leave/close) to tolerate less\nback-to-back traffic than the realtime loop (poll/signal/chat/state).\n"
+    }
+  ]
+}

package/registry/skills/premium-system.json

@@ -0,0 +1,11 @@
+{
+  "name": "premium-system",
+  "description": "Build a premium / subscription / VIP-tier system in a game on the iDosGames TypeScript SDK (@idosgames/core) via client.premium (PremiumService): load premium tier definitions, load the player's active subscriptions, activate a free trial, purchase a premium tier with virtual/item cost, or complete a real-money IAP subscription purchase (App Store / Google Play receipt validation). This is the player's subscription/IAP tier that other modules (Store cost discounts via ResourceConsume.PremiumDiscounts, reward/lootbox grant multipliers via ResourceGrant.PremiumTiers, segment gates via SegmentGate.MinPremiumTier) read to unlock perks. Use whenever the user wants a subscription/VIP/battle-pass-tier paywall, IAP receipt validation, trial flows, or touches client.premium, PremiumService, PremiumDefinition, MaxActiveTier, or premium discounts/multipliers — even if they don't name the module explicitly.",
+  "content": "---\nname: premium-system\ndescription: >-\n  Build a premium / subscription / VIP-tier system in a game on the iDosGames\n  TypeScript SDK (@idosgames/core) via client.premium (PremiumService): load\n  premium tier definitions, load the player's active subscriptions, activate a\n  free trial, purchase a premium tier with virtual/item cost, or complete a\n  real-money IAP subscription purchase (App Store / Google Play receipt\n  validation). This is the player's subscription/IAP tier that other modules\n  (Store cost discounts via ResourceConsume.PremiumDiscounts, reward/lootbox\n  grant multipliers via ResourceGrant.PremiumTiers, segment gates via\n  SegmentGate.MinPremiumTier) read to unlock perks. Use whenever the user wants\n  a subscription/VIP/battle-pass-tier paywall, IAP receipt validation, trial\n  flows, or touches client.premium, PremiumService, PremiumDefinition,\n  MaxActiveTier, or premium discounts/multipliers — even if they don't name the\n  module explicitly.\n---\n\n# Premium system (iDosGames TS SDK)\n\nThe Premium module is the title's **subscription / IAP tier** system: players\nactivate a trial or purchase a premium tier (with virtual currency, or —\nintended — real money via App Store / Google Play), and other modules read the\nplayer's active tier to unlock discounts, bonus multipliers, and gated\ncontent. Everything is **server-authoritative**: the client asks the backend\nto activate/purchase, the backend validates the transaction (cost, trial\neligibility, and — for real money — the receipt with Apple/Google), and the\nSDK mirrors the confirmed result into a local cache your UI reads. You never\nmutate premium state yourself — you call a method, check the result, and\nrender from the cache.\n\nThis skill is for **using** the production `PremiumService`, not for porting\nor extending it. If a call is rejected, that's the backend enforcing a rule\n(already trialed, receipt invalid, insufficient funds) — surface the error,\ndon't try to reproduce the check client-side.\n\n## The two data shapes\n\n1. **Definitions** (config, same for every player) — the title's catalog of\n   premium tiers: `Tier` number, `DurationDays`, `TrialDurationDays`, price\n   options (virtual/item cost per option), App/Google product IDs, and\n   free-form `Benefits` (display-only). Fetched with `getDefinitions()`.\n2. **User premium state** (state, per player) — this player's subscriptions\n   (`Subscriptions`, keyed by `PremiumID`, including expired ones — they're\n   never deleted), which trials they've already used (`ActivatedTrialIDs`,\n   permanent), and their current best tier (`MaxActiveTier`). Fetched with\n   `getUserState()`.\n\nA premium tier is identified by a string `PremiumID`. `Tier` is a plain number\n(higher = better) — it's what other modules compare against\n(`SegmentGate.MinPremiumTier`, `PremiumTierBundle.MinPremiumTier`) to decide\nwhether a perk applies; some gates instead pin an exact `RequiredPremiumID`,\nin which case the tier number is ignored. `MaxActiveTier` on the user state is\nthe number to read when you just need \"what's the player's current tier\"\nwithout walking `Subscriptions` yourself — the backend recalculates it from\nscratch (max `Tier` among non-expired subscriptions) on every read and write,\nso it self-heals even if a subscription lapsed since the last call.\n\nFor the full field-by-field shape, the trial-eligibility rules, tier\nresolution, and the purchase/renewal math, read\n[references/data-model.md](references/data-model.md). You do **not** need it\nto call the methods — only to drive richer UI (renewal countdowns, trial\neligibility, cost previews) off the config.\n\n## Setup\n\n```ts\nimport { createIDosGamesClient } from \"@idosgames/core\";\n\nconst client = createIDosGamesClient({ titleID: \"your-title-id\" });\nawait client.auth.loginWithDeviceID(); // or any auth.* method\n\nconst premium = client.premium; // the PremiumService\n```\n\nEvery premium method requires an authenticated session. Without one they\nreturn `{ ok: false, reason: \"unauthorized\" }` — they do not throw. There is\none `client` per player; don't share it across sessions.\n\n## Methods\n\nAll methods return `Promise<OperationResult<T>>`: a discriminated union that is\neither `{ ok: true, data }` or `{ ok: false, reason, error }`. Always branch on\n`result.ok` before touching `result.data`. `reason` is one of `\"client\"` (bad\nlocal args, e.g. missing `TransactionID`/`ProductID`/`ReceiptData`),\n`\"unauthorized\"`, `\"throttled\"` (fired the same endpoint again inside the\nthrottle window, default 600 ms), `\"connection\"` (transient, offer Retry),\n`\"validation\"` (response/schema drift), or `\"server\"` (backend rejected it —\n`error` carries the human-readable reason, e.g. `\"Trial already used.\"`,\n`\"Subscription already active.\"`, `\"PriceOption not found\"`, insufficient\nfunds).\n\n| Method                                                                                                                           | Purpose                                                                                             | `data` on success                        |\n| -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------- |\n| `getDefinitions()`                                                                                                               | Load the title's premium tier catalog (config).                                                     | `PremiumDefinitionsResponse` (`Premium`) |\n| `getUserState()`                                                                                                                 | Load this player's subscriptions/trials/tier (state).                                               | `PremiumStateResponse` (`Premium`)       |\n| `activateTrial(premiumID, transactionID)`                                                                                        | Start a free trial of a tier (one-time per `PremiumID`, forever).                                   | `PremiumPurchaseResponse`                |\n| `purchaseItemOrCurrency(premiumID, transactionID, selectedOptionID?, count?)`                                                    | Buy/renew a tier with a virtual/item price option (default option `\"Default\"`, count 1).            | `PremiumPurchaseResponse`                |\n| `purchaseRealMoney(premiumID, transactionID, store, productID, receiptData, purchaseToken?, packageName?, appStoreEnvironment?)` | Send a real-money IAP receipt for validation. **Not implemented on the backend yet** — see Gotchas. | `PremiumPurchaseResponse`                |\n\n`store` is `\"Apple\"` or `\"Google\"` (`StoreType`). `purchaseToken` is\nGoogle-specific (Play Billing purchase token); `packageName` and\n`appStoreEnvironment` are optional extra context some validators need. Every\npurchase/trial call requires a caller-supplied `transactionID` — treat it as\nthis attempt's client-side transaction id (distinct per attempt; the SDK also\nderives an internal idempotency key from it, and the backend independently\ntreats a repeated `transactionID` on an existing subscription as a no-charge\nreplay rather than a new purchase).\n\nOn success, each method also **mirrors the confirmed change into the cache and\nemits an event** — you don't apply anything by hand. The purchase methods also\napply the returned `Resources` (`ResourceOperation`, shared across the SDK —\n`packages/core/src/models/_shared/ResourceModels.ts`) to cached balances when\npresent; `activateTrial` always returns an empty `Resources` since a trial\ndoesn't move currency. Read updated tier/balances straight from the cache.\n\n## Reading state and reacting to changes\n\n```ts\n// Config (cached after getDefinitions()):\nimport type { PremiumDefinitions } from \"@idosgames/core\";\nconst defs = client.data.config.getSection<PremiumDefinitions>(\"Premium\");\nconst tier = defs?.Definitions?.[\"vip_gold\"];\ntier?.Tier; // numeric tier level\ntier?.PriceOptions; // { optionID: { RequiredResources: ResourceConsume } }\ntier?.Benefits; // free-form { key: stringified value } for display\n\n// User state (only present after getUserState() or a purchase/trial):\nconst p = client.data.user.state?.Premium;\np?.MaxActiveTier; // current best tier (number), self-healing on every fetch\np?.Subscriptions?.[\"vip_gold\"]?.ExpirationDate; // check this, not just key existence\np?.ActivatedTrialIDs; // trials already used, ever — don't offer them again\n```\n\n`applyPremium` fully **replaces** the cached `Premium` object on every write\n(`packages/core/src/cache/UserData.ts:672`) — it's not a deep merge, so a\n`getUserState()`/purchase/trial response always reflects the complete,\nauthoritative state.\n\nSubscribe with `client.on(...)`; each returns an unsubscribe fn:\n\n- `premium:definitionsLoaded` → `PremiumDefinitionsResponse`\n- `premium:stateLoaded` → `PremiumStateResponse`\n- `premium:trialActivated` → `PremiumPurchaseResponse`\n- `premium:purchaseCompleted` → `PremiumPurchaseResponse`\n- `premium:realMoneyPurchaseCompleted` → `PremiumPurchaseResponse`\n\nThe coarse `user:premiumUpdated` (and `user:anyUpdated`) also fire on any\npremium cache write — handy for a \"re-render everything\" hook, and useful for\nany other screen that displays a tier-gated perk.\n\n```ts\nconst off = client.on(\"premium:purchaseCompleted\", (r) => {\n  console.log(`Now on ${r.Subscription?.PremiumID}, tier state refreshed`);\n});\n// later: off();\n```\n\n## Recipes\n\n### Show tiers and the player's current status\n\n```ts\nawait client.premium.getDefinitions();\nawait client.premium.getUserState();\n\nconst defs = client.data.config.getSection<PremiumDefinitions>(\"Premium\");\nconst state = client.data.user.state?.Premium;\n\nfor (const [premiumID, tier] of Object.entries(defs?.Definitions ?? {})) {\n  const active = state?.Subscriptions?.[premiumID];\n  const isActive =\n    !!active?.ExpirationDate && new Date(active.ExpirationDate) > new Date();\n  const canTrial =\n    (tier.TrialDurationDays ?? 0) > 0 &&\n    !state?.ActivatedTrialIDs?.includes(premiumID);\n  // isActive drives \"renews on\"/\"expired\" copy;\n  // canTrial drives whether to show a \"Start free trial\" button.\n}\n```\n\n### Activate a free trial\n\n```ts\nconst res = await client.premium.activateTrial(\"vip_gold\", crypto.randomUUID());\nif (!res.ok) return showError(res.error); // e.g. \"Trial already used.\"\nres.data.Subscription?.ExpirationDate; // when the trial ends\n```\n\nOnly tiers with `TrialDurationDays > 0` support this — otherwise the backend\nrejects with `\"Trial is not available for this premium.\"` A trial also can't\nbe started on top of an already-active subscription to the same tier\n(`\"Subscription already active.\"`).\n\n### Purchase a tier with virtual currency\n\n```ts\nconst res = await client.premium.purchaseItemOrCurrency(\n  \"vip_gold\",\n  crypto.randomUUID(),\n  \"Default\",\n  1,\n);\nif (!res.ok) return showError(res.error); // e.g. \"PriceOption not found\", insufficient funds\n// cache now has the new/renewed subscription + debited balances.\n```\n\nIf the player already has this exact tier active, the purchase **extends**\nits `ExpirationDate` rather than starting a fresh countdown or stacking a\nsecond entry — see\n[the renewal rule](references/data-model.md#purchase-with-virtual-currency--items).\nThe chosen `selectedOptionID` must exist in that tier's `PriceOptions`, and\nthat option must carry a non-empty virtual cost — an option with no\n`RequiredResources` is reserved for the real-money flow and this call rejects\nit.\n\n### Complete a real-money purchase (App Store / Google Play) — not yet backed\n\n```ts\n// After your platform IAP SDK confirms the purchase and hands you a receipt:\nconst res = await client.premium.purchaseRealMoney(\n  \"vip_gold\",\n  crypto.randomUUID(),\n  \"Apple\",\n  \"com.yourgame.vip_gold_monthly\",\n  receiptData, // base64 receipt / signed transaction payload\n);\nif (!res.ok) return showError(res.error);\n```\n\nThe method, request shape, and events are implemented client-side, but the\ncurrent backend has **no handler** for this action — calling it returns\n`reason: \"server\", error: \"Action not implemented\"` (see Gotchas below and\n[the reference](references/data-model.md#real-money-iap-purchase--current-backend-status)\nfor exactly why). Do not wire this into a shipping purchase button yet; treat\nit as a documented but currently-nonfunctional call.\n\n### Read the tier elsewhere (discounts/multipliers)\n\nOther modules don't expose a \"premium\" parameter — they read the cached tier\nthemselves server-side when computing `ResourceConsume.PremiumDiscounts` /\n`ResourceGrant.PremiumTiers` / `SegmentGate.MinPremiumTier`. Client-side, use\n`MaxActiveTier` only to preview/gray-out UI (e.g. \"Requires VIP Gold+\" on a\nstore offer or reward tier); the actual discount/bonus is applied by the\nbackend and arrives in that call's own `Resources`.\n\n```ts\nconst myTier = client.data.user.state?.Premium?.MaxActiveTier ?? 0;\nconst locked = (bundle.MinPremiumTier ?? 0) > myTier;\n```\n\n## Gotchas\n\n- **`purchaseRealMoney` is not implemented on the backend.** The v2\n  `Premium.cs` HTTP handler's action switch only has cases for\n  `GetDefinitions`, `GetUserState`, `ActivateTrial`, and\n  `PurchaseWithResources` — `PurchaseRealMoney` falls through to\n  `default: \"Action not implemented\"`\n  (`IDosGamesSDK/API/Client/v2/Premium/Premium.cs:52-69`). Real-money receipt\n  validation exists in the backend only under the legacy **v1** surface\n  (`ValidateIAP.cs`/`ValidateIAPSubscription.cs`), which is a separate\n  endpoint family not reachable through `client.premium`. Don't build a\n  shipping IAP-subscription flow on this call until the backend adds a real\n  handler.\n- **`ActivatedTrialIDs` is permanent and never cleared.** A trial is one-time\n  per `PremiumID` per account for the lifetime of the account — cancelling,\n  expiring, or unsubscribing doesn't remove the id. Check it client-side\n  before showing a trial CTA rather than relying only on the server\n  rejection (`\"Trial already used.\"`).\n- **An entry in `Subscriptions` isn't necessarily active.** Expired\n  subscriptions are kept, not deleted (they support renewal-on-top-of-lapse\n  math and history). Always check `ExpirationDate`, or just trust\n  `MaxActiveTier`, which already excludes expired/unknown tiers.\n- **Tiers take the max, they don't stack.** Holding two active subscriptions\n  at once doesn't add their `Tier`s — `MaxActiveTier` is simply the highest\n  `Tier` among currently-active subscriptions.\n- **Buying an already-active tier extends it, it doesn't restart it.** The\n  new duration is added on top of the existing `ExpirationDate`; buying tier\n  X again while X is still active is a renewal, not a discard-and-replace.\n- **Guard against double-submit.** Each call needs a caller-supplied\n  `transactionID`; reusing the same one for a retry is fine (that's what it's\n  for — both the trial and purchase endpoints detect a matching\n  `TransactionID` on the existing subscription and return the current state\n  with no new charge), but a double-clicked \"Subscribe\" with two _different_\n  generated ids is two real attempts. Disable the control while a call is in\n  flight. Firing the same endpoint again within the client throttle window\n  (default 600 ms) is rejected with `reason: \"throttled\"` rather than\n  duplicated, but don't rely on that for correctness.\n- **`Resources` is nullish only in shape, not in practice.** Trial responses\n  and idempotent-replay responses always come back with an explicit empty\n  `ResourceOperation` (never `null`) — but the type is still nullish, so\n  guard before reading into it anyway.\n- **Render from the cache, handle the error from the result.** The happy path\n  updates the cache + emits an event; the failure path gives you `reason` +\n  `error`. Use `reason` to decide behavior (retry on `\"connection\"`, re-auth on\n  `\"unauthorized\"`, toast the `error` on `\"server\"`).\n\n## Full reference\n\n[references/data-model.md](references/data-model.md) — every config and\nstate field, the exact tier-resolution algorithm, trial eligibility rules,\nthe purchase/renewal math, verbatim backend rejection strings, the current\nreal-money-purchase gap, and how other modules' gate/discount/multiplier\ntypes reference Premium's `Tier`/`MaxActiveTier`. Read it when building\nconfig-driven UI (renewal countdowns, trial eligibility, cost previews) or\nwhen an error message points at a rule you need to understand.\n",
+  "references": [
+    {
+      "path": "data-model.md",
+      "content": "# Premium data model — reference\n\nFull shape of the config (Definitions) and player state, the tier-resolution\nand trial rules the backend enforces, and the purchase/receipt flow. All of\nthese are **strictly typed in the SDK** — `PremiumDefinitions` and its nested\nblocks (`PremiumDefinition`, `PremiumPriceOption`) are exported from\n`@idosgames/core`, so `getDefinitions()` and\n`getSection<PremiumDefinitions>(\"Premium\")` give you concrete types, not\n`unknown`. The schemas keep `.passthrough()`, so a field the backend adds\nlater still round-trips. Field names are PascalCase (straight from the\nbackend JSON).\n\n## Contents\n\n- [Player state](#player-state) — what `getUserState()` returns\n- [Config: PremiumDefinitions](#config-premiumdefinitions) — what `getDefinitions()` returns\n- [PremiumDefinition](#premiumdefinition)\n- [PremiumPriceOption](#premiumpriceoption)\n- [Tier resolution (MaxActiveTier)](#tier-resolution-maxactivetier)\n- [Trial rules](#trial-rules)\n- [Purchase with virtual currency / items](#purchase-with-virtual-currency--items)\n- [Real-money IAP purchase — current backend status](#real-money-iap-purchase--current-backend-status)\n- [How other modules read a player's tier](#how-other-modules-read-a-players-tier)\n\n---\n\n## Player state\n\nReturned by `getUserState()` as `{ Premium: UserPremiumState }` and cached at\n`client.data.user.state?.Premium` (full replace on every write — see\n`applyPremium` in `packages/core/src/cache/UserData.ts:672`).\n\n```ts\ninterface UserPremiumState {\n  Subscriptions?: Record<string, PremiumSubscription>; // key = PremiumID\n  ActivatedTrialIDs?: string[]; // PremiumIDs already trialed — permanent, one-shot\n  MaxActiveTier?: number; // highest Tier among currently-active subscriptions\n}\n\ninterface PremiumSubscription {\n  PremiumID?: string;\n  PurchaseDate?: string; // ISO; set on first purchase, or on renewal after a full lapse\n  ExpirationDate?: string; // ISO (UTC); subscription is \"active\" iff this is strictly in the future\n  TransactionID?: string; // last transaction that touched this subscription (idempotency key)\n  IsAutoRenewEnabled?: boolean; // always false for trial/virtual purchases — see below\n}\n```\n\nSource: `IDosGamesSDK/API/Client/v2/Premium/Models/UserPremiumState.cs:13-40`.\n\nA subscription entry existing in `Subscriptions` does **not** mean it's\nactive — always compare `ExpirationDate` to \"now\" (or just trust\n`MaxActiveTier`, which the backend already recalculates for you on every\nread/write). Expired entries are never deleted; they're left in place so\n`ActivatedTrialIDs`-style history and renewal-on-top-of-lapsed logic keep\nworking. Don't build \"is subscribed\" UI off `Subscriptions[id]` existing —\ncheck its `ExpirationDate`, or better, read `MaxActiveTier`.\n\n---\n\n## Config: PremiumDefinitions\n\nReturned by `getDefinitions()`; cached via\n`client.data.config.getSection<PremiumDefinitions>(\"Premium\")`.\n\n```ts\ninterface PremiumDefinitions {\n  Definitions?: Record<string, PremiumDefinition>; // key = PremiumID\n}\n```\n\nSource: `IDosGamesSDK/API/Client/v2/Premium/Models/PremiumDefinition.cs:20-26`.\n\n---\n\n## PremiumDefinition\n\nSelf-contained template for one subscription / premium pass / VIP tier.\n\n```ts\ninterface PremiumDefinition {\n  PremiumID?: string; // stable id, e.g. \"silver_vip\" — never renamed after publish\n  DisplayName?: string;\n  Tier?: number; // 1, 2, 3... higher = more premium; compared against MinPremiumTier gates\n  DurationDays?: number; // subscription length; 0 = permanent, 30 = monthly, 365 = yearly\n  TrialDurationDays?: number; // 0 = no trial available for this tier\n  PriceOptions?: Record<string, PremiumPriceOption>; // key = OptionID, e.g. \"Default\"\n  AppleProductID?: string; // empty = not sold via App Store\n  GoogleProductID?: string; // empty = not sold via Google Play\n  Benefits?: Record<string, string>; // free-form slug -> stringified numeric param, for display only\n}\n```\n\nSource: `IDosGamesSDK/API/Client/v2/Premium/Models/PremiumDefinition.cs:35-108`.\n\n- **`Tier`** is the number every other module's gate compares against\n  (`SegmentGate.MinPremiumTier`, `ResourceConsume.PremiumTiers` /\n  `ResourceGrant.PremiumTiers` entries' `MinPremiumTier`, and any\n  `RequiredPremiumID` variants of the same gate — see\n  [How other modules read a player's tier](#how-other-modules-read-a-players-tier)).\n- **`DurationDays: 0`** means \"permanent\" — the backend actually implements\n  this as expiring **100 years** from purchase (`ComputePurchase`,\n  `IDosGamesSDK/API/Client/v2/Premium/Services/PremiumHelpers.cs:211`:\n  `now.AddYears(100)`), not a literal null-expiration sentinel. Treat any\n  `ExpirationDate` more than a few decades out as \"effectively permanent\" in\n  UI, but don't special-case `0`/`null` yourself — always compare the actual\n  `ExpirationDate`.\n- **`Benefits`** is display-only free-form data (e.g. `\"ExpMult\": \"1.2\"`,\n  `\"NoAds\": \"1.0\"`). The SDK does not interpret these keys — a title defines\n  its own vocabulary and its own game code reads them for copy/UI. They are\n  **not** the mechanism that actually grants discounts/multipliers/gates —\n  those are wired up server-side through `ResourceConsume.PremiumDiscounts` /\n  `PremiumTiers`, `ResourceGrant.PremiumTiers`, and `SegmentGate.MinPremiumTier`\n  independently of `Benefits`.\n\n---\n\n## PremiumPriceOption\n\nOne payment option within a `PremiumDefinition.PriceOptions` map.\n\n```ts\ninterface PremiumPriceOption {\n  OptionID?: string; // key within PriceOptions, e.g. \"Default\", \"bundle_a\"\n  Name?: string; // optional display name, e.g. \"For Gold\"\n  RequiredResources?: ResourceConsume; // debit-only cost; see below\n}\n```\n\nSource: `IDosGamesSDK/API/Client/v2/Premium/Models/PremiumDefinition.cs:117-140`.\n\n`RequiredResources` is a standard `ResourceConsume`\n(`packages/core/src/models/_shared/ResourceModels.ts`) — cost lives in\n`RequiredResources.Standard.Entries` (items/currencies) and/or\n`RequiredResources.Standard.EventTokens`. **`purchaseItemOrCurrency` requires\nat least one of those two to be non-empty** — the backend rejects the call\noutright with `\"This purchase option has no RequiredResources. Real-money\nflow is not supported by this endpoint.\"` if both are empty (this is how the\nserver tells apart a virtual-cost option from a real-money-only one; see\n[Real-money IAP purchase](#real-money-iap-purchase--current-backend-status)).\n`RequiredResources` may also declare `PremiumDiscounts` — if present, the\nbackend auto-applies the player's own best tier discount when charging, so\nthe amount actually debited can be lower than the raw `Amount` shown in the\noption (same mechanism documented in character-system's stat-cost formulas).\n\nSource of the rejection string: `IDosGamesSDK/API/Client/v2/Premium/Premium.cs:268`.\n\n---\n\n## Tier resolution (MaxActiveTier)\n\n`MaxActiveTier` is **not** stored independently — it's recomputed by\n`PremiumHelpers.RecalculateMaxTier` every time subscriptions change or are\nread (`IDosGamesSDK/API/Client/v2/Premium/Services/PremiumHelpers.cs:122-144`):\n\n1. Walk every entry in `Subscriptions`.\n2. Skip any whose `ExpirationDate <= now` (UTC) — expired subscriptions are\n   silently ignored, never physically removed.\n3. Skip any `PremiumID` no longer present in the title's `Definitions` (a\n   tier that was deleted/renamed from config after the player subscribed).\n4. `MaxActiveTier` = the highest `Tier` among what's left; `0` if nothing\n   qualifies.\n\nThis runs on `GetUserState`, `ActivateTrial`, and\n`PurchaseWithResources` — so `MaxActiveTier` is always self-healing: even if\nsubscriptions expire between calls, the very next `getUserState()` (or any\npurchase/trial call) corrects it and persists the correction\n(`NormalizePremiumState`, `IDosGamesSDK/API/Client/v2/Premium/Premium.cs:391-409`).\n**Tiers don't stack** — holding two active subscriptions doesn't add their\ntiers together, it just takes the max.\n\nA separate helper, `PremiumHelpers.HasRequiredPremium`\n(`IDosGamesSDK/API/Client/v2/Premium/Services/PremiumHelpers.cs:44-55`), is\nwhat other modules' gate checks actually call server-side:\n\n- If a gate specifies a `RequiredPremiumID`, it checks only whether that\n  exact `PremiumID` has an active subscription — **the tier number is\n  ignored** in this branch (owning a specific pass matters, not its rank).\n- Otherwise, if the gate specifies `MinPremiumTier > 0`, it checks\n  `MaxActiveTier >= MinPremiumTier`.\n- If neither is specified, the gate passes for everyone.\n\nThis is why `SegmentGate` and the resource-bundle gate types below expose\n**both** `MinPremiumTier` and `RequiredPremiumID`/`RequiredPremiumIDs` —\ntitles choose per-gate whether \"any tier ≥ N\" or \"must own this exact pass\"\nis the right check.\n\n---\n\n## Trial rules\n\n`activateTrial(premiumID, transactionID)` → backend `ActivateTrial`\n(`IDosGamesSDK/API/Client/v2/Premium/Premium.cs:140-238`). Checks, in order:\n\n1. `PremiumID` must be a safe Mongo key (no `.` or `$`) — else\n   `\"Invalid PremiumID\"`.\n2. `TransactionID` is required — else `\"TransactionID is required\"`.\n3. The tier's definition must exist — else `\"Premium definition not found\"`.\n4. **`TrialDurationDays` must be `> 0`** — else\n   `\"Trial is not available for this premium.\"` Not every tier offers a\n   trial; check `TrialDurationDays` before showing a trial CTA.\n5. **Idempotent replay**: if the player already has a `Subscriptions[premiumID]`\n   entry whose `TransactionID` matches the one just sent, the call returns\n   the existing subscription unchanged (no new trial, no error) — this is\n   what makes retrying a dropped request safe.\n6. **One trial per `PremiumID` per account, forever**: if `premiumID` is\n   already in `ActivatedTrialIDs`, the call fails with\n   `\"Trial already used.\"` This list is never cleared — cancelling a trial,\n   letting it expire, or unsubscribing does not remove the id, so a player\n   can never get a second free trial of the same tier from this endpoint.\n7. If the player has a _currently active_ (non-expired) subscription to that\n   same `PremiumID` already, the call fails with\n   `\"Subscription already active.\"` — you can't \"trial\" on top of an\n   existing live subscription.\n8. On success: a new `PremiumSubscription` is created with\n   `ExpirationDate = now + TrialDurationDays`, `IsAutoRenewEnabled: false`,\n   `premiumID` is appended to `ActivatedTrialIDs`, and `MaxActiveTier` is\n   recalculated. **No resources are consumed or granted** —\n   `PremiumPurchaseResponse.Resources` comes back as an empty\n   `ResourceOperation` (`Resources: new()`), never `null`, for this call.\n\nExact rejection strings (verbatim, from `Premium.cs`):\n`\"Invalid PremiumID\"` (line 149), `\"TransactionID is required\"` (line 150),\n`\"Premium definition not found\"` (line 154),\n`\"Trial is not available for this premium.\"` (line 156),\n`\"Trial already used.\"` (line 184),\n`\"Subscription already active.\"` (line 189),\n`\"User not found\"` (line 164), `\"Database update failed\"` (line 224).\n\n---\n\n## Purchase with virtual currency / items\n\n`purchaseItemOrCurrency(premiumID, transactionID, selectedOptionID, count)` →\nbackend `PurchaseWithResources`\n(`IDosGamesSDK/API/Client/v2/Premium/Premium.cs:240-389`, pure calc in\n`PremiumHelpers.ComputePurchase`, lines 180-255). Checks and behavior, in\norder:\n\n1. `PremiumID` safe-key check, `TransactionID` required — same errors as\n   trial.\n2. Definition must exist (`\"Premium definition not found\"`) and\n   `selectedOptionID` (default `\"Default\"`) must resolve to a configured\n   `PriceOptions` entry (`\"PriceOption not found\"`).\n3. The option's `RequiredResources` must carry at least one item/currency\n   entry or event-token entry — otherwise\n   `\"This purchase option has no RequiredResources. Real-money flow is not\nsupported by this endpoint.\"` (this endpoint is virtual-cost only; see\n   next section for real money).\n4. **Idempotent replay** (`ComputePurchase`): if `Subscriptions[premiumID]`\n   already has this exact `TransactionID`, the call returns the current\n   state with **no charge** — safe retry.\n5. **Renewal stacking, not tier stacking**: if the player already has an\n   active (non-expired) subscription to the _same_ `PremiumID`, the new\n   duration is added **on top of** the existing `ExpirationDate` rather than\n   from `now` (`baseTime = existingSub.ExpirationDate` when it's still in the\n   future). Buying tier X while X is already active extends it; it does not\n   reset the clock or double-grant. `PurchaseDate` is only updated when\n   there was no prior subscription or the prior one had fully expired.\n6. `count` (default 1, clamped to minimum 1) multiplies `DurationDays` when\n   computing the new expiration (`baseTime.AddDays(DurationDays * count)`) —\n   there's no separate \"quantity\" concept beyond stretching the duration.\n   `DurationDays <= 0` still resolves to the fixed `+100 years`, ignoring\n   `count`.\n7. **Charge and write are atomic together**: the resource debit\n   (`RequiredResources`, with the player's own `PremiumDiscounts` applied\n   automatically if configured) and the subscription write happen in the\n   same `ResourceService.ApplyResourceOperationAtomicAsync` call, guarded\n   additionally by a Mongo filter that rejects the write if a subscription\n   with this `TransactionID` already exists at write time (defense-in-depth\n   against double-charging beyond the idempotency-key check). Idempotency\n   key used: `PremiumPurchase:<transactionID-or-derived>` (via\n   `ResourceService.ResolveRelatedEntityID`).\n8. On success, `Resources` in the response is the actual `ResourceOperation`\n   result of the debit (what was consumed, post-discount) — read updated\n   balances from the cache, not by re-deriving the discount yourself.\n\nExact rejection strings (verbatim): `\"Invalid PremiumID\"`,\n`\"TransactionID is required\"`, `\"Premium definition not found\"`,\n`\"PriceOption not found\"` (line 261),\n`\"This purchase option has no RequiredResources. Real-money flow is not\nsupported by this endpoint.\"` (line 268), `\"User not found\"` (line 281),\n`\"Purchase failed: {result.Error}\"` (line 375, where `{result.Error}` is\nwhatever `ResourceService` reports — e.g. insufficient funds).\n\n---\n\n## Real-money IAP purchase — current backend status\n\nThe SDK's `purchaseRealMoney(...)` method sends `PremiumAction.PurchaseRealMoney`\nto `v2/{titleID}/Client/Premium/PurchaseRealMoney/{userID}`\n(`packages/core/src/api/PremiumApi.ts:78-86`, action enum in\n`PremiumModels.ts:130`). **As of this read, the v2 `Premium.cs` HTTP handler's\nswitch statement does not implement this action** — its `switch (act)` only\nhas cases for `GetDefinitions`, `GetUserState`, `ActivateTrial`, and\n`PurchaseWithResources`\n(`IDosGamesSDK/API/Client/v2/Premium/Premium.cs:52-69`); anything else\n(including `PurchaseRealMoney`) falls through to\n`default: return new BadRequestObjectResult(OperationResult<object>.Fail(\"Action not implemented\"))`\n(line 67).\n\nPractical implications for a consumer right now:\n\n- Calling `client.premium.purchaseRealMoney(...)` will resolve with\n  `{ ok: false, reason: \"server\", error: \"Action not implemented\" }` against\n  the current backend — it is **not** wired to any App Store/Google Play\n  receipt validator in v2.\n- Real-money IAP receipt validation does exist elsewhere in the backend, but\n  only in the **legacy v1** surface (`IDosGamesSDK/API/Client/v1/ValidateIAP.cs`,\n  `ValidateIAPSubscription.cs`) — that is a different endpoint family, not\n  reachable through `client.premium`, and out of scope for this module.\n- Do not build a shipping IAP-subscription flow against `purchaseRealMoney`\n  until the backend gains a real handler for this action. If a title needs\n  real-money subscriptions today, that requires a backend change outside the\n  TS SDK's control — flag it rather than working around it client-side.\n\nThe method, request fields, and response shape are still documented below\nfor completeness (and because the shape is stable/forward-compatible once the\nbackend does implement it), but treat this whole section as **\"designed, not\nyet backed\"** rather than a working call.\n\nRequest fields sent by `purchaseRealMoney(premiumID, transactionID, store,\nproductID, receiptData, purchaseToken?, packageName?, appStoreEnvironment?)`:\n\n```ts\ninterface PremiumRequest {\n  PremiumID: string;\n  TransactionID: string;\n  Store: \"Apple\" | \"Google\"; // StoreType\n  ProductID: string; // AppleProductID or GoogleProductID from the definition\n  ReceiptData: string; // base64 receipt (Apple) or receipt payload (Google)\n  PurchaseToken?: string; // Google Play Billing purchase token\n  PackageName?: string; // optional extra context\n  AppStoreEnvironment?: string; // optional: e.g. distinguishing sandbox vs production\n}\n```\n\n`client`-side validation in `PremiumService.purchaseRealMoney` requires\n`premiumID`/`transactionID` (`\"PremiumID and TransactionID are required.\"`)\nand `productID`/`receiptData`\n(`\"ProductID and ReceiptData are required.\"`) before it will even attempt\nthe call (`packages/core/src/services/PremiumService.ts:107-111`) — those are\n`reason: \"client\"` failures, not server rejections.\n\n---\n\n## How other modules read a player's tier\n\nPremium's own state (`MaxActiveTier`, active `Subscriptions`) is a\ncross-module dependency. Other modules declare gates/bonuses that reference\nit; **this skill documents only the shape Premium exposes**, not how those\nother modules apply it (that's each module's own skill):\n\n- `SegmentGate.MinPremiumTier` / `SegmentGate.RequiredPremiumIDs`\n  (`packages/core/src/models/_shared/SegmentModels.ts:27-28`) — audience\n  gating used across Store/Quest/DealOffer/etc.\n- `ResourceConsume.PremiumDiscounts` / `ResourceConsume.PremiumTiers`\n  and `ResourceGrant.PremiumTiers`\n  (`packages/core/src/models/_shared/ResourceModels.ts:37-54`), each entry a\n  `PremiumTierBundle { MinPremiumTier?, RequiredPremiumID?, Resources? }` —\n  cost discounts / bonus grants scaled by tier, resolved entirely\n  server-side inside `ResourceService`.\n- Reward accrual multipliers, e.g. `PremiumTierMultiplier\n{ MinPremiumTier?, RequiredPremiumID?, Multiplier? }`\n  (`packages/core/src/models/reward/RewardModels.ts:192-197`) and\n  `ClaimLimitOverride` tier overrides (same file, line 283+).\n- Ad-reduction perks, e.g. `PremiumAdReduction { MinPremiumTier?,\nRequiredPremiumID?, ... }` (`packages/core/src/models/advertising/AdvertisingModels.ts:110-115`).\n\nAll of these follow the same two-field pattern documented in\n[Tier resolution](#tier-resolution-maxactivetier): `RequiredPremiumID` (exact\npass, tier ignored) takes precedence when present, otherwise\n`MinPremiumTier` is compared against `MaxActiveTier`. Client-side, use\n`MaxActiveTier` only to preview/gray-out UI — the actual discount/bonus is\ncomputed and applied server-side inside that other call's own response.\n"
+    }
+  ]
+}