@rotorsoft/act-http 1.2.0 → 1.3.0

package/dist/webhook/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/webhook/index.ts","../../src/webhook/types.ts","../../src/webhook/classify.ts","../../src/webhook/sign.ts"],"sourcesContent":["/**\n * @packageDocumentation\n * @module act-http/webhook\n *\n * Reaction-handler sugar for POSTing committed events to external URLs.\n *\n * Wraps `fetch` with timeouts, automatic `Idempotency-Key` derivation, and\n * status-classified errors. Designed to be composed with the reaction\n * options shipped in ACT-601 (`maxRetries`, `blockOnError`, `backoff`):\n *\n * ```ts\n * import { webhook } from \"@rotorsoft/act-http/webhook\";\n *\n * .on(\"OrderConfirmed\")\n *   .do(\n *     webhook({\n *       url: \"https://api.example.com/webhooks/orders\",\n *       headers: (e) => ({ Authorization: \"Bearer ...\" }),\n *       body: (e) => ({ orderId: e.stream, total: e.data.total }),\n *       timeoutMs: 5_000,\n *     }),\n *     { maxRetries: 5, backoff: { strategy: \"exponential\", baseMs: 200, maxMs: 30_000 } }\n *   )\n *   .to(resolver);\n * ```\n */\n\nimport type { Committed, ReactionHandler, Schemas } from \"@rotorsoft/act\";\nimport { classifyHttpResponse } from \"./classify.js\";\nimport { signRequest } from \"./sign.js\";\nimport {\n  NonRetryableWebhookError,\n  type WebhookConfig,\n  WebhookError,\n} from \"./types.js\";\n\nexport {\n  classifyHttpResponse,\n  type HttpDisposition,\n  type TryOkOptions,\n  tryOk,\n} from \"./classify.js\";\nexport type {\n  HttpDeliveryErrorInit,\n  WebhookBody,\n  WebhookConfig,\n  WebhookResolver,\n} from \"./types.js\";\nexport {\n  NonRetryableHttpError,\n  NonRetryableWebhookError,\n  RetryableHttpError,\n  WebhookError,\n} from \"./types.js\";\n\nfunction resolve<TEvents extends Schemas, T>(\n  resolver: T | ((e: Committed<TEvents, keyof TEvents>) => T) | undefined,\n  event: Committed<TEvents, keyof TEvents>,\n  fallback: T\n): T {\n  if (resolver === undefined) return fallback;\n  return typeof resolver === \"function\"\n    ? (resolver as (e: Committed<TEvents, keyof TEvents>) => T)(event)\n    : resolver;\n}\n\n/** Case-insensitive lookup; returns true if a header is already set. */\nfunction hasHeader(headers: Record<string, string>, name: string): boolean {\n  const lower = name.toLowerCase();\n  for (const k of Object.keys(headers)) {\n    if (k.toLowerCase() === lower) return true;\n  }\n  return false;\n}\n\n/**\n * Build a reaction handler that POSTs each event to an external URL.\n *\n * Behavior:\n *\n * - 2xx and 3xx return successfully.\n * - 5xx responses, network errors, and timeouts throw\n *   {@link WebhookError} (`status: 0` for network/timeout). Drain\n *   retries per the reaction's `maxRetries` / `backoff`.\n * - 4xx responses throw {@link NonRetryableWebhookError}, which\n *   extends `NonRetryableError`. The drain finalizer blocks the\n *   stream immediately (when `blockOnError` is true) without\n *   consuming the retry budget.\n */\nexport function webhook<TEvents extends Schemas = Schemas>(\n  config: WebhookConfig<TEvents>\n): ReactionHandler<TEvents, keyof TEvents> {\n  const timeoutMs = config.timeoutMs ?? 5_000;\n  const method = config.method ?? \"POST\";\n  const fetchImpl = config.fetch ?? globalThis.fetch;\n\n  // Named function: slice/act builders require non-anonymous reaction\n  // handlers so lifecycle telemetry can attribute work.\n  return async function webhookDeliver(event) {\n    const url = resolve(config.url, event, \"\");\n\n    const customHeaders = resolve(\n      config.headers,\n      event,\n      {} as Record<string, string>\n    );\n    const headers: Record<string, string> = { ...customHeaders };\n\n    if (!hasHeader(headers, \"content-type\")) {\n      headers[\"Content-Type\"] = \"application/json\";\n    }\n    if (!hasHeader(headers, \"idempotency-key\")) {\n      const key = config.idempotencyKey\n        ? config.idempotencyKey(event)\n        : String(event.id);\n      if (key !== null) headers[\"Idempotency-Key\"] = key;\n    }\n\n    const rawBody = resolve(config.body, event, event as unknown);\n    const body =\n      typeof rawBody === \"string\" ? rawBody : JSON.stringify(rawBody);\n\n    if (config.secret && !hasHeader(headers, \"x-webhook-signature\")) {\n      const { signature, timestamp } = signRequest(body, config.secret);\n      headers[\"X-Webhook-Signature\"] = signature;\n      if (!hasHeader(headers, \"x-webhook-timestamp\")) {\n        headers[\"X-Webhook-Timestamp\"] = timestamp;\n      }\n    }\n\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), timeoutMs);\n\n    let response: Response;\n    try {\n      response = await fetchImpl(url, {\n        method,\n        headers,\n        body,\n        signal: controller.signal,\n      });\n    } catch (err) {\n      const aborted = controller.signal.aborted;\n      throw new WebhookError(\n        aborted\n          ? `webhook ${method} ${url} timed out after ${timeoutMs}ms`\n          : `webhook ${method} ${url} failed: ${(err as Error).message}`,\n        { status: 0, url }\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n\n    const disposition = classifyHttpResponse(response);\n    if (disposition === \"ok\") return;\n\n    let responseBody: string | undefined;\n    try {\n      responseBody = await response.text();\n    } catch {\n      // best-effort body capture; ignore read errors\n    }\n\n    const ErrorClass =\n      disposition === \"retry\" ? WebhookError : NonRetryableWebhookError;\n    throw new ErrorClass(\n      `webhook ${method} ${url} responded ${response.status}`,\n      { status: response.status, url, responseBody }\n    );\n  };\n}\n","import {\n  type Committed,\n  NonRetryableError,\n  type Schemas,\n} from \"@rotorsoft/act\";\n\n/**\n * Function or static value resolver. Used so callers can pass either a\n * constant or a per-event function for headers / body / url.\n *\n * The static side `T` is constrained to non-function types so that a\n * passed `(event) => ...` is unambiguously typed as the function variant.\n */\nexport type WebhookResolver<TEvents extends Schemas, T> =\n  | T\n  | ((event: Committed<TEvents, keyof TEvents>) => T);\n\n/**\n * Plain-data body shape the helper accepts as a static value. Functions\n * are deliberately excluded so the union with the resolver function is\n * unambiguous at the call site (TypeScript can discriminate by shape).\n */\nexport type WebhookBody =\n  | string\n  | { readonly [k: string]: unknown }\n  | readonly unknown[];\n\n/**\n * Configuration for {@link webhook}.\n *\n * @template TEvents - Event schemas; resolvers receive the typed committed event.\n */\nexport type WebhookConfig<TEvents extends Schemas = Schemas> = {\n  /** Target URL — static string or per-event function. */\n  readonly url: WebhookResolver<TEvents, string>;\n  /** HTTP method. Defaults to `\"POST\"`. */\n  readonly method?: \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\";\n  /**\n   * Headers to send. Resolver may return a record per event. The\n   * `Content-Type: application/json` and `Idempotency-Key` headers are\n   * applied automatically; both can be overridden by returning a header\n   * with the same name (case-insensitive).\n   */\n  readonly headers?: WebhookResolver<TEvents, Record<string, string>>;\n  /**\n   * Request body. Static plain data (object, array, string) or a\n   * per-event function returning the same. Strings are sent as-is;\n   * anything else is JSON-serialized. Defaults to the committed event\n   * itself.\n   */\n  readonly body?:\n    | WebhookBody\n    | ((event: Committed<TEvents, keyof TEvents>) => WebhookBody);\n  /**\n   * Per-request timeout in milliseconds. Defaults to 5000.\n   * The handler throws after the timeout via `AbortController`.\n   */\n  readonly timeoutMs?: number;\n  /**\n   * Override for the auto-generated `Idempotency-Key`. By default, the\n   * helper sends `event.id` (the immutable, monotonic event identifier).\n   * Return a string to override; return `null` to skip the header entirely.\n   */\n  readonly idempotencyKey?: (\n    event: Committed<TEvents, keyof TEvents>\n  ) => string | null;\n  /**\n   * Injection point for tests. Defaults to global `fetch`.\n   */\n  readonly fetch?: typeof fetch;\n  /**\n   * HMAC-SHA256 signing key. When set, the webhook helper attaches\n   * two headers to every request:\n   *\n   * - `X-Webhook-Signature: sha256=<hex>` — HMAC of\n   *   `${timestamp}.${body}` (`body` is the final serialized payload)\n   * - `X-Webhook-Timestamp: <unix-seconds>`\n   *\n   * Pair with `verifyWebhook` from `@rotorsoft/act-http/receiver` on\n   * the receiving side. When undefined, no signature headers are\n   * added — back-compat with consumers that don't need signing.\n   *\n   * Callers can override either header by returning it from the\n   * `headers` resolver (case-insensitive), the same way the\n   * `Idempotency-Key` and `Content-Type` defaults yield to caller\n   * intent.\n   */\n  readonly secret?: string;\n};\n\n/**\n * Common fields carried on every HTTP delivery error in this package.\n */\nexport type HttpDeliveryErrorInit = {\n  status: number;\n  url: string;\n  responseBody?: string;\n};\n\n/**\n * Thrown when an HTTP delivery fails in a way the drain pipeline\n * should retry: network failure, timeout, or 5xx response. `status` is\n * `0` for network / timeout errors, the HTTP status code otherwise.\n *\n * The class itself is the retry signal — if a reaction throws this,\n * drain treats it like any other error (counts against `maxRetries`,\n * paces with `backoff`). For permanent failures, throw\n * {@link NonRetryableHttpError} instead.\n *\n * Generic enough to cover any custom HTTP-like integration (gRPC\n * bridges, SDK-based reactions). {@link WebhookError} is a\n * webhook-specific subclass kept for backward compatibility.\n */\nexport class RetryableHttpError extends Error {\n  readonly status: number;\n  readonly url: string;\n  readonly responseBody?: string;\n\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message);\n    this.name = \"RetryableHttpError\";\n    this.status = init.status;\n    this.url = init.url;\n    this.responseBody = init.responseBody;\n  }\n}\n\n/**\n * Thrown when an HTTP delivery returns a 3xx or 4xx response —\n * permanent client errors that won't recover on retry. Extends\n * {@link NonRetryableError} so the drain finalizer blocks the stream\n * on the first failed attempt (when `blockOnError` is true) — no\n * wasted retries on a malformed payload or wrong URL.\n *\n * Generic enough to cover any custom HTTP-like integration.\n * {@link NonRetryableWebhookError} is a webhook-specific subclass kept\n * for backward compatibility.\n */\nexport class NonRetryableHttpError extends NonRetryableError {\n  readonly status: number;\n  readonly url: string;\n  readonly responseBody?: string;\n\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message);\n    this.name = \"NonRetryableHttpError\";\n    this.status = init.status;\n    this.url = init.url;\n    this.responseBody = init.responseBody;\n  }\n}\n\n/**\n * Webhook-specific subclass of {@link RetryableHttpError}. Thrown by\n * the {@link webhook} helper on 5xx responses, network failures, and\n * timeouts. Existing `instanceof WebhookError` checks continue to\n * work; new code targeting the generic HTTP integration shape can\n * catch {@link RetryableHttpError} instead and handle webhook +\n * custom integrations uniformly.\n */\nexport class WebhookError extends RetryableHttpError {\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message, init);\n    this.name = \"WebhookError\";\n  }\n}\n\n/**\n * Webhook-specific subclass of {@link NonRetryableHttpError}. Thrown\n * by the {@link webhook} helper on 3xx/4xx responses. Existing\n * `instanceof NonRetryableWebhookError` checks continue to work; new\n * code can catch {@link NonRetryableHttpError} or\n * {@link NonRetryableError} for broader coverage.\n */\nexport class NonRetryableWebhookError extends NonRetryableHttpError {\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message, init);\n    this.name = \"NonRetryableWebhookError\";\n  }\n}\n","import { NonRetryableHttpError, RetryableHttpError } from \"./types.js\";\n\n/**\n * Three buckets for an HTTP response from an outbound delivery:\n *\n * - `ok` — the receiver accepted the delivery (2xx). Stop and return.\n * - `retry` — the receiver had a transient problem (5xx). Throw a\n *   retryable error; drain will pace the next attempt per `backoff`.\n * - `block` — the receiver rejected the delivery permanently (3xx\n *   or 4xx). Throw a non-retryable error; drain blocks the stream\n *   on the first failed attempt (when `blockOnError` is true) and\n *   surfaces it via the `\"blocked\"` lifecycle event.\n *\n * The 3xx → `block` mapping is intentional: a redirect at the\n * delivery layer means the configured URL is wrong, and retrying\n * the same URL won't fix that. Manual operator review is the right\n * next step, which is what the block path produces.\n */\nexport type HttpDisposition = \"ok\" | \"retry\" | \"block\";\n\n/**\n * Classify an HTTP response as `ok` (2xx), `retry` (5xx), or\n * `block` (3xx, 4xx). The classification {@link webhook} uses\n * internally, lifted here so custom integrations (gRPC bridges,\n * SDK-based reactions, etc.) can apply the same retry semantics\n * without inventing a parallel rule.\n */\nexport function classifyHttpResponse(response: Response): HttpDisposition {\n  if (response.ok) return \"ok\";\n  if (response.status >= 500) return \"retry\";\n  return \"block\";\n}\n\n/** Options for {@link tryOk}. */\nexport type TryOkOptions = {\n  /** The endpoint that received the request. Surfaced on the thrown error and in its message. */\n  url: string;\n  /**\n   * Label prefixed onto the error message — typically the\n   * integration's identity (`\"webhook\"`, `\"mySdk\"`, `\"grpc\"`).\n   * Default: `\"request\"`.\n   */\n  label?: string;\n};\n\n/**\n * If `response` is 2xx, return. Otherwise, capture the response body\n * (best-effort) and throw a {@link RetryableHttpError} (for 5xx) or\n * {@link NonRetryableHttpError} (for 3xx/4xx). Collapses the\n * classify-and-throw boilerplate every custom HTTP-like reaction\n * would otherwise write into one line:\n *\n * ```ts\n * .on(\"OrderConfirmed\").do(async (event) => {\n *   const response = await mySdk.deliver(event);\n *   await tryOk(response, { url: mySdk.url, label: \"mySdk\" });\n *   // ...response was 2xx; continue with downstream work...\n * });\n * ```\n *\n * The {@link webhook} helper throws webhook-specific subclasses\n * ({@link WebhookError} / {@link NonRetryableWebhookError}) for\n * backward compatibility — both extend the generic classes thrown\n * here, so `instanceof RetryableHttpError` matches both webhook and\n * custom-integration errors uniformly.\n */\nexport async function tryOk(\n  response: Response,\n  options: TryOkOptions\n): Promise<void> {\n  const disposition = classifyHttpResponse(response);\n  if (disposition === \"ok\") return;\n\n  let responseBody: string | undefined;\n  try {\n    responseBody = await response.text();\n  } catch {\n    // best-effort body capture; ignore read errors\n  }\n\n  const label = options.label ?? \"request\";\n  const ErrorClass =\n    disposition === \"retry\" ? RetryableHttpError : NonRetryableHttpError;\n  throw new ErrorClass(`${label} ${options.url} responded ${response.status}`, {\n    status: response.status,\n    url: options.url,\n    responseBody,\n  });\n}\n","import { createHmac } from \"node:crypto\";\n\n/**\n * Compute the HMAC-SHA256 signature for an outbound webhook request.\n *\n * The signed payload is `${timestamp}.${body}` — Stripe-style. The\n * timestamp is included so the receiver can reject replays via a\n * window check, and the dot separator prevents `timestamp + body`\n * ambiguity (12 + 345 vs 123 + 45).\n *\n * Returns `{ signature, timestamp }` so the webhook helper can attach\n * both as headers — `X-Webhook-Signature: sha256=<hex>` and\n * `X-Webhook-Timestamp: <unix-seconds>` — for the receiver to verify\n * via `verifyWebhook` from `@rotorsoft/act-http/receiver`.\n *\n * `now` is exposed for tests; production callers should leave it\n * undefined so wall-clock is used.\n *\n * @internal Reachable from tests via the source path. Not re-exported\n *   from the package's `./webhook` entry — the webhook helper calls\n *   it internally, and operators don't need it directly.\n */\nexport function signRequest(\n  body: string,\n  secret: string,\n  now: number = Math.floor(Date.now() / 1000)\n): { signature: string; timestamp: string } {\n  const timestamp = String(now);\n  const payload = `${timestamp}.${body}`;\n  const hex = createHmac(\"sha256\", secret).update(payload).digest(\"hex\");\n  return { signature: `sha256=${hex}`, timestamp };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/webhook/index.ts","../../src/webhook/types.ts","../../src/webhook/classify.ts","../../src/webhook/sign.ts"],"sourcesContent":["/**\n * @packageDocumentation\n * @module act-http/webhook\n *\n * Reaction-handler sugar for POSTing committed events to external URLs.\n *\n * Wraps `fetch` with timeouts, automatic `Idempotency-Key` derivation, and\n * status-classified errors. Designed to be composed with the reaction\n * options shipped in ACT-601 (`maxRetries`, `blockOnError`, `backoff`):\n *\n * ```ts\n * import { webhook } from \"@rotorsoft/act-http/webhook\";\n *\n * .on(\"OrderConfirmed\")\n *   .do(\n *     webhook({\n *       url: \"https://api.example.com/webhooks/orders\",\n *       headers: (e) => ({ Authorization: \"Bearer ...\" }),\n *       body: (e) => ({ orderId: e.stream, total: e.data.total }),\n *       timeoutMs: 5_000,\n *     }),\n *     { maxRetries: 5, backoff: { strategy: \"exponential\", baseMs: 200, maxMs: 30_000 } }\n *   )\n *   .to(resolver);\n * ```\n */\n\nimport type { Committed, ReactionHandler, Schemas } from \"@rotorsoft/act\";\nimport { classify_http_response } from \"./classify.js\";\nimport { sign_request } from \"./sign.js\";\nimport {\n  NonRetryableWebhookError,\n  type WebhookConfig,\n  WebhookError,\n} from \"./types.js\";\n\nexport type { HttpDisposition } from \"./classify.js\";\nexport type {\n  HttpDeliveryErrorInit,\n  WebhookBody,\n  WebhookConfig,\n  WebhookResolver,\n} from \"./types.js\";\nexport {\n  NonRetryableHttpError,\n  NonRetryableWebhookError,\n  RetryableHttpError,\n  WebhookError,\n} from \"./types.js\";\n\nfunction resolve<TEvents extends Schemas, T>(\n  resolver: T | ((e: Committed<TEvents, keyof TEvents>) => T) | undefined,\n  event: Committed<TEvents, keyof TEvents>,\n  fallback: T\n): T {\n  if (resolver === undefined) return fallback;\n  return typeof resolver === \"function\"\n    ? (resolver as (e: Committed<TEvents, keyof TEvents>) => T)(event)\n    : resolver;\n}\n\n/** Case-insensitive lookup; returns true if a header is already set. */\nfunction has_header(headers: Record<string, string>, name: string): boolean {\n  const lower = name.toLowerCase();\n  for (const k of Object.keys(headers)) {\n    if (k.toLowerCase() === lower) return true;\n  }\n  return false;\n}\n\n/**\n * Build a reaction handler that POSTs each event to an external URL.\n *\n * Behavior:\n *\n * - 2xx and 3xx return successfully.\n * - 5xx responses, network errors, and timeouts throw\n *   {@link WebhookError} (`status: 0` for network/timeout). Drain\n *   retries per the reaction's `maxRetries` / `backoff`.\n * - 4xx responses throw {@link NonRetryableWebhookError}, which\n *   extends `NonRetryableError`. The drain finalizer blocks the\n *   stream immediately (when `blockOnError` is true) without\n *   consuming the retry budget.\n */\nexport function webhook<TEvents extends Schemas = Schemas>(\n  config: WebhookConfig<TEvents>\n): ReactionHandler<TEvents, keyof TEvents> {\n  const timeoutMs = config.timeoutMs ?? 5_000;\n  const method = config.method ?? \"POST\";\n  const fetch_impl = config.fetch ?? globalThis.fetch;\n\n  // Named function: slice/act builders require non-anonymous reaction\n  // handlers so lifecycle telemetry can attribute work.\n  return async function webhook_deliver(event) {\n    const url = resolve(config.url, event, \"\");\n\n    const custom_headers = resolve(\n      config.headers,\n      event,\n      {} as Record<string, string>\n    );\n    const headers: Record<string, string> = { ...custom_headers };\n\n    if (!has_header(headers, \"content-type\")) {\n      headers[\"Content-Type\"] = \"application/json\";\n    }\n    if (!has_header(headers, \"idempotency-key\")) {\n      const key = config.idempotencyKey\n        ? config.idempotencyKey(event)\n        : String(event.id);\n      if (key !== null) headers[\"Idempotency-Key\"] = key;\n    }\n\n    const rawBody = resolve(config.body, event, event as unknown);\n    const body =\n      typeof rawBody === \"string\" ? rawBody : JSON.stringify(rawBody);\n\n    if (config.secret && !has_header(headers, \"x-webhook-signature\")) {\n      const { signature, timestamp } = sign_request(body, config.secret);\n      headers[\"X-Webhook-Signature\"] = signature;\n      if (!has_header(headers, \"x-webhook-timestamp\")) {\n        headers[\"X-Webhook-Timestamp\"] = timestamp;\n      }\n    }\n\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), timeoutMs);\n\n    let response: Response;\n    try {\n      response = await fetch_impl(url, {\n        method,\n        headers,\n        body,\n        signal: controller.signal,\n      });\n    } catch (err) {\n      const aborted = controller.signal.aborted;\n      throw new WebhookError(\n        aborted\n          ? `webhook ${method} ${url} timed out after ${timeoutMs}ms`\n          : `webhook ${method} ${url} failed: ${(err as Error).message}`,\n        { status: 0, url }\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n\n    const disposition = classify_http_response(response);\n    if (disposition === \"ok\") return;\n\n    let responseBody: string | undefined;\n    try {\n      responseBody = await response.text();\n    } catch {\n      // best-effort body capture; ignore read errors\n    }\n\n    const ErrorClass =\n      disposition === \"retry\" ? WebhookError : NonRetryableWebhookError;\n    throw new ErrorClass(\n      `webhook ${method} ${url} responded ${response.status}`,\n      { status: response.status, url, responseBody }\n    );\n  };\n}\n","import {\n  type Committed,\n  NonRetryableError,\n  type Schemas,\n} from \"@rotorsoft/act\";\n\n/**\n * Function or static value resolver. Used so callers can pass either a\n * constant or a per-event function for headers / body / url.\n *\n * The static side `T` is constrained to non-function types so that a\n * passed `(event) => ...` is unambiguously typed as the function variant.\n */\nexport type WebhookResolver<TEvents extends Schemas, T> =\n  | T\n  | ((event: Committed<TEvents, keyof TEvents>) => T);\n\n/**\n * Plain-data body shape the helper accepts as a static value. Functions\n * are deliberately excluded so the union with the resolver function is\n * unambiguous at the call site (TypeScript can discriminate by shape).\n */\nexport type WebhookBody =\n  | string\n  | { readonly [k: string]: unknown }\n  | readonly unknown[];\n\n/**\n * Configuration for {@link webhook}.\n *\n * @template TEvents - Event schemas; resolvers receive the typed committed event.\n */\nexport type WebhookConfig<TEvents extends Schemas = Schemas> = {\n  /** Target URL — static string or per-event function. */\n  readonly url: WebhookResolver<TEvents, string>;\n  /** HTTP method. Defaults to `\"POST\"`. */\n  readonly method?: \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\";\n  /**\n   * Headers to send. Resolver may return a record per event. The\n   * `Content-Type: application/json` and `Idempotency-Key` headers are\n   * applied automatically; both can be overridden by returning a header\n   * with the same name (case-insensitive).\n   */\n  readonly headers?: WebhookResolver<TEvents, Record<string, string>>;\n  /**\n   * Request body. Static plain data (object, array, string) or a\n   * per-event function returning the same. Strings are sent as-is;\n   * anything else is JSON-serialized. Defaults to the committed event\n   * itself.\n   */\n  readonly body?:\n    | WebhookBody\n    | ((event: Committed<TEvents, keyof TEvents>) => WebhookBody);\n  /**\n   * Per-request timeout in milliseconds. Defaults to 5000.\n   * The handler throws after the timeout via `AbortController`.\n   */\n  readonly timeoutMs?: number;\n  /**\n   * Override for the auto-generated `Idempotency-Key`. By default, the\n   * helper sends `event.id` (the immutable, monotonic event identifier).\n   * Return a string to override; return `null` to skip the header entirely.\n   */\n  readonly idempotencyKey?: (\n    event: Committed<TEvents, keyof TEvents>\n  ) => string | null;\n  /**\n   * Injection point for tests. Defaults to global `fetch`.\n   */\n  readonly fetch?: typeof fetch;\n  /**\n   * HMAC-SHA256 signing key. When set, the webhook helper attaches\n   * two headers to every request:\n   *\n   * - `X-Webhook-Signature: sha256=<hex>` — HMAC of\n   *   `${timestamp}.${body}` (`body` is the final serialized payload)\n   * - `X-Webhook-Timestamp: <unix-seconds>`\n   *\n   * Pair with `verifyWebhook` from `@rotorsoft/act-http/receiver` on\n   * the receiving side. When undefined, no signature headers are\n   * added — back-compat with consumers that don't need signing.\n   *\n   * Callers can override either header by returning it from the\n   * `headers` resolver (case-insensitive), the same way the\n   * `Idempotency-Key` and `Content-Type` defaults yield to caller\n   * intent.\n   */\n  readonly secret?: string;\n};\n\n/**\n * Common fields carried on every HTTP delivery error in this package.\n */\nexport type HttpDeliveryErrorInit = {\n  status: number;\n  url: string;\n  responseBody?: string;\n};\n\n/**\n * Thrown when an HTTP delivery fails in a way the drain pipeline\n * should retry: network failure, timeout, or 5xx response. `status` is\n * `0` for network / timeout errors, the HTTP status code otherwise.\n *\n * The class itself is the retry signal — if a reaction throws this,\n * drain treats it like any other error (counts against `maxRetries`,\n * paces with `backoff`). For permanent failures, throw\n * {@link NonRetryableHttpError} instead.\n *\n * Generic enough to cover any custom HTTP-like integration (gRPC\n * bridges, SDK-based reactions). {@link WebhookError} is a\n * webhook-specific subclass kept for backward compatibility.\n */\nexport class RetryableHttpError extends Error {\n  readonly status: number;\n  readonly url: string;\n  readonly responseBody?: string;\n\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message);\n    this.name = \"RetryableHttpError\";\n    this.status = init.status;\n    this.url = init.url;\n    this.responseBody = init.responseBody;\n  }\n}\n\n/**\n * Thrown when an HTTP delivery returns a 3xx or 4xx response —\n * permanent client errors that won't recover on retry. Extends\n * {@link NonRetryableError} so the drain finalizer blocks the stream\n * on the first failed attempt (when `blockOnError` is true) — no\n * wasted retries on a malformed payload or wrong URL.\n *\n * Generic enough to cover any custom HTTP-like integration.\n * {@link NonRetryableWebhookError} is a webhook-specific subclass kept\n * for backward compatibility.\n */\nexport class NonRetryableHttpError extends NonRetryableError {\n  readonly status: number;\n  readonly url: string;\n  readonly responseBody?: string;\n\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message);\n    this.name = \"NonRetryableHttpError\";\n    this.status = init.status;\n    this.url = init.url;\n    this.responseBody = init.responseBody;\n  }\n}\n\n/**\n * Webhook-specific subclass of {@link RetryableHttpError}. Thrown by\n * the {@link webhook} helper on 5xx responses, network failures, and\n * timeouts. Existing `instanceof WebhookError` checks continue to\n * work; new code targeting the generic HTTP integration shape can\n * catch {@link RetryableHttpError} instead and handle webhook +\n * custom integrations uniformly.\n */\nexport class WebhookError extends RetryableHttpError {\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message, init);\n    this.name = \"WebhookError\";\n  }\n}\n\n/**\n * Webhook-specific subclass of {@link NonRetryableHttpError}. Thrown\n * by the {@link webhook} helper on 3xx/4xx responses. Existing\n * `instanceof NonRetryableWebhookError` checks continue to work; new\n * code can catch {@link NonRetryableHttpError} or\n * {@link NonRetryableError} for broader coverage.\n */\nexport class NonRetryableWebhookError extends NonRetryableHttpError {\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message, init);\n    this.name = \"NonRetryableWebhookError\";\n  }\n}\n","import { NonRetryableHttpError, RetryableHttpError } from \"./types.js\";\n\n/**\n * Three buckets for an HTTP response from an outbound delivery:\n *\n * - `ok` — the receiver accepted the delivery (2xx). Stop and return.\n * - `retry` — the receiver had a transient problem (5xx). Throw a\n *   retryable error; drain will pace the next attempt per `backoff`.\n * - `block` — the receiver rejected the delivery permanently (3xx\n *   or 4xx). Throw a non-retryable error; drain blocks the stream\n *   on the first failed attempt (when `blockOnError` is true) and\n *   surfaces it via the `\"blocked\"` lifecycle event.\n *\n * The 3xx → `block` mapping is intentional: a redirect at the\n * delivery layer means the configured URL is wrong, and retrying\n * the same URL won't fix that. Manual operator review is the right\n * next step, which is what the block path produces.\n */\nexport type HttpDisposition = \"ok\" | \"retry\" | \"block\";\n\n/**\n * Classify an HTTP response as `ok` (2xx), `retry` (5xx), or\n * `block` (3xx, 4xx). The classification {@link webhook} uses\n * internally, lifted here so custom integrations (gRPC bridges,\n * SDK-based reactions, etc.) can apply the same retry semantics\n * without inventing a parallel rule.\n */\nexport function classify_http_response(response: Response): HttpDisposition {\n  if (response.ok) return \"ok\";\n  if (response.status >= 500) return \"retry\";\n  return \"block\";\n}\n\n/** Options for {@link try_ok}. */\nexport type TryOkOptions = {\n  /** The endpoint that received the request. Surfaced on the thrown error and in its message. */\n  url: string;\n  /**\n   * Label prefixed onto the error message — typically the\n   * integration's identity (`\"webhook\"`, `\"my_sdk\"`, `\"grpc\"`).\n   * Default: `\"request\"`.\n   */\n  label?: string;\n};\n\n/**\n * If `response` is 2xx, return. Otherwise, capture the response body\n * (best-effort) and throw a {@link RetryableHttpError} (for 5xx) or\n * {@link NonRetryableHttpError} (for 3xx/4xx). Collapses the\n * classify-and-throw boilerplate every custom HTTP-like reaction\n * would otherwise write into one line:\n *\n * ```ts\n * .on(\"OrderConfirmed\").do(async (event) => {\n *   const response = await my_sdk.deliver(event);\n *   await try_ok(response, { url: my_sdk.url, label: \"my_sdk\" });\n *   // ...response was 2xx; continue with downstream work...\n * });\n * ```\n *\n * The {@link webhook} helper throws webhook-specific subclasses\n * ({@link WebhookError} / {@link NonRetryableWebhookError}) for\n * backward compatibility — both extend the generic classes thrown\n * here, so `instanceof RetryableHttpError` matches both webhook and\n * custom-integration errors uniformly.\n */\nexport async function try_ok(\n  response: Response,\n  options: TryOkOptions\n): Promise<void> {\n  const disposition = classify_http_response(response);\n  if (disposition === \"ok\") return;\n\n  let responseBody: string | undefined;\n  try {\n    responseBody = await response.text();\n  } catch {\n    // best-effort body capture; ignore read errors\n  }\n\n  const label = options.label ?? \"request\";\n  const ErrorClass =\n    disposition === \"retry\" ? RetryableHttpError : NonRetryableHttpError;\n  throw new ErrorClass(`${label} ${options.url} responded ${response.status}`, {\n    status: response.status,\n    url: options.url,\n    responseBody,\n  });\n}\n","import { createHmac } from \"node:crypto\";\n\n/**\n * Compute the HMAC-SHA256 signature for an outbound webhook request.\n *\n * The signed payload is `${timestamp}.${body}` — Stripe-style. The\n * timestamp is included so the receiver can reject replays via a\n * window check, and the dot separator prevents `timestamp + body`\n * ambiguity (12 + 345 vs 123 + 45).\n *\n * Returns `{ signature, timestamp }` so the webhook helper can attach\n * both as headers — `X-Webhook-Signature: sha256=<hex>` and\n * `X-Webhook-Timestamp: <unix-seconds>` — for the receiver to verify\n * via `verifyWebhook` from `@rotorsoft/act-http/receiver`.\n *\n * `now` is exposed for tests; production callers should leave it\n * undefined so wall-clock is used.\n *\n * @internal Reachable from tests via the source path. Not re-exported\n *   from the package's `./webhook` entry — the webhook helper calls\n *   it internally, and operators don't need it directly.\n */\nexport function sign_request(\n  body: string,\n  secret: string,\n  now: number = Math.floor(Date.now() / 1000)\n): { signature: string; timestamp: string } {\n  const timestamp = String(now);\n  const payload = `${timestamp}.${body}`;\n  const hex = createHmac(\"sha256\", secret).update(payload).digest(\"hex\");\n  return { signature: `sha256=${hex}`, timestamp };\n}\n"],"mappings":"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","names":[]}

