@tai42/api-client 16.0.0 → 17.0.0

package/src/client/auth-client.ts

@@ -0,0 +1,170 @@
+/** Auth scopes, routes, roles and API-key sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+/** Body for creating or editing an API key (POST/PUT `/api/auth/api-keys`). */
+export interface ApiKeyBody {
+  readonly user_id: string;
+  readonly description: string;
+  readonly scopes: string[];
+  // The principal that OWNS the key. Admin-only: an admin may name a service
+  // principal; a non-admin omits it and the server forces self-ownership.
+  readonly owner_user_id?: string;
+  // `null` is an explicit clear on edit (PATCH-style PUT): absent preserves the
+  // stored policy data, `null` wipes it. Create never sends `null`.
+  readonly policy_data?: Record<string, unknown> | null;
+  // The access-control condition: an authored templated-text value (inline content
+  // or a stored template id), or `null` to explicitly clear it on edit.
+  readonly condition?: s.TemplatedText | null;
+}
+
+/**
+ * Body for one-time claim-link creation (POST `/api/auth/claim-links`). The
+ * `api_key` is a raw key the caller holds (the just-minted key, client-side
+ * exactly once); `ttl_seconds` optionally overrides the default lifetime (the
+ * server caps it at its ceiling).
+ */
+export interface ClaimLinkBody {
+  readonly api_key: string;
+  readonly ttl_seconds?: number | null;
+}
+
+/** Body for adding a URL to a scope (POST `/api/auth/scopes`). */
+export interface AddUrlToScopeBody {
+  readonly scope_id: string;
+  readonly url: string;
+  readonly pattern?: string;
+}
+
+/**
+ * Body for creating a role (POST `/api/auth/roles`). `base_tier` is the security
+ * tier the role inherits (`editor`/`viewer` — `admin` is reserved); its jq is
+ * resolved server-side, never authored here. `grants` is the editable per-tag
+ * access-level map (feature-group tag → `none`/`read`/`write`); it defaults to
+ * empty (every group `none`, fail-closed) when omitted.
+ */
+export interface RoleCreateBody {
+  readonly name: string;
+  readonly description?: string;
+  readonly base_tier: string;
+  readonly grants?: Record<string, s.GrantLevel>;
+}
+
+/**
+ * Body for editing a role (PUT `/api/auth/roles/{name}`). Both fields are
+ * omit-means-KEEP: an absent `grants` preserves the stored map (never a silent
+ * wipe), an absent `description` preserves the stored description. The base-tier jq
+ * is seed-fixed and not editable here.
+ */
+export interface RoleUpdateBody {
+  readonly grants?: Record<string, s.GrantLevel>;
+  readonly description?: string;
+}
+
+/**
+ * Body for pinning a route public (POST `/api/auth/public-routes`). `pattern` is an
+ * optional regex the AC verifier full-matches request paths against, mapping every
+ * match to the `url` key (so a mount's whole subtree can be pinned in one call).
+ */
+export interface PinRoutePublicBody {
+  readonly url: string;
+  readonly pattern?: string;
+}
+
+export function authClient(t: Transport) {
+  const { req } = t;
+  return {
+    listScopes: (signal?: AbortSignal) => req('/api/auth/scopes', s.authScopes, { signal }),
+    addUrlToScope: (body: AddUrlToScopeBody) =>
+      req('/api/auth/scopes', s.addUrlToScopeResult, { method: 'POST', body }),
+    removeUrlFromScope: (body: { url: string }) =>
+      req('/api/auth/scopes/urls', s.removeUrlFromScopeResult, { method: 'DELETE', body }),
+    removeScope: (scopeId: string) =>
+      req(`/api/auth/scopes/${encodeSegment(scopeId)}`, s.removeScopeResult, {
+        method: 'DELETE',
+      }),
+    // The app's HTTP route catalog with each route's current mapping — the only
+    // source of the mapper's unassigned-routes bucket (`mapped: null` entries).
+    listAuthRoutes: (signal?: AbortSignal) => req('/api/auth/routes', s.authRoutes, { signal }),
+    // The urls pinned to the public marker; pinning/unpinning is the dedicated
+    // public-routes writer, never the scope machinery.
+    listPublicRoutes: (signal?: AbortSignal) =>
+      req('/api/auth/public-routes', s.publicRoutes, { signal }),
+    pinRoutePublic: (body: PinRoutePublicBody) =>
+      req('/api/auth/public-routes', s.pinPublicResult, { method: 'POST', body }),
+    // Unpin a public url. A url that is absent or scope-mapped is a loud 404.
+    unpinPublicRoute: (url: string) =>
+      req('/api/auth/public-routes', s.unpinPublicResult, { method: 'DELETE', body: { url } }),
+
+    // The seeded + operator-authored roles as full bodies (base-tier ceiling +
+    // editable per-tag grant map). ADMIN-ONLY — the route is `secret` (a listing
+    // exposes each role's raw base-tier jq); a non-admin projection never reaches it.
+    listRoles: (signal?: AbortSignal) => req('/api/auth/roles', s.roleList, { signal }),
+    // Create an operator-authored role. The server validates the grant map + base
+    // tier and 409s on a name collision; the reserved `admin` role cannot be created.
+    createRole: (body: RoleCreateBody) =>
+      req('/api/auth/roles', s.roleBody, { method: 'POST', body }),
+    // Edit a role's per-tag grant map + description (omit-means-keep). The reserved
+    // `admin` role and any `allow_all` role are block-downgrade guarded server-side.
+    updateRole: (name: string, body: RoleUpdateBody) =>
+      req(`/api/auth/roles/${encodeSegment(name)}`, s.roleBody, { method: 'PUT', body }),
+    // Delete a role. The reserved `admin` role is undeletable; a role still assigned
+    // to any principal is a loud 409.
+    deleteRole: (name: string) =>
+      req(`/api/auth/roles/${encodeSegment(name)}`, s.roleDeleted, { method: 'DELETE' }),
+    // A role's append-only version history + who/action/before→after audit trail.
+    // ADMIN-ONLY (`secret`).
+    listRoleVersions: (name: string, signal?: AbortSignal) =>
+      req(`/api/auth/roles/${encodeSegment(name)}/versions`, s.roleVersions, { signal }),
+    // Re-point a role's active version to a prior one (LIVE — holders follow on
+    // their next request); returns the re-pointed role body.
+    rollbackRole: (name: string, version: number) =>
+      req(`/api/auth/roles/${encodeSegment(name)}/rollback`, s.roleBody, {
+        method: 'POST',
+        body: { version },
+      }),
+
+    listTokensPayload: (signal?: AbortSignal) =>
+      req('/api/auth/tokens-payload', s.tokensPayload, { signal }),
+    createApiKey: (body: ApiKeyBody) =>
+      req('/api/auth/api-keys', s.createdApiKey, { method: 'POST', body }),
+    editApiKey: (userId: string, body: Omit<ApiKeyBody, 'user_id'>) =>
+      req(`/api/auth/api-keys/${encodeSegment(userId)}`, s.editApiKeyResult, {
+        method: 'PUT',
+        body,
+      }),
+    revokeApiKey: (userId: string) =>
+      req(`/api/auth/api-keys/${encodeSegment(userId)}`, s.revokeApiKeyResult, {
+        method: 'DELETE',
+      }),
+    // Mint a one-time claim link carrying a raw key to another device (the QR
+    // onboarding leg). The token rides the URL fragment; the server returns a
+    // relative `claim_path` and the raw token ONCE.
+    createClaimLink: (body: ClaimLinkBody) =>
+      req('/api/auth/claim-links', s.claimLinkCreated, { method: 'POST', body }),
+
+    // The deployment's principals (identities). ADMIN-ONLY (`secret`) — a
+    // non-admin projection never reaches the route.
+    listPrincipals: (signal?: AbortSignal) =>
+      req('/api/auth/principals', s.principalList, { signal }),
+    // Create a `human` or `service` principal and apply its role (admin only).
+    // A duplicate id is a loud 409; an unknown role a loud 400.
+    createPrincipal: (body: {
+      user_id?: string;
+      kind: 'human' | 'service';
+      display_name: string;
+      role: string;
+    }) => req('/api/auth/principals', s.principal, { method: 'POST', body }),
+    // Update a principal's display name and/or `disabled` flag (omit-means-keep;
+    // an all-absent body is a loud 400). Disabling turns off every credential the
+    // principal owns.
+    updatePrincipal: (userId: string, body: { display_name?: string; disabled?: boolean }) =>
+      req(`/api/auth/principals/${encodeSegment(userId)}`, s.principal, { method: 'PUT', body }),
+    // Delete a principal — revokes every key it owns and its policy row.
+    deletePrincipal: (userId: string) =>
+      req(`/api/auth/principals/${encodeSegment(userId)}`, s.principalDeleted, {
+        method: 'DELETE',
+      }),
+  };
+}

