webhook-delivery-engine 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hamid Javadi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# Webhook Delivery Engine
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A lightweight, embeddable Node.js and TypeScript library for persistent, idempotent webhook delivery with bounded retries.
+
+**Requirements:** Node.js 24 or newer.
+**Database:** SQLite only in v1.0.0. PostgreSQL and MySQL support is planned for a future release.
+
+---
+
+## Key Goals
+
+- **Idempotent Ingestion:** Safely accept events without creating duplicate delivery jobs.
+- **Persistent queue:** Events and attempt history are stored in SQLite.
+- **Bounded retries:** Retryable delivery failures use capped exponential backoff with full jitter.
+- **Attempt history:** Query event status and recorded delivery attempts from the host application.
+- **Signed requests:** Outbound requests include HMAC-SHA256 signature, timestamp, and event ID headers.
+
+Version 1.0.0 embeds the queue and its workers in your Node.js process and uses SQLite. The project plans to grow toward separately configured clients, separate worker processes, PostgreSQL and MySQL backends, and stronger delivery guarantees, including exactly-once delivery as a future goal. These capabilities are not part of v1.0.0.
+
+---
+
+## Prerequisites
+
+- **Node.js:** `>= 24`
+- **Storage:** A writable, persistent local filesystem with SQLite locking support.
+- **Secret:** A non-empty HMAC signing secret supplied by the host at runtime.
+
+---
+
+## Install and Embed
+
+Install the package in a Node.js 24 or newer application:
+
+```bash
+npm install webhook-delivery-engine
+```
+
+The SQLite driver uses the native `better-sqlite3` module. Your package manager may require permission to run its install script. Create the database directory before starting the engine:
+
+```bash
+mkdir -p ./data
+```
+
+Create and start an engine instance in the host application:
+
+```ts
+import { createWebhookEngine } from 'webhook-delivery-engine';
+
+const hmacSecret = process.env.WEBHOOK_HMAC_SECRET;
+if (!hmacSecret) throw new Error('WEBHOOK_HMAC_SECRET is required');
+
+const engine = createWebhookEngine({
+  databasePath: './data/webhook-delivery-engine.db',
+  clientId: 'billing-service',
+  hmacSecret,
+  defaultDestinationUrl: 'https://consumer.example/hooks',
+  config: {
+    concurrency: { workerCount: 4, batchSize: 10, pollIntervalMs: 1_000 },
+    timeoutLimitMs: 10_000,
+    retry: { maxAttempts: 5, baseDelayMs: 1_000, maxDelayMs: 60_000 },
+  },
+});
+
+await engine.start();
+try {
+  const result = await engine.enqueue({
+    idempotency_key: 'invoice-123',
+    payload: { event: 'invoice.paid', invoiceId: 'invoice-123' },
+  });
+  if (result.statusCode !== 202) throw new Error(`Event rejected: ${result.body.error}`);
+
+  const event = await engine.getEvent(result.body.id);
+  console.log(event?.status);
+} finally {
+  await engine.stop();
+}
+```
+
+`start()` applies bundled SQLite migrations and starts polling. Call engine methods only after it resolves. `stop()` stops polling, releases claims that have not started dispatch, waits for active deliveries, and closes the database. The host owns process signals and must await `stop()` during shutdown.
+
+The configured `clientId` is bound to the engine and stamped on accepted events. The library is an in-process API: it does not provide an HTTP server or authenticate callers. If you expose an external endpoint, authenticate and authorize requests in the host before calling the engine. Use a separate SQLite database for each differently configured client; v1 does not support sharing one database between clients with different secrets.
+
+## Delivery behavior and security
+
+- Delivery is **at least once**, not exactly once. Consumers should deduplicate using the stable `x-webhook-event-id` header.
+- A `2xx` response is successful. Retryable client responses (`408`, `409`, `429`), server errors, timeouts, and network errors are retried up to `maxAttempts`; other `4xx` responses fail immediately. Events finish as `delivered` or `failed`, with intermediate `pending`, `processing`, or `retry` states.
+- Each request is signed with HMAC-SHA256 over `<timestamp>.<raw JSON body>`. The engine sends `x-webhook-signature` (`sha256=<hex>`), `x-webhook-timestamp` (Unix seconds), and `x-webhook-event-id`. The consumer must verify the signature and enforce its own timestamp freshness window.
+- Destinations must use HTTPS and pass the engine's SSRF checks. The dispatcher pins validated addresses and does not follow redirects.
+- SQLite persistence survives process restarts when the database is on persistent storage. Back up the database using a SQLite-consistent backup method; do not rely on ephemeral filesystems for durable data.
+- Structured JSON logs are written to standard output. `logLevel` or `LOG_LEVEL` controls verbosity; sensitive payload, credential, and request fields are redacted.
+
+See the [Embedded API Guide](docs/API.md) for option details, ingestion results,
+tenant-scoped queries, security expectations, and development commands.
+
+## Interactive Demo
+
+The [hosted package demo](examples/demo/README.md) shows successful delivery, retry recovery, terminal failure, idempotency, and attempt history using the public package interface. Its Render deployment is separate from the library release and is not automatically deployed by this repository.
+
+## Development
+
+Maintainers use pnpm 10.4.1 with the committed lockfile:
+
+| Script          | Description                                         |
+| --------------- | --------------------------------------------------- |
+| pnpm build      | Builds ESM output, declarations, and migration assets |
+| pnpm test       | Executes unit and integration test suites           |
+| pnpm lint       | Lints codebase                                      |
+| pnpm test:watch | Runs Vitest in interactive watch mode               |
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/src/app/bootstrap.d.ts

