@anchrd/colab-sdk 0.0.0-stage → 0.1.0

package/dist/sso/sso.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { UserId } from "../users/users.js";
+// Sign-in through Google and Microsoft, set up under Einstellungen › SSO (#358, E90): one row per
+// provider, set up or not. The id is the provider's word from the code (`google`), not a ULID, like a
+// connector's id: there are exactly these two, and the sign-in page and Better Auth name them so.
+//
+// ⚠️ The client secret goes in and never comes out: no answer carries it, and no field of an answer
+// is called `secret` (`/mcp` would strike it, `redactSecrets`). The input field is `clientSecret`.
+export const ssoIds = ["google", "microsoft"];
+export const SsoId = z.enum(ssoIds);
+// Where the sign-in page gets a provider from right now: `settings` (set up here, in the database of
+// `access`), `environment` (the installation's variables; locally `.dev.vars`), or null: not offered.
+export const SsoSource = z.enum(["settings", "environment"]);
+export const SsoListInput = z.strictObject({});
+// "Einrichten": both values every time. A new client id with the old secret would not sign anybody
+// in, so the pair is replaced together.
+export const SsoUpdateInput = z.strictObject({
+    ssoId: SsoId.describe("The provider: google or microsoft."),
+    clientId: z
+        .string()
+        .trim()
+        .min(1)
+        .max(512)
+        .describe("The client id of the app registered at the provider."),
+    clientSecret: z
+        .string()
+        .trim()
+        .min(1)
+        .max(1024)
+        .describe("The client secret of that app. Stored sealed; no answer ever shows it again."),
+});
+// "Entfernen": the provider's settings are deleted at once and without archive. A provider the
+// installation's variables name stays offered from there.
+export const SsoRemoveInput = z.strictObject({
+    ssoId: SsoId.describe("The provider: google or microsoft."),
+});
+export const Sso = z.strictObject({
+    ssoId: SsoId,
+    // Set up here: the client id, when and by whom. Null while it is not set up here.
+    clientId: z.string().nullable(),
+    setAt: z.iso.datetime().nullable(),
+    setBy: UserId.nullable(),
+    source: SsoSource.nullable(),
+    // The address to enter at the provider as the redirect URI ("Weiterleitungs-Adresse").
+    redirectUrl: z.url(),
+});
+export const SsoList = z.strictObject({
+    items: z.array(Sso),
+    // Two rows at most: never a further page.
+    nextCursor: z.null(),
+});
+// `GET /auth/providers`, public: which buttons the sign-in page shows, in their order. Nothing else
+// of a provider travels here.
+export const SignInProviders = z.strictObject({ providers: z.array(SsoId) });

package/dist/tables/tables.d.ts

