@tai42/api-client 19.3.0 → 21.0.0

package/src/headers.ts

@@ -0,0 +1,4 @@
+/** The platform's request header names the browser sends. */
+
+/** The platform's API-key header (contract `tai42_contract.access_control.API_KEY_HEADER`). */
+export const API_KEY_HEADER = 'x-api-key';

package/src/http.ts

@@ -10,6 +10,7 @@
 import type { z } from 'zod';
 
 import { ApiConflictError, ApiError, ApiSchemaError, ApiUnauthorizedError } from './errors';
+import { API_KEY_HEADER } from './headers';
 
 /** Supplies the current API key (in-memory or sessionStorage-backed) + base URL. */
 export interface ApiConfig {
@@ -153,7 +154,7 @@ export async function apiRequest<S extends z.ZodType>(
   const doFetch = config.fetch ?? globalThis.fetch;
   const token = config.getToken();
   const headers: Record<string, string> = { ...JSON_HEADERS };
-  if (token) headers['x-api-key'] = token;
+  if (token) headers[API_KEY_HEADER] = token;
 
   const response = await doFetch(buildUrl(config.baseUrl ?? '', path, options.query), {
     method: options.method ?? 'GET',
@@ -183,7 +184,7 @@ export async function apiText(
   const doFetch = config.fetch ?? globalThis.fetch;
   const token = config.getToken();
   const headers: Record<string, string> = {};
-  if (token) headers['x-api-key'] = token;
+  if (token) headers[API_KEY_HEADER] = token;
 
   const response = await doFetch(buildUrl(config.baseUrl ?? '', path, options.query), {
     method: options.method ?? 'GET',
@@ -211,7 +212,7 @@ export async function apiDownload(
   const token = config.getToken();
   const headers: Record<string, string> = {};
   if (options.body !== undefined) Object.assign(headers, JSON_HEADERS);
-  if (token) headers['x-api-key'] = token;
+  if (token) headers[API_KEY_HEADER] = token;
 
   const response = await doFetch(buildUrl(config.baseUrl ?? '', path, options.query), {
     method: options.method ?? 'GET',

package/src/index.ts

@@ -8,6 +8,7 @@
 export type { AgentEvent, AgentSummary, ParsedAgentEvent, UnknownAgentEvent } from './agents';
 export { agentEventSchema, parseAgentFrame, parseAgentTranscript } from './agents';
 export type {
+  AddServerArgs,
   AddUrlToScopeBody,
   ApiClient,
   ApiKeyBody,
@@ -18,6 +19,7 @@ export type {
   ConversationThreadMessageBody,
   ConversationTranscriptQuery,
   CreatePresetBody,
+  DiscoverServerTarget,
   MarketplaceInstallBody,
   MarketplaceInstallPreviewBody,
   MarketplaceSearchQuery,
@@ -29,6 +31,7 @@ export type {
   RunsQuery,
   RunToolArgs,
   SavePresetVersionBody,
+  SetProviderClientArgs,
   StartConnectArgs,
   StateAttachmentBody,
   StateDeclarationBody,
@@ -42,7 +45,6 @@ export type {
   TriggerLinkCreateBody,
   ValidateConditionBody,
   ValidatePresetBody,
-  WebEntryCodeMintBody,
 } from './client';
 export { createApiClient, isSafeApiPath } from './client';
 export {
@@ -58,6 +60,7 @@ export type {
   FleetFailureOutcome,
   FleetReportStatus,
   FleetReportSummary,
+  FleetWorkerAwaitingRespawn,
   FleetWorkerFailure,
 } from './fleet-report';
 export {
@@ -66,10 +69,14 @@ export {
   summarizeFleetFanout,
   summarizeFleetResult,
 } from './fleet-report';
+export type { ApiOperationId, ApiPathPrefix, ApiPathTemplate } from './generated/api-routes';
+export { apiPathPrefixes, apiRoutes, buildPath } from './generated/api-routes';
+export { API_KEY_HEADER } from './headers';
 export type { ApiConfig, RequestOptions } from './http';
 export { apiDownload, apiRequest, apiText } from './http';
 export type {
   AnswerFormat,
+  ApiConversationRouteCreate,
   ApplyResult,
   AttachmentMediaItem,
   AttachmentMediaKind,
@@ -78,7 +85,9 @@ export type {
   BackendInfo,
   BackupDocument,
   BackupImportReport,
-  CallerAsksEnvelope,
+  BackupNewApiKeys,
+  BackupSectionReport,
+  ChannelConversationRouteCreate,
   Channels,
   ChannelTemplate,
   ClaimLinkCreated,
@@ -104,6 +113,7 @@ export type {
   ConversationRouteCreate,
   ConversationRouteDeleted,
   ConversationRoutes,
+  ConversationRouteView,
   ConversationRouteWritten,
   ConversationTargetKind,
   ConversationThread,
@@ -114,6 +124,7 @@ export type {
   ConversationThreadsPage,
   ConversationTranscriptPage,
   DashboardMetrics,
+  DiscoveredServer,
   DisplayBlock,
   DisplayBlockKind,
   Extension,
@@ -132,7 +143,9 @@ export type {
   FormPages,
   FormReactions,
   FormUpdate,
+  FreshLife,
   GrantLevel,
+  HeldPendingSave,
   HookList,
   HookParams,
   HookRegister,
@@ -141,7 +154,10 @@ export type {
   InteractionAnswered,
   InteractionCancelled,
   InteractionMediaItem,
+  InteractionReaction,
   InteractionsPage,
+  InviteRow,
+  InvokeMemberActionResult,
   KindStatus,
   LoginFormField,
   LoginMethod,
@@ -180,13 +196,24 @@ export type {
   McpEnvRefs,
   McpReloadResult,
   MediaKind,
+  MemberActionCatalog,
+  MemberActionDescriptor,
+  MemberActionScope,
+  MemberDirectory,
+  MemberPrincipalState,
+  MemberRow,
   MeProjection,
   Notification,
   Notifications,
   OAuthCompleteResult,
+  ObservabilityCapabilities,
   ParkedCallerAsk,
   ParkedStatus,
   PatternEntry,
+  PendingSave,
+  PendingSaveRetried,
+  PendingSavesPage,
+  PendingSaveStatus,
   PolicyBody,
   PolicyVersion,
   PresetBody,
@@ -198,14 +225,22 @@ export type {
   PresetValidation,
   PresetVersion,
   PresetVersionTags,
+  PreviousProfileName,
   Principal,
+  PrincipalKind,
   PrincipalRef,
   ProviderCatalogResponse,
+  ProviderMutationResult,
   ProviderView,
   ReactionEvent,
   ReactionEventKind,
   RecordSearchPage,
+  RecycleEntry,
+  RecycleRoll,
+  RecycleStop,
   ReloadConfigResult,
+  RemoveProviderResult,
+  ResolvedSpanValue,
   RoleAuditEvent,
   RoleBody,
   RoleGrants,
@@ -214,12 +249,20 @@ export type {
   RouteAction,
   RouteEntry,
   Run,
+  RunAnswer,
   RunSpan,
+  RunSpanOutline,
   RunTrace,
-  ScheduleItem,
+  RunTraceOutline,
+  ScheduleCreate,
+  ScheduleListRow,
+  ScheduleRecord,
+  ServedConstants,
+  SettingsProfileName,
   SettingsSchema,
   SetupBody,
   SetupResult,
+  SpanKind,
   StateAttach,
   StateAttached,
   StateAttachment,
@@ -227,26 +270,29 @@ export type {
   StateBinding,
   StateConsumers,
   StateDeclaration,
+  StateDeclarationSaved,
   StateDetached,
   StateDetail,
   StateFoldReport,
   StateInjection,
   StateListItem,
   StateRecord,
+  StateRegimeRule,
   StateRetentionPruned,
   StateStats,
   StateSubject,
   StateTemplateDocument,
   StateTemplateListItem,
+  StateTemplateParameter,
+  StateTemplateTrace,
   StateUpdate,
   StorageInfo,
   StorageResourceStat,
-  StudioPluginManifest,
+  StudioPluginListingEntry,
   SubjectPage,
   SubjectRow,
   SubMcpEntry,
   SubMcpMount,
-  SuspendedRunReceipt,
   TargetConversationConfig,
   TemplateDeclarations,
   TemplatedText,
@@ -270,17 +316,13 @@ export type {
   TriggerLinkRecord,
   ValidateConditionResult,
   VisitOutcome,
-  WebEntryCode,
-  WebEntryCodeMinted,
-  WebEntryCodeRevoked,
-  WebEntryGate,
-  WebEntryGateState,
   WorkerKind,
   WorkerLastOp,
   WorkerState,
   WriteEntry,
   WritesPage,
 } from './schemas';
+export { runAnswer, servedConstants, servedDocumentsJson, servedVectors } from './schemas';
 export * as schemas from './schemas';
 export type { SseFrame } from './sse';
 export { readSseFrames, SseFrameParser } from './sse';

package/src/schemas/api-keys.ts

@@ -1,34 +1,18 @@
 /** API-key payload and mint/edit/revoke response schemas. */
 import { z } from 'zod';
 
-import { principalRef } from './principals';
-import { templatedText } from './served';
-import { jsonValue } from './shared';
+import * as openapi from '../generated/openapi-schemas';
 
 /** 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(),
-    // The key's OWNER principal (kind + display name); `null` for a key whose
-    // principal row is absent (an orphaned restore state).
-    principal: principalRef.nullable().optional(),
-    // `true` for a key whose owning principal row is gone (an orphaned key that a
-    // backup restore left without its principal).
-    orphaned: z.boolean().optional(),
-  }),
-);
+ * `key_fingerprint` is nested under `policy_data`; the picker reads it there. `principal`
+ * is the key's OWNER (`null` for a key whose principal row is absent), `orphaned` is `true`
+ * for a key whose owning principal row is gone. */
+export const tokensPayload = openapi.tokenPayloadList;
 export type TokensPayload = z.infer<typeof tokensPayload>;
 
+// Hand-written: the client narrows the mint reply to the raw key it shows once.
 /** 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() });
+export const createdApiKey = openapi.apiKeyCreateResult.transform((minted) => minted.api_key);
+export const editApiKeyResult = openapi.userUpdateAck;
+export const revokeApiKeyResult = openapi.revokeAck;

package/src/schemas/auth-routes.ts

@@ -1,22 +1,14 @@
 /** Route catalog, scope mapping and public-route response schemas. */
-import { z } from 'zod';
+import type { z } from 'zod';
 
-/** `{ url: scope_id }` — every URL currently mapped to a scope. */
-export const authScopes = z.record(z.string(), z.string());
+import * as openapi from '../generated/openapi-schemas';
 
-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() });
+/** `{ url: scope_id }` — every URL currently mapped to a scope. */
+export const authScopes = openapi.scopeUrlMap;
 
-/**
- * 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>;
+export const addUrlToScopeResult = openapi.scopeUrlAck;
+export const removeUrlFromScopeResult = openapi.urlAck;
+export const removeScopeResult = openapi.scopeDeleteResult;
 
 /**
  * One row of the route catalog (`GET /api/auth/routes`) — a plain HTTP route with
@@ -27,22 +19,29 @@ export type RouteAction = z.infer<typeof routeAction>;
  * 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`.
+ * carries `tags: []`, `summary: ''`, `action: null`. `declared_public` is `true` for
+ * a route its registration declares public: it is served without authentication
+ * and no scope mapping or public pin changes that, so the mapper never offers it
+ * for a scope.
  */
-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 const authRoute = openapi.routeMappingRow;
 export type AuthRoute = z.infer<typeof authRoute>;
-export const authRoutes = z.array(authRoute);
+export const authRoutes = openapi.routeMappingList;
+
+/**
+ * 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` on a row marks a path the registry carries no metadata
+ * for (an unregistered/ungated path — no feature tags, no action).
+ */
+export const routeAction = openapi.routeMappingRow.shape.action.unwrap();
+export type RouteAction = z.infer<typeof routeAction>;
+
 /** `GET /api/auth/public-routes` — the sorted urls pinned to the public marker. */
-export const publicRoutes = z.array(z.string());
+export const publicRoutes = openapi.stringList;
 
 /** `POST /api/auth/public-routes` — the pinned url. */
-export const pinPublicResult = z.object({ url: z.string() });
+export const pinPublicResult = openapi.urlAck;
 /** `DELETE /api/auth/public-routes` — the unpinned url (404 when not pinned). */
-export const unpinPublicResult = z.object({ url: z.string() });
+export const unpinPublicResult = openapi.urlAck;

package/src/schemas/backup.ts

@@ -1,43 +1,45 @@
 /** Backup section, document and import-report response schemas. */
 import { z } from 'zod';
 
+import * as openapi from '../generated/openapi-schemas';
 import { fleetReportFanout } from './fleet';
 
-export const backupSections = z.array(z.object({ name: z.string(), secret: z.boolean() }));
+export const backupSections = openapi.backupSectionListing;
 
-/** The exported backup document — validated when the UI reads a picked file. */
-export const backupDocument = z.object({
+/**
+ * A backup document as the import door accepts it — validated when the UI reads a picked
+ * file. Hand-written over the export's document: the import door takes `version` 1 and a
+ * `sections` object, and the export's `errors` map is optional there.
+ */
+export const backupDocument = openapi.backupExportDocument.extend({
   version: z.literal(1),
-  created_at: z.string(),
-  sections: z.record(z.string(), z.unknown()),
-  errors: z.record(z.string(), z.string()).optional(),
+  errors: openapi.backupExportDocument.shape.errors.optional(),
 });
 export type BackupDocument = z.infer<typeof backupDocument>;
 
-export const backupImportReport = z.object({
-  ok: z.boolean(),
-  sections: z.record(
-    z.string(),
-    z.object({
-      created: z.number(),
-      updated: z.number(),
-      skipped: z.number(),
-      errors: z.array(z.string()),
-      new_api_keys: z
-        .array(
-          z.object({
-            user_id: z.string(),
-            description: z.string(),
-            api_key: z.string(),
-          }),
-        )
-        .optional(),
-      // The `manifest` and `env` sections apply through the config pipeline, so their
-      // report carries the mode-wrapped fleet `fanout` of the restore's reload; other
-      // sections omit it. Parsed EXPLICITLY so the shared fleet-report handler can
-      // surface a failed restore propagation — otherwise zod would strip it silently.
-      fanout: fleetReportFanout.optional(),
-    }),
-  ),
+// Hand-written: the spec publishes a section's fan-out as one object with optional fields
+// and its `details` as an open map; the client discriminates the fan-out's modes and reads
+// the keys a restore minted.
+/** The api keys a restore minted, shown once: carried in a section report's `details`. */
+export const backupNewApiKeys = z.array(
+  z.object({ user_id: z.string(), description: z.string(), api_key: z.string() }),
+);
+export type BackupNewApiKeys = z.infer<typeof backupNewApiKeys>;
+
+export const backupSectionReport = openapi.backupSectionReport.extend({
+  // The `manifest` and `env` sections apply through the config pipeline, so their
+  // report carries the mode-wrapped fleet `fanout` of the restore's reload; other
+  // sections carry `null`. Parsed EXPLICITLY so the shared fleet-report handler can
+  // surface a failed restore propagation.
+  fanout: fleetReportFanout.nullable().default(null),
+  details: z
+    .object({ new_api_keys: backupNewApiKeys.optional() })
+    .catchall(z.unknown())
+    .default({}),
+});
+export type BackupSectionReport = z.infer<typeof backupSectionReport>;
+
+export const backupImportReport = openapi.backupImportResult.extend({
+  sections: z.record(z.string(), backupSectionReport),
 });
 export type BackupImportReport = z.infer<typeof backupImportReport>;

package/src/schemas/capabilities.ts

@@ -1,32 +1,27 @@
 /** Caller capability projection and auth-capabilities schemas. */
-import { z } from 'zod';
+import type { z } from 'zod';
 
-import { principalRef } from './principals';
-import { subMcpMount } from './sub-mcp';
+import * as openapi from '../generated/openapi-schemas';
 
 /** A concrete route the caller can reach, with the methods that pass its jq fence. */
-export const routeEntry = z.object({
-  path: z.string(),
-  methods: z.array(z.string()),
-});
+export const routeEntry = openapi.routeEntry;
 export type RouteEntry = z.infer<typeof routeEntry>;
 
 /**
  * A dynamic route pattern the caller can reach — a mount/pattern surface not
  * enumerable into concrete paths, projected only when its scope AND jq admit it.
+ * `open_prefix` is the literal path prefix the pattern opens, or `null` when the pattern
+ * opens none a prefix test can read.
  */
-export const patternEntry = z.object({
-  pattern: z.string(),
-  scope_id: z.string(),
-});
+export const patternEntry = openapi.patternEntry;
 export type PatternEntry = z.infer<typeof patternEntry>;
 
 /**
- * A sub-MCP mount the caller can reach, with the tools it exposes and its
- * transport. Shares the {@link subMcpMount} shape with the registry list, adding
- * the `slug` the projection carries inline (the list keys mounts by slug instead).
+ * A sub-MCP mount the caller can reach, with the tools it exposes, its transport and
+ * its served mount URL and access pattern, and the `slug` the projection carries inline
+ * (the registry list keys mounts by slug instead).
  */
-export const subMcpEntry = subMcpMount.extend({ slug: z.string() });
+export const subMcpEntry = openapi.subMcpEntry;
 export type SubMcpEntry = z.infer<typeof subMcpEntry>;
 
 /**
@@ -37,23 +32,12 @@ export type SubMcpEntry = z.infer<typeof subMcpEntry>;
  * session carries `admin: false` and a jq-exact `routes` list. `owner_user_id` is
  * the key's owner claim, `null` for a key with no owner claim. `principal` is the
  * caller's principal (kind + display name), `null` when no principal row backs the
- * credential. The invariant is projection ⊆ gate: every projected surface is one
+ * credential. `public_resource_id` is the deployment's reserved public marker (the
+ * route-table id a public route maps to — never a scope). The invariant is projection ⊆ gate: every projected surface is one
  * the server would admit, so the UI can filter on it without ever advertising a
  * door the gate denies.
  */
-export const meProjection = z.object({
-  user_id: z.string(),
-  owner_user_id: z.string().nullable(),
-  principal: principalRef.nullable().optional(),
-  admin: z.boolean(),
-  scopes: z.array(z.string()),
-  routes: z.array(routeEntry),
-  route_patterns: z.array(patternEntry),
-  sub_mcp: z.array(subMcpEntry),
-  tools: z.array(z.string()),
-  agents: z.array(z.string()),
-  mintable: z.boolean(),
-});
+export const meProjection = openapi.projectionResult;
 export type MeProjection = z.infer<typeof meProjection>;
 
 /**
@@ -62,11 +46,7 @@ export type MeProjection = z.infer<typeof meProjection>;
  * absolute URL — the Studio composes the origin); `token` is the raw claim token
  * returned exactly ONCE; `expires_at` is an ISO-8601 instant.
  */
-export const claimLinkCreated = z.object({
-  claim_path: z.string(),
-  token: z.string(),
-  expires_at: z.string(),
-});
+export const claimLinkCreated = openapi.claimLinkResult;
 export type ClaimLinkCreated = z.infer<typeof claimLinkCreated>;
 
 /**
@@ -76,7 +56,7 @@ export type ClaimLinkCreated = z.infer<typeof claimLinkCreated>;
  * `revoked: false` body. Non-strict, so a SUCCESSFUL logout never throws
  * `ApiSchemaError` on an additive field.
  */
-export const logoutResult = z.object({ revoked: z.boolean() });
+export const logoutResult = openapi.logoutResult;
 export type LogoutResult = z.infer<typeof logoutResult>;
 
 /**
@@ -85,8 +65,5 @@ export type LogoutResult = z.infer<typeof logoutResult>;
  * validator-only (keys are issued at an external issuer), so the key-creation
  * UI disables up front instead of surfacing a raw mint failure. Non-strict.
  */
-export const authCapabilities = z.object({
-  mintable: z.boolean(),
-  providers: z.array(z.object({ name: z.string(), mintable: z.boolean() })),
-});
+export const authCapabilities = openapi.mintCapabilities;
 export type AuthCapabilities = z.infer<typeof authCapabilities>;

package/src/schemas/channels.ts

@@ -1,11 +1,11 @@
 /** Installed channel-plugin catalog response schema. */
-import { z } from 'zod';
+import type { z } from 'zod';
+
+import * as openapi from '../generated/openapi-schemas';
 
 // The installed channel-plugin catalog: names registered via the manifest's
 // channel modules. A deployment with none bound answers questions only in this
 // inbox (the Studio default).
 
-export const channels = z.object({
-  channels: z.array(z.string()),
-});
+export const channels = openapi.channelListing;
 export type Channels = z.infer<typeof channels>;

package/src/schemas/config.ts

@@ -1,10 +1,11 @@
 /** Environment-config and config-mode response schemas. */
 import { z } from 'zod';
 
-export const envConfig = z.object({
-  env: z.record(z.string(), z.string()),
-  secret_keys: z.array(z.string()),
-});
+import * as openapi from '../generated/openapi-schemas';
+
+export const envConfig = openapi.envView;
+
+// `read_only` is hand-written: a UI-side gate the server does not publish.
 /**
  * `GET /api/config/mode` — the active config backend mode: `file`, or an installed
  * provider's mode name such as `kubernetes`. The skeleton emits only `config_mode`;
@@ -12,7 +13,6 @@ export const envConfig = z.object({
  * so a normal response never drifts, while a genuinely read-only deployment can opt in
  * by emitting `read_only: true`.
  */
-export const configMode = z.object({
-  config_mode: z.string(),
+export const configMode = openapi.configModeView.extend({
   read_only: z.boolean().default(false),
 });