@tai42/api-client 15.0.0 → 16.0.1

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 * as s from '../schemas';
+import { encodeSegment } from '../http';
+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 * as s from '../schemas';
+import { encodeSegment } from '../http';
+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 * as s from '../schemas';
+import { encodeSegment } from '../http';
+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 * as s from '../schemas';
+import { encodeSegment } from '../http';
+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 * as s from '../schemas';
+import { encodeSegment } from '../http';
+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/generated/served-schemas.ts

@@ -0,0 +1,126 @@
+// DO NOT EDIT — generated from the platform contract JSON-schema bundle.
+// Source: packages/api-client/contract-schema/contract-schema.json
+// Regenerate with: pnpm --filter @tai42/api-client run schema:generate
+//
+// One zod const + inferred type per published served document and per shared
+// sub-shape. A templated-text field is the shared `templatedText` zod, never a
+// bare string, so a body can never drift back to `z.string()`.
+import { z } from 'zod';
+
+import { templatedText } from '../templated-text';
+
+export const hookSubject = z.object({ "key_expr": templatedText, "kind": z.string(), "target_kind": z.enum(["agent","tool"]), "target_name": z.string().min(1) }).strict();
+export type HookSubject = z.infer<typeof hookSubject>;
+
+export const mediaKind = z.enum(["image","link","document","video","audio"]);
+export type MediaKind = z.infer<typeof mediaKind>;
+
+export const mediaItem = z.object({ "caption": z.union([z.string(), z.null()]).default(null), "filename": z.union([z.string(), z.null()]).default(null), "kind": mediaKind, "url": z.string() });
+export type MediaItem = z.infer<typeof mediaItem>;
+
+export const presetSeedToolMeta = z.object({ "display_name": z.union([z.string(), z.null()]).default(null), "folder_path": z.union([z.string(), z.null()]).default(null), "tags": z.union([z.array(z.string()), z.null()]).default(null) });
+export type PresetSeedToolMeta = z.infer<typeof presetSeedToolMeta>;
+
+export const presetSpec = z.object({ "base_tool": z.string(), "description": z.string().default(""), "fixed_kwargs": z.record(z.string(), z.unknown()).default({}), "name": z.string() });
+export type PresetSpec = z.infer<typeof presetSpec>;
+
+export const quickReplyButtonParam = z.object({ "kind": z.literal("quick_reply").default("quick_reply"), "payload": z.string() });
+export type QuickReplyButtonParam = z.infer<typeof quickReplyButtonParam>;
+
+export const stateInjection = z.object({ "into": z.string().min(1), "jq": z.union([templatedText, z.null()]).default(null), "template_jq": z.union([z.string(), z.null()]).default(null) }).strict();
+export type StateInjection = z.infer<typeof stateInjection>;
+
+export const stateUpdate = z.object({ "adapter": z.union([templatedText, z.null()]).default(null), "jq": z.union([templatedText, z.null()]).default(null), "op_id": z.union([templatedText, z.null()]).default(null), "template_jq": z.union([z.string(), z.null()]).default(null) }).strict();
+export type StateUpdate = z.infer<typeof stateUpdate>;
+
+export const stateAttach = z.object({ "input_injections": z.array(stateInjection).default([]), "scope_expr": z.union([templatedText, z.null()]).default(null), "state": z.string(), "subject_expr": templatedText, "templates": z.array(z.string()).default([]), "updates": z.array(stateUpdate).default([]) }).strict();
+export type StateAttach = z.infer<typeof stateAttach>;
+
+export const stateBinding = z.object({ "states": z.array(stateAttach).min(1) }).strict();
+export type StateBinding = z.infer<typeof stateBinding>;
+
+export const stateTemplateDeclarations = z.object({ "check": z.union([templatedText, z.null()]).default(null), "schema": z.record(z.string(), z.unknown()) }).strict();
+export type StateTemplateDeclarations = z.infer<typeof stateTemplateDeclarations>;
+
+export const stateTemplateJq = z.object({ "description": z.string().default(""), "jq": templatedText, "params": z.array(z.string()).default([]), "purpose": z.enum(["input","update"]), "reads": z.array(z.array(z.string())).default([]), "writes": z.array(z.array(z.string())).default([]) }).strict();
+export type StateTemplateJq = z.infer<typeof stateTemplateJq>;
+
+export const stateTemplateReconcile = z.object({ "close": templatedText, "orphans": templatedText, "resolutions": templatedText }).strict();
+export type StateTemplateReconcile = z.infer<typeof stateTemplateReconcile>;
+
+export const subAgentSpec: z.ZodType = z.lazy(() => z.object({ "description": z.string().default(""), "inline_skills": z.array(z.record(z.string(), z.unknown())).default([]), "name": z.string(), "presets": z.array(presetSpec).default([]), "response_format": z.union([z.unknown(), templatedText, z.record(z.string(), z.unknown()), z.null()]).default(null), "skills": z.array(z.string()).default([]), "strategy": z.union([z.string(), z.null()]).default(null), "subagents": z.array(subAgentSpec).default([]), "system_prompt": z.union([templatedText, z.null()]).default(null), "tool_names": z.array(z.string()).default([]), "tools": z.array(z.unknown()).default([]) }));
+export type SubAgentSpec = z.infer<typeof subAgentSpec>;
+
+export const urlButtonParam = z.object({ "kind": z.literal("url").default("url"), "url_parameter": z.string() });
+export type UrlButtonParam = z.infer<typeof urlButtonParam>;
+
+export const accessPolicy = z.object({ "condition": z.union([templatedText, z.null()]).default(null), "policy_data": z.record(z.string(), z.unknown()).default({}), "scopes": z.array(z.string()).default([]) });
+export type AccessPolicy = z.infer<typeof accessPolicy>;
+
+export const callbackSchema = z.object({ "condition": z.union([templatedText, z.null()]).default(null), "expr": z.union([templatedText, z.null()]).default(null), "tool": z.string().default("") });
+export type CallbackSchema = z.infer<typeof callbackSchema>;
+
+export const channelTemplate = z.object({ "body_parameters": z.array(z.string()).default([]), "buttons": z.array(z.unknown().superRefine((x, ctx) => {
+    const schemas = [quickReplyButtonParam, urlButtonParam];
+    const { errors, failed } = schemas.reduce<{
+      errors: z.core.$ZodIssue[];
+      failed: number;
+    }>(
+      ({ errors, failed }, schema) =>
+        ((result) =>
+          result.error
+            ? {
+                errors: [...errors, ...result.error.issues],
+                failed: failed + 1,
+              }
+            : { errors, failed })(
+          schema.safeParse(x),
+        ),
+      { errors: [], failed: 0 },
+    );
+    const passed = schemas.length - failed;
+    if (passed !== 1) {
+      ctx.addIssue(errors.length ? {
+        path: [],
+        code: "invalid_union",
+        errors: [errors],
+        message: "Invalid input: Should pass single schema. Passed " + passed,
+      } : {
+        path: [],
+        code: "custom",
+        errors: [errors],
+        message: "Invalid input: Should pass single schema. Passed " + passed,
+      });
+    }
+  })).default([]), "header_media": z.union([mediaItem, z.null()]).default(null), "language": z.string(), "name": z.string() });
+export type ChannelTemplate = z.infer<typeof channelTemplate>;
+
+export const conversationRoute = z.object({ "callback_secret": z.union([z.string(), z.null()]).default(null), "callback_url": z.union([z.string(), z.null()]).default(null), "channel": z.union([z.string(), z.null()]).default(null), "door": z.enum(["api","channel"]), "error_reply_text": z.union([z.string().min(1).max(2000), z.null()]).default(null), "execution_key": z.string().min(1), "execution_key_fingerprint": z.string().min(1), "initial_mode": z.enum(["agent","manual"]).default("agent"), "locale": z.union([z.string(), z.null()]).default(null), "our_identity": z.union([z.string(), z.null()]).default(null), "payload_expr": z.union([templatedText, z.null()]).default(null), "reply_expr": z.union([templatedText, z.null()]).default(null), "route_name": z.string(), "target_kind": z.enum(["agent","tool"]), "target_name": z.string().min(1), "turns_per_hour_override": z.union([z.number().int().gt(0), z.null()]).default(null) });
+export type ConversationRoute = z.infer<typeof conversationRoute>;
+
+export const conversationRouteCreate = z.object({ "callback_url": z.union([z.string(), z.null()]).default(null), "channel": z.union([z.string(), z.null()]).default(null), "door": z.enum(["api","channel"]), "error_reply_text": z.union([z.string().min(1).max(2000), z.null()]).default(null), "execution_key": z.string().min(1), "initial_mode": z.enum(["agent","manual"]).default("agent"), "locale": z.union([z.string(), z.null()]).default(null), "our_identity": z.union([z.string(), z.null()]).default(null), "payload_expr": z.union([templatedText, z.null()]).default(null), "reply_expr": z.union([templatedText, z.null()]).default(null), "route_name": z.string(), "target_kind": z.enum(["agent","tool"]), "target_name": z.string().min(1), "turns_per_hour_override": z.union([z.number().int().gt(0), z.null()]).default(null) });
+export type ConversationRouteCreate = z.infer<typeof conversationRouteCreate>;
+
+export const hookParams = z.object({ "condition": z.union([templatedText, z.null()]).default(null), "execution_key": z.string().min(1), "execution_key_fingerprint": z.string().min(1), "expr": z.union([templatedText, z.null()]).default(null), "name": z.string().min(1), "state_binding": z.union([stateBinding, z.null()]).default(null), "subject": z.union([hookSubject, z.null()]).default(null), "tool": z.string().min(1), "tool_kwargs": z.record(z.string(), z.unknown()).default({}), "topic": z.string().min(1) });
+export type HookParams = z.infer<typeof hookParams>;
+
+export const hookRegister = z.object({ "condition": z.union([templatedText, z.null()]).default(null), "execution_key": z.string().min(1), "expr": z.union([templatedText, z.null()]).default(null), "name": z.string().min(1), "state_binding": z.union([stateBinding, z.null()]).default(null), "subject": z.union([hookSubject, z.null()]).default(null), "tool": z.string().min(1), "tool_kwargs": z.record(z.string(), z.unknown()).default({}), "topic": z.string().min(1) });
+export type HookRegister = z.infer<typeof hookRegister>;
+
+export const presetBody = z.object({ "base_tool": z.string(), "description": z.string().default(""), "extensions": z.array(z.array(z.union([z.string(), z.record(z.string(), z.unknown())]))).default([]), "fixed_kwargs": z.record(z.string(), z.unknown()).default({}), "input_schema": z.union([templatedText, z.record(z.string(), z.unknown()), z.null()]).default(null), "output_schema": z.union([templatedText, z.record(z.string(), z.unknown()), z.null()]).default(null), "state_binding": z.union([stateBinding, z.null()]).default(null) });
+export type PresetBody = z.infer<typeof presetBody>;
+
+export const presetSeed = z.object({ "base_tool": z.string(), "description": z.string(), "fixed_kwargs": z.record(z.string(), z.unknown()).default({}), "input_schema": z.union([templatedText, z.record(z.string(), z.unknown()), z.null()]).default(null), "name": z.string(), "output_schema": z.union([templatedText, z.record(z.string(), z.unknown()), z.null()]).default(null), "state_binding": z.union([stateBinding, z.null()]).default(null), "tool_meta": z.union([presetSeedToolMeta, z.null()]).default(null) });
+export type PresetSeed = z.infer<typeof presetSeed>;
+
+export const roleDefinition = z.object({ "allow_all": z.boolean().default(false), "base_tier": z.union([z.string(), z.null()]).default(null), "condition": z.union([templatedText, z.null()]).default(null), "description": z.string(), "grants": z.record(z.string(), z.enum(["none","read","write"])), "name": z.string(), "scopes": z.array(z.string()).default([]) });
+export type RoleDefinition = z.infer<typeof roleDefinition>;
+
+export const stateDeclaration = z.object({ "default_subject_kind": z.string(), "description": z.string().default(""), "effective_schema": z.union([z.record(z.string(), z.unknown()), z.null()]).default(null), "name": z.string(), "regimes": z.union([z.array(z.record(z.string(), z.unknown())), z.null()]).default(null), "retention_days": z.union([z.number().int().gt(0).lte(2147483647), z.null()]).default(null), "schema": z.union([templatedText, z.record(z.string(), z.unknown())]).optional(), "subject_kinds": z.array(z.string()).min(1), "updated_at": z.union([z.string().datetime({ offset: true }), z.null()]).default(null) }).strict();
+export type StateDeclaration = z.infer<typeof stateDeclaration>;
+
+export const stateTemplateDocument = z.object({ "declarations": z.union([stateTemplateDeclarations, z.null()]).default(null), "description": z.string().default(""), "kind": z.literal("state-template").default("state-template"), "name": z.string(), "parameters": z.record(z.string(), z.unknown()).default({}), "reconcile": z.union([stateTemplateReconcile, z.null()]).default(null), "regimes": z.array(z.record(z.string(), z.unknown())).default([]), "schema": z.union([templatedText, z.record(z.string(), z.unknown())]).optional(), "template_jq": z.union([z.record(z.string(), stateTemplateJq), z.null()]).default(null), "trace": z.record(z.string(), z.unknown()).default({}) }).strict();
+export type StateTemplateDocument = z.infer<typeof stateTemplateDocument>;
+
+export const targetConversationConfig = z.object({ "greeting_template": z.union([z.string(), z.null()]).default(null), "multichannel": z.boolean().default(false), "state_binding": z.union([stateBinding, z.null()]).default(null), "target_kind": z.enum(["agent","tool"]), "target_name": z.string().min(1) });
+export type TargetConversationConfig = z.infer<typeof targetConversationConfig>;

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.