@@ -0,0 +1,133 @@
+import { z } from "zod";
+export declare const TableId: z.ZodTemplateLiteral<`node_${string}`>;
+export type TableId = z.infer<typeof TableId>;
+export declare const tableColumnTypes: readonly ["text", "number", "date", "email", "chip"];
+export declare const TableColumnType: z.ZodEnum<{
+    number: "number";
+    date: "date";
+    email: "email";
+    text: "text";
+    chip: "chip";
+}>;
+export type TableColumnType = z.infer<typeof TableColumnType>;
+export declare const TableColumn: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        number: "number";
+        date: "date";
+        email: "email";
+        text: "text";
+        chip: "chip";
+    }>;
+}, z.core.$strict>;
+export type TableColumn = z.infer<typeof TableColumn>;
+export declare const TableColumnChange: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        number: "number";
+        date: "date";
+        email: "email";
+        text: "text";
+        chip: "chip";
+    }>;
+    from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export type TableColumnChange = z.infer<typeof TableColumnChange>;
+export declare const TableCreateInput: z.ZodObject<{
+    parentId: z.ZodNullable<z.ZodTemplateLiteral<`node_${string}`>>;
+    name: z.ZodString;
+    columns: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            number: "number";
+            date: "date";
+            email: "email";
+            text: "text";
+            chip: "chip";
+        }>;
+    }, z.core.$strict>>;
+    rows: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+    csv: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodString;
+}, z.core.$strict>;
+export type TableCreateInput = z.infer<typeof TableCreateInput>;
+export declare const tableFormats: readonly ["rows", "csv"];
+export declare const TableGetInput: z.ZodObject<{
+    tableId: z.ZodTemplateLiteral<`node_${string}`>;
+    format: z.ZodOptional<z.ZodEnum<{
+        rows: "rows";
+        csv: "csv";
+    }>>;
+}, z.core.$strict>;
+export type TableGetInput = z.infer<typeof TableGetInput>;
+export declare const TableUpdateInput: z.ZodObject<{
+    tableId: z.ZodTemplateLiteral<`node_${string}`>;
+    rev: z.ZodOptional<z.ZodNumber>;
+    editSession: z.ZodOptional<z.ZodString>;
+    columns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            number: "number";
+            date: "date";
+            email: "email";
+            text: "text";
+            chip: "chip";
+        }>;
+        from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>>>;
+    csv: z.ZodOptional<z.ZodString>;
+    append: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+    replace: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        position: z.ZodNumber;
+        cells: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+    remove: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strict>;
+export type TableUpdateInput = z.infer<typeof TableUpdateInput>;
+export declare const TableDetail: z.ZodObject<{
+    secret: z.ZodOptional<z.ZodLiteral<true>>;
+    locked: z.ZodOptional<z.ZodBoolean>;
+    tableId: z.ZodTemplateLiteral<`node_${string}`>;
+    name: z.ZodString;
+    columns: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            number: "number";
+            date: "date";
+            email: "email";
+            text: "text";
+            chip: "chip";
+        }>;
+    }, z.core.$strict>>;
+    rows: z.ZodOptional<z.ZodArray<z.ZodArray<z.ZodString>>>;
+    csv: z.ZodOptional<z.ZodString>;
+    version: z.ZodNumber;
+    rev: z.ZodNumber;
+    rights: z.ZodObject<{
+        write: z.ZodBoolean;
+    }, z.core.$strict>;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type TableDetail = z.infer<typeof TableDetail>;
+export declare const TableSaved: z.ZodObject<{
+    tableId: z.ZodTemplateLiteral<`node_${string}`>;
+    name: z.ZodString;
+    columns: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            number: "number";
+            date: "date";
+            email: "email";
+            text: "text";
+            chip: "chip";
+        }>;
+    }, z.core.$strict>>;
+    rowCount: z.ZodNumber;
+    version: z.ZodNumber;
+    rev: z.ZodNumber;
+    removedColumns: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        rows: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type TableSaved = z.infer<typeof TableSaved>;

package/dist/tables/tables.js

