@indiegems/gem-web-sdk 23.2.0 → 24.0.0

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v23.2.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` v24.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.
 
@@ -3123,6 +3123,7 @@ fourth.
 - `declined` — the player closed the prompt, or the arcade chose not to show
   one. Return to the game silently.
 - `unavailable` — the arcade could not offer sign-in, or never answered.
+  [AccountApi.signInAvailable](#accountapi-signinavailable) says so before you draw the button.
 
 No reason is given for a `declined`, and one will never be added: why a
 sign-in did not happen is a fact about the player's account, and the arcade
@@ -3162,6 +3163,59 @@ interface AccountApi
 
 The account surface. `gem.account` is one of these.
 
+<a id="accountapi-signinavailable"></a>
+
+## AccountApi.signInAvailable
+
+```ts
+readonly signInAvailable: boolean
+```
+
+Whether [AccountApi.requestSignIn](#accountapi-requestsignin) can show this player a sign-in
+here. Read it before you draw a "Sign in to claim" button, and hide the
+offer when it is `false`.
+
+- `true` — a guest the arcade can offer sign-up to. An ask may still
+  answer `declined` at a busy moment.
+- `false` — an ask would show nothing. The player is already signed in
+  (it answers `signed_in` at once; every player in a current Gem Arcade
+  app build, v3.33.174 and later, is), or there is no Arcade sign-in here
+  (it answers `unavailable`). Also `false` until the player is known.
+
+On an arcade older than this signal it reads `true` for every player, a
+full account included, as before it existed. So gate a sign-up gift on it
+and on the guest test you use today; see docs/player-sign-in.md.
+[AccountApi.onSignInAvailableChange](#accountapi-onsigninavailablechange) tells you when it changes.
+
+```ts
+const draw = (available: boolean) => {
+  signInButton.hidden = !available;
+};
+draw(gem.account.signInAvailable);
+gem.account.onSignInAvailableChange(draw);
+```
+
+**Guides.** [player-sign-in](../player-sign-in.md)
+
+<a id="accountapi-onsigninavailablechange"></a>
+
+## AccountApi.onSignInAvailableChange
+
+```ts
+onSignInAvailableChange(listener: (available: boolean) => void): () => void
+```
+
+Runs `listener` whenever [AccountApi.signInAvailable](#accountapi-signinavailable) changes: when
+the player arrives, when the arcade changes its answer (a guest who signs
+up), and when the connection closes. Not on a re-sent player with the same
+answer.
+
+| Parameter | Type |
+| --- | --- |
+| `listener` | `(available: boolean) => void` |
+
+**Returns.** A function that stops the listener.
+
 <a id="accountapi-requestsignin"></a>
 
 ## AccountApi.requestSignIn
@@ -3998,7 +4052,8 @@ dimension for it on the events you want to break down, with the arms as its
 values, named after the experiment, and pass the selection there yourself:
 `gem.analytics.track('tutorial_finished', { tutorial_length: tutorial })`.
 Never the platform's `variant` field, which belongs to store-page
-experiments.
+experiments. For the platform's results to show the test, also declare it
+under `analytics_tests` in your game config (see docs/analytics.md).
 
 WAITS FOR THE PLAYER. The id arrives with the first play token, so a call
 during boot waits for it, and rejects as [Gem.awaitIdentity](#gem-awaitidentity) does
@@ -4683,10 +4738,13 @@ The SKU's id: what [StoreApi.purchase](#storeapi-purchase) takes.
 ## ArcadeOffer.kind
 
 ```ts
-readonly kind: "gem_pack" | "boost" | "pass" | "bundle"
+readonly kind: ArcadeOfferKind
 ```
 
-What sort of thing it is.
+What sort of thing it is: `coin_pack`, `boost`, `pass` or `bundle` — or
+`gem_pack`, which is deprecated: Gems are being retired, and a pack of
+Coins is `coin_pack`. Keep a `default` arm. See
+[the deprecation policy](../deprecation-policy.md).
 
 <a id="arcadeoffer-name"></a>
 
@@ -4736,7 +4794,7 @@ The price, formatted by the payment rail. Show it as given.
 readonly grant?: { currency: string; amount: number }
 ```
 
