@nest-batch/webhook 0.2.0

package/dist/src/module-options.d.ts

@@ -0,0 +1,163 @@
+import type { BatchEventType } from '@nest-batch/core';
+/**
+ * Public options bag for `WebhookBatchModule.forRoot()`.
+ *
+ * The contract the test suite (`tests/webhook-observer.test.ts`,
+ * T-AC-5) asserts against:
+ *
+ *   - `secret` is REQUIRED at the host level. It is never read from
+ *     disk, never defaulted to an empty string, never logged in any
+ *     code path. The optional `WEBHOOK_HMAC_SECRET` env var is the
+ *     fallback ONLY when the host does not pass `secret` (env is
+ *     the host-injection's safety net, not its primary).
+ *   - `urls[]` is the fan-out set. Every subscribed event is POSTed
+ *     to every URL in `urls`. Empty `urls` is a no-op (the observer
+ *     still subscribes, it just never POSTs).
+ *   - `events` is the subscription filter. Defaults to
+ *     `[JOB_COMPLETED, JOB_FAILED, STEP_FAILED]`. Subscribed events
+ *     are the only ones the observer signs + POSTs. A
+ *     `JOB_STARTED` event arrives at `onEvent`, is not in the
+ *     filter, and is dropped silently (the listener is fire-and-
+ *     forget by contract — see `BatchObserver.onEvent`).
+ *   - `attempts` is the number of total POST attempts (1 initial +
+ *     up to `attempts-1` retries). Defaults to 4 (matching the
+ *     fixed 1s/5s/25s/125s backoff schedule). Lowering the value
+ *     is supported for tests; raising it is intentionally NOT
+ *     supported in v1 (the retry schedule is the contract, see
+ *     `docs/RELEASE-0.2.0.md` §7.2).
+ *   - `timeoutMs` is the per-attempt HTTP timeout. Defaults to
+ *     10 000 ms (10 seconds). A timeout is treated as a network
+ *     error and retried through the full attempt budget.
+ *   - `logger` is the Nest `Logger`-compatible interface used for
+ *     the dead-letter `warn` line and the bootstrap notice. When
+ *     omitted, the observer instantiates a `new Logger('WebhookBatchObserver')`.
+ */
+export interface WebhookBatchModuleOptions {
+    /**
+     * Host-injected HMAC-SHA256 secret used to sign outbound
+     * envelopes. REQUIRED when not relying on the `WEBHOOK_HMAC_SECRET`
+     * env fallback. Recommended length: 32+ bytes of randomness
+     * (a per-environment secret, never re-used across services).
+     *
+     * The secret is bound to the `WebhookBatchObserver` instance at
+     * `forRoot` time and is never exported, logged, serialized into
+     * a dead-letter body, or otherwise observable by the host.
+     */
+    readonly secret?: string;
+    /**
+     * One or more absolute URLs the observer will fan out to on
+     * every subscribed event. Empty array is a no-op (the observer
+     * still subscribes to the event stream but never POSTs).
+     */
+    readonly urls: readonly string[];
+    /**
+     * Subscription filter. Defaults to
+     * `[BATCH_EVENT.JOB_COMPLETED, BATCH_EVENT.JOB_FAILED,
+     * BATCH_EVENT.STEP_FAILED]`. The v1 contract is these three
+     * events only; a future v2 may widen the default to STEP_*
+     * events.
+     */
+    readonly events?: readonly BatchEventType[];
+    /**
+     * Total number of POST attempts (initial + retries). Defaults
+     * to 4. Must be `>= 1`; `1` means "no retries" (single POST,
+     * then dead-letter on failure). Values `> 4` are clamped to 4
+     * — the v1 retry schedule is `[1s, 5s, 25s, 125s]` and has
+     * exactly 4 entries; further attempts would have no backoff to
+     * look up.
+     */
+    readonly attempts?: number;
+    /**
+     * Per-attempt HTTP timeout in milliseconds. Defaults to
+     * 10 000 (10 seconds). A timeout is treated as a network
+     * error and retried through the full attempt budget.
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Logger override. The observer is built to use a NestJS
+     * `Logger`-compatible interface (the four `log` / `warn` /
+     * `error` / `debug` methods). When omitted, the observer
+     * instantiates a `new Logger('WebhookBatchObserver')` against
+     * the `console`-backed Nest logger.
+     */
+    readonly logger?: WebhookLogger;
+}
+/**
+ * NestJS-`Logger`-compatible surface used by `WebhookBatchObserver`.
+ *
+ * We type this as a structural subset of `@nestjs/common`'s
+ * `LoggerService` so the host can pass a custom logger without
+ * having to import the full Nest surface. The four methods are
+ * the only ones the observer calls:
+ *
+ *   - `log`   — bootstrap / info-level messages
+ *   - `warn`  — dead-letter payload (post final failure)
+ *   - `error` — configuration / startup errors
+ *   - `debug` — per-attempt diagnostic info (URL, status, latency)
+ */
+export interface WebhookLogger {
+    log(message: string, context?: string): void;
+    warn(message: string, context?: string): void;
+    error(message: string, context?: string): void;
+    debug(message: string, context?: string): void;
+}
+/**
+ * Fully-resolved options bag the observer consumes at runtime.
+ * `forRoot` is responsible for filling in every default and
+ * freezing the result before handing it to the provider.
+ */
+export interface ResolvedWebhookOptions {
+    readonly secret: string;
+    readonly urls: readonly string[];
+    readonly events: readonly BatchEventType[];
+    readonly attempts: number;
+    readonly timeoutMs: number;
+    readonly logger: WebhookLogger;
+}
+/**
+ * The v1 default subscription set. Documented in
+ * `docs/RELEASE-0.2.0.md` §7.1 and in the README.
+ */
+export declare const DEFAULT_WEBHOOK_EVENTS: readonly BatchEventType[];
+/**
+ * The v1 fixed backoff schedule. Four entries (3 delays between
+ * 4 attempts). Documented in `docs/RELEASE-0.2.0.md` §7.2 and
+ * in the README. The schedule is the contract the test suite
+ * asserts against.
+ */
+export declare const DEFAULT_WEBHOOK_RETRY_DELAYS_MS: readonly number[];
+/**
+ * Fast-mode override for the retry schedule. Activated when
+ * `process.env.WEBHOOK_TEST_FAST === '1'`. The override exists
+ * so the test suite can exercise the 4-attempt retry path
+ * without waiting 156 seconds (1+5+25+125). Test-only; never
+ * touched in production. Documented in the README.
+ */
+export declare const FAST_WEBHOOK_RETRY_DELAYS_MS: readonly number[];
+/**
+ * The DI token under which the resolved options are stored.
+ * `Symbol.for` keeps the key process-scoped and stable across
+ * module versions, mirroring the pattern in
+ * `packages/bullmq/src/module-options.ts`.
+ */
+export declare const WEBHOOK_MODULE_OPTIONS: symbol;
+/**
+ * Resolve a partial `WebhookBatchModuleOptions` into a fully-
+ * populated `ResolvedWebhookOptions`. Called by `forRoot` so the
+ * provider always sees a frozen, default-filled bag.
+ *
+ * Resolution rules:
+ *   - `secret`: if absent, fall back to `process.env.WEBHOOK_HMAC_SECRET`.
+ *     If still absent, throw — the host MUST provide a secret one
+ *     way or another.
+ *   - `urls`: required, no default. Empty array is allowed (no-op
+ *     fan-out).
+ *   - `events`: defaults to `DEFAULT_WEBHOOK_EVENTS`. A `[]` value
+ *     is honoured (the observer subscribes to nothing).
+ *   - `attempts`: defaults to 4. Clamped to `[1, 4]`.
+ *   - `timeoutMs`: defaults to 10 000. Clamped to `>= 100` so the
+ *     observer cannot be configured into "immediate timeout" mode.
+ *   - `logger`: defaults to a `new Logger('WebhookBatchObserver')`.
+ */
+export declare function resolveWebhookOptions(raw: WebhookBatchModuleOptions): ResolvedWebhookOptions;
+//# sourceMappingURL=module-options.d.ts.map

