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

package/src/core/hub.ts

@@ -1,131 +1,133 @@
-/**
- * The `Hub` client: every REST method (in `hub-progress.ts` and
- * `hub-economy.ts`), the hub's version, and the page-wide namespaces as lazy
- * getters (`hub.input`, `hub.daily`, `hub.social`, `hub.mp`, `hub.rooms`,
- * `hub.race`, ...), so v1 code such as `hub.input.define(...)` works unchanged.
- */
-import type { HubVersion } from '@diffenderfer-games/hub-contract';
-import { getDaily, type DailyHost, type DailySystem } from '../daily';
-import { getInput, getUiStack, type InputSystem } from '../input';
-import { mp } from '../mp';
-import { race } from '../race';
-import { rooms } from '../rooms';
-import { linkRealtimeToHub, notify, presence, social } from '../social';
-import { OfflineError, toHubError } from './errors';
-import { HubEconomy } from './hub-economy';
-import { hubMenu, type HubMenuControl } from './menu-control';
-import { emitWindowEvent } from './page';
-import { fetchGameServerTicket } from './ticket';
-import { clientSupport, readHubVersion, type ClientSupport } from './version/hub-version';
-import { HUB_CLIENT_VERSION } from './version/client-version.gen';
-import type { HubOptions } from './types';
-
-/** The hub client. Use the ready-made {@link hub}, or `createHub()` for another slug or API base. */
-export class Hub extends HubEconomy {
-  /** This client's package version (sent as `x-hub-client`). */
-  readonly clientVersion: string = HUB_CLIENT_VERSION;
-
-  /**
-   * The hub's version and the client versions it supports (`GET /_api/version`),
-   * read once per page. `null` for a hub from before versioning.
-   */
-  hubVersion(): Promise<HubVersion | null> {
-    return readHubVersion(this.rest);
-  }
-
-  /** How the hub regards this client: `supported`, `deprecated`, `unsupported`, or `unknown` (an older hub). */
-  async clientSupport(): Promise<ClientSupport> {
-    return clientSupport(await this.hubVersion());
-  }
-
-  /**
-   * The input system (keyboard, touch and gamepad): `hub.input.define({ ... })`,
-   * `hub.input.value('jump')`. Page-wide; remaps are saved locally and to the
-   * reserved `__controls` save slot.
-   */
-  get input(): InputSystem {
-    return getInput({
-      slug: this.slug,
-      saveToCloud: (overrides) => {
-        void this.putSave('__controls', overrides).catch(() => undefined);
-      },
-    });
-  }
-
-  /** Hub UI covering the game (menu, dialogs, chat): open/close events and `autoPause`. Page-wide. */
-  get overlay(): ReturnType<typeof getUiStack> {
-    return getUiStack();
-  }
-
-  /** Show or hide the injected hub menu button (page-wide). */
-  get menu(): HubMenuControl {
-    return hubMenu;
-  }
-
-  /**
-   * Daily challenges: call `hub.daily.define({ play })` once at load and
-   * `hub.daily.complete({ ... })` on finish. Page-wide, shared with the
-   * injected menu, which can start a clicked day on the same instance.
-   */
-  get daily(): DailySystem {
-    return getDaily(this.dailyHost());
-  }
-
-  /** Tell friends what the player is doing in this game. */
-  get presence(): typeof presence {
-    return presence;
-  }
-
-  /** Friends, players and the hub's social dialogs. */
-  get social(): typeof social {
-    return social;
-  }
-
-  /** Invites, launches, the leave guard and own-server tickets. */
-  get mp(): typeof mp {
-    return mp;
-  }
-
-  /** Hub relay rooms, for games without a server. */
-  get rooms(): typeof rooms {
-    return rooms;
-  }
-
-  /** Toast behaviour during intense play. */
-  get notify(): typeof notify {
-    return notify;
-  }
-
-  /** Races: a single-player game becomes multiplayer by racing. */
-  get race(): typeof race {
-    return race;
-  }
-
-  /** What the daily system needs from this client: its REST calls and window events. */
-  private dailyHost(): DailyHost {
-    return {
-      slug: this.slug,
-      status: () => this.rest.call('getGameDailyChallenges', this.gameFields()),
-      all: () => this.rest.call('listDailyChallengesForAllGames'),
-      start: (day) => this.rest.call('startDailyChallenge', { ...this.gameFields(), day }),
-      complete: (day, token, meta) => this.rest.call('completeDailyChallenge', { ...this.gameFields(), day, token, meta }),
-      emit: (eventName, detail) => {
-        emitWindowEvent(eventName, detail);
-      },
-    };
-  }
-}
-
-linkRealtimeToHub({
-  toHubError,
-  createOfflineError: (message) => new OfflineError(message),
-  getGameServerTicket: fetchGameServerTicket,
-});
-
-/** A ready-to-use client, with the slug and API base detected from the page. */
-export const hub: Hub = new Hub();
-
-/** Create a client for another slug or API base, or with other offline behaviour. */
-export function createHub(options: HubOptions = {}): Hub {
-  return new Hub(options);
-}
+/**
+ * The `Hub` client: every REST method (in `hub-progress.ts` and
+ * `hub-economy.ts`), the hub's version, and the page-wide namespaces as lazy
+ * getters (`hub.input`, `hub.daily`, `hub.social`, `hub.mp`, `hub.rooms`,
+ * `hub.race`, ...), so v1 code such as `hub.input.define(...)` works unchanged.
+ */
+import type { HubVersion } from '@diffenderfer-games/hub-contract';
+import { getDaily, type DailyCompleteResponse, type DailyHost, type DailySystem } from '../daily';
+import { getInput, getUiStack, type InputSystem } from '../input';
+import { mp } from '../mp';
+import { race } from '../race';
+import { rooms } from '../rooms';
+import { linkRealtimeToHub, notify, presence, social } from '../social';
+import { OfflineError, toHubError } from './errors';
+import { HubEconomy } from './hub-economy';
+import { DAILY_KIND } from './offline/hub-kinds';
+import { readDailyCompletion } from './offline/hub-kinds/daily-kind';
+import { hubMenu, type HubMenuControl } from './menu-control';
+import { emitWindowEvent } from './page';
+import { fetchGameServerTicket } from './ticket';
+import { clientSupport, readHubVersion, type ClientSupport } from './version/hub-version';
+import { HUB_CLIENT_VERSION } from './version/client-version.gen';
+import type { HubOptions } from './types';
+
+/** The hub client. Use the ready-made {@link hub}, or `createHub()` for another slug or API base. */
+export class Hub extends HubEconomy {
+  /** This client's package version (sent as `x-hub-client`). */
+  readonly clientVersion: string = HUB_CLIENT_VERSION;
+
+  /**
+   * The hub's version and the client versions it supports (`GET /_api/version`),
+   * read once per page. `null` for a hub from before versioning.
+   */
+  hubVersion(): Promise<HubVersion | null> {
+    return readHubVersion(this.rest);
+  }
+
+  /** How the hub regards this client: `supported`, `deprecated`, `unsupported`, or `unknown` (an older hub). */
+  async clientSupport(): Promise<ClientSupport> {
+    return clientSupport(await this.hubVersion());
+  }
+
+  /**
+   * The input system (keyboard, touch and gamepad): `hub.input.define({ ... })`,
+   * `hub.input.value('jump')`. Page-wide; remaps are saved locally and to the
+   * reserved `__controls` save slot.
+   */
+  get input(): InputSystem {
+    return getInput({
+      slug: this.slug,
+      saveToCloud: (overrides) => {
+        void this.putSave('__controls', overrides).catch(() => undefined);
+      },
+    });
+  }
+
+  /** Hub UI covering the game (menu, dialogs, chat): open/close events and `autoPause`. Page-wide. */
+  get overlay(): ReturnType<typeof getUiStack> {
+    return getUiStack();
+  }
+
+  /** Show or hide the injected hub menu button (page-wide). */
+  get menu(): HubMenuControl {
+    return hubMenu;
+  }
+
+  /**
+   * Daily challenges: call `hub.daily.define({ play })` once at load and
+   * `hub.daily.complete({ ... })` on finish. Page-wide, shared with the
+   * injected menu, which can start a clicked day on the same instance.
+   */
+  get daily(): DailySystem {
+    return getDaily(this.dailyHost());
+  }
+
+  /** Tell friends what the player is doing in this game. */
+  get presence(): typeof presence {
+    return presence;
+  }
+
+  /** Friends, players and the hub's social dialogs. */
+  get social(): typeof social {
+    return social;
+  }
+
+  /** Invites, launches, the leave guard and own-server tickets. */
+  get mp(): typeof mp {
+    return mp;
+  }
+
+  /** Hub relay rooms, for games without a server. */
+  get rooms(): typeof rooms {
+    return rooms;
+  }
+
+  /** Toast behaviour during intense play. */
+  get notify(): typeof notify {
+    return notify;
+  }
+
+  /** Races: a single-player game becomes multiplayer by racing. */
+  get race(): typeof race {
+    return race;
+  }
+
+  /** What the daily system needs from this client: its REST calls and window events. */
+  private dailyHost(): DailyHost {
+    return {
+      slug: this.slug,
+      status: () => this.rest.call('getGameDailyChallenges', this.gameFields()),
+      all: () => this.rest.call('listDailyChallengesForAllGames'),
+      start: (day) => this.rest.call('startDailyChallenge', { ...this.gameFields(), day }),
+      complete: (day, token, meta) => this.mutateOffline<DailyCompleteResponse | null>(DAILY_KIND, { day, token, meta }, () => null, (result) => readDailyCompletion(result)),
+      emit: (eventName, detail) => {
+        emitWindowEvent(eventName, detail);
+      },
+    };
+  }
+}
+
+linkRealtimeToHub({
+  toHubError,
+  createOfflineError: (message) => new OfflineError(message),
+  getGameServerTicket: fetchGameServerTicket,
+});
+
+/** A ready-to-use client, with the slug and API base detected from the page. */
+export const hub: Hub = new Hub();
+
+/** Create a client for another slug or API base, or with other offline behaviour. */
+export function createHub(options: HubOptions = {}): Hub {
+  return new Hub(options);
+}

