@protoyard/flows 0.0.0-stage → 1.1.0

package/dist/model/recipes.js

@@ -0,0 +1,209 @@
+const team = [{ type: 'team', id: 'team', name: 'The team' }];
+const leads = [{ type: 'role', id: 'lead', name: 'Team leads' }];
+function recipe(id, title, summary, flow) {
+    return {
+        id,
+        title,
+        summary,
+        build: (overrides = {}) => ({
+            formatVersion: 1,
+            id: overrides.id ?? id,
+            name: overrides.name ?? title,
+            status: 'draft',
+            ...structuredClone(flow),
+        }),
+    };
+}
+export const FLOW_RECIPES = [
+    recipe('daily-check-in', 'Daily check-in', 'Ask the team three questions each workday and share a summary.', {
+        triggers: [
+            {
+                id: 'weekday-morning',
+                type: 'schedule',
+                days: ['monday', 'tuesday', 'wednesday', 'thursday', 'friday'],
+                time: '09:30',
+                timezone: 'local',
+            },
+        ],
+        steps: [
+            {
+                id: 'ask-team',
+                type: 'ask',
+                audience: team,
+                questions: [
+                    { id: 'done', kind: 'text', prompt: 'What did you finish yesterday?', required: true },
+                    { id: 'next', kind: 'text', prompt: 'What are you working on today?', required: true },
+                    { id: 'blocked', kind: 'boolean', prompt: 'Is anything blocking you?' },
+                ],
+                deadlineMinutes: 240,
+            },
+            {
+                id: 'summarize',
+                type: 'assistant',
+                task: 'summarize',
+                input: { from: 'step', stepId: 'ask-team' },
+            },
+            {
+                id: 'share-summary',
+                type: 'message',
+                channel: 'chat',
+                to: team,
+                text: ['Today’s check-in: ', { ref: { from: 'step', stepId: 'summarize' } }],
+            },
+        ],
+    }),
+    recipe('approval-request', 'Approval request', 'Collect a request, route it to an approver and tell the requester.', {
+        triggers: [
+            { id: 'request', type: 'manual', label: 'New request', surfaces: ['app', 'link'] },
+        ],
+        collections: [
+            {
+                id: 'requests',
+                noun: 'request',
+                plural: 'requests',
+                states: [
+                    { id: 'pending', label: 'Pending' },
+                    { id: 'approved', label: 'Approved', final: true },
+                    { id: 'declined', label: 'Declined', final: true },
+                ],
+            },
+        ],
+        steps: [
+            {
+                id: 'save-request',
+                type: 'save_record',
+                collection: 'requests',
+                title: [{ ref: { from: 'trigger', path: ['summary'] } }],
+                state: 'pending',
+            },
+            {
+                id: 'approve',
+                type: 'approval',
+                approvers: leads,
+                prompt: ['Approve this request? ', { ref: { from: 'trigger', path: ['summary'] } }],
+            },
+            {
+                id: 'decide',
+                type: 'branch',
+                when: {
+                    type: 'compare',
+                    left: { ref: { from: 'step', stepId: 'approve', path: ['decision'] } },
+                    op: 'eq',
+                    right: { value: 'approved' },
+                },
+                // biome-ignore lint/suspicious/noThenProperty: a branch arm, not a thenable
+                then: [
+                    { id: 'mark-approved', type: 'set_state', state: 'approved' },
+                    { id: 'tell-approved', type: 'reply', text: 'Your request was approved.' },
+                ],
+                otherwise: [
+                    { id: 'mark-declined', type: 'set_state', state: 'declined' },
+                    { id: 'tell-declined', type: 'reply', text: 'Your request was declined.' },
+                ],
+            },
+        ],
+    }),
+    recipe('incoming-triage', 'Incoming triage', 'Classify each new record and alert the team about urgent ones.', {
+        triggers: [{ id: 'new-record', type: 'event', event: 'record.created', source: 'records' }],
+        collections: [
+            {
+                id: 'tickets',
+                noun: 'ticket',
+                plural: 'tickets',
+                states: [
+                    { id: 'new', label: 'New' },
+                    { id: 'urgent', label: 'Urgent' },
+                    { id: 'closed', label: 'Closed', final: true },
+                ],
+            },
+        ],
+        steps: [
+            {
+                id: 'classify',
+                type: 'assistant',
+                task: 'classify',
+                input: { from: 'record', path: ['body'] },
+                labels: ['urgent', 'normal', 'spam'],
+            },
+            {
+                id: 'urgent',
+                type: 'branch',
+                when: {
+                    type: 'any',
+                    conditions: [
+                        {
+                            type: 'compare',
+                            left: { ref: { from: 'step', stepId: 'classify', path: ['label'] } },
+                            op: 'eq',
+                            right: { value: 'urgent' },
+                        },
+                        { type: 'judge', phrase: 'the customer cannot work at all' },
+                    ],
+                },
+                // biome-ignore lint/suspicious/noThenProperty: a branch arm, not a thenable
+                then: [
+                    { id: 'mark-urgent', type: 'set_state', state: 'urgent' },
+                    {
+                        id: 'alert-team',
+                        type: 'message',
+                        channel: 'notification',
+                        to: team,
+                        text: ['Urgent: ', { ref: { from: 'record', path: ['title'] } }],
+                    },
+                ],
+                otherwise: [],
+            },
+        ],
+    }),
+    recipe('weekly-digest', 'Weekly digest', 'Every Friday, gather the week’s records and send a digest by email.', {
+        triggers: [
+            { id: 'friday', type: 'schedule', days: ['friday'], time: '16:00', timezone: 'local' },
+        ],
+        collections: [{ id: 'updates', noun: 'update', states: [] }],
+        steps: [
+            { id: 'gather', type: 'get_records', collection: 'updates', sinceDays: 7, limit: 100 },
+            {
+                id: 'any-updates',
+                type: 'branch',
+                when: { type: 'test', subject: { from: 'step', stepId: 'gather' }, test: 'not_empty' },
+                // biome-ignore lint/suspicious/noThenProperty: a branch arm, not a thenable
+                then: [
+                    {
+                        id: 'digest',
+                        type: 'assistant',
+                        task: 'summarize',
+                        input: { from: 'step', stepId: 'gather' },
+                    },
+                    {
+                        id: 'send-digest',
+                        type: 'message',
+                        channel: 'email',
+                        to: leads,
+                        subject: 'Weekly digest',
+                        text: [{ ref: { from: 'step', stepId: 'digest' } }],
+                    },
+                ],
+                otherwise: [],
+            },
+        ],
+    }),
+    recipe('rotating-host', 'Rotating host', 'Each Monday, pick the next host from a list and announce it.', {
+        triggers: [
+            { id: 'monday', type: 'schedule', days: ['monday'], time: '10:00', timezone: 'local' },
+        ],
+        lists: [{ id: 'hosts', name: 'Hosts', items: ['Ada Example', 'Lin Example', 'Sam Example'] }],
+        steps: [
+            { id: 'pick-host', type: 'pick_from_list', list: 'hosts', order: 'next_unused' },
+            {
+                id: 'announce',
+                type: 'message',
+                channel: 'chat',
+                to: team,
+                text: ['This week’s host is ', { ref: { from: 'step', stepId: 'pick-host' } }, '.'],
+            },
+        ],
+    }),
+];
+export function findRecipe(id) {
+    return FLOW_RECIPES.find((r) => r.id === id);
+}

