zitejs 0.9.139 → 0.9.141

package/dist/esm/start/workflow.d.ts

@@ -0,0 +1,50 @@
+import type { ZiteTrigger, ZiteTriggerContext, ZiteTriggerSubscribe, ZiteTriggerUnsubscribe } from "../backend/index.js";
+import type { ZiteSchedule } from "../schedules/index.js";
+declare const WORKFLOW: unique symbol;
+type ProviderTriggerBase = Extract<ZiteTrigger, {
+    every?: never;
+    events?: never;
+}>;
+/**
+ * A provider trigger, registered with the provider by its `subscribe` when the
+ * app is published and taken down by its `unsubscribe` when it no longer is.
+ * Both run on the platform with only the trigger's own connection.
+ */
+export type StartProviderTrigger = ProviderTriggerBase & {
+    subscribe: ZiteTriggerSubscribe;
+    unsubscribe?: ZiteTriggerUnsubscribe;
+};
+export type StartTrigger = Exclude<ZiteTrigger, ProviderTriggerBase> | StartProviderTrigger;
+export type WorkflowConfig = {
+    /** What this workflow does, in a sentence. Shown in the editor. */
+    description?: string;
+} & ({
+    schedule: ZiteSchedule;
+    trigger?: never;
+} | {
+    trigger: StartTrigger;
+    schedule?: never;
+});
+/** What a workflow's handler gets. A trigger adds `trigger`, typed by the kind it declares. */
+export type WorkflowArgs<TConfig extends WorkflowConfig> = {
+    input: unknown;
+} & (TConfig extends {
+    trigger: infer T;
+} ? {
+    trigger: ZiteTriggerContext<T>;
+} : unknown);
+export type Workflow<TConfig extends WorkflowConfig = WorkflowConfig> = {
+    readonly [WORKFLOW]: true;
+    readonly config: TConfig;
+    readonly handler: (args: WorkflowArgs<TConfig>) => unknown;
+};
+/**
+ * Scheduled or triggered work, in a `*.server.ts` file:
+ * `export const nightly = createWorkflow({ schedule }).handler(async () => { ... })`.
+ * Only the platform runs it. It has no user and no URL, and reads data like a server function does.
+ */
+export declare function createWorkflow<const TConfig extends WorkflowConfig>(config: TConfig): {
+    handler: (fn: (args: WorkflowArgs<TConfig>) => unknown) => Workflow<TConfig>;
+};
+export declare const isWorkflow: (value: unknown) => value is Workflow;
+export {};

package/dist/esm/start/workflow.js

@@ -0,0 +1,13 @@
+// Shared across copies of zitejs in one bundle, like the access scope.
+const WORKFLOW = Symbol.for("zitejs:workflow");
+/**
+ * Scheduled or triggered work, in a `*.server.ts` file:
+ * `export const nightly = createWorkflow({ schedule }).handler(async () => { ... })`.
+ * Only the platform runs it. It has no user and no URL, and reads data like a server function does.
+ */
+export function createWorkflow(config) {
+    return {
+        handler: (fn) => ({ [WORKFLOW]: true, config, handler: fn }),
+    };
+}
+export const isWorkflow = (value) => typeof value === "object" && value !== null && value[WORKFLOW] === true;

package/dist/esm/start/workflow.test-d.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/start/workflow.test-d.js

@@ -0,0 +1,39 @@
+import { describe, expectTypeOf, it } from "vitest";
+import { createWorkflow } from "./workflow.js";
+describe("createWorkflow handler args", () => {
+    it("gives a schedule no trigger", () => {
+        createWorkflow({ schedule: { scheduleType: "oneTime", fireAt: "2026-10-10T03:00:00Z", timezone: "UTC" } }).handler((args) => {
+            expectTypeOf(args).toEqualTypeOf();
+        });
+    });
+    it("types the trigger by the kind it declares", () => {
+        createWorkflow({ trigger: { every: "5m" } }).handler(({ trigger }) => {
+            expectTypeOf(trigger).toEqualTypeOf();
+        });
+        createWorkflow({ trigger: { integration: "slack", events: ["message.channels"] } }).handler(({ trigger }) => {
+            expectTypeOf(trigger).toEqualTypeOf();
+        });
+        createWorkflow({
+            trigger: { integration: "asana", subscribe: async () => ({ externalId: "w1" }), unsubscribe: async () => { } },
+        }).handler(({ trigger }) => {
+            expectTypeOf(trigger).toEqualTypeOf();
+        });
+    });
+    it("registers a provider trigger with subscribe", () => {
+        // @ts-expect-error nothing would register it with the provider
+        createWorkflow({ trigger: { integration: "asana" } });
+        createWorkflow({
+            trigger: {
+                integration: "github",
+                subscribe: (input) => {
+                    expectTypeOf(input.notificationUrl).toEqualTypeOf();
+                    return { externalId: "1", secret: input.secret };
+                },
+            },
+        });
+    });
+    it("takes a schedule or a trigger, not both", () => {
+        // @ts-expect-error a workflow runs on one or the other
+        createWorkflow({ schedule: { scheduleType: "oneTime", fireAt: "x", timezone: "UTC" }, trigger: { every: "5m" } });
+    });
+});

