@tai42/api-client 16.0.0 → 17.0.0

package/src/schemas/presets.ts

@@ -0,0 +1,114 @@
+/** Preset record, version and validation response schemas. */
+import { z } from 'zod';
+
+import { presetExtensionElement } from './extensions';
+import { presetBody } from './served';
+
+/** A list of extension COMBOS — each combo an ordered list of elements. */
+export const presetExtensions = z.array(z.array(presetExtensionElement));
+
+/**
+ * One preset as `GET /api/presets` returns it. Every preset is versioned, so
+ * `active_version` is always an int; `conflicted` marks a QUARANTINED row (its
+ * name collided with a foreign tool at boot — delete-only). `extensions` are the
+ * ACTIVE version's extension combos, `output_schema` the optional author-set
+ * output JSON Schema, and `input_schema` the optional author-set input JSON
+ * Schema. Categorization tags live in the tool_meta overlay
+ * (`GET /api/tool-meta`), never on the record. A drift throws `ApiSchemaError`;
+ * nothing is coerced.
+ */
+export const presetRecord = z.object({
+  name: z.string(),
+  base_tool: z.string(),
+  description: z.string(),
+  active_version: z.number(),
+  extensions: presetExtensions,
+  output_schema: z.record(z.string(), z.unknown()).nullable(),
+  input_schema: z.record(z.string(), z.unknown()).nullable(),
+  conflicted: z.boolean(),
+  // The human-readable cause a row is quarantined (its name collided with a
+  // foreign tool at boot), or `null` when the row is not conflicted. Rendered
+  // verbatim; nothing is coerced.
+  conflicted_reason: z.string().nullable(),
+  // Sorted preset-name cross-references: `uses` names the presets this one
+  // composes as tools; `used_by` names the presets that compose this one.
+  uses: z.array(z.string()),
+  used_by: z.array(z.string()),
+});
+export type PresetRecord = z.infer<typeof presetRecord>;
+
+export const presetList = z.array(presetRecord);
+
+/** `GET /api/presets/{name}` — the record plus the active version's baked kwargs. */
+export const presetDetail = presetRecord.extend({
+  fixed_kwargs: z.record(z.string(), z.unknown()),
+});
+export type PresetDetail = z.infer<typeof presetDetail>;
+
+/**
+ * One immutable version row (`GET /api/presets/{name}/versions[/{version}]`).
+ * `is_current` flags the active version; `tags` here is the GENERIC per-version
+ * label list (kind-agnostic) — the only preset tags that remain, distinct from the
+ * removed record-level categorization and from the tool_meta overlay.
+ */
+export const presetVersion = z.object({
+  version: z.number(),
+  body: presetBody,
+  tags: z.array(z.string()),
+  created_at: z.string(),
+  is_current: z.boolean(),
+});
+export type PresetVersion = z.infer<typeof presetVersion>;
+
+export const presetVersionList = z.array(presetVersion);
+
+/** `POST /api/presets/{name}/rollback` — the re-pointed active version. */
+export const presetRollback = z.object({ name: z.string(), active_version: z.number() });
+
+/** `DELETE /api/presets/{name}` — the removed preset. */
+export const presetDeleted = z.object({ name: z.string(), deleted: z.literal(true) });
+
+/** `POST /api/presets/{name}/rename` — the re-keyed record identity. */
+export const presetRenamed = z.object({
+  name: z.string(),
+  renamed_from: z.string(),
+  active_version: z.number(),
+});
+export type PresetRenamed = z.infer<typeof presetRenamed>;
+
+/**
+ * `GET /api/presets/{name}/referees` — every OTHER preset whose active authored
+ * composition names this one as a tool (the referees a rename would strand). An
+ * empty list is the clean case; a non-empty list means a rename is blocked until
+ * those presets are updated. A drift throws `ApiSchemaError`.
+ */
+export const presetReferees = z.object({
+  name: z.string(),
+  referees: z.array(z.string()),
+});
+export type PresetReferees = z.infer<typeof presetReferees>;
+
+/**
+ * `POST /api/presets/validate` — the dry-run verdict for a preset draft. `valid`
+ * is the absence of an `error`; an invalid draft is a SUCCESSFUL validation (HTTP
+ * 200), so `error` carries the server's verbatim message. A drift throws
+ * `ApiSchemaError`.
+ */
+export const presetValidation = z.object({
+  valid: z.boolean(),
+  error: z.string().nullable(),
+});
+export type PresetValidation = z.infer<typeof presetValidation>;
+
+/**
+ * `PUT /api/presets/{name}/versions/{version}/tags` — the re-annotated version.
+ * Version tags are labels on an immutable body, so this rebinds nothing; the
+ * response echoes the identity plus the new tag list. A drift throws
+ * `ApiSchemaError`.
+ */
+export const presetVersionTags = z.object({
+  name: z.string(),
+  version: z.number(),
+  tags: z.array(z.string()),
+});
+export type PresetVersionTags = z.infer<typeof presetVersionTags>;

