@nest-batch/webhook 0.2.0

package/dist/src/webhook-batch.observer.js

@@ -0,0 +1,306 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get BATCH_EVENT () {
+        return _core.BATCH_EVENT;
+    },
+    get WebhookBatchObserver () {
+        return WebhookBatchObserver;
+    }
+});
+const _common = require("@nestjs/common");
+const _core = require("@nest-batch/core");
+const _moduleoptions = require("./module-options");
+const _webhooksigning = require("./webhook-signing");
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+let WebhookBatchObserver = class WebhookBatchObserver {
+    logger;
+    /** Resolved + frozen options. The secret lives here and nowhere else. */ options;
+    /**
+   * Cached lookup of the subscription set. Built once at
+   * construction time so `onEvent` is a single `Set.has` check.
+   */ subscribed;
+    /**
+   * Test-only override for the retry schedule. When
+   * `process.env.WEBHOOK_TEST_FAST === '1'`, the schedule is
+   * `[1ms, 5ms, 25ms, 125ms]` so the suite can exercise the
+   * 4-attempt path without waiting 156 seconds. The override
+   * is gated behind an env var so production cannot trip it
+   * by accident.
+   */ retryDelaysMs;
+    /**
+   * Sentinel subscriber set: defaults to
+   * `[JOB_COMPLETED, JOB_FAILED, STEP_FAILED]`. Overridable via
+   * the `events` option in `forRoot({...})`.
+   */ constructor(options){
+        this.options = options;
+        this.logger = options.logger ?? new _common.Logger(WebhookBatchObserver.name);
+        this.subscribed = new Set(options.events);
+        this.retryDelaysMs = process.env['WEBHOOK_TEST_FAST'] === '1' ? _moduleoptions.FAST_WEBHOOK_RETRY_DELAYS_MS : _moduleoptions.DEFAULT_WEBHOOK_RETRY_DELAYS_MS;
+    }
+    /**
+   * `BatchObserver` entry point. Filters by the subscription
+   * set, then dispatches to every URL. NEVER throws — a slow /
+   * failing observer must not poison the executor (the
+   * JobExecutor already swallows observer errors, but we are
+   * defensive in depth).
+   */ async onEvent(event) {
+        if (!this.subscribed.has(event.type)) return;
+        if (this.options.urls.length === 0) return;
+        try {
+            await this.deliverToAll(event);
+        } catch (err) {
+            // Defence in depth: the JobExecutor already swallows
+            // observer errors, but we re-assert it here so a single
+            // failing URL cannot starve the rest. The per-URL
+            // delivery loop has its own try/catch and writes a
+            // dead-letter `warn` for fully-failed URLs, so this
+            // outer catch only fires for genuinely unexpected
+            // errors (e.g. a synchronous throw in the envelope
+            // builder). The secret is NEVER included in this
+            // message.
+            this.logger.warn(`unexpected observer error type=${event.type} ` + `jobExecutionId=${event.jobExecutionId}: ` + `${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Fan-out
+    // -----------------------------------------------------------------------
+    /**
+   * Build the envelope once, then POST to every URL in
+   * `urls` in parallel. A single URL's retry exhaustion does
+   * not affect the other URLs — each URL has its own
+   * `deliverToUrl` invocation and its own dead-letter line.
+   *
+   * The envelope is built with `JSON.stringify` (NOT a Nest
+   * serializer) so the bytes are stable and match the HMAC
+   * input byte-for-byte. The body string is the literal
+   * argument to `fetch`, so the receiver sees the same
+   * bytes the observer signed.
+   */ async deliverToAll(event) {
+        const envelope = this.buildEnvelope(event);
+        const body = JSON.stringify(envelope);
+        await Promise.all(this.options.urls.map((url)=>this.deliverToUrl(url, event, body)));
+    }
+    /**
+   * Build the v1 envelope payload. The shape is the contract
+   * the receiver expects; changing it is a breaking change.
+   *
+   *   - `version: 1` — the envelope schema version (the
+   *     `v1=` in the signature header is the SIGNATURE
+   *     version, not the ENVELOPE version; they are
+   *     independent).
+   *   - `type` — the `BatchEvent.type` string verbatim
+   *     (e.g. `nest-batch.job.completed`).
+   *   - `timestamp` — the event's `Date` serialized as
+   *     ISO-8601 (the original `Date` is not JSON-safe).
+   *   - `jobId` — the `jobExecutionId` (the `BatchEvent`
+   *     contract guarantees this is always set).
+   *   - `execution` — the `JobExecution` shape derived from
+   *     the event's `data` payload. The observer treats
+   *     `data` as opaque `JsonValue` and passes it through
+   *     after a defensive deep-copy via `structuredClone`
+   *     so the observer cannot mutate the executor's
+   *     internal state by reference.
+   *   - `stepId` — present for STEP\_\* / CHUNK\_\* / ITEM\_\*
+   *     events; absent for JOB\_\* events. Mirrors the
+   *     `BatchEvent.stepExecutionId` contract.
+   */ buildEnvelope(event) {
+        return {
+            version: 1,
+            type: event.type,
+            timestamp: event.timestamp.toISOString(),
+            jobId: event.jobExecutionId,
+            ...event.stepExecutionId !== undefined ? {
+                stepId: event.stepExecutionId
+            } : {},
+            execution: cloneJson(event.data)
+        };
+    }
+    // -----------------------------------------------------------------------
+    // Per-URL delivery with retry
+    // -----------------------------------------------------------------------
+    /**
+   * POST the envelope to one URL with the full retry budget.
+   * Stops on the first 2xx; retries on 5xx and network errors;
+   * does NOT retry on 4xx; emits a dead-letter `warn` on
+   * exhaustion. The body is signed once; the same signed body
+   * is sent on every attempt.
+   */ async deliverToUrl(url, event, body) {
+        const timestamp = Math.floor(Date.now() / 1000);
+        const signature = (0, _webhooksigning.buildSignatureHeader)(this.options.secret, timestamp, body);
+        const fingerprint = (0, _webhooksigning.fingerprintSecret)(this.options.secret);
+        const totalAttempts = this.options.attempts;
+        let lastStatus;
+        let lastError;
+        for(let attempt = 1; attempt <= totalAttempts; attempt++){
+            const result = await this.attemptOnce(url, body, signature, timestamp);
+            if (result.kind === 'success') {
+                if (attempt > 1) {
+                    this.logger.log(`delivered url=${url} type=${event.type} ` + `jobExecutionId=${event.jobExecutionId} attempt=${attempt}/${totalAttempts} ` + `status=${result.status} (after retry)`);
+                } else {
+                    this.logger.debug(`delivered url=${url} type=${event.type} ` + `jobExecutionId=${event.jobExecutionId} attempt=${attempt}/${totalAttempts} ` + `status=${result.status}`);
+                }
+                return;
+            }
+            if (result.kind === 'client-error') {
+                // 4xx — NO retry. Log at `warn` and return. The host
+                // is expected to fix the misconfiguration (bad URL,
+                // missing auth, malformed payload). The signature
+                // fingerprint and the attempt count are included so
+                // the host can correlate with the receiver's logs.
+                this.logger.warn(`[WebhookBatchObserver] dead-letter url=${url} attempts=${attempt} ` + `lastStatus=${result.status} lastError=HTTP ${result.status} ` + `type=${event.type} jobExecutionId=${event.jobExecutionId} ` + `secret_sha256=${fingerprint}`);
+                return;
+            }
+            // result.kind === 'server-error' | 'network-error'
+            lastStatus = result.kind === 'server-error' ? result.status : undefined;
+            lastError = result.kind === 'server-error' ? `HTTP ${result.status}` : result.error;
+            if (attempt < totalAttempts) {
+                // The retry schedule has exactly `attempts - 1`
+                // entries (delays BETWEEN attempts). When attempts
+                // is < 4 (test override), the array is sliced to
+                // match — we do not extend the schedule.
+                const delayIndex = Math.min(attempt - 1, this.retryDelaysMs.length - 1);
+                const delayMs = this.retryDelaysMs[delayIndex] ?? 0;
+                this.logger.debug(`retry url=${url} attempt=${attempt}/${totalAttempts} ` + `status=${lastStatus ?? 'n/a'} lastError=${lastError} ` + `nextDelayMs=${delayMs}`);
+                await sleep(delayMs);
+            }
+        }
+        // Final failure — log dead-letter. NEVER include the
+        // secret. The fingerprint is a SHA-256 prefix (12 hex
+        // chars) that operators can use to correlate dead-letters
+        // across services without exposing the secret.
+        this.logger.warn(`[WebhookBatchObserver] dead-letter url=${url} attempts=${totalAttempts} ` + `lastStatus=${lastStatus ?? 'n/a'} lastError=${lastError ?? 'n/a'} ` + `type=${event.type} jobExecutionId=${event.jobExecutionId} ` + `secret_sha256=${fingerprint}`);
+    }
+    /**
+   * Single POST attempt. The signature header is sent on
+   * every attempt (the body bytes are identical across
+   * attempts; the receiver can verify the signature against
+   * any of them).
+   *
+   * The result is a discriminated union:
+   *   - `kind: 'success'`        — 2xx (or 3xx; we follow
+   *     the redirect by default in `fetch`, but the
+   *     receiver's terminal status is what we report)
+   *   - `kind: 'client-error'`   — 4xx (no retry)
+   *   - `kind: 'server-error'`   — 5xx (retry)
+   *   - `kind: 'network-error'`  — fetch threw, or
+   *     `AbortError` from the timeout (retry)
+   */ async attemptOnce(url, body, signature, timestamp) {
+        const controller = new AbortController();
+        const timer = setTimeout(()=>controller.abort(), this.options.timeoutMs);
+        try {
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    [_webhooksigning.SIGNATURE_HEADER_NAME]: signature,
+                    'x-nest-batch-timestamp': String(timestamp)
+                },
+                body,
+                signal: controller.signal,
+                // fetch follows 3xx redirects by default; the
+                // redirect target's terminal status drives the
+                // retry decision per the v1 contract
+                // (`docs/RELEASE-0.2.0.md` §7.3).
+                redirect: 'follow'
+            });
+            const status = response.status;
+            if (status >= 200 && status < 300) {
+                return {
+                    kind: 'success',
+                    status
+                };
+            }
+            if (status >= 400 && status < 500) {
+                return {
+                    kind: 'client-error',
+                    status
+                };
+            }
+            // 5xx (and 3xx that somehow slipped past redirect:
+            // should not happen with `redirect: 'follow'`, but
+            // be defensive). Treat anything >= 500 as a
+            // server-error and retry.
+            return {
+                kind: 'server-error',
+                status
+            };
+        } catch (err) {
+            // Network error, DNS failure, AbortError from the
+            // timeout, etc. All treated as retryable per the v1
+            // contract.
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                kind: 'network-error',
+                error: message
+            };
+        } finally{
+            clearTimeout(timer);
+        }
+    }
+};
+WebhookBatchObserver = _ts_decorate([
+    (0, _common.Injectable)(),
+    _ts_param(0, (0, _common.Inject)(_moduleoptions.WEBHOOK_MODULE_OPTIONS)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof ResolvedWebhookOptions === "undefined" ? Object : ResolvedWebhookOptions
+    ])
+], WebhookBatchObserver);
+// -----------------------------------------------------------------------
+// Internal helpers
+// -----------------------------------------------------------------------
+/**
+ * Sleep for `ms` milliseconds. Returns a promise that
+ * resolves with no value. Used between retry attempts. The
+ * `ms <= 0` short-circuit keeps the fast-mode test
+ * schedule (`1ms`, `5ms`, ...) from producing timer
+ * warnings.
+ */ function sleep(ms) {
+    if (ms <= 0) return Promise.resolve();
+    return new Promise((resolve)=>{
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Defensive deep-clone of an arbitrary `JsonValue`. The
+ * `BatchEvent.data` field is typed as `JsonValue` and is
+ * shared with the executor's internal state; we clone it
+ * so the observer cannot mutate the executor by reference.
+ * `structuredClone` is available in Node 17+ and is the
+ * fastest safe deep-clone for JSON-shaped data.
+ */ function cloneJson(value) {
+    if (value === null || typeof value !== 'object') return value;
+    // structuredClone can throw on non-cloneable values
+    // (e.g. functions, symbols). The BatchEvent contract
+    // guarantees `data` is `JsonValue`, so the catch is
+    // purely defensive.
+    try {
+        return structuredClone(value);
+    } catch  {
+        return value;
+    }
+}
+
+//# sourceMappingURL=webhook-batch.observer.js.map

package/dist/src/webhook-batch.observer.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/webhook-batch.observer.ts"],"sourcesContent":["import { Inject, Injectable, Logger } from '@nestjs/common';\nimport {\n  BATCH_EVENT,\n  type BatchEvent,\n  type BatchEventType,\n  type BatchObserver,\n} from '@nest-batch/core';\n\nimport {\n  DEFAULT_WEBHOOK_RETRY_DELAYS_MS,\n  FAST_WEBHOOK_RETRY_DELAYS_MS,\n  WEBHOOK_MODULE_OPTIONS,\n  type ResolvedWebhookOptions,\n  type WebhookLogger,\n} from './module-options';\nimport {\n  SIGNATURE_HEADER_NAME,\n  buildSignatureHeader,\n  fingerprintSecret,\n} from './webhook-signing';\n\n/**\n * `WebhookBatchObserver` — the v1 webhook delivery observer.\n *\n * Implements `BatchObserver` from `@nest-batch/core`. On every\n * subscribed `BATCH_EVENT.*` (default:\n * `[JOB_COMPLETED, JOB_FAILED, STEP_FAILED]`) the observer:\n *\n *   1. Serializes a normalized JSON envelope\n *      `{ version: 1, type, timestamp, jobId, execution }`.\n *   2. Computes the v1 HMAC-SHA256 signature over\n *      `<unix>.<raw-body>` (Stripe-style).\n *   3. POSTs the envelope + `X-Nest-Batch-Signature` header to\n *      every URL in `urls`.\n *   4. Retries on 5xx and network errors through the fixed\n *      4-attempt budget at `[1s, 5s, 25s, 125s]`. HTTP 4xx\n *      responses are NOT retried (client error, won't change).\n *   5. On final failure, emits a `logger.warn` dead-letter line\n *      including the URL, attempt count, last status / error,\n *      and a SHA-256 fingerprint of the secret (NEVER the\n *      secret itself).\n *\n * The observer is the v1 contract documented in\n * `docs/RELEASE-0.2.0.md` §7 and pinned by T-AC-5\n * (`packages/webhook/tests/webhook-observer.test.ts`).\n */\n@Injectable()\nexport class WebhookBatchObserver implements BatchObserver {\n  private readonly logger: WebhookLogger;\n\n  /** Resolved + frozen options. The secret lives here and nowhere else. */\n  private readonly options: ResolvedWebhookOptions;\n\n  /**\n   * Cached lookup of the subscription set. Built once at\n   * construction time so `onEvent` is a single `Set.has` check.\n   */\n  private readonly subscribed: ReadonlySet<BatchEventType>;\n\n  /**\n   * Test-only override for the retry schedule. When\n   * `process.env.WEBHOOK_TEST_FAST === '1'`, the schedule is\n   * `[1ms, 5ms, 25ms, 125ms]` so the suite can exercise the\n   * 4-attempt path without waiting 156 seconds. The override\n   * is gated behind an env var so production cannot trip it\n   * by accident.\n   */\n  private readonly retryDelaysMs: readonly number[];\n\n  /**\n   * Sentinel subscriber set: defaults to\n   * `[JOB_COMPLETED, JOB_FAILED, STEP_FAILED]`. Overridable via\n   * the `events` option in `forRoot({...})`.\n   */\n  constructor(\n    @Inject(WEBHOOK_MODULE_OPTIONS) options: ResolvedWebhookOptions,\n  ) {\n    this.options = options;\n    this.logger = options.logger ?? new Logger(WebhookBatchObserver.name);\n    this.subscribed = new Set(options.events);\n    this.retryDelaysMs =\n      process.env['WEBHOOK_TEST_FAST'] === '1'\n        ? FAST_WEBHOOK_RETRY_DELAYS_MS\n        : DEFAULT_WEBHOOK_RETRY_DELAYS_MS;\n  }\n\n  /**\n   * `BatchObserver` entry point. Filters by the subscription\n   * set, then dispatches to every URL. NEVER throws — a slow /\n   * failing observer must not poison the executor (the\n   * JobExecutor already swallows observer errors, but we are\n   * defensive in depth).\n   */\n  async onEvent(event: BatchEvent): Promise<void> {\n    if (!this.subscribed.has(event.type)) return;\n    if (this.options.urls.length === 0) return;\n    try {\n      await this.deliverToAll(event);\n    } catch (err) {\n      // Defence in depth: the JobExecutor already swallows\n      // observer errors, but we re-assert it here so a single\n      // failing URL cannot starve the rest. The per-URL\n      // delivery loop has its own try/catch and writes a\n      // dead-letter `warn` for fully-failed URLs, so this\n      // outer catch only fires for genuinely unexpected\n      // errors (e.g. a synchronous throw in the envelope\n      // builder). The secret is NEVER included in this\n      // message.\n      this.logger.warn(\n        `unexpected observer error type=${event.type} ` +\n          `jobExecutionId=${event.jobExecutionId}: ` +\n          `${err instanceof Error ? err.message : String(err)}`,\n      );\n    }\n  }\n\n  // -----------------------------------------------------------------------\n  // Fan-out\n  // -----------------------------------------------------------------------\n\n  /**\n   * Build the envelope once, then POST to every URL in\n   * `urls` in parallel. A single URL's retry exhaustion does\n   * not affect the other URLs — each URL has its own\n   * `deliverToUrl` invocation and its own dead-letter line.\n   *\n   * The envelope is built with `JSON.stringify` (NOT a Nest\n   * serializer) so the bytes are stable and match the HMAC\n   * input byte-for-byte. The body string is the literal\n   * argument to `fetch`, so the receiver sees the same\n   * bytes the observer signed.\n   */\n  private async deliverToAll(event: BatchEvent): Promise<void> {\n    const envelope = this.buildEnvelope(event);\n    const body = JSON.stringify(envelope);\n    await Promise.all(\n      this.options.urls.map((url) => this.deliverToUrl(url, event, body)),\n    );\n  }\n\n  /**\n   * Build the v1 envelope payload. The shape is the contract\n   * the receiver expects; changing it is a breaking change.\n   *\n   *   - `version: 1` — the envelope schema version (the\n   *     `v1=` in the signature header is the SIGNATURE\n   *     version, not the ENVELOPE version; they are\n   *     independent).\n   *   - `type` — the `BatchEvent.type` string verbatim\n   *     (e.g. `nest-batch.job.completed`).\n   *   - `timestamp` — the event's `Date` serialized as\n   *     ISO-8601 (the original `Date` is not JSON-safe).\n   *   - `jobId` — the `jobExecutionId` (the `BatchEvent`\n   *     contract guarantees this is always set).\n   *   - `execution` — the `JobExecution` shape derived from\n   *     the event's `data` payload. The observer treats\n   *     `data` as opaque `JsonValue` and passes it through\n   *     after a defensive deep-copy via `structuredClone`\n   *     so the observer cannot mutate the executor's\n   *     internal state by reference.\n   *   - `stepId` — present for STEP\\_\\* / CHUNK\\_\\* / ITEM\\_\\*\n   *     events; absent for JOB\\_\\* events. Mirrors the\n   *     `BatchEvent.stepExecutionId` contract.\n   */\n  private buildEnvelope(event: BatchEvent): WebhookEnvelope {\n    return {\n      version: 1,\n      type: event.type,\n      timestamp: event.timestamp.toISOString(),\n      jobId: event.jobExecutionId,\n      ...(event.stepExecutionId !== undefined\n        ? { stepId: event.stepExecutionId }\n        : {}),\n      execution: cloneJson(event.data),\n    };\n  }\n\n  // -----------------------------------------------------------------------\n  // Per-URL delivery with retry\n  // -----------------------------------------------------------------------\n\n  /**\n   * POST the envelope to one URL with the full retry budget.\n   * Stops on the first 2xx; retries on 5xx and network errors;\n   * does NOT retry on 4xx; emits a dead-letter `warn` on\n   * exhaustion. The body is signed once; the same signed body\n   * is sent on every attempt.\n   */\n  private async deliverToUrl(\n    url: string,\n    event: BatchEvent,\n    body: string,\n  ): Promise<void> {\n    const timestamp = Math.floor(Date.now() / 1000);\n    const signature = buildSignatureHeader(\n      this.options.secret,\n      timestamp,\n      body,\n    );\n    const fingerprint = fingerprintSecret(this.options.secret);\n\n    const totalAttempts = this.options.attempts;\n    let lastStatus: number | undefined;\n    let lastError: string | undefined;\n\n    for (let attempt = 1; attempt <= totalAttempts; attempt++) {\n      const result = await this.attemptOnce(url, body, signature, timestamp);\n      if (result.kind === 'success') {\n        if (attempt > 1) {\n          this.logger.log(\n            `delivered url=${url} type=${event.type} ` +\n              `jobExecutionId=${event.jobExecutionId} attempt=${attempt}/${totalAttempts} ` +\n              `status=${result.status} (after retry)`,\n          );\n        } else {\n          this.logger.debug(\n            `delivered url=${url} type=${event.type} ` +\n              `jobExecutionId=${event.jobExecutionId} attempt=${attempt}/${totalAttempts} ` +\n              `status=${result.status}`,\n          );\n        }\n        return;\n      }\n      if (result.kind === 'client-error') {\n        // 4xx — NO retry. Log at `warn` and return. The host\n        // is expected to fix the misconfiguration (bad URL,\n        // missing auth, malformed payload). The signature\n        // fingerprint and the attempt count are included so\n        // the host can correlate with the receiver's logs.\n        this.logger.warn(\n          `[WebhookBatchObserver] dead-letter url=${url} attempts=${attempt} ` +\n            `lastStatus=${result.status} lastError=HTTP ${result.status} ` +\n            `type=${event.type} jobExecutionId=${event.jobExecutionId} ` +\n            `secret_sha256=${fingerprint}`,\n        );\n        return;\n      }\n      // result.kind === 'server-error' | 'network-error'\n      lastStatus = result.kind === 'server-error' ? result.status : undefined;\n      lastError = result.kind === 'server-error'\n        ? `HTTP ${result.status}`\n        : result.error;\n\n      if (attempt < totalAttempts) {\n        // The retry schedule has exactly `attempts - 1`\n        // entries (delays BETWEEN attempts). When attempts\n        // is < 4 (test override), the array is sliced to\n        // match — we do not extend the schedule.\n        const delayIndex = Math.min(attempt - 1, this.retryDelaysMs.length - 1);\n        const delayMs = this.retryDelaysMs[delayIndex] ?? 0;\n        this.logger.debug(\n          `retry url=${url} attempt=${attempt}/${totalAttempts} ` +\n            `status=${lastStatus ?? 'n/a'} lastError=${lastError} ` +\n            `nextDelayMs=${delayMs}`,\n        );\n        await sleep(delayMs);\n      }\n    }\n\n    // Final failure — log dead-letter. NEVER include the\n    // secret. The fingerprint is a SHA-256 prefix (12 hex\n    // chars) that operators can use to correlate dead-letters\n    // across services without exposing the secret.\n    this.logger.warn(\n      `[WebhookBatchObserver] dead-letter url=${url} attempts=${totalAttempts} ` +\n        `lastStatus=${lastStatus ?? 'n/a'} lastError=${lastError ?? 'n/a'} ` +\n        `type=${event.type} jobExecutionId=${event.jobExecutionId} ` +\n        `secret_sha256=${fingerprint}`,\n    );\n  }\n\n  /**\n   * Single POST attempt. The signature header is sent on\n   * every attempt (the body bytes are identical across\n   * attempts; the receiver can verify the signature against\n   * any of them).\n   *\n   * The result is a discriminated union:\n   *   - `kind: 'success'`        — 2xx (or 3xx; we follow\n   *     the redirect by default in `fetch`, but the\n   *     receiver's terminal status is what we report)\n   *   - `kind: 'client-error'`   — 4xx (no retry)\n   *   - `kind: 'server-error'`   — 5xx (retry)\n   *   - `kind: 'network-error'`  — fetch threw, or\n   *     `AbortError` from the timeout (retry)\n   */\n  private async attemptOnce(\n    url: string,\n    body: string,\n    signature: string,\n    timestamp: number,\n  ): Promise<\n    | { kind: 'success'; status: number }\n    | { kind: 'client-error'; status: number }\n    | { kind: 'server-error'; status: number }\n    | { kind: 'network-error'; error: string }\n  > {\n    const controller = new AbortController();\n    const timer = setTimeout(() => controller.abort(), this.options.timeoutMs);\n    try {\n      const response = await fetch(url, {\n        method: 'POST',\n        headers: {\n          'content-type': 'application/json',\n          [SIGNATURE_HEADER_NAME]: signature,\n          'x-nest-batch-timestamp': String(timestamp),\n        },\n        body,\n        signal: controller.signal,\n        // fetch follows 3xx redirects by default; the\n        // redirect target's terminal status drives the\n        // retry decision per the v1 contract\n        // (`docs/RELEASE-0.2.0.md` §7.3).\n        redirect: 'follow',\n      });\n      const status = response.status;\n      if (status >= 200 && status < 300) {\n        return { kind: 'success', status };\n      }\n      if (status >= 400 && status < 500) {\n        return { kind: 'client-error', status };\n      }\n      // 5xx (and 3xx that somehow slipped past redirect:\n      // should not happen with `redirect: 'follow'`, but\n      // be defensive). Treat anything >= 500 as a\n      // server-error and retry.\n      return { kind: 'server-error', status };\n    } catch (err) {\n      // Network error, DNS failure, AbortError from the\n      // timeout, etc. All treated as retryable per the v1\n      // contract.\n      const message = err instanceof Error ? err.message : String(err);\n      return { kind: 'network-error', error: message };\n    } finally {\n      clearTimeout(timer);\n    }\n  }\n}\n\n// -----------------------------------------------------------------------\n// Internal helpers\n// -----------------------------------------------------------------------\n\n/**\n * Sleep for `ms` milliseconds. Returns a promise that\n * resolves with no value. Used between retry attempts. The\n * `ms <= 0` short-circuit keeps the fast-mode test\n * schedule (`1ms`, `5ms`, ...) from producing timer\n * warnings.\n */\nfunction sleep(ms: number): Promise<void> {\n  if (ms <= 0) return Promise.resolve();\n  return new Promise((resolve) => {\n    setTimeout(resolve, ms);\n  });\n}\n\n/**\n * Defensive deep-clone of an arbitrary `JsonValue`. The\n * `BatchEvent.data` field is typed as `JsonValue` and is\n * shared with the executor's internal state; we clone it\n * so the observer cannot mutate the executor by reference.\n * `structuredClone` is available in Node 17+ and is the\n * fastest safe deep-clone for JSON-shaped data.\n */\nfunction cloneJson<T>(value: T): T {\n  if (value === null || typeof value !== 'object') return value;\n  // structuredClone can throw on non-cloneable values\n  // (e.g. functions, symbols). The BatchEvent contract\n  // guarantees `data` is `JsonValue`, so the catch is\n  // purely defensive.\n  try {\n    return structuredClone(value) as T;\n  } catch {\n    return value;\n  }\n}\n\n// -----------------------------------------------------------------------\n// Public types\n// -----------------------------------------------------------------------\n\n/**\n * The v1 webhook envelope payload. This is the contract the\n * receiver's parser expects. Fields are stable; new fields\n * are additive only and use the `x-` prefix to mark them\n * as out-of-contract for v1.\n */\nexport interface WebhookEnvelope {\n  /** Envelope schema version. Always `1` for v1. */\n  readonly version: 1;\n  /** The `BatchEvent.type` string (e.g. `nest-batch.job.completed`). */\n  readonly type: BatchEventType;\n  /** Event timestamp as ISO-8601. */\n  readonly timestamp: string;\n  /** The `JobExecution.id` (a.k.a. `jobExecutionId`). */\n  readonly jobId: string;\n  /** The `StepExecution.id` (a.k.a. `stepExecutionId`). STEP\\_\\* / CHUNK\\_\\* / ITEM\\_\\* events only. */\n  readonly stepId?: string;\n  /** The `BatchEvent.data` payload, deep-cloned for safety. */\n  readonly execution: unknown;\n}\n\n// Re-export the `BATCH_EVENT` constant so consumers can\n// reference the exact subscription set without having to\n// import `@nest-batch/core` themselves. The names of the\n// event types are part of the public surface.\nexport { BATCH_EVENT };\n"],"names":["BATCH_EVENT","WebhookBatchObserver","logger","options","subscribed","retryDelaysMs","Logger","name","Set","events","process","env","FAST_WEBHOOK_RETRY_DELAYS_MS","DEFAULT_WEBHOOK_RETRY_DELAYS_MS","onEvent","event","has","type","urls","length","deliverToAll","err","warn","jobExecutionId","Error","message","String","envelope","buildEnvelope","body","JSON","stringify","Promise","all","map","url","deliverToUrl","version","timestamp","toISOString","jobId","stepExecutionId","undefined","stepId","execution","cloneJson","data","Math","floor","Date","now","signature","buildSignatureHeader","secret","fingerprint","fingerprintSecret","totalAttempts","attempts","lastStatus","lastError","attempt","result","attemptOnce","kind","log","status","debug","error","delayIndex","min","delayMs","sleep","controller","AbortController","timer","setTimeout","abort","timeoutMs","response","fetch","method","headers","SIGNATURE_HEADER_NAME","signal","redirect","clearTimeout","ms","resolve","value","structuredClone"],"mappings":"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"}

package/dist/src/webhook-signing.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Compute the v1 HMAC-SHA256 signature for the given (timestamp,
+ * raw body) pair.
+ *
+ * Returns the lowercase hex string the receiver compares against
+ * the `v1=` field. The function is timing-safe on the input
+ * (Node's `createHmac` is constant-time per the crypto spec), so
+ * it is safe to use for verification as well.
+ *
+ * @param secret  The host-injected secret. Never logged, never
+ *   serialized, never returned by the helper.
+ * @param timestamp  The unix-seconds integer the signature is
+ *   pinned to. Must be a positive integer; the helper does not
+ *   validate the value (callers may pin it to `Math.floor(Date.now() / 1000)`).
+ * @param rawBody  The exact JSON-serialized body bytes the
+ *   request will POST. Must match the body the receiver HMACs.
+ */
+export declare function signV1(secret: string, timestamp: number, rawBody: string): string;
+/**
+ * Build the full `X-Nest-Batch-Signature` header value for the
+ * given (timestamp, body) pair. The result is the literal
+ * header value, e.g. `t=1717941612,v1=4f3a...`.
+ */
+export declare function buildSignatureHeader(secret: string, timestamp: number, rawBody: string): string;
+/**
+ * Parse a `X-Nest-Batch-Signature` header value back into its
+ * parts. Used by the test server to extract the `t=` and
+ * `v1=` fields for byte-equality verification.
+ *
+ * Throws on malformed input. Does NOT verify the HMAC; the
+ * caller is expected to call `verifyV1` with the original body.
+ */
+export interface ParsedSignature {
+    readonly timestamp: number;
+    readonly v1: string;
+}
+export declare function parseSignatureHeader(header: string): ParsedSignature;
+/**
+ * Timing-safe verification of a `X-Nest-Batch-Signature` header
+ * against a (secret, raw body) pair.
+ *
+ * Returns `true` iff the v1 HMAC matches. Uses `timingSafeEqual`
+ * to prevent timing-leak attacks on the comparison.
+ *
+ * Note: this helper is the SYMMETRIC counterpart of `signV1`.
+ * Receivers (the URL targets) call it after extracting the
+ * header value via `parseSignatureHeader`. The test suite uses
+ * it to assert byte-equality of the HMAC computed by the
+ * observer against the HMAC computed independently with the
+ * same secret + body.
+ */
+export declare function verifyV1(secret: string, timestamp: number, rawBody: string, candidateV1: string): boolean;
+/**
+ * Compute a SHA-256 fingerprint of the secret for use in
+ * dead-letter log lines. The host NEVER wants the secret (or a
+ * substring of it) in a log line, but operators often want a
+ * stable identifier to correlate dead-letter lines across
+ * services ("all 4xx dead-letters today used secret_sha256=abc...").
+ *
+ * Returns the first 12 hex chars of `sha256(secret)` — enough
+ * to be useful as a correlation tag, short enough that it
+ * cannot be brute-forced back to the secret.
+ */
+export declare function fingerprintSecret(secret: string): string;
+/**
+ * The literal header name. Re-exported so the test server and
+ * the observer never have to repeat the magic string.
+ */
+export declare const SIGNATURE_HEADER_NAME = "X-Nest-Batch-Signature";
+//# sourceMappingURL=webhook-signing.d.ts.map

package/dist/src/webhook-signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-signing.d.ts","sourceRoot":"","sources":["../../src/webhook-signing.ts"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,MAAM,CAaR;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,MAAM,CAGR;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CA2BpE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,OAAO,CAiBT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKxD;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,2BAAmB,CAAC"}

package/dist/src/webhook-signing.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get SIGNATURE_HEADER_NAME () {
+        return SIGNATURE_HEADER_NAME;
+    },
+    get buildSignatureHeader () {
+        return buildSignatureHeader;
+    },
+    get fingerprintSecret () {
+        return fingerprintSecret;
+    },
+    get parseSignatureHeader () {
+        return parseSignatureHeader;
+    },
+    get signV1 () {
+        return signV1;
+    },
+    get verifyV1 () {
+        return verifyV1;
+    }
+});
+const _nodecrypto = require("node:crypto");
+/**
+ * HMAC-SHA256 signing helper for the outbound webhook envelope.
+ *
+ * The signature is shipped in the `X-Nest-Batch-Signature` header
+ * with the Stripe-style `t=<unix>,v1=<hex>` shape:
+ *
+ *   X-Nest-Batch-Signature: t=1717941612,v1=4f3a2b...c1d
+ *
+ * Where:
+ *   - `t` is the unix-seconds timestamp the receiver should use
+ *     to enforce a replay window (recommended: 5 minutes).
+ *   - `v1` is the lowercase hex of
+ *     `HMAC_SHA256(secret, "<unix>.<raw-body>")`.
+ *
+ * The `<raw-body>` is the EXACT JSON-serialized request body bytes
+ * (not a re-serialization). Callers must pass the same string
+ * they POST — the helper does not re-serialize. This avoids the
+ * classic "server signed stringified JSON, client re-stringified
+ * with different key order" footgun.
+ *
+ * The `v1` key is the v1 contract; a future v2 may add
+ * `v2=`-prefixed scheme-version constants (e.g. a SHA-512
+ * variant). Receivers MUST reject unknown `vN` keys.
+ *
+ * Reference: `docs/RELEASE-0.2.0.md` §7.4.
+ */ const SIGNATURE_HEADER = 'X-Nest-Batch-Signature';
+const SIGNATURE_VERSION = 'v1';
+function signV1(secret, timestamp, rawBody) {
+    if (typeof secret !== 'string' || secret.length === 0) {
+        throw new Error('[webhook-signing] secret must be a non-empty string');
+    }
+    if (!Number.isFinite(timestamp) || timestamp < 0) {
+        throw new Error('[webhook-signing] timestamp must be a non-negative number');
+    }
+    if (typeof rawBody !== 'string') {
+        throw new Error('[webhook-signing] rawBody must be a string');
+    }
+    const hmac = (0, _nodecrypto.createHmac)('sha256', secret);
+    hmac.update(`${timestamp}.${rawBody}`);
+    return hmac.digest('hex');
+}
+function buildSignatureHeader(secret, timestamp, rawBody) {
+    const v1 = signV1(secret, timestamp, rawBody);
+    return `t=${timestamp},${SIGNATURE_VERSION}=${v1}`;
+}
+function parseSignatureHeader(header) {
+    if (typeof header !== 'string' || header.length === 0) {
+        throw new Error('[webhook-signing] header is empty');
+    }
+    const parts = header.split(',').map((p)=>p.trim());
+    let timestamp;
+    let v1;
+    for (const part of parts){
+        if (part.startsWith('t=')) {
+            const raw = part.slice(2);
+            timestamp = Number.parseInt(raw, 10);
+            if (!Number.isFinite(timestamp) || timestamp < 0) {
+                throw new Error(`[webhook-signing] invalid t= value: ${raw}`);
+            }
+        } else if (part.startsWith(`${SIGNATURE_VERSION}=`)) {
+            v1 = part.slice(SIGNATURE_VERSION.length + 1);
+            if (v1.length === 0) {
+                throw new Error(`[webhook-signing] empty ${SIGNATURE_VERSION}= value`);
+            }
+        }
+    }
+    if (timestamp === undefined || v1 === undefined) {
+        throw new Error(`[webhook-signing] header missing t= or ${SIGNATURE_VERSION}= field: ${header}`);
+    }
+    return {
+        timestamp,
+        v1
+    };
+}
+function verifyV1(secret, timestamp, rawBody, candidateV1) {
+    const expected = signV1(secret, timestamp, rawBody);
+    // Both `expected` and `candidateV1` are lowercase hex of the
+    // same length for a given (secret, body) pair, so the equal-
+    // length precondition of `timingSafeEqual` holds. Defensive
+    // length check: if the candidate is the wrong length, return
+    // false without invoking the constant-time compare (the
+    // length itself is not a secret).
+    if (candidateV1.length !== expected.length) return false;
+    try {
+        return (0, _nodecrypto.timingSafeEqual)(Buffer.from(expected, 'hex'), Buffer.from(candidateV1, 'hex'));
+    } catch  {
+        return false;
+    }
+}
+function fingerprintSecret(secret) {
+    if (typeof secret !== 'string' || secret.length === 0) {
+        return '<missing>';
+    }
+    return (0, _nodecrypto.createHash)('sha256').update(secret, 'utf8').digest('hex').slice(0, 12);
+}
+const SIGNATURE_HEADER_NAME = SIGNATURE_HEADER;
+
+//# sourceMappingURL=webhook-signing.js.map

package/dist/src/webhook-signing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/webhook-signing.ts"],"sourcesContent":["import { createHmac, createHash, timingSafeEqual } from 'node:crypto';\n\n/**\n * HMAC-SHA256 signing helper for the outbound webhook envelope.\n *\n * The signature is shipped in the `X-Nest-Batch-Signature` header\n * with the Stripe-style `t=<unix>,v1=<hex>` shape:\n *\n *   X-Nest-Batch-Signature: t=1717941612,v1=4f3a2b...c1d\n *\n * Where:\n *   - `t` is the unix-seconds timestamp the receiver should use\n *     to enforce a replay window (recommended: 5 minutes).\n *   - `v1` is the lowercase hex of\n *     `HMAC_SHA256(secret, \"<unix>.<raw-body>\")`.\n *\n * The `<raw-body>` is the EXACT JSON-serialized request body bytes\n * (not a re-serialization). Callers must pass the same string\n * they POST — the helper does not re-serialize. This avoids the\n * classic \"server signed stringified JSON, client re-stringified\n * with different key order\" footgun.\n *\n * The `v1` key is the v1 contract; a future v2 may add\n * `v2=`-prefixed scheme-version constants (e.g. a SHA-512\n * variant). Receivers MUST reject unknown `vN` keys.\n *\n * Reference: `docs/RELEASE-0.2.0.md` §7.4.\n */\n\nconst SIGNATURE_HEADER = 'X-Nest-Batch-Signature';\nconst SIGNATURE_VERSION = 'v1';\n\n/**\n * Compute the v1 HMAC-SHA256 signature for the given (timestamp,\n * raw body) pair.\n *\n * Returns the lowercase hex string the receiver compares against\n * the `v1=` field. The function is timing-safe on the input\n * (Node's `createHmac` is constant-time per the crypto spec), so\n * it is safe to use for verification as well.\n *\n * @param secret  The host-injected secret. Never logged, never\n *   serialized, never returned by the helper.\n * @param timestamp  The unix-seconds integer the signature is\n *   pinned to. Must be a positive integer; the helper does not\n *   validate the value (callers may pin it to `Math.floor(Date.now() / 1000)`).\n * @param rawBody  The exact JSON-serialized body bytes the\n *   request will POST. Must match the body the receiver HMACs.\n */\nexport function signV1(\n  secret: string,\n  timestamp: number,\n  rawBody: string,\n): string {\n  if (typeof secret !== 'string' || secret.length === 0) {\n    throw new Error('[webhook-signing] secret must be a non-empty string');\n  }\n  if (!Number.isFinite(timestamp) || timestamp < 0) {\n    throw new Error('[webhook-signing] timestamp must be a non-negative number');\n  }\n  if (typeof rawBody !== 'string') {\n    throw new Error('[webhook-signing] rawBody must be a string');\n  }\n  const hmac = createHmac('sha256', secret);\n  hmac.update(`${timestamp}.${rawBody}`);\n  return hmac.digest('hex');\n}\n\n/**\n * Build the full `X-Nest-Batch-Signature` header value for the\n * given (timestamp, body) pair. The result is the literal\n * header value, e.g. `t=1717941612,v1=4f3a...`.\n */\nexport function buildSignatureHeader(\n  secret: string,\n  timestamp: number,\n  rawBody: string,\n): string {\n  const v1 = signV1(secret, timestamp, rawBody);\n  return `t=${timestamp},${SIGNATURE_VERSION}=${v1}`;\n}\n\n/**\n * Parse a `X-Nest-Batch-Signature` header value back into its\n * parts. Used by the test server to extract the `t=` and\n * `v1=` fields for byte-equality verification.\n *\n * Throws on malformed input. Does NOT verify the HMAC; the\n * caller is expected to call `verifyV1` with the original body.\n */\nexport interface ParsedSignature {\n  readonly timestamp: number;\n  readonly v1: string;\n}\n\nexport function parseSignatureHeader(header: string): ParsedSignature {\n  if (typeof header !== 'string' || header.length === 0) {\n    throw new Error('[webhook-signing] header is empty');\n  }\n  const parts = header.split(',').map((p) => p.trim());\n  let timestamp: number | undefined;\n  let v1: string | undefined;\n  for (const part of parts) {\n    if (part.startsWith('t=')) {\n      const raw = part.slice(2);\n      timestamp = Number.parseInt(raw, 10);\n      if (!Number.isFinite(timestamp) || timestamp < 0) {\n        throw new Error(`[webhook-signing] invalid t= value: ${raw}`);\n      }\n    } else if (part.startsWith(`${SIGNATURE_VERSION}=`)) {\n      v1 = part.slice(SIGNATURE_VERSION.length + 1);\n      if (v1.length === 0) {\n        throw new Error(`[webhook-signing] empty ${SIGNATURE_VERSION}= value`);\n      }\n    }\n  }\n  if (timestamp === undefined || v1 === undefined) {\n    throw new Error(\n      `[webhook-signing] header missing t= or ${SIGNATURE_VERSION}= field: ${header}`,\n    );\n  }\n  return { timestamp, v1 };\n}\n\n/**\n * Timing-safe verification of a `X-Nest-Batch-Signature` header\n * against a (secret, raw body) pair.\n *\n * Returns `true` iff the v1 HMAC matches. Uses `timingSafeEqual`\n * to prevent timing-leak attacks on the comparison.\n *\n * Note: this helper is the SYMMETRIC counterpart of `signV1`.\n * Receivers (the URL targets) call it after extracting the\n * header value via `parseSignatureHeader`. The test suite uses\n * it to assert byte-equality of the HMAC computed by the\n * observer against the HMAC computed independently with the\n * same secret + body.\n */\nexport function verifyV1(\n  secret: string,\n  timestamp: number,\n  rawBody: string,\n  candidateV1: string,\n): boolean {\n  const expected = signV1(secret, timestamp, rawBody);\n  // Both `expected` and `candidateV1` are lowercase hex of the\n  // same length for a given (secret, body) pair, so the equal-\n  // length precondition of `timingSafeEqual` holds. Defensive\n  // length check: if the candidate is the wrong length, return\n  // false without invoking the constant-time compare (the\n  // length itself is not a secret).\n  if (candidateV1.length !== expected.length) return false;\n  try {\n    return timingSafeEqual(\n      Buffer.from(expected, 'hex'),\n      Buffer.from(candidateV1, 'hex'),\n    );\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Compute a SHA-256 fingerprint of the secret for use in\n * dead-letter log lines. The host NEVER wants the secret (or a\n * substring of it) in a log line, but operators often want a\n * stable identifier to correlate dead-letter lines across\n * services (\"all 4xx dead-letters today used secret_sha256=abc...\").\n *\n * Returns the first 12 hex chars of `sha256(secret)` — enough\n * to be useful as a correlation tag, short enough that it\n * cannot be brute-forced back to the secret.\n */\nexport function fingerprintSecret(secret: string): string {\n  if (typeof secret !== 'string' || secret.length === 0) {\n    return '<missing>';\n  }\n  return createHash('sha256').update(secret, 'utf8').digest('hex').slice(0, 12);\n}\n\n/**\n * The literal header name. Re-exported so the test server and\n * the observer never have to repeat the magic string.\n */\nexport const SIGNATURE_HEADER_NAME = SIGNATURE_HEADER;\n"],"names":["SIGNATURE_HEADER_NAME","buildSignatureHeader","fingerprintSecret","parseSignatureHeader","signV1","verifyV1","SIGNATURE_HEADER","SIGNATURE_VERSION","secret","timestamp","rawBody","length","Error","Number","isFinite","hmac","createHmac","update","digest","v1","header","parts","split","map","p","trim","part","startsWith","raw","slice","parseInt","undefined","candidateV1","expected","timingSafeEqual","Buffer","from","createHash"],"mappings":"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"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@nest-batch/webhook",
+  "version": "0.2.0",
+  "description": "Webhook delivery observer for @nest-batch/core. Subscribes to BATCH_EVENT.* and POSTs HMAC-SHA256-signed JSON envelopes to one or more URLs with exponential-backoff retry and dead-letter logging. Uses native fetch (Node 20+); no HTTP client peer dep.",
+  "license": "MIT",
+  "author": "easdkr",
+  "homepage": "https://github.com/easdkr/nest-batch/tree/main/packages/webhook#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/easdkr/nest-batch.git",
+    "directory": "packages/webhook"
+  },
+  "bugs": {
+    "url": "https://github.com/easdkr/nest-batch/issues"
+  },
+  "keywords": [
+    "nestjs",
+    "batch",
+    "webhook",
+    "hmac",
+    "hmac-sha256",
+    "observer",
+    "dead-letter"
+  ],
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": [
+    "dist/src",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10 || ^11",
+    "@nestjs/core": "^10 || ^11",
+    "@nest-batch/core": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@nest-batch/core": {
+      "optional": false
+    },
+    "@nestjs/common": {
+      "optional": false
+    },
+    "@nestjs/core": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@swc/cli": "^0.7.0",
+    "@swc/core": "^1.10.7",
+    "@types/node": "^22.0.0",
+    "reflect-metadata": "^0.2.2",
+    "typescript": "^5.5.0",
+    "unplugin-swc": "^1.5.0",
+    "vitest": "^2.0.0",
+    "@nest-batch/core": "0.2.0"
+  },
+  "scripts": {
+    "build": "swc src -d dist --config-file ../../.swcrc && tsc --emitDeclarationOnly -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}