@tai42/api-client 16.0.1 → 17.0.0

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

@@ -1,6 +1,6 @@
 /** Web-channel entry-gate sub-client. */
-import * as s from '../schemas';
 import { encodeSegment } from '../http';
+import * as s from '../schemas';
 import type { Transport } from './transport';
 
 /**

package/src/errors.ts

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

package/src/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

@@ -1,5 +1,7 @@
 /** 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';
 
@@ -13,6 +15,12 @@ export const tokensPayload = z.array(
     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>;

package/src/schemas/backup.ts

@@ -1,5 +1,6 @@
 /** 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() }));

package/src/schemas/capabilities.ts

@@ -1,5 +1,7 @@
 /** Caller capability projection and auth-capabilities schemas. */
 import { z } from 'zod';
+
+import { principalRef } from './principals';
 import { subMcpMount } from './sub-mcp';
 
 /** A concrete route the caller can reach, with the methods that pass its jq fence. */
@@ -31,15 +33,18 @@ export type SubMcpEntry = z.infer<typeof subMcpEntry>;
  * `GET /api/auth/me` — the caller's derived capability projection: the concrete
  * (path, method) surface, dynamic patterns, sub-MCP mounts, tools, and agents it
  * can reach RIGHT NOW (derived server-side, never stored). `admin` is the
- * condition-free ownerless `"*"` discriminator (a TOTAL projection); a scoped
+ * condition-free `"*"` discriminator (a TOTAL projection); a scoped
  * session carries `admin: false` and a jq-exact `routes` list. `owner_user_id` is
- * the key's owner claim, `null` for an ownerless key. 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.
+ * 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
+ * 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),

package/src/schemas/connectors.ts

@@ -1,5 +1,6 @@
 /** Connector provider catalog and connection lifecycle schemas. */
 import { z } from 'zod';
+
 import { fleetReportFanout } from './fleet';
 
 export const subServiceView = z.object({

package/src/schemas/conversations.ts

@@ -1,5 +1,6 @@
 /** Conversation route, thread, transcript and config schemas. */
 import { z } from 'zod';
+
 import { conversationRoute, targetConversationConfig } from './served';
 import { pageWindow } from './shared';
 

package/src/schemas/fleet.ts

@@ -1,5 +1,6 @@
 /** Backend identity and worker-bus fleet/fan-out response schemas. */
 import { z } from 'zod';
+
 import { jsonValue } from './shared';
 
 /** `GET /api/backend` — the execution-backend identity, or the absent sentinel

package/src/schemas/hooks.ts

@@ -1,5 +1,6 @@
 /** Hook listing, registration and topic-verifier response schemas. */
 import { z } from 'zod';
+
 import { hookParams } from './served';
 
 // The hand-written hook response DTOs: the fire-door authority enum, the list rows and