package/dist/model/refs.d.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+/**
+ * A reference to data a run has at hand: a field of what started it
+ * (`trigger`), the output of an earlier step (`step`), or the record the run
+ * is about (`record`). The path is a list of plain segments, never an
+ * expression, and only own properties are read.
+ */
+export type DataRef = {
+    from: 'trigger';
+    path?: string[];
+} | {
+    from: 'step';
+    stepId: string;
+    path?: string[];
+} | {
+    from: 'record';
+    path?: string[];
+};
+export declare const FlowIdSchema: z.ZodString;
+export declare const DataRefSchema: z.ZodType<DataRef>;
+/** What a run offers references: its trigger payload, step outputs and record. */
+export interface RefScope {
+    trigger?: unknown;
+    outputs?: Readonly<Record<string, unknown>>;
+    record?: unknown;
+}
+/** Reads a reference from a run scope; anything missing is `undefined`. */
+export declare function resolveRef(ref: DataRef, scope?: RefScope): unknown;
+/** A short human label: `trigger.payload.status`, `step check.result`, `record.state`. */
+export declare function describeRef(ref: DataRef): string;

package/dist/model/refs.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { FORBIDDEN_KEYS } from "./data.js";
+import { FLOW_ID_PATTERN, FLOW_LIMITS } from "./limits.js";
+export const FlowIdSchema = z.string().regex(FLOW_ID_PATTERN, 'Use a lowercase slug id');
+const SegmentSchema = z
+    .string()
+    .regex(/^[A-Za-z0-9_-]{1,64}$/, 'Use letters, digits, - or _ in a path segment')
+    .refine((segment) => !FORBIDDEN_KEYS.has(segment), 'This path segment is not allowed');
+const PathSchema = z.array(SegmentSchema).min(1).max(FLOW_LIMITS.maxPathSegments).optional();
+export const DataRefSchema = z.discriminatedUnion('from', [
+    z.strictObject({ from: z.literal('trigger'), path: PathSchema }),
+    z.strictObject({ from: z.literal('step'), stepId: FlowIdSchema, path: PathSchema }),
+    z.strictObject({ from: z.literal('record'), path: PathSchema }),
+]);
+function readPath(root, path) {
+    let value = root;
+    for (const segment of path ?? []) {
+        if (value === null || typeof value !== 'object' || FORBIDDEN_KEYS.has(segment)) {
+            return undefined;
+        }
+        if (!Object.hasOwn(value, segment))
+            return undefined;
+        value = value[segment];
+    }
+    return value;
+}
+/** Reads a reference from a run scope; anything missing is `undefined`. */
+export function resolveRef(ref, scope = {}) {
+    switch (ref.from) {
+        case 'trigger':
+            return readPath(scope.trigger, ref.path);
+        case 'record':
+            return readPath(scope.record, ref.path);
+        case 'step': {
+            const outputs = scope.outputs ?? {};
+            if (!Object.hasOwn(outputs, ref.stepId))
+                return undefined;
+            return readPath(outputs[ref.stepId], ref.path);
+        }
+    }
+}
+/** A short human label: `trigger.payload.status`, `step check.result`, `record.state`. */
+export function describeRef(ref) {
+    const tail = ref.path?.length ? `.${ref.path.join('.')}` : '';
+    if (ref.from === 'step')
+        return `step ${ref.stepId}${tail}`;
+    return `${ref.from}${tail}`;
+}

