@hostwebhook/node 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,234 @@
+/**
+ * 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;
+
+/** Configuration for the HostWebhook client. */
+interface HostWebhookConfig {
+    /** Ingress token from your endpoint settings. */
+    token: string;
+    /** Base URL of the HostWebhook API. Default: `https://api.hostwebhook.com` */
+    baseUrl?: string;
+    /**
+     * Signing secret for incoming signature verification.
+     * When provided, every request is signed with HMAC-SHA256 using the `custom`
+     * format (`X-Webhook-Signature: sha256=<hex>`), which HostWebhook verifies
+     * if the endpoint has `incomingSignatureType: 'custom'` configured.
+     */
+    signingSecret?: string;
+    /** Custom headers to include in every request. */
+    defaultHeaders?: Record<string, string>;
+    /** Request timeout in milliseconds. Default: 10000 (10s). */
+    timeoutMs?: number;
+}
+/** 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;
+}
+/** Result returned after a successful send. */
+interface SendResult {
+    /** The event ID assigned by HostWebhook. */
+    eventId: string;
+}
+/** Thrown when the HostWebhook API returns a non-2xx response. */
+declare class SendError extends Error {
+    readonly statusCode: number;
+    readonly responseBody: string;
+    constructor(message: string, statusCode: number, responseBody: string);
+}
+
+/**
+ * HostWebhook client for sending webhooks through the platform.
+ *
+ * @example
+ * ```ts
+ * const hw = new HostWebhook({ token: 'your_ingress_token' });
+ * const { eventId } = await hw.send({ event: 'order.created', orderId: '123' });
+ * ```
+ */
+declare class HostWebhook {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly signingSecret?;
+    private readonly defaultHeaders;
+    private readonly timeoutMs;
+    constructor(config: HostWebhookConfig);
+    /**
+     * Send a webhook payload through HostWebhook.
+     *
+     * The payload is JSON-stringified and POST'd to the ingress endpoint.
+     * HostWebhook then handles delivery to the target URL with retries,
+     * monitoring, transforms, and signing.
+     *
+     * @param payload - The webhook payload (will be JSON.stringify'd)
+     * @param options - Optional per-request configuration
+     * @returns The event ID assigned by HostWebhook
+     * @throws {SendError} If the API returns a non-2xx status
+     */
+    send(payload: Record<string, unknown>, options?: SendOptions): Promise<SendResult>;
+    /**
+     * Convenience: send multiple payloads in parallel.
+     *
+     * @param payloads - Array of payloads to send
+     * @param options - Optional per-request configuration (shared for all)
+     * @returns Array of results (in same order as payloads)
+     */
+    sendBatch(payloads: Record<string, unknown>[], options?: SendOptions): Promise<SendResult[]>;
+}
+/**
+ * Standalone send function (no class instantiation needed).
+ *
+ * @example
+ * ```ts
+ * import { send } from '@hostwebhook/node';
+ * await send({ token: 'your_token' }, { event: 'test' });
+ * ```
+ */
+declare function send(config: HostWebhookConfig, payload: Record<string, unknown>, options?: SendOptions): Promise<SendResult>;
+
+export { HostWebhook, type HostWebhookConfig, SendError, type SendOptions, type SendResult, VerificationError, type VerifyOptions, type WebhookHeaders, createNestGuard, expressMiddleware, fastifyHook, parseHeaders, send, verify };

package/dist/index.d.ts

