@indiegems/gem-web-sdk 23.3.0 → 24.0.0

package/docs/arcade-and-store.md

@@ -1,8 +1,9 @@
 # Arcade features and the Arcade Store
 
 Your game can reach a few things the Arcade owns: its own app and yours in the app stores, another
-game, games like yours, and the **Arcade Store**, which sells Gem packs, Boosts, passes and
-bundles for real money.
+game, games like yours, and the **Arcade Store**, which sells Coin packs, passes such as VIP,
+Boosts and bundles for real money. **Only the Arcade sells Coins**: a game never sells currency
+for money.
 
 ```js
 // From the press on your own "More games like this" card.
@@ -12,17 +13,17 @@ async function onCardPressed(card) {
   if (outcome !== 'ok') showCardAsUnavailable(card);
 }
 
-// From the press on your own "Get Gems" button.
+// From the press on your own "Get Coins" button.
 async function onBuyPressed(offer) {
   const { outcome, reason } = await gem.store.purchase(offer.skuId);
   // Read through gem.me; nothing here carries an amount. `error` is "outcome unknown" (§9).
   if (outcome === 'ok' || reason === 'error') await refreshBalances();
 }
 
-// From the press on your own "Get VIP" button: the Arcade draws the offer.
+// From the press on your own "Get VIP" button: the Arcade draws the pass, found by its slug.
 async function onVipPressed() {
-  const { outcome, reason } = await gem.store.showOffer(VIP_SKU);
-  if (outcome === 'ok' || reason === 'error') await refreshBalances();
+  const { held } = await gem.store.showPass('vip');
+  if (held) drawVipBadge(); // a fresh read already shows VIP held (§10)
 }
 ```
 
@@ -51,10 +52,10 @@ itself. You get an outcome.
 | Money        | none                                             | **real money**, through the Arcade Store's checkout |
 | Who draws it | the Arcade (a new tab, a QR code, the next game) | your card or the Arcade's sheet, then the checkout  |
 
-`gem.store` is not `gem.purchases`. **`gem.purchases` spends Gems or Coins on your game's own
-items** ([`inventory-and-catalogs.md`](inventory-and-catalogs.md)). **`gem.store` sells the Arcade
-Store's own SKUs for the player's money.** A game that wants a "Get Gems" button uses `gem.store`;
-a game selling a sword for 50 Gems uses `gem.purchases`.
+`gem.store` is not `gem.purchases`. **`gem.purchases` spends Coins on your game's own items**
+([`inventory-and-catalogs.md`](inventory-and-catalogs.md)). **`gem.store` sells the Arcade Store's
+own SKUs for the player's money.** A game that wants a "Get Coins" button uses `gem.store`; a game
+selling a sword for 250 Coins uses `gem.purchases`.
 
 ## 2. Nothing rejects
 
@@ -78,7 +79,7 @@ An Arcade that does not offer a feature answers every call for it at once with `
 ```js
 if (gem.arcade.available.openGame) showMoreGamesSection();
 if (gem.arcade.available.appLinks) showGetTheAppButton();
-if (gem.store.available) showGetGemsButton();
+if (gem.store.available) showGetCoinsButton();
 if (gem.store.showOfferAvailable) showGetVipButton();
 ```
 
@@ -222,16 +223,26 @@ policy refused. Allow that host rather than a wildcard.
 ## 8. The Arcade Store's offers
 
 ```js
