@hostwebhook/node 1.1.1 → 1.3.0

package/README.md

@@ -92,19 +92,20 @@ Options: `verify(payload, headers, secret, { maxAgeSec: 300 })` — default 300s
 
 Send webhook payloads through HostWebhook for reliable delivery with retries and monitoring.
 
-### Class-based
+### 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 (SSE streaming)
+### 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.
+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(
@@ -117,7 +118,34 @@ console.log(result.steps);       // array of pipeline steps with nodeType, statu
 console.log(result.response);    // response body from target URL
 ```
 
-Works with any endpoint regardless of its response mode. Max wait: ~120 seconds.
+### 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
 
@@ -151,6 +179,32 @@ const { eventId } = await send(
 );
 ```
 
+## 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 |
@@ -169,7 +223,9 @@ const { eventId } = await send(
 | `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 |
+| `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
 

package/dist/index.js

@@ -253,7 +253,7 @@ var HostWebhook = class {
     }
     const headers = {
       "Content-Type": options?.contentType ?? "application/json",
-      "User-Agent": `HostWebhook-SDK/${"1.1.0"}`,
+      "User-Agent": `HostWebhook-SDK/${"1.3.0"}`,
       "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
       ...tz ? { "X-HostWebhook-Timezone": tz } : {},
       ...__privateGet(this, _defaultHeaders),
@@ -308,9 +308,16 @@ var HostWebhook = class {
     } finally {
       clearTimeout(timer);
     }
-    if (ingressResult.syncStatus !== void 0) return ingressResult;
+    if (ingressResult.syncStatus !== void 0) {
+      if (options?.onResult) options.onResult(ingressResult);
+      return ingressResult;
+    }
     if (options?.waitForResult && ingressResult.streamToken) {
-      return __privateMethod(this, _HostWebhook_instances, waitForStream_fn).call(this, ingressResult);
+      return __privateMethod(this, _HostWebhook_instances, waitForStream_fn).call(this, ingressResult, options?.onStep);
+    }
+    if (options?.onResult && ingressResult.streamToken) {
+      __privateMethod(this, _HostWebhook_instances, waitForStream_fn).call(this, ingressResult, options?.onStep).then((result) => options.onResult(result)).catch(() => {
+      });
     }
     return ingressResult;
   }
@@ -324,6 +331,53 @@ var HostWebhook = class {
   async sendBatch(payloads, options) {
     return Promise.all(payloads.map((p) => this.send(p, options)));
   }
+  /**
+   * Send a webhook with file attachments.
+   *
+   * Files are uploaded directly to storage via presigned URLs (zero memory on API),
+   * then file references are injected into the payload before sending.
+   *
+   * @param payload - The webhook payload
+   * @param files - Map of field name → file (Buffer or Blob with metadata)
+   * @param options - Optional per-request configuration
+   *
+   * @example
+   * ```ts
+   * const hw = new HostWebhook({ token: 'your_token' });
+   * await hw.sendWithFiles(
+   *   { orderId: '123', type: 'invoice' },
+   *   { invoice: { data: pdfBuffer, fileName: 'inv.pdf', mimeType: 'application/pdf' } },
+   * );
+   * ```
+   */
+  async sendWithFiles(payload, files, options) {
+    const enrichedPayload = { ...payload };
+    for (const [fieldName, file] of Object.entries(files)) {
+      const uploadRes = await fetch(`${__privateGet(this, _baseUrl)}/api/files/upload-url`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${__privateGet(this, _token)}`
+        },
+        body: JSON.stringify({ fileName: file.fileName, mimeType: file.mimeType })
+      });
+      if (!uploadRes.ok) throw new SendError(`Failed to get upload URL for ${fieldName}`, uploadRes.status, await uploadRes.text());
+      const { fileId, uploadUrl, key } = await uploadRes.json();
+      const uploadBody = file.data instanceof Blob ? file.data : new Blob([new Uint8Array(file.data)], { type: file.mimeType });
+      const putRes = await fetch(uploadUrl, { method: "PUT", headers: { "Content-Type": file.mimeType }, body: uploadBody });
+      if (!putRes.ok) throw new SendError(`Failed to upload ${fieldName} to storage`, putRes.status, await putRes.text());
+      const confirmRes = await fetch(`${__privateGet(this, _baseUrl)}/api/files/${fileId}/confirm`, {
+        method: "POST",
+        headers: { "Authorization": `Bearer ${__privateGet(this, _token)}` }
+      });
+      if (!confirmRes.ok) throw new SendError(`Failed to confirm upload for ${fieldName}`, confirmRes.status, await confirmRes.text());
+      const confirmed = await confirmRes.json();
+      enrichedPayload[fieldName] = {
+        _file: { id: confirmed.id, key, originalName: confirmed.originalName, mimeType: confirmed.mimeType, size: confirmed.size }
+      };
+    }
+    return this.send(enrichedPayload, options);
+  }
 };
 _token = new WeakMap();
 _baseUrl = new WeakMap();
@@ -332,7 +386,7 @@ _signature = new WeakMap();
 _defaultHeaders = new WeakMap();
 _timeoutMs = new WeakMap();
 _HostWebhook_instances = new WeakSet();
-waitForStream_fn = async function(ingressResult) {
+waitForStream_fn = async function(ingressResult, onStep) {
   const { eventId, streamToken } = ingressResult;
   const streamUrl = `${__privateGet(this, _baseUrl)}/api/events/${eventId}/stream?token=${streamToken}`;
   const controller = new AbortController();
@@ -364,6 +418,7 @@ waitForStream_fn = async function(ingressResult) {
             const parsed = JSON.parse(data);
             if (currentEvent === "step") {
               steps.push(parsed);
+              if (onStep) onStep(parsed);
             } else if (currentEvent === "done") {
               doneResult = parsed;
             } else if (currentEvent === "timeout") {

package/dist/index.mjs

@@ -220,7 +220,7 @@ var HostWebhook = class {
     }
     const headers = {
       "Content-Type": options?.contentType ?? "application/json",
-      "User-Agent": `HostWebhook-SDK/${"1.1.0"}`,
+      "User-Agent": `HostWebhook-SDK/${"1.3.0"}`,
       "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
       ...tz ? { "X-HostWebhook-Timezone": tz } : {},
       ...__privateGet(this, _defaultHeaders),
@@ -275,9 +275,16 @@ var HostWebhook = class {
     } finally {
       clearTimeout(timer);
     }
-    if (ingressResult.syncStatus !== void 0) return ingressResult;
+    if (ingressResult.syncStatus !== void 0) {
+      if (options?.onResult) options.onResult(ingressResult);
+      return ingressResult;
+    }
     if (options?.waitForResult && ingressResult.streamToken) {
-      return __privateMethod(this, _HostWebhook_instances, waitForStream_fn).call(this, ingressResult);
+      return __privateMethod(this, _HostWebhook_instances, waitForStream_fn).call(this, ingressResult, options?.onStep);
+    }
+    if (options?.onResult && ingressResult.streamToken) {
+      __privateMethod(this, _HostWebhook_instances, waitForStream_fn).call(this, ingressResult, options?.onStep).then((result) => options.onResult(result)).catch(() => {
+      });
     }
     return ingressResult;
   }
@@ -291,6 +298,53 @@ var HostWebhook = class {
   async sendBatch(payloads, options) {
     return Promise.all(payloads.map((p) => this.send(p, options)));
   }
+  /**
+   * Send a webhook with file attachments.
+   *
+   * Files are uploaded directly to storage via presigned URLs (zero memory on API),
+   * then file references are injected into the payload before sending.
+   *
+   * @param payload - The webhook payload
+   * @param files - Map of field name → file (Buffer or Blob with metadata)
+   * @param options - Optional per-request configuration
+   *
+   * @example
+   * ```ts
+   * const hw = new HostWebhook({ token: 'your_token' });
+   * await hw.sendWithFiles(
+   *   { orderId: '123', type: 'invoice' },
+   *   { invoice: { data: pdfBuffer, fileName: 'inv.pdf', mimeType: 'application/pdf' } },
+   * );
+   * ```
+   */
+  async sendWithFiles(payload, files, options) {
+    const enrichedPayload = { ...payload };
+    for (const [fieldName, file] of Object.entries(files)) {
+      const uploadRes = await fetch(`${__privateGet(this, _baseUrl)}/api/files/upload-url`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${__privateGet(this, _token)}`
+        },
+        body: JSON.stringify({ fileName: file.fileName, mimeType: file.mimeType })
+      });
+      if (!uploadRes.ok) throw new SendError(`Failed to get upload URL for ${fieldName}`, uploadRes.status, await uploadRes.text());
+      const { fileId, uploadUrl, key } = await uploadRes.json();
+      const uploadBody = file.data instanceof Blob ? file.data : new Blob([new Uint8Array(file.data)], { type: file.mimeType });
+      const putRes = await fetch(uploadUrl, { method: "PUT", headers: { "Content-Type": file.mimeType }, body: uploadBody });
+      if (!putRes.ok) throw new SendError(`Failed to upload ${fieldName} to storage`, putRes.status, await putRes.text());
+      const confirmRes = await fetch(`${__privateGet(this, _baseUrl)}/api/files/${fileId}/confirm`, {
+        method: "POST",
+        headers: { "Authorization": `Bearer ${__privateGet(this, _token)}` }
+      });
+      if (!confirmRes.ok) throw new SendError(`Failed to confirm upload for ${fieldName}`, confirmRes.status, await confirmRes.text());
+      const confirmed = await confirmRes.json();
+      enrichedPayload[fieldName] = {
+        _file: { id: confirmed.id, key, originalName: confirmed.originalName, mimeType: confirmed.mimeType, size: confirmed.size }
+      };
+    }
+    return this.send(enrichedPayload, options);
+  }
 };
 _token = new WeakMap();
 _baseUrl = new WeakMap();
