@indiegems/gem-web-sdk 21.1.1 → 23.0.0

package/schema/bridge.v1.json

@@ -1222,6 +1222,44 @@
       "rateLimit": { "perMinute": 30 }
     },
 
+    {
+      "type": "gem.inventoryChanged",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "Something in this player's inventory for THIS game and channel MAY have",
+        "changed on the server, so the frame should re-read it with its own",
+        "token if it shows it. Gated on `inventoryChanged`: a parent sends it",
+        "only when `frameSupports('inventoryChanged')`.",
+        "",
+        "NO FIELDS, AND IT SHOULD STAY THAT WAY. The frame re-reads its own",
+        "scope from gem-api, the authority, so the bridge never becomes a second",
+        "source of truth for a balance or an item. This message never carries",
+        "an item, a quantity, a balance, an order, an entity, a source or any",
+        "game's id: it says only that a change happened, around now.",
+        "",
+        "WHEN A PARENT MAY SEND IT: on gem-api's `game_inventory_changed` socket",
+        "event, only when its `game_id` is the game this session's token was",
+        "granted for and its `channel` is that token's channel, and only after",
+        "that token was sent. NEVER for another game's scope, another channel's,",
+        "or the platform wallet (`platform_grant_fired` and the other wallet",
+        "events): that send would tell this game, to the second, when another",
+        "game or the platform paid the player -- a timing oracle for payouts",
+        "this game is otherwise never shown. Nothing from the socket event's",
+        "payload is copied. It should coalesce a burst -- one send now, then at",
+        "most one trailing send every two seconds -- so a function that grants",
+        "in a loop stays inside the limit.",
+        "",
+        "A HINT, NOT A RECEIPT. A game that granted through its own function",
+        "already has the function's answer, which is the receipt; this is the",
+        "cue to redraw from a fresh read. An embedder that never sends it is not",
+        "defective. The SDK drops its cached reads of the game's inventory and",
+        "makes no request because of it."
+      ],
+      "fields": {},
+      "rateLimit": { "perMinute": 30 }
+    },
+
     {
       "type": "gem.viewport",
       "direction": "parentToFrame",
@@ -2947,10 +2985,24 @@
         "creator's ruling, 2026-09-24), so a game draws no Gems flight, counter or",
         "celebration of its own. The same holds for Coins (`ARCADE_TICKETS`):",
         "`currencySlug` decides what flies and which total moves. `origin` is the",
-        "centre of the game's icon for that currency — its gem, or its coin."
+        "centre of the game's icon for that currency — its gem, or its coin.",
+        "",
+        "`cueId` ties this cue to the grant it announces, so the arcade flies that",
+        "reward ONCE whichever of the two reaches it first. The game chooses it —",
+        "one `crypto.randomUUID()` per award — and passes the same one to the",
+        "`gem.functions.invoke` that pays, which carries it to gem-api as the",
+        "`cue_id` query parameter; gem-api echoes it as `cue_id` on every",
+        "`platform_grant_fired` that invocation's grants send. Opaque and for",
+        "animation only: it moves no balance, never names an order, and is never",
+        "rendered. The SDK sends only 1 to 64 letters, digits, `_` or `-`; the",
+        "wire bounds the length alone (no `format`, so a parent need not learn",
+        "one), and a parent that compares it rechecks the characters itself and",
+        "drops a malformed one, keeping the cue. Absent, the arcade pairs the cue",
+        "and the grant by currency and timing, as before."
       ],
       "fields": {
         "currencySlug": { "kind": "string", "maxLength": 32 },
+        "cueId": { "kind": "string", "maxLength": 64, "optional": true },
         "expected": { "kind": "int", "min": 1, "max": 1000000000, "optional": true },
         "origin": {
           "kind": "object",
@@ -2964,6 +3016,59 @@
       "rateLimit": { "perMinute": 60 }
     },
 
+    {
+      "type": "gem.rewardPresentation",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Who decides WHEN a platform-currency payout from this game is shown landing:",
+        "the arcade (`arcade`, what a parent does with no message at all) or the game",
+        "(`game`). It changes the presentation only. What is paid, when the server pays",
+        "it, the receipt, every ceiling and the player's ledger are the same either way.",
+        "",
+        "`arcade`: a payout the game cues within a beat of it flies from the cue's",
+        "`origin`, and one it does not flies from the middle of the frame. A cue that",
+        "arrives after its payout was already shown adds nothing.",
+        "",
+        "`game`: the game's cue supplies the moment and the payout supplies the number.",
+        "A parent adds each payout to an amount it HOLDS for that currency instead of",
+        "showing it, and its own wallet readout over the game shows the true total",
+        "minus what it still holds, so a spend or a payout from anywhere else still",
+        "moves it at once. A `gem.rewardCue` releases up to its `expected` of the held",
+        "amount, or all of it when it names none, flying from its `origin`. A cue that",
+        "finds nothing held waits for the next payout of its currency, as in `arcade`.",
+        "So payouts and cues meet in either order and several at once need no pairing.",
+        "Whatever part of a payout no cue has released within five minutes of its",
+        "arrival lands quietly, with no flight: a game can delay its payout's",
+        "presentation, never hide it.",
+        "",
+        "A cue still adds nothing to a wallet: what lands is always the payout's own",
+        "figure. The parent's other surfaces (its menu, its header, every purchase)",
+        "read the true total the moment the payout lands, so a held readout never stops",
+        "a player spending what they have.",
+        "",
+        "SCREEN STATE, NOT A TOGGLE, like `gem.gemCorner`. Each message is the whole",
+        "answer and the latest one wins. The SDK holds it from before the bridge is up",
+        "and re-sends it after every handshake, so a parent that reconnects presents",
+        "the way the game had asked. A switch back to `arcade` lands what is held.",
+        "",
+        "A PRESENTATION REQUEST ONLY, and not an authorization control. Cosmetic:",
+        "nothing may key a trust decision on it.",
+        "",
+        "Gated by `rewardPresentation`: sent only to a parent that advertised it. To",
+        "any other, `gem.setRewardPresentation` returns false, and that parent presents",
+        "every payout the `arcade` way."
+      ],
+      "fields": {
+        "mode": {
+          "kind": "enum",
+          "values": ["arcade", "game"],
+          "$comment": "`game` holds each payout's presentation for the game's cue; `arcade` is the default, for a parent that has had no message."
+        }
+      },
+      "rateLimit": { "perMinute": 12 }
+    },
+
     {
       "type": "gem.walletDisplay",
       "direction": "frameToParent",
@@ -5215,6 +5320,193 @@
       },
       "rateLimit": { "perMinute": 30 }
     },