@@ -0,0 +1,131 @@
+import { z } from "zod";
+import { NodeId, SecretFields } from "../nodes/nodes.js";
+import { IdempotencyKey, Rev } from "../primitives/primitives.js";
+// Tables (#40, Nodes › Tabelle, E39, E59, E70): the inputs of `intelligence_table_create`, `_get`
+// and `_update`, and their answers. A table is CSV, stored and exported as it is, whose first line is
+// the header; beside it every version keeps the columns with their types. A row has no id: it is
+// addressed by its position, counted from 1 at the first data row, against the state `rev` names.
+// Appending, replacing and removing rows are fields of `_update`, not a resource of their own.
+export const TableId = NodeId.describe("The table's id, a `node_…` of kind table.");
+// The five types of a column (E39). The type only decides how a cell is shown; a cell is never
+// checked against it.
+export const tableColumnTypes = ["text", "number", "date", "email", "chip"];
+export const TableColumnType = z
+    .enum(tableColumnTypes)
+    .describe("How the column's cells are shown: text; number (right-aligned); date (short); email (a link); chip (pills, several per cell separated by commas). The type is only how a cell looks: a cell is always text and is not checked against it.");
+const ColumnName = z
+    .string()
+    .max(200)
+    .describe("The column's name, the cell of the header line. Not empty, and no two columns of a table share one (letter case ignored).");
+export const TableColumn = z.strictObject({ name: ColumnName, type: TableColumnType });
+// A column of a new column list (`_update` with `columns`): which cells fill it is the only thing a
+// name cannot say when columns are renamed.
+export const TableColumnChange = TableColumn.extend({
+    from: z
+        .string()
+        .max(200)
+        .nullable()
+        .optional()
+        .describe("The current column whose cells fill this one, by its current name: how a column is renamed. Null makes it a new empty column. Left out, a current column of the same name fills it, else it starts empty."),
+});
+const Columns = z.array(TableColumn).min(1).max(64);
+const Cells = z
+    .array(z.string())
+    .describe("One row: its cells as text, as many as the table has columns, in the order of the columns. A chip cell holds several values separated by commas.");
+const Rows = z.array(Cells).max(10_000);
+const Csv = z
+    .string()
+    .describe("The whole table as CSV: the header line with the column names first, then one line per row, as intelligence_table_get with format csv answers it. At most 1 MB in UTF-8.");
+// Counted from 1 at the first data row; the header line is no row.
+const Position = z
+    .number()
+    .int()
+    .min(1)
+    .describe("A row's position, 1 for the first data row (the header line is not counted), as it stands in the state of the rev you send.");
+const EditSession = z
+    .string()
+    .min(1)
+    .max(100)
+    .optional()
+    .describe("The editing session the table view keeps while a person stays on the table: saves of one session go into one version. Leaving it out makes every save a version of its own, which is right for an AI.");
+export const TableCreateInput = z.strictObject({
+    // ⚠️ Required and nullable (trap C015): null is the top level of Shared.
+    parentId: NodeId.nullable().describe("The folder to create the table in, one you can write to; null creates it on the top level of Shared, visible to you until you share it."),
+    name: z.string().max(200).describe("The table's name as people read it."),
+    columns: Columns.describe("The columns in their order, at least one, each with its name and type. They are the table's header."),
+    rows: Rows.optional().describe("The first rows, each a list of cells in the order of the columns. Send rows or csv, not both; leaving both out creates an empty table."),
+    csv: Csv.optional().describe("The first content as CSV whose header line holds exactly the names of columns, in their order. Send rows or csv, not both."),
+    idempotencyKey: IdempotencyKey,
+});
+export const tableFormats = ["rows", "csv"];
+export const TableGetInput = z.strictObject({
+    tableId: TableId,
+    format: z
+        .enum(tableFormats)
+        .optional()
+        .describe("rows (the default) answers the rows as lists of cells; csv answers the whole table as CSV text instead, the header line first."),
+});
+export const TableUpdateInput = z.strictObject({
+    tableId: TableId,
+    rev: Rev.optional().describe("The revision of the table this change is based on, as the last read returned it; the positions of replace and remove are counted in that state. Required for every change except appending rows alone, which collides with nothing. If someone saved in between, the call answers conflict and changes nothing: read the table again and decide."),
+    editSession: EditSession,
+    columns: z
+        .array(TableColumnChange)
+        .min(1)
+        .max(64)
+        .optional()
+        .describe("The whole new column list in its new order: names, types, new columns and, by leaving them out, removed ones. A removed column's cells stay only in the table's history; the answer names the rows that had content in it. With csv, it is the header the csv must match instead."),
+    csv: Csv.optional().describe("Replace the whole table: CSV whose header line holds exactly the column names, the current ones or those sent in columns alongside."),
+    append: Rows.min(1)
+        .optional()
+        .describe("Rows to add at the end, each a list of cells in the order of the columns. Appending alone needs no rev and no reading of the table first."),
+    replace: z
+        .array(z.strictObject({
+        position: Position,
+        cells: Cells.describe("The complete new row: its cells as text, as many as the table has columns."),
+    }))
+        .min(1)
+        .max(10_000)
+        .optional()
+        .describe("Rows to overwrite whole, each by its position in the state of the rev you send. Applied first, then remove, then append."),
+    remove: z
+        .array(Position)
+        .min(1)
+        .max(10_000)
+        .optional()
+        .describe("Positions of the rows to remove, each counted in the state of the rev you send, so they do not shift while the call runs. Applied after replace and before append."),
+});
+export const TableDetail = z.strictObject({
+    tableId: TableId,
+    name: z.string(),
+    columns: z.array(TableColumn),
+    // The data rows, the first is position 1; absent when `format` is csv.
+    rows: z.array(z.array(z.string())).optional(),
+    // The whole table as CSV, header first; only when `format` is csv.
+    csv: z.string().optional(),
+    // The current version's number, as people read it ("Version 6").
+    version: z.number().int(),
+    // The state the next save sends (E70).
+    rev: z.number().int(),
+    rights: z.strictObject({ write: z.boolean() }),
+    updatedAt: z.iso.datetime(),
+    // A secret table (#357): no columns and no rows (an empty csv) while it is `locked` for this
+    // caller.
+    ...SecretFields,
+});
+// The answer of a create and an update: the state after it, without the rows, so appending one row
+// to a large table does not send the table back.
+export const TableSaved = z.strictObject({
+    tableId: TableId,
+    name: z.string(),
+    columns: z.array(TableColumn),
+    // How many data rows the table holds now.
+    rowCount: z.number().int(),
+    version: z.number().int(),
+    rev: z.number().int(),
+    // Only after a change of the columns: every removed column and the positions (in the new state)
+    // of the rows whose content in it now stands only in the history.
+    removedColumns: z
+        .array(z.strictObject({ name: z.string(), rows: z.array(z.number().int()) }))
+        .optional(),
+});

