@topolo/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,376 @@
+// src/auth.ts
+function applyAuthHeaders(headers, credential) {
+  if (credential.kind === "api_key") {
+    headers.set("X-Api-Key", credential.apiKey);
+    return;
+  }
+  headers.set("Authorization", `Bearer ${credential.accessToken}`);
+}
+function applyAuditHeaders(headers, agent, requestId) {
+  headers.set("X-Topolo-Client", `${agent.clientName}/${agent.clientVersion}`);
+  if (agent.agentName) headers.set("X-Topolo-Agent", agent.agentName);
+  headers.set("X-Topolo-Request-Id", requestId);
+}
+function generateRequestId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+// src/errors.ts
+var TopoloSdkError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "TopoloSdkError";
+    this.code = code;
+  }
+};
+var TopoloAuthError = class extends TopoloSdkError {
+  constructor(message, code = "auth_error") {
+    super(code, message);
+    this.name = "TopoloAuthError";
+  }
+};
+var TopoloPermissionError = class extends TopoloSdkError {
+  required;
+  constructor(message, required) {
+    super("permission_denied", message);
+    this.name = "TopoloPermissionError";
+    this.required = required;
+  }
+};
+var TopoloHttpError = class extends TopoloSdkError {
+  status;
+  body;
+  service;
+  path;
+  constructor(service, path, status, body, message) {
+    super("http_error", message ?? `HTTP ${status} from ${service}${path}`);
+    this.name = "TopoloHttpError";
+    this.status = status;
+    this.body = body;
+    this.service = service;
+    this.path = path;
+  }
+};
+
+// src/services.ts
+var DEFAULT_SERVICE_URLS = {
+  auth: "https://auth.topolo.app",
+  crm: "https://topolo-crm-worker.topolo.workers.dev"
+};
+var PLATFORM_SERVICE_IDS = {
+  crm: "srv_iCwM4jGXcwlj"
+};
+function resolveServiceUrl(service, overrides) {
+  const override = overrides?.[service];
+  if (override) return override;
+  const envKey = `TOPOLO_SERVICE_URL_${service.toUpperCase()}`;
+  const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
+  if (envValue) return envValue;
+  return DEFAULT_SERVICE_URLS[service];
+}
+
+// src/client.ts
+var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+var TopoloClient = class {
+  credential;
+  agent;
+  serviceUrls;
+  requireConfirmForWrites;
+  timeoutMs;
+  fetchImpl;
+  constructor(options) {
+    if (!options.credential) throw new TopoloAuthError("credential is required");
+    if (!options.agent?.clientName) throw new TopoloAuthError("agent.clientName is required");
+    this.credential = options.credential;
+    this.agent = options.agent;
+    this.serviceUrls = options.serviceUrls;
+    this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
+    this.timeoutMs = options.timeoutMs ?? 3e4;
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  /**
+   * Low-level JSON request. Prefer the typed module helpers (identity, crm, ...)
+   * for anything a caller would reach for; this stays exported for escape-hatch
+   * use and for the generic `topolo api` / MCP passthrough tool.
+   */
+  async request(opts) {
+    const method = opts.method ?? "GET";
+    if (this.requireConfirmForWrites && WRITE_METHODS.has(method) && !opts.confirm) {
+      throw new TopoloAuthError(
+        `Mutating ${method} requests require { confirm: true }. This guardrail prevents agents from issuing writes without an explicit human-in-the-loop acknowledgement.`
+      );
+    }
+    const baseUrl = resolveServiceUrl(opts.service, this.serviceUrls);
+    const url = new URL(opts.path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+    if (opts.query) {
+      for (const [k, v] of Object.entries(opts.query)) {
+        if (v !== void 0) url.searchParams.set(k, String(v));
+      }
+    }
+    const headers = new Headers();
+    headers.set("Accept", "application/json");
+    if (opts.body !== void 0) headers.set("Content-Type", "application/json");
+    const platformServiceId = PLATFORM_SERVICE_IDS[opts.service];
+    if (platformServiceId) headers.set("X-Service-ID", platformServiceId);
+    applyAuthHeaders(headers, this.credential);
+    applyAuditHeaders(headers, this.agent, generateRequestId());
+    if (opts.headers) {
+      for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
+    let res;
+    try {
+      res = await this.fetchImpl(url.toString(), {
+        method,
+        headers,
+        body: opts.body !== void 0 ? JSON.stringify(opts.body) : null,
+        signal
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    const contentType = res.headers.get("Content-Type") ?? "";
+    const parsed = contentType.includes("application/json") ? await res.json().catch(() => null) : await res.text().catch(() => null);
+    if (!res.ok) {
+      if (res.status === 401) throw new TopoloAuthError(describeError(parsed, "Unauthorized"));
+      if (res.status === 403) {
+        throw new TopoloPermissionError(
+          describeError(parsed, "Permission denied"),
+          extractRequired(parsed)
+        );
+      }
+      throw new TopoloHttpError(opts.service, opts.path, res.status, parsed);
+    }
+    return parsed;
+  }
+  /**
+   * Introspect the current credential. Returns the caller's resolved identity,
+   * organization, and permission set. Used by CLI `whoami` and by MCP to gate
+   * advertised tools by scope.
+   *
+   * Both JWT access tokens and platform API keys are resolved via the unified
+   * `GET /api/auth/me` endpoint on TopoloAuth, which does not require service
+   * credentials. The caller's possession of the credential secret is proof.
+   */
+  async introspect() {
+    const res = await this.request({
+      service: "auth",
+      method: "GET",
+      path: "/api/auth/me"
+    });
+    const payload = res.data ?? res;
+    const user = payload.user;
+    const organization = payload.organization;
+    const kind = payload.credentialType === "api_key" ? "api_key" : "access_token";
+    return {
+      kind,
+      user: {
+        id: user.id,
+        email: user.email,
+        name: user.name ?? null,
+        role: user.role ?? (kind === "api_key" ? "service" : "member"),
+        permissions: payload.permissions ?? user.permissions ?? []
+      },
+      organization: organization ? {
+        id: organization.id,
+        slug: organization.slug,
+        name: organization.name ?? organization.slug
+      } : user.orgId && user.orgSlug ? { id: user.orgId, slug: user.orgSlug, name: user.orgSlug } : null
+    };
+  }
+};
+function describeError(body, fallback) {
+  if (body && typeof body === "object") {
+    const maybe = body;
+    return maybe.message ?? maybe.error ?? fallback;
+  }
+  return fallback;
+}
+function extractRequired(body) {
+  if (body && typeof body === "object") {
+    const maybe = body;
+    if (Array.isArray(maybe.required)) return maybe.required.map(String);
+  }
+  return [];
+}
+function mergeSignals(a, b) {
+  if (a.aborted) return a;
+  if (b.aborted) return b;
+  const controller = new AbortController();
+  const onAbort = () => controller.abort();
+  a.addEventListener("abort", onAbort, { once: true });
+  b.addEventListener("abort", onAbort, { once: true });
+  return controller.signal;
+}
+
+// src/modules/crm.ts
+var CrmModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async listContacts(options = {}) {
+    const res = await this.client.request({
+      service: "crm",
+      path: "/api/contacts",
+      query: {
+        q: options.q,
+        page: options.page,
+        pageSize: options.pageSize
+      }
+    });
+    const rows = Array.isArray(res?.contacts) ? res.contacts : Array.isArray(res?.data) ? res.data : [];
+    return {
+      contacts: rows.map(toSummary),
+      total: res?.total ?? res?.pagination?.total ?? rows.length,
+      page: res?.page ?? res?.pagination?.page ?? options.page ?? 1,
+      pageSize: res?.pageSize ?? res?.pagination?.pageSize ?? options.pageSize ?? rows.length
+    };
+  }
+  async getContact(contactId) {
+    if (!contactId) throw new Error("contactId is required");
+    const res = await this.client.request({
+      service: "crm",
+      path: `/api/contacts/${encodeURIComponent(contactId)}`
+    });
+    const row = res.data ?? res;
+    return row ? toSummary(row) : null;
+  }
+};
+function toSummary(row) {
+  return {
+    id: row.id,
+    firstName: row.first ?? null,
+    lastName: row.last ?? null,
+    email: row.email ?? null,
+    phone: row.phone ?? null,
+    company: row.company ?? null,
+    leadStatus: row.lead_status ?? null,
+    lifecycleStage: row.lifecycle_stage ?? null,
+    updatedAt: row.updated_at ?? null
+  };
+}
+
+// src/modules/identity.ts
+var IdentityModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Returns the resolved user, organization, and permission set for the
+   *  current credential. Equivalent to `TopoloClient.introspect()` — exposed
+   *  on this module for symmetry with the other domain modules. */
+  whoami() {
+    return this.client.introspect();
+  }
+};
+
+// src/oauth.ts
+var DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+var TopoloOAuth = class {
+  baseUrl;
+  fetchImpl;
+  constructor(options = {}) {
+    this.baseUrl = resolveServiceUrl("auth", options.serviceUrls);
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  /**
+   * RFC 8628 device authorization grant — starts the flow by asking the server
+   * for a device_code + user_code. The caller prints the user_code +
+   * verification_uri and then polls `pollDeviceToken` until approval.
+   */
+  async requestDeviceCode(params) {
+    const body = new URLSearchParams();
+    body.set("client_id", params.clientId);
+    if (params.scope) {
+      body.set("scope", Array.isArray(params.scope) ? params.scope.join(" ") : params.scope);
+    }
+    return this.#postForm("/api/developer-oauth/device_authorization", body);
+  }
+  /**
+   * Polls the token endpoint once. Returns the token pair on success, or
+   * throws a `TopoloAuthError` whose `code` is one of the RFC 8628 poll
+   * states: `authorization_pending`, `slow_down`, `access_denied`,
+   * `expired_token`. Callers should back off on `slow_down`, wait at least
+   * one `interval` on `authorization_pending`, and give up on the rest.
+   */
+  async pollDeviceToken(params) {
+    const body = new URLSearchParams();
+    body.set("grant_type", DEVICE_GRANT);
+    body.set("client_id", params.clientId);
+    body.set("device_code", params.deviceCode);
+    if (params.clientSecret) body.set("client_secret", params.clientSecret);
+    return this.#postForm("/api/developer-oauth/token", body);
+  }
+  /** Exchange an authorization code (with PKCE) for tokens. */
+  async exchangeAuthorizationCode(params) {
+    const body = new URLSearchParams();
+    body.set("grant_type", "authorization_code");
+    body.set("client_id", params.clientId);
+    body.set("code", params.code);
+    body.set("redirect_uri", params.redirectUri);
+    if (params.codeVerifier) body.set("code_verifier", params.codeVerifier);
+    if (params.clientSecret) body.set("client_secret", params.clientSecret);
+    return this.#postForm("/api/developer-oauth/token", body);
+  }
+  /** Rotate a refresh token for a new token pair. */
+  async refreshToken(params) {
+    const body = new URLSearchParams();
+    body.set("grant_type", "refresh_token");
+    body.set("client_id", params.clientId);
+    body.set("refresh_token", params.refreshToken);
+    if (params.clientSecret) body.set("client_secret", params.clientSecret);
+    return this.#postForm("/api/developer-oauth/token", body);
+  }
+  async #postForm(path, body) {
+    const url = new URL(path, this.baseUrl.endsWith("/") ? this.baseUrl : `${this.baseUrl}/`);
+    const res = await this.fetchImpl(url.toString(), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json"
+      },
+      body: body.toString()
+    });
+    const contentType = res.headers.get("Content-Type") ?? "";
+    const parsed = contentType.includes("application/json") ? await res.json().catch(() => null) : await res.text().catch(() => null);
+    if (!res.ok) {
+      if (parsed && typeof parsed === "object" && "error" in parsed) {
+        const err = parsed;
+        throw new TopoloAuthError(err.error_description || err.error, err.error);
+      }
+      throw new TopoloHttpError("auth", path, res.status, parsed);
+    }
+    return parsed;
+  }
+};
+
+// src/index.ts
+function createTopolo(options) {
+  const client = new TopoloClient(options);
+  return {
+    client,
+    identity: new IdentityModule(client),
+    crm: new CrmModule(client)
+  };
+}
+export {
+  CrmModule,
+  DEFAULT_SERVICE_URLS,
+  IdentityModule,
+  PLATFORM_SERVICE_IDS,
+  TopoloAuthError,
+  TopoloClient,
+  TopoloHttpError,
+  TopoloOAuth,
+  TopoloPermissionError,
+  TopoloSdkError,
+  createTopolo,
+  resolveServiceUrl
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@topolo/sdk",
+  "version": "0.1.0",
+  "description": "Typed client SDK for the Topolo platform. Used by TopoloCli, TopoloMCP, and third-party agents.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.39",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,48 @@
+/**
+ * Auth credential types used by the SDK.
+ *
+ * Phase 1 supports two modes:
+ *   - `api_key`: a single platform API key (service-scoped at issuance).
+ *     Preferred for long-lived agent installs.
+ *   - `access_token`: a short-lived JWT from the interactive login flow.
+ *     Used by TopoloCli after `topolo auth login`.
+ *
+ * Phase 2 will add OAuth access tokens issued by the authorization-code +
+ * PKCE flow in TopoloAuth. Those will plug in as a third variant.
+ */
+export type TopoloCredential =
+  | { kind: 'api_key'; apiKey: string }
+  | { kind: 'access_token'; accessToken: string; refreshToken?: string; expiresAt?: number };
+
+export interface AgentIdentity {
+  /** Display name of the agent or tool making requests. Included in audit headers. */
+  clientName: string;
+  /** Semver of the client. Included in audit headers. */
+  clientVersion: string;
+  /**
+   * Optional agent-assigned label (e.g. "claude-code", "codex-cli") used for
+   * multi-tenant audit attribution when the client is used by another agent.
+   */
+  agentName?: string;
+}
+
+export function applyAuthHeaders(headers: Headers, credential: TopoloCredential): void {
+  if (credential.kind === 'api_key') {
+    headers.set('X-Api-Key', credential.apiKey);
+    return;
+  }
+  headers.set('Authorization', `Bearer ${credential.accessToken}`);
+}
+
+export function applyAuditHeaders(headers: Headers, agent: AgentIdentity, requestId: string): void {
+  headers.set('X-Topolo-Client', `${agent.clientName}/${agent.clientVersion}`);
+  if (agent.agentName) headers.set('X-Topolo-Agent', agent.agentName);
+  headers.set('X-Topolo-Request-Id', requestId);
+}
+
+export function generateRequestId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID();
+  }
+  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}

package/src/client.ts

@@ -0,0 +1,245 @@
+import {
+  applyAuditHeaders,
+  applyAuthHeaders,
+  generateRequestId,
+  type AgentIdentity,
+  type TopoloCredential,
+} from './auth.js';
+import { TopoloAuthError, TopoloHttpError, TopoloPermissionError } from './errors.js';
+import {
+  PLATFORM_SERVICE_IDS,
+  resolveServiceUrl,
+  type ServiceId,
+} from './services.js';
+
+export interface TopoloClientOptions {
+  credential: TopoloCredential;
+  agent: AgentIdentity;
+  /** Per-service URL overrides. Useful for staging/dev. */
+  serviceUrls?: Partial<Record<ServiceId, string>>;
+  /**
+   * When true, mutating helpers (POST/PUT/PATCH/DELETE) require callers to pass
+   * `{ confirm: true }`. Defaults to true. Set false only for trusted surfaces.
+   */
+  requireConfirmForWrites?: boolean;
+  /** HTTP request timeout (ms). Default 30s. */
+  timeoutMs?: number;
+  /** Injected fetch, for testing. Defaults to global fetch. */
+  fetch?: typeof fetch;
+}
+
+export interface RequestOptions {
+  service: ServiceId;
+  path: string;
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  query?: Record<string, string | number | boolean | undefined>;
+  body?: unknown;
+  /** Explicit write-acknowledgement for mutating calls. */
+  confirm?: boolean;
+  /** Extra headers appended after auth/audit headers. */
+  headers?: Record<string, string>;
+  signal?: AbortSignal;
+}
+
+const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+export class TopoloClient {
+  private readonly credential: TopoloCredential;
+  private readonly agent: AgentIdentity;
+  private readonly serviceUrls?: Partial<Record<ServiceId, string>>;
+  private readonly requireConfirmForWrites: boolean;
+  private readonly timeoutMs: number;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: TopoloClientOptions) {
+    if (!options.credential) throw new TopoloAuthError('credential is required');
+    if (!options.agent?.clientName) throw new TopoloAuthError('agent.clientName is required');
+    this.credential = options.credential;
+    this.agent = options.agent;
+    this.serviceUrls = options.serviceUrls;
+    this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
+    this.timeoutMs = options.timeoutMs ?? 30_000;
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+
+  /**
+   * Low-level JSON request. Prefer the typed module helpers (identity, crm, ...)
+   * for anything a caller would reach for; this stays exported for escape-hatch
+   * use and for the generic `topolo api` / MCP passthrough tool.
+   */
+  async request<T = unknown>(opts: RequestOptions): Promise<T> {
+    const method = opts.method ?? 'GET';
+    if (this.requireConfirmForWrites && WRITE_METHODS.has(method) && !opts.confirm) {
+      throw new TopoloAuthError(
+        `Mutating ${method} requests require { confirm: true }. This guardrail prevents ` +
+          `agents from issuing writes without an explicit human-in-the-loop acknowledgement.`,
+      );
+    }
+
+    const baseUrl = resolveServiceUrl(opts.service, this.serviceUrls);
+    const url = new URL(opts.path, baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
+    if (opts.query) {
+      for (const [k, v] of Object.entries(opts.query)) {
+        if (v !== undefined) url.searchParams.set(k, String(v));
+      }
+    }
+
+    const headers = new Headers();
+    headers.set('Accept', 'application/json');
+    if (opts.body !== undefined) headers.set('Content-Type', 'application/json');
+    const platformServiceId = PLATFORM_SERVICE_IDS[opts.service];
+    if (platformServiceId) headers.set('X-Service-ID', platformServiceId);
+
+    applyAuthHeaders(headers, this.credential);
+    applyAuditHeaders(headers, this.agent, generateRequestId());
+
+    if (opts.headers) {
+      for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    const signal = opts.signal
+      ? mergeSignals(opts.signal, controller.signal)
+      : controller.signal;
+
+    let res: Response;
+    try {
+      res = await this.fetchImpl(url.toString(), {
+        method,
+        headers,
+        body: opts.body !== undefined ? JSON.stringify(opts.body) : null,
+        signal,
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+
+    const contentType = res.headers.get('Content-Type') ?? '';
+    const parsed: unknown = contentType.includes('application/json')
+      ? await res.json().catch(() => null)
+      : await res.text().catch(() => null);
+
+    if (!res.ok) {
+      if (res.status === 401) throw new TopoloAuthError(describeError(parsed, 'Unauthorized'));
+      if (res.status === 403) {
+        throw new TopoloPermissionError(
+          describeError(parsed, 'Permission denied'),
+          extractRequired(parsed),
+        );
+      }
+      throw new TopoloHttpError(opts.service, opts.path, res.status, parsed);
+    }
+
+    return parsed as T;
+  }
+
+  /**
+   * Introspect the current credential. Returns the caller's resolved identity,
+   * organization, and permission set. Used by CLI `whoami` and by MCP to gate
+   * advertised tools by scope.
+   *
+   * Both JWT access tokens and platform API keys are resolved via the unified
+   * `GET /api/auth/me` endpoint on TopoloAuth, which does not require service
+   * credentials. The caller's possession of the credential secret is proof.
+   */
+  async introspect(): Promise<CredentialIntrospection> {
+    const res = await this.request<{ data: AuthMePayload } | AuthMePayload>({
+      service: 'auth',
+      method: 'GET',
+      path: '/api/auth/me',
+    });
+
+    const payload: AuthMePayload = (res as { data?: AuthMePayload }).data ?? (res as AuthMePayload);
+    const user = payload.user;
+    const organization = payload.organization;
+    const kind: CredentialIntrospection['kind'] =
+      payload.credentialType === 'api_key' ? 'api_key' : 'access_token';
+
+    return {
+      kind,
+      user: {
+        id: user.id,
+        email: user.email,
+        name: user.name ?? null,
+        role: user.role ?? (kind === 'api_key' ? 'service' : 'member'),
+        permissions: payload.permissions ?? user.permissions ?? [],
+      },
+      organization: organization
+        ? {
+            id: organization.id,
+            slug: organization.slug,
+            name: organization.name ?? organization.slug,
+          }
+        : user.orgId && user.orgSlug
+          ? { id: user.orgId, slug: user.orgSlug, name: user.orgSlug }
+          : null,
+    };
+  }
+}
+
+interface AuthMePayload {
+  credentialType?: 'access_token' | 'api_key';
+  user: RawUser;
+  organization?: RawOrg | null;
+  permissions?: string[];
+}
+
+export interface CredentialIntrospection {
+  kind: 'api_key' | 'access_token';
+  user: {
+    id: string;
+    email: string;
+    name: string | null;
+    role: string;
+    permissions: string[];
+  };
+  organization: {
+    id: string;
+    slug: string;
+    name: string;
+  } | null;
+}
+
+interface RawUser {
+  id: string;
+  email: string;
+  name?: string;
+  role?: string;
+  permissions?: string[];
+  orgId?: string;
+  orgSlug?: string;
+  organization?: { id: string; slug: string; name: string } | null;
+}
+
+interface RawOrg {
+  id: string;
+  slug: string;
+  name?: string;
+}
+
+function describeError(body: unknown, fallback: string): string {
+  if (body && typeof body === 'object') {
+    const maybe = body as { error?: string; message?: string };
+    return maybe.message ?? maybe.error ?? fallback;
+  }
+  return fallback;
+}
+
+function extractRequired(body: unknown): string[] {
+  if (body && typeof body === 'object') {
+    const maybe = body as { required?: unknown };
+    if (Array.isArray(maybe.required)) return maybe.required.map(String);
+  }
+  return [];
+}
+
+function mergeSignals(a: AbortSignal, b: AbortSignal): AbortSignal {
+  if (a.aborted) return a;
+  if (b.aborted) return b;
+  const controller = new AbortController();
+  const onAbort = () => controller.abort();
+  a.addEventListener('abort', onAbort, { once: true });
+  b.addEventListener('abort', onAbort, { once: true });
+  return controller.signal;
+}