@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.1

package/src/core/ticket.ts

@@ -1,43 +1,43 @@
-/**
- * The own-server ticket request (`hub.mp.ticket()`): a 60-second identity
- * ticket for this game's own server, fetched straight from the hub. It must
- * not depend on the social runtime: on the first visit after a deploy the
- * service worker can still serve an older menu that never loads it. When the
- * page has no session yet, a guest one is created and the request retried
- * once.
- */
-import { HubError, OfflineError } from './errors';
-import { detectApiBase, detectSlug } from './page';
-import { createRestClient, type RestClient } from './rest/rest-client';
-
-/** A REST client for the page's API base that uses the global fetch at call time. */
-function pageRestClient(): RestClient {
-  return createRestClient({ apiBase: detectApiBase(), fetch: (input, init) => globalThis.fetch(input, init) });
-}
-
-/** One ticket request; a transport failure is an {@link OfflineError}. */
-async function requestTicket(rest: RestClient, slug: string): Promise<string> {
-  try {
-    return (await rest.call('getGameServerTicket', { slug })).ticket;
-  } catch (failure) {
-    throw failure instanceof HubError && failure.isOffline ? new OfflineError() : failure;
-  }
-}
-
-/** A ticket for this page's game; signs in a guest first when the page has no session. */
-export async function fetchGameServerTicket(): Promise<string> {
-  const slug = detectSlug();
-  if (slug === null) {
-    throw new HubError('Hub: could not determine the game slug.');
-  }
-  const rest = pageRestClient();
-  try {
-    return await requestTicket(rest, slug);
-  } catch (failure) {
-    if (!(failure instanceof HubError) || failure.status !== 401) {
-      throw failure;
-    }
-    await rest.call('ensureGuestSession');
-    return requestTicket(rest, slug);
-  }
-}
+/**
+ * The own-server ticket request (`hub.mp.ticket()`): a 60-second identity
+ * ticket for this game's own server, fetched straight from the hub. It must
+ * not depend on the social runtime: on the first visit after a deploy the
+ * service worker can still serve an older menu that never loads it. When the
+ * page has no session yet, a guest one is created and the request retried
+ * once.
+ */
+import { HubError, OfflineError } from './errors';
+import { detectApiBase, detectSlug } from './page';
+import { createRestClient, type RestClient } from './rest/rest-client';
+
+/** A REST client for the page's API base that uses the global fetch at call time. */
+function pageRestClient(): RestClient {
+  return createRestClient({ apiBase: detectApiBase(), fetch: (input, init) => globalThis.fetch(input, init) });
+}
+
+/** One ticket request; a transport failure is an {@link OfflineError}. */
+async function requestTicket(rest: RestClient, slug: string): Promise<string> {
+  try {
+    return (await rest.call('getGameServerTicket', { slug })).ticket;
+  } catch (failure) {
+    throw failure instanceof HubError && failure.isOffline ? new OfflineError() : failure;
+  }
+}
+
+/** A ticket for this page's game; signs in a guest first when the page has no session. */
+export async function fetchGameServerTicket(): Promise<string> {
+  const slug = detectSlug();
+  if (slug === null) {
+    throw new HubError('Hub: could not determine the game slug.');
+  }
+  const rest = pageRestClient();
+  try {
+    return await requestTicket(rest, slug);
+  } catch (failure) {
+    if (!(failure instanceof HubError) || failure.status !== 401) {
+      throw failure;
+    }
+    await rest.call('ensureGuestSession');
+    return requestTicket(rest, slug);
+  }
+}

package/src/core/types.ts