package/dist/src/module-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-options.d.ts","sourceRoot":"","sources":["../../src/module-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;;OASG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAEjC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAE5C;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACjC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChD;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;CAChC;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,cAAc,EASlD,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,EAAE,SAAS,MAAM,EAEnD,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,EAAE,SAAS,MAAM,EAEhD,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,MAEpC,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,yBAAyB,GAC7B,sBAAsB,CAoCxB"}

package/dist/src/module-options.js

@@ -0,0 +1,124 @@
+"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 DEFAULT_WEBHOOK_EVENTS () {
+        return DEFAULT_WEBHOOK_EVENTS;
+    },
+    get DEFAULT_WEBHOOK_RETRY_DELAYS_MS () {
+        return DEFAULT_WEBHOOK_RETRY_DELAYS_MS;
+    },
+    get FAST_WEBHOOK_RETRY_DELAYS_MS () {
+        return FAST_WEBHOOK_RETRY_DELAYS_MS;
+    },
+    get WEBHOOK_MODULE_OPTIONS () {
+        return WEBHOOK_MODULE_OPTIONS;
+    },
+    get resolveWebhookOptions () {
+        return resolveWebhookOptions;
+    }
+});
+const DEFAULT_WEBHOOK_EVENTS = [
+    // JOB_COMPLETED, JOB_FAILED, STEP_FAILED
+    // We do not import BATCH_EVENT here to avoid a circular
+    // dep (the observer re-uses this list at construction
+    // time). The constant is the v1 contract; a future v2
+    // may widen the default to STEP_*, CHUNK_*, ITEM_*.
+    'nest-batch.job.completed',
+    'nest-batch.job.failed',
+    'nest-batch.step.failed'
+];
+const DEFAULT_WEBHOOK_RETRY_DELAYS_MS = [
+    1_000,
+    5_000,
+    25_000,
+    125_000
+];
+const FAST_WEBHOOK_RETRY_DELAYS_MS = [
+    1,
+    5,
+    25,
+    125
+];
+const WEBHOOK_MODULE_OPTIONS = Symbol.for('@nest-batch/webhook/MODULE_OPTIONS');
+function resolveWebhookOptions(raw) {
+    if (raw === null || typeof raw !== 'object') {
+        throw new Error('[WebhookBatchModule] options must be a non-null object');
+    }
+    const secret = pickSecret(raw.secret);
+    if (typeof secret !== 'string' || secret.length === 0) {
+        throw new Error('[WebhookBatchModule] secret is required: pass `secret` to ' + 'forRoot() or set the WEBHOOK_HMAC_SECRET env var');
+    }
+    const urls = Array.isArray(raw.urls) ? raw.urls.slice() : [];
+    for (const url of urls){
+        if (typeof url !== 'string' || url.length === 0) {
+            throw new Error('[WebhookBatchModule] every entry in `urls` must be a non-empty string');
+        }
+    }
+    const events = Array.isArray(raw.events) && raw.events.length > 0 ? raw.events.slice() : DEFAULT_WEBHOOK_EVENTS.slice();
+    const rawAttempts = typeof raw.attempts === 'number' ? raw.attempts : 4;
+    const attempts = Math.max(1, Math.min(4, Math.floor(rawAttempts)));
+    const rawTimeout = typeof raw.timeoutMs === 'number' ? raw.timeoutMs : 10_000;
+    const timeoutMs = Math.max(100, Math.floor(rawTimeout));
+    return Object.freeze({
+        secret,
+        urls,
+        events,
+        attempts,
+        timeoutMs,
+        logger: raw.logger ?? defaultLogger()
+    });
+}
+/**
+ * Pick the secret: host-injected first, env-var fallback second.
+ * Returns `undefined` if neither is set so the caller can throw
+ * a precise error.
+ */ function pickSecret(hostInjected) {
+    if (typeof hostInjected === 'string' && hostInjected.length > 0) {
+        return hostInjected;
+    }
+    const fromEnv = process.env['WEBHOOK_HMAC_SECRET'];
+    if (typeof fromEnv === 'string' && fromEnv.length > 0) {
+        return fromEnv;
+    }
+    return undefined;
+}
+/**
+ * The default `WebhookLogger` — a thin adapter around
+ * `console`. The observer is built to be test-friendly; tests
+ * pass a captured-`console.warn` spy via the `logger` option.
+ */ function defaultLogger() {
+    // We deliberately do NOT import @nestjs/common's `Logger` here
+    // — the `WebhookLogger` is a structural interface, and the
+    // adapter lets the package stay test-runner-agnostic. Tests
+    // pass a console-backed spy; hosts pass a NestJS `Logger`
+    // instance (the structural shape matches the official
+    // `LoggerService`).
+    return {
+        log: (message)=>{
+            // eslint-disable-next-line no-console
+            console.log(`[WebhookBatchObserver] ${message}`);
+        },
+        warn: (message)=>{
+            // eslint-disable-next-line no-console
+            console.warn(`[WebhookBatchObserver] ${message}`);
+        },
+        error: (message)=>{
+            // eslint-disable-next-line no-console
+            console.error(`[WebhookBatchObserver] ${message}`);
+        },
+        debug: (message)=>{
+            // eslint-disable-next-line no-console
+            console.debug(`[WebhookBatchObserver] ${message}`);
+        }
+    };
+}
+
+//# sourceMappingURL=module-options.js.map

