@diffenderfer-games/hub 0.0.0-stage → 2.0.0-next.1

package/src/core/errors.ts

@@ -0,0 +1,147 @@
+/**
+ * The errors every hub call throws: {@link HubError} and its two kinds,
+ * {@link OfflineError} and {@link ContentRejectedError}. The fields come from
+ * the contract's error body (`{ error, code, reason, hint, retryAfterMs, until }`).
+ */
+import type { ErrorCode, RejectReason } from '@diffenderfer-games/hub-contract';
+import { isRecord, optionalNumber, optionalString } from './storage/json-guards';
+
+/**
+ * The code a client gives a call the hub does not have yet (a newer client on
+ * an older hub, plan §4.3.3). Deploy the hub first, or use an older client.
+ */
+export const UNSUPPORTED_BY_HUB = 'unsupported_by_hub';
+
+/** The code the social runtime gives a call it could not send (no connection). */
+export const OFFLINE_CODE = 'offline';
+
+/**
+ * A machine-readable error code: one of the contract's public codes
+ * (`content_rejected`, `rate_limited`, `suspended`, `claim_required`, ...),
+ * {@link UNSUPPORTED_BY_HUB}, or a code a newer hub added.
+ */
+export type HubErrorCode = ErrorCode | typeof UNSUPPORTED_BY_HUB | typeof OFFLINE_CODE | (string & Record<never, never>);
+
+/** The machine-readable extras the hub attaches to an error body. */
+export interface HubErrorDetails {
+  /** A stable error code, for code to branch on. */
+  readonly code?: HubErrorCode | undefined;
+  /** Why content was refused (`link`, `language`, `muted`, `chat_off`, ...). */
+  readonly reason?: RejectReason | (string & Record<never, never>) | undefined;
+  /** A kid-friendly sentence to show the player. */
+  readonly hint?: string | undefined;
+  /** How long to wait before retrying, in ms (rate limits, mutes). */
+  readonly retryAfterMs?: number | undefined;
+  /** When a suspension or mute ends (epoch ms). */
+  readonly until?: number | undefined;
+}
+
+/**
+ * Thrown by every hub call that fails. `status` is the HTTP status when the
+ * hub answered (401 = not signed in, 404 = unknown game or board, 413 = too
+ * large), or `undefined` for a transport failure (offline, no host). Social
+ * and multiplayer errors also carry {@link HubErrorDetails}.
+ */
+export class HubError extends Error {
+  /** The HTTP status, or `undefined` when the hub could not be reached. */
+  readonly status: number | undefined;
+  /** A stable error code (see {@link HubErrorCode}). */
+  readonly code: HubErrorCode | undefined;
+  /** Why content was refused. */
+  readonly reason: string | undefined;
+  /** A kid-friendly sentence to show the player. */
+  readonly hint: string | undefined;
+  /** How long to wait before retrying, in ms. */
+  readonly retryAfterMs: number | undefined;
+  /** When a suspension or mute ends (epoch ms). */
+  readonly until: number | undefined;
+
+  /** An error with a player-safe `message`, the HTTP `status` (if any) and the body's extras. */
+  constructor(message: string, status?: number, details: HubErrorDetails = {}) {
+    super(message);
+    this.name = 'HubError';
+    this.status = status;
+    this.code = details.code;
+    this.reason = details.reason;
+    this.hint = details.hint;
+    this.retryAfterMs = details.retryAfterMs;
+    this.until = details.until;
+  }
+
+  /** `true` when the failure was a network or transport error, not an HTTP status. */
+  get isOffline(): boolean {
+    return this.status === undefined;
+  }
+}
+
+/** Thrown when an action that genuinely needs the hub is attempted offline. */
+export class OfflineError extends HubError {
+  /** An offline error; the default message is "This needs a connection.". */
+  constructor(message = 'This needs a connection.') {
+    super(message);
+    this.name = 'OfflineError';
+  }
+}
+
+/**
+ * Text was refused by the safety filter (HTTP 422, or a socket ack with
+ * `code: 'content_rejected'`). Keep the player's draft and show `hint`; when
+ * `reason` is `muted` or `rate_limited`, `retryAfterMs` says how long to wait.
+ */
+export class ContentRejectedError extends HubError {
+  /** A content reject with the hub's message, status and extras. */
+  constructor(message: string, status: number | undefined, details: HubErrorDetails) {
+    super(message, status, details);
+    this.name = 'ContentRejectedError';
+  }
+}
+
+/** An error body's fields, read without trusting its shape. */
+export interface ErrorBodyFields extends HubErrorDetails {
+  /** The player-safe sentence, when the body had one. */
+  readonly error?: string | undefined;
+}
+
+/** Read the fields this client understands from an error body (or any thrown object). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: an error body from the hub or an error from another bundle, read field by field
+export function readErrorFields(body: unknown): ErrorBodyFields {
+  if (!isRecord(body)) {
+    return {};
+  }
+  return {
+    error: optionalString(body.error),
+    code: optionalString(body.code),
+    reason: optionalString(body.reason),
+    hint: optionalString(body.hint),
+    retryAfterMs: optionalNumber(body.retryAfterMs),
+    until: optionalNumber(body.until),
+  };
+}
+
+/** The right error class for a failure: a 422 or `content_rejected` is a {@link ContentRejectedError}. */
+export function errorFor(message: string, status: number | undefined, details: HubErrorDetails): HubError {
+  return status === 422 || details.code === 'content_rejected'
+    ? new ContentRejectedError(message, status, details)
+    : new HubError(message, status, details);
+}
+
+/**
+ * Re-create an error from another bundle (the social runtime, or another
+ * client copy on the page) as this bundle's class, so `instanceof` works in
+ * games.
+ */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: whatever another bundle threw
+export function toHubError(thrown: unknown): HubError {
+  if (thrown instanceof HubError) {
+    return thrown;
+  }
+  if (!isRecord(thrown)) {
+    return new HubError(String(thrown));
+  }
+  const fields = readErrorFields(thrown);
+  const message = optionalString(thrown.message) ?? 'Request failed';
+  if (fields.code === OFFLINE_CODE) {
+    return new OfflineError(message);
+  }
+  return errorFor(message, optionalNumber(thrown.status), fields);
+}