@@ -0,0 +1,14 @@
+import { type MigrationRunnerOptions } from '../storage/migrations/runner.js';
+/** Options for ensuring database migrations finish before application startup. */
+export type ApplicationBootstrapOptions = MigrationRunnerOptions & {
+    /** Starts the scheduler, server, or embedded application after migrations complete. */
+    readonly start: () => void | Promise<void>;
+};
+/**
+ * Applies pending database migrations before starting application components.
+ *
+ * @param options - Migration connection, dialect, optional SQL directory, and start callback.
+ * @returns A promise that resolves after migrations and application startup succeed.
+ * @throws {@link MigrationError} when migration application fails; the start callback is not run.
+ */
+export declare function bootstrapApplication(options: ApplicationBootstrapOptions): Promise<void>;

package/dist/src/app/bootstrap.js

@@ -0,0 +1,13 @@
+import { runMigrations } from '../storage/migrations/runner.js';
+/**
+ * Applies pending database migrations before starting application components.
+ *
+ * @param options - Migration connection, dialect, optional SQL directory, and start callback.
+ * @returns A promise that resolves after migrations and application startup succeed.
+ * @throws {@link MigrationError} when migration application fails; the start callback is not run.
+ */
+export async function bootstrapApplication(options) {
+    const { start, ...migrationOptions } = options;
+    await runMigrations(migrationOptions);
+    await start();
+}

package/dist/src/app/embedded.d.ts

@@ -0,0 +1,45 @@
+import type { EngineConfig } from '../config/engine.config.js';
+import type { EventPage, ListEventsInput } from '../core/ports.js';
+import type { AttemptRecord, WebhookEvent } from '../core/types.js';
+import type { IngestionRequest } from '../features/ingestion/ingestion.schema.js';
+import { handleIngestion } from '../features/ingestion/ingestion.handler.js';
+import { type LogLevel } from '../shared/logger.js';
+/** Options required to create an embedded webhook engine. */
+export interface CreateWebhookEngineOptions {
+    /** Persistent SQLite database filename. */
+    readonly databasePath: string;
+    /** Tenant identity fixed for this engine instance. */
+    readonly clientId: string;
+    /** HMAC key used to sign outbound requests. */
+    readonly hmacSecret: string;
+    /** HTTPS destination used when an ingestion request omits destination_url. */
+    readonly defaultDestinationUrl: string;
+    /** Required polling, timeout, and retry controls. */
+    readonly config: EngineConfig;
+    /** Log threshold; defaults to LOG_LEVEL or info. */
+    readonly logLevel?: LogLevel;
+    /** Receives original scheduler and delivery failures; poll errors omit the event. */
+    readonly onError?: (error: unknown, event?: WebhookEvent) => void;
+}
+/** Tenant-scoped programmatic event query. */
+export type EngineListEventsInput = Omit<ListEventsInput, 'clientId'>;
+/** Embedded engine lifecycle and programmatic API. */
+export interface WebhookEngine {
+    /** Applies bundled migrations and starts polling. Safe to call repeatedly. */
+    start(): Promise<void>;
+    /** Stops polling, drains started dispatches, releases queued claims, and closes SQLite. */
+    stop(): Promise<void>;
+    /** Validates and enqueues an event for the configured tenant. */
+    enqueue(input: IngestionRequest): ReturnType<typeof handleIngestion>;
+    /** Returns an event by system id or idempotency key within the configured tenant. */
+    getEvent(identifier: string): Promise<WebhookEvent | null>;
+    /** Returns a tenant-scoped event page. */
+    listEvents(input: EngineListEventsInput): Promise<EventPage>;
+    /** Returns attempt history for an event owned by the configured tenant. */
+    listAttempts(eventId: string): Promise<readonly AttemptRecord[]>;
+}
+/**
+ * Creates the public embedded composition root. It does not bind a listener or
+ * register process signals; the host owns both responsibilities.
+ */
+export declare function createWebhookEngine(options: CreateWebhookEngineOptions): WebhookEngine;

