@mentra/cloud-client 0.1.0-beta.0

package/src/client.ts

@@ -0,0 +1,256 @@
+/**
+ * @fileoverview The top-level `CloudClient`: wiring only, no behavior.
+ *
+ * `new CloudClient(config)` resolves the server addresses (proxy-aware), builds
+ * the shared REST helpers, and constructs the three modules in dependency order
+ * (auth first, since runtime and core both pull their Bearer through it). All the
+ * actual logic lives in the modules under `./modules/**`; this file just hands
+ * each one its dependencies and exposes the three modules as readonly fields.
+ *
+ * It also owns the two cross-cutting concerns the design says belong in one
+ * place: the logger (so a host has a single hook for every module's logs) and the
+ * reconnect/backoff settings (so the live socket's timing is tuned here, not
+ * scattered across the runtime internals).
+ *
+ * See docs/issues/004-cloud-client/design.md ("The top-level CloudClient").
+ */
+import { noopLogger } from "./logger";
+import type { Logger } from "./logger";
+import type { CloudClientConfig } from "./config";
+import { createHttpClient } from "./http";
+import { CloudClientError } from "./errors";
+import type { ConnectionInit } from "@mentra/cloud-protocol";
+
+// The module implementations. Each is owned by another agent under ./modules/**;
+// this file only constructs them, matching the constructor signatures fixed in
+// design.md exactly.
+import { Auth } from "./modules/auth/auth";
+import { TokenStore } from "./modules/auth/token-store";
+import { Runtime } from "./modules/runtime/runtime";
+import { Connection } from "./modules/runtime/connection";
+import { RuntimeEmitter } from "./modules/runtime/emitter";
+import { Subscriptions } from "./modules/runtime/subscriptions";
+import { Camera } from "./modules/runtime/camera";
+import { Maps } from "./modules/runtime/maps";
+import { Tts } from "./modules/runtime/tts";
+import { UdpAudio } from "./modules/runtime/audio-udp";
+import { Core } from "./modules/core/core";
+
+/**
+ * Default reconnect/backoff for the live socket when a host supplies none.
+ *
+ * Half-second base, capped at five seconds, with jitter on. The small cap is
+ * deliberate: the socket should recover within a few seconds of the cloud
+ * coming back (a routine runtime redeploy is a ~30-60s blip), not sit on a long
+ * backoff. Full jitter still keeps a fleet of phones from reconnecting in
+ * lockstep after a shared blip. A host can override any of these through
+ * `config.reconnect`.
+ */
+const DEFAULT_RECONNECT = { baseMs: 500, maxMs: 5_000, jitter: true };
+
+/**
+ * The default audio codec the client announces in the handshake.
+ *
+ * LC3 at 16 kHz matches the glasses' on-device codec, so the cloud transcribes
+ * the same bytes the device captures. A future config knob can override this; for
+ * now the handshake announces the device default so audio that starts immediately
+ * after connect is decoded correctly.
+ */
+const DEFAULT_AUDIO_CODEC = "pcm" as const;
+const DEFAULT_AUDIO_SAMPLE_RATE = 16_000;
+
+/**
+ * The protocol semver this client build speaks, announced in `connection.init`.
+ *
+ * Hardcoded to the 2.x line this package targets; bumped here when the client
+ * starts speaking a newer protocol build, so there is one place to change it.
+ */
+const PROTOCOL_VERSION = "2.0.0";
+
+/**
+ * Rewrite a base URL to route through a proxy host while preserving its path.
+ *
+ * When a host sets `endpoints.proxy`, both the core and runtime addresses go
+ * through that one host (for example a dev-stack tunnel or a debugging relay). We
+ * swap only the origin (scheme + host + port) and keep the original path, so a
+ * core/runtime address that carries a path prefix is not lost when proxied.
+ */
+function rewriteThroughProxy(target: string, proxy: string): string {
+  const proxyUrl = new URL(proxy);
+  const targetUrl = new URL(target);
+  // Keep the target's path/query, take the proxy's origin.
+  targetUrl.protocol = proxyUrl.protocol;
+  targetUrl.host = proxyUrl.host;
+  return targetUrl.toString();
+}
+
+/**
+ * Derive the runtime WebSocket URL from its HTTP base.
+ *
+ * `endpoints.runtime` is the HTTP origin the REST calls use; the live session
+ * rides a WebSocket at the runtime's `/ws/session` path. So we swap the scheme
+ * (http -> ws, https -> wss) and append that path. Keeping this here (not in the
+ * Connection) means the Connection stays transport-URL-agnostic and the one
+ * place that knows the runtime's HTTP shape also derives its socket URL.
+ */
+function toRuntimeWsUrl(httpBase: string): string {
+  const u = new URL(httpBase);
+  u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
+  u.pathname = `${u.pathname.replace(/\/$/, "")}/ws/session`;
+  return u.toString();
+}
+
+export class CloudClient {
+  // Typed as the concrete module classes rather than separate `AuthModule` /
+  // `RuntimeModule` / `CoreModule` interfaces: each class IS the implementation
+  // of its public contract (per design.md), so a host gets the full, typed
+  // surface (`cloud.auth.getRuntimeToken()`, etc.) straight off these fields with
+  // no parallel interface to keep in sync.
+  readonly auth: Auth;
+  readonly runtime: Runtime;
+  readonly core?: Core;
+
+  constructor(config: CloudClientConfig) {
+    // One logger for the whole client, so a host routes every module's logs in
+    // one place. Default to the silent no-op so we never print uninvited.
+    const logger: Logger = config.logger ?? noopLogger;
+
+    // Reconnect/backoff lives here so the socket's timing is tuned in one spot.
+    const reconnect = config.reconnect ?? DEFAULT_RECONNECT;
+
+    // Resolve the two base addresses. With a proxy set, both route through it;
+    // without one, each module talks to its own service directly.
+    const { core: coreBase, runtime: runtimeBase, proxy } = config.endpoints;
+    const coreUrl = coreBase ? (proxy ? rewriteThroughProxy(coreBase, proxy) : coreBase) : undefined;
+    const runtimeUrl = proxy ? rewriteThroughProxy(runtimeBase, proxy) : runtimeBase;
+
+    if (config.auth.core && !coreUrl) {
+      throw new CloudClientError("auth.core requires endpoints.core");
+    }
+
+    // Runtime auth is the mandatory half (Core is optional). Guard it before the
+    // `in` check below so a caller passing the pre-split flat `auth` shape
+    // (`{ subjectToken, subjectTokenType }`, no `runtime`) gets a clear
+    // configuration error instead of an opaque `TypeError` from `"source" in undefined`.
+    if (!config.auth.runtime) {
+      throw new CloudClientError("auth.runtime is required (got a pre-split/flat auth config?)");
+    }
+
+    const runtimeUsesCore = "source" in config.auth.runtime && config.auth.runtime.source === "core";
+    if (runtimeUsesCore && (!coreUrl || !config.auth.core)) {
+      throw new CloudClientError("auth.runtime.source='core' requires endpoints.core and auth.core");
+    }
+
+    // Build auth FIRST: runtime and core both source their Bearer from it, so it
+    // has to exist before their HTTP helpers can reference token providers.
+    //
+    // Auth's own HTTP helper has no default token source: its `/exchange` and
+    // `/refresh` calls present the subject and refresh tokens via `opts.bearer`,
+    // before any access token exists. It is deliberately Core-only: runtime-only
+    // clients never get a fallback that points Core/Auth calls at Runtime.
+    const authHttp = coreUrl
+      ? createHttpClient({ baseUrl: coreUrl, logger, fetch: config.transports.http })
+      : undefined;
+    const store = new TokenStore({ storage: config.transports.storage });
+    const auth = new Auth({
+      http: authHttp,
+      store,
+      config: config.auth,
+      logger,
+      // Form-encoded `/exchange` and `/refresh` calls are not JSON HttpClient
+      // requests, but still use the host's injected HTTP transport.
+      baseUrl: coreUrl,
+      fetch: config.transports.http,
+    });
+
+    const getRuntimeToken = (): Promise<string> => auth.getRuntimeToken();
+    const getCoreToken = (): Promise<string> => auth.getCoreToken();
+
+    const coreHttp =
+      coreUrl && config.auth.core
+        ? createHttpClient({
+            baseUrl: coreUrl,
+            getToken: getCoreToken,
+            logger,
+            fetch: config.transports.http,
+          })
+        : null;
+    const runtimeHttp = createHttpClient({
+      baseUrl: runtimeUrl,
+      getToken: getRuntimeToken,
+      logger,
+      fetch: config.transports.http,
+    });
+
+    const emitter = new RuntimeEmitter();
+    const subscriptions = new Subscriptions({ http: runtimeHttp });
+
+    // The handshake payload the connection sends on every (re)open. It is a
+    // factory (not a fixed value) so each reconnect re-reads the current defaults
+    // rather than reusing a stale snapshot. The token is omitted here: the
+    // connection attaches the live access token itself via `getToken`, so the
+    // payload never carries a credential that could go stale between reopens.
+    //
+    // `initialSubscriptions` carries the LIVE subscription set on every reopen so
+    // the cloud seeds the new session's subscription key non-empty at handshake.
+    // Without this a reconnect's new (stateless) cloud session starts with an
+    // empty set and depends entirely on the follow-up REST resend's control-stream
+    // nudge — which the new owner pod's just-created `$`-positioned consumer group
+    // can miss, leaving the session with audio but no transcription provider. By
+    // riding the set in `connection.init`, the seed + the cloud's in-process
+    // post-seed reconcile (which reads the key directly, not the stream) brings
+    // providers up atomically with the session. On the very first connect the set
+    // is empty (no `set()` has run yet) and the first `setSubscriptions` REST call
+    // applies it; on every reconnect it is the live set.
+    const initPayload = (): ConnectionInit => ({
+      protocolVersion: PROTOCOL_VERSION,
+      audio: {
+        codec: config.audio?.codec ?? DEFAULT_AUDIO_CODEC,
+        sampleRate: config.audio?.sampleRate ?? DEFAULT_AUDIO_SAMPLE_RATE,
+        // Only LC3 carries a frame size; the config type forces LC3 hosts to
+        // state theirs explicitly (decoder is sized from this — no safe guess).
+        ...(config.audio?.codec === "lc3" ? { frameSizeBytes: config.audio.frameSizeBytes } : {}),
+        initialSubscriptions: subscriptions.currentSet(),
+      },
+    });
+
+    // Build the remaining runtime pieces, then the runtime that orchestrates them.
+    const connection = new Connection({
+      ws: config.transports.ws,
+      url: toRuntimeWsUrl(runtimeUrl),
+      getToken: getRuntimeToken,
+      initPayload,
+      reconnect,
+      onAuthRejected: async () => {
+        await auth.getRuntimeToken({ forceRefresh: true });
+      },
+      logger,
+    });
+    const camera = new Camera({ http: runtimeHttp });
+    const tts = new Tts({ http: runtimeHttp });
+    const maps = new Maps({ http: runtimeHttp });
+    const audio = new UdpAudio({ udp: config.transports.udp });
+
+    const runtime = new Runtime({
+      connection,
+      emitter,
+      subscriptions,
+      camera,
+      tts,
+      maps,
+      audio,
+      logger,
+      // On a fatal AUTH_EXPIRED at handshake, runtime forces auth to drop its
+      // cached access token and refresh; the connection then re-reads the fresh
+      // token via getRuntimeToken on the reopen.
+      forceRefreshToken: () => auth.getRuntimeToken({ forceRefresh: true }),
+    });
+
+    // Core is last: stateless REST on the core service, Bearer from auth.
+    const core = coreHttp ? new Core({ http: coreHttp }) : undefined;
+
+    this.auth = auth;
+    this.runtime = runtime;
+    this.core = core;
+  }
+}

