@indiegems/gem-web-sdk 18.1.0 → 19.0.0

package/docs/arcade-and-store.md

@@ -40,7 +40,8 @@ itself. You get an outcome.
 - [8. The Arcade Store's offers](#8-the-arcade-stores-offers)
 - [9. Buying from the Arcade Store](#9-buying-from-the-arcade-store)
 - [10. Letting the Arcade show one offer](#10-letting-the-arcade-show-one-offer)
-- [11. Outcomes and reasons](#11-outcomes-and-reasons)
+- [11. What the player holds, and a VIP door](#11-what-the-player-holds-and-a-vip-door)
+- [12. Outcomes and reasons](#12-outcomes-and-reasons)
 
 ## 1. Two surfaces, and which one is real money
 
@@ -67,7 +68,7 @@ three and never grows:
 
 `reason` is a short code that says why. The set is open: a new Arcade build may send a reason your
 game has never seen, so branch on `outcome` and treat `reason` as a hint. The codes in use today are
-in [§11](#11-outcomes-and-reasons).
+in [§12](#12-outcomes-and-reasons).
 
 ## 3. What is available here
 
@@ -316,9 +317,9 @@ Pick by who can say what the offer is:
 - **Do not show a price on the button.** The sheet shows the right one for this player, which a
   sale or a pass can change, and `priceDisplay` does not say either of those. If you want a price on
   screen, draw the offer yourself and use `purchase`.
-- **You cannot tell whether the player holds a pass.** The Arcade keeps that to itself, and the
-  sheet tells the player. So the button stays up for a holder, and that is fine: the sheet is what
-  they see, and they choose from there.
+- **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
   `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
@@ -332,7 +333,149 @@ closed checkout, shared with `purchase`: the next ask of either kind is `decline
 while. The press shows nothing during a back-off, so give the player something else to do on that
 screen.
 
-## 11. Outcomes and reasons
+## 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' }]
+
+const vip = await gem.me.passes.get('vip'); // one pass by its slug
+if (vip.held) drawVipBadge();
+```
+
+`gem.me.passes` says which store passes the player holds. **VIP is the pass `vip`**, its offering
+slug. Key on the slug, which is stable and not localized, and never on a display name.
+
+- **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 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
+  wherever your game has a token, including where the store is off: holding a pass is not buying one.
+  Each call goes to the platform, so read when you draw and do not poll.
+
+### The browser draws, the server decides
+
+**Never decide anything from `gem.me.passes`.** It runs in the player's browser, and a player can
+make any answer come back. It is for drawing the door. What is behind the door comes from your
+function, which asks the platform and answers with the contents. A level that ships in your build is
+not behind a door at all, because a player can open it by editing the page.
+
+```js
+// 1. DRAWING. Open or shut. Nothing here unlocks anything.
+function drawVipDoor(passes) {
+  door.drawOpen(passes.some((p) => p.pass === 'vip' && p.held));
+}
+
+await gem.awaitBridge();
+try {
+  drawVipDoor(await gem.me.passes.list());
+} catch {
+  door.drawShut(); // unknown: the press below still asks the function
+}
+gem.me.passes.on('changed', drawVipDoor); // opens after a purchase, locks when VIP ends
+
+// 2. DECIDING. The press asks the function. The browser's reading is not part of the call.
+door.onPress = async () => {
+  let answer;
+  try {
+    answer = (await gem.functions.invoke({ door: 'vip-lounge' })).json();
+  } catch {
+    showDoorIsStuck(); // nothing decided: not "you need VIP"
+    return;
+  }
+  if (answer.allowed) enterLounge(answer.lounge);
+  else showHowToGetVip();
+};
+
+// 3. BUYING. From the press on your own "How to get VIP" button.
+howToGetVipButton.onclick = () => gem.store.showOffer(VIP_SKU);
+```
+
+The function, in Rust, because only the platform's answer counts:
+
+```rust
+use gem::functions::host::{self, ApiRequest, Caller};
+
+// The input says which door. It never says who is asking, or what they hold.
+let context = host::get_context();
+let Caller::Player(_) = context.caller else {
+    return Err("expected a player's call".into());
+};
+let read = host::call_api(&ApiRequest {
+    method: "GET".into(),
+    path: format!("/v1/games/{}/players/me/passes", context.game_id),
+    body: Vec::new(),
+})?;
+if read.status != 200 {
+    return Err(format!("the pass read answered {}", read.status)); // decides nothing
+}
+let body: serde_json::Value = serde_json::from_slice(&read.body).map_err(|e| e.to_string())?;
+let vip = body["passes"]
+    .as_array()
+    .into_iter()
+    .flatten()
+    .any(|pass| pass["pass"] == "vip" && pass["held"] == true);
+let answer = if vip {
+    serde_json::json!({ "allowed": true, "lounge": lounge_contents() })
+} else {
+    serde_json::json!({ "allowed": false })
+};
+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.
+
+- **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 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                      |
+
+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
+without a listener, call `list()` yourself at those moments; it is always fresh.
+
+`on` never fires in a function, which has none of those moments.
+
+### 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,
+for two reasons:
+
+- **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()`.
+- **No game server is allowed to yet.** It answers `403` `client_permission_denied` to every caller
+  until the platform grants game servers `passes.read`, which ships after the route itself.
+
+Until both land, decide in a function, or leave a VIP door out of a dedicated-server match.
+
+## 12. Outcomes and reasons
 
 | Call             | `ok`                      | `declined`          | `unavailable`                                                                                                 |
 | ---------------- | ------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------- |

package/docs/changelog.md

@@ -16,6 +16,24 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 19.0.0
+
+Upgrading from 18.1.1. Impact: required.
+
+### Rebuild
+
+- The player scope on the game object is now typed as PlayerScope instead of EntityScope. Recompile your game. If you annotated that value, or passed it to code that expects EntityScope, change the annotation to PlayerScope. Otherwise nothing else needs to change.
+
+### New capability
+
+- A game can now read which passes its player holds. Every pass the Arcade marks as visible to games is reported, held or not, with the time it ends. The read is exposed through PassesApi on PlayerScope, and it is not available on EntityScope because a character holds no pass. The result only tells you who holds a pass; your game still decides what the pass unlocks. PassesEvent lets you listen for changes, and the SDK re-reads after a store purchase completes, on resume, after a sign-in, and when a held pass ends, so a buyer's doors open without a reload. GamePass describes one entry in the result.
+
+## 18.1.1
+
+Upgrading from 18.1.0. Impact: none.
+
+Nothing in this release asks anything of a game.
+
 ## 18.1.0
 
 Upgrading from 18.0.0. Impact: recommended.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "18.1.0"
+  "@indiegems/gem-web-sdk": "19.0.0"
 }
 ```
 

package/docs/manifest.json

@@ -18,8 +18,8 @@
     },
     {
       "file": "arcade-and-store.md",
-      "sha256": "7320826529435d290159c8b0707f69819124607d1b38160dbc85f63b385fdea9",
-      "updated": "2026-10-30T13:36:37Z"
+      "sha256": "f5c2d57fbd28f576a6653167f0e50d12b6e4269c5f55f6020fa40d7fe2f4f3f1",
+      "updated": "2026-10-30T21:39:33Z"
     },
     {
       "file": "arcade-avatars.md",
@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "75530d611c02d513b1789d787e83a219392cfa92bfa70b1995aaa46bd233fbbd",
-      "updated": "2026-10-30T18:08:09Z"
+      "sha256": "fb27142771fc12eda3370d5d2cd5128a3ed03adaa947f674c8d35e781edb55d1",
+      "updated": "2026-10-31T03:13:57Z"
     },
     {
       "file": "daily-challenges.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "cefcb0179415e448ac16b5e7e23be35c48745aa1b4ac5e23e7375f58b3c8890c",
-      "updated": "2026-10-30T18:08:09Z"
+      "sha256": "271469a08140655896a5127f987c183dca5bff617357645ce7dedae68610a9b2",
+      "updated": "2026-10-31T03:13:57Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -138,8 +138,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "a5bdf1ca63a3c5f9f3ca8b123cc569135779960934c74176453f2596a22da7f4",
-      "updated": "2026-10-30T18:08:09Z"
+      "sha256": "1a71596efb1eca4783929912ba503d63cdb7d7e24346e836d55abcfaf751b347",
+      "updated": "2026-10-31T03:13:57Z"
     },
     {
       "file": "serverless-functions-js.md",

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v18.1.0/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v18.1.0/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v19.0.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v19.0.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 
@@ -829,6 +829,12 @@ The short version: the browser half is what a player's **session** can do, and t
 what a **match** can do. `gem.rooms.join()` has no meaning to a process that exists because a match
 was already allocated.
 
+**`gem.me.passes` is browser and function only**, and that is a limit rather than a principle. The
+platform has a match read of which passes a player in your match holds, but your bundle cannot call
+it: it requires the allocation nonce, which the runtime never hands to a bundle, as the boost read
+does, and it answers `403` to every caller until game servers are granted `passes.read`.
+[arcade-and-store.md](arcade-and-store.md#on-a-dedicated-server) has what to do instead.
+
 **Rooms are the case where those two answers differ**, so they are worth stating separately rather
 than filed under "browser-only". `gem.rooms` — join, leave, ready up, quick-join — is a player
 acting on their own membership, and your server has none. Reading and administering the room your

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "18.1.0",
+  "version": "19.0.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",