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

package/src/core/offline/queue.ts

@@ -0,0 +1,171 @@
+/**
+ * The offline mutation queue. Writes apply to the local cache at once and
+ * queue a durable op; when the hub is reachable again the queue replays in
+ * order. Ops collapse as they are queued (a save's last write wins, `incr`s
+ * add up, `max`es keep the largest, a board keeps its best, profile patches
+ * merge), so the backlog stays small.
+ *
+ * The op shapes are the v1 client's, unchanged: a page upgraded from a
+ * vendored copy replays the queue that copy left in `localStorage`.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import type { SortDir } from '@diffenderfer-games/hub-contract';
+import { isJson, isNullableString, isRecord, optionalNumber, optionalString, type UncheckedRecord } from '../storage/json-guards';
+
+/** A score submission's options as queued (the metadata already JSON). */
+export 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. */
+export 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. */
+export 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`. */
+export type QueueOp = QueueOpInput & QueueStamp;
+
+/** The score options in a stored op, or `undefined` when they are malformed. */
+function readScoreOptions(stored: UncheckedRecord): QueuedScoreOptions | undefined {
+  const title = optionalString(stored.title);
+  const sort = stored.sort === 'asc' || stored.sort === 'desc' ? stored.sort : undefined;
+  if (stored.meta !== undefined && !isJson(stored.meta)) {
+    return undefined;
+  }
+  return { ...(title === undefined ? {} : { title }), ...(sort === undefined ? {} : { sort }), ...(stored.meta === undefined ? {} : { meta: stored.meta }) };
+}
+
+/** The profile patch in a stored op, or `undefined` when it is malformed. */
+function readProfilePatch(stored: UncheckedRecord): ProfilePatch | undefined {
+  if ((stored.displayName !== undefined && !isNullableString(stored.displayName)) || (stored.data !== undefined && !isJson(stored.data))) {
+    return undefined;
+  }
+  const patch: ProfilePatch = {};
+  if (stored.displayName !== undefined) {
+    patch.displayName = stored.displayName;
+  }
+  if (stored.data !== undefined) {
+    patch.data = stored.data;
+  }
+  return patch;
+}
+
+/** One stored op's write, or `undefined` when it is not a known, well-formed op. */
+function readOpInput(stored: UncheckedRecord): QueueOpInput | undefined {
+  const slot = optionalString(stored.slot);
+  const key = optionalString(stored.key);
+  const statValue = optionalNumber(stored.value);
+  switch (stored.kind) {
+    case 'putSave':
+      return slot !== undefined && isJson(stored.data) && isNullableString(stored.label) ? { kind: 'putSave', slot, data: stored.data, label: stored.label } : undefined;
+    case 'deleteSave':
+      return slot === undefined ? undefined : { kind: 'deleteSave', slot };
+    case 'setStat':
+    case 'maxStat':
+      return key !== undefined && statValue !== undefined ? { kind: stored.kind, key, value: statValue } : undefined;
+    case 'incrStat': {
+      const amount = optionalNumber(stored.amount);
+      return key !== undefined && amount !== undefined ? { kind: 'incrStat', key, amount } : undefined;
+    }
+    case 'submitScore': {
+      const score = optionalNumber(stored.score);
+      const opts = isRecord(stored.opts) ? readScoreOptions(stored.opts) : undefined;
+      return key !== undefined && score !== undefined && opts !== undefined ? { kind: 'submitScore', key, score, opts } : undefined;
+    }
+    case 'setProfile': {
+      const patch = isRecord(stored.patch) ? readProfilePatch(stored.patch) : undefined;
+      return patch === undefined ? undefined : { kind: 'setProfile', patch };
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** The well-formed ops of a stored queue, in order; anything malformed is dropped. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a queue read back from localStorage (possibly written by a v1 client)
+export function readQueue(stored: unknown): QueueOp[] {
+  if (!Array.isArray(stored)) {
+    return [];
+  }
+  return stored.flatMap((entry): QueueOp[] => {
+    if (!isRecord(entry)) {
+      return [];
+    }
+    const input = readOpInput(entry);
+    const id = optionalString(entry.id);
+    const ts = optionalNumber(entry.ts);
+    return input === undefined || id === undefined || ts === undefined ? [] : [{ ...input, id, ts }];
+  });
+}
+
+/** The better of two scores on a board sorted `sort` (`desc` by default). */
+export function betterScore(first: number, second: number, sort: SortDir | undefined): number {
+  return sort === 'asc' ? Math.min(first, second) : Math.max(first, second);
+}
+
+/** The op that `queued` becomes when `incoming` collapses into it, or `undefined` when they don't collapse. */
+function collapsedOp(queued: QueueOp, incoming: QueueOp): QueueOp | undefined {
+  if (queued.kind === 'incrStat' && incoming.kind === 'incrStat' && queued.key === incoming.key) {
+    return { ...queued, amount: queued.amount + incoming.amount };
+  }
+  if (queued.kind === 'maxStat' && incoming.kind === 'maxStat' && queued.key === incoming.key) {
+    return { ...queued, value: Math.max(queued.value, incoming.value) };
+  }
+  if (queued.kind === 'setStat' && incoming.kind === 'setStat' && queued.key === incoming.key) {
+    return { ...queued, value: incoming.value };
+  }
+  if (queued.kind === 'submitScore' && incoming.kind === 'submitScore' && queued.key === incoming.key) {
+    return { ...queued, score: betterScore(queued.score, incoming.score, incoming.opts.sort), opts: incoming.opts };
+  }
+  if (queued.kind === 'setProfile' && incoming.kind === 'setProfile') {
+    return { ...queued, patch: { ...queued.patch, ...incoming.patch } };
+  }
+  return undefined;
+}
+
+/** Whether an op writes save slot `slot`. */
+function writesSlot(op: QueueOp, slot: string): boolean {
+  return (op.kind === 'putSave' || op.kind === 'deleteSave') && op.slot === slot;
+}
+
+/**
+ * The queue with `incoming` added: a save or delete replaces any queued
+ * write to the same slot (and goes last); a compatible op merges into the
+ * first queued one in place; anything else is appended.
+ */
+export function enqueueOp(queue: readonly QueueOp[], incoming: QueueOp): QueueOp[] {
+  if (incoming.kind === 'putSave' || incoming.kind === 'deleteSave') {
+    return [...queue.filter((op) => !writesSlot(op, incoming.slot)), incoming];
+  }
+  const mergeAt = queue.findIndex((op) => collapsedOp(op, incoming) !== undefined);
+  if (mergeAt < 0) {
+    return [...queue, incoming];
+  }
+  return queue.map((op, i) => (i === mergeAt ? (collapsedOp(op, incoming) ?? op) : op));
+}

package/src/core/page.ts

@@ -0,0 +1,74 @@
+/**
+ * What the page tells the client: the host's injected `window.__HUB__`
+ * (contract `HubInject`), the game's slug, and the API base. A page the host
+ * did not inject (`game.hub: false`, local development) has no `__HUB__`.
+ */
+import type { HubInject } from '@diffenderfer-games/hub-contract';
+import { isRecord, optionalString } from './storage/json-guards';
+
+declare global {
+  interface Window {
+    /** The host's injected config (contract `HubInject`); read through {@link injectedConfig}. */
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: written by the host's inline script, read field by field
+    __HUB__?: unknown;
+  }
+}
+
+/** The fields of `window.__HUB__` the core client reads. */
+export type InjectedConfig = Partial<Pick<HubInject, 'slug'>> & { readonly apiBase?: string };
+
+/** Whether this code runs in a browser page. */
+export function isBrowserPage(): boolean {
+  return typeof window !== 'undefined';
+}
+
+/** Whether the host injected this page (`window.__HUB__` exists), so the menu and social runtime can arrive. */
+export function isHubInjectedPage(): boolean {
+  return isBrowserPage() && isRecord(window.__HUB__);
+}
+
+/** The injected config's slug and API base, read defensively (empty outside a hub page). */
+export function injectedConfig(): InjectedConfig {
+  if (!isBrowserPage() || !isRecord(window.__HUB__)) {
+    return {};
+  }
+  const slug = optionalString(window.__HUB__.slug);
+  const apiBase = optionalString(window.__HUB__.apiBase);
+  return { ...(slug === undefined ? {} : { slug }), ...(apiBase === undefined ? {} : { apiBase }) };
+}
+
+/** The game's slug: the injected one, else the first URL path segment, else `null`. */
+export function detectSlug(): string | null {
+  const injectedSlug = injectedConfig().slug;
+  if (injectedSlug !== undefined && injectedSlug !== '') {
+    return injectedSlug;
+  }
+  if (typeof location === 'undefined') {
+    return null;
+  }
+  return location.pathname.split('/').find((segment) => segment !== '') ?? null;
+}
+
+/** An API base made absolute against the page origin (`http://localhost` outside a browser), without a trailing slash. */
+export function absoluteApiBase(apiBase: string): string {
+  const origin = typeof location === 'undefined' ? 'http://localhost' : location.origin;
+  return new URL(apiBase, origin).toString().replace(/\/$/, '');
+}
+
+/** The page's API base: the injected one, else `/_api`, made absolute. */
+export function detectApiBase(): string {
+  return absoluteApiBase(injectedConfig().apiBase ?? '/_api');
+}
+
+/** Dispatch a `CustomEvent` on `window` (no-op outside a browser; listener errors never reach the caller). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: event details are whatever the event documents; listeners read them
+export function emitWindowEvent(eventName: string, detail?: unknown): void {
+  if (!isBrowserPage()) {
+    return;
+  }
+  try {
+    window.dispatchEvent(new CustomEvent(eventName, { detail }));
+  } catch {
+    // A page without CustomEvent (very old browsers) misses the event.
+  }
+}

package/src/core/rest/endpoint-types.ts

@@ -0,0 +1,22 @@
+/**
+ * Per-endpoint request and reply types, derived from the contract's spec
+ * **type** only (`import type`, erased at build): the browser bundle carries
+ * the route table, never the schemas (plan D16).
+ */
+import type { CallReturn, ClientData } from '@ayepi/core/client';
+import type { PublicEndpoints } from '@diffenderfer-games/hub-contract';
+
+/** The name of a public REST endpoint (`getCurrentUser`, `writeSave`, ...). */
+export type EndpointName = keyof PublicEndpoints;
+
+/** One endpoint's request fields: path params, query and body merged into one object. */
+export 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. */
+export type EndpointReply<K extends EndpointName> = ReplyBody<Awaited<CallReturn<PublicEndpoints[K]>>>;

