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

package/src/core/ticket.ts

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

package/src/core/types.ts

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

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

@@ -0,0 +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.1';

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

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

package/src/core/version/semver.ts

@@ -0,0 +1,97 @@
+/**
+ * Just enough semver for version ranges the hub sends (`>=2.0.0-0 <3.0.0`,
+ * `<2.2.0`): comparators separated by spaces must all hold, `||` separates
+ * alternatives. Versions compare in plain semver order, prereleases included
+ * (`2.0.0-next.1 < 2.0.0`); unlike npm, a prerelease is not excluded from a
+ * range of another release line, which is why the hub writes `-0` floors.
+ */
+
+/** A parsed `major.minor.patch[-prerelease]` version. */
+export interface ParsedVersion {
+  /** `[major, minor, patch]`. */
+  readonly release: readonly [number, number, number];
+  /** The dot-separated prerelease identifiers (empty for a release). */
+  readonly prerelease: readonly string[];
+}
+
+const VERSION_PATTERN = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/** Parse a version (`2`, `2.1`, `2.1.0`, `2.1.0-next.3`); `undefined` when it is not one. */
+export function parseVersion(text: string): ParsedVersion | undefined {
+  const match = VERSION_PATTERN.exec(text.trim());
+  if (match === null) {
+    return undefined;
+  }
+  const [, major = '0', minor = '0', patch = '0', prerelease] = match;
+  return { release: [Number(major), Number(minor), Number(patch)], prerelease: prerelease === undefined ? [] : prerelease.split('.') };
+}
+
+/** Compare two prerelease identifiers: numbers by value and before words, words as text. */
+function compareIdentifiers(first: string, second: string): number {
+  const isFirstNumeric = /^\d+$/.test(first);
+  const isSecondNumeric = /^\d+$/.test(second);
+  if (isFirstNumeric && isSecondNumeric) {
+    return Number(first) - Number(second);
+  }
+  if (isFirstNumeric !== isSecondNumeric) {
+    return isFirstNumeric ? -1 : 1;
+  }
+  return first < second ? -1 : first > second ? 1 : 0;
+}
+
+/** Negative when `first` is older, positive when newer, 0 when equal. */
+export function compareVersions(first: ParsedVersion, second: ParsedVersion): number {
+  for (let i = 0; i < 3; i += 1) {
+    const difference = (first.release[i] ?? 0) - (second.release[i] ?? 0);
+    if (difference !== 0) {
+      return difference;
+    }
+  }
+  if (first.prerelease.length === 0 || second.prerelease.length === 0) {
+    return second.prerelease.length - first.prerelease.length;
+  }
+  const length = Math.max(first.prerelease.length, second.prerelease.length);
+  for (let i = 0; i < length; i += 1) {
+    const firstIdentifier = first.prerelease[i];
+    const secondIdentifier = second.prerelease[i];
+    if (firstIdentifier === undefined || secondIdentifier === undefined) {
+      return firstIdentifier === undefined ? -1 : 1;
+    }
+    const difference = compareIdentifiers(firstIdentifier, secondIdentifier);
+    if (difference !== 0) {
+      return difference;
+    }
+  }
+  return 0;
+}
+
+const COMPARATOR_PATTERN = /^(>=|<=|>|<|=)?\s*(.+)$/;
+
+/** Whether `version` meets one comparator (`>=2.0.0`); a malformed comparator never holds. */
+function meetsComparator(version: ParsedVersion, comparator: string): boolean {
+  const match = COMPARATOR_PATTERN.exec(comparator);
+  const bound = match?.[2] === undefined ? undefined : parseVersion(match[2]);
+  if (match === null || bound === undefined) {
+    return false;
+  }
+  const order = compareVersions(version, bound);
+  switch (match[1]) {
+    case '>=': return order >= 0;
+    case '<=': return order <= 0;
+    case '>': return order > 0;
+    case '<': return order < 0;
+    default: return order === 0;
+  }
+}
+
+/** Whether `versionText` is in `range`; a malformed version or empty range never is. */
+export function satisfiesRange(versionText: string, range: string): boolean {
+  const version = parseVersion(versionText);
+  if (version === undefined) {
+    return false;
+  }
+  return range.split('||').some((alternative) => {
+    const comparators = alternative.trim().split(/\s+/).filter((comparator) => comparator !== '');
+    return comparators.length > 0 && comparators.every((comparator) => meetsComparator(version, comparator));
+  });
+}

