zitejs 0.9.137 → 0.9.139

package/README.md

@@ -23,10 +23,15 @@ const result = await zite.sql({
   query: 'SELECT "id", "email" FROM "ziteUsers"',
 });
 
-// Define API endpoints
+// Define API endpoints. step.run saves each result as it completes, so a
+// failed run resumed from run history skips the steps that already ran.
 import { createEndpoint, ZiteError } from 'zitejs/api';
 export default createEndpoint({
-  execute: async ({ input }) => { ... },
+  execute: async ({ input, step }) => {
+    const order = await step.run('load-order', () => loadOrder(input.id));
+    await step.run('charge', () => charge(order));
+    return { charged: true };
+  },
 });
 
 // Authentication

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

@@ -23,6 +23,8 @@ export type ZiteTrigger = {
     paused?: boolean;
     every?: never;
     events?: never;
+    table?: never;
+    form?: never;
 } | {
     /**
      * The connection's name in `zite.config.json`, for a provider whose
@@ -37,6 +39,8 @@ export type ZiteTrigger = {
     label?: string;
     paused?: boolean;
     every?: never;
+    table?: never;
+    form?: never;
 } | {
     /** `<n>m` (1–59) or `<n>h` (1–23). What makes the trigger a poll. */
     every: string;
@@ -46,6 +50,74 @@ export type ZiteTrigger = {
     label?: string;
     paused?: boolean;
     events?: never;
+    table?: never;
+    form?: never;
+} | {
+    /**
+     * A table in the project's own database, as `zite.<table>` names it.
+     * Every write to it reaches the trigger, from apps, forms, imports, the
+     * database view and other automations; nothing is registered.
+     */
+    table: string;
+    on: ZiteDatabaseTriggerEvent[];
+    /** Narrows `"updated"` to updates that changed one of these fields. */
+    fields?: string[];
+    /** The sentence the editor shows, e.g. "When an order ships". */
+    label?: string;
+    paused?: boolean;
+    integration?: never;
+    every?: never;
+    events?: never;
+    form?: never;
+} | {
+    /**
+     * One of the project's own Fillout forms, by its name as the project
+     * lists it, or its id. Each finished live submission fires the
+     * endpoint; nothing is registered.
+     */
+    form: string;
+    on: "submitted"[];
+    /** The sentence the editor shows, e.g. "When someone fills in the intake form". */
+    label?: string;
+    paused?: boolean;
+    integration?: never;
+    every?: never;
+    events?: never;
+    table?: never;
+};
+/**
+ * What a form trigger's run gets as `input`: one submission. `answers` is
+ * keyed by question name; `submission` is the whole export, as the Fillout
+ * API returns it (`questions`, `calculations`, `urlParameters`, …).
+ */
+export type ZiteFormTriggerInput = {
+    event: "submitted";
+    form: string;
+    formId: string;
+    submissionId: string;
+    submittedAt: string | null;
+    answers: Record<string, unknown>;
+    submission: Record<string, unknown> & {
+        submissionId: string;
+    };
+};
+export type ZiteDatabaseTriggerEvent = "created" | "updated" | "deleted";
+/**
+ * What a database trigger's run gets as `input`: one changed record. Field
+ * keys are the SDK's, as `zite.<table>.findOne` returns them; cast `record`
+ * and `previous` to the table's generated `<Table>RecordType` from
+ * `zitejs/db` to type their fields.
+ */
+export type ZiteDatabaseTriggerInput<TRecord extends Record<string, unknown> = Record<string, unknown>> = {
+    event: ZiteDatabaseTriggerEvent;
+    table: string;
+    recordId: string;
+    /** Null if it was deleted before the run read it; on `"deleted"`, the record as it was. */
+    record: TRecord | null;
+    /** The record before an `"updated"`; null otherwise, and on a very large bulk write. */
+    previous: TRecord | null;
+    /** What an `"updated"` changed. */
+    changedFields: string[];
 };
 /**
  * What a provider trigger's `subscribe` export receives. Write it as
@@ -115,10 +187,20 @@ export type ZiteTriggerDeliveryRun = ZiteTriggerRun & ZiteTriggerDeliveryInfo;
 export type ZiteTriggerContext<TTrigger> = TTrigger extends {
     every: string;
 } ? ZiteTriggerRun : TTrigger extends {
+    table: string;
+} | {
+    form: string;
+} ? ZiteTriggerDeliveryInfo : TTrigger extends {
     events: string[];
 } ? ZiteTriggerDeliveryInfo : TTrigger extends {
     integration: string;
 } ? ZiteTriggerDeliveryRun : never;
+/** A database or form trigger's runs get the change or submission as `input`. */
+export type ZiteEndpointInput<TInput, TTrigger> = TTrigger extends {
+    table: string;
+} ? ZiteDatabaseTriggerInput : TTrigger extends {
+    form: string;
+} ? ZiteFormTriggerInput : TInput;
 export interface ZiteRequestContext {
     user: {
         id: string;
@@ -215,7 +297,7 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
      */
     validatesInput?: boolean;
     execute: (params: {
-        input: TInput;
+        input: ZiteEndpointInput<TInput, TTrigger>;
         /**
          * Durable steps. `step.run(name, fn)` runs `fn` once per logical run:
          * its result is saved before anything after it executes, and when a

package/dist/cjs/backend/index.test.js

@@ -207,6 +207,58 @@ const stepStub = {
                 return params.trigger;
             },
         });
+        (0, index_js_1.createEndpoint)({
+            trigger: { table: "orders", on: ["updated"], fields: ["status"] },
+            execute: async ({ input, trigger }) => {
+                // @ts-expect-error a database change has no cursor API
+                trigger?.advance("x");
+                const status = input.record?.status;
+                return { status, changed: input.changedFields, at: input.event };
+            },
+        });
+        (0, index_js_1.createEndpoint)({
+            // @ts-expect-error a database trigger names its table, not a connection
+            trigger: { table: "orders", on: ["created"], integration: "x" },
+            execute: async () => 1,
+        });
+        (0, index_js_1.createEndpoint)({
+            trigger: { form: "Intake form", on: ["submitted"] },
+            execute: async ({ input, trigger }) => {
+                // @ts-expect-error a form submission has no cursor API
+                trigger?.advance("x");
+                return { email: input.answers.Email, id: input.submissionId };
+            },
+        });
+        (0, index_js_1.createEndpoint)({
+            // @ts-expect-error a form trigger watches submissions only
+            trigger: { form: "Intake form", on: ["updated"] },
+            execute: async () => 1,
+        });
+        (0, index_js_1.createEndpoint)({
+            // @ts-expect-error only created, updated and deleted
+            trigger: { table: "orders", on: ["archived"] },
+            execute: async () => 1,
+        });
+    });
+    (0, vitest_1.it)("hands a database trigger its change without parsing it against the input schema", async () => {
+        const endpoint = (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.object({ orderId: zod_1.z.string() }),
+            trigger: { table: "orders", on: ["created"] },
+            execute: async ({ input }) => input.recordId,
+        });
+        await (0, vitest_1.expect)(endpoint.execute({
+            step: stepStub,
+            input: {
+                event: "created",
+                table: "orders",
+                recordId: "rec_1",
+                record: { id: "rec_1" },
+                previous: null,
+                changedFields: [],
+            },
+            context: { user: null },
+            trigger: { headers: {}, deliveryId: "db:e1:rec_1" },
+        })).resolves.toBe("rec_1");
     });
     (0, vitest_1.it)("types a trigger's registration exports and checks what subscribe returns", async () => {
         const subscribe = (async (input) => ({

package/dist/cjs/sync/lib.js

@@ -524,7 +524,7 @@ function generateDbTs(inputSchema) {
     lines.push('//       `not: null` means "is set". An empty `in: []` matches nothing; an', "//       empty `notIn: []` applies no filter.");
     lines.push("//     sort is currently IGNORED here — it is stripped before the request.", "//       (it does work on zite.auth.findAllUsers). Order in SQL instead.");
     lines.push("//     limit defaults to 500, max 2000; offset is a row count (a number)");
-    lines.push('//     a filter value of `undefined` is REJECTED (it would query unfiltered', '//       and match an arbitrary record). Check the value first.');
+    lines.push("//     a filter value of `undefined` is REJECTED (it would query unfiltered", "//       and match an arbitrary record). Check the value first.");
     lines.push("//   .findOne({ id?, filters?, fields? }) → T | undefined");
     lines.push("//   .create({ record }) → T");
     lines.push("//   .update({ id, record }) → { id: string, fields: Partial<T> }");
@@ -1232,13 +1232,13 @@ function generateBackendWrapperTs(envVarNames = []) {
         "// Auto-generated type-narrowing wrapper. Do not edit manually.",
         "// Re-exports createEndpoint with context.user typed to the app User.",
         "",
-        "import type { ZiteRequestContext as _ZiteRequestContext, ZiteScheduledContext, ZiteErrorCode, ZiteSchedule, ZiteStreamInterface, ZiteTrigger, ZiteTriggerContext, ZiteWebhook } from 'zitejs/backend/base';",
+        "import type { ZiteRequestContext as _ZiteRequestContext, ZiteScheduledContext, ZiteErrorCode, ZiteSchedule, ZiteStep, ZiteStreamInterface, ZiteTrigger, ZiteTriggerContext, ZiteEndpointInput, ZiteWebhook } from 'zitejs/backend/base';",
         "import type { User } from 'zitejs/auth';",
         "",
-        "export type { ZiteErrorCode, ZiteSchedule, ZiteScheduledContext, ZiteStreamInterface, ZiteTrigger, ZiteWebhook };",
+        "export type { ZiteErrorCode, ZiteSchedule, ZiteScheduledContext, ZiteStep, ZiteStreamInterface, ZiteTrigger, ZiteWebhook };",
         // A trigger's registration exports are typed against these, and they
         // only reach app code through this file.
-        "export type { ZiteTriggerContext, ZiteTriggerDeliveryInfo, ZiteTriggerDeliveryRun, ZiteTriggerRun, ZiteTriggerSubscribe, ZiteTriggerSubscribeInput, ZiteTriggerSubscribeResult, ZiteTriggerUnsubscribe, ZiteTriggerUnsubscribeInput } from 'zitejs/backend/base';",
+        "export type { ZiteDatabaseTriggerEvent, ZiteDatabaseTriggerInput, ZiteFormTriggerInput, ZiteTriggerContext, ZiteTriggerDeliveryInfo, ZiteTriggerDeliveryRun, ZiteTriggerRun, ZiteTriggerSubscribe, ZiteTriggerSubscribeInput, ZiteTriggerSubscribeResult, ZiteTriggerUnsubscribe, ZiteTriggerUnsubscribeInput } from 'zitejs/backend/base';",
         // The pre-monorepo SDK put this in scope for every endpoint, so migrated
         // code can name it. `createEndpoint` infers the same thing without it.
         "export type InferSchemaType<T> = T extends { _output: infer U } ? U : T;",
@@ -1326,11 +1326,13 @@ function generateBackendWrapperTs(envVarNames = []) {
         "  schedule?: TSchedule;",
         "  /** When set, an inbound webhook can also trigger this endpoint. Like `schedule`, it widens `context` — a webhook fire has no session. */",
         "  webhook?: TWebhook;",
-        "  /** When set, a connection's events (registered by this file's own `subscribe` export) or a poll (`every`) also fire this endpoint. Like `webhook`, it widens `context` — a trigger fire has no session. */",
+        "  /** When set, a connection's events (registered by this file's own `subscribe` export), a poll (`every`), a change to one of the project's tables (`table`) or a submission to one of its forms (`form`) also fire this endpoint. Like `webhook`, it widens `context` — a trigger fire has no session. */",
         "  trigger?: TTrigger;",
         "  execute: (",
         "    params: {",
-        "      input: TInput;",
+        "      input: ZiteEndpointInput<TInput, TTrigger>;",
+        "      /** Durable steps: step.run(name, fn) runs fn once per logical run — its result is saved before anything after it executes, and a resumed run replays completed steps from their saved results. Provided by the platform; never define a local stand-in. */",
+        "      step: ZiteStep;",
         "      context: TSchedule extends ZiteSchedule ? ZiteRequestContext | ZiteScheduledContext : TWebhook extends ZiteWebhook ? ZiteRequestContext | ZiteScheduledContext : TTrigger extends ZiteTrigger ? ZiteRequestContext | ZiteScheduledContext : ZiteRequestContext;",
         // Mirrors the base module: a trigger's run gets `trigger`.
         "    } & (TStream extends true ? { stream: ZiteStreamInterface } : {}) & (TTrigger extends ZiteTrigger ? { trigger?: ZiteTriggerContext<TTrigger> } : {}),",

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

@@ -23,6 +23,8 @@ export type ZiteTrigger = {
     paused?: boolean;
     every?: never;
     events?: never;
+    table?: never;
+    form?: never;
 } | {
     /**
      * The connection's name in `zite.config.json`, for a provider whose
@@ -37,6 +39,8 @@ export type ZiteTrigger = {
     label?: string;
     paused?: boolean;
     every?: never;
+    table?: never;
+    form?: never;
 } | {
     /** `<n>m` (1–59) or `<n>h` (1–23). What makes the trigger a poll. */
     every: string;
@@ -46,6 +50,74 @@ export type ZiteTrigger = {
     label?: string;
     paused?: boolean;
     events?: never;
+    table?: never;
+    form?: never;
+} | {
+    /**
+     * A table in the project's own database, as `zite.<table>` names it.
+     * Every write to it reaches the trigger, from apps, forms, imports, the
+     * database view and other automations; nothing is registered.
+     */
+    table: string;
+    on: ZiteDatabaseTriggerEvent[];
+    /** Narrows `"updated"` to updates that changed one of these fields. */
+    fields?: string[];
+    /** The sentence the editor shows, e.g. "When an order ships". */
+    label?: string;
+    paused?: boolean;
+    integration?: never;
+    every?: never;
+    events?: never;
+    form?: never;
+} | {
+    /**
+     * One of the project's own Fillout forms, by its name as the project
+     * lists it, or its id. Each finished live submission fires the
+     * endpoint; nothing is registered.
+     */
+    form: string;
+    on: "submitted"[];
+    /** The sentence the editor shows, e.g. "When someone fills in the intake form". */
+    label?: string;
+    paused?: boolean;
+    integration?: never;
+    every?: never;
+    events?: never;
+    table?: never;
+};
+/**
+ * What a form trigger's run gets as `input`: one submission. `answers` is
+ * keyed by question name; `submission` is the whole export, as the Fillout
+ * API returns it (`questions`, `calculations`, `urlParameters`, …).
+ */
+export type ZiteFormTriggerInput = {
+    event: "submitted";
+    form: string;
+    formId: string;
+    submissionId: string;
+    submittedAt: string | null;
+    answers: Record<string, unknown>;
+    submission: Record<string, unknown> & {
+        submissionId: string;
+    };
+};
+export type ZiteDatabaseTriggerEvent = "created" | "updated" | "deleted";
+/**
+ * What a database trigger's run gets as `input`: one changed record. Field
+ * keys are the SDK's, as `zite.<table>.findOne` returns them; cast `record`
+ * and `previous` to the table's generated `<Table>RecordType` from
+ * `zitejs/db` to type their fields.
+ */
+export type ZiteDatabaseTriggerInput<TRecord extends Record<string, unknown> = Record<string, unknown>> = {
+    event: ZiteDatabaseTriggerEvent;
+    table: string;
+    recordId: string;
+    /** Null if it was deleted before the run read it; on `"deleted"`, the record as it was. */
+    record: TRecord | null;
+    /** The record before an `"updated"`; null otherwise, and on a very large bulk write. */
+    previous: TRecord | null;
+    /** What an `"updated"` changed. */
+    changedFields: string[];
 };
 /**
  * What a provider trigger's `subscribe` export receives. Write it as
@@ -115,10 +187,20 @@ export type ZiteTriggerDeliveryRun = ZiteTriggerRun & ZiteTriggerDeliveryInfo;
 export type ZiteTriggerContext<TTrigger> = TTrigger extends {
     every: string;
 } ? ZiteTriggerRun : TTrigger extends {
+    table: string;
+} | {
+    form: string;
+} ? ZiteTriggerDeliveryInfo : TTrigger extends {
     events: string[];
 } ? ZiteTriggerDeliveryInfo : TTrigger extends {
     integration: string;
 } ? ZiteTriggerDeliveryRun : never;
+/** A database or form trigger's runs get the change or submission as `input`. */
+export type ZiteEndpointInput<TInput, TTrigger> = TTrigger extends {
+    table: string;
+} ? ZiteDatabaseTriggerInput : TTrigger extends {
+    form: string;
+} ? ZiteFormTriggerInput : TInput;
 export interface ZiteRequestContext {
     user: {
         id: string;
@@ -215,7 +297,7 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
      */
     validatesInput?: boolean;
     execute: (params: {
-        input: TInput;
+        input: ZiteEndpointInput<TInput, TTrigger>;
         /**
          * Durable steps. `step.run(name, fn)` runs `fn` once per logical run:
          * its result is saved before anything after it executes, and when a

package/dist/esm/backend/index.test.js

@@ -205,6 +205,58 @@ describe("platform-triggered runs", () => {
                 return params.trigger;
             },
         });
+        createEndpoint({
+            trigger: { table: "orders", on: ["updated"], fields: ["status"] },
+            execute: async ({ input, trigger }) => {
+                // @ts-expect-error a database change has no cursor API
+                trigger?.advance("x");
+                const status = input.record?.status;
+                return { status, changed: input.changedFields, at: input.event };
+            },
+        });
+        createEndpoint({
+            // @ts-expect-error a database trigger names its table, not a connection
+            trigger: { table: "orders", on: ["created"], integration: "x" },
+            execute: async () => 1,
+        });
+        createEndpoint({
+            trigger: { form: "Intake form", on: ["submitted"] },
+            execute: async ({ input, trigger }) => {
+                // @ts-expect-error a form submission has no cursor API
+                trigger?.advance("x");
+                return { email: input.answers.Email, id: input.submissionId };
+            },
+        });
+        createEndpoint({
+            // @ts-expect-error a form trigger watches submissions only
+            trigger: { form: "Intake form", on: ["updated"] },
+            execute: async () => 1,
+        });
+        createEndpoint({
+            // @ts-expect-error only created, updated and deleted
+            trigger: { table: "orders", on: ["archived"] },
+            execute: async () => 1,
+        });
+    });
+    it("hands a database trigger its change without parsing it against the input schema", async () => {
+        const endpoint = createEndpoint({
+            inputSchema: z.object({ orderId: z.string() }),
+            trigger: { table: "orders", on: ["created"] },
+            execute: async ({ input }) => input.recordId,
+        });
+        await expect(endpoint.execute({
+            step: stepStub,
+            input: {
+                event: "created",
+                table: "orders",
+                recordId: "rec_1",
+                record: { id: "rec_1" },
+                previous: null,
+                changedFields: [],
+            },
+            context: { user: null },
+            trigger: { headers: {}, deliveryId: "db:e1:rec_1" },
+        })).resolves.toBe("rec_1");
     });
     it("types a trigger's registration exports and checks what subscribe returns", async () => {
         const subscribe = (async (input) => ({

package/dist/esm/sync/lib.js

@@ -509,7 +509,7 @@ export function generateDbTs(inputSchema) {
     lines.push('//       `not: null` means "is set". An empty `in: []` matches nothing; an', "//       empty `notIn: []` applies no filter.");
     lines.push("//     sort is currently IGNORED here — it is stripped before the request.", "//       (it does work on zite.auth.findAllUsers). Order in SQL instead.");
     lines.push("//     limit defaults to 500, max 2000; offset is a row count (a number)");
-    lines.push('//     a filter value of `undefined` is REJECTED (it would query unfiltered', '//       and match an arbitrary record). Check the value first.');
+    lines.push("//     a filter value of `undefined` is REJECTED (it would query unfiltered", "//       and match an arbitrary record). Check the value first.");
     lines.push("//   .findOne({ id?, filters?, fields? }) → T | undefined");
     lines.push("//   .create({ record }) → T");
     lines.push("//   .update({ id, record }) → { id: string, fields: Partial<T> }");
@@ -1217,13 +1217,13 @@ export function generateBackendWrapperTs(envVarNames = []) {
         "// Auto-generated type-narrowing wrapper. Do not edit manually.",
         "// Re-exports createEndpoint with context.user typed to the app User.",
         "",
-        "import type { ZiteRequestContext as _ZiteRequestContext, ZiteScheduledContext, ZiteErrorCode, ZiteSchedule, ZiteStreamInterface, ZiteTrigger, ZiteTriggerContext, ZiteWebhook } from 'zitejs/backend/base';",
+        "import type { ZiteRequestContext as _ZiteRequestContext, ZiteScheduledContext, ZiteErrorCode, ZiteSchedule, ZiteStep, ZiteStreamInterface, ZiteTrigger, ZiteTriggerContext, ZiteEndpointInput, ZiteWebhook } from 'zitejs/backend/base';",
         "import type { User } from 'zitejs/auth';",
         "",
-        "export type { ZiteErrorCode, ZiteSchedule, ZiteScheduledContext, ZiteStreamInterface, ZiteTrigger, ZiteWebhook };",
+        "export type { ZiteErrorCode, ZiteSchedule, ZiteScheduledContext, ZiteStep, ZiteStreamInterface, ZiteTrigger, ZiteWebhook };",
         // A trigger's registration exports are typed against these, and they
         // only reach app code through this file.
-        "export type { ZiteTriggerContext, ZiteTriggerDeliveryInfo, ZiteTriggerDeliveryRun, ZiteTriggerRun, ZiteTriggerSubscribe, ZiteTriggerSubscribeInput, ZiteTriggerSubscribeResult, ZiteTriggerUnsubscribe, ZiteTriggerUnsubscribeInput } from 'zitejs/backend/base';",
+        "export type { ZiteDatabaseTriggerEvent, ZiteDatabaseTriggerInput, ZiteFormTriggerInput, ZiteTriggerContext, ZiteTriggerDeliveryInfo, ZiteTriggerDeliveryRun, ZiteTriggerRun, ZiteTriggerSubscribe, ZiteTriggerSubscribeInput, ZiteTriggerSubscribeResult, ZiteTriggerUnsubscribe, ZiteTriggerUnsubscribeInput } from 'zitejs/backend/base';",
         // The pre-monorepo SDK put this in scope for every endpoint, so migrated
         // code can name it. `createEndpoint` infers the same thing without it.
         "export type InferSchemaType<T> = T extends { _output: infer U } ? U : T;",
@@ -1311,11 +1311,13 @@ export function generateBackendWrapperTs(envVarNames = []) {
         "  schedule?: TSchedule;",
         "  /** When set, an inbound webhook can also trigger this endpoint. Like `schedule`, it widens `context` — a webhook fire has no session. */",
         "  webhook?: TWebhook;",
-        "  /** When set, a connection's events (registered by this file's own `subscribe` export) or a poll (`every`) also fire this endpoint. Like `webhook`, it widens `context` — a trigger fire has no session. */",
+        "  /** When set, a connection's events (registered by this file's own `subscribe` export), a poll (`every`), a change to one of the project's tables (`table`) or a submission to one of its forms (`form`) also fire this endpoint. Like `webhook`, it widens `context` — a trigger fire has no session. */",
         "  trigger?: TTrigger;",
         "  execute: (",
         "    params: {",
-        "      input: TInput;",
+        "      input: ZiteEndpointInput<TInput, TTrigger>;",
+        "      /** Durable steps: step.run(name, fn) runs fn once per logical run — its result is saved before anything after it executes, and a resumed run replays completed steps from their saved results. Provided by the platform; never define a local stand-in. */",
+        "      step: ZiteStep;",
         "      context: TSchedule extends ZiteSchedule ? ZiteRequestContext | ZiteScheduledContext : TWebhook extends ZiteWebhook ? ZiteRequestContext | ZiteScheduledContext : TTrigger extends ZiteTrigger ? ZiteRequestContext | ZiteScheduledContext : ZiteRequestContext;",
         // Mirrors the base module: a trigger's run gets `trigger`.
         "    } & (TStream extends true ? { stream: ZiteStreamInterface } : {}) & (TTrigger extends ZiteTrigger ? { trigger?: ZiteTriggerContext<TTrigger> } : {}),",

package/package.json

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