package/dist/esm/start/workflowModules.d.ts

@@ -0,0 +1 @@
+export declare const workflowModules: Record<string, () => Promise<Record<string, unknown>>>;

package/dist/esm/start/workflowModules.js

@@ -0,0 +1,3 @@
+// Replaced at build by zite() with a lazy import of every app module that
+// mentions createWorkflow. Empty wherever the plugin didn't build the app.
+export const workflowModules = {};

package/dist/esm/start/workflowRun.d.ts

@@ -0,0 +1,80 @@
+import { type Workflow } from "./workflow.js";
+export type TriggerReport = {
+    handled: string[];
+    cursor?: string;
+};
+export type WorkflowRunResult = {
+    ok: true;
+    output: unknown;
+    trigger?: TriggerReport;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+    trigger?: TriggerReport;
+};
+/**
+ * Splits the platform's state out of the input. A poll or a provider delivery
+ * with a cursor gets `seen`, `handled` and `advance`. Handled ids are reported
+ * whether or not the run throws, so an item acted on is never acted on again;
+ * the staged cursor only on success. Only ids the incoming `seen` lacked are
+ * reported: billing reads an empty list as a run that found nothing new.
+ */
+export declare function triggerContext(workflow: Workflow, rawInput: unknown): {
+    input: unknown;
+    trigger?: undefined;
+    report?: undefined;
+} | {
+    input: {
+        [x: string]: unknown;
+    };
+    trigger: {
+        provider: string;
+        deliveryId?: string | undefined;
+        headers: Record<string, unknown>;
+    } | {
+        headers?: undefined;
+    } | {
+        headers: {};
+    };
+    report?: undefined;
+} | {
+    input: {
+        [x: string]: unknown;
+    };
+    trigger: {
+        provider: string;
+        deliveryId?: string | undefined;
+        headers: Record<string, unknown>;
+        cursor: string | null;
+        seen: (id: string) => boolean;
+        handled: (id: string) => void;
+        advance: (cursor: string) => void;
+    } | {
+        headers?: undefined;
+        cursor: string | null;
+        seen: (id: string) => boolean;
+        handled: (id: string) => void;
+        advance: (cursor: string) => void;
+    } | {
+        headers: {};
+        cursor: string | null;
+        seen: (id: string) => boolean;
+        handled: (id: string) => void;
+        advance: (cursor: string) => void;
+    };
+    report: (succeeded: boolean) => TriggerReport;
+};
+/** Runs the handler in a workflow access scope: no user, and data calls allowed. */
+export declare function runWorkflow(workflow: Workflow, rawInput: unknown): Promise<WorkflowRunResult>;
+export type LoadedWorkflow = {
+    id: string;
+    file: string;
+    workflow: Workflow;
+};
+/** Every exported workflow in the app, by export name. */
+export declare function loadWorkflows(modules?: Record<string, () => Promise<Record<string, unknown>>>): Promise<LoadedWorkflow[]>;
+/** The input as the run log keeps it: a trigger's `seen` list can hold thousands of ids. */
+export declare const loggedInput: (rawInput: unknown) => unknown;

package/dist/esm/start/workflowRun.js

