@indiegems/gem-web-sdk 23.1.3 → 23.2.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 2,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "23.1.3"
+    "version": "23.2.0"
   },
   "entries": [
     {
@@ -397,7 +397,7 @@
           "group": "config",
           "signature": "rewarded_placements?: SnapshotRewardedPlacement[]",
           "documented": true,
-          "summary": "Your rewarded placements — what pressing a rewarded button grants. An\narray, one row per placement, each naming itself in `placement`, with its\n`grants`, the caps the platform enforces on it (`max_per_day`,\n`cooldown_seconds`, `max_held`) and what happens where no ad serves\n(`without_ads`, which is `nothing` when the config leaves it out).\n\nRead it to LABEL your button — \"+1 Revive\" — never to decide a reward. A\ngrant is an `item_grant`, with a `quantity` of the item its\n`item_definition_id` names, or a `currency_grant`, with an `amount` of the\ncurrency its `currency_id` names; the word on the button is that\ndefinition's `display_name`, from [GameConfig.item](api-reference-game.md#gameconfig-item) or\n[GameConfig.currency](api-reference-game.md#gameconfig-currency):\n\n```js\nconst row = config?.rewarded_placements?.find((p) => p.placement === 'classic_revive');\nconst grant = row?.grants[0];\nconst label =\n  grant?.type === 'item_grant'\n    ? `+${grant.quantity} ${config.item(grant.item_definition_id)?.display_name ?? ''}`\n    : grant?.type === 'currency_grant'\n      ? `+${grant.amount} ${config.currency(grant.currency_id)?.display_name ?? ''}`\n      : undefined;\n```\n\nWhether an ask grants anything is the platform's decision, made against\nthis config server-side; the grant lands on your game's inventory, and\nre-reading `gem.me.inventory` is the only way to learn that it did. Whether\nthe button could pay right now is [AdsApi.rewardedStatus](api-reference-game.md#adsapi-rewardedstatus).\n\nAbsent when your game declares none.",
+          "summary": "Your rewarded placements — what pressing a rewarded button grants. An\narray, one row per placement, each naming itself in `placement`, with its\n`grants`, the caps the platform enforces on it (`max_per_day`,\n`cooldown_seconds`, `max_held`) and what happens where no ad serves\n(`without_ads`, which is `nothing` when the config leaves it out).\n\nRead it to LABEL your button — \"+1 Revive\" — never to decide a reward. A\ngrant is an `item_grant`, with a `quantity` of the item its\n`item_definition_id` names, or a `currency_grant`, with an `amount` of the\ncurrency its `currency_id` names; the word on the button is that\ndefinition's `display_name`, from [GameConfig.item](api-reference-game.md#gameconfig-item) or\n[GameConfig.currency](api-reference-game.md#gameconfig-currency):\n\n```js\nconst row = config?.rewarded_placements?.find((p) => p.placement === 'classic_revive');\nconst grant = row?.grants[0];\nconst label =\n  grant?.type === 'item_grant'\n    ? `+${grant.quantity} ${config.item(grant.item_definition_id)?.display_name ?? ''}`\n    : grant?.type === 'currency_grant'\n      ? `+${grant.amount} ${config.currency(grant.currency_id)?.display_name ?? ''}`\n      : undefined;\n```\n\nWhether an ask grants anything is the platform's decision, made against\nthis config server-side; the grant lands on your game's inventory, and\nre-reading `gem.me.inventory` is the only way to learn that it did. Whether\nthe button could pay right now is [AdsApi.rewardedStatus](api-reference-game.md#adsapi-rewardedstatus).\n\nA row may also carry `platform_prices`, the Coin and Gem prices that unlock\nit beside the ad, and `ad: false` when only a price does (`ad` is absent\notherwise, which means the ad unlocks it). Both are what you declared, not\nwhat is offered now: label the button from `rewardedStatus`'s\n`adGrantable` and `options`, which say what this platform serves.\n\nAbsent when your game declares none.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -4170,7 +4170,7 @@
           "group": "ads",
           "signature": "rewardedStatus(placement: string): Promise<RewardedStatus>",
           "documented": true,
-          "summary": "Whether a rewarded placement could pay right now, so you can decide whether\nto draw its button. **It never says whether an ad will play.**\n\nThe answer comes from your own `rewarded_placements` config — its daily\ncap, cooldown and `max_held` — applied to this player's use of it, as the\nplatform holds them. Nothing in it describes the player. `grantable: true`\nmeans the platform would grant if an ad is watched or, where no ad serves,\nunder the placement's `without_ads: grant`; a player can still press the\nbutton and get `no_ad`, for reasons your game is not told.\n\nNOTHING REJECTS, like everything else on `gem.ads`. Without a play token,\nwhen the read fails or takes longer than ten seconds, or for a `placement`\noutside the grammar [AdRequest.placement](api-reference-game.md#adrequest-placement) documents, it resolves not\ndeclared and not grantable, with no `resetsAt`, and the reason goes to your\n`onError` handler.\n\nIt is a read of the platform, so call it when you draw the button — on a\nresults or death screen — not every frame. Calls for one placement that\noverlap share one request. Draw the rest of the screen first rather than\nholding it on this answer.\n\n⚠️ It grants nothing and reserves nothing. The reward is granted by the\nplatform when the player asks with `requestAd`; re-read `gem.me.inventory`\nafter that ask settles, whatever it settled as.",
+          "summary": "Whether a rewarded placement could pay right now, so you can decide whether\nto draw its button. **It never says whether an ad will play.**\n\nThe answer comes from your own `rewarded_placements` config — its daily\ncap, cooldown and `max_held` — applied to this player's use of it, as the\nplatform holds them. Nothing in it describes the player. `grantable: true`\nmeans the platform would grant if an ad is watched or, where no ad serves,\nunder the placement's `without_ads: grant`; a player can still press the\nbutton and get `no_ad`, for reasons your game is not told.\n\nA placement your config also prices in Coins or Gems (`platform_prices`)\ncarries those prices in `options`, where the platform lets players pay for\none, and `adGrantable` says whether the ad itself could pay. Label your\nbutton from both: name the ad only when `adGrantable` is `true`, and each\nprice in `options`. The Arcade then shows the player those choices when\nthey press, and the press answers and is re-read exactly as an ad's is.\n\nNOTHING REJECTS, like everything else on `gem.ads`. Without a play token,\nwhen the read fails or takes longer than ten seconds, or for a `placement`\noutside the grammar [AdRequest.placement](api-reference-game.md#adrequest-placement) documents, it resolves not\ndeclared and not grantable, with no `resetsAt`, and the reason goes to your\n`onError` handler.\n\nIt is a read of the platform, so call it when you draw the button — on a\nresults or death screen — not every frame. Calls for one placement that\noverlap share one request. Draw the rest of the screen first rather than\nholding it on this answer.\n\n⚠️ It grants nothing and reserves nothing. The reward is granted by the\nplatform when the player asks with `requestAd`; re-read `gem.me.inventory`\nafter that ask settles, whatever it settled as.",
           "deprecated": null,
           "params": [
             {
@@ -4191,6 +4191,70 @@
             }
           ]
         },
+        {
+          "id": "RewardedOption",
+          "name": "RewardedOption",
+          "anchor": "rewardedoption",
+          "group": "ads",
+          "signature": "interface RewardedOption",
+          "documented": true,
+          "summary": "One price that also unlocks a rewarded placement, in\n[RewardedStatus.options](api-reference-game.md#rewardedstatus-options): what your config's `platform_prices` set for\nit, as the platform serves it. Label your button from it (\"5 Gems\").\n\nIt says nothing about the player: not their balance, and not whether they\ncan afford it. The Arcade shows them that when they press.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedOption.kind",
+          "name": "kind",
+          "anchor": "rewardedoption-kind",
+          "group": "ads",
+          "signature": "readonly kind: \"coins\" | \"gems\"",
+          "documented": true,
+          "summary": "Which platform currency: `coins` (Coins, `ARCADE_TICKETS`) or `gems`\n(Gems, `GEMS`).",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedOption.currencyId",
+          "name": "currencyId",
+          "anchor": "rewardedoption-currencyid",
+          "group": "ads",
+          "signature": "readonly currencyId: string",
+          "documented": true,
+          "summary": "The platform currency's id, as your config's `platform_prices` resolved it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedOption.price",
+          "name": "price",
+          "anchor": "rewardedoption-price",
+          "group": "ads",
+          "signature": "readonly price: number",
+          "documented": true,
+          "summary": "The price, a positive whole number of the currency.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "RewardedStatus",
           "name": "RewardedStatus",
@@ -4230,7 +4294,39 @@
           "group": "ads",
           "signature": "readonly grantable: boolean",
           "documented": true,
-          "summary": "Whether pressing your button could pay right now: the platform would grant\nthe reward if an ad is watched or, where no ad serves, under the\nplacement's `without_ads: grant`.\n\n**Not a promise that an ad will play, and not a promise of a reward.** It\nis `false` whenever a cap is spent, a cooldown is running, the player holds\n`max_held`, rewarded is off on this channel, or the arcade running your\ngame does not take ad requests at all.",
+          "summary": "Whether pressing your button could pay right now: the platform would grant\nthe reward if an ad is watched or, where no ad serves, under the\nplacement's `without_ads: grant` — or, where [RewardedStatus.options](api-reference-game.md#rewardedstatus-options)\nis present, if the player pays one of its prices.\n\n**Not a promise that an ad will play, and not a promise of a reward.** For\nthe ad, it is `false` whenever a cap is spent, a cooldown is running, the\nplayer holds `max_held`, rewarded is off on this channel, or the arcade\nrunning your game does not take ad requests at all. The cap, the cooldown\nand `max_held` limit the ad only: a placement with `options` stays\ngrantable through them, because the player can still pay. It never says\nwhether the player can afford a price.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.adGrantable",
+          "name": "adGrantable",
+          "anchor": "rewardedstatus-adgrantable",
+          "group": "ads",
+          "signature": "readonly adGrantable: boolean",
+          "documented": true,
+          "summary": "Whether the AD could pay right now: [RewardedStatus.grantable](api-reference-game.md#rewardedstatus-grantable) for\nthe ad alone, leaving out the prices. Name the ad on your button only when\nthis is `true`.\n\nThe same as `grantable` for a placement with no `options`. `false` for a\nplacement whose config switches the ad off (`ad: false`) where the\nplatform lets players pay for it, and on every answer where `grantable` is.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "RewardedStatus.options",
+          "name": "options",
+          "anchor": "rewardedstatus-options",
+          "group": "ads",
+          "signature": "readonly options?: readonly RewardedOption[]",
+          "documented": true,
+          "summary": "The Coin and Gem prices that also unlock the placement, from your config's\n`platform_prices`, at most one per currency.\n\nABSENT — no key — for a placement with no prices, on any answer where\n`declared` is `false`, and wherever the platform does not yet let players\npay for a placement: there your prices are not offered and the placement\nunlocks by its ad alone. Nothing here says what the player holds.",
           "deprecated": null,
           "params": [],
           "returns": null,

package/docs/changelog.md

@@ -16,6 +16,18 @@ Its entries are grouped under up to five headings:
 - **Rebuild**: a type changed. Recompile against the new version; code that compiles today keeps compiling unless the entry says otherwise.
 - **New capability**: something a game can now do. Nothing changes unless you use it.
 
+## 23.2.0
+
+*Written from the API facts alone; no summary was generated for this release.*
+
+Upgrading from 23.1.3. Impact: none.
+
+### New capability
+
+- RewardedOption was added.
+- RewardedStatus.adGrantable was added.
+- RewardedStatus.options was added.
+
 ## 23.1.3
 
 Upgrading from 23.1.2. Impact: none.

package/docs/getting-started.md

@@ -50,7 +50,7 @@ either way.
 ```jsonc
 // package.json
 "dependencies": {
-  "@indiegems/gem-web-sdk": "23.1.3"
+  "@indiegems/gem-web-sdk": "23.2.0"
 }
 ```
 

package/docs/manifest.json

@@ -48,8 +48,8 @@
     },
     {
       "file": "changelog.md",
-      "sha256": "e6195c6d12e52535a21a4a3291268a82a445b85e6a76f0049b981ff9ab374232",
-      "updated": "2026-11-09T03:45:00Z"
+      "sha256": "819160e36c0258c34aa3e8b06ea0f1e26a50bcc83c5919780de2b33f4fac1cd9",
+      "updated": "2026-11-09T16:19:51Z"
     },
     {
       "file": "daily-challenges.md",
@@ -78,8 +78,8 @@
     },
     {
       "file": "getting-started.md",
-      "sha256": "aaed9165f80ea79b32eae8509dc2ef0af436b3e3df1d23cac30941c8268ee022",
-      "updated": "2026-11-09T03:45:00Z"
+      "sha256": "763113c6da4ae1d154ba655e44e87f32912a66ea7db40a61dca9c17f51fcc234",
+      "updated": "2026-11-09T16:19:51Z"
     },
     {
       "file": "graphics-route.md",
@@ -123,8 +123,8 @@
     },
     {
       "file": "rewarded-ads.md",
-      "sha256": "81b421d4bde3f71b40c7a5a173e6a2c114a315215a11491e488872ff9e1909dc",
-      "updated": "2026-11-07T16:40:01Z"
+      "sha256": "f632d54aa605b34dc071b59d49e7ecfd35ab95eb6f601885ceb0d3d6fc41a949",
+      "updated": "2026-11-09T15:28:20Z"
     },
     {
       "file": "room-shapes.md",
@@ -143,8 +143,8 @@
     },
     {
       "file": "server-bundles.md",
-      "sha256": "3274318b99daed546ee192381e40962c9e1e62436cbf4edfb61340548d6dc493",
-      "updated": "2026-11-09T03:45:00Z"
+      "sha256": "b712e407e79482f1edc596ebcaab00852429fbaacebb05d04a2a2f9cbe1f5b9c",
+      "updated": "2026-11-09T16:19:51Z"
     },
     {
       "file": "serverless-functions-js.md",

package/docs/rewarded-ads.md

@@ -111,6 +111,8 @@ rewarded_placements:
 | `max_held`                | No grant while the player already holds at least this many of the granted item. 1 to 100, and only on a placement whose grants are all items.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `without_ads`             | **Optional:** `grant` or `nothing`, and `nothing` when you leave it out. What a press gets when no ad plays: where no ad serves your channel at all, and where one does but no ad was available for this press or it failed to play (§8). `grant` pays the reward with no ad, within your caps, so write it out only for a reward that is fine to give free.                                                                                                                                                                                                                  |
 | `allowance_currency_slug` | Optional: one of your own currencies that each grant also spends 1 of. Use it when another path in your game must share the same daily cap. It must not be `client_writable` and must have `transfer_policy: none`. A grant is refused while it is empty (§3). ⚠️ For an allowance your game grants per use, put it in a bucket that never resets (`reset_interval: never`) for now, even though the upload warns `rewarded_placement_allowance_no_reset` (below).                                                                                                            |
+| `ad`                      | **Optional:** `true` or `false`, and `true` when you leave it out. Whether watching an ad unlocks the placement. Write `false` only beside `platform_prices`, for a placement a price alone unlocks.                                                                                                                                                                                                                                                                                                                                                                          |
+| `platform_prices`         | **Optional:** Coin and Gem prices that also unlock the placement, beside the ad or instead of it, written as an item's prices are. Leave it out for none. See [Coins and Gems beside the ad](#coins-and-gems-beside-the-ad), below.                                                                                                                                                                                                                                                                                                                                           |
 
 ⚠️ **Until a gem-api fix ships, an allowance in a resetting bucket refuses a player's first
 press.** A grant that creates the player's balance of the allowance currency is not stamped with
@@ -170,6 +172,60 @@ pays without one. If both said `grant`, the bigger reward would cost the player
 everyone would press that button. Leaving it out of the bigger one, which is `nothing`, keeps it a
 reward for watching.
 
+### Coins and Gems beside the ad
+
+A placement can also be unlocked for the player's **Coins** (`ARCADE_TICKETS`) or **Gems** (`GEMS`),
+beside its ad or instead of it. Give it `platform_prices`, the same shape an item's prices take,
+at most one per currency, each a positive whole number:
+
+```yaml
+rewarded_placements:
+  - placement: classic_revive
+    grants:
+      - { type: item_grant, item_definition_slug: revive_token, quantity: 1 }
+    max_per_day: 5 # limits the ad only
+    platform_prices:
+      - { currency: ARCADE_TICKETS, price: 50 } # 50 Coins
+      - { currency: GEMS, price: 5 } # 5 Gems
+  - placement: skip_level
+    grants:
+      - { type: item_grant, item_definition_slug: level_skip, quantity: 1 }
+    ad: false # a price alone unlocks this one
+    platform_prices:
+      - { currency: GEMS, price: 10 }
+```
+
+Your game asks exactly as it does for an ad: `requestAd` from the press (§3), then re-read your
+inventory. The Arcade, not your game, shows the player the choices that press has: a chooser when
+there are several, such as **Watch an ad**, **50 Coins** and **5 Gems**, or a confirmation when a
+price is the only one. A price the player cannot afford is shown but cannot be picked. Paying takes
+the price from the player's wallet and grants the reward in one step: never the reward without the
+payment, never charged twice, and the payment given back if the reward cannot be granted. Nothing
+is bought with real money here. The answer is `shown` whenever the Arcade put a choice up, whatever
+the player then did, so **branch on your inventory, never on the outcome**, as for an ad.
+
+- **Your caps limit the ad only.** `max_per_day`, `cooldown_seconds`, `max_held` and
+  `allowance_currency_slug` decide when the ad can pay. The prices stay on offer when the ad
+  cannot, and a paid unlock does not count toward them. Only the player's balance limits how often
+  they pay, so price the reward for that. The grant still refuses a reward that would not fit
+  (a full stack, say), and the payment is then given back.
+- **Not with `without_ads: grant`,** which would give the reward free and make the price pointless.
+  The upload refuses it, and `ad: false` with no `platform_prices` too, since then nothing unlocks
+  the placement.
+- **Each currency's spend scope applies,** as it does to an item's price
+  ([`inventory-and-catalogs.md`](inventory-and-catalogs.md#what-coins-and-gems-may-buy-the-spend-scope)):
+  where Coins may price cosmetics only, a Coin price on a placement that grants anything else is
+  refused. Gems may price any placement. `gemctl platform config` lists which currencies your
+  game may price in, and each one's spend scope: author against it, never against a list you
+  remember.
+- **A placement's own prices do not make its reward "sold for a platform currency"** in §1's sense,
+  so the ad keeps serving beside them as it did before.
+
+⚠️ **The upload warns `rewarded_paid_unlocks_not_live` while the platform does not let players pay
+for a placement yet.** Until then your prices are not offered, the placement unlocks by its ad
+alone, `ad: false` included, and `rewardedStatus` carries no `options` (§5). Nothing in your game
+needs to change when it goes live: draw the button from `rewardedStatus` and it follows.
+
 ## 3. Ask from the press, then re-read
 
 ```js
@@ -342,14 +398,32 @@ const status = await gem.ads.rewardedStatus('classic_revive');
 watchAdButton.hidden = !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       |
+**For a placement with prices** (§2), `grantable` is `true` when the ad could pay **or** a price
+could, so the button stays up through the ad's caps. Label it from the answer: name the ad only
+when `adGrantable` is `true`, and each price in `options`, whose `kind` is `coins` or `gems`.
+Neither says what the player holds; the Arcade shows that when they press. Both are in SDK
+releases after 23.1.3.
+
+```js
+const status = await gem.ads.rewardedStatus('classic_revive');
+const ways = [
+  ...(status.adGrantable ? ['watch an ad'] : []),
+  ...(status.options ?? []).map((o) => `${o.price} ${o.kind === 'coins' ? 'Coins' : 'Gems'}`),
+];
+reviveButton.textContent = `Revive: ${ways.join(' or ')}`; // "Revive: watch an ad or 5 Gems"
+reviveButton.hidden = !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                     |
+| `adGrantable`      | the ad itself could pay right now: `grantable` without the prices                          |
+| `options`          | the Coin and Gem prices on offer, each `{ kind, currencyId, price }`; absent when none are |
+| `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                       |
 
 Without a play token, when the read fails or takes longer than ten seconds, or for a placement
 outside the grammar, it answers not declared and not grantable with no `resetsAt`, and the reason

package/docs/server-bundles.md

@@ -80,8 +80,8 @@ To check the download yourself: the package npm serves is, byte for byte, the fi
 also publishes on its download host, with the hash beside it:
 
 ```bash
-curl -fsSL -O https://downloads.gemarcade.com/sdk/v23.1.3/gem-web-sdk.tgz
-curl -fsSL https://downloads.gemarcade.com/sdk/v23.1.3/gem-web-sdk.tgz.sri
+curl -fsSL -O https://downloads.gemarcade.com/sdk/v23.2.0/gem-web-sdk.tgz
+curl -fsSL https://downloads.gemarcade.com/sdk/v23.2.0/gem-web-sdk.tgz.sri
 openssl dgst -sha384 -binary gem-web-sdk.tgz | openssl base64 -A
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indiegems/gem-web-sdk",
-  "version": "23.1.3",
+  "version": "23.2.0",
   "description": "postMessage bridge contract between gem-web and browser-playable games",
   "license": "UNLICENSED",
   "type": "module",