@@ -0,0 +1,234 @@
+/**
+ * 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;
+
+/** Configuration for the HostWebhook client. */
+interface HostWebhookConfig {
+    /** Ingress token from your endpoint settings. */
+    token: string;
+    /** Base URL of the HostWebhook API. Default: `https://api.hostwebhook.com` */
+    baseUrl?: string;
+    /**
+     * Signing secret for incoming signature verification.
+     * When provided, every request is signed with HMAC-SHA256 using the `custom`
+     * format (`X-Webhook-Signature: sha256=<hex>`), which HostWebhook verifies
+     * if the endpoint has `incomingSignatureType: 'custom'` configured.
+     */
+    signingSecret?: string;
+    /** Custom headers to include in every request. */
+    defaultHeaders?: Record<string, string>;
+    /** Request timeout in milliseconds. Default: 10000 (10s). */
+    timeoutMs?: number;
+}
+/** 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;
+}
+/** Result returned after a successful send. */
+interface SendResult {
+    /** The event ID assigned by HostWebhook. */
+    eventId: string;
+}
+/** Thrown when the HostWebhook API returns a non-2xx response. */
+declare class SendError extends Error {
+    readonly statusCode: number;
+    readonly responseBody: string;
+    constructor(message: string, statusCode: number, responseBody: string);
+}
+
+/**
+ * HostWebhook client for sending webhooks through the platform.
+ *
+ * @example
+ * ```ts
+ * const hw = new HostWebhook({ token: 'your_ingress_token' });
+ * const { eventId } = await hw.send({ event: 'order.created', orderId: '123' });
+ * ```
+ */
+declare class HostWebhook {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly signingSecret?;
+    private readonly defaultHeaders;
+    private readonly timeoutMs;
+    constructor(config: HostWebhookConfig);
+    /**
+     * Send a webhook payload through HostWebhook.
+     *
+     * The payload is JSON-stringified and POST'd to the ingress endpoint.
+     * HostWebhook then handles delivery to the target URL with retries,
+     * monitoring, transforms, and signing.
+     *
+     * @param payload - The webhook payload (will be JSON.stringify'd)
+     * @param options - Optional per-request configuration
+     * @returns The event ID assigned by HostWebhook
+     * @throws {SendError} If the API returns a non-2xx status
+     */
+    send(payload: Record<string, unknown>, options?: SendOptions): Promise<SendResult>;
+    /**
+     * Convenience: send multiple payloads in parallel.
+     *
+     * @param payloads - Array of payloads to send
+     * @param options - Optional per-request configuration (shared for all)
+     * @returns Array of results (in same order as payloads)
+     */
+    sendBatch(payloads: Record<string, unknown>[], options?: SendOptions): Promise<SendResult[]>;
+}
+/**
+ * Standalone send function (no class instantiation needed).
+ *
+ * @example
+ * ```ts
+ * import { send } from '@hostwebhook/node';
+ * await send({ token: 'your_token' }, { event: 'test' });
+ * ```
+ */
+declare function send(config: HostWebhookConfig, payload: Record<string, unknown>, options?: SendOptions): Promise<SendResult>;
+
+export { HostWebhook, type HostWebhookConfig, SendError, type SendOptions, type SendResult, VerificationError, type VerifyOptions, type WebhookHeaders, createNestGuard, expressMiddleware, fastifyHook, parseHeaders, send, verify };

package/dist/index.js

