@tai42/api-client 16.0.0 → 17.0.0

package/src/client/storage-client.ts

@@ -0,0 +1,63 @@
+/** Storage resource CRUD sub-client. */
+import { apiDownload, isUnsafePathSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+/**
+ * Body for a storage upload (POST `/api/storage/resources`). Exactly ONE of
+ * `content_text` (stored verbatim) or `content_base64` (a base64 string decoded to
+ * bytes) supplies the content for `id`; uploading an existing id overwrites it
+ * (provider passthrough semantics).
+ */
+export interface StorageUploadBody {
+  readonly id: string;
+  readonly content_text?: string;
+  readonly content_base64?: string;
+}
+
+/**
+ * Encode a possibly-nested storage id / directory path for use in a URL path,
+ * percent-encoding each segment while preserving the `/` separators. A storage id
+ * can be a nested path (e.g. `a/b c.txt`); encoding each segment independently keeps
+ * the slashes structural and escapes everything else (spaces, `#`, `?`, …).
+ *
+ * Dot segments (`.`, `..`), empty segments (a leading/trailing/doubled `/`, or an
+ * empty id) are REJECTED loudly rather than encoded: the browser's WHATWG URL parser
+ * removes dot-segments from a relative request path before it is sent — collapsing
+ * `..` even when percent-encoded — so such an id can never be faithfully transmitted.
+ * Left to encode, it would silently retarget the request at an unrelated same-origin
+ * route. The server enforces the same relative-path rule; failing fast here keeps a
+ * malformed id from ever leaving the client.
+ */
+function encodePath(id: string): string {
+  const segments = id.split('/');
+  if (segments.some(isUnsafePathSegment)) {
+    throw new Error("storage path must be a relative path with no empty, '.', or '..' segment");
+  }
+  return segments.map(encodeURIComponent).join('/');
+}
+
+export function storageClient(t: Transport) {
+  const { config, req } = t;
+  return {
+    // The content store a storage-provider plugin exposes. Dead by default:
+    // `getStorageInfo` reports `present: false` (a 200 empty state) and every other
+    // door answers a loud 501 when no provider is installed. Ids may be nested
+    // paths, so each is `encodePath`-encoded (per-segment, `/` preserved).
+    getStorageInfo: (signal?: AbortSignal) => req('/api/storage', s.storageInfo, { signal }),
+    listStorageResources: (signal?: AbortSignal) =>
+      req('/api/storage/resources', s.storageResourceList, { signal }),
+    statStorageResource: (id: string, signal?: AbortSignal) =>
+      req(`/api/storage/resources/${encodePath(id)}/stat`, s.storageResourceStat, { signal }),
+    downloadStorageResource: (id: string, signal?: AbortSignal): Promise<Blob> =>
+      apiDownload(config, `/api/storage/resources/${encodePath(id)}/content`, { signal }),
+    uploadStorageResource: (body: StorageUploadBody) =>
+      req('/api/storage/resources', s.storageResourceStored, { method: 'POST', body }),
+    deleteStorageResource: (id: string) =>
+      req(`/api/storage/resources/${encodePath(id)}`, s.storageResourceDeleted, {
+        method: 'DELETE',
+      }),
+    deleteStorageDir: (path: string) =>
+      req(`/api/storage/dirs/${encodePath(path)}`, s.storageDirDeleted, { method: 'DELETE' }),
+  };
+}

package/src/client/sub-mcp-client.ts

@@ -0,0 +1,17 @@
+/** Sub-MCP mount registry sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function subMcpClient(t: Transport) {
+  const { req } = t;
+  return {
+    listSubMcp: (signal?: AbortSignal) => req('/api/sub-mcp', s.subMcpList, { signal }),
+    // `transport` is optional at the client boundary (the server defaults it to
+    // `http`); when omitted, JSON.stringify drops the undefined key from the body.
+    createSubMcp: (slug: string, tools: string[], transport?: string) =>
+      req('/api/sub-mcp', s.subMcpCreated, { method: 'POST', body: { slug, tools, transport } }),
+    deleteSubMcp: (slug: string) =>
+      req(`/api/sub-mcp/${encodeSegment(slug)}`, s.subMcpRemoved, { method: 'DELETE' }),
+  };
+}

package/src/client/system-client.ts

@@ -0,0 +1,16 @@
+/** System health and pluggable-kind status sub-client. */
+import { apiText } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function systemClient(t: Transport) {
+  const { config, req } = t;
+  return {
+    getHealth: (signal?: AbortSignal) => apiText(config, '/health', { signal }),
+
+    // The pluggable-kind status table (`GET /api/system/kinds`) — a JSON `{data}`
+    // envelope, one row per kind with its active/default/off state.
+    getSystemKinds: (signal?: AbortSignal) =>
+      req('/api/system/kinds', s.kindStatusList, { signal }),
+  };
+}

package/src/client/templates-client.ts

@@ -0,0 +1,28 @@
+/** Prompt-template listing, render and mutation sub-client. */
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function templatesClient(t: Transport) {
+  const { req } = t;
+  return {
+    listTemplates: (signal?: AbortSignal) => req('/api/templates', s.templateNames, { signal }),
+    getTemplate: (templateId: string) =>
+      req('/api/template', s.templateDetail, { method: 'POST', body: { template_id: templateId } }),
+    uploadTemplate: (path: string, content: string) =>
+      req('/api/upload-template', s.templateUploaded, { method: 'POST', body: { path, content } }),
+    deleteTemplate: (path: string) =>
+      req('/api/delete-template', s.templateDeleted, { method: 'POST', body: { path } }),
+    // Delete every stored template under a directory prefix. Unlike the idempotent
+    // single delete, the server 404s a prefix matching nothing and 400s the template
+    // root; those surface as loud errors, never a faked success.
+    deleteTemplateDir: (path: string) =>
+      req('/api/delete-template-dir', s.templateDirDeleted, { method: 'POST', body: { path } }),
+    // Render one authored text — inline `content` OR a stored template `id`, plus its
+    // render `kwargs` — and parse the rendered output. The value is the shared
+    // `TemplatedText` (exactly one source); the route wraps it under `text`.
+    renderTemplate: (text: s.TemplatedText) =>
+      req('/api/render-template', s.templateRendered, { method: 'POST', body: { text } }),
+    clearTemplatesCache: () =>
+      req('/api/clear-templates-cache', s.templateCacheCleared, { method: 'POST' }),
+  };
+}

package/src/client/tool-extensions-client.ts

@@ -0,0 +1,24 @@
+/** Tool extension listing and authoring sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function toolExtensionsClient(t: Transport) {
+  const { req } = t;
+  return {
+    listExtensions: (signal?: AbortSignal) => req('/api/extensions', s.extensions, { signal }),
+    // A MANIFEST-provided tool's current combos + the extension catalog. (A preset
+    // tool's extensions live on the preset spec, read via `getPreset`.)
+    getToolExtensions: (name: string, signal?: AbortSignal) =>
+      req(`/api/tools/${encodeSegment(name)}/extensions`, s.toolExtensions, { signal }),
+    // Author ALL of a MANIFEST tool's combos at once (the full lossless list; `[]`
+    // clears). Returns the apply result: the local reload (`status` + `env_keys`) plus
+    // the mode-wrapped fleet `fanout` of the reload it broadcast, from which the shared
+    // fleet-report handler surfaces any failed propagation.
+    setToolExtensions: (name: string, combos: readonly s.PresetExtensionElement[][]) =>
+      req(`/api/tools/${encodeSegment(name)}/extensions`, s.toolExtensionsApplyResult, {
+        method: 'POST',
+        body: { combos },
+      }),
+  };
+}

package/src/client/tool-meta-client.ts

@@ -0,0 +1,65 @@
+/** Tool-organization overlay (folders and meta) sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+/**
+ * Merge-patch body for a tool's overlay row (PATCH
+ * `/api/tool-meta/tools/{tool_name}`). Only the fields PRESENT are written; a
+ * present-null clears (`hidden: null` writes the tri-state "defer to the plugin
+ * declaration" state, `display_name: null` clears the label, `folder_id: null`
+ * unfiles); a present `tags` array replaces the whole set. Absent fields are left
+ * untouched — there is no full-row replace, so a display-name+tags editor sends
+ * ONLY those two keys with no risk to `folder_id`/`hidden`. At least one field must
+ * be present. A blank/whitespace-only `display_name` is rejected by the API (422) —
+ * callers map an emptied label to `null`, never `""`. A present `badges` array
+ * replaces the whole overlay set (INFORMATIONAL labels, never an enforced gate).
+ */
+export interface ToolMetaPatch {
+  readonly display_name?: string | null;
+  readonly folder_id?: string | null;
+  readonly tags?: readonly string[];
+  readonly badges?: readonly string[];
+  readonly hidden?: boolean | null;
+}
+
+export function toolMetaClient(t: Transport) {
+  const { req } = t;
+  return {
+    // The folder tree + per-tool overlay rows in one read; the features merge the
+    // rows against the live tool list and native tags client-side.
+    listToolMeta: (signal?: AbortSignal) => req('/api/tool-meta', s.toolMetaOverlay, { signal }),
+    // Merge-patch a tool's overlay row (create it if absent). `patch` carries ONLY
+    // the fields to change — a present-null clears, an absent field is untouched,
+    // and a present `tags` array replaces the set.
+    upsertToolMeta: (toolName: string, patch: ToolMetaPatch) =>
+      req(`/api/tool-meta/tools/${encodeSegment(toolName)}`, s.toolMetaRecord, {
+        method: 'PATCH',
+        body: patch,
+      }),
+    deleteToolMeta: (toolName: string) =>
+      req(`/api/tool-meta/tools/${encodeSegment(toolName)}`, s.toolMetaDeleted, {
+        method: 'DELETE',
+      }),
+    createFolder: (name: string, parentId: string | null = null) =>
+      req('/api/tool-meta/folders', s.folderRecord, {
+        method: 'POST',
+        body: { name, parent_id: parentId },
+      }),
+    renameFolder: (folderId: string, name: string) =>
+      req(`/api/tool-meta/folders/${encodeSegment(folderId)}/rename`, s.folderRecord, {
+        method: 'POST',
+        body: { name },
+      }),
+    // `null` re-parents to the root.
+    moveFolder: (folderId: string, parentId: string | null) =>
+      req(`/api/tool-meta/folders/${encodeSegment(folderId)}/move`, s.folderRecord, {
+        method: 'POST',
+        body: { parent_id: parentId },
+      }),
+    deleteFolder: (folderId: string) =>
+      req(`/api/tool-meta/folders/${encodeSegment(folderId)}`, s.folderDeleted, {
+        method: 'DELETE',
+      }),
+  };
+}

package/src/client/tools-client.ts

@@ -0,0 +1,66 @@
+/** Tool catalog, run, live-registry admin and tag sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import { getToolRun, listToolRuns, submitToolRun, type SubmitToolRunArgs } from '../tool-runs';
+import type { Transport } from './transport';
+
+export interface RunToolArgs {
+  readonly tool: string;
+  readonly kwargs?: Record<string, unknown>;
+}
+
+/**
+ * Identify one app tool for a live-registry op (`POST /api/tools/reload`,
+ * `POST /api/tools/remove`): its `kind` (the reloader kind a plugin registered,
+ * e.g. `example_tool`) and `name`. `targets` optionally restricts the fleet
+ * fan-out to specific workers; omit it to reach every worker.
+ */
+export interface ToolAdminArgs {
+  readonly kind: string;
+  readonly name: string;
+  readonly targets?: string[];
+}
+
+export function toolsClient(t: Transport) {
+  const { config, req } = t;
+  return {
+    listTools: (signal?: AbortSignal) => req('/api/tools', s.toolNames, { signal }),
+    getToolSchema: (name: string, signal?: AbortSignal) =>
+      req(`/api/tools/${encodeSegment(name)}/schema`, s.toolSchema, { signal }),
+    getAllToolSchemas: (signal?: AbortSignal) =>
+      req('/api/tools-schema', s.allToolSchemas, { signal }),
+    runTool: (args: RunToolArgs, signal?: AbortSignal) =>
+      req('/api/run-tool', s.runToolResult, {
+        method: 'POST',
+        // The backend's `/api/run-tool` door reads `{tool_name, arguments}` (the
+        // shape `read_tool_call` enforces and the background `/api/tool-runs`
+        // submit already sends). The SPA keeps `tool`/`kwargs` as its ergonomic
+        // arg names; map them onto the wire fields here.
+        body: { tool_name: args.tool, arguments: args.kwargs ?? {} },
+        signal,
+      }),
+
+    // Re-register or remove one app tool by kind+name, applied on this worker and
+    // broadcast to the fleet (all workers, or only `targets`); both return the bare
+    // per-worker `fleetResult` the shared fleet-report handler renders. Both are
+    // fenced + destructive server-side, so a refusal surfaces as a loud error.
+    reloadTool: (args: ToolAdminArgs) =>
+      req('/api/tools/reload', s.fleetResult, {
+        method: 'POST',
+        body: { kind: args.kind, name: args.name, targets: args.targets ?? null },
+      }),
+    removeTool: (args: ToolAdminArgs) =>
+      req('/api/tools/remove', s.fleetResult, {
+        method: 'POST',
+        body: { kind: args.kind, name: args.name, targets: args.targets ?? null },
+      }),
+
+    submitToolRun: (args: SubmitToolRunArgs, signal?: AbortSignal) =>
+      submitToolRun(config, args, signal),
+    getToolRun: (runId: string, signal?: AbortSignal) => getToolRun(config, runId, signal),
+    listToolRuns: (toolName: string, signal?: AbortSignal) =>
+      listToolRuns(config, toolName, signal),
+
+    listToolTags: (signal?: AbortSignal) => req('/api/tools/tags', s.toolTags, { signal }),
+  };
+}

package/src/client/transport.ts

@@ -0,0 +1,18 @@
+/** The shared transport seam every sub-client method flows through. */
+import type { ApiConfig } from '../http';
+import { apiRequest } from '../http';
+
+/**
+ * Build the per-request transport for one client: the bound `config` and the
+ * `req` chokepoint that validates every response against its schema.
+ */
+export function makeTransport(config: ApiConfig) {
+  const req = <S extends Parameters<typeof apiRequest>[2]>(
+    path: string,
+    schema: S,
+    options?: Parameters<typeof apiRequest>[3],
+  ) => apiRequest(config, path, schema, options);
+  return { config, req };
+}
+
+export type Transport = ReturnType<typeof makeTransport>;

package/src/client/trigger-links-client.ts

@@ -0,0 +1,51 @@
+/** Trigger-link mint, listing and revoke sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+/**
+ * Body for minting a trigger link (POST `/api/hooks/trigger-links`). `ttl_seconds`
+ * is REQUIRED and nullable — a positive int is a timed link, `null` is a permanent
+ * link (`0`/negative is a loud server 400); it is always sent EXPLICITLY (a dropped
+ * key 400s server-side). `name` is optional (the server generates one when omitted);
+ * `tool_kwargs` is the optional per-link params merged last into every fire.
+ */
+export interface TriggerLinkCreateBody {
+  readonly topic: string;
+  readonly name?: string;
+  readonly execution_key: string;
+  // The link is a token door; this is its only auth knob (token → token+api_key).
+  readonly require_api_key: boolean;
+  readonly ttl_seconds: number | null;
+  readonly tool_kwargs?: Record<string, unknown> | null;
+}
+
+export function triggerLinksClient(t: Transport) {
+  const { req } = t;
+  return {
+    // Mint a trigger link for a topic. `ttl_seconds` is sent EXPLICITLY
+    // (including `null` for a permanent link) — the server requires the key present
+    // and 400s a dropped one; `tool_kwargs` is omitted when undefined. The raw
+    // `token` rides the response ONCE (composed into the QR URL client-side).
+    createTriggerLink: (body: TriggerLinkCreateBody) =>
+      req('/api/hooks/trigger-links', s.triggerLinkCreated, {
+        method: 'POST',
+        body: {
+          topic: body.topic,
+          name: body.name,
+          execution_key: body.execution_key,
+          require_api_key: body.require_api_key,
+          ttl_seconds: body.ttl_seconds,
+          tool_kwargs: body.tool_kwargs,
+        },
+      }),
+    // Every live trigger-link record (hash prefix only — never a raw token).
+    listTriggerLinks: (signal?: AbortSignal) =>
+      req('/api/hooks/trigger-links', s.triggerLinkList, { signal }),
+    // Revoke a link by name (immediate + durable). 404 when the name is unknown.
+    deleteTriggerLink: (name: string) =>
+      req(`/api/hooks/trigger-links/${encodeSegment(name)}`, s.triggerLinkDeleted, {
+        method: 'DELETE',
+      }),
+  };
+}

package/src/client/web-entry-gate-client.ts

@@ -0,0 +1,45 @@
+/** Web-channel entry-gate sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+/**
+ * Body for minting a web entry code (POST
+ * `/api/channels/web/gates/{identity}/codes`). Both fields are optional-nullable
+ * and sent EXPLICITLY: `label` is a human tag (`null` for none); `expires_at` is
+ * an ISO-8601 instant the code dies at (`null` for a code that never expires).
+ */
+export interface WebEntryCodeMintBody {
+  readonly label: string | null;
+  readonly expires_at: string | null;
+}
+
+export function webEntryGateClient(t: Transport) {
+  const { req } = t;
+  return {
+    // A web route's entry gate, keyed by its `our_identity`: read the flag + its
+    // live codes, flip the flag, mint a code (raw returned ONCE), revoke a code by
+    // its hash id. The conversation monitor's first route mutations.
+    getWebEntryGate: (identity: string, signal?: AbortSignal) =>
+      req(`/api/channels/web/gates/${encodeSegment(identity)}`, s.webEntryGate, { signal }),
+    setWebEntryGate: (identity: string, enabled: boolean) =>
+      req(`/api/channels/web/gates/${encodeSegment(identity)}`, s.webEntryGateState, {
+        method: 'PUT',
+        body: { enabled },
+      }),
+    // Mint a code. `label`/`expires_at` are sent EXPLICITLY (including `null`). The
+    // raw `code` rides the reply ONCE (composed into the chat URL client-side).
+    mintWebEntryCode: (identity: string, body: WebEntryCodeMintBody) =>
+      req(`/api/channels/web/gates/${encodeSegment(identity)}/codes`, s.webEntryCodeMinted, {
+        method: 'POST',
+        body: { label: body.label, expires_at: body.expires_at },
+      }),
+    // Revoke a code by its hash id (immediate + durable). 404 when the id is unknown.
+    revokeWebEntryCode: (identity: string, codeId: string) =>
+      req(
+        `/api/channels/web/gates/${encodeSegment(identity)}/codes/${encodeSegment(codeId)}`,
+        s.webEntryCodeRevoked,
+        { method: 'DELETE' },
+      ),
+  };
+}

package/src/errors.ts

@@ -71,6 +71,22 @@ export class ApiLoginFailedError extends Error {
   }
 }
 
