@indiegems/gem-web-sdk 18.1.0 → 19.0.0

package/docs/api/api-reference-function.md

@@ -1,6 +1,6 @@
 # The function surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/function` v18.1.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/function` v19.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/function` exports exactly the symbols on this page and nothing else.
 
@@ -3165,6 +3165,127 @@ was already claimed from it — the progress resets, the rewards stay.
 | `progressionId` | `string` |
 | `signal` | `AbortSignal` |
 
+<a id="gamepass"></a>
+
+## GamePass
+
+```ts
+interface GamePass
+```
+
+One pass games may see, and whether this player holds it. Listed whether they
+hold it or not, and this is everything a game learns about it.
+
+<a id="gamepass-pass"></a>
+
+## GamePass.pass
+
+```ts
+readonly pass: string
+```
+
+The pass's offering slug, such as `vip`. Stable and not localized: key on this.
+
+<a id="gamepass-held"></a>
+
+## GamePass.held
+
+```ts
+readonly held: boolean
+```
+
+Whether the player holds it right now.
+
+<a id="gamepass-endsat"></a>
+
+## GamePass.endsAt
+
+```ts
+readonly endsAt: string | null
+```
+
+When the player stops holding it, RFC 3339 in UTC, grace and any queued
+period included. `null` when it is not held, and when it is held with no
+end, so read [GamePass.held](#gamepass-held) first: `null` alone never means ended.
+
+<a id="passesevent"></a>
+
+## PassesEvent
+
+```ts
+type PassesEvent = "changed"
+```
+
+The events [PassesApi.on](#passesapi-on) emits.
+
+<a id="passesapi"></a>
+
+## PassesApi
+
+```ts
+interface PassesApi
+```
+
+Which store passes the player holds, for the passes the platform lets games
+see. Reached as `gem.me.passes`. VIP is the pass `vip`.
+
+Use it to DRAW a door open or shut, never to decide: it runs in the player's
+browser. What a pass unlocks is decided by your function or server.
+
+Reads reject with a `GemApiError`, as every `gem.me` read does. That is
+unknown, not "not held", so keep what you drew. A guest reads as not holding.
+
+**Guides.** [arcade-and-store](../arcade-and-store.md)
+
+<a id="passesapi-list"></a>
+
+## PassesApi.list
+
+```ts
+list(): Promise<readonly GamePass[]>
+```
+
+Every pass games may see, held or not, ordered by slug. Empty when the
+platform marks none. Always a fresh read; callers at the same moment share
+one request.
+
+<a id="passesapi-get"></a>
+
+## PassesApi.get
+
+```ts
+get(pass: string): Promise<GamePass>
+```
+
+One pass by its slug. A pass the platform does not list reads as not held,
+so a door for a pass that is not on sale yet simply stays shut.
+
+| Parameter | Type |
+| --- | --- |
+| `pass` | `string` |
+
+<a id="passesapi-on"></a>
+
+## PassesApi.on
+
+```ts
+on(event: "changed", listener: (passes: readonly GamePass[]) => void): () => void
+```
+
+Hear the list change, with the new list, so a door opens right after a
+purchase and locks again when the pass ends. Returns a function that stops
+listening.
+
+While something listens, the SDK reads again after a `gem.store` purchase
+answers, when one settles, on resume (so a purchase in the Arcade's own
+store is heard), after a sign-in and when a held pass ends. It says
+something only if the answer differs. Never fires in a function.
+
+| Parameter | Type |
+| --- | --- |
+| `event` | `"changed"` |
+| `listener` | `(passes: readonly GamePass[]) => void` |
+
 <a id="saverecord"></a>
 
 ## SaveRecord
@@ -3923,6 +4044,130 @@ readonly progressions: ProgressionsApi
 Progressions this entity is working through — a projection over the same
 cached snapshot [EntityScope.inventory](#entityscope-inventory) serves.
 
+<a id="playerscope"></a>
+
+## PlayerScope
+
+```ts
+interface PlayerScope
+```
+
+What the signed-in player has in your game: everything a character has, and
+the store passes they hold. Reached as `gem.me`.
+
+**Guides.** [saving-player-progress](../saving-player-progress.md)
+
+<a id="playerscope-settings"></a>
+
+## PlayerScope.settings
+
+```ts
+readonly settings: SettingsApi
+```
+
+Small named values your game chooses to persist — a difficulty, a control
+scheme, a last-used loadout.
+
+Per key, so two settings written from two places do not overwrite each
+other. For a whole document of progress, use [EntityScope.saves](#entityscope-saves).
+
+<a id="playerscope-inventory"></a>
+
+## PlayerScope.inventory
+
+```ts
+readonly inventory: InventoryApi
+```
+
+What this player owns — items, and the progressions they are working
+through. Reads are cached; writes go through
+[EntityScope.mutations](#entityscope-mutations).
+
+<a id="playerscope-currencies"></a>
+
+## PlayerScope.currencies
+
+```ts
+readonly currencies: CurrenciesApi
+```
+
+Currency balances.
+
+A currency the player holds none of is simply absent rather than present as
+zero, so read it as a lookup with a default rather than a list to iterate.
+
+<a id="playerscope-mutations"></a>
+
+## PlayerScope.mutations
+
+```ts
+readonly mutations: MutationsApi
+```
+
+Changing what this player has — spending currency, granting items, running
+a crafting recipe, advancing a progression.
+
+Separate from [EntityScope.inventory](#entityscope-inventory) on purpose: reads are cached and
+safe to repeat, writes are neither, and one object holding both makes that
+distinction invisible where you call it.
+
+<a id="playerscope-saves"></a>
+
+## PlayerScope.saves
+
+```ts
+readonly saves: SavesApi
+```
+
+Saved progress — a world, a campaign, a replay. One document per key.
+
+The line against [EntityScope.settings](#entityscope-settings) is what the value is, not how
+big it is: a setting is a value your game names, a save is an opaque
+document the platform stores and hands back. A chosen difficulty is a
+setting; the campaign it applies to is a save.
+
+**Every save key must be declared in your game config first.** Writing to an
+undeclared key fails with a message naming it.
+
+**Guides.** [saving-player-progress](../saving-player-progress.md)
+
+<a id="playerscope-orders"></a>
+
+## PlayerScope.orders
+
+```ts
+readonly orders: OrdersApi
+```
+
+This entity's order history — a read-only record of changes that happened.
+
+Creating an order is [EntityScope.mutations](#entityscope-mutations); this answers "what
+happened" and "did my write land" (`orders.get(orderId)`).
+
+<a id="playerscope-progressions"></a>
+
+## PlayerScope.progressions
+
+```ts
+readonly progressions: ProgressionsApi
+```
+
+Progressions this entity is working through — a projection over the same
+cached snapshot [EntityScope.inventory](#entityscope-inventory) serves.
+
+<a id="playerscope-passes"></a>
+
+## PlayerScope.passes
+
+```ts
+readonly passes: PassesApi
+```
+
+Which store passes the player holds, of those the platform lets games see.
+For drawing a door; your function or server decides what a pass unlocks.
+
+**Guides.** [arcade-and-store](../arcade-and-store.md)
+
 <a id="setting"></a>
 
 ## Setting
@@ -8243,7 +8488,7 @@ cover. Prefer the named surfaces; this one takes a path and checks nothing.
 ## GemFunction.me
 
 ```ts
-readonly me: EntityScope
+readonly me: PlayerScope
 ```
 
 The invoking player's data in your game — settings, inventory, currencies,

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v18.1.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v19.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -2797,6 +2797,130 @@ readonly progressions: ProgressionsApi
 Progressions this entity is working through — a projection over the same
 cached snapshot [EntityScope.inventory](#entityscope-inventory) serves.
 
+<a id="playerscope"></a>
+
+## PlayerScope
+
+```ts
+interface PlayerScope
+```
+
+What the signed-in player has in your game: everything a character has, and
+the store passes they hold. Reached as `gem.me`.
+
+**Guides.** [saving-player-progress](../saving-player-progress.md)
+
+<a id="playerscope-settings"></a>
+
+## PlayerScope.settings
+
+```ts
+readonly settings: SettingsApi
+```
+
+Small named values your game chooses to persist — a difficulty, a control
+scheme, a last-used loadout.
+
+Per key, so two settings written from two places do not overwrite each
+other. For a whole document of progress, use [EntityScope.saves](#entityscope-saves).
+
+<a id="playerscope-inventory"></a>
+
+## PlayerScope.inventory
+
+```ts
+readonly inventory: InventoryApi
+```
+
+What this player owns — items, and the progressions they are working
+through. Reads are cached; writes go through
+[EntityScope.mutations](#entityscope-mutations).
+
+<a id="playerscope-currencies"></a>
+
+## PlayerScope.currencies
+
+```ts
+readonly currencies: CurrenciesApi
+```
+
+Currency balances.
+
+A currency the player holds none of is simply absent rather than present as
+zero, so read it as a lookup with a default rather than a list to iterate.
+
+<a id="playerscope-mutations"></a>
+
+## PlayerScope.mutations
+
+```ts
+readonly mutations: MutationsApi
+```
+
+Changing what this player has — spending currency, granting items, running
+a crafting recipe, advancing a progression.
+
+Separate from [EntityScope.inventory](#entityscope-inventory) on purpose: reads are cached and
+safe to repeat, writes are neither, and one object holding both makes that
+distinction invisible where you call it.
+
+<a id="playerscope-saves"></a>
+
+## PlayerScope.saves
+
+```ts
+readonly saves: SavesApi
+```
+
+Saved progress — a world, a campaign, a replay. One document per key.
+
+The line against [EntityScope.settings](#entityscope-settings) is what the value is, not how
+big it is: a setting is a value your game names, a save is an opaque
+document the platform stores and hands back. A chosen difficulty is a
+setting; the campaign it applies to is a save.
+
+**Every save key must be declared in your game config first.** Writing to an
+undeclared key fails with a message naming it.
+
+**Guides.** [saving-player-progress](../saving-player-progress.md)
+
+<a id="playerscope-orders"></a>
+
+## PlayerScope.orders
+
+```ts
+readonly orders: OrdersApi
+```
+
+This entity's order history — a read-only record of changes that happened.
+
+Creating an order is [EntityScope.mutations](#entityscope-mutations); this answers "what
+happened" and "did my write land" (`orders.get(orderId)`).
+
+<a id="playerscope-progressions"></a>
+
+## PlayerScope.progressions
+
+```ts
+readonly progressions: ProgressionsApi
+```
+
+Progressions this entity is working through — a projection over the same
+cached snapshot [EntityScope.inventory](#entityscope-inventory) serves.
+
+<a id="playerscope-passes"></a>
+
+## PlayerScope.passes
+
+```ts
+readonly passes: PassesApi
+```
+
+Which store passes the player holds, of those the platform lets games see.
+For drawing a door; your function or server decides what a pass unlocks.
+
+**Guides.** [arcade-and-store](../arcade-and-store.md)
+
 <a id="setting"></a>
 
 ## Setting
@@ -6898,6 +7022,127 @@ readonly isOpen: boolean
 
 Whether the panel is on screen right now.
 
+<a id="gamepass"></a>
+
+## GamePass
+
+```ts
+interface GamePass
+```
+
+One pass games may see, and whether this player holds it. Listed whether they
+hold it or not, and this is everything a game learns about it.
+
+<a id="gamepass-pass"></a>
+
+## GamePass.pass
+
+```ts
+readonly pass: string
+```
+
+The pass's offering slug, such as `vip`. Stable and not localized: key on this.
+
+<a id="gamepass-held"></a>
+
+## GamePass.held
+
+```ts
+readonly held: boolean
+```
+
+Whether the player holds it right now.
+
+<a id="gamepass-endsat"></a>
+
+## GamePass.endsAt
+
+```ts
+readonly endsAt: string | null
+```
+
+When the player stops holding it, RFC 3339 in UTC, grace and any queued
+period included. `null` when it is not held, and when it is held with no
+end, so read [GamePass.held](#gamepass-held) first: `null` alone never means ended.
+
+<a id="passesevent"></a>
+
+## PassesEvent
+
+```ts
+type PassesEvent = "changed"
+```
+
+The events [PassesApi.on](#passesapi-on) emits.
+
+<a id="passesapi"></a>
+
+## PassesApi
+
+```ts
+interface PassesApi
+```
+
+Which store passes the player holds, for the passes the platform lets games
+see. Reached as `gem.me.passes`. VIP is the pass `vip`.
+
+Use it to DRAW a door open or shut, never to decide: it runs in the player's
+browser. What a pass unlocks is decided by your function or server.
+
+Reads reject with a `GemApiError`, as every `gem.me` read does. That is
+unknown, not "not held", so keep what you drew. A guest reads as not holding.
+
+**Guides.** [arcade-and-store](../arcade-and-store.md)
+
+<a id="passesapi-list"></a>
+
+## PassesApi.list
+
+```ts
+list(): Promise<readonly GamePass[]>
+```
+
+Every pass games may see, held or not, ordered by slug. Empty when the
+platform marks none. Always a fresh read; callers at the same moment share
+one request.
+
+<a id="passesapi-get"></a>
+
+## PassesApi.get
+
+```ts
+get(pass: string): Promise<GamePass>
+```
+
+One pass by its slug. A pass the platform does not list reads as not held,
+so a door for a pass that is not on sale yet simply stays shut.
+
+| Parameter | Type |
+| --- | --- |
+| `pass` | `string` |
+
+<a id="passesapi-on"></a>
+
+## PassesApi.on
+
+```ts
+on(event: "changed", listener: (passes: readonly GamePass[]) => void): () => void
+```
+
+Hear the list change, with the new list, so a door opens right after a
+purchase and locks again when the pass ends. Returns a function that stops
+listening.
+
+While something listens, the SDK reads again after a `gem.store` purchase
+answers, when one settles, on resume (so a purchase in the Arcade's own
+store is heard), after a sign-in and when a held pass ends. It says
+something only if the answer differs. Never fires in a function.
+
+| Parameter | Type |
+| --- | --- |
+| `event` | `"changed"` |
+| `listener` | `(passes: readonly GamePass[]) => void` |
+
 <a id="rewardcue"></a>
 
 ## RewardCue
@@ -11080,7 +11325,7 @@ they are, and from [Gem.me](#gem-me), which is their data in your game.
 ## Gem.me
 
 ```ts
-readonly me: EntityScope
+readonly me: PlayerScope
 ```
 
 This player's data in your game — settings, inventory, currencies and
@@ -11334,7 +11579,8 @@ List what the store sells here with `offers()`, show each `priceDisplay`
 exactly as given, and call `purchase(skuId)` from the player's press. For a
 pass, a bundle or anything else whose pitch you would have to hardcode, call
 `showOffer(skuId)` instead, and the arcade draws the offer. After `ok`,
-re-read balances through [Gem.me](#gem-me). Nothing rejects.
+re-read balances through [Gem.me](#gem-me), and `gem.me.passes` for a pass.
+Nothing rejects.
 
 **Guides.** [arcade-and-store](../arcade-and-store.md)
 

package/docs/api/api-reference-server.md

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v18.1.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
+Generated from `@indiegems/gem-web-sdk/sdk` v19.0.0, the version of the package this file ships in. Every symbol below carries an explicit anchor, its `anchor` in `reference.json` beside this file.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.