@@ -0,0 +1,107 @@
+// Server-only: runs a workflow the host invoked. Takes the same platform input
+// as classic triggered endpoints (`__cron`, `__poll`, `__webhook`), so the
+// runner's schedules, polls and provider deliveries work unchanged.
+import { errorOf } from "./runLog.js";
+import { runInScope } from "./scope.js";
+import { isWorkflow } from "./workflow.js";
+import { workflowModules } from "./workflowModules.js";
+const asRecord = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : null;
+const idOf = (id) => {
+    if (typeof id !== "string" && typeof id !== "number")
+        throw new TypeError(`trigger ids must be strings, got ${typeof id}`);
+    const value = String(id);
+    if (value.length === 0 || value.length > 512)
+        throw new TypeError("trigger ids must be 1 to 512 characters");
+    return value;
+};
+/**
+ * Splits the platform's state out of the input. A poll or a provider delivery
+ * with a cursor gets `seen`, `handled` and `advance`. Handled ids are reported
+ * whether or not the run throws, so an item acted on is never acted on again;
+ * the staged cursor only on success. Only ids the incoming `seen` lacked are
+ * reported: billing reads an empty list as a run that found nothing new.
+ */
+export function triggerContext(workflow, rawInput) {
+    const raw = asRecord(rawInput);
+    const { __cron, __poll, __webhook, ...input } = raw ?? {};
+    const declared = workflow.config.trigger;
+    if (!declared)
+        return { input: raw ? input : rawInput };
+    const poll = asRecord(__poll);
+    const webhook = asRecord(__webhook);
+    const delivery = typeof webhook?.provider === "string" ? webhook : null;
+    // A run with no trigger state, such as a manual one, still gets a trigger: an empty one.
+    const info = delivery
+        ? {
+            headers: asRecord(delivery.headers) ?? {},
+            ...(typeof delivery.deliveryId === "string" ? { deliveryId: delivery.deliveryId } : {}),
+            provider: delivery.provider,
+        }
+        : declared.every
+            ? {}
+            : { headers: {} };
+    if (!poll && declared.events)
+        return { input, trigger: info };
+    const state = poll ?? delivery ?? {};
+    const known = new Set(Array.isArray(state.seen) ? state.seen.map(String) : []);
+    const handled = [];
+    let staged;
+    const trigger = {
+        cursor: typeof state.cursor === "string" ? state.cursor : null,
+        seen: (id) => known.has(String(id)),
+        handled: (id) => {
+            const value = idOf(id);
+            if (known.has(value))
+                return;
+            known.add(value);
+            handled.push(value);
+        },
+        advance: (cursor) => {
+            if (typeof cursor !== "string" || cursor.length > 4096) {
+                throw new TypeError("trigger.advance takes a string of at most 4096 characters");
+            }
+            staged = cursor;
+        },
+        ...info,
+    };
+    const report = (succeeded) => ({
+        handled: handled.slice(-2000),
+        ...(succeeded && staged !== undefined ? { cursor: staged } : {}),
+    });
+    return { input, trigger, report };
+}
+/** Runs the handler in a workflow access scope: no user, and data calls allowed. */
+export async function runWorkflow(workflow, rawInput) {
+    const { input, trigger, report } = triggerContext(workflow, rawInput);
+    const args = { input, ...(trigger ? { trigger } : {}) };
+    try {
+        const output = await runInScope({ kind: "workflow", user: null }, () => workflow.handler(args));
+        return { ok: true, output, ...(report ? { trigger: report(true) } : {}) };
+    }
+    catch (error) {
+        return { ok: false, error: errorOf(error), ...(report ? { trigger: report(false) } : {}) };
+    }
+}
+/** Every exported workflow in the app, by export name. */
+export async function loadWorkflows(modules = workflowModules) {
+    const found = [];
+    for (const [file, load] of Object.entries(modules)) {
+        for (const [id, value] of Object.entries(await load()))
+            if (isWorkflow(value))
+                found.push({ id, file, workflow: value });
+    }
+    return found;
+}
+/** The input as the run log keeps it: a trigger's `seen` list can hold thousands of ids. */
+export const loggedInput = (rawInput) => {
+    const raw = asRecord(rawInput);
+    if (!raw)
+        return rawInput;
+    const out = { ...raw };
+    for (const key of ["__poll", "__webhook"]) {
+        const state = asRecord(raw[key]);
+        if (state && Array.isArray(state.seen))
+            out[key] = { ...state, seen: `[${state.seen.length} ids]` };
+    }
+    return out;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zitejs",
-  "version": "0.9.139",
+  "version": "0.9.141",
   "description": "The Zite framework — build apps on Zite Database",
   "type": "module",
   "sideEffects": false,

package/dist/cjs/meta/index.d.ts

@@ -1,14 +0,0 @@
-export type ZiteProjectUser = {
-    uuid: string;
-    firstName: string | null;
-    lastName: string | null;
-    email: string;
-    profilePictureUrl: string | null;
-};
-export type MetaListUsersResult = {
-    users: ZiteProjectUser[];
-};
-export declare class ZiteMeta {
-    static listUsers(): Promise<MetaListUsersResult>;
-}
-export declare const Meta: typeof ZiteMeta;

package/dist/cjs/meta/index.js

@@ -1,12 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Meta = exports.ZiteMeta = void 0;
-const sdkCall_js_1 = require("../internal/sdkCall.js");
-const META_SDK_INTEGRATION_ID = '__meta__';
-class ZiteMeta {
-    static listUsers() {
-        return (0, sdkCall_js_1.getSdkCall)()(META_SDK_INTEGRATION_ID, 'ZiteMeta', 'listUsers', {});
-    }
-}
-exports.ZiteMeta = ZiteMeta;
-exports.Meta = ZiteMeta;

package/dist/cjs/notifications/index.d.ts

@@ -1,25 +0,0 @@
-export interface NotificationLink {
-    path?: string;
-    params?: Record<string, string>;
-}
-export type NotificationsCreateParams = {
-    recipients: string[];
-    title: string;
-    body?: string;
-    link?: NotificationLink;
-    path?: string;
-    params?: Record<string, string>;
-    payload?: Record<string, unknown>;
-    idempotencyKey?: string;
-};
-export type NotificationsCreateResult = {
-    created: number;
-} | {
-    created: 0;
-    preview: true;
-    wouldCreate: number;
-};
-export declare class ZiteNotifications {
-    static create(params: NotificationsCreateParams): Promise<NotificationsCreateResult>;
-}
-export declare const Notifications: typeof ZiteNotifications;

package/dist/cjs/notifications/index.js

@@ -1,12 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Notifications = exports.ZiteNotifications = void 0;
-const sdkCall_js_1 = require("../internal/sdkCall.js");
-const NOTIFICATIONS_SDK_INTEGRATION_ID = '__notifications__';
-class ZiteNotifications {
-    static create(params) {
-        return (0, sdkCall_js_1.getSdkCall)()(NOTIFICATIONS_SDK_INTEGRATION_ID, 'ZiteNotifications', 'create', params);
-    }
-}
-exports.ZiteNotifications = ZiteNotifications;
-exports.Notifications = ZiteNotifications;

package/dist/esm/meta/index.d.ts

@@ -1,14 +0,0 @@
-export type ZiteProjectUser = {
-    uuid: string;
-    firstName: string | null;
-    lastName: string | null;
-    email: string;
-    profilePictureUrl: string | null;
-};
-export type MetaListUsersResult = {
-    users: ZiteProjectUser[];
-};
-export declare class ZiteMeta {
-    static listUsers(): Promise<MetaListUsersResult>;
-}
-export declare const Meta: typeof ZiteMeta;

package/dist/esm/meta/index.js

@@ -1,8 +0,0 @@
-import { getSdkCall } from '../internal/sdkCall.js';
-const META_SDK_INTEGRATION_ID = '__meta__';
-export class ZiteMeta {
-    static listUsers() {
-        return getSdkCall()(META_SDK_INTEGRATION_ID, 'ZiteMeta', 'listUsers', {});
-    }
-}
-export const Meta = ZiteMeta;

package/dist/esm/notifications/index.d.ts

@@ -1,25 +0,0 @@
-export interface NotificationLink {
-    path?: string;
-    params?: Record<string, string>;
-}
-export type NotificationsCreateParams = {
-    recipients: string[];
-    title: string;
-    body?: string;
-    link?: NotificationLink;
-    path?: string;
-    params?: Record<string, string>;
-    payload?: Record<string, unknown>;
-    idempotencyKey?: string;
-};
-export type NotificationsCreateResult = {
-    created: number;
-} | {
-    created: 0;
-    preview: true;
-    wouldCreate: number;
-};
-export declare class ZiteNotifications {
-    static create(params: NotificationsCreateParams): Promise<NotificationsCreateResult>;
-}
-export declare const Notifications: typeof ZiteNotifications;

package/dist/esm/notifications/index.js

@@ -1,8 +0,0 @@
-import { getSdkCall } from '../internal/sdkCall.js';
-const NOTIFICATIONS_SDK_INTEGRATION_ID = '__notifications__';
-export class ZiteNotifications {
-    static create(params) {
-        return getSdkCall()(NOTIFICATIONS_SDK_INTEGRATION_ID, 'ZiteNotifications', 'create', params);
-    }
-}
-export const Notifications = ZiteNotifications;