@zapier/zapier-sdk 0.68.0 → 0.69.0

package/dist/plugins/triggers/watchTriggerInbox/index.js

@@ -4,46 +4,213 @@ import { requireOnMessage, resolveConcurrencyAndLease, runDrainPass, } from "../
 import { resolveTriggerInboxId } from "../utils";
 import { triggerInboxResolver } from "../../../resolvers";
 import { triggersDefaults } from "../shared";
-const POLL_STAGES = [
-    [125, 125],
-    [375, 250],
-    [875, 500],
-    [10000, 1000],
-    [30000, 2500],
-    [60000, 5000],
-    [180000, 10000],
-];
-const DEFAULT_MAX_DRAIN_INTERVAL_MS = 60000;
-function pickPollIntervalMs(elapsedMs, maxIntervalMs) {
-    const stage = POLL_STAGES.find(([threshold]) => elapsedMs < threshold);
-    const interval = stage ? stage[1] : maxIntervalMs;
-    return Math.min(interval, maxIntervalMs);
+import { isAbortError, combineAbortSignals } from "../../../utils/abort-utils";
+import { sleep } from "../../../utils/retry-utils";
+import { isPermanentHttpError } from "../../../api";
+import { ZapierError } from "../../../types/errors";
+import { readInboxEvents } from "./sse";
+// First entry is the floor, not 0: a server that closes the stream immediately
+// (instant EOF, empty body) must not be able to reconnect with no delay, or it
+// busy-loops. Repeated instant closes escalate through the later entries (up to
+// 5 s); only a clean end after a healthy, long-lived connection resets to the
+// floor — see SSE_HEALTHY_CONNECTION_MS.
+const SSE_RECONNECT_BACKOFF_MS = [500, 1000, 2000, 5000];
+const DEFAULT_SAFETY_DRAIN_INTERVAL_MS = 300000; // 5 minutes
+// A clean stream end only resets the reconnect backoff to the floor if the
+// connection stayed open at least this long. A connection that lived longer
+// than our longest reconnect backoff is "healthy", so resetting gives fast
+// recovery from routine server-side cycling (e.g. JWT expiry); a stream that
+// closes sooner is treated as unstable and escalates like any other.
+const SSE_HEALTHY_CONNECTION_MS = 5000;
+/**
+ * Coalescing wake latch between the drain producers (SSE connect, SSE frames,
+ * the safety timer, abort) and the single drain consumer. A `request()` that
+ * lands while the consumer is mid-drain is not lost: `pending` stays set, so
+ * the consumer's next `waitForRequest()` returns immediately and runs one more
+ * drain. Mirrors `createWaiter` in drainTriggerInbox/pipeline.ts.
+ *
+ * Exported for unit testing the coalescing / no-lost-wakeup semantics.
+ */
+export function createDrainLatch() {
+    let pending = false;
+    const make = () => {
+        let resolve;
+        const promise = new Promise((r) => {
+            resolve = r;
+        });
+        return { promise, resolve };
+    };
+    let current = make();
+    return {
+        request() {
+            pending = true;
+            const prev = current;
+            current = make();
+            prev.resolve();
+        },
+        async waitForRequest() {
+            if (pending) {
+                pending = false;
+                return;
+            }
+            await current.promise;
+            pending = false;
+        },
+    };
+}
+/**
+ * Sole caller of `runDrainPass`, so drains are serial and never overlap. Waits
+ * for a request, drains the inbox to empty, repeats. The first pass carries
+ * `firstFetch: true` (preserving the initialization_failure check). Returns how
+ * the watch ended so the caller can resolve or re-throw.
+ */
+async function drainRunner({ drainOptions, drainRequest, signal, }) {
+    let firstFetch = true;
+    while (!signal.aborted) {
+        await drainRequest.waitForRequest();
+        if (signal.aborted)
+            return { kind: "aborted" };
+        let abortedFromCallback = false;
+        try {
+            ({ abortedFromCallback } = await runDrainPass({
+                ...drainOptions,
+                firstFetch,
+            }));
+        }
+        catch (error) {
+            return { kind: "error", error };
+        }
+        firstFetch = false;
+        if (abortedFromCallback)
+            return { kind: "abortedFromCallback" };
+    }
+    return { kind: "aborted" };
+}
+/** statusCode off any ZapierError (ZapierApiError, ZapierApprovalError, …). */
+function sseErrorStatusCode(err) {
+    return err instanceof ZapierError ? err.statusCode : undefined;
 }
-function sleepOrAbort(ms, signal) {
-    if (signal?.aborted)
-        return Promise.resolve();
-    return new Promise((resolve) => {
-        let settled = false;
-        const settle = () => {
-            if (settled)
+function sseErrorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Holds one persistent SSE connection open and requests a drain on connect
+ * (catch-up) and on every frame, keeping the socket open across drains so no
+ * notification window is missed. Reconnects with backoff on clean end or
+ * transient error. A 4xx is permanent for now (auth/permission/bad request);
+ * rather than hammer the endpoint or abandon SSE, it waits a full safety
+ * interval before retrying so a transient misconfiguration still self-heals,
+ * while the independent safety timer keeps draining. (429 never lands here —
+ * api.fetch retries it upstream as ZapierRateLimitError, treated as transient.)
+ *
+ * Failures are printed to stderr (never stdout, so `--json` NDJSON stays clean):
+ * permanent degradation warns once on entering the degraded state (silent on
+ * the per-safety-interval retries, warning again only after a reconnect then
+ * re-failure); transient reconnects are dim diagnostics printed only under
+ * `debug`. Clean stream ends (e.g. routine JWT-expiry cycling) print nothing,
+ * so a reconnect notice always means an error broke the stream.
+ */
+async function sseLoop({ api, inboxId, drainRequest, safetyDrainMs, signal, debug, }) {
+    let attempt = 0;
+    // Whether we've already warned about the current permanent-failure spell.
+    // Warn once on entering it; stay silent on retries; re-arm on a successful
+    // reconnect (onOpen) — the only way out, since a permanent 4xx throws before
+    // onOpen fires. Without this a standing 4xx prints the same warning every
+    // safety interval forever.
+    let degraded = false;
+    while (!signal.aborted) {
+        let connected = false;
+        let connectedAt = 0;
+        let transientError;
+        try {
+            for await (const _event of readInboxEvents({
+                api,
+                inboxId,
+                signal,
+                // SSE is edge-triggered with no replay, so draining on connect is the
+                // only way to pick up messages that arrived before this connection —
+                // including the window left by a prior disconnect.
+                onOpen: () => {
+                    connected = true;
+                    connectedAt = Date.now();
+                    degraded = false;
+                    drainRequest.request();
+                },
+            })) {
+                drainRequest.request();
+            }
+            // Clean stream end. Reset to the floor only if the connection stayed open
+            // long enough to count as healthy (e.g. routine JWT-expiry cycling), so a
+            // server that accepts the connection and immediately closes it escalates
+            // through the backoff below instead of reconnecting at a fixed 500 ms.
+            if (connected && Date.now() - connectedAt >= SSE_HEALTHY_CONNECTION_MS) {
+                attempt = 0;
+            }
+        }
+        catch (err) {
+            if (signal.aborted || isAbortError(err))
                 return;
-            settled = true;
-            clearTimeout(timer);
-            signal?.removeEventListener("abort", settle);
-            resolve();
-        };
-        const timer = setTimeout(settle, ms);
-        signal?.addEventListener("abort", settle, { once: true });
-    });
+            if (isPermanentHttpError(err)) {
+                if (!degraded) {
+                    const statusCode = sseErrorStatusCode(err);
+                    const errorMsg = sseErrorMessage(err);
+                    const httpPart = statusCode !== undefined ? ` (HTTP ${statusCode})` : "";
+                    console.warn(`[zapier-sdk] Real-time wake-ups for inbox ${inboxId}${httpPart} ` +
+                        `paused: ${errorMsg}. Falling back to the periodic safety drain.`);
+                    degraded = true;
+                }
+                attempt = 0;
+                if (signal.aborted)
+                    return;
+                await sleep(safetyDrainMs, signal);
+                continue;
+            }
+            // A connection that opened then dropped proves the endpoint is reachable,
+            // so reset to the floor; a failed connect grows the backoff instead.
+            if (connected)
+                attempt = 0;
+            transientError = err;
+        }
+        if (signal.aborted)
+            return;
+        const delay = SSE_RECONNECT_BACKOFF_MS[Math.min(attempt, SSE_RECONNECT_BACKOFF_MS.length - 1)];
+        attempt = Math.min(attempt + 1, SSE_RECONNECT_BACKOFF_MS.length - 1);
+        if (transientError !== undefined && debug) {
+            const statusCode = sseErrorStatusCode(transientError);
+            const errorMsg = sseErrorMessage(transientError);
+            const httpPart = statusCode !== undefined ? ` (HTTP ${statusCode})` : "";
+            console.error(`[zapier-sdk] Reconnecting real-time wake-ups for inbox ${inboxId} ` +
+                `(attempt ${attempt}, retry in ${delay}ms)${httpPart}: ${errorMsg}`);
+        }
+        await sleep(delay, signal);
+    }
+}
+/**
+ * Requests a drain every `safetyDrainMs`, independent of SSE state. Guarantees
+ * forward progress when SSE frames are missed, the connection drops undetected,
+ * or SSE is degraded. The timer is ref'd (like the prior poll loop) so the
+ * watch keeps the process alive until aborted — that is what makes this a real
+ * backstop even when SSE is parked on a permanent failure with no open socket.
+ */
+async function safetyTimerLoop({ safetyDrainMs, drainRequest, signal, }) {
+    while (!signal.aborted) {
+        await sleep(safetyDrainMs, signal);
+        if (signal.aborted)
+            return;
+        drainRequest.request();
+    }
 }
 /**
  * `watchTriggerInbox` is the continuous-consumption variant of
  * `drainTriggerInbox`. Same options surface, same callback shape;
- * the difference is that an empty lease triggers poll-and-wait
- * (with backoff) rather than ending the command. Resolves cleanly
- * on `signal` abort or when a callback throws
- * `ZapierAbortDrainSignal`; rejects on a fatal error or a
- * fail-fast handler error (when `continueOnError` is false).
+ * the difference is that after draining the inbox, it subscribes to
+ * a Server-Sent Events stream to wake on new-message notifications
+ * rather than polling. A periodic safety drain fires every
+ * `maxDrainIntervalSeconds` seconds (default: 300) to guarantee
+ * forward progress if SSE events are missed or the connection drops
+ * undetected. Resolves cleanly on `signal` abort or when a callback
+ * throws `ZapierAbortDrainSignal`; rejects on a fatal error or a
+ * fail-fast handler error.
  */
 export const watchTriggerInboxPlugin = definePlugin((sdk) => {
     async function watchTriggerInbox(options) {
@@ -53,38 +220,78 @@ export const watchTriggerInboxPlugin = definePlugin((sdk) => {
             api: sdk.context.api,
             inbox: options.inbox,
         });
-        const maxDrainIntervalMs = options.maxDrainIntervalSeconds !== undefined
+        if (options.signal?.aborted)
+            return;
+        const safetyDrainMs = options.maxDrainIntervalSeconds !== undefined
             ? options.maxDrainIntervalSeconds * 1000
-            : DEFAULT_MAX_DRAIN_INTERVAL_MS;
-        let firstFetch = true;
-        let lastNonEmptyAt = Date.now();
-        while (!options.signal?.aborted) {
-            const outcome = await runDrainPass({
-                sdk,
-                inboxId,
-                onMessage,
-                concurrency,
-                leaseLimit,
-                leaseSeconds: options.leaseSeconds,
-                maxMessages: undefined,
-                releaseOnError: options.releaseOnError ?? false,
-                continueOnError: options.continueOnError ?? false,
-                onError: options.onError,
-                signal: options.signal,
-                firstFetch,
-            });
-            firstFetch = false;
-            if (options.signal?.aborted)
-                return;
-            if (outcome.abortedFromCallback)
-                return;
-            if (outcome.processed > 0) {
-                lastNonEmptyAt = Date.now();
-                continue;
-            }
-            const elapsedMs = Date.now() - lastNonEmptyAt;
-            await sleepOrAbort(pickPollIntervalMs(elapsedMs, maxDrainIntervalMs), options.signal);
+            : DEFAULT_SAFETY_DRAIN_INTERVAL_MS;
+        // Internal stop lets the drain runner's terminal states (a handler's
+        // ZapierAbortDrainSignal, a fatal error) tear down the background SSE and
+        // safety loops. Combined with the caller's signal so either stops all.
+        const stop = new AbortController();
+        const combined = combineAbortSignals({
+            handles: [
+                ...(options.signal
+                    ? [{ signal: options.signal, dispose: () => { } }]
+                    : []),
+                { signal: stop.signal, dispose: () => { } },
+            ],
+        });
+        const signal = combined?.signal ?? stop.signal;
+        const drainRequest = createDrainLatch();
+        // Abort wakes the idle drain runner so it observes the abort and exits;
+        // the latch otherwise only resolves on a drain request.
+        signal.addEventListener("abort", () => drainRequest.request(), {
+            once: true,
+        });
+        // Real-time health is printed to stderr by the SSE loop (warnings always,
+        // reconnect diagnostics only under `debug`), so every consumer surfaces it
+        // without wiring anything — the watcher never routes this through onEvent.
+        const debug = sdk.context.options.debug === true;
+        const drainOptions = {
+            sdk,
+            inboxId,
+            onMessage,
+            concurrency,
+            leaseLimit,
+            leaseSeconds: options.leaseSeconds,
+            maxMessages: undefined,
+            releaseOnError: options.releaseOnError ?? false,
+            continueOnError: options.continueOnError ?? false,
+            onError: options.onError,
+            signal,
+        };
+        // Unconditional initial drain (firstFetch: true): handle anything already
+        // in the inbox even if SSE never connects (e.g. a permanent 4xx). SSE and
+        // the safety timer then layer on additional catch-up drains.
+        drainRequest.request();
+        const runnerDone = drainRunner({ drainOptions, drainRequest, signal });
+        const sseDone = sseLoop({
+            api: sdk.context.api,
+            inboxId,
+            drainRequest,
+            safetyDrainMs,
+            signal,
+            debug,
+        }).catch(() => { });
+        const safetyDone = safetyTimerLoop({
+            safetyDrainMs,
+            drainRequest,
+            signal,
+        }).catch(() => { });
+        let end;
+        try {
+            end = await runnerDone;
+        }
+        finally {
+            // Stop the producers and wait for them to unwind so no fetch or timer
+            // outlives this call, then release the combined-signal listeners.
+            stop.abort();
+            await Promise.all([sseDone, safetyDone]);
+            combined?.dispose();
         }
+        if (end.kind === "error")
+            throw end.error;
     }
     return {
         watchTriggerInbox,
@@ -93,7 +300,7 @@ export const watchTriggerInboxPlugin = definePlugin((sdk) => {
                 watchTriggerInbox: {
                     ...triggersDefaults,
                     type: "create",
-                    description: "Continuously consume a trigger inbox: drain currently-available messages via onMessage, then poll with backoff for new arrivals, until aborted. Resolves cleanly on signal abort or ZapierAbortDrainSignal from a handler; rejects on fatal SDK errors or fail-fast handler errors.",
+                    description: "Continuously consume a trigger inbox: drain currently-available messages via onMessage, then subscribe to SSE notifications for new arrivals until aborted. A periodic safety drain runs every maxDrainIntervalSeconds (default: 300) to guarantee forward progress if SSE events are missed. Resolves cleanly on signal abort or ZapierAbortDrainSignal from a handler; rejects on fatal SDK errors or fail-fast handler errors. Real-time wake-up health is reported on stderr: a warning when wake-ups pause and the watch falls back to the safety drain, plus (with debug) transient reconnect notices.",
                     itemType: "void",
                     // See drainTriggerInbox: override the doc generator's default
                     // suffix so the rendered return type is Promise<void>, not

package/dist/plugins/triggers/watchTriggerInbox/sse.d.ts

@@ -0,0 +1,30 @@
+import type { ApiClient } from "../../../api";
+interface InboxSseEvent {
+    inbox_id: string;
+    count?: number;
+}
+/**
+ * Streams the trigger inbox events endpoint and yields the notification frames
+ * for this inbox. The transport (SSE connection, parsing, reconnect-able error
+ * mapping, abort/cleanup) lives in `api.fetchStream`; this only adds the inbox
+ * URL and the `inbox_id` filter.
+ *
+ * `onOpen` fires once the connection is live (response ok, body present) and
+ * before the first frame. The endpoint is edge-triggered with no replay, so a
+ * caller must drain on `onOpen` to pick up messages that arrived before this
+ * connection existed — a frame alone never covers that window.
+ *
+ * The generator returns (without throwing) when the signal is aborted, when
+ * the server closes the connection (JWT expiry, clean shutdown), or when the
+ * body is empty. For a non-ok response `api.fetchStream` throws a `ZapierError`
+ * carrying the HTTP `statusCode`; `isPermanentHttpError` classifies it so the
+ * caller can tell permanent (4xx) failures from transient ones.
+ */
+export declare function readInboxEvents({ api, inboxId, signal, onOpen, }: {
+    api: ApiClient;
+    inboxId: string;
+    signal?: AbortSignal;
+    onOpen?: () => void;
+}): AsyncGenerator<InboxSseEvent>;
+export {};
+//# sourceMappingURL=sse.d.ts.map

package/dist/plugins/triggers/watchTriggerInbox/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../../../src/plugins/triggers/watchTriggerInbox/sse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,UAAU,aAAa;IACrB,QAAQ,EAAE,MAAM,CAAC;IAIjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAuB,eAAe,CAAC,EACrC,GAAG,EACH,OAAO,EACP,MAAM,EACN,MAAM,GACP,EAAE;IACD,GAAG,EAAE,SAAS,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB,GAAG,cAAc,CAAC,aAAa,CAAC,CAyBhC"}

package/dist/plugins/triggers/watchTriggerInbox/sse.js

@@ -0,0 +1,38 @@
+/**
+ * Streams the trigger inbox events endpoint and yields the notification frames
+ * for this inbox. The transport (SSE connection, parsing, reconnect-able error
+ * mapping, abort/cleanup) lives in `api.fetchStream`; this only adds the inbox
+ * URL and the `inbox_id` filter.
+ *
+ * `onOpen` fires once the connection is live (response ok, body present) and
+ * before the first frame. The endpoint is edge-triggered with no replay, so a
+ * caller must drain on `onOpen` to pick up messages that arrived before this
+ * connection existed — a frame alone never covers that window.
+ *
+ * The generator returns (without throwing) when the signal is aborted, when
+ * the server closes the connection (JWT expiry, clean shutdown), or when the
+ * body is empty. For a non-ok response `api.fetchStream` throws a `ZapierError`
+ * carrying the HTTP `statusCode`; `isPermanentHttpError` classifies it so the
+ * caller can tell permanent (4xx) failures from transient ones.
+ */
+export async function* readInboxEvents({ api, inboxId, signal, onOpen, }) {
+    for await (const message of api.fetchStream(`/trigger-inbox/api/v1/inboxes/${encodeURIComponent(inboxId)}/events`, { method: "GET", signal, authRequired: true, onOpen })) {
+        let parsed;
+        try {
+            parsed = JSON.parse(message.data);
+        }
+        catch {
+            continue;
+        }
+        if (typeof parsed === "object" &&
+            parsed !== null &&
+            typeof parsed.inbox_id === "string" &&
+            // Only wake on a frame for this inbox. Case-insensitive: the endpoint
+            // echoes the canonical lowercase UUID, but resolveTriggerInboxId passes
+            // a UUID-shaped `inbox` through unchanged, so its casing may differ.
+            parsed.inbox_id.toLowerCase() ===
+                inboxId.toLowerCase()) {
+            yield parsed;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/zapier-sdk",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "Complete Zapier SDK - combines all Zapier SDK packages",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -61,6 +61,7 @@
   "files": [
     "dist",
     "README.md",
+    "AGENTS.md",
     "CLAUDE.md",
     "CHANGELOG.md"
   ],