package/src/schemas/principals.ts

@@ -0,0 +1,41 @@
+/** Principal (identity) reference, row, listing and delete-result schemas. */
+import { z } from 'zod';
+
+/**
+ * A compact reference to a principal — the owner of a key, or the human behind a
+ * session — carried inline on payloads that name one.
+ */
+export const principalRef = z.object({
+  user_id: z.string(),
+  kind: z.enum(['human', 'service']),
+  display_name: z.string(),
+});
+export type PrincipalRef = z.infer<typeof principalRef>;
+
+/**
+ * A principal row (`/api/auth/principals`). `kind` is `human` (logs in
+ * interactively) or `service` (holds keys only, never logs in). `created_by` is
+ * the principal that created this one, or `null` for the owner the setup door
+ * mints. `disabled` turns off every credential the principal owns. `created_at`
+ * is an ISO-8601 instant.
+ */
+export const principal = z.object({
+  user_id: z.string(),
+  kind: z.enum(['human', 'service']),
+  display_name: z.string(),
+  created_by: z.string().nullable(),
+  disabled: z.boolean(),
+  created_at: z.string(),
+});
+export type Principal = z.infer<typeof principal>;
+
+/** The principals listing (`GET /api/auth/principals`). */
+export const principalList = z.array(principal);
+export type PrincipalList = z.infer<typeof principalList>;
+
+/** The delete result (`DELETE /api/auth/principals/{user_id}`). */
+export const principalDeleted = z.object({
+  user_id: z.string(),
+  deleted: z.boolean(),
+});
+export type PrincipalDeleted = z.infer<typeof principalDeleted>;

package/src/schemas/profiles.ts