package/dist/src/module-options.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/module-options.ts"],"sourcesContent":["import type { BatchEventType } from '@nest-batch/core';\n\n/**\n * Public options bag for `WebhookBatchModule.forRoot()`.\n *\n * The contract the test suite (`tests/webhook-observer.test.ts`,\n * T-AC-5) asserts against:\n *\n *   - `secret` is REQUIRED at the host level. It is never read from\n *     disk, never defaulted to an empty string, never logged in any\n *     code path. The optional `WEBHOOK_HMAC_SECRET` env var is the\n *     fallback ONLY when the host does not pass `secret` (env is\n *     the host-injection's safety net, not its primary).\n *   - `urls[]` is the fan-out set. Every subscribed event is POSTed\n *     to every URL in `urls`. Empty `urls` is a no-op (the observer\n *     still subscribes, it just never POSTs).\n *   - `events` is the subscription filter. Defaults to\n *     `[JOB_COMPLETED, JOB_FAILED, STEP_FAILED]`. Subscribed events\n *     are the only ones the observer signs + POSTs. A\n *     `JOB_STARTED` event arrives at `onEvent`, is not in the\n *     filter, and is dropped silently (the listener is fire-and-\n *     forget by contract — see `BatchObserver.onEvent`).\n *   - `attempts` is the number of total POST attempts (1 initial +\n *     up to `attempts-1` retries). Defaults to 4 (matching the\n *     fixed 1s/5s/25s/125s backoff schedule). Lowering the value\n *     is supported for tests; raising it is intentionally NOT\n *     supported in v1 (the retry schedule is the contract, see\n *     `docs/RELEASE-0.2.0.md` §7.2).\n *   - `timeoutMs` is the per-attempt HTTP timeout. Defaults to\n *     10 000 ms (10 seconds). A timeout is treated as a network\n *     error and retried through the full attempt budget.\n *   - `logger` is the Nest `Logger`-compatible interface used for\n *     the dead-letter `warn` line and the bootstrap notice. When\n *     omitted, the observer instantiates a `new Logger('WebhookBatchObserver')`.\n */\nexport interface WebhookBatchModuleOptions {\n  /**\n   * Host-injected HMAC-SHA256 secret used to sign outbound\n   * envelopes. REQUIRED when not relying on the `WEBHOOK_HMAC_SECRET`\n   * env fallback. Recommended length: 32+ bytes of randomness\n   * (a per-environment secret, never re-used across services).\n   *\n   * The secret is bound to the `WebhookBatchObserver` instance at\n   * `forRoot` time and is never exported, logged, serialized into\n   * a dead-letter body, or otherwise observable by the host.\n   */\n  readonly secret?: string;\n\n  /**\n   * One or more absolute URLs the observer will fan out to on\n   * every subscribed event. Empty array is a no-op (the observer\n   * still subscribes to the event stream but never POSTs).\n   */\n  readonly urls: readonly string[];\n\n  /**\n   * Subscription filter. Defaults to\n   * `[BATCH_EVENT.JOB_COMPLETED, BATCH_EVENT.JOB_FAILED,\n   * BATCH_EVENT.STEP_FAILED]`. The v1 contract is these three\n   * events only; a future v2 may widen the default to STEP_*\n   * events.\n   */\n  readonly events?: readonly BatchEventType[];\n\n  /**\n   * Total number of POST attempts (initial + retries). Defaults\n   * to 4. Must be `>= 1`; `1` means \"no retries\" (single POST,\n   * then dead-letter on failure). Values `> 4` are clamped to 4\n   * — the v1 retry schedule is `[1s, 5s, 25s, 125s]` and has\n   * exactly 4 entries; further attempts would have no backoff to\n   * look up.\n   */\n  readonly attempts?: number;\n\n  /**\n   * Per-attempt HTTP timeout in milliseconds. Defaults to\n   * 10 000 (10 seconds). A timeout is treated as a network\n   * error and retried through the full attempt budget.\n   */\n  readonly timeoutMs?: number;\n\n  /**\n   * Logger override. The observer is built to use a NestJS\n   * `Logger`-compatible interface (the four `log` / `warn` /\n   * `error` / `debug` methods). When omitted, the observer\n   * instantiates a `new Logger('WebhookBatchObserver')` against\n   * the `console`-backed Nest logger.\n   */\n  readonly logger?: WebhookLogger;\n}\n\n/**\n * NestJS-`Logger`-compatible surface used by `WebhookBatchObserver`.\n *\n * We type this as a structural subset of `@nestjs/common`'s\n * `LoggerService` so the host can pass a custom logger without\n * having to import the full Nest surface. The four methods are\n * the only ones the observer calls:\n *\n *   - `log`   — bootstrap / info-level messages\n *   - `warn`  — dead-letter payload (post final failure)\n *   - `error` — configuration / startup errors\n *   - `debug` — per-attempt diagnostic info (URL, status, latency)\n */\nexport interface WebhookLogger {\n  log(message: string, context?: string): void;\n  warn(message: string, context?: string): void;\n  error(message: string, context?: string): void;\n  debug(message: string, context?: string): void;\n}\n\n/**\n * Fully-resolved options bag the observer consumes at runtime.\n * `forRoot` is responsible for filling in every default and\n * freezing the result before handing it to the provider.\n */\nexport interface ResolvedWebhookOptions {\n  readonly secret: string;\n  readonly urls: readonly string[];\n  readonly events: readonly BatchEventType[];\n  readonly attempts: number;\n  readonly timeoutMs: number;\n  readonly logger: WebhookLogger;\n}\n\n/**\n * The v1 default subscription set. Documented in\n * `docs/RELEASE-0.2.0.md` §7.1 and in the README.\n */\nexport const DEFAULT_WEBHOOK_EVENTS: readonly BatchEventType[] = [\n  // JOB_COMPLETED, JOB_FAILED, STEP_FAILED\n  // We do not import BATCH_EVENT here to avoid a circular\n  // dep (the observer re-uses this list at construction\n  // time). The constant is the v1 contract; a future v2\n  // may widen the default to STEP_*, CHUNK_*, ITEM_*.\n  'nest-batch.job.completed',\n  'nest-batch.job.failed',\n  'nest-batch.step.failed',\n] as const;\n\n/**\n * The v1 fixed backoff schedule. Four entries (3 delays between\n * 4 attempts). Documented in `docs/RELEASE-0.2.0.md` §7.2 and\n * in the README. The schedule is the contract the test suite\n * asserts against.\n */\nexport const DEFAULT_WEBHOOK_RETRY_DELAYS_MS: readonly number[] = [\n  1_000, 5_000, 25_000, 125_000,\n] as const;\n\n/**\n * Fast-mode override for the retry schedule. Activated when\n * `process.env.WEBHOOK_TEST_FAST === '1'`. The override exists\n * so the test suite can exercise the 4-attempt retry path\n * without waiting 156 seconds (1+5+25+125). Test-only; never\n * touched in production. Documented in the README.\n */\nexport const FAST_WEBHOOK_RETRY_DELAYS_MS: readonly number[] = [\n  1, 5, 25, 125,\n] as const;\n\n/**\n * The DI token under which the resolved options are stored.\n * `Symbol.for` keeps the key process-scoped and stable across\n * module versions, mirroring the pattern in\n * `packages/bullmq/src/module-options.ts`.\n */\nexport const WEBHOOK_MODULE_OPTIONS: symbol = Symbol.for(\n  '@nest-batch/webhook/MODULE_OPTIONS',\n);\n\n/**\n * Resolve a partial `WebhookBatchModuleOptions` into a fully-\n * populated `ResolvedWebhookOptions`. Called by `forRoot` so the\n * provider always sees a frozen, default-filled bag.\n *\n * Resolution rules:\n *   - `secret`: if absent, fall back to `process.env.WEBHOOK_HMAC_SECRET`.\n *     If still absent, throw — the host MUST provide a secret one\n *     way or another.\n *   - `urls`: required, no default. Empty array is allowed (no-op\n *     fan-out).\n *   - `events`: defaults to `DEFAULT_WEBHOOK_EVENTS`. A `[]` value\n *     is honoured (the observer subscribes to nothing).\n *   - `attempts`: defaults to 4. Clamped to `[1, 4]`.\n *   - `timeoutMs`: defaults to 10 000. Clamped to `>= 100` so the\n *     observer cannot be configured into \"immediate timeout\" mode.\n *   - `logger`: defaults to a `new Logger('WebhookBatchObserver')`.\n */\nexport function resolveWebhookOptions(\n  raw: WebhookBatchModuleOptions,\n): ResolvedWebhookOptions {\n  if (raw === null || typeof raw !== 'object') {\n    throw new Error(\n      '[WebhookBatchModule] options must be a non-null object',\n    );\n  }\n  const secret = pickSecret(raw.secret);\n  if (typeof secret !== 'string' || secret.length === 0) {\n    throw new Error(\n      '[WebhookBatchModule] secret is required: pass `secret` to ' +\n        'forRoot() or set the WEBHOOK_HMAC_SECRET env var',\n    );\n  }\n  const urls = Array.isArray(raw.urls) ? raw.urls.slice() : [];\n  for (const url of urls) {\n    if (typeof url !== 'string' || url.length === 0) {\n      throw new Error(\n        '[WebhookBatchModule] every entry in `urls` must be a non-empty string',\n      );\n    }\n  }\n  const events = Array.isArray(raw.events) && raw.events.length > 0\n    ? raw.events.slice()\n    : DEFAULT_WEBHOOK_EVENTS.slice();\n  const rawAttempts = typeof raw.attempts === 'number' ? raw.attempts : 4;\n  const attempts = Math.max(1, Math.min(4, Math.floor(rawAttempts)));\n  const rawTimeout = typeof raw.timeoutMs === 'number' ? raw.timeoutMs : 10_000;\n  const timeoutMs = Math.max(100, Math.floor(rawTimeout));\n  return Object.freeze({\n    secret,\n    urls,\n    events,\n    attempts,\n    timeoutMs,\n    logger: raw.logger ?? defaultLogger(),\n  });\n}\n\n/**\n * Pick the secret: host-injected first, env-var fallback second.\n * Returns `undefined` if neither is set so the caller can throw\n * a precise error.\n */\nfunction pickSecret(hostInjected: string | undefined): string | undefined {\n  if (typeof hostInjected === 'string' && hostInjected.length > 0) {\n    return hostInjected;\n  }\n  const fromEnv = process.env['WEBHOOK_HMAC_SECRET'];\n  if (typeof fromEnv === 'string' && fromEnv.length > 0) {\n    return fromEnv;\n  }\n  return undefined;\n}\n\n/**\n * The default `WebhookLogger` — a thin adapter around\n * `console`. The observer is built to be test-friendly; tests\n * pass a captured-`console.warn` spy via the `logger` option.\n */\nfunction defaultLogger(): WebhookLogger {\n  // We deliberately do NOT import @nestjs/common's `Logger` here\n  // — the `WebhookLogger` is a structural interface, and the\n  // adapter lets the package stay test-runner-agnostic. Tests\n  // pass a console-backed spy; hosts pass a NestJS `Logger`\n  // instance (the structural shape matches the official\n  // `LoggerService`).\n  return {\n    log: (message: string) => {\n      // eslint-disable-next-line no-console\n      console.log(`[WebhookBatchObserver] ${message}`);\n    },\n    warn: (message: string) => {\n      // eslint-disable-next-line no-console\n      console.warn(`[WebhookBatchObserver] ${message}`);\n    },\n    error: (message: string) => {\n      // eslint-disable-next-line no-console\n      console.error(`[WebhookBatchObserver] ${message}`);\n    },\n    debug: (message: string) => {\n      // eslint-disable-next-line no-console\n      console.debug(`[WebhookBatchObserver] ${message}`);\n    },\n  };\n}\n"],"names":["DEFAULT_WEBHOOK_EVENTS","DEFAULT_WEBHOOK_RETRY_DELAYS_MS","FAST_WEBHOOK_RETRY_DELAYS_MS","WEBHOOK_MODULE_OPTIONS","resolveWebhookOptions","Symbol","for","raw","Error","secret","pickSecret","length","urls","Array","isArray","slice","url","events","rawAttempts","attempts","Math","max","min","floor","rawTimeout","timeoutMs","Object","freeze","logger","defaultLogger","hostInjected","fromEnv","process","env","undefined","log","message","console","warn","error","debug"],"mappings":";;;;;;;;;;;QAiIaA;eAAAA;;QAiBAC;eAAAA;;QAWAC;eAAAA;;QAUAC;eAAAA;;QAsBGC;eAAAA;;;AA5DT,MAAMJ,yBAAoD;IAC/D,yCAAyC;IACzC,wDAAwD;IACxD,sDAAsD;IACtD,sDAAsD;IACtD,oDAAoD;IACpD;IACA;IACA;CACD;AAQM,MAAMC,kCAAqD;IAChE;IAAO;IAAO;IAAQ;CACvB;AASM,MAAMC,+BAAkD;IAC7D;IAAG;IAAG;IAAI;CACX;AAQM,MAAMC,yBAAiCE,OAAOC,GAAG,CACtD;AAqBK,SAASF,sBACdG,GAA8B;IAE9B,IAAIA,QAAQ,QAAQ,OAAOA,QAAQ,UAAU;QAC3C,MAAM,IAAIC,MACR;IAEJ;IACA,MAAMC,SAASC,WAAWH,IAAIE,MAAM;IACpC,IAAI,OAAOA,WAAW,YAAYA,OAAOE,MAAM,KAAK,GAAG;QACrD,MAAM,IAAIH,MACR,+DACE;IAEN;IACA,MAAMI,OAAOC,MAAMC,OAAO,CAACP,IAAIK,IAAI,IAAIL,IAAIK,IAAI,CAACG,KAAK,KAAK,EAAE;IAC5D,KAAK,MAAMC,OAAOJ,KAAM;QACtB,IAAI,OAAOI,QAAQ,YAAYA,IAAIL,MAAM,KAAK,GAAG;YAC/C,MAAM,IAAIH,MACR;QAEJ;IACF;IACA,MAAMS,SAASJ,MAAMC,OAAO,CAACP,IAAIU,MAAM,KAAKV,IAAIU,MAAM,CAACN,MAAM,GAAG,IAC5DJ,IAAIU,MAAM,CAACF,KAAK,KAChBf,uBAAuBe,KAAK;IAChC,MAAMG,cAAc,OAAOX,IAAIY,QAAQ,KAAK,WAAWZ,IAAIY,QAAQ,GAAG;IACtE,MAAMA,WAAWC,KAAKC,GAAG,CAAC,GAAGD,KAAKE,GAAG,CAAC,GAAGF,KAAKG,KAAK,CAACL;IACpD,MAAMM,aAAa,OAAOjB,IAAIkB,SAAS,KAAK,WAAWlB,IAAIkB,SAAS,GAAG;IACvE,MAAMA,YAAYL,KAAKC,GAAG,CAAC,KAAKD,KAAKG,KAAK,CAACC;IAC3C,OAAOE,OAAOC,MAAM,CAAC;QACnBlB;QACAG;QACAK;QACAE;QACAM;QACAG,QAAQrB,IAAIqB,MAAM,IAAIC;IACxB;AACF;AAEA;;;;CAIC,GACD,SAASnB,WAAWoB,YAAgC;IAClD,IAAI,OAAOA,iBAAiB,YAAYA,aAAanB,MAAM,GAAG,GAAG;QAC/D,OAAOmB;IACT;IACA,MAAMC,UAAUC,QAAQC,GAAG,CAAC,sBAAsB;IAClD,IAAI,OAAOF,YAAY,YAAYA,QAAQpB,MAAM,GAAG,GAAG;QACrD,OAAOoB;IACT;IACA,OAAOG;AACT;AAEA;;;;CAIC,GACD,SAASL;IACP,+DAA+D;IAC/D,2DAA2D;IAC3D,4DAA4D;IAC5D,0DAA0D;IAC1D,sDAAsD;IACtD,oBAAoB;IACpB,OAAO;QACLM,KAAK,CAACC;YACJ,sCAAsC;YACtCC,QAAQF,GAAG,CAAC,CAAC,uBAAuB,EAAEC,SAAS;QACjD;QACAE,MAAM,CAACF;YACL,sCAAsC;YACtCC,QAAQC,IAAI,CAAC,CAAC,uBAAuB,EAAEF,SAAS;QAClD;QACAG,OAAO,CAACH;YACN,sCAAsC;YACtCC,QAAQE,KAAK,CAAC,CAAC,uBAAuB,EAAEH,SAAS;QACnD;QACAI,OAAO,CAACJ;YACN,sCAAsC;YACtCC,QAAQG,KAAK,CAAC,CAAC,uBAAuB,EAAEJ,SAAS;QACnD;IACF;AACF"}

package/dist/src/webhook-batch.module.d.ts

@@ -0,0 +1,59 @@
+import { type DynamicModule } from '@nestjs/common';
+import { BATCH_EVENT, type BatchEventType } from '@nest-batch/core';
+import { type ResolvedWebhookOptions, type WebhookBatchModuleOptions, type WebhookLogger } from './module-options';
+import { WebhookBatchObserver } from './webhook-batch.observer';
+/**
+ * `WebhookBatchModule` — the NestJS dynamic module that wires
+ * the `WebhookBatchObserver` into the host's DI container and
+ * binds it to the `BatchObserver` token used by the executor
+ * (and by `@nest-batch/bullmq` / `@nest-batch/kafka`'s runtime
+ * bridge).
+ *
+ * The host wires it alongside `NestBatchModule.forRoot({...})`:
+ *
+ * ```ts
+ * @Module({
+ *   imports: [
+ *     NestBatchModule.forRoot({
+ *       adapters: { persistence: MikroOrmAdapter.forRoot(), transport: BullmqAdapter.forRoot() },
+ *     }),
+ *     WebhookBatchModule.forRoot({
+ *       secret: process.env.WEBHOOK_HMAC_SECRET,
+ *       urls: ['https://hooks.example.com/nest-batch'],
+ *     }),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * The observer is auto-registered against the `BatchObserver`
+ * token via `useExisting`, so the executor's optional-injection
+ * path picks it up without any extra wiring on the host's side.
+ */
+export declare class WebhookBatchModule {
+}
+/**
+ * `forRoot` — synchronous configuration. Resolves the options
+ * up-front (filling in defaults, falling back to the
+ * `WEBHOOK_HMAC_SECRET` env var when `secret` is omitted,
+ * freezing the result) and emits a `DynamicModule` that:
+ *
+ *   - registers `WebhookBatchObserver` as a provider,
+ *   - registers a `useExisting` alias so anything injecting
+ *     `BatchObserver` (or `WebhookBatchObserver` by class)
+ *     resolves to the same instance,
+ *   - registers the resolved options under
+ *     `WEBHOOK_MODULE_OPTIONS` (the observer's `@Inject`
+ *     key),
+ *   - marks the module `global: true` so the observer is
+ *     visible across the host's sub-modules.
+ *
+ * The `urls: []` case is a no-op (the observer subscribes
+ * to the event stream but never POSTs); it does not throw.
+ * The `secret` case throws at `forRoot` time with a clear
+ * message (the host sees the error at boot, not at the first
+ * event).
+ */
+export declare function forRoot(options: WebhookBatchModuleOptions): DynamicModule;
+export { BATCH_EVENT, WebhookBatchObserver, type BatchEventType, type ResolvedWebhookOptions, type WebhookBatchModuleOptions, type WebhookLogger, };
+//# sourceMappingURL=webhook-batch.module.d.ts.map

package/dist/src/webhook-batch.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-batch.module.d.ts","sourceRoot":"","sources":["../../src/webhook-batch.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEpE,OAAO,EAGL,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBACa,kBAAkB;CAAG;AAElC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,yBAAyB,GAAG,aAAa,CAQzE;AAoDD,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,yBAAyB,EAC9B,KAAK,aAAa,GACnB,CAAC"}

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

@@ -0,0 +1,94 @@
+"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 WebhookBatchModule () {
+        return WebhookBatchModule;
+    },
+    get WebhookBatchObserver () {
+        return _webhookbatchobserver.WebhookBatchObserver;
+    },
+    get forRoot () {
+        return forRoot;
+    }
+});
+const _common = require("@nestjs/common");
+const _core = require("@nest-batch/core");
+const _moduleoptions = require("./module-options");
+const _webhookbatchobserver = require("./webhook-batch.observer");
+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;
+}
+let WebhookBatchModule = class WebhookBatchModule {
+};
+WebhookBatchModule = _ts_decorate([
+    (0, _common.Module)({})
+], WebhookBatchModule);
+function forRoot(options) {
+    const resolved = (0, _moduleoptions.resolveWebhookOptions)(options);
+    return {
+        module: WebhookBatchModule,
+        global: true,
+        providers: buildProviders(resolved),
+        exports: [
+            _webhookbatchobserver.WebhookBatchObserver
+        ]
+    };
+}
+/**
+ * Build the static provider list shared by `forRoot()`.
+ *
+ * The list is three entries:
+ *   - `WebhookBatchObserver` — the concrete class.
+ *   - `BATCH_OBSERVER_PROVIDER` — a `useExisting` alias so the
+ *     executor's `@Optional() @Inject(BatchObserver) observer`
+ *     resolves to the same instance.
+ *   - `WEBHOOK_MODULE_OPTIONS` — the resolved + frozen
+ *     options bag, injected into the observer's constructor.
+ *
+ * Centralising the list keeps the public factory surface
+ * (`forRoot`) a one-liner; any future addition (e.g. a
+ * per-package health check) only needs to land here.
+ */ function buildProviders(resolved) {
+    return [
+        _webhookbatchobserver.WebhookBatchObserver,
+        {
+            provide: BATCH_OBSERVER_TOKEN,
+            useExisting: _webhookbatchobserver.WebhookBatchObserver
+        },
+        {
+            provide: _moduleoptions.WEBHOOK_MODULE_OPTIONS,
+            useValue: resolved
+        }
+    ];
+}
+/**
+ * The DI token the executor / runtime services use to inject
+ * a `BatchObserver`. We re-export the `BatchObserver` class
+ * itself as the token (mirroring the pattern in
+ * `@nest-batch/bullmq` and `@nest-batch/kafka`, where the
+ * `BatchObserver` interface is the type and the class-as-
+ * token resolves to the singleton).
+ *
+ * Using the `BatchObserver` class (an interface in
+ * `@nest-batch/core`) as the token is a NestJS pattern:
+ * Nest uses the class reference as the default DI key. We
+ * redeclare it as `BATCH_OBSERVER_TOKEN` so the `useExisting`
+ * provider above has a stable, imported symbol to bind
+ * against.
+ */ const BATCH_OBSERVER_TOKEN = Symbol.for('@nest-batch/webhook/BATCH_OBSERVER');
+
+//# sourceMappingURL=webhook-batch.module.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/webhook-batch.module.ts"],"sourcesContent":["import { Module, type DynamicModule, type Provider } from '@nestjs/common';\nimport { BATCH_EVENT, type BatchEventType } from '@nest-batch/core';\n\nimport {\n  resolveWebhookOptions,\n  WEBHOOK_MODULE_OPTIONS,\n  type ResolvedWebhookOptions,\n  type WebhookBatchModuleOptions,\n  type WebhookLogger,\n} from './module-options';\nimport { WebhookBatchObserver } from './webhook-batch.observer';\n\n/**\n * `WebhookBatchModule` — the NestJS dynamic module that wires\n * the `WebhookBatchObserver` into the host's DI container and\n * binds it to the `BatchObserver` token used by the executor\n * (and by `@nest-batch/bullmq` / `@nest-batch/kafka`'s runtime\n * bridge).\n *\n * The host wires it alongside `NestBatchModule.forRoot({...})`:\n *\n * ```ts\n * @Module({\n *   imports: [\n *     NestBatchModule.forRoot({\n *       adapters: { persistence: MikroOrmAdapter.forRoot(), transport: BullmqAdapter.forRoot() },\n *     }),\n *     WebhookBatchModule.forRoot({\n *       secret: process.env.WEBHOOK_HMAC_SECRET,\n *       urls: ['https://hooks.example.com/nest-batch'],\n *     }),\n *   ],\n * })\n * export class AppModule {}\n * ```\n *\n * The observer is auto-registered against the `BatchObserver`\n * token via `useExisting`, so the executor's optional-injection\n * path picks it up without any extra wiring on the host's side.\n */\n@Module({})\nexport class WebhookBatchModule {}\n\n/**\n * `forRoot` — synchronous configuration. Resolves the options\n * up-front (filling in defaults, falling back to the\n * `WEBHOOK_HMAC_SECRET` env var when `secret` is omitted,\n * freezing the result) and emits a `DynamicModule` that:\n *\n *   - registers `WebhookBatchObserver` as a provider,\n *   - registers a `useExisting` alias so anything injecting\n *     `BatchObserver` (or `WebhookBatchObserver` by class)\n *     resolves to the same instance,\n *   - registers the resolved options under\n *     `WEBHOOK_MODULE_OPTIONS` (the observer's `@Inject`\n *     key),\n *   - marks the module `global: true` so the observer is\n *     visible across the host's sub-modules.\n *\n * The `urls: []` case is a no-op (the observer subscribes\n * to the event stream but never POSTs); it does not throw.\n * The `secret` case throws at `forRoot` time with a clear\n * message (the host sees the error at boot, not at the first\n * event).\n */\nexport function forRoot(options: WebhookBatchModuleOptions): DynamicModule {\n  const resolved = resolveWebhookOptions(options);\n  return {\n    module: WebhookBatchModule,\n    global: true,\n    providers: buildProviders(resolved),\n    exports: [WebhookBatchObserver],\n  };\n}\n\n/**\n * Build the static provider list shared by `forRoot()`.\n *\n * The list is three entries:\n *   - `WebhookBatchObserver` — the concrete class.\n *   - `BATCH_OBSERVER_PROVIDER` — a `useExisting` alias so the\n *     executor's `@Optional() @Inject(BatchObserver) observer`\n *     resolves to the same instance.\n *   - `WEBHOOK_MODULE_OPTIONS` — the resolved + frozen\n *     options bag, injected into the observer's constructor.\n *\n * Centralising the list keeps the public factory surface\n * (`forRoot`) a one-liner; any future addition (e.g. a\n * per-package health check) only needs to land here.\n */\nfunction buildProviders(resolved: ResolvedWebhookOptions): Provider[] {\n  return [\n    WebhookBatchObserver,\n    {\n      provide: BATCH_OBSERVER_TOKEN,\n      useExisting: WebhookBatchObserver,\n    },\n    {\n      provide: WEBHOOK_MODULE_OPTIONS,\n      useValue: resolved,\n    },\n  ];\n}\n\n/**\n * The DI token the executor / runtime services use to inject\n * a `BatchObserver`. We re-export the `BatchObserver` class\n * itself as the token (mirroring the pattern in\n * `@nest-batch/bullmq` and `@nest-batch/kafka`, where the\n * `BatchObserver` interface is the type and the class-as-\n * token resolves to the singleton).\n *\n * Using the `BatchObserver` class (an interface in\n * `@nest-batch/core`) as the token is a NestJS pattern:\n * Nest uses the class reference as the default DI key. We\n * redeclare it as `BATCH_OBSERVER_TOKEN` so the `useExisting`\n * provider above has a stable, imported symbol to bind\n * against.\n */\nconst BATCH_OBSERVER_TOKEN: symbol = Symbol.for(\n  '@nest-batch/webhook/BATCH_OBSERVER',\n);\n\n// Re-export the public surface of this module so the\n// package barrel can re-export it in turn.\nexport {\n  BATCH_EVENT,\n  WebhookBatchObserver,\n  type BatchEventType,\n  type ResolvedWebhookOptions,\n  type WebhookBatchModuleOptions,\n  type WebhookLogger,\n};\n"],"names":["BATCH_EVENT","WebhookBatchModule","WebhookBatchObserver","forRoot","options","resolved","resolveWebhookOptions","module","global","providers","buildProviders","exports","provide","BATCH_OBSERVER_TOKEN","useExisting","WEBHOOK_MODULE_OPTIONS","useValue","Symbol","for"],"mappings":";;;;;;;;;;;QA8HEA;eAAAA,iBAAW;;QArFAC;eAAAA;;QAsFXC;eAAAA,0CAAoB;;QA9DNC;eAAAA;;;wBAjE0C;sBACT;+BAQ1C;sCAC8B;;;;;;;AA+B9B,IAAA,AAAMF,qBAAN,MAAMA;AAAoB;;;;AAwB1B,SAASE,QAAQC,OAAkC;IACxD,MAAMC,WAAWC,IAAAA,oCAAqB,EAACF;IACvC,OAAO;QACLG,QAAQN;QACRO,QAAQ;QACRC,WAAWC,eAAeL;QAC1BM,SAAS;YAACT,0CAAoB;SAAC;IACjC;AACF;AAEA;;;;;;;;;;;;;;CAcC,GACD,SAASQ,eAAeL,QAAgC;IACtD,OAAO;QACLH,0CAAoB;QACpB;YACEU,SAASC;YACTC,aAAaZ,0CAAoB;QACnC;QACA;YACEU,SAASG,qCAAsB;YAC/BC,UAAUX;QACZ;KACD;AACH;AAEA;;;;;;;;;;;;;;CAcC,GACD,MAAMQ,uBAA+BI,OAAOC,GAAG,CAC7C"}