@@ -1,134 +1,134 @@
-/**
- * The core client's public types, under the v1 client's names. Each one is
- * the contract's shape (so the contract stays the one source of truth),
- * widened where the offline cache can only know less than the hub (a local
- * user has no role) or made generic over a game's own JSON (`Save<MySave>`).
- */
-import type { Board, GameInfo as ContractGameInfo, Json, Metrics, SessionUser, SortDir } from '@diffenderfer-games/hub-contract';
-import type { GamePayload } from './game-data';
-import type { EndpointReply } from './rest/endpoint-types';
-
-export type { GamePayload } from './game-data';
-
-export type { Board, GameLeaderboards, GameRecords, Inventory, Json, LeaderboardEntry, Metrics, SortDir, Stats } from '@diffenderfer-games/hub-contract';
-
-/** The signed-in player. Offline (a locally stored user) only `id`, `username` and `guest` are known. */
-export type User = Pick<SessionUser, 'id' | 'username'> & Partial<Omit<SessionUser, 'id' | 'username'>>;
-
-/** One game the player has a profile in. */
-export interface ProfileSummary {
-  /** The game's slug. */
-  readonly game: string;
-  /** The player's display name there, or `null`. */
-  readonly displayName: string | null;
-}
-
-/** What `hub.me()` answers: the current user (or `null`) and their game profiles. */
-export interface MeResponse {
-  /** The signed-in player, or `null`. */
-  readonly user: User | null;
-  /** The games the player has a profile in. */
-  readonly profiles: ProfileSummary[];
-}
-
-/** A player's profile in one game, with the game's own data typed as `TData`. */
-export interface Profile<TData = Json> {
-  /** The game's slug. */
-  readonly game: string;
-  /** Shown to other players; `null` when never set. */
-  readonly displayName: string | null;
-  /** The game's own profile data. */
-  readonly data: TData;
-  /** Epoch ms. */
-  readonly updatedAt: number;
-}
-
-/** A save slot's metadata (no payload). */
-export interface SaveMeta {
-  /** The slot key. */
-  readonly slot: string;
-  /** The slot's label, or `null`. */
-  readonly label: string | null;
-  /** Epoch ms. */
-  readonly updatedAt: number;
-}
-
-/** A save slot with its payload typed as `TData`. */
-export interface Save<TData = Json> extends SaveMeta {
-  /** The stored JSON. */
-  readonly data: TData;
-}
-
-/** Options for `hub.submitScore()`, with the score's metadata typed as `TMeta`. */
-export interface SubmitScoreOptions<TMeta extends GamePayload = Json> {
-  /** The board's title; only used when the board key is first created. */
-  readonly title?: string;
-  /** The sort direction; only used on board creation. Default `desc`. */
-  readonly sort?: SortDir;
-  /** Any JSON stored with the entry (a character, a run seed). */
-  readonly meta?: TMeta;
-}
-
-/** What `hub.submitScore()` answers: the board, the player's best and rank (offline: rank 1). */
-export interface SubmitScoreResult {
-  /** The board. */
-  readonly board: Board;
-  /** The player's best score, or `null` when it did not count (a zero on a board that hides zeros). */
-  readonly best: number | null;
-  /** The player's rank, or `null`. */
-  readonly rank: number | null;
-}
-
-/** One board's ranked entries (`hub.getLeaderboard()`). */
-export type LeaderboardResult = EndpointReply<'getLeaderboard'>;
-
-/** A board with its top entries. */
-export type BoardWithTop = EndpointReply<'listTopOfEveryLeaderboard'>['games'][number]['boards'][number];
-
-/** One game's play counts, with its slug (`hub.analytics()`). */
-export type GameAnalytics = EndpointReply<'getGameAnalytics'>;
-
-/** Catalog-wide play counts with a per-game breakdown (`hub.globalAnalytics()`). */
-export interface GlobalAnalytics {
-  /** Across every game. */
-  readonly global: Metrics;
-  /** Per game. */
-  readonly games: (Metrics & { readonly slug: string; readonly title: string })[];
-}
-
-/** A listed game (`hub.listGames()`). */
-export type GameInfo = ContractGameInfo;
-
-/** What `GET /me/snapshot` answers; `hub.prefetchAll()` warms the offline cache for every game from it. */
-export type SnapshotResponse = EndpointReply<'getMyOfflineSnapshot'>;
-
-/** A player's holdings in one game, as the inventory calls answer. */
-export type InventorySnapshot = EndpointReply<'getMyInventory'>;
-
-/** The connection and sync status `hub.onStatus()` reports. */
-export interface HubStatus {
-  /** The hub is reachable. */
-  readonly online: boolean;
-  /** Calls are being served from the offline cache. */
-  readonly offline: boolean;
-  /** Queued writes plus buffered events waiting to sync. */
-  readonly pending: number;
-}
-
-/** How a client created with `createHub()` / `new Hub()` behaves. */
-export interface HubOptions {
-  /** The game's slug. Default: `window.__HUB__.slug`, then the first URL path segment. */
-  readonly slug?: string;
-  /** The API base. Default: `window.__HUB__.apiBase`, then `/_api`. */
-  readonly apiBase?: string;
-  /** A custom fetch (tests, non-browser code). Default: the global fetch. */
-  readonly fetch?: typeof fetch;
-  /**
-   * What to do when the hub can't be reached:
-   * - `auto` (default): try the network; on a connection failure fall back to
-   *   the offline cache in `localStorage`, and sync when the hub is back;
-   * - `always`: never touch the network (develop a game without a hub);
-   * - `never`: never fall back; every call throws when the hub is unreachable.
-   */
-  readonly offline?: 'auto' | 'always' | 'never';
-}
+/**
+ * The core client's public types, under the v1 client's names. Each one is
+ * the contract's shape (so the contract stays the one source of truth),
+ * widened where the offline cache can only know less than the hub (a local
+ * user has no role) or made generic over a game's own JSON (`Save<MySave>`).
+ */
+import type { Board, GameInfo as ContractGameInfo, Json, Metrics, SessionUser, SortDir } from '@diffenderfer-games/hub-contract';
+import type { GamePayload } from './game-data';
+import type { EndpointReply } from './rest/endpoint-types';
+
+export type { GamePayload } from './game-data';
+
+export type { Board, GameLeaderboards, GameRecords, Inventory, Json, LeaderboardEntry, Metrics, SortDir, Stats } from '@diffenderfer-games/hub-contract';
+
+/** The signed-in player. Offline (a locally stored user) only `id`, `username` and `guest` are known. */
+export type User = Pick<SessionUser, 'id' | 'username'> & Partial<Omit<SessionUser, 'id' | 'username'>>;
+
+/** One game the player has a profile in. */
+export interface ProfileSummary {
+  /** The game's slug. */
+  readonly game: string;
+  /** The player's display name there, or `null`. */
+  readonly displayName: string | null;
+}
+
+/** What `hub.me()` answers: the current user (or `null`) and their game profiles. */
+export interface MeResponse {
+  /** The signed-in player, or `null`. */
+  readonly user: User | null;
+  /** The games the player has a profile in. */
+  readonly profiles: ProfileSummary[];
+}
+
+/** A player's profile in one game, with the game's own data typed as `TData`. */
+export interface Profile<TData = Json> {
+  /** The game's slug. */
+  readonly game: string;
+  /** Shown to other players; `null` when never set. */
+  readonly displayName: string | null;
+  /** The game's own profile data. */
+  readonly data: TData;
+  /** Epoch ms. */
+  readonly updatedAt: number;
+}
+
+/** A save slot's metadata (no payload). */
+export interface SaveMeta {
+  /** The slot key. */
+  readonly slot: string;
+  /** The slot's label, or `null`. */
+  readonly label: string | null;
+  /** Epoch ms. */
+  readonly updatedAt: number;
+}
+
+/** A save slot with its payload typed as `TData`. */
+export interface Save<TData = Json> extends SaveMeta {
+  /** The stored JSON. */
+  readonly data: TData;
+}
+
+/** Options for `hub.submitScore()`, with the score's metadata typed as `TMeta`. */
+export interface SubmitScoreOptions<TMeta extends GamePayload = Json> {
+  /** The board's title; only used when the board key is first created. */
+  readonly title?: string;
+  /** The sort direction; only used on board creation. Default `desc`. */
+  readonly sort?: SortDir;
+  /** Any JSON stored with the entry (a character, a run seed). */
+  readonly meta?: TMeta;
+}
+
+/** What `hub.submitScore()` answers: the board, the player's best and rank (offline: rank 1). */
+export interface SubmitScoreResult {
+  /** The board. */
+  readonly board: Board;
+  /** The player's best score, or `null` when it did not count (a zero on a board that hides zeros). */
+  readonly best: number | null;
+  /** The player's rank, or `null`. */
+  readonly rank: number | null;
+}
+
+/** One board's ranked entries (`hub.getLeaderboard()`). */
+export type LeaderboardResult = EndpointReply<'getLeaderboard'>;
+
+/** A board with its top entries. */
+export type BoardWithTop = EndpointReply<'listTopOfEveryLeaderboard'>['games'][number]['boards'][number];
+
+/** One game's play counts, with its slug (`hub.analytics()`). */
+export type GameAnalytics = EndpointReply<'getGameAnalytics'>;
+
+/** Catalog-wide play counts with a per-game breakdown (`hub.globalAnalytics()`). */
+export interface GlobalAnalytics {
+  /** Across every game. */
+  readonly global: Metrics;
+  /** Per game. */
+  readonly games: (Metrics & { readonly slug: string; readonly title: string })[];
+}
+
+/** A listed game (`hub.listGames()`). */
+export type GameInfo = ContractGameInfo;
+
+/** What `GET /me/snapshot` answers; `hub.prefetchAll()` warms the offline cache for every game from it. */
+export type SnapshotResponse = EndpointReply<'getMyOfflineSnapshot'>;
+
+/** A player's holdings in one game, as the inventory calls answer. */
+export type InventorySnapshot = EndpointReply<'getMyInventory'>;
+
+/** The connection and sync status `hub.onStatus()` reports. */
+export interface HubStatus {
+  /** The hub is reachable. */
+  readonly online: boolean;
+  /** Calls are being served from the offline cache. */
+  readonly offline: boolean;
+  /** Queued writes plus buffered events waiting to sync. */
+  readonly pending: number;
+}
+
+/** How a client created with `createHub()` / `new Hub()` behaves. */
+export interface HubOptions {
+  /** The game's slug. Default: `window.__HUB__.slug`, then the first URL path segment. */
+  readonly slug?: string;
+  /** The API base. Default: `window.__HUB__.apiBase`, then `/_api`. */
+  readonly apiBase?: string;
+  /** A custom fetch (tests, non-browser code). Default: the global fetch. */
+  readonly fetch?: typeof fetch;
+  /**
+   * What to do when the hub can't be reached:
+   * - `auto` (default): try the network; on a connection failure fall back to
+   *   the offline cache in `localStorage`, and sync when the hub is back;
+   * - `always`: never touch the network (develop a game without a hub);
+   * - `never`: never fall back; every call throws when the hub is unreachable.
+   */
+  readonly offline?: 'auto' | 'always' | 'never';
+}