-const { outcome, reason, offers } = await gem.store.offers();
-if (outcome === 'unavailable' && reason === 'sign_in_required' && gem.account.signInAvailable)
-  showSignInButton(); // gem.account.requestSignIn
-for (const offer of offers) drawOffer(offer);
+const { outcome, offers } = await gem.store.offers();
+for (const offer of offers) if (offer.kind === 'coin_pack') drawCoinPack(offer);
 ```
 
-`offers()` lists what the Arcade Store sells this player, here, right now: Gem packs, Boosts,
-passes and bundles. Each offer has a `skuId`, a `kind` (`gem_pack`, `boost`, `pass` or `bundle`),
-the store's own `name` and `description`, an optional `imageUrl`, a `priceDisplay`, and, for a
-Gem pack, a `grant` naming the currency and amount.
+`offers()` lists what the Arcade Store sells this player, here, right now: Coin packs, passes,
+Boosts and bundles. Each offer has:
+
+- a `skuId`, which `purchase` and `showOffer` take;
+- a `kind`: `coin_pack`, `pass`, `boost` or `bundle`. `gem_pack` is deprecated: Gems are being
+  retired and a Gem pack is no longer sold. Keep a `default` arm;
+- the store's own `name` and `description`, an optional `imageUrl`, and a `priceDisplay`;
+- for a Coin pack, a `grant` naming the currency (`ARCADE_TICKETS`) and the amount;
+- for a pass, its slug in `pass` (VIP is `vip`), which `showPass` takes;
+- `earnMultipliers`: for an offer that makes the player earn a currency faster while they hold it,
+  such as VIP's +50% Coins, one `{ currencySlug, multiplierBp }` per currency. Empty otherwise.
+  **Never multiply a reward by it yourself**; the platform applies it when it pays.
+
+**A guest is answered too.** Buying takes a guest through sign-up in the Arcade's own screens, then
+back to what they chose, so a guest sees your "Get Coins" and "Get VIP" buttons. An older Arcade
+answers a guest `unavailable` / `sign_in_required`: hide the buttons there.
 
 - **Show `priceDisplay` exactly as given.** It is the payment rail's own price in the player's
   currency, already formatted. Never parse it, compare two of them, or compute a discount from it.
@@ -295,16 +306,17 @@ arrives, so your own celebration is visible.
 
 ```js
 // Decide on the screen you draw the button on.
-const { offers } = await gem.store.offers();
-const vip = offers.find((offer) => offer.skuId === VIP_SKU);
-if (gem.store.showOfferAvailable && vip) showGetVipButton();
+if (gem.store.showOfferAvailable && (await gem.store.passOnSale('vip'))) showGetVipButton();
 else hideGetVipButton();
 
 // From the press on that button.
