@indiegems/gem-web-sdk 8.0.0 → 9.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` v8.0.0. Every symbol below links to its page on the Gem Arcade developer site.
+Generated from `@indiegems/gem-web-sdk/sdk` v9.0.0. Every symbol below links to its page on the Gem Arcade developer site.
 
 `@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.
 
@@ -247,6 +247,47 @@ check that a funnel you declared names events you are actually sending.
 
 Absent when your game declares none.
 
+## GameConfig.rewarded_placements
+
+[GameConfig.rewarded_placements](https://gemarcade.com/developer/api/game#gameconfig-rewarded_placements)
+
+```ts
+rewarded_placements?: SnapshotRewardedPlacement[]
+```
+
+Your rewarded placements — what pressing a rewarded button grants. An
+array, one row per placement, each naming itself in `placement`, with its
+`grants`, the caps the platform enforces on it (`max_per_day`,
+`cooldown_seconds`, `max_held`) and what happens where no ad serves
+(`without_ads`).
+
+Read it to LABEL your button — "+1 Revive" — never to decide a reward. A
+grant is an `item_grant`, with a `quantity` of the item its
+`item_definition_id` names, or a `currency_grant`, with an `amount` of the
+currency its `currency_id` names; the word on the button is that
+definition's `display_name`, from [GameConfig.item](https://gemarcade.com/developer/api/game#gameconfig-item) or
+[GameConfig.currency](https://gemarcade.com/developer/api/game#gameconfig-currency):
+
+```js
+const row = config?.rewarded_placements?.find((p) => p.placement === 'classic_revive');
+const grant = row?.grants[0];
+const label =
+  grant?.type === 'item_grant'
+    ? `+${grant.quantity} ${config.item(grant.item_definition_id)?.display_name ?? ''}`
+    : grant?.type === 'currency_grant'
+      ? `+${grant.amount} ${config.currency(grant.currency_id)?.display_name ?? ''}`
+      : undefined;
+```
+
+Whether an ask grants anything is the platform's decision, made against
+this config server-side; the grant lands on your game's inventory, and
+re-reading `gem.me.inventory` is the only way to learn that it did. Whether
+the button could pay right now is [AdsApi.rewardedStatus](https://gemarcade.com/developer/api/game#adsapi-rewardedstatus).
+
+Absent when your game declares none.
+
+**Guides.** [cross-promotion](https://gemarcade.com/developer/docs/cross-promotion)
+
 ## GameConfig.version
 
 [GameConfig.version](https://gemarcade.com/developer/api/game#gameconfig-version)
@@ -2862,14 +2903,16 @@ Which kind of break this is.
 
 `interstitial` is a panel the player dismisses and nothing follows from.
 
-⚠️ `rewarded` is part of the vocabulary and is answered `no_ad` today. It is
-here so a game's own analytics can distinguish the two kinds of break, and so
-this request has the shape an ad request has everywhere. Even when it is
-served, the outcome grants nothing — a reward is granted by the platform,
-against its own record, never by your game reading `shown`. It arrives on
-your game's inventory for this player, written by the platform, so re-read
-`gem.me.inventory` after a `rewarded` ask settles rather than waiting for a
-signal on this pair; there will not be one.
+`rewarded` is a button the player pressed for a reward — a revive, an extra
+attempt — that your game config declares for the placement in
+`rewarded_placements`. It is served where this arcade serves it, and answered
+`no_ad` where it does not. ⚠️ The outcome grants nothing: the platform grants
+the reward, against its own record, never your game reading `shown`. It
+arrives on your game's inventory for this player, written by the platform,
+so re-read `gem.me.inventory` after a `rewarded` ask settles rather than
+waiting for a signal on this pair; there will not be one.
+
+**Guides.** [rewarded-ads](https://gemarcade.com/developer/docs/rewarded-ads)
 
 ## AdRequest
 
@@ -2893,14 +2936,17 @@ Your own name for the break — `level-complete`, `between-rounds`.
 
 **1 to 32 characters of `a-z`, `0-9`, `-` and `_`.** Lowercase, no spaces,
 no accents: `'Boss Fight'` is not a placement, `'boss-fight'` is. The
-grammar is the platform's own, and it is narrow deliberately — this is the
-field an ad unit is keyed by, so a name that does not fit it is a name that
-would stop working later rather than now. A placement outside it is
-answered `no_ad` and reported to your `onError` handler.
-
-The platform matches it against nothing today and never shows it to a
-player. It is for your own telemetry, so two break points in your game can
-be told apart.
+grammar is the platform's own, and the SDK enforces it so a name that does
+not fit is refused at your keyboard rather than in the field. A placement
+outside it is answered `no_ad` and reported to your `onError` handler.
+
+For `rewarded`, it names the reward your game config declares in
+`rewarded_placements`: the platform matches it against that config, and a
+placement the config does not declare is answered `no_ad`. For
+`interstitial`, the platform matches it against nothing; there it is for
+your own telemetry, so two break points in your game can be told apart.
+Either way it is never shown to a player and **never sent to an ad
+network**.
 
 ## AdRequest.format
 
@@ -2926,7 +2972,8 @@ fourth.
 - `shown` — a panel was painted and has now closed. Resume. **It grants
   nothing.**
 - `no_ad` — nothing was painted. Carry on exactly as if you had not asked.
-  This is the common answer.
+  This is the common answer. After a `rewarded` ask the reward may still
+  have landed, with no ad, so re-read your inventory either way.
 - `unavailable` — the arcade could not render just now. Not a softer no; read
   it exactly as you read `no_ad`.
 
@@ -2934,6 +2981,11 @@ No reason is given for a `no_ad`, and one will never be added: a reason would
 tell your game something about the player — an age, a consent state, a
 subscription — that game code is deliberately not told.
 
+The one thing you can learn is about **your own economy**, and not from this
+answer: [AdsApi.rewardedStatus](https://gemarcade.com/developer/api/game#adsapi-rewardedstatus) reports your own declared rewarded caps
+as the platform holds them (a platform-wide per-placement maximum, where one
+is set, can lower a cap). It never reports anything about the player.
+
 ## AdOutcome
 
 [AdOutcome](https://gemarcade.com/developer/api/game#adoutcome)
@@ -2989,7 +3041,9 @@ The arcade pauses your game while a panel is up and resumes it when this
 settles, so you do not need to pause anything yourself.
 
 ⚠️ `shown` grants nothing. Never hand out a reward, an unlock or a currency
-on the strength of it.
+on the strength of it. A `rewarded` placement's reward is granted by the
+platform into your game's inventory; re-read `gem.me.inventory` once this
+settles, whatever it settled as.
 
 | Parameter | Type | Description |
 | --- | --- | --- |
@@ -3007,8 +3061,160 @@ const { outcome } = await gem.ads.requestAd({
 startNextLevel();
 ```
 
+## AdsApi.rewardedStatus
+
+[AdsApi.rewardedStatus](https://gemarcade.com/developer/api/game#adsapi-rewardedstatus)
+
+```ts
+rewardedStatus(placement: string): Promise<RewardedStatus>
+```
+
+Whether a rewarded placement could pay right now, so you can decide whether
+to draw its button. **It never says whether an ad will play.**
+
+The answer comes from your own `rewarded_placements` config — its daily
+cap, cooldown and `max_held` — applied to this player's use of it, as the
+platform holds them. Nothing in it describes the player. `grantable: true`
+means the platform would grant if an ad is watched or, where no ad serves,
+under the placement's `without_ads: grant`; a player can still press the
+button and get `no_ad`, for reasons your game is not told.
+
+NOTHING REJECTS, like everything else on `gem.ads`. Without a play token,
+when the read fails or takes longer than ten seconds, or for a `placement`
+outside the grammar [AdRequest.placement](https://gemarcade.com/developer/api/game#adrequest-placement) documents, it resolves not
+declared and not grantable, with no `resetsAt`, and the reason goes to your
+`onError` handler.
+
+It is a read of the platform, so call it when you draw the button — on a
+results or death screen — not every frame. Calls for one placement that
+overlap share one request. Draw the rest of the screen first rather than
+holding it on this answer.
+
+⚠️ It grants nothing and reserves nothing. The reward is granted by the
+platform when the player asks with `requestAd`; re-read `gem.me.inventory`
+after that ask settles, whatever it settled as.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `placement` | `string` | A placement your `rewarded_placements` config declares. |
+
+**Returns.** The placement's state. Always resolves; never rejects.
+
+```ts
+const status = await gem.ads.rewardedStatus('classic_revive');
+reviveButton.disabled = !status.grantable;
+if (status.nextEligibleAt !== undefined) {
+  reviveButton.title = `Back at ${new Date(status.nextEligibleAt).toLocaleTimeString()}`;
+}
+```
+
 **Guides.** [cross-promotion](https://gemarcade.com/developer/docs/cross-promotion)
 
+## RewardedStatus
+
+[RewardedStatus](https://gemarcade.com/developer/api/game#rewardedstatus)
+
+```ts
+interface RewardedStatus
+```
+
+What [AdsApi.rewardedStatus](https://gemarcade.com/developer/api/game#adsapi-rewardedstatus) answers: the state of one rewarded
+placement for this player, from your own declared caps.
+
+Every figure comes from **your** `rewarded_placements` config — `max_per_day`,
+`cooldown_seconds`, `max_held` — applied to this player's use of it, as the
+platform holds them. The platform can hold a placement's daily cap below what
+you declared, never above it. Nothing here describes the player.
+
+⚠️ **It never says whether an ad will play.** Whether one does depends on
+things your game is deliberately not told. A player can see your button,
+press it, and get `no_ad`: read that `no_ad` like any other, and never guess
+a reason.
+
+## RewardedStatus.declared
+
+[RewardedStatus.declared](https://gemarcade.com/developer/api/game#rewardedstatus-declared)
+
+```ts
+readonly declared: boolean
+```
+
+Whether this channel's published config declares the placement.
+
+`false` for a placement your config does not name, a config that is not
+promoted to the channel being played, and every answer the platform did not
+give (see [RewardedStatus.resetsAt](https://gemarcade.com/developer/api/game#rewardedstatus-resetsat)).
+
+## RewardedStatus.grantable
+
+[RewardedStatus.grantable](https://gemarcade.com/developer/api/game#rewardedstatus-grantable)
+
+```ts
+readonly grantable: boolean
+```
+
+Whether pressing your button could pay right now: the platform would grant
+the reward if an ad is watched or, where no ad serves, under the
+placement's `without_ads: grant`.
+
+**Not a promise that an ad will play, and not a promise of a reward.** It
+is `false` whenever a cap is spent, a cooldown is running, the player holds
+`max_held`, rewarded is off on this channel, or the arcade running your
+game does not take ad requests at all.
+
+## RewardedStatus.remainingToday
+
+[RewardedStatus.remainingToday](https://gemarcade.com/developer/api/game#rewardedstatus-remainingtoday)
+
+```ts
+readonly remainingToday?: number
+```
+
+Grants left today under the placement's daily cap, a non-negative integer.
+
+ABSENT — no key, never a sentinel — when the placement has no daily cap,
+and on any answer where `declared` is `false`.
+
+## RewardedStatus.nextEligibleAt
+
+[RewardedStatus.nextEligibleAt](https://gemarcade.com/developer/api/game#rewardedstatus-nexteligibleat)
+
+```ts
+readonly nextEligibleAt?: number
+```
+
+When the placement's cooldown ends, in epoch milliseconds — render it with
+`new Date(nextEligibleAt)`.
+
+ABSENT when no cooldown is running.
+
+## RewardedStatus.heldLimitReached
+
+[RewardedStatus.heldLimitReached](https://gemarcade.com/developer/api/game#rewardedstatus-heldlimitreached)
+
+```ts
+readonly heldLimitReached: boolean
+```
+
+Whether the player already holds the placement's `max_held` of the item it
+grants. Spend one first.
+
+## RewardedStatus.resetsAt
+
+[RewardedStatus.resetsAt](https://gemarcade.com/developer/api/game#rewardedstatus-resetsat)
+
+```ts
+readonly resetsAt?: number
+```
+
+When the daily count resets — the next 00:00 UTC — in epoch milliseconds.
+Take it from here rather than computing midnight in game code.
+
+ABSENT when the platform gave no answer: no play token yet, a read that
+failed or took longer than ten seconds, or a platform that does not serve
+this read. Then the rest of the status reads not declared and not
+grantable, and the reason went to your `onError` handler.
+
 ## AnalyticsValue
 
 [AnalyticsValue](https://gemarcade.com/developer/api/game#analyticsvalue)
@@ -4863,6 +5069,29 @@ sends only while connected, and only to an arcade that draws a wallet.
 **Returns.** whether it entered the send path — `false` before the bridge is
   up, and `false` for an arcade with no wallet to move.
 
+## GemFrame.showPortraitBorders
+
+[GemFrame.showPortraitBorders](https://gemarcade.com/developer/api/game#gemframe-showportraitborders)
+
+```ts
+showPortraitBorders(name: string | null): boolean
+```
+
+Tell the arcade which of your store page's portrait borders to paint beside
+your game, or `null` for none.
+
+Prefer `gem.showPortraitBorders`, which holds your choice until the bridge
+is up and paces a burst of changes for you. This one sends every call it
+accepts, only while connected, and only to an arcade that paints borders.
+
+| Parameter | Type |
+| --- | --- |
+| `name` | `string \| null` |
+
+**Returns.** whether the message left the frame — `false` for a string that is
+  not a border name (with a console warning), before the bridge is up, for
+  an arcade that paints no borders, and past this frame's own limit.
+
 ## GemFrame.setWalletVisible
 
 [GemFrame.setWalletVisible](https://gemarcade.com/developer/api/game#gemframe-setwalletvisible)
@@ -5091,8 +5320,9 @@ draw your own placeholder rather than a broken image. Pass it through
 readonly badges: readonly PlayerBadge[]
 ```
 
-The player's equipped badges, in display order. Always a list, and empty
-until platform achievements equip any.
+The player's equipped badges, at most two, in the order the player
+arranged them. Always a list — empty when they wear none, or when their
+identity is withheld — so draw what is there and key on `itemId`.
 
 ## FriendsPage
 
@@ -5930,7 +6160,7 @@ The answer parsed as JSON.
 [FunctionFailure](https://gemarcade.com/developer/api/game#functionfailure)
 
 ```ts
-type FunctionFailure = "trap" | "memory_exceeded" | "cpu_budget_exceeded" | "host_call_limit"
+type FunctionFailure = "trap" | "memory_exceeded" | "cpu_budget_exceeded" | "host_call_limit" | "output_too_large" | "argument_too_large"
 ```
 
 Why a call that reached your function did not finish — carried on
@@ -5941,6 +6171,10 @@ Why a call that reached your function did not finish — carried on
 - `memory_exceeded` — past the memory limit.
 - `cpu_budget_exceeded` — past the CPU budget.
 - `host_call_limit` — more platform API calls than one invocation may make.
+- `output_too_large` — your function's result was over the 1 MiB output cap.
+- `argument_too_large` — a value your function handed to a platform call
+  (`log`, `call-api`, `download-link` or `upload-link`) was over the 16 MiB
+  per-call limit.
 
 ## GemFunctionError
 
@@ -6158,8 +6392,9 @@ const { accepted, why } = result.json();
 ARCADE_EMBEDDERS: readonly string[]
 ```
 
-The origins the Gem Arcade embeds a game from, which every game accepts
-without naming them: the website, and the Gem Arcade app.
+The origins the platform embeds a game from, which every game accepts
+without naming them: the Gem Arcade website, the Meme Games website, and
+the Gem Arcade app.
 
 You do not pass these. They are always allowed, and
 [GemOptions.allowedEmbedders](https://gemarcade.com/developer/api/game#gemoptions-allowedembedders) adds to them rather than replacing them.
@@ -6188,7 +6423,7 @@ readonly allowedEmbedders?: readonly string[]
 Extra origins allowed to embed your game, **added to** the ones the Gem
 Arcade uses. Most games leave this out.
 
-The website and the Gem Arcade app are always allowed — see
+The platform's websites and the Gem Arcade app are always allowed — see
 [ARCADE_EMBEDDERS](https://gemarcade.com/developer/api/game#arcade_embedders) — so do not list them. Set this only when a site
 of your own embeds your game.
 
@@ -6883,8 +7118,9 @@ draw your own placeholder rather than a broken image. Pass it through
 readonly badges: readonly PlayerBadge[]
 ```
 
-The player's equipped badges, in display order. Always a list, and empty
-until platform achievements equip any.
+The player's equipped badges, at most two, in the order the player
+arranged them. Always a list — empty when they wear none, or when their
+identity is withheld — so draw what is there and key on `itemId`.
 
 ## GemPrefs
 
@@ -7664,7 +7900,10 @@ resumes it when the promise settles, so you do not pause anything yourself.
 ⚠️ `shown` **grants nothing.** It is not a receipt and not an entitlement,
 and a reward must never be handed out on the strength of it.
 
-You are told no reason for a no, and there is nothing to infer from one.
+You are told no reason for a no, and there is nothing to infer from one
+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](https://gemarcade.com/developer/docs/cross-promotion)
 
@@ -8059,6 +8298,51 @@ arcade just said is not sent.
 | --- | --- |
 | `muted` | `boolean` |
 
+## Gem.showPortraitBorders
+
+[Gem.showPortraitBorders](https://gemarcade.com/developer/api/game#gem-showportraitborders)
+
+```ts
+showPortraitBorders(name: string | null): void
+```
+
+Choose which of your store page's **portrait borders** the arcade paints on
+either side of your game, or `null` for none.
+
+On a desktop browser, the arcade's desktop app or a television, the arcade
+shows a portrait-only game as a centred portrait column. With borders
+declared on your store page (`media.portrait_borders`), it paints one of
+those images beside the column instead of its own bars. Call this at
+start-up and on every theme change, with the border that goes with what is
+on screen:
+
+```js
+const BORDERS = new Set(['meadow', 'alpine']); // the names your store page declares
+
+function applyTheme(id) {
+  document.body.dataset.theme = id;
+  gem.showPortraitBorders(BORDERS.has(id) ? id : null); // null: a theme with no art
+}
+```
+
+Until your first call the arcade shows the page's first border. Whether
+your game is letterboxed at all is decided by your store page's
+`orientations`, never by this call, so call it unconditionally: before the
+connection exists your choice is held and sent when it connects, a burst of
+changes (a picker previewing on hover) reaches the arcade as its final
+value, and an arcade that paints no borders is simply not told. The arcade
+owns the change itself — when and how the image swaps — and sends no
+acknowledgement.
+
+A name is 1 to 40 characters of `a-z`, `0-9`, `_` and `-`, starting with a
+letter or digit — the store page's own rule. Anything else is refused with
+a console warning and never sent; a valid name your page does not declare
+is ignored by the arcade, which keeps the image it is showing.
+
+| Parameter | Type |
+| --- | --- |
+| `name` | `string \| null` |
+
 ## Gem.cueReward
 
 [Gem.cueReward](https://gemarcade.com/developer/api/game#gem-cuereward)
@@ -9159,7 +9443,8 @@ interface PlayerBadge
 One badge a player has equipped — an icon the platform shows beside their
 name.
 
-Always an empty list today; platform achievements fill it with at most two.
+A player wears at most two, in the order they arranged them. Each is an icon
+they own — an achievement in any game may have awarded it.
 
 ## PlayerBadge.itemId
 
@@ -9283,8 +9568,9 @@ draw your own placeholder rather than a broken image. Pass it through
 readonly badges: readonly PlayerBadge[]
 ```
 
-The player's equipped badges, in display order. Always a list, and empty
-until platform achievements equip any.
+The player's equipped badges, at most two, in the order the player
+arranged them. Always a list — empty when they wear none, or when their
+identity is withheld — so draw what is there and key on `itemId`.
 
 ## mapIdentity
 
@@ -11831,8 +12117,9 @@ draw your own placeholder rather than a broken image. Pass it through
 readonly badges: readonly PlayerBadge[]
 ```
 
-The player's equipped badges, in display order. Always a list, and empty
-until platform achievements equip any.
+The player's equipped badges, at most two, in the order the player
+arranged them. Always a list — empty when they wear none, or when their
+identity is withheld — so draw what is there and key on `itemId`.
 
 ## LeaderboardEntry.rank
 
@@ -13272,8 +13559,9 @@ draw your own placeholder rather than a broken image. Pass it through
 readonly badges: readonly PlayerBadge[]
 ```
 
-The player's equipped badges, in display order. Always a list, and empty
-until platform achievements equip any.
+The player's equipped badges, at most two, in the order the player
+arranged them. Always a list — empty when they wear none, or when their
+identity is withheld — so draw what is there and key on `itemId`.
 
 ## PlayerProfile.playerId
 
@@ -15306,8 +15594,9 @@ draw your own placeholder rather than a broken image. Pass it through
 readonly badges: readonly PlayerBadge[]
 ```
 
-The player's equipped badges, in display order. Always a list, and empty
-until platform achievements equip any.
+The player's equipped badges, at most two, in the order the player
+arranged them. Always a list — empty when they wear none, or when their
+identity is withheld — so draw what is there and key on `itemId`.
 
 ## RoomMember.playerId
 
@@ -16070,8 +16359,9 @@ draw your own placeholder rather than a broken image. Pass it through
 readonly badges: readonly PlayerBadge[]
 ```
 
-The player's equipped badges, in display order. Always a list, and empty
-until platform achievements equip any.
+The player's equipped badges, at most two, in the order the player
+arranged them. Always a list — empty when they wear none, or when their
+identity is withheld — so draw what is there and key on `itemId`.
 
 ## ShowcaseFriendEntry.playerId
 

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

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v8.0.0. Every symbol below links to its page on the Gem Arcade developer site.
+Generated from `@indiegems/gem-web-sdk/sdk` v9.0.0. Every symbol below links to its page on the Gem Arcade developer site.
 
 `@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.
 
@@ -1535,7 +1535,7 @@ The answer parsed as JSON.
 [FunctionFailure](https://gemarcade.com/developer/api/server#functionfailure)
 
 ```ts
-type FunctionFailure = "trap" | "memory_exceeded" | "cpu_budget_exceeded" | "host_call_limit"
+type FunctionFailure = "trap" | "memory_exceeded" | "cpu_budget_exceeded" | "host_call_limit" | "output_too_large" | "argument_too_large"
 ```
 
 Why a call that reached your function did not finish — carried on
@@ -1546,6 +1546,10 @@ Why a call that reached your function did not finish — carried on
 - `memory_exceeded` — past the memory limit.
 - `cpu_budget_exceeded` — past the CPU budget.
 - `host_call_limit` — more platform API calls than one invocation may make.
+- `output_too_large` — your function's result was over the 1 MiB output cap.
+- `argument_too_large` — a value your function handed to a platform call
+  (`log`, `call-api`, `download-link` or `upload-link`) was over the 16 MiB
+  per-call limit.
 
 ## GemFunctionError