@@ -0,0 +1,120 @@
+/** Settings-profile record, version, diff and apply response schemas. */
+import { z } from 'zod';
+
+import { fleetReportFanout } from './fleet';
+
+// The admin-only `/api/config/profiles/*` surface. Secrets ride the wire in the
+// clear (secret/fenced routes); masking is CLIENT-SIDE per the secret-mask union. A drift
+// on any of these throws `ApiSchemaError`.
+
+/**
+ * `GET /api/config/profiles` — one row per stored profile. The list is
+ * names+descriptions ONLY (action=read); no `env`, no `secret_keys`, no bodies.
+ * (No `last_modified`: the list carries identity, not history — version metadata
+ * is the `/versions` surface — so the list renders no last-modified column.)
+ */
+export const settingsProfileSummary = z.object({
+  name: z.string(),
+  description: z.string(),
+});
+export type SettingsProfileSummary = z.infer<typeof settingsProfileSummary>;
+export const settingsProfileList = z.array(settingsProfileSummary);
+
+/**
+ * `GET /api/config/profiles/{name}` and each version body — the stored profile
+ * document (action=secret). `env` carries REAL values; `secret_keys` is the
+ * per-profile secret-marks band folded into the secret-mask union for masking.
+ */
+export const settingsProfileBody = z.object({
+  description: z.string(),
+  env: z.record(z.string(), z.string()),
+  secret_keys: z.array(z.string()),
+});
+export type SettingsProfileBody = z.infer<typeof settingsProfileBody>;
+
+/** `PUT /api/config/profiles/{name}` — a minimal save ack; `version` is the new store version. */
+export const settingsProfileSaved = z.object({
+  ok: z.literal(true),
+  version: z.number().optional(),
+});
+export type SettingsProfileSaved = z.infer<typeof settingsProfileSaved>;
+
+/** `DELETE /api/config/profiles/{name}` — a minimal removal ack. */
+export const settingsProfileDeleted = z.object({ ok: z.literal(true) });
+
+/** `POST /api/config/profiles/{name}/rollback` — the restore ack; `version` is the resulting active version. */
+export const settingsProfileRollback = z.object({
+  ok: z.literal(true),
+  version: z.number(),
+});
+export type SettingsProfileRollback = z.infer<typeof settingsProfileRollback>;
+
+/**
+ * `POST /api/config/profiles/{name}/diff` — the SAVED profile vs the stored env
+ * (action=secret). `changed` carries real `old`/`new` values (UI masks via
+ * JsonDiff); `recycle_keys`/`refused_keys` are the diff's recycle-class and
+ * boundary-refused key names, called out in the UI before apply.
+ */
+export const settingsProfileDiff = z.object({
+  added: z.array(z.string()),
+  removed: z.array(z.string()),
+  changed: z.array(z.object({ key: z.string(), old: z.string(), new: z.string() })),
+  recycle_keys: z.array(z.string()),
+  refused_keys: z.array(z.string()),
+});
+export type SettingsProfileDiff = z.infer<typeof settingsProfileDiff>;
+
+/**
+ * `POST /api/config/profiles/{name}/apply` — the dedicated `profile_apply_response`
+ * (action=fenced, destructive). NAMES-ONLY (no env value in any
+ * section): `hot` is the hot-swapped key names; `recycle` is the orchestrator's
+ * per-worker section — one `{name, kind, status, generation_before}` row per recycled
+ * target, `generation_before` the life that was recycled, the applier's OWN row carrying
+ * the `self-deferred` status literal when the diff has serve-affecting recycle keys;
+ * `fresh` is the per-kind list of NEW ready lives observed since the pre-apply snapshot
+ * (each `{name, kind, generation}`), evidence of fresh capacity and never claimed as any
+ * target's successor; `refused` is `[]` on success by construction (populated
+ * `{key, reason}` only on a refusal), the populated refusal surfaces being the diff
+ * preview and the refusal error report. `fanout` is the mode-wrapped fleet broadcast,
+ * parsed EXPLICITLY so a failed propagation reaches the shared fleet-report handler. A
+ * drift throws `ApiSchemaError`.
+ */
+export const profileApplyResponse = z.object({
+  hot: z.array(z.string()),
+  recycle: z.array(
+    z.object({
+      name: z.string(),
+      kind: z.string(),
+      status: z.string(),
+      generation_before: z.number(),
+    }),
+  ),
+  fresh: z.array(z.object({ name: z.string(), kind: z.string(), generation: z.number() })),
+  refused: z.array(z.object({ key: z.string(), reason: z.string() })),
+  fanout: fleetReportFanout,
+});
+export type ProfileApplyResponse = z.infer<typeof profileApplyResponse>;
+
+/**
+ * `GET /api/config/profiles/{name}/versions` — version METADATA only (action=read;
+ * no bodies), the generic versioned-store row minus `body`. `is_current` flags the
+ * active pointer.
+ */
+export const settingsProfileVersionMeta = z.object({
+  version: z.number(),
+  tags: z.array(z.string()),
+  created_at: z.string(),
+  is_current: z.boolean(),
+});
+export type SettingsProfileVersionMeta = z.infer<typeof settingsProfileVersionMeta>;
+export const settingsProfileVersionList = z.array(settingsProfileVersionMeta);
+
+/**
+ * `GET /api/config/profiles/{name}/versions/{version}` — one immutable version WITH
+ * its `body` (action=secret; body rendered masked per the secret-mask union). The generic
+ * versioned-store row shape.
+ */
+export const settingsProfileVersion = settingsProfileVersionMeta.extend({
+  body: settingsProfileBody,
+});
+export type SettingsProfileVersion = z.infer<typeof settingsProfileVersion>;

package/src/schemas/roles.ts

