@tai42/api-client 16.0.0 → 17.0.0

package/src/index.ts

@@ -5,279 +5,284 @@
  * validated and every failure throws. No caching of its own — server state
  * lives in TanStack Query in the feature packages.
  */
-export { createApiClient, isSafeApiPath } from './client';
+export type { AgentEvent, AgentSummary, ParsedAgentEvent, UnknownAgentEvent } from './agents';
+export { agentEventSchema, parseAgentFrame, parseAgentTranscript } from './agents';
 export type {
+  AddUrlToScopeBody,
   ApiClient,
-  RunToolArgs,
-  ToolAdminArgs,
-  ApiToolsListsBody,
-  StartConnectArgs,
   ApiKeyBody,
+  ApiToolsListsBody,
   ClaimLinkBody,
-  ValidateConditionBody,
-  TopicVerifierBody,
-  TriggerLinkCreateBody,
-  WebEntryCodeMintBody,
-  AddUrlToScopeBody,
+  ConversationMessageSearchQuery,
+  ConversationThreadFilters,
+  ConversationThreadMessageBody,
+  ConversationTranscriptQuery,
+  CreatePresetBody,
+  MarketplaceInstallBody,
+  MarketplaceInstallPreviewBody,
+  MarketplaceSearchQuery,
+  MarketplaceUninstallBody,
+  MetricsQuery,
+  PinRoutePublicBody,
   RoleCreateBody,
   RoleUpdateBody,
-  PinRoutePublicBody,
-  CreatePresetBody,
+  RunsQuery,
+  RunToolArgs,
   SavePresetVersionBody,
-  ValidatePresetBody,
-  StateDeclarationBody,
-  StateTemplateBody,
+  StartConnectArgs,
   StateAttachmentBody,
-  StateSubjectRef,
+  StateDeclarationBody,
   StatePageQuery,
-  ToolMetaPatch,
+  StateSubjectRef,
+  StateTemplateBody,
   StorageUploadBody,
-  ConversationThreadFilters,
-  ConversationTranscriptQuery,
-  ConversationMessageSearchQuery,
-  ConversationThreadMessageBody,
-  MetricsQuery,
-  RunsQuery,
-  MarketplaceSearchQuery,
-  MarketplaceInstallBody,
-  MarketplaceInstallPreviewBody,
-  MarketplaceUninstallBody,
+  ToolAdminArgs,
+  ToolMetaPatch,
+  TopicVerifierBody,
+  TriggerLinkCreateBody,
+  ValidateConditionBody,
+  ValidatePresetBody,
+  WebEntryCodeMintBody,
 } from './client';
-export type { ApiConfig, RequestOptions } from './http';
-export { apiRequest, apiText, apiDownload } from './http';
+export { createApiClient, isSafeApiPath } from './client';
 export {
-  ApiError,
-  ApiUnauthorizedError,
   ApiConflictError,
+  ApiError,
   ApiLoginFailedError,
   ApiSchemaError,
+  ApiSetupFailedError,
+  ApiUnauthorizedError,
 } from './errors';
-export { SseFrameParser, readSseFrames } from './sse';
-export type { SseFrame } from './sse';
-export { parseAgentFrame, parseAgentTranscript, agentEventSchema } from './agents';
-export type { AgentSummary, AgentEvent, UnknownAgentEvent, ParsedAgentEvent } from './agents';
-export {
-  toolRunStatus,
-  toolRunSubmitResult,
-  toolRunRecord,
-  toolRunListItem,
-  toolRunList,
-  isTerminalRunStatus,
-} from './tool-runs';
-export type {
-  ToolRunStatus,
-  ToolRunSubmitResult,
-  ToolRunRecord,
-  ToolRunListItem,
-  SubmitToolRunArgs,
-} from './tool-runs';
-export {
-  summarizeFleetResult,
-  summarizeFleetFanout,
-  isFleetReportFailure,
-  failedMcpsFromReport,
-} from './fleet-report';
 export type {
-  FleetReportSummary,
+  FailedMcpEntry,
+  FleetFailureOutcome,
   FleetReportStatus,
+  FleetReportSummary,
   FleetWorkerFailure,
-  FleetFailureOutcome,
-  FailedMcpEntry,
 } from './fleet-report';
