@indiegems/gem-web-sdk 15.3.2 → 16.0.0

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

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v15.3.2, 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` v16.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.
 
@@ -3787,6 +3787,725 @@ key.
 **Throws.** TypeError for an empty key or player id, or a list holding something
   other than strings; RangeError for a count or list size outside 1 to 2048.
 
+<a id="appstore"></a>
+
+## AppStore
+
+```ts
+type AppStore = "app_store" | "google_play"
+```
+
+Which app store a listing is in, so a game can draw the matching badge.
+
+<a id="applisting"></a>
+
+## AppListing
+
+```ts
+interface AppListing
+```
+
+A store listing the arcade can open from here.
+
+<a id="applisting-store"></a>
+
+## AppListing.store
+
+```ts
+readonly store: AppStore
+```
+
+Which store it is in. Never a URL: the arcade builds the link.
+
+<a id="applinksoutcome"></a>
+
+## AppLinksOutcome
+
+```ts
+interface AppLinksOutcome
+```
+
+What [ArcadeApi.appLinks](#arcadeapi-applinks) resolves with. `arcade` and `game` are each
+present only when [ArcadeApi.openApp](#arcadeapi-openapp) with that target would open a
+listing here; show the matching button only then.
+
+<a id="applinksoutcome-arcade"></a>
+
+## AppLinksOutcome.arcade
+
+```ts
+readonly arcade?: AppListing
+```
+
+The Gem Arcade app's listing. Absent inside the Gem Arcade app itself.
+
+<a id="applinksoutcome-game"></a>
+
+## AppLinksOutcome.game
+
+```ts
+readonly game?: AppListing
+```
+
+This game's own app's listing, when it has one for this platform.
+
+<a id="applinksoutcome-outcome"></a>
+
+## AppLinksOutcome.outcome
+
+```ts
+readonly outcome: ArcadeOutcomeKind
+```
+
+What happened: `ok`, `declined` or `unavailable`. Branch on this.
+
+<a id="applinksoutcome-reason"></a>
+
+## AppLinksOutcome.reason
+
+```ts
+readonly reason?: string
+```
+
+Why, as a machine code — `busy`, `cancelled`, `not_found`, `pending`,
+`store_off`, `sign_in_required` and more. OPEN-ENDED: the arcade may send a
+code this SDK has never heard of, so keep a `default` arm and never show a
+code to a player. Absent when there is nothing to add.
+
+Three are the SDK's own, answered without asking the arcade:
+`unsupported` (the arcade here does not offer this), `invalid_argument`
+(the SDK refused what you passed) and `busy` (another ask of the same kind
+is still open). `error` means no reliable answer arrived — the ask never
+left, the wait ran out, the bridge closed or the arcade had none. For
+`gem.store.purchase` that makes the outcome UNKNOWN, not a refusal: the
+player may have paid.
+
+<a id="gamecard"></a>
+
+## GameCard
+
+```ts
+interface GameCard
+```
+
+One game, as an Arcade home tile shows it.
+
+⚠️ `name`, `tagline`, `shortDescription` and `tags` are **another
+developer's text**, so they arrive as [PlayerText](#playertext): convert with
+`text.toPlain()` and render them as text, never as markup. The media URLs are
+the platform's; your page's CSP must allow its media host for `img-src` and
+`media-src` (see `docs/arcade-and-store.md`).
+
+<a id="gamecard-gameid"></a>
+
+## GameCard.gameId
+
+```ts
+readonly gameId: string
+```
+
+The game's id: what [ArcadeApi.openGame](#arcadeapi-opengame) takes.
+
+<a id="gamecard-slug"></a>
+
+## GameCard.slug
+
+```ts
+readonly slug?: string
+```
+
+The game's web address, when it has one.
+
+<a id="gamecard-name"></a>
+
+## GameCard.name
+
+```ts
+readonly name: PlayerText
+```
+
+The game's public name. Another developer's text.
+
+<a id="gamecard-tagline"></a>
+
+## GameCard.tagline
+
+```ts
+readonly tagline: PlayerText
+```
+
+One line under the name. Another developer's text; may be empty.
+
+<a id="gamecard-shortdescription"></a>
+
+## GameCard.shortDescription
+
+```ts
+readonly shortDescription: PlayerText
+```
+
+A sentence or two. Another developer's text; may be empty.
+
+<a id="gamecard-tags"></a>
+
+## GameCard.tags
+
+```ts
+readonly tags: readonly PlayerText[]
+```
+
+The game's store tags. Another developer's text.
+
+<a id="gamecard-iconurl"></a>
+
+## GameCard.iconUrl
+
+```ts
+readonly iconUrl: string
+```
+
+The game's icon.
+
+<a id="gamecard-capsulelandscapeurl"></a>
+
+## GameCard.capsuleLandscapeUrl
+
+```ts
+readonly capsuleLandscapeUrl: string
+```
+
+The landscape tile art.
+
+<a id="gamecard-capsuleportraiturl"></a>
+
+## GameCard.capsulePortraitUrl
+
+```ts
+readonly capsulePortraitUrl: string
+```
+
+The portrait tile art.
+
+<a id="gamecard-previewvideourl"></a>
+
+## GameCard.previewVideoUrl
+
+```ts
+readonly previewVideoUrl?: string
+```
+
+The tile's hover clip. Absent when the game has none, and whenever the
+arcade judges a clip unwelcome: reduced motion, data saver, a phone.
+
+<a id="gamecard-previewposterurl"></a>
+
+## GameCard.previewPosterUrl
+
+```ts
+readonly previewPosterUrl?: string
+```
+
+The still shown before, and instead of, the clip.
+
+<a id="similargamesoutcome"></a>
+
+## SimilarGamesOutcome
+
+```ts
+interface SimilarGamesOutcome
+```
+
+What [ArcadeApi.similarGames](#arcadeapi-similargames) resolves with.
+
+<a id="similargamesoutcome-games"></a>
+
+## SimilarGamesOutcome.games
+
+```ts
+readonly games: readonly GameCard[]
+```
+
+Up to `limit` games, best first. Empty unless `ok` — and an `ok` may be empty too.
+
+<a id="similargamesoutcome-outcome"></a>
+
+## SimilarGamesOutcome.outcome
+
+```ts
+readonly outcome: ArcadeOutcomeKind
+```
+
+What happened: `ok`, `declined` or `unavailable`. Branch on this.
+
+<a id="similargamesoutcome-reason"></a>
+
+## SimilarGamesOutcome.reason
+
+```ts
+readonly reason?: string
+```
+
+Why, as a machine code — `busy`, `cancelled`, `not_found`, `pending`,
+`store_off`, `sign_in_required` and more. OPEN-ENDED: the arcade may send a
+code this SDK has never heard of, so keep a `default` arm and never show a
+code to a player. Absent when there is nothing to add.
+
+Three are the SDK's own, answered without asking the arcade:
+`unsupported` (the arcade here does not offer this), `invalid_argument`
+(the SDK refused what you passed) and `busy` (another ask of the same kind
+is still open). `error` means no reliable answer arrived — the ask never
+left, the wait ran out, the bridge closed or the arcade had none. For
+`gem.store.purchase` that makes the outcome UNKNOWN, not a refusal: the
+player may have paid.
+
+<a id="arcadeavailability"></a>
+
+## ArcadeAvailability
+
+```ts
+interface ArcadeAvailability
+```
+
+Which arcade features answer here, read synchronously. Decide from these
+whether to draw a "Get the app" button or a "More games" section at all.
+
+<a id="arcadeavailability-applinks"></a>
+
+## ArcadeAvailability.appLinks
+
+```ts
+readonly appLinks: boolean
+```
+
+[ArcadeApi.appLinks](#arcadeapi-applinks) and [ArcadeApi.openApp](#arcadeapi-openapp) reach the arcade.
+
+<a id="arcadeavailability-opengame"></a>
+
+## ArcadeAvailability.openGame
+
+```ts
+readonly openGame: boolean
+```
+
+[ArcadeApi.openGame](#arcadeapi-opengame) and [ArcadeApi.similarGames](#arcadeapi-similargames) reach the arcade.
+
+<a id="arcadeapi"></a>
+
+## ArcadeApi
+
+```ts
+interface ArcadeApi
+```
+
+The arcade-features surface. `gem.arcade` is one of these.
+
+<a id="arcadeapi-available"></a>
+
+## ArcadeApi.available
+
+```ts
+readonly available: ArcadeAvailability
+```
+
+Which of these features the arcade answers here, synchronously. False
+before the bridge is up and wherever the arcade does not offer one — the
+single-game app, for instance, opens no other game.
+
+<a id="arcadeapi-applinks"></a>
+
+## ArcadeApi.appLinks
+
+```ts
+appLinks(): Promise<AppLinksOutcome>
+```
+
+Which app-store listings the arcade can open from here: the Gem Arcade
+app's and this game's own. A read: call it whenever, and show a button
+for each listing present.
+
+**Returns.** Always resolves; never rejects.
+
+<a id="arcadeapi-openapp"></a>
+
+## ArcadeApi.openApp
+
+```ts
+openApp(target: "arcade" | "game"): Promise<ArcadeOutcome>
+```
+
+Open a store listing: the Gem Arcade app's (`'arcade'`) or this game's own
+(`'game'`). **Call it from the player's press handler** — the arcade
+refuses an ask no person pressed for, `declined` / `busy`.
+
+`ok` means it opened, in a new tab or the store app, or (`reason:
+'handed_off'`) the arcade put up its own QR sheet. The answer comes at
+that moment, not when the player closes the sheet, so carry on either
+way; while the sheet is up, another acting call is `declined` / `busy`.
+
+| Parameter | Type |
+| --- | --- |
+| `target` | `"arcade" \| "game"` |
+
+**Returns.** Always resolves; never rejects.
+
+<a id="arcadeapi-opengame"></a>
+
+## ArcadeApi.openGame
+
+```ts
+openGame(ref: string): Promise<ArcadeOutcome>
+```
+
+Open another game in place of this one, by id or web address. **Call it
+from the player's press handler.**
+
+⚠️ On `ok` your game is about to be closed: `onWillTerminate` follows with
+the ordinary save grace (250 ms). Save before you call this, not after.
+`declined` / `same_game` names this game; `unavailable` / `not_found` is a
+game the player cannot open here.
+
+| Parameter | Type |
+| --- | --- |
+| `ref` | `string` |
+
+**Returns.** Always resolves; never rejects.
+
+<a id="arcadeapi-similargames"></a>
+
+## ArcadeApi.similarGames
+
+```ts
+similarGames(options?: { limit?: number }): Promise<SimilarGamesOutcome>
+```
+
+Games like this one, as Arcade home tiles: up to `limit` (1 to 24, default
+12), best first. Hide the section when `games` is empty.
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `{ limit?: number }` |
+
+**Returns.** Always resolves; never rejects.
+
+<a id="arcadeoutcomekind"></a>
+
+## ArcadeOutcomeKind
+
+```ts
+type ArcadeOutcomeKind = "ok" | "declined" | "unavailable"
+```
+
+What the arcade did with an ask, the complete vocabulary: `ok`, `declined`
+or `unavailable`. Why is in `reason`, which is open-ended.
+
+<a id="arcadeoutcome"></a>
+
+## ArcadeOutcome
+
+```ts
+interface ArcadeOutcome
+```
+
+The answer every `gem.arcade` and `gem.store` call resolves with, before
+anything specific to the call.
+
+<a id="arcadeoutcome-outcome"></a>
+
+## ArcadeOutcome.outcome
+
+```ts
+readonly outcome: ArcadeOutcomeKind
+```
+
+What happened: `ok`, `declined` or `unavailable`. Branch on this.
+
+<a id="arcadeoutcome-reason"></a>
+
+## ArcadeOutcome.reason
+
+```ts
+readonly reason?: string
+```
+
+Why, as a machine code — `busy`, `cancelled`, `not_found`, `pending`,
+`store_off`, `sign_in_required` and more. OPEN-ENDED: the arcade may send a
+code this SDK has never heard of, so keep a `default` arm and never show a
+code to a player. Absent when there is nothing to add.
+
+Three are the SDK's own, answered without asking the arcade:
+`unsupported` (the arcade here does not offer this), `invalid_argument`
+(the SDK refused what you passed) and `busy` (another ask of the same kind
+is still open). `error` means no reliable answer arrived — the ask never
+left, the wait ran out, the bridge closed or the arcade had none. For
+`gem.store.purchase` that makes the outcome UNKNOWN, not a refusal: the
+player may have paid.
+
+<a id="arcadeoffer"></a>
+
+## ArcadeOffer
+
+```ts
+interface ArcadeOffer
+```
+
+One SKU the Arcade Store sells to this player, here, right now.
+
+Show `priceDisplay` **exactly as given**: it is the payment rail's own
+formatted price in the player's currency. Never parse it, compare it or
+compute a discount from it. There is no numeric price, no balance and no
+availability flag — the arcade's sheet explains anything that stops a
+purchase.
+
+<a id="arcadeoffer-skuid"></a>
+
+## ArcadeOffer.skuId
+
+```ts
+readonly skuId: string
+```
+
+The SKU's id: what [StoreApi.purchase](#storeapi-purchase) takes.
+
+<a id="arcadeoffer-kind"></a>
+
+## ArcadeOffer.kind
+
+```ts
+readonly kind: "gem_pack" | "boost" | "pass" | "bundle"
+```
+
+What sort of thing it is.
+
+<a id="arcadeoffer-name"></a>
+
+## ArcadeOffer.name
+
+```ts
+readonly name: string
+```
+
+The store's own name for it, localized as the store shows it.
+
+<a id="arcadeoffer-description"></a>
+
+## ArcadeOffer.description
+
+```ts
+readonly description: string
+```
+
+What the player gets, in the store's words. May be empty.
+
+<a id="arcadeoffer-imageurl"></a>
+
+## ArcadeOffer.imageUrl
+
+```ts
+readonly imageUrl?: string
+```
+
+The SKU's art, when it has any.
+
+<a id="arcadeoffer-pricedisplay"></a>
+
+## ArcadeOffer.priceDisplay
+
+```ts
+readonly priceDisplay: string
+```
+
+The price, formatted by the payment rail. Show it as given.
+
+<a id="arcadeoffer-grant"></a>
+
+## ArcadeOffer.grant
+
+```ts
+readonly grant?: { currency: string; amount: number }
+```
+
+For a Gem pack: the platform currency and the amount it grants.
+
+<a id="arcadeoffer-grant-currency"></a>
+
+## ArcadeOffer.grant.currency
+
+```ts
+readonly currency: string
+```
+
+The platform currency's exact slug, e.g. `GEMS`.
+
+<a id="arcadeoffer-grant-amount"></a>
+
+## ArcadeOffer.grant.amount
+
+```ts
+readonly amount: number
+```
+
+How much of it the pack grants.
+
+<a id="storeoffersoutcome"></a>
+
+## StoreOffersOutcome
+
+```ts
+interface StoreOffersOutcome
+```
+
+What [StoreApi.offers](#storeapi-offers) resolves with.
+
+<a id="storeoffersoutcome-outcome"></a>
+
+## StoreOffersOutcome.outcome
+
+```ts
+readonly outcome: ArcadeOutcomeKind
+```
+
+What happened: `ok`, `declined` or `unavailable`. Branch on this.
+
+<a id="storeoffersoutcome-reason"></a>
+
+## StoreOffersOutcome.reason
+
+```ts
+readonly reason?: string
+```
+
+Why, as a machine code — `busy`, `cancelled`, `not_found`, `pending`,
+`store_off`, `sign_in_required` and more. OPEN-ENDED: the arcade may send a
+code this SDK has never heard of, so keep a `default` arm and never show a
+code to a player. Absent when there is nothing to add.
+
+Three are the SDK's own, answered without asking the arcade:
+`unsupported` (the arcade here does not offer this), `invalid_argument`
+(the SDK refused what you passed) and `busy` (another ask of the same kind
+is still open). `error` means no reliable answer arrived — the ask never
+left, the wait ran out, the bridge closed or the arcade had none. For
+`gem.store.purchase` that makes the outcome UNKNOWN, not a refusal: the
+player may have paid.
+
+<a id="storeoffersoutcome-offers"></a>
+
+## StoreOffersOutcome.offers
+
+```ts
+readonly offers: readonly ArcadeOffer[]
+```
+
+What the store sells here, in its own order. Empty unless `ok`.
+
+<a id="storesettlement"></a>
+
+## StoreSettlement
+
+```ts
+interface StoreSettlement
+```
+
+A purchase that answered `ok` / `pending` has settled.
+
+<a id="storesettlement-skuid"></a>
+
+## StoreSettlement.skuId
+
+```ts
+readonly skuId: string
+```
+
+The SKU it was for. Re-read balances and inventory through `gem.me`.
+
+<a id="storeapi"></a>
+
+## StoreApi
+
+```ts
+interface StoreApi
+```
+
+**Real money.** The Arcade Store's own Gem packs, Boosts, passes and bundles,
+bought with the player's money through the arcade's own purchase sheet.
+`gem.store` is one of these. To spend Gems or Coins on your game's own items,
+use `gem.purchases`.
+
+<a id="storeapi-available"></a>
+
+## StoreApi.available
+
+```ts
+readonly available: boolean
+```
+
+Whether the Arcade Store answers here, synchronously. Draw your own "Get
+Gems" button only when it is true.
+
+<a id="storeapi-offers"></a>
+
+## StoreApi.offers
+
+```ts
+offers(): Promise<StoreOffersOutcome>
+```
+
+What the store sells this player here: names, art and the rail's own
+prices. `unavailable` / `sign_in_required` for a guest (offer
+`gem.account.requestSignIn`), `unavailable` / `store_off` where the store
+is withheld. Re-read on resume: what is on sale can change.
+
+**Returns.** Always resolves; never rejects.
+
+<a id="storeapi-purchase"></a>
+
+## StoreApi.purchase
+
+```ts
+purchase(skuId: string): Promise<ArcadeOutcome>
+```
+
+Ask the arcade to open its store's purchase sheet for one SKU from
+[StoreApi.offers](#storeapi-offers). **Call it from the player's press handler** — the
+arcade refuses an ask no person pressed for, `declined` / `busy`.
+
+- `ok` — the player paid. Re-read balances and inventory through `gem.me`;
+  nothing here carries an amount. With `reason: 'pending'`, the provider
+  has not settled yet: [StoreApi.onSettled](#storeapi-onsettled) hears when it does.
+- `declined` — nothing was bought: `cancelled` (the player said no) or
+  `busy`. Return to your screen silently, and do not ask again unprompted.
+- `unavailable` with `store_off`, `sign_in_required`, `not_found`,
+  `unsupported`, `invalid_argument` or a payment provider's failure code —
+  nothing was bought.
+- `unavailable` / `error` — **the outcome is unknown, and the player may
+  have paid.** It is what you get when the bridge closes while the sheet
+  is open, or the arcade has no reliable answer. Never tell the player
+  nothing was bought: re-read balances and inventory through `gem.me`,
+  and keep listening with [StoreApi.onSettled](#storeapi-onsettled).
+
+NO TIMEOUT: it waits for as long as the arcade is connected, because a
+payment takes as long as it takes.
+
+| Parameter | Type |
+| --- | --- |
+| `skuId` | `string` |
+
+**Returns.** Always resolves; never rejects.
+
+<a id="storeapi-onsettled"></a>
+
+## StoreApi.onSettled
+
+```ts
+onSettled(listener: (settlement: StoreSettlement) => void): () => void
+```
+
+Hear when a purchase that answered `ok` / `pending` settles, while your
+game is running. Returns a function that stops listening.
+
+| Parameter | Type |
+| --- | --- |
+| `listener` | `(settlement: StoreSettlement) => void` |
+
 <a id="avatar3dprice"></a>
 
 ## Avatar3dPrice
@@ -9751,8 +10470,10 @@ synchronously wherever you render.
 readonly purchases: PurchaseApi
 ```
 
