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

package/src/core/hub.ts

@@ -0,0 +1,131 @@
+/**
+ * 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);
+}

package/src/core/menu-control.ts

@@ -0,0 +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;
+  },
+};

package/src/core/offline/events.ts

@@ -0,0 +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;
+}

package/src/core/offline/favorites.ts

@@ -0,0 +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));
+}

package/src/core/offline/local-store.ts

@@ -0,0 +1,261 @@
+/**
+ * The offline cache: what the client serves when the hub can't be reached,
+ * and where queued writes and buffered events wait. Keys are the v1 client's
+ * (`hub:user`, `hub:<slug>:save:<slot>`, `hub:<slug>:queue`, ...), so a page
+ * upgraded from a vendored copy keeps that copy's cache and queues.
+ */
+import type { Board, Json, SortDir, Stats } from '@diffenderfer-games/hub-contract';
+import { isJson, isNullableString, isNumberRecord, isRecord, optionalNumber, optionalString, parseJsonText } from '../storage/json-guards';
+import { createPageStore, type KeyValueStore } from '../storage/key-value';
+import type { Profile, Save, SaveMeta, SnapshotResponse, User } from '../types';
+import { appendEvent, readEvents, type BufferedEvent } from './events';
+import { betterScore, enqueueOp, readQueue, type QueueOp, type QueueOpInput, type QueuedScoreOptions } from './queue';
+
+/** The key of the locally known user, shared by every game (like the real session). */
+export const USER_KEY = 'hub:user';
+
+/** A board this player has a local best on. */
+export interface LocalBoard {
+  /** The board. */
+  readonly board: Board;
+  /** This player's best score. */
+  readonly best: number;
+}
+
+/** How a stat update combines with the stored value. */
+export type StatUpdateMode = 'set' | 'incr' | 'max';
+
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a cached user read back from localStorage
+function readUser(stored: unknown): User | null {
+  if (!isRecord(stored)) {
+    return null;
+  }
+  const id = optionalNumber(stored.id);
+  const username = optionalString(stored.username);
+  if (id === undefined || username === undefined) {
+    return null;
+  }
+  return typeof stored.guest === 'boolean' ? { id, username, guest: stored.guest } : { id, username };
+}
+
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a cached save read back from localStorage
+function readSave(stored: unknown): Save | null {
+  if (!isRecord(stored)) {
+    return null;
+  }
+  const slot = optionalString(stored.slot);
+  const updatedAt = optionalNumber(stored.updatedAt);
+  if (slot === undefined || updatedAt === undefined || !isNullableString(stored.label) || !isJson(stored.data)) {
+    return null;
+  }
+  return { slot, label: stored.label, data: stored.data, updatedAt };
+}
+
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a cached profile read back from localStorage
+function readProfile(stored: unknown): Profile | null {
+  if (!isRecord(stored)) {
+    return null;
+  }
+  const game = optionalString(stored.game);
+  const updatedAt = optionalNumber(stored.updatedAt);
+  if (game === undefined || updatedAt === undefined || !isNullableString(stored.displayName) || !isJson(stored.data)) {
+    return null;
+  }
+  return { game, displayName: stored.displayName, data: stored.data, updatedAt };
+}
+
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a cached board read back from localStorage
+function readLocalBoard(stored: unknown): LocalBoard | null {
+  if (!isRecord(stored) || !isRecord(stored.board)) {
+    return null;
+  }
+  const key = optionalString(stored.board.key);
+  const title = optionalString(stored.board.title);
+  const sortDir = stored.board.sortDir === 'asc' || stored.board.sortDir === 'desc' ? stored.board.sortDir : undefined;
+  const best = optionalNumber(stored.best);
+  if (key === undefined || title === undefined || sortDir === undefined || best === undefined) {
+    return null;
+  }
+  return { board: { key, title, sortDir }, best };
+}
+
+/** One game's offline cache, queue and event buffer. */
+export class LocalStore {
+  private readonly prefix: string;
+  private readonly store: KeyValueStore;
+  private sequence = 0;
+
+  /** The cache for game `slug` in `store` (default: `localStorage`, or memory without it). */
+  constructor(slug: string, store: KeyValueStore = createPageStore()) {
+    this.prefix = `hub:${slug}:`;
+    this.store = store;
+  }
+
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON read back from storage, checked by each caller's guard
+  private readStored(key: string): unknown {
+    const text = this.store.read(key);
+    return text === null ? undefined : parseJsonText(text);
+  }
+
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: any JSON-serializable value the cache stores
+  private writeStored(key: string, stored: unknown): void {
+    this.store.write(key, JSON.stringify(stored));
+  }
+
+  /** The locally known user. */
+  getUser(): User | null {
+    return readUser(this.readStored(USER_KEY));
+  }
+
+  /** Remember the user (offline sign-in, or a snapshot). */
+  setUser(user: User): void {
+    this.writeStored(USER_KEY, user);
+  }
+
+  /** Forget the user (offline sign-out). */
+  clearUser(): void {
+    this.store.remove(USER_KEY);
+  }
+
+  /** This game's cached profile. */
+  getProfile(): Profile | null {
+    return readProfile(this.readStored(`${this.prefix}profile`));
+  }
+
+  /** Store this game's profile and return it. */
+  setProfile(game: string, displayName: string | null, profileData: Json): Profile {
+    const profile: Profile = { game, displayName, data: profileData, updatedAt: Date.now() };
+    this.writeStored(`${this.prefix}profile`, profile);
+    return profile;
+  }
+
+  /** Every cached save's metadata, newest first. */
+  listSaves(): SaveMeta[] {
+    return this.store.keys()
+      .filter((key) => key.startsWith(`${this.prefix}save:`))
+      .flatMap((key) => {
+        const save = readSave(this.readStored(key));
+        return save === null ? [] : [{ slot: save.slot, label: save.label, updatedAt: save.updatedAt }];
+      })
+      .sort((first, second) => second.updatedAt - first.updatedAt);
+  }
+
+  /** One cached save, or `null`. */
+  getSave(slot: string): Save | null {
+    return readSave(this.readStored(`${this.prefix}save:${slot}`));
+  }
+
+  /** Store a save and return its `updatedAt`. */
+  putSave(slot: string, saveData: Json, label: string | null): number {
+    const updatedAt = Date.now();
+    this.writeStored(`${this.prefix}save:${slot}`, { slot, label, data: saveData, updatedAt });
+    return updatedAt;
+  }
+
+  /** Forget a save. */
+  deleteSave(slot: string): void {
+    this.store.remove(`${this.prefix}save:${slot}`);
+  }
+
+  /** This game's cached stats. */
+  getStats(): Stats {
+    const stored = this.readStored(`${this.prefix}stats`);
+    return isNumberRecord(stored) ? { ...stored } : {};
+  }
+
+  /** Apply one stat update and return the stat's new value. */
+  updateStat(key: string, amount: number, mode: StatUpdateMode): number {
+    const stats = this.getStats();
+    const current = stats[key] ?? 0;
+    const updated = mode === 'incr' ? current + amount : mode === 'max' ? Math.max(current, amount) : amount;
+    this.writeStored(`${this.prefix}stats`, { ...stats, [key]: updated });
+    return updated;
+  }
+
+  /** The boards this player has a local best on (offline boards only know the player's own best). */
+  listBoards(): Board[] {
+    return this.store.keys()
+      .filter((key) => key.startsWith(`${this.prefix}lb:`))
+      .flatMap((key) => {
+        const local = readLocalBoard(this.readStored(key));
+        return local === null ? [] : [local.board];
+      });
+  }
+
+  /** One board's local best, or `null`. */
+  getBoard(key: string): LocalBoard | null {
+    return readLocalBoard(this.readStored(`${this.prefix}lb:${key}`));
+  }
+
+  /** Record a score locally, keeping the best one; returns the board and best. */
+  submitScore(key: string, score: number, options: QueuedScoreOptions): LocalBoard {
+    const existing = this.getBoard(key);
+    const sortDir: SortDir = existing?.board.sortDir ?? (options.sort === 'asc' ? 'asc' : 'desc');
+    const board: Board = existing?.board ?? { key, title: options.title !== undefined && options.title !== '' ? options.title : key, sortDir };
+    const best = existing === null ? score : betterScore(existing.best, score, sortDir);
+    this.writeStored(`${this.prefix}lb:${key}`, { board, best });
+    return { board, best };
+  }
+
+  /** The queued writes, oldest first. */
+  getQueue(): QueueOp[] {
+    return readQueue(this.readStored(`${this.prefix}queue`));
+  }
+
+  /** Replace the queue. */
+  setQueue(queue: readonly QueueOp[]): void {
+    this.writeStored(`${this.prefix}queue`, queue);
+  }
+
+  /** How many writes are queued. */
+  queueLength(): number {
+    return this.getQueue().length;
+  }
+
+  /** Queue a write, collapsing it with a compatible queued one. */
+  enqueue(input: QueueOpInput): void {
+    this.sequence += 1;
+    const now = Date.now();
+    this.setQueue(enqueueOp(this.getQueue(), { ...input, id: `${String(now)}-${String(this.sequence)}`, ts: now }));
+  }
+
+  /** The buffered analytics events, oldest first. */
+  getEvents(): BufferedEvent[] {
+    return readEvents(this.readStored(`${this.prefix}events`));
+  }
+
+  /** Replace the event buffer. */
+  setEvents(events: readonly BufferedEvent[]): void {
+    this.writeStored(`${this.prefix}events`, events);
+  }
+
+  /** Buffer one event (capped; heartbeats are dropped first). */
+  bufferEvent(type: string): void {
+    this.setEvents(appendEvent(this.getEvents(), { type, ts: Date.now() }));
+  }
+
+  /** Fan a `/me/snapshot` reply out across every game's cache keys. */
+  hydrate(snapshot: SnapshotResponse): void {
+    if (snapshot.user !== null) {
+      this.writeStored(USER_KEY, snapshot.user);
+    }
+    for (const [slug, game] of Object.entries(snapshot.games)) {
+      const gamePrefix = `hub:${slug}:`;
+      if (game.profile !== null) {
+        this.writeStored(`${gamePrefix}profile`, game.profile);
+      }
+      for (const save of game.saves) {
+        this.writeStored(`${gamePrefix}save:${save.slot}`, save);
+      }
+      this.writeStored(`${gamePrefix}stats`, game.stats);
+      this.writeStored(`${gamePrefix}inventory`, game.inventory);
+    }
+    for (const gameRecords of snapshot.records) {
+      for (const record of gameRecords.records) {
+        this.writeStored(`hub:${gameRecords.slug}:lb:${record.key}`, { board: { key: record.key, title: record.title, sortDir: record.sortDir }, best: record.score });
+      }
+    }
+    this.writeStored('hub:records', snapshot.records);
+    this.writeStored('hub:leaderboards', snapshot.leaderboards);
+  }
+}