zitejs 0.9.125 → 0.9.127

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

@@ -13,17 +13,100 @@ export type ZiteWebhook = {
 export type ZiteTrigger = {
     /**
      * The connection's name in `zite.config.json`. Registered with the
-     * provider by `src/triggers/<endpointId>/subscribe.ts` and taken down
-     * by `unsubscribe.ts`, which the platform runs at publish and teardown.
+     * provider by the endpoint file's own `subscribe` export and taken down
+     * by its `unsubscribe` export, which the platform runs at publish and
+     * teardown.
      */
     integration: string;
+    /** The sentence the editor shows for what fires this endpoint, e.g. "When a task is completed in Asana". */
+    label?: string;
     paused?: boolean;
+    every?: never;
 } | {
-    provider: "poll";
-    /** `<n>m` (1–59) or `<n>h` (1–23) */
+    /** `<n>m` (1–59) or `<n>h` (1–23). What makes the trigger a poll. */
     every: string;
+    /** The connection the poll checks, if any, so the editor can name it. */
+    integration?: string;
+    /** The sentence the editor shows for this poll, e.g. "Every 10 minutes, new Stripe charges". */
+    label?: string;
     paused?: boolean;
 };
+/**
+ * What a provider trigger's `subscribe` export receives. Write it as
+ * `export const subscribe = (async input => { ... }) satisfies ZiteTriggerSubscribe`
+ * so the input is typed and a wrong return shape is a typecheck error.
+ */
+export type ZiteTriggerSubscribeInput = {
+    /** Where the provider must deliver, token included. */
+    notificationUrl: string;
+    /** The connection's name, as the trigger names it. */
+    integration: string;
+    endpointId: string;
+    /** A fresh 64-char hex secret, for providers that let the caller choose the signing secret. */
+    secret: string;
+    /** Set on a re-subscribe, including a renewal. */
+    previous: {
+        externalId: string;
+        state: Record<string, unknown>;
+    } | null;
+};
+export type ZiteTriggerSubscribeResult = {
+    /** The provider's id for the registration; what `unsubscribe` receives. */
+    externalId: string;
+    /** The signing secret, if the provider issued one or accepted `input.secret`. */
+    secret?: string;
+    /** Anything `unsubscribe` needs later; handed back to it and to the next `subscribe`. */
+    state?: Record<string, unknown>;
+    /** The provider's starting change marker, for notifications that only say something changed. */
+    cursor?: string;
+    /** ISO time the provider says the registration lapses, read from its response. */
+    expiresAt?: string;
+};
+export type ZiteTriggerUnsubscribeInput = {
+    externalId: string;
+    state: Record<string, unknown>;
+    integration: string;
+    endpointId: string;
+};
+export type ZiteTriggerSubscribe = (input: ZiteTriggerSubscribeInput) => Promise<ZiteTriggerSubscribeResult> | ZiteTriggerSubscribeResult;
+export type ZiteTriggerUnsubscribe = (input: ZiteTriggerUnsubscribeInput) => Promise<void> | void;
+/**
+ * What a poll-triggered run receives as `input.__poll`. Only on a fire from
+ * the poll's schedule; a request call to the same endpoint carries none.
+ */
+export type ZitePollInput = {
+    /** What the previous successful run returned as `cursor`; null on the first run. */
+    cursor: string | null;
+    /** Ids earlier runs returned as `handled`, newest last. Skip these. */
+    seen: string[];
+};
+/**
+ * What a provider trigger's delivery carries as `input.__webhook`, beside the
+ * provider's own body. `cursor` and `seen` work as they do for a poll: for a
+ * provider whose notification only says that something changed, `subscribe`
+ * returns a starting `cursor` and each delivery returns the next one. A
+ * trigger that keeps a cursor gets one delivery at a time.
+ */
+export type ZiteTriggerDelivery = {
+    headers: Record<string, string>;
+    /** The provider's id for this delivery; redeliveries share it. */
+    deliveryId?: string;
+    provider?: string;
+    /** What `subscribe` or the previous successful delivery returned as `cursor`. */
+    cursor: string | null;
+    /** Ids earlier deliveries returned as `handled`, newest last. Skip these. */
+    seen: string[];
+};
+/**
+ * What a poll-triggered run, or a provider trigger's delivery, returns for
+ * the platform to keep: its new `cursor`, and the id of every item it acted
+ * on, so the next run's `seen` includes them even if the cursor hands them
+ * back.
+ */
+export type ZitePollResult = {
+    cursor?: string;
+    handled?: string[];
+};
 export interface ZiteRequestContext {
     user: {
         id: string;
@@ -116,7 +199,15 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
      */
     validatesInput?: boolean;
     execute: (params: {
-        input: TInput;
+        input: TTrigger extends {
+            every: string;
+        } ? TInput & {
+            __poll?: ZitePollInput;
+        } : TTrigger extends {
+            integration: string;
+        } ? TInput & {
+            __webhook?: ZiteTriggerDelivery;
+        } : TInput;
         context: TSchedule extends ZiteSchedule ? ZiteRequestContext | ZiteScheduledContext : TWebhook extends ZiteWebhook ? ZiteRequestContext | ZiteScheduledContext : TTrigger extends ZiteTrigger ? ZiteRequestContext | ZiteScheduledContext : ZiteRequestContext;
     } & (TStream extends true ? {
         stream: ZiteStreamInterface;

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

@@ -133,6 +133,74 @@ const requestContext = { user: { id: "u1", email: "a@b.c" } };
         });
         await (0, vitest_1.expect)(endpoint.execute({ input: undefined, context: requestContext })).rejects.toMatchObject({ code: "BAD_REQUEST" });
     });
+    (0, vitest_1.it)("hands a poll its cursor and seen ids, typed", async () => {
+        const endpoint = (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.object({}),
+            trigger: { every: "5m", integration: "stripe" },
+            execute: async ({ input }) => {
+                const seen = new Set(input.__poll?.seen);
+                const items = ["a", "b"].filter((id) => !seen.has(id));
+                return { cursor: input.__poll?.cursor ?? "start", handled: items };
+            },
+        });
+        await (0, vitest_1.expect)(endpoint.execute({
+            input: { __poll: { cursor: "c1", seen: ["a"] } },
+            context: { user: null },
+        })).resolves.toEqual({ cursor: "c1", handled: ["b"] });
+    });
+    (0, vitest_1.it)("gives __poll only to poll triggers", () => {
+        (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.object({ action: zod_1.z.string() }),
+            trigger: { integration: "github" },
+            execute: async ({ input }) => {
+                // @ts-expect-error a provider trigger's input has no __poll
+                return input.__poll;
+            },
+        });
+    });
+    (0, vitest_1.it)("types a trigger's registration exports and checks what subscribe returns", async () => {
+        const subscribe = (async (input) => ({
+            externalId: `hook-for-${input.endpointId}`,
+            secret: input.secret,
+            state: { repo: "acme/api" },
+        }));
+        const unsubscribe = (async (input) => {
+            (0, vitest_1.expect)(input.state.repo).toBe("acme/api");
+        });
+        // @ts-expect-error subscribe has to return the provider's id
+        void (async () => ({ secret: "s" }));
+        const registered = await subscribe({
+            notificationUrl: "https://x",
+            integration: "github",
+            endpointId: "onPush",
+            secret: "abc",
+            previous: null,
+        });
+        (0, vitest_1.expect)(registered.externalId).toBe("hook-for-onPush");
+        await unsubscribe({
+            externalId: registered.externalId,
+            state: registered.state ?? {},
+            integration: "github",
+            endpointId: "onPush",
+        });
+    });
+    (0, vitest_1.it)("hands a provider trigger's delivery its cursor and seen ids, typed", async () => {
+        const endpoint = (0, index_js_1.createEndpoint)({
+            inputSchema: zod_1.z.object({}),
+            trigger: { integration: "googleCalendar" },
+            execute: async ({ input }) => {
+                const seen = new Set(input.__webhook?.seen);
+                const changed = ["e1", "e2"].filter((id) => !seen.has(id));
+                return { cursor: `${input.__webhook?.cursor}+1`, handled: changed };
+            },
+        });
+        await (0, vitest_1.expect)(endpoint.execute({
+            input: {
+                __webhook: { headers: {}, cursor: "sync1", seen: ["e1"] },
+            },
+            context: { user: null },
+        })).resolves.toEqual({ cursor: "sync1+1", handled: ["e2"] });
+    });
     (0, vitest_1.it)("does not validate a webhook fire", async () => {
         const endpoint = (0, index_js_1.createEndpoint)({
             inputSchema: zod_1.z.object({ token: zod_1.z.string().min(10) }),

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

@@ -2,7 +2,7 @@
  * `npx zitejs bundle` — Bundle endpoint files for cloudflare-lambda deployment.
  *
  * Replaces the legacy `scripts/bundle-endpoints.js` from zitejs-starter.
- * Reads an app's src/api/*.ts endpoints (an automation's single src/workflow.ts), resolves SDK imports via .zite/backend.ts
+ * Reads an app's src/api/*.ts endpoints (an automation's single src/index.ts), resolves SDK imports via .zite/backend.ts
  * (monorepo) or src/__zite__/integrations.ts (legacy), and outputs bundled ESM
  * code suitable for the cloudflare-lambda worker runtime.
  *

package/dist/cjs/bundle/index.js

@@ -40,7 +40,7 @@ exports.runBundle = runBundle;
  * `npx zitejs bundle` — Bundle endpoint files for cloudflare-lambda deployment.
  *
  * Replaces the legacy `scripts/bundle-endpoints.js` from zitejs-starter.
- * Reads an app's src/api/*.ts endpoints (an automation's single src/workflow.ts), resolves SDK imports via .zite/backend.ts
+ * Reads an app's src/api/*.ts endpoints (an automation's single src/index.ts), resolves SDK imports via .zite/backend.ts
  * (monorepo) or src/__zite__/integrations.ts (legacy), and outputs bundled ESM
  * code suitable for the cloudflare-lambda worker runtime.
  *