-Buy one of YOUR OWN items or recipes with platform currency, on the
-player's behalf.
+**Gems and Coins, not real money.** Buy one of YOUR OWN items or recipes
+with platform currency, on the player's behalf. To sell the Arcade Store's
+own Gem packs, Boosts and passes for the player's money, use
+[Gem.store](#gem-store).
 
 This is the platform-owned path: the request crosses the bridge, the parent
 always renders the platform purchase sheet in trusted chrome, and the
@@ -9893,6 +10614,44 @@ shareButton.onclick = () => {
 
 **Guides.** [getting-started](../getting-started.md)
 
+<a id="gem-arcade"></a>
+
+## Gem.arcade
+
+```ts
+readonly arcade: ArcadeApi
+```
+
+The Gem Arcade's own features, asked for from your game: link out to the
+Gem Arcade app or your game's own app, open another game, and list games
+like yours as home tiles.
+
+The game asks; the arcade decides. Nothing you send is a URL, and nothing
+rejects: every call resolves `{ outcome, reason, … }`. Check
+[ArcadeApi.available](#arcadeapi-available) before drawing a button, and call `openApp`
+and `openGame` from the player's press handler.
+
+**Guides.** [arcade-and-store](../arcade-and-store.md)
+
+<a id="gem-store"></a>
+
+## Gem.store
+
+```ts
+readonly store: StoreApi
+```
+
+**Real money.** The Arcade Store's own Gem packs, Boosts, passes and
+bundles, sold for the player's money through the arcade's own purchase
+sheet. To spend Gems or Coins on your game's own items, use
+[Gem.purchases](#gem-purchases).
+
+List what the store sells here with `offers()`, show each `priceDisplay`
+exactly as given, and call `purchase(skuId)` from the player's press. After
+`ok`, re-read balances through [Gem.me](#gem-me). Nothing rejects.
+
+**Guides.** [arcade-and-store](../arcade-and-store.md)
+
 <a id="gem-avatarpickeravailable"></a>
 
 ## Gem.avatarPickerAvailable