@indiegems/gem-web-sdk 7.9.1 → 8.0.0

package/docs/api/api-reference-game.md

@@ -1,6 +1,6 @@
 # The browser surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v7.9.1. Every symbol below links to its page on the Gem Arcade developer site.
+Generated from `@indiegems/gem-web-sdk/sdk` v8.0.0. Every symbol below links to its page on the Gem Arcade developer site.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/game` exports exactly the symbols on this page and nothing else, for a build that wants only this half.
 
@@ -4935,6 +4935,30 @@ arcade that handles share.
   up, for an arcade that does not handle share, and past this frame's own
   limit of six a minute.
 
+## GemFrame.requestVibrate
+
+[GemFrame.requestVibrate](https://gemarcade.com/developer/api/game#gemframe-requestvibrate)
+
+```ts
+requestVibrate(pattern: readonly number[]): boolean
+```
+
+Ask the arcade to play a vibration pattern where this frame has no
+`navigator.vibrate` of its own. Nothing comes back.
+
+Prefer `gem.vibration.vibrate`, which calls `navigator.vibrate` itself
+where it exists, normalizes the pattern and caps its total length. This one
+checks only the message's bounds, sends only while connected, and only to
+an arcade that handles vibration.
+
+| Parameter | Type |
+| --- | --- |
+| `pattern` | `readonly number[]` |
+
+**Returns.** whether the message left the frame — `false` before the bridge is
+  up, for an arcade that does not handle vibration, and past this frame's
+  own limit of 600 a minute.
+
 ## GemFrame.reportFrameStats
 
 [GemFrame.reportFrameStats](https://gemarcade.com/developer/api/game#gemframe-reportframestats)
@@ -5121,7 +5145,9 @@ readonly limit?: number
 ```
 
 Friends per page — default 50, at most 200. A player holds at most 1000
-friends, so five max-size pages is the whole list.
+friends, so five max-size pages is the whole list. A larger value is
+clamped to 200; a value that is not a non-negative integer is refused with
+`invalid`.
 
 ## ListFriendsOptions.cursor
 
@@ -5144,6 +5170,181 @@ readonly signal?: AbortSignal
 
 Abort the read.
 
