@indiegems/gem-web-sdk 7.9.1 → 8.0.0

package/docs/api/reference.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "source": {
     "repo": "IndieGems/gem-web-sdk",
-    "version": "7.9.1"
+    "version": "8.0.0"
   },
   "entries": [
     {
@@ -61,6 +61,10 @@
           "key": "share",
           "title": "Sharing a link to your game"
         },
+        {
+          "key": "vibration",
+          "title": "Vibrating the device"
+        },
         {
           "key": "config",
           "title": "Your published config"
@@ -6184,6 +6188,30 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "GemFrame.requestVibrate",
+          "name": "requestVibrate",
+          "anchor": "gemframe-requestvibrate",
+          "group": "frame",
+          "url": "https://gemarcade.com/developer/api/game#gemframe-requestvibrate",
+          "signature": "requestVibrate(pattern: readonly number[]): boolean",
+          "documented": true,
+          "summary": "Ask the arcade to play a vibration pattern where this frame has no\n`navigator.vibrate` of its own. Nothing comes back.\n\nPrefer `gem.vibration.vibrate`, which calls `navigator.vibrate` itself\nwhere it exists, normalizes the pattern and caps its total length. This one\nchecks only the message's bounds, sends only while connected, and only to\nan arcade that handles vibration.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "pattern",
+              "type": "readonly number[]",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": "whether the message left the frame — `false` before the bridge is\n  up, for an arcade that does not handle vibration, and past this frame's\n  own limit of 600 a minute.",
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "GemFrame.reportFrameStats",
           "name": "reportFrameStats",
@@ -6444,7 +6472,7 @@
           "url": "https://gemarcade.com/developer/api/game#listfriendsoptions-limit",
           "signature": "readonly limit?: number",
           "documented": true,
-          "summary": "Friends per page — default 50, at most 200. A player holds at most 1000\nfriends, so five max-size pages is the whole list.",
+          "summary": "Friends per page — default 50, at most 200. A player holds at most 1000\nfriends, so five max-size pages is the whole list. A larger value is\nclamped to 200; a value that is not a non-negative integer is refused with\n`invalid`.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -6487,6 +6515,261 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "FriendChallenge",
+          "name": "FriendChallenge",
+          "anchor": "friendchallenge",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge",
+          "signature": "interface FriendChallenge",
+          "documented": true,
+          "summary": "One friend challenge this player received, in THIS game on THIS channel.\n\nWhat the platform holds, not what the card said: there is no rendered line,\nbecause your game renders its own copy from [FriendChallenge.template](https://gemarcade.com/developer/api/game#friendchallenge-template)\nand [FriendChallenge.params](https://gemarcade.com/developer/api/game#friendchallenge-params). Who sent it is\n[FriendChallenge.from](https://gemarcade.com/developer/api/game#friendchallenge-from), resolved by the platform from its own records.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallenge.id",
+          "name": "id",
+          "anchor": "friendchallenge-id",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge-id",
+          "signature": "readonly id: string",
+          "documented": true,
+          "summary": "The challenge's id — the value the Arcade puts in the `gemChallenge`\nlaunch key, and what [FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered) takes. Opaque: compare\nit, store it, never parse it.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallenge.from",
+          "name": "from",
+          "anchor": "friendchallenge-from",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge-from",
+          "signature": "readonly from: Friend",
+          "documented": true,
+          "summary": "Who sent it, with the same display identity a [Friend](https://gemarcade.com/developer/api/game#friend) row carries.\n\nThe ONLY name to show. Never read a name out of\n[FriendChallenge.params](https://gemarcade.com/developer/api/game#friendchallenge-params): a name in a param is one nobody checked.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallenge.template",
+          "name": "template",
+          "anchor": "friendchallenge-template",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge-template",
+          "signature": "readonly template: string",
+          "documented": true,
+          "summary": "The `friend_challenge_templates[].key` it was sent with — which of your\ntemplates, so your game knows what was asked.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallenge.params",
+          "name": "params",
+          "anchor": "friendchallenge-params",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge-params",
+          "signature": "readonly params: Readonly<Record<string, string | number>>",
+          "documented": true,
+          "summary": "The params exactly as sent: integers as numbers, date, enum and code\nparams as strings. The template constrained them when the challenge was\nsent, but the config may have changed since, so check each one against\nwhat your game expects before it does anything — as you would a launch\nkey.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallenge.createdAt",
+          "name": "createdAt",
+          "anchor": "friendchallenge-createdat",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge-createdat",
+          "signature": "readonly createdAt: number",
+          "documented": true,
+          "summary": "When it was sent, in Unix seconds.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallenge.openedAt",
+          "name": "openedAt",
+          "anchor": "friendchallenge-openedat",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge-openedat",
+          "signature": "readonly openedAt?: number",
+          "documented": true,
+          "summary": "When the player pressed Play on it in the Arcade, in Unix seconds. Absent\nuntil they have.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallenge.answeredAt",
+          "name": "answeredAt",
+          "anchor": "friendchallenge-answeredat",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallenge-answeredat",
+          "signature": "readonly answeredAt?: number",
+          "documented": true,
+          "summary": "When a game marked it answered with [FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered), in\nUnix seconds. Absent until one has — so present on a relaunch of a\nchallenge already played, which is how a replay is told from a first\nattempt.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallengesPage",
+          "name": "FriendChallengesPage",
+          "anchor": "friendchallengespage",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallengespage",
+          "signature": "interface FriendChallengesPage",
+          "documented": true,
+          "summary": "One page of the friend challenges this player holds in this game.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallengesPage.challenges",
+          "name": "challenges",
+          "anchor": "friendchallengespage-challenges",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallengespage-challenges",
+          "signature": "readonly challenges: readonly FriendChallenge[]",
+          "documented": true,
+          "summary": "The page's challenges, newest first, answered ones last.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendChallengesPage.nextCursor",
+          "name": "nextCursor",
+          "anchor": "friendchallengespage-nextcursor",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendchallengespage-nextcursor",
+          "signature": "readonly nextCursor?: string",
+          "documented": true,
+          "summary": "Present exactly when another page exists — pass it back as\n[ListFriendChallengesOptions.cursor](https://gemarcade.com/developer/api/game#listfriendchallengesoptions-cursor) to continue. Opaque: mint\nnothing, store nothing, compare nothing.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ListFriendChallengesOptions",
+          "name": "ListFriendChallengesOptions",
+          "anchor": "listfriendchallengesoptions",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#listfriendchallengesoptions",
+          "signature": "interface ListFriendChallengesOptions",
+          "documented": true,
+          "summary": "What [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox) takes.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ListFriendChallengesOptions.limit",
+          "name": "limit",
+          "anchor": "listfriendchallengesoptions-limit",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#listfriendchallengesoptions-limit",
+          "signature": "readonly limit?: number",
+          "documented": true,
+          "summary": "Challenges per page — default 50, at most 200. The platform keeps at most\n200 per player, so one max-size page is the whole inbox. A larger value is\nclamped to 200; a value that is not a non-negative integer is refused with\n`invalid`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ListFriendChallengesOptions.cursor",
+          "name": "cursor",
+          "anchor": "listfriendchallengesoptions-cursor",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#listfriendchallengesoptions-cursor",
+          "signature": "readonly cursor?: string",
+          "documented": true,
+          "summary": "The previous page's [FriendChallengesPage.nextCursor](https://gemarcade.com/developer/api/game#friendchallengespage-nextcursor), verbatim. A\ncursor the platform did not mint is refused with `invalid`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "ListFriendChallengesOptions.signal",
+          "name": "signal",
+          "anchor": "listfriendchallengesoptions-signal",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#listfriendchallengesoptions-signal",
+          "signature": "readonly signal?: AbortSignal",
+          "documented": true,
+          "summary": "Abort the read.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FriendChallengeRequest",
           "name": "FriendChallengeRequest",
@@ -6801,7 +7084,7 @@
           "url": "https://gemarcade.com/developer/api/game#friendsapi",
           "signature": "class FriendsApi",
           "documented": true,
-          "summary": "Reading the signed-in player's accepted friends, and asking the Arcade to\nsend one of them a friend challenge.\n\nReached as `gem.friends`. Display identity only, and every accepted friend\nappears whether or not they have played this game — an invite-a-friend flow\nneeds exactly the ones who have not. The graph itself — requests, accepts,\nblocks — is managed on the Arcade, not here. So is a friend challenge's\nsend: [FriendsApi.challenge](https://gemarcade.com/developer/api/game#friendsapi-challenge) asks, and the Arcade confirms with the\nplayer and sends.\n\n```js\nlet page = await gem.friends.list();\nrender(page.friends);\nwhile (page.nextCursor) {\n  page = await gem.friends.list({ cursor: page.nextCursor });\n  render(page.friends);\n}\n```",
+          "summary": "Reading the signed-in player's accepted friends, asking the Arcade to send\none of them a friend challenge, and reading the friend challenges this\nplayer received in this game.\n\nReached as `gem.friends`. Display identity only, and every accepted friend\nappears whether or not they have played this game — an invite-a-friend flow\nneeds exactly the ones who have not. The graph itself — requests, accepts,\nblocks — is managed on the Arcade, not here. So is a friend challenge's\nsend: [FriendsApi.challenge](https://gemarcade.com/developer/api/game#friendsapi-challenge) asks, and the Arcade confirms with the\nplayer and sends. The receiving side is [FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge)\n(the challenge this frame was launched with), [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox) and\n[FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered).\n\n```js\nlet page = await gem.friends.list();\nrender(page.friends);\nwhile (page.nextCursor) {\n  page = await gem.friends.list({ cursor: page.nextCursor });\n  render(page.friends);\n}\n```",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -6829,7 +7112,7 @@
             }
           ],
           "returns": null,