package/src/core/game-data.ts

@@ -0,0 +1,38 @@
+/**
+ * A game's own JSON (save payloads, profile data, score metadata) is typed by
+ * the game: `hub.putSave<MySave>(...)`, `hub.getSave<MySave>(...)`. The hub
+ * stores it as opaque JSON, so neither the contract nor this client can check
+ * it against `MySave`: the game vouches for its own type, exactly as with the
+ * v1 client. These two functions are the only places that hand-over happens.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+
+/** Anything a game may store as JSON: an object (interfaces included), an array, text, a number, a boolean or `null`. */
+export type GamePayload = object | string | number | boolean | null;
+
+/** Always true: a game's payload is sent as JSON (`JSON.stringify` drops what JSON can't hold). */
+function isSentAsJson(_payload: GamePayload): _payload is GamePayload & Json {
+  return true;
+}
+
+/** Always true: JSON the game stored is read back as the game's type. */
+function isGameOwnData<TData>(_stored: Json): _stored is Json & TData {
+  return true;
+}
+
+/** A game's payload as the JSON the hub stores. */
+export function toStoredJson(payload: GamePayload): Json {
+  if (isSentAsJson(payload)) {
+    return payload;
+  }
+  throw new TypeError('unreachable: every payload is sent as JSON');
+}
+
+/** JSON the game stored, typed as the game's own type. */
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- the caller names the game's own type; the game vouches for it (see above)
+export function toGameData<TData>(stored: Json): TData {
+  if (isGameOwnData<TData>(stored)) {
+    return stored;
+  }
+  throw new TypeError('unreachable: stored game data is the game\'s own');
+}

