@indiegems/gem-web-sdk 23.2.0 → 24.0.0

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

@@ -1,6 +1,6 @@
 # The server 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/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -1469,6 +1469,125 @@ 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="platformgrantsource"></a>
+
+## PlatformGrantSource
+
+```ts
+type PlatformGrantSource = { source: "pass"; pass: string; amount: number } | { source: "boost"; amount: number }
+```
+
+Where the part of a payout above its base comes from.
+
+<a id="platformgrantpreview"></a>
+
+## PlatformGrantPreview
+
+```ts
+interface PlatformGrantPreview
+```
+
+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="platformgrantpreview-currencyslug"></a>
+
+## PlatformGrantPreview.currencySlug
+
+```ts
+readonly currencySlug?: string
+```
+
+The currency's slug, e.g. `ARCADE_TICKETS`. Absent when unknown.
+
+<a id="platformgrantpreview-currencyid"></a>
+
+## PlatformGrantPreview.currencyId
+
+```ts
+readonly currencyId?: string
+```
+
+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="functioninvokeoptions"></a>
 
 ## FunctionInvokeOptions
@@ -1814,6 +1933,67 @@ await gem.functions.invoke({ claim: 'daily' }, { cueId });
   own `Err`. `TransportRefusal` for an input that is neither bytes nor
   JSON, before anything is sent. `AuthError` if the token cannot be renewed.
 
+<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="clock"></a>
 
 ## Clock
