@hostwebhook/node 1.3.0 → 1.4.0

package/dist/index.d.mts

@@ -0,0 +1,355 @@
+/**
+ * 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).
+     */
+    waitForResult?: boolean;
+    /**
+     * Non-blocking pipeline result callback. `send()` returns immediately with
+     * the eventId, and the callback fires in the background when the pipeline
+     * completes (via SSE stream). Perfect for UIs that shouldn't block.
+     *
+     * Requires the endpoint to be in `none` response mode (async).
+     *
+     * @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>;
+}
+/**
+ * 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

@@ -0,0 +1,355 @@
+/**
+ * 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).
+     */
+    waitForResult?: boolean;
+    /**
+     * Non-blocking pipeline result callback. `send()` returns immediately with
+     * the eventId, and the callback fires in the background when the pipeline
+     * completes (via SSE stream). Perfect for UIs that shouldn't block.
+     *
+     * Requires the endpoint to be in `none` response mode (async).
+     *
+     * @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>;
+}
+/**
+ * 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.js

@@ -207,24 +207,26 @@ 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, _HostWebhook_instances, waitForStream_fn;
+var _apiKey, _token, _baseUrl, _signingSecret, _signature, _defaultHeaders, _timeoutMs, _HostWebhook_instances, doSend_fn, waitForStream_fn;
 var HostWebhook = class {
   constructor(config) {
     __privateAdd(this, _HostWebhook_instances);
+    __privateAdd(this, _apiKey);
     __privateAdd(this, _token);
     __privateAdd(this, _baseUrl);
     __privateAdd(this, _signingSecret);
     __privateAdd(this, _signature);
     __privateAdd(this, _defaultHeaders);
     __privateAdd(this, _timeoutMs);
-    if (!config.token) {
-      throw new Error("HostWebhook: token is required");
+    if (!config.apiKey && !config.token) {
+      throw new Error("HostWebhook: apiKey or token is required");
     }
     if (config.signingSecret && config.signature) {
       throw new Error(
         "HostWebhook: use either signingSecret or signature, not both"
       );
     }
+    __privateSet(this, _apiKey, config.apiKey);
     __privateSet(this, _token, config.token);
     __privateSet(this, _baseUrl, (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""));
     __privateSet(this, _signingSecret, config.signingSecret);
@@ -235,91 +237,29 @@ var HostWebhook = class {
   /**
    * 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.
+   * @overload send(payload, options?) — uses default token from constructor
+   * @overload send(token, payload, options?) — specify token per call
    *
-   * @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
+   * @throws {Error} If no token is available
    */