-export * as schemas from './schemas';
+export {
+  failedMcpsFromReport,
+  isFleetReportFailure,
+  summarizeFleetFanout,
+  summarizeFleetResult,
+} from './fleet-report';
+export type { ApiConfig, RequestOptions } from './http';
+export { apiDownload, apiRequest, apiText } from './http';
 export type {
-  TemplatedText,
-  ToolSchema,
-  ToolMediaResult,
-  ToolTagEntry,
-  AuthRoute,
-  RouteAction,
-  GrantLevel,
-  RoleGrants,
-  RoleBody,
-  RoleVersion,
-  RoleAuditEvent,
-  RoleVersions,
-  PresetRecord,
-  PresetDetail,
-  PresetBody,
-  PresetVersion,
-  PresetRenamed,
-  PresetReferees,
-  PresetValidation,
-  PresetVersionTags,
-  PresetExtensionElement,
-  StateSubject,
-  StateDeclaration,
-  StateListItem,
-  StateAttachment,
-  StateDetail,
-  StateStats,
-  TemplateJq,
-  TemplateReconcile,
-  TemplateDeclarations,
-  StateTemplateDocument,
-  StateTemplateListItem,
-  StateInjection,
-  StateUpdate,
-  StateAttach,
-  StateBinding,
-  StateRecord,
+  AnswerFormat,
   ApplyResult,
-  TemplateJqResult,
-  TemplateJqApplyResult,
-  SubjectRow,
-  SubjectPage,
-  RecordSearchPage,
+  AuthCapabilities,
+  AuthRoute,
+  BackendInfo,
+  BackupDocument,
+  BackupImportReport,
+  Channels,
+  ChannelTemplate,
+  ClaimLinkCreated,
   CompletedOrigin,
-  WriteEntry,
-  WritesPage,
-  ConsumerLink,
-  ConsumerRow,
-  StateConsumers,
-  StateAttached,
-  StateAttachmentUpdated,
-  StateDetached,
-  StateFoldReport,
-  StateRetentionPruned,
-  FolderRecord,
-  ToolMetaRecord,
-  ToolMetaOverlay,
-  PolicyBody,
-  PolicyVersion,
-  ValidateConditionResult,
-  Extension,
-  ToolExtensions,
-  ToolExtensionsApplyResult,
-  ProviderView,
+  ConnectionView,
   ConnectorCategoryView,
-  ProviderCatalogResponse,
   ConnectorRef,
-  ManifestMcpEntry,
-  McpEnvRef,
-  McpEnvRefs,
-  ConnectionView,
-  OAuthCompleteResult,
-  StudioPluginManifest,
-  Interaction,
-  InteractionAnswered,
-  InteractionCancelled,
-  InteractionsPage,
-  InteractionMediaItem,
-  FormOption,
-  FormData,
-  FormPage,
-  FormPages,
-  MediaKind,
-  AnswerFormat,
-  Channels,
+  ConsumerLink,
+  ConsumerRow,
+  ConversationAnswerStatus,
+  ConversationConfigDeleted,
+  ConversationConfigs,
+  ConversationConfigWritten,
+  ConversationDeliveryStatus,
   ConversationDoor,
-  ConversationTargetKind,
+  ConversationFailedMessages,
+  ConversationMessage,
+  ConversationMessageSearchPage,
   ConversationMode,
-  ConversationDeliveryStatus,
-  ConversationAnswerStatus,
+  ConversationPersonDeleted,
+  ConversationRecordOrigin,
   ConversationRoute,
-  ConversationRoutes,
   ConversationRouteCreate,
-  ConversationRouteWritten,
   ConversationRouteDeleted,
+  ConversationRoutes,
+  ConversationRouteWritten,
+  ConversationTargetKind,
   ConversationThread,
-  ConversationThreadsPage,
-  ConversationMessage,
-  ConversationRecordOrigin,
-  TranscriptOrder,
-  ConversationTranscriptPage,
-  ConversationMessageSearchPage,
+  ConversationThreadDeleted,
+  ConversationThreadMessageSent,
   ConversationThreadMode,
   ConversationThreadModeState,
-  ConversationThreadMessageSent,
-  TargetConversationConfig,
-  ConversationConfigs,
-  ConversationConfigWritten,
-  ConversationConfigDeleted,
-  ConversationFailedMessages,
-  ConversationThreadDeleted,
-  ConversationPersonDeleted,
-  WebEntryCode,
-  WebEntryGate,
-  WebEntryGateState,
-  WebEntryCodeMinted,
-  WebEntryCodeRevoked,
-  Notification,
-  Notifications,
-  ChannelTemplate,
+  ConversationThreadsPage,
+  ConversationTranscriptPage,
+  DashboardMetrics,
+  Extension,
+  FleetOutcome,
+  FleetReloadResult,
+  FleetReportFanout,
+  FleetResult,
+  FleetWorker,
+  FleetWorkerResult,
+  FleetWorkers,
+  FolderRecord,
+  FormData,
+  FormOption,
+  FormPage,
+  FormPages,
+  GrantLevel,
+  HookList,
   HookParams,
   HookRegister,
   HookSubject,
-  HookList,
-  TriggerAuth,
-  SettingsSchema,
-  TokensPayload,
+  Interaction,
+  InteractionAnswered,
+  InteractionCancelled,
+  InteractionMediaItem,
+  InteractionsPage,
+  KindStatus,
   LoginFormField,
   LoginMethod,
   LoginMethods,
   LoginResult,
-  MeProjection,
-  RouteEntry,
-  PatternEntry,
-  SubMcpEntry,
-  SubMcpMount,
-  ClaimLinkCreated,
-  TriggerLinkCreated,
-  TriggerLinkRecord,
-  TriggerLinkList,
-  TriggerLinkDeleted,
   LogoutResult,
-  AuthCapabilities,
-  BackupDocument,
-  BackupImportReport,
-  ScheduleItem,
-  StorageInfo,
-  StorageResourceStat,
-  BackendInfo,
-  WorkerKind,
-  WorkerState,
-  WorkerLastOp,
-  FleetWorker,
-  FleetWorkers,
-  FleetOutcome,
-  FleetWorkerResult,
-  FleetResult,
-  FleetReloadResult,
-  FleetReportFanout,
-  ReloadConfigResult,
-  McpReloadResult,
-  KindStatus,
-  DashboardMetrics,
-  Run,
-  RunSpan,
-  RunTrace,
-  MarketplaceItem,
-  MarketplaceDelivery,
-  MarketplaceSource,
-  MarketplaceRequiredEnvVar,
-  MarketplaceRouteDecl,
-  MarketplaceRoutesDecl,
-  MarketplaceSearchKind,
-  MarketplaceSearchGroup,
-  MarketplaceSearchRow,
-  MarketplaceSearchPage,
-  MarketplaceVersion,
-  MarketplaceLatestVersion,
+  ManifestMcpEntry,
   MarketplaceAdvisory,
-  MarketplacePluginDetail,
+  MarketplaceDelivery,
+  MarketplaceInstalled,
   MarketplaceInstalledCompat,
   MarketplaceInstalledPlugin,
-  MarketplaceQuarantinedPlugin,
-  MarketplaceInstalled,
-  MarketplaceUpgradeAllRow,
-  MarketplaceUpgradeAllResult,
+  MarketplaceInstallPreview,
   MarketplaceInstallResult,
+  MarketplaceItem,
+  MarketplaceLatestVersion,
   MarketplaceMountedRoute,
-  MarketplacePreviewRoute,
-  MarketplacePreviewItem,
+  MarketplacePluginDetail,
   MarketplacePreviewCollision,
+  MarketplacePreviewItem,
   MarketplacePreviewPublicRoute,
-  MarketplaceInstallPreview,
+  MarketplacePreviewRoute,
+  MarketplaceQuarantinedPlugin,
+  MarketplaceRequiredEnvVar,
+  MarketplaceRouteDecl,
+  MarketplaceRoutesDecl,
+  MarketplaceSearchGroup,
+  MarketplaceSearchKind,
+  MarketplaceSearchPage,
+  MarketplaceSearchRow,
+  MarketplaceSource,
   MarketplaceUninstallResult,
+  MarketplaceUpgradeAllResult,
+  MarketplaceUpgradeAllRow,
+  MarketplaceVersion,
+  McpEnvRef,
+  McpEnvRefs,
+  McpReloadResult,
+  MediaKind,
+  MeProjection,
+  Notification,
+  Notifications,
+  OAuthCompleteResult,
+  PatternEntry,
+  PolicyBody,
+  PolicyVersion,
+  PresetBody,
+  PresetDetail,
+  PresetExtensionElement,
+  PresetRecord,
+  PresetReferees,
+  PresetRenamed,
+  PresetValidation,
+  PresetVersion,
+  PresetVersionTags,
+  Principal,
+  PrincipalRef,
+  ProviderCatalogResponse,
+  ProviderView,
+  RecordSearchPage,
+  ReloadConfigResult,
+  RoleAuditEvent,
+  RoleBody,
+  RoleGrants,
+  RoleVersion,
+  RoleVersions,
+  RouteAction,
+  RouteEntry,
+  Run,
+  RunSpan,
+  RunTrace,
+  ScheduleItem,
+  SettingsSchema,
+  SetupBody,
+  SetupResult,
+  StateAttach,
+  StateAttached,
+  StateAttachment,
+  StateAttachmentUpdated,
+  StateBinding,
+  StateConsumers,
+  StateDeclaration,
+  StateDetached,
+  StateDetail,
+  StateFoldReport,
+  StateInjection,
+  StateListItem,
+  StateRecord,
+  StateRetentionPruned,
+  StateStats,
+  StateSubject,
+  StateTemplateDocument,
+  StateTemplateListItem,
+  StateUpdate,
+  StorageInfo,
+  StorageResourceStat,
+  StudioPluginManifest,
+  SubjectPage,
+  SubjectRow,
+  SubMcpEntry,
+  SubMcpMount,
+  TargetConversationConfig,
+  TemplateDeclarations,
+  TemplatedText,
+  TemplateJq,
+  TemplateJqApplyResult,
+  TemplateJqResult,
+  TemplateReconcile,
+  TokensPayload,
+  ToolExtensions,
+  ToolExtensionsApplyResult,
+  ToolMediaResult,
+  ToolMetaOverlay,
+  ToolMetaRecord,
+  ToolSchema,
+  ToolTagEntry,
+  TranscriptOrder,
+  TriggerAuth,
+  TriggerLinkCreated,
+  TriggerLinkDeleted,
+  TriggerLinkList,
+  TriggerLinkRecord,
+  ValidateConditionResult,
+  WebEntryCode,
+  WebEntryCodeMinted,
+  WebEntryCodeRevoked,
+  WebEntryGate,
+  WebEntryGateState,
+  WorkerKind,
+  WorkerLastOp,
+  WorkerState,
+  WriteEntry,
+  WritesPage,
 } from './schemas';