package/dist/tool.d.ts

@@ -0,0 +1,31 @@
+import type { z } from "zod";
+import type { Package } from "./grammar/grammar.js";
+export type ToolInput = z.ZodObject<z.core.$ZodShape, z.core.$strict>;
+export type Permission = `${Package} / ${string} / ${string}`;
+export type Actor = {
+    userId: string;
+    kind: "human" | "machine";
+    adminMode: boolean;
+    client?: string;
+    session?: string;
+};
+export type ToolSource = "api" | "mcp";
+export type ToolContext = {
+    actor: Actor;
+    source?: ToolSource;
+};
+export type ToolAnnotations = {
+    readOnlyHint?: boolean;
+    openWorldHint?: boolean;
+};
+export type Tool<Input extends ToolInput = ToolInput> = {
+    name: string;
+    description: string;
+    input: Input;
+    permission: Permission;
+    revealsSecret?: true;
+    browserOnly?: true;
+    annotations?: ToolAnnotations;
+    handler(input: z.output<Input>, context: ToolContext): Promise<unknown>;
+};
+export declare function defineTool<Input extends ToolInput>(tool: Tool<Input>): Tool;

package/dist/tool.js

@@ -0,0 +1,4 @@
+// Keeps a tool's input type for its handler, and hands it on as a plain `Tool` for the list.
+export function defineTool(tool) {
+    return tool;
+}

