@anchrd/colab-sdk 0.0.0-stage → 0.1.0

package/dist/boards/boards.js

@@ -0,0 +1,289 @@
+import { z } from "zod";
+import { ColumnId, ColumnType, TaskColumn } from "../columns/columns.js";
+import { Schedule } from "../dashboards/dashboards.js";
+import { idSchema } from "../ids/ids.js";
+import { BoardShownKind, BoardSystem, NodeId, NodePerson } from "../nodes/nodes.js";
+import { IdempotencyKey, Rev } from "../primitives/primitives.js";
+import { TicketMove, TicketSubject, TicketSubjectRef } from "../validation/validation.js";
+// Boards, their columns and labels, and tasks (#42, Nodes › Board, Nodes › Aufgabe, E38, E40, E41,
+// E43, E44, E67, E70): the inputs of `intelligence_board_create`, `_get`, `_update`,
+// `intelligence_board_task_list`, `_create`, `intelligence_task_get`, `_update`, and the answers. A
+// board and a task are nodes, so their ids are `node_…`; columns and labels have no tools of their
+// own and are kept as whole lists through `intelligence_board_update`.
+// A ULID in Crockford base32, as `ids.ts` takes it.
+const ulid = z.string().regex(/^[0-9A-HJKMNP-TV-Z]{26}$/);
+export const BoardId = idSchema("node").describe("The board's id, its node id `node_…`, as intelligence_node_list or intelligence_board_create returned it.");
+export const TaskId = idSchema("node").describe("The task's id, its node id `node_…`, as intelligence_board_task_list returned it.");
+// `label_…` is no word of the grammar (#42): a row of a board, not a resource. Columns are in
+// `columns.ts`.
+export const LabelId = z
+    .templateLiteral([z.literal("label"), z.literal("_"), ulid])
+    .describe("A label of this board, `label_…`, as intelligence_board_get returned it.");
+// A run of a process (#43). The same id `runs.ts` names `RunId`; written here again because
+// `runs.ts` builds on this file and the graph between the files stays acyclic (trap C009).
+const RunRef = idSchema("run");
+// What a board is (#43, Nodes › Board › Prozess): a board, or a process whose runs are copies of it.
+export const boardKinds = ["board", "process"];
+export const BoardKind = z
+    .enum(boardKinds)
+    .describe("board: a board people work on. process: a template whose runs the Operator works through, each a copy of its columns and tasks; it needs a machine (an Operator) with write on it, a first column of type backlog, and every task of the template in that first column.");
+const Name = z.string().max(200);
+const ColumnInput = z.strictObject({
+    columnId: ColumnId.optional().describe("The column to keep, as intelligence_board_get returned it. Leaving it out makes a new column."),
+    name: Name.describe("The column's name as people read it."),
+    type: ColumnType,
+    visible: z
+        .boolean()
+        .optional()
+        .describe("Whether the board shows the column. Leaving it out shows it, except the archive column, which is hidden by default."),
+});
+const Columns = z
+    .array(ColumnInput)
+    .min(2)
+    .max(30)
+    .describe("The board's columns, all of them, in their order: a column with columnId is kept, one without is made, and a column left out is removed. Exactly one column of type archive, always last; it cannot be removed. A column that still holds tasks cannot be removed: move them first.");
+export const BoardCreateInput = z.strictObject({
+    // ⚠️ Required and nullable (trap C015): null is the top level of Shared.
+    parentId: NodeId.nullable().describe("The folder to create the board in, one you can write to; null creates it on the top level of Shared, visible to you until you share it."),
+    name: Name.describe("The board's name as people read it."),
+    columns: Columns.optional().describe("The board's columns in their order, without columnId. Exactly one of type archive, last. Leaving it out gives Backlog, Open, In progress, Done and Archive, named in your language."),
+    idempotencyKey: IdempotencyKey,
+});
+export const BoardGetInput = z.strictObject({ boardId: BoardId });
+// The instruction of a board or a dashboard (E87, #354), Markdown for every AI working on it.
+const BoardInstruction = z.string().max(200_000);
+export const BoardUpdateInput = z.strictObject({
+    boardId: BoardId,
+    rev: Rev,
+    kind: BoardKind.optional().describe("Make the board a process or a board again. Saving a process is refused with conflict while no machine can write on the board, the first column is not of type backlog, or a task of the template stands outside the first column."),
+    schedule: Schedule.optional().describe("When a run of the process or of the validation falls due (Ausführung), as on a dashboard. Leaving it out keeps it; a board made a process without one runs by hand."),
+    instruction: BoardInstruction.optional().describe("The board's instruction, Markdown: what the board is about and how every AI working on it goes about it. It comes along with every read of the board and its tasks over MCP. On the validation board only an admin in admin mode changes it. An empty text removes it; leaving it out keeps it."),
+    columns: Columns.optional(),
+    labels: z
+        .array(z.strictObject({
+        labelId: LabelId.optional().describe("The label to keep or rename. Leaving it out makes a new label."),
+        name: Name.describe("The label's name; one name per board, whatever its case."),
+    }))
+        .max(200)
+        .optional()
+        .describe("The board's labels, all of them: a label with labelId is kept or renamed, one without is made, and a label left out is removed from the board and from every task carrying it."),
+});
+export const BoardColumn = z.strictObject({
+    columnId: ColumnId,
+    name: z.string(),
+    type: ColumnType,
+    visible: z.boolean(),
+});
+export const BoardLabel = z.strictObject({ labelId: LabelId, name: z.string() });
+// What stands between a board and saving it as a process (#43): the UI shows a box for each, and the
+// server refuses on its own (trap P066).
+export const ProcessCheck = z.strictObject({
+    // A machine (an Operator) holds write on the board (#334: any machine, whatever its roles).
+    operator: z.boolean(),
+    // The first column is of type backlog.
+    firstColumnBacklog: z.boolean(),
+    // How many tasks of the template stand outside the first column.
+    outside: z.number().int(),
+    // Every machine that is neither locked nor archived, whatever its roles, by name (#148, #334):
+    // whom the settings offer "Für Operator freigeben". Empty when there is none. Readable with the board,
+    // without any right in `access`.
+    operators: z.array(z.strictObject({ userId: z.string(), name: z.string() })),
+});
+export const BoardDetail = z.strictObject({
+    boardId: NodeId,
+    name: z.string(),
+    kind: BoardShownKind,
+    // A system part with a lock, null for every other board.
+    system: BoardSystem.nullable(),
+    // A process's or the validation's schedule, its zone filled; null for a board.
+    schedule: Schedule.nullable(),
+    // The board's instruction (E87, #354; the validation's since #47), Markdown; null without one.
+    instruction: z.string().nullable(),
+    // The next moment a run falls due, null for a board, a manual process or dates that have passed.
+    nextRunAt: z.iso.datetime().nullable(),
+    // The moment a run is owed for now (passed, unanswered, no run open), else null.
+    dueAt: z.iso.datetime().nullable(),
+    processCheck: ProcessCheck,
+    // Who carries the validation (E79, #378): the holder of the role `validator` while they can act,
+    // for every reader of the validation board; null without one and for every other board.
+    validator: NodePerson.nullable(),
+    columns: z.array(BoardColumn),
+    labels: z.array(BoardLabel),
+    rights: z.strictObject({ write: z.boolean() }),
+    rev: z.number().int(),
+    updatedAt: z.iso.datetime(),
+});
+// The most one page of a board's tasks holds: a board is read whole for the kanban.
+const TaskLimit = z.coerce
+    .number()
+    .int()
+    .min(1)
+    .max(500)
+    .describe("How many tasks one page holds, 1 to 500. Leaving it out gives 200.");
+export const BoardTaskListInput = z.strictObject({
+    boardId: BoardId,
+    runId: RunRef.optional().describe("The run of this process whose tasks and columns to list. Leaving it out lists the template, the board itself."),
+    columnId: ColumnId.optional().describe("Only the tasks in this column."),
+    type: ColumnType.optional().describe("Only the tasks in columns of this type. The archive column's tasks are listed only with type archive."),
+    assigneeId: idSchema("user").optional().describe("Only the tasks assigned to this person."),
+    labelId: LabelId.optional().describe("Only the tasks carrying this label."),
+    parentTaskId: TaskId.optional().describe("Only the direct subtasks of this task."),
+    cursor: z
+        .string()
+        .max(1000)
+        .optional()
+        .describe("The nextCursor of the previous page, unchanged. Leaving it out starts at the top."),
+    limit: TaskLimit.optional(),
+});
+const Title = z.string().max(500).describe("The task's title.");
+const Content = z
+    .string()
+    .max(200_000)
+    .describe("The task's text in Markdown. Images linked in it (an image URL, or a link to a file in Colab) show on the card.");
+const Time = z.iso.datetime({ offset: true });
+const StartsAt = Time.describe("When the task starts, ISO 8601.");
+const EndsAt = Time.describe("When the task ends, ISO 8601; only together with a start, not before it.");
+const Labels = z
+    .array(Name)
+    .max(50)
+    .describe("The names of the board's labels the task carries. A name the board does not have yet makes a new label on the board.");
+const DependsOn = z
+    .array(TaskId)
+    .max(100)
+    .describe("The tasks of the same board this one waits for. It is ready once each of them is in a column of type done or discarded.");
+const Position = z
+    .string()
+    .min(1)
+    .max(100)
+    .describe("The place in the column: a fractional-indexing key between the positions of the neighbours, as intelligence_board_task_list returns them. Leaving it out puts the task at the end of its column.");
+const Assignee = idSchema("user").describe("The one person responsible for the task, someone who can read the board. Leaving it out on create makes it you, on a process the first machine that can write on it.");
+export const BoardTaskCreateInput = z.strictObject({
+    boardId: BoardId,
+    runId: RunRef.optional().describe("Create the task in this running run of the process, in one of the run's columns. Leaving it out creates it in the template. A completed run takes no task."),
+    title: Title,
+    content: Content.optional(),
+    columnId: ColumnId.optional().describe("The column to put the task in. Leaving it out puts it in the board's first column."),
+    assigneeId: Assignee.optional(),
+    startsAt: StartsAt.optional(),
+    endsAt: EndsAt.optional(),
+    labels: Labels.optional(),
+    parentTaskId: TaskId.optional().describe("Make it a subtask of this task of the same board; it is still a card of its own."),
+    dependsOn: DependsOn.optional(),
+    position: Position.optional(),
+    idempotencyKey: IdempotencyKey,
+});
+export const TaskGetInput = z.strictObject({ taskId: TaskId });
+export const TaskUpdateInput = z.strictObject({
+    taskId: TaskId,
+    rev: Rev,
+    title: Title.optional(),
+    content: Content.optional(),
+    columnId: ColumnId.optional().describe("Move the task to this column of its board. Into the archive column archives it; out of it brings it back."),
+    assigneeId: Assignee.optional(),
+    startsAt: StartsAt.nullable()
+        .optional()
+        .describe("When the task starts, ISO 8601; null clears it and the end."),
+    endsAt: EndsAt.nullable()
+        .optional()
+        .describe("When the task ends, ISO 8601, not before the start; null clears it."),
+    labels: Labels.optional(),
+    parentTaskId: TaskId.nullable()
+        .optional()
+        .describe("Hang the task under this task of the same board; null makes it a task of its own again."),
+    dependsOn: DependsOn.optional(),
+    position: Position.optional(),
+    waiting: z
+        .boolean()
+        .optional()
+        .describe("true: the task waits, because something is missing that you cannot get yourself, a right above all; say in the task's chat what is missing and mention who can give it. false: it waits no more. The assignee sets and clears it with reading the board alone, and then sends nothing else; a move to another column clears it."),
+    comment: z
+        .string()
+        .max(10_000)
+        .optional()
+        .describe("Only on a ticket of the validation board, together with columnId: why it moves, kept in the ticket's history. Elsewhere it is invalid."),
+});
+// An image linked in a task's content: an outside URL, or a file in Colab the caller can read.
+export const TaskImage = z.union([
+    z.strictObject({ kind: z.literal("url"), url: z.string() }),
+    z.strictObject({ kind: z.literal("file"), nodeId: NodeId }),
+]);
+export const BoardTaskItem = z.strictObject({
+    taskId: NodeId,
+    // The run the task belongs to, null for a task of the board itself (the template of a process).
+    runId: RunRef.nullable(),
+    title: z.string(),
+    column: TaskColumn,
+    assignee: NodePerson,
+    startsAt: z.iso.datetime().nullable(),
+    endsAt: z.iso.datetime().nullable(),
+    labels: z.array(BoardLabel),
+    parentTaskId: NodeId.nullable(),
+    // How deep it hangs as a subtask: 0 for a task of its own.
+    depth: z.number().int(),
+    // Everything it waits for is in a column of type done or discarded (true without any).
+    ready: z.boolean(),
+    images: z.array(TaskImage),
+    // A ticket of the validation board (#47): the node it validates; null for every other task.
+    subject: TicketSubjectRef.nullable(),
+    // Whether the caller may change this task, as intelligence_task_update decides it: the board's
+    // right for a task, its node's for a ticket (#47: the node's responsible person, the holder of
+    // `validator` (#334), an admin in admin mode; only reading while the node is archived).
+    rights: z.strictObject({ write: z.boolean() }),
+    position: z.string(),
+    rev: z.number().int(),
+    updatedAt: z.iso.datetime(),
+});
+export const BoardTaskList = z.strictObject({
+    items: z.array(BoardTaskItem),
+    nextCursor: z.string().nullable(),
+    // Over MCP only (E87, #354): the board's instruction, a run's copy of it with `runId`; null
+    // without one.
+    instruction: z.string().nullable().optional(),
+});
+const TaskRef = z.strictObject({ taskId: NodeId, title: z.string(), column: TaskColumn });
+export const TaskDetail = z.strictObject({
+    taskId: NodeId,
+    boardId: NodeId,
+    runId: RunRef.nullable(),
+    title: z.string(),
+    content: z.string(),
+    column: TaskColumn,
+    columnAt: z.iso.datetime(),
+    columnBy: NodePerson,
+    assignee: NodePerson,
+    startsAt: z.iso.datetime().nullable(),
+    endsAt: z.iso.datetime().nullable(),
+    labels: z.array(BoardLabel),
+    parentTaskId: NodeId.nullable(),
+    position: z.string(),
+    // The crumbs: the board with what board it is (its icon, #385), then every task above it, top down.
+    path: z.strictObject({
+        board: z.strictObject({ boardId: NodeId, name: z.string(), boardKind: BoardShownKind }),
+        tasks: z.array(z.strictObject({ taskId: NodeId, title: z.string() })),
+    }),
+    // The direct subtasks, and how many of them are done.
+    subtasks: z.strictObject({
+        items: z.array(TaskRef),
+        done: z.number().int(),
+        total: z.number().int(),
+    }),
+    dependencies: z.array(TaskRef),
+    ready: z.boolean(),
+    images: z.array(TaskImage),
+    rights: z.strictObject({ write: z.boolean() }),
+    // The task waits (#377, E77): its assignee lacks something, a right above all, and asked in the
+    // chat. Shown in place of the column; null while it does not wait.
+    waiting: z.strictObject({ since: z.iso.datetime(), by: NodePerson }).nullable(),
+    // A ticket of the validation board (#47): the node it validates with its path, and every move,
+    // newest first. Both null for every other task.
+    subject: TicketSubject.nullable(),
+    history: z.array(TicketMove).nullable(),
+    createdBy: NodePerson,
+    rev: z.number().int(),
+    archivedAt: z.iso.datetime().nullable(),
+    createdAt: z.iso.datetime(),
+    updatedAt: z.iso.datetime(),
+    // Over MCP only (E87, #354): the instruction of the task's board, of its run for a run's task;
+    // null without one.
+    instruction: z.string().nullable().optional(),
+});