package/src/core/menu-control.ts

@@ -1,61 +1,61 @@
-/**
- * `hub.menu`: show or hide the injected hub menu button. The menu
- * (`/_hub/menu.js`) may load before or after the game, and the game may
- * bundle its own client copy, so the shared state is a window global and a
- * window event rather than an object:
- *
- * - `window.__HUB_MENU_VISIBLE__` (boolean; absent means visible);
- * - `hub:menu-visibility` (`CustomEvent`, detail `{ visible }`).
- *
- * The menu reads the global on boot and listens for the event.
- */
-import { emitWindowEvent, isBrowserPage } from './page';
-
-declare global {
-  interface Window {
-    /** The last requested menu-button visibility (absent: visible). */
-    __HUB_MENU_VISIBLE__?: boolean;
-  }
-}
-
-/** Control over the injected hub menu button. */
-export interface HubMenuControl {
-  /**
-   * Show (`true`) or hide (`false`) the menu button. Hidden means faded out,
-   * not focusable and `aria-hidden`; an open drawer stays open until closed,
-   * and the gamepad Select button still opens it. A small corner hotspot
-   * peeks it back for a few seconds on hover or tap, so players can always
-   * reach it.
-   */
-  setVisible(isVisible: boolean): void;
-  /** Show the menu button. */
-  show(): void;
-  /** Hide the menu button. */
-  hide(): void;
-  /** The last requested visibility (`true` unless a game hid it). */
-  readonly visible: boolean;
-}
-
-/** The page's menu control (one per page; every client copy shares the window state). */
-export const hubMenu: HubMenuControl = {
-  setVisible(isVisible: boolean): void {
-    if (!isBrowserPage()) {
-      return;
-    }
-    const wasVisible = window.__HUB_MENU_VISIBLE__;
-    if (wasVisible === isVisible || (wasVisible === undefined && isVisible)) {
-      return;
-    }
-    window.__HUB_MENU_VISIBLE__ = isVisible;
-    emitWindowEvent('hub:menu-visibility', { visible: isVisible });
-  },
-  show(): void {
-    hubMenu.setVisible(true);
-  },
-  hide(): void {
-    hubMenu.setVisible(false);
-  },
-  get visible(): boolean {
-    return !isBrowserPage() || window.__HUB_MENU_VISIBLE__ !== false;
-  },
-};
+/**
+ * `hub.menu`: show or hide the injected hub menu button. The menu
+ * (`/_hub/menu.js`) may load before or after the game, and the game may
+ * bundle its own client copy, so the shared state is a window global and a
+ * window event rather than an object:
+ *
+ * - `window.__HUB_MENU_VISIBLE__` (boolean; absent means visible);
+ * - `hub:menu-visibility` (`CustomEvent`, detail `{ visible }`).
+ *
+ * The menu reads the global on boot and listens for the event.
+ */
+import { emitWindowEvent, isBrowserPage } from './page';
+
+declare global {
+  interface Window {
+    /** The last requested menu-button visibility (absent: visible). */
+    __HUB_MENU_VISIBLE__?: boolean;
+  }
+}
+
+/** Control over the injected hub menu button. */
+export interface HubMenuControl {
+  /**
+   * Show (`true`) or hide (`false`) the menu button. Hidden means faded out,
+   * not focusable and `aria-hidden`; an open drawer stays open until closed,
+   * and the gamepad Select button still opens it. A small corner hotspot
+   * peeks it back for a few seconds on hover or tap, so players can always
+   * reach it.
+   */
+  setVisible(isVisible: boolean): void;
+  /** Show the menu button. */
+  show(): void;
+  /** Hide the menu button. */
+  hide(): void;
+  /** The last requested visibility (`true` unless a game hid it). */
+  readonly visible: boolean;
+}
+
+/** The page's menu control (one per page; every client copy shares the window state). */
+export const hubMenu: HubMenuControl = {
+  setVisible(isVisible: boolean): void {
+    if (!isBrowserPage()) {
+      return;
+    }
+    const wasVisible = window.__HUB_MENU_VISIBLE__;
+    if (wasVisible === isVisible || (wasVisible === undefined && isVisible)) {
+      return;
+    }
+    window.__HUB_MENU_VISIBLE__ = isVisible;
+    emitWindowEvent('hub:menu-visibility', { visible: isVisible });
+  },
+  show(): void {
+    hubMenu.setVisible(true);
+  },
+  hide(): void {
+    hubMenu.setVisible(false);
+  },
+  get visible(): boolean {
+    return !isBrowserPage() || window.__HUB_MENU_VISIBLE__ !== false;
+  },
+};

