@anchrd/colab-sdk 0.0.0-stage → 0.1.0

package/dist/operators/operators.js

@@ -0,0 +1,398 @@
+import { z } from "zod";
+import { Schedule } from "../dashboards/dashboards.js";
+import { idSchema } from "../ids/ids.js";
+import { Limit } from "../list-input.js";
+import { MachineId } from "../machines/machines.js";
+import { RoleId } from "../roles/roles.js";
+import { OperatorProvider, UserId } from "../users/users.js";
+// The package `operator` (#336, Einstellungen › Operator): the credentials at a provider ("Zugang",
+// `operator_credential_*`) and the Operators themselves (`operator_machine_*`). An Operator is a machine
+// of kind `operator` in `access` (E80, E85); its `machineId` is that user's id, and this package
+// keeps only what a run needs: provider, credential, model, subagents, trigger and limits.
+//
+// ⚠️ A credential's value goes in and never comes out: no answer carries it, and no field of an answer
+// is called `key`, `secret`, `token` or `password` (`/mcp` would strike it, `redactSecrets`). The
+// value's field in the inputs is `value`, the kinds are `subscription` and `apikey`.
+// The catalog (Einstellungen › Operator › Katalog). `models` are the names the provider's CLI takes
+// without a UI: Claude Code's aliases for "the newest of this line", Gemini CLI's aliases `pro`,
+// `flash` and `flash-lite` the same; Codex has no aliases, so its names are the models
+// `codex debug models` of Codex 0.162.1 lists as current (#455). `subagents`: only Claude Code has
+// them (#455); the UI hides the setting for the others. `costs`: only Claude Code reports a dollar
+// amount; Codex and Gemini report tokens, and their runs carry no `costUsd` (Jack, #455), unless
+// they run through the Cloudflare AI Gateway, whose logs carry the amount (#470). `gateway` is in
+// every provider's kinds: one gateway credential serves the Operators of all three (#470). Only Claude
+// keeps the sign-in of a subscription (#459). `beta`: Codex and Gemini carry the mark wherever the UI
+// names them, with the note that Claude is the tried way (#459).
+//
+// `gateway`: the models an Operator on a gateway credential may take, and its default there (#483).
+// ⚠️ The gateway pays only for the models it knows; any other request goes on to the provider without
+// a key and is refused. Nothing is replaced on the way: a model not in this list cannot be chosen
+// with a gateway credential, and with the customer's own key or subscription the full `models` stay.
+// Measured 2026-10-15 with one smallest request per model through a gateway with Unified Billing
+// (paths and header as in developers.cloudflare.com/ai-gateway/usage/providers/{anthropic,openai,
+// google-ai-studio}/; the gateway's docs name no list of models, /features/unified-billing/):
+// - Claude Code 2.1.299: `opus` (`claude-opus-5-5`) and `sonnet` (`claude-sonnet-5-5`) answer 200;
+//   `haiku` (`claude-haiku-5-5`) 401 from Anthropic. `claude-haiku-4-5` answers, but Claude Code then
+//   finds none of its MCP tools (run `…ZX0N8A` of #470), so it is no choice.
+// - Codex: `gpt-6.1-sol` and `gpt-6-luna` 200, `gpt-6-astra` 401 from OpenAI.
+// - Gemini CLI 0.63.0: its aliases are the 3.5 line, 403 from Google; `gemini-2.5-pro`, `-flash`
+//   and `-flash-lite` 200 and ran as Operators (#470), so the gateway offers those by name. Also 200
+//   that day, not offered without a run: `gemini-3.8-flash`, `gemini-3.1-flash-lite`,
+//   `gemini-3.1-pro-preview`.
+// Add a model here once the gateway pays for it, after one smallest request and one run.
+export const operatorProviders = [
+    {
+        provider: "claude",
+        name: "Claude",
+        vendor: "Anthropic",
+        selectable: true,
+        kinds: ["subscription", "apikey", "gateway"],
+        beta: false,
+        models: ["opus", "sonnet", "haiku"],
+        defaultModel: "sonnet",
+        gateway: { models: ["opus", "sonnet"], defaultModel: "sonnet" },
+        subagents: true,
+        costs: true,
+    },
+    {
+        provider: "codex",
+        name: "Codex",
+        vendor: "OpenAI",
+        selectable: true,
+        // No ChatGPT sign-in (#459): chatgpt.com refuses every request that carries `CF-Worker`,
+        // which Cloudflare sets on each request of a Worker; GPT runs with an API key or the gateway.
+        kinds: ["apikey", "gateway"],
+        beta: true,
+        models: ["gpt-6-astra", "gpt-6.1-sol", "gpt-6-luna"],
+        defaultModel: "gpt-6.1-sol",
+        gateway: { models: ["gpt-6.1-sol", "gpt-6-luna"], defaultModel: "gpt-6.1-sol" },
+        subagents: false,
+        costs: false,
+    },
+    {
+        provider: "gemini",
+        name: "Gemini",
+        vendor: "Google",
+        selectable: true,
+        // No Google sign-in (#459): Code Assist then asks for a Google Cloud project of the account,
+        // and for free accounts the Gemini CLI gave way to Antigravity (#507, from #502).
+        kinds: ["apikey", "gateway"],
+        beta: true,
+        models: ["pro", "flash", "flash-lite"],
+        defaultModel: "flash",
+        gateway: {
+            models: ["gemini-2.5-pro", "gemini-2.5-flash", "gemini-2.5-flash-lite"],
+            defaultModel: "gemini-2.5-flash",
+        },
+        subagents: false,
+        costs: false,
+    },
+];
+// The models an Operator of this provider may take with a credential of this kind, and the default
+// among them (#483): the gateway's own list, else the provider's.
+export function modelsOf(entry, kind) {
+    return kind === "gateway" ? entry.gateway : entry;
+}
+// `subscription`: the sign-in of a subscription, the token of `claude setup-token`; none for Codex
+// and Gemini since #459, a stored one reads as invalid. `apikey`: an API key (Claude Console,
+// OpenAI, Gemini API). The same words for every provider, so the Claude credentials stored before #455 keep their kind. Always the
+// customer's own (Spike #335, E86). `gateway`: a token of the customer's Cloudflare AI Gateway with
+// its account and gateway (#470); the runs of Claude, Codex and Gemini go through it, paid by the
+// credits of the Cloudflare account (Unified Billing) or the keys stored in the gateway (BYOK). One
+// such credential belongs to no provider and serves the Operators of all three.
+export const CredentialKind = z.enum(["subscription", "apikey", "gateway"]);
+// `valid` until the provider refuses it; `invalid` pauses every Operator that uses it (E81) until it
+// is replaced.
+export const CredentialState = z.enum(["valid", "invalid"]);
+// Every provider's models in one list; which belong to which provider says the catalog, and the
+// package refuses a model of another provider.
+export const OperatorModel = z.enum([
+    "opus",
+    "sonnet",
+    "haiku",
+    "gpt-6-astra",
+    "gpt-6.1-sol",
+    "gpt-6-luna",
+    "pro",
+    "flash",
+    "flash-lite",
+    "gemini-2.5-pro",
+    "gemini-2.5-flash",
+    "gemini-2.5-flash-lite",
+]);
+export const CredentialId = idSchema("credential");
+const CredentialName = z.string().trim().min(1).max(64);
+// The value as pasted. Its shape per provider and kind is checked by the package, whose message never
+// quotes it. A sign-in file of Codex is a few kilobytes (#455).
+const CredentialValue = z.string().trim().min(16).max(20_000);
+// Where a gateway credential's token goes (#470): the Cloudflare account and the gateway in it, as
+// the dashboard names them. Not secret, but checked strictly: both become parts of a URL.
+export const GatewayTarget = z.strictObject({
+    accountId: z
+        .string()
+        .trim()
+        .regex(/^[0-9a-f]{32}$/i, "A Cloudflare account id is 32 hexadecimal characters."),
+    gatewayId: z
+        .string()
+        .trim()
+        .regex(/^[A-Za-z0-9_-]{1,64}$/, "A gateway id holds letters, digits, - and _ only."),
+});
+export const CredentialListInput = z.strictObject({
+    cursor: CredentialId.optional(),
+    limit: Limit.optional(),
+});
+export const CredentialGetInput = z.strictObject({ credentialId: CredentialId });
+// A gateway credential names no provider and takes `gateway` beside its token in `value` (#470);
+// every other kind names its provider and takes no `gateway`.
+export const CredentialCreateInput = z
+    .strictObject({
+    provider: OperatorProvider.optional(),
+    kind: CredentialKind,
+    name: CredentialName,
+    value: CredentialValue,
+    gateway: GatewayTarget.optional(),
+})
+    .refine((input) => input.kind === "gateway"
+    ? input.provider === undefined && input.gateway !== undefined
+    : input.provider !== undefined && input.gateway === undefined, {
+    message: "A gateway credential takes gateway and no provider; every other kind takes provider and no gateway.",
+});
+// "Token ersetzen": a new value, a new name, or both. A new value is tested at once. A gateway
+// credential takes a new value only together with its `gateway` (#470).
+export const CredentialUpdateInput = z
+    .strictObject({
+    credentialId: CredentialId,
+    name: CredentialName.optional(),
+    value: CredentialValue.optional(),
+    gateway: GatewayTarget.optional(),
+})
+    .refine((input) => input.name !== undefined || input.value !== undefined, {
+    message: "Name a field to change: name or value.",
+})
+    .refine((input) => input.gateway === undefined || input.value !== undefined, {
+    message: "A new gateway goes together with a new value.",
+});
+export const CredentialTestInput = z.strictObject({ credentialId: CredentialId });
+// "Trennen": the value is deleted at once and without archive. Refused while an Operator uses it.
+export const CredentialRevokeInput = z.strictObject({ credentialId: CredentialId });
+export const Credential = z.strictObject({
+    credentialId: CredentialId,
+    // Null for a gateway credential, which serves the Operators of every provider (#470).
+    provider: OperatorProvider.nullable(),
+    kind: CredentialKind,
+    name: z.string(),
+    state: CredentialState,
+    // The last test, whatever its result; null before the first.
+    checkedAt: z.iso.datetime().nullable(),
+    // When the value was set; never the value.
+    setAt: z.iso.datetime(),
+    // The Operators that use it, archived ones left out: "Genutzt von n Operatoren", and while it is
+    // invalid, the ones that pause because of it.
+    machineIds: z.array(MachineId),
+    createdAt: z.iso.datetime(),
+    createdBy: UserId.nullable(),
+    updatedAt: z.iso.datetime(),
+});
+export const CredentialList = z.strictObject({
+    items: z.array(Credential),
+    nextCursor: CredentialId.nullable(),
+});
+// The smallest call at the provider with the stored value. An error names the outcome, never a value.
+export const CredentialTestResult = z.discriminatedUnion("ok", [
+    z.strictObject({ ok: z.literal(true) }),
+    z.strictObject({ ok: z.literal(false), error: z.string() }),
+]);
+export const CredentialTested = z.strictObject({
+    credential: Credential,
+    test: CredentialTestResult,
+});
+// Subagents (#335): allowed or not, and at most `max` at the same time. Claude Code knows no limit
+// per run, only at the same time (Jack's decision at #336).
+export const Subagents = z.strictObject({
+    allowed: z.boolean(),
+    max: z.int().min(1).max(10),
+});
+// When an Operator wakes (Springt an): once something changed, after `quietMinutes` without a further
+// change; or at fixed times, with the schedule of processes and dashboards.
+export const Trigger = z.discriminatedUnion("on", [
+    z.strictObject({ on: z.literal("change"), quietMinutes: z.int().min(0).max(1440) }),
+    z.strictObject({ on: z.literal("schedule"), schedule: Schedule }),
+]);
+// The limits of E81: the longest run in minutes and the most runs a day.
+export const OperatorLimits = z.strictObject({
+    maxRunMinutes: z.int().min(1).max(240),
+    maxRunsPerDay: z.int().min(1).max(1000),
+});
+export const operatorDefaults = {
+    model: "sonnet",
+    subagents: { allowed: false, max: 3 },
+    trigger: { on: "change", quietMinutes: 5 },
+    limits: { maxRunMinutes: 30, maxRunsPerDay: 50 },
+};
+// `no_role`: it has no role and starts no run (E84). `paused`: see `pausedReason`. `ready`: it may run.
+// "läuft" is `running` beside the state (#337).
+export const OperatorState = z.enum(["no_role", "ready", "paused"]);
+// `manual` by hand, `limit` the daily limit, `failures` three failed runs in a row (#337 sets those
+// two), `credential` its credential is invalid or gone.
+export const PauseReason = z.enum(["manual", "limit", "failures", "credential"]);
+export const MachineListInput = z.strictObject({
+    cursor: MachineId.optional(),
+    limit: Limit.optional(),
+});
+export const MachineGetInput = z.strictObject({ machineId: MachineId });
+// The name and roles go to the machine in `access`; without `roleIds` it has none (E84).
+export const OperatorMachineCreateInput = z.strictObject({
+    name: z.string().trim().min(1).max(64),
+    roleIds: z.array(RoleId).max(50).optional(),
+    provider: OperatorProvider,
+    credentialId: CredentialId,
+    model: OperatorModel.optional(),
+    subagents: Subagents.optional(),
+    trigger: Trigger.optional(),
+    limits: OperatorLimits.partial().optional(),
+});
+// Every field optional; `responsibleId` hands the machine to another person in `access` (E76).
+export const OperatorMachineUpdateInput = z
+    .strictObject({
+    machineId: MachineId,
+    credentialId: CredentialId.optional(),
+    model: OperatorModel.optional(),
+    subagents: Subagents.optional(),
+    trigger: Trigger.optional(),
+    limits: OperatorLimits.partial().optional(),
+    responsibleId: UserId.optional(),
+})
+    .refine((input) => Object.keys(input).some((field) => field !== "machineId"), {
+    message: "Name a field to change.",
+});
+// Pause and resume by hand. Resuming lifts a pause for the daily limit or failures too.
+export const MachineDisableInput = z.strictObject({ machineId: MachineId });
+export const MachineEnableInput = z.strictObject({ machineId: MachineId });
+// Deleting an Operator archives its machine in `access`; nothing is deleted.
+export const OperatorMachineArchiveInput = z.strictObject({ machineId: MachineId });
+export const Operator = z.strictObject({
+    machineId: MachineId,
+    // The machine's name in `access`, read now.
+    name: z.string(),
+    provider: OperatorProvider,
+    credentialId: CredentialId.nullable(),
+    model: OperatorModel,
+    subagents: Subagents,
+    trigger: Trigger,
+    limits: OperatorLimits,
+    state: OperatorState,
+    pausedReason: PauseReason.nullable(),
+    pausedAt: z.iso.datetime().nullable(),
+    // "läuft" (#337): the run in progress, beside the state, so a paused Operator can still finish
+    // the run it started; null while none runs.
+    running: z.strictObject({ runId: idSchema("run"), startedAt: z.iso.datetime() }).nullable(),
+    archivedAt: z.iso.datetime().nullable(),
+    createdAt: z.iso.datetime(),
+    createdBy: UserId.nullable(),
+    updatedAt: z.iso.datetime(),
+});
+export const OperatorList = z.strictObject({
+    items: z.array(Operator),
+    nextCursor: MachineId.nullable(),
+});
+// ---------------------------------------------------------------------------------------------
+// The runs of an Operator (#337, Einstellungen › Operator › Protokoll und Nutzung, E75, E81, E82).
+// A run's id is `run_…` like a run of `intelligence`: both are the resource `run`, in two databases.
+export const OperatorRunId = idSchema("run").describe("The Operator run's id, `run_…`, as operator_run_list returned it.");
+// `running` until the runner reports; then `completed` or `failed` with its reason (E82).
+export const OperatorRunStatus = z.enum(["running", "completed", "failed"]);
+// Why a run failed (E82): the container did not start (`container`), the provider refused or was
+// overloaded (`provider`), the longest run was reached (`timeout`), Claude Code crashed or ended with
+// an error (`crash`), it ended without its closing message (`noresult`), the package itself broke
+// (`error`), or the provider refused the credential (`credential`: it is marked invalid and its
+// Operators pause; no failure in a row is counted and no run follows).
+export const OperatorRunReason = z.enum([
+    "container",
+    "provider",
+    "timeout",
+    "crash",
+    "noresult",
+    "error",
+    "credential",
+]);
+// What woke it: a change after the quiet minutes, a fixed time, or the retry after a failure.
+export const OperatorRunTrigger = z.enum(["change", "schedule", "retry"]);
+export const OperatorRunTokens = z.strictObject({
+    input: z.int().min(0),
+    output: z.int().min(0),
+    cacheRead: z.int().min(0),
+    cacheWrite: z.int().min(0),
+});
+// The processes and connectors a run touched, as the runner names them (#338).
+export const OperatorRunTouched = z.strictObject({
+    processes: z.array(z.string().max(200)).max(200),
+    connectors: z.array(z.string().max(200)).max(200),
+});
+// Who ran, named by the backend (#448): the machine's name in `access`, archived ones included, and
+// when the Operator was deleted (archived), so a run of a deleted Operator still says whose it was.
+const RunMachine = {
+    machineId: MachineId,
+    machineName: z.string(),
+    machineArchivedAt: z.iso.datetime().nullable(),
+};
+export const OperatorRun = z.strictObject({
+    runId: OperatorRunId,
+    ...RunMachine,
+    trigger: OperatorRunTrigger,
+    status: OperatorRunStatus,
+    reason: OperatorRunReason.nullable(),
+    // What the runner said about a failure, never a credential's value.
+    detail: z.string().nullable(),
+    // The summary the Operator wrote at the end itself.
+    summary: z.string().nullable(),
+    touched: OperatorRunTouched,
+    // The credential's kind decides how the cost reads: `apikey` is cost, `subscription` the API
+    // equivalent (E81).
+    credentialKind: CredentialKind.nullable(),
+    // Claude's own amount; Codex and Gemini report tokens and no amount, so their runs carry null
+    // (#455). Through the Cloudflare AI Gateway the amount of its logs, for every provider (#470).
+    costUsd: z.number().nullable(),
+    tokens: OperatorRunTokens.nullable(),
+    startedAt: z.iso.datetime(),
+    endedAt: z.iso.datetime().nullable(),
+    durationMs: z.int().nullable(),
+});
+const RunMoment = z.iso.datetime({ offset: true });
+export const OperatorRunListInput = z.strictObject({
+    machineId: MachineId.optional().describe("Only this Operator's runs, `user_…`. An Operator without admin rights reads its own runs only, whatever it names here."),
+    provider: OperatorProvider.optional().describe("Only the runs of this provider's Operators: claude, codex or gemini."),
+    status: OperatorRunStatus.optional().describe("Only runs in this status."),
+    from: RunMoment.optional().describe("Runs started at or after this moment, ISO."),
+    to: RunMoment.optional().describe("Runs started before this moment, ISO."),
+    search: z
+        .string()
+        .trim()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe("Words in a run's summary or failure, case-insensitive."),
+    cursor: OperatorRunId.optional().describe("The nextCursor of the previous page, for the runs after it; newest first."),
+    limit: Limit.optional().describe("Runs per page, 1 to 100. Leaving it out gives 50."),
+});
+export const OperatorRunGetInput = z.strictObject({ runId: OperatorRunId });
+const UsageSums = {
+    runs: z.int(),
+    costUsd: z.number(),
+    tokens: OperatorRunTokens,
+};
+// The use over every run the filter takes, not only the page (Nutzung): in total, per Operator, per
+// day (UTC), per credential kind, so cost and API equivalent stand apart, and per provider, so the
+// tokens of Codex and Gemini, which report no amount, stand apart from Claude's (#455). `costUsd`
+// sums the runs that carry an amount: Claude's, and every run through the AI Gateway (#470).
+export const OperatorRunUsage = z.strictObject({
+    ...UsageSums,
+    byMachine: z.array(z.strictObject({ ...RunMachine, ...UsageSums })),
+    byDay: z.array(z.strictObject({ day: z.iso.date(), ...UsageSums })),
+    byKind: z.array(z.strictObject({ kind: CredentialKind, ...UsageSums })),
+    byProvider: z.array(z.strictObject({ provider: OperatorProvider, ...UsageSums })),
+});
+export const OperatorRunList = z.strictObject({
+    items: z.array(OperatorRun),
+    nextCursor: OperatorRunId.nullable(),
+    usage: OperatorRunUsage,
+});