package/src/core/hub-economy.ts

@@ -0,0 +1,179 @@
+/**
+ * Analytics, the catalog, favorites, records, inventory and trades. Analytics
+ * calls are fire-and-forget and never throw (telemetry must not break a game);
+ * offline they are buffered and sent when the hub is back. Method names are
+ * the v1 client's, unchanged.
+ */
+import { HubProgress } from './hub-progress';
+import { readLocalFavorites, writeLocalFavorites } from './offline/favorites';
+import { HubError } from './errors';
+import type { EndpointFields, EndpointReply } from './rest/endpoint-types';
+import type { GameAnalytics, GameInfo, GlobalAnalytics, InventorySnapshot } from './types';
+
+/** Goods to grant: item key to quantity, and coins. */
+export type GrantBundle = Omit<EndpointFields<'grantInventoryItems'>, 'slug'>;
+
+/** Goods taken or given in an exchange or a trade. */
+export type TradeBundle = EndpointFields<'exchangeInventoryItems'>['take'];
+
+/** A trade offer's id, as a number or its text. */
+export type TradeId = number | string;
+
+/** Extras for creating or countering a trade. */
+export interface TradeNoteOptions {
+  /** A short note to the other player (moderated). */
+  readonly note?: string;
+}
+
+/** Which trades `listTrades` lists. */
+export type TradeListOptions = Omit<EndpointFields<'listMyTrades'>, 'slug'>;
+
+/** Analytics, catalog, favorites, records, inventory and trades. */
+export class HubEconomy extends HubProgress {
+  /** Record a "play". Call once when the game starts. */
+  recordPlay(): Promise<void> {
+    return this.event('play');
+  }
+
+  /** Record a "heartbeat". Call periodically while the game is active. */
+  heartbeat(): Promise<void> {
+    return this.event('heartbeat');
+  }
+
+  /** Record a custom event. Never throws; offline, events are buffered and sent on reconnect. */
+  async event(type: string): Promise<void> {
+    if (this.slug === null) {
+      return;
+    }
+    if (this.isOffline) {
+      this.store.bufferEvent(type);
+      this.notifyStatus();
+      return;
+    }
+    try {
+      await this.rest.call('recordGameEvent', { ...this.gameFields(), type });
+    } catch (failure) {
+      if (failure instanceof HubError && failure.isOffline) {
+        this.setReachable(false);
+        this.store.bufferEvent(type);
+      }
+    }
+  }
+
+  /** This game's play counts. */
+  analytics(): Promise<GameAnalytics> {
+    return this.withFallback(() => this.rest.call('getGameAnalytics', this.gameFields()), () => ({ slug: this.slug ?? 'app', totalPlays: 0, uniquePlayers: 0, activeNow: 0 }));
+  }
+
+  /** Catalog-wide play counts with a per-game breakdown. */
+  globalAnalytics(): Promise<GlobalAnalytics> {
+    return this.withFallback(() => this.rest.call('getSiteAnalytics'), () => ({ global: { totalPlays: 0, uniquePlayers: 0, activeNow: 0 }, games: [] }));
+  }
+
+  /** The listed games, for "jump to another game" navigation. */
+  listGames(): Promise<{ games: GameInfo[] }> {
+    return this.withFallback(() => this.rest.call('listGames'), () => ({ games: [] }));
+  }
+
+  /** Every board of every game, each with its top `top` entries (default 5). */
+  allLeaderboards(top = 5): Promise<EndpointReply<'listTopOfEveryLeaderboard'>> {
+    return this.withFallback(() => this.rest.call('listTopOfEveryLeaderboard', { top }), () => ({ games: [] }));
+  }
+
+  /**
+   * The starred games (slugs), shown first in the menu's game list. Kept per
+   * account by the hub and mirrored to `localStorage`, so it shows offline.
+   */
+  favorites(): Promise<{ games: string[] }> {
+    return this.withFallback(async () => {
+      const reply = await this.rest.call('listFavoriteGames');
+      writeLocalFavorites(reply.games);
+      return reply;
+    }, () => ({ games: readLocalFavorites() }));
+  }
+
+  /** Star (`isOn = true`) or unstar a game. Needs a connection. */
+  async setFavorite(slug: string, isOn: boolean): Promise<{ games: string[] }> {
+    const reply = await this.rest.call('setGameFavorite', { slug, on: isOn });
+    writeLocalFavorites(reply.games);
+    return reply;
+  }
+
+  /** The player's leaderboard standings, grouped by game (every game, or one via `forSlug`). Empty offline or signed out. */
+  myRecords(forSlug?: string): Promise<EndpointReply<'listMyLeaderboardRecords'>> {
+    return this.withFallback(
+      () => this.rest.call('listMyLeaderboardRecords', forSlug === undefined || forSlug === '' ? {} : { game: forSlug }),
+      () => ({ games: [] }),
+    );
+  }
+
+  /** This game's inventory and coin balance for the current user. */
+  getInventory(): Promise<InventorySnapshot> {
+    return this.withFallback(() => this.rest.call('getMyInventory', this.gameFields()), () => ({ items: [], coins: 0 }));
+  }
+
+  /** Another player's available holdings (to compose a trade). */
+  playerInventory(userId: number): Promise<InventorySnapshot> {
+    return this.withFallback(() => this.rest.call('getPlayerInventory', { ...this.gameFields(), userId }), () => ({ items: [], coins: 0 }));
+  }
+
+  /** Add goods to the player (gameplay rewards); answers the new holdings. */
+  grant(bundle: GrantBundle): Promise<EndpointReply<'grantInventoryItems'>> {
+    return this.rest.call('grantInventoryItems', { ...this.gameFields(), ...bundle });
+  }
+
+  /** An atomic swap with the house: remove `take`, add `give`. */
+  exchange(take?: TradeBundle, give?: TradeBundle): Promise<EndpointReply<'exchangeInventoryItems'>> {
+    return this.rest.call('exchangeInventoryItems', { ...this.gameFields(), ...(take === undefined ? {} : { take }), ...(give === undefined ? {} : { give }) });
+  }
+
+  /** Sell items to the house for coins. */
+  sell(items: Record<string, number>, coins: number): Promise<EndpointReply<'exchangeInventoryItems'>> {
+    return this.exchange({ items }, { coins });
+  }
+
+  /** Buy items from the house with coins. */
+  buy(coins: number, items: Record<string, number>): Promise<EndpointReply<'exchangeInventoryItems'>> {
+    return this.exchange({ coins }, { items });
+  }
+
+  /** Wipe the player's progress in this game (saves, stats, inventory and coins). */
+  resetGame(): Promise<{ ok: true }> {
+    return this.rest.call('resetMyGameProgress', this.gameFields());
+  }
+
+  /** Players this player can trade with in this game. */
+  listPlayers(): Promise<EndpointReply<'listTradePartners'>> {
+    return this.withFallback(() => this.rest.call('listTradePartners', this.gameFields()), () => ({ players: [] }));
+  }
+
+  /** The player's trades (`box`: `incoming` or `outgoing`; `status` filters). */
+  listTrades(opts: TradeListOptions = {}): Promise<EndpointReply<'listMyTrades'>> {
+    return this.withFallback(() => this.rest.call('listMyTrades', { ...this.gameFields(), ...opts }), () => ({ offers: [] }));
+  }
+
+  /** Offer a trade to another player (by id or name). */
+  createTrade(toUser: number | string, give?: TradeBundle, want?: TradeBundle, opts: TradeNoteOptions = {}): Promise<EndpointReply<'createTrade'>> {
+    return this.rest.call('createTrade', { ...this.gameFields(), toUser: String(toUser), ...(give === undefined ? {} : { give }), ...(want === undefined ? {} : { want }), ...opts });
+  }
+
+  /** Accept a trade offered to the player. */
+  acceptTrade(id: TradeId): Promise<EndpointReply<'acceptTrade'>> {
+    return this.rest.call('acceptTrade', { ...this.gameFields(), id: Number(id) });
+  }
+
+  /** Decline a trade offered to the player. */
+  declineTrade(id: TradeId): Promise<EndpointReply<'declineTrade'>> {
+    return this.rest.call('declineTrade', { ...this.gameFields(), id: Number(id) });
+  }
+
+  /** Cancel a trade the player offered. */
+  cancelTrade(id: TradeId): Promise<EndpointReply<'cancelTrade'>> {
+    return this.rest.call('cancelTrade', { ...this.gameFields(), id: Number(id) });
+  }
+
+  /** Answer a trade with a counter-offer. */
+  counterTrade(id: TradeId, give?: TradeBundle, want?: TradeBundle, opts: TradeNoteOptions = {}): Promise<EndpointReply<'counterTradeOffer'>> {
+    return this.rest.call('counterTradeOffer', { ...this.gameFields(), id: Number(id), ...(give === undefined ? {} : { give }), ...(want === undefined ? {} : { want }), ...opts });
+  }
+}