package/src/daily/daily-system.ts

@@ -0,0 +1,161 @@
+/**
+ * Daily challenges, client side. A daily-enabled game calls
+ * `hub.daily.define({ play })` once at load; `play` receives a
+ * {@link DailyChallenge} and starts exactly that challenge. When the player
+ * finishes, the game calls `hub.daily.complete({ score, … })`.
+ *
+ * The system is a page-wide singleton shared by the game's client and the
+ * injected menu, so the menu can start a day on the instance the game
+ * registered `play` on. Deep links (`/<slug>/?daily=YYYY-MM-DD`) auto-start.
+ */
+import { readField } from '../realtime/cross-bundle';
+import type { DailyAll, DailyChallenge, DailyCompleteResponse, DailyCompletionMeta, DailyDefinition, DailyHost, DailyStatus } from './types';
+
+const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+/** The window event the injected menu fires to start a day on the game's instance. */
+export const DAILY_START_EVENT = 'hub:daily-start';
+
+/** A day key, or `null` when `candidate` isn't one. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a URL parameter or a window global set by the host page
+function asDayKey(candidate: unknown): string | null {
+  return typeof candidate === 'string' && DAY_PATTERN.test(candidate) ? candidate : null;
+}
+
+/** The day the page was deep-linked to, if any. */
+function readDeepLinkDay(): string | null {
+  // Prefer the value the host's injected snippet captured at parse time: it
+  // survives games that rewrite their own URL on boot.
+  const captured = typeof window === 'undefined' ? null : asDayKey(readField(window, '__hubDailyDeep'));
+  if (captured !== null || typeof location === 'undefined') {
+    return captured;
+  }
+  return asDayKey(new URL(location.href).searchParams.get('daily'));
+}
+
+/** The message of a thrown value. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: anything a REST call can throw
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Daily challenges (`hub.daily`). */
+export class DailySystem {
+  /**
+   * The challenge in progress (set when a day starts, cleared on complete).
+   * A game's win handler checks it: `if (hub.daily.active) hub.daily.complete(…)`.
+   */
+  active: DailyChallenge | null = null;
+  private readonly host: DailyHost;
+  private play: DailyDefinition['play'] | null = null;
+  private pendingDay: string | null = null;
+  private isRelaying = false;
+
+  constructor(host: DailyHost) {
+    this.host = host;
+    if (typeof window !== 'undefined') {
+      // The injected menu (another module instance) asks us to start a day.
+      window.addEventListener(DAILY_START_EVENT, (event) => {
+        if (this.isRelaying) {
+          return;
+        }
+        const day = event instanceof CustomEvent ? readField(event.detail, 'day') : undefined;
+        if (typeof day === 'string') {
+          void this.startAndPlay(day);
+        }
+      });
+    }
+  }
+
+  /** Whether a game registered a daily-challenge handler on this page. */
+  get isDefined(): boolean {
+    return this.play !== null;
+  }
+
+  /**
+   * Register the game's challenge runner. Call once at load. If the page was
+   * deep-linked with `?daily=DATE` (or a start was requested before this),
+   * that day starts now.
+   */
+  define(definition: DailyDefinition): void {
+    this.play = definition.play;
+    const day = readDeepLinkDay() ?? this.pendingDay;
+    this.pendingDay = null;
+    if (day !== null) {
+      void this.startAndPlay(day);
+    }
+  }
+
+  /**
+   * Fetch the signed token for `day`, make it active and call the game's
+   * `play`. Before `define`, the day is kept and played then, so the menu's
+   * own instance never fetches a token; it is also relayed to any other
+   * daily system on the page (a client copy that couldn't share this one).
+   */
+  async startAndPlay(day: string): Promise<void> {
+    const play = this.play;
+    if (play === null) {
+      this.pendingDay = day;
+      this.relayStart(day);
+      return;
+    }
+    try {
+      const started = await this.host.start(day);
+      const challenge: DailyChallenge = { day: started.day, seed: started.seed, token: started.token, alreadyCompleted: started.alreadyCompleted };
+      this.active = challenge;
+      this.host.emit('hub:daily-started', { day: started.day, seed: started.seed, alreadyCompleted: started.alreadyCompleted });
+      play({ ...challenge });
+    } catch (error) {
+      this.host.emit('hub:daily-error', { day, error: messageOf(error) });
+    }
+  }
+
+  /**
+   * Record completion of the active challenge with optional metadata.
+   * Resolves with the new completion count and rank, or `null` when no
+   * challenge is active or the hub refused.
+   */
+  async complete(meta: DailyCompletionMeta = {}): Promise<DailyCompleteResponse | null> {
+    const challenge = this.active;
+    if (challenge === null) {
+      return null;
+    }
+    try {
+      const completed = await this.host.complete(challenge.day, challenge.token, meta);
+      this.active = null;
+      this.host.emit('hub:daily-complete', { day: challenge.day, count: completed.count, rank: completed.rank, meta });
+      return completed;
+    } catch (error) {
+      this.host.emit('hub:daily-error', { day: challenge.day, error: messageOf(error) });
+      return null;
+    }
+  }
+
+  /** Ask the page's other daily systems to start `day` (this one ignores its own event). */
+  private relayStart(day: string): void {
+    if (typeof window === 'undefined') {
+      return;
+    }
+    this.isRelaying = true;
+    try {
+      window.dispatchEvent(new CustomEvent(DAILY_START_EVENT, { detail: { day } }));
+    } finally {
+      this.isRelaying = false;
+    }
+  }
+
+  /** Abandon the active challenge without recording it (e.g. the player quit). */
+  cancel(): void {
+    this.active = null;
+  }
+
+  /** This game's window and the player's completions. */
+  status(): Promise<DailyStatus> {
+    return this.host.status();
+  }
+
+  /** Every daily-enabled game and the global standings (for the home hub). */
+  all(): Promise<DailyAll> {
+    return this.host.all();
+  }
+}