package/src/core/offline/events.ts

@@ -1,50 +1,50 @@
-/**
- * Analytics events recorded while offline (`play`, `heartbeat`, custom
- * events), kept under `hub:<slug>:events` and sent when the hub is back.
- * The buffer is capped; heartbeats are dropped first, then the oldest.
- */
-import { isRecord, optionalNumber, optionalString } from '../storage/json-guards';
-
-/** The most events kept while offline. */
-export const EVENT_BUFFER_CAP = 100;
-
-/** One buffered event. */
-export interface BufferedEvent {
-  /** The event type, as `recordGameEvent` sends it. */
-  readonly type: string;
-  /** When it happened (epoch ms). */
-  readonly ts: number;
-}
-
-/** The well-formed events of a stored buffer. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: a buffer read back from localStorage (possibly written by a v1 client)
-export function readEvents(stored: unknown): BufferedEvent[] {
-  if (!Array.isArray(stored)) {
-    return [];
-  }
-  return stored.flatMap((entry): BufferedEvent[] => {
-    if (!isRecord(entry)) {
-      return [];
-    }
-    const type = optionalString(entry.type);
-    const ts = optionalNumber(entry.ts);
-    return type === undefined || ts === undefined ? [] : [{ type, ts }];
-  });
-}
-
-/** The buffer with one more event, trimmed to {@link EVENT_BUFFER_CAP}: oldest heartbeats go first, then the oldest events. */
-export function appendEvent(events: readonly BufferedEvent[], incoming: BufferedEvent): BufferedEvent[] {
-  let buffered = [...events, incoming];
-  let excess = buffered.length - EVENT_BUFFER_CAP;
-  if (excess <= 0) {
-    return buffered;
-  }
-  buffered = buffered.filter((event) => {
-    if (excess > 0 && event.type === 'heartbeat') {
-      excess -= 1;
-      return false;
-    }
-    return true;
-  });
-  return buffered.length > EVENT_BUFFER_CAP ? buffered.slice(buffered.length - EVENT_BUFFER_CAP) : buffered;
-}
+/**
+ * Analytics events recorded while offline (`play`, `heartbeat`, custom
+ * events), kept under `hub:<slug>:events` and sent when the hub is back.
+ * The buffer is capped; heartbeats are dropped first, then the oldest.
+ */
+import { isRecord, optionalNumber, optionalString } from '../storage/json-guards';
+
+/** The most events kept while offline. */
+export const EVENT_BUFFER_CAP = 100;
+
+/** One buffered event. */
+export interface BufferedEvent {
+  /** The event type, as `recordGameEvent` sends it. */
+  readonly type: string;
+  /** When it happened (epoch ms). */
+  readonly ts: number;
+}
+
+/** The well-formed events of a stored buffer. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a buffer read back from localStorage (possibly written by a v1 client)
+export function readEvents(stored: unknown): BufferedEvent[] {
+  if (!Array.isArray(stored)) {
+    return [];
+  }
+  return stored.flatMap((entry): BufferedEvent[] => {
+    if (!isRecord(entry)) {
+      return [];
+    }
+    const type = optionalString(entry.type);
+    const ts = optionalNumber(entry.ts);
+    return type === undefined || ts === undefined ? [] : [{ type, ts }];
+  });
+}
+
+/** The buffer with one more event, trimmed to {@link EVENT_BUFFER_CAP}: oldest heartbeats go first, then the oldest events. */
+export function appendEvent(events: readonly BufferedEvent[], incoming: BufferedEvent): BufferedEvent[] {
+  let buffered = [...events, incoming];
+  let excess = buffered.length - EVENT_BUFFER_CAP;
+  if (excess <= 0) {
+    return buffered;
+  }
+  buffered = buffered.filter((event) => {
+    if (excess > 0 && event.type === 'heartbeat') {
+      excess -= 1;
+      return false;
+    }
+    return true;
+  });
+  return buffered.length > EVENT_BUFFER_CAP ? buffered.slice(buffered.length - EVENT_BUFFER_CAP) : buffered;
+}

