@voyant-travel/webhook-delivery 0.1.0

package/README.md

@@ -0,0 +1,10 @@
+# @voyant-travel/webhook-delivery
+
+Node-host outbound webhook delivery behind the Framework's selected-event
+enqueue boundary. The package owns subscription fan-out, visibility policy,
+HMAC signing, persisted attempts, idempotency, bounded retries, terminal
+dead-letter state, and delivery audit outcomes.
+
+The audit tables intentionally contain only redacted, bounded excerpts. The
+original event payload remains at the host enqueue boundary and is never used
+as an audit-storage surrogate.

package/dist/contracts.d.ts

@@ -0,0 +1,14 @@
+import type { EventEnvelope } from "@voyant-travel/core";
+export interface ExternalWebhookEventContract {
+    eventId: string;
+    eventType: string;
+    eventVersion: string;
+    payloadSchema: Readonly<Record<string, unknown>>;
+}
+export interface WebhookSubscriptionEventInput {
+    events?: readonly string[];
+}
+export declare function assertWebhookSubscriptionCreateEvents(input: WebhookSubscriptionEventInput, contracts: readonly ExternalWebhookEventContract[]): void;
+export declare function assertWebhookSubscriptionUpdateEvents(input: WebhookSubscriptionEventInput, contracts: readonly ExternalWebhookEventContract[]): void;
+export declare function prepareExternalWebhookEvent(event: EventEnvelope, contract: ExternalWebhookEventContract): EventEnvelope;
+//# sourceMappingURL=contracts.d.ts.map

package/dist/contracts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.d.ts","sourceRoot":"","sources":["../src/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAKxD,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CACjD;AAED,MAAM,WAAW,6BAA6B;IAC5C,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3B;AAED,wBAAgB,qCAAqC,CACnD,KAAK,EAAE,6BAA6B,EACpC,SAAS,EAAE,SAAS,4BAA4B,EAAE,GACjD,IAAI,CAEN;AAED,wBAAgB,qCAAqC,CACnD,KAAK,EAAE,6BAA6B,EACpC,SAAS,EAAE,SAAS,4BAA4B,EAAE,GACjD,IAAI,CAGN;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,aAAa,EACpB,QAAQ,EAAE,4BAA4B,GACrC,aAAa,CAsBf"}

package/dist/contracts.js