-          "throws": "`invalid` when the cursor is not one a previous page minted,\n  `forbidden` in a context with no player — this is a player surface, and\n  a game server has no friend list.",
+          "throws": "`invalid` when the cursor is not one a previous page minted or\n  `limit` is not a non-negative integer,\n  `forbidden` in a context with no player — this is a player surface, and\n  a game server has no friend list.",
           "example": null,
           "defaultValue": null,
           "guides": []
@@ -6858,6 +7141,78 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "FriendsApi.inbox",
+          "name": "inbox",
+          "anchor": "friendsapi-inbox",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendsapi-inbox",
+          "signature": "inbox(options?: ListFriendChallengesOptions): Promise<FriendChallengesPage>",
+          "documented": true,
+          "summary": "Read one page of the friend challenges this player holds in THIS game on\nTHIS channel — in every state. Answered challenges are INCLUDED, and sort\nafter the rest; within each part, newest first.\n\nPass the result's `nextCursor` back as `cursor` until it stops arriving.\nA guest holds no challenges, so a guest's page is empty rather than a\nrefusal — build the screen for the empty state, not around an error.\n\nFor the one challenge this frame was launched with, use\n[FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge) rather than searching this list.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "options",
+              "type": "ListFriendChallengesOptions",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": "`invalid` when the cursor is not one a previous page minted or\n  `limit` is not a non-negative integer,\n  `forbidden` in a context with no player of this game — a game server,\n  or a token that is not a game-scoped player token.",
+          "example": "```ts\nconst page = await gem.friends.inbox();\nfor (const c of page.challenges) {\n  if (c.template !== 'beat_code_jar') continue;\n  renderChallengeRow(c.from, c.params, c.answeredAt !== undefined);\n}\n```",
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendsApi.launchedChallenge",
+          "name": "launchedChallenge",
+          "anchor": "friendsapi-launchedchallenge",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge",
+          "signature": "launchedChallenge(options?: { signal?: AbortSignal }): Promise<FriendChallenge | null>",
+          "documented": true,
+          "summary": "The friend challenge this frame was launched with, or `null`.\n\nWhen a player opens a friend challenge in the Arcade, the Arcade launches\nyour game with the challenge's params as launch keys plus its own\n`gemChallenge` key. This reads that key — never parse it yourself — and\nlooks the challenge up, so you get the sender from the platform's records\nand the params as they were sent.\n\nThe key is read ONCE, when `createGem` runs, so cleaning your URL with\n`history.replaceState` afterwards changes nothing here.\n\nRESOLVES `null`, never rejects, for every launch that is not this\nplayer's challenge in this game: no `gemChallenge` key, a value that is\nnot a challenge id, a challenge that is not this player's (a link\nsomeone shared), one from another game or channel, and every guest\nlaunch. Treat `null` as an ordinary launch.\n\nA RELAUNCH REPLAYS. Pressing Play again in the Arcade relaunches the\nsame challenge, so the same one comes back; it carries\n[FriendChallenge.answeredAt](https://gemarcade.com/developer/api/game#friendchallenge-answeredat) once a game has called\n[FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered), which is how a replay is told from a\nfirst attempt. Asks the platform on every call, so `answeredAt` is\ncurrent.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "options",
+              "type": "{ signal?: AbortSignal }",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": "What any platform read throws: `forbidden` in a context with no\n  player of this game, `unavailable` and `rate_limited` when the platform\n  cannot answer now — and `not_found` for a 404 that is NOT the platform's\n  uniform challenge answer (no `inbox_item_not_found` code), which is a\n  platform that does not serve this read rather than an ordinary launch.",
+          "example": "```ts\nconst challenge = await gem.friends.launchedChallenge();\nif (challenge?.template === 'beat_code_jar') {\n  // Check every param before it does anything: the config may have changed since.\n  const jar = challenge.params.jar;\n  if (typeof jar === 'string' && /^[A-Z0-9]{7}$/.test(jar)) {\n    startJar(jar, { from: challenge.from, replay: challenge.answeredAt !== undefined });\n  }\n}\n```",
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "FriendsApi.markAnswered",
+          "name": "markAnswered",
+          "anchor": "friendsapi-markanswered",
+          "group": "friends",
+          "url": "https://gemarcade.com/developer/api/game#friendsapi-markanswered",
+          "signature": "markAnswered(id: string): Promise<void>",
+          "documented": true,
+          "summary": "Mark one of this player's friend challenges answered — the player has\nplayed it. Call it when your game has finished the attempt the challenge\nasked for, win or lose.\n\nIdempotent: a second call changes nothing, and a challenge keeps the\nfirst time it was answered. The sender is told nothing — there is no read\nreceipt — so this is your game's own record, which\n[FriendChallenge.answeredAt](https://gemarcade.com/developer/api/game#friendchallenge-answeredat) reads back.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "id",
+              "type": "string",
+              "optional": false,
+              "summary": "A [FriendChallenge.id](https://gemarcade.com/developer/api/game#friendchallenge-id), from\n  [FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge) or [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox)."
+            }
+          ],
+          "returns": null,
+          "throws": "`not_found` when no challenge of this player's in this game and\n  channel has that id — one answer for unknown and someone else's;\n  `invalid` when `id` cannot be a challenge id at all, before anything is\n  sent; `forbidden` in a context with no player of this game;\n  `rate_limited` past the platform's per-player budget.",
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "FunctionInvokeOptions",
           "name": "FunctionInvokeOptions",