package/src/client/backend-client.ts

@@ -0,0 +1,25 @@
+/** Backend identity and worker-bus fleet sub-client. */
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function backendClient(t: Transport) {
+  const { req } = t;
+  return {
+    // Backend IDENTITY (`getBackendInfo`, kept on `/api/backend`) is distinct from
+    // the FLEET doors, which ride the app's worker bus and need no backend at all.
+    // `getBackendInfo` reports `present: false` (a 200 empty state) when no backend
+    // plugin is registered. `listFleetWorkers` reads the live bus presence census
+    // (every subscribed worker, ASGI + backend-runtime) and never fabricates an empty
+    // fleet — a census read that fails surfaces as a loud 500.
+    getBackendInfo: (signal?: AbortSignal) => req('/api/backend', s.backendInfo, { signal }),
+    listFleetWorkers: (signal?: AbortSignal) =>
+      req('/api/fleet/workers', s.fleetWorkers, { signal }),
+    // Soft-restart the fleet: `targets` names the workers to reload, or `null` for
+    // the whole fleet. The serving worker applies locally then broadcasts; a 200
+    // response carries the per-worker fleet report, so workers that did not converge
+    // are named, not hidden. A failed local apply instead re-raises as a loud error
+    // (the transport throws with the failure message), not a returned report.
+    reloadFleetConfig: (targets: string[] | null) =>
+      req('/api/fleet/reload-config', s.fleetReloadResult, { method: 'POST', body: { targets } }),
+  };
+}

