@tai42/api-client 16.0.0 → 16.0.1

package/src/schemas/presets.ts

@@ -0,0 +1,113 @@
+/** 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/profiles.ts

@@ -0,0 +1,119 @@
+/** 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,57 @@
+/** 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,27 @@
+/** 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,49 @@
+/** Generated served-document schema aliases and templated-text re-exports. */
+import { z } from 'zod';
+import * as generated from '../generated/served-schemas';
+
+export { templatedText, requiredTemplatedText } from '../templated-text';
+export type { 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,31 @@
+/** 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/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(),
+};