@indiegems/gem-web-sdk 23.2.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/analytics.md

@@ -295,6 +295,46 @@ It counts against the event's three dimensions and its cardinality cap like any
 on the events that answer the question rather than on all of them. Name the dimension after your
 experiment, never `variant`: the platform fills that one in itself, for store-page experiments.
 
+**Declare the test too, or the platform's results never show it.** The platform reads your own
+A/B test, every arm side by side, only when your game config names it under `analytics_tests`:
+which funnel it is read through, and which dimension of that funnel's first event holds the arm.
+This config uploads as it stands; its `tutorial_finished` entry is the one above, so declare it
+once:
+
+```yaml
+analytics_events:
+  - id: tutorial_started                 # step 0: carries the arm dimension
+    dimensions:
+      tutorial_length: { values: [short, long] }
+  - id: tutorial_finished
+    dimensions:
+      tutorial_length: { values: [short, long] }
+
+analytics_funnels:
+  - id: tutorial_test
+    steps: [tutorial_started, tutorial_finished]
+
+analytics_tests:
+  - id: tutorial_length_ab
+    name: "Tutorial: short vs long"        # optional, at most 60 characters
+    funnel: tutorial_test                  # declared in analytics_funnels
+    arm: tutorial_length                   # a values dimension of the funnel's step-0 event
+    arms: [short, long]                    # 2 to 8 of its declared values; the first is the control
+    step_labels: [Started, Finished]       # optional, one per step
+```
+
+- **The funnel's first step (step 0) must be your own event, and it must carry the arm
+  dimension.** Here `tutorial_started` declares `tutorial_length: { values: [short, long] }` and
+  your game passes the selection on it. Never start the funnel at `gem_session_start`: that is
+  the platform's event, and it can't carry your arm.
+- **The arm is a `values` dimension.** Its `arms` are values that dimension declares, so give
+  `experiment` a list of strings, not a count, for a test you want read this way.
+- **The first arm listed is the control.** The others are compared against it.
+
+It ships with the rest of your config, uploaded and promoted to the channel. The declaration
+records nothing new about any player: the arm is already in your events, and the declaration only
+names the funnel and the dimension.
+
 **The selection can be reproduced anywhere** — a dedicated server, an analytics query — because
 the hash is fixed and will not change: FNV-1a 32-bit over the UTF-8 bytes of
 `"<key>:<playerId>"`, then MurmurHash3's 32-bit finalizer (`fmix32`), as an unsigned integer, mod

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

@@ -1,6 +1,6 @@
 # The function surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/function` 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/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.
 
@@ -360,7 +360,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` does
@@ -1667,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
@@ -3183,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
@@ -7028,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
@@ -8714,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