@svgrid/enterprise 3.1.8 → 3.1.10

package/dist/fields/automation-server.js

@@ -0,0 +1,333 @@
+/**
+ * Automations on the server: the ones set to "Runs in: the server".
+ *
+ * The browser runner runs an automation in the page of whoever made the
+ * change. That cannot send an email, keep an API key, notice a change made by
+ * another app, or run at 9:00 when nobody has the base open. This runner can:
+ * it lives in your server (a SvelteKit route, a worker process), reads and
+ * writes the tables through the same `baseSource`s, and hears of changes in
+ * one of three ways:
+ *
+ *  - `recordChanged(table, { before, after })`: a change with both sides, as
+ *    a Supabase database webhook or a Postgres trigger sends it;
+ *  - `audit(table)`: the `audit` hook of `createKitHandlers`, after every
+ *    write through your endpoint (the "before" is what it read last);
+ *  - `tableChanged(table)`: read the table again and compare.
+ *
+ * `tick()` runs the scheduled ones; call it once a minute (a cron job, a
+ * `setInterval`). A change it makes is kept as what it read, so the echo of
+ * its own write (the webhook firing for it) is recognized and ignored, and
+ * automations setting each other off stop at `MAX_DEPTH`.
+ */
+import { cronMatches } from '../scheduling.js';
+import { primaryOf, rowIdOf, syncAllInverses } from './base-tables.js';
+import { newRecordId } from './field-ops.js';
+import { registerLinkedTable } from './sources.svelte.js';
+import { MAX_DEPTH, automationsFor, fieldValueFrom, fillTokens, matches, outbound, runAppAction, tableFields, } from './automations.svelte.js';
+import { callWebhook, sendEmailAction } from './automation-outbound.js';
+let runSeq = 0;
+const same = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+export function createAutomationServer(options) {
+    const now = options.now ?? (() => new Date());
+    const keep = options.keepRuns ?? 200;
+    let tables = options.tables.map((t) => ({ ...t, data: [] }));
+    let primed = null;
+    let chain = Promise.resolve();
+    const runs = [];
+    const lastFired = new Map();
+    const secret = (name) => (typeof options.secrets === 'function' ? options.secrets(name) : options.secrets?.[name]);
+    const tableOf = (id) => tables.find((t) => t.id === id);
+    const sourceOf = (t) => {
+        if (!t.source)
+            throw new Error(`Table ${t.name} has no source`);
+        return t.source;
+    };
+    function setData(tableId, change) {
+        tables = tables.map((t) => (t.id === tableId ? { ...t, data: change(t.data) } : t));
+        // The fields that link back are worked out from the other side.
+        for (const t of tables)
+            tables = syncAllInverses(tables, t.id);
+    }
+    /** Read every table once, so later changes have a "before" and links have names. */
+    function prime() {
+        primed ?? (primed = (async () => {
+            for (const t of tables) {
+                const rows = await sourceOf(t).load();
+                setData(t.id, () => rows);
+            }
+            for (const t of tables) {
+                const id = t.id;
+                registerLinkedTable({
+                    id,
+                    name: t.name,
+                    rows: () => tableOf(id)?.data ?? [],
+                    getRowId: (r) => rowIdOf(tableOf(id) ?? t, r),
+                    primaryField: primaryOf(t),
+                    fields: t.columns.filter((d) => d.field).map((d) => ({ field: String(d.field), header: String(d.header ?? d.field), fieldType: d.fieldType, fieldProps: d.fieldProps })),
+                });
+            }
+        })());
+        return primed;
+    }
+    /** Column ids of the fields that differ between two versions of a record. */
+    function changedFields(t, before, after) {
+        const out = [];
+        for (const c of tableFields(t).values())
+            if (!same(before[c.field], after[c.field]))
+                out.push(c.id);
+        return out;
+    }
+    // ---- What it hears ---------------------------------------------------------------
+    /**
+     * A record changed: rows as the database has them (`db: false` for rows
+     * already in the base's shape). No `after` is a delete; no `before` is
+     * read from what it last read.
+     */
+    async function recordChanged(tableId, change, opts = {}) {
+        await prime();
+        const t = tableOf(tableId);
+        if (!t)
+            throw new Error(`No table "${tableId}"`);
+        const asPage = (r) => (r ? (opts.db === false ? r : sourceOf(t).toPage(r)) : null);
+        const after = asPage(change.after);
+        const before = asPage(change.before);
+        if (!after) {
+            const id = String(before?.id ?? '');
+            setData(tableId, (rows) => rows.filter((r) => rowIdOf(t, r) !== id));
+            return [];
+        }
+        const id = String(after.id);
+        const known = t.data.find((r) => rowIdOf(t, r) === id);
+        // A junction link is not in a database row: keep the one it read.
+        const merged = { ...(known ?? {}), ...after };
+        // The echo of a change it made, or one it already heard: nothing new.
+        if (known && same(known, merged))
+            return [];
+        const prev = before ? { ...(known ?? {}), ...before } : known;
+        setData(tableId, (rows) => (known ? rows.map((r) => (r === known ? merged : r)) : [...rows, merged]));
+        const record = tableOf(tableId).data.find((r) => rowIdOf(t, r) === id);
+        if (!prev)
+            return handle({ type: 'created', table: tableId, record });
+        const fields = changedFields(t, prev, record);
+        return fields.length ? handle({ type: 'updated', table: tableId, record, before: prev, fields }) : [];
+    }
+    /** Read a table again and run what its changes set off. */
+    async function tableChanged(tableId) {
+        await prime();
+        const t = tableOf(tableId);
+        if (!t)
+            throw new Error(`No table "${tableId}"`);
+        const fresh = await sourceOf(t).load();
+        const old = new Map(t.data.map((r) => [rowIdOf(t, r), r]));
+        setData(tableId, () => fresh);
+        const out = [];
+        for (const r of tableOf(tableId).data) {
+            const prev = old.get(rowIdOf(t, r));
+            if (!prev)
+                out.push(...(await handle({ type: 'created', table: tableId, record: r })));
+            else {
+                const fields = changedFields(t, prev, r);
+                if (fields.length)
+                    out.push(...(await handle({ type: 'updated', table: tableId, record: r, before: prev, fields })));
+            }
+        }
+        return out;
+    }
+    /** The `audit` hook of `createKitHandlers` for a table: every write through the endpoint. */
+    function audit(tableId) {
+        return async (entry) => {
+            if (entry.action === 'delete') {
+                await recordChanged(tableId, { before: { id: entry.id }, after: null }, { db: false });
+                return;
+            }
+            // A bulk update has no single row: read the table.
+            if (!entry.result) {
+                await tableChanged(tableId);
+                return;
+            }
+            await recordChanged(tableId, { after: entry.result });
+        };
+    }
+    async function formSubmitted(tableId, recordId, view) {
+        await prime();
+        const record = await recordById(tableId, recordId);
+        return record ? handle({ type: 'form', table: tableId, record, view }) : [];
+    }
+    async function buttonPressed(tableId, recordId, field) {
+        await prime();
+        const record = await recordById(tableId, recordId);
+        return record ? handle({ type: 'button', table: tableId, record, field }) : [];
+    }
+    async function recordById(tableId, id) {
+        const t = tableOf(tableId);
+        if (!t)
+            return null;
+        let hit = t.data.find((r) => rowIdOf(t, r) === id);
+        if (!hit) {
+            await tableChanged(tableId);
+            hit = tableOf(tableId).data.find((r) => rowIdOf(t, r) === id);
+        }
+        return hit ?? null;
+    }
+    /** Run the scheduled automations due at this minute (call it once a minute). */
+    async function tick(at = now()) {
+        await prime();
+        const minute = `${at.getFullYear()}-${at.getMonth()}-${at.getDate()} ${at.getHours()}:${at.getMinutes()}`;
+        const out = [];
+        for (const t of tables) {
+            for (const a of t.automations ?? []) {
+                if (!a.enabled || a.runOn !== 'server' || a.trigger.type !== 'scheduled')
+                    continue;
+                const key = `${t.id}:${a.id}`;
+                if (lastFired.get(key) === minute || !cronMatches(a.trigger.cron, at))
+                    continue;
+                lastFired.set(key, minute);
+                if (!a.condition)
+                    out.push(await queue(a, t.id, null, 0));
+                else
+                    for (const r of tableOf(t.id).data)
+                        if (matches(t, a.condition, r))
+                            out.push(await queue(a, t.id, rowIdOf(t, r), 0));
+            }
+        }
+        return out;
+    }
+    // ---- Running ------------------------------------------------------------------------
+    async function handle(e) {
+        const t = tableOf(e.table);
+        if (!t)
+            return [];
+        const depth = 'depth' in e ? (e.depth ?? 0) : 0;
+        const out = [];
+        for (const a of automationsFor(t, e, 'server'))
+            out.push(await queue(a, t.id, rowIdOf(t, e.record), depth));
+        return out;
+    }
+    /** One run at a time, in the order they were set off. */
+    function queue(a, tableId, recordId, depth) {
+        const next = chain.then(() => runOne(a, tableId, recordId, depth));
+        chain = next.catch(() => undefined);
+        return next;
+    }
+    async function runOne(a, tableId, recordId, depth) {
+        const t = tableOf(tableId);
+        const rec = recordId == null ? null : (t.data.find((r) => rowIdOf(t, r) === recordId) ?? null);
+        const run = { id: ++runSeq, automationId: a.id, name: a.name, table: t.name, record: rec ? String(rec[primaryOf(t)] ?? recordId) : null, at: now().getTime(), status: 'ok', steps: [] };
+        if (depth >= MAX_DEPTH) {
+            run.status = 'stopped';
+            run.steps.push({ action: 'Stopped', detail: `Automations set each other off ${MAX_DEPTH} times in a row; this one did not run, so they cannot loop.` });
+        }
+        else {
+            const follow = [];
+            for (const action of a.actions) {
+                try {
+                    const step = await act(a, action, tableId, recordId, depth, follow);
+                    if (step)
+                        run.steps.push(step);
+                }
+                catch (e) {
+                    run.status = 'error';
+                    run.steps.push({ action: action.type, detail: '', error: e instanceof Error ? e.message : String(e) });
+                    break;
+                }
+            }
+            remember(run);
+            // What its actions changed can set off others, after this run is kept.
+            for (const f of follow)
+                void f();
+            return run;
+        }
+        remember(run);
+        return run;
+    }
+    function remember(run) {
+        runs.unshift(run);
+        if (runs.length > keep)
+            runs.length = keep;
+        options.onRun?.(run);
+    }
+    async function act(a, action, tableId, recordId, depth, follow) {
+        const t = tableOf(tableId);
+        const rec = recordId == null ? null : (t.data.find((r) => rowIdOf(t, r) === recordId) ?? null);
+        const ctx = { tables, from: t, record: rec, now: now() };
+        switch (action.type) {
+            case 'notify': {
+                const message = fillTokens(t, rec, action.message);
+                options.notify?.({ message, severity: action.severity ?? 'info', automation: a.name, table: t.name, record: rec });
+                return { action: 'Notice', detail: message };
+            }
+            case 'highlight':
+                return null;
+            case 'updateRecord': {
+                if (!rec || recordId == null)
+                    return { action: 'Update record', detail: 'No record to update' };
+                const fields = tableFields(t);
+                const patch = {};
+                for (const [id, spec] of Object.entries(action.values)) {
+                    const c = fields.get(id);
+                    if (c)
+                        patch[c.field] = fieldValueFrom(t, c.def, spec, ctx);
+                }
+                const after = { ...rec, ...patch };
+                const changed = Object.keys(patch).filter((f) => !same(rec[f], after[f]));
+                if (!changed.length)
+                    return { action: 'Update record', detail: 'Already set' };
+                const only = {};
+                for (const f of changed)
+                    only[f] = after[f];
+                await sourceOf(t).update(recordId, only, rec);
+                setData(tableId, (rows) => rows.map((r) => (r === rec ? after : r)));
+                const ids = changed.map((f) => [...fields.values()].find((c) => c.field === f)?.id ?? f);
+                follow.push(() => handle({ type: 'updated', table: tableId, record: tableOf(tableId).data.find((r) => rowIdOf(t, r) === recordId), before: rec, fields: ids, depth: depth + 1 }));
+                return { action: 'Update record', detail: changed.map((f) => `${[...fields.values()].find((c) => c.field === f)?.header ?? f}: ${String(after[f] ?? '')}`).join(', ') };
+            }
+            case 'createRecord': {
+                const target = tableOf(action.table);
+                if (!target)
+                    throw new Error(`No table "${action.table}"`);
+                const fields = tableFields(target);
+                const row = { id: newRecordId() };
+                for (const [id, spec] of Object.entries(action.values)) {
+                    const c = fields.get(id);
+                    if (c)
+                        row[c.field] = fieldValueFrom(target, c.def, spec, ctx);
+                }
+                if (action.linkField && rec) {
+                    const c = fields.get(action.linkField);
+                    if (c)
+                        row[c.field] = [rowIdOf(t, rec)];
+                }
+                const stored = await sourceOf(target).insert(row);
+                const made = { ...row, id: String(stored.id ?? row.id) };
+                setData(target.id, (rows) => [...rows, made]);
+                follow.push(() => handle({ type: 'created', table: target.id, record: made, depth: depth + 1 }));
+                return { action: 'Create record', detail: `${String(made[primaryOf(target)] ?? '') || 'a record'} in ${target.name}` };
+            }
+            case 'run':
+                return runAppAction(a, action, t, rec);
+            case 'webhook':
+                return { action: 'Webhook', detail: await callWebhook(action, outbound(a, t, rec, { secret, fetch: options.fetch })) };
+            case 'email':
+                return { action: 'Email', detail: await sendEmailAction(action, outbound(a, t, rec), options.sendEmail) };
+        }
+    }
+    return {
+        prime,
+        recordChanged,
+        tableChanged,
+        audit,
+        formSubmitted,
+        buttonPressed,
+        tick,
+        /** The latest runs, newest first: hand them to `<SvBase serverRuns>` from an endpoint. */
+        get runs() {
+            return runs;
+        },
+        /** Resolves when every queued run has finished. */
+        settled: () => chain.then(() => undefined),
+        /** The tables as it last read them. */
+        get tables() {
+            return tables;
+        },
+    };
+}