-const { outcome, reason } = await gem.store.showOffer(VIP_SKU);
-if (outcome === 'ok' || reason === 'error') await refreshBalances();
+const { outcome, reason, held } = await gem.store.showPass('vip');
 ```
 
+For a pass, use **`showPass(slug)`**: it finds the pass's offer by its slug and shows it, so your
+game never names a SKU ([below](#a-pass-by-its-slug-showpass)). `showOffer(skuId)` is the same
+sheet for any other SKU, such as a bundle.
+
 `showOffer(skuId)` asks the Arcade to draw one SKU from `offers()` in its own sheet, over your paused
 and hidden game. The Arcade draws the art, what the player gets, a sale if one is running, and, for a
 pass the player already holds, how long it has left. The sheet's Buy opens the same checkout
@@ -312,13 +324,13 @@ pass the player already holds, how long it has left. The sheet's Buy opens the s
 
 Pick by who can say what the offer is:
 
-|                 | **You draw it: `offers()` + `purchase()`**          | **The Arcade draws it: `showOffer()`**                          |
-| --------------- | --------------------------------------------------- | --------------------------------------------------------------- |
-| Use it for      | Gem packs: a name, an amount and a price say it all | VIP and other passes, and bundles                               |
-| Your button     | says what it buys and shows `priceDisplay`          | says what it opens, such as "Get VIP"                           |
-| The press opens | the checkout, straight away                         | the Arcade's sheet, then the checkout if the player presses Buy |
-| Perks and sales | not available to you                                | always current, in the player's language                        |
-| A holder sees   | the same Buy button                                 | what they already have                                          |
+|                 | **You draw it: `offers()` + `purchase()`**           | **The Arcade draws it: `showPass()` or `showOffer()`**          |
+| --------------- | ---------------------------------------------------- | --------------------------------------------------------------- |
+| Use it for      | Coin packs: a name, an amount and a price say it all | VIP and other passes (`showPass`), and bundles                  |
+| Your button     | says what it buys and shows `priceDisplay`           | says what it opens, such as "Get VIP"                           |
+| The press opens | the checkout, straight away                          | the Arcade's sheet, then the checkout if the player presses Buy |
+| Perks and sales | not available to you                                 | always current, in the player's language                        |
+| A holder sees   | the same Buy button                                  | what they already have, and how to add time                     |
 
 - **Never write an offer's perks into your game.** They change without a new build of your game, and
   yours would go stale. Your button only needs the offer's name.
@@ -328,7 +340,9 @@ Pick by who can say what the offer is:
 - **The sheet does not tell you what the player holds.** It tells the player, so a button that
   stays up for a holder is fine: they see what they already have, and choose from there. To change
   your own screen for a holder, read `gem.me.passes` ([§11](#11-what-the-player-holds-and-a-vip-door)).
-- **Hide the button when the SKU is not in `offers()`.** A SKU that is not on sale here answers
+- **Hide the button when the pass is not on sale.** `passOnSale(slug)` says so, and is `false`
+  where the store is off, for a player the platform won't sell it to, once the player has declined
+  its sheet twice today, and on an older Arcade. A pass that is not on sale answers
   `unavailable` / `not_found`, and the player would have pressed a button that does nothing.
 - **Read `showOfferAvailable`, not `available`.** An older Arcade can sell through `purchase` and
   still not draw this sheet. It answers `unavailable` / `unsupported` and sends nothing. Hide the
@@ -337,16 +351,72 @@ Pick by who can say what the offer is:
 Every rule of `purchase` holds ([§9](#9-buying-from-the-arcade-store)), and the answers are the
 same, with one addition. `declined` / `cancelled` also covers the player leaving the sheet without
 pressing Buy, and you are not told which of the two they closed. Nothing backs off: the player's
-next press on either button opens it again.
+next press on either button opens it again. A pass is the exception: after the player declines its
+sheet **twice in a day**, the Arcade stops offering it to them until tomorrow, and `passOnSale`
+answers `false`. Your game cannot reset that count.
+
+### A pass, by its slug: `showPass`
+
+`showPass(slug)` is `offers()` plus `showOffer()`, with one promise of its own: **`ok` means a fresh
+read of `gem.me.passes` shows the pass held.** A recipe or claim your game runs next gets the pass's
+bonus, with no reload. That makes it safe to call at the moment the player is about to claim
+something:
+
+| Answer                        | `held`  | What happened                                                       | Then                                                               |
+| ----------------------------- | ------- | ------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `ok`                          | `true`  | the player bought it, and it is held now                            | run the recipe or claim: the bonus applies                         |
+| `ok` / `pending`              | `false` | the player paid, and the pass has not arrived yet (Ask to Buy, say) | run it now, without the bonus; nothing is held back for later      |
+| `declined` / `cancelled`      | `false` | they closed the sheet                                               | run it as it is, and don't ask again at this moment                |
+| `unavailable` / `not_found`   | `false` | not on sale to this player here, or an older Arcade                 | run it as it is, and hide the button                               |
+| `unavailable` / `unsupported` | `false` | this Arcade draws no sheet                                          | run it as it is, and hide the button                               |
+| `unavailable` / `error`       | `false` | **the outcome is unknown, and the player may have paid**            | run it; `gem.me.passes.on('changed')` hears the pass if it arrives |
+
+- **Pass it the slug the platform gave you,** never a SKU. VIP is `vip`.
+- **A guest** goes through sign-up first, then back to the sheet. A guest who signs up and buys
+  answers `ok` like anyone else.
+- **After a paid sheet it waits a little.** It reads `gem.me.passes` for about ten seconds before it
+  settles for `pending`, because the payment provider's notice can trail the checkout.
+- **A player who already holds the pass** sees how long they have left and can add time.
+
+### At a reward: the VIP extra roll
+
+The moment a pass sells best is the moment it would pay: a chest the player is about to open, where
+VIP adds a roll. **Your game never names the pass and never works out the extra.** It asks
+`gem.gameConfig.preview` what the claim gives, and the answer's `upsells` says what each pass on
+sale here would add:
+
+```js
+// The recipe carries `bonuses: [{ id: 'vip_roll', requires: [{ kind: 'holds_pass', pass: 'vip' }],
+//   grants: [{ type: 'roll', loot_table_id: '<chest_common>', count: 1 }] }]` in your game config.
+openButton.onclick = async () => {
+  const preview = await gem.gameConfig.preview({ recipe: 'open_chest' });
+  const upsell = preview.upsells[0];
+  if (upsell) {
+    // "VIP: +1 roll, 45 Coins" — upsell.name, and the extras locked, never what a roll would land on.
+    const choice = await vipCard.ask(upsell); // Get VIP and Continue, with equal weight
+    if (choice === 'get') await gem.store.showPass(upsell.pass);
+    openButton.focus(); // focus goes back where it was
+  }
+  const order = await gem.me.mutations.executeRecipe(CHESTS, 'open_chest');
+  // The base always runs; the VIP roll applies if the pass is held now.
+};
+```
+
+`upsells` is already empty wherever no upsell may be shown: for a minor, a store that is off, a pass
+the player declined twice today or already holds, and a claim no pass would change. So an empty
+list means draw no card. **Upsell only before the grant**, once per reward moment: the platform
+holds nothing back, so a pass bought afterwards cannot reach a chest already opened.
+[inventory-and-catalogs.md](inventory-and-catalogs.md#offering-vip-before-a-reward-the-upsell) has
+the rest of the rules, every one a must, and `bonuses` in full.
 
 ## 11. What the player holds, and a VIP door
 
 ```js
 const passes = await gem.me.passes.list();
