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

package/src/core/page.ts

@@ -1,74 +1,87 @@
-/**
- * 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.
-  }
-}
+/**
+ * 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 display title: the host's injected one, else the page's `<title>`, else `fallback`. */
+export function detectGameTitle(fallback: string): string {
+  const injected = isBrowserPage() && isRecord(window.__HUB__) ? optionalString(window.__HUB__.title) : undefined;
+  if (injected !== undefined && injected !== '') {
+    return injected;
+  }
+  const pageTitle = typeof document === 'undefined' ? '' : document.title.trim();
+  return pageTitle === '' ? fallback : pageTitle;
+}
+
+/** The game's slug: the injected one; `null` on an injected site page (the catalog, `/world`); else the first path segment. */
+export function detectSlug(): string | null {
+  const injectedSlug = injectedConfig().slug;
+  if (injectedSlug !== undefined && injectedSlug !== '') {
+    return injectedSlug;
+  }
+  if (isHubInjectedPage()) {
+    return null;
+  }
+  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

@@ -1,22 +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]>>>;
+/**
+ * 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

@@ -1,152 +1,163 @@
-/**
- * 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]),
-  };
-}
+/**
+ * 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 { OFFLINE_OP_HEADER, 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>>;
+  /**
+   * Call an endpoint as part of an offline operation: an endpoint marked for
+   * offline replay gets `opKey` in the operation header, so the hub runs it
+   * once however often it is sent; any other endpoint is called as usual.
+   */
+  callOnce<K extends EndpointName>(opKey: string, 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, opKey?: string): 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,
+          ...(opKey !== undefined && ROUTES[name].offline === 'replay' ? { [OFFLINE_OP_HEADER]: opKey } : {}),
+        },
+        ...(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]),
+    callOnce: (opKey, name, ...fieldsArgument) => send(name, fieldsArgument[0], opKey),
+  };
+}