package/src/core/offline/favorites.ts

@@ -1,21 +1,21 @@
-/**
- * Starred games are site-wide, not per game, so they live under one global
- * key (`hub:favorites`, the v1 client's) rather than in a game's cache. The
- * list mirrors the hub's so the menu still shows it offline.
- */
-import { parseJsonText, stringsIn } from '../storage/json-guards';
-import { createPageStore } from '../storage/key-value';
-
-/** The key of the mirrored favorites list. */
-export const FAVORITES_KEY = 'hub:favorites';
-
-/** The mirrored favorite slugs (empty when none or unreadable). */
-export function readLocalFavorites(): string[] {
-  const text = createPageStore().read(FAVORITES_KEY);
-  return text === null ? [] : stringsIn(parseJsonText(text));
-}
-
-/** Mirror the hub's favorites list. */
-export function writeLocalFavorites(games: readonly string[]): void {
-  createPageStore().write(FAVORITES_KEY, JSON.stringify(games));
-}
+/**
+ * Starred games are site-wide, not per game, so they live under one global
+ * key (`hub:favorites`, the v1 client's) rather than in a game's cache. The
+ * list mirrors the hub's so the menu still shows it offline.
+ */
+import { parseJsonText, stringsIn } from '../storage/json-guards';
+import { createPageStore } from '../storage/key-value';
+
+/** The key of the mirrored favorites list. */
+export const FAVORITES_KEY = 'hub:favorites';
+
+/** The mirrored favorite slugs (empty when none or unreadable). */
+export function readLocalFavorites(): string[] {
+  const text = createPageStore().read(FAVORITES_KEY);
+  return text === null ? [] : stringsIn(parseJsonText(text));
+}
+
+/** Mirror the hub's favorites list. */
+export function writeLocalFavorites(games: readonly string[]): void {
+  createPageStore().write(FAVORITES_KEY, JSON.stringify(games));
+}

