@hostwebhook/node 1.2.0 → 1.4.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.d.mts

@@ -154,15 +154,23 @@ interface StaticSignature {
 }
 /** Configuration for the HostWebhook client. */
 interface HostWebhookConfig {
-    /** Ingress token from your endpoint settings. */
-    token: string;
+    /**
+     * 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 `signature` for new integrations.
+     * @deprecated Prefer `apiKey` for authentication.
      */
     signingSecret?: string;
     /**
@@ -271,10 +279,17 @@ declare class SendError extends Error {
 /**
  * HostWebhook client for sending webhooks through the platform.
  *
- * @example
+ * @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({ token: 'your_ingress_token' });
- * const { eventId } = await hw.send({ event: 'order.created', orderId: '123' });
+ * 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 {
@@ -283,16 +298,13 @@ declare class HostWebhook {
     /**
      * 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
      */
-    send(payload: Record<string, unknown>, options?: SendOptions): Promise<SendResult>;
+    send(tokenOrPayload: string | Record<string, unknown>, payloadOrOptions?: Record<string, unknown> | SendOptions, maybeOptions?: SendOptions): Promise<SendResult>;
     /**
      * Convenience: send multiple payloads in parallel.
      *
@@ -301,6 +313,33 @@ declare class HostWebhook {
      * @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).

package/dist/index.d.ts

@@ -154,15 +154,23 @@ interface StaticSignature {
 }
 /** Configuration for the HostWebhook client. */
 interface HostWebhookConfig {
-    /** Ingress token from your endpoint settings. */
-    token: string;
+    /**
+     * 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 `signature` for new integrations.
+     * @deprecated Prefer `apiKey` for authentication.
      */
     signingSecret?: string;
     /**
@@ -271,10 +279,17 @@ declare class SendError extends Error {
 /**
  * HostWebhook client for sending webhooks through the platform.
  *
- * @example
+ * @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({ token: 'your_ingress_token' });
- * const { eventId } = await hw.send({ event: 'order.created', orderId: '123' });
+ * 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 {
@@ -283,16 +298,13 @@ declare class HostWebhook {
     /**
      * 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
      */
-    send(payload: Record<string, unknown>, options?: SendOptions): Promise<SendResult>;
+    send(tokenOrPayload: string | Record<string, unknown>, payloadOrOptions?: Record<string, unknown> | SendOptions, maybeOptions?: SendOptions): Promise<SendResult>;
     /**
      * Convenience: send multiple payloads in parallel.
      *
@@ -301,6 +313,33 @@ declare class HostWebhook {
      * @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).

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.2.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.
@@ -331,7 +271,74 @@ var HostWebhook = class {
   async sendBatch(payloads, options) {
     return Promise.all(payloads.map((p) => this.send(p, options)));
   }
+  /**
+   * 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' } },
+   * );
+   * ```
+   */
+  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, _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 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, _apiKey)}` }
+      });
+      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 __privateMethod(this, _HostWebhook_instances, doSend_fn).call(this, token, enrichedPayload, options);
+  }
 };
+_apiKey = new WeakMap();
 _token = new WeakMap();
 _baseUrl = new WeakMap();
 _signingSecret = new WeakMap();
@@ -339,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.2.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.
@@ -298,7 +238,74 @@ var HostWebhook = class {
   async sendBatch(payloads, options) {
     return Promise.all(payloads.map((p) => this.send(p, options)));
   }
+  /**
+   * 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' } },
+   * );
+   * ```
+   */
+  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, _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 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, _apiKey)}` }
+      });
+      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 __privateMethod(this, _HostWebhook_instances, doSend_fn).call(this, token, enrichedPayload, options);
+  }
 };
+_apiKey = new WeakMap();
 _token = new WeakMap();
 _baseUrl = new WeakMap();
 _signingSecret = new WeakMap();
@@ -306,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.2.0",
+  "version": "1.4.0",
   "description": "Official HostWebhook SDK — verify signatures, parse headers, and send webhooks",
   "main": "dist/index.js",
   "module": "dist/index.mjs",