@indiegems/gem-web-sdk 7.3.1 → 7.4.1

package/docs/leaderboards.md

@@ -0,0 +1,277 @@
+# Leaderboards
+
+Games do not have to rank anything. This is a capability, not an obligation — but if your game
+has a score, a fastest time, or a longest streak worth comparing between players, the platform
+can hold the standings and your game can read them with the token your frame already holds.
+
+A leaderboard here is **read-only from the browser, by design**. Your game reads standings and
+renders them; it cannot write a score, because a browser credential is public and a
+client-asserted score would be forgeable. Where the rows actually come from is covered
+[below](#where-the-rows-come-from) — read that section before you design around this feature,
+because it decides whether your game can use it at all today.
+
+## Which read do you want
+
+One declaration, four reads. Picking the wrong one is the commonest mistake here, and the
+tempting shortcut — read the global board and filter it client-side for the player — is the wrong
+answer twice over: `maxSize` caps the board, so a player outside the cut simply is not in the
+response, and their rank among everyone is not the rank most screens want anyway.
+
+| Read                                          | Ranks                          | `rank` means                       | Freshness                                |
+| --------------------------------------------- | ------------------------------ | ---------------------------------- | ---------------------------------------- |
+| `gem.leaderboards.get(id)`                    | everyone, capped at `maxSize`  | position on the whole board        | cached; poll at `updateFrequencySeconds` |
+| `gem.leaderboards.friends(id)`                | the viewer and their friends   | position within that circle        | cached, per viewer, same cadence         |
+| `gem.leaderboards.mine(id)`                   | the player, against themselves | **your own** best-to-worst         | exact when read — do not poll            |
+| `gem.leaderboards.character(id, characterId)` | one character, against itself  | **that character's** best-to-worst | exact when read — do not poll            |
+
+`mine()` is the one to reach for when the question is _"is this a personal best?"_ or _"show my
+last runs"_. `get()` is for a standings screen. `friends()` is for a standings screen among people
+the player knows.
+
+`character()` is `mine()` for a character. **Read the leg your server WRITES.** Runs carry the
+entity that owns them, so if your server reports character-owned runs, `mine()` returns nothing and
+`character()` is the read you want — and vice versa. That mismatch is the commonest reason one of
+these boards is unexpectedly empty, and it is silent: both legs answer `200` with `entries: []`.
+
+## Two roles, and they are not the same person
+
+The same split as save slots: one half is something you publish, the other is code.
+
+|                       | Who                      | When                                |
+| --------------------- | ------------------------ | ----------------------------------- |
+| **Declaring a board** | you, the developer       | once, in your game config           |
+| **Reading a board**   | your game's running code | whenever a standings screen renders |
+
+A board your config does not declare does not exist: reading it is refused with `not_found`,
+at the first call and at every retry after it.
+
+## 1. Declare the board, in your game config
+
+Two sections of the game config work together. A **run type** names the values a single play
+produces — up to two integers and two floats, each with a friendly name — and a **leaderboard**
+says how to rank runs of that type:
+
+```yaml
+run_types:
+  - id: race
+    int_value_1_name: score
+
+leaderboards:
+  - id: top-score
+    run_type: race
+    order_by:
+      - column: int_value_1
+        direction: desc
+    max_size: 100
+    update_frequency_seconds: 600
+```
+
+The friendly name is what your game reads back: a row on this board carries `stats.score`,
+not `stats.int_value_1`. `max_size` caps the board at up to 1000 rows, and
+`update_frequency_seconds` is how often the served board refreshes — more on that below.
+
+Three flags decide what a row shows, all declared on the board rather than chosen by the
+reader: `expose_player` (identity — on by default), `expose_stats` (the run's values — on by
+default), and `expose_properties` (the run's freeform properties — off by default).
+
+## 2. Read it, whole
+
+```js
+const board = await gem.leaderboards.get('top-score');
+console.log(`generated ${board.generatedAt}, refreshes every ${board.updateFrequencySeconds}s`);
+for (const row of board.entries) {
+  const name = row.displayName ? text.toPlain(row.displayName) : 'Anonymous player';
+  render(row.rank, name, row.discriminator, row.stats?.score);
+}
+```
+
+A row carries the identity fields every surface that shows a player carries — the name and tag as
+`PlayerText`, the discriminator, the portrait and badges — and a row with no `playerId` is an
+anonymous player who keeps their rank. [Showing a player](what-a-game-must-do.md#showing-a-player-one-identity-on-every-surface) is how to render them.
+
+The whole board arrives in one response, already sorted, at most `max_size` rows. There is no
+paging and nothing further to assemble.
+
+**On the CACHED reads — `get` and `friends` — poll at the cadence the response states, not
+faster.** The platform serves a cached rendering and regenerates it at most once per
+`updateFrequencySeconds`; polling faster re-downloads the same rendering. `generatedAt` says when
+the rendering you hold was made.
+
+That rule is about these two reads only. The entity reads —
+[`mine()`](#one-players-own-runs-mine) and `character()` — carry no cadence, because they are not
+refreshed on one: they are exact when read, and are called on an event rather than on a timer.
+
+Two facts about rows worth designing for:
+
+- **A player can hold several rows.** Ranks are per run, arcade-style — the same player's
+  second-best run is still on the board if it ranks.
+- **An anonymous row is still a row.** A deleted player's entry keeps its rank — removing it
+  would shift everyone below it — and arrives with an `entityId` but no display fields. Render
+  it as "anonymous" rather than skipping it, or every rank under it will look wrong.
+
+## Buckets — one declaration, many boards
+
+A board that declares `bucket_by` is partitioned: each distinct bucket value is its own board
+with its own ranks. Declare the bucket column on the run type, list its allowed values, and
+name the bucket when you read:
+
+```yaml
+run_types:
+  - id: race
+    int_value_1_name: score
+    bucket_1_name: region
+    bucket_1_allowed_values: [na, eu]
+
+leaderboards:
+  - id: regional
+    run_type: race
+    order_by:
+      - column: int_value_1
+        direction: desc
+    bucket_by: [bucket_1]
+```
+
+```js
+const board = await gem.leaderboards.get('regional', { bucket1: 'na' });
+```
+
+A bucketed board owes exactly its declared buckets — omitting one, or supplying one the board
+does not declare, is refused with `invalid`.
+
+## Friends — the same board, restricted to people the player knows
+
+Every declared board also answers a **friend view**: `GET /v1/leaderboards/{id}/friends` is the
+same board — same run type, ordering, buckets, expose flags, `max_size` cap and freshness window —
+ranking only the runs owned by the viewer and their accepted friends. The friend set is resolved
+on the backend at generation time, and the re-ranking is the platform's work: your game is handed
+finished rows and joins nothing. Your game _can_ also read the friend list itself now —
+`gem.friends`, covered in [`friends.md`](friends.md) — but that does not replace this view. A
+friend standings screen wants the ranked subset, not a list to filter the global board by, and
+the global board's `max_size` cap means filtering it client-side would silently drop any friend
+ranked below the cutoff.
+
+```js
+const board = await gem.leaderboards.friends('top-score');
+for (const row of board.entries) {
+  const name = row.displayName ? text.toPlain(row.displayName) : 'Anonymous player';
+  render(row.rank, row.isViewer ? 'you' : name, row.stats?.score);
+}
+```
+
+Four ways a friend view differs from the board it restricts:
+
+- **Ranks are positions within the view,** not the run's global rank — a friend circle has its
+  own first place.
+- **The viewer's own rows say so.** They carry `isViewer: true` — present even on a board that
+  hides identity fields, because the viewer is being told about their own row, nobody else's. On
+  `gem.leaderboards.get` the field is **absent**, not `false`: a global board does not answer that
+  question at all, and the difference matters if you write `row.isViewer ? 'you' : name`.
+- **It is a player surface only.** A game server token is refused — a server has no friend
+  list — and character-owned runs are not ranked here, because friendship is a player-to-player
+  relation.
+- **The cache is per viewer,** on the same `update_frequency_seconds` cadence — a new friendship,
+  or a friend's new run, appears within one window.
+
+A bucketed board buckets its friend view the same way: name the buckets in the query string
+(`/v1/leaderboards/regional/friends?bucket_1=na`), owing exactly the buckets the board declares.
+
+## One player's own runs — `mine()`
+
+The two reads above rank a _field_. This one ranks **one entity against itself**: your own runs on
+a board, best first, so `rank: 1` is your personal best. It is the read behind "New personal
+best!", and behind a run-history panel.
+
+⚠️ **Before you write it, read [Where the rows come from](#where-the-rows-come-from) below.** A
+browser cannot report a run, so a game where neither a dedicated server nor a serverless function
+reports runs will get an empty board here forever — and empty is also the correct answer for every
+player's first session, so the two are indistinguishable from the response alone. That is the
+single most likely reason this returns nothing.
+
+```js
+const mine = await gem.leaderboards.mine('time-trial');
+if (mine.personalBest) showBest(mine.personalBest.stats?.finish_ms);
+for (const row of mine.entries) render(row.rank, row.stats?.finish_ms);
+```
+
+**When to call it.** Not on a timer — there is deliberately no `updateFrequencySeconds` on the
+result, because the read is exact when made rather than refreshed on a cadence. Call it once a run
+has been reported. ⚠️ Reporting is your _server's_ job, or your function's, and your client has no
+happens-after edge with a server: a read fired the instant a match ends can legitimately miss the
+run just played. Read it when your server has told your client the run landed, or once the function
+that recorded it has answered.
+
+Five things that differ from the reads above:
+
+- **`rank` is a position among this entity's own runs**, not a global rank. It is the number most
+  games actually want, and the one the global board cannot give you unless the player happens to be
+  on it.
+- **`personalBest` is returned outright**, and is the same row as `entries[0]`. Render one or the
+  other, not both. It is `null` when the entity has no eligible run.
+- **`totalRuns` counts your eligible runs before `limit`** and after any bucket filter, and is
+  capped — past the cap `totalRunsExact` goes `false` and the honest rendering is `` `${totalRuns}+` ``.
+  A run missing a value the board sorts on is not on the board and is not counted.
+- **`limit` (1–100, default 25) slices; it does not select.** A read at `limit=5` and a read at the
+  default return the same list, cut differently. There is no cursor: history deeper than the cap is
+  not reachable here.
+- **`expose_stats: false` means something different here.** On the reads above it hides stats
+  entirely; here it narrows them to the columns the board _sorts on_ — the numbers being ranked.
+  A run type may name a column no board orders by, and that is where server-authored values live,
+  so those stay hidden.
+
+**Characters: read the leg your server writes.** Runs carry the entity that owns them, so a game
+whose server reports character-owned runs gets nothing from `mine()`, and vice versa. That mismatch
+is the second most likely reason a board looks empty.
+
+```js
+const theirs = await gem.leaderboards.character('time-trial', characterId);
+```
+
+## Where the rows come from
+
+Runs are reported **from the server side** — by a dedicated server during its match, or by your
+game's serverless function — never from the browser. That is the integrity model: the standings
+are only worth rendering because nothing a player controls can write to them.
+
+Two consequences to plan around:
+
+- A game whose matches run entirely in the browser (single-player, or peer-to-peer multiplayer)
+  reaches a board through a serverless function, which checks a finished run and records it with
+  no match and no server of yours:
+  [What `call-api` can reach](serverless-functions.md#what-call-api-can-reach). ⚠️ A function
+  that records the score its client sent, unchecked, hands players the write this model keeps
+  from them. Otherwise its scoring matches need to be dedicated-server matches —
+  [`dedicated-server-flow.md`](dedicated-server-flow.md). If what you
+  wanted was competition rather than a ranking, [`async-opponents.md`](async-opponents.md) is the
+  mode that needs no server of yours: the platform holds a snapshot of one player's run for another
+  player's game to play against later.
+- The server-bundle call that reports runs is **not available yet**. The read surface this page
+  documents works today, and a board with no runs yet is an ordinary empty board — `entries` is
+  `[]`, which your standings screen must render as a designed state, because every new game's
+  board starts that way.
+
+## When a read is refused
+
+**Branch on `err.code` when the server sent one, and on `err.reason` otherwise.** They are
+different fields with different vocabularies, and mixing them is the easy mistake: `bad_request` is
+a `code`, and testing `err.reason === 'bad_request'` never matches, because a 400 arrives as
+`reason: 'invalid'`.
+
+| What you get                                                                        | What happened                                                                                                                                                                                      | What to do                                                                                                                                                                                                                                                                                                                               |
+| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `reason: 'not_found'`, `code: 'leaderboard_not_found'`                              | no board with this id in the channel's active config                                                                                                                                               | check the id against your config, and that the config is assigned to the channel you are on                                                                                                                                                                                                                                              |
+| `reason: 'invalid'`, `code: 'invalid_bucket'`                                       | bucket values do not match the board's `bucket_by`                                                                                                                                                 | supply exactly the buckets the board declares                                                                                                                                                                                                                                                                                            |
+| `reason: 'not_found'`, `code: 'leaderboard_not_found'`, on `mine()` / `character()` | **also** the entity is not one you may read — an unknown character, one you do not own, one in another game, or a malformed id                                                                     | **the same code as the row above**, which is the point: the entity read answers ONE refusal for every reason that depends on the target, deliberately, because a distinguishable answer would tell a caller whether a given player plays this game. Check the entity id as well as the board id — nothing in the response separates them |
+| `reason: 'forbidden'`, on `mine()` / `character()` / `friends()`                    | the caller may not act for this entity at all, or (on `friends()`) carries no player identity at all — a game server token, say. Decided from the caller's own claims, not from what was asked for | this one is worth telling apart, and it is not about the target: it will not start working because the player played more. Treat it as a bug in how the call was made, not as an empty board. `get()` never answers this — the global board needs no viewer                                                                              |
+| `reason: 'invalid'`, `code: 'bad_request'`                                          | `limit` is not an integer in 1–100                                                                                                                                                                 | the SDK refuses this locally with a `TypeError` before any request, so seeing it from the server means something else built the URL                                                                                                                                                                                                      |
+| `TypeError` (thrown, no request sent)                                               | `limit` out of range, passed to `mine()` / `character()`                                                                                                                                           | pass an integer 1–100, or omit it for the default 25                                                                                                                                                                                                                                                                                     |
+
+The _target-dependent_ refusals on the entity read are deliberately uninformative and that is the
+feature: "no such board", "no such entity" and "not yours" are one answer. Do not build retry or
+fallback logic that tries to tell those apart — there is nothing there to read. `forbidden` is not
+an exception to that set so much as outside it: it is about the caller rather than the target, so
+it stays distinguishable and is worth its own branch.
+
+**A session that cannot be refreshed is not in this table.** The SDK replays a `401` against a
+fresh token and, if that fails too, raises `AuthError` rather than `GemApiError` — a different
+class, and one that carries no `reason` at all. A `catch` written from this table alone falls
+through it.

package/docs/manifest.json

@@ -0,0 +1,135 @@
+{
+  "$comment": [
+    "When each published guide in this folder last changed. Written by",
+    "`node scripts/docs-manifest.mjs`; `--check` fails when a guide changed and its",
+    "entry did not. `updated` is when the change was recorded, not when it shipped."
+  ],
+  "schema_version": 1,
+  "documents": [
+    {
+      "file": "achievements.md",
+      "sha256": "2bb4790db96a48171826a9cb3ea8e517d9128f07e55b1fd71b072a491021a15b",
+      "updated": "2026-09-28T01:10:05Z"
+    },
+    {
+      "file": "analytics.md",
+      "sha256": "3ca38659d3c7fd9087d0f17d6c0a31659246724c227cf63701e1bd9a058f0df2",
+      "updated": "2026-09-16T22:32:35Z"
+    },
+    {
+      "file": "arcade-economy.md",
+      "sha256": "7840941e761c1a460b6dc83ed4cec1ae8838161e0b37ec16cb184c66ccee1385",
+      "updated": "2026-10-01T19:42:50Z"
+    },
+    {
+      "file": "async-opponents.md",
+      "sha256": "9bf14e66a03c4cbdc21208456eabae13fa419ebdfa09db6cac708f21610014d7",
+      "updated": "2026-09-28T19:56:41Z"
+    },
+    {
+      "file": "brand-art.md",
+      "sha256": "cf54939a0fcee1f5a6e11b9de52b5ed498ec8c373683e92aa5bc6654b12eb0ab",
+      "updated": "2026-10-01T03:49:20Z"
+    },
+    {
+      "file": "cross-promotion.md",
+      "sha256": "3a8121a9c973e4a1bfed076a3226d139f8b4e38a173a06ea9f08000c72bca4b4",
+      "updated": "2026-09-29T17:32:40Z"
+    },
+    {
+      "file": "daily-challenges.md",
+      "sha256": "6b3fac0f91442561e45af35ee1213685b007f27782fd40434eb1bf2423de797e",
+      "updated": "2026-10-01T16:38:53Z"
+    },
+    {
+      "file": "dedicated-server-flow.md",
+      "sha256": "06dfa9341e924628f67d33e8751f523ea27a3bc91eb07f1f52aadc5e2aa62de7",
+      "updated": "2026-09-24T19:20:12Z"
+    },
+    {
+      "file": "deprecation-policy.md",
+      "sha256": "2923c4af22f266bb545e0218efb3ffb3c7cc7184ea538e431b6b87352c6b9e51",
+      "updated": "2026-09-24T16:41:50Z"
+    },
+    {
+      "file": "friends.md",
+      "sha256": "1c0a427a4e86d4c0e48faad9a80bdef9d528a60485b5aadee18d7759d9051e63",
+      "updated": "2026-10-01T16:38:53Z"
+    },
+    {
+      "file": "game-economy-tutorial.md",
+      "sha256": "7c94ec70c9e2490bdef23b92743b48409a3c6e22d9f26aff8c09fd86af84eae1",
+      "updated": "2026-10-01T19:42:50Z"
+    },
+    {
+      "file": "getting-started.md",
+      "sha256": "00ca91b36945d37bade4954a204b3bcb9af39c142011647220b3c7a4c587d44f",
+      "updated": "2026-10-01T19:58:52Z"
+    },
+    {
+      "file": "inventory-and-catalogs.md",
+      "sha256": "23de4799808ec3745664eb8c8fd948891921d5077535e27155c7e4ed4b584fd8",
+      "updated": "2026-10-01T19:42:50Z"
+    },
+    {
+      "file": "leaderboards.md",
+      "sha256": "940be101a9a06a6ddad85a1afe18a23e9acca43772d158ff7be70ed0f2f6b28d",
+      "updated": "2026-09-28T19:46:26Z"
+    },
+    {
+      "file": "match-session.md",
+      "sha256": "738c54766f5489ba7509f5f31ef1387a2a80ad89f03eaccd52113a18f2765b0d",
+      "updated": "2026-09-25T21:03:24Z"
+    },
+    {
+      "file": "p2p-and-parties.md",
+      "sha256": "3887bc706d098014cefab84e9b8bd5b964841888c242a7ccb1f799a9b9723fc0",
+      "updated": "2026-09-24T01:00:22Z"
+    },
+    {
+      "file": "platform-rules.md",
+      "sha256": "269f2d75a717de583af5ca7e0b91655a2d1edcedb5745c6f2d6f8f0be4dcfbdc",
+      "updated": "2026-09-27T19:51:18Z"
+    },
+    {
+      "file": "player-sign-in.md",
+      "sha256": "df1e39628ccba04b6f7bcd0b90381dfa34a4480330a6af041d9b71bcaefddb5f",
+      "updated": "2026-09-17T20:51:57Z"
+    },
+    {
+      "file": "room-shapes.md",
+      "sha256": "5aab02d65a7573ac690649b70e5db4fed4f779c3102c35e64a8ced02218410a9",
+      "updated": "2026-09-29T23:14:43Z"
+    },
+    {
+      "file": "rooms-and-matches.md",
+      "sha256": "d8c397bc3657d7f46dba7ca0af81dcf181148df798dbaced27dfd294889a1da6",
+      "updated": "2026-09-25T02:14:45Z"
+    },
+    {
+      "file": "saving-player-progress.md",
+      "sha256": "e556b9ef033b0ae611a7d136da3422c8145367939848eda193ab2674087c884f",
+      "updated": "2026-10-01T18:37:21Z"
+    },
+    {
+      "file": "server-bundles.md",
+      "sha256": "d9a5cac21415179fceb8b5d584e7563820634558f01ebeb4c2aa9ce56dad0139",
+      "updated": "2026-10-01T19:58:52Z"
+    },
+    {
+      "file": "serverless-functions.md",
+      "sha256": "3b61ee955d3bc439c39a7cad9339f8ffe8c0fb584f0a25621b877e185160a45a",
+      "updated": "2026-10-01T18:13:51Z"
+    },
+    {
+      "file": "trading-and-gifting.md",
+      "sha256": "d7ee3c85540ab8aae29988c16a76bee3ba03cc66b10d2faaf5cd7210a80a0544",
+      "updated": "2026-08-26T03:27:49Z"
+    },
+    {
+      "file": "what-a-game-must-do.md",
+      "sha256": "f34156c8e369197a1b7ce010ccd837e5ee38cd20150c3836e9da8f38811b06e6",
+      "updated": "2026-10-01T19:03:17Z"
+    }
+  ]
+}