@indiegems/gem-web-sdk 8.0.0 → 8.1.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` v8.1.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)
@@ -2934,6 +2975,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)
@@ -3009,6 +3055,160 @@ startNextLevel();
 
 **Guides.** [cross-promotion](https://gemarcade.com/developer/docs/cross-promotion)
 
+## 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 +5063,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 +5314,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
 
@@ -6883,8 +7107,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 +7889,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 +8287,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 +9432,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 +9557,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 +12106,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 +13548,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 +15583,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 +16348,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` v8.1.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.