-  async send(payload, options) {
-    const body = options?.rawBody !== void 0 ? typeof options.rawBody === "string" ? options.rawBody : options.rawBody.toString("utf8") : JSON.stringify(payload);
-    let tz = "";
-    try {
-      tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
-    } catch {
-    }
-    const headers = {
-      "Content-Type": options?.contentType ?? "application/json",
-      "User-Agent": `HostWebhook-SDK/${"1.3.0"}`,
-      "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
-      ...tz ? { "X-HostWebhook-Timezone": tz } : {},
-      ...__privateGet(this, _defaultHeaders),
-      ...options?.headers
-    };
-    if (__privateGet(this, _signature)?.type === "static") {
-      const { secret, header } = __privateGet(this, _signature);
-      if (header) {
-        headers[header] = secret;
-      } else {
-        headers["Authorization"] = `Bearer ${secret}`;
+  async send(tokenOrPayload, payloadOrOptions, maybeOptions) {
+    let token;
+    let payload;
+    let options;
+    if (typeof tokenOrPayload === "string") {
+      token = tokenOrPayload;
+      payload = payloadOrOptions ?? {};
+      options = maybeOptions;
+    } else {
+      if (!__privateGet(this, _token)) {
+        throw new Error("HostWebhook: no default token set \u2014 pass token as first argument: send(token, payload)");
       }
-    } else if (__privateGet(this, _signingSecret)) {
-      const timestamp = Math.floor(Date.now() / 1e3);
-      const sig = (0, import_crypto2.createHmac)("sha256", __privateGet(this, _signingSecret)).update(`${timestamp}.${body}`).digest("hex");
-      headers["X-HostWebhook-Signature"] = `t=${timestamp},v1=${sig}`;
+      token = __privateGet(this, _token);
+      payload = tokenOrPayload;
+      options = payloadOrOptions;
     }
-    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",
-        headers,
-        body,
-        signal: controller.signal
-      });
-      const text = await res.text();
-      if (!res.ok) {
-        throw new SendError(
-          `HostWebhook ingress error (${res.status}): ${text}`,
-          res.status,
-          text
-        );
-      }
-      try {
-        ingressResult = JSON.parse(text);
-      } catch {
-        ingressResult = { eventId: text };
-      }
-    } catch (err) {
-      if (err instanceof SendError) throw err;
-      if (err instanceof DOMException && err.name === "AbortError") {
-        throw new SendError(
-          `HostWebhook request timed out after ${__privateGet(this, _timeoutMs)}ms`,
-          0,
-          ""
-        );
-      }
-      throw err;
-    } finally {
-      clearTimeout(timer);
-    }
-    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, 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;
+    return __privateMethod(this, _HostWebhook_instances, doSend_fn).call(this, token, payload, options);
   }
   /**
    * Convenience: send multiple payloads in parallel.
@@ -334,41 +274,60 @@ var HostWebhook = class {
   /**
    * 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.
+   * Requires `apiKey` with `canvas:write` scope for file operations.
+   * Files are uploaded via presigned URLs, then references are injected into the payload.
    *
-   * @param payload - The webhook payload
-   * @param files - Map of field name → file (Buffer or Blob with metadata)
-   * @param options - Optional per-request configuration
+   * @overload sendWithFiles(payload, files, options?) — uses default token
+   * @overload sendWithFiles(token, payload, files, options?) — specify token per call
    *
    * @example
    * ```ts
-   * const hw = new HostWebhook({ token: 'your_token' });
+   * const hw = new HostWebhook({ apiKey: 'hwk_...', token: 'ingress_token' });
    * await hw.sendWithFiles(
-   *   { orderId: '123', type: 'invoice' },
+   *   { orderId: '123' },
    *   { invoice: { data: pdfBuffer, fileName: 'inv.pdf', mimeType: 'application/pdf' } },
    * );
    * ```
    */
-  async sendWithFiles(payload, files, options) {
+  async sendWithFiles(tokenOrPayload, payloadOrFiles, filesOrOptions, maybeOptions) {
+    let token;
+    let payload;
+    let files;
+    let options;
+    if (typeof tokenOrPayload === "string") {
+      token = tokenOrPayload;
+      payload = payloadOrFiles;
+      files = filesOrOptions ?? {};
+      options = maybeOptions;
+    } else {
+      if (!__privateGet(this, _token)) {
+        throw new Error("HostWebhook: no default token set \u2014 pass token as first argument");
+      }
+      token = __privateGet(this, _token);
+      payload = tokenOrPayload;
+      files = payloadOrFiles ?? {};
+      options = filesOrOptions;
+    }
+    if (!__privateGet(this, _apiKey)) {
+      throw new Error("HostWebhook: apiKey is required for sendWithFiles (needs canvas:write scope)");
+    }
     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)}`
+          "Authorization": `Bearer ${__privateGet(this, _apiKey)}`
         },
         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 });
+      const putRes = await fetch(uploadUrl, { method: "PUT", headers: { "Content-Type": file.mimeType }, body: file.data });
       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)}` }
+        headers: { "Authorization": `Bearer ${__privateGet(this, _apiKey)}` }
       });
       if (!confirmRes.ok) throw new SendError(`Failed to confirm upload for ${fieldName}`, confirmRes.status, await confirmRes.text());
       const confirmed = await confirmRes.json();
@@ -376,9 +335,10 @@ var HostWebhook = class {
         _file: { id: confirmed.id, key, originalName: confirmed.originalName, mimeType: confirmed.mimeType, size: confirmed.size }
       };
     }
-    return this.send(enrichedPayload, options);
+    return __privateMethod(this, _HostWebhook_instances, doSend_fn).call(this, token, enrichedPayload, options);
   }
 };
+_apiKey = new WeakMap();
 _token = new WeakMap();
 _baseUrl = new WeakMap();
 _signingSecret = new WeakMap();
@@ -386,6 +346,88 @@ _signature = new WeakMap();
 _defaultHeaders = new WeakMap();
 _timeoutMs = new WeakMap();
 _HostWebhook_instances = new WeakSet();