package/dist/src/app/embedded.js

@@ -0,0 +1,228 @@
+import { createDeliveryWorker } from '../features/delivery/delivery.worker.js';
+import { handleIngestion } from '../features/ingestion/ingestion.handler.js';
+import { ClaimScheduler } from '../features/scheduler/scheduler.js';
+import { createStructuredLogger, resolveLogLevel } from '../shared/logger.js';
+import { SqliteDatabaseAdapter } from '../storage/sqlite.adapter.js';
+import { GracefulShutdown } from './lifecycle.js';
+/**
+ * Creates the public embedded composition root. It does not bind a listener or
+ * register process signals; the host owns both responsibilities.
+ */
+export function createWebhookEngine(options) {
+    validateOptions(options);
+    const logger = createStructuredLogger({
+        level: resolveLogLevel(options.logLevel, process.env.LOG_LEVEL),
+    });
+    let adapter = null;
+    let scheduler = null;
+    let lifecycle = null;
+    let deliveryWorker = null;
+    let startPromise = null;
+    let stopPromise = null;
+    let acceptingDispatches = false;
+    let activeWorkers = 0;
+    const queuedClaims = [];
+    let state = 'new';
+    const requireRunning = () => {
+        if (state !== 'running' || adapter === null) {
+            throw new Error('Webhook engine must be started and not stopping before use.');
+        }
+        return adapter;
+    };
+    return {
+        async start() {
+            if (state === 'running')
+                return;
+            if (state === 'starting')
+                return startPromise;
+            if (state !== 'new')
+                throw new Error(`Webhook engine cannot start from state ${state}.`);
+            state = 'starting';
+            startPromise = (async () => {
+                try {
+                    const db = await SqliteDatabaseAdapter.open(options.databasePath);
+                    adapter = db;
+                    deliveryWorker = createDeliveryWorker({
+                        adapter: db,
+                        hmacSecret: options.hmacSecret,
+                        timeoutLimitMs: options.config.timeoutLimitMs,
+                        retry: options.config.retry,
+                        onError: (error, event) => reportError(error, event),
+                        onDispatchStarted: (event, work) => {
+                            logger.info({
+                                event: 'delivery.dispatch.started',
+                                eventId: event.id,
+                                clientId: event.clientId,
+                                attemptNumber: event.attemptCount,
+                            }, 'delivery dispatch started');
+                            lifecycle?.trackDispatch(event.id, work);
+                            const finish = () => {
+                                activeWorkers -= 1;
+                                startQueuedClaims();
+                            };
+                            void work.then(finish, finish);
+                        },
+                        onAttemptCompleted: (event, result) => {
+                            logger.info({
+                                event: 'delivery.attempt.completed',
+                                eventId: event.id,
+                                clientId: event.clientId,
+                                attemptNumber: event.attemptCount,
+                                outcome: result.outcome,
+                                nextStatus: result.nextStatus,
+                                statusCode: result.statusCode,
+                                latencyMs: result.latencyMs,
+                                persisted: result.persisted,
+                            }, 'delivery attempt completed');
+                        },
+                    });
+                    scheduler = new ClaimScheduler(db, options.config, (event) => {
+                        lifecycle?.trackClaimed(event);
+                        logger.info({
+                            event: 'delivery.claimed',
+                            eventId: event.id,
+                            clientId: event.clientId,
+                            attemptNumber: event.attemptCount,
+                        }, 'delivery event claimed');
+                        if (!acceptingDispatches)
+                            return;
+                        queuedClaims.push(event);
+                        startQueuedClaims();
+                    }, (error) => reportError(error), (recoveredCount) => {
+                        if (recoveredCount === 0)
+                            return;
+                        logger.warn({ event: 'scheduler.stale_leases_recovered', recoveredCount }, 'stale delivery leases recovered');
+                    });
+                    lifecycle = new GracefulShutdown(scheduler, db);
+                    acceptingDispatches = true;
+                    scheduler.start();
+                    state = 'running';
+                    logger.info({ event: 'engine.started', clientId: options.clientId }, 'engine started');
+                }
+                catch (error) {
+                    logger.error({ event: 'engine.start.failed', errorType: errorType(error) }, 'engine startup failed');
+                    adapter?.close();
+                    adapter = null;
+                    state = 'failed';
+                    throw error;
+                }
+            })();
+            return startPromise;
+        },
+        async stop() {
+            if (state === 'stopped')
+                return;
+            if (state === 'stopping')
+                return stopPromise;
+            if (state === 'new' || state === 'failed') {
+                state = 'stopped';
+                return;
+            }
+            if (state === 'starting')
+                await startPromise;
+            state = 'stopping';
+            acceptingDispatches = false;
+            logger.info({ event: 'engine.stopping', clientId: options.clientId }, 'engine stopping');
+            stopPromise = (async () => {
+                try {
+                    await lifecycle?.shutdown();
+                }
+                finally {
+                    adapter?.close();
+                    adapter = null;
+                    state = 'stopped';
+                    logger.info({ event: 'engine.stopped', clientId: options.clientId }, 'engine stopped');
+                }
+            })();
+            return stopPromise;
+        },
+        async enqueue(input) {
+            const db = requireRunning();
+            const result = await handleIngestion({
+                clientId: options.clientId,
+                body: input,
+                defaultDestinationUrl: options.defaultDestinationUrl,
+                database: db,
+            });
+            if (result.statusCode === 202) {
+                logger.info({
+                    event: 'ingestion.accepted',
+                    eventId: result.body.id,
+                    clientId: options.clientId,
+                    idempotentReplay: result.body.idempotent_replay,
+                }, 'webhook event accepted');
+            }
+            return result;
+        },
+        async getEvent(identifier) {
+            const db = requireRunning();
+            return ((await db.findEventById(identifier, options.clientId)) ??
+                db.findEventByIdempotencyKey(options.clientId, identifier));
+        },
+        async listEvents(input) {
+            const db = requireRunning();
+            return db.listEvents({ ...input, clientId: options.clientId });
+        },
+        async listAttempts(eventId) {
+            const db = requireRunning();
+            const event = await db.findEventById(eventId, options.clientId);
+            return event === null ? [] : db.listAttempts(event.id, options.clientId);
+        },
+    };
+    function startQueuedClaims() {
+        while (acceptingDispatches &&
+            activeWorkers < options.config.concurrency.workerCount &&
+            queuedClaims.length > 0) {
+            const event = queuedClaims.shift();
+            activeWorkers += 1;
+            deliveryWorker?.(event);
+        }
+    }
+    function reportError(error, event) {
+        logger.error({
+            event: event === undefined ? 'scheduler.poll.failed' : 'delivery.processing.failed',
+            ...(event === undefined ? {} : { eventId: event.id, clientId: event.clientId }),
+            errorType: errorType(error),
+        }, event === undefined ? 'scheduler poll failed' : 'delivery processing failed');
+        if (options.onError !== undefined) {
+            options.onError(error, event);
+        }
+    }
+}
+function errorType(error) {
+    if (error instanceof TypeError)
+        return 'TypeError';
+    if (error instanceof RangeError)
+        return 'RangeError';
+    if (error instanceof SyntaxError)
+        return 'SyntaxError';
+    return error instanceof Error ? 'Error' : typeof error;
+}
+function validateOptions(options) {
+    for (const [name, value] of Object.entries({
+        databasePath: options.databasePath,
+        clientId: options.clientId,
+        hmacSecret: options.hmacSecret,
+        defaultDestinationUrl: options.defaultDestinationUrl,
+    })) {
+        if (typeof value !== 'string' || value.trim().length === 0) {
+            throw new TypeError(`${name} must be a non-empty string.`);
+        }
+    }
+    const { concurrency, timeoutLimitMs, retry } = options.config;
+    const positive = [
+        concurrency.workerCount,
+        concurrency.batchSize,
+        concurrency.pollIntervalMs,
+        timeoutLimitMs,
+        retry.maxAttempts,
+        retry.baseDelayMs,
+        retry.maxDelayMs,
+    ];
+    if (!positive.every((value) => Number.isSafeInteger(value) && value > 0)) {
+        throw new RangeError('Engine configuration values must be positive safe integers.');
+    }
+    if (retry.maxDelayMs < retry.baseDelayMs) {
+        throw new RangeError('retry.maxDelayMs must be greater than or equal to retry.baseDelayMs.');
+    }
+}