package/dist/columns/columns.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export declare const ColumnId: z.ZodTemplateLiteral<`column_${string}`>;
+export type ColumnId = z.infer<typeof ColumnId>;
+export declare const columnTypes: readonly ["backlog", "open", "progress", "done", "discarded", "blocked", "archive"];
+export declare const ColumnType: z.ZodEnum<{
+    backlog: "backlog";
+    open: "open";
+    progress: "progress";
+    done: "done";
+    discarded: "discarded";
+    blocked: "blocked";
+    archive: "archive";
+}>;
+export type ColumnType = z.infer<typeof ColumnType>;
+export declare const TaskColumn: z.ZodObject<{
+    columnId: z.ZodTemplateLiteral<`column_${string}`>;
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        backlog: "backlog";
+        open: "open";
+        progress: "progress";
+        done: "done";
+        discarded: "discarded";
+        blocked: "blocked";
+        archive: "archive";
+    }>;
+}, z.core.$strict>;
+export type TaskColumn = z.infer<typeof TaskColumn>;

package/dist/columns/columns.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+// A board's columns as other domains name them (#42, #47): the id, the seven types and a column as a
+// task or a node's validation shows it. A base file of its own, so `nodes.ts` can carry a node's
+// validation status without importing `boards.ts`, which imports `nodes.ts` (trap C009).
+// A ULID in Crockford base32, as `ids.ts` takes it.
+const ulid = z.string().regex(/^[0-9A-HJKMNP-TV-Z]{26}$/);
+// `column_…` is no word of the grammar (#42): a row of a board, not a resource.
+export const ColumnId = z
+    .templateLiteral([z.literal("column"), z.literal("_"), ulid])
+    .describe("A column of this board, `column_…`, as intelligence_board_get returned it.");
+// The seven types of a column (E40, E43), each shown as an icon.
+export const columnTypes = [
+    "backlog",
+    "open",
+    "progress",
+    "done",
+    "discarded",
+    "blocked",
+    "archive",
+];
+export const ColumnType = z
+    .enum(columnTypes)
+    .describe("What a column means: backlog (not ready yet), open (waiting), progress (being worked on), done (closed with yes), discarded (closed with no: rejected or lost, no error), blocked (an error), archive (the shelf at the bottom of every board, hidden by default).");
+export const TaskColumn = z.strictObject({
+    columnId: ColumnId,
+    name: z.string(),
+    type: ColumnType,
+});