+doSend_fn = async function(token, payload, options) {
+  const body = options?.rawBody !== void 0 ? typeof options.rawBody === "string" ? options.rawBody : options.rawBody.toString("utf8") : JSON.stringify(payload);
+  let tz = "";
+  try {
+    tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  } catch {
+  }
+  const headers = {
+    "Content-Type": options?.contentType ?? "application/json",
+    "User-Agent": `HostWebhook-SDK/${"1.4.0"}`,
+    "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
+    ...tz ? { "X-HostWebhook-Timezone": tz } : {},
+    ...__privateGet(this, _defaultHeaders),
+    ...options?.headers
+  };
+  if (__privateGet(this, _apiKey)) {
+    headers["Authorization"] = `Bearer ${__privateGet(this, _apiKey)}`;
+  }
+  if (!__privateGet(this, _apiKey)) {
+    if (__privateGet(this, _signature)?.type === "static") {
+      const { secret, header } = __privateGet(this, _signature);
+      if (header) {
+        headers[header] = secret;
+      } else {
+        headers["Authorization"] = `Bearer ${secret}`;
+      }
+    } else if (__privateGet(this, _signingSecret)) {
+      const timestamp = Math.floor(Date.now() / 1e3);
+      const sig = (0, import_crypto2.createHmac)("sha256", __privateGet(this, _signingSecret)).update(`${timestamp}.${body}`).digest("hex");
+      headers["X-HostWebhook-Signature"] = `t=${timestamp},v1=${sig}`;
+    }
+  }
+  const url = `${__privateGet(this, _baseUrl)}/api/in/${token}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), __privateGet(this, _timeoutMs));
+  let ingressResult;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers,
+      body,
+      signal: controller.signal
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      throw new SendError(
+        `HostWebhook ingress error (${res.status}): ${text}`,
+        res.status,
+        text
+      );
+    }
+    try {
+      ingressResult = JSON.parse(text);
+    } catch {
+      ingressResult = { eventId: text };
+    }
+  } catch (err) {
+    if (err instanceof SendError) throw err;
+    if (err instanceof DOMException && err.name === "AbortError") {
+      throw new SendError(
+        `HostWebhook request timed out after ${__privateGet(this, _timeoutMs)}ms`,
+        0,
+        ""
+      );
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+  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, 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;
+};
 waitForStream_fn = async function(ingressResult, onStep) {
   const { eventId, streamToken } = ingressResult;
   const streamUrl = `${__privateGet(this, _baseUrl)}/api/events/${eventId}/stream?token=${streamToken}`;

package/dist/index.mjs

@@ -174,24 +174,26 @@ 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, _HostWebhook_instances, waitForStream_fn;
+var _apiKey, _token, _baseUrl, _signingSecret, _signature, _defaultHeaders, _timeoutMs, _HostWebhook_instances, doSend_fn, waitForStream_fn;
 var HostWebhook = class {
   constructor(config) {
     __privateAdd(this, _HostWebhook_instances);
+    __privateAdd(this, _apiKey);
     __privateAdd(this, _token);
     __privateAdd(this, _baseUrl);
     __privateAdd(this, _signingSecret);
     __privateAdd(this, _signature);
     __privateAdd(this, _defaultHeaders);
     __privateAdd(this, _timeoutMs);
-    if (!config.token) {
-      throw new Error("HostWebhook: token is required");
+    if (!config.apiKey && !config.token) {
+      throw new Error("HostWebhook: apiKey or token is required");
     }
     if (config.signingSecret && config.signature) {
       throw new Error(
         "HostWebhook: use either signingSecret or signature, not both"
       );
     }
+    __privateSet(this, _apiKey, config.apiKey);
     __privateSet(this, _token, config.token);
     __privateSet(this, _baseUrl, (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, ""));
     __privateSet(this, _signingSecret, config.signingSecret);
@@ -202,91 +204,29 @@ var HostWebhook = class {
   /**
    * 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.
+   * @overload send(payload, options?) — uses default token from constructor
+   * @overload send(token, payload, options?) — specify token per call
    *
-   * @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
+   * @throws {Error} If no token is available
    */
-  async send(payload, options) {
-    const body = options?.rawBody !== void 0 ? typeof options.rawBody === "string" ? options.rawBody : options.rawBody.toString("utf8") : JSON.stringify(payload);
-    let tz = "";
-    try {
-      tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
-    } catch {
-    }
-    const headers = {
-      "Content-Type": options?.contentType ?? "application/json",
-      "User-Agent": `HostWebhook-SDK/${"1.3.0"}`,
-      "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
-      ...tz ? { "X-HostWebhook-Timezone": tz } : {},
-      ...__privateGet(this, _defaultHeaders),
-      ...options?.headers
-    };
-    if (__privateGet(this, _signature)?.type === "static") {
-      const { secret, header } = __privateGet(this, _signature);
-      if (header) {
-        headers[header] = secret;
-      } else {
-        headers["Authorization"] = `Bearer ${secret}`;
+  async send(tokenOrPayload, payloadOrOptions, maybeOptions) {
+    let token;
+    let payload;
+    let options;
+    if (typeof tokenOrPayload === "string") {
+      token = tokenOrPayload;
+      payload = payloadOrOptions ?? {};
+      options = maybeOptions;
+    } else {
+      if (!__privateGet(this, _token)) {
+        throw new Error("HostWebhook: no default token set \u2014 pass token as first argument: send(token, payload)");
       }
-    } else if (__privateGet(this, _signingSecret)) {
-      const timestamp = Math.floor(Date.now() / 1e3);
-      const sig = createHmac2("sha256", __privateGet(this, _signingSecret)).update(`${timestamp}.${body}`).digest("hex");
-      headers["X-HostWebhook-Signature"] = `t=${timestamp},v1=${sig}`;
+      token = __privateGet(this, _token);
+      payload = tokenOrPayload;
+      options = payloadOrOptions;
     }
-    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",
-        headers,
-        body,
-        signal: controller.signal
-      });
-      const text = await res.text();
-      if (!res.ok) {
-        throw new SendError(
-          `HostWebhook ingress error (${res.status}): ${text}`,
-          res.status,
-          text
-        );
-      }
-      try {
-        ingressResult = JSON.parse(text);
-      } catch {
-        ingressResult = { eventId: text };
-      }
-    } catch (err) {
-      if (err instanceof SendError) throw err;
-      if (err instanceof DOMException && err.name === "AbortError") {
-        throw new SendError(
-          `HostWebhook request timed out after ${__privateGet(this, _timeoutMs)}ms`,
-          0,
-          ""
-        );
-      }
-      throw err;
-    } finally {
-      clearTimeout(timer);
-    }
-    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, 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;
+    return __privateMethod(this, _HostWebhook_instances, doSend_fn).call(this, token, payload, options);
   }
   /**
    * Convenience: send multiple payloads in parallel.
@@ -301,41 +241,60 @@ var HostWebhook = class {
   /**
    * 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.
+   * Requires `apiKey` with `canvas:write` scope for file operations.
+   * Files are uploaded via presigned URLs, then references are injected into the payload.
    *
-   * @param payload - The webhook payload
-   * @param files - Map of field name → file (Buffer or Blob with metadata)
-   * @param options - Optional per-request configuration
+   * @overload sendWithFiles(payload, files, options?) — uses default token
+   * @overload sendWithFiles(token, payload, files, options?) — specify token per call
    *
    * @example
    * ```ts
-   * const hw = new HostWebhook({ token: 'your_token' });
+   * const hw = new HostWebhook({ apiKey: 'hwk_...', token: 'ingress_token' });
    * await hw.sendWithFiles(
-   *   { orderId: '123', type: 'invoice' },
+   *   { orderId: '123' },
    *   { invoice: { data: pdfBuffer, fileName: 'inv.pdf', mimeType: 'application/pdf' } },
    * );
    * ```
    */
-  async sendWithFiles(payload, files, options) {
+  async sendWithFiles(tokenOrPayload, payloadOrFiles, filesOrOptions, maybeOptions) {
+    let token;
+    let payload;
+    let files;
+    let options;
+    if (typeof tokenOrPayload === "string") {
+      token = tokenOrPayload;
+      payload = payloadOrFiles;
+      files = filesOrOptions ?? {};
+      options = maybeOptions;
+    } else {
+      if (!__privateGet(this, _token)) {
+        throw new Error("HostWebhook: no default token set \u2014 pass token as first argument");
+      }
+      token = __privateGet(this, _token);
+      payload = tokenOrPayload;
+      files = payloadOrFiles ?? {};
+      options = filesOrOptions;
+    }
+    if (!__privateGet(this, _apiKey)) {
+      throw new Error("HostWebhook: apiKey is required for sendWithFiles (needs canvas:write scope)");
+    }
     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)}`
+          "Authorization": `Bearer ${__privateGet(this, _apiKey)}`
         },
         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 });