+## FriendChallenge
+
+[FriendChallenge](https://gemarcade.com/developer/api/game#friendchallenge)
+
+```ts
+interface FriendChallenge
+```
+
+One friend challenge this player received, in THIS game on THIS channel.
+
+What the platform holds, not what the card said: there is no rendered line,
+because your game renders its own copy from [FriendChallenge.template](https://gemarcade.com/developer/api/game#friendchallenge-template)
+and [FriendChallenge.params](https://gemarcade.com/developer/api/game#friendchallenge-params). Who sent it is
+[FriendChallenge.from](https://gemarcade.com/developer/api/game#friendchallenge-from), resolved by the platform from its own records.
+
+## FriendChallenge.id
+
+[FriendChallenge.id](https://gemarcade.com/developer/api/game#friendchallenge-id)
+
+```ts
+readonly id: string
+```
+
+The challenge's id — the value the Arcade puts in the `gemChallenge`
+launch key, and what [FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered) takes. Opaque: compare
+it, store it, never parse it.
+
+## FriendChallenge.from
+
+[FriendChallenge.from](https://gemarcade.com/developer/api/game#friendchallenge-from)
+
+```ts
+readonly from: Friend
+```
+
+Who sent it, with the same display identity a [Friend](https://gemarcade.com/developer/api/game#friend) row carries.
+
+The ONLY name to show. Never read a name out of
+[FriendChallenge.params](https://gemarcade.com/developer/api/game#friendchallenge-params): a name in a param is one nobody checked.
+
+## FriendChallenge.template
+
+[FriendChallenge.template](https://gemarcade.com/developer/api/game#friendchallenge-template)
+
+```ts
+readonly template: string
+```
+
+The `friend_challenge_templates[].key` it was sent with — which of your
+templates, so your game knows what was asked.
+
+## FriendChallenge.params
+
+[FriendChallenge.params](https://gemarcade.com/developer/api/game#friendchallenge-params)
+
+```ts
+readonly params: Readonly<Record<string, string | number>>
+```
+
+The params exactly as sent: integers as numbers, date, enum and code
+params as strings. The template constrained them when the challenge was
+sent, but the config may have changed since, so check each one against
+what your game expects before it does anything — as you would a launch
+key.
+
+## FriendChallenge.createdAt
+
+[FriendChallenge.createdAt](https://gemarcade.com/developer/api/game#friendchallenge-createdat)
+
+```ts
+readonly createdAt: number
+```
+
+When it was sent, in Unix seconds.
+
+## FriendChallenge.openedAt
+
+[FriendChallenge.openedAt](https://gemarcade.com/developer/api/game#friendchallenge-openedat)
+
+```ts
+readonly openedAt?: number
+```
+
+When the player pressed Play on it in the Arcade, in Unix seconds. Absent
+until they have.
+
+## FriendChallenge.answeredAt
+
+[FriendChallenge.answeredAt](https://gemarcade.com/developer/api/game#friendchallenge-answeredat)
+
+```ts
+readonly answeredAt?: number
+```
+
+When a game marked it answered with [FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered), in
+Unix seconds. Absent until one has — so present on a relaunch of a
+challenge already played, which is how a replay is told from a first
+attempt.
+
+## FriendChallengesPage
+
+[FriendChallengesPage](https://gemarcade.com/developer/api/game#friendchallengespage)
+
+```ts
+interface FriendChallengesPage
+```
+
+One page of the friend challenges this player holds in this game.
+
+## FriendChallengesPage.challenges
+
+[FriendChallengesPage.challenges](https://gemarcade.com/developer/api/game#friendchallengespage-challenges)
+
+```ts
+readonly challenges: readonly FriendChallenge[]
+```
+
+The page's challenges, newest first, answered ones last.
+
+## FriendChallengesPage.nextCursor
+
+[FriendChallengesPage.nextCursor](https://gemarcade.com/developer/api/game#friendchallengespage-nextcursor)
+
+```ts
+readonly nextCursor?: string
+```
+
+Present exactly when another page exists — pass it back as
+[ListFriendChallengesOptions.cursor](https://gemarcade.com/developer/api/game#listfriendchallengesoptions-cursor) to continue. Opaque: mint
+nothing, store nothing, compare nothing.
+
+## ListFriendChallengesOptions
+
+[ListFriendChallengesOptions](https://gemarcade.com/developer/api/game#listfriendchallengesoptions)
+
+```ts
+interface ListFriendChallengesOptions
+```
+
+What [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox) takes.
+
+## ListFriendChallengesOptions.limit
+
+[ListFriendChallengesOptions.limit](https://gemarcade.com/developer/api/game#listfriendchallengesoptions-limit)
+
+```ts
+readonly limit?: number
+```
+
+Challenges per page — default 50, at most 200. The platform keeps at most
+200 per player, so one max-size page is the whole inbox. A larger value is
+clamped to 200; a value that is not a non-negative integer is refused with
+`invalid`.
+
+## ListFriendChallengesOptions.cursor
+
+[ListFriendChallengesOptions.cursor](https://gemarcade.com/developer/api/game#listfriendchallengesoptions-cursor)
+
+```ts
+readonly cursor?: string
+```
+
+The previous page's [FriendChallengesPage.nextCursor](https://gemarcade.com/developer/api/game#friendchallengespage-nextcursor), verbatim. A
+cursor the platform did not mint is refused with `invalid`.
+
+## ListFriendChallengesOptions.signal
+
+[ListFriendChallengesOptions.signal](https://gemarcade.com/developer/api/game#listfriendchallengesoptions-signal)
+
+```ts
+readonly signal?: AbortSignal
+```
+
+Abort the read.
+
 ## FriendChallengeRequest
 
 [FriendChallengeRequest](https://gemarcade.com/developer/api/game#friendchallengerequest)
@@ -5423,15 +5624,18 @@ channel: the version the template is missing from.
 class FriendsApi
 ```
 
-Reading the signed-in player's accepted friends, and asking the Arcade to
-send one of them a friend challenge.
+Reading the signed-in player's accepted friends, asking the Arcade to send
+one of them a friend challenge, and reading the friend challenges this
+player received in this game.
 
 Reached as `gem.friends`. Display identity only, and every accepted friend
 appears whether or not they have played this game — an invite-a-friend flow
 needs exactly the ones who have not. The graph itself — requests, accepts,
 blocks — is managed on the Arcade, not here. So is a friend challenge's
 send: [FriendsApi.challenge](https://gemarcade.com/developer/api/game#friendsapi-challenge) asks, and the Arcade confirms with the
-player and sends.
+player and sends. The receiving side is [FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge)
+(the challenge this frame was launched with), [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox) and
+[FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered).
 
 ```js
 let page = await gem.friends.list();
@@ -5460,7 +5664,8 @@ have played this one.
 | --- | --- |
 | `options` | `ListFriendsOptions` |
 
-**Throws.** `invalid` when the cursor is not one a previous page minted,
+**Throws.** `invalid` when the cursor is not one a previous page minted or
+  `limit` is not a non-negative integer,
   `forbidden` in a context with no player — this is a player surface, and
   a game server has no friend list.
 
@@ -5520,6 +5725,123 @@ challengeButton.onclick = async () => {
 };
 ```
 
+## FriendsApi.inbox
+
+[FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox)
+
+```ts
+inbox(options?: ListFriendChallengesOptions): Promise<FriendChallengesPage>
+```
+
+Read one page of the friend challenges this player holds in THIS game on
+THIS channel — in every state. Answered challenges are INCLUDED, and sort
+after the rest; within each part, newest first.
+
+Pass the result's `nextCursor` back as `cursor` until it stops arriving.
+A guest holds no challenges, so a guest's page is empty rather than a
+refusal — build the screen for the empty state, not around an error.
+
+For the one challenge this frame was launched with, use
+[FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge) rather than searching this list.
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `ListFriendChallengesOptions` |
+
+**Throws.** `invalid` when the cursor is not one a previous page minted or
+  `limit` is not a non-negative integer,
+  `forbidden` in a context with no player of this game — a game server,
+  or a token that is not a game-scoped player token.
+
+```ts
+const page = await gem.friends.inbox();
+for (const c of page.challenges) {
+  if (c.template !== 'beat_code_jar') continue;
+  renderChallengeRow(c.from, c.params, c.answeredAt !== undefined);
+}
+```
+
+## FriendsApi.launchedChallenge
+
+[FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge)
+
+```ts
+launchedChallenge(options?: { signal?: AbortSignal }): Promise<FriendChallenge | null>
+```
+
+The friend challenge this frame was launched with, or `null`.
+
+When a player opens a friend challenge in the Arcade, the Arcade launches
+your game with the challenge's params as launch keys plus its own
+`gemChallenge` key. This reads that key — never parse it yourself — and
+looks the challenge up, so you get the sender from the platform's records
+and the params as they were sent.
+
+The key is read ONCE, when `createGem` runs, so cleaning your URL with
+`history.replaceState` afterwards changes nothing here.
+
+RESOLVES `null`, never rejects, for every launch that is not this
+player's challenge in this game: no `gemChallenge` key, a value that is
+not a challenge id, a challenge that is not this player's (a link
+someone shared), one from another game or channel, and every guest
+launch. Treat `null` as an ordinary launch.
+
+A RELAUNCH REPLAYS. Pressing Play again in the Arcade relaunches the
+same challenge, so the same one comes back; it carries
+[FriendChallenge.answeredAt](https://gemarcade.com/developer/api/game#friendchallenge-answeredat) once a game has called
+[FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered), which is how a replay is told from a
+first attempt. Asks the platform on every call, so `answeredAt` is
+current.
+
+| Parameter | Type |
+| --- | --- |
+| `options` | `{ signal?: AbortSignal }` |
+
+**Throws.** What any platform read throws: `forbidden` in a context with no
+  player of this game, `unavailable` and `rate_limited` when the platform
+  cannot answer now — and `not_found` for a 404 that is NOT the platform's
+  uniform challenge answer (no `inbox_item_not_found` code), which is a
+  platform that does not serve this read rather than an ordinary launch.
+
+```ts
+const challenge = await gem.friends.launchedChallenge();
+if (challenge?.template === 'beat_code_jar') {
+  // Check every param before it does anything: the config may have changed since.
+  const jar = challenge.params.jar;
+  if (typeof jar === 'string' && /^[A-Z0-9]{7}$/.test(jar)) {
+    startJar(jar, { from: challenge.from, replay: challenge.answeredAt !== undefined });
+  }
+}
+```
+
+## FriendsApi.markAnswered
+
+[FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered)
+
+```ts
+markAnswered(id: string): Promise<void>
+```
+
+Mark one of this player's friend challenges answered — the player has
+played it. Call it when your game has finished the attempt the challenge
+asked for, win or lose.
+
+Idempotent: a second call changes nothing, and a challenge keeps the
+first time it was answered. The sender is told nothing — there is no read
+receipt — so this is your game's own record, which
+[FriendChallenge.answeredAt](https://gemarcade.com/developer/api/game#friendchallenge-answeredat) reads back.
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | A [FriendChallenge.id](https://gemarcade.com/developer/api/game#friendchallenge-id), from
+  [FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge) or [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox). |
+
+**Throws.** `not_found` when no challenge of this player's in this game and
+  channel has that id — one answer for unknown and someone else's;
+  `invalid` when `id` cannot be a challenge id at all, before anything is
+  sent; `forbidden` in a context with no player of this game;
+  `rate_limited` past the platform's per-player budget.
+
 ## FunctionInvokeOptions
 
 [FunctionInvokeOptions](https://gemarcade.com/developer/api/game#functioninvokeoptions)
@@ -7405,6 +7727,40 @@ shareButton.onclick = () => {
 
 **Guides.** [getting-started](https://gemarcade.com/developer/docs/getting-started)
 
+## Gem.vibration
+
+[Gem.vibration](https://gemarcade.com/developer/api/game#gem-vibration)
+
+```ts
+readonly vibration: VibrationApi
+```
+
+Vibrate the player's device — call this instead of `navigator.vibrate`,
+which does nothing on any iPhone. It takes the same pattern and returns the
+same boolean, calls `navigator.vibrate` itself where that works, and asks
+the arcade to vibrate where it does not.
+
+Read [VibrationApi.available](https://gemarcade.com/developer/api/game#vibrationapi-available) live, after `awaitBridge()`, to decide
+whether to show your game's vibration toggle — on an iPhone it is `false`
+until the bridge connects — and check that toggle before every call:
+
+```js
+await gem.awaitBridge();
+vibrationRow.hidden = !gem.vibration.available;
+
+function onHit() {
+  if (settings.vibration) gem.vibration.vibrate(30);
+}
+```
+
+- **Never call `navigator.vibrate`**, guarded or not, and never fall back
+  to it: this already does.
+- **Nothing vibrates before the player's first tap** in your game; the
+  call returns `false` until then.
+- **Stop on pause** with `gem.vibration.vibrate(0)`.
+
+**Guides.** [vibration](https://gemarcade.com/developer/docs/vibration)
+
 ## Gem.analytics
 
 [Gem.analytics](https://gemarcade.com/developer/api/game#gem-analytics)
@@ -7499,12 +7855,17 @@ readonly friends: FriendsApi
 The signed-in player's accepted friends — display identity only,
 read-only, paginated — and the one ask that reaches past them:
 [FriendsApi.challenge](https://gemarcade.com/developer/api/game#friendsapi-challenge), which asks the Arcade to send a friend a
-challenge after the player confirms it in the Arcade's own sheet.
+challenge after the player confirms it in the Arcade's own sheet. The
+receiving side reads the challenges this player holds in this game:
+[FriendsApi.launchedChallenge](https://gemarcade.com/developer/api/game#friendsapi-launchedchallenge) for the one this frame was launched
+with, [FriendsApi.inbox](https://gemarcade.com/developer/api/game#friendsapi-inbox) for all of them, and
+[FriendsApi.markAnswered](https://gemarcade.com/developer/api/game#friendsapi-markanswered) once one has been played.
 
 Every accepted friend appears whether or not they have played this game;
 an invite-a-friend flow needs exactly the ones who have not. The graph
 itself — requests, accepts, blocks, presence — stays on the Arcade: there
-is nothing here to mutate and nothing that says who is online.
+is nothing here to mutate but a challenge's own answered mark, and nothing
+that says who is online.
 
 A player surface only. In a context with no player — a game server — the
 platform refuses the read; a server has no friend list.
@@ -11247,6 +11608,61 @@ A unit test that constructs the SDK in a simulated DOM has to give its
 window a parent of its own, because a simulated top-level window is exactly
 what this refuses.
 
+## VibrationApi
+
+[VibrationApi](https://gemarcade.com/developer/api/game#vibrationapi)
+
+```ts
+interface VibrationApi
+```
+
+`gem.vibration` — vibrate the player's device, on every platform that can.
+Call it instead of `navigator.vibrate`, which does nothing on any iPhone.
+
+## VibrationApi.available
+
+[VibrationApi.available](https://gemarcade.com/developer/api/game#vibrationapi-available)
+
+```ts
+readonly available: boolean
+```
+
+Whether this device can vibrate for your game: decide from this whether to
+show your game's vibration toggle. Read it live, every time — after
+`awaitBridge()`, and again when your settings screen opens — never once at
+boot: on an iPhone it is `false` until the bridge connects.
+
+`false` on a desktop with a mouse, in iOS Safari, in Firefox, before the
+bridge is up where vibration goes through the arcade, and after the
+session ends there.
+
+## VibrationApi.vibrate
+
+[VibrationApi.vibrate](https://gemarcade.com/developer/api/game#vibrationapi-vibrate)
+
+```ts
+vibrate(pattern: number | readonly number[]): boolean
+```
+
+Vibrate: takes what `navigator.vibrate` takes and returns what it returns.
+`pattern` is a duration in milliseconds, or an array of alternating
+vibration and pause durations, starting with a vibration. `0` or `[]`
+stops a pattern that is still playing, and every call replaces it.
+
+The pattern is capped at 99 entries of at most 10 000 ms each, and at
+10 000 ms in all: a longer one is cut short, not refused.
+
+Check your game's own vibration toggle before every call. Returns `false`,
+and vibrates nothing, when [VibrationApi.available](https://gemarcade.com/developer/api/game#vibrationapi-available) is false, before
+the player's first tap or key press in your game, for a pattern with a
+negative or non-finite entry, and past 600 calls a minute; each of the last
+three says so once a session through your `log`. `true` means the pattern
+was accepted, never that a motor moved.
+
+| Parameter | Type |
+| --- | --- |
+| `pattern` | `number \| readonly number[]` |
+
 ## LeaderboardPeriod.id
 
 [LeaderboardPeriod.id](https://gemarcade.com/developer/api/game#leaderboardperiod-id)

package/docs/api/api-reference-server.md

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v7.9.1. Every symbol below links to its page on the Gem Arcade developer site.
+Generated from `@indiegems/gem-web-sdk/sdk` v8.0.0. Every symbol below links to its page on the Gem Arcade developer site.
 
 `@indiegems/gem-web-sdk/sdk` is the one import a game writes, wherever its code runs. `@indiegems/gem-web-sdk/server` exports exactly the symbols on this page and nothing else, for a build that wants only this half.