+/**
+ * A setup attempt was REJECTED — a bad or throttled token (403/429), an
+ * already-initialized deployment (409), an unsupported setup door (501), or an
+ * invalid body (400/422). Like {@link ApiLoginFailedError} it is NOT an
+ * ApiUnauthorizedError: it renders inline on the setup entry, keyed on `status`
+ * so the page shows the right copy, never a global unauthorized redirect.
+ */
+export class ApiSetupFailedError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = 'ApiSetupFailedError';
+    this.status = status;
+  }
+}
+
 /**
  * The response body did not match its declared zod schema. This is a contract
  * drift between the Studio and the skeleton — a loud, visible error, never a

package/src/http.ts

@@ -92,30 +92,18 @@ function retryAfterSeconds(header: string | null): number | undefined {
   return Number.isFinite(seconds) && seconds >= 0 ? seconds : undefined;
 }
 
-export async function apiRequest<S extends z.ZodType>(
-  config: ApiConfig,
+/**
+ * Read the JSON body of a request response, applying the transport's error
+ * policy: a non-2xx status throws (a 409 as `ApiConflictError` carrying the
+ * parsed body, every other as `ApiError` with the server message/code and the
+ * named `Retry-After` delay), and a body that is not JSON throws `ApiSchemaError`
+ * on a 2xx or `ApiError` otherwise. Returns the parsed payload only for a 2xx.
+ */
+async function readJsonPayload(
+  response: Response,
   path: string,
-  schema: S,
-  options: RequestOptions = {},
-): Promise<z.infer<S>> {
-  const doFetch = config.fetch ?? globalThis.fetch;
-  const token = config.getToken();
-  const headers: Record<string, string> = { ...JSON_HEADERS };
-  if (token) headers['x-api-key'] = token;
-
-  const response = await doFetch(buildUrl(config.baseUrl ?? '', path, options.query), {
-    method: options.method ?? 'GET',
-    headers,
-    body: options.body === undefined ? undefined : JSON.stringify(options.body),
-    signal: options.signal,
-  });
-
-  if (response.status === 401) throw new ApiUnauthorizedError();
-
-  // `Retry-After` rides on the error so a retrying caller waits the delay the server
-  // named (the gated routes' reloading 503 carries one) instead of guessing.
-  const retryAfter = retryAfterSeconds(response.headers.get('Retry-After'));
-
+  retryAfter: number | undefined,
+): Promise<unknown> {
   let payload: unknown;
   try {
     payload = await response.json();
@@ -138,15 +126,51 @@ export async function apiRequest<S extends z.ZodType>(
     throw new ApiError(text, response.status, code, retryAfter, payload);
   }
 
+  return payload;
+}
+
+/** Unwrap the `{ data }` envelope and validate it against `schema`; a missing
+ *  envelope or a validation failure throws `ApiSchemaError`. */
+function validateEnvelope<S extends z.ZodType>(
+  schema: S,
+  path: string,
+  payload: unknown,
+): z.infer<S> {
   if (!isDataEnvelope(payload)) {
     throw new ApiSchemaError(path, 'response was not a { data } envelope');
   }
-
   const parsed = schema.safeParse(payload.data);
   if (!parsed.success) throw new ApiSchemaError(path, parsed.error.issues);
   return parsed.data;
 }
 
+export async function apiRequest<S extends z.ZodType>(
+  config: ApiConfig,
+  path: string,
+  schema: S,
+  options: RequestOptions = {},
+): Promise<z.infer<S>> {
+  const doFetch = config.fetch ?? globalThis.fetch;
+  const token = config.getToken();
+  const headers: Record<string, string> = { ...JSON_HEADERS };
+  if (token) headers['x-api-key'] = token;
+
+  const response = await doFetch(buildUrl(config.baseUrl ?? '', path, options.query), {
+    method: options.method ?? 'GET',
+    headers,
+    body: options.body === undefined ? undefined : JSON.stringify(options.body),
+    signal: options.signal,
+  });
+
+  if (response.status === 401) throw new ApiUnauthorizedError();
+
+  // `Retry-After` rides on the error so a retrying caller waits the delay the server
+  // named (the gated routes' reloading 503 carries one) instead of guessing.
+  const retryAfter = retryAfterSeconds(response.headers.get('Retry-After'));
+  const payload = await readJsonPayload(response, path, retryAfter);
+  return validateEnvelope(schema, path, payload);
+}
+
 /**
  * Fetch a plain-text endpoint (the skeleton's `/health` → `"OK"`). No `{ data }`
  * envelope, no zod — the body is returned verbatim. Non-2xx still throws loudly.