@indiegems/gem-web-sdk 6.0.0 → 7.1.0

package/package.json

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

package/schema/bridge.v1.json

@@ -583,6 +583,80 @@
           "format": "url",
           "optional": true,
           "$comment": "LEGACY — the earlier spelling of `avatarIconUrl`, and the same value. Same pin caveat. A current frame reads it only when `avatarIconUrl` is absent."
+        },
+        "boost": {
+          "kind": "object",
+          "optional": true,
+          "$comment": [
+            "The player's Boost, FOR DISPLAY ONLY — a platform rule, not advice. A",
+            "Boost is the Arcade's one real-money product: it",
+            "multiplies what the player EARNS in platform currencies (Gems and",
+            "Tickets) and raises their earning limits. It never touches achievement",
+            "points.",
+            "",
+            "ADVISORY. It may lag: it is pushed on connect and again when the",
+            "parent's copy changes, never on the instant a boost starts or ends. The",
+            "platform applies the real multiplier server-side when it pays, whatever",
+            "a game renders. A game may SHOW it — a \"2x\" badge on a reward screen —",
+            "and must never gate content, difficulty, matchmaking, prices or power on",
+            "it. It is also trivially forgeable inside the game's own realm, which is",
+            "the second reason nothing may key on it.",
+            "",
+            "Platform-assigned numbers only, so it sits on the trusted side of the",
+            "`untrusted` split: currency ids and slugs, multipliers, a day count. NO",
+            "tier, SKU, price, source (paid, comp, trial) or instant: free and paid",
+            "boosts look identical to a game, and `expiresInDays` is whole days",
+            "rounded up because a second-precision expiry is a near-unique",
+            "per-player value two games could join on to link a player's two",
+            "game-scoped identities.",
+            "",
+            "ABSENT MEANS THE PARENT DID NOT SAY — an older parent, a backend without",
+            "boosts, or a read that has not landed. A frame reads absence as 1x",
+            "everywhere, which is also what an unboosted player's message says.",
+            "",
+            "Additive and optional, so no `v` bump, and ungated like the rest of",
+            "`gem.player`: no capability, because a frame that ignores the field",
+            "loses nothing but a badge."
+          ],
+          "fields": {
+            "multipliers": {
+              "kind": "array",
+              "maxItems": 8,
+              "$comment": "One entry per boostable platform currency the parent knows of, in the parent's display order. `multiplierBp` is basis points: 10000 is 1x (not boosted), 20000 is 2x. A currency missing from the list is 1x. A parent drops an entry it cannot fit in these bounds rather than losing the whole message to it.",
+              "items": {
+                "kind": "object",
+                "fields": {
+                  "currencyId": { "kind": "string", "maxLength": 64 },
+                  "currencySlug": {
+                    "kind": "string",
+                    "maxLength": 32,
+                    "$comment": "The currency's slug, e.g. GEMS or ARCADE_TICKETS — the same slug `gem.rewardCue` and `gem.requestPurchase` take."
+                  },
+                  "multiplierBp": { "kind": "int", "min": 10000, "max": 1000000 }
+                }
+              }
+            },
+            "expiresInDays": {
+              "kind": "int",
+              "min": 1,
+              "max": 7,
+              "optional": true,
+              "$comment": [
+                "Whole days until the SOONEST multiplied currency drops back, rounded up",
+                "so a boost with any time left reads at least 1, and CAPPED AT 7: 7 means",
+                "\"7 or more\". Absent when no currency is multiplied. A count of days,",
+                "never an instant.",
+                "",
+                "THE CAP IS A PRIVACY BOUND, not a display choice. An exact count lets a",
+                "game watch it jump by a purchase's term (30 days) and infer that the",
+                "player just paid, and when. Capped, a boost with more than a week left",
+                "looks the same whether it was bought yesterday or a month ago. The",
+                "player's own account surfaces keep the exact figure; only what crosses",
+                "here is capped, and a parent clamps rather than letting a larger value",
+                "cost the frame the whole message."
+              ]
+            }
+          }
         }
       },
       "rateLimit": { "perMinute": 12 }
@@ -2104,11 +2178,22 @@
         "player's one real wallet (gem-api's rule), so a cue confirms the same",
         "way everywhere; a grant the receipt reports suppressed confirms nothing.",
         "",
+        "AT THE DAILY MAXIMUM the platform trims a grant to what is left of the",
+        "player's day across all games, down to 0 once it is spent, and sends the",
+        "parent `platform_daily_maximum_reached`. A parent resolves a cue it holds",
+        "then into its own \"daily max\" state rather than letting it fade, and",
+        "tells the player itself. That event is the player's, never relayed into",
+        "the frame: the game learns nothing from it, and needs to do nothing",
+        "differently.",
+        "",
         "Gated by `rewardCue`: sent only to a parent that advertised it; to any",
         "other, `gem.cueReward` returns false and the game does NOTHING. There is",
         "no fallback celebration: Gems display belongs to the arcade (the",
         "creator's ruling, 2026-09-24), so a game draws no Gems flight, counter or",
-        "celebration of its own. `origin` is the centre of the game's Gems icon."
+        "celebration of its own. The same holds for Tickets (`ARCADE_TICKETS`): the",
+        "arcade's wallet shows Gems and Tickets side by side and flies a payout",
+        "into the one `currencySlug` names. `origin` is the centre of the game's icon for",
+        "that currency — its gem, or its ticket."
       ],
       "fields": {
         "currencySlug": { "kind": "string", "maxLength": 32 },
@@ -2308,7 +2393,7 @@
         "currencySlug": {
           "kind": "string",
           "maxLength": 32,
-          "$comment": "Which platform currency to pay in, e.g. GEMS. 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, 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."
         },
         "quantity": {
           "kind": "int",