@@ -420,7 +420,7 @@ async function bundleEndpointsImpl(baseDir, root, endpointNames) {
     for (const name of endpointNames) {
         if (root === 'automations' && name !== sourceRoots_js_1.AUTOMATION_ENDPOINT_NAME) {
             endpointErrors[name] =
-                `An automation is one workflow, src/workflow.ts, bundled as "${sourceRoots_js_1.AUTOMATION_ENDPOINT_NAME}"; there is no endpoint "${name}"`;
+                `An automation is one workflow, src/index.ts, bundled as "${sourceRoots_js_1.AUTOMATION_ENDPOINT_NAME}"; there is no endpoint "${name}"`;
             continue;
         }
         const entryFile = (0, sourceRoots_js_1.endpointEntryFile)(root, name);
@@ -592,6 +592,10 @@ ${bodySection}
             },
             minify: false,
             logLevel: 'silent',
+            // A script that imports an endpoint file's named exports (a trigger's
+            // subscribe/unsubscribe) must not carry the endpoint along with them:
+            // unused, its `createEndpoint(...)` and everything `execute` imports go.
+            pure: ['createEndpoint'],
             plugins: [plugin],
         });
         if (result.errors.length > 0) {

package/dist/cjs/cli.js

@@ -75,7 +75,7 @@ async function main() {
             console.error('  dev       Run sync then watch for changes (like npx convex dev)');
             console.error('  generate  Regenerate every app and automation .zite/ (monorepo)');
             console.error('  check   Run tsc --noEmit (and vite build where there is one) for every app and automation');
-            console.error('  bundle  Bundle endpoints (src/api/*.ts, or an automation\'s src/workflow.ts) for cloudflare-lambda');
+            console.error('  bundle  Bundle endpoints (src/api/*.ts, or an automation\'s src/index.ts) for cloudflare-lambda');
             process.exit(1);
     }
 }

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

