@indiegems/gem-web-sdk 22.0.0 → 23.0.0

package/dist/sdk.d.ts

@@ -1086,6 +1086,7 @@ declare class CharactersApi {
     private readonly scopes;
     constructor(api: GameApi$1, saves?: SavesOptions | undefined, identity?: (() => string | null) | undefined, resolveCurrencyId?: ((slugOrId: string) => Promise<string | undefined>) | undefined);
     private readonly scope;
+    refreshHeld(): void;
     list(signal?: AbortSignal): Promise<readonly Character[]>;
     get(id: string, signal?: AbortSignal): Promise<Character>;
     create(options: CreateCharacterOptions): Promise<Character>;
@@ -1416,8 +1417,13 @@ declare class FriendChallengeError extends GemApiError {
         readonly configVersion?: number;
     });
 }
+interface PlayInviteRequest {
+    readonly params?: Readonly<Record<string, string>>;
+}
 interface FriendsApiDependencies {
     readonly challenge?: (request: FriendChallengeRequest) => Promise<FriendChallengeOutcome>;
+    readonly inviteToPlay?: (request?: PlayInviteRequest) => Promise<boolean>;
+    readonly setInviteParams?: (params: Readonly<Record<string, string>> | null) => boolean;
     readonly launchedChallengeId?: string;
 }
 declare class FriendsApi {
@@ -1425,6 +1431,8 @@ declare class FriendsApi {
     constructor(api: GameApi$1, dependencies?: FriendsApiDependencies);
     list(options?: ListFriendsOptions): Promise<FriendsPage>;
     challenge(request: FriendChallengeRequest): Promise<FriendChallengeOutcome>;
+    inviteToPlay(request?: PlayInviteRequest): Promise<boolean>;
+    setInviteParams(params: Readonly<Record<string, string>> | null): boolean;
     inbox(options?: ListFriendChallengesOptions): Promise<FriendChallengesPage>;
     launchedChallenge(options?: {
         readonly signal?: AbortSignal;
@@ -2208,6 +2216,10 @@ interface GemCohorts$1 {
         variantKey: string;
     }[];
 }
+interface GemInventoryChanged {
+    readonly gem: typeof PROTOCOL;
+    readonly type: "gem.inventoryChanged";
+}
 interface GemViewport$1 {
     readonly gem: typeof PROTOCOL;
     readonly type: "gem.viewport";
@@ -2445,6 +2457,29 @@ interface GemFriendChallengeResult {
     readonly retryAfterMs?: number;
     readonly detail?: string;
 }
+interface GemRequestPlayInvite {
+    readonly gem: typeof PROTOCOL;
+    readonly type: "gem.requestPlayInvite";
+    readonly requestId: string;
+    readonly params?: {
+        key: string;
+        value: string;
+    }[];
+}
+interface GemPlayInviteResult {
+    readonly gem: typeof PROTOCOL;
+    readonly type: "gem.playInviteResult";
+    readonly requestId: string;
+    readonly shown: boolean;
+}
+interface GemInviteParams {
+    readonly gem: typeof PROTOCOL;
+    readonly type: "gem.inviteParams";
+    readonly params?: {
+        key: string;
+        value: string;
+    }[];
+}
 interface GemRequestAppLinks {
     readonly gem: typeof PROTOCOL;
     readonly type: "gem.requestAppLinks";
@@ -4809,6 +4844,7 @@ interface FramePlayer extends PlayerIdentity {
     readonly boost: PlayerBoost;
 }
 type GemArcadeAsk = Omit<GemRequestAppLinks, "gem"> | Omit<GemRequestOpenApp, "gem"> | Omit<GemRequestOpenGame, "gem"> | Omit<GemRequestSimilarGames, "gem"> | Omit<GemRequestStoreOffers, "gem"> | Omit<GemRequestStorePurchase, "gem"> | Omit<GemRequestStoreOfferSheet, "gem">;
+type GemFriendsWindowAsk = Omit<GemRequestPlayInvite, "gem"> | Omit<GemInviteParams, "gem">;
 type GemArcadeAnswer = GemAppLinksResult | GemOpenAppResult | GemOpenGameResult | GemSimilarGamesResult | GemStoreOffersResult | GemStorePurchaseResult | GemStorePurchaseSettled | GemStoreOfferSheetResult;
 interface FrameCallbacks {
     onToken?(msg: GemToken): void;
@@ -4818,6 +4854,7 @@ interface FrameCallbacks {
     onPrefs?(msg: GemPrefs$1): void;
     onCohorts?(msg: GemCohorts$1): void;
     onEarnAllowanceChanged?(): void;
+    onInventoryChanged?(msg: GemInventoryChanged): void;
     onViewport?(msg: GemViewport$1): void;
     onWillTerminate?(msg: GemWillTerminate): void;
     onDevtools?(action: "open" | "close" | "toggle"): void;
@@ -4851,6 +4888,7 @@ interface FrameCallbacks {
     onSignInResult?(msg: GemSignInResult): void;
     onFriendChallengeResult?(msg: GemFriendChallengeResult): void;
     onArcadeAnswer?(msg: GemArcadeAnswer): void;
+    onPlayInviteResult?(msg: GemPlayInviteResult): void;
     onError?(code: GemErrorCode, message?: string): void;
     onDropped?(code: GemErrorCode, message?: string): void;
     onStateChange?(state: FrameState): void;
@@ -4931,7 +4969,7 @@ declare class GemFrame {
     readyCalled(): boolean;
     requestSignIn(requestId: string): boolean;
     requestFriendChallenge(requestId: string, playerId: string, template: string, params?: Readonly<Record<string, string | number>>): boolean;
-    requestArcade(msg: GemArcadeAsk): boolean;
+    requestArcade(msg: GemArcadeAsk | GemFriendsWindowAsk): boolean;
     close(): void;
     private transition;
     private refuseMalformed;
@@ -5392,4 +5430,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, type AppLinksOutcome, type AppListing, type AppStore, type ArcadeApi, type ArcadeAvailability, type ArcadeOffer, type ArcadeOutcome, type ArcadeOutcomeKind, 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 BrandingApi, type BrandingAsset, type BrandingAssetOptions, type BrandingCurrency, type BrandingImageOptions, type BrandingList, type BrandingLookup, type BrandingTheme, type BrandingVariant, 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 GameCard, type GameConfig, type GameMenu, type GameMenuItem, type GamePass, type GameServerLink, type GameSettingsApi, type Gem, GemApiError, type GemAudioChannels, GemClient, type GemCohort, type GemCohorts, GemConfigError, type GemControlBox, type GemCorner, type GemDevTools, type GemErrorReason, GemFrame, GemFunctionError, type GemGameChoiceSetting, type GemGameSetting, type GemGameSettingBase, type GemGameSettingChange, type GemGameSettingIcon, type GemGameSettingOption, type GemGameSettingValue, type GemGameSliderSetting, type GemGameToggleSetting, type GemGraphicsQuality, type GemGraphicsRoute, type GemGraphicsRouteEntry, 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 GemPreferredRoute, 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 GraphicsApi, 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 MenuStyle, type MessageMeta, type MomentKind, type MomentResult, type MomentSignal, type MomentsApi, type MultiTransportSession, PLATFORM_EVENTS, type PassesApi, type PassesEvent, 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, type PlayerScope, PlayerText, type PreferredRouteOptions, type ProfileCallOptions, type ProfileShowcaseEntry$1 as ProfileShowcaseEntry, ProfilesApi, type PurchaseApi, type PurchaseOptions, type PurchaseOutcome, PurchaseRefusal, type PurchaseRefusalCode, type PurchaseRequest, type PurchaseSettlement, type PutBytesOptions, type PutSaveOptions, type RankedRow, type RecipeAvailability, type RecipeLock, type RequestOptions, type RewardCue, type RewardPresentation, type RewardedStatus, type RoomArgValue, type SavePage, type SaveRecord, type SendOptions$1 as SendOptions, type ServerApi, type ServerBundleHost, type ServerTokenGrant, type SessionEndReason, type ShareApi, ShareRefusal, type ShareRequest, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SignInOutcome, type SignInOutcomeKind, type SimilarGamesOutcome, type SnapshotCurrency, type SnapshotItem, type StoreApi, type StoreOffersOutcome, type StoreSettlement, 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, experimentSelection, 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, type AppLinksOutcome, type AppListing, type AppStore, type ArcadeApi, type ArcadeAvailability, type ArcadeOffer, type ArcadeOutcome, type ArcadeOutcomeKind, 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 BrandingApi, type BrandingAsset, type BrandingAssetOptions, type BrandingCurrency, type BrandingImageOptions, type BrandingList, type BrandingLookup, type BrandingTheme, type BrandingVariant, 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 GameCard, type GameConfig, type GameMenu, type GameMenuItem, type GamePass, type GameServerLink, type GameSettingsApi, type Gem, GemApiError, type GemAudioChannels, GemClient, type GemCohort, type GemCohorts, GemConfigError, type GemControlBox, type GemCorner, type GemDevTools, type GemErrorReason, GemFrame, GemFunctionError, type GemGameChoiceSetting, type GemGameSetting, type GemGameSettingBase, type GemGameSettingChange, type GemGameSettingIcon, type GemGameSettingOption, type GemGameSettingValue, type GemGameSliderSetting, type GemGameToggleSetting, type GemGraphicsQuality, type GemGraphicsRoute, type GemGraphicsRouteEntry, 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 GemPreferredRoute, 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 GraphicsApi, 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 MenuStyle, type MessageMeta, type MomentKind, type MomentResult, type MomentSignal, type MomentsApi, type MultiTransportSession, PLATFORM_EVENTS, type PassesApi, type PassesEvent, type PeriodOptions, PlatformApi, PlatformCurrenciesApi, type PlatformCurrency, type PlatformCurrencyAccess, type PlatformCurrencyPurchasePayment, type PlatformCurrencyPurchaseRequest, type PlatformCurrencyPurchaseResult, type PlatformCurrencyReadOptions, PlatformEarnAllowanceApi, type PlatformEventName, type PlayInviteRequest, type PlayerBadge$1 as PlayerBadge, type PlayerBoost, type PlayerBoostMultiplier, type PlayerIdentity, type PlayerProfile, type PlayerScope, PlayerText, type PreferredRouteOptions, type ProfileCallOptions, type ProfileShowcaseEntry$1 as ProfileShowcaseEntry, ProfilesApi, type PurchaseApi, type PurchaseOptions, type PurchaseOutcome, PurchaseRefusal, type PurchaseRefusalCode, type PurchaseRequest, type PurchaseSettlement, type PutBytesOptions, type PutSaveOptions, type RankedRow, type RecipeAvailability, type RecipeLock, type RequestOptions, type RewardCue, type RewardPresentation, type RewardedStatus, type RoomArgValue, type SavePage, type SaveRecord, type SendOptions$1 as SendOptions, type ServerApi, type ServerBundleHost, type ServerTokenGrant, type SessionEndReason, type ShareApi, ShareRefusal, type ShareRequest, ShowcaseApi, type ShowcaseCallOptions, type ShowcaseFriendEntry, type ShowcaseFriends, type ShowcaseValue, type SignInOutcome, type SignInOutcomeKind, type SimilarGamesOutcome, type SnapshotCurrency, type SnapshotItem, type StoreApi, type StoreOffersOutcome, type StoreSettlement, 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, experimentSelection, leaveAndExit, mapIdentity, markOnResolve, platformIconUrl, presentJoinCredential, readTemplateTransports, readTransportAdvert, reportOnResolve, systemClock, text, toBase64, webTransportAvailable };

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

@@ -1,6 +1,6 @@
 # The function surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/function` v22.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.
+Generated from `@indiegems/gem-web-sdk/function` v23.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.
 
@@ -2039,8 +2039,9 @@ Throw away what is cached, so the next [InventoryApi.snapshot](#inventoryapi-sna
 asks.
 
 For when something you did not do changed the inventory — a purchase on
-another device, a grant from a server. The SDK already drops the cache
-itself after any change it made.
+another device, a grant from a server — and nothing told you. The SDK
+already drops the cache itself after any change it made, and on an
+Arcade's hint that this game's inventory changed on the server.
 
 <a id="inventoryapi-onchanged"></a>
 
@@ -2053,12 +2054,17 @@ onChanged(listener: () => void): () => void
 Run something whenever this inventory changes, and get back a function that
 stops listening.
 
-⚠️ LOCAL CHANGES ONLY — this fires for changes THIS game made through this
-SDK. It does NOT fire when an inventory changes anywhere else: another
-device, a game server, an admin tool, or a gift from another player. Do not
-build "keep the bag live" on it; use it to react to your own writes, and
-call [InventoryApi.refresh](#inventoryapi-refresh) when you have reason to think something
-else moved.
+Fires for every change THIS game made through this SDK, and — on an Arcade
+that relays it — for any change to this game's inventory on the server: a
+grant from your function or server, a purchase, a gift accepted, a support
+grant, another device. It is a cue to re-read, not a receipt: it carries
+nothing, so call [InventoryApi.snapshot](#inventoryapi-snapshot) for what changed. After your
+own function's grant, show the function's answer and let this redraw.
+
+An older Arcade sends no hint, and there it fires for your own writes
+only. Keep a fallback that does not depend on it: refresh on
+`visibilitychange` to `visible` and after any action that could involve
+another player. Do not poll.
 
 | Parameter | Type |
 | --- | --- |
@@ -5030,6 +5036,31 @@ readonly configVersion?: number
 On `template_not_on_channel`, when a config version is promoted to that
 channel: the version the template is missing from.
 
+<a id="playinviterequest"></a>
+
+## PlayInviteRequest
+
+```ts
+interface PlayInviteRequest
+```
+
+What `gem.friends.inviteToPlay` takes.
+
+<a id="playinviterequest-params"></a>
+
+## PlayInviteRequest.params
+
+```ts
+readonly params?: Readonly<Record<string, string>>
+```
+
+Your own launch parameters for what the Arcade's link and invites open —
+`{ room: joinCode }` for a room joined by code — exactly as they should
+reach your game, on `gem.share.request`'s rules: at most 16, keys a letter
+then up to 63 letters, digits, `_` or `-`, string values of at most 512
+characters. For this one opening, they replace what
+`gem.friends.setInviteParams` declared. Omit it to use that declaration.
+
 <a id="friendsapi"></a>
 
 ## FriendsApi
@@ -5144,6 +5175,95 @@ challengeButton.onclick = async () => {
 };
 ```
 
+<a id="friendsapi-invitetoplay"></a>
+
+## FriendsApi.inviteToPlay
+
+```ts
+inviteToPlay(request?: PlayInviteRequest): Promise<boolean>
+```
+
+Ask the Arcade to open ITS invite sheet, so the player can invite friends
+to come and play this game with them.
+
+The Arcade lists the player's friends in its own chrome and sends an
+invite only when the player presses Invite there. A friend who accepts is
+opened into this game by the Arcade, and their quick-join seats them in
+the player's room when there is a seat: your game makes no call for it,
+and reads them as a room member who shares the player's `groupId`. Your
+game names nobody and writes no text.
+
+An Arcade that does not offer the sheet answers `false` at once, and asks
+nothing. Hide the button on `gem.frame.parentSupports('playInvites')`
+rather than letting a player press one that cannot work.
+
+⚠️ **Call it ONLY from a player's press**, never on a timer or as a screen
+opens. The Arcade answers an ask with no press behind it `false`, and
+shows nothing.
+
+RESOLVES `true` when the Arcade opened its sheet, and `false` when it did
+not: outside the Arcade, without `playInvites`, with another sheet
+already open, without a press, or when no answer arrived. **That is all it
+says** — never whom the player invited, how many, or whether any invite
+was sent — so never gate a reward on it. Never rejects.
+
+Calls made while an ask is open share its answer.
+
+**The window's share link and its invites are one system.** Pass
+`params` — your own launch parameters, `{ room: joinCode }` for a room
+joined by code — and a friend who accepts and anyone who opens the link
+arrive with them, on `gem.share.request`'s rules. Omitted, the window uses
+what [FriendsApi.setInviteParams](#friendsapi-setinviteparams) declared. A param those rules
+refuse is said on the console and nothing is asked: the call resolves
+`false`.
+
+| Parameter | Type |
+| --- | --- |
+| `request` | `PlayInviteRequest` |
+
+```ts
+inviteButton.onclick = async () => {
+  const shown = await gem.friends.inviteToPlay({ params: { room: joinCode } });
+  if (!shown) showJoinCode(); // the Arcade's sheet did not open: your own fallback
+};
+```
+
+<a id="friendsapi-setinviteparams"></a>
+
+## FriendsApi.setInviteParams
+
+```ts
+setInviteParams(params: Readonly<Record<string, string>> | null): boolean
+```
+
+Say what the Arcade's Friends window opens when the PLAYER opens it from
+the Arcade's own menu over your game: your launch parameters, carried by
+its share link and its friend invites alike, on `gem.share.request`'s
+rules. Pass `null` to clear.
+
+Call it when the player enters a room joined by code —
+`setInviteParams({ room: joinCode })` — and `setInviteParams(null)` when
+they leave it, so the window never invites anyone into a room that is
+gone. The latest call stands until the next; the SDK holds it and says it
+again after a reconnect. An explicit `inviteToPlay({ params })` wins for
+that one opening. Nothing comes back, and nothing changes on screen.
+
+| Parameter | Type |
+| --- | --- |
+| `params` | `Readonly<Record<string, string>> \| null` |
+
+**Returns.** whether the declaration reached the Arcade now. `false` outside
+  the Arcade, without `playInvites`, before the bridge is up (it is sent on
+  connect) and for params the share rules refuse, which are said on the
+  console; the last declaration then stands.
+
+```ts
+// On entering a room joined by code:
+gem.friends.setInviteParams({ room: joinCode });
+// ...and on leaving it:
+gem.friends.setInviteParams(null);
+```
+
 <a id="friendsapi-inbox"></a>
 
 ## FriendsApi.inbox

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v22.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.
+Generated from `@indiegems/gem-web-sdk/sdk` v23.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.
 
@@ -907,8 +907,9 @@ Throw away what is cached, so the next [InventoryApi.snapshot](#inventoryapi-sna
 asks.
 
 For when something you did not do changed the inventory — a purchase on
-another device, a grant from a server. The SDK already drops the cache
-itself after any change it made.
+another device, a grant from a server — and nothing told you. The SDK
+already drops the cache itself after any change it made, and on an
+Arcade's hint that this game's inventory changed on the server.
 
 <a id="inventoryapi-onchanged"></a>
 
@@ -921,12 +922,17 @@ onChanged(listener: () => void): () => void
 Run something whenever this inventory changes, and get back a function that
 stops listening.
 
-⚠️ LOCAL CHANGES ONLY — this fires for changes THIS game made through this
-SDK. It does NOT fire when an inventory changes anywhere else: another
-device, a game server, an admin tool, or a gift from another player. Do not
-build "keep the bag live" on it; use it to react to your own writes, and
-call [InventoryApi.refresh](#inventoryapi-refresh) when you have reason to think something
-else moved.
+Fires for every change THIS game made through this SDK, and — on an Arcade
+that relays it — for any change to this game's inventory on the server: a
+grant from your function or server, a purchase, a gift accepted, a support
+grant, another device. It is a cue to re-read, not a receipt: it carries
+nothing, so call [InventoryApi.snapshot](#inventoryapi-snapshot) for what changed. After your
+own function's grant, show the function's answer and let this redraw.
+
+An older Arcade sends no hint, and there it fires for your own writes
+only. Keep a fallback that does not depend on it: refresh on
+`visibilitychange` to `visible` and after any action that could involve
+another player. Do not poll.
 
 | Parameter | Type |
 | --- | --- |
@@ -8528,6 +8534,31 @@ readonly configVersion?: number
 On `template_not_on_channel`, when a config version is promoted to that
 channel: the version the template is missing from.
 
+<a id="playinviterequest"></a>
+
+## PlayInviteRequest
+
+```ts
+interface PlayInviteRequest
+```
+
+What `gem.friends.inviteToPlay` takes.
+
+<a id="playinviterequest-params"></a>
+
+## PlayInviteRequest.params
+
+```ts
+readonly params?: Readonly<Record<string, string>>
+```
+
+Your own launch parameters for what the Arcade's link and invites open —
+`{ room: joinCode }` for a room joined by code — exactly as they should
+reach your game, on `gem.share.request`'s rules: at most 16, keys a letter
+then up to 63 letters, digits, `_` or `-`, string values of at most 512
+characters. For this one opening, they replace what
+`gem.friends.setInviteParams` declared. Omit it to use that declaration.
+
 <a id="friendsapi"></a>
 
 ## FriendsApi
@@ -8642,6 +8673,95 @@ challengeButton.onclick = async () => {
 };
 ```
 
+<a id="friendsapi-invitetoplay"></a>
+
+## FriendsApi.inviteToPlay
+
+```ts
+inviteToPlay(request?: PlayInviteRequest): Promise<boolean>
+```
+
+Ask the Arcade to open ITS invite sheet, so the player can invite friends
+to come and play this game with them.
+
+The Arcade lists the player's friends in its own chrome and sends an
+invite only when the player presses Invite there. A friend who accepts is
+opened into this game by the Arcade, and their quick-join seats them in
+the player's room when there is a seat: your game makes no call for it,
+and reads them as a room member who shares the player's `groupId`. Your
+game names nobody and writes no text.
+
+An Arcade that does not offer the sheet answers `false` at once, and asks
+nothing. Hide the button on `gem.frame.parentSupports('playInvites')`
+rather than letting a player press one that cannot work.
+
+⚠️ **Call it ONLY from a player's press**, never on a timer or as a screen
+opens. The Arcade answers an ask with no press behind it `false`, and
+shows nothing.
+
+RESOLVES `true` when the Arcade opened its sheet, and `false` when it did
+not: outside the Arcade, without `playInvites`, with another sheet
+already open, without a press, or when no answer arrived. **That is all it
+says** — never whom the player invited, how many, or whether any invite
+was sent — so never gate a reward on it. Never rejects.
+
+Calls made while an ask is open share its answer.
+
+**The window's share link and its invites are one system.** Pass
+`params` — your own launch parameters, `{ room: joinCode }` for a room
+joined by code — and a friend who accepts and anyone who opens the link
+arrive with them, on `gem.share.request`'s rules. Omitted, the window uses
+what [FriendsApi.setInviteParams](#friendsapi-setinviteparams) declared. A param those rules
+refuse is said on the console and nothing is asked: the call resolves
+`false`.
+
+| Parameter | Type |
+| --- | --- |
+| `request` | `PlayInviteRequest` |
+
+```ts
+inviteButton.onclick = async () => {
+  const shown = await gem.friends.inviteToPlay({ params: { room: joinCode } });
+  if (!shown) showJoinCode(); // the Arcade's sheet did not open: your own fallback
+};
+```
+
+<a id="friendsapi-setinviteparams"></a>
+
+## FriendsApi.setInviteParams
+
+```ts
+setInviteParams(params: Readonly<Record<string, string>> | null): boolean
+```
+
+Say what the Arcade's Friends window opens when the PLAYER opens it from
+the Arcade's own menu over your game: your launch parameters, carried by
+its share link and its friend invites alike, on `gem.share.request`'s
+rules. Pass `null` to clear.
+
+Call it when the player enters a room joined by code —
+`setInviteParams({ room: joinCode })` — and `setInviteParams(null)` when
+they leave it, so the window never invites anyone into a room that is
+gone. The latest call stands until the next; the SDK holds it and says it
+again after a reconnect. An explicit `inviteToPlay({ params })` wins for
+that one opening. Nothing comes back, and nothing changes on screen.
+
+| Parameter | Type |
+| --- | --- |
+| `params` | `Readonly<Record<string, string>> \| null` |
+
+**Returns.** whether the declaration reached the Arcade now. `false` outside
+  the Arcade, without `playInvites`, before the bridge is up (it is sent on
+  connect) and for params the share rules refuse, which are said on the
+  console; the last declaration then stands.
+
+```ts
+// On entering a room joined by code:
+gem.friends.setInviteParams({ room: joinCode });
+// ...and on leaving it:
+gem.friends.setInviteParams(null);
+```
+
 <a id="friendsapi-inbox"></a>
 
 ## FriendsApi.inbox
@@ -9075,6 +9195,12 @@ The call is made once. It is never repeated for you, because your function
 may have granted or written something: see [GemFunctionError.retryable](#gemfunctionerror-retryable)
 for whether repeating it could help.
 
+The answer is the receipt: when this resolves, what your function says it
+granted has been written. A game shows it at once and re-reads the
+inventory in the background (`gem.me.inventory.refresh()`, then
+`snapshot()`, or on `gem.me.inventory.onChanged`); never hold the player on
+a loop that re-reads until the grant shows.
+
 ```js
 const result = await gem.functions.invoke({ v: 2, runId, finishMs });
 const { accepted, why } = result.json();
@@ -12015,10 +12141,12 @@ readonly friends: FriendsApi
 ```
 
 The signed-in player's accepted friends — display identity only,
-read-only, paginated — and the one ask that reaches past them:
+read-only, paginated — and the asks that reach past them:
 [FriendsApi.challenge](#friendsapi-challenge), which asks the Arcade to send a friend a
-challenge after the player confirms it in the Arcade's own sheet. The
-receiving side reads the challenges this player holds in this game:
+challenge after the player confirms it in the Arcade's own sheet, and
+[FriendsApi.inviteToPlay](#friendsapi-invitetoplay), which asks the Arcade to open its own
+invite-to-play sheet. The receiving side reads the challenges this player
+holds in this game:
 [FriendsApi.launchedChallenge](#friendsapi-launchedchallenge) for the one this frame was launched
 with, [FriendsApi.inbox](#friendsapi-inbox) for all of them, and
 [FriendsApi.markAnswered](#friendsapi-markanswered) once one has been played.
@@ -20102,7 +20230,7 @@ readonly playWith: PlayWithOutcome | null
 
 What the last [RoomManager.quickJoin](#roommanager-quickjoin) did when the Arcade opened
 your game to play with someone — a friend whose Join the player pressed,
-or their party's leader. Read-only.
+a friend's invite, or their party's leader. Read-only.
 
 - `'joined'` — the player was seated in that person's room, as a member
   sharing their `groupId`.

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

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v22.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.
+Generated from `@indiegems/gem-web-sdk/sdk` v23.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.
 
@@ -1785,6 +1785,12 @@ The call is made once. It is never repeated for you, because your function
 may have granted or written something: see [GemFunctionError.retryable](#gemfunctionerror-retryable)
 for whether repeating it could help.
 
+The answer is the receipt: when this resolves, what your function says it
+granted has been written. A game shows it at once and re-reads the
+inventory in the background (`gem.me.inventory.refresh()`, then
+`snapshot()`, or on `gem.me.inventory.onChanged`); never hold the player on
+a loop that re-reads until the grant shows.
+
 ```js
 const result = await gem.functions.invoke({ v: 2, runId, finishMs });
 const { accepted, why } = result.json();