-// [{ pass: 'vip', held: true, endsAt: '2026-11-29T12:34:56Z' }]
+// [{ pass: 'vip', held: true, daysLeft: 7, endsAt: '2026-11-29T12:34:56Z' }]
 
 const vip = await gem.me.passes.get('vip'); // one pass by its slug
-if (vip.held) drawVipBadge();
+if (vip.held) drawVipBadge(vip.daysLeft === 7 ? '7+ days left' : `${vip.daysLeft} days left`);
 ```
 
 `gem.me.passes` says which store passes the player holds. **VIP is the pass `vip`**, its offering
@@ -355,12 +425,15 @@ slug. Key on the slug, which is stable and not localized, and never on a display
 - **It lists every pass games may see, held or not.** An admin marks a pass as visible to games, and
   the list has one entry for each, so its shape never says what the player bought. A pass that is not
   marked is left out, and `get` reads a pass that is not listed as not held.
-- **A pass is a slug, whether it is held, and when it ends.** No price, no name, no perks, nothing
-  about how the player got it, and nothing about a pass that has ended.
-- **`endsAt` is the exact end,** grace and any queued period included, and `null` when the pass is not
-  held or is held with no end, which support can grant. Read `held` first: `null` alone never means
-  ended.
-- **A guest reads as not holding.** Every pass is `held: false`, and that is no error.
+- **A pass is a slug, whether it is held, and how many days it has left.** No price, no name, no
+  perks, nothing about how the player got it, and nothing about a pass that has ended.
+- **`daysLeft` is whole days, rounded up and capped at 7**: `7` means "7 or more", and is also what
+  a pass held with no end reads (support can grant one). `0` when it is not held. Show `7` as
+  "7+ days left", never as a date.
+- **`endsAt` is deprecated.** It is the exact end, to the second, and two games could match that
+  value to link one player's accounts, so the platform will stop sending it. Use `daysLeft`.
+- **A guest holds nothing.** When the Arcade says the player is a guest, every pass reads
+  `held: false` without a call to the platform, and that is no error.
 - **A read that fails rejects with a `GemApiError`, as every `gem.me` read does.** That is unknown,
   not "not held", so keep what you drew. It is the one call on this page that rejects.
 - **It is a read over your play token,** not an ask of the Arcade. It needs no press, and works
@@ -402,7 +475,7 @@ door.onPress = async () => {
 };
 
 // 3. BUYING. From the press on your own "How to get VIP" button.
-howToGetVipButton.onclick = () => gem.store.showOffer(VIP_SKU);
+howToGetVipButton.onclick = () => gem.store.showPass('vip');
 ```
 
 The function, in Rust, because only the platform's answer counts:
@@ -440,26 +513,32 @@ Ok(answer.to_string().into_bytes())
 "Me" on that route is the player who invoked the function. A function your server invoked has no
 player, and the route refuses it with `403`. The body is `{ pass, held, ends_at }` for each pass.
 
+**Gate on the pass, never on the boost.** VIP also shows in `gem.player.boost` as +50% Coins, but a
+boost is display-only and a player can hold one without VIP. What a pass unlocks is decided by
+`held` on this read, or by a `requires: holds_pass` on your config, checked by the platform
+([platform rules §8](platform-rules.md#8-a-players-boost-is-for-display-never-a-gate)).
+
 - **If the door and the function disagree, the function is right.** The player sees "How to get VIP"
   or the lounge, and either way nobody got in by editing the page. Redraw the door when the function
   says no.
-- **A guest has no VIP and cannot buy it from here.** Their door is shut, and `offers()` answers
-  `unavailable` / `sign_in_required`, so offer `gem.account.requestSignIn` instead of the button,
-  when `gem.account.signInAvailable` says the Arcade can show them a sign-in.
+- **A guest has no VIP, and can buy it from here.** Their door is shut, and `showPass('vip')` takes
+  them through sign-up, then back to the sheet. On an older Arcade, which answers a guest
+  `unavailable` / `sign_in_required`, offer `gem.account.requestSignIn` instead, when
+  `gem.account.signInAvailable` says the Arcade can show them a sign-in.
 
 ### When the door moves by itself
 
 While something listens to `on('changed')`, the SDK reads again at each of these, and calls you only
 if the answer differs:
 
-| Moment                                             | Why you cannot rely on something else                                          |
-| -------------------------------------------------- | ------------------------------------------------------------------------------ |
-| `store.purchase` or `store.showOffer` answers `ok` | `onSettled` does not fire after a plain `ok`                                   |
-| Either answers `unavailable` / `error`             | The outcome is unknown, and the player may have paid                           |
-| `gem.store.onSettled` fires                        | `ok` / `pending` still reads as not held                                       |
-| Your game resumes                                  | A purchase in the Arcade's own store, from the Gem menu, sends no event at all |
-| The player signs in                                | A guest who signs in may hold VIP                                              |
-| A held pass reaches `endsAt`                       | VIP does not renew, so the door has to lock by itself                          |
+| Moment                                              | Why you cannot rely on something else                                          |
+| --------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `store.purchase`, `showOffer` or `showPass` is `ok` | `onSettled` does not fire after a plain `ok`                                   |
+| Either answers `unavailable` / `error`              | The outcome is unknown, and the player may have paid                           |
+| `gem.store.onSettled` fires                         | `ok` / `pending` still reads as not held                                       |
+| Your game resumes                                   | A purchase in the Arcade's own store, from the Gem menu, sends no event at all |
+| The player signs in                                 | A guest who signs in may hold VIP                                              |
+| A held pass reaches `endsAt`                        | VIP does not renew, so the door has to lock by itself                          |
 
 A read that fails changes nothing, and is tried again later. A read that was already on its way when
 a purchase ended is never reused, so a stale answer cannot shut the door on the buyer. If you read
@@ -469,14 +548,36 @@ without a listener, call `list()` yourself at those moments; it is always fresh.
 
 ### On a dedicated server
 
-The platform has a read for this,
-`GET /v1/games/{game_id}/matches/{match_id}/players/{player_id}/passes`, with the same body, for a
-player in your live match. **A server bundle cannot call it yet**, and the SDK has no method for it,
-because it needs the allocation nonce: the route requires `X-Alloc-Nonce`, which the platform's
-runtime holds and never hands to your bundle. The boost read has the same limit. Reaching it takes a
-hook in the runtime, like the one behind `gem.match.end()`.
+`gem.match.playerPasses(playerId)` reads which passes a player in your match holds, in the shape
+`gem.me.passes.list()` gives: `{ pass, held, daysLeft }` for each pass marked visible to games. On a
+server it is the decision itself, because the browser is not in the call:
+
+```js
+export default defineServer((gem) => ({
+  async join(playerId) {
+    let vip = false;
+    try {
+      vip = (await gem.match.playerPasses(playerId)).some((p) => p.pass === 'vip' && p.held);
+    } catch {
+      // unknown: keep the lounge shut, and let the player ask again
+    }
+    if (vip) admitToLounge(playerId);
+  },
+}));
+```
+
+- **The platform half of the runtime makes the read**, with the match's own proof, which never
+  enters your bundle. So does `gem.match.end()`.
+- **It throws on a runtime image that predates it, and on a listen host** (a player's browser
+  hosting a P2P match), which has no such proof. Decide in a function there.
+- **A player outside your match** is refused `not_found` (`player_not_in_match`), and nothing about
+  them is read.
+- **It may be refused `forbidden` (`client_permission_denied`)** until the platform grants game
+  servers the pass read. That is unknown, not "not held": keep the door shut and say so, rather
+  than telling a VIP they have no VIP.
 
-Until then, decide in a function, or leave a VIP door out of a dedicated-server match.
+`gem.match.playerBoost(playerId)` reads the player's Boost for **display** — "2x Coins" on a results
+screen — never for a decision.
 
 ## 12. Outcomes and reasons
 
@@ -486,9 +587,10 @@ Until then, decide in a function, or leave a VIP door out of a dedicated-server
 | `openApp`         | opened, or `handed_off`   | `busy`              | `already_in_app`, `unsupported`, `error`                                                                      |
 | `openGame`        | the next game is starting | `busy`, `same_game` | `not_found`, `unsupported`, `error`                                                                           |
 | `similarGames`    | cards, possibly none      |                     | `unsupported`, `error`                                                                                        |
-| `store.offers`    | offers, possibly none     |                     | `sign_in_required`, `store_off`, `unsupported`, `error`                                                       |
+| `store.offers`    | offers, possibly none     |                     | `store_off`, `sign_in_required` (an older Arcade's guest), `unsupported`, `error`                             |
 | `store.purchase`  | paid, or `pending`        | `cancelled`, `busy` | `sign_in_required`, `store_off`, `not_found`, the provider's reason, `unsupported`, `error` (outcome unknown) |
 | `store.showOffer` | paid, or `pending`        | `cancelled`, `busy` | `sign_in_required`, `store_off`, `not_found`, the provider's reason, `unsupported`, `error` (outcome unknown) |
+| `store.showPass`  | held, or `pending`        | `cancelled`, `busy` | `not_found`, `store_off`, the provider's reason, `invalid_argument`, `unsupported`, `error` (outcome unknown) |
 
 Every reason is a short code of lower-case letters and underscores. The Arcade turns a payment
 provider's own code into that shape before it reaches you.
@@ -497,10 +599,11 @@ Four reasons come from the SDK itself rather than the Arcade:
 
 - `unsupported`: this Arcade does not offer the feature. Nothing was sent.
 - `invalid_argument`: the SDK refused the argument (an unknown `target`, a `ref` that is not an id
-  or a web address, a `limit` outside 1–24, an empty `skuId`). Nothing was sent.
+  or a web address, a `limit` outside 1–24, an empty `skuId` or pass slug). Nothing was sent.
 - `busy`: another acting ask from your game is still open. Nothing was sent.
 - `error`: no reliable answer arrived. The ask could not be sent, a read or an open waited out its
   timeout (30 seconds for a read, two minutes for `openApp` and `openGame`), the bridge closed
   before the answer came, or the Arcade said it had no reliable answer. For a read, try again
-  later. For `store.purchase` and `store.showOffer` it means **the outcome is unknown**, never
+  later. For `store.purchase`, `store.showOffer` and `store.showPass` it means **the outcome is
+  unknown**, never
   "nothing was bought" ([§9](#9-buying-from-the-arcade-store)).