@@ -8895,6 +9250,29 @@
             }
           ]
         },
+        {
+          "id": "Gem.vibration",
+          "name": "vibration",
+          "anchor": "gem-vibration",
+          "group": "start",
+          "url": "https://gemarcade.com/developer/api/game#gem-vibration",
+          "signature": "readonly vibration: VibrationApi",
+          "documented": true,
+          "summary": "Vibrate the player's device — call this instead of `navigator.vibrate`,\nwhich does nothing on any iPhone. It takes the same pattern and returns the\nsame boolean, calls `navigator.vibrate` itself where that works, and asks\nthe arcade to vibrate where it does not.\n\nRead [VibrationApi.available](https://gemarcade.com/developer/api/game#vibrationapi-available) live, after `awaitBridge()`, to decide\nwhether to show your game's vibration toggle — on an iPhone it is `false`\nuntil the bridge connects — and check that toggle before every call:\n\n```js\nawait gem.awaitBridge();\nvibrationRow.hidden = !gem.vibration.available;\n\nfunction onHit() {\n  if (settings.vibration) gem.vibration.vibrate(30);\n}\n```\n\n- **Never call `navigator.vibrate`**, guarded or not, and never fall back\n  to it: this already does.\n- **Nothing vibrates before the player's first tap** in your game; the\n  call returns `false` until then.\n- **Stop on pause** with `gem.vibration.vibrate(0)`.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": [
+            {
+              "slug": "vibration",
+              "anchor": null,
+              "url": "https://gemarcade.com/developer/docs/vibration"
+            }
+          ]
+        },
         {
           "id": "Gem.analytics",
           "name": "analytics",
@@ -8983,7 +9361,7 @@
           "url": "https://gemarcade.com/developer/api/game#gem-friends",
           "signature": "readonly friends: FriendsApi",
           "documented": true,
-          "summary": "The signed-in player's accepted friends — display identity only,\nread-only, paginated — and the one ask that reaches past them:\n[FriendsApi.challenge](https://gemarcade.com/developer/api/game#friendsapi-challenge), which asks the Arcade to send a friend a\nchallenge after the player confirms it in the Arcade's own sheet.\n\nEvery accepted friend appears whether or not they have played this game;\nan invite-a-friend flow needs exactly the ones who have not. The graph\nitself — requests, accepts, blocks, presence — stays on the Arcade: there\nis nothing here to mutate and nothing that says who is online.\n\nA player surface only. In a context with no player — a game server — the\nplatform refuses the read; a server has no friend list.",
+          "summary": "The signed-in player's accepted friends — display identity only,\nread-only, paginated — and the one ask that reaches past them:\n[FriendsApi.challenge](https://gemarcade.com/developer/api/game#friendsapi-challenge), which asks the Arcade to send a friend a\nchallenge after the player confirms it in the Arcade's own sheet. The\nreceiving side reads the challenges this player holds in this game:\n[FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge) for the one this frame was launched\nwith, [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox) for all of them, and\n[FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered) once one has been played.\n\nEvery accepted friend appears whether or not they have played this game;\nan invite-a-friend flow needs exactly the ones who have not. The graph\nitself — requests, accepts, blocks, presence — stays on the Arcade: there\nis nothing here to mutate but a challenge's own answered mark, and nothing\nthat says who is online.\n\nA player surface only. In a context with no player — a game server — the\nplatform refuses the read; a server has no friend list.",
           "deprecated": null,
           "params": [],
           "returns": null,
@@ -13221,6 +13599,64 @@
           "defaultValue": null,
           "guides": []
         },