package/dist/connections/connections.d.ts

@@ -0,0 +1,149 @@
+import { z } from "zod";
+export declare const ConnectionId: z.ZodTemplateLiteral<`connection_${string}`>;
+export declare const ConnectionState: z.ZodEnum<{
+    expired: "expired";
+    running: "running";
+    not_connected: "not_connected";
+    unreachable: "unreachable";
+}>;
+export type ConnectionState = z.infer<typeof ConnectionState>;
+export declare const ConnectionListInput: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strict>;
+export type ConnectionListInput = z.infer<typeof ConnectionListInput>;
+export declare const ConnectionGetInput: z.ZodObject<{
+    connectionId: z.ZodTemplateLiteral<`connection_${string}`>;
+}, z.core.$strict>;
+export type ConnectionGetInput = z.infer<typeof ConnectionGetInput>;
+export declare const ConnectionCreateInput: z.ZodObject<{
+    connectorId: z.ZodString;
+    settings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    secrets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export type ConnectionCreateInput = z.infer<typeof ConnectionCreateInput>;
+export declare const ConnectionUpdateInput: z.ZodObject<{
+    connectionId: z.ZodTemplateLiteral<`connection_${string}`>;
+    settings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    secrets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export type ConnectionUpdateInput = z.infer<typeof ConnectionUpdateInput>;
+export declare const ConnectionTestInput: z.ZodObject<{
+    connectionId: z.ZodTemplateLiteral<`connection_${string}`>;
+}, z.core.$strict>;
+export type ConnectionTestInput = z.infer<typeof ConnectionTestInput>;
+export declare const ConnectionRevokeInput: z.ZodObject<{
+    connectionId: z.ZodTemplateLiteral<`connection_${string}`>;
+}, z.core.$strict>;
+export type ConnectionRevokeInput = z.infer<typeof ConnectionRevokeInput>;
+export declare const ConnectionCredential: z.ZodObject<{
+    name: z.ZodString;
+    setAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type ConnectionCredential = z.infer<typeof ConnectionCredential>;
+export declare const Connection: z.ZodObject<{
+    connectorId: z.ZodString;
+    connectionId: z.ZodNullable<z.ZodTemplateLiteral<`connection_${string}`>>;
+    enabled: z.ZodBoolean;
+    configured: z.ZodBoolean;
+    state: z.ZodEnum<{
+        expired: "expired";
+        running: "running";
+        not_connected: "not_connected";
+        unreachable: "unreachable";
+    }>;
+    checkedAt: z.ZodNullable<z.ZodISODateTime>;
+    expiredAt: z.ZodNullable<z.ZodISODateTime>;
+    expiredStatus: z.ZodNullable<z.ZodNumber>;
+    failedCalls: z.ZodNumber;
+    credentials: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        setAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Connection = z.infer<typeof Connection>;
+export declare const ConnectionDetail: z.ZodObject<{
+    connectorId: z.ZodString;
+    connectionId: z.ZodNullable<z.ZodTemplateLiteral<`connection_${string}`>>;
+    enabled: z.ZodBoolean;
+    configured: z.ZodBoolean;
+    state: z.ZodEnum<{
+        expired: "expired";
+        running: "running";
+        not_connected: "not_connected";
+        unreachable: "unreachable";
+    }>;
+    checkedAt: z.ZodNullable<z.ZodISODateTime>;
+    expiredAt: z.ZodNullable<z.ZodISODateTime>;
+    expiredStatus: z.ZodNullable<z.ZodNumber>;
+    failedCalls: z.ZodNumber;
+    credentials: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        setAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    settings: z.ZodRecord<z.ZodString, z.ZodString>;
+}, z.core.$strict>;
+export type ConnectionDetail = z.infer<typeof ConnectionDetail>;
+export declare const ConnectionList: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        connectorId: z.ZodString;
+        connectionId: z.ZodNullable<z.ZodTemplateLiteral<`connection_${string}`>>;
+        enabled: z.ZodBoolean;
+        configured: z.ZodBoolean;
+        state: z.ZodEnum<{
+            expired: "expired";
+            running: "running";
+            not_connected: "not_connected";
+            unreachable: "unreachable";
+        }>;
+        checkedAt: z.ZodNullable<z.ZodISODateTime>;
+        expiredAt: z.ZodNullable<z.ZodISODateTime>;
+        expiredStatus: z.ZodNullable<z.ZodNumber>;
+        failedCalls: z.ZodNumber;
+        credentials: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            setAt: z.ZodISODateTime;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type ConnectionList = z.infer<typeof ConnectionList>;
+export declare const ConnectionTestResult: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    ok: z.ZodLiteral<true>;
+    detail: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    ok: z.ZodLiteral<false>;
+    error: z.ZodString;
+}, z.core.$strict>], "ok">;
+export type ConnectionTestResult = z.infer<typeof ConnectionTestResult>;
+export declare const ConnectionTested: z.ZodObject<{
+    connection: z.ZodObject<{
+        connectorId: z.ZodString;
+        connectionId: z.ZodNullable<z.ZodTemplateLiteral<`connection_${string}`>>;
+        enabled: z.ZodBoolean;
+        configured: z.ZodBoolean;
+        state: z.ZodEnum<{
+            expired: "expired";
+            running: "running";
+            not_connected: "not_connected";
+            unreachable: "unreachable";
+        }>;
+        checkedAt: z.ZodNullable<z.ZodISODateTime>;
+        expiredAt: z.ZodNullable<z.ZodISODateTime>;
+        expiredStatus: z.ZodNullable<z.ZodNumber>;
+        failedCalls: z.ZodNumber;
+        credentials: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            setAt: z.ZodISODateTime;
+        }, z.core.$strict>>;
+        settings: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>;
+    test: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        ok: z.ZodLiteral<true>;
+        detail: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        ok: z.ZodLiteral<false>;
+        error: z.ZodString;
+    }, z.core.$strict>], "ok">;
+}, z.core.$strict>;
+export type ConnectionTested = z.infer<typeof ConnectionTested>;

