@anchrd/colab-sdk 0.0.0-stage → 0.1.1

package/dist/nodes/nodes.js

@@ -0,0 +1,354 @@
+import { z } from "zod";
+import { ColumnType, TaskColumn } from "../columns/columns.js";
+import { idSchema } from "../ids/ids.js";
+import { Instructions } from "../instructions/instructions.js";
+import { Flag, Limit as PageSize } from "../list-input.js";
+import { IdempotencyKey, Rev } from "../primitives/primitives.js";
+import { MessageMachine } from "../users/users.js";
+// Nodes, folders and the three areas of the tree (#36): the inputs of `intelligence_node_list`,
+// `_get`, `_update`, `_move`, `intelligence_folder_create` and `intelligence_user_list`, and the
+// answers the UI draws. Every input field carries its description (trap C004): HTTP, MCP and the
+// types read the same sentence, and `nodes.unit.ts` holds that none is missing.
+export const NodeId = idSchema("node").describe("The node's id, `node_…`.");
+// The password of a secret document or table (#357), the node's one sub-resource `secret`. Here and
+// not in `secrets.ts`, because `NodeDetail` names it and `secrets.ts` imports from this file (C012).
+export const SecretId = idSchema("secret").describe("The id of a secret node's password, `secret_…`, from intelligence_node_get (secretId).");
+// What a secret document or table says about itself (#357, E94), in every answer that names it:
+// `secret` only on a secret node, `locked` whether its content is withheld from this caller. Both are
+// absent on every other node. Every AI and every machine reads a secret node locked.
+const secretFlag = z
+    .literal(true)
+    .optional()
+    .describe("Only on a secret document or table: its content is encrypted and needs its password.");
+const lockedFlag = z
+    .boolean()
+    .optional()
+    .describe("Only on a secret node: true when its content is withheld from you (no AI and no machine ever reads it; a person unlocks it in the browser).");
+export const SecretFields = { secret: secretFlag, locked: lockedFlag };
+// Every kind lives in the one table `nodes` (E55, E64). A task never stands in the tree (E67).
+export const nodeKinds = [
+    "folder",
+    "document",
+    "table",
+    "board",
+    "task",
+    "dashboard",
+    "file",
+];
+export const NodeKind = z.enum(nodeKinds);
+// Only these kinds have a responsible person (E32): the one who answers for the content's validity.
+export const responsibleKinds = [
+    "document",
+    "table",
+    "file",
+];
+// A system part with a lock (E67): renaming, moving, archiving, deleting and sharing refuse. The one
+// validation board (#47); the board Vorschläge in every root is gone (E88, #355). It lives here, not
+// beside the boards, because the listing carries it too (#52) and `boards.ts` imports from this file.
+export const BoardSystem = z.enum(["validation"]);
+// What a board is as an answer shows it: besides the two a caller makes (`boardKinds` in
+// `boards.ts`), the one validation board of a Colab (#47), which no caller makes or turns into. Here
+// for the same reason as `BoardSystem`: the lists carry it too (#227).
+export const BoardShownKind = z.enum(["board", "process", "validation"]);
+// The three sections of the tree (Funktionen › Seitenbaum, E67).
+export const NodeSection = z.enum(["own", "shared", "users"]);
+export const NodeSort = z.enum(["name", "updated", "kind", "status"]);
+const Limit = PageSize.describe("How many entries one page holds, 1 to 100. Leaving it out gives 50.");
+// The name a person reads. ⚠️ A name starting with a dot hides the node from listings (`.Intern`),
+// which is appearance only: rights, search and links still see it.
+const NodeName = z
+    .string()
+    .max(200)
+    .describe("The name as people read it. A name that starts with a dot (`.Intern`) hides the node from listings until hidden ones are asked for; it is never a permission.");
+// The words a search looks for (#48, E67): searching is `intelligence_node_list` with `query`.
+export const NodeQuery = z
+    .string()
+    .trim()
+    .min(2)
+    .max(200)
+    .describe("Search instead of listing: words to find in titles, the text of documents, tables, files and tasks and the values of dashboards, at least two characters; each word also finds longer words it begins (preis finds Preisliste). Only what you can read, never archived nodes or chats. parentId narrows it to that folder and everything below it, section to own, shared or users; leaving both out searches own and shared together. The hits come in the order of their rank, grouped by folder; sort, foldersFirst and includeHidden do not apply.");
+export const NodeListInput = z.strictObject({
+    parentId: NodeId.optional().describe("List the children of this folder. Give exactly one of parentId, section and nodeIds; with query at most one of parentId and section."),
+    section: NodeSection.optional().describe("List a section of the tree instead of a folder: own (what lies in your own root folder), shared (the tops of everything others let you reach) or users (every other person's root folder, only for an admin in admin mode)."),
+    query: NodeQuery.optional(),
+    includeHidden: Flag.optional().describe("Also list nodes whose name starts with a dot. Leaving it out hides them."),
+    sort: NodeSort.optional().describe("The order: name (default, A to Z), updated (most recently changed first), kind, or status (the type of the column the validation ticket stands in: backlog, open, progress, done, discarded, blocked, archive, then nodes without a ticket)."),
+    foldersFirst: Flag.optional().describe("Put folders before everything else, each group in the chosen order."),
+    cursor: z
+        .string()
+        .max(1000)
+        .optional()
+        .describe("The nextCursor of the previous page, unchanged. Leaving it out starts at the top."),
+    limit: Limit.optional(),
+    archived: Flag.optional().describe("List the archive instead: with section own or shared the archived entries there, each with its path and when it was archived; with parentId the archived nodes in that folder, also inside an archived one. Leaving it out lists what is not archived."),
+    // Over REST one comma-separated value (`?nodeIds=node_…,node_…`): a query string carries text.
+    nodeIds: z
+        .preprocess((value) => (typeof value === "string" ? value.split(",") : value), z.array(NodeId).min(1).max(100))
+        .optional()
+        .describe("Name these nodes, 1 to 100, for links and images in a text: the answer holds only those you can read, in the order given; one you cannot read or that does not exist is left out without a note."),
+});
+// A person behind a `user_…` id, as `access` names them. A deleted account has no name (null).
+export const NodePerson = z.strictObject({
+    userId: z.string(),
+    name: z.string().nullable(),
+    kind: z.enum(["human", "machine"]).nullable(),
+});
+// The crumbs above a node, from the first level the caller can read, and the section they start in.
+export const NodePath = z.strictObject({
+    section: NodeSection,
+    items: z.array(z.strictObject({ nodeId: NodeId, name: z.string() })),
+});
+export const NodeListItem = z.strictObject({
+    nodeId: NodeId,
+    kind: NodeKind,
+    name: z.string(),
+    hidden: z.boolean(),
+    // A root folder belongs to this person; null for every other node.
+    rootOf: z.string().nullable(),
+    // That person's picture as `access.directory.resolve` gives it (#123): null for every other node,
+    // for a machine and for a person without one.
+    rootImage: z.string().nullable(),
+    createdBy: NodePerson,
+    // Only for document, table and file (E32); null for every other kind.
+    responsible: NodePerson.nullable(),
+    // Bytes of the current version (#38), for the phone; null for a kind without versions and for a
+    // document, table or file that has none yet.
+    size: z.number().int().nullable(),
+    updatedAt: z.iso.datetime(),
+    // How many people hold a grant on it, inherited ones included.
+    sharedWith: z.number().int(),
+    // When it went into the archive; null for a node that is not archived.
+    archivedAt: z.iso.datetime().nullable(),
+    // The validation status (#47): the type of the column its ticket stands in; null for a kind that is
+    // not validated.
+    status: ColumnType.nullable(),
+    // A board that is a system part with a lock (#52: the tree draws the lock and no ⋯); null for
+    // every other node.
+    system: BoardSystem.nullable(),
+    // What a board is (#227): the tree, the folder and the archive draw a process and the validation
+    // board apart from a board; null for every other kind.
+    boardKind: BoardShownKind.nullable(),
+    // Only in the archive (`archived: true`): where it stood, as the caller can read it, for a folder
+    // how many archived nodes it holds directly, and for a board how many archived tasks (#135).
+    path: NodePath.optional(),
+    count: z.number().int().nullable().optional(),
+    // Only on a secret document or table (#357): the tree draws the lock.
+    secret: secretFlag,
+    // Only in section users (E97, #447): the root of an archived account, listed only while it still
+    // holds something, after all others.
+    rootArchived: z
+        .literal(true)
+        .optional()
+        .describe("Only in section users: the root folder of an archived account. It is listed only while something in it is not archived, after all others."),
+});
+export const NodeList = z.strictObject({
+    items: z.array(NodeListItem),
+    nextCursor: z.string().nullable(),
+    // Only with section own and not archived (#52): the caller's root folder, the parent of what is
+    // listed and the folder something new in Own is created in.
+    rootId: NodeId.optional(),
+    // Over MCP only, with parentId: the INSTRUCTIONS of that folder (#39).
+    instructions: Instructions.optional(),
+});
+// Where a hit was found (#386), told before its passage: in its name (`title`), its text (`text`),
+// a column of a table (`column`, `label` the column's name), a page of a file (`page`, `label` the
+// page's number as text) or, for a task found by its name, the card on a board (`card`, `label` the
+// board's name where the caller reads it). `label` is null where there is nothing to name.
+export const NodeHitFoundIn = z.strictObject({
+    kind: z.enum(["title", "text", "column", "page", "card"]),
+    label: z.string().nullable(),
+});
+// A hit of a search (#48): the node, where it stands for the caller, the passage that matched and its
+// place in the fused order.
+export const NodeHit = z.strictObject({
+    nodeId: NodeId,
+    kind: NodeKind,
+    name: z.string(),
+    // The crumbs above it, from the first level the caller can read, like `path` of the archive.
+    path: NodePath,
+    // ⚠️ Plain text: the matched words stand between <mark> and </mark>, and nothing else in it is
+    // markup. The UI splits on the two marks and never renders it as HTML (the text is a person's).
+    snippet: z.string(),
+    foundIn: NodeHitFoundIn,
+    // 1 is the best hit; counted over the whole answer, not per page.
+    rank: z.number().int().min(1),
+    // The validation status like `NodeListItem.status` (#236): the type of the column its ticket stands
+    // in; null for a kind that is not validated.
+    status: ColumnType.nullable(),
+    // The last change, beside the status on the hit (#236).
+    updatedAt: z.iso.datetime(),
+    // What a board is, like `NodeListItem.boardKind` (#227); null for every other kind.
+    boardKind: BoardShownKind.nullable(),
+    // Only on a secret document or table (#429): the hit draws the lock. Its content is never searched.
+    secret: secretFlag,
+});
+// The hits of one folder ("Vertrieb · 7 Treffer"): the folder the hits stand in, null where the
+// caller cannot read it or a hit stands on the top level of Shared, and its crumbs.
+export const NodeHitGroup = z.strictObject({
+    parentId: NodeId.nullable(),
+    path: NodePath,
+    count: z.number().int().min(1),
+});
+export const NodeSearch = z.strictObject({
+    items: z.array(NodeHit),
+    // Every folder with hits, over the whole answer, in the order of each folder's best hit.
+    groups: z.array(NodeHitGroup),
+    nextCursor: z.string().nullable(),
+    // unavailable: the semantic half did not answer, and the hits are the lexical half alone (E68).
+    semantic: z.enum(["ok", "unavailable"]),
+});
+// The search index for the page System (#48, #68): the last rebuild and whether one is running.
+// Answered by `GET /api/intelligence/index`, a door without a tool (E67, E69).
+export const SearchIndexState = z.strictObject({
+    running: z.boolean(),
+    last: z
+        .strictObject({
+        requestedBy: z.string(),
+        requestedAt: z.iso.datetime(),
+        startedAt: z.iso.datetime().nullable(),
+        completedAt: z.iso.datetime().nullable(),
+    })
+        .nullable(),
+});
+export const NodeGetInput = z.strictObject({ nodeId: NodeId });
+// A document's, table's or file's validation (#47, Seiten › Validierung): where its ticket stands.
+export const NodeValidation = z.strictObject({
+    ticketId: NodeId,
+    // The ticket's column; its type is the node's status.
+    column: TaskColumn,
+    // The end of the ticket's period, set by the Operator ("gültig bis"); null without one.
+    validUntil: z.iso.datetime().nullable(),
+    // Who is asked when the validity is to be decided: the node's responsible person.
+    responsible: NodePerson,
+    // What holds for exactly this node, the ticket's Markdown; empty without a word.
+    content: z.string(),
+});
+export const NodeDetail = z.strictObject({
+    nodeId: NodeId,
+    kind: NodeKind,
+    name: z.string(),
+    hidden: z.boolean(),
+    rootOf: z.string().nullable(),
+    // A board that is a system part with a lock (#52): its page shows no ⋯; null for every other node.
+    system: BoardSystem.nullable(),
+    // What a board is, like `NodeListItem.boardKind` (#227): the recently opened nodes of the search
+    // are these; null for every other kind.
+    boardKind: BoardShownKind.nullable(),
+    // Null at the top level of Shared, and where the caller cannot read the parent.
+    parentId: NodeId.nullable(),
+    path: NodePath,
+    createdBy: NodePerson,
+    responsible: NodePerson.nullable(),
+    // What the caller may do here; reading is implied by the answer itself.
+    rights: z.strictObject({ write: z.boolean(), share: z.boolean() }),
+    // Only for a folder: how many hidden nodes it holds ("Versteckte anzeigen").
+    hiddenCount: z.number().int().nullable(),
+    // Bytes of the current version, as in the listing (#38).
+    size: z.number().int().nullable(),
+    rev: z.number().int(),
+    // When it went into the archive; null for a node that is not archived.
+    archivedAt: z.iso.datetime().nullable(),
+    // Only for an archived node: per table, the rows deleting it for good would take along.
+    purge: z.record(z.string(), z.number().int()).nullable(),
+    createdAt: z.iso.datetime(),
+    updatedAt: z.iso.datetime(),
+    // Only for a document, table or file with a ticket (#47); null for every other node.
+    validation: NodeValidation.nullable(),
+    // Over MCP only: the INSTRUCTIONS of the node's folder, the node itself for a folder (#39).
+    instructions: Instructions.optional(),
+    // Over MCP only, for a board, a task and a dashboard (E87, #354): the board's or dashboard's own
+    // instruction, a task's board's (its run's copy for a run's task); null without one.
+    instruction: z.string().nullable().optional(),
+    // Only on a secret document or table (#357, E94): the password's id (for its settings), whether
+    // its content is withheld from this caller, and until when this browser session holds it unlocked
+    // (null when it does not; an admin in admin mode reads it without).
+    ...SecretFields,
+    secretId: SecretId.optional(),
+    // Who made it secret (they and an admin change its password and make it public again) and when its
+    // password was last set (#429); never the password.
+    secretBy: NodePerson.optional(),
+    secretSetAt: z.iso.datetime().optional(),
+    unlockedUntil: z.iso.datetime().nullable().optional(),
+});
+export const NodeUpdateInput = z.strictObject({
+    nodeId: NodeId,
+    rev: Rev,
+    name: NodeName.optional(),
+    responsibleId: idSchema("user")
+        .optional()
+        .describe("Make this person responsible for the content's validity. Only for documents, tables and files, and only someone who can read the node."),
+});
+export const NodeMoveInput = z.strictObject({
+    nodeId: NodeId,
+    // ⚠️ Required and nullable (trap C015): null is the top level of Shared, and leaving the field out
+    // is refused, so a forgetful caller cannot move a node to the top by accident.
+    parentId: NodeId.nullable().describe("The folder to move the node into, one you can write to; null puts it on the top level of Shared. The node takes the grants of its new folder and loses those of the old one."),
+});
+// Who reaches a node after inheritance (`readersOf`), and where it comes from.
+export const NodeReader = z.strictObject({
+    userId: z.string(),
+    name: z.string().nullable(),
+    kind: z.enum(["human", "machine"]).nullable(),
+    right: z.enum(["read", "write", "share"]),
+    // creator: made this node; direct: a grant on this node; inherited: from the folder `fromNodeId`,
+    // by a grant on it or by having made it.
+    origin: z.enum(["creator", "direct", "inherited"]),
+    fromNodeId: NodeId,
+});
+export const NodeMoved = z.strictObject({
+    nodeId: NodeId,
+    parentId: NodeId.nullable(),
+    // Who can read the node now, for the short note the UI shows after the drop.
+    readers: z.array(NodeReader),
+});
+export const FolderCreateInput = z.strictObject({
+    // ⚠️ Required and nullable (trap C015): null is the top level of Shared.
+    parentId: NodeId.nullable().describe("The folder to create it in, one you can write to; null creates it on the top level of Shared, visible to you until you share it."),
+    name: NodeName,
+    idempotencyKey: IdempotencyKey,
+});
+export const FolderCreated = z.strictObject({
+    nodeId: NodeId,
+    kind: z.literal("folder"),
+    name: z.string(),
+    hidden: z.boolean(),
+    parentId: NodeId.nullable(),
+    rev: z.number().int(),
+    createdAt: z.iso.datetime(),
+    updatedAt: z.iso.datetime(),
+});
+// ⚠️ Not `UserListInput`, the name `toolSchemaName` derives: that one is `access_user_list`'s, and
+// the derivation drops the package. The package word goes in front where two packages share a
+// resource and an action.
+export const IntelligenceUserListInput = z.strictObject({
+    query: z
+        .string()
+        .trim()
+        .min(2)
+        .max(200)
+        .optional()
+        .describe("Part of a name or an address, at least two characters. Leaving it out with a nodeId lists the first people who can read that node."),
+    nodeId: NodeId.optional().describe("Say for each person whether they can read this node (canRead), for the @ menu and the share dialog."),
+    readersOnly: Flag.optional().describe("With nodeId: only the people who can read the node, the only ones a mention or an assignment may name."),
+    cursor: z
+        .string()
+        .max(1000)
+        .optional()
+        .describe("The nextCursor of the previous page, unchanged. Leaving it out starts at the top."),
+    limit: Limit.optional(),
+});
+export const IntelligenceUser = z.strictObject({
+    userId: z.string(),
+    kind: z.enum(["human", "machine"]),
+    name: z.string(),
+    email: z.string(),
+    image: z.string().nullable(),
+    // A machine's kind, and an Operator's provider ("Validierung · Claude", #403); null for a person.
+    machine: MessageMachine.nullable(),
+    // Only with nodeId.
+    canRead: z.boolean().optional(),
+});
+export const IntelligenceUserList = z.strictObject({
+    items: z.array(IntelligenceUser),
+    nextCursor: z.string().nullable(),
+});