package/src/daily/page-daily.ts

@@ -0,0 +1,36 @@
+/**
+ * The page's one daily-challenge system (plan §4.4): the first bundle to
+ * create it wins, so the menu starts days on the instance the game defined.
+ */
+import { HUB_CLIENT_VERSION } from '../core/version/client-version.gen';
+import { claimSingleton } from '../globals';
+import { hasMethods } from '../realtime/cross-bundle';
+import { DailySystem } from './daily-system';
+import type { DailyHost } from './types';
+
+/** The cross-bundle shape number of the `daily` singleton. Bump only on an incompatible change. */
+export const DAILY_SINGLETON_API = 1;
+
+/** Whether `candidate` is some bundle's daily system (v1 copies included). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle
+export function isDailySystem(candidate: unknown): candidate is DailySystem {
+  return hasMethods(candidate, ['define', 'startAndPlay', 'complete', 'cancel', 'status', 'all']);
+}
+
+let claimedDaily: DailySystem | null = null;
+
+/**
+ * The page-wide daily system, created with `host` if no bundle has made one
+ * yet. On a shape mismatch the registered one is kept and this bundle gets a
+ * private instance. The answer is kept for this bundle.
+ */
+export function getDaily(host: DailyHost): DailySystem {
+  claimedDaily ??= claimSingleton({
+    name: 'daily',
+    version: HUB_CLIENT_VERSION,
+    api: DAILY_SINGLETON_API,
+    create: () => new DailySystem(host),
+    isInstance: isDailySystem,
+  });
+  return claimedDaily;
+}