+        {
+          "id": "VibrationApi",
+          "name": "VibrationApi",
+          "anchor": "vibrationapi",
+          "group": "vibration",
+          "url": "https://gemarcade.com/developer/api/game#vibrationapi",
+          "signature": "interface VibrationApi",
+          "documented": true,
+          "summary": "`gem.vibration` — vibrate the player's device, on every platform that can.\nCall it instead of `navigator.vibrate`, which does nothing on any iPhone.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "VibrationApi.available",
+          "name": "available",
+          "anchor": "vibrationapi-available",
+          "group": "vibration",
+          "url": "https://gemarcade.com/developer/api/game#vibrationapi-available",
+          "signature": "readonly available: boolean",
+          "documented": true,
+          "summary": "Whether this device can vibrate for your game: decide from this whether to\nshow your game's vibration toggle. Read it live, every time — after\n`awaitBridge()`, and again when your settings screen opens — never once at\nboot: on an iPhone it is `false` until the bridge connects.\n\n`false` on a desktop with a mouse, in iOS Safari, in Firefox, before the\nbridge is up where vibration goes through the arcade, and after the\nsession ends there.",
+          "deprecated": null,
+          "params": [],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
+        {
+          "id": "VibrationApi.vibrate",
+          "name": "vibrate",
+          "anchor": "vibrationapi-vibrate",
+          "group": "vibration",
+          "url": "https://gemarcade.com/developer/api/game#vibrationapi-vibrate",
+          "signature": "vibrate(pattern: number | readonly number[]): boolean",
+          "documented": true,
+          "summary": "Vibrate: takes what `navigator.vibrate` takes and returns what it returns.\n`pattern` is a duration in milliseconds, or an array of alternating\nvibration and pause durations, starting with a vibration. `0` or `[]`\nstops a pattern that is still playing, and every call replaces it.\n\nThe pattern is capped at 99 entries of at most 10 000 ms each, and at\n10 000 ms in all: a longer one is cut short, not refused.\n\nCheck your game's own vibration toggle before every call. Returns `false`,\nand vibrates nothing, when [VibrationApi.available](https://gemarcade.com/developer/api/game#vibrationapi-available) is false, before\nthe player's first tap or key press in your game, for a pattern with a\nnegative or non-finite entry, and past 600 calls a minute; each of the last\nthree says so once a session through your `log`. `true` means the pattern\nwas accepted, never that a motor moved.",
+          "deprecated": null,
+          "params": [
+            {
+              "name": "pattern",
+              "type": "number | readonly number[]",
+              "optional": false,
+              "summary": null
+            }
+          ],
+          "returns": null,
+          "throws": null,
+          "example": null,
+          "defaultValue": null,
+          "guides": []
+        },
         {
           "id": "LeaderboardPeriod.id",
           "name": "id",

package/docs/changelog.md

@@ -16,6 +16,36 @@ 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.
 
+## 8.0.0
+
+*Written from the API facts alone; no summary was generated for this release.*
+
+Upgrading from 7.9.1. Impact: required.
+
+### Must change
+
+- BucketConfig changed its signature.
+- FRAME_TO_PARENT changed its signature.
+- FrameMessage changed its signature.
+- GemCapability changed its signature.
+
+### New capability
+
+- FriendChallenge was added.
+- FriendChallengesPage was added.
+- FriendsApi.inbox was added.
+- FriendsApi.launchedChallenge was added.
+- FriendsApi.markAnswered was added.
+- FriendsApiDependencies.launchedChallengeId was added.
+- ListFriendChallengesOptions was added.
+- Gem.vibration was added.
+- GemFrame.requestVibrate was added.
+- VibrationApi was added.
+- GemVibrate was added.
+- HostCallbacks.onVibrate was added.
+- HostOptions.onVibrate was added.
+- validateGemVibrate was added.
+
 ## 7.9.1
 
 Upgrading from 7.9.0. Impact: none.