zitejs 0.9.126 → 0.9.127

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

@@ -21,14 +21,55 @@ export type ZiteTrigger = {
     /** 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.
@@ -159,7 +200,7 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
     validatesInput?: boolean;
     execute: (params: {
         input: TTrigger extends {
-            provider: "poll";
+            every: string;
         } ? TInput & {
             __poll?: ZitePollInput;
         } : TTrigger extends {

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

@@ -136,7 +136,7 @@ const requestContext = { user: { id: "u1", email: "a@b.c" } };
     (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: { provider: "poll", every: "5m" },
+            trigger: { every: "5m", integration: "stripe" },
             execute: async ({ input }) => {
                 const seen = new Set(input.__poll?.seen);
                 const items = ["a", "b"].filter((id) => !seen.has(id));
@@ -158,6 +158,32 @@ const requestContext = { user: { id: "u1", email: "a@b.c" } };
             },
         });
     });
+    (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({}),

package/dist/cjs/bundle/index.js

@@ -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/esm/backend/index.d.ts

@@ -21,14 +21,55 @@ export type ZiteTrigger = {
     /** 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.
@@ -159,7 +200,7 @@ export interface EndpointConfig<TInput = unknown, TOutput = unknown, TStream ext
     validatesInput?: boolean;
     execute: (params: {
         input: TTrigger extends {
-            provider: "poll";
+            every: string;
         } ? TInput & {
             __poll?: ZitePollInput;
         } : TTrigger extends {

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(() => {
@@ -134,7 +134,7 @@ describe("platform-triggered runs", () => {
     it("hands a poll its cursor and seen ids, typed", async () => {
         const endpoint = createEndpoint({
             inputSchema: z.object({}),
-            trigger: { provider: "poll", every: "5m" },
+            trigger: { every: "5m", integration: "stripe" },
             execute: async ({ input }) => {
                 const seen = new Set(input.__poll?.seen);
                 const items = ["a", "b"].filter((id) => !seen.has(id));
@@ -156,6 +156,32 @@ describe("platform-triggered runs", () => {
             },
         });
     });
+    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({}),

package/dist/esm/bundle/index.js

@@ -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/package.json

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