package/src/config.ts

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview The config you pass to `new CloudClient(...)`.
+ *
+ * This is the public construction contract. The platform-specific wrappers
+ * (`react-native`, `node`) supply `transports` for you, so a host using one of
+ * those imports passes everything here except `transports`.
+ *
+ * See docs/issues/004-cloud-client/spec.md ("Construction") and design.md.
+ */
+import type { Logger } from "./logger";
+import type { CloudClientTransports } from "./transports";
+
+/**
+ * The full shape passed to the root `CloudClient`.
+ *
+ * `endpoints.proxy`, when set, rewrites BOTH the core and runtime addresses to
+ * route through one host. We keep it as a single optional field (rather than two
+ * pre-rewritten URLs) so a host configures the proxy in one place and cannot get
+ * the two halves out of sync.
+ */
+export interface CloudClientConfig {
+  // `core` is optional only for runtime-only deployments. If `auth.core` is set,
+  // or if `auth.runtime.source` is `"core"`, this must be present; Core/Auth
+  // calls are never routed to Runtime.
+  endpoints: { core?: string; runtime: string; proxy?: string };
+  auth: AuthConfig;
+  transports: CloudClientTransports;
+  logger?: Logger;
+  // backoff tuning for the live socket; one place so a host can match its fleet
+  reconnect?: { baseMs: number; maxMs: number; jitter: boolean };
+  /**
+   * Audio format announced in `connection.init`. Defaults to PCM at 16 kHz when
+   * omitted. An LC3 host MUST pass the frame size its encoder emits — the
+   * runtime sizes its decoder from this field, and phone builds legitimately
+   * differ (20/40/60); there is no safe default, so the type requires it.
+   */
+  audio?:
+    | { codec: "pcm"; sampleRate?: number }
+    | { codec: "lc3"; sampleRate?: number; frameSizeBytes: 20 | 40 | 60 };
+}
+
+/**
+ * Which kind of subject token the host is exchanging for a Mentra access token.
+ *
+ * The cloud's `/exchange` endpoint needs to know how to verify the incoming
+ * token, so the type travels alongside the token itself.
+ */
+export type SubjectTokenType = "oem-jwt" | "mentra-core" | "supabase";
+
+/**
+ * The three ways a host can give the client its credentials.
+ *
+ * The variants exist so a host hands over only what it has: a raw subject token
+ * to exchange once, a callback that fetches one on demand (for tokens that
+ * themselves expire), or an already-exchanged access/refresh pair (for example
+ * restored from secure storage on relaunch).
+ */
+export type CoreAuthConfig =
+  // exchanged once on first use
+  | { subjectToken: string; subjectTokenType: SubjectTokenType }
+  // fetched on demand, for subject tokens that expire before exchange
+  | { getSubjectToken: () => Promise<{ token: string; type: SubjectTokenType }> }
+  // already exchanged, skip straight to refresh
+  | { accessToken: string; refreshToken: string };
+
+export type RuntimeAuthConfig =
+  | {
+      /**
+       * Ask Cloud Core/Auth to mint a short-lived `cloud-runtime` token. This is
+       * explicit hosted-Core mode, not an implicit Core-token fallback.
+       */
+      source: "core";
+    }
+  | {
+      /** Host/OEM/local-dev supplied runtime-token provider. */
+      getToken(opts?: { forceRefresh?: boolean }): Promise<string>;
+    };
+
+export interface AuthConfig {
+  // Core-backed auth owns identity, Core token exchange/refresh, miniapp token
+  // minting, and miniapp auto-auth. Omit only for true runtime-only deployments.
+  core?: CoreAuthConfig;
+  runtime: RuntimeAuthConfig;
+}

