@nestarc/webhook 0.13.0 → 0.13.2

package/dist/webhook.delivery-admin.service.js

@@ -17,8 +17,10 @@ const common_1 = require("@nestjs/common");
 const webhook_constants_1 = require("./webhook.constants");
 let WebhookDeliveryAdminService = class WebhookDeliveryAdminService {
     deliveryRepo;
-    constructor(deliveryRepo) {
+    options;
+    constructor(deliveryRepo, options) {
         this.deliveryRepo = deliveryRepo;
+        this.options = options;
     }
     async getDeliveryLogs(endpointId, filters) {
         return this.deliveryRepo.getDeliveryLogs(endpointId, filters);
@@ -39,13 +41,15 @@ let WebhookDeliveryAdminService = class WebhookDeliveryAdminService {
         if (!this.deliveryRepo.replayEvent) {
             throw new Error('WebhookDeliveryRepository does not support event replay');
         }
-        return this.deliveryRepo.replayEvent(eventId, options);
+        return this.deliveryRepo.replayEvent(eventId, options, this.options?.delivery?.maxRetries ?? webhook_constants_1.DEFAULT_MAX_RETRIES);
     }
 };
 exports.WebhookDeliveryAdminService = WebhookDeliveryAdminService;
 exports.WebhookDeliveryAdminService = WebhookDeliveryAdminService = __decorate([
     (0, common_1.Injectable)(),
     __param(0, (0, common_1.Inject)(webhook_constants_1.WEBHOOK_DELIVERY_REPOSITORY)),
-    __metadata("design:paramtypes", [Object])
+    __param(1, (0, common_1.Optional)()),
+    __param(1, (0, common_1.Inject)(webhook_constants_1.WEBHOOK_MODULE_OPTIONS)),
+    __metadata("design:paramtypes", [Object, Object])
 ], WebhookDeliveryAdminService);
 //# sourceMappingURL=webhook.delivery-admin.service.js.map

package/dist/webhook.delivery-admin.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhook.delivery-admin.service.js","sourceRoot":"","sources":["../src/webhook.delivery-admin.service.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAAoD;AACpD,2DAAkE;AAc3D,IAAM,2BAA2B,GAAjC,MAAM,2BAA2B;IAGnB;IAFnB,YAEmB,YAAuC;QAAvC,iBAAY,GAAZ,YAAY,CAA2B;IACvD,CAAC;IAEJ,KAAK,CAAC,eAAe,CACnB,UAAkB,EAClB,OAA4B;QAE5B,OAAO,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAChE,CAAC;IAED,KAAK,CAAC,mBAAmB,CAAC,UAAkB;QAC1C,OAAO,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAC3D,CAAC;IAED,KAAK,CAAC,aAAa,CACjB,UAAkB,EAClB,OAA8B;QAE9B,OAAO,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,qBAAqB,CACzB,OAAqC,EACrC,OAA8B;QAE9B,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,qBAAqB,EAAE,CAAC;YAC7C,MAAM,IAAI,KAAK,CACb,uEAAuE,CACxE,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC,YAAY,CAAC,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACnE,CAAC;IAED,KAAK,CAAC,WAAW,CACf,OAAe,EACf,OAA4B;QAE5B,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;QAC7E,CAAC;QAED,OAAO,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACzD,CAAC;CACF,CAAA;AA/CY,kEAA2B;sCAA3B,2BAA2B;IADvC,IAAA,mBAAU,GAAE;IAGR,WAAA,IAAA,eAAM,EAAC,+CAA2B,CAAC,CAAA;;GAF3B,2BAA2B,CA+CvC"}
+{"version":3,"file":"webhook.delivery-admin.service.js","sourceRoot":"","sources":["../src/webhook.delivery-admin.service.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAA8D;AAC9D,2DAI6B;AAetB,IAAM,2BAA2B,GAAjC,MAAM,2BAA2B;IAGnB;IAGA;IALnB,YAEmB,YAAuC,EAGvC,OAA8B;QAH9B,iBAAY,GAAZ,YAAY,CAA2B;QAGvC,YAAO,GAAP,OAAO,CAAuB;IAC9C,CAAC;IAEJ,KAAK,CAAC,eAAe,CACnB,UAAkB,EAClB,OAA4B;QAE5B,OAAO,IAAI,CAAC,YAAY,CAAC,eAAe,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAChE,CAAC;IAED,KAAK,CAAC,mBAAmB,CAAC,UAAkB;QAC1C,OAAO,IAAI,CAAC,YAAY,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;IAC3D,CAAC;IAED,KAAK,CAAC,aAAa,CACjB,UAAkB,EAClB,OAA8B;QAE9B,OAAO,IAAI,CAAC,YAAY,CAAC,aAAa,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,qBAAqB,CACzB,OAAqC,EACrC,OAA8B;QAE9B,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,qBAAqB,EAAE,CAAC;YAC7C,MAAM,IAAI,KAAK,CACb,uEAAuE,CACxE,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC,YAAY,CAAC,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACnE,CAAC;IAED,KAAK,CAAC,WAAW,CACf,OAAe,EACf,OAA4B;QAE5B,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;QAC7E,CAAC;QAED,OAAO,IAAI,CAAC,YAAY,CAAC,WAAW,CAClC,OAAO,EACP,OAAO,EACP,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,UAAU,IAAI,uCAAmB,CAC1D,CAAC;IACJ,CAAC;CACF,CAAA;AAtDY,kEAA2B;sCAA3B,2BAA2B;IADvC,IAAA,mBAAU,GAAE;IAGR,WAAA,IAAA,eAAM,EAAC,+CAA2B,CAAC,CAAA;IAEnC,WAAA,IAAA,iBAAQ,GAAE,CAAA;IACV,WAAA,IAAA,eAAM,EAAC,0CAAsB,CAAC,CAAA;;GALtB,2BAA2B,CAsDvC"}

package/dist/webhook.service.d.ts

@@ -11,8 +11,21 @@ export declare class WebhookService {
     private readonly maxAttempts;
     private readonly redaction?;
     constructor(eventRepo: WebhookEventRepository, endpointRepo: WebhookEndpointRepository, deliveryRepo: WebhookDeliveryRepository, options: WebhookModuleOptions);
+    /**
+     * Publish to active matching endpoints across all tenants.
+     * Returns the saved event ID even when no endpoints match. correlationId is
+     * stored independently of idempotencyKey; duplicate keys return the original
+     * event without creating deliveries or updating its metadata.
+     */
     send(event: WebhookEvent, options?: WebhookPublishOptions): Promise<string>;
+    /** Publish to active matching endpoints belonging to the specified tenant. */
     sendToTenant(tenantId: string, event: WebhookEvent, options?: WebhookPublishOptions): Promise<string>;
+    /**
+     * Publish to eligible endpoints among the specified IDs. The built-in repository
+     * requires active endpoints subscribed to the exact event type or literal '*'.
+     * When a tenant ID is provided, endpoint ownership must match that tenant.
+     * Pass publish options as the third argument when no tenant ID is needed.
+     */
     sendToEndpoints(endpointIds: string[], event: WebhookEvent, tenantIdOrOptions?: string | WebhookPublishOptions, options?: WebhookPublishOptions): Promise<string>;
     private sendInternal;
     private saveEventInTransaction;

package/dist/webhook.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhook.service.d.ts","sourceRoot":"","sources":["../src/webhook.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAO/C,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EAEtB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AAChF,OAAO,EACL,yBAAyB,EAE1B,MAAM,qCAAqC,CAAC;AAE7C,qBACa,cAAc;IAOvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAE1B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAE7B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAV/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAA0B;gBAIlC,SAAS,EAAE,sBAAsB,EAEjC,YAAY,EAAE,yBAAyB,EAEvC,YAAY,EAAE,yBAAyB,EAExD,OAAO,EAAE,oBAAoB;IAMzB,IAAI,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAI3E,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,MAAM,CAAC;IAIZ,eAAe,CACnB,WAAW,EAAE,MAAM,EAAE,EACrB,KAAK,EAAE,YAAY,EACnB,iBAAiB,CAAC,EAAE,MAAM,GAAG,qBAAqB,EAClD,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,MAAM,CAAC;YAmDJ,YAAY;YA2DZ,sBAAsB;IA6BpC,OAAO,CAAC,eAAe;CAOxB"}
+{"version":3,"file":"webhook.service.d.ts","sourceRoot":"","sources":["../src/webhook.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAO/C,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EAEtB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AAChF,OAAO,EACL,yBAAyB,EAE1B,MAAM,qCAAqC,CAAC;AAE7C,qBACa,cAAc;IAOvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAE1B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAE7B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAV/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAA0B;gBAIlC,SAAS,EAAE,sBAAsB,EAEjC,YAAY,EAAE,yBAAyB,EAEvC,YAAY,EAAE,yBAAyB,EAExD,OAAO,EAAE,oBAAoB;IAM/B;;;;;OAKG;IACG,IAAI,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,MAAM,CAAC;IAIjF,8EAA8E;IACxE,YAAY,CAChB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,MAAM,CAAC;IAIlB;;;;;OAKG;IACG,eAAe,CACnB,WAAW,EAAE,MAAM,EAAE,EACrB,KAAK,EAAE,YAAY,EACnB,iBAAiB,CAAC,EAAE,MAAM,GAAG,qBAAqB,EAClD,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,MAAM,CAAC;YAmDJ,YAAY;YA2DZ,sBAAsB;IA8BpC,OAAO,CAAC,eAAe;CAOxB"}

package/dist/webhook.service.js

@@ -30,12 +30,25 @@ let WebhookService = WebhookService_1 = class WebhookService {
         this.maxAttempts = options.delivery?.maxRetries ?? 5;
         this.redaction = options.redaction;
     }
+    /**
+     * Publish to active matching endpoints across all tenants.
+     * Returns the saved event ID even when no endpoints match. correlationId is
+     * stored independently of idempotencyKey; duplicate keys return the original
+     * event without creating deliveries or updating its metadata.
+     */
     async send(event, options) {
         return this.sendInternal(event, undefined, options);
     }
+    /** Publish to active matching endpoints belonging to the specified tenant. */
     async sendToTenant(tenantId, event, options) {
         return this.sendInternal(event, tenantId, options);
     }
+    /**
+     * Publish to eligible endpoints among the specified IDs. The built-in repository
+     * requires active endpoints subscribed to the exact event type or literal '*'.
+     * When a tenant ID is provided, endpoint ownership must match that tenant.
+     * Pass publish options as the third argument when no tenant ID is needed.
+     */
     async sendToEndpoints(endpointIds, event, tenantIdOrOptions, options) {
         const tenantId = typeof tenantIdOrOptions === 'string' ? tenantIdOrOptions : undefined;
         const publishOptions = typeof tenantIdOrOptions === 'object' ? tenantIdOrOptions : options;
@@ -80,7 +93,7 @@ let WebhookService = WebhookService_1 = class WebhookService {
     }
     async saveEventInTransaction(tx, eventType, payload, tenantId, options) {
         if (!options?.idempotencyKey) {
-            const id = await this.eventRepo.saveEventInTransaction(tx, eventType, payload, tenantId);
+            const id = await this.eventRepo.saveEventInTransaction(tx, eventType, payload, tenantId, options);
             return { id, created: true };
         }
         if (!this.eventRepo.saveEventOnceInTransaction) {

package/dist/webhook.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhook.service.js","sourceRoot":"","sources":["../src/webhook.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webhook.service.js","sourceRoot":"","sources":["../src/webhook.service.ts"],"names":[],"mappings":"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"}

package/docs/usage.md

@@ -0,0 +1,109 @@
+# Using @nestarc/webhook
+
+This is the consumer contract for **0.13.2**. See the [0.13.2 changes](../CHANGELOG.md#0132---2026-09-11); if that version is not yet available on npm, use a locally packed build. In 0.13.1, correlation IDs are only stored with idempotency keys, replay always uses five attempts, and manual retry does not guard against purged payloads.
+
+Start with the [README](../README.md) and the [executable example](../examples/quick-start/README.md). Online references: [usage documentation](https://nestarc.dev/packages/webhook/) and [API reference](https://nestarc.dev/api/webhook/). Use the types in your installed package when they differ from an unreleased example.
+
+## Runtime and ownership
+
+- The default adapters use PostgreSQL and a Prisma client supplied by the application. No Redis, broker, or separate webhook server is required.
+- Supported peers: NestJS 10/11, `@nestjs/schedule` 4/5, Prisma Client 5/6/7. Match peer versions; do not bypass peer validation.
+- The package declares Node >=20. Prisma 7.10.0 requires Node `^20.19 || ^22.12 || >=24.0`; use a supported version for your selected dependencies.
+- Prisma 7 needs a driver adapter and a generated client. For a CommonJS Nest application, configure `moduleFormat = "cjs"` in the `prisma-client` generator. The runnable example includes generation and compilation.
+- The application owns Prisma connection setup and shutdown. For signal handling, enable Nest shutdown hooks or call `app.close()` explicitly; then disconnect the application-owned database client.
+- Apply SQL to the same database/schema used by the client. New installs use `src/sql/create-webhook-tables.sql` from the installed package. Existing pre-0.9 installations run v0.9.0, v0.12.0, then v0.13.0 migrations; skip migrations already applied. v0.12.0 adds performance indexes.
+
+## First delivery
+
+1. Prepare the database, client, and receiving HTTP endpoint.
+2. Register `WebhookModule.forRoot()` or `forRootAsync()` with that client.
+3. Create an endpoint with the intended tenant and subscriptions; provision its returned secret to the receiver.
+4. Define a `WebhookEvent` subclass with a nonempty static `eventType` and publish it.
+5. Verify the raw request body and headers at the receiver, deduplicate the event, then acknowledge with `2xx`.
+6. Inspect `getDeliveryLogs()` and `getDeliveryAttempts()` for the delivery result.
+
+Publishing without any matching endpoints stores the event but creates no deliveries. Creating an endpoint later does not automatically deliver past events. Explicit replay can enqueue a retained event for current matching endpoints.
+
+## Publish and tenant contract
+
+| API | Destination selection with default repositories | Result |
+| --- | --- | --- |
+| `send(event, options?)` | Every active endpoint subscribed to the event, across all tenants, including endpoints with no tenant | `Promise<string>` event ID |
+| `sendToTenant(tenantId, event, options?)` | Active subscribed endpoints whose tenant equals `tenantId`; global endpoints are excluded | `Promise<string>` event ID |
+| `sendToEndpoints(ids, event, options?)` | Requested IDs, still filtered by active status and subscription, across tenants | `Promise<string>` event ID |
+| `sendToEndpoints(ids, event, tenantId, options?)` | Requested IDs, also filtered to the specified tenant | `Promise<string>` event ID |
+
+Subscriptions match an exact event name or the literal `"*"`. Patterns such as `"order.*"` are not supported. Endpoint IDs and event IDs are UUIDs with the PostgreSQL adapters. Tenant IDs are opaque strings.
+
+`await send(...)` means the event and initial delivery rows have committed, not that HTTP delivery succeeded. The package transaction does not include an application operation such as `saveOrder()`. If both must commit atomically, integrate an application outbox/transaction strategy; do not assume two awaited calls provide that guarantee.
+
+All publish methods accept `WebhookPublishOptions`:
+
+- `idempotencyKey`: deduplicates by tenant, event type, and key. A duplicate returns the original event ID and creates no new delivery rows, even if the payload or targeted endpoint list changed. Reuse a key only for the same business event. This is producer-side deduplication, not receiver-side exactly-once processing.
+- `correlationId`: diagnostic event metadata. In this source version it is stored independently of idempotency. It is not added to HTTP headers or the delivered payload. It does not deduplicate events. Duplicate idempotent publishes retain the original metadata.
+
+The delivered JSON is `{ "type": "order.created", "data": { ...eventFields } }`. `sanitizePayload` receives the data object before persistence; its output is also what receivers receive.
+
+## Delivery, retry, and concurrency
+
+Workers atomically claim database rows using `FOR UPDATE SKIP LOCKED`. Retries, lost acknowledgements, crashes, and database write failures can produce duplicate HTTP requests. Delivery uses a bounded attempt budget; it does not guarantee eventual success or exactly-once delivery. No ordering guarantee is provided between events.
+
+`delivery.maxRetries` means **total attempts including the first**. The default five attempts allow four retries: 30 seconds, 5 minutes, 30 minutes, and 2 hours. A sixth attempt uses the 24-hour delay; later retries reuse 24 hours. Jitter adds 0–10% to a delay, never subtracts from it. These are minimum scheduling delays; polling, backlog, and outages can delay actual dispatch.
+
+| Result | Action |
+| --- | --- |
+| `2xx` | Mark `SENT` |
+| `3xx`, `408`, `409`, `425`, `429`, `5xx`, network/validation/dispatch failure | Retry while attempts remain; otherwise mark `FAILED` |
+| Other `4xx` | Mark `FAILED` immediately |
+
+The fixed schedule does not interpret `Retry-After`. Redirects are not followed. The default class is named `FetchHttpClient` for compatibility but uses Node `http`/`https.request`, connecting to prevalidated IPs while preserving the original hostname for HTTP/TLS. Custom clients must honor the supplied `resolvedIpAddresses` to retain that DNS-rebinding protection.
+
+The circuit breaker disables an endpoint for **new normal deliveries** after consecutive failures. Already queued deliveries and retries continue. A successful queued delivery may reset the breaker before cooldown; otherwise cooldown recovery can reactivate breaker-disabled endpoints. Manually disabled endpoints are not automatically reactivated by breaker recovery. Notification and observer callbacks are best-effort, not a durable notification queue.
+
+## Signature verification and rotation
+
+The HMAC-SHA256 input and `webhook-id`, `webhook-timestamp`, `webhook-signature` headers follow the Standard Webhooks signing format. This package accepts bare base64 secrets with at least 16 decoded bytes for compatibility and generates 32-byte secrets. It does not accept `whsec_`-prefixed secrets through endpoint management; remove the prefix only when converting a known compatible secret. Do not describe all secret formats or every Standard Webhooks recommendation as supported.
+
+Verify the **original UTF-8 body**, not JSON that has been parsed and serialized again. Prefer `verifyWithTolerance(..., { toleranceSeconds: 300 })`; `verify()` alone performs no freshness check. Freshness permits repeated requests within the tolerance window. Store a receiver-scoped `webhook-id` deduplication key atomically with your business effect. Use durable shared storage across receiver instances. The example's in-memory set is only a single-process demonstration.
+
+`createEndpoint()` and `rotateSecret()` return the new provisioning secret. Read APIs omit it. The built-in vault stores secrets as plaintext unless you supply an encryption vault.
+
+New delivery rows snapshot their URL and signing secret **when queued**. Legacy rows created before snapshot support, with null snapshot columns, fall back to the endpoint's live URL/current key. Rotation expiry controls whether a previous secret is copied as a secondary signature into a new delivery at that moment:
+
+| When the delivery was queued | Keys retained for dispatch and retries |
+| --- | --- |
+| Before rotation | Its original key |
+| During the overlap window | Current and previous keys |
+| After the overlap window | Current key only |
+
+Dispatch does not reevaluate expiry for existing snapshots. Rotation neither rewrites the queue nor immediately revokes a compromised key for queued deliveries. Receiver acceptance windows and operational handling of existing deliveries must account for this behavior. Replay creates fresh snapshots; manual retry preserves existing snapshots.
+
+## Administration and retention
+
+| Operation | Contract |
+| --- | --- |
+| `createEndpoint(dto)` | Returns endpoint and secret; invalid URL or secret throws |
+| `getEndpoint(id)` / `updateEndpoint(id, dto)` | Return endpoint without secret, or `null` when missing |
+| `rotateSecret(id, dto)` | Requires a future `Date`; returns endpoint and new secret, or `null` |
+| `deleteEndpoint(id)` | Returns `false` when missing. The default schema prevents deletion while delivery rows reference the endpoint, raising a foreign-key error; disable it instead when retaining history |
+| `sendTestEvent(id)` | Returns event ID, or `null` when missing; explicit diagnostic delivery bypasses normal subscription matching |
+| `retryDelivery(id, options?)` | Requeues a failed delivery with retained payload and grants at least one additional attempt; returns `false` if ineligible/missing |
+| `retryFailedDeliveries(filters, options?)` | Returns `{ matched, retried, skipped }`; limit defaults to 100, allowed range 1–1000 |
+| `replayEvent(id, options?)` | Returns `{ eventId, deliveriesCreated, endpointIds }`; creates new rows for currently active matching endpoints using the configured total attempt limit |
+| `purgeExpiredData(now?)` | Returns payload/response purge counts; must be invoked by the application's scheduler |
+
+Replay reuses the original event ID. Receivers deduplicating that ID may acknowledge replay without processing it again. Coordinate intentional reprocessing with the receiver. `options.tenantId` must match the **source event's tenant**, not just the intended destination: a global event cannot be replayed with a different tenant option. `endpointIds` further restricts the destination list. Missing or payload-purged source events throw. Zero matching destinations returns zero created deliveries.
+
+The optional retry/replay `reason` field is metadata for custom adapters. The built-in Prisma adapter does not persist it. Record support actions in your application's audit log if needed.
+
+Retention is disabled by default. Payload purging replaces data with `{}` and marks it purged; it does not delete the event/idempotency key. This source version rejects retry and replay of purged payloads. Response retention clears response bodies only; delivery/attempt metadata remains. `sanitizeResponseBody` can suppress responses before storage.
+
+Delivery logs show the latest persisted state of a delivery. Attempt records show recorded attempts separately. The default transport retains at most 4096 UTF-16 code units of a response body; logs are not a complete copy of every response. An interrupted process can lose the response before recording it; stale recovery records the recovery, not the lost HTTP response. The `responseBodyTruncated` flag reflects truncation by the repository and cannot detect bytes already discarded by a custom or built-in HTTP client.
+
+## Custom adapters and authoritative references
+
+Import public services, options, records, tokens, and ports from `@nestarc/webhook`. `WebhookDeliveryWorker`, dispatcher, retry policy, and circuit breaker exports are advanced/internal integration surfaces; normal applications use `WebhookModule` and public services.
+
+Custom repositories must preserve transaction and tenant boundaries. Optional port capabilities include idempotent persistence, bulk retry, replay, retention, and backlog summary; calling unsupported operations throws or is unavailable. Event repositories should store the optional correlation metadata. Replay repositories receive the configured attempt budget as an optional third argument. A method with fewer parameters remains TypeScript-compatible, but must be updated to use the new metadata/budget.
+
+For this checkout, prefer current public types and this guide over dated files in `docs/`. Historical plans explain past decisions and are not installation recipes. The [changelog](../CHANGELOG.md) identifies released versus pending behavior.

package/examples/quick-start/README.md

@@ -0,0 +1,83 @@
+# Runnable NestJS webhook example
+
+This example starts a NestJS application context and a receiver on an ephemeral
+loopback port, registers an endpoint, publishes a tenant event, and lets the normal
+scheduled worker deliver it. It verifies the raw request signature, rejects a
+tampered body, acknowledges a duplicate without processing it again, and checks
+the persisted `SENT` delivery and its attempt log.
+
+## Run
+
+This example targets `@nestarc/webhook@0.13.2`. Before that version is available
+on npm, use the [packed-source verification](#verify-the-repository-build) below.
+
+Use Node.js **20.19+, 22.12+, or 24+** (the supported Prisma 7 release lines) and
+PostgreSQL **14+**. The database user needs permission to create schemas. Use a
+local test database; each run creates a random schema and drops only that schema
+when it finishes. Existing webhook tables are not used.
+
+From this directory:
+
+```bash
+export DATABASE_URL='postgresql://webhook_test:webhook_test@localhost:5433/webhook_test'
+npm install --strict-peer-deps
+npm start
+```
+
+For example, start a disposable PostgreSQL database with Docker first:
+
+```bash
+docker run --rm --name webhook-quick-start-db \
+  -e POSTGRES_USER=webhook_test \
+  -e POSTGRES_PASSWORD=webhook_test \
+  -e POSTGRES_DB=webhook_test \
+  -p 127.0.0.1:5433:5432 postgres:16-alpine
+```
+
+Wait for PostgreSQL to report that it is ready to accept connections, then run the
+example in a second terminal. Stop the Docker command when finished.
+
+Expected output:
+
+```text
+Verified webhook: type=order.created tenant=tenant_example delivery=SENT attempts=1
+Verified receiver: tampered=401 duplicate=200 processed=1
+Quick start passed; temporary schema removed and connections closed.
+```
+
+`npm start` generates the Prisma 7 client, compiles the CommonJS application, and
+runs it. The package uses raw SQL, so the Prisma schema needs no webhook models.
+The example applies the SQL shipped with the installed package to its temporary
+schema; it skips the `pgcrypto` extension because PostgreSQL 14+ already supplies
+`gen_random_uuid()`.
+
+## Use the pattern in your application
+
+- Register an endpoint and provide its secret to the receiver **before** publishing.
+  `sendToTenant()` limits matching destinations to that tenant. `send()` broadcasts
+  to matching endpoints across tenants.
+- Verify the untouched request body before parsing JSON. A successful
+  `verifyWithTolerance()` check accepts repeated valid requests within the window;
+  deduplicate by `webhook-id` separately.
+- The in-memory `Set` here lasts for one process. In production, store the event ID
+  durably with a unique constraint and commit it atomically with the business
+  change. Concurrent requests, restarts, and retries must not repeat that change.
+- `allowPrivateUrls: true` permits this loopback destination. Omit it for production
+  public destinations, use HTTPS, and store signing secrets securely.
+- Replace the temporary-schema setup with your normal versioned migrations, and
+  keep your application's existing Prisma client and Nest lifecycle. This finite
+  example closes Nest before disconnecting the database.
+
+## Verify the repository build
+
+From the repository root, with `DATABASE_URL` set, run:
+
+```bash
+npm run test:consumer:quick-start
+```
+
+The verifier packs the current build, copies this example into a temporary
+consumer directory, installs the tarball with strict peer dependency resolution,
+and runs the same `npm start` command. Application imports use only the package's
+public root exports; SQL comes from the installed package. No repository source
+imports or mocked database/HTTP adapters are used.

package/examples/quick-start/main.ts

@@ -0,0 +1,247 @@
+import 'reflect-metadata';
+import assert from 'node:assert/strict';
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createServer, IncomingHttpHeaders, ServerResponse } from 'node:http';
+import { setTimeout as delay } from 'node:timers/promises';
+import { INestApplicationContext, Module } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+import { PrismaPg } from '@prisma/adapter-pg';
+import {
+  WebhookDeliveryAdminService,
+  WebhookEndpointAdminService,
+  WebhookEvent,
+  WebhookModule,
+  WebhookService,
+  WebhookSigner,
+} from '@nestarc/webhook';
+import { PrismaClient } from './generated/prisma/client';
+
+class OrderCreatedEvent extends WebhookEvent {
+  static readonly eventType = 'order.created';
+
+  constructor(public readonly orderId: string) {
+    super();
+  }
+}
+
+async function main(): Promise<void> {
+  const connectionString = process.env.DATABASE_URL;
+  if (!connectionString) throw new Error('Set DATABASE_URL to a local test PostgreSQL database');
+
+  // Each run owns one temporary schema; no existing webhook tables are changed.
+  const schema = `webhook_example_${randomUUID().replaceAll('-', '')}`;
+  const scopedUrl = new URL(connectionString);
+  scopedUrl.searchParams.set('options', `-c search_path=${schema}`);
+  const database = new PrismaClient({
+    adapter: new PrismaPg({ connectionString, connectionTimeoutMillis: 5000 }),
+  });
+  const prisma = new PrismaClient({
+    adapter: new PrismaPg({
+      connectionString: scopedUrl.toString(),
+      connectionTimeoutMillis: 5000,
+    }),
+  });
+  const signer = new WebhookSigner();
+  // This Set demonstrates the check for a single process. Production receivers
+  // must persist a unique event ID with their business change in one transaction.
+  const processed = new Set<string>();
+  const received: Array<{ headers: IncomingHttpHeaders; body: string }> = [];
+  let secret = '';
+  let app: INestApplicationContext | undefined;
+  let schemaCreated = false;
+
+  function respond(response: ServerResponse, status: number, body: string): void {
+    response.writeHead(status, { 'content-type': 'text/plain' });
+    response.end(body);
+  }
+
+  const receiver = createServer((request, response) => {
+    if (request.method !== 'POST' || request.url !== '/webhooks') {
+      respond(response, 404, 'Not found');
+      return;
+    }
+    const chunks: Buffer[] = [];
+    let bytes = 0;
+    request.on('data', (chunk: Buffer) => {
+      bytes += chunk.length;
+      if (bytes <= 1024 * 1024) chunks.push(chunk);
+    });
+    request.on('error', () => {
+      if (!response.headersSent) respond(response, 400, 'Invalid request');
+    });
+    request.on('end', () => {
+      if (bytes > 1024 * 1024) return respond(response, 413, 'Body too large');
+      // Verify the exact request body before JSON parsing or any business changes.
+      const body = Buffer.concat(chunks).toString('utf8');
+      const eventId = request.headers['webhook-id'];
+      const timestamp = request.headers['webhook-timestamp'];
+      const signature = request.headers['webhook-signature'];
+      if (
+        !secret ||
+        typeof eventId !== 'string' ||
+        !eventId ||
+        typeof timestamp !== 'string' ||
+        !/^\d+$/.test(timestamp) ||
+        typeof signature !== 'string' ||
+        !signer.verifyWithTolerance(eventId, Number(timestamp), body, secret, signature, {
+          toleranceSeconds: 300,
+        })
+      ) {
+        return respond(response, 401, 'Invalid or expired signature');
+      }
+      if (processed.has(eventId)) return respond(response, 200, 'Already processed');
+
+      let event: { type?: string; data?: { orderId?: string } };
+      try {
+        event = JSON.parse(body);
+      } catch {
+        return respond(response, 400, 'Invalid JSON');
+      }
+      if (event?.type !== 'order.created' || event.data?.orderId !== 'order_123') {
+        return respond(response, 400, 'Unexpected event');
+      }
+      // The example's business action is recording this verified request.
+      received.push({ headers: request.headers, body });
+      processed.add(eventId);
+      respond(response, 200, 'Processed');
+    });
+  });
+
+  try {
+    await database.$connect();
+    // schema is generated locally from UUID characters, never from user input.
+    await database.$executeRawUnsafe(`CREATE SCHEMA "${schema}"`);
+    schemaCreated = true;
+    await prisma.$connect();
+    const sql = readFileSync(
+      require.resolve('@nestarc/webhook/src/sql/create-webhook-tables.sql'),
+      'utf8',
+    );
+    const statements = sql
+      .split('\n')
+      .filter((line) => !line.trimStart().startsWith('--'))
+      .join('\n')
+      .split(';')
+      .map((statement) => statement.trim())
+      .filter(Boolean);
+    for (const statement of statements) {
+      // PostgreSQL 14+ supplies gen_random_uuid(); avoid creating a global extension.
+      if (/^CREATE EXTENSION\b/i.test(statement)) continue;
+      await prisma.$executeRawUnsafe(statement);
+    }
+
+    await new Promise<void>((resolve, reject) => {
+      receiver.once('error', reject);
+      receiver.listen(0, '127.0.0.1', () => {
+        receiver.removeListener('error', reject);
+        resolve();
+      });
+    });
+    const address = receiver.address();
+    assert(address && typeof address !== 'string');
+    const url = `http://127.0.0.1:${address.port}/webhooks`;
+
+    @Module({
+      imports: [
+        WebhookModule.forRoot({
+          prisma,
+          polling: { interval: 100 },
+          delivery: { timeout: 5000, maxRetries: 1 },
+          allowPrivateUrls: true, // Only for this loopback example; omit in production.
+        }),
+      ],
+    })
+    class AppModule {}
+
+    app = await NestFactory.createApplicationContext(AppModule, {
+      logger: ['error', 'warn'],
+      abortOnError: false,
+    });
+    const endpoints = app.get(WebhookEndpointAdminService);
+    const deliveries = app.get(WebhookDeliveryAdminService);
+    const webhooks = app.get(WebhookService);
+
+    // Register the destination and securely provision its secret before publishing.
+    const endpoint = await endpoints.createEndpoint({
+      url,
+      events: ['order.created'],
+      tenantId: 'tenant_example',
+    });
+    secret = endpoint.secret;
+    const eventId = await webhooks.sendToTenant(
+      'tenant_example',
+      new OrderCreatedEvent('order_123'),
+      { idempotencyKey: 'order_123:created', correlationId: 'example_request' },
+    );
+
+    let logs = await deliveries.getDeliveryLogs(endpoint.id);
+    const deadline = Date.now() + 15_000;
+    while (logs[0]?.status !== 'SENT') {
+      assert.notEqual(logs[0]?.status, 'FAILED', 'Delivery failed');
+      assert(Date.now() < deadline, 'Timed out waiting for scheduled delivery');
+      await delay(50);
+      logs = await deliveries.getDeliveryLogs(endpoint.id);
+    }
+    assert.equal(logs.length, 1);
+    assert.equal(logs[0].eventId, eventId);
+    assert.equal(logs[0].tenantId, 'tenant_example');
+    assert.equal(logs[0].attempts, 1);
+    const attempts = await deliveries.getDeliveryAttempts(logs[0].id);
+    assert.equal(attempts.length, 1);
+    assert.equal(attempts[0].status, 'SENT');
+    assert.equal(attempts[0].responseStatus, 200);
+    assert.equal(received.length, 1);
+    assert.equal(received[0].headers['webhook-id'], eventId);
+
+    // A timestamp check alone permits a duplicate within its tolerance window.
+    const original = received[0];
+    const headers = {
+      'content-type': 'application/json',
+      'webhook-id': eventId,
+      'webhook-timestamp': String(original.headers['webhook-timestamp']),
+      'webhook-signature': String(original.headers['webhook-signature']),
+    };
+    const tampered = await fetch(url, {
+      method: 'POST', headers, body: `${original.body} `, signal: AbortSignal.timeout(5000),
+    });
+    assert.equal(tampered.status, 401);
+    await tampered.text();
+    const duplicate = await fetch(url, {
+      method: 'POST', headers, body: original.body, signal: AbortSignal.timeout(5000),
+    });
+    assert.equal(duplicate.status, 200);
+    assert.equal(await duplicate.text(), 'Already processed');
+    assert.equal(received.length, 1);
+    assert.equal(processed.size, 1);
+
+    console.log('Verified webhook: type=order.created tenant=tenant_example delivery=SENT attempts=1');
+    console.log('Verified receiver: tampered=401 duplicate=200 processed=1');
+  } finally {
+    // Stop polling and await in-flight work before closing its resources.
+    try {
+      await app?.close();
+    } finally {
+      try {
+        if (receiver.listening) {
+          await new Promise<void>((resolve, reject) =>
+            receiver.close((error) => error ? reject(error) : resolve()),
+          );
+        }
+      } finally {
+        try {
+          await prisma.$disconnect();
+          if (schemaCreated) await database.$executeRawUnsafe(`DROP SCHEMA "${schema}" CASCADE`);
+        } finally {
+          await database.$disconnect();
+        }
+      }
+    }
+  }
+  console.log('Quick start passed; temporary schema removed and connections closed.');
+}
+
+main().catch((error: unknown) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/examples/quick-start/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "webhook-quick-start",
+  "private": true,
+  "version": "0.0.0",
+  "scripts": {
+    "generate": "prisma generate",
+    "build": "tsc -p tsconfig.json",
+    "start": "npm run generate && npm run build && node dist/main.js"
+  },
+  "engines": {
+    "node": "^20.19 || ^22.12 || >=24.0"
+  },
+  "dependencies": {
+    "@nestarc/webhook": "0.13.2",
+    "@nestjs/common": "11.2.1",
+    "@nestjs/core": "11.2.1",
+    "@nestjs/schedule": "5.0.1",
+    "@prisma/adapter-pg": "7.10.0",
+    "@prisma/client": "7.10.0",
+    "pg": "8.23.0",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2"
+  },
+  "devDependencies": {
+    "@types/node": "25.6.0",
+    "prisma": "7.10.0",
+    "typescript": "5.9.3"
+  }
+}

package/examples/quick-start/prisma/schema.prisma

@@ -0,0 +1,10 @@
+generator client {
+  provider     = "prisma-client"
+  output       = "../generated/prisma"
+  moduleFormat = "cjs"
+  engineType   = "client"
+}
+
+datasource db {
+  provider = "postgresql"
+}

package/examples/quick-start/prisma.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig, env } from 'prisma/config';
+
+export default defineConfig({
+  schema: 'prisma/schema.prisma',
+  datasource: { url: env('DATABASE_URL') },
+});

package/examples/quick-start/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "strict": true,
+    "skipLibCheck": false,
+    "outDir": "dist",
+    "rootDir": "."
+  },
+  "include": ["main.ts", "generated/**/*.ts"]
+}