package/src/core/hub-progress.ts

@@ -0,0 +1,205 @@
+/**
+ * Accounts and the player's progress in this game: sign-in, the profile,
+ * saves, stats and leaderboards. Reads fall back to the offline cache; writes
+ * apply to the cache at once and are queued while offline. Method names are
+ * the v1 client's, unchanged.
+ */
+import type { Board, Json, Stats } from '@diffenderfer-games/hub-contract';
+import { HubConnection } from './connection';
+import { toGameData, toStoredJson, type GamePayload } from './game-data';
+import type { ProfilePatch, QueuedScoreOptions } from './offline/queue';
+import type { LeaderboardResult, MeResponse, Profile, Save, SaveMeta, SubmitScoreOptions, SubmitScoreResult, User } from './types';
+
+/** A signed-in user, as the auth calls answer. */
+export interface AuthResponse {
+  /** The signed-in user. */
+  readonly user: User;
+}
+
+/** A stat's new value, as the stat calls answer. */
+export interface StatResult {
+  /** The stat key. */
+  readonly key: string;
+  /** Its value after the update. */
+  readonly value: number;
+}
+
+/** A profile change with the game's own data typed as `TData`. */
+export interface ProfileUpdate<TData extends GamePayload = Json> {
+  /** Shown to other players; `null` clears it. */
+  readonly displayName?: string | null;
+  /** The game's own profile data. */
+  readonly data?: TData;
+}
+
+/** A profile with the game's own data typed as `TData`. */
+function typedProfile<TData>(profile: Profile | null): Profile<TData> | null {
+  return profile === null ? null : { ...profile, data: toGameData<TData>(profile.data) };
+}
+
+/** A save with the game's own data typed as `TData`. */
+function typedSave<TData>(save: Save | null): Save<TData> | null {
+  return save === null ? null : { ...save, data: toGameData<TData>(save.data) };
+}
+
+/** Accounts, profile, saves, stats and leaderboards. */
+export class HubProgress extends HubConnection {
+  /** The current user (or `null`) and the games they have a profile in. */
+  me(): Promise<MeResponse> {
+    return this.withFallback(() => this.rest.call('getCurrentUser'), () => {
+      const profile = this.store.getProfile();
+      return { user: this.store.getUser(), profiles: profile === null ? [] : [{ game: profile.game, displayName: profile.displayName }] };
+    });
+  }
+
+  /**
+   * Make sure a session exists, creating a guest (a random name, no
+   * password) when the player isn't signed in, so progress saves without a
+   * sign-in. Idempotent. Offline, a local guest is used.
+   */
+  ensureGuest(): Promise<AuthResponse> {
+    return this.withFallback<AuthResponse>(() => this.rest.call('ensureGuestSession'), () => {
+      const known = this.store.getUser();
+      if (known !== null) {
+        return { user: known };
+      }
+      const guest: User = { id: 0, username: 'Guest-local', guest: true };
+      this.store.setUser(guest);
+      return { user: guest };
+    });
+  }
+
+  /**
+   * Turn the current guest into a registered account (the same identity, so
+   * all progress carries over). Rejects with 409 when already registered or
+   * the name is taken; the player should `login` instead.
+   */
+  claim(username: string, password: string): Promise<AuthResponse> {
+    return this.withFallback<AuthResponse>(() => this.rest.call('claimGuestAccount', { username, password }), () => this.signInLocally({ id: 0, username, guest: false }));
+  }
+
+  /** Create an account and sign in. (Offline: a local user is stored.) */
+  signup(username: string, password: string): Promise<AuthResponse> {
+    return this.withFallback<AuthResponse>(() => this.rest.call('signUpWithPassword', { username, password }), () => this.signInLocally({ id: 0, username }));
+  }
+
+  /** Sign in. (Offline: a local user is stored so signed-in flows work.) */
+  login(username: string, password: string): Promise<AuthResponse> {
+    return this.withFallback<AuthResponse>(() => this.rest.call('logInWithPassword', { username, password }), () => this.signInLocally({ id: 0, username }));
+  }
+
+  /** Sign out (ends the session shared by every game). */
+  logout(): Promise<{ ok: true }> {
+    return this.withFallback(() => this.rest.call('logOut'), () => {
+      this.store.clearUser();
+      return { ok: true } as const;
+    });
+  }
+
+  private signInLocally(user: User): AuthResponse {
+    this.store.setUser(user);
+    return { user };
+  }
+
+  /** This game's profile for the current user, or `profile: null`. `TData` is the game's own data type. */
+  getProfile<TData = Json>(): Promise<{ profile: Profile<TData> | null }> {
+    return this.withFallback(
+      async () => ({ profile: typedProfile<TData>((await this.rest.call('getGameProfile', this.gameFields())).profile) }),
+      () => ({ profile: typedProfile<TData>(this.store.getProfile()) }),
+    );
+  }
+
+  /** Create or update this game's profile for the current user. */
+  setProfile<TData extends GamePayload = Json>(patch: ProfileUpdate<TData>): Promise<{ profile: Profile<TData> }> {
+    const queued: ProfilePatch = {};
+    if (patch.displayName !== undefined) {
+      queued.displayName = patch.displayName;
+    }
+    if (patch.data !== undefined) {
+      queued.data = toStoredJson(patch.data);
+    }
+    return this.mutateQueued({ kind: 'setProfile', patch: queued }, () => {
+      const stored = this.store.setProfile(this.slug ?? 'app', patch.displayName ?? null, queued.data ?? {});
+      return { profile: { ...stored, data: toGameData<TData>(stored.data) } };
+    });
+  }
+
+  /** Metadata for every save slot (no payloads), newest first. */
+  listSaves(): Promise<{ saves: SaveMeta[] }> {
+    return this.withFallback(() => this.rest.call('listSaves', this.gameFields()), () => ({ saves: this.store.listSaves() }));
+  }
+
+  /** One slot's contents, or `save: null` when the slot is empty. `TData` is the game's own save type. */
+  getSave<TData = Json>(slot: string): Promise<{ save: Save<TData> | null }> {
+    return this.withFallback(
+      async () => ({ save: typedSave<TData>((await this.rest.call('getSave', { ...this.gameFields(), slot })).save) }),
+      () => ({ save: typedSave<TData>(this.store.getSave(slot)) }),
+    );
+  }
+
+  /** Create or overwrite a save slot. `saveData` is any JSON up to 64 KB. */
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- kept so v1 calls such as putSave<MySave>(...) still compile
+  putSave<TData extends GamePayload = Json>(slot: string, saveData: TData, label?: string): Promise<{ ok: true; updatedAt: number }> {
+    const stored = toStoredJson(saveData);
+    return this.mutateQueued({ kind: 'putSave', slot, data: stored, label: label ?? null }, () => ({ ok: true as const, updatedAt: this.store.putSave(slot, stored, label ?? null) }));
+  }
+
+  /** Delete a save slot. */
+  deleteSave(slot: string): Promise<{ ok: true }> {
+    return this.mutateQueued({ kind: 'deleteSave', slot }, () => {
+      this.store.deleteSave(slot);
+      return { ok: true as const };
+    });
+  }
+
+  /** Numeric stats for the current user, or another player's via `userId`. */
+  getStats(userId?: number): Promise<{ stats: Stats }> {
+    return this.withFallback(
+      () => this.rest.call('getGameStats', { ...this.gameFields(), ...(userId === undefined ? {} : { user: userId }) }),
+      () => ({ stats: this.store.getStats() }),
+    );
+  }
+
+  /** Overwrite a stat. */
+  setStat(key: string, value: number): Promise<StatResult> {
+    return this.mutateQueued({ kind: 'setStat', key, value }, () => ({ key, value: this.store.updateStat(key, value, 'set') }));
+  }
+
+  /** Add to a stat (creating it at `amount` when absent). */
+  incrStat(key: string, amount = 1): Promise<StatResult> {
+    return this.mutateQueued({ kind: 'incrStat', key, amount }, () => ({ key, value: this.store.updateStat(key, amount, 'incr') }));
+  }
+
+  /** Keep the larger of the stored and the given value. */
+  maxStat(key: string, value: number): Promise<StatResult> {
+    return this.mutateQueued({ kind: 'maxStat', key, value }, () => ({ key, value: this.store.updateStat(key, value, 'max') }));
+  }
+
+  /** Submit a score. The board is created on first use; only a player's best score sticks. */
+  submitScore<TMeta extends GamePayload = Json>(boardKey: string, score: number, opts: SubmitScoreOptions<TMeta> = {}): Promise<SubmitScoreResult> {
+    const queued: QueuedScoreOptions = {
+      ...(opts.title === undefined ? {} : { title: opts.title }),
+      ...(opts.sort === undefined ? {} : { sort: opts.sort }),
+      ...(opts.meta === undefined ? {} : { meta: toStoredJson(opts.meta) }),
+    };
+    return this.mutateQueued({ kind: 'submitScore', key: boardKey, score, opts: queued }, () => ({ ...this.store.submitScore(boardKey, score, queued), rank: 1 }));
+  }
+
+  /** One board's ranked entries (top `limit`, default 50). Offline: only the player's own best. */
+  getLeaderboard(boardKey: string, limit = 50): Promise<LeaderboardResult> {
+    return this.withFallback(() => this.rest.call('getLeaderboard', { ...this.gameFields(), key: boardKey, limit }), () => {
+      const local = this.store.getBoard(boardKey);
+      if (local === null) {
+        return { board: { key: boardKey, title: boardKey, sortDir: 'desc' }, entries: [] };
+      }
+      const user = this.store.getUser();
+      return { board: local.board, entries: [{ rank: 1, userId: user?.id ?? 0, username: user?.username ?? 'you', score: local.best, meta: null }] };
+    });
+  }
+
+  /** The boards this game owns (keys and titles, no entries). */
+  listLeaderboards(): Promise<{ boards: Board[] }> {
+    return this.withFallback(() => this.rest.call('listGameLeaderboards', this.gameFields()), () => ({ boards: this.store.listBoards() }));
+  }
+
+}