package/dist/fields/automations.svelte.d.ts

@@ -0,0 +1,208 @@
+import { type BaseTable } from './base-tables.js';
+import { type FieldFilter } from './filter-model.js';
+import type { FieldColumn } from './grid-access.js';
+import { type EmailAction, type OutboundContext, type WebhookAction } from './automation-outbound.js';
+type Row = Record<string, unknown>;
+type Def = Record<string, any>;
+export type AutomationTrigger = 
+/** A record is added: "+ Add row", a form, a board lane, another automation. */
+{
+    type: 'recordCreated';
+}
+/** A record changes; with `fields`, only when one of them does. */
+ | {
+    type: 'recordUpdated';
+    fields?: string[];
+}
+/** A record starts matching the condition (it did not before the change). */
+ | {
+    type: 'recordMatches';
+}
+/** A form view sends a record; with `view`, only that form. */
+ | {
+    type: 'formSubmitted';
+    view?: string;
+}
+/** A button field is pressed on a record. */
+ | {
+    type: 'button';
+    field: string;
+}
+/** On a schedule: once for each record matching the condition then, or once with no record. */
+ | {
+    type: 'scheduled';
+    cron: string;
+};
+export type AutomationAction = 
+/** Set fields of the record that set it off. */
+{
+    type: 'updateRecord';
+    values: Record<string, unknown>;
+}
+/** Add a record to a table; `linkField` there links it to the record that set it off. */
+ | {
+    type: 'createRecord';
+    table: string;
+    values: Record<string, unknown>;
+    linkField?: string;
+}
+/** A notice: `{Field name}` is that field of the record. */
+ | {
+    type: 'notify';
+    message: string;
+    severity?: 'info' | 'success' | 'warning' | 'error';
+}
+/** While the record matches the condition, color these fields (or the whole row). */
+ | {
+    type: 'highlight';
+    fields?: string[];
+    background: string;
+    color?: string;
+}
+/** A function the app registered with `registerAutomationAction`. */
+ | {
+    type: 'run';
+    action: string;
+    options?: Record<string, unknown>;
+}
+/** Call a URL with the record (a chat webhook, your API). */
+ | WebhookAction
+/** Send an email (the server runner's `sendEmail`). */
+ | EmailAction;
+export type BaseAutomation = {
+    id: string;
+    name: string;
+    enabled: boolean;
+    /**
+     * Where it runs: in the browser of the person who made the change
+     * (default), or on the server with `createAutomationServer`, which hears of
+     * changes from the database and can read secrets and send email.
+     */
+    runOn?: 'browser' | 'server';
+    trigger: AutomationTrigger;
+    /** Only records that match (the view bar's filter). */
+    condition?: FieldFilter;
+    actions: AutomationAction[];
+};
+/**
+ * Field values in `updateRecord` / `createRecord` are written as the field
+ * shows them: an option's name, a person's name, a linked record's name, a
+ * number, `true`. Text may name fields: `{Task} follow-up`. Dates also take
+ * `today`, `now`, `today+7`, `today-1`. `{record}` in a link field is the
+ * record that set the automation off. An empty string clears the field.
+ */
+export type AutomationValue = unknown;
+export type AutomationActionContext = {
+    automation: BaseAutomation;
+    table: BaseTable;
+    /** The record that set it off; null for a scheduled run with no condition. */
+    record: Row | null;
+    /** A field of the record as its cell shows it. */
+    text: (fieldName: string) => string;
+    options: Record<string, unknown>;
+};
+export type RegisteredAutomationAction = {
+    /** How the editor names it: "Post to Slack". */
+    label: string;
+    run: (ctx: AutomationActionContext) => unknown | Promise<unknown>;
+};
+/**
+ * Add an action automations can run: a webhook, an email, a message to chat.
+ * It runs in the page; keep secrets on your server and call it from here.
+ */
+export declare function registerAutomationAction(id: string, action: RegisteredAutomationAction): void;
+export declare function listAutomationActions(): Array<{
+    id: string;
+    label: string;
+}>;
+/** A table's fields as filled in (formulas, lookups, formats), by column id. */
+export declare function tableFields(t: BaseTable): Map<string, FieldColumn>;
+/** `{Field name}` tokens of a template, filled from a record. */
+export declare function fillTokens(t: BaseTable, record: Row | null, template: string): string;
+/** Whether a record matches a condition (no condition matches every record). */
+export declare function matches(t: BaseTable, condition: FieldFilter | undefined, record: Row): boolean;
+/** What a value written in an action becomes in a field of `t`. */
+export declare function fieldValueFrom(t: BaseTable, def: Def, spec: unknown, ctx: {
+    tables: BaseTable[];
+    from: BaseTable;
+    record: Row | null;
+    now: Date;
+}): unknown;
+export type AutomationStep = {
+    action: string;
+    detail: string;
+    error?: string;
+};
+export type AutomationRun = {
+    id: number;
+    automationId: string;
+    name: string;
+    table: string;
+    record: string | null;
+    at: number;
+    status: 'ok' | 'error' | 'stopped';
+    steps: AutomationStep[];
+};
+/** The longest chain of automations setting each other off. */
+export declare const MAX_DEPTH = 4;
+export type AutomationEvent = {
+    type: 'created';
+    table: string;
+    record: Row;
+    depth?: number;
+} | {
+    type: 'updated';
+    table: string;
+    record: Row;
+    before: Row;
+    fields: string[];
+    depth?: number;
+} | {
+    type: 'form';
+    table: string;
+    record: Row;
+    view?: string;
+} | {
+    type: 'button';
+    table: string;
+    record: Row;
+    field: string;
+};
+export type AutomationRunnerOptions = {
+    getTables: () => BaseTable[] | undefined;
+    /**
+     * Put changed tables in the page (and, through a table's source, in the
+     * database). `depth` is how deep in a chain of automations the change was
+     * made: changes it causes in other tables (through links) carry it on.
+     * `wrote` is the table it changed itself; it reports that change on its own.
+     */
+    apply: (tables: BaseTable[], depth?: number, wrote?: string) => void;
+    now?: () => Date;
+    /** The base's own object (its grids' `baseScope`), so its records' activity stays its own. */
+    scope?: object;
+};
+export declare function createAutomationRunner(options: AutomationRunnerOptions): {
+    handle: (e: AutomationEvent) => Promise<void>;
+    schedule: () => void;
+    runScheduled: (key: string) => Promise<void>;
+    /** Run one automation now for a record (or none), as its trigger would. */
+    /** Run one automation now for a record (or none), as its trigger would; a record that does not match its condition is reported, not run. */
+    runNow: (a: BaseAutomation, tableId: string, recordId: string | null) => Promise<void | undefined>;
+    readonly runs: AutomationRun[];
+    clearRuns: () => never[];
+    settled: () => Promise<void>;
+    stop: () => void | undefined;
+};
+export type AutomationRunner = ReturnType<typeof createAutomationRunner>;
+/** Which of a table's automations an event sets off, for the runner on one side. */
+export declare function automationsFor(t: BaseTable, e: AutomationEvent, side: 'browser' | 'server'): BaseAutomation[];
+/** What a webhook or an email reads of the record. */
+export declare function outbound(a: BaseAutomation, t: BaseTable, rec: Row | null, extra?: Partial<OutboundContext>): OutboundContext;
+/** An action the app registered, run on a record. */
+export declare function runAppAction(a: BaseAutomation, action: Extract<AutomationAction, {
+    type: 'run';
+}>, t: BaseTable, rec: Row | null): Promise<AutomationStep>;
+export declare function actionLabel(a: AutomationAction): string;
+/** "When a record matches: Status is Blocked", for the list of automations. */
+export declare function triggerText(t: BaseTable | undefined, a: BaseAutomation): string;
+export {};