package/src/client/backup-client.ts

@@ -0,0 +1,16 @@
+/** Backup section listing, export and import sub-client. */
+import { apiDownload } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function backupClient(t: Transport) {
+  const { config, req } = t;
+  return {
+    listBackupSections: (signal?: AbortSignal) =>
+      req('/api/backup/sections', s.backupSections, { signal }),
+    exportBackup: (sections: string[], signal?: AbortSignal): Promise<Blob> =>
+      apiDownload(config, '/api/backup/export', { method: 'POST', body: { sections }, signal }),
+    importBackup: (body: { document: unknown; sections: string[] }) =>
+      req('/api/backup/import', s.backupImportReport, { method: 'POST', body }),
+  };
+}

package/src/client/capabilities-client.ts

@@ -0,0 +1,22 @@
+/** Caller capability projection and auth-capabilities sub-clients. */
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function capabilitiesGetMe(t: Transport) {
+  const { req } = t;
+  return {
+    // The derived (path, method) surface + tools/agents the caller can reach
+    // right now — the projection the Studio filters its nav and pages on.
+    getMe: (signal?: AbortSignal) => req('/api/auth/me', s.meProjection, { signal }),
+  };
+}
+
+export function capabilitiesGetCaps(t: Transport) {
+  const { req } = t;
+  return {
+    // Whether this deployment can mint API keys locally (the settings key-create
+    // UI gates on `mintable`). AUTHED.
+    getAuthCapabilities: (signal?: AbortSignal) =>
+      req('/api/auth/capabilities', s.authCapabilities, { signal }),
+  };
+}

package/src/client/channels-client.ts

@@ -0,0 +1,11 @@
+/** Installed channel-plugin catalog sub-client. */
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function channelsClient(t: Transport) {
+  const { req } = t;
+  return {
+    // The installed channel-plugin names (delivery media for ask_user questions).
+    listChannels: (signal?: AbortSignal) => req('/api/channels', s.channels, { signal }),
+  };
+}