package/dist/src/app/http.server.d.ts

@@ -0,0 +1,10 @@
+import { type Server } from 'node:http';
+import type { DatabaseAdapter } from '../core/ports.js';
+import type { ApiKeyAuthenticator } from '../security/auth.js';
+export interface WebhookHttpServerOptions {
+    readonly database: DatabaseAdapter;
+    readonly authenticate: ApiKeyAuthenticator;
+    readonly defaultDestinationUrl: string;
+}
+/** Creates the standalone REST server without starting a listener. */
+export declare function createWebhookHttpServer(options: WebhookHttpServerOptions): Server;

package/dist/src/app/http.server.js

@@ -0,0 +1,65 @@
+import { createServer } from 'node:http';
+import { handleIngestionRoute } from '../features/ingestion/ingestion.routes.js';
+import { handleQueryRoute } from '../features/query/query.routes.js';
+import { sendJson } from '../features/http/http.responses.js';
+/** Creates the standalone REST server without starting a listener. */
+export function createWebhookHttpServer(options) {
+    return createServer((request, response) => {
+        void routeRequest(request, response, options).catch(() => {
+            if (!response.headersSent) {
+                sendJson(response, 503, { error: 'service_unavailable' });
+            }
+            else {
+                response.destroy();
+            }
+        });
+    });
+}
+async function routeRequest(request, response, options) {
+    let url;
+    try {
+        url = new URL(request.url, 'http://localhost');
+    }
+    catch {
+        sendJson(response, 400, { error: 'invalid_request' });
+        return;
+    }
+    if (url.pathname !== '/webhooks' && !url.pathname.startsWith('/webhooks/')) {
+        sendJson(response, 404, { error: 'not_found' });
+        return;
+    }
+    if (request.method !== 'GET' && !(url.pathname === '/webhooks' && request.method === 'POST')) {
+        sendJson(response, 405, { error: 'method_not_allowed' });
+        return;
+    }
+    const authentication = options.authenticate(extractApiKey(request));
+    if (!authentication.authenticated) {
+        sendJson(response, 401, { error: 'unauthorized' });
+        return;
+    }
+    if (url.pathname === '/webhooks' && request.method === 'POST') {
+        await handleIngestionRoute({
+            request,
+            response,
+            authentication,
+            database: options.database,
+            defaultDestinationUrl: options.defaultDestinationUrl,
+        });
+        return;
+    }
+    await handleQueryRoute({
+        response,
+        url,
+        authentication,
+        database: options.database,
+    });
+}
+function extractApiKey(request) {
+    const authorization = request.headers.authorization;
+    if (authorization !== undefined) {
+        const match = /^Bearer ([^\s]+)$/i.exec(authorization);
+        return match?.[1];
+    }
+    const apiKey = request.headers['x-api-key'];
+    return typeof apiKey === 'string' ? apiKey : undefined;
+}

