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

package/dist/shared/index.d.ts

@@ -0,0 +1,706 @@
+import { s as DailySystem } from "./daily.js";
+import { n as getUiStack, w as InputSystem } from "./input.js";
+import { o as multiplayerForwarder } from "./mp.js";
+import { f as raceForwarder } from "./race.js";
+import { n as roomsForwarder } from "./rooms.js";
+import { Q as socialForwarder, X as notifyForwarder, Z as presenceForwarder } from "./social.js";
+import { Board, Board as Board$1, ErrorCode, GameInfo, GameLeaderboards, GameRecords, HubVersion, Inventory, Json, Json as Json$1, LeaderboardEntry, Metrics, Metrics as Metrics$1, PublicEndpoints, RejectReason, SessionUser, SortDir, SortDir as SortDir$1, Stats, Stats as Stats$1 } from "@diffenderfer-games/hub-contract";
+import { CallReturn, ClientData } from "@ayepi/core/client";
+//#region src/core/storage/key-value.d.ts
+/**
+ * The string store behind the offline cache and queues: `localStorage` when
+ * the page has it, else an in-memory map (privacy mode, Node, tests). Every
+ * key keeps the v1 client's name, so a page upgraded from a vendored copy
+ * still reads the queue and cache that copy wrote.
+ */
+/** A string key-value store with `localStorage`'s semantics. */
+interface KeyValueStore {
+  /** The stored text, or `null`. */
+  read(key: string): string | null;
+  /** Store text; a full or blocked storage is ignored. */
+  write(key: string, text: string): void;
+  /** Forget a key. */
+  remove(key: string): void;
+  /** Every stored key. */
+  keys(): string[];
+}
+//#endregion
+//#region src/core/game-data.d.ts
+/** Anything a game may store as JSON: an object (interfaces included), an array, text, a number, a boolean or `null`. */
+type GamePayload = object | string | number | boolean | null;
+//#endregion
+//#region src/core/rest/endpoint-types.d.ts
+/** The name of a public REST endpoint (`getCurrentUser`, `writeSave`, ...). */
+type EndpointName = keyof PublicEndpoints;
+/** One endpoint's request fields: path params, query and body merged into one object. */
+type EndpointFields<K extends EndpointName> = ClientData<PublicEndpoints[K]>;
+/**
+ * An endpoint that declares several success statuses comes back from ayepi's
+ * client as `{ status, data }`; this client always hands back the body.
+ */
+type ReplyBody<Reply> = Reply extends {
+  readonly status: number;
+  readonly data: infer Body;
+} ? Body : Reply;
+/** One endpoint's success reply body. */
+type EndpointReply<K extends EndpointName> = ReplyBody<Awaited<CallReturn<PublicEndpoints[K]>>>;
+//#endregion
+//#region src/core/types.d.ts
+/** The signed-in player. Offline (a locally stored user) only `id`, `username` and `guest` are known. */
+type User = Pick<SessionUser, 'id' | 'username'> & Partial<Omit<SessionUser, 'id' | 'username'>>;
+/** One game the player has a profile in. */
+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. */
+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`. */
+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). */
+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`. */
+interface Save<TData = Json> extends SaveMeta {
+  /** The stored JSON. */
+  readonly data: TData;
+}
+/** Options for `hub.submitScore()`, with the score's metadata typed as `TMeta`. */
+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). */
+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()`). */
+type LeaderboardResult = EndpointReply<'getLeaderboard'>;
+/** A board with its top entries. */
+type BoardWithTop = EndpointReply<'listTopOfEveryLeaderboard'>['games'][number]['boards'][number];
+/** One game's play counts, with its slug (`hub.analytics()`). */
+type GameAnalytics = EndpointReply<'getGameAnalytics'>;
+/** Catalog-wide play counts with a per-game breakdown (`hub.globalAnalytics()`). */
+interface GlobalAnalytics {
+  /** Across every game. */
+  readonly global: Metrics;
+  /** Per game. */
+  readonly games: (Metrics & {
+    readonly slug: string;
+    readonly title: string;
+  })[];
+}
+/** A listed game (`hub.listGames()`). */
+type GameInfo$1 = GameInfo;
+/** What `GET /me/snapshot` answers; `hub.prefetchAll()` warms the offline cache for every game from it. */
+type SnapshotResponse = EndpointReply<'getMyOfflineSnapshot'>;
+/** A player's holdings in one game, as the inventory calls answer. */
+type InventorySnapshot = EndpointReply<'getMyInventory'>;
+/** The connection and sync status `hub.onStatus()` reports. */
+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. */
+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';
+}
+//#endregion
+//#region src/core/offline/events.d.ts
+/** One buffered event. */
+interface BufferedEvent {
+  /** The event type, as `recordGameEvent` sends it. */
+  readonly type: string;
+  /** When it happened (epoch ms). */
+  readonly ts: number;
+}
+//#endregion
+//#region src/core/offline/queue.d.ts
+/** A score submission's options as queued (the metadata already JSON). */
+interface QueuedScoreOptions {
+  /** 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?: Json;
+}
+/** A profile change: either part may be left out. */
+interface ProfilePatch {
+  /** Shown to other players; `null` clears it. */
+  displayName?: string | null;
+  /** The game's own profile data. */
+  data?: Json;
+}
+/** A queued op's id and when it was queued. */
+interface QueueStamp {
+  /** Unique within this page: `<epoch ms>-<sequence>`. */
+  readonly id: string;
+  /** When it was queued (epoch ms). */
+  readonly ts: number;
+}
+/** A queued write, before it is stamped. */
+type QueueOpInput = {
+  readonly kind: 'putSave';
+  readonly slot: string;
+  readonly data: Json;
+  readonly label: string | null;
+} | {
+  readonly kind: 'deleteSave';
+  readonly slot: string;
+} | {
+  readonly kind: 'setStat';
+  readonly key: string;
+  readonly value: number;
+} | {
+  readonly kind: 'maxStat';
+  readonly key: string;
+  readonly value: number;
+} | {
+  readonly kind: 'incrStat';
+  readonly key: string;
+  readonly amount: number;
+} | {
+  readonly kind: 'submitScore';
+  readonly key: string;
+  readonly score: number;
+  readonly opts: QueuedScoreOptions;
+} | {
+  readonly kind: 'setProfile';
+  readonly patch: ProfilePatch;
+};
+/** A queued write, as stored under `hub:<slug>:queue`. */
+type QueueOp = QueueOpInput & QueueStamp;
+//#endregion
+//#region src/core/offline/local-store.d.ts
+/** A board this player has a local best on. */
+interface LocalBoard {
+  /** The board. */
+  readonly board: Board;
+  /** This player's best score. */
+  readonly best: number;
+}
+/** How a stat update combines with the stored value. */
+type StatUpdateMode = 'set' | 'incr' | 'max';
+/** One game's offline cache, queue and event buffer. */
+declare class LocalStore {
+  private readonly prefix;
+  private readonly store;
+  private sequence;
+  /** The cache for game `slug` in `store` (default: `localStorage`, or memory without it). */
+  constructor(slug: string, store?: KeyValueStore);
+  private readStored;
+  private writeStored;
+  /** The locally known user. */
+  getUser(): User | null;
+  /** Remember the user (offline sign-in, or a snapshot). */
+  setUser(user: User): void;
+  /** Forget the user (offline sign-out). */
+  clearUser(): void;
+  /** This game's cached profile. */
+  getProfile(): Profile | null;
+  /** Store this game's profile and return it. */
+  setProfile(game: string, displayName: string | null, profileData: Json): Profile;
+  /** Every cached save's metadata, newest first. */
+  listSaves(): SaveMeta[];
+  /** One cached save, or `null`. */
+  getSave(slot: string): Save | null;
+  /** Store a save and return its `updatedAt`. */
+  putSave(slot: string, saveData: Json, label: string | null): number;
+  /** Forget a save. */
+  deleteSave(slot: string): void;
+  /** This game's cached stats. */
+  getStats(): Stats;
+  /** Apply one stat update and return the stat's new value. */
+  updateStat(key: string, amount: number, mode: StatUpdateMode): number;
+  /** The boards this player has a local best on (offline boards only know the player's own best). */
+  listBoards(): Board[];
+  /** One board's local best, or `null`. */
+  getBoard(key: string): LocalBoard | null;
+  /** Record a score locally, keeping the best one; returns the board and best. */
+  submitScore(key: string, score: number, options: QueuedScoreOptions): LocalBoard;
+  /** The queued writes, oldest first. */
+  getQueue(): QueueOp[];
+  /** Replace the queue. */
+  setQueue(queue: readonly QueueOp[]): void;
+  /** How many writes are queued. */
+  queueLength(): number;
+  /** Queue a write, collapsing it with a compatible queued one. */
+  enqueue(input: QueueOpInput): void;
+  /** The buffered analytics events, oldest first. */
+  getEvents(): BufferedEvent[];
+  /** Replace the event buffer. */
+  setEvents(events: readonly BufferedEvent[]): void;
+  /** Buffer one event (capped; heartbeats are dropped first). */
+  bufferEvent(type: string): void;
+  /** Fan a `/me/snapshot` reply out across every game's cache keys. */
+  hydrate(snapshot: SnapshotResponse): void;
+}
+//#endregion
+//#region src/core/rest/rest-client.d.ts
+/** The header that tells the hub which client version is calling. */
+declare const CLIENT_VERSION_HEADER = "x-hub-client";
+/** The arguments of a call: the fields, optional when the endpoint takes none that are required. */
+type CallArguments<K extends EndpointName> = Partial<EndpointFields<K>> extends EndpointFields<K> ? [fields?: EndpointFields<K>] : [fields: EndpointFields<K>];
+/** Typed calls to the hub's public REST API. */
+interface RestClient {
+  /** The API's absolute base URL. */
+  readonly apiBase: string;
+  /** Call an endpoint; resolves with its reply body, rejects with a {@link HubError}. */
+  call<K extends EndpointName>(name: K, ...fieldsArgument: CallArguments<K>): Promise<EndpointReply<K>>;
+}
+//#endregion
+//#region src/core/connection.d.ts
+/** A queued write the hub refused during a sync: dropped, with the hub's message. */
+interface SyncConflict {
+  /** The refused op. */
+  readonly op: QueueOp;
+  /** The hub's message. */
+  readonly error?: string;
+}
+/** What one `sync()` did. */
+interface SyncResult {
+  /** Queued writes the hub accepted. */
+  readonly flushed: number;
+  /** Queued writes the hub refused (and that were dropped). */
+  readonly conflicts: SyncConflict[];
+}
+/** The game slug's path field, or a {@link HubError} when the slug is unknown. */
+interface GameFields {
+  /** The game's slug. */
+  readonly slug: string;
+}
+/** The connection, offline cache and sync machinery shared by every `Hub` method. */
+declare class HubConnection {
+  /** This client's game slug (`null` when it could not be determined). */
+  readonly slug: string | null;
+  /** The absolute API base, e.g. `https://diffenderfer.games/_api`. */
+  readonly apiBase: string;
+  /** Typed REST calls to {@link apiBase}. */
+  protected readonly rest: RestClient;
+  /** This game's offline cache, queue and event buffer. */
+  protected readonly store: LocalStore;
+  private readonly offlineMode;
+  private isReachable;
+  private isSyncing;
+  private lastPrefetchAt;
+  private readonly statusListeners;
+  /** A connection for `options` (slug and API base default to the page's). */
+  constructor(options?: HubOptions);
+  /** `true` when calls are being served from the offline cache rather than the hub. */
+  get isOffline(): boolean;
+  /** `true` while the hub is reachable. */
+  get isOnline(): boolean;
+  /** Queued writes plus buffered analytics events waiting to sync. */
+  pending(): number;
+  /** Subscribe to connection and sync status changes; returns the unsubscribe function. */
+  onStatus(listener: (status: HubStatus) => void): () => void;
+  /** Tell `onStatus` listeners and the page (`hub:status`) the current status. */
+  protected notifyStatus(): void;
+  /** Record reachability; coming back online syncs the queue and re-warms the cache. */
+  protected setReachable(isReachableNow: boolean): void;
+  /** `{ slug }` for this game's endpoints; throws when the slug is unknown. */
+  protected gameFields(): GameFields;
+  /**
+   * Run the network call, falling back to the offline answer when the hub
+   * can't be reached (per the offline mode). Real API errors (with an HTTP
+   * status) always reach the caller.
+   */
+  protected withFallback<Reply>(networkCall: () => Promise<Reply>, offlineAnswer: () => Reply): Promise<Reply>;
+  /** Send one queued write. */
+  private sendOp;
+  /**
+   * Apply a write to the offline cache at once, then send it now (online
+   * with an empty queue) or queue it behind the others. Resolves with the
+   * local answer; a real API error on the direct path reaches the caller and
+   * is not queued.
+   */
+  protected mutateQueued<Reply>(input: QueueOpInput, localAnswer: () => Reply): Promise<Reply>;
+  /**
+   * Replay the queue, then the buffered events, in order. Stops at the first
+   * transport failure (offline again: the rest stays queued); a write the hub
+   * refuses is dropped and reported as a conflict.
+   */
+  sync(): Promise<SyncResult>;
+  /** Send the buffered analytics events; a refused one is dropped (telemetry never blocks). */
+  private flushEvents;
+  /**
+   * Warm the offline cache for every game the player has touched, in one
+   * request, so going offline later still shows complete progress.
+   * Throttled to once per 30 s unless `isForced`; `null` when offline or throttled.
+   */
+  prefetchAll(isForced?: boolean): Promise<SnapshotResponse | null>;
+}
+//#endregion
+//#region src/core/hub-progress.d.ts
+/** A signed-in user, as the auth calls answer. */
+interface AuthResponse {
+  /** The signed-in user. */
+  readonly user: User;
+}
+/** A stat's new value, as the stat calls answer. */
+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`. */
+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;
+}
+/** Accounts, profile, saves, stats and leaderboards. */
+declare class HubProgress extends HubConnection {
+  /** The current user (or `null`) and the games they have a profile in. */
+  me(): Promise<MeResponse>;
+  /**
+   * 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>;
+  /**
+   * 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>;
+  /** Create an account and sign in. (Offline: a local user is stored.) */
+  signup(username: string, password: string): Promise<AuthResponse>;
+  /** Sign in. (Offline: a local user is stored so signed-in flows work.) */
+  login(username: string, password: string): Promise<AuthResponse>;
+  /** Sign out (ends the session shared by every game). */
+  logout(): Promise<{
+    ok: true;
+  }>;
+  private signInLocally;
+  /** 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;
+  }>;
+  /** Create or update this game's profile for the current user. */
+  setProfile<TData extends GamePayload = Json>(patch: ProfileUpdate<TData>): Promise<{
+    profile: Profile<TData>;
+  }>;
+  /** Metadata for every save slot (no payloads), newest first. */
+  listSaves(): Promise<{
+    saves: SaveMeta[];
+  }>;
+  /** 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;
+  }>;
+  /** Create or overwrite a save slot. `saveData` is any JSON up to 64 KB. */
+  putSave<TData extends GamePayload = Json>(slot: string, saveData: TData, label?: string): Promise<{
+    ok: true;
+    updatedAt: number;
+  }>;
+  /** Delete a save slot. */
+  deleteSave(slot: string): Promise<{
+    ok: true;
+  }>;
+  /** Numeric stats for the current user, or another player's via `userId`. */
+  getStats(userId?: number): Promise<{
+    stats: Stats;
+  }>;
+  /** Overwrite a stat. */
+  setStat(key: string, value: number): Promise<StatResult>;
+  /** Add to a stat (creating it at `amount` when absent). */
+  incrStat(key: string, amount?: number): Promise<StatResult>;
+  /** Keep the larger of the stored and the given value. */
+  maxStat(key: string, value: number): Promise<StatResult>;
+  /** 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>;
+  /** One board's ranked entries (top `limit`, default 50). Offline: only the player's own best. */
+  getLeaderboard(boardKey: string, limit?: number): Promise<LeaderboardResult>;
+  /** The boards this game owns (keys and titles, no entries). */
+  listLeaderboards(): Promise<{
+    boards: Board[];
+  }>;
+}
+//#endregion
+//#region src/core/hub-economy.d.ts
+/** Goods to grant: item key to quantity, and coins. */
+type GrantBundle = Omit<EndpointFields<'grantInventoryItems'>, 'slug'>;
+/** Goods taken or given in an exchange or a trade. */
+type TradeBundle = EndpointFields<'exchangeInventoryItems'>['take'];
+/** A trade offer's id, as a number or its text. */
+type TradeId = number | string;
+/** Extras for creating or countering a trade. */
+interface TradeNoteOptions {
+  /** A short note to the other player (moderated). */
+  readonly note?: string;
+}
+/** Which trades `listTrades` lists. */
+type TradeListOptions = Omit<EndpointFields<'listMyTrades'>, 'slug'>;
+/** Analytics, catalog, favorites, records, inventory and trades. */
+declare class HubEconomy extends HubProgress {
+  /** Record a "play". Call once when the game starts. */
+  recordPlay(): Promise<void>;
+  /** Record a "heartbeat". Call periodically while the game is active. */
+  heartbeat(): Promise<void>;
+  /** Record a custom event. Never throws; offline, events are buffered and sent on reconnect. */
+  event(type: string): Promise<void>;
+  /** This game's play counts. */
+  analytics(): Promise<GameAnalytics>;
+  /** Catalog-wide play counts with a per-game breakdown. */
+  globalAnalytics(): Promise<GlobalAnalytics>;
+  /** The listed games, for "jump to another game" navigation. */
+  listGames(): Promise<{
+    games: GameInfo$1[];
+  }>;
+  /** Every board of every game, each with its top `top` entries (default 5). */
+  allLeaderboards(top?: number): Promise<EndpointReply<'listTopOfEveryLeaderboard'>>;
+  /**
+   * 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[];
+  }>;
+  /** Star (`isOn = true`) or unstar a game. Needs a connection. */
+  setFavorite(slug: string, isOn: boolean): Promise<{
+    games: string[];
+  }>;
+  /** 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'>>;
+  /** This game's inventory and coin balance for the current user. */
+  getInventory(): Promise<InventorySnapshot>;
+  /** Another player's available holdings (to compose a trade). */
+  playerInventory(userId: number): Promise<InventorySnapshot>;
+  /** Add goods to the player (gameplay rewards); answers the new holdings. */
+  grant(bundle: GrantBundle): Promise<EndpointReply<'grantInventoryItems'>>;
+  /** An atomic swap with the house: remove `take`, add `give`. */
+  exchange(take?: TradeBundle, give?: TradeBundle): Promise<EndpointReply<'exchangeInventoryItems'>>;
+  /** Sell items to the house for coins. */
+  sell(items: Record<string, number>, coins: number): Promise<EndpointReply<'exchangeInventoryItems'>>;
+  /** Buy items from the house with coins. */
+  buy(coins: number, items: Record<string, number>): Promise<EndpointReply<'exchangeInventoryItems'>>;
+  /** Wipe the player's progress in this game (saves, stats, inventory and coins). */
+  resetGame(): Promise<{
+    ok: true;
+  }>;
+  /** Players this player can trade with in this game. */
+  listPlayers(): Promise<EndpointReply<'listTradePartners'>>;
+  /** The player's trades (`box`: `incoming` or `outgoing`; `status` filters). */
+  listTrades(opts?: TradeListOptions): Promise<EndpointReply<'listMyTrades'>>;
+  /** Offer a trade to another player (by id or name). */
+  createTrade(toUser: number | string, give?: TradeBundle, want?: TradeBundle, opts?: TradeNoteOptions): Promise<EndpointReply<'createTrade'>>;
+  /** Accept a trade offered to the player. */
+  acceptTrade(id: TradeId): Promise<EndpointReply<'acceptTrade'>>;
+  /** Decline a trade offered to the player. */
+  declineTrade(id: TradeId): Promise<EndpointReply<'declineTrade'>>;
+  /** Cancel a trade the player offered. */
+  cancelTrade(id: TradeId): Promise<EndpointReply<'cancelTrade'>>;
+  /** Answer a trade with a counter-offer. */
+  counterTrade(id: TradeId, give?: TradeBundle, want?: TradeBundle, opts?: TradeNoteOptions): Promise<EndpointReply<'counterTradeOffer'>>;
+}
+//#endregion
+//#region src/core/menu-control.d.ts
+declare global {
+  interface Window {
+    /** The last requested menu-button visibility (absent: visible). */
+    __HUB_MENU_VISIBLE__?: boolean;
+  }
+}
+/** Control over the injected hub menu button. */
+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;
+}
+//#endregion
+//#region src/core/version/hub-version.d.ts
+/** How a hub regards a client version. */
+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';
+//#endregion
+//#region src/core/hub.d.ts
+/** The hub client. Use the ready-made {@link hub}, or `createHub()` for another slug or API base. */
+declare class Hub extends HubEconomy {
+  /** This client's package version (sent as `x-hub-client`). */
+  readonly clientVersion: string;
+  /**
+   * 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>;
+  /** How the hub regards this client: `supported`, `deprecated`, `unsupported`, or `unknown` (an older hub). */
+  clientSupport(): Promise<ClientSupport>;
+  /**
+   * 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;
+  /** Hub UI covering the game (menu, dialogs, chat): open/close events and `autoPause`. Page-wide. */
+  get overlay(): ReturnType<typeof getUiStack>;
+  /** Show or hide the injected hub menu button (page-wide). */
+  get menu(): HubMenuControl;
+  /**
+   * 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;
+  /** Tell friends what the player is doing in this game. */
+  get presence(): typeof presenceForwarder;
+  /** Friends, players and the hub's social dialogs. */
+  get social(): typeof socialForwarder;
+  /** Invites, launches, the leave guard and own-server tickets. */
+  get mp(): typeof multiplayerForwarder;
+  /** Hub relay rooms, for games without a server. */
+  get rooms(): typeof roomsForwarder;
+  /** Toast behaviour during intense play. */
+  get notify(): typeof notifyForwarder;
+  /** Races: a single-player game becomes multiplayer by racing. */
+  get race(): typeof raceForwarder;
+  /** What the daily system needs from this client: its REST calls and window events. */
+  private dailyHost;
+}
+/** A ready-to-use client, with the slug and API base detected from the page. */
+declare const hub: Hub;
+/** Create a client for another slug or API base, or with other offline behaviour. */
+declare function createHub(options?: HubOptions): Hub;
+//#endregion
+//#region src/core/errors.d.ts
+/**
+ * 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.
+ */
+declare const UNSUPPORTED_BY_HUB = "unsupported_by_hub";
+/** The code the social runtime gives a call it could not send (no connection). */
+declare 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.
+ */
+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. */
+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}.
+ */
+declare 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);
+  /** `true` when the failure was a network or transport error, not an HTTP status. */
+  get isOffline(): boolean;
+}
+/** Thrown when an action that genuinely needs the hub is attempted offline. */
+declare class OfflineError extends HubError {
+  /** An offline error; the default message is "This needs a connection.". */
+  constructor(message?: string);
+}
+/**
+ * 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.
+ */
+declare class ContentRejectedError extends HubError {
+  /** A content reject with the hub's message, status and extras. */
+  constructor(message: string, status: number | undefined, details: HubErrorDetails);
+}
+//#endregion
+//#region src/core/version/client-version.gen.d.ts
+/** This client's package version, sent as `x-hub-client` on REST calls and `client` in `hello`. */
+declare const HUB_CLIENT_VERSION = "2.0.0-next.1";
+//#endregion
+export { SubmitScoreResult as $, BoardWithTop as A, Json$1 as B, CLIENT_VERSION_HEADER as C, QueuedScoreOptions as D, QueueOpInput as E, GlobalAnalytics as F, Profile as G, LeaderboardResult as H, HubOptions as I, SaveMeta as J, ProfileSummary as K, HubStatus as L, GameInfo$1 as M, GameLeaderboards as N, BufferedEvent as O, GameRecords as P, SubmitScoreOptions as Q, Inventory as R, SyncResult as S, QueueOp as T, MeResponse as U, LeaderboardEntry as V, Metrics$1 as W, SortDir$1 as X, SnapshotResponse as Y, Stats$1 as Z, TradeNoteOptions as _, HubErrorDetails as a, StatResult as b, Hub as c, ClientSupport as d, User as et, HubMenuControl as f, TradeListOptions as g, TradeId as h, HubErrorCode as i, GamePayload as it, GameAnalytics as j, Board$1 as k, createHub as l, TradeBundle as m, ContentRejectedError as n, EndpointName as nt, OfflineError as o, GrantBundle as p, Save as q, HubError as r, EndpointReply as rt, UNSUPPORTED_BY_HUB as s, HUB_CLIENT_VERSION as t, EndpointFields as tt, hub as u, AuthResponse as v, ProfilePatch as w, SyncConflict as x, ProfileUpdate as y, InventorySnapshot as z };
+//# sourceMappingURL=index.d.ts.map