@@ -2449,6 +2629,21 @@ player, and that is not an error — fall back to something of your own.
 [GemMatchServer.profile](#gemmatchserver-profile) is the version you usually want: same
 information, with the name typed as [PlayerText](#playertext).
 
+<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="sendoptions"></a>
 
 ## SendOptions
@@ -2756,6 +2951,82 @@ gameId(): string
 
 The game this server is running — taken from its credential.
 
+<a id="matchboostmultiplier"></a>
+
+## MatchBoostMultiplier
+
+```ts
+interface MatchBoostMultiplier
+```
+
+One platform currency's Boost, as a dedicated server reads it.
+
+<a id="matchboostmultiplier-currencyslug"></a>
+
+## MatchBoostMultiplier.currencySlug
+
+```ts
+readonly currencySlug: string
+```
+
+The currency's slug, e.g. `GEMS` or `ARCADE_TICKETS`.
+
+<a id="matchboostmultiplier-multiplier"></a>
+
+## MatchBoostMultiplier.multiplier
+
+```ts
+readonly multiplier: number
+```
+
+How much faster the player earns it right now: `2` is 2x, `1` is not boosted.
+
+<a id="matchplayerboost"></a>
+
+## MatchPlayerBoost
+
+```ts
+interface MatchPlayerBoost
+```
+
+A player's Boost, as a dedicated server reads it — **for display only**,
+exactly as `gem.player.boost` is in the browser.
+
+⚠️ **Show it; never gate on it.** Nothing a player can do, reach or win may
+depend on whether they are boosted. To gate on something a player paid for,
+gate on a pass: `gem.match.playerPasses`.
+
+<a id="matchplayerboost-active"></a>
+
+## MatchPlayerBoost.active
+
+```ts
+readonly active: boolean
+```
+
+Whether any currency earns faster than 1x right now.
+
+<a id="matchplayerboost-multipliers"></a>
+
+## MatchPlayerBoost.multipliers
+
+```ts
+readonly multipliers: readonly MatchBoostMultiplier[]
+```
+
+One entry per boostable platform currency, boosted or not.
+
+<a id="matchplayerboost-expiresindays"></a>
+
+## MatchPlayerBoost.expiresInDays
+
+```ts
+readonly expiresInDays?: number
+```
+
+Whole days until the soonest boosted currency drops back to 1x, rounded up
+and **capped at 7** (`7` means "7 or more"). Absent when nothing is boosted.
+
 <a id="playertext"></a>
 
 ## PlayerText
@@ -3205,7 +3476,7 @@ See [ServerApi](#serverapi).
 ## GemServer.match
 
 ```ts
-readonly match: { end: null; setBackfill: null; reportPlayers: null }
+readonly match: { end: null; setBackfill: null; reportPlayers: null; playerPasses: null; playerBoost: null }
 ```
 
 Ending the match.
@@ -3311,6 +3582,77 @@ leave(playerId) {
 }
 ```
 
+<a id="gemserver-match-playerpasses"></a>
+
+## GemServer.match.playerPasses
+
+```ts
+playerPasses(playerId: string, signal?: AbortSignal): Promise<readonly GamePass[]>
+```
+
+Which game-visible passes a player in this match holds, in the shape
+`gem.me.passes.list()` gives in the browser: one entry per pass the
+platform marked visible to games, held or not, with `held` and
+`daysLeft`.
+
+**This is what to gate on** — a VIP door, a VIP-only mode. `held` is
+exactly what a `requires: holds_pass` requirement on the same slug
+decides. Read it when the player joins and again when you need it; it is
+not pushed.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `playerId` | `string` | A player in THIS match. Anyone else is refused
+  `not_found` (`player_not_in_match`) and nothing about them is read. |
+| `signal` | `AbortSignal` | Not used — the platform half bounds its own request. |
+
+**Throws.** When the platform image running this server predates the hook, or
+  on a listen host (a player's browser hosting a P2P match), which holds no
+  allocation proof. A `GemApiError` when the platform refuses, including
+  `forbidden` (`client_permission_denied`) until the platform grants game
+  servers the pass read.
+
+```js
+const vip = (await gem.match.playerPasses(playerId)).find((p) => p.pass === 'vip');
+if (vip?.held) openVipLounge(playerId);
+```
+
+<a id="gemserver-match-playerboost"></a>
+
+## GemServer.match.playerBoost
+
+```ts
+playerBoost(playerId: string, signal?: AbortSignal): Promise<MatchPlayerBoost>
+```
+
+A player's Boost, **for display only** — "2x Coins" on a results screen.
+Never gate content, difficulty, matchmaking or power on it; gate on a pass
+with `playerPasses`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `playerId` | `string` | A player in THIS match. |
+| `signal` | `AbortSignal` | Not used — the platform half bounds its own request. |
+
+**Throws.** As `playerPasses` does.
+
+<a id="gemserver-earnings"></a>
+
+## GemServer.earnings
+
+```ts
+readonly earnings: EarningsApi
+```
+
+What a platform payout was: `earnings.fromReceipt(change)` turns a
+`platform_grant` change from a receipt into the shape the browser's payout
+preview gives — `base`, `total`, and the pass's or the Boost's part — to
+send to the player whose screen draws it.
+
+A server has no read of the platform's currencies, so the answer carries
+`currencyId` and no `currencySlug`; the browser's `gem.earnings` fills the
+slug in.
+
 <a id="gemserver-analytics"></a>
 
 ## GemServer.analytics
@@ -3872,6 +4214,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
@@ -3904,6 +4287,26 @@ Like [GemServerHost.log](#gemserverhost-log), marked as a warning.
 | --- | --- |
 | `message` | `string` |
 
+<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="hosttokensourceoptions-clock"></a>
 
 ## HostTokenSourceOptions.clock
@@ -4299,7 +4702,7 @@ See [ServerApi](#serverapi).
 ## GemMatchServer.match
 
 ```ts
-readonly match: { end: null; setBackfill: null; reportPlayers: null }
+readonly match: { end: null; setBackfill: null; reportPlayers: null; playerPasses: null; playerBoost: null }
 ```
 
 Ending the match.
@@ -4405,6 +4808,77 @@ leave(playerId) {
 }
 ```
 
+<a id="gemmatchserver-match-playerpasses"></a>
+
+## GemMatchServer.match.playerPasses
+
+```ts
+playerPasses(playerId: string, signal?: AbortSignal): Promise<readonly GamePass[]>
+```
+
+Which game-visible passes a player in this match holds, in the shape
+`gem.me.passes.list()` gives in the browser: one entry per pass the
+platform marked visible to games, held or not, with `held` and
+`daysLeft`.
+
+**This is what to gate on** — a VIP door, a VIP-only mode. `held` is
+exactly what a `requires: holds_pass` requirement on the same slug
+decides. Read it when the player joins and again when you need it; it is
+not pushed.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `playerId` | `string` | A player in THIS match. Anyone else is refused
+  `not_found` (`player_not_in_match`) and nothing about them is read. |
+| `signal` | `AbortSignal` | Not used — the platform half bounds its own request. |
+
+**Throws.** When the platform image running this server predates the hook, or
+  on a listen host (a player's browser hosting a P2P match), which holds no
+  allocation proof. A `GemApiError` when the platform refuses, including
+  `forbidden` (`client_permission_denied`) until the platform grants game
+  servers the pass read.
+
+```js
+const vip = (await gem.match.playerPasses(playerId)).find((p) => p.pass === 'vip');
+if (vip?.held) openVipLounge(playerId);
+```
+
+<a id="gemmatchserver-match-playerboost"></a>
+
+## GemMatchServer.match.playerBoost
+
+```ts
+playerBoost(playerId: string, signal?: AbortSignal): Promise<MatchPlayerBoost>
+```
+
+A player's Boost, **for display only** — "2x Coins" on a results screen.
+Never gate content, difficulty, matchmaking or power on it; gate on a pass
+with `playerPasses`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `playerId` | `string` | A player in THIS match. |
+| `signal` | `AbortSignal` | Not used — the platform half bounds its own request. |
+
+**Throws.** As `playerPasses` does.
+
+<a id="gemmatchserver-earnings"></a>
+
+## GemMatchServer.earnings
+
+```ts
+readonly earnings: EarningsApi
+```
+
+What a platform payout was: `earnings.fromReceipt(change)` turns a
+`platform_grant` change from a receipt into the shape the browser's payout
+preview gives — `base`, `total`, and the pass's or the Boost's part — to
+send to the player whose screen draws it.
+
+A server has no read of the platform's currencies, so the answer carries
+`currencyId` and no `currencySlug`; the browser's `gem.earnings` fills the
+slug in.
+
 <a id="gemmatchserver-analytics"></a>
 
 ## GemMatchServer.analytics