@hostwebhook/node 1.6.0 → 1.6.2

package/README.md

@@ -1,276 +1,276 @@
-# @hostwebhook/node
-
-> **Early Access** — This SDK is in early access. The API may change between versions. We'd love your feedback — [report an issue](https://www.hostwebhook.com/#issues) if you run into anything.
-
-Official Node.js SDK for [HostWebhook](https://www.hostwebhook.com) — verify webhook signatures and send webhooks through the platform.
-
-## Install
-
-```sh
-npm install @hostwebhook/node
-```
-
-Requires Node.js 18+.
-
-## Verify Webhook Signatures
-
-HostWebhook signs every delivery with HMAC-SHA256. Use these helpers to verify authenticity and prevent replay attacks.
-
-### Express
-
-```ts
-import express from 'express';
-import { expressMiddleware } from '@hostwebhook/node';
-
-const app = express();
-
-app.post('/webhooks',
-  express.raw({ type: 'application/json' }),
-  expressMiddleware(process.env.SIGNING_SECRET!),
-  (req, res) => {
-    const payload = JSON.parse(req.body.toString());
-    // process payload...
-    res.json({ received: true });
-  },
-);
-```
-
-> **Important:** Use `express.raw()` so `req.body` is a Buffer, not parsed JSON.
-
-### NestJS
-
-```ts
-import { Controller, Post, UseGuards, Req } from '@nestjs/common';
-import { createNestGuard } from '@hostwebhook/node';
-
-const WebhookGuard = createNestGuard(process.env.SIGNING_SECRET!);
-
-@Controller('webhooks')
-export class WebhooksController {
-  @Post()
-  @UseGuards(WebhookGuard)
-  handle(@Req() req: Request) {
-    return { received: true };
-  }
-}
-```
-
-### Fastify
-
-```ts
-import Fastify from 'fastify';
-import { fastifyHook } from '@hostwebhook/node';
-
-const app = Fastify();
-app.addContentTypeParser('application/json', { parseAs: 'buffer' }, (req, body, done) => done(null, body));
-
-app.post('/webhooks', {
-  preHandler: fastifyHook(process.env.SIGNING_SECRET!),
-}, (req, reply) => {
-  reply.send({ received: true });
-});
-```
-
-### Manual Verification
-
-```ts
-import { verify, VerificationError } from '@hostwebhook/node';
-
-try {
-  verify(rawBody, request.headers, secret);
-  // signature valid
-} catch (err) {
-  if (err instanceof VerificationError) {
-    // invalid — reject the request
-  }
-}
-```
-
-Options: `verify(payload, headers, secret, { maxAgeSec: 300 })` — default 300s (5 min). Set `0` to disable replay protection.
-
-## Send Webhooks
-
-Send webhook payloads through HostWebhook for reliable delivery with retries and monitoring.
-
-### Fire & forget (default)
-
-```ts
-import { HostWebhook } from '@hostwebhook/node';
-
-const hw = new HostWebhook({ token: 'your_ingress_token' });
-
-// Returns immediately with the event ID — you don't know what happened in the pipeline
-const { eventId } = await hw.send({ event: 'order.created', orderId: '123' });
-```
-
-### Wait for pipeline result (blocking)
-
-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. **This blocks until the pipeline finishes** (~120s max).
-
-```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
-```
-
-### Non-blocking result (recommended for UIs)
-
-Use `onResult` to get the pipeline result in a background callback. `send()` returns immediately so your UI never blocks. Perfect for forms and user-facing apps.
-
-```ts
-const { eventId } = await hw.send(
-  { event: 'order.created', orderId: '123' },
-  {
-    onResult: (result) => {
-      // Fires when the pipeline completes (via SSE in background)
-      if (result.awaitingApproval) {
-        showToast('Awaiting approval from ' + result.approvalNodeName);
-      } else if (result.syncStatus === 200) {
-        showToast('Delivered successfully');
-      } else {
-        showToast('Pipeline failed: ' + result.error);
-      }
-    },
-    onStep: (step) => {
-      // Optional: fires for each pipeline node as it executes
-      updateProgress(step.nodeName, step.status);
-    },
-  },
-);
-// UI shows "Sent!" immediately here — never blocks
-```
-
-> **Important:** `onResult` requires the endpoint to be in **None** response mode (async). In Sync mode, the server holds the HTTP connection open until the pipeline completes, which blocks `send()` regardless of callbacks. See [Choosing the right mode](#choosing-the-right-mode) below.
-
-### 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
-const results = await hw.sendBatch([
-  { event: 'user.signup', userId: '1' },
-  { event: 'user.signup', userId: '2' },
-]);
-```
-
-### Standalone Function
-
-```ts
-import { send } from '@hostwebhook/node';
-
-const { eventId } = await send(
-  { token: 'your_ingress_token' },
-  { event: 'test', data: 'hello' },
-);
-```
-
-## Choosing the right mode
-
-Your endpoint has a **Response Mode** setting (None or Sync) that affects how `send()` behaves:
-
-| Scenario | Endpoint mode | SDK option | Behavior |
-|----------|--------------|------------|----------|
-| **Forms / UIs** | None | `onResult` | `send()` returns instantly. Pipeline result arrives in background callback. **UI never blocks.** |
-| **Backend scripts** | None | `waitForResult` | `send()` blocks until pipeline completes via SSE (~120s max). |
-| **API proxy / Stripe** | Sync | *(none)* | `send()` blocks until pipeline completes via HTTP (~120s max). Result is inline in the response. |
-| **Testing (Postman)** | Sync | *(none)* | Single request, response includes full pipeline result. |
-
-> **Warning: Never use Sync mode for user-facing forms or UIs.** Sync mode holds the HTTP connection open on the server, which blocks `send()` and freezes the UI until the pipeline completes. If the pipeline has approval nodes, merge nodes, or long delays, the SDK will timeout. Use **None** mode with `onResult` instead — the user sees "Sent!" immediately and the pipeline result arrives in the background.
-
-### When to use Sync mode
-
-- The caller is a **server or script**, not a human looking at a UI
-- The caller **needs the pipeline result in the same HTTP request** (e.g., Stripe expects a specific response body)
-- The pipeline is **fast and linear** (filter -> transform -> action) with no human-gated nodes (approval, merge)
-
-### When to use None mode + onResult
-
-- The caller is a **form, UI, or frontend app**
-- You want **instant feedback** ("Sent!") without waiting for the pipeline
-- The pipeline has **approval nodes, merge nodes, or delays**
-- You want **real-time progress** via `onStep` callbacks
-
-## Configuration
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `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 (blocking) |
-| `onResult` | `(result) => void` | — | Non-blocking pipeline result callback via SSE |
-| `onStep` | `(step) => void` | — | Real-time pipeline step callback (with `onResult` or `waitForResult`) |
-
-## Error Handling
-
-```ts
-import { SendError, VerificationError } from '@hostwebhook/node';
-
-// Send errors
-try {
-  await hw.send(payload);
-} catch (err) {
-  if (err instanceof SendError) {
-    console.log(err.statusCode, err.responseBody);
-  }
-}
-
-// Verification errors
-try {
-  verify(body, headers, secret);
-} catch (err) {
-  if (err instanceof VerificationError) {
-    console.log(err.message);
-  }
-}
-```
-
-## Signature Format
-
-```
-X-HostWebhook-Signature: t=<timestamp_ms>,v1=<hmac_hex>
-```
-
-HMAC computed as: `HMAC-SHA256(secret, "${timestamp}.${rawBody}")`
-
-## Support
-
-Found a bug or have a feature request? [Report an issue](https://www.hostwebhook.com/#issues) on our website.
-
-## Privacy
-
-Your webhook data is yours. HostWebhook is built with privacy as a core principle:
-
-- **Your payloads stay between you and your endpoints** — we never sell, share, or use your data for training.
-- **Encryption in transit** — all traffic between the SDK, the platform, and your endpoints is sent over TLS.
-- **Minimal data retention** — event payloads are stored only for delivery and debugging, and are automatically purged based on your plan's retention window.
-
-## License
-
-MIT
+# @hostwebhook/node
+
+> **Early Access** — This SDK is in early access. The API may change between versions. We'd love your feedback — [report an issue](https://www.hostwebhook.com/#issues) if you run into anything.
+
+Official Node.js SDK for [HostWebhook](https://www.hostwebhook.com) — verify webhook signatures and send webhooks through the platform.
+
+## Install
+
+```sh
+npm install @hostwebhook/node
+```
+
+Requires Node.js 18+.
+
+## Verify Webhook Signatures
+
+HostWebhook signs every delivery with HMAC-SHA256. Use these helpers to verify authenticity and prevent replay attacks.
+
+### Express
+
+```ts
+import express from 'express';
+import { expressMiddleware } from '@hostwebhook/node';
+
+const app = express();
+
+app.post('/webhooks',
+  express.raw({ type: 'application/json' }),
+  expressMiddleware(process.env.SIGNING_SECRET!),
+  (req, res) => {
+    const payload = JSON.parse(req.body.toString());
+    // process payload...
+    res.json({ received: true });
+  },
+);
+```
+
+> **Important:** Use `express.raw()` so `req.body` is a Buffer, not parsed JSON.
+
+### NestJS
+
+```ts
+import { Controller, Post, UseGuards, Req } from '@nestjs/common';
+import { createNestGuard } from '@hostwebhook/node';
+
+const WebhookGuard = createNestGuard(process.env.SIGNING_SECRET!);
+
+@Controller('webhooks')
+export class WebhooksController {
+  @Post()
+  @UseGuards(WebhookGuard)
+  handle(@Req() req: Request) {
+    return { received: true };
+  }
+}
+```
+
+### Fastify
+
+```ts
+import Fastify from 'fastify';
+import { fastifyHook } from '@hostwebhook/node';
+
+const app = Fastify();
+app.addContentTypeParser('application/json', { parseAs: 'buffer' }, (req, body, done) => done(null, body));
+
+app.post('/webhooks', {
+  preHandler: fastifyHook(process.env.SIGNING_SECRET!),
+}, (req, reply) => {
+  reply.send({ received: true });
+});
+```
+
+### Manual Verification
+
+```ts
+import { verify, VerificationError } from '@hostwebhook/node';
+
+try {
+  verify(rawBody, request.headers, secret);
+  // signature valid
+} catch (err) {
+  if (err instanceof VerificationError) {
+    // invalid — reject the request
+  }
+}
+```
+
+Options: `verify(payload, headers, secret, { maxAgeSec: 300 })` — default 300s (5 min). Set `0` to disable replay protection.
+
+## Send Webhooks
+
+Send webhook payloads through HostWebhook for reliable delivery with retries and monitoring.
+
+### Fire & forget (default)
+
+```ts
+import { HostWebhook } from '@hostwebhook/node';
+
+const hw = new HostWebhook({ token: 'your_ingress_token' });
+
+// Returns immediately with the event ID — you don't know what happened in the pipeline
+const { eventId } = await hw.send({ event: 'order.created', orderId: '123' });
+```
+
+### Wait for pipeline result (blocking)
+
+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. **This blocks until the pipeline finishes** (~120s max).
+
+```ts
+const result = await hw.send(
+  { event: 'order.created', orderId: '123' },
+  { waitForResult: true },
+);
+
+console.log(result.syncStatus);  // 200 = delivered, 202 = paused, 422 = validation failed, 500 = failed, 408 = timeout
+console.log(result.steps);       // array of pipeline steps with nodeType, status, durationMs
+console.log(result.response);    // response body from target URL
+```
+
+### Non-blocking result (recommended for UIs)
+
+Use `onResult` to get the pipeline result in a background callback. `send()` returns immediately so your UI never blocks. Perfect for forms and user-facing apps.
+
+```ts
+const { eventId } = await hw.send(
+  { event: 'order.created', orderId: '123' },
+  {
+    onResult: (result) => {
+      // Fires when the pipeline completes (via SSE in background)
+      if (result.awaitingApproval) {
+        showToast('Awaiting approval from ' + result.approvalNodeName);
+      } else if (result.syncStatus === 200) {
+        showToast('Delivered successfully');
+      } else {
+        showToast('Pipeline failed: ' + result.error);
+      }
+    },
+    onStep: (step) => {
+      // Optional: fires for each pipeline node as it executes
+      updateProgress(step.nodeName, step.status);
+    },
+  },
+);
+// UI shows "Sent!" immediately here — never blocks
+```
+
+> **Important:** `onResult` requires the endpoint to be in **None** response mode (async). In Sync mode, the server holds the HTTP connection open until the pipeline completes, which blocks `send()` regardless of callbacks. See [Choosing the right mode](#choosing-the-right-mode) below.
+
+### 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
+const results = await hw.sendBatch([
+  { event: 'user.signup', userId: '1' },
+  { event: 'user.signup', userId: '2' },
+]);
+```
+
+### Standalone Function
+
+```ts
+import { send } from '@hostwebhook/node';
+
+const { eventId } = await send(
+  { token: 'your_ingress_token' },
+  { event: 'test', data: 'hello' },
+);
+```
+
+## Choosing the right mode
+
+Your endpoint has a **Response Mode** setting (None or Sync) that affects how `send()` behaves:
+
+| Scenario | Endpoint mode | SDK option | Behavior |
+|----------|--------------|------------|----------|
+| **Forms / UIs** | None | `onResult` | `send()` returns instantly. Pipeline result arrives in background callback. **UI never blocks.** |
+| **Backend scripts** | None | `waitForResult` | `send()` blocks until pipeline completes via SSE (~120s max). |
+| **API proxy / Stripe** | Sync | *(none)* | `send()` blocks until a Schema Validator or an AI Node in the flow answers (20s at most, 55s with an AI Node; `timeoutMs` is 60s by default, enough for both). A 2xx is the result; a 422, 500 or 408 throws `SendError` with the JSON body in `responseBody`. |
+| **Testing (Postman)** | Sync | *(none)* | Single request, response includes full pipeline result. |
+
+> **Warning: Never use Sync mode for user-facing forms or UIs.** Sync mode holds the HTTP connection open on the server, which blocks `send()` and freezes the UI until the pipeline completes. If the pipeline has approval nodes, merge nodes, or long delays, the SDK will timeout. Use **None** mode with `onResult` instead — the user sees "Sent!" immediately and the pipeline result arrives in the background.
+
+### When to use Sync mode
+
+- The caller is a **server or script**, not a human looking at a UI
+- The caller **needs the pipeline result in the same HTTP request** (e.g., Stripe expects a specific response body)
+- The pipeline is **fast and linear** (filter -> transform -> action) with no human-gated nodes (approval, merge)
+
+### When to use None mode + onResult
+
+- The caller is a **form, UI, or frontend app**
+- You want **instant feedback** ("Sent!") without waiting for the pipeline
+- The pipeline has **approval nodes, merge nodes, or delays**
+- You want **real-time progress** via `onStep` callbacks
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `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` | `60000` | Request timeout in ms (long enough for a Sync webhook) |
+
+### 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 (blocking) |
+| `onResult` | `(result) => void` | — | Non-blocking pipeline result callback via SSE |
+| `onStep` | `(step) => void` | — | Real-time pipeline step callback (with `onResult` or `waitForResult`) |
+
+## Error Handling
+
+```ts
+import { SendError, VerificationError } from '@hostwebhook/node';
+
+// Send errors
+try {
+  await hw.send(payload);
+} catch (err) {
+  if (err instanceof SendError) {
+    console.log(err.statusCode, err.responseBody);
+  }
+}
+
+// Verification errors
+try {
+  verify(body, headers, secret);
+} catch (err) {
+  if (err instanceof VerificationError) {
+    console.log(err.message);
+  }
+}
+```
+
+## Signature Format
+
+```
+X-HostWebhook-Signature: t=<timestamp_ms>,v1=<hmac_hex>
+```
+
+HMAC computed as: `HMAC-SHA256(secret, "${timestamp}.${rawBody}")`
+
+## Support
+
+Found a bug or have a feature request? [Report an issue](https://www.hostwebhook.com/#issues) on our website.
+
+## Privacy
+
+Your webhook data is yours. HostWebhook is built with privacy as a core principle:
+
+- **Your payloads stay between you and your endpoints** — we never sell, share, or use your data for training.
+- **Encryption in transit** — all traffic between the SDK, the platform, and your endpoints is sent over TLS.
+- **Minimal data retention** — event payloads are stored only for delivery and debugging, and are automatically purged based on your plan's retention window.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -192,7 +192,7 @@ interface HostWebhookConfig {
     apiKey?: string;
     /**
      * Default ingress token. When set, `send(payload)` uses this token.
-     * For multi-endpoint usage, pass the token per-call: `send(token, payload)`.
+     * For multi-webhook usage, pass the token per-call: `send(token, payload)`.
      */
     token?: string;
     /** Base URL of the HostWebhook API. Default: `https://api.hostwebhook.com` */
@@ -200,7 +200,7 @@ interface HostWebhookConfig {
     /**
      * HMAC-SHA256 signing secret. When set, every request is signed with the
      * HostWebhook signature format (`X-HostWebhook-Signature: t=<ts>,v1=<hmac>`).
-     * Pair with `incomingSignatureType: 'hostwebhook'` on the endpoint.
+     * Pair with `incomingSignatureType: 'hostwebhook'` on the webhook.
      * @deprecated Prefer `apiKey` for authentication.
      */
     signingSecret?: string;
@@ -220,7 +220,7 @@ interface HostWebhookConfig {
     signature?: StaticSignature;
     /** Custom headers to include in every request. */
     defaultHeaders?: Record<string, string>;
-    /** Request timeout in milliseconds. Default: 10000 (10s). */
+    /** Request timeout in milliseconds. Default: 60000 (60s), long enough for a Sync webhook with an AI Node (55s at most). */
     timeoutMs?: number;
 }
 /** A single pipeline execution step received via SSE stream. */
@@ -262,7 +262,7 @@ interface SendOptions {
      *   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 —
+     * For approval workflows, use `responseMode: 'sync'` on the webhook instead —
      * it returns the approval status inline without blocking the SSE stream.
      */
     waitForResult?: boolean;
@@ -295,7 +295,13 @@ interface SendResult {
     eventId: string;
     /** 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) */
+    /**
+     * Stream (`waitForResult`, `onResult`, `stream()`): pipeline result status —
+     * 200=delivered, 202=paused (approval, merge or a long delay), 422=validation
+     * failed, 500=delivery failed, 408=timeout. A webhook in Sync response mode
+     * answers with the real HTTP status instead: a non-2xx (422, 500, 408) throws
+     * `SendError` with the JSON body in `responseBody`.
+     */
     syncStatus?: number;
     /** Sync/stream: delivery status ('delivered') */
     deliveryStatus?: string;
@@ -324,13 +330,13 @@ declare class SendError extends Error {
 /**
  * HostWebhook client for sending webhooks through the platform.
  *
- * @example Single-endpoint
+ * @example Single-webhook
  * ```ts
  * const hw = new HostWebhook({ apiKey: 'hwk_...', token: 'ingress_token' });
  * await hw.send({ event: 'order.created' });
  * ```
  *
- * @example Multi-endpoint
+ * @example Multi-webhook
  * ```ts
  * const hw = new HostWebhook({ apiKey: 'hwk_...' });
  * await hw.send('token_a', { event: 'order.created' });

package/dist/index.d.ts

@@ -192,7 +192,7 @@ interface HostWebhookConfig {
     apiKey?: string;
     /**
      * Default ingress token. When set, `send(payload)` uses this token.
-     * For multi-endpoint usage, pass the token per-call: `send(token, payload)`.
+     * For multi-webhook usage, pass the token per-call: `send(token, payload)`.
      */
     token?: string;
     /** Base URL of the HostWebhook API. Default: `https://api.hostwebhook.com` */
@@ -200,7 +200,7 @@ interface HostWebhookConfig {
     /**
      * HMAC-SHA256 signing secret. When set, every request is signed with the
      * HostWebhook signature format (`X-HostWebhook-Signature: t=<ts>,v1=<hmac>`).
-     * Pair with `incomingSignatureType: 'hostwebhook'` on the endpoint.
+     * Pair with `incomingSignatureType: 'hostwebhook'` on the webhook.
      * @deprecated Prefer `apiKey` for authentication.
      */
     signingSecret?: string;
@@ -220,7 +220,7 @@ interface HostWebhookConfig {
     signature?: StaticSignature;
     /** Custom headers to include in every request. */
     defaultHeaders?: Record<string, string>;
-    /** Request timeout in milliseconds. Default: 10000 (10s). */
+    /** Request timeout in milliseconds. Default: 60000 (60s), long enough for a Sync webhook with an AI Node (55s at most). */
     timeoutMs?: number;
 }
 /** A single pipeline execution step received via SSE stream. */
@@ -262,7 +262,7 @@ interface SendOptions {
      *   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 —
+     * For approval workflows, use `responseMode: 'sync'` on the webhook instead —
      * it returns the approval status inline without blocking the SSE stream.
      */
     waitForResult?: boolean;
@@ -295,7 +295,13 @@ interface SendResult {
     eventId: string;
     /** 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) */
+    /**
+     * Stream (`waitForResult`, `onResult`, `stream()`): pipeline result status —
+     * 200=delivered, 202=paused (approval, merge or a long delay), 422=validation
+     * failed, 500=delivery failed, 408=timeout. A webhook in Sync response mode
+     * answers with the real HTTP status instead: a non-2xx (422, 500, 408) throws
+     * `SendError` with the JSON body in `responseBody`.
+     */
     syncStatus?: number;
     /** Sync/stream: delivery status ('delivered') */
     deliveryStatus?: string;
@@ -324,13 +330,13 @@ declare class SendError extends Error {
 /**
  * HostWebhook client for sending webhooks through the platform.
  *
- * @example Single-endpoint
+ * @example Single-webhook
  * ```ts
  * const hw = new HostWebhook({ apiKey: 'hwk_...', token: 'ingress_token' });
  * await hw.send({ event: 'order.created' });
  * ```
  *
- * @example Multi-endpoint
+ * @example Multi-webhook
  * ```ts
  * const hw = new HostWebhook({ apiKey: 'hwk_...' });
  * await hw.send('token_a', { event: 'order.created' });

package/dist/index.js

@@ -213,7 +213,7 @@ var SendError = class extends Error {
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.hostwebhook.com";
-var DEFAULT_TIMEOUT = 1e4;
+var DEFAULT_TIMEOUT = 6e4;
 var _apiKey, _token, _baseUrl, _signingSecret, _signature, _defaultHeaders, _timeoutMs, _HostWebhook_instances, doSend_fn, waitForStream_fn;
 var HostWebhook = class {
   constructor(config) {
@@ -410,7 +410,7 @@ doSend_fn = async function(token, payload, options) {
   }
   const headers = {
     "Content-Type": options?.contentType ?? "application/json",
-    "User-Agent": `HostWebhook-SDK/${"1.5.1"}`,
+    "User-Agent": `HostWebhook-SDK/${"1.6.2"}`,
     "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
     ...tz ? { "X-HostWebhook-Timezone": tz } : {},
     ...__privateGet(this, _defaultHeaders),
@@ -457,6 +457,10 @@ doSend_fn = async function(token, payload, options) {
     } catch {
       ingressResult = { eventId: text };
     }
+    if (!ingressResult.eventId) {
+      const deCabecera = res.headers.get("x-hostwebhook-event-id");
+      if (deCabecera) ingressResult = { ...ingressResult, eventId: deCabecera };
+    }
   } catch (err) {
     if (err instanceof SendError) throw err;
     if (err instanceof DOMException && err.name === "AbortError") {

package/dist/index.mjs

@@ -179,7 +179,7 @@ var SendError = class extends Error {
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.hostwebhook.com";
-var DEFAULT_TIMEOUT = 1e4;
+var DEFAULT_TIMEOUT = 6e4;
 var _apiKey, _token, _baseUrl, _signingSecret, _signature, _defaultHeaders, _timeoutMs, _HostWebhook_instances, doSend_fn, waitForStream_fn;
 var HostWebhook = class {
   constructor(config) {
@@ -376,7 +376,7 @@ doSend_fn = async function(token, payload, options) {
   }
   const headers = {
     "Content-Type": options?.contentType ?? "application/json",
-    "User-Agent": `HostWebhook-SDK/${"1.5.1"}`,
+    "User-Agent": `HostWebhook-SDK/${"1.6.2"}`,
     "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
     ...tz ? { "X-HostWebhook-Timezone": tz } : {},
     ...__privateGet(this, _defaultHeaders),
@@ -423,6 +423,10 @@ doSend_fn = async function(token, payload, options) {
     } catch {
       ingressResult = { eventId: text };
     }
+    if (!ingressResult.eventId) {
+      const deCabecera = res.headers.get("x-hostwebhook-event-id");
+      if (deCabecera) ingressResult = { ...ingressResult, eventId: deCabecera };
+    }
   } catch (err) {
     if (err instanceof SendError) throw err;
     if (err instanceof DOMException && err.name === "AbortError") {

package/llms.txt

@@ -1,167 +1,167 @@
-# @hostwebhook/node
-
-> Official HostWebhook Node.js SDK — verify webhook signatures and send webhooks through the platform.
-
-## Install
-
-npm install @hostwebhook/node
-
-## Verify Signatures (receiving webhooks)
-
-HostWebhook signs every delivery with HMAC-SHA256. Use these helpers to verify authenticity.
-
-### Express
-
-```ts
-import express from 'express';
-import { expressMiddleware } from '@hostwebhook/node';
-
-const app = express();
-app.post('/webhooks',
-  express.raw({ type: 'application/json' }),
-  expressMiddleware(process.env.SIGNING_SECRET!),
-  (req, res) => {
-    const payload = JSON.parse(req.body.toString());
-    // process payload...
-    res.json({ received: true });
-  },
-);
-```
-
-IMPORTANT: Use `express.raw()` so `req.body` is a Buffer, not parsed JSON.
-
-### NestJS
-
-```ts
-import { Controller, Post, UseGuards, Req } from '@nestjs/common';
-import { createNestGuard } from '@hostwebhook/node';
-
-const WebhookGuard = createNestGuard(process.env.SIGNING_SECRET!);
-
-@Controller('webhooks')
-export class WebhooksController {
-  @Post()
-  @UseGuards(WebhookGuard)
-  handle(@Req() req: Request) {
-    return { received: true };
-  }
-}
-```
-
-### Fastify
-
-```ts
-import Fastify from 'fastify';
-import { fastifyHook } from '@hostwebhook/node';
-
-const app = Fastify();
-app.addContentTypeParser('application/json', { parseAs: 'buffer' }, (req, body, done) => done(null, body));
-
-app.post('/webhooks', {
-  preHandler: fastifyHook(process.env.SIGNING_SECRET!),
-}, (req, reply) => {
-  reply.send({ received: true });
-});
-```
-
-### Manual verification
-
-```ts
-import { verify, VerificationError } from '@hostwebhook/node';
-
-try {
-  verify(rawBody, request.headers, secret);
-  // signature is valid
-} catch (err) {
-  if (err instanceof VerificationError) {
-    // invalid signature — reject
-  }
-}
-```
-
-verify(payload, headers, secret, options?) — throws VerificationError if invalid.
-VerifyOptions: { maxAgeSec?: number } — default 300 (5 min). Set 0 to disable replay protection.
-
-## Send Webhooks (sending through HostWebhook)
-
-### Class-based client
-
-```ts
-import { HostWebhook } from '@hostwebhook/node';
-
-const hw = new HostWebhook({ token: 'your_ingress_token' });
-
-// Send a single event
-const { eventId } = await hw.send({ event: 'order.created', orderId: '123' });
-
-// Send multiple events in parallel
-const results = await hw.sendBatch([
-  { event: 'user.signup', userId: '1' },
-  { event: 'user.signup', userId: '2' },
-]);
-```
-
-### Standalone function (no class needed)
-
-```ts
-import { send } from '@hostwebhook/node';
-
-const { eventId } = await send(
-  { token: 'your_ingress_token' },
-  { event: 'test', data: 'hello' },
-);
-```
-
-## Configuration
-
-HostWebhookConfig: {
-  token: string (required — your endpoint's ingress token),
-  baseUrl?: string (default: https://api.hostwebhook.com),
-  signingSecret?: string (optional — signs outgoing requests with HMAC-SHA256),
-  defaultHeaders?: Record<string, string>,
-  timeoutMs?: number (default: 10000),
-}
-
-SendOptions: {
-  headers?: Record<string, string>,
-  contentType?: string (default: application/json),
-  rawBody?: string | Buffer (skip JSON.stringify, send raw),
-}
-
-SendResult: { eventId: string }
-
-## Signature Format
-
-Header: `X-HostWebhook-Signature: t=<timestamp_ms>,v1=<hmac_hex>`
-HMAC computed as: `HMAC-SHA256(secret, "${timestamp}.${rawBody}")`
-
-## Error Handling
-
-```ts
-import { SendError, VerificationError } from '@hostwebhook/node';
-
-// SendError — thrown when API returns non-2xx
-try {
-  await hw.send(payload);
-} catch (err) {
-  if (err instanceof SendError) {
-    console.log(err.statusCode, err.responseBody);
-  }
-}
-
-// VerificationError — thrown when signature is invalid
-try {
-  verify(body, headers, secret);
-} catch (err) {
-  if (err instanceof VerificationError) {
-    console.log(err.message); // e.g. "Signature mismatch"
-  }
-}
-```
-
-## Exports
-
-Functions: verify, expressMiddleware, createNestGuard, fastifyHook, send
-Classes: HostWebhook, SendError, VerificationError
-Types: VerifyOptions, HostWebhookConfig, SendOptions, SendResult, WebhookHeaders
-Helpers: parseHeaders (extract webhook metadata from headers)
+# @hostwebhook/node
+
+> Official HostWebhook Node.js SDK — verify webhook signatures and send webhooks through the platform.
+
+## Install
+
+npm install @hostwebhook/node
+
+## Verify Signatures (receiving webhooks)
+
+HostWebhook signs every delivery with HMAC-SHA256. Use these helpers to verify authenticity.
+
+### Express
+
+```ts
+import express from 'express';
+import { expressMiddleware } from '@hostwebhook/node';
+
+const app = express();
+app.post('/webhooks',
+  express.raw({ type: 'application/json' }),
+  expressMiddleware(process.env.SIGNING_SECRET!),
+  (req, res) => {
+    const payload = JSON.parse(req.body.toString());
+    // process payload...
+    res.json({ received: true });
+  },
+);
+```
+
+IMPORTANT: Use `express.raw()` so `req.body` is a Buffer, not parsed JSON.
+
+### NestJS
+
+```ts
+import { Controller, Post, UseGuards, Req } from '@nestjs/common';
+import { createNestGuard } from '@hostwebhook/node';
+
+const WebhookGuard = createNestGuard(process.env.SIGNING_SECRET!);
+
+@Controller('webhooks')
+export class WebhooksController {
+  @Post()
+  @UseGuards(WebhookGuard)
+  handle(@Req() req: Request) {
+    return { received: true };
+  }
+}
+```
+
+### Fastify
+
+```ts
+import Fastify from 'fastify';
+import { fastifyHook } from '@hostwebhook/node';
+
+const app = Fastify();
+app.addContentTypeParser('application/json', { parseAs: 'buffer' }, (req, body, done) => done(null, body));
+
+app.post('/webhooks', {
+  preHandler: fastifyHook(process.env.SIGNING_SECRET!),
+}, (req, reply) => {
+  reply.send({ received: true });
+});
+```
+
+### Manual verification
+
+```ts
+import { verify, VerificationError } from '@hostwebhook/node';
+
+try {
+  verify(rawBody, request.headers, secret);
+  // signature is valid
+} catch (err) {
+  if (err instanceof VerificationError) {
+    // invalid signature — reject
+  }
+}
+```
+
+verify(payload, headers, secret, options?) — throws VerificationError if invalid.
+VerifyOptions: { maxAgeSec?: number } — default 300 (5 min). Set 0 to disable replay protection.
+
+## Send Webhooks (sending through HostWebhook)
+
+### Class-based client
+
+```ts
+import { HostWebhook } from '@hostwebhook/node';
+
+const hw = new HostWebhook({ token: 'your_ingress_token' });
+
+// Send a single event
+const { eventId } = await hw.send({ event: 'order.created', orderId: '123' });
+
+// Send multiple events in parallel
+const results = await hw.sendBatch([
+  { event: 'user.signup', userId: '1' },
+  { event: 'user.signup', userId: '2' },
+]);
+```
+
+### Standalone function (no class needed)
+
+```ts
+import { send } from '@hostwebhook/node';
+
+const { eventId } = await send(
+  { token: 'your_ingress_token' },
+  { event: 'test', data: 'hello' },
+);
+```
+
+## Configuration
+
+HostWebhookConfig: {
+  token: string (required — your endpoint's ingress token),
+  baseUrl?: string (default: https://api.hostwebhook.com),
+  signingSecret?: string (optional — signs outgoing requests with HMAC-SHA256),
+  defaultHeaders?: Record<string, string>,
+  timeoutMs?: number (default: 10000),
+}
+
+SendOptions: {
+  headers?: Record<string, string>,
+  contentType?: string (default: application/json),
+  rawBody?: string | Buffer (skip JSON.stringify, send raw),
+}
+
+SendResult: { eventId: string }
+
+## Signature Format
+
+Header: `X-HostWebhook-Signature: t=<timestamp_ms>,v1=<hmac_hex>`
+HMAC computed as: `HMAC-SHA256(secret, "${timestamp}.${rawBody}")`
+
+## Error Handling
+
+```ts
+import { SendError, VerificationError } from '@hostwebhook/node';
+
+// SendError — thrown when API returns non-2xx
+try {
+  await hw.send(payload);
+} catch (err) {
+  if (err instanceof SendError) {
+    console.log(err.statusCode, err.responseBody);
+  }
+}
+
+// VerificationError — thrown when signature is invalid
+try {
+  verify(body, headers, secret);
+} catch (err) {
+  if (err instanceof VerificationError) {
+    console.log(err.message); // e.g. "Signature mismatch"
+  }
+}
+```
+
+## Exports
+
+Functions: verify, expressMiddleware, createNestGuard, fastifyHook, send
+Classes: HostWebhook, SendError, VerificationError
+Types: VerifyOptions, HostWebhookConfig, SendOptions, SendResult, WebhookHeaders
+Helpers: parseHeaders (extract webhook metadata from headers)

package/package.json

@@ -1,43 +1,43 @@
-{
-  "name": "@hostwebhook/node",
-  "version": "1.6.0",
-  "description": "Official HostWebhook SDK — verify signatures, parse headers, and send webhooks",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "llms.txt"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "test": "node --test __tests__/sdk.test.mjs",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "hostwebhook",
-    "webhook",
-    "signature",
-    "verify",
-    "send",
-    "hmac",
-    "retry"
-  ],
-  "license": "MIT",
-  "devDependencies": {
-    "@types/node": "^25.3.3",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0"
-  },
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "@hostwebhook/node",
+  "version": "1.6.2",
+  "description": "Official HostWebhook SDK — verify signatures, parse headers, and send webhooks",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "llms.txt"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "node --test __tests__/sdk.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "hostwebhook",
+    "webhook",
+    "signature",
+    "verify",
+    "send",
+    "hmac",
+    "retry"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}