@@ -0,0 +1,58 @@
+/** Role grant, version and audit response schemas. */
+import { z } from 'zod';
+
+import { roleBody } from './served';
+import { jsonValue } from './shared';
+
+/** A role's per-tag ACCESS LEVEL: `none` (no access), `read`, or `write`. */
+export const grantLevel = z.enum(['none', 'read', 'write']);
+export type GrantLevel = z.infer<typeof grantLevel>;
+
+/** A role's editable grant map: feature-group TAG name → the role's access level. */
+export const roleGrants = z.record(z.string(), grantLevel);
+export type RoleGrants = z.infer<typeof roleGrants>;
+
+export const roleList = z.array(roleBody);
+
+/** `DELETE /api/auth/roles/{name}` — the deleted role's name. */
+export const roleDeleted = z.object({ name: z.string(), deleted: z.boolean() });
+
+/**
+ * One immutable role-version row (`GET /api/auth/roles/{name}/versions` →
+ * `versions`). `body` is the role body at that version; `is_current` flags the
+ * active pointer. Mirrors the generic versioned-store row shape.
+ */
+export const roleVersion = z.object({
+  version: z.number(),
+  body: roleBody,
+  tags: z.array(z.string()),
+  created_at: z.string(),
+  is_current: z.boolean(),
+});
+export type RoleVersion = z.infer<typeof roleVersion>;
+
+/**
+ * One who/action/before→after audit row (`GET /api/auth/roles/{name}/versions` →
+ * `audit`). Its `body` carries the mutation kind, the actor, and the before/after
+ * role bodies (both `null` for a create's `before` / a delete's `after`).
+ */
+export const roleAuditEvent = z.object({
+  version: z.number(),
+  body: z.object({
+    action: z.string(),
+    actor: z.string().nullable(),
+    before: jsonValue.nullable(),
+    after: jsonValue.nullable(),
+  }),
+  tags: z.array(z.string()),
+  created_at: z.string(),
+  is_current: z.boolean(),
+});
+export type RoleAuditEvent = z.infer<typeof roleAuditEvent>;
+
+/** `GET /api/auth/roles/{name}/versions` — the append-only history + audit trail. */
+export const roleVersions = z.object({
+  versions: z.array(roleVersion),
+  audit: z.array(roleAuditEvent),
+});
+export type RoleVersions = z.infer<typeof roleVersions>;

package/src/schemas/schedules.ts

@@ -0,0 +1,28 @@
+/** Schedule listing and server-clock response schemas. */
+import { z } from 'zod';
+
+import { jsonValue } from './shared';
+
+// The skeleton returns opaque backend-tool results; the table reads a few known
+// fields and passes the rest through untouched.
+
+export const scheduleItem = z
+  .object({
+    name: z.string(),
+    enabled: z.boolean().optional(),
+    schedule: jsonValue.optional(),
+    target: jsonValue.optional(),
+    args: z.array(jsonValue).optional(),
+    kwargs: z.record(z.string(), jsonValue).optional(),
+  })
+  .loose();
+export const scheduleList = z.array(scheduleItem);
+export type ScheduleItem = z.infer<typeof scheduleItem>;
+
+export const serverDateTime = z
+  .object({
+    utc: jsonValue,
+    local: jsonValue.optional(),
+    system: jsonValue.optional(),
+  })
+  .loose();

package/src/schemas/served.ts

@@ -0,0 +1,50 @@
+/** Generated served-document schema aliases and templated-text re-exports. */
+import { z } from 'zod';
+
+import * as generated from '../generated/served-schemas';
+
+export type { TemplatedText } from '../templated-text';
+export { requiredTemplatedText, templatedText } from '../templated-text';
+
+// Served-document schemas are GENERATED from the platform contract JSON-schema
+// bundle (src/generated/served-schemas.ts) and re-exported here under the names the
+// rest of the client uses. The generator maps every `x-tai42-templated-text` field
+// to the shared `templatedText` zod, so a served body can never be a bare string.
+export const stateInjection = generated.stateInjection;
+export type StateInjection = z.infer<typeof stateInjection>;
+export const stateUpdate = generated.stateUpdate;
+export type StateUpdate = z.infer<typeof stateUpdate>;
+export const stateAttach = generated.stateAttach;
+export type StateAttach = z.infer<typeof stateAttach>;
+export const stateBinding = generated.stateBinding;
+export type StateBinding = z.infer<typeof stateBinding>;
+export const presetBody = generated.presetBody;
+export type PresetBody = z.input<typeof presetBody>;
+export const conversationRoute = generated.conversationRoute;
+export type ConversationRoute = z.infer<typeof conversationRoute>;
+export const conversationRouteCreate = generated.conversationRouteCreate;
+export type ConversationRouteCreate = z.input<typeof conversationRouteCreate>;
+export const targetConversationConfig = generated.targetConversationConfig;
+export type TargetConversationConfig = z.input<typeof targetConversationConfig>;
+export const channelTemplate = generated.channelTemplate;
+export type ChannelTemplate = z.infer<typeof channelTemplate>;
+export const hookSubject = generated.hookSubject;
+export type HookSubject = z.infer<typeof hookSubject>;
+export const hookParams = generated.hookParams;
+export type HookParams = z.infer<typeof hookParams>;
+export const hookRegister = generated.hookRegister;
+export type HookRegister = z.input<typeof hookRegister>;
+export const stateDeclaration = generated.stateDeclaration;
+export type StateDeclaration = z.infer<typeof stateDeclaration>;
+export const stateTemplateDocument = generated.stateTemplateDocument;
+export type StateTemplateDocument = z.infer<typeof stateTemplateDocument>;
+export const templateJq = generated.stateTemplateJq;
+export type TemplateJq = z.infer<typeof templateJq>;
+export const templateReconcile = generated.stateTemplateReconcile;
+export type TemplateReconcile = z.infer<typeof templateReconcile>;
+export const templateDeclarations = generated.stateTemplateDeclarations;
+export type TemplateDeclarations = z.infer<typeof templateDeclarations>;
+export const policyBody = generated.accessPolicy;
+export type PolicyBody = z.infer<typeof policyBody>;
+export const roleBody = generated.roleDefinition;
+export type RoleBody = z.infer<typeof roleBody>;