+    {
+      "type": "gem.requestPlayInvite",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "Ask the parent to open ITS OWN invite-to-play sheet for this game, so",
+        "the player can invite friends to come and play it with them - the",
+        "\"Invite friends\" button of a lobby or a hub. Gated by the",
+        "`playInvites` capability. Answered by `gem.playInviteResult`.",
+        "",
+        "A PLATFORM DECISION: DESIGN.md section 10's eighth amendment,",
+        "decided by the platform owner on 2026-11-04, amending its 'no",
+        "invites in the frame'. The sheet is the Arcade's own Friends window,",
+        "the one the player also opens from the Arcade's menu.",
+        "",
+        "WHY THIS CROSSES THE BRIDGE AT ALL. A game knows the moment an invite is",
+        "worth offering - a lobby with an empty seat, a hub the player just",
+        "reached - but an invite puts a notice in front of another person, which",
+        "is an account-session act the game-scoped token is refused by",
+        "construction, and the friends worth inviting are chosen by their",
+        "presence, which never reaches a frame. So the game ASKS, and the parent,",
+        "which holds the account session, renders its own sheet of the player's",
+        "friends and sends an invite only on the player's own press in it.",
+        "",
+        "A CORRELATOR AND, OPTIONALLY, THE GAME'S LAUNCH PARAMS, deliberately",
+        "nothing more. The params say what the window's link and invites open,",
+        "as a share's do, and name nobody. No player id: a game",
+        "that could name the friend would be choosing whom the platform notifies,",
+        "and could learn from the answer whether that friend is reachable. No",
+        "game id and no channel: the parent takes both from what it framed. No",
+        "text: what the sheet and the invite say is the platform's own.",
+        "",
+        "WHAT THE PARENT OWES, none of which this schema can enforce:",
+        "",
+        "  ADVERTISE IT AS A DEPLOYMENT-WIDE FACT, never by account state, and",
+        "  only once the platform has decided it. A guest, or a player with no",
+        "  friends, is the parent's to explain in its own chrome or to answer",
+        "  `shown: false`; a token that blinked with sign-in would move that",
+        "  disclosure into the handshake.",
+        "",
+        "  CHECK ACTIVATION ON RECEIPT. Read `navigator.userActivation.isActive`",
+        "  synchronously when the message arrives, before any `await`, and answer",
+        "  an ask that arrives without it `shown: false` with nothing rendered.",
+        "  The frame chooses the moment it asks; the player's press is what makes",
+        "  a sheet over their game wanted rather than a nag.",
+        "",
+        "  ONE SHEET AT A TIME, AND CAPPED. An ask arriving while this sheet - or",
+        "  any other sheet that holds the stage: a purchase, a sign-in prompt, a",
+        "  friend challenge - is open is answered `shown: false` with nothing",
+        "  rendered, and the open invite sheet holds the stage against those asks",
+        "  too. A short cooldown after the player closes one is the parent's",
+        "  call.",
+        "",
+        "  RENDER ONLY FROM PLATFORM RECORDS. The friends, their presence and the",
+        "  game's name come from the parent's own reads, never from the frame.",
+        "  Each Invite press is one account-session send.",
+        "",
+        "  PAUSE THE GAME while the sheet is open (`gem.pause`) and lift it when",
+        "  the sheet closes, returning focus to the frame.",
+        "",
+        "  ANSWER ONCE, AS THE SHEET OPENS. `shown: true` once it has painted,",
+        "  not when it closes: how long the player browsed, and what they did in",
+        "  it, are theirs.",
+        "",
+        "NOT AN AUTHORIZATION CONTROL. The player's Invite press in the parent's",
+        "chrome is the control, and the platform's account-session send is the",
+        "enforcement: it re-checks the friendship, blocks and every budget,",
+        "whatever reached it."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Opaque and frame-chosen. The parent treats it as an echo-only correlator, exactly as it does for gem.requestFriendChallenge - it is not unique across tabs or reloads and must never key anything. It may also contain newlines and control characters, so it is not safe to write into a log line unescaped."
+        },
+        "params": {
+          "kind": "array",
+          "maxItems": 16,
+          "optional": true,
+          "$comment": [
+            "The game's own launch parameters for what the invite and the",
+            "window's share link open - `{ room: <join code> }` for a game whose",
+            "rooms are joined by code. The same shape, grammar and reserved-key",
+            "rules as `gem.requestShare.params`: the window's share link and its",
+            "friend invites carry the same params, so a friend who accepts and a",
+            "stranger who opens the link arrive the same way. ABSENT: the parent",
+            "uses the params the game last declared with `gem.inviteParams`, or",
+            "none. PRESENT, even empty: these, for this one opening.",
+            "",
+            "The parent applies the share rules to them and answers `shown:",
+            "false`, rendering nothing, for anything it would refuse. They name",
+            "what the link opens, never a person."
+          ],
+          "items": {
+            "kind": "object",
+            "fields": {
+              "key": { "kind": "string", "maxLength": 64 },
+              "value": { "kind": "string", "maxLength": 512 }
+            }
+          }
+        }
+      },
+      "rateLimit": {
+        "perMinute": 6,
+        "$comment": "Bounds a BUGGY game. NOT a security control: a hostile game posts on the port it holds rather than calling the SDK. What stops a game nagging is the parent's activation check, its one-sheet-at-a-time rule and the player's own Invite press."
+      }
+    },
+    {
+      "type": "gem.playInviteResult",
+      "direction": "parentToFrame",
+      "transport": "port",
+      "$comment": [
+        "The answer to one gem.requestPlayInvite. Gated by the `playInvites`",
+        "capability.",
+        "",
+        "ONE BOOLEAN, AND NOTHING ELSE. `shown: true` - the parent opened its",
+        "invite sheet. `shown: false` - nothing was rendered: no activation,",
+        "another sheet held the stage, a guest, a parent with no sheet to offer.",
+        "",
+        "WHAT THE FRAME NEVER LEARNS, and a parent must not attach: whom the",
+        "player invited, how many, whether any invite was sent, delivered or",
+        "accepted, or why nothing was shown. Who the player invites is a fact",
+        "about the people they know, and whether an invite landed is a fact about",
+        "a stranger's settings; neither is the game's. So `shown: true` grants",
+        "nothing and is no sign anything was sent - a game never gates a reward",
+        "on it. A",
+        "friend who accepts arrives the ordinary way: the Arcade opens the game",
+        "for them, and its own quick-join seats them beside the player.",
+        "",
+        "PERMANENTLY A BOOLEAN. A field reporting the outcome would undo the",
+        "amendment this pair rides on (DESIGN.md section 10, pending the",
+        "platform's decision)."
+      ],
+      "fields": {
+        "requestId": {
+          "kind": "string",
+          "maxLength": 64,
+          "$comment": "Echoes the gem.requestPlayInvite that asked. Echo-only."
+        },
+        "shown": {
+          "kind": "boolean",
+          "$comment": "Whether the parent opened its invite sheet. It grants nothing, and says nothing about whether anyone was invited."
+        }
+      },
+      "rateLimit": { "perMinute": 12 }
+    },
+    {
+      "type": "gem.inviteParams",
+      "direction": "frameToParent",
+      "transport": "port",
+      "$comment": [
+        "A standing declaration: the launch parameters the Arcade's Friends",
+        "window should carry when the PLAYER opens it from the Arcade's own",
+        "menu, over this game - its share link and its friend invites alike.",
+        "Gated by the `playInvites` capability. Nothing answers it.",
+        "",
+        "A game sends it when it enters a room joined by code (`{ room:",
+        "<join code> }`) and clears it - `params` absent - when it leaves. The",
+        "latest one stands until the next, and an explicit",
+        "`gem.requestPlayInvite` carrying `params` wins for that one opening.",
+        "The SDK re-sends the latest on every handshake, so a fresh parent",
+        "holds what the game last said.",
+        "",
+        "THE SAME PARAMS AS A SHARE, on the same rules. They name what a link",
+        "opens and never a person: no player, no game id and no channel",
+        "travel. The parent applies the share rules to them when it uses",
+        "them, and leaves a link it would refuse unbuilt rather than",
+        "carrying it. Sending one changes nothing on screen and tells the",
+        "game nothing."
+      ],
+      "fields": {
+        "params": {
+          "kind": "array",
+          "maxItems": 16,
+          "optional": true,
+          "$comment": "The declared params, in order; the shape, grammar and reserved-key rules of `gem.requestShare.params`. ABSENT clears the declaration.",
+          "items": {
+            "kind": "object",
+            "fields": {
+              "key": { "kind": "string", "maxLength": 64 },
+              "value": { "kind": "string", "maxLength": 512 }
+            }
+          }
+        }
+      },
+      "rateLimit": { "perMinute": 30 }
+    },
     {
       "type": "gem.requestAppLinks",
       "direction": "frameToParent",

package/schema/capabilities.public.json

@@ -46,6 +46,14 @@
         "gem.friendChallengeResult"
       ]
     },
+    "playInvites": {
+      "implemented": true,
+      "gates": [
+        "gem.requestPlayInvite",
+        "gem.playInviteResult",
+        "gem.inviteParams"
+      ]
+    },
     "devtools": {
       "implemented": true,
       "gates": [
@@ -141,6 +149,12 @@
         "gem.rewardCue"
       ]
     },
+    "rewardPresentation": {
+      "implemented": true,
+      "gates": [
+        "gem.rewardPresentation"
+      ]
+    },
     "frameStats": {
       "implemented": true,
       "gates": [
@@ -207,6 +221,12 @@
         "gem.earnAllowanceChanged"
       ]
     },
+    "inventoryChanged": {
+      "implemented": true,
+      "gates": [
+        "gem.inventoryChanged"
+      ]
+    },
     "deviceSettings": {
       "implemented": true,
       "gates": [