package/src/client/config-client.ts

@@ -0,0 +1,21 @@
+/** Environment-config and reload sub-client. */
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export function configClient(t: Transport) {
+  const { req } = t;
+  return {
+    getEnvConfig: (signal?: AbortSignal) => req('/api/config/env', s.envConfig, { signal }),
+    setEnvConfig: (env: Record<string, string>) =>
+      req('/api/config/env', s.reloadConfigResult, { method: 'POST', body: env }),
+    getConfigMode: (signal?: AbortSignal) => req('/api/config/mode', s.configMode, { signal }),
+    // The LOCAL soft-restart door (distinct from the System page's fleet door
+    // `/api/fleet/reload-config`): refresh env from the config manager, reset the
+    // settings caches, and re-initialize from the manifest — applied on the serving
+    // worker and broadcast to the fleet (all workers, or only `targets`; `null` = all).
+    // Admin-`fenced`; the 200 body is the bare per-worker fleet report so an
+    // unconverged sibling is visible, never hidden.
+    reloadConfig: (targets: string[] | null = null) =>
+      req('/api/config/reload', s.fleetReloadResult, { method: 'POST', body: { targets } }),
+  };
+}

package/src/client/connectors-client.ts

@@ -0,0 +1,52 @@
+/** Connector provider and connection lifecycle sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+export interface StartConnectArgs {
+  readonly provider_id: string;
+  readonly alias: string;
+  readonly enabled_sub_services: string[];
+  readonly config_values?: Record<string, string>;
+  readonly return_url?: string;
+}
+
+export function connectorsClient(t: Transport) {
+  const { req } = t;
+  return {
+    listProviders: (signal?: AbortSignal) =>
+      req('/api/connectors/providers', s.providers, { signal }),
+    listConnections: (signal?: AbortSignal) =>
+      req('/api/connectors/connections', s.connectionsList, { signal }),
+    getConnection: (id: string, signal?: AbortSignal) =>
+      req(`/api/connectors/connections/${encodeSegment(id)}`, s.connectionView, { signal }),
+    startConnect: (args: StartConnectArgs) =>
+      req('/api/connectors/connections/start', s.startConnectResult, {
+        method: 'POST',
+        body: args,
+      }),
+    disconnect: (id: string) =>
+      req(`/api/connectors/connections/${encodeSegment(id)}`, s.disconnectResult, {
+        method: 'DELETE',
+      }),
+    reconnect: (id: string, enabled_sub_services: string[], return_url?: string) =>
+      req(`/api/connectors/connections/${encodeSegment(id)}/reconnect`, s.reconnectResult, {
+        method: 'POST',
+        body: { enabled_sub_services, return_url },
+      }),
+    patchSubServices: (id: string, enabled_sub_services: string[], return_url?: string) =>
+      req(
+        `/api/connectors/connections/${encodeSegment(id)}/sub-services`,
+        s.patchSubServicesResult,
+        {
+          method: 'PATCH',
+          body: { enabled_sub_services, return_url },
+        },
+      ),
+    completeOAuth: (state: string, code: string, error?: string) =>
+      req('/api/connectors/oauth/complete', s.oauthCompleteResult, {
+        method: 'POST',
+        body: { state, code, error },
+      }),
+  };
+}

package/src/client/conversations-client.ts

@@ -0,0 +1,240 @@
+/** Conversation route, thread, transcript, config and admin sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+/**
+ * The thread-list filter set (GET `/api/conversations/{route}/threads` query
+ * params, alongside `page`/`pageSize`). `status` narrows to threads whose newest
+ * record sits in one delivery state; `address` is a SUBSTRING match over the
+ * client address. Both omitted when undefined — an unfiltered listing.
+ */
+export interface ConversationThreadFilters {
+  readonly status?: s.ConversationDeliveryStatus;
+  readonly address?: string;
+}
+
+/**
+ * One transcript read (GET `/api/conversations/{route}/transcript` query params).
+ * `order` is not a default the caller may skip: `asc` reads the thread from its
+ * beginning and `desc` from its newest end, and which one a screen wants is a
+ * decision that screen must make. `q` narrows the page to records whose text
+ * matches it (a SUBSTRING), omitted for an unfiltered read.
+ */
+export interface ConversationTranscriptQuery {
+  readonly routeName: string;
+  readonly threadId: string;
+  readonly page: number;
+  readonly pageSize: number;
+  readonly order: s.TranscriptOrder;
+  readonly q?: string;
+}
+
+/**
+ * A route-scoped message search (GET
+ * `/api/conversations/{route}/messages/search` query params). `q` is the required
+ * needle — a substring over record text, across every thread on the route; `page`
+ * is supplied per-request by the infinite query.
+ */
+export interface ConversationMessageSearchQuery {
+  readonly routeName: string;
+  readonly q: string;
+  readonly page: number;
+  readonly pageSize: number;
+}
+
+/**
+ * Body for sending a message into a thread (POST
+ * `/api/conversations/{route}/thread/messages`). `thread_id` names the thread
+ * (an api-door address, passed as a value); `text` is the message. `address` is
+ * an optional override the server otherwise derives from the thread, omitted
+ * when undefined.
+ */
+export interface ConversationThreadMessageBody {
+  readonly thread_id: string;
+  readonly text: string;
+  readonly address?: string;
+}
+
+/** Route CRUD: the stored routing rows and their create/replace/delete doors. */
+function conversationRouteMethods(t: Transport) {
+  const { req } = t;
+  return {
+    // The stored routing rows, each with its `callback_secret` withheld — the
+    // conversation monitor's route picker.
+    listConversationRoutes: (signal?: AbortSignal) =>
+      req('/api/conversations', s.conversationRoutes, { signal }),
+    // Create or REPLACE a route (an UPSERT: the same door is the create and the
+    // edit path). `route_name` rides the URL path AND the body; the door rejects a
+    // disagreeing pair, so both come from the one create object. The reply carries
+    // the freshly-minted `callback_secret` for an `api`-door row, returned ONCE.
+    createOrReplaceConversationRoute: (route: s.ConversationRouteCreate) =>
+      req(`/api/conversations/${encodeSegment(route.route_name)}`, s.conversationRouteWritten, {
+        method: 'POST',
+        body: route,
+      }),
+    // Delete a route by name (destructive + authority-changing server-side): it
+    // drops the routing row and reclaims the thread indexes it owned.
+    deleteConversationRoute: (routeName: string) =>
+      req(`/api/conversations/${encodeSegment(routeName)}`, s.conversationRouteDeleted, {
+        method: 'DELETE',
+      }),
+  };
+}
+
+/** Thread reads and writes: listings, transcript, message search, send, reply mode. */
+function conversationThreadMethods(t: Transport) {
+  const { req } = t;
+  return {
+    // One route's threads, newest activity first. Admin-only server-side: a
+    // listing spans every caller on the route, so a scoped session gets a 403.
+    listConversationThreads: (
+      routeName: string,
+      page: number,
+      pageSize: number,
+      filters: ConversationThreadFilters = {},
+      signal?: AbortSignal,
+    ) =>
+      req(`/api/conversations/${encodeSegment(routeName)}/threads`, s.conversationThreadsPage, {
+        signal,
+        query: { page, pageSize, status: filters.status, address: filters.address },
+      }),
+    // One thread's transcript, caller-scoped, read in the asked-for direction.
+    // The `thread_id` rides the QUERY STRING, never the path: it embeds the api
+    // door's `{principal}/{end user}` address with the principal already
+    // percent-encoded, which a path segment would have to encode a second time
+    // and the server would then decode once too few. A query value is decoded
+    // exactly once whatever it holds, so it is passed through verbatim.
+    readConversationTranscript: (query: ConversationTranscriptQuery, signal?: AbortSignal) =>
+      req(
+        `/api/conversations/${encodeSegment(query.routeName)}/transcript`,
+        s.conversationTranscriptPage,
+        {
+          signal,
+          query: {
+            thread_id: query.threadId,
+            page: query.page,
+            pageSize: query.pageSize,
+            order: query.order,
+            q: query.q,
+          },
+        },
+      ),
+    // Search every record on a route by text, across threads, newest first. The
+    // needle rides the QUERY (`q`); paging is the infinite query's own window. The
+    // page's `truncated` flag says the match set outran the door's scan cap.
+    searchConversationMessages: (query: ConversationMessageSearchQuery, signal?: AbortSignal) =>
+      req(
+        `/api/conversations/${encodeSegment(query.routeName)}/messages/search`,
+        s.conversationMessageSearchPage,
+        { signal, query: { q: query.q, page: query.page, pageSize: query.pageSize } },
+      ),
+    // Send a human message into a thread. The `thread_id` rides the BODY (a POST,
+    // never a path segment) — same encode-once reasoning as the transcript read.
+    sendConversationThreadMessage: (routeName: string, body: ConversationThreadMessageBody) =>
+      req(
+        `/api/conversations/${encodeSegment(routeName)}/thread/messages`,
+        s.conversationThreadMessageSent,
+        { method: 'POST', body },
+      ),
+    // Read a thread's reply mode (`agent`/`manual`) and where it comes from. The
+    // `thread_id` rides the QUERY value, encoded once, as the transcript read does.
+    getConversationThreadMode: (routeName: string, threadId: string, signal?: AbortSignal) =>
+      req(
+        `/api/conversations/${encodeSegment(routeName)}/thread/mode`,
+        s.conversationThreadModeState,
+        { signal, query: { thread_id: threadId } },
+      ),
+    // Flip a thread's reply mode. The `thread_id` rides the BODY (a PUT).
+    setConversationThreadMode: (
+      routeName: string,
+      threadId: string,
+      mode: s.ConversationThreadMode,
+    ) =>
+      req(
+        `/api/conversations/${encodeSegment(routeName)}/thread/mode`,
+        s.conversationThreadModeState,
+        { method: 'PUT', body: { thread_id: threadId, mode } },
+      ),
+  };
+}
+
+/** Per-target presentation configs, keyed by `(target_kind, target_name)`. Admin surface. */
+function conversationConfigMethods(t: Transport) {
+  const { req } = t;
+  return {
+    // The stored per-target presentation configs (each `(target_kind, target_name)`
+    // pair's multichannel flag + first-contact greeting). Admin config surface.
+    listConversationConfigs: (signal?: AbortSignal) =>
+      req('/api/conversation-configs', s.conversationConfigs, { signal }),
+    // One config by its `(target_kind, target_name)` key. 404 when unknown.
+    getConversationConfig: (
+      targetKind: s.ConversationTargetKind,
+      targetName: string,
+      signal?: AbortSignal,
+    ) =>
+      req(
+        `/api/conversation-configs/${encodeSegment(targetKind)}/${encodeSegment(targetName)}`,
+        s.targetConversationConfig,
+        { signal },
+      ),
+    // Create or REPLACE a config (an UPSERT: the same door is the create and the
+    // edit path). The `(target_kind, target_name)` key rides the URL path; the door
+    // rejects a body whose key disagrees, so both come from the one config object.
+    setConversationConfig: (config: s.TargetConversationConfig) =>
+      req(
+        `/api/conversation-configs/${encodeSegment(config.target_kind)}/${encodeSegment(config.target_name)}`,
+        s.conversationConfigWritten,
+        { method: 'PUT', body: config },
+      ),
+    // Delete a config by its key. 404 when the key is unknown.
+    deleteConversationConfig: (targetKind: s.ConversationTargetKind, targetName: string) =>
+      req(
+        `/api/conversation-configs/${encodeSegment(targetKind)}/${encodeSegment(targetName)}`,
+        s.conversationConfigDeleted,
+        { method: 'DELETE' },
+      ),
+  };
+}
+
+/** Admin/GDPR doors: failed-message audit and destructive thread/person erasure. */
+function conversationAdminMethods(t: Transport) {
+  const { req } = t;
+  return {
+    // Every answer record whose delivery ended `failed`, across every route and
+    // caller. Admin-only server-side; not a paged window (returns `{items, total}`).
+    listFailedConversationMessages: (signal?: AbortSignal) =>
+      req('/api/conversations/messages/failed', s.conversationFailedMessages, { signal }),
+    // Forget ONE thread on a route (destructive): its checkpoint, answer records and
+    // thread indexes. The `thread_id` rides the QUERY value, encoded once — it embeds
+    // the api door's percent-encoded `{principal}/{end user}` address, which a path
+    // segment would encode a second time. `removed` counts the records this call
+    // cleared; a valid id on its own route always succeeds, never a 404.
+    deleteConversationThread: (routeName: string, threadId: string) =>
+      req(`/api/conversations/${encodeSegment(routeName)}/thread`, s.conversationThreadDeleted, {
+        method: 'DELETE',
+        query: { thread_id: threadId },
+      }),
+    // Erase a LINKED person ENTIRELY (GDPR, wide blast radius): its aggregated thread
+    // and checkpoint, its person row, and every address→person index mapping, across
+    // EVERY route it wrote under. The `person_id` is a uuid4 with no percent-encoded
+    // principal, so it rides the PATH cleanly. `erased` says whether this call removed
+    // the person row (idempotent — a retry answers `false`, never a 404).
+    deleteConversationPerson: (personId: string) =>
+      req(`/api/conversations/persons/${encodeSegment(personId)}`, s.conversationPersonDeleted, {
+        method: 'DELETE',
+      }),
+  };
+}
+
+export function conversationsClient(t: Transport) {
+  // Declaration emit prepends each spread group's members, so the groups are
+  // spread in reverse of their public order to keep the surface route → thread
+  // → config → admin.
+  return {
+    ...conversationAdminMethods(t),
+    ...conversationConfigMethods(t),
+    ...conversationThreadMethods(t),
+    ...conversationRouteMethods(t),
+  };
+}