package/src/errors.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview The client-side error types every module throws.
+ *
+ * These are distinct from the protocol's `ProtocolError` (which is a wire
+ * payload from the cloud). These are JS errors thrown locally so a host can
+ * branch with `instanceof` instead of string-matching messages.
+ *
+ * See docs/issues/004-cloud-client/design.md.
+ */
+
+/** Base class so a host can catch every cloud-client error with one check. */
+export class CloudClientError extends Error {
+  constructor(message: string) {
+    super(message);
+    // Without this, `instanceof` checks fail once the code is transpiled down to
+    // ES5-class semantics, since the prototype chain gets reset by `super`.
+    this.name = "CloudClientError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * A non-2xx HTTP response from a REST call.
+ *
+ * `status` is the HTTP status so a caller can branch (for example a 401 triggers
+ * one refresh-and-retry). `code` is the optional machine-readable error code the
+ * cloud puts in the JSON body, when present, for finer branching than status
+ * alone allows.
+ */
+export class HttpError extends CloudClientError {
+  status!: number;
+  code?: string;
+
+  constructor(message: string, status: number, code?: string) {
+    super(message);
+    this.name = "HttpError";
+    this.status = status;
+    this.code = code;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+/**
+ * Thrown when a token refresh fails and the host must send the user back through
+ * login. Separate from `HttpError` so a host can catch the "credentials are
+ * truly dead" case on its own without inspecting status codes.
+ */
+export class AuthExpiredError extends CloudClientError {
+  constructor(message = "Authentication expired; re-auth required") {
+    super(message);
+    this.name = "AuthExpiredError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/http.ts

@@ -0,0 +1,259 @@
+/**
+ * @fileoverview The one REST helper every module uses.
+ *
+ * Centralizing REST here keeps behavior consistent across auth, runtime, and
+ * core: one place builds the URL, attaches the Bearer header, parses JSON, maps
+ * a non-2xx response to a typed `HttpError`, and retries only safe (idempotent)
+ * calls on a transient failure. Modules never call `fetch` directly, so none of
+ * them can drift on error handling or auth headers.
+ *
+ * Uses the global `fetch`, which exists on both a modern phone and a modern
+ * server, so REST needs no platform input (unlike sockets and storage).
+ *
+ * See docs/issues/004-cloud-client/design.md ("The shared HTTP helper").
+ */
+import { HttpError } from "./errors";
+import type { Logger } from "./logger";
+import type { HttpTransport } from "./transports";
+
+/**
+ * Per-request options.
+ *
+ * `bearer` overrides the default token source for this one call: the `/exchange`
+ * call presents the subject token instead of an access token, and `/refresh`
+ * presents the refresh token, so they pass `bearer` explicitly rather than going
+ * through `cloud.auth`.
+ *
+ * `idempotent` marks a call as safe to retry on a transient network error. GET
+ * is always treated as idempotent; the full-replace PUT opts in via this flag.
+ * POST is never retried by default because it may not be safe to repeat.
+ */
+export interface ReqOpts {
+  bearer?: string;
+  idempotent?: boolean;
+}
+
+/** The REST surface the modules consume. */
+export interface HttpClient {
+  get<T>(path: string, opts?: ReqOpts): Promise<T>;
+  head(path: string, opts?: ReqOpts): Promise<Response>;
+  post<T>(path: string, body?: unknown, opts?: ReqOpts): Promise<T>;
+  postForm<T>(path: string, form: FormData, opts?: ReqOpts): Promise<T>;
+  put<T>(path: string, body: unknown, opts?: ReqOpts): Promise<T>;
+  delete<T>(path: string, opts?: ReqOpts): Promise<T>;
+  url(path: string): string;
+}
+
+/**
+ * Dependencies for the helper.
+ *
+ * `getToken` is the default Bearer source (for example
+ * `cloud.auth.getRuntimeToken` or `cloud.auth.getCoreToken`).
+ * It is optional because the auth module's own `/exchange` and `/refresh` calls
+ * run before any access token exists; those calls pass `opts.bearer` directly.
+ */
+export interface CreateHttpClientDeps {
+  baseUrl: string;
+  // default Bearer source, usually cloud.auth.getRuntimeToken/getCoreToken
+  getToken?: () => Promise<string>;
+  logger: Logger;
+  fetch?: HttpTransport;
+}
+
+/** How many times to retry a transient failure on an idempotent call. */
+const MAX_RETRIES = 2;
+/** Base backoff in milliseconds; doubles per attempt (250, 500, ...). */
+const RETRY_BASE_MS = 250;
+
+/** Resolve after `ms`, used for retry backoff. */
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Join a base URL and a path without producing a double slash or dropping one.
+ *
+ * Done by hand (not `new URL`) so a `baseUrl` that already carries a path prefix
+ * (for example a proxy mount point) is preserved rather than discarded.
+ */
+function joinUrl(baseUrl: string, path: string): string {
+  const base = baseUrl.replace(/\/+$/, "");
+  const suffix = path.replace(/^\/+/, "");
+  return `${base}/${suffix}`;
+}
+
+export function createHttpClient(deps: CreateHttpClientDeps): HttpClient {
+  const { baseUrl, getToken, logger } = deps;
+  const executeFetch = deps.fetch ?? globalThis.fetch;
+
+  /**
+   * Resolve the Bearer to attach: a per-call override wins, otherwise the
+   * default token source. We never log the resolved token: tokens stay out of
+   * logs everywhere in this library.
+   */
+  async function resolveBearer(opts?: ReqOpts): Promise<string | undefined> {
+    if (opts?.bearer) return opts.bearer;
+    if (getToken) return await getToken();
+    return undefined;
+  }
+
+  /**
+   * The one retry loop behind every request shape (JSON, form, bodyless).
+   *
+   * A network-level failure (DNS, reset, timeout) is transient and worth a
+   * retry on an idempotent call. A non-2xx response is NOT transient here: it is
+   * a definite answer from the server, mapped to an `HttpError` for the caller
+   * to branch on (auth handles its own 401 refresh-and-retry a layer up).
+   * The thrown exhaustion error keeps the network-error detail out of its
+   * message to avoid leaking anything host-specific into a string a host might
+   * surface to a user.
+   */
+  async function fetchWithRetry(args: {
+    method: "GET" | "POST" | "PUT" | "DELETE" | "HEAD";
+    path: string;
+    headers: Record<string, string>;
+    body: string | FormData | undefined;
+    idempotent: boolean;
+  }): Promise<Response> {
+    const { method, path, headers, body, idempotent } = args;
+    const url = joinUrl(baseUrl, path);
+
+    for (let attempt = 0; attempt <= (idempotent ? MAX_RETRIES : 0); attempt++) {
+      if (attempt > 0) {
+        const backoff = RETRY_BASE_MS * 2 ** (attempt - 1);
+        logger.debug("http retrying request", { method, path, attempt });
+        await delay(backoff);
+      }
+
+      let res: Response;
+      try {
+        res = await executeFetch(url, { method, headers, body });
+      } catch {
+        // Transient network failure: let the loop retry.
+        logger.warn("http network error", { method, path, attempt });
+        continue;
+      }
+
+      if (!res.ok) {
+        // Definite answer from the server: map to a typed error, no retry.
+        throw await toHttpError(res, method, path);
+      }
+
+      return res;
+    }
+
+    // Exhausted retries on a transient failure.
+    throw new HttpError(`Network request failed: ${method} ${path}`, 0, "NETWORK_ERROR");
+  }
+
+  async function requestRaw(
+    method: "GET" | "POST" | "PUT" | "DELETE" | "HEAD",
+    path: string,
+    body: unknown,
+    opts?: ReqOpts,
+  ): Promise<Response> {
+    const bearer = await resolveBearer(opts);
+
+    const headers: Record<string, string> = {};
+    if (bearer) headers["Authorization"] = `Bearer ${bearer}`;
+
+    let payload: string | undefined;
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+      payload = JSON.stringify(body);
+    }
+
+    // GET and DELETE are idempotent by HTTP semantics, so safe to retry; other
+    // verbs opt in via the flag.
+    const idempotent = opts?.idempotent ?? (method === "GET" || method === "DELETE" || method === "HEAD");
+
+    return await fetchWithRetry({ method, path, headers, body: payload, idempotent });
+  }
+
+  async function request<T>(
+    method: "GET" | "POST" | "PUT" | "DELETE",
+    path: string,
+    body: unknown,
+    opts?: ReqOpts,
+  ): Promise<T> {
+    const res = await requestRaw(method, path, body, opts);
+    return await parseJson<T>(res);
+  }
+
+  async function requestForm<T>(path: string, form: FormData, opts?: ReqOpts): Promise<T> {
+    const bearer = await resolveBearer(opts);
+
+    // No Content-Type here: fetch/FormData must generate the multipart
+    // boundary. POST is not idempotent, so retries stay opt-in.
+    const headers: Record<string, string> = {};
+    if (bearer) headers["Authorization"] = `Bearer ${bearer}`;
+
+    const res = await fetchWithRetry({
+      method: "POST",
+      path,
+      headers,
+      body: form,
+      idempotent: opts?.idempotent ?? false,
+    });
+    return await parseJson<T>(res);
+  }
+
+  /**
+   * Turn a non-2xx response into an `HttpError`, reading a machine-readable
+   * `code` from the JSON body when the server provides one. We swallow any body
+   * parse failure here because the status is the load-bearing signal and we do
+   * not want a malformed error body to mask the real status.
+   */
+  async function toHttpError(res: Response, method: string, path: string): Promise<HttpError> {
+    let code: string | undefined;
+    let detail = "";
+    try {
+      const data = (await res.json()) as {
+        code?: string;
+        message?: string;
+        error?: string;
+        error_description?: string;
+      };
+      code = data?.code ?? data?.error;
+      const message = data?.message ?? data?.error_description;
+      detail = message ? `: ${message}` : "";
+    } catch {
+      // No JSON body, or unparseable: fall back to status alone.
+    }
+    return new HttpError(`HTTP ${res.status} on ${method} ${path}${detail}`, res.status, code);
+  }
+
+  /**
+   * Parse a successful response as JSON, tolerating an empty body (a 204 or an
+   * endpoint that returns nothing) by resolving to `undefined`.
+   */
+  async function parseJson<T>(res: Response): Promise<T> {
+    const text = await res.text();
+    if (text.length === 0) return undefined as T;
+    return JSON.parse(text) as T;
+  }
+
+  return {
+    get<T>(path: string, opts?: ReqOpts): Promise<T> {
+      return request<T>("GET", path, undefined, opts);
+    },
+    head(path: string, opts?: ReqOpts): Promise<Response> {
+      return requestRaw("HEAD", path, undefined, opts);
+    },
+    post<T>(path: string, body?: unknown, opts?: ReqOpts): Promise<T> {
+      return request<T>("POST", path, body, opts);
+    },
+    postForm<T>(path: string, form: FormData, opts?: ReqOpts): Promise<T> {
+      return requestForm<T>(path, form, opts);
+    },
+    put<T>(path: string, body: unknown, opts?: ReqOpts): Promise<T> {
+      return request<T>("PUT", path, body, opts);
+    },
+    delete<T>(path: string, opts?: ReqOpts): Promise<T> {
+      return request<T>("DELETE", path, undefined, opts);
+    },
+    url(path: string): string {
+      return joinUrl(baseUrl, path);
+    },
+  };
+}