package/dist/pages/pages.d.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+export declare const PageId: z.ZodString;
+export type PageId = z.infer<typeof PageId>;
+export declare const PageHead: z.ZodObject<{
+    title: z.ZodString;
+    group: z.ZodString;
+    parent: z.ZodNullable<z.ZodString>;
+    order: z.ZodNumber;
+    summary: z.ZodString;
+}, z.core.$strict>;
+export type PageHead = z.infer<typeof PageHead>;
+export declare const PageListInput: z.ZodObject<{
+    locale: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        de: "de";
+    }>>;
+    query: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strict>;
+export type PageListInput = z.infer<typeof PageListInput>;
+export declare const PageGetInput: z.ZodObject<{
+    pageId: z.ZodString;
+    locale: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        de: "de";
+    }>>;
+}, z.core.$strict>;
+export type PageGetInput = z.infer<typeof PageGetInput>;
+export declare const PageSummary: z.ZodObject<{
+    title: z.ZodString;
+    group: z.ZodString;
+    parent: z.ZodNullable<z.ZodString>;
+    order: z.ZodNumber;
+    summary: z.ZodString;
+    pageId: z.ZodString;
+    locale: z.ZodEnum<{
+        en: "en";
+        de: "de";
+    }>;
+    match: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type PageSummary = z.infer<typeof PageSummary>;
+export declare const PageList: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        group: z.ZodString;
+        parent: z.ZodNullable<z.ZodString>;
+        order: z.ZodNumber;
+        summary: z.ZodString;
+        pageId: z.ZodString;
+        locale: z.ZodEnum<{
+            en: "en";
+            de: "de";
+        }>;
+        match: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type PageList = z.infer<typeof PageList>;
+export declare const PageHeading: z.ZodObject<{
+    depth: z.ZodNumber;
+    text: z.ZodString;
+    slug: z.ZodString;
+}, z.core.$strict>;
+export type PageHeading = z.infer<typeof PageHeading>;
+export declare const PageDetail: z.ZodObject<{
+    title: z.ZodString;
+    group: z.ZodString;
+    parent: z.ZodNullable<z.ZodString>;
+    order: z.ZodNumber;
+    summary: z.ZodString;
+    pageId: z.ZodString;
+    locale: z.ZodEnum<{
+        en: "en";
+        de: "de";
+    }>;
+    markdown: z.ZodString;
+    headings: z.ZodArray<z.ZodObject<{
+        depth: z.ZodNumber;
+        text: z.ZodString;
+        slug: z.ZodString;
+    }, z.core.$strict>>;
+    breadcrumbs: z.ZodArray<z.ZodObject<{
+        pageId: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PageDetail = z.infer<typeof PageDetail>;

package/dist/pages/pages.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+import { Limit } from "../list-input.js";
+import { Locale } from "../profile/profile.js";
+// The pages of the documentation (Seiten › Documentation, E23, #51): Markdown files per language in
+// the package `documentation`, read by the docs overlay and by the AI through the
+// `documentation_page_*` tools.
+// ⚠️ Not a prefixed ULID like every other id: a page is a file in the package, and its id is the
+// file's name (`connect-ai`), stable across languages and releases (#51).
+export const PageId = z
+    .string()
+    .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "A page id is the file name in kebab-case, such as connect-ai");
+// The YAML head every page file starts with. Strict: a key nobody reads is a typo.
+export const PageHead = z.strictObject({
+    title: z.string().trim().min(1),
+    // The heading in the overlay's side bar, in the page's language ("Getting started", "Einstieg").
+    group: z.string().trim().min(1),
+    // The page this one sits under, or null at the top of its group.
+    parent: PageId.nullable(),
+    // The position among the pages with the same parent.
+    order: z.number().int().min(0),
+    // The grey lead under the title.
+    summary: z.string().trim().min(1),
+});
+export const PageListInput = z.strictObject({
+    // Without it, the caller's own language.
+    locale: Locale.optional(),
+    // Searches title, summary and text, ignoring case.
+    query: z.string().trim().min(1).max(200).optional(),
+    cursor: PageId.optional(),
+    limit: Limit.optional(),
+});
+export const PageGetInput = z.strictObject({
+    pageId: PageId,
+    locale: Locale.optional(),
+});
+// One page in the list. `locale` is the language delivered: English stands in for a missing
+// translation (E22).
+export const PageSummary = PageHead.extend({
+    pageId: PageId,
+    locale: Locale,
+    // Only with `query`: the passage that matched.
+    match: z.string().optional(),
+});
+export const PageList = z.strictObject({
+    items: z.array(PageSummary),
+    nextCursor: PageId.nullable(),
+});
+export const PageHeading = z.strictObject({
+    depth: z.number().int().min(2).max(6),
+    text: z.string(),
+    // GitHub's anchor for the heading, for "Auf dieser Seite".
+    slug: z.string(),
+});
+export const PageDetail = PageHead.extend({
+    pageId: PageId,
+    locale: Locale,
+    // The page without its YAML head.
+    markdown: z.string(),
+    headings: z.array(PageHeading),
+    // From the top of the tree down to this page itself; the group comes first in the UI, from `group`.
+    breadcrumbs: z.array(z.strictObject({ pageId: PageId, title: z.string() })),
+});

package/dist/primitives/primitives.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+export declare const IdempotencyKey: z.ZodString;
+export type IdempotencyKey = z.infer<typeof IdempotencyKey>;
+export declare const Rev: z.ZodNumber;
+export type Rev = z.infer<typeof Rev>;

package/dist/primitives/primitives.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+// Primitives every writer of every package takes the same way, each described ONCE (trap C006): a
+// word used everywhere gets one schema with one sentence, so HTTP, MCP and the types say the same.
+// Taken from anchrd/intel `src/contract/contract.ts` (f4eccd16). The description says what the caller
+// has to DO, because that is the part a model gets wrong: it invents a fresh key on the retry and
+// creates the thing twice.
+export const IdempotencyKey = z
+    .string()
+    .min(8)
+    .max(200)
+    .describe("A caller-chosen key that makes this call safe to retry: repeating the same key returns the first result instead of doing the work twice. Reuse the SAME key when retrying one attempt, and a new one for a genuinely new call.");
+// The revision a save is based on (E70): every save counts it up by one, and a save that names
+// another than the stored one is `conflict` and writes nothing. Not the version number of a
+// document and not `updatedAt`: a move or a grant touches the row too (trap P117).
+export const Rev = z
+    .number()
+    .int()
+    .min(1)
+    .describe("The revision of the node this change is based on, as the last read returned it. If someone saved in between, the call answers conflict and changes nothing: read the node again and decide.");

package/dist/profile/profile.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+export declare const locales: readonly ["en", "de"];
+export declare const Locale: z.ZodEnum<{
+    en: "en";
+    de: "de";
+}>;
+export type Locale = z.infer<typeof Locale>;
+export declare const themes: readonly ["light", "dark", "system"];
+export declare const Theme: z.ZodEnum<{
+    light: "light";
+    dark: "dark";
+    system: "system";
+}>;
+export type Theme = z.infer<typeof Theme>;
+export declare const TimeZone: z.ZodString;
+export type TimeZone = z.infer<typeof TimeZone>;
+export declare const Name: z.ZodString;
+export declare const ProfileUpdateInput: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        de: "de";
+    }>>;
+    timezone: z.ZodOptional<z.ZodString>;
+    theme: z.ZodOptional<z.ZodEnum<{
+        light: "light";
+        dark: "dark";
+        system: "system";
+    }>>;
+}, z.core.$strict>;
+export type ProfileUpdateInput = z.infer<typeof ProfileUpdateInput>;
+export declare const profileImageTypes: readonly ["image/png", "image/jpeg", "image/webp"];
+export declare const profileImageMaxBytes = 5000000;
+export declare const ProfileImageResponse: z.ZodObject<{
+    image: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type ProfileImageResponse = z.infer<typeof ProfileImageResponse>;

package/dist/profile/profile.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+// The own profile (Einstellungen › Profil, Darstellung): what a person writes about themselves
+// through `/auth/update-user` and `/auth/profile-image`. The email is not here: it comes from the
+// sign-in and is read only.
+// The languages Colab speaks (E22). English is the default.
+export const locales = ["en", "de"];
+export const Locale = z.enum(locales);
+// Einstellungen › Darstellung.
+export const themes = ["light", "dark", "system"];
+export const Theme = z.enum(themes);
+// An IANA zone `Intl` knows, such as `Europe/Berlin`. A zone it does not know would make every date
+// in a mail or the UI throw, so it is refused at the door instead.
+export const TimeZone = z
+    .string()
+    .min(1)
+    .max(64)
+    .refine((zone) => {
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: zone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}, "Unknown time zone");
+export const Name = z.string().trim().min(1).max(200);
+// The body of `POST /auth/update-user`. Strict: `email` and `image` are refused there, the email
+// because it identifies the account, the picture because it only comes through its own door.
+export const ProfileUpdateInput = z.strictObject({
+    name: Name.optional(),
+    locale: Locale.optional(),
+    timezone: TimeZone.optional(),
+    theme: Theme.optional(),
+});
+// The picture's upload door takes the file itself as body, never base64 in JSON. The allowlist is
+// not a filter of the dangerous types: `image/svg+xml` can carry script and stays off it.
+// Taken from anchrd/gate `packages/sdk/src/contract/contract.ts` (9d8ece3).
+export const profileImageTypes = ["image/png", "image/jpeg", "image/webp"];
+// A portrait drawn at 40 pixels needs a thousandth of this; the limit catches the untouched photo
+// straight from the phone. One figure for the UI before the upload and for the door that refuses.
+export const profileImageMaxBytes = 5_000_000;
+// The answer of upload and removal: the address the profile carries in `image`, or `null`.
+export const ProfileImageResponse = z.strictObject({ image: z.string().nullable() });