@@ -0,0 +1,14 @@
+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

@@ -0,0 +1,12 @@
+"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

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,12 @@
+"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/cjs/sourceRoots.d.ts

@@ -18,12 +18,12 @@ export declare function listSourceDirs(cwd?: string): SourceDir[];
 /** The source dir with this bare name, under whichever root holds it. */
 export declare function findSourceDir(name: string, cwd?: string): SourceDir | undefined;
 /**
- * An automation is one workflow: its single endpoint is `src/workflow.ts` and
+ * An automation is one workflow: its single endpoint is `src/index.ts` and
  * its name is fixed, so nothing about an automation is keyed on a file name
  * the way an app's `src/api/<name>.ts` endpoints are.
  */
-export declare const AUTOMATION_ENDPOINT_NAME = "workflow";
-export declare const AUTOMATION_WORKFLOW_FILE = "src/workflow.ts";
+export declare const AUTOMATION_ENDPOINT_NAME = "index";
+export declare const AUTOMATION_ENTRY_FILE = "src/index.ts";
 /** The root a source dir sits under, read from its parent directory. */
 export declare function sourceRootOf(sourceDirPath: string): SourceRoot | undefined;
 /** An endpoint's entry file, relative to the source dir. */

package/dist/cjs/sourceRoots.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AUTOMATION_WORKFLOW_FILE = exports.AUTOMATION_ENDPOINT_NAME = exports.SOURCE_ROOTS = void 0;
+exports.AUTOMATION_ENTRY_FILE = exports.AUTOMATION_ENDPOINT_NAME = exports.SOURCE_ROOTS = void 0;
 exports.listSourceDirs = listSourceDirs;
 exports.findSourceDir = findSourceDir;
 exports.sourceRootOf = sourceRootOf;
@@ -35,12 +35,12 @@ function findSourceDir(name, cwd = ".") {
     return listSourceDirs(cwd).find((d) => d.dir === name);
 }
 /**
- * An automation is one workflow: its single endpoint is `src/workflow.ts` and
+ * An automation is one workflow: its single endpoint is `src/index.ts` and
  * its name is fixed, so nothing about an automation is keyed on a file name
  * the way an app's `src/api/<name>.ts` endpoints are.
  */