-For a Gem pack: the platform currency and the amount it grants.
+For a Coin pack: the platform currency and the amount it grants.
 
 <a id="arcadeoffer-grant-currency"></a>
 
@@ -4746,7 +4804,7 @@ For a Gem pack: the platform currency and the amount it grants.
 readonly currency: string
 ```
 
-The platform currency's exact slug, e.g. `GEMS`.
+The platform currency's exact slug, e.g. `ARCADE_TICKETS` for Coins.
 
 <a id="arcadeoffer-grant-amount"></a>
 
@@ -4758,6 +4816,129 @@ readonly amount: number
 
 How much of it the pack grants.
 
+<a id="arcadeoffer-pass"></a>
+
+## ArcadeOffer.pass
+
+```ts
+readonly pass?: string
+```
+
+For a pass, or a bundle carrying one: the pass's slug, such as `vip` — the
+slug `gem.me.passes` reports and [StoreApi.showPass](#storeapi-showpass) takes. Absent
+for everything else, and on an older Arcade.
+
+<a id="arcadeoffer-earnmultipliers"></a>
+
+## ArcadeOffer.earnMultipliers
+
+```ts
+readonly earnMultipliers: readonly ArcadeOfferEarnMultiplier[]
+```
+
+For an offer that makes the player earn a platform currency faster while
+they hold it: one entry per currency. Empty when it boosts nothing.
+
+The platform's own figure, for `gem.gameConfig.preview` to work out what
+holding it would add. **Never multiply a reward by it yourself**: the
+preview rounds the way the platform pays.
+
+<a id="arcadeofferkind"></a>
+
+## ArcadeOfferKind
+
+```ts
+type ArcadeOfferKind = "coin_pack" | "gem_pack" | "boost" | "pass" | "bundle"
+```
+
+What sort of SKU an [ArcadeOffer](#arcadeoffer) is. `gem_pack` is deprecated: Gems
+are being retired, and a pack of Coins is `coin_pack`.
+
+<a id="arcadeofferearnmultiplier"></a>
+
+## ArcadeOfferEarnMultiplier
+
+```ts
+interface ArcadeOfferEarnMultiplier
+```
+
+One currency an [ArcadeOffer](#arcadeoffer) boosts while it is held.
+
+<a id="arcadeofferearnmultiplier-currencyslug"></a>
+
+## ArcadeOfferEarnMultiplier.currencySlug
+
+```ts
+readonly currencySlug: string
+```
+
+The currency's slug, e.g. `ARCADE_TICKETS`.
+
+<a id="arcadeofferearnmultiplier-multiplierbp"></a>
+
+## ArcadeOfferEarnMultiplier.multiplierBp
+
+```ts
+readonly multiplierBp: number
+```
+
+Basis points: `10000` is 1x, `15000` is 1.5x. An integer, so the preview
+rounds exactly as the platform does.
+
+<a id="showpassoutcome"></a>
+
+## ShowPassOutcome
+
+```ts
+interface ShowPassOutcome
+```
+
+What [StoreApi.showPass](#storeapi-showpass) resolves with: an [ArcadeOutcome](#arcadeoutcome), plus
+whether a fresh read shows the pass held.
+
+<a id="showpassoutcome-outcome"></a>
+
+## ShowPassOutcome.outcome
+
+```ts
+readonly outcome: ArcadeOutcomeKind
+```
+
+What happened: `ok`, `declined` or `unavailable`. Branch on this.
+
+<a id="showpassoutcome-reason"></a>
+
+## ShowPassOutcome.reason
+
+```ts
+readonly reason?: string
+```
+
+Why, as a machine code — `busy`, `cancelled`, `not_found`, `pending`,
+`store_off`, `sign_in_required` and more. OPEN-ENDED: the arcade may send a
+code this SDK has never heard of, so keep a `default` arm and never show a
+code to a player. Absent when there is nothing to add.
+
+Three are the SDK's own, answered without asking the arcade:
+`unsupported` (the arcade here does not offer this), `invalid_argument`
+(the SDK refused what you passed) and `busy` (another ask of the same kind
+is still open). `error` means no reliable answer arrived — the ask never
+left, the wait ran out, the bridge closed or the arcade had none. For
+`gem.store.purchase` that makes the outcome UNKNOWN, not a refusal: the
+player may have paid.
+
+<a id="showpassoutcome-held"></a>
+
+## ShowPassOutcome.held
+
+```ts
+readonly held: boolean
+```
+
+Whether a fresh read of `gem.me.passes` showed the pass held once the
+sheet closed. `true` exactly when `outcome` is `ok` with no `reason`: a
+recipe the game runs next gets the pass's bonus.
+
 <a id="storeoffersoutcome"></a>
 
 ## StoreOffersOutcome
@@ -4837,10 +5018,11 @@ The SKU it was for. Re-read balances and inventory through `gem.me`.
 interface StoreApi
 ```
 