package/src/index.ts

@@ -207,6 +207,7 @@ export type {
   Notifications,
   ChannelTemplate,
   HookParams,
+  HookRegister,
   HookSubject,
   HookList,
   TriggerAuth,

package/src/schemas/api-keys.ts

@@ -0,0 +1,26 @@
+/** API-key payload and mint/edit/revoke response schemas. */
+import { z } from 'zod';
+import { templatedText } from './served';
+import { jsonValue } from './shared';
+
+/** The per-key payloads (`GET /api/auth/tokens-payload`). The stable per-mint
+ * `key_fingerprint` is nested under `policy_data`; the picker reads it there. */
+export const tokensPayload = z.array(
+  z.object({
+    // The value an `execution_key` binding names.
+    user_id: z.string().min(1),
+    description: z.string(),
+    scopes: z.array(z.string()),
+    policy_data: jsonValue,
+    condition: templatedText.nullable().optional(),
+  }),
+);
+export type TokensPayload = z.infer<typeof tokensPayload>;
+
+/** Mint reply `{ api_key, key_fingerprint }` narrowed to the raw `sk-…` key,
+ *  returned once at creation and never again. */
+export const createdApiKey = z
+  .object({ api_key: z.string(), key_fingerprint: z.string() })
+  .transform((minted) => minted.api_key);
+export const editApiKeyResult = z.object({ user_id: z.string(), updated: z.boolean() });
+export const revokeApiKeyResult = z.object({ user_id: z.string(), revoked: z.boolean() });

package/src/schemas/auth-routes.ts

@@ -0,0 +1,48 @@
+/** Route catalog, scope mapping and public-route response schemas. */
+import { z } from 'zod';
+
+/** `{ url: scope_id }` — every URL currently mapped to a scope. */
+export const authScopes = z.record(z.string(), z.string());
+
+export const addUrlToScopeResult = z.object({ scope_id: z.string(), url: z.string() });
+export const removeUrlFromScopeResult = z.object({ url: z.string() });
+export const removeScopeResult = z.object({ scope_id: z.string(), deleted_keys: z.number() });
+
+/**
+ * A route's authorization ACTION class, joined onto the catalog from the route
+ * registry. `read`/`write` routes are GRANTABLE — a role's per-tag level opens
+ * them; `fenced`/`secret` routes are ADMIN-ONLY and never grantable (no per-tag
+ * level reaches them). `null` marks a path the registry carries no metadata for
+ * (an unregistered/ungated path — no feature tags, no action).
+ */
+export const routeAction = z.enum(['read', 'write', 'fenced', 'secret']);
+export type RouteAction = z.infer<typeof routeAction>;
+
+/**
+ * One row of the route catalog (`GET /api/auth/routes`) — a plain HTTP route with
+ * its current mapping, JOINED with its route-registry metadata. `mapped` is the
+ * scope id, the public marker, or `null` when the path is unmapped (the mapper's
+ * "unassigned" bucket source). `methods` is the route's method set with `HEAD`
+ * removed. `tags` are the route's feature-group labels, `summary` its one-line
+ * description, and `action` its authorization class — the join fields the Roles
+ * grant editor reads to derive grantable feature groups and mark the admin-only
+ * (fenced/secret) routes it must never offer a grant for. An unregistered path
+ * carries `tags: []`, `summary: ''`, `action: null`.
+ */
+export const authRoute = z.object({
+  path: z.string(),
+  methods: z.array(z.string()),
+  mapped: z.string().nullable(),
+  tags: z.array(z.string()),
+  summary: z.string(),
+  action: routeAction.nullable(),
+});
+export type AuthRoute = z.infer<typeof authRoute>;
+export const authRoutes = z.array(authRoute);
+/** `GET /api/auth/public-routes` — the sorted urls pinned to the public marker. */
+export const publicRoutes = z.array(z.string());
+
+/** `POST /api/auth/public-routes` — the pinned url. */
+export const pinPublicResult = z.object({ url: z.string() });
+/** `DELETE /api/auth/public-routes` — the unpinned url (404 when not pinned). */
+export const unpinPublicResult = z.object({ url: z.string() });