@indiegems/gem-web-sdk 23.3.0 → 24.0.0

package/dist/server.d.ts

@@ -139,9 +139,15 @@ interface GemServerHost extends ServerBundleHost {
     broadcast(data: string | Uint8Array, options?: BroadcastOptions): void;
     kick(playerId: string, reason?: string): void;
     endMatch?(): Promise<"ok" | "already_ended" | "refused" | "failed" | (string & {})>;
+    passes?(playerId: string): Promise<GemServerHostRead>;
+    boost?(playerId: string): Promise<GemServerHostRead>;
     log(message: string): void;
     warn(message: string): void;
 }
+interface GemServerHostRead {
+    readonly status: number;
+    readonly body: unknown;
+}
 interface HostTokenSourceOptions {
     readonly clock: Clock;
     readonly timeoutMs?: number;
@@ -1774,6 +1780,40 @@ interface ServerListChallengesOptions {
 interface ServerChallenges {
     list(options: ServerListChallengesOptions): Promise<Challenge[]>;
 }
+interface MatchBoostMultiplier {
+    readonly currencySlug: string;
+    readonly multiplier: number;
+}
+interface MatchPlayerBoost {
+    readonly active: boolean;
+    readonly multipliers: readonly MatchBoostMultiplier[];
+    readonly expiresInDays?: number;
+}
+type PlatformGrantSource = {
+    readonly source: "pass";
+    readonly pass: string;
+    readonly amount: number;
+} | {
+    readonly source: "boost";
+    readonly amount: number;
+};
+interface PlatformGrantPreview {
+    readonly currencySlug?: string;
+    readonly currencyId?: string;
+    readonly base: number;
+    readonly total: number;
+    readonly breakdown: readonly PlatformGrantSource[];
+    readonly ifComplete?: true;
+}
+interface EarningsApi {
+    fromReceipt(change: unknown): Promise<PlatformGrantPreview | null>;
+}
+interface GamePass {
+    readonly pass: string;
+    readonly held: boolean;
+    readonly daysLeft: number;
+    readonly endsAt: string | null;
+}
 interface GemServerOptions {
     readonly baseUrl?: string;
     readonly clock?: Clock;
@@ -1812,7 +1852,10 @@ interface GemServer {
             readonly seats?: number;
         }, signal?: AbortSignal): Promise<MatchBackfillState>;
         reportPlayers(reports: readonly MatchPlayerReport[], signal?: AbortSignal): Promise<MatchPlayerReportResult[]>;
+        playerPasses(playerId: string, signal?: AbortSignal): Promise<readonly GamePass[]>;
+        playerBoost(playerId: string, signal?: AbortSignal): Promise<MatchPlayerBoost>;
     };
+    readonly earnings: EarningsApi;
     readonly analytics: ServerAnalytics;
     readonly functions: FunctionsApi;
     readonly challenges: ServerChallenges;
@@ -1913,4 +1956,4 @@ interface AchievementReceipt {
     readonly reason?: string;
 }
 declare function achievementReceipts(order: unknown): AchievementReceipt[];
-export { type AchievementReceipt, type AnalyticsFlushResult, type AnalyticsRejection, type AnalyticsValue, AuthError, type AuthFailure, type AuthState, type Base64String, type BroadcastOptions, type BytesResponse, CONDITIONAL_HEADERS, type Challenge, type ChallengeWindow, type ClientOptions, type Clock, type ConditionalRequestHeaders, type FunctionFailure, type FunctionInvokeOptions, type FunctionResult, FunctionsApi, type GameApi, GemApiError, GemClient, type GemErrorReason, GemFunctionError, type GemMatchServer, type GemServer, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerIdentity, type GemServerLifecycle, type GemServerOptions, type GemServerProfile, type HostTokenSource, type HostTokenSourceOptions, type MatchBackfillState, type MatchPlayerReport, type MatchPlayerReportResult, PlayerText, type RequestOptions, type RoomArgValue, type RuntimeShutdownPayload, type SendOptions, type ServerAnalytics, type ServerApi, type ServerBundleHost, type ServerChallenges, type ServerListChallengesOptions, type ServerShutdownInfo, type ServerTokenGrant, type TokenGrant, type Transport, TransportRefusal, type TransportRequest, type TransportResponse, type VersionedGetOptions, type VersionedResponse, achievementReceipts, asPlayerText, createGemServer, createHostTokenSource, createMatchServer, defineServer, systemClock, text, toBase64 };
+export { type AchievementReceipt, type AnalyticsFlushResult, type AnalyticsRejection, type AnalyticsValue, AuthError, type AuthFailure, type AuthState, type Base64String, type BroadcastOptions, type BytesResponse, CONDITIONAL_HEADERS, type Challenge, type ChallengeWindow, type ClientOptions, type Clock, type ConditionalRequestHeaders, type EarningsApi, type FunctionFailure, type FunctionInvokeOptions, type FunctionResult, FunctionsApi, type GameApi, type GamePass, GemApiError, GemClient, type GemErrorReason, GemFunctionError, type GemMatchServer, type GemServer, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerHostRead, type GemServerIdentity, type GemServerLifecycle, type GemServerOptions, type GemServerProfile, type HostTokenSource, type HostTokenSourceOptions, type MatchBackfillState, type MatchBoostMultiplier, type MatchPlayerBoost, type MatchPlayerReport, type MatchPlayerReportResult, type PlatformGrantPreview, type PlatformGrantSource, PlayerText, type RequestOptions, type RoomArgValue, type RuntimeShutdownPayload, type SendOptions, type ServerAnalytics, type ServerApi, type ServerBundleHost, type ServerChallenges, type ServerListChallengesOptions, type ServerShutdownInfo, type ServerTokenGrant, type TokenGrant, type Transport, TransportRefusal, type TransportRequest, type TransportResponse, type VersionedGetOptions, type VersionedResponse, achievementReceipts, asPlayerText, createGemServer, createHostTokenSource, createMatchServer, defineServer, systemClock, text, toBase64 };

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

@@ -1,6 +1,6 @@
 # The function surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/function` v23.3.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` 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/function` exports exactly the symbols on this page and nothing else.
 
@@ -1668,6 +1668,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="currencybalance"></a>
 
 ## CurrencyBalance
@@ -3184,49 +3303,6 @@ 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
@@ -7029,6 +7105,67 @@ const theirs = await gem.leaderboards.character('time-trial', characterId);
   caller may not act for this character at all — that one is decided from
   the caller's own claims, not from which character was asked for.
 
+<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
@@ -8715,6 +8852,19 @@ The invoking player's platform-currency balances and earn allowance. The
 platform refuses both for a game server. `earnAllowance.on()` never fires
 here: the hint comes from the arcade, and a function has none.
 
+<a id="gemfunction-earnings"></a>
+
+## GemFunction.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
+return to the game that draws it.
+
 <a id="gemfunction-profiles"></a>
 
 ## GemFunction.profiles