-**Real money.** The Arcade Store's own Gem packs, Boosts, passes and bundles,
+**Real money.** The Arcade Store's own Coin packs, Boosts, passes and bundles,
 bought with the player's money through the Arcade Store's own checkout.
-`gem.store` is one of these. To spend Gems or Coins on your game's own items,
-use `gem.purchases`.
+`gem.store` is one of these. To spend Coins on your game's own items, use
+`gem.purchases`. Only the Arcade sells Coins: a game never sells currency
+for money.
 
 <a id="storeapi-available"></a>
 
@@ -4851,7 +5033,7 @@ readonly available: boolean
 ```
 
 Whether the Arcade Store answers here, synchronously. Draw your own "Get
-Gems" button only when it is true.
+Coins" button only when it is true.
 
 <a id="storeapi-showofferavailable"></a>
 
@@ -4875,9 +5057,10 @@ offers(): Promise<StoreOffersOutcome>
 ```
 
 What the store sells this player here: names, art and the rail's own
-prices. `unavailable` / `sign_in_required` for a guest (offer
-`gem.account.requestSignIn`), `unavailable` / `store_off` where the store
-is withheld. Re-read on resume: what is on sale can change.
+prices. A guest is answered too: buying takes them through sign-up first,
+in the Arcade's own screens. `unavailable` / `store_off` where the store is
+withheld. An older Arcade answers a guest `unavailable` /
+`sign_in_required`. Re-read on resume: what is on sale can change.
 
 **Returns.** Always resolves; never rejects.
 
@@ -4937,7 +5120,8 @@ has left. The sheet's Buy opens the same checkout as
 
 Use it for an offer you would have to hardcode a pitch for: VIP and other
 passes, and bundles. Your button only needs to say what it opens. Draw a