package/dist/model/steps.d.ts

@@ -0,0 +1,276 @@
+import { z } from 'zod';
+import { type Condition } from './conditions.ts';
+export declare const QUESTION_KINDS: readonly ["text", "choice", "boolean", "number"];
+export declare const QuestionSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        number: "number";
+        boolean: "boolean";
+        text: "text";
+        choice: "choice";
+    }>;
+    prompt: z.ZodString;
+    required: z.ZodOptional<z.ZodBoolean>;
+    choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type Question = z.infer<typeof QuestionSchema>;
+declare const LEAF_STEP_SCHEMAS: readonly [z.ZodObject<{
+    type: z.ZodLiteral<"ask">;
+    audience: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            person: "person";
+            team: "team";
+            role: "role";
+            channel: "channel";
+            list: "list";
+            everyone: "everyone";
+        }>;
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+    questions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            number: "number";
+            boolean: "boolean";
+            text: "text";
+            choice: "choice";
+        }>;
+        prompt: z.ZodString;
+        required: z.ZodOptional<z.ZodBoolean>;
+        choices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    deadlineMinutes: z.ZodOptional<z.ZodNumber>;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"approval">;
+    approvers: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            person: "person";
+            team: "team";
+            role: "role";
+            channel: "channel";
+            list: "list";
+            everyone: "everyone";
+        }>;
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+    prompt: z.ZodType<import("./text.ts").FlowText, unknown, z.core.$ZodTypeInternals<import("./text.ts").FlowText, unknown>>;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"wait">;
+    minutes: z.ZodNumber;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"wait_until">;
+    until: z.ZodEnum<{
+        time: "time";
+        event: "event";
+        approval: "approval";
+        replies: "replies";
+    }>;
+    time: z.ZodOptional<z.ZodString>;
+    event: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"message">;
+    channel: z.ZodEnum<{
+        email: "email";
+        chat: "chat";
+        inbox: "inbox";
+        notification: "notification";
+    }>;
+    to: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            person: "person";
+            team: "team";
+            role: "role";
+            channel: "channel";
+            list: "list";
+            everyone: "everyone";
+        }>;
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+    subject: z.ZodOptional<z.ZodString>;
+    text: z.ZodType<import("./text.ts").FlowText, unknown, z.core.$ZodTypeInternals<import("./text.ts").FlowText, unknown>>;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"reply">;
+    text: z.ZodType<import("./text.ts").FlowText, unknown, z.core.$ZodTypeInternals<import("./text.ts").FlowText, unknown>>;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"assistant">;
+    task: z.ZodEnum<{
+        check: "check";
+        summarize: "summarize";
+        classify: "classify";
+        extract: "extract";
+        draft: "draft";
+    }>;
+    input: z.ZodOptional<z.ZodType<import("./refs.ts").DataRef, unknown, z.core.$ZodTypeInternals<import("./refs.ts").DataRef, unknown>>>;
+    instructions: z.ZodOptional<z.ZodType<import("./text.ts").FlowText, unknown, z.core.$ZodTypeInternals<import("./text.ts").FlowText, unknown>>>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"save_record">;
+    collection: z.ZodString;
+    title: z.ZodOptional<z.ZodType<import("./text.ts").FlowText, unknown, z.core.$ZodTypeInternals<import("./text.ts").FlowText, unknown>>>;
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<import("./text.ts").FlowText, unknown, z.core.$ZodTypeInternals<import("./text.ts").FlowText, unknown>>>>;
+    state: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"get_records">;
+    collection: z.ZodString;
+    sinceDays: z.ZodNumber;
+    limit: z.ZodNumber;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"set_state">;
+    state: z.ZodString;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"pick_from_list">;
+    list: z.ZodString;
+    order: z.ZodEnum<{
+        next_unused: "next_unused";
+        seeded: "seeded";
+    }>;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"update_list">;
+    list: z.ZodString;
+    action: z.ZodEnum<{
+        add: "add";
+        remove: "remove";
+    }>;
+    value: z.ZodType<import("./text.ts").FlowText, unknown, z.core.$ZodTypeInternals<import("./text.ts").FlowText, unknown>>;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"group_people">;
+    from: z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            person: "person";
+            team: "team";
+            role: "role";
+            channel: "channel";
+            list: "list";
+            everyone: "everyone";
+        }>;
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+    mode: z.ZodEnum<{
+        pairs: "pairs";
+        groups: "groups";
+        pick_one: "pick_one";
+    }>;
+    size: z.ZodOptional<z.ZodNumber>;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"call_tool">;
+    tool: z.ZodString;
+    action: z.ZodString;
+    input: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<import("./text.ts").FlowText, unknown, z.core.$ZodTypeInternals<import("./text.ts").FlowText, unknown>>>>;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"start_flow">;
+    flowId: z.ZodString;
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    only: z.ZodOptional<z.ZodType<Condition, unknown, z.core.$ZodTypeInternals<Condition, unknown>>>;
+    delayMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>];
+type LeafStep = z.infer<(typeof LEAF_STEP_SCHEMAS)[number]>;
+/** A branch: `then` runs when `when` passes, `otherwise` when it fails. */
+export interface BranchStep {
+    id: string;
+    type: 'branch';
+    label?: string;
+    enabled?: boolean;
+    only?: Condition;
+    delayMinutes?: number;
+    when: Condition;
+    then: Step[];
+    otherwise: Step[];
+}
+export type Step = LeafStep | BranchStep;
+export type StepType = Step['type'];
+export type StepOf<T extends StepType> = Extract<Step, {
+    type: T;
+}>;
+export declare const StepSchema: z.ZodType<Step>;
+export type StepCategory = 'people' | 'timing' | 'logic' | 'messages' | 'data' | 'tools';
+export interface StepKind {
+    type: StepType;
+    label: string;
+    category: StepCategory;
+    /** What the step leaves for later steps to reference. */
+    output: 'replies' | 'decision' | 'text' | 'records' | 'item' | 'group' | 'none';
+    /** True when a runtime turns it into a proposed effect (a message, a saved record…). */
+    effect: boolean;
+}
+/** One entry per step type, in editor order. */
+export declare const STEP_KINDS: readonly StepKind[];
+export declare const STEP_TYPES: readonly StepType[];
+export declare function stepKind(type: StepType): StepKind;
+export declare function isStepEnabled(step: Step): boolean;
+export {};