@indiegems/gem-web-sdk 7.6.0 → 7.7.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.6.0. Every symbol below links to its page on the Gem Arcade developer site.
+Generated from `@indiegems/gem-web-sdk/sdk` v7.7.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.
 
@@ -7991,6 +7991,43 @@ What [LeaderboardsApi.mine](https://gemarcade.com/developer/api/game#leaderboard
 Separate from [GetLeaderboardOptions](https://gemarcade.com/developer/api/game#getleaderboardoptions) because `limit` has no meaning
 there — the global board arrives whole.
 
+## LeaderboardPeriod
+
+[LeaderboardPeriod](https://gemarcade.com/developer/api/game#leaderboardperiod)
+
+```ts
+interface LeaderboardPeriod
+```
+
+Which period a `per_period` board's result is for.
+
+A board whose config sets `per_period: true` exists once per period of the
+challenge its run type names: one board for each day of a daily challenge,
+each week of a weekly one. Present on a result exactly when the board is one
+of those; absent — not `null` — on an ordinary board.
+
+⚠️ **Players on the same date share a board, whatever their time zone.** On
+a challenge that follows each player's own time zone (the default), a date
+begins for each player at their own midnight, so one day's board is open for
+about 50 hours worldwide and the standings can still change after YOUR day
+has ended. [LeaderboardPeriod.final](https://gemarcade.com/developer/api/game#leaderboardperiod-final) says when they no longer can.
+
+## PeriodOptions
+
+[PeriodOptions](https://gemarcade.com/developer/api/game#periodoptions)
+
+```ts
+interface PeriodOptions
+```
+
+Which period of a `per_period` board to read. Shared by every read.
+
+Name at most one of [PeriodOptions.periodsBack](https://gemarcade.com/developer/api/game#periodoptions-periodsback) and
+[PeriodOptions.period](https://gemarcade.com/developer/api/game#periodoptions-period); with neither, the read answers for the current
+period. On a board that is not `per_period` both are refused with `invalid`
+rather than ignored — asking an all-time board for yesterday and being
+handed all time would be a different answer with nothing saying so.
+
 ## ShowcaseApi
 
 [ShowcaseApi](https://gemarcade.com/developer/api/game#showcaseapi)
@@ -11038,6 +11075,101 @@ 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.
 
+## LeaderboardPeriod.id
+
+[LeaderboardPeriod.id](https://gemarcade.com/developer/api/game#leaderboardperiod-id)
+
+```ts
+readonly id: string
+```
+
+The period this board is for: the date for a daily challenge, the Monday
+for a weekly, the 1st for a monthly (`2026-10-02`), or a cron challenge's
+start as `2026-10-02T06:00:00Z`.
+
+**This is the board's identity.** Pass it back as
+[GetLeaderboardOptions.period](https://gemarcade.com/developer/api/game#getleaderboardoptions-period) to read this same board again later —
+from a shared link, or a history screen — and key any cache on it.
+
+## LeaderboardPeriod.localDate
+
+[LeaderboardPeriod.localDate](https://gemarcade.com/developer/api/game#leaderboardperiod-localdate)
+
+```ts
+readonly localDate?: string
+```
+
+The period's calendar date, `YYYY-MM-DD` — the same value
+`gem.challenges.list()` gives as `periodLocalDate` for the challenge, so
+the two can be compared. Absent for a cron challenge, which has no date.
+
+## LeaderboardPeriod.startAt
+
+[LeaderboardPeriod.startAt](https://gemarcade.com/developer/api/game#leaderboardperiod-startat)
+
+```ts
+readonly startAt?: number
+```
+
+When this period began for the player the read answered for, in Unix
+seconds. Absent when the read answered for no player — a server or a
+function that named none — on a challenge that follows each player's own
+time zone.
+
+## LeaderboardPeriod.endsAt
+
+[LeaderboardPeriod.endsAt](https://gemarcade.com/developer/api/game#leaderboardperiod-endsat)
+
+```ts
+readonly endsAt?: number
+```
+
+When this period ends for that player, in Unix seconds: their own runs stop
+counting towards this board then.
+
+⚠️ **Not when the board stops changing.** Players in later time zones are
+still on this date after it; see [LeaderboardPeriod.closesAt](https://gemarcade.com/developer/api/game#leaderboardperiod-closesat) and
+[LeaderboardPeriod.final](https://gemarcade.com/developer/api/game#leaderboardperiod-final). Absent exactly when
+[LeaderboardPeriod.startAt](https://gemarcade.com/developer/api/game#leaderboardperiod-startat) is.
+
+## LeaderboardPeriod.opensAt
+
+[LeaderboardPeriod.opensAt](https://gemarcade.com/developer/api/game#leaderboardperiod-opensat)
+
+```ts
+readonly opensAt: number
+```
+
+When this board started accepting runs from anyone, in Unix seconds. `0`
+when the platform sent something this SDK could not read.
+
+## LeaderboardPeriod.closesAt
+
+[LeaderboardPeriod.closesAt](https://gemarcade.com/developer/api/game#leaderboardperiod-closesat)
+
+```ts
+readonly closesAt: number
+```
+
+When this board stops accepting runs from anyone, in Unix seconds. `0`
+when the platform sent something this SDK could not read.
+
+## LeaderboardPeriod.final
+
+[LeaderboardPeriod.final](https://gemarcade.com/developer/api/game#leaderboardperiod-final)
+
+```ts
+readonly final: boolean
+```
+
+`true` once no run can still arrive, so the standings will not change
+again — stop polling, and say "final" if your screen says anything.
+
+While it is `false` the standings may change, **including after the
+viewer's own period has ended**: a "you finished 3rd today" shown at the
+player's midnight can be wrong an hour later. Say "so far" until this is
+`true`.
+
 ## LeaderboardEntry.playerId
 
 [LeaderboardEntry.playerId](https://gemarcade.com/developer/api/game#leaderboardentry-playerid)
@@ -11135,6 +11267,12 @@ readonly occurredAt: number
 
 When the ranked run occurred — Unix seconds.
 
+⚠️ **`0` on a `per_period` board whose challenge follows each player's own
+time zone** (the default `local` boundary). The platform serves no time
+there: beside the board's date, the time of a run would show which time
+zones its player could be in. Render no time for `0` rather than 1970.
+Ranks are unaffected — ties are still broken by the real time.
+
 ## LeaderboardEntry.entityId
 
 [LeaderboardEntry.entityId](https://gemarcade.com/developer/api/game#leaderboardentry-entityid)
@@ -11278,6 +11416,20 @@ interval: polling faster re-downloads the same rendering.
 Absent if the server did not state one. Absent means *unknown*, not
 "refreshes constantly" — do not substitute `0` and poll on it.
 
+## Leaderboard.period
+
+[Leaderboard.period](https://gemarcade.com/developer/api/game#leaderboard-period)
+
+```ts
+readonly period?: LeaderboardPeriod
+```
+
+Which period this result is for, on a board whose config sets
+`per_period`. Absent on an ordinary board, which ranks every run.
+
+Once `period.final` is `true` the board no longer changes and need not be
+polled.
+
 ## RankedRow.rank
 
 [RankedRow.rank](https://gemarcade.com/developer/api/game#rankedrow-rank)
@@ -11296,7 +11448,9 @@ readonly rank: number
 readonly occurredAt: number
 ```
 
-When the ranked run occurred — Unix seconds.
+When the ranked run occurred — Unix seconds. `0` on a `per_period` board
+whose challenge follows each player's own time zone, where the platform
+serves no time; render nothing for it.
 
 ## RankedRow.stats
 
@@ -11326,7 +11480,9 @@ The run's freeform properties.
 readonly occurredAt: number
 ```
 
-When the ranked run occurred — Unix seconds.
+When the ranked run occurred — Unix seconds. `0` on a `per_period` board
+whose challenge follows each player's own time zone, where the platform
+serves no time; render nothing for it.
 
 ## EntityLeaderboardEntry.properties
 
@@ -11488,6 +11644,107 @@ readonly generatedAt: number
 
 When this rendering was computed — Unix seconds.
 
+## EntityLeaderboard.period
+
+[EntityLeaderboard.period](https://gemarcade.com/developer/api/game#entityleaderboard-period)
+
+```ts
+readonly period?: LeaderboardPeriod
+```
+
+Which period these runs are from, on a board whose config sets
+`per_period`: `entries`, `personalBest` and `totalRuns`
+are then that ONE period's, not the entity's whole history. Absent on an
+ordinary board.
+
+## PeriodOptions.periodsBack
+
+[PeriodOptions.periodsBack](https://gemarcade.com/developer/api/game#periodoptions-periodsback)
+
+```ts
+readonly periodsBack?: number
+```
+
+How many periods back to read. `0` — the default — is the current period;
+`1` is yesterday's board for a daily challenge, last week's for a weekly.
+
+An integer from 0 to 400. Anything else is a `TypeError` before the
+request is made.
+
+## PeriodOptions.period
+
+[PeriodOptions.period](https://gemarcade.com/developer/api/game#periodoptions-period)
+
+```ts
+readonly period?: string
+```
+
+The period to read, as an earlier result's [LeaderboardPeriod.id](https://gemarcade.com/developer/api/game#leaderboardperiod-id) —
+for a board reached from a shared link or a history screen. At most 400
+periods back.
+
+⚠️ A period that has not begun for the player is refused, even when it has
+already begun for players in time zones ahead of theirs.
+
+## PeriodOptions.playerId
+
+[PeriodOptions.playerId](https://gemarcade.com/developer/api/game#periodoptions-playerid)
+
+```ts
+readonly playerId?: string
+```
+
+For a serverless function or a dedicated server: the player whose period
+to answer for. Their credential names no player, so without this a
+`per_period` board on each player's own time zone is answered in UTC,
+which is not that player's day.
+
+Ignored in the browser, where the read is always for the signed-in player.
+
+## EntityLeaderboardOptions.periodsBack
+
+[EntityLeaderboardOptions.periodsBack](https://gemarcade.com/developer/api/game#entityleaderboardoptions-periodsback)
+
+```ts
+readonly periodsBack?: number
+```
+
+How many periods back to read. `0` — the default — is the current period;
+`1` is yesterday's board for a daily challenge, last week's for a weekly.
+
+An integer from 0 to 400. Anything else is a `TypeError` before the
+request is made.
+
+## EntityLeaderboardOptions.period
+
+[EntityLeaderboardOptions.period](https://gemarcade.com/developer/api/game#entityleaderboardoptions-period)
+
+```ts
+readonly period?: string
+```
+
+The period to read, as an earlier result's [LeaderboardPeriod.id](https://gemarcade.com/developer/api/game#leaderboardperiod-id) —
+for a board reached from a shared link or a history screen. At most 400
+periods back.
+
+⚠️ A period that has not begun for the player is refused, even when it has
+already begun for players in time zones ahead of theirs.
+
+## EntityLeaderboardOptions.playerId
+
+[EntityLeaderboardOptions.playerId](https://gemarcade.com/developer/api/game#entityleaderboardoptions-playerid)
+
+```ts
+readonly playerId?: string
+```
+
+For a serverless function or a dedicated server: the player whose period
+to answer for. Their credential names no player, so without this a
+`per_period` board on each player's own time zone is answered in UTC,
+which is not that player's day.
+
+Ignored in the browser, where the read is always for the signed-in player.
+
 ## EntityLeaderboardOptions.bucket1
 
 [EntityLeaderboardOptions.bucket1](https://gemarcade.com/developer/api/game#entityleaderboardoptions-bucket1)
@@ -11534,6 +11791,50 @@ readonly signal?: AbortSignal
 
 Abort the read.
 
+## GetLeaderboardOptions.periodsBack
+
+[GetLeaderboardOptions.periodsBack](https://gemarcade.com/developer/api/game#getleaderboardoptions-periodsback)
+
+```ts
+readonly periodsBack?: number
+```
+
+How many periods back to read. `0` — the default — is the current period;
+`1` is yesterday's board for a daily challenge, last week's for a weekly.
+
+An integer from 0 to 400. Anything else is a `TypeError` before the
+request is made.
+
+## GetLeaderboardOptions.period
+
+[GetLeaderboardOptions.period](https://gemarcade.com/developer/api/game#getleaderboardoptions-period)
+
+```ts
+readonly period?: string
+```
+
+The period to read, as an earlier result's [LeaderboardPeriod.id](https://gemarcade.com/developer/api/game#leaderboardperiod-id) —
+for a board reached from a shared link or a history screen. At most 400
+periods back.
+
+⚠️ A period that has not begun for the player is refused, even when it has
+already begun for players in time zones ahead of theirs.
+
+## GetLeaderboardOptions.playerId
+
+[GetLeaderboardOptions.playerId](https://gemarcade.com/developer/api/game#getleaderboardoptions-playerid)
+
+```ts
+readonly playerId?: string
+```
+
+For a serverless function or a dedicated server: the player whose period
+to answer for. Their credential names no player, so without this a
+`per_period` board on each player's own time zone is answered in UTC,
+which is not that player's day.
+
+Ignored in the browser, where the read is always for the signed-in player.
+
 ## GetLeaderboardOptions.bucket1
 
 [GetLeaderboardOptions.bucket1](https://gemarcade.com/developer/api/game#getleaderboardoptions-bucket1)
@@ -11581,14 +11882,28 @@ A bucketed board (config `bucket_by`) needs exactly its bucket values —
 faster than the result's `updateFrequencySeconds`; the server regenerates
 at that cadence and faster polling re-reads the same rendering.
 
+A `per_period` board answers for one period — the current one by default:
+
+```js
+const today = await gem.leaderboards.get('daily');
+const yesterday = await gem.leaderboards.get('daily', { periodsBack: 1 });
+label(today.period.final ? 'Final standings' : 'Standings so far');
+```
+
 | Parameter | Type | Description |
 | --- | --- | --- |
 | `leaderboardType` | `string` | The board's id in your game config. |
 | `options` | `GetLeaderboardOptions` |  |
 
-**Throws.** `not_found` when no board with this id is in the channel's active
+**Throws.** `TypeError` when `periodsBack` is not an integer from 0 to 400,
+  `period` is not a period id, or both are passed — refused before the
+  request.
+
+`not_found` when no board with this id is in the channel's active
   config, `invalid` when bucket values do not match the board's
-  `bucket_by`.
+  `bucket_by`, when a period is asked of a board that is not `per_period`
+  (`code` `invalid_period`), or when the period has not begun for the
+  player (`code` `period_not_begun`).
 
 ## LeaderboardsApi.friends
 
@@ -11619,16 +11934,20 @@ for (const row of board.entries) {
 }
 ```
 
+On a `per_period` board this takes the same `periodsBack` and `period` as
+`get`. A friend in another time zone who is on the same date is on
+the same board.
+
 | Parameter | Type |
 | --- | --- |
 | `leaderboardType` | `string` |
 | `options` | `GetLeaderboardOptions` |
 
 **Throws.** `not_found` when no board with this id is in the channel's active
-  config, `invalid` when bucket values do not match the board's
-  `bucket_by`, and `forbidden` in a context with no player — the friend
-  view is a player surface, and a game server has no friends. (The global
-  `get` declares no such refusal: it needs no viewer.)
+  config, `invalid` when bucket values or a period do not match the board
+  (as on `get`), and `forbidden` in a context with no player — the
+  friend view is a player surface, and a game server has no friends. (The
+  global `get` declares no such refusal: it needs no viewer.)
 
 ## LeaderboardsApi.mine
 
@@ -11664,6 +11983,11 @@ a `200` with no entries, not an error. If it is *always* empty, see
 [LeaderboardsApi](https://gemarcade.com/developer/api/game#leaderboardsapi) on where runs come from: a browser cannot submit
 one.
 
+On a `per_period` board the runs, the personal best and the total are ONE
+period's — the current one unless `periodsBack` or `period` names another
+— so `personalBest` is "your best today", and an empty result at the start
+of a day is the ordinary state.
+
 | Parameter | Type |
 | --- | --- |
 | `leaderboardType` | `string` |

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

@@ -1,6 +1,6 @@
 # The server surface — API reference
 
-Generated from `@indiegems/gem-web-sdk/sdk` v7.6.0. Every symbol below links to its page on the Gem Arcade developer site.
+Generated from `@indiegems/gem-web-sdk/sdk` v7.7.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.