@indiegems/gem-web-sdk 7.1.0 → 7.1.1

package/schema/bridge.v1.json

@@ -2318,14 +2318,20 @@
         "the following is not offering a degraded store, it is offering a game a",
         "button that charges a player:",
         "",
-        "  EARNED CURRENCIES ONLY. `currencySlug` is frame-chosen and this schema does",
-        "  not constrain which currency it names. The argument that unblocked shipping",
-        "  this without a top-up flow binds a currency a player EARNS - short of",
-        "  Gems, the answer is to go and play. It does not bind one they BUY. Check",
-        "  the requested currency against a server-side allowlist of earnable",
-        "  currencies and refuse the rest; on the day an item carries a price in both",
-        "  Gems and Coins, an unchecked slug lets the frame choose which wallet to",
-        "  drain, and the safety argument lapses with no code change and no review.",
+        "  PAYABLE, EARNED CURRENCIES ONLY. `currencySlug` is frame-chosen and this",
+        "  schema does not constrain which currency it names. The argument that let",
+        "  this ship without a top-up flow binds a currency a player EARNS: short of",
+        "  Gems or Tickets the answer is to go and play, and neither is sold for",
+        "  money. It does not bind a currency a player BUYS. So resolve the slug",
+        "  against the platform's own currency records - an active currency the",
+        "  platform marks payable in games - and refuse the rest, `declined` with",
+        "  `unknown_currency` or `currency_not_in_game_payable`. Resolve it EXACTLY,",
+        "  with no",
+        "  alias table of your own: the retired `TICKETS` meant GEMS, and resolving",
+        "  it charged Gems to games that meant Tickets. An item may carry prices in",
+        "  more than one payable currency, so",
+        "  the frame does choose which wallet pays; the prompt names that currency",
+        "  and its price from platform records, which keeps the choice the player's.",
         "",
         "  THE FRAME CHOOSES THE AMOUNT. Not the unit price - but `targetId` x",
         "  `currencySlug` x `quantity` is nevertheless the total, up to ten times the",
@@ -2333,12 +2339,26 @@
         "  price, quantity and total distinctly so a 10x multiplier is never hidden",
         "  behind one figure.",
         "",
+        "  ONLY ON USER ACTIVATION. Render nothing, and answer `declined` with",
+        "  reason `busy`, unless `navigator.userActivation.isActive` is true when",
+        "  the ask arrives. A click or key press in the game frame activates the",
+        "  parent page too, so a Buy button works and a timer does not. It is the",
+        "  browser's own signal, so keyboard and assistive-technology activation",
+        "  count. This is the control that makes `cancelled` (gem.purchaseResult)",
+        "  safe to disclose: a prompt costs a real player's gesture.",
+        "",
+        "  BACK OFF AFTER A CANCEL. After a `cancelled`, answer further asks from",
+        "  that game `declined` / `busy` without rendering, for an interval that",
+        "  grows with each consecutive cancel. Without it, 'ask, learn cancelled,",
+        "  ask again' is a re-prompt loop a game can write in three lines.",
+        "",
         "  ONE PROMPT AT A TIME, and not instantly actionable. A gem.requestPurchase",
-        "  arriving while a prompt is open is answered `declined` without rendering",
-        "  anything. Twelve modals a minute is inside the rate limit below and is a",
-        "  successful consent-fatigue attack; and because the frame chooses the moment",
-        "  it asks, a confirm control that is actionable the instant it paints is a",
-        "  tap-jacking target - quiet input on it briefly after paint.",
+        "  arriving while a prompt is open is answered `declined` / `busy` without",
+        "  rendering anything. Twelve modals a minute is inside the rate limit",
+        "  below and is a successful consent-fatigue attack; and because the frame",
+        "  chooses the moment it asks, a confirm control that is actionable the",
+        "  instant it paints is a tap-jacking target - quiet input on it briefly",
+        "  after paint.",
         "",
         "  ONE PURCHASE PER ASK. Each gem.requestPurchase is a distinct purchase and",
         "  carries its own idempotency key. Do NOT collapse repeated asks: a player",