+export * as schemas from './schemas';
+export type { SseFrame } from './sse';
+export { readSseFrames, SseFrameParser } from './sse';
+export type {
+  SubmitToolRunArgs,
+  ToolRunListItem,
+  ToolRunRecord,
+  ToolRunStatus,
+  ToolRunSubmitResult,
+} from './tool-runs';
+export {
+  isTerminalRunStatus,
+  toolRunList,
+  toolRunListItem,
+  toolRunRecord,
+  toolRunStatus,
+  toolRunSubmitResult,
+} from './tool-runs';

package/src/schemas/api-keys.ts

@@ -0,0 +1,34 @@
+/** 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';
+
+/** 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(),
+  }),
+);
+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() });

package/src/schemas/backup.ts

@@ -0,0 +1,43 @@
+/** Backup section, document and import-report response schemas. */
+import { z } from 'zod';
+
+import { fleetReportFanout } from './fleet';
+
+export const backupSections = z.array(z.object({ name: z.string(), secret: z.boolean() }));
+
+/** The exported backup document — validated when the UI reads a picked file. */
+export const backupDocument = z.object({
+  version: z.literal(1),
+  created_at: z.string(),
+  sections: z.record(z.string(), z.unknown()),
+  errors: z.record(z.string(), z.string()).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(),
+    }),
+  ),
+});
+export type BackupImportReport = z.infer<typeof backupImportReport>;