package/src/client/hooks-client.ts

@@ -0,0 +1,44 @@
+/** Hook listing, registration and topic-verifier sub-client. */
+import { encodeSegment } from '../http';
+import * as s from '../schemas';
+import type { Transport } from './transport';
+
+/**
+ * Body for binding a webhook verifier to a topic
+ * (PUT `/api/hooks/topics/{topic}/verifier`). `verifier` is a registered verifier
+ * NAME, resolved against the live registry at bind time (an unknown name is a loud
+ * 400). `config` is that verifier's config object — it carries a `secret_env` name,
+ * never a secret value — and defaults to `{}` when omitted.
+ */
+export interface TopicVerifierBody {
+  readonly verifier: string;
+  readonly config?: Record<string, unknown>;
+}
+
+export function hooksClient(t: Transport) {
+  const { req } = t;
+  return {
+    listHooks: (topic?: string, signal?: AbortSignal) =>
+      req('/api/hooks', s.hookList, { signal, query: topic === undefined ? undefined : { topic } }),
+    registerHook: (params: s.HookRegister) =>
+      req('/api/hooks', s.hookRegistered, { method: 'POST', body: params }),
+    unregisterHook: (name: string) =>
+      req(`/api/hooks/${encodeSegment(name)}`, s.hookRemoved, { method: 'DELETE' }),
+    // The registered webhook-verifier catalog — the only source the bind picker
+    // reads (names only; an empty registry is a valid empty list).
+    listHookVerifiers: (signal?: AbortSignal) =>
+      req('/api/hooks/verifiers', s.hookVerifiers, { signal }),
+    // Bind a verifier to a topic (locks its otherwise-open public ingress). A PUT
+    // replaces any existing binding; an unknown verifier name is a loud 400.
+    setTopicVerifier: (topic: string, body: TopicVerifierBody) =>
+      req(`/api/hooks/topics/${encodeSegment(topic)}/verifier`, s.topicVerifierSet, {
+        method: 'PUT',
+        body,
+      }),
+    // Unbind a topic's verifier (re-opens its public ingress). 404 when no binding.
+    deleteTopicVerifier: (topic: string) =>
+      req(`/api/hooks/topics/${encodeSegment(topic)}/verifier`, s.topicVerifierRemoved, {
+        method: 'DELETE',
+      }),
+  };
+}