@indiegems/gem-web-sdk 7.4.0 → 7.4.2

package/docs/deprecation-policy.md

@@ -0,0 +1,124 @@
+# When a deprecated surface stops working
+
+A handful of the surfaces in this SDK are marked **deprecated**. The mark tells you there is
+something better to call. It does not tell you how long the old one has, and that is the
+question you actually need answered before you can decide what to do about it. This page is
+the answer, and it is the only place in this documentation that gives it.
+
+Read it when something your game calls is marked deprecated and you are choosing between
+migrating now and folding the migration into your next major upgrade. If nothing you call is
+marked, you do not need this page.
+
+- [1. What this covers](#1-what-this-covers)
+- [2. The rule for the package's API surface](#2-the-rule-for-the-packages-api-surface)
+- [3. Runtime-delivered pushes are a separate question](#3-runtime-delivered-pushes-are-a-separate-question)
+- [4. What is deprecated today](#4-what-is-deprecated-today)
+- [5. What this is not](#5-what-this-is-not)
+
+---
+
+## 1. What this covers
+
+This policy governs the **API surface of `@indiegems/gem-web-sdk`**: the exports, methods,
+fields and options your game compiles against. A deprecation on one of those is a statement
+about package releases, and section 2 is the statement.
+
+**A deprecated surface still works.** The mark removes nothing and changes no behaviour. It is
+a notice period, and the point of a notice period is that you get to spend it rather than
+react to it.
+
+Four of the surfaces in section 4 are only half a package question, because the value behind
+them is pushed to your server bundle by the platform rather than returned by a call you make.
+Section 3 is that other half. And three separate things on this platform carry a version;
+section 5 says which of them this is.
+
+## 2. The rule for the package's API surface
+
+**A surface deprecated in a `3.x` release keeps working for every remaining `3.x` release, and
+`4.0.0` is the earliest release that may remove it.** The same rule holds at every major: a
+surface first deprecated in a `4.x` release works for the rest of `4.x`, and `5.0.0` is the
+earliest that may remove it. A major that deprecates a surface never removes it in the same
+breath.
+
+*Earliest release that may* is the whole of the strength, and it is worth reading twice. It is
+a floor: it names the soonest a removal could reach you, which is the number a migration plan
+needs. It is not a schedule. It does not say the surface is removed in `4.0.0`, and it does
+not put a date on `4.0.0`.
+
+What the floor buys you is that the removal lands on an upgrade you already control. No minor
+and no patch release inside `3.x` takes a deprecated surface away, so a dependency range that
+stays inside `3.x` cannot lose one underneath you — not on an install, not on a lockfile
+refresh, not on a transitive bump. The next time you have to think about any of this is the
+next time you deliberately change a major version.
+
+This is what package-level semver already costs here rather than a new promise:
+[`server-bundles.md`](server-bundles.md) records the whole package going to `3.0.0` for a
+single removed export, because that is the price of taking a surface away.
+
+**So migrate at the major, not at the mark.** A deprecation is worth a note in your backlog
+the day you read it; it is worth your afternoon only when you are already planning the major
+upgrade it lands on.
+
+## 3. Runtime-delivered pushes are a separate question
+
+Four of the deprecated surfaces are not values this package produces. `roomArgs` and `roster`
+on the server host — and the same two on the match-server wrapper around it — are **pushed into
+your bundle by the dedicated-server runtime image your bundle runs on**. That splits the
+question in two, and the halves are decided in different places.
+
+- **The member is package surface, and section 2 governs it unchanged.** The property keeps
+  compiling for the rest of `3.x`, and `4.0.0` is the earliest release that may take it off
+  the type.
+- **Whether a value still arrives is the runtime's decision, and no date has been set for it.**
+  This package does not build the runtime image and cannot say when a server stops sending one
+  of these. That is decided where the image is built. Nothing here names a version for it,
+  because a version this package cannot honour would be worse than the silence it replaces.
+
+**So treat delivery as something your code checks, not something you can read off a version.**
+That is the advice [`server-bundles.md`](server-bundles.md) already gives and none of it
+changes: read the room when it is there, and keep the deprecated push as the fallback for a
+server running an older image. [Room args](server-bundles.md#room-args) has the shape of both
+and the check that chooses between them.
+
+## 4. What is deprecated today
+
+Every deprecated surface this documentation publishes, with what to call instead. A notice you
+meet in the reference or in a guide points here; if a surface is not in this table, it is not
+deprecated.
+
+| Surface | Replacement | Earliest release that may remove it | Governing rule |
+| ------- | ----------- | ----------------------------------- | -------------- |
+| `Gem.client` | The named surfaces — `Gem.rooms`, `Gem.me`, `Gem.characters` and the rest | `4.0.0` | Package API surface |
+| `ClientVersion.platform` | None; drop the field, the SDK reports it | `4.0.0` | Package API surface |
+| `ClientVersion.gameVersion` | None; drop the field, the arcade tells your game which build it routed to | `6.0.0` | Package API surface |
+| `CreateRoomOptions.maxPlayers` | The room template's seats | `4.0.0` | Package API surface |
+| `GemServerHost.roomArgs` | `gem.room?.args()` | `4.0.0`, for the member | Package API surface, plus runtime delivery |
+| `GemServerHost.roster` | `gem.room?.get()` | `4.0.0`, for the member | Package API surface, plus runtime delivery |
+| `GemMatchServer.roomArgs` | `gem.room?.args()` | `4.0.0`, for the member | Package API surface, plus runtime delivery |
+| `GemMatchServer.roster` | `gem.room?.get()` | `4.0.0`, for the member | Package API surface, plus runtime delivery |
+| `MatchHosting.stop` | `MatchHosting.end` when the match is over, `MatchHosting.leave` to hand it to another host | `5.0.0` | Package API surface |
+| `GemPlayer.displayHandle` | `PlayerIdentity.displayTag` — the same value | `7.0.0` | Package API surface |
+| `GemPlayer.avatarUrl` | `PlayerIdentity.avatarIconUrl` — the same value | `7.0.0` | Package API surface |
+| `profile(playerId)` | The room read's per-member display identity | Not a package release | Runtime delivery only |
+
+**"For the member" is the split from section 3**, and it is the row's real answer: `4.0.0` is
+the earliest release that may take the property off the type, and it says nothing about when a
+server stops putting a value in it.
+
+The last row is the one that is only a guide's. `profile(playerId)` is marked deprecated in
+[`server-bundles.md`](server-bundles.md) and carries no mark in the generated reference, so
+there is no package release to name for it and section 3 is its whole rule.
+
+## 5. What this is not
+
+Three separate things on this platform carry a version. This policy is about one of them, and
+mistaking it for either of the others produces a plan for a rule that does not exist.
+
+- **Not the bridge protocol version.** The handshake between the arcade page and your game
+  negotiates its own version, and `README.md` § "Version negotiation" is the rule that governs
+  it. Different axis, different trigger, and nothing on this page restates or amends it.
+- **Not your game's compatibility line.** Which builds of *your* game can meet in a room is
+  derived from the version the build was published under, and
+  [the compatibility line](platform-rules.md#4-the-compatibility-line) is the rule for that.
+- **Not a removal schedule.** This page names the earliest release that may remove a surface,
+  which is a floor and not a plan. A surface may outlive the release named beside it.

package/docs/friends.md

@@ -0,0 +1,233 @@
+# Friends
+
+Your game can read **who the signed-in player's accepted friends are** — display identity only —
+with the token your frame already holds:
+
+```js
+const page = await gem.friends.list();
+for (const friend of page.friends) {
+  const name = friend.displayName ? text.toPlain(friend.displayName) : 'a friend';
+  render(name, friend.discriminator, platformIconUrl(friend.avatarIconUrl));
+}
+```
+
+That read, and one ask — [sending a friend a challenge](#friend-challenges), which the Arcade
+confirms with the player and sends itself — are the whole surface. The boundary around them is the
+thing to understand before you design against it.
+
+## What the read is, and is not
+
+`gem.friends.list()` returns the player's **accepted** friends: for each one, a `playerId` and —
+when the friend has set them — `displayName`, `discriminator`, `displayTag`, a portrait
+(`avatarIconId` and its thumbnail `avatarIconUrl`) and `badges`. These are the identity fields
+every surface that shows a player carries — the name and tag as `PlayerText` — and
+[Showing a player](what-a-game-must-do.md#showing-a-player-one-identity-on-every-surface) is how to render them. Every field beyond `playerId` is optional, and absent means
+absent: render what is there and fall back per field, because a friend with no display name is
+still a friend.
+
+Everything else about the friend graph stays on the Arcade, by design:
+
+- **No mutations.** There is no add, accept, remove or block here. The graph is managed on
+  platform screens with the player's own account credential — a game frame holds a play token,
+  and a play token cannot touch the graph. Sending a [friend challenge](#friend-challenges) does
+  not touch it either: your game asks, and the Arcade sends only after the player confirms in its
+  own sheet.
+- **No states.** Pending requests, blocks and relationship history do not appear. An accepted
+  friend appears; everyone else does not exist on this surface.
+- **No presence, no invites.** Nothing here says who is online or delivers an invite — an invite
+  is something happening *in* the graph, and it is rendered where the graph lives. See the
+  deliberate-absence notes in [`rooms-and-matches.md`](rooms-and-matches.md). A friend challenge
+  is not an invite to play together: it is a card in the friend's Arcade inbox, written by the
+  platform from your template, that launches your game when they tap it — whenever they next open
+  the Arcade, not now.
+
+Two properties worth designing around rather than discovering:
+
+- **Every accepted friend appears, whether or not they have played your game.** That is the
+  point, not an oversight — an invite-a-friend flow needs exactly the friends who have *not*
+  played it. If you only want friends with progress in your game, join the list against your own
+  data (a friend's `playerId` is the same id leaderboard rows and transfers carry).
+- **It is a player surface only.** On a dedicated server there is no `gem.friends`, and the route
+  refuses a game-server token — a server has no friend list. A server that needs a friend fact is
+  handed it by a client, and must treat it as a claim, not a fact.
+
+## Pagination
+
+The list is paginated behind an opaque cursor: a page carries `nextCursor` exactly when another
+page exists, and you pass it back verbatim.
+
+```js
+let page = await gem.friends.list();
+render(page.friends);
+while (page.nextCursor) {
+  page = await gem.friends.list({ cursor: page.nextCursor });
+  render(page.friends);
+}
+```
+
+Pages default to 50 friends and cap at 200; a player holds at most 1000 friends, so the whole
+list is never more than five max-size pages. Ordering is newest friendship first. Mint nothing:
+a cursor the server did not hand you is refused with `invalid`, not treated as page one.
+
+## Friends and leaderboards
+
+If what you want is a **friend standings screen**, do not build it from this list. Every declared
+board answers a friend view — the same board, re-ranked server-side over the viewer and their
+accepted friends — and that view is the right tool, because ranks are positions within the
+subset and the global board's size cap would make client-side filtering silently lossy.
+[`leaderboards.md`](leaderboards.md) covers it.
+
+## Friend challenges
+
+A **friend challenge** is your game asking the Arcade to send one of the player's friends a
+card — from Kate#0001, saying "Can you open jar 2 in fewer than 9 tries?". The line is your
+template, rendered with your params; the Arcade shows who sent it beside the line, from its own
+records, so no template names the sender. The Arcade shows the player a confirmation sheet in
+its own chrome, sends only if they press Send there, and puts the card in the friend's Arcade
+inbox under "Friend challenges". Tapping it launches your game for the friend, with the
+challenge's params in the launch query.
+
+```js
+challengeButton.onclick = async () => {
+  try {
+    const { outcome } = await gem.friends.challenge({
+      playerId: friend.playerId, // from gem.friends.list()
+      template: 'beat_code_jar', // a friend_challenge_templates key in your config
+      params: { jar: 'K7Q2M9X', n: 2, beat: 9 }, // every param that template declares
+    });
+    if (outcome === 'accepted') challengeButton.textContent = 'Challenge sent';
+    // `cancelled`, `refused` and `unavailable`: carry on, and say nothing.
+  } catch (err) {
+    if (!(err instanceof FriendChallengeError)) throw err;
+    if (err.reason === 'rate_limited') showTryLater(err.retryAfterSeconds);
+    else console.error('friend challenge refused:', err.code, err.param, err.detail);
+  }
+};
+```
+
+**Your game never writes the words.** It names a friend, a template and the template's params;
+the text is your template from the published config (`friend_challenge_templates`, authored with
+`gemctl` — its `game-config` skill covers it), rendered and translated by the platform, and the
+sender's name comes from the platform's own records. So **never put a player's name in a param**:
+the card already says who sent it, and a name in a param is one nobody checked.
+
+### The four answers
+
+`challenge()` resolves for every answer the player or the platform gives, and none of them
+carries a reason:
+
+| outcome | what happened | what to show |
+|---|---|---|
+| `accepted` | the player pressed Send and the platform took it | "Challenge sent", or nothing — the Arcade already said so |
+| `cancelled` | the player closed the sheet, or another prompt already held the screen | **nothing** |
+| `refused` | the platform will not send this one — a guest or signed out, not friends with that player, or no access to this channel | **nothing** |
+| `unavailable` | the Arcade could not offer this, or no answer arrived | **nothing**, and never retry it on your own |
+
+⚠️ **`accepted` is not a delivery receipt.** The platform may decide not to deliver a challenge
+— the friend muted your game, has had enough challenges today, or cannot receive them — and
+answers exactly as if it had. That is deliberate: those are facts about players' accounts, and
+your game must not be able to learn them one challenge at a time. There is no "sent" list and no
+read receipt either.
+
+`refused` is not a verdict on the player's account either: age and moderation never produce it.
+A player the platform will not let send is answered `accepted` or `cancelled`, by design.
+
+`unavailable` does not prove nothing was sent, only that no answer arrived.
+
+### The two that reject
+
+Two answers are yours to fix, and they reject with a `FriendChallengeError` — a `GemApiError`, so
+existing `instanceof GemApiError` handling keeps working:
+
+- **`invalid`** — the request was malformed or the platform refused it as such. `code` says
+  which:
+  - `recipient_invalid` — `playerId` is not a player id;
+  - `unknown_template` — no template with that key is on this channel;
+  - `template_not_on_channel` — the template exists, but the config promoted to this channel
+    does not carry it. Only a member of your team is told this, with `channel` and
+    `configVersion`; everyone else gets `unknown_template`. Promote the config, then try again by
+    hand;
+  - `param_invalid` — a param's value is not what the template declares (`param` names the key
+    when one is at fault);
+  - `param_undeclared` — a param the template does not declare, or more than 8.
+
+  The SDK checks the shape before asking — a player id, a template key of lowercase letters,
+  digits, `_` and `-`, a plain object of strings and integers, at most 8 keys — so most of these
+  reach you before anything is shown to the player. `detail` is the platform's sentence, for your
+  console, never for a player.
+- **`rate_limited`** — the player has sent too many. `retryAfterSeconds` is the earliest a fresh
+  press could succeed, and it can be up to a day.
+
+### Rules that are not optional
+
+- **Call it only from a player's press.** Each call puts a sheet in front of the player. Never on
+  a timer, at start-up, or once per friend in a loop.
+- **Never retry it automatically** — not on `unavailable`, and not on `rate_limited` even though
+  that error is `retryable`. Only a fresh press may ask again.
+- **One ask per press.** Calls are not joined, and an ask arriving while a sheet is open is
+  answered `cancelled`.
+- **Never write "today" in a template.** A challenge never expires, so a friend may open it a
+  week later. Pass a `date` param and let the line say which day.
+- **Hide the button where it cannot work.** `gem.frame.parentSupports('friendChallenges')` is
+  false outside the Arcade — a local dev host included — and `challenge()` answers `unavailable`
+  there at once, asking nothing. Try the real flow on your game's dev channel in the Arcade.
+
+### When a challenge launches your game
+
+The friend's tap opens your game with the challenge's params in its launch query, read exactly as
+[your own launch keys](getting-started.md#linking-to-your-game) are: the param keys are
+launch-query keys, and every value arrived in a link, so validate it the same way. The Arcade adds
+one key of its own, `gemChallenge`, which is the platform's, not yours: never parse it. The SDK
+method that reads it ships in a later release.
+
+**A relaunch replays the same challenge.** When the player presses Play again in the Arcade, it
+reuses the launch query, so the same params arrive again. Make answering a challenge idempotent:
+a second run of the same challenge is a replay, not a new one.
+
+## Inspecting a player: game profiles
+
+The "inspect this player" screen — tap a roster row, a leaderboard entry or a friend, see who
+they are and how far they have come — is one read:
+
+```js
+const profile = await gem.profiles.of(playerId);
+if (!profile) {
+  renderUnavailable(); // no such player — or they blocked you; you cannot tell
+} else {
+  const name = profile.displayName ? text.toPlain(profile.displayName) : 'Anonymous player';
+  renderHeader(name, profile.discriminator, platformIconUrl(profile.avatarIconUrl));
+  for (const entry of profile.showcase) render(entry.key, entry.value);
+}
+```
+
+One response carries the player's display identity (the same optional fields a friend row has)
+plus **every showcase value your relationship to them admits**: `public` slots if you are anyone
+in the game, `friends` slots too if you are an accepted friend, everything if it is your own
+profile. Entries arrive ordered by key, each naming its slot's declared `visibility`.
+
+Three properties to design around:
+
+- **A game shapes its profile in the game config, not here.** Profile content *is* the game's
+  showcase slots — save schemas declared with a `visibility` of `friends` or `public` — and the
+  write path is `gem.showcase.set` (or your dedicated server, for values a modified client must
+  not forge). There is no profile write on this surface, and identity is the player's own,
+  managed on the Arcade. The showcase section of
+  [`saving-player-progress.md`](saving-player-progress.md) covers declaring and writing slots.
+- **`null` is deliberately two answers at once.** An unknown player and a player who blocked the
+  viewer are the same `profile_not_found`, so a response can never reveal which. Do not build UI
+  that tries to distinguish them.
+- **An empty `showcase` is a real profile, not a failure.** A real, unblocked player with nothing
+  visible to you still answers — identity and an empty list. Render "nothing to show", and
+  render a profile with no display fields as anonymous rather than broken.
+
+Where does a `playerId` come from? Anywhere the platform names a player: `gem.friends` rows,
+leaderboard entries, match rosters, transfer counterparties — they all carry the same id this
+read takes.
+
+## Testing a friends screen
+
+The SDK ships no seeded mock ([`what-a-game-must-do.md`](what-a-game-must-do.md) says why), so if
+you stub this surface in your own tests, stub the states the type does not force on you: a friend
+with no display fields at all, the friendless empty state — every friends screen must survive a
+player who knows nobody — and a list long enough to page, because the cursor loop is code that
+otherwise first runs in production against the one player with 300 friends.