@indiegems/gem-web-sdk 13.1.0 → 13.2.0

package/dist/sdk.d.ts

@@ -87,6 +87,7 @@ interface RequestOptions {
     readonly keepalive?: boolean;
     readonly ifMatch?: string;
     readonly replaySafe?: boolean;
+    readonly retryRateLimited?: boolean;
 }
 interface VersionedGetOptions {
     readonly signal?: AbortSignal;
@@ -2264,6 +2265,12 @@ interface GemAdResult {
     readonly requestId: string;
     readonly outcome: "shown" | "no_ad" | "unavailable";
 }
+interface GemMomentResult {
+    readonly gem: typeof PROTOCOL;
+    readonly type: "gem.momentResult";
+    readonly requestId: string;
+    readonly shown: boolean;
+}
 interface GemSignInResult {
     readonly gem: typeof PROTOCOL;
     readonly type: "gem.signInResult";
@@ -4500,6 +4507,7 @@ interface FrameCallbacks {
     onDeviceSettings?(msg: GemDeviceSettings): void;
     onDeviceSettingsResult?(msg: GemDeviceSettingsResult): void;
     onAdResult?(msg: GemAdResult): void;
+    onMomentResult?(msg: GemMomentResult): void;
     onSignInResult?(msg: GemSignInResult): void;
     onFriendChallengeResult?(msg: GemFriendChallengeResult): void;
     onError?(code: GemErrorCode, message?: string): void;
@@ -4574,6 +4582,8 @@ declare class GemFrame {
     requestAvatar3dPurchase(requestId: string, itemId: string, currencySlug: string): boolean;
     putDeviceSettings(requestId: string, settings: Readonly<Record<string, unknown>>): boolean;
     requestAd(requestId: string, placement: string, format: "interstitial" | "rewarded"): boolean;
+    signalMoment(requestId: string, kind: string, placement?: string): boolean;
+    readyCalled(): boolean;
     requestSignIn(requestId: string): boolean;
     requestFriendChallenge(requestId: string, playerId: string, template: string, params?: Readonly<Record<string, string | number>>): boolean;
     close(): void;
@@ -4651,6 +4661,17 @@ interface AdsApi {
     requestAd(req: AdRequest): Promise<AdOutcome>;
     rewardedStatus(placement: string): Promise<RewardedStatus>;
 }
+type MomentKind = "level_end" | "run_end" | "match_end" | "menu_return" | "other_break";
+interface MomentSignal {
+    kind: MomentKind;
+    placement?: string;
+}
+interface MomentResult {
+    readonly shown: boolean;
+}
+interface MomentsApi {
+    signal(moment: MomentSignal): Promise<MomentResult>;
+}
 type DeviceSettings = Readonly<Record<string, unknown>>;
 type DeviceSettingsPutOutcome = "stored" | "too_large" | "unavailable";
 interface DeviceSettingsApi {
@@ -4785,6 +4806,7 @@ interface Gem {
     readonly gameConfig: GameConfigApi;
     readonly purchases: PurchaseApi;
     readonly deviceSettings: DeviceSettingsApi;
+    readonly moments: MomentsApi;
     readonly ads: AdsApi;
     readonly account: AccountApi;
     readonly share: ShareApi;
@@ -4840,4 +4862,4 @@ interface ExitAnalytics {
 }
 declare function leaveAndExit(rooms: ExitRooms, bridge: ExitBridge | null, reason?: string, analytics?: ExitAnalytics): Promise<void>;
 declare function createGem(options?: GemOptions): Gem;
-export { ARCADE_EMBEDDERS, AVATAR_RIGS, type AccountApi, type AdFormat, type AdOutcome, type AdOutcomeKind, type AdRequest, type AdsApi, AnalyticsApi, type AnalyticsFlushOptions, type AnalyticsFlushResult, type AnalyticsOptions, type AnalyticsRejection$1 as AnalyticsRejection, type AnalyticsValue, AuthError, type AuthFailure, type AuthState, type Avatar3dFamily, type Avatar3dOffer, type Avatar3dPrice, type Avatar3dPurchaseRequest, type AvatarRigNode, type AvatarRigs, type Avatars3dApi, type Base64String, type BootMark, type BootTimeline, type BroadcastOptions, type BytesResponse, CONDITIONAL_HEADERS, type Challenge, type ChallengeWindow, ChallengesApi, type ClientOptions, type Clock, type ConditionalRequestHeaders, type ConfiguredPurchasePayment, type ConfiguredPurchaseRequest, type ConfiguredPurchaseResult, type ControlsApi, DEVICE_SETTINGS_MAX_BYTES, DedicatedServerError, type DedicatedServerFailure, type DedicatedServerSession, type DevToolsOpener, type DeviceSettings, type DeviceSettingsApi, type DeviceSettingsPutOutcome, type DirectPurchaseRequest, type DirectPurchaseResult, type EarnAllowance, type EarnAllowanceEvent, type EarnAllowancePeriod, type EarnAllowanceReadOptions, type EntityLeaderboard, type EntityLeaderboardEntry, type EntityLeaderboardOptions, type EntityType$1 as EntityType, type ExitAnalytics, type ExitBridge, type ExitRooms, type FrameState, type Friend, type FriendChallenge, FriendChallengeError, type FriendChallengeErrorCode, type FriendChallengeOutcome, type FriendChallengeOutcomeKind, type FriendChallengeRequest, type FriendChallengesPage, FriendsApi, type FriendsPage, type FunctionFailure, type FunctionInvokeOptions, type FunctionResult, FunctionsApi, type GameApi, type GameConfig, type GameMenu, type GameMenuItem, type GameServerLink, type Gem, GemApiError, GemClient, type GemCohort, type GemCohorts, GemConfigError, type GemCorner, type GemDevTools, type GemErrorReason, GemFrame, GemFunctionError, type GemGraphicsQuality, type GemIdentity, type GemInsets, type GemLook, type GemLookBase, type GemLookDelta, type GemLookOptions, type GemLookSpeed, type GemMatchApi, type GemMatchServer, type GemMatchServerModule, type GemOptions, type GemPlayer, type GemPrefs, type GemRecommendedSettings, type GemReservedArea, GemSaveError, type GemServer, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerIdentity, type GemServerLifecycle, type GemServerOptions, type GemServerProfile, type GemTerminationNotice, GemUnframedError, type GemViewport, type GetLeaderboardOptions, type HostTokenSource, type HostTokenSourceOptions, type JoinWelcome, type Leaderboard, type LeaderboardEntry, type LeaderboardPeriod, LeaderboardsApi, type ListChallengesOptions, type ListFriendChallengesOptions, type ListFriendsOptions, MAX_PERIODS_BACK, type MatchBackfillState, type MatchConnectOptions, type MatchConnection, type MatchHosting, type MatchHostingMode, type MatchPlayerReport, type MatchPlayerReportResult, type MatchServeOptions, type MatchTransport, type MessageMeta, type MultiTransportSession, PLATFORM_EVENTS, type PeriodOptions, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, PlatformEarnAllowanceApi, type PlatformEventName, type PlayerBadge$1 as PlayerBadge, type PlayerBoost, type PlayerBoostMultiplier, type PlayerIdentity, type PlayerProfile, PlayerText, type ProfileCallOptions, type ProfileShowcaseEntry$1 as ProfileShowcaseEntry, ProfilesApi, type PurchaseApi, type PurchaseOptions, type PurchaseOutcome, PurchaseRefusal, type PurchaseRefusalCode, type PurchaseRequest, type PutBytesOptions, type PutSaveOptions, type RankedRow, type RecipeAvailability, type RecipeLock, type RequestOptions, type RewardCue, type RewardedStatus, type RoomArgValue, type SavePage, type SaveRecord, type SendOptions$1 as SendOptions, type ServerApi, type ServerBundleHost, type ServerTokenGrant, type SessionEndReason, type ShareApi, type ShareRequest, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SignInOutcome, type SignInOutcomeKind, type SnapshotCurrency, type SnapshotItem, type TokenGrant, type Transport, type TransportAdvert, type TransportKind, TransportRefusal, type TransportRequest, type TransportResponse, UNRELIABLE_CHANNEL_LABEL, type VersionedGetOptions, type VersionedResponse, type VibrationApi, type WalletVisibleOptions, type WornAvatar3d$1 as WornAvatar3d, asPlayerText, createBootTimeline, createGem, createGemServer, createHostTokenSource, createMatchServer, defineServer, leaveAndExit, mapIdentity, markOnResolve, platformIconUrl, presentJoinCredential, readTemplateTransports, readTransportAdvert, reportOnResolve, systemClock, text, toBase64, webTransportAvailable };
+export { ARCADE_EMBEDDERS, AVATAR_RIGS, type AccountApi, type AdFormat, type AdOutcome, type AdOutcomeKind, type AdRequest, type AdsApi, AnalyticsApi, type AnalyticsFlushOptions, type AnalyticsFlushResult, type AnalyticsOptions, type AnalyticsRejection$1 as AnalyticsRejection, type AnalyticsValue, AuthError, type AuthFailure, type AuthState, type Avatar3dFamily, type Avatar3dOffer, type Avatar3dPrice, type Avatar3dPurchaseRequest, type AvatarRigNode, type AvatarRigs, type Avatars3dApi, type Base64String, type BootMark, type BootTimeline, type BroadcastOptions, type BytesResponse, CONDITIONAL_HEADERS, type Challenge, type ChallengeWindow, ChallengesApi, type ClientOptions, type Clock, type ConditionalRequestHeaders, type ConfiguredPurchasePayment, type ConfiguredPurchaseRequest, type ConfiguredPurchaseResult, type ControlsApi, DEVICE_SETTINGS_MAX_BYTES, DedicatedServerError, type DedicatedServerFailure, type DedicatedServerSession, type DevToolsOpener, type DeviceSettings, type DeviceSettingsApi, type DeviceSettingsPutOutcome, type DirectPurchaseRequest, type DirectPurchaseResult, type EarnAllowance, type EarnAllowanceEvent, type EarnAllowancePeriod, type EarnAllowanceReadOptions, type EntityLeaderboard, type EntityLeaderboardEntry, type EntityLeaderboardOptions, type EntityType$1 as EntityType, type ExitAnalytics, type ExitBridge, type ExitRooms, type FrameState, type Friend, type FriendChallenge, FriendChallengeError, type FriendChallengeErrorCode, type FriendChallengeOutcome, type FriendChallengeOutcomeKind, type FriendChallengeRequest, type FriendChallengesPage, FriendsApi, type FriendsPage, type FunctionFailure, type FunctionInvokeOptions, type FunctionResult, FunctionsApi, type GameApi, type GameConfig, type GameMenu, type GameMenuItem, type GameServerLink, type Gem, GemApiError, GemClient, type GemCohort, type GemCohorts, GemConfigError, type GemCorner, type GemDevTools, type GemErrorReason, GemFrame, GemFunctionError, type GemGraphicsQuality, type GemIdentity, type GemInsets, type GemLook, type GemLookBase, type GemLookDelta, type GemLookOptions, type GemLookSpeed, type GemMatchApi, type GemMatchServer, type GemMatchServerModule, type GemOptions, type GemPlayer, type GemPrefs, type GemRecommendedSettings, type GemReservedArea, GemSaveError, type GemServer, type GemServerBundle, type GemServerFactory, type GemServerHost, type GemServerHostProfile, type GemServerIdentity, type GemServerLifecycle, type GemServerOptions, type GemServerProfile, type GemTerminationNotice, GemUnframedError, type GemViewport, type GetLeaderboardOptions, type HostTokenSource, type HostTokenSourceOptions, type JoinWelcome, type Leaderboard, type LeaderboardEntry, type LeaderboardPeriod, LeaderboardsApi, type ListChallengesOptions, type ListFriendChallengesOptions, type ListFriendsOptions, MAX_PERIODS_BACK, type MatchBackfillState, type MatchConnectOptions, type MatchConnection, type MatchHosting, type MatchHostingMode, type MatchPlayerReport, type MatchPlayerReportResult, type MatchServeOptions, type MatchTransport, type MessageMeta, type MomentKind, type MomentResult, type MomentSignal, type MomentsApi, type MultiTransportSession, PLATFORM_EVENTS, type PeriodOptions, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, PlatformEarnAllowanceApi, type PlatformEventName, type PlayerBadge$1 as PlayerBadge, type PlayerBoost, type PlayerBoostMultiplier, type PlayerIdentity, type PlayerProfile, PlayerText, type ProfileCallOptions, type ProfileShowcaseEntry$1 as ProfileShowcaseEntry, ProfilesApi, type PurchaseApi, type PurchaseOptions, type PurchaseOutcome, PurchaseRefusal, type PurchaseRefusalCode, type PurchaseRequest, type PutBytesOptions, type PutSaveOptions, type RankedRow, type RecipeAvailability, type RecipeLock, type RequestOptions, type RewardCue, type RewardedStatus, type RoomArgValue, type SavePage, type SaveRecord, type SendOptions$1 as SendOptions, type ServerApi, type ServerBundleHost, type ServerTokenGrant, type SessionEndReason, type ShareApi, type ShareRequest, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SignInOutcome, type SignInOutcomeKind, type SnapshotCurrency, type SnapshotItem, type TokenGrant, type Transport, type TransportAdvert, type TransportKind, TransportRefusal, type TransportRequest, type TransportResponse, UNRELIABLE_CHANNEL_LABEL, type VersionedGetOptions, type VersionedResponse, type VibrationApi, type WalletVisibleOptions, type WornAvatar3d$1 as WornAvatar3d, asPlayerText, createBootTimeline, createGem, createGemServer, createHostTokenSource, createMatchServer, defineServer, leaveAndExit, mapIdentity, markOnResolve, platformIconUrl, presentJoinCredential, readTemplateTransports, readTransportAdvert, reportOnResolve, systemClock, text, toBase64, webTransportAvailable };

package/dist/server-api.d.ts

@@ -40,6 +40,7 @@ interface RequestOptions {
     readonly keepalive?: boolean;
     readonly ifMatch?: string;
     readonly replaySafe?: boolean;
+    readonly retryRateLimited?: boolean;
 }
 interface VersionedGetOptions {
     readonly signal?: AbortSignal;

package/dist/server.d.ts

@@ -69,6 +69,7 @@ interface RequestOptions {
     readonly keepalive?: boolean;
     readonly ifMatch?: string;
     readonly replaySafe?: boolean;
+    readonly retryRateLimited?: boolean;
 }
 interface VersionedGetOptions {
     readonly signal?: AbortSignal;

package/docs/analytics.md

@@ -11,9 +11,9 @@ you design around them:
 - **Nothing is recorded that you did not declare.** There is no free-text property. Every event,
   every dimension and every value a dimension may take is published in your game config ahead of
   time, and anything else is refused per event rather than stored.
-- **Detail older than 30 days is gone.** Raw events live 30 days. The daily counters built from
+- **Detail older than 60 days is gone.** Raw events live 60 days. The daily counters built from
   them live 400. A question you can only answer by reading individual events is a question you can
-  only ask about the last month.
+  only ask about the last two months.
 
 What you record here is **yours**. It feeds your own reporting and nothing the platform treats as
 authoritative — see [section 8](#8-what-analytics-is-not) before you attach a reward to it.
@@ -253,7 +253,10 @@ Two results are not refusals and should not be treated as one:
   being counted twice.
 
 A rate limit or a temporarily unreachable backend **keeps the queue** and rejects the `flush`
-promise, so the next send carries the same events. A refusal that would fail identically forever
+promise, so the next send carries the same events. The SDK's own sends then wait for the longer
+of the platform's `Retry-After` and a cooldown that starts at 10 seconds and doubles with each
+refusal in a row, up to five minutes; the send on the way out of the page goes regardless. Only one
+`flush` is on the wire at a time. A refusal that would fail identically forever
 discards its batch instead, because a queue that can never empty fills up and starts dropping the
 events that would explain the problem.
 

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

@@ -1,6 +1,6 @@
 # The function surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/function` v13.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` v13.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.
 
 `@indiegems/gem-web-sdk/function` exports exactly the symbols on this page and nothing else.
 
@@ -8,6 +8,8 @@ Generated from `@indiegems/gem-web-sdk/function` v13.1.0, the version of the pac
 import { createGem } from '@indiegems/gem-web-sdk/function';
 ```
 
+⚠️ **JavaScript functions are disabled for now, due to performance issues.** Uploading a new JavaScript function is refused with `400 js_functions_disabled`: write a new function in Rust, as [serverless-functions](../serverless-functions.md#3-writing-one) shows. A JavaScript function already published keeps running, and this page is what it imports.
+
 A function imports the same package your game already depends on, written out in [getting-started](../getting-started.md#3-add-the-sdk) — the only place the install is written out. Your function’s build bundles this module, so the version your function runs is the one your `package.json` names: pin the version your game pins. A function published importing the SDK from the engine runs the engine’s built-in copy instead; [serverless-functions-js](../serverless-functions-js.md) says what that means.
 
 <a id="analyticsvalue"></a>
@@ -243,7 +245,7 @@ is what says which events exist, which dimensions each has and which values
 each dimension may take. An undeclared name or key is not stored — it comes
 back as a rejection, which the SDK prints to the console during development.
 
-⚠️ **Detail older than 30 days is gone.** Raw events live 30 days; the daily
+⚠️ **Detail older than 60 days is gone.** Raw events live 60 days; the daily
 counters live 400. Anything you want to be able to ask about a year from now
 has to be a declared dimension today.
 
@@ -355,9 +357,14 @@ the page.
 A refusal that could clear on its own — a 429 from the rate limiter, a 503
 while the platform's idempotency store is unreachable — KEEPS the queue
 and rejects, so the next flush sends the same events rather than losing
-them. A refusal that cannot clear discards the batch it was sent for,
+them. The SDK's own flushes then hold off for the longer of the server's
+`Retry-After` and a cooldown that doubles from 10 seconds, up to five
+minutes. A refusal that cannot clear discards the batch it was sent for,
 because resending it can only fail identically.
 
+One flush at a time: called while another is still on the wire, this
+resolves at once with nothing sent, and what is queued goes out after it.
+
 | Parameter | Type |
 | --- | --- |
 | `options` | `AnalyticsFlushOptions` |
@@ -666,6 +673,22 @@ It buys the same budget a read gets — see [ClientOptions.maxRetries](#clientop
 final: only the failures [GemApiError.retryable](#gemapierror-retryable) describes, and a
 connection that died with no answer, are attempted again.
 
+<a id="requestoptions-retryratelimited"></a>
+
+## RequestOptions.retryRateLimited
+
+```ts
+readonly retryRateLimited?: boolean
+```
+
+Set `false` to make a 429 final for this call instead of waiting out
+`Retry-After` and trying again.
+
+For a caller that keeps its own queue and its own cooldown, such as a
+batch sender on a timer: retrying inside the call only spends more of the
+same limit, and holds the caller's queue while it does. Every other
+failure is retried exactly as before. Defaults to `true`.
+
 <a id="versionedgetoptions"></a>
 
 ## VersionedGetOptions

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v13.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` v13.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.
 
 `@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.
 
@@ -286,7 +286,7 @@ the button could pay right now is [AdsApi.rewardedStatus](#adsapi-rewardedstatus
 
 Absent when your game declares none.
 
-**Guides.** [cross-promotion](../cross-promotion.md)
+**Guides.** [rewarded-ads](../rewarded-ads.md)
 
 <a id="gameconfig-version"></a>
 
@@ -2902,6 +2902,9 @@ type AdFormat = "interstitial" | "rewarded"
 Which kind of break this is.
 
 `interstitial` is a panel the player dismisses and nothing follows from.
+**Deprecated:** signal a platform moment with `gem.moments.signal` instead.
+It keeps working — the arcade treats it as a platform moment — and `14.0.0`
+is the earliest release that may remove it (`docs/deprecation-policy.md`).
 
 `rewarded` is a button the player pressed for a reward, such as a revive or
 an extra attempt, that your game config declares for the placement in
@@ -3021,7 +3024,7 @@ Which of the three answers this is.
 interface AdsApi
 ```
 
-The cross-promotion surface. `gem.ads` is one of these.
+Rewarded ads, and the deprecated interstitial ask. `gem.ads` is one of these.
 
 <a id="adsapi-requestad"></a>
 
@@ -3033,6 +3036,10 @@ requestAd(req: AdRequest): Promise<AdOutcome>
 
 Ask whether the arcade has anything to show at this break in play.
 
+**For a break in play, signal a platform moment with
+`gem.moments.signal` instead: `format: 'interstitial'` is deprecated.** It
+keeps working until at least `14.0.0`. A `rewarded` ask is unchanged.
+
 NOTHING REJECTS, and the answer is usually `no_ad`. Every local refusal —
 an arcade that does not do this at all, a call while another is still in
 flight, a `placement` this module will not send — resolves `no_ad` rather
@@ -3070,16 +3077,6 @@ An `interstitial` needs no press.
 
 **Returns.** The arcade's answer. Always resolves; never rejects.
 
-```ts
-const { outcome } = await gem.ads.requestAd({
-  placement: 'level-complete',
-  format: 'interstitial',
-});
-// `no_ad` is the ordinary answer. There is nothing to show and nothing
-// to draw; carry straight on to the next level.
-startNextLevel();
-```
-
 ```ts
 // A rewarded ask, from the button's own click: the ask comes first, and
 // the inventory read comes after it.
@@ -3142,7 +3139,7 @@ if (status.nextEligibleAt !== undefined) {
 }
 ```
 
-**Guides.** [cross-promotion](../cross-promotion.md)
+**Guides.** [rewarded-ads](../rewarded-ads.md)
 
 <a id="rewardedstatus"></a>
 
@@ -3482,7 +3479,7 @@ is what says which events exist, which dimensions each has and which values
 each dimension may take. An undeclared name or key is not stored — it comes
 back as a rejection, which the SDK prints to the console during development.
 
-⚠️ **Detail older than 30 days is gone.** Raw events live 30 days; the daily
+⚠️ **Detail older than 60 days is gone.** Raw events live 60 days; the daily
 counters live 400. Anything you want to be able to ask about a year from now
 has to be a declared dimension today.
 
@@ -3594,9 +3591,14 @@ the page.
 A refusal that could clear on its own — a 429 from the rate limiter, a 503
 while the platform's idempotency store is unreachable — KEEPS the queue
 and rejects, so the next flush sends the same events rather than losing
-them. A refusal that cannot clear discards the batch it was sent for,
+them. The SDK's own flushes then hold off for the longer of the server's
+`Retry-After` and a cooldown that doubles from 10 seconds, up to five
+minutes. A refusal that cannot clear discards the batch it was sent for,
 because resending it can only fail identically.
 
+One flush at a time: called while another is still on the wire, this
+resolves at once with nothing sent, and what is queued goes out after it.
+
 | Parameter | Type |
 | --- | --- |
 | `options` | `AnalyticsFlushOptions` |
@@ -8951,6 +8953,25 @@ every account on the device shares it, and it can vanish at any time. A
 game must boot correctly from `null`. Progress belongs in `gem.me.saves`;
 a setting that must follow the player belongs in `gem.me.settings`.
 
+<a id="gem-moments"></a>
+
+## Gem.moments
+
+```ts
+readonly moments: MomentsApi
+```
+
+Platform moments — **every game, at every break.** Signal one from the
+player's press that leaves a natural break in play (Next, Retry, Back to
+menu), and the arcade may show one of its own offers over your paused
+game. It usually shows nothing.
+
+Required by the release checklist at every important break, whether or
+not your game has a shop of its own. Never resolves a reason, never
+rejects, and `shown` grants nothing.
+
+**Guides.** [platform-moments](../platform-moments.md)
+
 <a id="gem-ads"></a>
 
 ## Gem.ads
@@ -8959,13 +8980,15 @@ a setting that must follow the player belongs in `gem.me.settings`.
 readonly ads: AdsApi
 ```
 
-One full-screen cross-promotion at a natural break in play, rendered by
-the arcade over your paused game.
+Rewarded ads, and the deprecated interstitial ask.
 
-Ask at a break the player already expects — a level ending, a round
-finishing — never mid-input. **The answer is usually no, and that is
-ordinary rather than a failure:** carry straight on, and draw no
-placeholder while you wait.
+**`format: 'interstitial'` is deprecated: signal a platform moment with
+`gem.moments.signal` instead.** It keeps working until at least `14.0.0`
+(`docs/deprecation-policy.md`); the arcade treats it as a platform moment.
+
+A rewarded ask comes from the player's press on your own button. **The
+answer is usually no, and that is ordinary rather than a failure:** carry
+straight on, and draw no placeholder while you wait.
 
 Nothing here rejects. The arcade pauses your game while a panel is up and
 resumes it when the promise settles, so you do not pause anything yourself.
@@ -8978,7 +9001,7 @@ about the player. What you can read is your own economy:
 `rewardedStatus(placement)` says whether a rewarded placement could pay
 right now under your own declared caps — never whether an ad will play.
 
-**Guides.** [cross-promotion](../cross-promotion.md)
+**Guides.** [rewarded-ads](../rewarded-ads.md)
 
 <a id="gem-account"></a>
 
@@ -11032,6 +11055,152 @@ so portraits appear only against production and loopback.
 | --- | --- |
 | `url` | `string \| undefined` |
 
+<a id="momentkind"></a>
+
+## MomentKind
+
+```ts
+type MomentKind = "level_end" | "run_end" | "match_end" | "menu_return" | "other_break"
+```
+
+Which kind of break a platform moment is. A closed set — there will not be a
+sixth:
+
+- `level_end` — a level, stage, wave or puzzle finished, won or lost.
+- `run_end` — game over, death, or a run banked, in an endless, arcade or
+  roguelike game.
+- `match_end` — a multiplayer round or match finished and the player is
+  leaving its results.
+- `menu_return` — the player chose to go back to the title, a main menu or
+  level select. A return, never the first arrival.
+- `other_break` — any other natural stop: a story chapter, a between-waves
+  shop.
+
+It is a label, for the arcade's analytics, the dev host's log and the release
+checklist. It never changes what the arcade decides for your game.
+
+**Guides.** [platform-moments](../platform-moments.md)
+
+<a id="momentsignal"></a>
+
+## MomentSignal
+
+```ts
+interface MomentSignal
+```
+
+A platform moment: which kind of break the player is leaving, and optionally
+your own name for the screen.
+
+<a id="momentsignal-kind"></a>
+
+## MomentSignal.kind
+
+```ts
+kind: MomentKind
+```
+
+Which kind of break this is. Required.
+
+<a id="momentsignal-placement"></a>
+
+## MomentSignal.placement
+
+```ts
+placement?: string
+```
+
+Optional: your own name for the screen the player is leaving —
+`world-1-3`, `results`. **1 to 32 characters of `a-z`, `0-9`, `-` and
+`_`.** It appears only in the dev host's log, so a reviewer can map each
+moment to a screen. It is never sent to the platform, never stored, never
+shown to a player and never sent to an ad network.
+
+<a id="momentresult"></a>
+
+## MomentResult
+
+```ts
+interface MomentResult
+```
+
+What the arcade answers at a platform moment.
+
+<a id="momentresult-shown"></a>
+
+## MomentResult.shown
+
+```ts
+readonly shown: boolean
+```
+
+Whether the arcade showed anything of its own at this break. Usually
+`false`. Either way, carry on exactly as you would have. **It grants
+nothing**, and it never says what was shown or why nothing was.
+
+<a id="momentsapi"></a>
+
+## MomentsApi
+
+```ts
+interface MomentsApi
+```
+
+Platform moments. `gem.moments` is one of these.
+
+<a id="momentsapi-signal"></a>
+
+## MomentsApi.signal
+
+```ts
+signal(moment: MomentSignal): Promise<MomentResult>
+```
+
+Signal a platform moment: the player is leaving a natural break in play.
+The arcade may show one of its own offers over your paused game, and
+usually shows nothing.
+
+**Call it from the player's press that LEAVES the break** — Next, Retry,
+Back to menu — once per break. Start your own transition in parallel, and
+start play when this settles. **Never** mid-input, during a timed
+sequence, on a timer, on boot or the first arrival at the title, or from a
+player-opened pause menu (choosing Quit to menu from it is a
+`menu_return`). No press is required by the SDK; the rule is about when a
+break really is one.
+
+NOTHING REJECTS. It resolves `{ shown: false }` without asking for an
+arcade that does not do platform moments, a `kind` or `placement` outside
+the grammar, a call before `gem.frame.ready()`, a call while another is in
+flight, a call within 10 seconds of the last answer, or no answer within
+three minutes — and each of those, except an arcade that does not do it
+(said once a session), is reported to your `onError` handler with code
+`'internal'` and a message beginning with a stable token:
+`moments_unsupported`, `moments_invalid_argument`, `moments_before_ready`,
+`moments_in_flight`, `moments_called_repeatedly` or `moments_timeout`.
+
+The arcade pauses and resumes your game through the ordinary
+`gem.pause`, so you do not pause anything yourself.
+
+⚠️ `shown` grants nothing. Never hand out a reward, an unlock or a currency
+on it, and never pop your own offer at a break that settled `shown: true`.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `moment` | `MomentSignal` | Which kind of break, and optionally your name for the screen. |
+
+**Returns.** Whether the arcade showed anything. Always resolves; never rejects.
+
+```ts
+// From the press that LEAVES the break — Next, Retry, Back to menu.
+async function onNextPressed() {
+  startLevelTransition(); // your fade or loading beat, in parallel
+  await gem.moments.signal({ kind: 'level_end', placement: 'world-1-3' });
+  startNextLevel(); // settled either way; never grant anything on `shown`
+}
+```
+
+**Guides.** [platform-moments](../platform-moments.md)
+
 <a id="dedicatedserverfailure"></a>
 
 ## DedicatedServerFailure

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

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v13.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` v13.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.
 
 `@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.
 
@@ -440,6 +440,22 @@ It buys the same budget a read gets — see [ClientOptions.maxRetries](#clientop
 final: only the failures [GemApiError.retryable](#gemapierror-retryable) describes, and a
 connection that died with no answer, are attempted again.
 
+<a id="requestoptions-retryratelimited"></a>
+
+## RequestOptions.retryRateLimited
+
+```ts
+readonly retryRateLimited?: boolean
+```
+
+Set `false` to make a 429 final for this call instead of waiting out
+`Retry-After` and trying again.
+
+For a caller that keeps its own queue and its own cooldown, such as a
+batch sender on a timer: retrying inside the call only spends more of the
+same limit, and holds the caller's queue while it does. Every other
+failure is retried exactly as before. Defaults to `true`.
+
 <a id="versionedgetoptions"></a>
 
 ## VersionedGetOptions
@@ -2523,9 +2539,14 @@ Send what is queued now, and find out what happened to it.
 
 Resolves with the platform's own answer, INCLUDING per-event rejections, which
 arrive inside a 200 rather than as an error. A refusal that could clear on
-its own — a 429, a 503 — keeps the queue and rejects; one that cannot
+its own — a 429, a 503 — keeps the queue and rejects, and the SDK's own
+flushes then hold off for the longer of the server's `Retry-After` and a
+cooldown that doubles from 10 seconds, up to five minutes; one that cannot
 discards the batch, because resending it can only fail the same way.
 
+One flush at a time: called while another is on the wire, this waits for
+it and then sends what is left.
+
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `signal` | `AbortSignal` | Cancels the call — not the queue. |