+      const putRes = await fetch(uploadUrl, { method: "PUT", headers: { "Content-Type": file.mimeType }, body: file.data });
       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)}` }
+        headers: { "Authorization": `Bearer ${__privateGet(this, _apiKey)}` }
       });
       if (!confirmRes.ok) throw new SendError(`Failed to confirm upload for ${fieldName}`, confirmRes.status, await confirmRes.text());
       const confirmed = await confirmRes.json();
@@ -343,9 +302,10 @@ var HostWebhook = class {
         _file: { id: confirmed.id, key, originalName: confirmed.originalName, mimeType: confirmed.mimeType, size: confirmed.size }
       };
     }
-    return this.send(enrichedPayload, options);
+    return __privateMethod(this, _HostWebhook_instances, doSend_fn).call(this, token, enrichedPayload, options);
   }
 };
+_apiKey = new WeakMap();
 _token = new WeakMap();
 _baseUrl = new WeakMap();
 _signingSecret = new WeakMap();
@@ -353,6 +313,88 @@ _signature = new WeakMap();
 _defaultHeaders = new WeakMap();
 _timeoutMs = new WeakMap();
 _HostWebhook_instances = new WeakSet();
+doSend_fn = async function(token, payload, options) {
+  const body = options?.rawBody !== void 0 ? typeof options.rawBody === "string" ? options.rawBody : options.rawBody.toString("utf8") : JSON.stringify(payload);
+  let tz = "";
+  try {
+    tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  } catch {
+  }
+  const headers = {
+    "Content-Type": options?.contentType ?? "application/json",
+    "User-Agent": `HostWebhook-SDK/${"1.4.0"}`,
+    "X-HostWebhook-Sent-At": (/* @__PURE__ */ new Date()).toISOString(),
+    ...tz ? { "X-HostWebhook-Timezone": tz } : {},
+    ...__privateGet(this, _defaultHeaders),
+    ...options?.headers
+  };
+  if (__privateGet(this, _apiKey)) {
+    headers["Authorization"] = `Bearer ${__privateGet(this, _apiKey)}`;
+  }
+  if (!__privateGet(this, _apiKey)) {
+    if (__privateGet(this, _signature)?.type === "static") {
+      const { secret, header } = __privateGet(this, _signature);
+      if (header) {
+        headers[header] = secret;
+      } else {
+        headers["Authorization"] = `Bearer ${secret}`;
+      }
+    } else if (__privateGet(this, _signingSecret)) {
+      const timestamp = Math.floor(Date.now() / 1e3);
+      const sig = createHmac2("sha256", __privateGet(this, _signingSecret)).update(`${timestamp}.${body}`).digest("hex");
+      headers["X-HostWebhook-Signature"] = `t=${timestamp},v1=${sig}`;
+    }
+  }
+  const url = `${__privateGet(this, _baseUrl)}/api/in/${token}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), __privateGet(this, _timeoutMs));
+  let ingressResult;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers,
+      body,
+      signal: controller.signal
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      throw new SendError(
+        `HostWebhook ingress error (${res.status}): ${text}`,
+        res.status,
+        text
+      );
+    }
+    try {
+      ingressResult = JSON.parse(text);
+    } catch {
+      ingressResult = { eventId: text };
+    }
+  } catch (err) {
+    if (err instanceof SendError) throw err;
+    if (err instanceof DOMException && err.name === "AbortError") {
+      throw new SendError(
+        `HostWebhook request timed out after ${__privateGet(this, _timeoutMs)}ms`,
+        0,
+        ""
+      );
+    }
+    throw err;
+  } finally {
+    clearTimeout(timer);
+  }
+  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, 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;
+};
 waitForStream_fn = async function(ingressResult, onStep) {
   const { eventId, streamToken } = ingressResult;
   const streamUrl = `${__privateGet(this, _baseUrl)}/api/events/${eventId}/stream?token=${streamToken}`;

package/package.json

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