@indiegems/gem-web-sdk 8.0.0 → 9.0.0

package/docs/cross-promotion.md

@@ -4,6 +4,11 @@ The Arcade can show a **full-screen panel about another game** at a break in you
 for one; the Arcade decides whether to show anything, draws it in its own chrome over your paused
 game, and tells you when it is done.
 
+The same call with `format: 'rewarded'` is a button the player presses for something your game
+gives — a revive, an extra attempt. That one has its own page,
+[`rewarded-ads.md`](rewarded-ads.md). This page is about the interstitial; where a rule here reads
+differently for a rewarded ask, it says so.
+
 ```js
 const { outcome } = await gem.ads.requestAd({
   placement: 'level-complete',
@@ -13,8 +18,8 @@ const { outcome } = await gem.ads.requestAd({
 startNextLevel();
 ```
 
-That is the whole surface. The rest of this page is the four things a game gets wrong when nobody
-tells it.
+That is the whole surface, apart from one read that tells a rewarded button whether it could pay
+(§3). The rest of this page is the four things a game gets wrong when nobody tells it.
 
 ## 1. The answer is usually no, and no is ordinary
 
@@ -37,6 +42,12 @@ So write the `no_ad` path as your ordinary path:
 - Do **not** hold up your own flow waiting for a fill. Ask, and continue when the promise settles.
 - Do **not** retry on a no. A second ask at the same break gets the same answer and spends a slot.
 
