@hostwebhook/node 1.3.0 → 1.4.1

package/dist/index.d.mts

@@ -0,0 +1,411 @@
+/**
+ * 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 {
+    /**
+     * API key (`hwk_...`) for authentication. Required for file uploads
+     * and recommended for all operations. Must have appropriate scopes.
+     */
+    apiKey?: string;
+    /**
+     * Default ingress token. When set, `send(payload)` uses this token.
+     * For multi-endpoint usage, pass the token per-call: `send(token, payload)`.
+     */
+    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 `apiKey` for authentication.
+     */
+    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 (blocking).
+     * The SDK will POST the payload, then open an SSE stream to receive
+     * pipeline steps and the final result. Returns when the pipeline completes.
+     *
+     * **Timeout:** ~125s (slightly above the server's 120s SSE timeout).
+     *
+     * **When to use:** Short pipelines where you need the result before
+     * responding to the user (e.g., validation, quick transforms).
+     *
+     * **When NOT to use:**
+     * - Long-running pipelines (file processing, scraping) — use fire-and-forget instead
+     * - Approval nodes — the stream returns `{ awaitingApproval: true }` immediately,
+     *   it does NOT wait for the approval to be resolved (that can take hours/days)
+     * - Delay nodes — if the delay exceeds the 125s timeout, the stream times out
+     *
+     * For approval workflows, use `responseMode: 'sync'` on the endpoint instead —
+     * it returns the approval status inline without blocking the SSE stream.
+     */
+    waitForResult?: boolean;
+    /**
+     * Non-blocking pipeline result callback. `send()` returns immediately with
+     * the eventId, and the callback fires in the background when the pipeline
+     * completes (via SSE stream).
+     *
+     * Same timeout limitations as `waitForResult` (125s max).
+     * For long pipelines, use WebSocket subscription instead.
+     *
+     * @example
+     * ```ts
+     * const { eventId } = await hw.send(payload, {
+     *   onResult: (result) => console.log('Pipeline done:', result.syncStatus),
+     * });
+     * // UI shows "Sent!" immediately here
+     * ```
+     */
+    onResult?: (result: SendResult) => void;
+    /**
+     * Called for each pipeline step during SSE streaming.
+     * Only fires when `onResult` or `waitForResult` is used.
+     */
+    onStep?: (step: PipelineStep) => void;
+}
+/** 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 Single-endpoint
+ * ```ts
+ * const hw = new HostWebhook({ apiKey: 'hwk_...', token: 'ingress_token' });
+ * await hw.send({ event: 'order.created' });
+ * ```
+ *
+ * @example Multi-endpoint
+ * ```ts
+ * const hw = new HostWebhook({ apiKey: 'hwk_...' });
+ * await hw.send('token_a', { event: 'order.created' });
+ * await hw.send('token_b', { event: 'user.updated' });
+ * ```
+ */
+declare class HostWebhook {
+    #private;
+    constructor(config: HostWebhookConfig);
+    /**
+     * Send a webhook payload through HostWebhook.
+     *
+     * @overload send(payload, options?) — uses default token from constructor
+     * @overload send(token, payload, options?) — specify token per call
+     *
+     * @throws {SendError} If the API returns a non-2xx status
+     * @throws {Error} If no token is available
+     */
+    send(tokenOrPayload: string | Record<string, unknown>, payloadOrOptions?: Record<string, unknown> | SendOptions, maybeOptions?: 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[]>;
+    /**
+     * Send a webhook with file attachments.
+     *
+     * Requires `apiKey` with `canvas:write` scope for file operations.
+     * Files are uploaded via presigned URLs, then references are injected into the payload.
+     *
+     * @overload sendWithFiles(payload, files, options?) — uses default token
+     * @overload sendWithFiles(token, payload, files, options?) — specify token per call
+     *
+     * @example
+     * ```ts
+     * const hw = new HostWebhook({ apiKey: 'hwk_...', token: 'ingress_token' });
+     * await hw.sendWithFiles(
+     *   { orderId: '123' },
+     *   { invoice: { data: pdfBuffer, fileName: 'inv.pdf', mimeType: 'application/pdf' } },
+     * );
+     * ```
+     */
+    sendWithFiles(tokenOrPayload: string | Record<string, unknown>, payloadOrFiles: Record<string, unknown> | Record<string, {
+        data: Buffer | Blob | Uint8Array;
+        fileName: string;
+        mimeType: string;
+    }>, filesOrOptions?: Record<string, {
+        data: Buffer | Blob | Uint8Array;
+        fileName: string;
+        mimeType: string;
+    }> | SendOptions, maybeOptions?: SendOptions): Promise<SendResult>;
+    /**
+     * Send a webhook and stream pipeline steps as an async iterable.
+     *
+     * Much simpler than `waitForResult` or `onResult` callbacks.
+     * Iteration ends when the pipeline completes. Access `stream.result`
+     * after the loop for the final pipeline result.
+     *
+     * @overload stream(payload) — uses default token
+     * @overload stream(token, payload) — specify token per call
+     *
+     * @example
+     * ```ts
+     * const hw = new HostWebhook({ apiKey: 'hwk_...', token: 'ingress_token' });
+     * const stream = await hw.stream({ event: 'order.created' });
+     *
+     * for await (const step of stream) {
+     *   console.log(`${step.nodeType}: ${step.status}`);
+     * }
+     * console.log('Done:', stream.result);
+     * ```
+     */
+    stream(tokenOrPayload: string | Record<string, unknown>, maybePayload?: Record<string, unknown>): Promise<PipelineStream>;
+}
+/**
+ * Async iterable pipeline stream. Yields PipelineStep objects as
+ * nodes execute, then completes. Access `.result` after iteration.
+ *
+ * @example
+ * ```ts
+ * const stream = await hw.stream(payload);
+ * for await (const step of stream) {
+ *   console.log(step.nodeType, step.status);
+ * }
+ * console.log(stream.result); // { syncStatus: 200, ... }
+ * ```
+ */
+declare class PipelineStream {
+    #private;
+    result: SendResult;
+    constructor(steps: PipelineStep[], result: SendResult);
+    static connect(streamUrl: string, ingressResult: SendResult): Promise<PipelineStream>;
+    [Symbol.asyncIterator](): AsyncGenerator<PipelineStep, void, undefined>;
+}
+/**
+ * Standalone send function (no class instantiation needed).
+ *
+ * @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, PipelineStream, SendError, type SendOptions, type SendResult, type StaticSignature, VerificationError, type VerifyOptions, type WebhookHeaders, createNestGuard, expressMiddleware, fastifyHook, parseHeaders, send, verify };