package/dist/user-settings/user-settings.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+export declare const notifyModes: readonly ["immediate", "daily", "never"];
+export declare const NotifyMode: z.ZodEnum<{
+    never: "never";
+    daily: "daily";
+    immediate: "immediate";
+}>;
+export type NotifyMode = z.infer<typeof NotifyMode>;
+export declare const IntelligenceUserGetInput: z.ZodObject<{
+    userId: z.ZodTemplateLiteral<`user_${string}`>;
+}, z.core.$strict>;
+export type IntelligenceUserGetInput = z.infer<typeof IntelligenceUserGetInput>;
+export declare const IntelligenceUserUpdateInput: z.ZodObject<{
+    userId: z.ZodTemplateLiteral<`user_${string}`>;
+    notify: z.ZodOptional<z.ZodEnum<{
+        never: "never";
+        daily: "daily";
+        immediate: "immediate";
+    }>>;
+    digestHour: z.ZodOptional<z.ZodNumber>;
+    digestZone: z.ZodOptional<z.ZodString>;
+    digestLocale: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        de: "de";
+    }>>;
+    baseUpdatedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type IntelligenceUserUpdateInput = z.infer<typeof IntelligenceUserUpdateInput>;
+export declare const UserSettings: z.ZodObject<{
+    userId: z.ZodTemplateLiteral<`user_${string}`>;
+    notify: z.ZodEnum<{
+        never: "never";
+        daily: "daily";
+        immediate: "immediate";
+    }>;
+    digestHour: z.ZodNumber;
+    digestZone: z.ZodString;
+    digestLocale: z.ZodEnum<{
+        en: "en";
+        de: "de";
+    }>;
+    updatedAt: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type UserSettings = z.infer<typeof UserSettings>;

package/dist/user-settings/user-settings.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { Locale, TimeZone } from "../profile/profile.js";
+import { UserId } from "../users/users.js";
+// How new things in Actions reach a person by mail (#50, Einstellungen › Benachrichtigungen, E53):
+// the setting of the resource `user` in `intelligence`, read and changed by the person themselves.
+// "Notification" is no resource. ⚠️ `UserGetInput` and `UserUpdateInput` belong to `access_user_get`
+// and `access_user_update`, so these two carry the package word (`toolSchemaName`, as
+// `IntelligenceUserListInput` beside `UserListInput`). Every input field carries its description
+// (trap C004).
+// Immediately ("New for you"), once a day (the daily summary) or never.
+export const notifyModes = ["immediate", "daily", "never"];
+export const NotifyMode = z.enum(notifyModes);
+export const IntelligenceUserGetInput = z.strictObject({
+    userId: UserId.describe("Your own user id, `user_…`. Only your own setting can be read; any other id answers not_found."),
+});
+export const IntelligenceUserUpdateInput = z.strictObject({
+    userId: UserId.describe("Your own user id, `user_…`. Only your own setting can be changed; any other id answers not_found."),
+    notify: NotifyMode.optional().describe("How something new in your Actions (a task open for you, a mention in a chat) reaches you by mail: immediate sends one mail each time, daily one summary at digestHour, never none. Leaving it out keeps it."),
+    digestHour: z
+        .number()
+        .int()
+        .min(0)
+        .max(23)
+        .optional()
+        .describe("The hour of the daily summary, 0 to 23, in digestZone. Leaving it out keeps it; the default is 8."),
+    digestZone: TimeZone.optional().describe("The IANA time zone the hour counts in, such as Europe/Berlin. Leaving it out keeps it; the default is the zone of your profile."),
+    digestLocale: Locale.optional().describe("The language of your mails, en or de. Leaving it out keeps it; the default is the language of your profile."),
+    // ⚠️ Required and nullable (trap C015): a caller that leaves it out could overwrite a newer save.
+    baseUpdatedAt: z.iso
+        .datetime()
+        .nullable()
+        .describe("The updatedAt your last read returned, null when it was null (nothing saved yet). If someone saved in between, the call answers conflict and changes nothing: read again and decide."),
+});
+// The answer of both: the values that apply now, stored or the defaults.
+export const UserSettings = z.strictObject({
+    userId: UserId,
+    // A machine is always `never`: it fetches its tasks and messages over MCP itself.
+    notify: NotifyMode,
+    digestHour: z.number().int(),
+    digestZone: z.string(),
+    digestLocale: Locale,
+    // The last save, null while nothing is saved and the defaults apply. The next save sends it back.
+    updatedAt: z.iso.datetime().nullable(),
+});