+**A rewarded ask reads differently, because the player pressed your button and is waiting on it.**
+Its `no_ad` can arrive with the reward already granted (§3), so branch on your inventory, never on
+the outcome; and where nothing landed, a neutral line in your own UI — "No revive this time" — is
+right, with no reason given. [`rewarded-ads.md`
+§5](rewarded-ads.md#5-draw-the-button-and-name-the-reward) is that button.
+
 ## 2. Nothing rejects
 
 `requestAd` always resolves. There is no error branch and no `try`/`catch` to write. Even a refusal
@@ -49,36 +60,68 @@ resolves `no_ad`, so your game keeps exactly one branch. (The mistake is still r
 `shown` says a panel was painted and has closed. It is **not** a receipt, **not** an entitlement,
 and **not** permission to hand anything out.
 
-`format: 'rewarded'` exists in the vocabulary and is answered `no_ad` today. Even when that
-changes, a reward will be granted by the platform against its own record of what was shown — never
-by your game reading an outcome. An outcome travels over the same channel as everything else your
-frame receives, and a game that unlocks a level or grants a currency on the strength of one has an
-unlock that any page embedding your game can forge.
+That holds for `format: 'rewarded'` too, the one format that pays the player. The platform grants a
+rewarded placement's reward itself, against its own record of what the player did on the Arcade's
+offer sheet — never your game, by reading an outcome. An outcome travels over the same channel as
+everything else your frame receives, and a game that unlocks a level or grants a currency on the
+strength of one has an unlock that any page embedding your game can forge.
 
 Treat a break as a break. If your game wants to give the player something for reaching the end of a
 level, give it to them for reaching the end of the level.
 
-**Where a rewarded grant will arrive, so you can write the code now.** On your game's own inventory
-for this player, written by the platform — never by your game — and read through
-`gem.me.inventory`, the same place a purchase lands, read the same way. (That is the game-scoped
-inventory `gem.me` shows you, not the player's platform wallet.) There will be **no fourth outcome
-and no extra field** on the answer. `outcome` is pinned at three values because a new value would
-break every game bundle already in the field: its validator refuses the whole message. A new field
-would not break anything — validators ignore fields they do not know — but it is not coming either:
-anything on that answer can be forged by the page embedding your game, so a reward carried there
-would be a reward anyone could hand out. If you serve `rewarded`, re-read your snapshot once the ask
-settles, whatever it settled as:
+**Where a rewarded grant arrives.** On your game's own inventory for this player, written by the
+platform — never by your game — and read through `gem.me.inventory`, the same place a purchase
+lands, read the same way. (That is the game-scoped inventory `gem.me` shows you, not the player's
+platform wallet.) There is **no fourth outcome and no extra field** on the answer. `outcome` is
+pinned at three values because a new value would break every game bundle already in the field: its
+validator refuses the whole message. A new field would not break anything — validators ignore
+fields they do not know — but it is not coming either: anything on that answer can be forged by the
+page embedding your game, so a reward carried there would be a reward anyone could hand out. So
+re-read your snapshot once a rewarded ask settles, whatever it settled as:
 
 ```js
 await gem.ads.requestAd({ placement: 'run-banked', format: 'rewarded' });
 gem.me.inventory.refresh(); // drop what is cached
-const snap = await gem.me.inventory.snapshot(); // the grant, if there was one, is here
+const snap = await gem.me.inventory.snapshot(); // a reward granted before the answer is here
 ```
 
-Today that re-read finds nothing new, because nothing is served. It costs one request at a break
-your player is already sitting in, and it is the whole of what changes on the day one is — no
-rebuild. [`inventory-and-catalogs.md` §6](inventory-and-catalogs.md#6-when-to-re-read) is the
-general form of this.
+A `no_ad` can come back with the reward already in that snapshot, because the platform grants
+without an ad in some cases, so branch on the inventory and never on the outcome. And a reward that
+an ad provider confirms from its own server can land after this re-read, so read again when the
+screen that spends it opens; [`inventory-and-catalogs.md`
+§6](inventory-and-catalogs.md#6-when-to-re-read) is the general form of this.
+[`rewarded-ads.md`](rewarded-ads.md) is the rest: declaring what a placement grants, spending it,
+drawing the button, and testing.
+
+**Whether a rewarded button could pay right now.** A rewarded placement is a button the player
+presses, so you need to know whether to draw it. `gem.ads.rewardedStatus(placement)` reads one
+placement's state from **your own** `rewarded_placements` config — its daily cap, cooldown and
+`max_held` — applied to this player's use of it:
+
+```js
+const status = await gem.ads.rewardedStatus('run-banked');
+bankButton.disabled = !status.grantable;
+```
+
+| field | what it says |
+|---|---|
+| `declared` | the config promoted to the channel being played names this placement |
+| `grantable` | pressing the button could pay right now — **not** that an ad will play |
+| `remainingToday` | grants left today under the daily cap; absent when the placement has none |
+| `nextEligibleAt` | when a running cooldown ends, in epoch milliseconds; absent when none runs |
+| `heldLimitReached` | the player already holds the placement's `max_held` — spend one first |
+| `resetsAt` | when today's count resets, the next 00:00 UTC, in epoch milliseconds |
+
+**`grantable` is not a promise.** A player can press a `grantable` button and get `no_ad`, for
+reasons your game is not told. Read that `no_ad` like any other (§1) — never guess a reason — and
+re-read your inventory whatever the ask settled as. The status grants nothing and reserves
+nothing.
+
+It never rejects, like the rest of `gem.ads`. Without a play token, when the read fails or takes
+longer than ten seconds, or for a placement outside the grammar below, it answers 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 — and not every
+frame, and draw the rest of the screen first rather than holding it on the answer.
 
 ## 4. The Arcade pauses your game for you
 
@@ -94,20 +137,23 @@ If you have not wired the pause at all yet, that is the thing to fix first;
 
 At a break **the player already expects**: a level ending, a round finishing, a run being banked, a
 return to a menu. Never mid-input, never during a timed sequence, and never on a screen the player
-reached by accident.
+reached by accident. (A rewarded ask goes where the player pressed your button for it, and nowhere
+else; [`rewarded-ads.md`](rewarded-ads.md) covers the button.)
 
-`placement` is your own name for that break — `level-complete`, `run-banked`, `back-to-menu`. The
-platform matches it against nothing today, never shows it to a player, and does not vary its
-decision on it. It exists so your own analytics can tell two break points apart, so name it for
-yourself.
+`placement` is your own name for that break — `level-complete`, `run-banked`, `back-to-menu`. For
+an interstitial, the platform matches it against nothing, never shows it to a player, and does not
+vary its decision on it; it exists so your own analytics can tell two break points apart, so name
+it for yourself. For `format: 'rewarded'`, the placement names the reward your game config declares
+in `rewarded_placements`, and the platform matches it against that config. Either way it **never
+reaches an ad network**, and neither does any other string your game writes.
 
 **It has a grammar, and it is narrow on purpose: 1 to 32 characters of `a-z`, `0-9`, `-` and `_`.**
 Lowercase, no spaces, no accents — `'Boss Fight'` is not a placement, `'boss-fight'` is. Anything
 else resolves `no_ad` and is reported to your `onError` handler, so you meet it while you are
-building rather than later. The reason it is enforced now, while nothing depends on it, is that
-this is the field a promotion is eventually **keyed by**: the Arcade will forward it unchanged, and
-a name that does not fit the platform's grammar would be a name that stopped working after your
-game had shipped. The bound is the platform's, not the SDK's, and the two agree.
+building rather than later. The platform holds the same grammar where it reads the name: for a
+rewarded ask the Arcade forwards the placement unchanged, and a config that declares one outside
+the grammar is refused at upload, so a name that did not fit would be a reward your shipped game
+could never reach. The bound is the platform's, not the SDK's, and the two agree.
 
 ```js
 async function onLevelComplete() {
@@ -130,6 +176,16 @@ schedule that does not depend on which branch produced it, so there is nothing i
 read either. (`shown` is not held back — how long that one takes is how long your player spent
 looking at a panel.)
 
+A rewarded ask is the one case where something else reaches your game: the reward itself, in your
+own inventory, when one was granted. That is what the ask is for. It says that a reward landed,
+never why, so do not read a reason into it.
+
+The other thing you can read is your own economy, and never from the answer:
+`gem.ads.rewardedStatus` reports **your own declared** rewarded caps as the platform holds them —
+the platform can hold a placement's daily cap below what you declared, never above — so you can
+tell when a rewarded `no_ad` was your own cap. It never reports anything about the player, the
+platform's spacing between offers, or any limit that spans games.
+
 ## If you do nothing
 
 Nothing happens. A game that never calls `gem.ads.requestAd` is never interrupted, and the call is

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "8.0.0"
+  "@indiegems/gem-web-sdk": "9.0.0"
 }
 ```
 
@@ -355,7 +355,8 @@ What reaches the frame:
   only keys the arcade keeps for itself; it never interprets yours:
   - Store and play-page switches: `play`, `channel`, `purchase`, and `build`, which pins one
     of your own builds when you play it from your Builds page.
-  - Platform switches: `devtools`, `devLocale`.
+  - Platform switches: `devtools`, `devLocale`, and `gem_test_ads`, the mode of the arcade's
+    rewarded TEST ads.
   - The arcade's own sign-in return marker: `social`.
   - Attribution and campaign keys, which the arcade keeps out of every game: `_s`, `utm_*`
     (every key with that prefix, matched case-sensitively, so UTM_X and utmost are yours),

package/docs/manifest.json

@@ -8,8 +8,8 @@
   "documents": [
     {
       "file": "achievements.md",
-      "sha256": "e67bc5d0e6abd9ff842be46fa82bf5117fce74b2eb9d28a3954919ddc8a11c73",
-      "updated": "2026-10-02T23:09:37Z"
+      "sha256": "adc8bfaa769fbb283a53de1190ed85cdf4c1c9753e8cf78335b4595e98f8fad4",
+      "updated": "2026-10-06T22:14:30Z"
     },
     {
       "file": "analytics.md",
@@ -33,13 +33,13 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "37bae4170e89587ee8c498891fa2dac008f09fb01fcfbcf87b1310340d2cfc62",
-      "updated": "2026-10-06T19:43:21Z"
+      "sha256": "dd8afde50d0e34052ebdb8b894d30faa4814d4209fc62644fdc5ab53a1395e32",
+      "updated": "2026-10-08T00:55:05Z"
     },
     {
       "file": "cross-promotion.md",
-      "sha256": "3a8121a9c973e4a1bfed076a3226d139f8b4e38a173a06ea9f08000c72bca4b4",
-      "updated": "2026-09-29T17:32:40Z"
+      "sha256": "4336d72595115950919361c36ab1af9beaa787c3c57d27fea27d42dac69d81cf",
+      "updated": "2026-10-07T19:15:38Z"
     },
     {
       "file": "daily-challenges.md",
@@ -68,8 +68,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "77ce7b2223d18267ac3ca2f49e09481752539f2674910e2cb12832825c945000",
-      "updated": "2026-10-06T19:43:21Z"
+      "sha256": "95f645a73bfb522537fe14562d4a87b10a7f06af036c5658996c05bddced875b",
+      "updated": "2026-10-08T00:55:05Z"
     },
     {
       "file": "inventory-and-catalogs.md",
@@ -83,8 +83,8 @@
     },
     {
       "file": "match-session.md",
-      "sha256": "738c54766f5489ba7509f5f31ef1387a2a80ad89f03eaccd52113a18f2765b0d",
-      "updated": "2026-09-25T21:03:24Z"
+      "sha256": "33fdef4edc170cadd2284ff399fcf16455b7691d9aeac52bd09bade24b8b051a",
+      "updated": "2026-10-07T19:27:16Z"
     },
     {
       "file": "p2p-and-parties.md",
@@ -101,15 +101,20 @@
       "sha256": "df1e39628ccba04b6f7bcd0b90381dfa34a4480330a6af041d9b71bcaefddb5f",
       "updated": "2026-09-17T20:51:57Z"
     },
+    {
+      "file": "rewarded-ads.md",
+      "sha256": "39332bd7b08adbb33d3b6382142d214e17d8f24a7776061a97f372d658e48974",
+      "updated": "2026-10-07T19:17:55Z"
+    },
     {
       "file": "room-shapes.md",
-      "sha256": "5aab02d65a7573ac690649b70e5db4fed4f779c3102c35e64a8ced02218410a9",
-      "updated": "2026-09-29T23:14:43Z"
+      "sha256": "78fad1eee7602b10a9b39f100d3daedfed6c313a884f95382233434a3206930b",
+      "updated": "2026-10-07T19:27:16Z"
     },
     {
       "file": "rooms-and-matches.md",
-      "sha256": "d8c397bc3657d7f46dba7ca0af81dcf181148df798dbaced27dfd294889a1da6",
-      "updated": "2026-09-25T02:14:45Z"
+      "sha256": "0abf3717a42c94ec832dfa1310c2d93a9f58236fd75b0aacaab301976bffe286",
+      "updated": "2026-10-07T19:27:16Z"
     },
     {
       "file": "saving-player-progress.md",
@@ -118,8 +123,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "49f51b37e969b6120d2df6cf6d2f33d2856c1602fd7504a7b308a9ea21c9b502",
-      "updated": "2026-10-06T19:43:21Z"
+      "sha256": "584ace965c1be20ca90ee1cd3beff7c1473f1ca9bccef428b3efb6846b2315a7",
+      "updated": "2026-10-08T00:55:05Z"
     },
     {
       "file": "serverless-functions-js.md",
@@ -128,8 +133,8 @@
     },
     {
       "file": "serverless-functions.md",
-      "sha256": "1edaa60a8aaf20499f24d661f169790cacfdb11c26529735a93e5b7b996e5432",
-      "updated": "2026-10-03T00:26:43Z"
+      "sha256": "b1562b4442b69bb6895198def7b00ccd7a8c56133862a939c2cce9b6e9d30290",
+      "updated": "2026-10-07T19:27:16Z"
     },
     {
       "file": "trading-and-gifting.md",
@@ -143,8 +148,8 @@
     },
     {
       "file": "what-a-game-must-do.md",
-      "sha256": "436a8b61c46a3de6c7d5db65293bdcd17426412742dffd21f976bf87d1418d88",
-      "updated": "2026-10-06T17:36:25Z"
+      "sha256": "7dc6bdc55e3cfbc88d667bbc2ebf908e357a1b6d768d5e3f4ce486ded614c1bf",
+      "updated": "2026-10-07T19:15:38Z"
     }
   ]
 }

package/docs/match-session.md

@@ -204,7 +204,7 @@ next round is one call:
 
 **A template's `auto_start_host` starts the first match, not the second.** It fires when the room
 reaches `min_players`; a reopened room already has them, and nothing fires again. A shape whose
-first match started itself — a hub, a worker, a matchmade lobby — still needs a client to call
+first match started itself — a hub, a matchmade lobby — still needs a client to call
 `startMatch()` for the next one, and that client is whoever `gem.rooms.isHost` says. Watch
 `hostChanged`: if the host closed their tab during the match, the room has a new host, and the
 start belongs to them now.