package/dist/connections/connections.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { ConnectorId } from "../connectors/connectors.js";
+import { idSchema } from "../ids/ids.js";
+import { Limit } from "../list-input.js";
+// The vault of the connectors (#6): the inputs of `connectors_connection_*` and the answers the UI
+// (#7) reads. A secret goes in and never comes out; an answer names a secret's field, never its value.
+//
+// ⚠️ No field of an answer is called `secrets`, `key` or `secret`: `/mcp` strikes every value under such
+// a key (`redactSecrets` in `shared`), so UI and AI would read different answers. The set secrets are
+// `credentials`, each with `name` and `setAt`.
+export const ConnectionId = idSchema("connection");
+// `not_connected`: never connected, or revoked. `running`: the last test succeeded. `unreachable`: the
+// last test failed for another reason than the credential. `expired`: the provider refused the
+// credential with 401 or 403.
+export const ConnectionState = z.enum(["not_connected", "running", "unreachable", "expired"]);
+// A field's value as the form sends it. Long enough for a private key in PEM; an empty value counts
+// as missing, so it clears an optional field.
+const FieldValues = z.record(z.string().min(1).max(100), z.string().max(20_000));
+export const ConnectionListInput = z.strictObject({
+    cursor: ConnectorId.optional(),
+    limit: Limit.optional(),
+});
+export const ConnectionGetInput = z.strictObject({ connectionId: ConnectionId });
+export const ConnectionCreateInput = z.strictObject({
+    connectorId: ConnectorId,
+    settings: FieldValues.optional(),
+    secrets: FieldValues.optional(),
+});
+// Settings: the given ones replace theirs, the rest stay. Secrets: only the given ones are replaced.
+export const ConnectionUpdateInput = z.strictObject({
+    connectionId: ConnectionId,
+    settings: FieldValues.optional(),
+    secrets: FieldValues.optional(),
+});
+export const ConnectionTestInput = z.strictObject({ connectionId: ConnectionId });
+export const ConnectionRevokeInput = z.strictObject({ connectionId: ConnectionId });
+// A set secret: its field and when it was set, never its value.
+export const ConnectionCredential = z.strictObject({
+    name: z.string(),
+    setAt: z.iso.datetime(),
+});
+// One connector's connection as the list shows it, also for a connector never connected.
+export const Connection = z.strictObject({
+    connectorId: ConnectorId,
+    // Null while the connector was never connected.
+    connectionId: ConnectionId.nullable(),
+    // The connector stands in the installation's `colab.config.ts`; false for a row whose connector
+    // left the list.
+    enabled: z.boolean(),
+    // Settings and secrets are complete and valid.
+    configured: z.boolean(),
+    state: ConnectionState,
+    checkedAt: z.iso.datetime().nullable(),
+    // Since when the provider refuses the credential, and with which status.
+    expiredAt: z.iso.datetime().nullable(),
+    expiredStatus: z.number().int().nullable(),
+    failedCalls: z.number().int(),
+    credentials: z.array(ConnectionCredential),
+});
+export const ConnectionDetail = Connection.extend({ settings: z.record(z.string(), z.string()) });
+export const ConnectionList = z.strictObject({
+    items: z.array(Connection),
+    nextCursor: ConnectorId.nullable(),
+});
+// The connector's own test against its provider; an error is struck of every secret.
+export const ConnectionTestResult = z.discriminatedUnion("ok", [
+    z.strictObject({ ok: z.literal(true), detail: z.string().nullable() }),
+    z.strictObject({ ok: z.literal(false), error: z.string() }),
+]);
+// The answer of create, update and test: the connection after the test, and the test.
+export const ConnectionTested = z.strictObject({
+    connection: ConnectionDetail,
+    test: ConnectionTestResult,
+});