package/src/core/rest/rest-client.ts

@@ -0,0 +1,152 @@
+/**
+ * The REST transport: a small fetch router over the contract's route table
+ * (plan §12 A10). It splits one merged fields object into the path, query
+ * and JSON body the way ayepi's client does, stamps `x-hub-client`, and turns
+ * failures into {@link HubError}s. It carries no schemas: replies are typed
+ * from the contract and trusted, as ayepi's zod-free client trusts them.
+ */
+import { errorFor, HubError, readErrorFields, UNSUPPORTED_BY_HUB } from '../errors';
+import { isRecord } from '../storage/json-guards';
+import { HUB_CLIENT_VERSION } from '../version/client-version.gen';
+import type { EndpointFields, EndpointName, EndpointReply } from './endpoint-types';
+import { ROUTES } from './routes.gen';
+
+/** The header that tells the hub which client version is calling. */
+export const CLIENT_VERSION_HEADER = 'x-hub-client';
+
+/** What both hubs answer for a route they do not have. */
+const NO_SUCH_ENDPOINT = 'No such API endpoint.';
+
+/** How a {@link RestClient} reaches the hub. */
+export interface RestClientOptions {
+  /** The API's absolute base URL without a trailing slash, e.g. `https://diffenderfer.games/_api`. */
+  readonly apiBase: string;
+  /** The fetch to use. */
+  readonly fetch: typeof fetch;
+  /** Called whenever the hub answered at all (any status): the network is up. */
+  readonly onReachable?: () => void;
+}
+
+/** The arguments of a call: the fields, optional when the endpoint takes none that are required. */
+export 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. */
+export 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>>;
+}
+
+/** One field value as URL text. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a request field value of any contract type
+function urlText(fieldValue: unknown): string {
+  if (typeof fieldValue === 'string') {
+    return fieldValue;
+  }
+  if (typeof fieldValue === 'number' || typeof fieldValue === 'boolean') {
+    return String(fieldValue);
+  }
+  return JSON.stringify(fieldValue);
+}
+
+/** The request one call makes: its URL (under the API base), method and JSON body. */
+export interface PlannedRequest {
+  /** The path and query, e.g. `/games/pool/leaderboards/best?limit=50`. */
+  readonly pathAndQuery: string;
+  /** The HTTP method. */
+  readonly method: string;
+  /** The JSON body text, or `undefined` for none. */
+  readonly bodyText: string | undefined;
+}
+
+/**
+ * Split merged fields into path, query and body for one endpoint: `:name`
+ * segments take their field, query keys go to the query string, and the
+ * rest is the JSON body. POST and PUT always send a body (`{}` when empty),
+ * as the v1 client did; DELETE sends one only when it has fields.
+ */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
+export function planRequest(name: EndpointName, fields: unknown): PlannedRequest {
+  const route = ROUTES[name];
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
+  const remaining = new Map<string, unknown>(Object.entries(isRecord(fields) ? fields : {}).filter(([, fieldValue]) => fieldValue !== undefined));
+  const path = route.path.replace(/:([A-Za-z]+)/g, (_segment, paramName: string) => {
+    const paramValue = remaining.get(paramName);
+    remaining.delete(paramName);
+    return encodeURIComponent(urlText(paramValue));
+  });
+  const queryKeys: readonly string[] = route.method === 'GET' ? [...remaining.keys()] : route.query;
+  const query = new URLSearchParams();
+  for (const key of queryKeys) {
+    const queryValue = remaining.get(key);
+    remaining.delete(key);
+    if (queryValue !== undefined && queryValue !== null) {
+      query.set(key, urlText(queryValue));
+    }
+  }
+  const queryText = query.toString();
+  const hasBody = route.method === 'POST' || route.method === 'PUT' || (route.method === 'DELETE' && remaining.size > 0);
+  return {
+    pathAndQuery: queryText === '' ? path : `${path}?${queryText}`,
+    method: route.method,
+    bodyText: hasBody ? JSON.stringify(Object.fromEntries(remaining)) : undefined,
+  };
+}
+
+/**
+ * The reply body, typed by the contract. This is the client's one trust
+ * boundary on replies: there is no zod in the browser bundle (plan D16).
+ */
+async function readReply<Reply>(response: Response): Promise<Reply> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return -- trust boundary: the hub's JSON reply, typed by the contract (the zod-free client trusts the server, plan D16)
+    return await response.json();
+  } catch {
+    throw new HubError('The hub sent a reply that is not JSON.', response.status);
+  }
+}
+
+/** The error for a failed response. */
+async function failureOf(name: EndpointName, response: Response): Promise<HubError> {
+  let fields = readErrorFields(undefined);
+  try {
+    fields = readErrorFields(await response.json());
+  } catch {
+    // A non-JSON error body keeps the generic message.
+  }
+  if (response.status === 404 && fields.error === NO_SUCH_ENDPOINT) {
+    return new HubError(`This hub does not have "${name}" yet: deploy the hub first, or use an older client.`, 404, { code: UNSUPPORTED_BY_HUB });
+  }
+  return errorFor(fields.error ?? `Request failed (${response.status})`, response.status, fields);
+}
+
+/** A REST client for one API base. */
+export function createRestClient(options: RestClientOptions): RestClient {
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: the caller's typed fields, walked generically
+  async function send<Reply>(name: EndpointName, fields: unknown): Promise<Reply> {
+    const planned = planRequest(name, fields);
+    let response: Response;
+    try {
+      response = await options.fetch(options.apiBase + planned.pathAndQuery, {
+        method: planned.method,
+        credentials: 'same-origin',
+        headers: { 'content-type': 'application/json', [CLIENT_VERSION_HEADER]: HUB_CLIENT_VERSION },
+        ...(planned.bodyText === undefined ? {} : { body: planned.bodyText }),
+      });
+    } catch (failure) {
+      throw new HubError(`Hub unreachable: ${failure instanceof Error ? failure.message : String(failure)}`);
+    }
+    options.onReachable?.();
+    if (!response.ok) {
+      throw await failureOf(name, response);
+    }
+    return readReply<Reply>(response);
+  }
+  return {
+    apiBase: options.apiBase,
+    call: (name, ...fieldsArgument) => send(name, fieldsArgument[0]),
+  };
+}

