@tai42/api-client 10.0.0 → 11.0.0

package/src/schemas.ts

@@ -282,6 +282,7 @@ export const templateNames = z.array(z.string());
 export const templateDetail = z.object({ template: z.string(), schema: jsonSchema });
 export const templateUploaded = z.object({ path: z.string(), uploaded: z.literal(true) });
 export const templateDeleted = z.object({ path: z.string(), deleted: z.literal(true) });
+export const templateDirDeleted = z.object({ path: z.string(), deleted: z.literal(true) });
 export const templateRendered = z.object({ rendered: z.string() });
 export const templateCacheCleared = z.object({ cleared: z.literal(true) });
 
@@ -1027,6 +1028,15 @@ export type ConversationDoor = z.infer<typeof conversationDoor>;
 export const conversationTargetKind = z.enum(['agent', 'tool']);
 export type ConversationTargetKind = z.infer<typeof conversationTargetKind>;
 
+/**
+ * A route's default control mode (`initial_mode`) when a thread carries no
+ * per-thread override: `agent` runs the target turn, `manual` suppresses it for an
+ * operator to answer. The same value vocabulary as a per-thread mode override, but
+ * a distinct concept (the route default vs. one thread's override).
+ */
+export const conversationMode = z.enum(['agent', 'manual']);
+export type ConversationMode = z.infer<typeof conversationMode>;
+
 /**
  * Where a record sits between intake and a terminal outcome. `failed` is the one
  * the monitor surfaces loudly; `shed` and `silent` are terminal by design and
@@ -1055,7 +1065,14 @@ export type ConversationAnswerStatus = z.infer<typeof conversationAnswerStatus>;
 export const conversationRecordOrigin = z.enum(['client', 'operator']);
 export type ConversationRecordOrigin = z.infer<typeof conversationRecordOrigin>;
 
-/** A stored routing row as a read door returns it, its `callback_secret` withheld. */
+/**
+ * A stored routing row as a read door returns it, its `callback_secret` withheld.
+ *
+ * `initial_mode`, `turns_per_hour_override`, and `error_reply_text` carry defaults
+ * because a stored row always returns them, while a hand-built stub/fixture may
+ * omit them — the default keeps such a payload valid without inventing a field the
+ * server never sends.
+ */
 export const conversationRoute = z.object({
   route_name: z.string(),
   door: conversationDoor,
@@ -1063,10 +1080,13 @@ export const conversationRoute = z.object({
   target_name: z.string(),
   payload_expr: z.string().nullable(),
   reply_expr: z.string().nullable(),
+  initial_mode: conversationMode.default('agent'),
   execution_key: z.string(),
   channel: z.string().nullable(),
   our_identity: z.string().nullable(),
   callback_url: z.string().nullable(),
+  turns_per_hour_override: z.number().int().nullable().default(null),
+  error_reply_text: z.string().nullable().default(null),
   execution_key_fingerprint: z.string(),
 });
 export type ConversationRoute = z.infer<typeof conversationRoute>;
@@ -1077,6 +1097,62 @@ export const conversationRoutes = z.object({
 });
 export type ConversationRoutes = z.infer<typeof conversationRoutes>;
 
+/**
+ * The client-facing create/edit body for a conversation route — the wire model of
+ * `tai42_contract.conversations.ConversationRouteCreate`. `POST
+ * /api/conversations/{route_name}` is an UPSERT, so this one shape is both the
+ * create AND the edit body. `route_name` rides the URL path; it is carried here too
+ * (the door rejects a body whose `route_name` disagrees with the path).
+ *
+ * The contract's cross-field validators are mirrored where the form authors this
+ * body: `payload_expr`/`reply_expr` are tool-only; an `api` door carries a
+ * `callback_url` (and no channel identity); a `channel` door carries `channel` +
+ * `our_identity` (and no callback). Sent explicitly (including `null`) so an edit
+ * clears a field the operator emptied rather than leaving the stored value.
+ */
+export const conversationRouteCreate = z.object({
+  route_name: z.string(),
+  door: conversationDoor,
+  target_kind: conversationTargetKind,
+  target_name: z.string().min(1),
+  payload_expr: z.string().nullable().default(null),
+  reply_expr: z.string().nullable().default(null),
+  initial_mode: conversationMode.default('agent'),
+  execution_key: z.string().min(1),
+  channel: z.string().nullable().default(null),
+  our_identity: z.string().nullable().default(null),
+  callback_url: z.string().nullable().default(null),
+  turns_per_hour_override: z.number().int().positive().nullable().default(null),
+  error_reply_text: z.string().min(1).max(2000).nullable().default(null),
+});
+export type ConversationRouteCreate = z.infer<typeof conversationRouteCreate>;
+
+/**
+ * The create/replace reply: whether THIS call created the row (vs. replaced an
+ * existing one), the row itself (its `callback_secret` withheld), and the
+ * `callback_secret` returned ONCE for an `api`-door row (`null` for a `channel`
+ * row). The secret signs delivery callbacks and is never re-read from any door, so
+ * a caller that needs it must capture it from this reply.
+ */
+export const conversationRouteWritten = z.object({
+  created: z.boolean(),
+  route_name: z.string(),
+  route: conversationRoute,
+  callback_secret: z.string().nullable(),
+});
+export type ConversationRouteWritten = z.infer<typeof conversationRouteWritten>;
+
+/**
+ * The delete reply: `removed` says whether THIS call removed the routing row (a
+ * retryable reclamation of orphaned thread indexes answers `false` rather than a
+ * 404).
+ */
+export const conversationRouteDeleted = z.object({
+  removed: z.boolean(),
+  route_name: z.string(),
+});
+export type ConversationRouteDeleted = z.infer<typeof conversationRouteDeleted>;
+
 /**
  * One thread of a route, summarized from its newest record. A `thread_id` holds
  * an api-door address (`{principal}/{end user}`, percent-encoded), so it never
@@ -1179,6 +1255,94 @@ export const conversationThreadMessageSent = z.object({
 });
 export type ConversationThreadMessageSent = z.infer<typeof conversationThreadMessageSent>;
 
+/**
+ * Per-target presentation config for the conversation bridge, keyed by
+ * `(target_kind, target_name)` — the wire model of
+ * `tai42_contract.conversations.TargetConversationConfig`. The row carries no
+ * server-derived fields, so this ONE shape is the stored row AND the upsert body
+ * (`PUT /api/conversation-configs/{target_kind}/{target_name}` is the create AND
+ * the edit path).
+ *
+ * `multichannel` opts the target into person linking; `greeting_template` is the
+ * first-contact greeting. `greeting_template` is a `str.format` template (NOT a jq
+ * expression) that may reference at most the `{pairing_code}` placeholder — it
+ * carries no `x-tai42-expression`. `null` is the explicit spelling for "no
+ * greeting"; a blank string is refused server-side.
+ */
+export const targetConversationConfig = z.object({
+  target_kind: conversationTargetKind,
+  target_name: z.string().min(1),
+  multichannel: z.boolean().default(false),
+  greeting_template: z.string().nullable().default(null),
+});
+export type TargetConversationConfig = z.infer<typeof targetConversationConfig>;
+
+/** Every stored per-target config (`GET /api/conversation-configs`). */
+export const conversationConfigs = z.object({
+  items: z.array(targetConversationConfig),
+  total: z.number(),
+});
+export type ConversationConfigs = z.infer<typeof conversationConfigs>;
+
+/**
+ * The upsert reply: whether THIS call created the config (vs. replaced an existing
+ * one), its key, and the stored row.
+ */
+export const conversationConfigWritten = z.object({
+  created: z.boolean(),
+  target_kind: conversationTargetKind,
+  target_name: z.string(),
+  config: targetConversationConfig,
+});
+export type ConversationConfigWritten = z.infer<typeof conversationConfigWritten>;
+
+/** The config-delete reply: `removed` is always `true` on success (an unknown key is a 404). */
+export const conversationConfigDeleted = z.object({
+  removed: z.boolean(),
+  target_kind: conversationTargetKind,
+  target_name: z.string(),
+});
+export type ConversationConfigDeleted = z.infer<typeof conversationConfigDeleted>;
+
+/**
+ * The admin-only failed-delivery listing (`GET /api/conversations/messages/failed`):
+ * every answer record whose delivery ended `failed`, across every route and caller.
+ * The records are the ADMIN projection (delivery bookkeeping and `error` included),
+ * so the row shape is {@link conversationMessage} exactly. It is NOT a paged window —
+ * the door returns `{items, total}` and nothing more.
+ */
+export const conversationFailedMessages = z.object({
+  items: z.array(conversationMessage),
+  total: z.number(),
+});
+export type ConversationFailedMessages = z.infer<typeof conversationFailedMessages>;
+
+/**
+ * The thread-delete reply (`DELETE /api/conversations/{route_name}/thread?thread_id=`).
+ * `removed` is a COUNT of the answer records this call deleted — `0` when a prior
+ * run already cleared them, when they had aged out under retention, or when the id
+ * was never stored (forgetting is absolute, never a 404 on a valid id).
+ */
+export const conversationThreadDeleted = z.object({
+  removed: z.number(),
+  route_name: z.string(),
+  thread_id: z.string(),
+});
+export type ConversationThreadDeleted = z.infer<typeof conversationThreadDeleted>;
+
+/**
+ * The person-erase reply (`DELETE /api/conversations/persons/{person_id}`).
+ * `removed` counts the answer records deleted across the person's routes; `erased`
+ * says whether THIS call removed the person row (`false` on a retry or an
+ * already-gone person — never a 404).
+ */
+export const conversationPersonDeleted = z.object({
+  person_id: z.string(),
+  removed: z.number(),
+  erased: z.boolean(),
+});
+export type ConversationPersonDeleted = z.infer<typeof conversationPersonDeleted>;
+
 // -- channel-web entry gate --------------------------------------------------
 // The web channel's entry gate: a web route can be gated so its chat page is
 // served only to a navigation carrying a live entry code. These four doors are
@@ -2195,8 +2359,9 @@ export const marketplaceInstalledPlugin = z
     missing_upstream: z.boolean(),
     compat: marketplaceInstalledCompat,
     // The `{kind, name}` of every item this plugin's stored spec provides
-    // (local truth). The McpTab joins the mcp-server item names against the
-    // manifest's mcp-entry titles to render an installer-written entry read-only.
+    // (local truth). The connectors page's McpServersSection joins the mcp-server
+    // item names against the manifest's mcp-entry titles to render an
+    // installer-written entry read-only.
     items: z.array(marketplaceItem.pick({ kind: true, name: true })),
     // The persisted `{item_name: base}` mount this plugin is installed at (local
     // truth; `{}` means every item at its declared base). Studio seeds the update