-exports.AUTOMATION_ENDPOINT_NAME = "workflow";
-exports.AUTOMATION_WORKFLOW_FILE = "src/workflow.ts";
+exports.AUTOMATION_ENDPOINT_NAME = "index";
+exports.AUTOMATION_ENTRY_FILE = "src/index.ts";
 /** The root a source dir sits under, read from its parent directory. */
 function sourceRootOf(sourceDirPath) {
     const parent = (0, path_1.basename)((0, path_1.dirname)((0, path_1.resolve)(sourceDirPath)));
@@ -51,13 +51,13 @@ function sourceRootOf(sourceDirPath) {
 /** An endpoint's entry file, relative to the source dir. */
 function endpointEntryFile(root, name) {
     return root === "automations"
-        ? exports.AUTOMATION_WORKFLOW_FILE
+        ? exports.AUTOMATION_ENTRY_FILE
         : (0, path_1.join)("src", "api", `${name}.ts`);
 }
 /** Every endpoint name a source dir has on disk. */
 function listEndpointNames(root, sourceDirPath) {
     if (root === "automations") {
-        return (0, fs_1.existsSync)((0, path_1.join)(sourceDirPath, exports.AUTOMATION_WORKFLOW_FILE))
+        return (0, fs_1.existsSync)((0, path_1.join)(sourceDirPath, exports.AUTOMATION_ENTRY_FILE))
             ? [exports.AUTOMATION_ENDPOINT_NAME]
             : [];
     }

package/dist/cjs/sourceRoots.test.js

@@ -11,9 +11,9 @@ const sourceRoots_js_1 = require("./sourceRoots.js");
         (0, vitest_1.expect)((0, sourceRoots_js_1.sourceRootOf)("/repo/automations/digest")).toBe("automations");
         (0, vitest_1.expect)((0, sourceRoots_js_1.sourceRootOf)("/repo/packages/ui")).toBeUndefined();
     });
-    (0, vitest_1.it)("an app's endpoints are src/api/<name>.ts; an automation's one endpoint is src/workflow.ts", () => {
+    (0, vitest_1.it)("an app's endpoints are src/api/<name>.ts; an automation's one endpoint is src/index.ts", () => {
         (0, vitest_1.expect)((0, sourceRoots_js_1.endpointEntryFile)("apps", "listItems")).toBe("src/api/listItems.ts");
-        (0, vitest_1.expect)((0, sourceRoots_js_1.endpointEntryFile)("automations", "workflow")).toBe("src/workflow.ts");
+        (0, vitest_1.expect)((0, sourceRoots_js_1.endpointEntryFile)("automations", "index")).toBe("src/index.ts");
     });
     (0, vitest_1.it)("lists what is on disk under each layout", () => {
         const repo = (0, fs_1.mkdtempSync)((0, path_1.join)((0, os_1.tmpdir)(), "zitejs-roots-"));
@@ -22,9 +22,9 @@ const sourceRoots_js_1 = require("./sourceRoots.js");
         (0, fs_1.writeFileSync)((0, path_1.join)(repo, "apps/crm/src/api/apiTypes.d.ts"), "");
         (0, fs_1.mkdirSync)((0, path_1.join)(repo, "automations/digest/src"), { recursive: true });
         (0, fs_1.mkdirSync)((0, path_1.join)(repo, "automations/empty/src"), { recursive: true });
-        (0, fs_1.writeFileSync)((0, path_1.join)(repo, "automations/digest/src/workflow.ts"), "");
+        (0, fs_1.writeFileSync)((0, path_1.join)(repo, "automations/digest/src/index.ts"), "");
         (0, vitest_1.expect)((0, sourceRoots_js_1.listEndpointNames)("apps", (0, path_1.join)(repo, "apps/crm"))).toEqual(["listItems"]);
-        (0, vitest_1.expect)((0, sourceRoots_js_1.listEndpointNames)("automations", (0, path_1.join)(repo, "automations/digest"))).toEqual(["workflow"]);
+        (0, vitest_1.expect)((0, sourceRoots_js_1.listEndpointNames)("automations", (0, path_1.join)(repo, "automations/digest"))).toEqual(["index"]);
         (0, vitest_1.expect)((0, sourceRoots_js_1.listEndpointNames)("automations", (0, path_1.join)(repo, "automations/empty"))).toEqual([]);
     });
 });

package/dist/cjs/sync/lib.js

@@ -1426,7 +1426,7 @@ function generateIntegrationsIndex(entries, opts) {
         "// Auto-generated by zitejs generate from zite.config.json. Do not edit manually.",
         "// zitejs/integrations — an integration's credentials by its zite.config.json entry name.",
         "//",
-        "// Usage in endpoints (src/api/*.ts) and automations (src/workflow.ts):",
+        "// Usage in endpoints (src/api/*.ts) and automations (src/index.ts):",
         "//   import { integrations } from 'zitejs/integrations';",
         "//",
         "//   const crm = await integrations.get('<entry name>');",

package/dist/cjs/sync/lib.test.js

@@ -465,7 +465,7 @@ const duplicateIdentifierErrorsIn = (source) => {
       "// Auto-generated by zitejs generate from zite.config.json. Do not edit manually.
       // zitejs/integrations — an integration's credentials by its zite.config.json entry name.
       //
-      // Usage in endpoints (src/api/*.ts) and automations (src/workflow.ts):
+      // Usage in endpoints (src/api/*.ts) and automations (src/index.ts):
       //   import { integrations } from 'zitejs/integrations';
       //
       //   const crm = await integrations.get('<entry name>');

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

@@ -13,17 +13,100 @@ export type ZiteWebhook = {
 export type ZiteTrigger = {
     /**
      * The connection's name in `zite.config.json`. Registered with the
-     * provider by `src/triggers/<endpointId>/subscribe.ts` and taken down
-     * by `unsubscribe.ts`, which the platform runs at publish and teardown.
+     * provider by the endpoint file's own `subscribe` export and taken down
+     * by its `unsubscribe` export, which the platform runs at publish and
+     * teardown.
      */
     integration: string;
+    /** The sentence the editor shows for what fires this endpoint, e.g. "When a task is completed in Asana". */
+    label?: string;
     paused?: boolean;
+    every?: never;
 } | {
-    provider: "poll";
-    /** `<n>m` (1–59) or `<n>h` (1–23) */
+    /** `<n>m` (1–59) or `<n>h` (1–23). What makes the trigger a poll. */
     every: string;
+    /** The connection the poll checks, if any, so the editor can name it. */
+    integration?: string;
+    /** The sentence the editor shows for this poll, e.g. "Every 10 minutes, new Stripe charges". */
+    label?: string;
     paused?: boolean;
 };
+/**
+ * What a provider trigger's `subscribe` export receives. Write it as
+ * `export const subscribe = (async input => { ... }) satisfies ZiteTriggerSubscribe`
+ * so the input is typed and a wrong return shape is a typecheck error.
+ */
+export type ZiteTriggerSubscribeInput = {
+    /** Where the provider must deliver, token included. */
+    notificationUrl: string;
+    /** The connection's name, as the trigger names it. */
+    integration: string;
+    endpointId: string;
+    /** A fresh 64-char hex secret, for providers that let the caller choose the signing secret. */
+    secret: string;
+    /** Set on a re-subscribe, including a renewal. */
+    previous: {
+        externalId: string;
+        state: Record<string, unknown>;
+    } | null;
+};
+export type ZiteTriggerSubscribeResult = {
+    /** The provider's id for the registration; what `unsubscribe` receives. */
+    externalId: string;
+    /** The signing secret, if the provider issued one or accepted `input.secret`. */
+    secret?: string;
+    /** Anything `unsubscribe` needs later; handed back to it and to the next `subscribe`. */
+    state?: Record<string, unknown>;
+    /** The provider's starting change marker, for notifications that only say something changed. */
+    cursor?: string;
+    /** ISO time the provider says the registration lapses, read from its response. */
+    expiresAt?: string;
+};
+export type ZiteTriggerUnsubscribeInput = {
+    externalId: string;
+    state: Record<string, unknown>;
+    integration: string;
+    endpointId: string;
+};
+export type ZiteTriggerSubscribe = (input: ZiteTriggerSubscribeInput) => Promise<ZiteTriggerSubscribeResult> | ZiteTriggerSubscribeResult;
+export type ZiteTriggerUnsubscribe = (input: ZiteTriggerUnsubscribeInput) => Promise<void> | void;
+/**
+ * What a poll-triggered run receives as `input.__poll`. Only on a fire from
+ * the poll's schedule; a request call to the same endpoint carries none.
+ */
+export type ZitePollInput = {
+    /** What the previous successful run returned as `cursor`; null on the first run. */
+    cursor: string | null;
+    /** Ids earlier runs returned as `handled`, newest last. Skip these. */
+    seen: string[];
+};
+/**
+ * What a provider trigger's delivery carries as `input.__webhook`, beside the
+ * provider's own body. `cursor` and `seen` work as they do for a poll: for a
+ * provider whose notification only says that something changed, `subscribe`
+ * returns a starting `cursor` and each delivery returns the next one. A
+ * trigger that keeps a cursor gets one delivery at a time.
+ */
+export type ZiteTriggerDelivery = {
+    headers: Record<string, string>;
+    /** The provider's id for this delivery; redeliveries share it. */
+    deliveryId?: string;
+    provider?: string;
+    /** What `subscribe` or the previous successful delivery returned as `cursor`. */
+    cursor: string | null;
+    /** Ids earlier deliveries returned as `handled`, newest last. Skip these. */
+    seen: string[];
+};
+/**
+ * What a poll-triggered run, or a provider trigger's delivery, returns for
+ * the platform to keep: its new `cursor`, and the id of every item it acted
+ * on, so the next run's `seen` includes them even if the cursor hands them
+ * back.
+ */
+export type ZitePollResult = {
+    cursor?: string;
+    handled?: string[];
+};
 export interface ZiteRequestContext {
     user: {
         id: string;
@@ -116,7 +199,15 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
      */
     validatesInput?: boolean;
     execute: (params: {
-        input: TInput;
+        input: TTrigger extends {
+            every: string;
+        } ? TInput & {
+            __poll?: ZitePollInput;
+        } : TTrigger extends {
+            integration: string;
+        } ? TInput & {
+            __webhook?: ZiteTriggerDelivery;
+        } : TInput;
         context: TSchedule extends ZiteSchedule ? ZiteRequestContext | ZiteScheduledContext : TWebhook extends ZiteWebhook ? ZiteRequestContext | ZiteScheduledContext : TTrigger extends ZiteTrigger ? ZiteRequestContext | ZiteScheduledContext : ZiteRequestContext;
     } & (TStream extends true ? {
         stream: ZiteStreamInterface;

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

@@ -1,6 +1,6 @@
 import { describe, it, expect, afterEach, vi } from "vitest";
 import { z } from "zod";
-import { createEndpoint, ZiteError } from "./index.js";
+import { createEndpoint, ZiteError, } from "./index.js";
 import { createTableClient } from "../runtime/index.js";
 const requestContext = { user: { id: "u1", email: "a@b.c" } };
 afterEach(() => {
@@ -131,6 +131,74 @@ describe("platform-triggered runs", () => {
         });
         await expect(endpoint.execute({ input: undefined, context: requestContext })).rejects.toMatchObject({ code: "BAD_REQUEST" });
     });
+    it("hands a poll its cursor and seen ids, typed", async () => {
+        const endpoint = createEndpoint({
+            inputSchema: z.object({}),
+            trigger: { every: "5m", integration: "stripe" },
+            execute: async ({ input }) => {
+                const seen = new Set(input.__poll?.seen);
+                const items = ["a", "b"].filter((id) => !seen.has(id));
+                return { cursor: input.__poll?.cursor ?? "start", handled: items };
+            },
+        });
+        await expect(endpoint.execute({
+            input: { __poll: { cursor: "c1", seen: ["a"] } },
+            context: { user: null },
+        })).resolves.toEqual({ cursor: "c1", handled: ["b"] });
+    });
+    it("gives __poll only to poll triggers", () => {
+        createEndpoint({
+            inputSchema: z.object({ action: z.string() }),
+            trigger: { integration: "github" },
+            execute: async ({ input }) => {
+                // @ts-expect-error a provider trigger's input has no __poll
+                return input.__poll;
+            },
+        });
+    });
+    it("types a trigger's registration exports and checks what subscribe returns", async () => {
+        const subscribe = (async (input) => ({
+            externalId: `hook-for-${input.endpointId}`,
+            secret: input.secret,
+            state: { repo: "acme/api" },
+        }));
+        const unsubscribe = (async (input) => {
+            expect(input.state.repo).toBe("acme/api");
+        });
+        // @ts-expect-error subscribe has to return the provider's id
+        void (async () => ({ secret: "s" }));
+        const registered = await subscribe({
+            notificationUrl: "https://x",
+            integration: "github",
+            endpointId: "onPush",
+            secret: "abc",
+            previous: null,
+        });
+        expect(registered.externalId).toBe("hook-for-onPush");
+        await unsubscribe({
+            externalId: registered.externalId,
+            state: registered.state ?? {},
+            integration: "github",
+            endpointId: "onPush",
+        });
+    });
+    it("hands a provider trigger's delivery its cursor and seen ids, typed", async () => {
+        const endpoint = createEndpoint({
+            inputSchema: z.object({}),
+            trigger: { integration: "googleCalendar" },
+            execute: async ({ input }) => {
+                const seen = new Set(input.__webhook?.seen);
+                const changed = ["e1", "e2"].filter((id) => !seen.has(id));
+                return { cursor: `${input.__webhook?.cursor}+1`, handled: changed };
+            },
+        });
+        await expect(endpoint.execute({
+            input: {
+                __webhook: { headers: {}, cursor: "sync1", seen: ["e1"] },
+            },
+            context: { user: null },
+        })).resolves.toEqual({ cursor: "sync1+1", handled: ["e2"] });
+    });
     it("does not validate a webhook fire", async () => {
         const endpoint = createEndpoint({
             inputSchema: z.object({ token: z.string().min(10) }),

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

@@ -2,7 +2,7 @@
  * `npx zitejs bundle` — Bundle endpoint files for cloudflare-lambda deployment.
  *
  * Replaces the legacy `scripts/bundle-endpoints.js` from zitejs-starter.
- * Reads an app's src/api/*.ts endpoints (an automation's single src/workflow.ts), resolves SDK imports via .zite/backend.ts
+ * Reads an app's src/api/*.ts endpoints (an automation's single src/index.ts), resolves SDK imports via .zite/backend.ts
  * (monorepo) or src/__zite__/integrations.ts (legacy), and outputs bundled ESM
  * code suitable for the cloudflare-lambda worker runtime.
  *

package/dist/esm/bundle/index.js

@@ -2,7 +2,7 @@
  * `npx zitejs bundle` — Bundle endpoint files for cloudflare-lambda deployment.
  *
  * Replaces the legacy `scripts/bundle-endpoints.js` from zitejs-starter.
- * Reads an app's src/api/*.ts endpoints (an automation's single src/workflow.ts), resolves SDK imports via .zite/backend.ts
+ * Reads an app's src/api/*.ts endpoints (an automation's single src/index.ts), resolves SDK imports via .zite/backend.ts
  * (monorepo) or src/__zite__/integrations.ts (legacy), and outputs bundled ESM
  * code suitable for the cloudflare-lambda worker runtime.
  *
@@ -382,7 +382,7 @@ async function bundleEndpointsImpl(baseDir, root, endpointNames) {
     for (const name of endpointNames) {
         if (root === 'automations' && name !== AUTOMATION_ENDPOINT_NAME) {
             endpointErrors[name] =
-                `An automation is one workflow, src/workflow.ts, bundled as "${AUTOMATION_ENDPOINT_NAME}"; there is no endpoint "${name}"`;
+                `An automation is one workflow, src/index.ts, bundled as "${AUTOMATION_ENDPOINT_NAME}"; there is no endpoint "${name}"`;
             continue;
         }
         const entryFile = endpointEntryFile(root, name);
@@ -554,6 +554,10 @@ ${bodySection}
             },
             minify: false,
             logLevel: 'silent',
+            // A script that imports an endpoint file's named exports (a trigger's
+            // subscribe/unsubscribe) must not carry the endpoint along with them:
+            // unused, its `createEndpoint(...)` and everything `execute` imports go.
+            pure: ['createEndpoint'],
             plugins: [plugin],
         });
         if (result.errors.length > 0) {

package/dist/esm/cli.js

@@ -40,7 +40,7 @@ async function main() {
             console.error('  dev       Run sync then watch for changes (like npx convex dev)');
             console.error('  generate  Regenerate every app and automation .zite/ (monorepo)');
             console.error('  check   Run tsc --noEmit (and vite build where there is one) for every app and automation');
-            console.error('  bundle  Bundle endpoints (src/api/*.ts, or an automation\'s src/workflow.ts) for cloudflare-lambda');
+            console.error('  bundle  Bundle endpoints (src/api/*.ts, or an automation\'s src/index.ts) for cloudflare-lambda');
             process.exit(1);
     }
 }

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

@@ -0,0 +1,14 @@
+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

@@ -0,0 +1,8 @@
+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

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,8 @@
+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;

package/dist/esm/sourceRoots.d.ts

@@ -18,12 +18,12 @@ export declare function listSourceDirs(cwd?: string): SourceDir[];
 /** The source dir with this bare name, under whichever root holds it. */
 export declare function findSourceDir(name: string, cwd?: string): SourceDir | undefined;
 /**
- * An automation is one workflow: its single endpoint is `src/workflow.ts` and
+ * An automation is one workflow: its single endpoint is `src/index.ts` and
  * its name is fixed, so nothing about an automation is keyed on a file name
  * the way an app's `src/api/<name>.ts` endpoints are.
  */
-export declare const AUTOMATION_ENDPOINT_NAME = "workflow";
-export declare const AUTOMATION_WORKFLOW_FILE = "src/workflow.ts";
+export declare const AUTOMATION_ENDPOINT_NAME = "index";
+export declare const AUTOMATION_ENTRY_FILE = "src/index.ts";
 /** The root a source dir sits under, read from its parent directory. */
 export declare function sourceRootOf(sourceDirPath: string): SourceRoot | undefined;
 /** An endpoint's entry file, relative to the source dir. */

package/dist/esm/sourceRoots.js

@@ -27,12 +27,12 @@ export function findSourceDir(name, cwd = ".") {
     return listSourceDirs(cwd).find((d) => d.dir === name);
 }
 /**
- * An automation is one workflow: its single endpoint is `src/workflow.ts` and
+ * An automation is one workflow: its single endpoint is `src/index.ts` and
  * its name is fixed, so nothing about an automation is keyed on a file name
  * the way an app's `src/api/<name>.ts` endpoints are.
  */
-export const AUTOMATION_ENDPOINT_NAME = "workflow";
-export const AUTOMATION_WORKFLOW_FILE = "src/workflow.ts";
+export const AUTOMATION_ENDPOINT_NAME = "index";
+export const AUTOMATION_ENTRY_FILE = "src/index.ts";
 /** The root a source dir sits under, read from its parent directory. */
 export function sourceRootOf(sourceDirPath) {
     const parent = basename(dirname(resolve(sourceDirPath)));
@@ -43,13 +43,13 @@ export function sourceRootOf(sourceDirPath) {
 /** An endpoint's entry file, relative to the source dir. */
 export function endpointEntryFile(root, name) {
     return root === "automations"
-        ? AUTOMATION_WORKFLOW_FILE
+        ? AUTOMATION_ENTRY_FILE
         : join("src", "api", `${name}.ts`);
 }
 /** Every endpoint name a source dir has on disk. */
 export function listEndpointNames(root, sourceDirPath) {
     if (root === "automations") {
-        return existsSync(join(sourceDirPath, AUTOMATION_WORKFLOW_FILE))
+        return existsSync(join(sourceDirPath, AUTOMATION_ENTRY_FILE))
             ? [AUTOMATION_ENDPOINT_NAME]
             : [];
     }

package/dist/esm/sourceRoots.test.js

@@ -9,9 +9,9 @@ describe("source roots", () => {
         expect(sourceRootOf("/repo/automations/digest")).toBe("automations");
         expect(sourceRootOf("/repo/packages/ui")).toBeUndefined();
     });
-    it("an app's endpoints are src/api/<name>.ts; an automation's one endpoint is src/workflow.ts", () => {
+    it("an app's endpoints are src/api/<name>.ts; an automation's one endpoint is src/index.ts", () => {
         expect(endpointEntryFile("apps", "listItems")).toBe("src/api/listItems.ts");
-        expect(endpointEntryFile("automations", "workflow")).toBe("src/workflow.ts");
+        expect(endpointEntryFile("automations", "index")).toBe("src/index.ts");
     });
     it("lists what is on disk under each layout", () => {
         const repo = mkdtempSync(join(tmpdir(), "zitejs-roots-"));
@@ -20,9 +20,9 @@ describe("source roots", () => {
         writeFileSync(join(repo, "apps/crm/src/api/apiTypes.d.ts"), "");
         mkdirSync(join(repo, "automations/digest/src"), { recursive: true });
         mkdirSync(join(repo, "automations/empty/src"), { recursive: true });
-        writeFileSync(join(repo, "automations/digest/src/workflow.ts"), "");
+        writeFileSync(join(repo, "automations/digest/src/index.ts"), "");
         expect(listEndpointNames("apps", join(repo, "apps/crm"))).toEqual(["listItems"]);
-        expect(listEndpointNames("automations", join(repo, "automations/digest"))).toEqual(["workflow"]);
+        expect(listEndpointNames("automations", join(repo, "automations/digest"))).toEqual(["index"]);
         expect(listEndpointNames("automations", join(repo, "automations/empty"))).toEqual([]);
     });
 });

package/dist/esm/sync/lib.js

@@ -1411,7 +1411,7 @@ export function generateIntegrationsIndex(entries, opts) {
         "// Auto-generated by zitejs generate from zite.config.json. Do not edit manually.",
         "// zitejs/integrations — an integration's credentials by its zite.config.json entry name.",
         "//",
-        "// Usage in endpoints (src/api/*.ts) and automations (src/workflow.ts):",
+        "// Usage in endpoints (src/api/*.ts) and automations (src/index.ts):",
         "//   import { integrations } from 'zitejs/integrations';",
         "//",
         "//   const crm = await integrations.get('<entry name>');",

package/dist/esm/sync/lib.test.js

@@ -460,7 +460,7 @@ describe('generateIntegrationsIndex', () => {
       "// Auto-generated by zitejs generate from zite.config.json. Do not edit manually.
       // zitejs/integrations — an integration's credentials by its zite.config.json entry name.
       //
-      // Usage in endpoints (src/api/*.ts) and automations (src/workflow.ts):
+      // Usage in endpoints (src/api/*.ts) and automations (src/index.ts):
       //   import { integrations } from 'zitejs/integrations';
       //
       //   const crm = await integrations.get('<entry name>');

package/package.json

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