package/dist/src/webhook-batch.observer.d.ts

@@ -0,0 +1,144 @@
+import { BATCH_EVENT, type BatchEvent, type BatchEventType, type BatchObserver } from '@nest-batch/core';
+import { type ResolvedWebhookOptions } from './module-options';
+/**
+ * `WebhookBatchObserver` — the v1 webhook delivery observer.
+ *
+ * Implements `BatchObserver` from `@nest-batch/core`. On every
+ * subscribed `BATCH_EVENT.*` (default:
+ * `[JOB_COMPLETED, JOB_FAILED, STEP_FAILED]`) the observer:
+ *
+ *   1. Serializes a normalized JSON envelope
+ *      `{ version: 1, type, timestamp, jobId, execution }`.
+ *   2. Computes the v1 HMAC-SHA256 signature over
+ *      `<unix>.<raw-body>` (Stripe-style).
+ *   3. POSTs the envelope + `X-Nest-Batch-Signature` header to
+ *      every URL in `urls`.
+ *   4. Retries on 5xx and network errors through the fixed
+ *      4-attempt budget at `[1s, 5s, 25s, 125s]`. HTTP 4xx
+ *      responses are NOT retried (client error, won't change).
+ *   5. On final failure, emits a `logger.warn` dead-letter line
+ *      including the URL, attempt count, last status / error,
+ *      and a SHA-256 fingerprint of the secret (NEVER the
+ *      secret itself).
+ *
+ * The observer is the v1 contract documented in
+ * `docs/RELEASE-0.2.0.md` §7 and pinned by T-AC-5
+ * (`packages/webhook/tests/webhook-observer.test.ts`).
+ */
+export declare class WebhookBatchObserver implements BatchObserver {
+    private readonly logger;
+    /** Resolved + frozen options. The secret lives here and nowhere else. */
+    private readonly options;
+    /**
+     * Cached lookup of the subscription set. Built once at
+     * construction time so `onEvent` is a single `Set.has` check.
+     */
+    private readonly 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.
+     */
+    private readonly retryDelaysMs;
+    /**
+     * Sentinel subscriber set: defaults to
+     * `[JOB_COMPLETED, JOB_FAILED, STEP_FAILED]`. Overridable via
+     * the `events` option in `forRoot({...})`.
+     */
+    constructor(options: ResolvedWebhookOptions);
+    /**
+     * `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).
+     */
+    onEvent(event: BatchEvent): Promise<void>;
+    /**
+     * 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.
+     */
+    private deliverToAll;
+    /**
+     * 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.
+     */
+    private buildEnvelope;
+    /**
+     * 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.
+     */
+    private deliverToUrl;
+    /**
+     * 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)
+     */
+    private attemptOnce;
+}
+/**
+ * The v1 webhook envelope payload. This is the contract the
+ * receiver's parser expects. Fields are stable; new fields
+ * are additive only and use the `x-` prefix to mark them
+ * as out-of-contract for v1.
+ */
+export interface WebhookEnvelope {
+    /** Envelope schema version. Always `1` for v1. */
+    readonly version: 1;
+    /** The `BatchEvent.type` string (e.g. `nest-batch.job.completed`). */
+    readonly type: BatchEventType;
+    /** Event timestamp as ISO-8601. */
+    readonly timestamp: string;
+    /** The `JobExecution.id` (a.k.a. `jobExecutionId`). */
+    readonly jobId: string;
+    /** The `StepExecution.id` (a.k.a. `stepExecutionId`). STEP\_\* / CHUNK\_\* / ITEM\_\* events only. */
+    readonly stepId?: string;
+    /** The `BatchEvent.data` payload, deep-cloned for safety. */
+    readonly execution: unknown;
+}
+export { BATCH_EVENT };
+//# sourceMappingURL=webhook-batch.observer.d.ts.map

package/dist/src/webhook-batch.observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-batch.observer.d.ts","sourceRoot":"","sources":["../../src/webhook-batch.observer.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EACX,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAIL,KAAK,sBAAsB,EAE5B,MAAM,kBAAkB,CAAC;AAO1B;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBACa,oBAAqB,YAAW,aAAa;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IAEvC,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAEjD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8B;IAEzD;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoB;IAElD;;;;OAIG;gBAE+B,OAAO,EAAE,sBAAsB;IAWjE;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA2B/C;;;;;;;;;;;OAWG;YACW,YAAY;IAQ1B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,aAAa;IAiBrB;;;;;;OAMG;YACW,YAAY;IAmF1B;;;;;;;;;;;;;;OAcG;YACW,WAAW;CAmD1B;AA6CD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sGAAsG;IACtG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAMD,OAAO,EAAE,WAAW,EAAE,CAAC"}