package/src/core/rest/routes.gen.ts

@@ -0,0 +1,90 @@
+// Generated by tools/hub-client/generate.ts. Do not edit; run `npm run gen:hub-client` in next/.
+/** Every public REST endpoint's method, path (under `/_api`) and query keys, from the contract. */
+export const ROUTES = {
+  ensureGuestSession: { method: 'POST', path: '/auth/guest', query: [] },
+  signUpWithPassword: { method: 'POST', path: '/auth/signup', query: [] },
+  logInWithPassword: { method: 'POST', path: '/auth/login', query: [] },
+  logOut: { method: 'POST', path: '/auth/logout', query: [] },
+  getCurrentUser: { method: 'GET', path: '/me', query: [] },
+  claimGuestAccount: { method: 'POST', path: '/auth/claim', query: [] },
+  listGames: { method: 'GET', path: '/games', query: [] },
+  listWhatsNewNotes: { method: 'GET', path: '/changes', query: ['game', 'since'] },
+  listFavoriteGames: { method: 'GET', path: '/favorites', query: [] },
+  setGameFavorite: { method: 'PUT', path: '/favorites/:slug', query: [] },
+  markWhatsNewSeen: { method: 'POST', path: '/changes/seen', query: [] },
+  getGameStats: { method: 'GET', path: '/games/:slug/stats', query: ['user'] },
+  getGameProfile: { method: 'GET', path: '/games/:slug/profile', query: [] },
+  setGameProfile: { method: 'PUT', path: '/games/:slug/profile', query: [] },
+  listSaves: { method: 'GET', path: '/games/:slug/saves', query: [] },
+  getSave: { method: 'GET', path: '/games/:slug/saves/:slot', query: [] },
+  writeSave: { method: 'PUT', path: '/games/:slug/saves/:slot', query: [] },
+  deleteSave: { method: 'DELETE', path: '/games/:slug/saves/:slot', query: [] },
+  updateGameStat: { method: 'POST', path: '/games/:slug/stats', query: [] },
+  resetMyGameProgress: { method: 'POST', path: '/games/:slug/reset', query: [] },
+  listMyLeaderboardRecords: { method: 'GET', path: '/me/records', query: ['game'] },
+  getMyOfflineSnapshot: { method: 'GET', path: '/me/snapshot', query: ['top'] },
+  listTopOfEveryLeaderboard: { method: 'GET', path: '/leaderboards', query: ['top'] },
+  listGameLeaderboards: { method: 'GET', path: '/games/:slug/leaderboards', query: [] },
+  getLeaderboard: { method: 'GET', path: '/games/:slug/leaderboards/:key', query: ['limit'] },
+  submitScore: { method: 'POST', path: '/games/:slug/leaderboards/:key/scores', query: [] },
+  listDailyChallengesForAllGames: { method: 'GET', path: '/daily', query: [] },
+  getGameDailyChallenges: { method: 'GET', path: '/games/:slug/daily', query: [] },
+  startDailyChallenge: { method: 'POST', path: '/games/:slug/daily/:day/start', query: [] },
+  completeDailyChallenge: { method: 'POST', path: '/games/:slug/daily/:day/complete', query: [] },
+  getMyInventory: { method: 'GET', path: '/games/:slug/inventory', query: [] },
+  grantInventoryItems: { method: 'POST', path: '/games/:slug/inventory/grant', query: [] },
+  exchangeInventoryItems: { method: 'POST', path: '/games/:slug/inventory/exchange', query: [] },
+  getPlayerInventory: { method: 'GET', path: '/games/:slug/players/:userId/inventory', query: [] },
+  listTradePartners: { method: 'GET', path: '/games/:slug/trades/players', query: [] },
+  listMyTrades: { method: 'GET', path: '/games/:slug/trades', query: ['box', 'status'] },
+  declineTrade: { method: 'POST', path: '/games/:slug/trades/:id/decline', query: [] },
+  cancelTrade: { method: 'POST', path: '/games/:slug/trades/:id/cancel', query: [] },
+  createTrade: { method: 'POST', path: '/games/:slug/trades', query: [] },
+  acceptTrade: { method: 'POST', path: '/games/:slug/trades/:id/accept', query: [] },
+  counterTradeOffer: { method: 'POST', path: '/games/:slug/trades/:id/counter', query: [] },
+  getSiteAnalytics: { method: 'GET', path: '/analytics', query: [] },
+  reportClientError: { method: 'POST', path: '/client-log', query: [] },
+  recordGameEvent: { method: 'POST', path: '/games/:slug/events', query: [] },
+  getGameAnalytics: { method: 'GET', path: '/games/:slug/analytics', query: [] },
+  getSocialConfig: { method: 'GET', path: '/social/config', query: [] },
+  getOnlineCounts: { method: 'GET', path: '/social/counts', query: [] },
+  getMySocialProfile: { method: 'GET', path: '/social/me', query: [] },
+  listFriendsAndRequests: { method: 'GET', path: '/social/friends', query: [] },
+  findPlayerByName: { method: 'GET', path: '/social/players/by-name/:name', query: [] },
+  getPlayerCard: { method: 'GET', path: '/social/players/:id', query: [] },
+  updateMySocialProfile: { method: 'PUT', path: '/social/me', query: [] },
+  setParentChatLock: { method: 'POST', path: '/social/chat-lock', query: [] },
+  sendFriendRequest: { method: 'POST', path: '/social/friends', query: [] },
+  acceptFriendRequest: { method: 'POST', path: '/social/friends/:id/accept', query: [] },
+  declineFriendRequest: { method: 'POST', path: '/social/friends/:id/decline', query: [] },
+  removeFriend: { method: 'DELETE', path: '/social/friends/:id', query: [] },
+  setFriendNotifications: { method: 'PUT', path: '/social/friends/:id/notify', query: [] },
+  blockPlayer: { method: 'POST', path: '/social/blocks', query: [] },
+  unblockPlayer: { method: 'DELETE', path: '/social/blocks/:id', query: [] },
+  listRecentPlayers: { method: 'GET', path: '/social/recent', query: [] },
+  listConversations: { method: 'GET', path: '/social/conversations', query: [] },
+  listDirectMessages: { method: 'GET', path: '/social/messages/:userId', query: ['before'] },
+  sendDirectMessage: { method: 'POST', path: '/social/messages/:userId', query: [] },
+  markDirectMessagesRead: { method: 'POST', path: '/social/messages/:userId/read', query: [] },
+  getNotificationPreferences: { method: 'GET', path: '/social/notify', query: [] },
+  unsubscribeFromPush: { method: 'DELETE', path: '/social/push', query: [] },
+  setNotificationPreferences: { method: 'PUT', path: '/social/notify', query: [] },
+  subscribeToPush: { method: 'POST', path: '/social/push', query: [] },
+  fileReport: { method: 'POST', path: '/social/reports', query: [] },
+  listPublicSuggestions: { method: 'GET', path: '/suggestions', query: ['sort'] },
+  submitSuggestion: { method: 'POST', path: '/suggestions', query: [] },
+  voteForSuggestion: { method: 'POST', path: '/suggestions/:id/vote', query: [] },
+  removeSuggestionVote: { method: 'DELETE', path: '/suggestions/:id/vote', query: [] },
+  withdrawSuggestion: { method: 'DELETE', path: '/suggestions/:id', query: [] },
+  sendGameInvite: { method: 'POST', path: '/mp/invites', query: [] },
+  acceptGameInvite: { method: 'POST', path: '/mp/invites/:id/accept', query: [] },
+  declineGameInvite: { method: 'POST', path: '/mp/invites/:id/decline', query: [] },
+  cancelGameInvite: { method: 'DELETE', path: '/mp/invites/:id', query: [] },
+  redeemLaunchToken: { method: 'GET', path: '/mp/launch/:token', query: [] },
+  setPartyJoinInfo: { method: 'POST', path: '/mp/parties/:id/join-info', query: [] },
+  leaveParty: { method: 'POST', path: '/mp/parties/:id/leave', query: [] },
+  launchIntoFriendsRoom: { method: 'POST', path: '/mp/join', query: [] },
+  getGameServerTicket: { method: 'POST', path: '/mp/ticket', query: [] },
+  listMyRaceHistory: { method: 'GET', path: '/race/history', query: ['game', 'with', 'before', 'limit'] },
+  getHubVersion: { method: 'GET', path: '/version', query: [] },
+} as const;