package/dist/src/app/lifecycle.d.ts

@@ -0,0 +1,108 @@
+import type { WebhookEvent } from '../core/types.js';
+import type { DatabaseAdapter } from '../core/ports.js';
+/**
+ * Minimal scheduler interface required by the graceful shutdown coordinator.
+ *
+ * This keeps the lifecycle module decoupled from the concrete `ClaimScheduler`
+ * implementation while still being able to stop the poll loop.
+ */
+export interface StoppableScheduler {
+    /** Stops the poll loop and resolves when the current cycle completes. */
+    stop(): Promise<void>;
+}
+/**
+ * Coordinates a clean process exit on SIGINT or SIGTERM.
+ *
+ * Responsibilities (WBS 4.2):
+ * 1. Register one-time SIGINT and SIGTERM handlers via `register()`.
+ * 2. On signal (or direct `shutdown()` call): stop the scheduler so no new
+ *    events are claimed.
+ * 3. Call `DatabaseAdapter.releaseEventLease` for every event that was claimed
+ *    but whose dispatch has not yet started, returning those leases to the
+ *    `pending` state so they are picked up on the next startup.
+ * 4. Remain idempotent — duplicate signals or `shutdown()` calls run the
+ *    shutdown sequence exactly once.
+ *
+ * The lifecycle module does NOT implement the poll loop itself (WBS 4.1), does
+ * NOT dispatch events, and does NOT know about HMAC signing or HTTP transport.
+ *
+ * ### Lease tracking contract
+ *
+ * When the scheduler claims an event and hands it to the worker seam, callers
+ * should immediately call `trackClaimed(event)`. When network dispatch starts,
+ * call `trackDispatch(event.id, work)` to move the event from releasable claims
+ * to work that shutdown must drain. `untrackClaimed` remains available for
+ * callers that only need claim release tracking.
+ */
+export declare class GracefulShutdown {
+    private readonly scheduler;
+    private readonly adapter;
+    /**
+     * Events that have been claimed by the scheduler but have not yet started
+     * network dispatch. Keyed by event id for O(1) lookup and removal.
+     */
+    private readonly pendingClaims;
+    /** Dispatches that crossed the network-start boundary and must be drained. */
+    private readonly activeDispatches;
+    /** Whether the shutdown sequence has been started (guards idempotency). */
+    private shuttingDown;
+    /** Shared completion promise so concurrent stop calls await the same drain. */
+    private shutdownPromise;
+    /** Whether `register()` has been called (guards duplicate listener registration). */
+    private registered;
+    /**
+     * Creates a lifecycle coordinator for the given scheduler and adapter.
+     *
+     * @param scheduler - The running poll loop to stop on shutdown.
+     * @param adapter - Adapter used to release unclaimed-dispatch leases.
+     */
+    constructor(scheduler: StoppableScheduler, adapter: Pick<DatabaseAdapter, 'releaseEventLease'>);
+    /**
+     * Registers one-time SIGINT and SIGTERM listeners on `process`.
+     *
+     * Safe to call multiple times — only one pair of listeners is ever added.
+     * Each signal triggers `shutdown()` which is itself idempotent.
+     */
+    register(): void;
+    /**
+     * Marks an event as claimed-but-not-dispatched.
+     *
+     * Call this immediately after the scheduler hands an event to the worker
+     * seam so that a concurrent or subsequent `shutdown()` can release its
+     * lease.
+     *
+     * @param event - The claimed event to track.
+     */
+    trackClaimed(event: WebhookEvent): void;
+    /**
+     * Removes an event from the pending-claim tracking set.
+     *
+     * Call this when the worker begins actual network dispatch for an event.
+     * After removal, `shutdown()` will not attempt to release that lease —
+     * the stale-lease recovery mechanism will handle it if the process aborts
+     * mid-dispatch.
+     *
+     * @param eventId - Id of the event whose dispatch has started.
+     */
+    untrackClaimed(eventId: string): void;
+    /**
+     * Marks dispatch as started and tracks its completion for shutdown.
+     * The lease is no longer eligible for release once network dispatch begins.
+     */
+    trackDispatch(eventId: string, dispatch: Promise<unknown>): void;
+    /**
+     * Executes the graceful shutdown sequence exactly once.
+     *
+     * 1. Stops the scheduler (no new claims after this point).
+     * 2. Releases the leases of all still-tracked (not-yet-dispatched) events
+     *    by calling `releaseEventLease` for each. Failures for individual events
+     *    are swallowed so that the remaining releases still run; those events
+     *    will be recovered by the stale-lease mechanism on next startup.
+     *
+     * Safe to call multiple times — subsequent calls resolve immediately.
+     *
+     * @returns A promise that resolves when the shutdown sequence completes.
+     */
+    shutdown(): Promise<void>;
+    private drainAndRelease;
+}