@@ -2393,7 +2413,7 @@
         "currencySlug": {
           "kind": "string",
           "maxLength": 32,
-          "$comment": "Which platform currency to pay in, e.g. GEMS or ARCADE_TICKETS. The item must carry a price in it; the parent resolves that price itself and refuses when there is none. FRAME-CHOSEN AND UNCONSTRAINED HERE: nothing in this schema limits it to a currency the player earned rather than bought, so the parent checks it against a server-side earned-currency allowlist. See the EARNED CURRENCIES ONLY obligation above - this field is where that whole argument lands."
+          "$comment": "Which platform currency to pay in, by its exact slug: GEMS or ARCADE_TICKETS. The item must carry a price in it; the parent resolves that price itself and refuses when there is none (`no_price_in_currency`). There are no aliases: `TICKETS` is a retired name for GEMS and is answered `unknown_currency`, never resolved. FRAME-CHOSEN AND UNCONSTRAINED HERE: nothing in this schema limits it to a currency the player earned rather than bought, so the parent checks it against the platform's own currency records. See the PAYABLE, EARNED CURRENCIES ONLY obligation above - this field is where that whole argument lands."
         },
         "quantity": {
           "kind": "int",
@@ -2421,11 +2441,32 @@
       "$comment": [
         "The answer to one gem.requestPurchase. Gated by the `purchases` capability.",
         "",
-        "OUTCOME CARRIES NO REASON, and that is a control rather than an oversight.",
-        "Distinguishing 'the player said no' from 'the player could not afford it'",
-        "tells untrusted game code about the player's wallet, one purchase at a time -",
-        "a catalog priced on a 1/2/4/8 ladder recovers a balance to within one item",
-        "price, free. So a decline is a decline.",
+        "THREE OUTCOMES, AND A REASON ON THE TWO THAT ARE NOT `ok`. `outcome` says",
+        "what the game should DO;",
+        "`reason` says WHY, so a developer can fix a config mistake instead of",
+        "reading 'failed'. The mapping from condition to reason is normative and is",
+        "written on the `reason` field below.",
+        "",
+        "WHY THIS MESSAGE NOW CARRIES A REASON, WHEN IT USED TO FORBID ONE. The old",
+        "rule - no reason, 'no insufficient funds and there will not be one' -",
+        "protected the player's wallet from untrusted game code: a decline that",
+        "said 'could not afford' let a game walk a balance down a 1/2/4/8 price",
+        "ladder, one prompt at a time. Platform-currency access for games made that",
+        "wallet readable directly - `gem.platform.currencies.get()` hands a game",
+        "the exact balance of every active platform currency - and spendable",
+        "without a sheet through `gem.me.mutations.purchase`, whose refusals",
+        "already say `insufficient_funds`. The owner accepted that as risk M3",
+        "(2026-09-21). So `insufficient_funds` and the config-mistake reasons tell",
+        "a game nothing it cannot already read.",
+        "",
+        "THE ONE ADDED DISCLOSURE IS `cancelled`: what the player chose in",
+        "platform UI. It is behavioural data, and it is what makes an instant",
+        "re-prompt loop cheap - ask, learn 'cancelled', ask again. It ships with",
+        "two parent-side controls, stated as obligations on gem.requestPurchase:",
+        "ONLY ON USER ACTIVATION (no prompt without a real gesture) and BACK OFF",
+        "AFTER A CANCEL (further asks answered `busy`, unrendered, for a growing",
+        "interval). A parent that cannot enforce both must not send `cancelled`;",
+        "it sends `error` in its place.",
         "",
         "EVERY OUTCOME RESOLVES. Only a protocol failure rejects. A player tapping",
         "Cancel is an ordinary thing that happens in every shop, and rejecting there",
@@ -2436,16 +2477,21 @@
         "  ok          - the purchase completed and the grant is on the player's",
         "                game-scope inventory. Re-read inventory rather than assuming",
         "                what landed; `purchaseId` names the server's record of it.",
-        "  declined    - return to the shop SILENTLY. No dialog, no 'purchase failed'",
-        "                copy. The player already saw the prompt and answered it, and an",
+        "  declined    - a DEFINITE refusal before any debit. Return to the shop",
+        "                SILENTLY: no dialog, no 'purchase failed' copy. The player",
+        "                already saw the parent's answer where there was one, and an",
         "                error toast after a deliberate Cancel reads as a bug.",
-        "  unavailable - one neutral 'store unavailable'. Never auto-retried; only a",
-        "                fresh player action may ask again. AND RE-READ INVENTORY:",
-        "                'unavailable' means no answer arrived, not that nothing",
-        "                happened - the parent may have prompted, charged and",
-        "                answered while the answer was lost at a gate or a timeout.",
-        "                'declined' is the only outcome that says a purchase",
-        "                definitely did not happen."
+        "                `reason` is for the game's logs and shop state - grey out a",
+        "                `recipe_locked` row, fix an `unknown_currency` slug - never",
+        "                for a top-up or payment screen of the game's own.",
+        "  unavailable - no reliable answer. One neutral 'store unavailable'. Never",
+        "                auto-retried; only a fresh player action may ask again. AND",
+        "                RE-READ INVENTORY: 'unavailable' means no answer arrived,",
+        "                not that nothing happened - the parent may have prompted,",
+        "                charged and answered while the answer was lost at a gate or",
+        "                a timeout. A reason never makes it more certain. 'declined'",
+        "                is the only outcome that says a purchase definitely did not",
+        "                happen."
       ],
       "fields": {
         "requestId": {
@@ -2456,7 +2502,91 @@
         "outcome": {
           "kind": "enum",
           "values": ["ok", "declined", "unavailable"],
-          "$comment": "THREE VALUES, AND THAT IS THE COMPLETE VOCABULARY - there is no 'insufficient funds' and there will not be one. A reason would leak the wallet this message exists to keep private, and the top-up case is handled entirely in the parent's own chrome: a player short of currency is offered the route there and the game only ever sees 'declined'. So this set does not need to grow when Coins joins Gems, which matters because `check-schema-freeze` treats a new enum value as breaking (an N-1 receiver refuses it). THE VALUE IS NOT THE WHOLE CHANNEL, AND THE REST OF IT IS DELIBERATELY NOT DEFENDED. A refusal the parent reaches without rendering anything is separable from a human Cancel by latency, so a game can learn 'could not afford' from timing even though no reason is sent. That is accepted rather than mitigated: every probe costs the attacker a prompt a real person has to look at and dismiss, so the oracle runs at human speed, in the open, against an EARNED in-game balance that is not a secret, a credential or money - and a game that spams purchase prompts to read it is a game players close. An earlier revision of this comment promised a quantised emission schedule; nothing implemented it, and a contract that names a control nobody built is worse than one that admits the gap. Parents: do not infer from this that you may send a reason. The enum stays closed at three, because that much is free."
+          "$comment": "THREE VALUES, AND THAT IS THE COMPLETE VOCABULARY OF WHAT TO DO. The WHY is `reason`, a bounded string, so the explanations can grow without this enum growing - which matters because `check-schema-freeze` treats a new enum value as breaking (an N-1 receiver refuses it, and a refused `declined` becomes a two-minute timeout and an `unavailable`). A game branches its money logic on this field and on a re-read of inventory, never on `reason`. THE TIMING CHANNEL: a refusal the parent reaches without rendering anything is separable from a human Cancel by latency. That used to be the gap the no-reason rule left open; with `reason` sent, it tells a game nothing `reason` and `gem.platform.currencies.get()` do not already say. What still matters is how fast a game can ask, and user activation plus the cancel back-off bound that at human speed."
+        },
+        "reason": {
+          "kind": "string",
+          "maxLength": 64,
+          "format": "code",
+          "optional": true,
+          "$comment": [
+            "WHY a purchase did not complete. Sent ONLY with `declined` and",
+            "`unavailable`, never with `ok`; a receiver ignores one on `ok`. OPTIONAL:",
+            "a parent that predates it sends none, and a receiver reads an absent",
+            "reason as `error`.",
+            "",
+            "A BOUNDED STRING, NOT AN ENUM, deliberately. An enum here would be closed",
+            "for good: `check-schema-freeze` refuses an added value, and an older SDK",
+            "validating a new one refuses the WHOLE message, turning a `declined` into a",
+            "two-minute timeout and an `unavailable`. `format: code` is `^[a-z_]+$`, so",
+            "with the bound this is `^[a-z_]{1,64}$`: a machine code, never prose or",
+            "markup. Precedent: gem.exit's `reason`. A receiver maps a value it does not",
+            "know to `error`, so a new code costs an old game an `error`, not a hang.",
+            "",
+            "ONE VOCABULARY FOR BOTH PURCHASE PATHS. The value equals the `code` the",
+            "game gets from `gem.me.mutations.purchase` for the same refusal, so a game",
+            "handles both with one switch. gem-api's purchase wire codes pass VERBATIM;",
+            "`unknown_currency`, `no_price_in_currency`, `busy`, `cancelled` and `error`",
+            "are the parent's (and the SDK's) own. `currency_not_in_game_payable` and",
+            "`not_purchasable` are gem-api's, which a parent may also detect first.",
+            "",
+            "THE MAPPING IS NORMATIVE, AND IT IS AN ALLOW-LIST. A parent sends exactly",
+            "these. Anything it meets that is not listed is sent as `error`, never",
+            "forwarded - so a new gem-api code, a detail field or an account state",
+            "cannot leak through by default:",
+            "",
+            "  CONDITION                                   OUTCOME      REASON",
+            "  the slug is not an active platform          declined     unknown_currency",
+            "    currency - including the retired TICKETS",
+            "  the currency is not payable in games        declined     currency_not_in_game_payable",
+            "  the target is not in the purchase catalog,  declined     not_purchasable",
+            "    or is not purchasable",
+            "  the target has no price in that currency    declined     no_price_in_currency",
+            "  a sheet is already open, a purchase is in   declined     busy",
+            "    flight, a cancel back-off is running, or",
+            "    the ask arrived without user activation",
+            "  the player dismissed a sheet they could     declined     cancelled",
+            "    afford",
+            "  a shortfall shown on the sheet, or gem-api  declined     insufficient_funds",
+            "    400 insufficient_funds",
+            "  gem-api price_mismatch or                   declined     the code, verbatim",
+            "    config_version_stale (both refused",
+            "    before any debit)",
+            "  gem-api platform_currency_unavailable       declined     the code, verbatim",
+            "  gem-api not_available (the recipe is        declined     the code, verbatim",
+            "    outside its availability window, or",
+            "    inactive)",
+            "  gem-api recipe_locked                       declined     recipe_locked - the",
+            "                                                           CODE ONLY; the",
+            "                                                           response's",
+            "                                                           details.lock_reasons",
+            "                                                           is never forwarded",
+            "  gem-api recipe_on_cooldown,                 declined     the code, verbatim",
+            "    recipe_max_uses_exceeded,",
+            "    item_max_stack_exceeded,",
+            "    recipe_costs_unmet, quantity_invalid",
+            "  gem-api confirmation_required               -            NEVER REACHES THE",
+            "                                                           GAME: the parent",
+            "                                                           handles it itself,",
+            "                                                           because it reveals",
+            "                                                           the player's age",
+            "  gem-api 429 (its limiter is per IP, so it   declined     error",
+            "    would describe other people's activity),",
+            "    403, nonce conflicts, and every account",
+            "    state - sanction, age, region",
+            "  5xx, a network failure, a timeout, an `ok`  unavailable  error, or absent",
+            "    the frame could not verify, and a charge",
+            "    whose refund failed",
+            "",
+            "`declined` is for a definite refusal before any debit; a parent that",
+            "answers such a refusal `unavailable` is wrong, because `unavailable` means",
+            "'no reliable answer'. A reason never makes `unavailable` more certain: the",
+            "game re-reads inventory after it, whatever the reason says.",
+            "",
+            "ADVISORY, AND NO DEFENCE AGAINST A HOSTILE PARENT. A lying parent can",
+            "mislead a game's copy, never its ledger: games branch money on `outcome`",
+            "and on inventory, and the SDK never retries because of a reason."
+          ]
         },
         "purchaseId": {
           "kind": "string",