-Gem pack yourself and use `purchase` instead. Check
+Coin pack yourself and use `purchase` instead. For a pass, call
+[StoreApi.showPass](#storeapi-showpass) with its slug. Check
 [StoreApi.showOfferAvailable](#storeapi-showofferavailable) first, and that the SKU is in `offers`.
 
 It answers exactly as `purchase` does, with one addition: `declined` /
@@ -4958,6 +5142,66 @@ player may read a sheet and pay for as long as they like.
 
 **Returns.** Always resolves; never rejects.
 
+<a id="storeapi-showpass"></a>
+
+## StoreApi.showPass
+
+```ts
+showPass(slug: string): Promise<ShowPassOutcome>
+```
+
+Show a pass by its slug in the Arcade's own sheet, over your paused game.
+Pass it `upsell.pass` straight from `gem.gameConfig.preview`, never a
+literal. Sugar over [StoreApi.offers](#storeapi-offers) and [StoreApi.showOffer](#storeapi-showoffer):
+it finds the offer whose `pass` is `slug` and shows that. A guest is taken
+through sign-up first, then back to the sheet.
+
+- `ok`, `held: true` — **a fresh read of `gem.me.passes` shows the pass
+  held.** Run the recipe or claim now, and the pass's bonus applies.
+- `ok` / `pending`, `held: false` — the player paid, and the pass has not
+  arrived yet (Ask to Buy, a slow payment). Run the recipe now, without
+  the bonus: the platform holds nothing back for later.
+- `declined` — they closed the sheet. Run the recipe as it is, and don't
+  ask again at this reward moment.
+- `unavailable` / `not_found` — the pass is not on sale to this player
+  here, or this Arcade is too old to say which offer is a pass, and
+  nothing opened. `unavailable` / `unsupported` — this Arcade draws no
+  sheet. Run the recipe as it is.
+- `unavailable` / `error` — **the outcome is unknown, and the player may
+  have paid.** Run the recipe; `gem.me.passes.on('changed')` hears the
+  pass if it arrives.
+
+NO TIMEOUT on the sheet, as with `showOffer`. After a paid `ok` it reads
+`gem.me.passes` for about ten seconds before it settles for `pending`.
+
+| Parameter | Type |
+| --- | --- |
+| `slug` | `string` |
+
+**Returns.** Always resolves; never rejects.
+
+<a id="storeapi-passonsale"></a>
+
+## StoreApi.passOnSale
+
+```ts
+passOnSale(slug: string): Promise<boolean>
+```
+
+Whether the pass `slug` is on sale to this player here, so
+[StoreApi.showPass](#storeapi-showpass) would open it. For a screen that sells a pass
+outside a reward moment, such as a "VIP perks" panel; at a reward moment,
+`gem.gameConfig.preview`'s `upsells` already says so. `false` where the
+store is off, for a player the platform won't sell it to, after the
+player declined its sheet twice today, and on an older Arcade. A player
+who holds the pass may still read `true`: the sheet adds time.
+
+| Parameter | Type |
+| --- | --- |
+| `slug` | `string` |
+
+**Returns.** Always resolves; never rejects.
+
 <a id="storeapi-onsettled"></a>
 
 ## StoreApi.onSettled
@@ -6647,6 +6891,256 @@ only when your studio corrects a running period; clients may hold the old
 content for up to an hour afterwards, and the hash is how a verifier tells
 them apart.
 
+<a id="previewtarget"></a>
+
+## PreviewTarget
+
+```ts
+type PreviewTarget = { recipe: string } | { progression: string; add?: number }
+```
+
+What to preview: a recipe, or a progression with the delta the game is about
+to apply. A config id, never an amount and never a pass.
+
+- `{ recipe: 'open_chest' }` — the recipe's grants, its roll, its bonuses,
+  and the platform payouts of any progression it adds to.
+- `{ progression: 'run_complete' }` — the progression's `on_complete`
+  payouts, "if it completes".
+- `{ progression: 'puzzles_cleared', add: 3 }` — its `on_add` payouts for
+  that delta, and its `on_complete` payouts if it completes.
+
+Ids and slugs are both accepted, as everywhere in `gem.gameConfig`.
+
+<a id="previewgrant"></a>
+
+## PreviewGrant
+
+```ts
+type PreviewGrant = { kind: "item"; itemId: string; quantity: number } | { kind: "currency"; currencyId: string; amount: number } | { kind: "roll"; lootTableId: string; count: number }
+```
+
+One thing a claim grants in your game. A roll is a count of rolls from a loot
+table, never what they land on: never show a locked roll's outcome.
+
+<a id="unmetrequirement"></a>
+
+## UnmetRequirement
+
+```ts
+interface UnmetRequirement
+```
+
+One requirement a bonus has that the player does not meet: where it is, and its kind.
+
+<a id="unmetrequirement-index"></a>
+
+## UnmetRequirement.index
+
+```ts
+readonly index: number
+```
+
+Its position in the bonus's `requires`.
+
+<a id="unmetrequirement-kind"></a>
+
+## UnmetRequirement.kind
+
+```ts
+readonly kind: string
+```
+
+Its kind, such as `holds_pass`. Never the pass or the item it names.
+
+<a id="bonuspreview"></a>
+
+## BonusPreview
+
+```ts
+interface BonusPreview
+```
+
+One `bonuses` entry, and whether this player gets it.
+
+<a id="bonuspreview-id"></a>
+
+## BonusPreview.id
+
+```ts
+readonly id: string
+```
+
+The bonus's id, as you configured it.
+
+<a id="bonuspreview-grants"></a>
+
+## BonusPreview.grants
+
+```ts
+readonly grants: readonly PreviewGrant[]
+```
+
+What it grants.
+
+<a id="bonuspreview-eligible"></a>
+
+## BonusPreview.eligible
+
+```ts
+readonly eligible: boolean | "unknown"
+```
+
+`true` — every requirement holds now. `false` — at least one does not
+(see `unmet`). `'unknown'` — one the browser cannot see, such as owning a
+platform item; never a guess. Advisory: the run decides.
+
+<a id="bonuspreview-unmet"></a>
+
+## BonusPreview.unmet
+
+```ts
+readonly unmet: readonly UnmetRequirement[]
+```
+
+The requirements that do not hold. Empty unless `eligible` is `false`.
+
+<a id="passupsell"></a>
+
+## PassUpsell
+
+```ts
+interface PassUpsell
+```
+
+What holding one pass would add to a claim.
+
+<a id="passupsell-pass"></a>
+
+## PassUpsell.pass
+
+```ts
+readonly pass: string
+```
+
+The pass's slug: what `gem.store.showPass` takes.
+
+<a id="passupsell-name"></a>
+
+## PassUpsell.name
+
+```ts
+readonly name: string
+```
+
+The store's own name for it, localized. Show this, never your own word for it.
+
+<a id="passupsell-offer"></a>
+
+## PassUpsell.offer
+
+```ts
+readonly offer: ArcadeOffer
+```
+
+The pass's offer, as `gem.store.offers` lists it.
+
+<a id="passupsell-platformgrants"></a>
+
+## PassUpsell.platformGrants
+
+```ts
+readonly platformGrants: readonly { currencySlug?: string; currencyId?: string; total: number; extra: number; ifComplete?: true }[]
+```
+
+Each payout this pass would raise: the new `total`, and the `extra` over now.
+
+<a id="passupsell-bonuses"></a>
+
+## PassUpsell.bonuses
+
+```ts
+readonly bonuses: readonly { id: string; grants: readonly PreviewGrant[] }[]
+```
+
+The bonuses this pass would make eligible.
+
+<a id="configpreview"></a>
+
+## ConfigPreview
+
+```ts
+interface ConfigPreview
+```
+
+What [PreviewTarget](#previewtarget) would give this player now, and what each pass would add.
+
+<a id="configpreview-grants"></a>
+
+## ConfigPreview.grants
+
+```ts
+readonly grants: readonly PreviewGrant[]
+```
+
+Your game's own grants: items, game currencies, rolls.
+
+<a id="configpreview-platformgrants"></a>
+
+## ConfigPreview.platformGrants
+
+```ts
+readonly platformGrants: readonly PlatformGrantPreview[]
+```
+
+One per platform payout that would fire.
+
+<a id="configpreview-bonuses"></a>
+
+## ConfigPreview.bonuses
+
+```ts
+readonly bonuses: readonly BonusPreview[]
+```
+
+One per `bonuses` entry, in config order.
+
+<a id="configpreview-upsells"></a>
+
+## ConfigPreview.upsells
+
+```ts
+readonly upsells: readonly PassUpsell[]
+```
+
+One per pass on sale here, not held, that would change this answer. Empty
+means show no upsell: no pass would add anything, or none is on sale to
+this player (a minor, a store that is off, a pass declined twice today, or
+already held).
+
+<a id="previewerror"></a>
+
+## PreviewError
+
+```ts
+class PreviewError
+```
+
+Why `gem.gameConfig.preview` could not work out an answer.
+
+<a id="previewerror-code"></a>
+
+## PreviewError.code
+
+```ts
+readonly code: "unsupported" | "not_found" | "invalid_argument"
+```
+
+`not_found` — the config has no recipe or progression by that id or
+slug; `invalid_argument` — the target is not `{ recipe }` or
+`{ progression, add? }` with a positive whole `add`; `unsupported` —
+not in a browser game (a function or a server runs the recipe and reads
+the receipt).
+
 <a id="gemlookspeed"></a>
 
 ## GemLookSpeed
@@ -7137,48 +7631,124 @@ readonly isOpen: boolean
 
 Whether the panel is on screen right now.
 
-<a id="gamepass"></a>
+<a id="platformgrantsource"></a>
 
-## GamePass
+## PlatformGrantSource
 
 ```ts
-interface GamePass
+type PlatformGrantSource = { source: "pass"; pass: string; amount: number } | { source: "boost"; amount: number }
 ```
 
-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.
+Where the part of a payout above its base comes from.
 
-<a id="gamepass-pass"></a>
+<a id="platformgrantpreview"></a>
 
-## GamePass.pass
+## PlatformGrantPreview
 
 ```ts
-readonly pass: string
+interface PlatformGrantPreview
 ```
 
-The pass's offering slug, such as `vip`. Stable and not localized: key on this.
+One platform payout — Coins, today — as the preview expects it or a receipt
+reports it, in one shape, so "you will earn" and "you earned" render with one
+component.
 
-<a id="gamepass-held"></a>
+<a id="platformgrantpreview-currencyslug"></a>
 
-## GamePass.held
+## PlatformGrantPreview.currencySlug
 
 ```ts
-readonly held: boolean
+readonly currencySlug?: string
 ```
 
-Whether the player holds it right now.
+The currency's slug, e.g. `ARCADE_TICKETS`. Absent when unknown.
 
-<a id="gamepass-endsat"></a>
+<a id="platformgrantpreview-currencyid"></a>
 
-## GamePass.endsAt
+## PlatformGrantPreview.currencyId
 
 ```ts
-readonly endsAt: string | null
+readonly currencyId?: string
 ```
 
-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.
+The currency's id, when it is known.
+
+<a id="platformgrantpreview-base"></a>
+
+## PlatformGrantPreview.base
+
+```ts
+readonly base: number
+```
+
+What a player with no pass and no Boost gets.
+
+<a id="platformgrantpreview-total"></a>
+
+## PlatformGrantPreview.total
+
+```ts
+readonly total: number
+```
+
+What this player gets: `base` plus `breakdown`.
+
+<a id="platformgrantpreview-breakdown"></a>
+
+## PlatformGrantPreview.breakdown
+
+```ts
+readonly breakdown: readonly PlatformGrantSource[]
+```
+
+The part above `base`, and what it is from. Empty when `total` is `base`.
+
+<a id="platformgrantpreview-ifcomplete"></a>
+
+## PlatformGrantPreview.ifComplete
+
+```ts
+readonly ifComplete?: true
+```
+
+`true` for an `on_complete` payout in a preview: it pays only if this
+claim completes the progression. Absent otherwise, and on a receipt.
+
+<a id="earningsapi"></a>
+
+## EarningsApi
+
+```ts
+interface EarningsApi
+```
+
+`gem.earnings`: what a payout was, in the shape `gem.gameConfig.preview`
+says it would be.
+
+<a id="earningsapi-fromreceipt"></a>
+
+## EarningsApi.fromReceipt
+
+```ts
+fromReceipt(change: unknown): Promise<PlatformGrantPreview | null>
+```
+
+Turn one `platform_grant` change from an order's receipt into a
+[PlatformGrantPreview](#platformgrantpreview): `base` is what a player with no pass and no
+Boost would have got under the same limits, `total` what this player got,
+and `breakdown` the pass's or the Boost's part, even when a limit trimmed
+the payout. Draw "you earned" with the component that drew "you will
+earn". Resolves `null` for any other kind of change.
+
+**This and `preview` are the only way to show a platform payout.** Never
+multiply by `gem.player.boost`, and never copy a config amount into your
+game.
+
+| Parameter | Type |
+| --- | --- |
+| `change` | `unknown` |
+
+**Returns.** Always resolves; never rejects.
 
 <a id="passesevent"></a>
 
@@ -10581,6 +11151,32 @@ when it pays. See [PlayerBoost](#playerboost).
 
 **Guides.** [platform-rules](../platform-rules.md)
 
+<a id="gemplayer-isguest"></a>
+
+## GemPlayer.isGuest
+
+```ts
+readonly isGuest: boolean
+```
+
+Whether the Arcade says this player is a **guest it can sign up here**.
+
+`true` only when the Arcade said so. `false` for a player with a full
+account, on a surface that offers no sign-up, and when the Arcade did not
+say — an older Arcade — so `false` is never proof of an account. That
+makes it the test for a sign-up gift: offer one only while this is
+`true`, and the gift can never reach a player who already has an account.
+
+It changes when a guest signs up in place: `gem.player` is pushed again,
+and `onPlayer` hears it.
+
+```js
+const gem = createGem({ onPlayer: (player) => (signUpGift.hidden = !player.isGuest) });
+```
+
+For drawing only, like everything on `gem.player`: what a sign-up earns
+is granted by your function or server, which reads the account itself.
+
 <a id="gemplayer-playerid"></a>
 
 ## GemPlayer.playerId
@@ -11774,6 +12370,18 @@ Every other surface returns ids; this is what turns them into something a
 player can read. Call `load()` once during start-up, then look up
 synchronously wherever you render.
 
+<a id="gem-earnings"></a>
+
+## Gem.earnings
+
+```ts
+readonly earnings: EarningsApi
+```
+
+What a platform payout was: `gem.earnings.fromReceipt(change)` turns a
+receipt's `platform_grant` change into the shape `gem.gameConfig.preview`
+gives, so "you will earn" and "you earned" draw with one component.
+
 <a id="gem-purchases"></a>
 
 ## Gem.purchases
@@ -15178,6 +15786,67 @@ engine's WebTransport without a datagram lane (WebKit today): that is a
 fact about the browser too, and one worth remembering — see
 [webTransportRefusal](#webtransportrefusal).
 
+<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-daysleft"></a>
+
+## GamePass.daysLeft
+
+```ts
+readonly daysLeft: number
+```
+
+Whole days the player keeps it, rounded up so a pass with any time left
+reads at least `1`, and **capped at 7**: `7` means "7 or more", and is
+also what a pass held with no end reads. `0` when it is not held. Show
+`7` as "7+ days left", never as an exact end.
+
+<a id="gamepass-endsat"></a>
+
+## GamePass.endsAt
+
+```ts
+readonly endsAt: string | null
+```
+
+**Deprecated.** Use [GamePass.daysLeft](#gamepass-daysleft). An exact instant is a value two
+games could match to link one player's identities, so the platform will
+stop sending it; it reads `null` then. See
+[the deprecation policy](../deprecation-policy.md).
+
+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="platformcurrencyaccess"></a>
 
 ## PlatformCurrencyAccess
@@ -16349,6 +17018,47 @@ Resolves with what the platform half did: `ok`, `already_ended` (this
 match was already over, or you asked twice), `refused` (the allocation was
 not ready yet) or `failed` (the platform could not be reached).
 
+<a id="gemserverhost-passes"></a>
+
+## GemServerHost.passes
+
+```ts
+passes(playerId: string): Promise<GemServerHostRead>
+```
+
+Ask the platform half which game-visible passes a player in this match
+holds: the match pass read, made with the allocation's own proof.
+
+MAY BE ABSENT on older platform images, exactly as `endMatch` may, and a
+listen host never has it. `gem.match.playerPasses(playerId)` is this call;
+you rarely call it yourself.
+
+Resolves with what the platform answered — see [GemServerHostRead](#gemserverhostread)
+— and rejects only when the platform half could not be asked at all.
+
+| Parameter | Type |
+| --- | --- |
+| `playerId` | `string` |
+
+<a id="gemserverhost-boost"></a>
+
+## GemServerHost.boost
+
+```ts
+boost(playerId: string): Promise<GemServerHostRead>
+```
+
+Ask the platform half for a player's Boost, for display: the match boost
+read, made with the allocation's own proof.
+
+MAY BE ABSENT on older platform images and on a listen host.
+`gem.match.playerBoost(playerId)` is this call; you rarely call it
+yourself. Resolves and rejects as [GemServerHost.passes](#gemserverhost-passes) does.
+
+| Parameter | Type |
+| --- | --- |
+| `playerId` | `string` |
+
 <a id="gemserverhost-log"></a>
 
 ## GemServerHost.log
@@ -16381,6 +17091,41 @@ Like [GemServerHost.log](#gemserverhost-log), marked as a warning.
 | --- | --- |
 | `message` | `string` |
 
+<a id="gemserverhostread"></a>
+
+## GemServerHostRead
+
+```ts
+interface GemServerHostRead
+```
+
+What the platform half answered to a player read it made for this match:
+the HTTP status and the decoded JSON body, untouched.
+
+The runtime adds only the allocation's proof, which never enters the bundle
+process; the SDK reads the body and turns a refusal into a `GemApiError`, so
+a runtime never has to know what the route's answer means.
+
+<a id="gemserverhostread-status"></a>
+
+## GemServerHostRead.status
+
+```ts
+readonly status: number
+```
+
+The HTTP status the platform answered with.
+
+<a id="gemserverhostread-body"></a>
+
+## GemServerHostRead.body
+
+```ts
+readonly body: unknown
+```
+
+The decoded JSON body, or `null` when there was none.
+
 <a id="gemserverbundle"></a>
 
 ## GemServerBundle