package/src/daily/types.ts

@@ -0,0 +1,67 @@
+/**
+ * Daily challenge shapes: what a game's `play` receives, and the hub's
+ * answers (typed from the contract's daily endpoints).
+ */
+import type { dailyEndpoints, Json } from '@diffenderfer-games/hub-contract';
+import type { SchemaOutput } from '../realtime/wire-types';
+
+/** The response type of a daily endpoint. */
+type DailyResponse<Name extends keyof typeof dailyEndpoints> = SchemaOutput<(typeof dailyEndpoints)[Name]['cfg']['response']>;
+
+/** This game's daily window and the player's completions (`GET /games/:slug/daily`). */
+export type DailyStatus = DailyResponse<'getGameDailyChallenges'>;
+
+/** Every daily game and the global standings (`GET /daily`). */
+export type DailyAll = DailyResponse<'listDailyChallengesForAllGames'>;
+
+/** One game's row in {@link DailyAll}. */
+export type DailyGameStatus = DailyAll['games'][number];
+
+/** The answer to starting a day: its seed and the signed token to present on completion. */
+export type DailyStartResponse = DailyResponse<'startDailyChallenge'>;
+
+/** The answer to completing a day: the player's new completion count and rank. */
+export type DailyCompleteResponse = DailyResponse<'completeDailyChallenge'>;
+
+/** The challenge a game's `play` receives: set up and start exactly this day (derive the level from `seed`). */
+export interface DailyChallenge {
+  /** The day, `YYYY-MM-DD`. */
+  day: string;
+  /** Deterministic per game and day. */
+  seed: number;
+  /** The signed token `complete` presents. */
+  token: string;
+  /** The player already completed this day (a replay). */
+  alreadyCompleted?: boolean;
+}
+
+/** What `hub.daily.define` takes. */
+export interface DailyDefinition {
+  /** Start this challenge now. */
+  play: (challenge: DailyChallenge) => void;
+}
+
+/** Metadata a game records with a completion (`{ score, difficulty, timeMs, … }`). */
+export type DailyCompletionMeta = Record<string, Json>;
+
+/** What the daily system needs from the hub client: the REST calls and its window events. */
+export interface DailyHost {
+  /** This page's game slug. */
+  readonly slug: string | null;
+  /** `GET /games/:slug/daily`. */
+  status(): Promise<DailyStatus>;
+  /** `GET /daily`. */
+  all(): Promise<DailyAll>;
+  /** `POST /games/:slug/daily/:day/start`. */
+  start(day: string): Promise<DailyStartResponse>;
+  /** `POST /games/:slug/daily/:day/complete`. */
+  complete(day: string, token: string, meta: DailyCompletionMeta): Promise<DailyCompleteResponse>;
+  /** Fire a `hub:*` window event (the menu listens). */
+  emit(name: string, detail: DailyEventDetail): void;
+}
+
+/** The detail of the `hub:daily-*` window events. */
+export type DailyEventDetail =
+  | { day: string; seed: number; alreadyCompleted: boolean }
+  | { day: string; count: number; rank: number | null; meta: DailyCompletionMeta }
+  | { day: string; error: string };

package/src/daily.ts

@@ -0,0 +1,10 @@
+/**
+ * `@diffenderfer-games/hub/daily`: daily challenges (`hub.daily`): the
+ * {@link DailySystem} and the page-wide {@link getDaily}.
+ *
+ * @packageDocumentation
+ */
+export { DAILY_START_EVENT, DailySystem } from './daily/daily-system';
+export { DAILY_SINGLETON_API, getDaily, isDailySystem } from './daily/page-daily';
+export type * from './daily/types';
+export type { DailyCompletion, DailyCompletions } from '@diffenderfer-games/hub-contract';