package/src/schemas/settings-schema.ts

@@ -0,0 +1,32 @@
+/** Declarative settings-form schema response. */
+import { z } from 'zod';
+
+import { jsonValue } from './shared';
+
+// The settings form is auto-rendered from a declarative group/field description
+// the skeleton emits from its typed settings models.
+
+export const settingsSchema = z.object({
+  groups: z.array(
+    z.object({
+      name: z.string(),
+      module: z.string(),
+      qualname: z.string(),
+      fields: z.array(
+        z.object({
+          name: z.string(),
+          env_var: z.string(),
+          type: z.string(),
+          default: jsonValue.nullable(),
+          required: z.boolean(),
+          secret: z.boolean(),
+          description: z.string().nullable(),
+          nested_group: z.string().nullable(),
+          default_namespace_var: z.string().nullable(),
+          value: jsonValue.nullable(),
+        }),
+      ),
+    }),
+  ),
+});
+export type SettingsSchema = z.infer<typeof settingsSchema>;

package/src/schemas/setup.ts

@@ -0,0 +1,39 @@
+/** Setup-door (`POST /api/setup`) request-body and result schemas. */
+import { z } from 'zod';
+
+/**
+ * The result of a successful `POST /api/setup`, returned exactly ONCE. `api_key`
+ * is the owner key's plaintext (shown once, never retrievable again).
+ * `login_attached` is whether an interactive login was attached now;
+ * `invite_token` and `login_path` are set only when the attachment was an invite
+ * the operator completes later.
+ */
+export const setupResult = z.object({
+  owner_user_id: z.string(),
+  key_user_id: z.string(),
+  api_key: z.string().min(1),
+  key_fingerprint: z.string(),
+  login_attached: z.boolean(),
+  invite_token: z.string().nullable().optional(),
+  login_path: z.string().nullable().optional(),
+});
+export type SetupResult = z.infer<typeof setupResult>;
+
+/**
+ * The body of `POST /api/setup`. `setup_token` is checked against the
+ * deployment's setup token. `owner_user_id`/`key_user_id` are optional — the door
+ * mints ids when they are absent. `owner_display_name` is required. `login`
+ * attaches the owner's interactive login when a login-attaching accounts provider
+ * is configured (a password set now, or a one-time invite completed later); a
+ * keys-only setup omits it.
+ */
+export interface SetupBody {
+  readonly setup_token: string;
+  readonly owner_display_name: string;
+  readonly owner_user_id?: string;
+  readonly key_user_id?: string;
+  readonly key_description?: string;
+  readonly login?:
+    | { readonly kind: 'password'; readonly email: string; readonly password: string }
+    | { readonly kind: 'invite'; readonly email: string };
+}

package/src/schemas/shared.ts

@@ -0,0 +1,21 @@
+/** Shared primitive schemas (json value/schema) and the paged-window fields. */
+import { z } from 'zod';
+
+/** An arbitrary JSON value (tool results, rendered payloads). */
+export const jsonValue: z.ZodType = z.unknown();
+
+/** A JSON Schema object (Pydantic-emitted). Permissive; parsed by the auto-form. */
+export const jsonSchema = z.record(z.string(), z.unknown());
+/**
+ * The page window every paged read door carries; `next_page` is null on the last
+ * page. `truncated` is TRUE when the door had more matches than it would scan or
+ * return under its cap — the UI must surface that LOUDLY, never a silent cut — and
+ * false whenever the window is exhaustive.
+ */
+export const pageWindow = {
+  total: z.number(),
+  page: z.number(),
+  page_size: z.number(),
+  next_page: z.number().nullable(),
+  truncated: z.boolean(),
+};