package/dist/webhook/index.js

@@ -40,31 +40,15 @@ var NonRetryableWebhookError = class extends NonRetryableHttpError {
 };
 
 // src/webhook/classify.ts
-function classifyHttpResponse(response) {
+function classify_http_response(response) {
   if (response.ok) return "ok";
   if (response.status >= 500) return "retry";
   return "block";
 }
-async function tryOk(response, options) {
-  const disposition = classifyHttpResponse(response);
-  if (disposition === "ok") return;
-  let responseBody;
-  try {
-    responseBody = await response.text();
-  } catch {
-  }
-  const label = options.label ?? "request";
-  const ErrorClass = disposition === "retry" ? RetryableHttpError : NonRetryableHttpError;
-  throw new ErrorClass(`${label} ${options.url} responded ${response.status}`, {
-    status: response.status,
-    url: options.url,
-    responseBody
-  });
-}
 
 // src/webhook/sign.ts
 import { createHmac } from "crypto";
-function signRequest(body, secret, now = Math.floor(Date.now() / 1e3)) {
+function sign_request(body, secret, now = Math.floor(Date.now() / 1e3)) {
   const timestamp = String(now);
   const payload = `${timestamp}.${body}`;
   const hex = createHmac("sha256", secret).update(payload).digest("hex");
@@ -76,7 +60,7 @@ function resolve(resolver, event, fallback) {
   if (resolver === void 0) return fallback;
   return typeof resolver === "function" ? resolver(event) : resolver;
 }
-function hasHeader(headers, name) {
+function has_header(headers, name) {
   const lower = name.toLowerCase();
   for (const k of Object.keys(headers)) {
     if (k.toLowerCase() === lower) return true;
@@ -86,28 +70,28 @@ function hasHeader(headers, name) {
 function webhook(config) {
   const timeoutMs = config.timeoutMs ?? 5e3;
   const method = config.method ?? "POST";
-  const fetchImpl = config.fetch ?? globalThis.fetch;
-  return async function webhookDeliver(event) {
+  const fetch_impl = config.fetch ?? globalThis.fetch;
+  return async function webhook_deliver(event) {
     const url = resolve(config.url, event, "");
-    const customHeaders = resolve(
+    const custom_headers = resolve(
       config.headers,
       event,
       {}
     );
-    const headers = { ...customHeaders };
-    if (!hasHeader(headers, "content-type")) {
+    const headers = { ...custom_headers };
+    if (!has_header(headers, "content-type")) {
       headers["Content-Type"] = "application/json";
     }
-    if (!hasHeader(headers, "idempotency-key")) {
+    if (!has_header(headers, "idempotency-key")) {
       const key = config.idempotencyKey ? config.idempotencyKey(event) : String(event.id);
       if (key !== null) headers["Idempotency-Key"] = key;
     }
     const rawBody = resolve(config.body, event, event);
     const body = typeof rawBody === "string" ? rawBody : JSON.stringify(rawBody);
-    if (config.secret && !hasHeader(headers, "x-webhook-signature")) {
-      const { signature, timestamp } = signRequest(body, config.secret);
+    if (config.secret && !has_header(headers, "x-webhook-signature")) {
+      const { signature, timestamp } = sign_request(body, config.secret);
       headers["X-Webhook-Signature"] = signature;
-      if (!hasHeader(headers, "x-webhook-timestamp")) {
+      if (!has_header(headers, "x-webhook-timestamp")) {
         headers["X-Webhook-Timestamp"] = timestamp;
       }
     }
@@ -115,7 +99,7 @@ function webhook(config) {
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     let response;
     try {
-      response = await fetchImpl(url, {
+      response = await fetch_impl(url, {
         method,
         headers,
         body,
@@ -130,7 +114,7 @@ function webhook(config) {
     } finally {
       clearTimeout(timer);
     }
-    const disposition = classifyHttpResponse(response);
+    const disposition = classify_http_response(response);
     if (disposition === "ok") return;
     let responseBody;
     try {
@@ -149,8 +133,6 @@ export {
   NonRetryableWebhookError,
   RetryableHttpError,
   WebhookError,
-  classifyHttpResponse,
-  tryOk,
   webhook
 };
 //# sourceMappingURL=index.js.map

package/dist/webhook/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/webhook/types.ts","../../src/webhook/classify.ts","../../src/webhook/sign.ts","../../src/webhook/index.ts"],"sourcesContent":["import {\n  type Committed,\n  NonRetryableError,\n  type Schemas,\n} from \"@rotorsoft/act\";\n\n/**\n * Function or static value resolver. Used so callers can pass either a\n * constant or a per-event function for headers / body / url.\n *\n * The static side `T` is constrained to non-function types so that a\n * passed `(event) => ...` is unambiguously typed as the function variant.\n */\nexport type WebhookResolver<TEvents extends Schemas, T> =\n  | T\n  | ((event: Committed<TEvents, keyof TEvents>) => T);\n\n/**\n * Plain-data body shape the helper accepts as a static value. Functions\n * are deliberately excluded so the union with the resolver function is\n * unambiguous at the call site (TypeScript can discriminate by shape).\n */\nexport type WebhookBody =\n  | string\n  | { readonly [k: string]: unknown }\n  | readonly unknown[];\n\n/**\n * Configuration for {@link webhook}.\n *\n * @template TEvents - Event schemas; resolvers receive the typed committed event.\n */\nexport type WebhookConfig<TEvents extends Schemas = Schemas> = {\n  /** Target URL — static string or per-event function. */\n  readonly url: WebhookResolver<TEvents, string>;\n  /** HTTP method. Defaults to `\"POST\"`. */\n  readonly method?: \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\";\n  /**\n   * Headers to send. Resolver may return a record per event. The\n   * `Content-Type: application/json` and `Idempotency-Key` headers are\n   * applied automatically; both can be overridden by returning a header\n   * with the same name (case-insensitive).\n   */\n  readonly headers?: WebhookResolver<TEvents, Record<string, string>>;\n  /**\n   * Request body. Static plain data (object, array, string) or a\n   * per-event function returning the same. Strings are sent as-is;\n   * anything else is JSON-serialized. Defaults to the committed event\n   * itself.\n   */\n  readonly body?:\n    | WebhookBody\n    | ((event: Committed<TEvents, keyof TEvents>) => WebhookBody);\n  /**\n   * Per-request timeout in milliseconds. Defaults to 5000.\n   * The handler throws after the timeout via `AbortController`.\n   */\n  readonly timeoutMs?: number;\n  /**\n   * Override for the auto-generated `Idempotency-Key`. By default, the\n   * helper sends `event.id` (the immutable, monotonic event identifier).\n   * Return a string to override; return `null` to skip the header entirely.\n   */\n  readonly idempotencyKey?: (\n    event: Committed<TEvents, keyof TEvents>\n  ) => string | null;\n  /**\n   * Injection point for tests. Defaults to global `fetch`.\n   */\n  readonly fetch?: typeof fetch;\n  /**\n   * HMAC-SHA256 signing key. When set, the webhook helper attaches\n   * two headers to every request:\n   *\n   * - `X-Webhook-Signature: sha256=<hex>` — HMAC of\n   *   `${timestamp}.${body}` (`body` is the final serialized payload)\n   * - `X-Webhook-Timestamp: <unix-seconds>`\n   *\n   * Pair with `verifyWebhook` from `@rotorsoft/act-http/receiver` on\n   * the receiving side. When undefined, no signature headers are\n   * added — back-compat with consumers that don't need signing.\n   *\n   * Callers can override either header by returning it from the\n   * `headers` resolver (case-insensitive), the same way the\n   * `Idempotency-Key` and `Content-Type` defaults yield to caller\n   * intent.\n   */\n  readonly secret?: string;\n};\n\n/**\n * Common fields carried on every HTTP delivery error in this package.\n */\nexport type HttpDeliveryErrorInit = {\n  status: number;\n  url: string;\n  responseBody?: string;\n};\n\n/**\n * Thrown when an HTTP delivery fails in a way the drain pipeline\n * should retry: network failure, timeout, or 5xx response. `status` is\n * `0` for network / timeout errors, the HTTP status code otherwise.\n *\n * The class itself is the retry signal — if a reaction throws this,\n * drain treats it like any other error (counts against `maxRetries`,\n * paces with `backoff`). For permanent failures, throw\n * {@link NonRetryableHttpError} instead.\n *\n * Generic enough to cover any custom HTTP-like integration (gRPC\n * bridges, SDK-based reactions). {@link WebhookError} is a\n * webhook-specific subclass kept for backward compatibility.\n */\nexport class RetryableHttpError extends Error {\n  readonly status: number;\n  readonly url: string;\n  readonly responseBody?: string;\n\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message);\n    this.name = \"RetryableHttpError\";\n    this.status = init.status;\n    this.url = init.url;\n    this.responseBody = init.responseBody;\n  }\n}\n\n/**\n * Thrown when an HTTP delivery returns a 3xx or 4xx response —\n * permanent client errors that won't recover on retry. Extends\n * {@link NonRetryableError} so the drain finalizer blocks the stream\n * on the first failed attempt (when `blockOnError` is true) — no\n * wasted retries on a malformed payload or wrong URL.\n *\n * Generic enough to cover any custom HTTP-like integration.\n * {@link NonRetryableWebhookError} is a webhook-specific subclass kept\n * for backward compatibility.\n */\nexport class NonRetryableHttpError extends NonRetryableError {\n  readonly status: number;\n  readonly url: string;\n  readonly responseBody?: string;\n\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message);\n    this.name = \"NonRetryableHttpError\";\n    this.status = init.status;\n    this.url = init.url;\n    this.responseBody = init.responseBody;\n  }\n}\n\n/**\n * Webhook-specific subclass of {@link RetryableHttpError}. Thrown by\n * the {@link webhook} helper on 5xx responses, network failures, and\n * timeouts. Existing `instanceof WebhookError` checks continue to\n * work; new code targeting the generic HTTP integration shape can\n * catch {@link RetryableHttpError} instead and handle webhook +\n * custom integrations uniformly.\n */\nexport class WebhookError extends RetryableHttpError {\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message, init);\n    this.name = \"WebhookError\";\n  }\n}\n\n/**\n * Webhook-specific subclass of {@link NonRetryableHttpError}. Thrown\n * by the {@link webhook} helper on 3xx/4xx responses. Existing\n * `instanceof NonRetryableWebhookError` checks continue to work; new\n * code can catch {@link NonRetryableHttpError} or\n * {@link NonRetryableError} for broader coverage.\n */\nexport class NonRetryableWebhookError extends NonRetryableHttpError {\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message, init);\n    this.name = \"NonRetryableWebhookError\";\n  }\n}\n","import { NonRetryableHttpError, RetryableHttpError } from \"./types.js\";\n\n/**\n * Three buckets for an HTTP response from an outbound delivery:\n *\n * - `ok` — the receiver accepted the delivery (2xx). Stop and return.\n * - `retry` — the receiver had a transient problem (5xx). Throw a\n *   retryable error; drain will pace the next attempt per `backoff`.\n * - `block` — the receiver rejected the delivery permanently (3xx\n *   or 4xx). Throw a non-retryable error; drain blocks the stream\n *   on the first failed attempt (when `blockOnError` is true) and\n *   surfaces it via the `\"blocked\"` lifecycle event.\n *\n * The 3xx → `block` mapping is intentional: a redirect at the\n * delivery layer means the configured URL is wrong, and retrying\n * the same URL won't fix that. Manual operator review is the right\n * next step, which is what the block path produces.\n */\nexport type HttpDisposition = \"ok\" | \"retry\" | \"block\";\n\n/**\n * Classify an HTTP response as `ok` (2xx), `retry` (5xx), or\n * `block` (3xx, 4xx). The classification {@link webhook} uses\n * internally, lifted here so custom integrations (gRPC bridges,\n * SDK-based reactions, etc.) can apply the same retry semantics\n * without inventing a parallel rule.\n */\nexport function classifyHttpResponse(response: Response): HttpDisposition {\n  if (response.ok) return \"ok\";\n  if (response.status >= 500) return \"retry\";\n  return \"block\";\n}\n\n/** Options for {@link tryOk}. */\nexport type TryOkOptions = {\n  /** The endpoint that received the request. Surfaced on the thrown error and in its message. */\n  url: string;\n  /**\n   * Label prefixed onto the error message — typically the\n   * integration's identity (`\"webhook\"`, `\"mySdk\"`, `\"grpc\"`).\n   * Default: `\"request\"`.\n   */\n  label?: string;\n};\n\n/**\n * If `response` is 2xx, return. Otherwise, capture the response body\n * (best-effort) and throw a {@link RetryableHttpError} (for 5xx) or\n * {@link NonRetryableHttpError} (for 3xx/4xx). Collapses the\n * classify-and-throw boilerplate every custom HTTP-like reaction\n * would otherwise write into one line:\n *\n * ```ts\n * .on(\"OrderConfirmed\").do(async (event) => {\n *   const response = await mySdk.deliver(event);\n *   await tryOk(response, { url: mySdk.url, label: \"mySdk\" });\n *   // ...response was 2xx; continue with downstream work...\n * });\n * ```\n *\n * The {@link webhook} helper throws webhook-specific subclasses\n * ({@link WebhookError} / {@link NonRetryableWebhookError}) for\n * backward compatibility — both extend the generic classes thrown\n * here, so `instanceof RetryableHttpError` matches both webhook and\n * custom-integration errors uniformly.\n */\nexport async function tryOk(\n  response: Response,\n  options: TryOkOptions\n): Promise<void> {\n  const disposition = classifyHttpResponse(response);\n  if (disposition === \"ok\") return;\n\n  let responseBody: string | undefined;\n  try {\n    responseBody = await response.text();\n  } catch {\n    // best-effort body capture; ignore read errors\n  }\n\n  const label = options.label ?? \"request\";\n  const ErrorClass =\n    disposition === \"retry\" ? RetryableHttpError : NonRetryableHttpError;\n  throw new ErrorClass(`${label} ${options.url} responded ${response.status}`, {\n    status: response.status,\n    url: options.url,\n    responseBody,\n  });\n}\n","import { createHmac } from \"node:crypto\";\n\n/**\n * Compute the HMAC-SHA256 signature for an outbound webhook request.\n *\n * The signed payload is `${timestamp}.${body}` — Stripe-style. The\n * timestamp is included so the receiver can reject replays via a\n * window check, and the dot separator prevents `timestamp + body`\n * ambiguity (12 + 345 vs 123 + 45).\n *\n * Returns `{ signature, timestamp }` so the webhook helper can attach\n * both as headers — `X-Webhook-Signature: sha256=<hex>` and\n * `X-Webhook-Timestamp: <unix-seconds>` — for the receiver to verify\n * via `verifyWebhook` from `@rotorsoft/act-http/receiver`.\n *\n * `now` is exposed for tests; production callers should leave it\n * undefined so wall-clock is used.\n *\n * @internal Reachable from tests via the source path. Not re-exported\n *   from the package's `./webhook` entry — the webhook helper calls\n *   it internally, and operators don't need it directly.\n */\nexport function signRequest(\n  body: string,\n  secret: string,\n  now: number = Math.floor(Date.now() / 1000)\n): { signature: string; timestamp: string } {\n  const timestamp = String(now);\n  const payload = `${timestamp}.${body}`;\n  const hex = createHmac(\"sha256\", secret).update(payload).digest(\"hex\");\n  return { signature: `sha256=${hex}`, timestamp };\n}\n","/**\n * @packageDocumentation\n * @module act-http/webhook\n *\n * Reaction-handler sugar for POSTing committed events to external URLs.\n *\n * Wraps `fetch` with timeouts, automatic `Idempotency-Key` derivation, and\n * status-classified errors. Designed to be composed with the reaction\n * options shipped in ACT-601 (`maxRetries`, `blockOnError`, `backoff`):\n *\n * ```ts\n * import { webhook } from \"@rotorsoft/act-http/webhook\";\n *\n * .on(\"OrderConfirmed\")\n *   .do(\n *     webhook({\n *       url: \"https://api.example.com/webhooks/orders\",\n *       headers: (e) => ({ Authorization: \"Bearer ...\" }),\n *       body: (e) => ({ orderId: e.stream, total: e.data.total }),\n *       timeoutMs: 5_000,\n *     }),\n *     { maxRetries: 5, backoff: { strategy: \"exponential\", baseMs: 200, maxMs: 30_000 } }\n *   )\n *   .to(resolver);\n * ```\n */\n\nimport type { Committed, ReactionHandler, Schemas } from \"@rotorsoft/act\";\nimport { classifyHttpResponse } from \"./classify.js\";\nimport { signRequest } from \"./sign.js\";\nimport {\n  NonRetryableWebhookError,\n  type WebhookConfig,\n  WebhookError,\n} from \"./types.js\";\n\nexport {\n  classifyHttpResponse,\n  type HttpDisposition,\n  type TryOkOptions,\n  tryOk,\n} from \"./classify.js\";\nexport type {\n  HttpDeliveryErrorInit,\n  WebhookBody,\n  WebhookConfig,\n  WebhookResolver,\n} from \"./types.js\";\nexport {\n  NonRetryableHttpError,\n  NonRetryableWebhookError,\n  RetryableHttpError,\n  WebhookError,\n} from \"./types.js\";\n\nfunction resolve<TEvents extends Schemas, T>(\n  resolver: T | ((e: Committed<TEvents, keyof TEvents>) => T) | undefined,\n  event: Committed<TEvents, keyof TEvents>,\n  fallback: T\n): T {\n  if (resolver === undefined) return fallback;\n  return typeof resolver === \"function\"\n    ? (resolver as (e: Committed<TEvents, keyof TEvents>) => T)(event)\n    : resolver;\n}\n\n/** Case-insensitive lookup; returns true if a header is already set. */\nfunction hasHeader(headers: Record<string, string>, name: string): boolean {\n  const lower = name.toLowerCase();\n  for (const k of Object.keys(headers)) {\n    if (k.toLowerCase() === lower) return true;\n  }\n  return false;\n}\n\n/**\n * Build a reaction handler that POSTs each event to an external URL.\n *\n * Behavior:\n *\n * - 2xx and 3xx return successfully.\n * - 5xx responses, network errors, and timeouts throw\n *   {@link WebhookError} (`status: 0` for network/timeout). Drain\n *   retries per the reaction's `maxRetries` / `backoff`.\n * - 4xx responses throw {@link NonRetryableWebhookError}, which\n *   extends `NonRetryableError`. The drain finalizer blocks the\n *   stream immediately (when `blockOnError` is true) without\n *   consuming the retry budget.\n */\nexport function webhook<TEvents extends Schemas = Schemas>(\n  config: WebhookConfig<TEvents>\n): ReactionHandler<TEvents, keyof TEvents> {\n  const timeoutMs = config.timeoutMs ?? 5_000;\n  const method = config.method ?? \"POST\";\n  const fetchImpl = config.fetch ?? globalThis.fetch;\n\n  // Named function: slice/act builders require non-anonymous reaction\n  // handlers so lifecycle telemetry can attribute work.\n  return async function webhookDeliver(event) {\n    const url = resolve(config.url, event, \"\");\n\n    const customHeaders = resolve(\n      config.headers,\n      event,\n      {} as Record<string, string>\n    );\n    const headers: Record<string, string> = { ...customHeaders };\n\n    if (!hasHeader(headers, \"content-type\")) {\n      headers[\"Content-Type\"] = \"application/json\";\n    }\n    if (!hasHeader(headers, \"idempotency-key\")) {\n      const key = config.idempotencyKey\n        ? config.idempotencyKey(event)\n        : String(event.id);\n      if (key !== null) headers[\"Idempotency-Key\"] = key;\n    }\n\n    const rawBody = resolve(config.body, event, event as unknown);\n    const body =\n      typeof rawBody === \"string\" ? rawBody : JSON.stringify(rawBody);\n\n    if (config.secret && !hasHeader(headers, \"x-webhook-signature\")) {\n      const { signature, timestamp } = signRequest(body, config.secret);\n      headers[\"X-Webhook-Signature\"] = signature;\n      if (!hasHeader(headers, \"x-webhook-timestamp\")) {\n        headers[\"X-Webhook-Timestamp\"] = timestamp;\n      }\n    }\n\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), timeoutMs);\n\n    let response: Response;\n    try {\n      response = await fetchImpl(url, {\n        method,\n        headers,\n        body,\n        signal: controller.signal,\n      });\n    } catch (err) {\n      const aborted = controller.signal.aborted;\n      throw new WebhookError(\n        aborted\n          ? `webhook ${method} ${url} timed out after ${timeoutMs}ms`\n          : `webhook ${method} ${url} failed: ${(err as Error).message}`,\n        { status: 0, url }\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n\n    const disposition = classifyHttpResponse(response);\n    if (disposition === \"ok\") return;\n\n    let responseBody: string | undefined;\n    try {\n      responseBody = await response.text();\n    } catch {\n      // best-effort body capture; ignore read errors\n    }\n\n    const ErrorClass =\n      disposition === \"retry\" ? WebhookError : NonRetryableWebhookError;\n    throw new ErrorClass(\n      `webhook ${method} ${url} responded ${response.status}`,\n      { status: response.status, url, responseBody }\n    );\n  };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/webhook/types.ts","../../src/webhook/classify.ts","../../src/webhook/sign.ts","../../src/webhook/index.ts"],"sourcesContent":["import {\n  type Committed,\n  NonRetryableError,\n  type Schemas,\n} from \"@rotorsoft/act\";\n\n/**\n * Function or static value resolver. Used so callers can pass either a\n * constant or a per-event function for headers / body / url.\n *\n * The static side `T` is constrained to non-function types so that a\n * passed `(event) => ...` is unambiguously typed as the function variant.\n */\nexport type WebhookResolver<TEvents extends Schemas, T> =\n  | T\n  | ((event: Committed<TEvents, keyof TEvents>) => T);\n\n/**\n * Plain-data body shape the helper accepts as a static value. Functions\n * are deliberately excluded so the union with the resolver function is\n * unambiguous at the call site (TypeScript can discriminate by shape).\n */\nexport type WebhookBody =\n  | string\n  | { readonly [k: string]: unknown }\n  | readonly unknown[];\n\n/**\n * Configuration for {@link webhook}.\n *\n * @template TEvents - Event schemas; resolvers receive the typed committed event.\n */\nexport type WebhookConfig<TEvents extends Schemas = Schemas> = {\n  /** Target URL — static string or per-event function. */\n  readonly url: WebhookResolver<TEvents, string>;\n  /** HTTP method. Defaults to `\"POST\"`. */\n  readonly method?: \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\";\n  /**\n   * Headers to send. Resolver may return a record per event. The\n   * `Content-Type: application/json` and `Idempotency-Key` headers are\n   * applied automatically; both can be overridden by returning a header\n   * with the same name (case-insensitive).\n   */\n  readonly headers?: WebhookResolver<TEvents, Record<string, string>>;\n  /**\n   * Request body. Static plain data (object, array, string) or a\n   * per-event function returning the same. Strings are sent as-is;\n   * anything else is JSON-serialized. Defaults to the committed event\n   * itself.\n   */\n  readonly body?:\n    | WebhookBody\n    | ((event: Committed<TEvents, keyof TEvents>) => WebhookBody);\n  /**\n   * Per-request timeout in milliseconds. Defaults to 5000.\n   * The handler throws after the timeout via `AbortController`.\n   */\n  readonly timeoutMs?: number;\n  /**\n   * Override for the auto-generated `Idempotency-Key`. By default, the\n   * helper sends `event.id` (the immutable, monotonic event identifier).\n   * Return a string to override; return `null` to skip the header entirely.\n   */\n  readonly idempotencyKey?: (\n    event: Committed<TEvents, keyof TEvents>\n  ) => string | null;\n  /**\n   * Injection point for tests. Defaults to global `fetch`.\n   */\n  readonly fetch?: typeof fetch;\n  /**\n   * HMAC-SHA256 signing key. When set, the webhook helper attaches\n   * two headers to every request:\n   *\n   * - `X-Webhook-Signature: sha256=<hex>` — HMAC of\n   *   `${timestamp}.${body}` (`body` is the final serialized payload)\n   * - `X-Webhook-Timestamp: <unix-seconds>`\n   *\n   * Pair with `verifyWebhook` from `@rotorsoft/act-http/receiver` on\n   * the receiving side. When undefined, no signature headers are\n   * added — back-compat with consumers that don't need signing.\n   *\n   * Callers can override either header by returning it from the\n   * `headers` resolver (case-insensitive), the same way the\n   * `Idempotency-Key` and `Content-Type` defaults yield to caller\n   * intent.\n   */\n  readonly secret?: string;\n};\n\n/**\n * Common fields carried on every HTTP delivery error in this package.\n */\nexport type HttpDeliveryErrorInit = {\n  status: number;\n  url: string;\n  responseBody?: string;\n};\n\n/**\n * Thrown when an HTTP delivery fails in a way the drain pipeline\n * should retry: network failure, timeout, or 5xx response. `status` is\n * `0` for network / timeout errors, the HTTP status code otherwise.\n *\n * The class itself is the retry signal — if a reaction throws this,\n * drain treats it like any other error (counts against `maxRetries`,\n * paces with `backoff`). For permanent failures, throw\n * {@link NonRetryableHttpError} instead.\n *\n * Generic enough to cover any custom HTTP-like integration (gRPC\n * bridges, SDK-based reactions). {@link WebhookError} is a\n * webhook-specific subclass kept for backward compatibility.\n */\nexport class RetryableHttpError extends Error {\n  readonly status: number;\n  readonly url: string;\n  readonly responseBody?: string;\n\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message);\n    this.name = \"RetryableHttpError\";\n    this.status = init.status;\n    this.url = init.url;\n    this.responseBody = init.responseBody;\n  }\n}\n\n/**\n * Thrown when an HTTP delivery returns a 3xx or 4xx response —\n * permanent client errors that won't recover on retry. Extends\n * {@link NonRetryableError} so the drain finalizer blocks the stream\n * on the first failed attempt (when `blockOnError` is true) — no\n * wasted retries on a malformed payload or wrong URL.\n *\n * Generic enough to cover any custom HTTP-like integration.\n * {@link NonRetryableWebhookError} is a webhook-specific subclass kept\n * for backward compatibility.\n */\nexport class NonRetryableHttpError extends NonRetryableError {\n  readonly status: number;\n  readonly url: string;\n  readonly responseBody?: string;\n\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message);\n    this.name = \"NonRetryableHttpError\";\n    this.status = init.status;\n    this.url = init.url;\n    this.responseBody = init.responseBody;\n  }\n}\n\n/**\n * Webhook-specific subclass of {@link RetryableHttpError}. Thrown by\n * the {@link webhook} helper on 5xx responses, network failures, and\n * timeouts. Existing `instanceof WebhookError` checks continue to\n * work; new code targeting the generic HTTP integration shape can\n * catch {@link RetryableHttpError} instead and handle webhook +\n * custom integrations uniformly.\n */\nexport class WebhookError extends RetryableHttpError {\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message, init);\n    this.name = \"WebhookError\";\n  }\n}\n\n/**\n * Webhook-specific subclass of {@link NonRetryableHttpError}. Thrown\n * by the {@link webhook} helper on 3xx/4xx responses. Existing\n * `instanceof NonRetryableWebhookError` checks continue to work; new\n * code can catch {@link NonRetryableHttpError} or\n * {@link NonRetryableError} for broader coverage.\n */\nexport class NonRetryableWebhookError extends NonRetryableHttpError {\n  constructor(message: string, init: HttpDeliveryErrorInit) {\n    super(message, init);\n    this.name = \"NonRetryableWebhookError\";\n  }\n}\n","import { NonRetryableHttpError, RetryableHttpError } from \"./types.js\";\n\n/**\n * Three buckets for an HTTP response from an outbound delivery:\n *\n * - `ok` — the receiver accepted the delivery (2xx). Stop and return.\n * - `retry` — the receiver had a transient problem (5xx). Throw a\n *   retryable error; drain will pace the next attempt per `backoff`.\n * - `block` — the receiver rejected the delivery permanently (3xx\n *   or 4xx). Throw a non-retryable error; drain blocks the stream\n *   on the first failed attempt (when `blockOnError` is true) and\n *   surfaces it via the `\"blocked\"` lifecycle event.\n *\n * The 3xx → `block` mapping is intentional: a redirect at the\n * delivery layer means the configured URL is wrong, and retrying\n * the same URL won't fix that. Manual operator review is the right\n * next step, which is what the block path produces.\n */\nexport type HttpDisposition = \"ok\" | \"retry\" | \"block\";\n\n/**\n * Classify an HTTP response as `ok` (2xx), `retry` (5xx), or\n * `block` (3xx, 4xx). The classification {@link webhook} uses\n * internally, lifted here so custom integrations (gRPC bridges,\n * SDK-based reactions, etc.) can apply the same retry semantics\n * without inventing a parallel rule.\n */\nexport function classify_http_response(response: Response): HttpDisposition {\n  if (response.ok) return \"ok\";\n  if (response.status >= 500) return \"retry\";\n  return \"block\";\n}\n\n/** Options for {@link try_ok}. */\nexport type TryOkOptions = {\n  /** The endpoint that received the request. Surfaced on the thrown error and in its message. */\n  url: string;\n  /**\n   * Label prefixed onto the error message — typically the\n   * integration's identity (`\"webhook\"`, `\"my_sdk\"`, `\"grpc\"`).\n   * Default: `\"request\"`.\n   */\n  label?: string;\n};\n\n/**\n * If `response` is 2xx, return. Otherwise, capture the response body\n * (best-effort) and throw a {@link RetryableHttpError} (for 5xx) or\n * {@link NonRetryableHttpError} (for 3xx/4xx). Collapses the\n * classify-and-throw boilerplate every custom HTTP-like reaction\n * would otherwise write into one line:\n *\n * ```ts\n * .on(\"OrderConfirmed\").do(async (event) => {\n *   const response = await my_sdk.deliver(event);\n *   await try_ok(response, { url: my_sdk.url, label: \"my_sdk\" });\n *   // ...response was 2xx; continue with downstream work...\n * });\n * ```\n *\n * The {@link webhook} helper throws webhook-specific subclasses\n * ({@link WebhookError} / {@link NonRetryableWebhookError}) for\n * backward compatibility — both extend the generic classes thrown\n * here, so `instanceof RetryableHttpError` matches both webhook and\n * custom-integration errors uniformly.\n */\nexport async function try_ok(\n  response: Response,\n  options: TryOkOptions\n): Promise<void> {\n  const disposition = classify_http_response(response);\n  if (disposition === \"ok\") return;\n\n  let responseBody: string | undefined;\n  try {\n    responseBody = await response.text();\n  } catch {\n    // best-effort body capture; ignore read errors\n  }\n\n  const label = options.label ?? \"request\";\n  const ErrorClass =\n    disposition === \"retry\" ? RetryableHttpError : NonRetryableHttpError;\n  throw new ErrorClass(`${label} ${options.url} responded ${response.status}`, {\n    status: response.status,\n    url: options.url,\n    responseBody,\n  });\n}\n","import { createHmac } from \"node:crypto\";\n\n/**\n * Compute the HMAC-SHA256 signature for an outbound webhook request.\n *\n * The signed payload is `${timestamp}.${body}` — Stripe-style. The\n * timestamp is included so the receiver can reject replays via a\n * window check, and the dot separator prevents `timestamp + body`\n * ambiguity (12 + 345 vs 123 + 45).\n *\n * Returns `{ signature, timestamp }` so the webhook helper can attach\n * both as headers — `X-Webhook-Signature: sha256=<hex>` and\n * `X-Webhook-Timestamp: <unix-seconds>` — for the receiver to verify\n * via `verifyWebhook` from `@rotorsoft/act-http/receiver`.\n *\n * `now` is exposed for tests; production callers should leave it\n * undefined so wall-clock is used.\n *\n * @internal Reachable from tests via the source path. Not re-exported\n *   from the package's `./webhook` entry — the webhook helper calls\n *   it internally, and operators don't need it directly.\n */\nexport function sign_request(\n  body: string,\n  secret: string,\n  now: number = Math.floor(Date.now() / 1000)\n): { signature: string; timestamp: string } {\n  const timestamp = String(now);\n  const payload = `${timestamp}.${body}`;\n  const hex = createHmac(\"sha256\", secret).update(payload).digest(\"hex\");\n  return { signature: `sha256=${hex}`, timestamp };\n}\n","/**\n * @packageDocumentation\n * @module act-http/webhook\n *\n * Reaction-handler sugar for POSTing committed events to external URLs.\n *\n * Wraps `fetch` with timeouts, automatic `Idempotency-Key` derivation, and\n * status-classified errors. Designed to be composed with the reaction\n * options shipped in ACT-601 (`maxRetries`, `blockOnError`, `backoff`):\n *\n * ```ts\n * import { webhook } from \"@rotorsoft/act-http/webhook\";\n *\n * .on(\"OrderConfirmed\")\n *   .do(\n *     webhook({\n *       url: \"https://api.example.com/webhooks/orders\",\n *       headers: (e) => ({ Authorization: \"Bearer ...\" }),\n *       body: (e) => ({ orderId: e.stream, total: e.data.total }),\n *       timeoutMs: 5_000,\n *     }),\n *     { maxRetries: 5, backoff: { strategy: \"exponential\", baseMs: 200, maxMs: 30_000 } }\n *   )\n *   .to(resolver);\n * ```\n */\n\nimport type { Committed, ReactionHandler, Schemas } from \"@rotorsoft/act\";\nimport { classify_http_response } from \"./classify.js\";\nimport { sign_request } from \"./sign.js\";\nimport {\n  NonRetryableWebhookError,\n  type WebhookConfig,\n  WebhookError,\n} from \"./types.js\";\n\nexport type { HttpDisposition } from \"./classify.js\";\nexport type {\n  HttpDeliveryErrorInit,\n  WebhookBody,\n  WebhookConfig,\n  WebhookResolver,\n} from \"./types.js\";\nexport {\n  NonRetryableHttpError,\n  NonRetryableWebhookError,\n  RetryableHttpError,\n  WebhookError,\n} from \"./types.js\";\n\nfunction resolve<TEvents extends Schemas, T>(\n  resolver: T | ((e: Committed<TEvents, keyof TEvents>) => T) | undefined,\n  event: Committed<TEvents, keyof TEvents>,\n  fallback: T\n): T {\n  if (resolver === undefined) return fallback;\n  return typeof resolver === \"function\"\n    ? (resolver as (e: Committed<TEvents, keyof TEvents>) => T)(event)\n    : resolver;\n}\n\n/** Case-insensitive lookup; returns true if a header is already set. */\nfunction has_header(headers: Record<string, string>, name: string): boolean {\n  const lower = name.toLowerCase();\n  for (const k of Object.keys(headers)) {\n    if (k.toLowerCase() === lower) return true;\n  }\n  return false;\n}\n\n/**\n * Build a reaction handler that POSTs each event to an external URL.\n *\n * Behavior:\n *\n * - 2xx and 3xx return successfully.\n * - 5xx responses, network errors, and timeouts throw\n *   {@link WebhookError} (`status: 0` for network/timeout). Drain\n *   retries per the reaction's `maxRetries` / `backoff`.\n * - 4xx responses throw {@link NonRetryableWebhookError}, which\n *   extends `NonRetryableError`. The drain finalizer blocks the\n *   stream immediately (when `blockOnError` is true) without\n *   consuming the retry budget.\n */\nexport function webhook<TEvents extends Schemas = Schemas>(\n  config: WebhookConfig<TEvents>\n): ReactionHandler<TEvents, keyof TEvents> {\n  const timeoutMs = config.timeoutMs ?? 5_000;\n  const method = config.method ?? \"POST\";\n  const fetch_impl = config.fetch ?? globalThis.fetch;\n\n  // Named function: slice/act builders require non-anonymous reaction\n  // handlers so lifecycle telemetry can attribute work.\n  return async function webhook_deliver(event) {\n    const url = resolve(config.url, event, \"\");\n\n    const custom_headers = resolve(\n      config.headers,\n      event,\n      {} as Record<string, string>\n    );\n    const headers: Record<string, string> = { ...custom_headers };\n\n    if (!has_header(headers, \"content-type\")) {\n      headers[\"Content-Type\"] = \"application/json\";\n    }\n    if (!has_header(headers, \"idempotency-key\")) {\n      const key = config.idempotencyKey\n        ? config.idempotencyKey(event)\n        : String(event.id);\n      if (key !== null) headers[\"Idempotency-Key\"] = key;\n    }\n\n    const rawBody = resolve(config.body, event, event as unknown);\n    const body =\n      typeof rawBody === \"string\" ? rawBody : JSON.stringify(rawBody);\n\n    if (config.secret && !has_header(headers, \"x-webhook-signature\")) {\n      const { signature, timestamp } = sign_request(body, config.secret);\n      headers[\"X-Webhook-Signature\"] = signature;\n      if (!has_header(headers, \"x-webhook-timestamp\")) {\n        headers[\"X-Webhook-Timestamp\"] = timestamp;\n      }\n    }\n\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), timeoutMs);\n\n    let response: Response;\n    try {\n      response = await fetch_impl(url, {\n        method,\n        headers,\n        body,\n        signal: controller.signal,\n      });\n    } catch (err) {\n      const aborted = controller.signal.aborted;\n      throw new WebhookError(\n        aborted\n          ? `webhook ${method} ${url} timed out after ${timeoutMs}ms`\n          : `webhook ${method} ${url} failed: ${(err as Error).message}`,\n        { status: 0, url }\n      );\n    } finally {\n      clearTimeout(timer);\n    }\n\n    const disposition = classify_http_response(response);\n    if (disposition === \"ok\") return;\n\n    let responseBody: string | undefined;\n    try {\n      responseBody = await response.text();\n    } catch {\n      // best-effort body capture; ignore read errors\n    }\n\n    const ErrorClass =\n      disposition === \"retry\" ? WebhookError : NonRetryableWebhookError;\n    throw new ErrorClass(\n      `webhook ${method} ${url} responded ${response.status}`,\n      { status: response.status, url, responseBody }\n    );\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rotorsoft/act-http",
   "type": "module",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "HTTP integrations for act apps — webhooks and SSE",
   "keywords": [
     "typescript",
@@ -26,26 +26,16 @@
     "dist"
   ],
   "exports": {
-    "./webhook": {
-      "types": "./dist/@types/webhook/index.d.ts",
-      "import": "./dist/webhook/index.js",
-      "require": "./dist/webhook/index.cjs"
-    },
-    "./sse": {
-      "types": "./dist/@types/sse/index.d.ts",
-      "import": "./dist/sse/index.js",
-      "require": "./dist/sse/index.cjs"
+    "./api": {
+      "types": "./dist/@types/api/index.d.ts",
+      "import": "./dist/api/index.js",
+      "require": "./dist/api/index.cjs"
     },
     "./receiver": {
       "types": "./dist/@types/receiver/index.d.ts",
       "import": "./dist/receiver/index.js",
       "require": "./dist/receiver/index.cjs"
     },
-    "./receiver/trpc": {
-      "types": "./dist/@types/receiver/trpc/index.d.ts",
-      "import": "./dist/receiver/trpc/index.js",
-      "require": "./dist/receiver/trpc/index.cjs"
-    },
     "./receiver/express": {
       "types": "./dist/@types/receiver/express/index.d.ts",
       "import": "./dist/receiver/express/index.js",
@@ -61,23 +51,42 @@
       "import": "./dist/receiver/hono/index.js",
       "require": "./dist/receiver/hono/index.cjs"
     },
-    "./api": {
-      "types": "./dist/@types/api/index.d.ts",
-      "import": "./dist/api/index.js",
-      "require": "./dist/api/index.cjs"
+    "./receiver/trpc": {
+      "types": "./dist/@types/receiver/trpc/index.d.ts",
+      "import": "./dist/receiver/trpc/index.js",
+      "require": "./dist/receiver/trpc/index.cjs"
+    },
+    "./sse": {
+      "types": "./dist/@types/sse/index.d.ts",
+      "import": "./dist/sse/index.js",
+      "require": "./dist/sse/index.cjs"
+    },
+    "./trpc": {
+      "types": "./dist/@types/trpc/index.d.ts",
+      "import": "./dist/trpc/index.js",
+      "require": "./dist/trpc/index.cjs"
+    },
+    "./webhook": {
+      "types": "./dist/@types/webhook/index.d.ts",
+      "import": "./dist/webhook/index.js",
+      "require": "./dist/webhook/index.cjs"
     }
   },
   "sideEffects": false,
   "engines": {
-    "node": ">=22.18.0"
+    "node": ">=22.22.3"
   },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
-    "@trpc/server": ">=11",
-    "@rotorsoft/act": "^1.7.0",
-    "@rotorsoft/act-ops": "^0.2.0"
+    "@trpc/server": ">=11.17.0",
+    "@hono/node-server": "^2.0.4",
+    "express": "^5.2.1",
+    "fastify": "^5.8.5",
+    "hono": "^4.12.23",
+    "@rotorsoft/act": "^1.10.2",
+    "@rotorsoft/act-ops": "^0.2.1"
   },
   "peerDependenciesMeta": {
     "@rotorsoft/act-ops": {
@@ -85,19 +94,32 @@
     },
     "@trpc/server": {
       "optional": true
+    },
+    "@hono/node-server": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "fastify": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
     }
   },
   "dependencies": {
-    "@rotorsoft/act-patch": "^1.2.3"
+    "@rotorsoft/act-patch": "^1.2.4"
   },
   "devDependencies": {
-    "@hono/node-server": "^1",
+    "@hono/node-server": "^2.0.4",
     "@trpc/server": "^11.17.0",
-    "@types/express": "^5",
-    "fastify": "^5",
-    "hono": "^4",
-    "zod": "^4",
-    "@rotorsoft/act-ops": "^0.2.0"
+    "@types/express": "^5.0.6",
+    "express": "^5.2.1",
+    "fastify": "^5.8.5",
+    "hono": "^4.12.23",
+    "zod": "^4.4.3",
+    "@rotorsoft/act-ops": "^0.2.1"
   },
   "scripts": {
     "clean": "rm -rf dist",

package/dist/chunk-NOIXOF2I.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/receiver/extract.ts","../src/receiver/verify.ts","../src/receiver/check.ts"],"sourcesContent":["/**\n * Pull the `Idempotency-Key` header from a Node-style headers bag,\n * case-insensitive. Returns `undefined` when any of the following\n * carries no usable key:\n *\n * - the header is missing\n * - its value is an array (ambiguous — can't pick one without a\n *   policy the receiver hasn't declared)\n * - its value is the empty string (carries no idempotency\n *   information; structurally equivalent to \"no header at all\")\n *\n * Pair with `IdempotencyStore.claim` from\n * `@rotorsoft/act-ops/idempotency`: extract the key from the inbound\n * request, claim it on the store, return a `deduped` marker when the\n * claim fails. The framework-agnostic middleware that wires these\n * together lands in #744.\n *\n * Validation beyond \"is there a usable key?\" (length bounds, format\n * checks, normalization) is intentionally out of scope. Receivers\n * picking a policy can layer it on top — or, when #744 ships, opt\n * into the middleware's opinionated defaults.\n */\nexport function extractIdempotencyKey(\n  headers: Record<string, string | string[] | undefined>\n): string | undefined {\n  for (const [name, value] of Object.entries(headers)) {\n    if (name.toLowerCase() !== \"idempotency-key\") continue;\n    if (Array.isArray(value)) return undefined;\n    if (value === \"\") return undefined;\n    return value;\n  }\n  return undefined;\n}\n","import { createHmac, timingSafeEqual } from \"node:crypto\";\n\n/**\n * Outcome of {@link verifyWebhook}. Either the request signature\n * checks out, or one of five distinct failure reasons applies. Each\n * reason maps to an operator-meaningful telemetry bucket — separated\n * deliberately so dashboards can distinguish \"client lost its secret\"\n * from \"client clock is wrong\" from \"this is a replay attack.\"\n */\nexport type VerifyResult =\n  | { ok: true }\n  | {\n      ok: false;\n      reason:\n        | \"missing-signature\"\n        | \"missing-timestamp\"\n        | \"stale\"\n        | \"future\"\n        | \"bad-signature\";\n    };\n\n/** Options for {@link verifyWebhook}. */\nexport type VerifyOptions = {\n  /**\n   * Maximum acceptable timestamp drift in either direction, in\n   * seconds. Default: 300 (±5 minutes) — matches Stripe / GitHub /\n   * Slack conventions. Tightening narrows the replay window;\n   * loosening accommodates clients with worse clock sync.\n   */\n  maxAgeSeconds?: number;\n  /**\n   * Current Unix-seconds time. Exposed for tests; production\n   * callers should leave it undefined so wall-clock is used.\n   */\n  now?: number;\n};\n\n/**\n * Verify an inbound webhook's signature and timestamp against the\n * shared secret. Pair with the sender side: configure\n * `webhook({ secret })` from `@rotorsoft/act-http/webhook`.\n *\n * Returns `{ ok: true }` on success or `{ ok: false; reason }` on\n * failure. The reasons are:\n *\n * - `missing-signature` — no `X-Webhook-Signature` header, value\n *   was an array, or value was empty.\n * - `missing-timestamp` — no `X-Webhook-Timestamp` header, value\n *   was empty, or value isn't a parseable integer.\n * - `stale` — timestamp older than `maxAgeSeconds` from `now`.\n * - `future` — timestamp more than `maxAgeSeconds` ahead of `now`.\n * - `bad-signature` — signature header didn't start with `sha256=`,\n *   wasn't 64 hex chars, or the recomputed HMAC didn't match\n *   (constant-time compare).\n *\n * The signed payload is `${timestamp}.${body}`, so `body` must be\n * the **raw request body bytes**. Any pre-parse normalization\n * (whitespace trimming, JSON re-stringification) would change the\n * hash and reject every otherwise-valid request. Framework adapters\n * in #744 will provide the raw body alongside the parsed one.\n *\n * Uses Node's `crypto.timingSafeEqual` for the final comparison to\n * avoid signature-equality timing attacks.\n */\nexport function verifyWebhook(\n  headers: Record<string, string | string[] | undefined>,\n  body: string,\n  secret: string,\n  options?: VerifyOptions\n): VerifyResult {\n  const maxAgeSeconds = options?.maxAgeSeconds ?? 300;\n  const now = options?.now ?? Math.floor(Date.now() / 1000);\n\n  const signature = pickHeader(headers, \"x-webhook-signature\");\n  if (!signature) return { ok: false, reason: \"missing-signature\" };\n\n  const timestampStr = pickHeader(headers, \"x-webhook-timestamp\");\n  if (!timestampStr) return { ok: false, reason: \"missing-timestamp\" };\n  const timestamp = Number.parseInt(timestampStr, 10);\n  if (Number.isNaN(timestamp) || String(timestamp) !== timestampStr) {\n    return { ok: false, reason: \"missing-timestamp\" };\n  }\n\n  const delta = now - timestamp;\n  if (delta > maxAgeSeconds) return { ok: false, reason: \"stale\" };\n  if (delta < -maxAgeSeconds) return { ok: false, reason: \"future\" };\n\n  if (!signature.startsWith(\"sha256=\")) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n  const providedHex = signature.slice(\"sha256=\".length);\n  if (!/^[0-9a-fA-F]{64}$/.test(providedHex)) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n\n  const expectedHex = createHmac(\"sha256\", secret)\n    .update(`${timestampStr}.${body}`)\n    .digest(\"hex\");\n\n  const a = Buffer.from(providedHex, \"hex\");\n  const b = Buffer.from(expectedHex, \"hex\");\n  if (!timingSafeEqual(a, b)) {\n    return { ok: false, reason: \"bad-signature\" };\n  }\n\n  return { ok: true };\n}\n\nfunction pickHeader(\n  headers: Record<string, string | string[] | undefined>,\n  lowerName: string\n): string | undefined {\n  for (const [name, value] of Object.entries(headers)) {\n    if (name.toLowerCase() !== lowerName) continue;\n    if (Array.isArray(value) || value === undefined || value === \"\") {\n      return undefined;\n    }\n    return value;\n  }\n  return undefined;\n}\n","import type { IdempotencyStore } from \"@rotorsoft/act-ops/idempotency\";\nimport { extractIdempotencyKey } from \"./extract.js\";\nimport { type VerifyOptions, verifyWebhook } from \"./verify.js\";\n\n/**\n * Failure reasons returned by {@link checkWebhook}. The shape splits\n * `missing-key` (a client error, mapped to HTTP 400) from the five\n * verification failures (authentication errors, HTTP 401) so each\n * maps to its own telemetry bucket.\n */\nexport type CheckFailureReason =\n  | \"missing-key\"\n  | \"missing-signature\"\n  | \"missing-timestamp\"\n  | \"stale\"\n  | \"future\"\n  | \"bad-signature\";\n\n/**\n * Outcome of {@link checkWebhook}. Either the request passed every\n * configured check and carries a usable idempotency key, or it\n * failed one of them and the framework adapter should reply with the\n * corresponding HTTP status.\n */\nexport type CheckResult =\n  | { ok: false; status: 400 | 401; reason: CheckFailureReason }\n  | { ok: true; key: string; deduped: boolean };\n\n/** Options for {@link checkWebhook}. */\nexport type CheckWebhookOptions = {\n  /** Idempotency store the framework-agnostic core claims the key on. */\n  store: IdempotencyStore;\n  /**\n   * Optional HMAC-SHA256 secret. When set, the request's\n   * `X-Webhook-Signature` and `X-Webhook-Timestamp` headers are\n   * verified before the dedup claim. When omitted, signature\n   * verification is skipped (unsigned receivers).\n   */\n  secret?: string;\n  /**\n   * Verification options forwarded to {@link verifyWebhook}. Only\n   * meaningful when `secret` is set. Defaults to a ±300-second\n   * timestamp window.\n   */\n  verify?: VerifyOptions;\n};\n\n/**\n * Framework-agnostic receiver check: verify the signature (when a\n * secret is configured), extract the `Idempotency-Key`, and claim\n * it on the store. Returns the request's fate as a discriminated\n * union the per-framework adapter translates into the framework's\n * idiomatic 4xx response or context injection.\n *\n * **Order of checks** (matters):\n *\n * 1. Verify signature + timestamp window (when `secret` is set).\n *    Rejecting bad signatures *before* extracting and claiming the\n *    key keeps attacker-supplied keys out of the dedup store —\n *    otherwise a flood of spoofed POSTs would pollute the LRU.\n * 2. Extract the `Idempotency-Key`. Missing → reject with 400.\n * 3. Claim the key on the store. If already seen, return\n *    `{ ok: true; deduped: true }` so the framework adapter can\n *    short-circuit the handler without re-running side effects.\n *\n * The dedup store may be sync (`InMemoryIdempotencyStore`) or async\n * (durable adapters like a future `PostgresIdempotencyStore`); the\n * core awaits unconditionally so both shapes compose cleanly.\n */\nexport async function checkWebhook(\n  headers: Record<string, string | string[] | undefined>,\n  body: string,\n  options: CheckWebhookOptions\n): Promise<CheckResult> {\n  if (options.secret !== undefined) {\n    const verification = verifyWebhook(\n      headers,\n      body,\n      options.secret,\n      options.verify\n    );\n    if (!verification.ok) {\n      return { ok: false, status: 401, reason: verification.reason };\n    }\n  }\n\n  const key = extractIdempotencyKey(headers);\n  if (!key) return { ok: false, status: 400, reason: \"missing-key\" };\n\n  const claimed = await options.store.claim(key);\n  return { ok: true, key, deduped: !claimed };\n}\n"],"mappings":";AAsBO,SAAS,sBACd,SACoB;AACpB,aAAW,CAAC,MAAM,KAAK,KAAK,OAAO,QAAQ,OAAO,GAAG;AACnD,QAAI,KAAK,YAAY,MAAM,kBAAmB;AAC9C,QAAI,MAAM,QAAQ,KAAK,EAAG,QAAO;AACjC,QAAI,UAAU,GAAI,QAAO;AACzB,WAAO;AAAA,EACT;AACA,SAAO;AACT;;;AChCA,SAAS,YAAY,uBAAuB;AAgErC,SAAS,cACd,SACA,MACA,QACA,SACc;AACd,QAAM,gBAAgB,SAAS,iBAAiB;AAChD,QAAM,MAAM,SAAS,OAAO,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AAExD,QAAM,YAAY,WAAW,SAAS,qBAAqB;AAC3D,MAAI,CAAC,UAAW,QAAO,EAAE,IAAI,OAAO,QAAQ,oBAAoB;AAEhE,QAAM,eAAe,WAAW,SAAS,qBAAqB;AAC9D,MAAI,CAAC,aAAc,QAAO,EAAE,IAAI,OAAO,QAAQ,oBAAoB;AACnE,QAAM,YAAY,OAAO,SAAS,cAAc,EAAE;AAClD,MAAI,OAAO,MAAM,SAAS,KAAK,OAAO,SAAS,MAAM,cAAc;AACjE,WAAO,EAAE,IAAI,OAAO,QAAQ,oBAAoB;AAAA,EAClD;AAEA,QAAM,QAAQ,MAAM;AACpB,MAAI,QAAQ,cAAe,QAAO,EAAE,IAAI,OAAO,QAAQ,QAAQ;AAC/D,MAAI,QAAQ,CAAC,cAAe,QAAO,EAAE,IAAI,OAAO,QAAQ,SAAS;AAEjE,MAAI,CAAC,UAAU,WAAW,SAAS,GAAG;AACpC,WAAO,EAAE,IAAI,OAAO,QAAQ,gBAAgB;AAAA,EAC9C;AACA,QAAM,cAAc,UAAU,MAAM,UAAU,MAAM;AACpD,MAAI,CAAC,oBAAoB,KAAK,WAAW,GAAG;AAC1C,WAAO,EAAE,IAAI,OAAO,QAAQ,gBAAgB;AAAA,EAC9C;AAEA,QAAM,cAAc,WAAW,UAAU,MAAM,EAC5C,OAAO,GAAG,YAAY,IAAI,IAAI,EAAE,EAChC,OAAO,KAAK;AAEf,QAAM,IAAI,OAAO,KAAK,aAAa,KAAK;AACxC,QAAM,IAAI,OAAO,KAAK,aAAa,KAAK;AACxC,MAAI,CAAC,gBAAgB,GAAG,CAAC,GAAG;AAC1B,WAAO,EAAE,IAAI,OAAO,QAAQ,gBAAgB;AAAA,EAC9C;AAEA,SAAO,EAAE,IAAI,KAAK;AACpB;AAEA,SAAS,WACP,SACA,WACoB;AACpB,aAAW,CAAC,MAAM,KAAK,KAAK,OAAO,QAAQ,OAAO,GAAG;AACnD,QAAI,KAAK,YAAY,MAAM,UAAW;AACtC,QAAI,MAAM,QAAQ,KAAK,KAAK,UAAU,UAAa,UAAU,IAAI;AAC/D,aAAO;AAAA,IACT;AACA,WAAO;AAAA,EACT;AACA,SAAO;AACT;;;ACnDA,eAAsB,aACpB,SACA,MACA,SACsB;AACtB,MAAI,QAAQ,WAAW,QAAW;AAChC,UAAM,eAAe;AAAA,MACnB;AAAA,MACA;AAAA,MACA,QAAQ;AAAA,MACR,QAAQ;AAAA,IACV;AACA,QAAI,CAAC,aAAa,IAAI;AACpB,aAAO,EAAE,IAAI,OAAO,QAAQ,KAAK,QAAQ,aAAa,OAAO;AAAA,IAC/D;AAAA,EACF;AAEA,QAAM,MAAM,sBAAsB,OAAO;AACzC,MAAI,CAAC,IAAK,QAAO,EAAE,IAAI,OAAO,QAAQ,KAAK,QAAQ,cAAc;AAEjE,QAAM,UAAU,MAAM,QAAQ,MAAM,MAAM,GAAG;AAC7C,SAAO,EAAE,IAAI,MAAM,KAAK,SAAS,CAAC,QAAQ;AAC5C;","names":[]}