package/src/core/offline/hub-kinds/daily-kind.ts

@@ -0,0 +1,68 @@
+/**
+ * The hub's daily kind, a composite op: complete a day with the token the
+ * game started it with; when that token has expired by the time the op
+ * replays (401), start the day again for a fresh token and complete with
+ * that. The completion is replayable, so a retry after a lost reply never
+ * records it twice. A completion sent at once (online) is reported by the
+ * daily system itself; one that replays later is reported here.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { HubError } from '../../errors';
+import type { EndpointReply } from '../../rest/endpoint-types';
+import { isJsonObject, isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { RegisteredKind } from '../outbox-kinds';
+import type { GameFieldsSource } from './game-fields';
+
+/** One daily completion. */
+export type DailyPayload = { readonly day: string; readonly token: string; readonly meta: { readonly [key: string]: Json } };
+
+/** The kind name. */
+export const DAILY_KIND = 'hub.daily';
+
+/** What a completion answers. */
+export type DailyCompletion = EndpointReply<'completeDailyChallenge'>;
+
+function readDaily(stored: Json): DailyPayload | undefined {
+  if (!isRecord(stored) || !isJsonObject(stored.meta)) {
+    return undefined;
+  }
+  const day = optionalString(stored.day);
+  const token = optionalString(stored.token);
+  return day === undefined || token === undefined ? undefined : { day, token, meta: stored.meta };
+}
+
+/** A completion reply read back, or `undefined` when it doesn't read as one. */
+export function readDailyCompletion(result: Json | undefined): DailyCompletion | undefined {
+  if (!isRecord(result) || result.ok !== true) {
+    return undefined;
+  }
+  const day = optionalString(result.day);
+  const count = optionalNumber(result.count);
+  const rank = result.rank === null ? null : optionalNumber(result.rank);
+  return day === undefined || count === undefined || rank === undefined ? undefined : { ok: true, day, count, rank };
+}
+
+/** The daily kind, by name; `onCompleted` hears each completion that lands from the queue. */
+export function dailyKinds(game: GameFieldsSource, onCompleted: (payload: DailyPayload, completion: DailyCompletion) => void): Record<string, RegisteredKind> {
+  return {
+    [DAILY_KIND]: checkedKind(readDaily, {
+      run: async ({ day, token, meta }, context) => {
+        let completion: DailyCompletion;
+        try {
+          completion = await context.call('completeDailyChallenge', { ...game(), day, token, meta });
+        } catch (failure) {
+          if (!(failure instanceof HubError) || failure.status !== 401) {
+            throw failure;
+          }
+          const started = await context.call('startDailyChallenge', { ...game(), day });
+          completion = await context.call('completeDailyChallenge', { ...game(), day, token: started.token, meta });
+        }
+        if (context.isReplay) {
+          onCompleted({ day, token, meta }, completion);
+        }
+        return completion;
+      },
+    }),
+  };
+}