@@ -299,7 +353,7 @@ _signature = new WeakMap();
 _defaultHeaders = new WeakMap();
 _timeoutMs = new WeakMap();
 _HostWebhook_instances = new WeakSet();
-waitForStream_fn = async function(ingressResult) {
+waitForStream_fn = async function(ingressResult, onStep) {
   const { eventId, streamToken } = ingressResult;
   const streamUrl = `${__privateGet(this, _baseUrl)}/api/events/${eventId}/stream?token=${streamToken}`;
   const controller = new AbortController();
@@ -331,6 +385,7 @@ waitForStream_fn = async function(ingressResult) {
             const parsed = JSON.parse(data);
             if (currentEvent === "step") {
               steps.push(parsed);
+              if (onStep) onStep(parsed);
             } else if (currentEvent === "done") {
               doneResult = parsed;
             } else if (currentEvent === "timeout") {

package/package.json

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

package/dist/index.d.mts

@@ -1,295 +0,0 @@
-/**
- * Thrown when signature verification fails.
- */
-declare class VerificationError extends Error {
-    constructor(message: string);
-}
-interface VerifyOptions {
-    /** Max allowed age of the signature timestamp in seconds. Default: 300 (5 min). Set 0 to disable. */
-    maxAgeSec?: number;
-}
-/**
- * Verify a HostWebhook signature.
- *
- * Matches the format produced by HostWebhook's delivery processor:
- *   `X-HostWebhook-Signature: t=<timestamp_ms>,v1=<hmac_hex>`
- *
- * The HMAC is computed as: HMAC-SHA256(secret, `${timestamp}.${rawBody}`)
- *
- * @param payload - The raw request body (string or Buffer)
- * @param headers - The request headers object
- * @param secret  - Your signing secret (e.g. `whsec_...`)
- * @param options - Optional configuration
- * @throws {VerificationError} If the signature is missing, malformed, expired, or invalid
- */
-declare function verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string, options?: VerifyOptions): void;
-
-/**
- * Typed representation of HostWebhook delivery headers.
- */
-interface WebhookHeaders {
-    /** Unique event ID (`X-HostWebhook-Event-Id`) */
-    eventId: string;
-    /** Delivery attempt number (`X-HostWebhook-Attempt`) */
-    attempt: number;
-    /** Signature timestamp in milliseconds */
-    timestamp: number;
-    /** Raw HMAC-SHA256 hex signature */
-    signature: string;
-    /** Chain step number, if this is a chained delivery */
-    chainStep?: number;
-    /** Original chain payload (base64-decoded JSON) */
-    chainOriginal?: unknown;
-    /** Previous chain step response (base64-decoded JSON) */
-    chainPrevious?: unknown;
-    /** Chain response metadata (base64-decoded JSON) */
-    chainResponse?: {
-        status: number;
-        body: unknown;
-        [key: string]: unknown;
-    };
-    /** Whether the chain response was truncated */
-    chainResponseTruncated?: boolean;
-    /** Original size of the chain response before truncation */
-    chainResponseOriginalSize?: number;
-}
-/**
- * Parse all `X-HostWebhook-*` headers into a typed object.
- *
- * @param headers - The raw request headers
- * @returns Parsed webhook headers
- */
-declare function parseHeaders(headers: Record<string, string | string[] | undefined>): WebhookHeaders;
-
-type NextFn = (err?: unknown) => void;
-interface ExpressRequest {
-    body: string | Buffer;
-    headers: Record<string, string | string[] | undefined>;
-}
-interface ExpressResponse {
-    status(code: number): ExpressResponse;
-    json(body: unknown): void;
-}
-/**
- * Express middleware that verifies HostWebhook signatures.
- *
- * IMPORTANT: You must use `express.raw({ type: 'application/json' })` before
- * this middleware so that `req.body` is a Buffer (not parsed JSON).
- *
- * @example
- * ```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());
- *     res.status(200).json({ received: true });
- *   },
- * );
- * ```
- */
-declare function expressMiddleware(secret: string, options?: VerifyOptions): (req: ExpressRequest, res: ExpressResponse, next: NextFn) => void;
-/**
- * NestJS guard factory. Returns a class that can be used with @UseGuards().
- *
- * @example
- * ```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 };
- *   }
- * }
- * ```
- */
-declare function createNestGuard(secret: string, options?: VerifyOptions): {
-    new (): {
-        canActivate(context: {
-            switchToHttp(): {
-                getRequest(): ExpressRequest;
-            };
-        }): boolean;
-    };
-};
-/**
- * Fastify preHandler hook that verifies HostWebhook signatures.
- *
- * @example
- * ```ts
- * import Fastify from 'fastify';
- * import { fastifyHook } from '@hostwebhook/node';
- *
- * const app = Fastify({ bodyLimit: 1_048_576 });
- * 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 });
- * });
- * ```
- */
-declare function fastifyHook(secret: string, options?: VerifyOptions): (req: ExpressRequest, reply: ExpressResponse, done: NextFn) => void;
-
-/** Static secret signature — sends the secret as-is in a header (no HMAC). */
-interface StaticSignature {
-    type: 'static';
-    /** The secret/token value to send. */
-    secret: string;
-    /**
-     * Header name to send the secret in.
-     * Default: `Authorization` with `Bearer <secret>` format.
-     * @example 'X-My-Custom-Key'
-     */
-    header?: string;
-}
-/** Configuration for the HostWebhook client. */
-interface HostWebhookConfig {
-    /** Ingress token from your endpoint settings. */
-    token: string;
-    /** Base URL of the HostWebhook API. Default: `https://api.hostwebhook.com` */
-    baseUrl?: string;
-    /**
-     * 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.
-     * @deprecated Prefer `signature` for new integrations.
-     */
-    signingSecret?: string;
-    /**
-     * Signature configuration for incoming webhook verification.
-     * Cannot be used together with `signingSecret`.
-     *
-     * @example Static with default header (Authorization: Bearer)
-     * ```ts
-     * { type: 'static', secret: 'my-secret' }
-     * ```
-     * @example Static with custom header
-     * ```ts
-     * { type: 'static', secret: 'my-secret', header: 'X-My-Custom-Key' }
-     * ```
-     */
-    signature?: StaticSignature;
-    /** Custom headers to include in every request. */
-    defaultHeaders?: Record<string, string>;
-    /** 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). */
-    headers?: Record<string, string>;
-    /** Override the Content-Type. Default: `application/json`. */
-    contentType?: string;
-    /**
-     * Send raw string/Buffer body instead of JSON-stringifying a payload object.
-     * 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;
-    /** 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/stream: delivery status ('delivered') */
-    deliveryStatus?: string;
-    /** Sync/stream: HTTP status code from the target URL */
-    statusCode?: number;
-    /** Sync/stream: response body from the target URL (truncated to 4KB) */
-    response?: string;
-    /** Sync/stream: delivery latency in ms */
-    latencyMs?: number;
-    /** Sync/stream: error message if pipeline/delivery failed */
-    error?: string;
-    /** 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;
-}
-/** Thrown when the HostWebhook API returns a non-2xx response. */
-declare class SendError extends Error {
-    readonly statusCode: number;
-    readonly responseBody: string;
-    constructor(message: string, statusCode: number, responseBody: string);
-}
-
-/**
- * HostWebhook client for sending webhooks through the platform.
- *
- * @example
- * ```ts
- * const hw = new HostWebhook({ token: 'your_ingress_token' });
- * const { eventId } = await hw.send({ event: 'order.created', orderId: '123' });
- * ```
- */
-declare class HostWebhook {
-    #private;
-    constructor(config: HostWebhookConfig);
-    /**
-     * Send a webhook payload through HostWebhook.
-     *
-     * The payload is JSON-stringified and POST'd to the ingress endpoint.
-     * HostWebhook then handles delivery to the target URL with retries,
-     * monitoring, transforms, and signing.
-     *
-     * @param payload - The webhook payload (will be JSON.stringify'd)
-     * @param options - Optional per-request configuration
-     * @returns The event ID assigned by HostWebhook
-     * @throws {SendError} If the API returns a non-2xx status
-     */
-    send(payload: Record<string, unknown>, options?: SendOptions): Promise<SendResult>;
-    /**
-     * Convenience: send multiple payloads in parallel.
-     *
-     * @param payloads - Array of payloads to send
-     * @param options - Optional per-request configuration (shared for all)
-     * @returns Array of results (in same order as payloads)
-     */
-    sendBatch(payloads: Record<string, unknown>[], options?: SendOptions): Promise<SendResult[]>;
-}
-/**
- * Standalone send function (no class instantiation needed).
- *
- * @example
- * ```ts
- * import { send } from '@hostwebhook/node';
- * await send({ token: 'your_token' }, { event: 'test' });
- * ```
- */
-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 };

package/dist/index.d.ts

@@ -1,295 +0,0 @@
-/**
- * Thrown when signature verification fails.
- */
-declare class VerificationError extends Error {
-    constructor(message: string);
-}
-interface VerifyOptions {
-    /** Max allowed age of the signature timestamp in seconds. Default: 300 (5 min). Set 0 to disable. */
-    maxAgeSec?: number;
-}
-/**
- * Verify a HostWebhook signature.
- *
- * Matches the format produced by HostWebhook's delivery processor:
- *   `X-HostWebhook-Signature: t=<timestamp_ms>,v1=<hmac_hex>`
- *
- * The HMAC is computed as: HMAC-SHA256(secret, `${timestamp}.${rawBody}`)
- *
- * @param payload - The raw request body (string or Buffer)
- * @param headers - The request headers object
- * @param secret  - Your signing secret (e.g. `whsec_...`)
- * @param options - Optional configuration
- * @throws {VerificationError} If the signature is missing, malformed, expired, or invalid
- */
-declare function verify(payload: string | Buffer, headers: Record<string, string | string[] | undefined>, secret: string, options?: VerifyOptions): void;
-
-/**
- * Typed representation of HostWebhook delivery headers.
- */
-interface WebhookHeaders {
-    /** Unique event ID (`X-HostWebhook-Event-Id`) */
-    eventId: string;
-    /** Delivery attempt number (`X-HostWebhook-Attempt`) */
-    attempt: number;
-    /** Signature timestamp in milliseconds */
-    timestamp: number;
-    /** Raw HMAC-SHA256 hex signature */
-    signature: string;
-    /** Chain step number, if this is a chained delivery */
-    chainStep?: number;
-    /** Original chain payload (base64-decoded JSON) */
-    chainOriginal?: unknown;
-    /** Previous chain step response (base64-decoded JSON) */
-    chainPrevious?: unknown;
-    /** Chain response metadata (base64-decoded JSON) */
-    chainResponse?: {
-        status: number;
-        body: unknown;
-        [key: string]: unknown;
-    };
-    /** Whether the chain response was truncated */
-    chainResponseTruncated?: boolean;
-    /** Original size of the chain response before truncation */
-    chainResponseOriginalSize?: number;
-}
-/**
- * Parse all `X-HostWebhook-*` headers into a typed object.
- *
- * @param headers - The raw request headers
- * @returns Parsed webhook headers
- */
-declare function parseHeaders(headers: Record<string, string | string[] | undefined>): WebhookHeaders;
-
-type NextFn = (err?: unknown) => void;
-interface ExpressRequest {
-    body: string | Buffer;
-    headers: Record<string, string | string[] | undefined>;
-}
-interface ExpressResponse {
-    status(code: number): ExpressResponse;
-    json(body: unknown): void;
-}
-/**
- * Express middleware that verifies HostWebhook signatures.
- *
- * IMPORTANT: You must use `express.raw({ type: 'application/json' })` before
- * this middleware so that `req.body` is a Buffer (not parsed JSON).
- *
- * @example
- * ```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());
- *     res.status(200).json({ received: true });
- *   },
- * );
- * ```
- */
-declare function expressMiddleware(secret: string, options?: VerifyOptions): (req: ExpressRequest, res: ExpressResponse, next: NextFn) => void;
-/**
- * NestJS guard factory. Returns a class that can be used with @UseGuards().
- *
- * @example
- * ```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 };
- *   }
- * }
- * ```
- */
-declare function createNestGuard(secret: string, options?: VerifyOptions): {
-    new (): {
-        canActivate(context: {
-            switchToHttp(): {
-                getRequest(): ExpressRequest;
-            };
-        }): boolean;
-    };
-};
-/**
- * Fastify preHandler hook that verifies HostWebhook signatures.
- *
- * @example
- * ```ts
- * import Fastify from 'fastify';
- * import { fastifyHook } from '@hostwebhook/node';
- *
- * const app = Fastify({ bodyLimit: 1_048_576 });
- * 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 });
- * });
- * ```
- */
-declare function fastifyHook(secret: string, options?: VerifyOptions): (req: ExpressRequest, reply: ExpressResponse, done: NextFn) => void;
-
-/** Static secret signature — sends the secret as-is in a header (no HMAC). */
-interface StaticSignature {
-    type: 'static';
-    /** The secret/token value to send. */
-    secret: string;
-    /**
-     * Header name to send the secret in.
-     * Default: `Authorization` with `Bearer <secret>` format.
-     * @example 'X-My-Custom-Key'
-     */
-    header?: string;
-}
-/** Configuration for the HostWebhook client. */
-interface HostWebhookConfig {
-    /** Ingress token from your endpoint settings. */
-    token: string;
-    /** Base URL of the HostWebhook API. Default: `https://api.hostwebhook.com` */
-    baseUrl?: string;
-    /**
-     * 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.
-     * @deprecated Prefer `signature` for new integrations.
-     */
-    signingSecret?: string;
-    /**
-     * Signature configuration for incoming webhook verification.
-     * Cannot be used together with `signingSecret`.
-     *
-     * @example Static with default header (Authorization: Bearer)
-     * ```ts
-     * { type: 'static', secret: 'my-secret' }
-     * ```
-     * @example Static with custom header
-     * ```ts
-     * { type: 'static', secret: 'my-secret', header: 'X-My-Custom-Key' }
-     * ```
-     */
-    signature?: StaticSignature;
-    /** Custom headers to include in every request. */
-    defaultHeaders?: Record<string, string>;
-    /** 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). */
-    headers?: Record<string, string>;
-    /** Override the Content-Type. Default: `application/json`. */
-    contentType?: string;
-    /**
-     * Send raw string/Buffer body instead of JSON-stringifying a payload object.
-     * 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;
-    /** 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/stream: delivery status ('delivered') */
-    deliveryStatus?: string;
-    /** Sync/stream: HTTP status code from the target URL */
-    statusCode?: number;
-    /** Sync/stream: response body from the target URL (truncated to 4KB) */
-    response?: string;
-    /** Sync/stream: delivery latency in ms */
-    latencyMs?: number;
-    /** Sync/stream: error message if pipeline/delivery failed */
-    error?: string;
-    /** 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;
-}
-/** Thrown when the HostWebhook API returns a non-2xx response. */
-declare class SendError extends Error {
-    readonly statusCode: number;
-    readonly responseBody: string;
-    constructor(message: string, statusCode: number, responseBody: string);
-}
-
-/**
- * HostWebhook client for sending webhooks through the platform.
- *
- * @example
- * ```ts
- * const hw = new HostWebhook({ token: 'your_ingress_token' });
- * const { eventId } = await hw.send({ event: 'order.created', orderId: '123' });
- * ```
- */
-declare class HostWebhook {
-    #private;
-    constructor(config: HostWebhookConfig);
-    /**
-     * Send a webhook payload through HostWebhook.
-     *
-     * The payload is JSON-stringified and POST'd to the ingress endpoint.
-     * HostWebhook then handles delivery to the target URL with retries,
-     * monitoring, transforms, and signing.
-     *
-     * @param payload - The webhook payload (will be JSON.stringify'd)
-     * @param options - Optional per-request configuration
-     * @returns The event ID assigned by HostWebhook
-     * @throws {SendError} If the API returns a non-2xx status
-     */
-    send(payload: Record<string, unknown>, options?: SendOptions): Promise<SendResult>;
-    /**
-     * Convenience: send multiple payloads in parallel.
-     *
-     * @param payloads - Array of payloads to send
-     * @param options - Optional per-request configuration (shared for all)
-     * @returns Array of results (in same order as payloads)
-     */
-    sendBatch(payloads: Record<string, unknown>[], options?: SendOptions): Promise<SendResult[]>;
-}
-/**
- * Standalone send function (no class instantiation needed).
- *
- * @example
- * ```ts
- * import { send } from '@hostwebhook/node';
- * await send({ token: 'your_token' }, { event: 'test' });
- * ```
- */
-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 };