@hostwebhook/node 1.1.0 → 1.1.1

package/README.md

@@ -102,6 +102,35 @@ const hw = new HostWebhook({ token: 'your_ingress_token' });
 const { eventId } = await hw.send({ event: 'order.created', orderId: '123' });
 ```
 
+### Wait for pipeline result (SSE streaming)
+
+Use `waitForResult` to wait for the full pipeline to complete. The SDK opens an SSE stream behind the scenes and returns the result with all pipeline steps.
+
+```ts
+const result = await hw.send(
+  { event: 'order.created', orderId: '123' },
+  { waitForResult: true },
+);
+
+console.log(result.syncStatus);  // 200 = delivered, 422 = validation failed, 502 = failed, 408 = timeout
+console.log(result.steps);       // array of pipeline steps with nodeType, status, durationMs
+console.log(result.response);    // response body from target URL
+```
+
+Works with any endpoint regardless of its response mode. Max wait: ~120 seconds.
+
+### Deduplication detection
+
+When an event is deduplicated, the response includes `deduplicated: true`:
+
+```ts
+const result = await hw.send({ event: 'order.created', orderId: '123' });
+
+if (result.deduplicated) {
+  console.log('Duplicate! Original event:', result.originalEventId);
+}
+```
+
 ### Batch
 
 ```ts