@@ -0,0 +1,300 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HostWebhook: () => HostWebhook,
+  SendError: () => SendError,
+  VerificationError: () => VerificationError,
+  createNestGuard: () => createNestGuard,
+  expressMiddleware: () => expressMiddleware,
+  fastifyHook: () => fastifyHook,
+  parseHeaders: () => parseHeaders,
+  send: () => send,
+  verify: () => verify
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/verify.ts
+var import_crypto = require("crypto");
+var VerificationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VerificationError";
+  }
+};
+function verify(payload, headers, secret, options) {
+  const sigHeader = getHeader(headers, "x-hostwebhook-signature");
+  if (!sigHeader) {
+    throw new VerificationError("Missing X-HostWebhook-Signature header");
+  }
+  const parts = {};
+  for (const part of sigHeader.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq > 0) {
+      parts[part.slice(0, eq).trim()] = part.slice(eq + 1).trim();
+    }
+  }
+  const { t, v1 } = parts;
+  if (!t || !v1) {
+    throw new VerificationError(
+      "Malformed X-HostWebhook-Signature: expected t=<timestamp>,v1=<signature>"
+    );
+  }
+  const timestamp = parseInt(t, 10);
+  if (isNaN(timestamp)) {
+    throw new VerificationError("Malformed timestamp in signature header");
+  }
+  const maxAge = options?.maxAgeSec ?? 300;
+  if (maxAge > 0) {
+    const drift = Math.abs(Date.now() - timestamp);
+    if (drift > maxAge * 1e3) {
+      throw new VerificationError(
+        `Signature timestamp is too old (drift: ${Math.round(drift / 1e3)}s, max: ${maxAge}s)`
+      );
+    }
+  }
+  const body = typeof payload === "string" ? payload : payload.toString("utf8");
+  const expected = (0, import_crypto.createHmac)("sha256", secret).update(`${t}.${body}`).digest("hex");
+  const expectedBuf = Buffer.from(expected, "hex");
+  const receivedBuf = Buffer.from(v1, "hex");
+  if (expectedBuf.length !== receivedBuf.length || !(0, import_crypto.timingSafeEqual)(expectedBuf, receivedBuf)) {
+    throw new VerificationError("Signature mismatch");
+  }
+}
+function getHeader(headers, key) {
+  const val = headers[key] ?? headers[key.toLowerCase()];
+  if (Array.isArray(val)) return val[0];
+  return val;
+}
+
+// src/headers.ts
+function parseHeaders(headers) {
+  const get = (key) => {
+    const val = headers[key] ?? headers[key.toLowerCase()];
+    if (Array.isArray(val)) return val[0];
+    return val;
+  };
+  const sigHeader = get("x-hostwebhook-signature") ?? "";
+  const sigParts = {};
+  for (const part of sigHeader.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq > 0) {
+      sigParts[part.slice(0, eq).trim()] = part.slice(eq + 1).trim();
+    }
+  }
+  const result = {
+    eventId: get("x-hostwebhook-event-id") ?? "",
+    attempt: parseInt(get("x-hostwebhook-attempt") ?? "1", 10) || 1,
+    timestamp: parseInt(sigParts["t"] ?? "0", 10),
+    signature: sigParts["v1"] ?? ""
+  };
+  const chainStep = get("x-hostwebhook-chain-step");
+  if (chainStep) {
+    result.chainStep = parseInt(chainStep, 10) || void 0;
+  }
+  const chainOriginal = get("x-hostwebhook-chain-original");
+  if (chainOriginal) {
+    try {
+      result.chainOriginal = JSON.parse(
+        Buffer.from(chainOriginal, "base64").toString("utf8")
+      );
+    } catch {
+      result.chainOriginal = chainOriginal;
+    }
+  }
+  const chainPrevious = get("x-hostwebhook-chain-previous");
+  if (chainPrevious) {
+    try {
+      result.chainPrevious = JSON.parse(
+        Buffer.from(chainPrevious, "base64").toString("utf8")
+      );
+    } catch {
+      result.chainPrevious = chainPrevious;
+    }
+  }
+  const chainResponse = get("x-hostwebhook-chain-response");
+  if (chainResponse) {
+    try {
+      result.chainResponse = JSON.parse(
+        Buffer.from(chainResponse, "base64").toString("utf8")
+      );
+    } catch {
+      result.chainResponse = void 0;
+    }
+  }
+  if (get("x-hostwebhook-chain-response-truncated") === "true") {
+    result.chainResponseTruncated = true;
+    const origSize = get("x-hostwebhook-chain-response-original-size");
+    if (origSize) result.chainResponseOriginalSize = parseInt(origSize, 10);
+  }
+  return result;
+}
+
+// src/middleware.ts
+function expressMiddleware(secret, options) {
+  return (req, res, next) => {
+    try {
+      verify(req.body, req.headers, secret, options);
+      next();
+    } catch (err) {
+      if (err instanceof VerificationError) {
+        res.status(401).json({ error: err.message });
+      } else {
+        next(err);
+      }
+    }
+  };
+}
+function createNestGuard(secret, options) {
+  return class HostWebhookGuard {
+    canActivate(context) {
+      const req = context.switchToHttp().getRequest();
+      verify(req.body, req.headers, secret, options);
+      return true;
+    }
+  };
+}
+function fastifyHook(secret, options) {
+  return (req, _reply, done) => {
+    try {
+      verify(req.body, req.headers, secret, options);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  };
+}
+
+// src/client.ts
+var import_crypto2 = require("crypto");
+
+// src/send-types.ts
+var SendError = class extends Error {
+  constructor(message, statusCode, responseBody) {
+    super(message);
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+    this.name = "SendError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.hostwebhook.com";
+var DEFAULT_TIMEOUT = 1e4;
+var HostWebhook = class {
+  constructor(config) {
+    if (!config.token) {
+      throw new Error("HostWebhook: token is required");
+    }
+    this.token = config.token;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.signingSecret = config.signingSecret;
+    this.defaultHeaders = config.defaultHeaders ?? {};
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT;
+  }
+  /**
+   * Send a webhook payload through HostWebhook.
+   *
+   * The payload is JSON-stringified and POST'd to the ingress endpoint.
+   * HostWebhook then handles delivery to the target URL with retries,
+   * monitoring, transforms, and signing.
+   *
+   * @param payload - The webhook payload (will be JSON.stringify'd)
+   * @param options - Optional per-request configuration
+   * @returns The event ID assigned by HostWebhook
+   * @throws {SendError} If the API returns a non-2xx status
+   */
+  async send(payload, options) {
+    const body = options?.rawBody !== void 0 ? typeof options.rawBody === "string" ? options.rawBody : options.rawBody.toString("utf8") : JSON.stringify(payload);
+    const headers = {
+      "Content-Type": options?.contentType ?? "application/json",
+      "User-Agent": "HostWebhook-SDK/1.0",
+      ...this.defaultHeaders,
+      ...options?.headers
+    };
+    if (this.signingSecret) {
+      const sig = (0, import_crypto2.createHmac)("sha256", this.signingSecret).update(body).digest("hex");
+      headers["X-Webhook-Signature"] = `sha256=${sig}`;
+    }
+    const url = `${this.baseUrl}/api/in/${this.token}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    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 {
+        return JSON.parse(text);
+      } catch {
+        return { 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 ${this.timeoutMs}ms`,
+          0,
+          ""
+        );
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /**
+   * 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)
+   */
+  async sendBatch(payloads, options) {
+    return Promise.all(payloads.map((p) => this.send(p, options)));
+  }
+};
+async function send(config, payload, options) {
+  const client = new HostWebhook(config);
+  return client.send(payload, options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HostWebhook,
+  SendError,
+  VerificationError,
+  createNestGuard,
+  expressMiddleware,
+  fastifyHook,
+  parseHeaders,
+  send,
+  verify
+});

package/dist/index.mjs

@@ -0,0 +1,265 @@
+// src/verify.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var VerificationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VerificationError";
+  }
+};
+function verify(payload, headers, secret, options) {
+  const sigHeader = getHeader(headers, "x-hostwebhook-signature");
+  if (!sigHeader) {
+    throw new VerificationError("Missing X-HostWebhook-Signature header");
+  }
+  const parts = {};
+  for (const part of sigHeader.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq > 0) {
+      parts[part.slice(0, eq).trim()] = part.slice(eq + 1).trim();
+    }
+  }
+  const { t, v1 } = parts;
+  if (!t || !v1) {
+    throw new VerificationError(
+      "Malformed X-HostWebhook-Signature: expected t=<timestamp>,v1=<signature>"
+    );
+  }
+  const timestamp = parseInt(t, 10);
+  if (isNaN(timestamp)) {
+    throw new VerificationError("Malformed timestamp in signature header");
+  }
+  const maxAge = options?.maxAgeSec ?? 300;
+  if (maxAge > 0) {
+    const drift = Math.abs(Date.now() - timestamp);
+    if (drift > maxAge * 1e3) {
+      throw new VerificationError(
+        `Signature timestamp is too old (drift: ${Math.round(drift / 1e3)}s, max: ${maxAge}s)`
+      );
+    }
+  }
+  const body = typeof payload === "string" ? payload : payload.toString("utf8");
+  const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
+  const expectedBuf = Buffer.from(expected, "hex");
+  const receivedBuf = Buffer.from(v1, "hex");
+  if (expectedBuf.length !== receivedBuf.length || !timingSafeEqual(expectedBuf, receivedBuf)) {
+    throw new VerificationError("Signature mismatch");
+  }
+}
+function getHeader(headers, key) {
+  const val = headers[key] ?? headers[key.toLowerCase()];
+  if (Array.isArray(val)) return val[0];
+  return val;
+}
+
+// src/headers.ts
+function parseHeaders(headers) {
+  const get = (key) => {
+    const val = headers[key] ?? headers[key.toLowerCase()];
+    if (Array.isArray(val)) return val[0];
+    return val;
+  };
+  const sigHeader = get("x-hostwebhook-signature") ?? "";
+  const sigParts = {};
+  for (const part of sigHeader.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq > 0) {
+      sigParts[part.slice(0, eq).trim()] = part.slice(eq + 1).trim();
+    }
+  }
+  const result = {
+    eventId: get("x-hostwebhook-event-id") ?? "",
+    attempt: parseInt(get("x-hostwebhook-attempt") ?? "1", 10) || 1,
+    timestamp: parseInt(sigParts["t"] ?? "0", 10),
+    signature: sigParts["v1"] ?? ""
+  };
+  const chainStep = get("x-hostwebhook-chain-step");
+  if (chainStep) {
+    result.chainStep = parseInt(chainStep, 10) || void 0;
+  }
+  const chainOriginal = get("x-hostwebhook-chain-original");
+  if (chainOriginal) {
+    try {
+      result.chainOriginal = JSON.parse(
+        Buffer.from(chainOriginal, "base64").toString("utf8")
+      );
+    } catch {
+      result.chainOriginal = chainOriginal;
+    }
+  }
+  const chainPrevious = get("x-hostwebhook-chain-previous");
+  if (chainPrevious) {
+    try {
+      result.chainPrevious = JSON.parse(
+        Buffer.from(chainPrevious, "base64").toString("utf8")
+      );
+    } catch {
+      result.chainPrevious = chainPrevious;
+    }
+  }
+  const chainResponse = get("x-hostwebhook-chain-response");
+  if (chainResponse) {
+    try {
+      result.chainResponse = JSON.parse(
+        Buffer.from(chainResponse, "base64").toString("utf8")
+      );
+    } catch {
+      result.chainResponse = void 0;
+    }
+  }
+  if (get("x-hostwebhook-chain-response-truncated") === "true") {
+    result.chainResponseTruncated = true;
+    const origSize = get("x-hostwebhook-chain-response-original-size");
+    if (origSize) result.chainResponseOriginalSize = parseInt(origSize, 10);
+  }
+  return result;
+}
+
+// src/middleware.ts
+function expressMiddleware(secret, options) {
+  return (req, res, next) => {
+    try {
+      verify(req.body, req.headers, secret, options);
+      next();
+    } catch (err) {
+      if (err instanceof VerificationError) {
+        res.status(401).json({ error: err.message });
+      } else {
+        next(err);
+      }
+    }
+  };
+}
+function createNestGuard(secret, options) {
+  return class HostWebhookGuard {
+    canActivate(context) {
+      const req = context.switchToHttp().getRequest();
+      verify(req.body, req.headers, secret, options);
+      return true;
+    }
+  };
+}
+function fastifyHook(secret, options) {
+  return (req, _reply, done) => {
+    try {
+      verify(req.body, req.headers, secret, options);
+      done();
+    } catch (err) {
+      done(err);
+    }
+  };
+}
+
+// src/client.ts
+import { createHmac as createHmac2 } from "crypto";
+
+// src/send-types.ts
+var SendError = class extends Error {
+  constructor(message, statusCode, responseBody) {
+    super(message);
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+    this.name = "SendError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.hostwebhook.com";
+var DEFAULT_TIMEOUT = 1e4;
+var HostWebhook = class {
+  constructor(config) {
+    if (!config.token) {
+      throw new Error("HostWebhook: token is required");
+    }
+    this.token = config.token;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.signingSecret = config.signingSecret;
+    this.defaultHeaders = config.defaultHeaders ?? {};
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT;
+  }
+  /**
+   * Send a webhook payload through HostWebhook.
+   *
+   * The payload is JSON-stringified and POST'd to the ingress endpoint.
+   * HostWebhook then handles delivery to the target URL with retries,
+   * monitoring, transforms, and signing.
+   *
+   * @param payload - The webhook payload (will be JSON.stringify'd)
+   * @param options - Optional per-request configuration
+   * @returns The event ID assigned by HostWebhook
+   * @throws {SendError} If the API returns a non-2xx status
+   */
+  async send(payload, options) {
+    const body = options?.rawBody !== void 0 ? typeof options.rawBody === "string" ? options.rawBody : options.rawBody.toString("utf8") : JSON.stringify(payload);
+    const headers = {
+      "Content-Type": options?.contentType ?? "application/json",
+      "User-Agent": "HostWebhook-SDK/1.0",
+      ...this.defaultHeaders,
+      ...options?.headers
+    };
+    if (this.signingSecret) {
+      const sig = createHmac2("sha256", this.signingSecret).update(body).digest("hex");
+      headers["X-Webhook-Signature"] = `sha256=${sig}`;
+    }
+    const url = `${this.baseUrl}/api/in/${this.token}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    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 {
+        return JSON.parse(text);
+      } catch {
+        return { 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 ${this.timeoutMs}ms`,
+          0,
+          ""
+        );
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  /**
+   * 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)
+   */
+  async sendBatch(payloads, options) {
+    return Promise.all(payloads.map((p) => this.send(p, options)));
+  }
+};
+async function send(config, payload, options) {
+  const client = new HostWebhook(config);
+  return client.send(payload, options);
+}
+export {
+  HostWebhook,
+  SendError,
+  VerificationError,
+  createNestGuard,
+  expressMiddleware,
+  fastifyHook,
+  parseHeaders,
+  send,
+  verify
+};

package/package.json

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