package/src/core/version/client-version.gen.ts

@@ -1,3 +1,3 @@
 // Generated by tools/hub-client/generate.ts. Do not edit; run `npm run gen:hub-client` in next/.
 /** This client's package version, sent as `x-hub-client` on REST calls and `client` in `hello`. */
-export const HUB_CLIENT_VERSION = '2.0.0-next.0';
+export const HUB_CLIENT_VERSION = '2.0.0-next.1';

package/src/core/version/hub-version.ts

@@ -1,62 +1,62 @@
-/**
- * The hub's `GET /_api/version`, read at most once per page and API base
- * (plan §4.3.3), and what it says about this client. Nothing reads it on
- * load: it costs a request only when a game (or `hub-doctor`) asks.
- */
-import type { HubVersion } from '@diffenderfer-games/hub-contract';
-import { HubError, UNSUPPORTED_BY_HUB } from '../errors';
-import type { RestClient } from '../rest/rest-client';
-import { HUB_CLIENT_VERSION } from './client-version.gen';
-import { satisfiesRange } from './semver';
-
-/** How a hub regards a client version. */
-export type ClientSupport =
-  /** In `supported` and not `deprecated`. */
-  | 'supported'
-  /** Still supported, but `deprecated`: update soon. */
-  | 'deprecated'
-  /** Outside `supported`: update now. */
-  | 'unsupported'
-  /** The hub predates versioning (the old hub): nothing to compare. */
-  | 'unknown';
-
-/** How `version` fares against a hub's answer (`null`: a hub from before versioning). */
-export function clientSupport(hubVersion: HubVersion | null, version: string = HUB_CLIENT_VERSION): ClientSupport {
-  if (hubVersion === null) {
-    return 'unknown';
-  }
-  if (!satisfiesRange(version, hubVersion.supported)) {
-    return 'unsupported';
-  }
-  return satisfiesRange(version, hubVersion.deprecated) ? 'deprecated' : 'supported';
-}
-
-const versionsByApiBase = new Map<string, Promise<HubVersion | null>>();
-
-/**
- * The hub's version, fetched once per page and API base. Resolves `null` for
- * a hub from before versioning (it has no `/version` route); a failed
- * request is not cached, so a later call tries again.
- */
-export function readHubVersion(rest: RestClient): Promise<HubVersion | null> {
-  const cached = versionsByApiBase.get(rest.apiBase);
-  if (cached !== undefined) {
-    return cached;
-  }
-  const pending = fetchHubVersion(rest);
-  versionsByApiBase.set(rest.apiBase, pending);
-  return pending;
-}
-
-/** One `GET /version`; `null` when the hub has no such route. */
-async function fetchHubVersion(rest: RestClient): Promise<HubVersion | null> {
-  try {
-    return await rest.call('getHubVersion');
-  } catch (failure) {
-    if (failure instanceof HubError && failure.code === UNSUPPORTED_BY_HUB) {
-      return null;
-    }
-    versionsByApiBase.delete(rest.apiBase);
-    throw failure;
-  }
-}
+/**
+ * The hub's `GET /_api/version`, read at most once per page and API base
+ * (plan §4.3.3), and what it says about this client. Nothing reads it on
+ * load: it costs a request only when a game (or `hub-doctor`) asks.
+ */
+import type { HubVersion } from '@diffenderfer-games/hub-contract';
+import { HubError, UNSUPPORTED_BY_HUB } from '../errors';
+import type { RestClient } from '../rest/rest-client';
+import { HUB_CLIENT_VERSION } from './client-version.gen';
+import { satisfiesRange } from './semver';
+
+/** How a hub regards a client version. */
+export type ClientSupport =
+  /** In `supported` and not `deprecated`. */
+  | 'supported'
+  /** Still supported, but `deprecated`: update soon. */
+  | 'deprecated'
+  /** Outside `supported`: update now. */
+  | 'unsupported'
+  /** The hub predates versioning (the old hub): nothing to compare. */
+  | 'unknown';
+
+/** How `version` fares against a hub's answer (`null`: a hub from before versioning). */
+export function clientSupport(hubVersion: HubVersion | null, version: string = HUB_CLIENT_VERSION): ClientSupport {
+  if (hubVersion === null) {
+    return 'unknown';
+  }
+  if (!satisfiesRange(version, hubVersion.supported)) {
+    return 'unsupported';
+  }
+  return satisfiesRange(version, hubVersion.deprecated) ? 'deprecated' : 'supported';
+}
+
+const versionsByApiBase = new Map<string, Promise<HubVersion | null>>();
+
+/**
+ * The hub's version, fetched once per page and API base. Resolves `null` for
+ * a hub from before versioning (it has no `/version` route); a failed
+ * request is not cached, so a later call tries again.
+ */
+export function readHubVersion(rest: RestClient): Promise<HubVersion | null> {
+  const cached = versionsByApiBase.get(rest.apiBase);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const pending = fetchHubVersion(rest);
+  versionsByApiBase.set(rest.apiBase, pending);
+  return pending;
+}
+
+/** One `GET /version`; `null` when the hub has no such route. */
+async function fetchHubVersion(rest: RestClient): Promise<HubVersion | null> {
+  try {
+    return await rest.call('getHubVersion');
+  } catch (failure) {
+    if (failure instanceof HubError && failure.code === UNSUPPORTED_BY_HUB) {
+      return null;
+    }
+    versionsByApiBase.delete(rest.apiBase);
+    throw failure;
+  }
+}