@hostwebhook/node 1.4.0 → 1.4.1

package/dist/index.d.mts

@@ -219,15 +219,29 @@ interface SendOptions {
      * Wait for the full pipeline result via SSE streaming (blocking).
      * The SDK will POST the payload, then open an SSE stream to receive
      * pipeline steps and the final result. Returns when the pipeline completes.
-     * Timeout: ~125s (slightly above the server's 120s SSE timeout).
+     *
+     * **Timeout:** ~125s (slightly above the server's 120s SSE timeout).
+     *
+     * **When to use:** Short pipelines where you need the result before
+     * responding to the user (e.g., validation, quick transforms).
+     *
+     * **When NOT to use:**
+     * - Long-running pipelines (file processing, scraping) — use fire-and-forget instead
+     * - Approval nodes — the stream returns `{ awaitingApproval: true }` immediately,
+     *   it does NOT wait for the approval to be resolved (that can take hours/days)
+     * - Delay nodes — if the delay exceeds the 125s timeout, the stream times out
+     *
+     * For approval workflows, use `responseMode: 'sync'` on the endpoint instead —
+     * it returns the approval status inline without blocking the SSE stream.
      */
     waitForResult?: boolean;
     /**
      * Non-blocking pipeline result callback. `send()` returns immediately with
      * the eventId, and the callback fires in the background when the pipeline
-     * completes (via SSE stream). Perfect for UIs that shouldn't block.
+     * completes (via SSE stream).
      *
-     * Requires the endpoint to be in `none` response mode (async).
+     * Same timeout limitations as `waitForResult` (125s max).
+     * For long pipelines, use WebSocket subscription instead.
      *
      * @example
      * ```ts
@@ -340,6 +354,48 @@ declare class HostWebhook {
         fileName: string;
         mimeType: string;
     }> | SendOptions, maybeOptions?: SendOptions): Promise<SendResult>;
+    /**
+     * Send a webhook and stream pipeline steps as an async iterable.
+     *
+     * Much simpler than `waitForResult` or `onResult` callbacks.
+     * Iteration ends when the pipeline completes. Access `stream.result`
+     * after the loop for the final pipeline result.
+     *
+     * @overload stream(payload) — uses default token
+     * @overload stream(token, payload) — specify token per call
+     *
+     * @example
+     * ```ts
+     * const hw = new HostWebhook({ apiKey: 'hwk_...', token: 'ingress_token' });
+     * const stream = await hw.stream({ event: 'order.created' });
+     *
+     * for await (const step of stream) {
+     *   console.log(`${step.nodeType}: ${step.status}`);
+     * }
+     * console.log('Done:', stream.result);
+     * ```
+     */
+    stream(tokenOrPayload: string | Record<string, unknown>, maybePayload?: Record<string, unknown>): Promise<PipelineStream>;
+}
+/**
+ * Async iterable pipeline stream. Yields PipelineStep objects as
+ * nodes execute, then completes. Access `.result` after iteration.
+ *
+ * @example
+ * ```ts
+ * const stream = await hw.stream(payload);
+ * for await (const step of stream) {
+ *   console.log(step.nodeType, step.status);
+ * }
+ * console.log(stream.result); // { syncStatus: 200, ... }
+ * ```
+ */
+declare class PipelineStream {
+    #private;
+    result: SendResult;
+    constructor(steps: PipelineStep[], result: SendResult);
+    static connect(streamUrl: string, ingressResult: SendResult): Promise<PipelineStream>;
+    [Symbol.asyncIterator](): AsyncGenerator<PipelineStep, void, undefined>;
 }
 /**
  * Standalone send function (no class instantiation needed).
@@ -352,4 +408,4 @@ declare class HostWebhook {
  */
 declare function send(config: HostWebhookConfig, payload: Record<string, unknown>, options?: SendOptions): Promise<SendResult>;
 
-export { HostWebhook, type HostWebhookConfig, type PipelineStep, SendError, type SendOptions, type SendResult, type StaticSignature, VerificationError, type VerifyOptions, type WebhookHeaders, createNestGuard, expressMiddleware, fastifyHook, parseHeaders, send, verify };
+export { HostWebhook, type HostWebhookConfig, type PipelineStep, PipelineStream, SendError, type SendOptions, type SendResult, type StaticSignature, VerificationError, type VerifyOptions, type WebhookHeaders, createNestGuard, expressMiddleware, fastifyHook, parseHeaders, send, verify };

package/dist/index.d.ts

@@ -219,15 +219,29 @@ interface SendOptions {
      * Wait for the full pipeline result via SSE streaming (blocking).
      * The SDK will POST the payload, then open an SSE stream to receive
      * pipeline steps and the final result. Returns when the pipeline completes.
-     * Timeout: ~125s (slightly above the server's 120s SSE timeout).
+     *
+     * **Timeout:** ~125s (slightly above the server's 120s SSE timeout).
+     *
+     * **When to use:** Short pipelines where you need the result before
+     * responding to the user (e.g., validation, quick transforms).
+     *
+     * **When NOT to use:**
+     * - Long-running pipelines (file processing, scraping) — use fire-and-forget instead
+     * - Approval nodes — the stream returns `{ awaitingApproval: true }` immediately,
+     *   it does NOT wait for the approval to be resolved (that can take hours/days)
+     * - Delay nodes — if the delay exceeds the 125s timeout, the stream times out
+     *
+     * For approval workflows, use `responseMode: 'sync'` on the endpoint instead —
+     * it returns the approval status inline without blocking the SSE stream.
      */
     waitForResult?: boolean;
     /**
      * Non-blocking pipeline result callback. `send()` returns immediately with
      * the eventId, and the callback fires in the background when the pipeline
-     * completes (via SSE stream). Perfect for UIs that shouldn't block.
+     * completes (via SSE stream).
      *
-     * Requires the endpoint to be in `none` response mode (async).
+     * Same timeout limitations as `waitForResult` (125s max).
+     * For long pipelines, use WebSocket subscription instead.
      *
      * @example
      * ```ts
@@ -340,6 +354,48 @@ declare class HostWebhook {
         fileName: string;
         mimeType: string;
     }> | SendOptions, maybeOptions?: SendOptions): Promise<SendResult>;
+    /**
+     * Send a webhook and stream pipeline steps as an async iterable.
+     *
+     * Much simpler than `waitForResult` or `onResult` callbacks.
+     * Iteration ends when the pipeline completes. Access `stream.result`
+     * after the loop for the final pipeline result.
+     *
+     * @overload stream(payload) — uses default token
+     * @overload stream(token, payload) — specify token per call
+     *
+     * @example
+     * ```ts
+     * const hw = new HostWebhook({ apiKey: 'hwk_...', token: 'ingress_token' });
+     * const stream = await hw.stream({ event: 'order.created' });
+     *
+     * for await (const step of stream) {
+     *   console.log(`${step.nodeType}: ${step.status}`);
+     * }
+     * console.log('Done:', stream.result);
+     * ```
+     */
+    stream(tokenOrPayload: string | Record<string, unknown>, maybePayload?: Record<string, unknown>): Promise<PipelineStream>;
+}
+/**
+ * Async iterable pipeline stream. Yields PipelineStep objects as
+ * nodes execute, then completes. Access `.result` after iteration.
+ *
+ * @example
+ * ```ts
+ * const stream = await hw.stream(payload);
+ * for await (const step of stream) {
+ *   console.log(step.nodeType, step.status);
+ * }
+ * console.log(stream.result); // { syncStatus: 200, ... }
+ * ```
+ */
+declare class PipelineStream {
+    #private;
+    result: SendResult;
+    constructor(steps: PipelineStep[], result: SendResult);
+    static connect(streamUrl: string, ingressResult: SendResult): Promise<PipelineStream>;
+    [Symbol.asyncIterator](): AsyncGenerator<PipelineStep, void, undefined>;
 }
 /**
  * Standalone send function (no class instantiation needed).
@@ -352,4 +408,4 @@ declare class HostWebhook {
  */
 declare function send(config: HostWebhookConfig, payload: Record<string, unknown>, options?: SendOptions): Promise<SendResult>;
 
-export { HostWebhook, type HostWebhookConfig, type PipelineStep, SendError, type SendOptions, type SendResult, type StaticSignature, VerificationError, type VerifyOptions, type WebhookHeaders, createNestGuard, expressMiddleware, fastifyHook, parseHeaders, send, verify };
+export { HostWebhook, type HostWebhookConfig, type PipelineStep, PipelineStream, SendError, type SendOptions, type SendResult, type StaticSignature, VerificationError, type VerifyOptions, type WebhookHeaders, createNestGuard, expressMiddleware, fastifyHook, parseHeaders, send, verify };

package/dist/index.js

@@ -29,6 +29,7 @@ var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "acce
 var index_exports = {};
 __export(index_exports, {
   HostWebhook: () => HostWebhook,
+  PipelineStream: () => PipelineStream,
   SendError: () => SendError,
   VerificationError: () => VerificationError,
   createNestGuard: () => createNestGuard,
@@ -337,6 +338,47 @@ var HostWebhook = class {
     }
     return __privateMethod(this, _HostWebhook_instances, doSend_fn).call(this, token, enrichedPayload, options);
   }
+  /**
+   * Send a webhook and stream pipeline steps as an async iterable.
+   *
+   * Much simpler than `waitForResult` or `onResult` callbacks.
+   * Iteration ends when the pipeline completes. Access `stream.result`
+   * after the loop for the final pipeline result.
+   *
+   * @overload stream(payload) — uses default token
+   * @overload stream(token, payload) — specify token per call
+   *
+   * @example
+   * ```ts
+   * const hw = new HostWebhook({ apiKey: 'hwk_...', token: 'ingress_token' });
+   * const stream = await hw.stream({ event: 'order.created' });
+   *
+   * for await (const step of stream) {
+   *   console.log(`${step.nodeType}: ${step.status}`);
+   * }
+   * console.log('Done:', stream.result);
+   * ```
+   */
+  async stream(tokenOrPayload, maybePayload) {
+    let token;
+    let payload;
+    if (typeof tokenOrPayload === "string") {
+      token = tokenOrPayload;
+      payload = maybePayload ?? {};
+    } else {
+      if (!__privateGet(this, _token)) {
+        throw new Error("HostWebhook: no default token set \u2014 pass token as first argument: stream(token, payload)");
+      }
+      token = __privateGet(this, _token);
+      payload = tokenOrPayload;
+    }
+    const ingressResult = await __privateMethod(this, _HostWebhook_instances, doSend_fn).call(this, token, payload);
+    if (!ingressResult.streamToken) {
+      return new PipelineStream([], ingressResult);
+    }
+    const streamUrl = `${__privateGet(this, _baseUrl)}/api/events/${ingressResult.eventId}/stream?token=${ingressResult.streamToken}`;
+    return PipelineStream.connect(streamUrl, ingressResult);
+  }
 };
 _apiKey = new WeakMap();
 _token = new WeakMap();
@@ -355,7 +397,7 @@ doSend_fn = async function(token, payload, options) {
   }
   const headers = {
     "Content-Type": options?.contentType ?? "application/json",
-    "User-Agent": `HostWebhook-SDK/${"1.4.0"}`,
+    "User-Agent": `HostWebhook-SDK/${"1.4.1"}`,
     "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
     ...tz ? { "X-HostWebhook-Timezone": tz } : {},
     ...__privateGet(this, _defaultHeaders),
@@ -492,6 +534,114 @@ waitForStream_fn = async function(ingressResult, onStep) {
     clearTimeout(timer);
   }
 };
+var _steps, _pendingSteps, _done, _doneResult, _resolve, _reader, _abortController;
+var _PipelineStream = class _PipelineStream {
+  constructor(steps, result) {
+    __privateAdd(this, _steps);
+    __privateAdd(this, _pendingSteps, []);
+    __privateAdd(this, _done, false);
+    __privateAdd(this, _doneResult, null);
+    __privateAdd(this, _resolve, null);
+    __privateAdd(this, _reader, null);
+    __privateAdd(this, _abortController, null);
+    __privateSet(this, _steps, steps);
+    this.result = result;
+    __privateSet(this, _done, true);
+  }
+  static async connect(streamUrl, ingressResult) {
+    const stream = new _PipelineStream([], ingressResult);
+    __privateSet(stream, _done, false);
+    const controller = new AbortController();
+    __privateSet(stream, _abortController, controller);
+    const timer = setTimeout(() => controller.abort(), 125e3);
+    try {
+      const res = await fetch(streamUrl, { signal: controller.signal });
+      if (!res.ok) {
+        clearTimeout(timer);
+        __privateSet(stream, _done, true);
+        return stream;
+      }
+      __privateSet(stream, _reader, res.body.getReader());
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let currentEvent = "";
+      (async () => {
+        var _a, _b, _c, _d;
+        try {
+          while (true) {
+            const { done, value } = await __privateGet(stream, _reader).read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop();
+            for (const line of lines) {
+              if (line.startsWith("event: ")) {
+                currentEvent = line.slice(7).trim();
+              } else if (line.startsWith("data: ")) {
+                try {
+                  const parsed = JSON.parse(line.slice(6));
+                  if (currentEvent === "step") {
+                    __privateGet(stream, _steps).push(parsed);
+                    __privateGet(stream, _pendingSteps).push(parsed);
+                    (_a = __privateGet(stream, _resolve)) == null ? void 0 : _a.call(stream);
+                  } else if (currentEvent === "done") {
+                    __privateSet(stream, _doneResult, parsed);
+                    stream.result = {
+                      ...ingressResult,
+                      steps: __privateGet(stream, _steps),
+                      syncStatus: parsed.status ?? 200,
+                      ...parsed.body ?? parsed
+                    };
+                    __privateSet(stream, _done, true);
+                    (_b = __privateGet(stream, _resolve)) == null ? void 0 : _b.call(stream);
+                    return;
+                  } else if (currentEvent === "timeout") {
+                    stream.result = { ...ingressResult, steps: __privateGet(stream, _steps), syncStatus: 408, error: "Pipeline timeout" };
+                    __privateSet(stream, _done, true);
+                    (_c = __privateGet(stream, _resolve)) == null ? void 0 : _c.call(stream);
+                    return;
+                  }
+                } catch {
+                }
+                currentEvent = "";
+              }
+            }
+          }
+        } catch {
+        } finally {
+          clearTimeout(timer);
+          __privateSet(stream, _done, true);
+          (_d = __privateGet(stream, _resolve)) == null ? void 0 : _d.call(stream);
+        }
+      })();
+    } catch {
+      clearTimeout(timer);
+      __privateSet(stream, _done, true);
+    }
+    return stream;
+  }
+  async *[Symbol.asyncIterator]() {
+    while (true) {
+      if (__privateGet(this, _pendingSteps).length > 0) {
+        yield __privateGet(this, _pendingSteps).shift();
+        continue;
+      }
+      if (__privateGet(this, _done)) return;
+      await new Promise((resolve) => {
+        __privateSet(this, _resolve, resolve);
+      });
+      __privateSet(this, _resolve, null);
+    }
+  }
+};
+_steps = new WeakMap();
+_pendingSteps = new WeakMap();
+_done = new WeakMap();
+_doneResult = new WeakMap();
+_resolve = new WeakMap();
+_reader = new WeakMap();
+_abortController = new WeakMap();
+var PipelineStream = _PipelineStream;
 async function send(config, payload, options) {
   const client = new HostWebhook(config);
   return client.send(payload, options);
@@ -499,6 +649,7 @@ async function send(config, payload, options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   HostWebhook,
+  PipelineStream,
   SendError,
   VerificationError,
   createNestGuard,

package/dist/index.mjs

@@ -304,6 +304,47 @@ var HostWebhook = class {
     }
     return __privateMethod(this, _HostWebhook_instances, doSend_fn).call(this, token, enrichedPayload, options);
   }
+  /**
+   * Send a webhook and stream pipeline steps as an async iterable.
+   *
+   * Much simpler than `waitForResult` or `onResult` callbacks.
+   * Iteration ends when the pipeline completes. Access `stream.result`
+   * after the loop for the final pipeline result.
+   *
+   * @overload stream(payload) — uses default token
+   * @overload stream(token, payload) — specify token per call
+   *
+   * @example
+   * ```ts
+   * const hw = new HostWebhook({ apiKey: 'hwk_...', token: 'ingress_token' });
+   * const stream = await hw.stream({ event: 'order.created' });
+   *
+   * for await (const step of stream) {
+   *   console.log(`${step.nodeType}: ${step.status}`);
+   * }
+   * console.log('Done:', stream.result);
+   * ```
+   */
+  async stream(tokenOrPayload, maybePayload) {
+    let token;
+    let payload;
+    if (typeof tokenOrPayload === "string") {
+      token = tokenOrPayload;
+      payload = maybePayload ?? {};
+    } else {
+      if (!__privateGet(this, _token)) {
+        throw new Error("HostWebhook: no default token set \u2014 pass token as first argument: stream(token, payload)");
+      }
+      token = __privateGet(this, _token);
+      payload = tokenOrPayload;
+    }
+    const ingressResult = await __privateMethod(this, _HostWebhook_instances, doSend_fn).call(this, token, payload);
+    if (!ingressResult.streamToken) {
+      return new PipelineStream([], ingressResult);
+    }
+    const streamUrl = `${__privateGet(this, _baseUrl)}/api/events/${ingressResult.eventId}/stream?token=${ingressResult.streamToken}`;
+    return PipelineStream.connect(streamUrl, ingressResult);
+  }
 };
 _apiKey = new WeakMap();
 _token = new WeakMap();
@@ -322,7 +363,7 @@ doSend_fn = async function(token, payload, options) {
   }
   const headers = {
     "Content-Type": options?.contentType ?? "application/json",
-    "User-Agent": `HostWebhook-SDK/${"1.4.0"}`,
+    "User-Agent": `HostWebhook-SDK/${"1.4.1"}`,
     "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
     ...tz ? { "X-HostWebhook-Timezone": tz } : {},
     ...__privateGet(this, _defaultHeaders),
@@ -459,12 +500,121 @@ waitForStream_fn = async function(ingressResult, onStep) {
     clearTimeout(timer);
   }
 };
+var _steps, _pendingSteps, _done, _doneResult, _resolve, _reader, _abortController;
+var _PipelineStream = class _PipelineStream {
+  constructor(steps, result) {
+    __privateAdd(this, _steps);
+    __privateAdd(this, _pendingSteps, []);
+    __privateAdd(this, _done, false);
+    __privateAdd(this, _doneResult, null);
+    __privateAdd(this, _resolve, null);
+    __privateAdd(this, _reader, null);
+    __privateAdd(this, _abortController, null);
+    __privateSet(this, _steps, steps);
+    this.result = result;
+    __privateSet(this, _done, true);
+  }
+  static async connect(streamUrl, ingressResult) {
+    const stream = new _PipelineStream([], ingressResult);
+    __privateSet(stream, _done, false);
+    const controller = new AbortController();
+    __privateSet(stream, _abortController, controller);
+    const timer = setTimeout(() => controller.abort(), 125e3);
+    try {
+      const res = await fetch(streamUrl, { signal: controller.signal });
+      if (!res.ok) {
+        clearTimeout(timer);
+        __privateSet(stream, _done, true);
+        return stream;
+      }
+      __privateSet(stream, _reader, res.body.getReader());
+      const decoder = new TextDecoder();
+      let buffer = "";
+      let currentEvent = "";
+      (async () => {
+        var _a, _b, _c, _d;
+        try {
+          while (true) {
+            const { done, value } = await __privateGet(stream, _reader).read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split("\n");
+            buffer = lines.pop();
+            for (const line of lines) {
+              if (line.startsWith("event: ")) {
+                currentEvent = line.slice(7).trim();
+              } else if (line.startsWith("data: ")) {
+                try {
+                  const parsed = JSON.parse(line.slice(6));
+                  if (currentEvent === "step") {
+                    __privateGet(stream, _steps).push(parsed);
+                    __privateGet(stream, _pendingSteps).push(parsed);
+                    (_a = __privateGet(stream, _resolve)) == null ? void 0 : _a.call(stream);
+                  } else if (currentEvent === "done") {
+                    __privateSet(stream, _doneResult, parsed);
+                    stream.result = {
+                      ...ingressResult,
+                      steps: __privateGet(stream, _steps),
+                      syncStatus: parsed.status ?? 200,
+                      ...parsed.body ?? parsed
+                    };
+                    __privateSet(stream, _done, true);
+                    (_b = __privateGet(stream, _resolve)) == null ? void 0 : _b.call(stream);
+                    return;
+                  } else if (currentEvent === "timeout") {
+                    stream.result = { ...ingressResult, steps: __privateGet(stream, _steps), syncStatus: 408, error: "Pipeline timeout" };
+                    __privateSet(stream, _done, true);
+                    (_c = __privateGet(stream, _resolve)) == null ? void 0 : _c.call(stream);
+                    return;
+                  }
+                } catch {
+                }
+                currentEvent = "";
+              }
+            }
+          }
+        } catch {
+        } finally {
+          clearTimeout(timer);
+          __privateSet(stream, _done, true);
+          (_d = __privateGet(stream, _resolve)) == null ? void 0 : _d.call(stream);
+        }
+      })();
+    } catch {
+      clearTimeout(timer);
+      __privateSet(stream, _done, true);
+    }
+    return stream;
+  }
+  async *[Symbol.asyncIterator]() {
+    while (true) {
+      if (__privateGet(this, _pendingSteps).length > 0) {
+        yield __privateGet(this, _pendingSteps).shift();
+        continue;
+      }
+      if (__privateGet(this, _done)) return;
+      await new Promise((resolve) => {
+        __privateSet(this, _resolve, resolve);
+      });
+      __privateSet(this, _resolve, null);
+    }
+  }
+};
+_steps = new WeakMap();
+_pendingSteps = new WeakMap();
+_done = new WeakMap();
+_doneResult = new WeakMap();
+_resolve = new WeakMap();
+_reader = new WeakMap();
+_abortController = new WeakMap();
+var PipelineStream = _PipelineStream;
 async function send(config, payload, options) {
   const client = new HostWebhook(config);
   return client.send(payload, options);
 }
 export {
   HostWebhook,
+  PipelineStream,
   SendError,
   VerificationError,
   createNestGuard,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/node",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Official HostWebhook SDK — verify signatures, parse headers, and send webhooks",
   "main": "dist/index.js",
   "module": "dist/index.mjs",