@@ -129,9 +158,19 @@ const { eventId } = await send(
 | `token` | `string` | *required* | Endpoint ingress token |
 | `baseUrl` | `string` | `https://api.hostwebhook.com` | API base URL |
 | `signingSecret` | `string` | — | Signs outgoing requests with HMAC-SHA256 |
+| `signature` | `StaticSignature` | — | Static secret signature (alternative to HMAC) |
 | `defaultHeaders` | `Record<string, string>` | — | Headers added to every request |
 | `timeoutMs` | `number` | `10000` | Request timeout in ms |
 
+### SendOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `headers` | `Record<string, string>` | — | Per-request headers |
+| `contentType` | `string` | `application/json` | Override content type |
+| `rawBody` | `string \| Buffer` | — | Send raw body instead of JSON |
+| `waitForResult` | `boolean` | `false` | Wait for pipeline result via SSE stream |
+
 ## Error Handling
 
 ```ts

package/dist/index.d.mts

@@ -184,6 +184,18 @@ interface HostWebhookConfig {
     /** Request timeout in milliseconds. Default: 10000 (10s). */
     timeoutMs?: number;
 }
+/** A single pipeline execution step received via SSE stream. */
+interface PipelineStep {
+    eventId?: string;
+    nodeType: string;
+    nodeId: string;
+    nodeName?: string;
+    status: 'running' | 'success' | 'error' | 'blocked';
+    statusCode?: number;
+    durationMs?: number;
+    error?: string;
+    lastPayload?: Record<string, unknown>;
+}
 /** Options for a single send call. */
 interface SendOptions {
     /** Custom headers for this specific request (merged with defaultHeaders). */
@@ -195,25 +207,36 @@ interface SendOptions {
      * When set, the `payload` parameter to `send()` is ignored.
      */
     rawBody?: string | Buffer;
+    /**
+     * Wait for the full pipeline result via SSE streaming.
+     * 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).
+     */
+    waitForResult?: boolean;
 }
 /** Result returned after a successful send. */
 interface SendResult {
     /** The event ID assigned by HostWebhook. */
     eventId: string;
-    /** Sync mode: pipeline result status (200=delivered, 422=validation failed, 502=delivery failed, 408=timeout) */
+    /** Short-lived token for SSE stream auth (returned by ingress, used internally by waitForResult). */
+    streamToken?: string;
+    /** Sync/stream: pipeline result status (200=delivered, 422=validation failed, 502=delivery failed, 408=timeout) */
     syncStatus?: number;
-    /** Sync mode: delivery status ('delivered') */
+    /** Sync/stream: delivery status ('delivered') */
     deliveryStatus?: string;
-    /** Sync mode: HTTP status code from the target URL */
+    /** Sync/stream: HTTP status code from the target URL */
     statusCode?: number;
-    /** Sync mode: response body from the target URL (truncated to 4KB) */
+    /** Sync/stream: response body from the target URL (truncated to 4KB) */
     response?: string;
-    /** Sync mode: delivery latency in ms */
+    /** Sync/stream: delivery latency in ms */
     latencyMs?: number;
-    /** Sync mode: error message if pipeline/delivery failed */
+    /** Sync/stream: error message if pipeline/delivery failed */
     error?: string;
-    /** Sync mode: validation error messages (schema validator) */
+    /** Sync/stream: validation error messages (schema validator) */
     message?: string[];
+    /** SSE stream: pipeline execution steps (only when waitForResult is used) */
+    steps?: PipelineStep[];
     /** Any additional fields from the sync response */
     [key: string]: unknown;
 }
@@ -269,4 +292,4 @@ declare class HostWebhook {
  */
 declare function send(config: HostWebhookConfig, payload: Record<string, unknown>, options?: SendOptions): Promise<SendResult>;
 
-export { HostWebhook, type HostWebhookConfig, SendError, type SendOptions, type SendResult, type StaticSignature, VerificationError, type VerifyOptions, type WebhookHeaders, createNestGuard, expressMiddleware, fastifyHook, parseHeaders, send, verify };
+export { HostWebhook, type HostWebhookConfig, type PipelineStep, SendError, type SendOptions, type SendResult, type StaticSignature, VerificationError, type VerifyOptions, type WebhookHeaders, createNestGuard, expressMiddleware, fastifyHook, parseHeaders, send, verify };

package/dist/index.d.ts

@@ -184,6 +184,18 @@ interface HostWebhookConfig {
     /** Request timeout in milliseconds. Default: 10000 (10s). */
     timeoutMs?: number;
 }
+/** A single pipeline execution step received via SSE stream. */
+interface PipelineStep {
+    eventId?: string;
+    nodeType: string;
+    nodeId: string;
+    nodeName?: string;
+    status: 'running' | 'success' | 'error' | 'blocked';
+    statusCode?: number;
+    durationMs?: number;
+    error?: string;
+    lastPayload?: Record<string, unknown>;
+}
 /** Options for a single send call. */
 interface SendOptions {
     /** Custom headers for this specific request (merged with defaultHeaders). */
@@ -195,25 +207,36 @@ interface SendOptions {
      * When set, the `payload` parameter to `send()` is ignored.
      */
     rawBody?: string | Buffer;
+    /**
+     * Wait for the full pipeline result via SSE streaming.
+     * 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).
+     */
+    waitForResult?: boolean;
 }
 /** Result returned after a successful send. */
 interface SendResult {
     /** The event ID assigned by HostWebhook. */
     eventId: string;
-    /** Sync mode: pipeline result status (200=delivered, 422=validation failed, 502=delivery failed, 408=timeout) */
+    /** Short-lived token for SSE stream auth (returned by ingress, used internally by waitForResult). */
+    streamToken?: string;
+    /** Sync/stream: pipeline result status (200=delivered, 422=validation failed, 502=delivery failed, 408=timeout) */
     syncStatus?: number;
-    /** Sync mode: delivery status ('delivered') */
+    /** Sync/stream: delivery status ('delivered') */
     deliveryStatus?: string;
-    /** Sync mode: HTTP status code from the target URL */
+    /** Sync/stream: HTTP status code from the target URL */
     statusCode?: number;
-    /** Sync mode: response body from the target URL (truncated to 4KB) */
+    /** Sync/stream: response body from the target URL (truncated to 4KB) */
     response?: string;
-    /** Sync mode: delivery latency in ms */
+    /** Sync/stream: delivery latency in ms */
     latencyMs?: number;
-    /** Sync mode: error message if pipeline/delivery failed */
+    /** Sync/stream: error message if pipeline/delivery failed */
     error?: string;
-    /** Sync mode: validation error messages (schema validator) */
+    /** Sync/stream: validation error messages (schema validator) */
     message?: string[];
+    /** SSE stream: pipeline execution steps (only when waitForResult is used) */
+    steps?: PipelineStep[];
     /** Any additional fields from the sync response */
     [key: string]: unknown;
 }
@@ -269,4 +292,4 @@ declare class HostWebhook {
  */
 declare function send(config: HostWebhookConfig, payload: Record<string, unknown>, options?: SendOptions): Promise<SendResult>;
 
-export { HostWebhook, type HostWebhookConfig, SendError, type SendOptions, type SendResult, type StaticSignature, VerificationError, type VerifyOptions, type WebhookHeaders, createNestGuard, expressMiddleware, fastifyHook, parseHeaders, send, verify };
+export { HostWebhook, type HostWebhookConfig, type PipelineStep, SendError, type SendOptions, type SendResult, type StaticSignature, VerificationError, type VerifyOptions, type WebhookHeaders, createNestGuard, expressMiddleware, fastifyHook, parseHeaders, send, verify };

package/dist/index.js

@@ -23,6 +23,7 @@ var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot
 var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
 var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
 
 // src/index.ts
 var index_exports = {};
@@ -206,9 +207,10 @@ var SendError = class extends Error {
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.hostwebhook.com";
 var DEFAULT_TIMEOUT = 1e4;
-var _token, _baseUrl, _signingSecret, _signature, _defaultHeaders, _timeoutMs;
+var _token, _baseUrl, _signingSecret, _signature, _defaultHeaders, _timeoutMs, _HostWebhook_instances, waitForStream_fn;
 var HostWebhook = class {
   constructor(config) {
+    __privateAdd(this, _HostWebhook_instances);
     __privateAdd(this, _token);
     __privateAdd(this, _baseUrl);
     __privateAdd(this, _signingSecret);
@@ -251,7 +253,7 @@ var HostWebhook = class {
     }
     const headers = {
       "Content-Type": options?.contentType ?? "application/json",
-      "User-Agent": `HostWebhook-SDK/${"1.0.7"}`,
+      "User-Agent": `HostWebhook-SDK/${"1.1.0"}`,
       "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
       ...tz ? { "X-HostWebhook-Timezone": tz } : {},
       ...__privateGet(this, _defaultHeaders),
@@ -272,6 +274,7 @@ var HostWebhook = class {
     const url = `${__privateGet(this, _baseUrl)}/api/in/${__privateGet(this, _token)}`;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), __privateGet(this, _timeoutMs));
+    let ingressResult;
     try {
       const res = await fetch(url, {
         method: "POST",
@@ -288,9 +291,9 @@ var HostWebhook = class {
         );
       }
       try {
-        return JSON.parse(text);
+        ingressResult = JSON.parse(text);
       } catch {
-        return { eventId: text };
+        ingressResult = { eventId: text };
       }
     } catch (err) {
       if (err instanceof SendError) throw err;
@@ -305,6 +308,11 @@ var HostWebhook = class {
     } finally {
       clearTimeout(timer);
     }
+    if (ingressResult.syncStatus !== void 0) return ingressResult;
+    if (options?.waitForResult && ingressResult.streamToken) {
+      return __privateMethod(this, _HostWebhook_instances, waitForStream_fn).call(this, ingressResult);
+    }
+    return ingressResult;
   }
   /**
    * Convenience: send multiple payloads in parallel.
@@ -323,6 +331,70 @@ _signingSecret = new WeakMap();
 _signature = new WeakMap();
 _defaultHeaders = new WeakMap();
 _timeoutMs = new WeakMap();
+_HostWebhook_instances = new WeakSet();
+waitForStream_fn = async function(ingressResult) {
+  const { eventId, streamToken } = ingressResult;
+  const streamUrl = `${__privateGet(this, _baseUrl)}/api/events/${eventId}/stream?token=${streamToken}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 125e3);
+  try {
+    const res = await fetch(streamUrl, { signal: controller.signal });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new SendError(`SSE stream error (${res.status}): ${text}`, res.status, text);
+    }
+    const steps = [];
+    let doneResult = null;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let currentEvent = "";
+    while (true) {
+      const { done, value } = await 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: ")) {
+          const data = line.slice(6);
+          try {
+            const parsed = JSON.parse(data);
+            if (currentEvent === "step") {
+              steps.push(parsed);
+            } else if (currentEvent === "done") {
+              doneResult = parsed;
+            } else if (currentEvent === "timeout") {
+              return { ...ingressResult, steps, syncStatus: 408, error: "Pipeline timeout" };
+            }
+          } catch {
+          }
+          currentEvent = "";
+        }
+      }
+      if (doneResult) break;
+    }
+    if (doneResult) {
+      return {
+        ...ingressResult,
+        steps,
+        syncStatus: doneResult.status ?? 200,
+        ...doneResult.body ?? doneResult
+      };
+    }
+    return { ...ingressResult, steps, syncStatus: 408, error: "Stream ended without result" };
+  } catch (err) {
+    if (err instanceof SendError) throw err;
+    if (err instanceof DOMException && err.name === "AbortError") {
+      throw new SendError("Pipeline stream timed out after 125s", 0, "");
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+};
 async function send(config, payload, options) {
   const client = new HostWebhook(config);
   return client.send(payload, options);

package/dist/index.mjs

@@ -5,6 +5,7 @@ var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot
 var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
 var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
 
 // src/verify.ts
 import { createHmac, timingSafeEqual } from "crypto";
@@ -173,9 +174,10 @@ var SendError = class extends Error {
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.hostwebhook.com";
 var DEFAULT_TIMEOUT = 1e4;
-var _token, _baseUrl, _signingSecret, _signature, _defaultHeaders, _timeoutMs;
+var _token, _baseUrl, _signingSecret, _signature, _defaultHeaders, _timeoutMs, _HostWebhook_instances, waitForStream_fn;
 var HostWebhook = class {
   constructor(config) {
+    __privateAdd(this, _HostWebhook_instances);
     __privateAdd(this, _token);
     __privateAdd(this, _baseUrl);
     __privateAdd(this, _signingSecret);
@@ -218,7 +220,7 @@ var HostWebhook = class {
     }
     const headers = {
       "Content-Type": options?.contentType ?? "application/json",
-      "User-Agent": `HostWebhook-SDK/${"1.0.7"}`,
+      "User-Agent": `HostWebhook-SDK/${"1.1.0"}`,
       "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
       ...tz ? { "X-HostWebhook-Timezone": tz } : {},
       ...__privateGet(this, _defaultHeaders),
@@ -239,6 +241,7 @@ var HostWebhook = class {
     const url = `${__privateGet(this, _baseUrl)}/api/in/${__privateGet(this, _token)}`;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), __privateGet(this, _timeoutMs));
+    let ingressResult;
     try {
       const res = await fetch(url, {
         method: "POST",
@@ -255,9 +258,9 @@ var HostWebhook = class {
         );
       }
       try {
-        return JSON.parse(text);
+        ingressResult = JSON.parse(text);
       } catch {
-        return { eventId: text };
+        ingressResult = { eventId: text };
       }
     } catch (err) {
       if (err instanceof SendError) throw err;
@@ -272,6 +275,11 @@ var HostWebhook = class {
     } finally {
       clearTimeout(timer);
     }
+    if (ingressResult.syncStatus !== void 0) return ingressResult;
+    if (options?.waitForResult && ingressResult.streamToken) {
+      return __privateMethod(this, _HostWebhook_instances, waitForStream_fn).call(this, ingressResult);
+    }
+    return ingressResult;
   }
   /**
    * Convenience: send multiple payloads in parallel.
@@ -290,6 +298,70 @@ _signingSecret = new WeakMap();
 _signature = new WeakMap();
 _defaultHeaders = new WeakMap();
 _timeoutMs = new WeakMap();
+_HostWebhook_instances = new WeakSet();
+waitForStream_fn = async function(ingressResult) {
+  const { eventId, streamToken } = ingressResult;
+  const streamUrl = `${__privateGet(this, _baseUrl)}/api/events/${eventId}/stream?token=${streamToken}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 125e3);
+  try {
+    const res = await fetch(streamUrl, { signal: controller.signal });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new SendError(`SSE stream error (${res.status}): ${text}`, res.status, text);
+    }
+    const steps = [];
+    let doneResult = null;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let currentEvent = "";
+    while (true) {
+      const { done, value } = await 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: ")) {
+          const data = line.slice(6);
+          try {
+            const parsed = JSON.parse(data);
+            if (currentEvent === "step") {
+              steps.push(parsed);
+            } else if (currentEvent === "done") {
+              doneResult = parsed;
+            } else if (currentEvent === "timeout") {
+              return { ...ingressResult, steps, syncStatus: 408, error: "Pipeline timeout" };
+            }
+          } catch {
+          }
+          currentEvent = "";
+        }
+      }
+      if (doneResult) break;
+    }
+    if (doneResult) {
+      return {
+        ...ingressResult,
+        steps,
+        syncStatus: doneResult.status ?? 200,
+        ...doneResult.body ?? doneResult
+      };
+    }
+    return { ...ingressResult, steps, syncStatus: 408, error: "Stream ended without result" };
+  } catch (err) {
+    if (err instanceof SendError) throw err;
+    if (err instanceof DOMException && err.name === "AbortError") {
+      throw new SendError("Pipeline stream timed out after 125s", 0, "");
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+};
 async function send(config, payload, options) {
   const client = new HostWebhook(config);
   return client.send(payload, options);

package/package.json

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