@@ -0,0 +1,112 @@
+import { isExternalWebhookPayloadSchema } from "@voyant-travel/core/project";
+const REDACTION_MARKER = "[REDACTED]";
+export function assertWebhookSubscriptionCreateEvents(input, contracts) {
+    assertSelectedExternalEvents(input.events, contracts, "create");
+}
+export function assertWebhookSubscriptionUpdateEvents(input, contracts) {
+    if (input.events === undefined)
+        return;
+    assertSelectedExternalEvents(input.events, contracts, "update");
+}
+export function prepareExternalWebhookEvent(event, contract) {
+    if (!isExternalWebhookPayloadSchema(contract.payloadSchema)) {
+        throw new Error(`External webhook contract "${contract.eventId}" requires an object payload schema with explicit properties.`);
+    }
+    if (event.name !== contract.eventType) {
+        throw new Error(`External webhook contract "${contract.eventId}" governs "${contract.eventType}", not "${event.name}".`);
+    }
+    const metadata = event.metadata ?? {};
+    assertMetadata(metadata, "graphEventId", contract.eventId);
+    assertMetadata(metadata, "graphEventVersion", contract.eventVersion);
+    return {
+        name: event.name,
+        data: projectValue(event.data, contract.payloadSchema, "$.data"),
+        emittedAt: event.emittedAt,
+        metadata: externalMetadata(metadata, contract),
+    };
+}
+function assertSelectedExternalEvents(events, contracts, operation) {
+    if (!events || events.length === 0) {
+        throw new Error(`Webhook subscription ${operation} requires at least one event.`);
+    }
+    const selected = new Set(contracts.map(({ eventType }) => eventType));
+    const unknown = [...new Set(events.filter((eventType) => !selected.has(eventType)))].sort();
+    if (unknown.length > 0) {
+        throw new Error(`Webhook subscription ${operation} requested events outside the selected external catalog: ${unknown.join(", ")}.`);
+    }
+}
+function projectValue(value, schema, path) {
+    if (schema.writeOnly === true || schema["x-voyant-redact"] === true)
+        return REDACTION_MARKER;
+    if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+        throw new Error(`External webhook payload ${path} is not an allowed enum value.`);
+    }
+    const type = schema.type;
+    if (type === "object")
+        return projectObject(value, schema, path);
+    if (type === "array")
+        return projectArray(value, schema, path);
+    if (type === "string" && typeof value !== "string")
+        return invalidType(path, "string");
+    if (type === "number" && (typeof value !== "number" || !Number.isFinite(value))) {
+        return invalidType(path, "number");
+    }
+    if (type === "integer" && (typeof value !== "number" || !Number.isInteger(value))) {
+        return invalidType(path, "integer");
+    }
+    if (type === "boolean" && typeof value !== "boolean")
+        return invalidType(path, "boolean");
+    if (type === "null" && value !== null)
+        return invalidType(path, "null");
+    return value;
+}
+function projectObject(value, schema, path) {
+    if (!isRecord(value))
+        return invalidType(path, "object");
+    const properties = isRecord(schema.properties) ? schema.properties : {};
+    const required = new Set(Array.isArray(schema.required)
+        ? schema.required.filter((entry) => typeof entry === "string")
+        : []);
+    const output = {};
+    for (const [key, propertySchema] of Object.entries(properties)) {
+        if (!isRecord(propertySchema))
+            continue;
+        if (!(key in value)) {
+            if (required.has(key))
+                throw new Error(`External webhook payload ${path}.${key} is required.`);
+            continue;
+        }
+        output[key] = projectValue(value[key], propertySchema, `${path}.${key}`);
+    }
+    return output;
+}
+function projectArray(value, schema, path) {
+    if (!Array.isArray(value))
+        return invalidType(path, "array");
+    if (!isRecord(schema.items))
+        return [];
+    return value.map((entry, index) => projectValue(entry, schema.items, `${path}[${index}]`));
+}
+function externalMetadata(metadata, contract) {
+    return {
+        ...(typeof metadata.eventId === "string" ? { eventId: metadata.eventId } : {}),
+        ...(typeof metadata.correlationId === "string"
+            ? { correlationId: metadata.correlationId }
+            : {}),
+        ...(typeof metadata.causationId === "string" ? { causationId: metadata.causationId } : {}),
+        graphEventId: contract.eventId,
+        graphEventVersion: contract.eventVersion,
+    };
+}
+function assertMetadata(metadata, key, expected) {
+    const actual = metadata[key];
+    if (actual !== undefined && actual !== expected) {
+        throw new Error(`External webhook metadata ${key} does not match selected contract "${expected}".`);
+    }
+}
+function invalidType(path, expected) {
+    throw new Error(`External webhook payload ${path} must be ${expected}.`);
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export type { ExternalWebhookEventContract, WebhookSubscriptionEventInput, } from "./contracts.js";
+export { assertWebhookSubscriptionCreateEvents, assertWebhookSubscriptionUpdateEvents, prepareExternalWebhookEvent, } from "./contracts.js";
+export { hashWebhookPayload, redactWebhookHeaders, signWebhookPayload, webhookBodyExcerpt, } from "./security.js";
+export type { CreateSelectedExternalWebhookQueueOptions } from "./selected-queue.js";
+export { createSelectedExternalWebhookQueue, externalContractFromEventMetadata, } from "./selected-queue.js";
+export type { WebhookSubscriptionMutationStore, WebhookSubscriptionService, } from "./subscriptions.js";
+export { createWebhookSubscriptionService } from "./subscriptions.js";
+export type { CompleteWebhookAttemptInput, CreateWebhookDeliveryWorkerOptions, EnqueuedWebhookAttempt, EnqueueWebhookAttemptInput, SelectedExternalWebhookQueue, WebhookDeliveryAuditEvent, WebhookDeliveryOutcome, WebhookDeliveryStore, WebhookDeliveryWorker, WebhookEnqueueOutcome, WebhookRetryOptions, WebhookSubscription, } from "./types.js";
+export { createWebhookDeliveryWorker } from "./worker.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,4BAA4B,EAC5B,6BAA6B,GAC9B,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,qCAAqC,EACrC,qCAAqC,EACrC,2BAA2B,GAC5B,MAAM,gBAAgB,CAAA;AACvB,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,yCAAyC,EAAE,MAAM,qBAAqB,CAAA;AACpF,OAAO,EACL,kCAAkC,EAClC,iCAAiC,GAClC,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,gCAAgC,EAChC,0BAA0B,GAC3B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,gCAAgC,EAAE,MAAM,oBAAoB,CAAA;AACrE,YAAY,EACV,2BAA2B,EAC3B,kCAAkC,EAClC,sBAAsB,EACtB,0BAA0B,EAC1B,4BAA4B,EAC5B,yBAAyB,EACzB,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { assertWebhookSubscriptionCreateEvents, assertWebhookSubscriptionUpdateEvents, prepareExternalWebhookEvent, } from "./contracts.js";
+export { hashWebhookPayload, redactWebhookHeaders, signWebhookPayload, webhookBodyExcerpt, } from "./security.js";
+export { createSelectedExternalWebhookQueue, externalContractFromEventMetadata, } from "./selected-queue.js";
+export { createWebhookSubscriptionService } from "./subscriptions.js";
+export { createWebhookDeliveryWorker } from "./worker.js";

package/dist/postgres-store.d.ts

@@ -0,0 +1,20 @@
+import type { EventEnvelope } from "@voyant-travel/core";
+import type { AnyDrizzleDb } from "@voyant-travel/db";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { ExternalWebhookEventContract } from "./contracts.js";
+import { type WebhookSubscriptionService } from "./subscriptions.js";
+import type { SelectedExternalWebhookQueue, WebhookDeliveryStore, WebhookEnqueueOutcome } from "./types.js";
+export interface EnqueuePostgresWebhookEventOptions {
+    queue?: SelectedExternalWebhookQueue;
+}
+/** Persist one graph-selected event through the neutral Postgres delivery queue. */
+export declare function enqueuePostgresWebhookEvent(db: AnyDrizzleDb, event: EventEnvelope, options?: EnqueuePostgresWebhookEventOptions): Promise<WebhookEnqueueOutcome[]>;
+/**
+ * Postgres implementation for the Node delivery host. Transaction-scoped
+ * advisory locks make `(idempotencyKey, attemptNumber)` atomic even though the
+ * legacy audit table has an index rather than a unique constraint.
+ */
+export declare function createPostgresWebhookDeliveryStore(db: PostgresJsDatabase): WebhookDeliveryStore;
+/** The only package-owned Postgres mutation boundary for webhook subscriptions. */
+export declare function createPostgresWebhookSubscriptionService(db: PostgresJsDatabase, contracts: readonly ExternalWebhookEventContract[]): WebhookSubscriptionService;
+//# sourceMappingURL=postgres-store.d.ts.map

package/dist/postgres-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-store.d.ts","sourceRoot":"","sources":["../src/postgres-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAYrD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AACjE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAA;AAKlE,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAIV,4BAA4B,EAC5B,oBAAoB,EACpB,qBAAqB,EACtB,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,kCAAkC;IACjD,KAAK,CAAC,EAAE,4BAA4B,CAAA;CACrC;AAED,oFAAoF;AACpF,wBAAsB,2BAA2B,CAC/C,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,aAAa,EACpB,OAAO,GAAE,kCAAuC,GAC/C,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAQlC;AAED;;;;GAIG;AACH,wBAAgB,kCAAkC,CAAC,EAAE,EAAE,kBAAkB,GAAG,oBAAoB,CA+K/F;AAkCD,mFAAmF;AACnF,wBAAgB,wCAAwC,CACtD,EAAE,EAAE,kBAAkB,EACtB,SAAS,EAAE,SAAS,4BAA4B,EAAE,GACjD,0BAA0B,CAuB5B"}

package/dist/postgres-store.js

@@ -0,0 +1,216 @@
+import { newId } from "@voyant-travel/db/lib/typeid";
+import { infraWebhookDeliveriesTable, infraWebhookDeliverySelectSchema, infraWebhookSubscriptionInsertSchema, infraWebhookSubscriptionSelectSchema, infraWebhookSubscriptionsTable, infraWebhookSubscriptionUpdateSchema, } from "@voyant-travel/db/schema/infra";
+import { and, arrayContains, asc, eq, isNull, lte, or, sql } from "drizzle-orm";
+import { createSelectedExternalWebhookQueue, externalContractFromEventMetadata, } from "./selected-queue.js";
+import { createWebhookSubscriptionService, } from "./subscriptions.js";
+/** Persist one graph-selected event through the neutral Postgres delivery queue. */
+export async function enqueuePostgresWebhookEvent(db, event, options = {}) {
+    const queue = options.queue ??
+        createSelectedExternalWebhookQueue({
+            contracts: [externalContractFromEventMetadata(event)],
+            store: createPostgresWebhookDeliveryStore(db),
+        });
+    return queue.enqueue(event);
+}
+/**
+ * Postgres implementation for the Node delivery host. Transaction-scoped
+ * advisory locks make `(idempotencyKey, attemptNumber)` atomic even though the
+ * legacy audit table has an index rather than a unique constraint.
+ */
+export function createPostgresWebhookDeliveryStore(db) {
+    return {
+        async listActiveSubscriptions(eventName) {
+            const rows = await db
+                .select()
+                .from(infraWebhookSubscriptionsTable)
+                .where(and(eq(infraWebhookSubscriptionsTable.active, true), arrayContains(infraWebhookSubscriptionsTable.events, [eventName])));
+            return rows.map(toWebhookSubscription);
+        },
+        async getSubscription(id) {
+            const rows = await db
+                .select()
+                .from(infraWebhookSubscriptionsTable)
+                .where(eq(infraWebhookSubscriptionsTable.id, id))
+                .limit(1);
+            return rows[0] ? toWebhookSubscription(rows[0]) : null;
+        },
+        async listReadyAttemptIds(now, staleBefore, limit) {
+            const rows = await db
+                .select({ id: infraWebhookDeliveriesTable.id })
+                .from(infraWebhookDeliveriesTable)
+                .where(or(and(eq(infraWebhookDeliveriesTable.status, "pending"), or(isNull(infraWebhookDeliveriesTable.scheduledFor), lte(infraWebhookDeliveriesTable.scheduledFor, now))), and(eq(infraWebhookDeliveriesTable.status, "in_flight"), lte(infraWebhookDeliveriesTable.startedAt, staleBefore))))
+                .orderBy(asc(infraWebhookDeliveriesTable.scheduledFor), asc(infraWebhookDeliveriesTable.id))
+                .limit(limit);
+            return rows.map(({ id }) => id);
+        },
+        async enqueueAttempt(input) {
+            return db.transaction(async (tx) => {
+                const lockKey = `webhook-delivery:${input.idempotencyKey}:${input.attemptNumber}`;
+                await tx.execute(sql `SELECT pg_advisory_xact_lock(hashtextextended(${lockKey}, 0))`);
+                const existing = await tx
+                    .select()
+                    .from(infraWebhookDeliveriesTable)
+                    .where(and(eq(infraWebhookDeliveriesTable.idempotencyKey, input.idempotencyKey), eq(infraWebhookDeliveriesTable.attemptNumber, input.attemptNumber)))
+                    .limit(1);
+                if (existing[0]) {
+                    return {
+                        attempt: infraWebhookDeliverySelectSchema.parse(existing[0]),
+                        created: false,
+                    };
+                }
+                const inserted = await tx
+                    .insert(infraWebhookDeliveriesTable)
+                    .values(pendingAttemptValues(input))
+                    .returning();
+                const row = inserted[0];
+                if (!row)
+                    throw new Error("Webhook attempt insert returned no row");
+                return {
+                    attempt: infraWebhookDeliverySelectSchema.parse(row),
+                    created: true,
+                };
+            });
+        },
+        async claimAttempt(id, now, staleBefore) {
+            const rows = await db
+                .update(infraWebhookDeliveriesTable)
+                .set({ status: "in_flight", startedAt: now, updatedAt: now })
+                .where(and(eq(infraWebhookDeliveriesTable.id, id), or(eq(infraWebhookDeliveriesTable.status, "pending"), and(eq(infraWebhookDeliveriesTable.status, "in_flight"), lte(infraWebhookDeliveriesTable.startedAt, staleBefore))), or(isNull(infraWebhookDeliveriesTable.scheduledFor), lte(infraWebhookDeliveriesTable.scheduledFor, now))))
+                .returning();
+            return rows[0] ? infraWebhookDeliverySelectSchema.parse(rows[0]) : null;
+        },
+        async completeAttempt(input) {
+            const rows = await db
+                .update(infraWebhookDeliveriesTable)
+                .set({
+                status: input.status,
+                responseStatus: input.responseStatus,
+                responseHeaders: input.responseHeaders,
+                responseBodyExcerpt: input.responseBodyExcerpt,
+                errorClass: input.errorClass,
+                errorMessage: input.errorMessage,
+                finishedAt: input.finishedAt,
+                durationMs: input.durationMs,
+                updatedAt: input.finishedAt,
+            })
+                .where(and(eq(infraWebhookDeliveriesTable.id, input.id), eq(infraWebhookDeliveriesTable.status, "in_flight")))
+                .returning();
+            const row = rows[0];
+            if (!row)
+                throw new Error(`Webhook attempt ${input.id} was not in flight`);
+            return infraWebhookDeliverySelectSchema.parse(row);
+        },
+        async completeAndEnqueueRetry(completion, retry) {
+            return db.transaction(async (tx) => {
+                const completedRows = await tx
+                    .update(infraWebhookDeliveriesTable)
+                    .set(completedAttemptValues(completion))
+                    .where(and(eq(infraWebhookDeliveriesTable.id, completion.id), eq(infraWebhookDeliveriesTable.status, "in_flight")))
+                    .returning();
+                const completed = completedRows[0];
+                if (!completed)
+                    throw new Error(`Webhook attempt ${completion.id} was not in flight`);
+                const retryRows = await tx
+                    .insert(infraWebhookDeliveriesTable)
+                    .values(pendingAttemptValues(retry))
+                    .returning();
+                const retryRow = retryRows[0];
+                if (!retryRow) {
+                    throw new Error(`Webhook retry ${retry.idempotencyKey}:${retry.attemptNumber} returned no row`);
+                }
+                return {
+                    completed: infraWebhookDeliverySelectSchema.parse(completed),
+                    retry: infraWebhookDeliverySelectSchema.parse(retryRow),
+                };
+            });
+        },
+        async recordSubscriptionOutcome(subscriptionId, succeeded, at) {
+            await db
+                .update(infraWebhookSubscriptionsTable)
+                .set({
+                lastDeliveryAt: at,
+                failureCount: succeeded ? 0 : sql `${infraWebhookSubscriptionsTable.failureCount} + 1`,
+                updatedAt: at,
+            })
+                .where(eq(infraWebhookSubscriptionsTable.id, subscriptionId));
+        },
+    };
+}
+function toWebhookSubscription(row) {
+    return {
+        id: row.id,
+        url: row.url,
+        secret: row.secret,
+        headers: row.headers ?? null,
+        maxRetries: row.maxRetries,
+        active: row.active,
+    };
+}
+function completedAttemptValues(input) {
+    return {
+        status: input.status,
+        responseStatus: input.responseStatus,
+        responseHeaders: input.responseHeaders,
+        responseBodyExcerpt: input.responseBodyExcerpt,
+        errorClass: input.errorClass,
+        errorMessage: input.errorMessage,
+        finishedAt: input.finishedAt,
+        durationMs: input.durationMs,
+        updatedAt: input.finishedAt,
+    };
+}
+/** The only package-owned Postgres mutation boundary for webhook subscriptions. */
+export function createPostgresWebhookSubscriptionService(db, contracts) {
+    return createWebhookSubscriptionService({
+        contracts,
+        store: {
+            async create(input) {
+                const values = infraWebhookSubscriptionInsertSchema.parse(input);
+                const rows = await db
+                    .insert(infraWebhookSubscriptionsTable)
+                    .values({ id: newId("webhook_subscriptions"), ...values })
+                    .returning();
+                return requireSubscription(rows[0], "create");
+            },
+            async update(id, input) {
+                const values = infraWebhookSubscriptionUpdateSchema.parse(input);
+                const rows = await db
+                    .update(infraWebhookSubscriptionsTable)
+                    .set({ ...values, updatedAt: new Date() })
+                    .where(eq(infraWebhookSubscriptionsTable.id, id))
+                    .returning();
+                return requireSubscription(rows[0], `update "${id}"`);
+            },
+        },
+    });
+}
+function requireSubscription(row, operation) {
+    if (!row)
+        throw new Error(`Webhook subscription ${operation} returned no row.`);
+    return infraWebhookSubscriptionSelectSchema.parse(row);
+}
+function pendingAttemptValues(input) {
+    return {
+        id: newId("webhook_deliveries"),
+        sourceModule: input.sourceModule,
+        sourceEvent: input.sourceEvent,
+        sourceEntityModule: input.sourceEntityModule,
+        sourceEntityId: input.sourceEntityId,
+        subscriptionId: input.subscriptionId,
+        targetUrl: input.targetUrl,
+        targetKind: "subscription",
+        targetRef: input.subscriptionId,
+        requestMethod: input.requestMethod,
+        requestHeaders: input.requestHeaders,
+        requestBodyHash: input.requestBodyHash,
+        requestBodyExcerpt: input.requestBodyExcerpt,
+        requestPayload: input.requestPayload,
+        deliveryContract: input.deliveryContract,
+        attemptNumber: input.attemptNumber,
+        parentDeliveryId: input.parentDeliveryId,
+        idempotencyKey: input.idempotencyKey,
+        status: "pending",
+        scheduledFor: input.scheduledFor,
+        startedAt: null,
+    };
+}

package/dist/security.d.ts

@@ -0,0 +1,5 @@
+export declare function signWebhookPayload(secret: string, timestamp: string, body: string): string;
+export declare function hashWebhookPayload(body: string): string;
+export declare function redactWebhookHeaders(headers: Record<string, string> | undefined): Record<string, string> | null;
+export declare function webhookBodyExcerpt(body: unknown, maxBytes?: number): string | null;
+//# sourceMappingURL=security.d.ts.map

package/dist/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AAsDA,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1F;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAC1C,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAQ/B;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,SAAwB,GAAG,MAAM,GAAG,IAAI,CAoBjG"}

package/dist/security.js

@@ -0,0 +1,111 @@
+import { createHash, createHmac } from "node:crypto";
+const DEFAULT_EXCERPT_BYTES = 4 * 1024;
+const REDACTION_MARKER = "[REDACTED]";
+const REDACTED_HEADERS = new Set([
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+    "x-api-token",
+    "x-auth-token",
+    "x-access-token",
+    "x-voyant-signature",
+    "api-key",
+    "apikey",
+]);
+const REDACTED_BODY_KEYS = new Set([
+    "password",
+    "secret",
+    "token",
+    "accesstoken",
+    "refreshtoken",
+    "apikey",
+    "apitoken",
+    "authorization",
+    "email",
+    "phone",
+    "phonenumber",
+    "mobile",
+    "ssn",
+    "passport",
+    "passportnumber",
+    "documentnumber",
+    "nationalid",
+    "taxid",
+    "dob",
+    "dateofbirth",
+    "birthdate",
+    "cardnumber",
+    "pan",
+    "cvv",
+    "cvc",
+    "iban",
+    "bic",
+    "accountnumber",
+    "firstname",
+    "lastname",
+    "fullname",
+    "middlename",
+]);
+const EMAIL_PATTERN = /[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}/gi;
+const PHONE_PATTERN = /\+?\d[\d\s().-]{6,}\d/g;
+export function signWebhookPayload(secret, timestamp, body) {
+    return `sha256=${createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex")}`;
+}
+export function hashWebhookPayload(body) {
+    return createHash("sha256").update(body).digest("hex");
+}
+export function redactWebhookHeaders(headers) {
+    if (!headers)
+        return null;
+    return Object.fromEntries(Object.entries(headers).map(([name, value]) => [
+        name,
+        REDACTED_HEADERS.has(name.toLowerCase()) ? REDACTION_MARKER : value,
+    ]));
+}
+export function webhookBodyExcerpt(body, maxBytes = DEFAULT_EXCERPT_BYTES) {
+    if (body == null)
+        return null;
+    let text;
+    if (typeof body === "string") {
+        try {
+            text = JSON.stringify(redactValue(JSON.parse(body)));
+        }
+        catch {
+            text = redactString(body);
+        }
+    }
+    else {
+        try {
+            text = JSON.stringify(redactValue(body));
+        }
+        catch {
+            text = "[unserializable]";
+        }
+    }
+    if (Buffer.byteLength(text, "utf8") <= maxBytes)
+        return text;
+    return `${Buffer.from(text, "utf8")
+        .subarray(0, Math.max(0, maxBytes - 3))
+        .toString("utf8")}...`;
+}
+function redactValue(value) {
+    if (value == null)
+        return value;
+    if (typeof value === "string")
+        return redactString(value);
+    if (typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(redactValue);
+    const output = {};
+    for (const [key, item] of Object.entries(value)) {
+        const normalized = key.toLowerCase().replace(/[_-]/g, "");
+        output[key] = REDACTED_BODY_KEYS.has(normalized) ? REDACTION_MARKER : redactValue(item);
+    }
+    return output;
+}
+function redactString(value) {
+    return value.replace(EMAIL_PATTERN, REDACTION_MARKER).replace(PHONE_PATTERN, REDACTION_MARKER);
+}

package/dist/selected-queue.d.ts

@@ -0,0 +1,11 @@
+import type { EventEnvelope } from "@voyant-travel/core";
+import { type ExternalWebhookEventContract } from "./contracts.js";
+import type { SelectedExternalWebhookQueue, WebhookDeliveryStore } from "./types.js";
+export interface CreateSelectedExternalWebhookQueueOptions {
+    contracts: readonly ExternalWebhookEventContract[];
+    store: WebhookDeliveryStore;
+    now?: () => Date;
+}
+export declare function createSelectedExternalWebhookQueue(options: CreateSelectedExternalWebhookQueueOptions): SelectedExternalWebhookQueue;
+export declare function externalContractFromEventMetadata(event: EventEnvelope): ExternalWebhookEventContract;
+//# sourceMappingURL=selected-queue.d.ts.map

package/dist/selected-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"selected-queue.d.ts","sourceRoot":"","sources":["../src/selected-queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGxD,OAAO,EAAE,KAAK,4BAA4B,EAA+B,MAAM,gBAAgB,CAAA;AAE/F,OAAO,KAAK,EACV,4BAA4B,EAC5B,oBAAoB,EAErB,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,yCAAyC;IACxD,SAAS,EAAE,SAAS,4BAA4B,EAAE,CAAA;IAClD,KAAK,EAAE,oBAAoB,CAAA;IAC3B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACjB;AAED,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,yCAAyC,GACjD,4BAA4B,CA0D9B;AAED,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,aAAa,GACnB,4BAA4B,CAU9B"}

package/dist/selected-queue.js

@@ -0,0 +1,102 @@
+import { isExternalWebhookPayloadSchema } from "@voyant-travel/core/project";
+import { prepareExternalWebhookEvent } from "./contracts.js";
+import { hashWebhookPayload, redactWebhookHeaders, webhookBodyExcerpt } from "./security.js";
+export function createSelectedExternalWebhookQueue(options) {
+    const contracts = contractCatalog(options.contracts);
+    const now = options.now ?? (() => new Date());
+    return {
+        async enqueue(input) {
+            const eventId = requireEventId(input);
+            const contract = contracts.get(input.name);
+            if (!contract) {
+                throw new Error(`Event "${input.name}" is not in the selected external catalog.`);
+            }
+            const event = prepareExternalWebhookEvent(input, contract);
+            const body = JSON.stringify(event);
+            const subscriptions = await options.store.listActiveSubscriptions(event.name);
+            return Promise.all(subscriptions.map(async (subscription) => {
+                const idempotencyKey = `graph-webhook:${eventId}:${subscription.id}`;
+                const enqueued = await options.store.enqueueAttempt({
+                    sourceModule: stringMetadata(input, "graphEventSourceModule") ?? "graph-outbound-webhooks",
+                    sourceEvent: event.name,
+                    ...sourceEntity(event.data),
+                    subscriptionId: subscription.id,
+                    targetUrl: subscription.url,
+                    requestMethod: "POST",
+                    requestHeaders: redactWebhookHeaders({
+                        ...(subscription.headers ?? {}),
+                        "content-type": "application/json",
+                        "idempotency-key": idempotencyKey,
+                        "x-voyant-event": event.name,
+                        "x-voyant-event-id": eventId,
+                        "x-voyant-event-contract": contract.eventId,
+                        "x-voyant-event-version": contract.eventVersion,
+                    }) ?? {},
+                    requestBodyHash: hashWebhookPayload(body),
+                    requestBodyExcerpt: webhookBodyExcerpt(body),
+                    requestPayload: event,
+                    deliveryContract: contract,
+                    attemptNumber: 1,
+                    parentDeliveryId: null,
+                    idempotencyKey,
+                    scheduledFor: now(),
+                });
+                return {
+                    status: enqueued.created
+                        ? "pending"
+                        : isTerminal(enqueued.attempt.status)
+                            ? "already_completed"
+                            : "already_pending",
+                    subscriptionId: subscription.id,
+                    delivery: enqueued.attempt,
+                };
+            }));
+        },
+    };
+}
+export function externalContractFromEventMetadata(event) {
+    const eventId = stringMetadata(event, "graphEventId");
+    const eventVersion = stringMetadata(event, "graphEventVersion");
+    const payloadSchema = event.metadata?.graphEventPayloadSchema;
+    if (!eventId || !eventVersion || !isExternalWebhookPayloadSchema(payloadSchema)) {
+        throw new Error(`External webhook event "${event.name}" is missing its selected contract metadata.`);
+    }
+    return { eventId, eventType: event.name, eventVersion, payloadSchema };
+}
+function contractCatalog(contracts) {
+    const catalog = new Map();
+    for (const contract of contracts) {
+        if (catalog.has(contract.eventType)) {
+            throw new Error(`Duplicate external webhook event contract "${contract.eventType}".`);
+        }
+        catalog.set(contract.eventType, contract);
+    }
+    return catalog;
+}
+function requireEventId(event) {
+    const eventId = event.metadata?.eventId;
+    if (typeof eventId !== "string" || eventId.trim().length === 0) {
+        throw new Error(`Webhook event "${event.name}" requires metadata.eventId.`);
+    }
+    return eventId;
+}
+function stringMetadata(event, key) {
+    const value = event.metadata?.[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function sourceEntity(data) {
+    if (!isRecord(data))
+        return { sourceEntityModule: null, sourceEntityId: null };
+    const module = data.entityModule ?? data.entity_module;
+    const id = data.entityId ?? data.entity_id;
+    return {
+        sourceEntityModule: typeof module === "string" ? module : null,
+        sourceEntityId: typeof id === "string" ? id : null,
+    };
+}
+function isTerminal(status) {
+    return status === "succeeded" || status === "abandoned";
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/dist/subscriptions.d.ts

@@ -0,0 +1,15 @@
+import type { InfraWebhookSubscription, NewInfraWebhookSubscription, UpdateInfraWebhookSubscription } from "@voyant-travel/db/schema/infra";
+import { type ExternalWebhookEventContract } from "./contracts.js";
+export interface WebhookSubscriptionMutationStore {
+    create(input: NewInfraWebhookSubscription): Promise<InfraWebhookSubscription>;
+    update(id: string, input: UpdateInfraWebhookSubscription): Promise<InfraWebhookSubscription>;
+}
+export interface WebhookSubscriptionService {
+    create(input: NewInfraWebhookSubscription): Promise<InfraWebhookSubscription>;
+    update(id: string, input: UpdateInfraWebhookSubscription): Promise<InfraWebhookSubscription>;
+}
+export declare function createWebhookSubscriptionService(options: {
+    contracts: readonly ExternalWebhookEventContract[];
+    store: WebhookSubscriptionMutationStore;
+}): WebhookSubscriptionService;
+//# sourceMappingURL=subscriptions.d.ts.map

package/dist/subscriptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.d.ts","sourceRoot":"","sources":["../src/subscriptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,2BAA2B,EAC3B,8BAA8B,EAC/B,MAAM,gCAAgC,CAAA;AAEvC,OAAO,EAGL,KAAK,4BAA4B,EAClC,MAAM,gBAAgB,CAAA;AAEvB,MAAM,WAAW,gCAAgC;IAC/C,MAAM,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAA;IAC7E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,8BAA8B,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAA;CAC7F;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAA;IAC7E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,8BAA8B,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAA;CAC7F;AAED,wBAAgB,gCAAgC,CAAC,OAAO,EAAE;IACxD,SAAS,EAAE,SAAS,4BAA4B,EAAE,CAAA;IAClD,KAAK,EAAE,gCAAgC,CAAA;CACxC,GAAG,0BAA0B,CAW7B"}

package/dist/subscriptions.js

@@ -0,0 +1,13 @@
+import { assertWebhookSubscriptionCreateEvents, assertWebhookSubscriptionUpdateEvents, } from "./contracts.js";
+export function createWebhookSubscriptionService(options) {
+    return {
+        async create(input) {
+            assertWebhookSubscriptionCreateEvents(input, options.contracts);
+            return options.store.create(input);
+        },
+        async update(id, input) {
+            assertWebhookSubscriptionUpdateEvents(input, options.contracts);
+            return options.store.update(id, input);
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,104 @@
+import type { EventEnvelope } from "@voyant-travel/core";
+import type { InfraWebhookDelivery } from "@voyant-travel/db/schema/infra";
+import type { ExternalWebhookEventContract } from "./contracts.js";
+export interface WebhookSubscription {
+    id: string;
+    url: string;
+    secret: string;
+    headers: Record<string, string> | null;
+    maxRetries: number;
+    active: boolean;
+}
+export interface EnqueueWebhookAttemptInput {
+    sourceModule: string;
+    sourceEvent: string;
+    sourceEntityModule: string | null;
+    sourceEntityId: string | null;
+    subscriptionId: string;
+    targetUrl: string;
+    requestMethod: string;
+    requestHeaders: Record<string, string>;
+    requestBodyHash: string;
+    requestBodyExcerpt: string | null;
+    requestPayload: EventEnvelope;
+    deliveryContract: ExternalWebhookEventContract;
+    attemptNumber: number;
+    parentDeliveryId: string | null;
+    idempotencyKey: string;
+    scheduledFor: Date;
+}
+export interface CompleteWebhookAttemptInput {
+    id: string;
+    status: "succeeded" | "failed" | "abandoned";
+    responseStatus: number | null;
+    responseHeaders: Record<string, string> | null;
+    responseBodyExcerpt: string | null;
+    errorClass: InfraWebhookDelivery["errorClass"];
+    errorMessage: string | null;
+    finishedAt: Date;
+    durationMs: number;
+}
+export interface EnqueuedWebhookAttempt {
+    attempt: InfraWebhookDelivery;
+    created: boolean;
+}
+export interface WebhookDeliveryStore {
+    listActiveSubscriptions(eventName: string): Promise<WebhookSubscription[]>;
+    getSubscription(id: string): Promise<WebhookSubscription | null>;
+    enqueueAttempt(input: EnqueueWebhookAttemptInput): Promise<EnqueuedWebhookAttempt>;
+    listReadyAttemptIds(now: Date, staleBefore: Date, limit: number): Promise<string[]>;
+    claimAttempt(id: string, now: Date, staleBefore: Date): Promise<InfraWebhookDelivery | null>;
+    completeAttempt(input: CompleteWebhookAttemptInput): Promise<InfraWebhookDelivery>;
+    completeAndEnqueueRetry(completion: CompleteWebhookAttemptInput, retry: EnqueueWebhookAttemptInput): Promise<{
+        completed: InfraWebhookDelivery;
+        retry: InfraWebhookDelivery;
+    }>;
+    recordSubscriptionOutcome(subscriptionId: string, succeeded: boolean, at: Date): Promise<void>;
+}
+export type WebhookEnqueueOutcome = {
+    status: "pending" | "already_pending" | "already_completed";
+    subscriptionId: string;
+    delivery: InfraWebhookDelivery;
+};
+export type WebhookDeliveryOutcome = {
+    status: "succeeded" | "dead_lettered" | "retry_scheduled";
+    subscriptionId: string | null;
+    delivery: InfraWebhookDelivery;
+    nextAttempt?: InfraWebhookDelivery;
+} | {
+    status: "idle";
+};
+export interface WebhookDeliveryAuditEvent {
+    eventId: string | null;
+    eventName: string;
+    contractId?: string;
+    contractVersion?: string;
+    subscriptionId: string | null;
+    outcome: Exclude<WebhookDeliveryOutcome["status"], "idle">;
+    deliveryId: string;
+    attemptNumber: number;
+    reason?: string;
+}
+export interface WebhookRetryOptions {
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    requestTimeoutMs?: number;
+    claimTimeoutMs?: number;
+}
+export interface CreateWebhookDeliveryWorkerOptions {
+    store: WebhookDeliveryStore;
+    fetch?: typeof globalThis.fetch;
+    now?: () => Date;
+    retry?: WebhookRetryOptions;
+    onAudit?: (event: WebhookDeliveryAuditEvent) => void | Promise<void>;
+}
+export interface WebhookDeliveryWorker {
+    runNext(): Promise<WebhookDeliveryOutcome>;
+    drain(options?: {
+        limit?: number;
+    }): Promise<WebhookDeliveryOutcome[]>;
+}
+export interface SelectedExternalWebhookQueue {
+    enqueue(event: EventEnvelope): Promise<WebhookEnqueueOutcome[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/worker.d.ts

@@ -0,0 +1,3 @@
+import type { CreateWebhookDeliveryWorkerOptions, WebhookDeliveryWorker } from "./types.js";
+export declare function createWebhookDeliveryWorker(options: CreateWebhookDeliveryWorkerOptions): WebhookDeliveryWorker;
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAEV,kCAAkC,EAIlC,qBAAqB,EAEtB,MAAM,YAAY,CAAA;AASnB,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,kCAAkC,GAC1C,qBAAqB,CAkJvB"}

package/dist/worker.js

@@ -0,0 +1,317 @@
+import { isExternalWebhookPayloadSchema } from "@voyant-travel/core/project";
+import { hashWebhookPayload, redactWebhookHeaders, signWebhookPayload, webhookBodyExcerpt, } from "./security.js";
+const DEFAULT_BASE_DELAY_MS = 1_000;
+const DEFAULT_MAX_DELAY_MS = 60_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+const DEFAULT_CLAIM_TIMEOUT_MS = 60_000;
+const MAX_RESPONSE_BODY_BYTES = 4 * 1024;
+const MAX_ERROR_MESSAGE_LENGTH = 1_000;
+export function createWebhookDeliveryWorker(options) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const now = options.now ?? (() => new Date());
+    const baseDelayMs = positiveInteger(options.retry?.baseDelayMs, DEFAULT_BASE_DELAY_MS);
+    const maxDelayMs = positiveInteger(options.retry?.maxDelayMs, DEFAULT_MAX_DELAY_MS);
+    const requestTimeoutMs = positiveInteger(options.retry?.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS);
+    const claimTimeoutMs = positiveInteger(options.retry?.claimTimeoutMs, DEFAULT_CLAIM_TIMEOUT_MS);
+    return {
+        async runNext() {
+            const claimedAt = now();
+            const staleBefore = new Date(claimedAt.getTime() - claimTimeoutMs);
+            const ids = await options.store.listReadyAttemptIds(claimedAt, staleBefore, 1);
+            for (const id of ids) {
+                const delivery = await options.store.claimAttempt(id, claimedAt, staleBefore);
+                if (delivery)
+                    return execute(delivery, claimedAt);
+            }
+            return { status: "idle" };
+        },
+        async drain(input = {}) {
+            const outcomes = [];
+            const limit = positiveInteger(input.limit, 100);
+            while (outcomes.length < limit) {
+                const outcome = await this.runNext();
+                if (outcome.status === "idle")
+                    break;
+                outcomes.push(outcome);
+            }
+            return outcomes;
+        },
+    };
+    async function execute(delivery, startedAt) {
+        const hydrated = hydrateAttempt(delivery);
+        if (!hydrated.ok)
+            return abandon(delivery, startedAt, hydrated.reason);
+        const subscription = await options.store.getSubscription(delivery.subscriptionId ?? "");
+        if (!subscription?.active) {
+            return abandon(delivery, startedAt, "webhook subscription is unavailable or inactive");
+        }
+        const body = JSON.stringify(hydrated.event);
+        if (hashWebhookPayload(body) !== delivery.requestBodyHash) {
+            return abandon(delivery, startedAt, "persisted webhook payload hash does not match");
+        }
+        const timestamp = Math.floor(startedAt.getTime() / 1_000).toString();
+        const requestHeaders = signedHeaders(subscription, hydrated.event, hydrated.contract, delivery.idempotencyKey ?? delivery.id, timestamp, body);
+        const result = await dispatch(fetchImpl, delivery.targetUrl, requestHeaders, body, requestTimeoutMs);
+        const finishedAt = now();
+        const completion = completionInput(delivery, result, startedAt, finishedAt);
+        if (result.succeeded) {
+            const completed = await options.store.completeAttempt({ ...completion, status: "succeeded" });
+            await options.store.recordSubscriptionOutcome(subscription.id, true, finishedAt);
+            const outcome = {
+                status: "succeeded",
+                subscriptionId: subscription.id,
+                delivery: completed,
+            };
+            await audit(options, hydrated.event, hydrated.contract, outcome);
+            return outcome;
+        }
+        const mayRetry = result.retryable && delivery.attemptNumber <= subscription.maxRetries;
+        if (mayRetry) {
+            const retry = retryInput(delivery, hydrated.event, hydrated.contract, subscription, body, finishedAt, baseDelayMs, maxDelayMs);
+            const persisted = await options.store.completeAndEnqueueRetry({ ...completion, status: "failed" }, retry);
+            const outcome = {
+                status: "retry_scheduled",
+                subscriptionId: subscription.id,
+                delivery: persisted.completed,
+                nextAttempt: persisted.retry,
+            };
+            await audit(options, hydrated.event, hydrated.contract, outcome);
+            return outcome;
+        }
+        const completed = await options.store.completeAttempt({ ...completion, status: "abandoned" });
+        await options.store.recordSubscriptionOutcome(subscription.id, false, finishedAt);
+        const outcome = {
+            status: "dead_lettered",
+            subscriptionId: subscription.id,
+            delivery: completed,
+        };
+        await audit(options, hydrated.event, hydrated.contract, outcome);
+        return outcome;
+    }
+    async function abandon(delivery, startedAt, reason) {
+        const finishedAt = now();
+        const completed = await options.store.completeAttempt({
+            id: delivery.id,
+            status: "abandoned",
+            responseStatus: null,
+            responseHeaders: null,
+            responseBodyExcerpt: null,
+            errorClass: "adapter_error",
+            errorMessage: boundedMessage(reason),
+            finishedAt,
+            durationMs: Math.max(0, finishedAt.getTime() - startedAt.getTime()),
+        });
+        if (delivery.subscriptionId) {
+            await options.store.recordSubscriptionOutcome(delivery.subscriptionId, false, finishedAt);
+        }
+        const outcome = {
+            status: "dead_lettered",
+            subscriptionId: delivery.subscriptionId,
+            delivery: completed,
+        };
+        await auditFromDelivery(options, delivery, outcome, reason);
+        return outcome;
+    }
+}
+function hydrateAttempt(delivery) {
+    if (!isEventEnvelope(delivery.requestPayload)) {
+        return { ok: false, reason: "pending webhook delivery has no complete request payload" };
+    }
+    if (!isExternalContract(delivery.deliveryContract)) {
+        return { ok: false, reason: "pending webhook delivery has no valid contract snapshot" };
+    }
+    if (delivery.requestPayload.name !== delivery.deliveryContract.eventType) {
+        return { ok: false, reason: "persisted webhook payload and contract event types differ" };
+    }
+    return { ok: true, event: delivery.requestPayload, contract: delivery.deliveryContract };
+}
+function isEventEnvelope(value) {
+    return (isRecord(value) &&
+        typeof value.name === "string" &&
+        "data" in value &&
+        typeof value.emittedAt === "string");
+}
+function isExternalContract(value) {
+    return (isRecord(value) &&
+        typeof value.eventId === "string" &&
+        typeof value.eventType === "string" &&
+        typeof value.eventVersion === "string" &&
+        isExternalWebhookPayloadSchema(value.payloadSchema));
+}
+async function dispatch(fetchImpl, url, headers, body, timeoutMs) {
+    assertWebhookUrl(url);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(url, {
+            method: "POST",
+            headers,
+            body,
+            signal: controller.signal,
+        });
+        const responseBody = await readBoundedResponseBody(response, MAX_RESPONSE_BODY_BYTES);
+        const responseHeaders = Object.fromEntries(response.headers.entries());
+        if (response.ok) {
+            return {
+                succeeded: true,
+                retryable: false,
+                responseStatus: response.status,
+                responseHeaders,
+                responseBody,
+                errorClass: null,
+                errorMessage: null,
+            };
+        }
+        const rateLimited = response.status === 429;
+        return {
+            succeeded: false,
+            retryable: rateLimited || response.status === 408 || response.status >= 500,
+            responseStatus: response.status,
+            responseHeaders,
+            responseBody,
+            errorClass: rateLimited ? "rate_limited" : response.status >= 500 ? "5xx" : "4xx",
+            errorMessage: boundedMessage(`HTTP ${response.status}`),
+        };
+    }
+    catch (error) {
+        return {
+            succeeded: false,
+            retryable: true,
+            responseStatus: null,
+            errorClass: controller.signal.aborted ? "timeout" : "network",
+            errorMessage: boundedMessage(error instanceof Error ? error.message : String(error)),
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function retryInput(delivery, event, contract, subscription, body, now, baseDelayMs, maxDelayMs) {
+    const nextAttempt = delivery.attemptNumber + 1;
+    return {
+        sourceModule: delivery.sourceModule,
+        sourceEvent: delivery.sourceEvent,
+        sourceEntityModule: delivery.sourceEntityModule,
+        sourceEntityId: delivery.sourceEntityId,
+        subscriptionId: subscription.id,
+        targetUrl: delivery.targetUrl,
+        requestMethod: "POST",
+        requestHeaders: delivery.requestHeaders ?? {},
+        requestBodyHash: hashWebhookPayload(body),
+        requestBodyExcerpt: webhookBodyExcerpt(body),
+        requestPayload: event,
+        deliveryContract: contract,
+        attemptNumber: nextAttempt,
+        parentDeliveryId: delivery.id,
+        idempotencyKey: delivery.idempotencyKey ?? delivery.id,
+        scheduledFor: new Date(now.getTime() + retryDelay(delivery.attemptNumber, baseDelayMs, maxDelayMs)),
+    };
+}
+function completionInput(delivery, result, startedAt, finishedAt) {
+    return {
+        id: delivery.id,
+        responseStatus: result.responseStatus,
+        responseHeaders: redactWebhookHeaders(result.responseHeaders),
+        responseBodyExcerpt: webhookBodyExcerpt(result.responseBody),
+        errorClass: result.errorClass,
+        errorMessage: result.errorMessage,
+        finishedAt,
+        durationMs: Math.max(0, finishedAt.getTime() - startedAt.getTime()),
+    };
+}
+function signedHeaders(subscription, event, contract, idempotencyKey, timestamp, body) {
+    const eventId = stringMetadata(event, "eventId");
+    if (!eventId)
+        throw new Error(`Persisted webhook event "${event.name}" has no event id.`);
+    return {
+        ...(subscription.headers ?? {}),
+        "content-type": "application/json",
+        "idempotency-key": idempotencyKey,
+        "x-voyant-event": event.name,
+        "x-voyant-event-id": eventId,
+        "x-voyant-event-contract": contract.eventId,
+        "x-voyant-event-version": contract.eventVersion,
+        "x-voyant-timestamp": timestamp,
+        "x-voyant-signature": signWebhookPayload(subscription.secret, timestamp, body),
+    };
+}
+async function audit(options, event, contract, outcome) {
+    if (!options.onAudit)
+        return;
+    await options.onAudit({
+        eventId: stringMetadata(event, "eventId"),
+        eventName: event.name,
+        contractId: contract.eventId,
+        contractVersion: contract.eventVersion,
+        subscriptionId: outcome.subscriptionId,
+        outcome: outcome.status,
+        deliveryId: outcome.delivery.id,
+        attemptNumber: outcome.delivery.attemptNumber,
+    });
+}
+async function auditFromDelivery(options, delivery, outcome, reason) {
+    if (!options.onAudit)
+        return;
+    const payload = isEventEnvelope(delivery.requestPayload) ? delivery.requestPayload : null;
+    const contract = isExternalContract(delivery.deliveryContract) ? delivery.deliveryContract : null;
+    const auditEvent = {
+        eventId: payload ? stringMetadata(payload, "eventId") : null,
+        eventName: payload?.name ?? delivery.sourceEvent,
+        ...(contract ? { contractId: contract.eventId, contractVersion: contract.eventVersion } : {}),
+        subscriptionId: delivery.subscriptionId,
+        outcome: outcome.status,
+        deliveryId: outcome.delivery.id,
+        attemptNumber: outcome.delivery.attemptNumber,
+        reason,
+    };
+    await options.onAudit(auditEvent);
+}
+async function readBoundedResponseBody(response, maxBytes) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        return "";
+    const buffer = new Uint8Array(maxBytes);
+    let offset = 0;
+    let complete = false;
+    try {
+        while (offset < maxBytes) {
+            const chunk = await reader.read();
+            if (chunk.done) {
+                complete = true;
+                break;
+            }
+            const length = Math.min(maxBytes - offset, chunk.value.byteLength);
+            buffer.set(chunk.value.subarray(0, length), offset);
+            offset += length;
+            if (length < chunk.value.byteLength)
+                break;
+        }
+    }
+    finally {
+        if (!complete)
+            await reader.cancel().catch(() => undefined);
+    }
+    return new TextDecoder().decode(buffer.subarray(0, offset));
+}
+function retryDelay(attemptNumber, baseDelayMs, maxDelayMs) {
+    return Math.min(maxDelayMs, baseDelayMs * 2 ** Math.max(0, attemptNumber - 1));
+}
+function positiveInteger(value, fallback) {
+    return value !== undefined && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+function boundedMessage(message) {
+    return message.slice(0, MAX_ERROR_MESSAGE_LENGTH);
+}
+function assertWebhookUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`Webhook URL must use HTTP(S): ${value}`);
+    }
+}
+function stringMetadata(event, key) {
+    const value = event.metadata?.[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@voyant-travel/webhook-delivery",
+  "version": "0.1.0",
+  "description": "Durable, policy-aware outbound webhook delivery for Voyant Node deployments.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./postgres": "./src/postgres-store.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "lint": "biome check src/ tests/",
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "prepack": "pnpm --filter @voyant-travel/webhook-delivery... run build"
+  },
+  "dependencies": {
+    "@voyant-travel/core": "workspace:^",
+    "@voyant-travel/db": "workspace:^",
+    "drizzle-orm": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@voyant-travel/voyant-typescript-config": "workspace:^",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      },
+      "./postgres": {
+        "types": "./dist/postgres-store.d.ts",
+        "import": "./dist/postgres-store.js",
+        "default": "./dist/postgres-store.js"
+      }
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyant-travel/voyant.git",
+    "directory": "packages/webhook-delivery"
+  }
+}