package/src/core/storage/json-guards.ts

@@ -0,0 +1,74 @@
+/**
+ * Small type guards for values this client did not create: JSON read back
+ * from `localStorage`, error bodies, objects from other bundles. The browser
+ * client carries no zod (plan D16), so these replace schema parsing on the
+ * few shapes it reads.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+
+/** A plain object's fields, not yet checked. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the fields of a value read from storage or another bundle
+export type UncheckedRecord = Readonly<Record<string, unknown>>;
+
+/** Whether `candidate` is a non-null, non-array object. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage or another bundle
+export function isRecord(candidate: unknown): candidate is UncheckedRecord {
+  return typeof candidate === 'object' && candidate !== null && !Array.isArray(candidate);
+}
+
+/** `candidate` when it is a string, else `undefined`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
+export function optionalString(candidate: unknown): string | undefined {
+  return typeof candidate === 'string' ? candidate : undefined;
+}
+
+/** `candidate` when it is a finite number, else `undefined`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
+export function optionalNumber(candidate: unknown): number | undefined {
+  return typeof candidate === 'number' && Number.isFinite(candidate) ? candidate : undefined;
+}
+
+/** Whether `candidate` is a string or `null`. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: one field of an unchecked record
+export function isNullableString(candidate: unknown): candidate is string | null {
+  return candidate === null || typeof candidate === 'string';
+}
+
+/** Whether `candidate` is a JSON value (what `JSON.parse` can return). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage
+export function isJson(candidate: unknown): candidate is Json {
+  if (candidate === null || typeof candidate === 'string' || typeof candidate === 'boolean') {
+    return true;
+  }
+  if (typeof candidate === 'number') {
+    return Number.isFinite(candidate);
+  }
+  if (Array.isArray(candidate)) {
+    return candidate.every(isJson);
+  }
+  return isRecord(candidate) && Object.values(candidate).every(isJson);
+}
+
+/** Whether `candidate` is an object whose every value is a finite number. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: checks a value read from storage
+export function isNumberRecord(candidate: unknown): candidate is Readonly<Record<string, number>> {
+  return isRecord(candidate) && Object.values(candidate).every((entry) => optionalNumber(entry) !== undefined);
+}
+
+/** The strings in `candidate`, or an empty list when it is not an array. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a list read from storage
+export function stringsIn(candidate: unknown): string[] {
+  return Array.isArray(candidate) ? candidate.filter((entry): entry is string => typeof entry === 'string') : [];
+}
+
+/** Parse JSON text without throwing: `undefined` when it is not JSON. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: text read from storage, checked by the caller's guard next
+export function parseJsonText(text: string): unknown {
+  try {
+    // eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON.parse's result, checked by the caller's guard next
+    const parsed: unknown = JSON.parse(text);
+    return parsed;
+  } catch {
+    return undefined;
+  }
+}

package/src/core/storage/key-value.ts

@@ -0,0 +1,66 @@
+/**
+ * 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. */
+export 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[];
+}
+
+/** A store backed by a `Storage` (`localStorage`). */
+function storageBacked(storage: Storage): KeyValueStore {
+  return {
+    read: (key) => storage.getItem(key),
+    write: (key, text) => {
+      try {
+        storage.setItem(key, text);
+      } catch {
+        // A full or blocked storage loses the write, as in v1.
+      }
+    },
+    remove: (key) => {
+      storage.removeItem(key);
+    },
+    keys: () => Object.keys(storage),
+  };
+}
+
+/** A store held in memory for this page only. */
+export function createMemoryStore(): KeyValueStore {
+  const entries = new Map<string, string>();
+  return {
+    read: (key) => entries.get(key) ?? null,
+    write: (key, text) => {
+      entries.set(key, text);
+    },
+    remove: (key) => {
+      entries.delete(key);
+    },
+    keys: () => [...entries.keys()],
+  };
+}
+
+/** The page's `localStorage`, or `undefined` when it is missing or throws (privacy mode). */
+function pageStorage(): Storage | undefined {
+  try {
+    return typeof localStorage === 'undefined' ? undefined : localStorage;
+  } catch {
+    return undefined;
+  }
+}
+
+/** `localStorage` when available, else a fresh in-memory store. */
+export function createPageStore(): KeyValueStore {
+  const storage = pageStorage();
+  return storage === undefined ? createMemoryStore() : storageBacked(storage);
+}