@openlup/platform 0.16.0 → 0.18.0

package/dist/communications/postgresNotificationRecipients.js

@@ -0,0 +1,60 @@
+import { CommunicationConflictError } from "./errors.js";
+import { nativeEmail, nativeStamp, nativeText, nativeTransactions } from "./postgresNativeOperations.js";
+const types = ["packaging_digest", "new_signup", "commerce_payment_critical"];
+function notificationType(value) {
+    if (!types.includes(value))
+        throw new Error("native_notification_type_invalid");
+    return value;
+}
+export function createPostgresNotificationRecipientsPort(env, options) {
+    const operator = nativeText(options.operatorId);
+    const lane = nativeTransactions(env, options, ["public.notification_recipients", "public.platform_communication_operators", "public.platform_human_memberships", "public.platform_control_operators"]);
+    const run = (work) => lane.run(async (db) => {
+        // Match the reference communications control-plane admission, retaining row locks through commit.
+        const allowed = (await db.query(`SELECT o.principal_id FROM public.platform_communication_operators o
+      JOIN public.platform_human_memberships m ON m.principal_id=o.principal_id
+      WHERE o.principal_id=$1 AND o.active AND m.membership_state='active' AND m.role IN ('admin','distributor')
+      AND NOT EXISTS (SELECT 1 FROM public.platform_control_operators c WHERE c.principal_id=o.principal_id) FOR SHARE OF o,m`, [operator])).rows;
+        if (allowed.length !== 1)
+            throw new Error("communications_operator_required");
+        return work(db);
+    });
+    return {
+        close: lane.close,
+        listNotificationRecipients(input) {
+            const type = notificationType(input.notification_type);
+            return run(async (db) => ({ recipients: (await db.query("SELECT id,email,name,active,notification_type,created_at FROM public.notification_recipients WHERE notification_type=$1 ORDER BY created_at,id", [type])).rows.map(row => {
+                    if (typeof row.active !== "boolean" || (row.name !== null && typeof row.name !== "string"))
+                        throw new Error("native_notification_row_invalid");
+                    return { id: nativeText(row.id), email: nativeEmail(row.email), name: row.name, active: row.active, notification_type: notificationType(row.notification_type), created_at: nativeStamp(row.created_at) };
+                }) }));
+        },
+        async createNotificationRecipient(input) {
+            const email = nativeEmail(input.email), type = notificationType(input.notification_type);
+            if (input.active !== true || (input.name !== null && typeof input.name !== "string"))
+                throw new Error("native_notification_request_invalid");
+            const name = input.name === null ? null : input.name.trim();
+            if (name !== null && name.length > 256)
+                throw new Error("native_notification_request_invalid");
+            try {
+                return await run(async (db) => {
+                    await db.query("INSERT INTO public.notification_recipients (email,name,notification_type,active) VALUES ($1,$2,$3,true)", [email, name, type]);
+                    return { created: true, email, notification_type: type };
+                });
+            }
+            catch (error) {
+                if (error && typeof error === "object" && "code" in error && error.code === "23505")
+                    throw new CommunicationConflictError("notification_recipient_conflict");
+                throw error;
+            }
+        },
+        async updateNotificationRecipient(input) {
+            if (typeof input.active !== "boolean" || Object.keys(input).some(key => !["active", "recipientId"].includes(key)))
+                throw new Error("native_notification_request_invalid");
+            return run(async (db) => { await db.query("UPDATE public.notification_recipients SET active=$2,updated_at=clock_timestamp() WHERE id=$1", [input.recipientId, input.active]); return { updated: true, recipientId: input.recipientId }; });
+        },
+        deleteNotificationRecipient(input) {
+            return run(async (db) => { await db.query("DELETE FROM public.notification_recipients WHERE id=$1", [input.recipientId]); return { deleted: true, recipientId: input.recipientId }; });
+        },
+    };
+}

package/dist/communications/postgresTransactionalDeliveryStore.d.ts

@@ -0,0 +1,7 @@
+import { createPostgresRoleFreeTransactionLane, type PostgresDataGatewayEnv, type PostgresDataGatewayOptions } from "../data/index.js";
+import type { TransactionalDeliveryReceiptStore } from "./contracts/transactionalDelivery.js";
+export interface PostgresTransactionalDeliveryStore extends TransactionalDeliveryReceiptStore {
+    close(): Promise<void>;
+}
+/** Direct-Postgres receipt adapter: one role-free transaction for each store operation. */
+export declare function createPostgresTransactionalDeliveryStore(env: PostgresDataGatewayEnv, options?: PostgresDataGatewayOptions, createTransactionLane?: typeof createPostgresRoleFreeTransactionLane): PostgresTransactionalDeliveryStore;

package/dist/communications/postgresTransactionalDeliveryStore.js

@@ -0,0 +1,55 @@
+import { createPostgresRoleFreeTransactionLane, } from "../data/index.js";
+function failure(name, error) {
+    const result = new Error(`${name}_failed: ${error.message ?? error.code ?? "unknown"}`);
+    result.code = error.code;
+    return result;
+}
+function receipt(data) {
+    const value = (Array.isArray(data) ? data[0] : data);
+    if (!value || typeof value !== "object")
+        throw new Error("transactional_delivery_receipt_invalid");
+    const common = {
+        idempotencyKey: String(value.idempotency_key ?? ""),
+        commandFingerprint: String(value.command_fingerprint ?? ""),
+        attemptCount: Number(value.attempt_count ?? 0),
+    };
+    if (value.state === "accepted" && typeof value.delivery_reference === "string" && value.error_code == null) {
+        return { ...common, state: "accepted", deliveryReference: value.delivery_reference, errorCode: null };
+    }
+    if (value.state === "failed" && value.delivery_reference == null && typeof value.error_code === "string") {
+        return { ...common, state: "failed", deliveryReference: null, errorCode: value.error_code };
+    }
+    throw new Error("transactional_delivery_receipt_invalid");
+}
+/** Direct-Postgres receipt adapter: one role-free transaction for each store operation. */
+export function createPostgresTransactionalDeliveryStore(env, options = {}, createTransactionLane = createPostgresRoleFreeTransactionLane) {
+    const transactions = createTransactionLane(env, options);
+    const call = (work) => transactions.run((client) => work(client));
+    const write = (name, args) => call(async (client) => {
+        const { data, error } = await client.rpc(name, args);
+        if (error)
+            throw failure(name, error);
+        return receipt(data);
+    });
+    return {
+        async readReceipt(idempotencyKey) {
+            return call(async (client) => {
+                const { data, error } = await client.rpc("transactional_delivery_read_receipt", { p_idempotency_key: idempotencyKey });
+                if (error)
+                    throw failure("transactional_delivery_read_receipt", error);
+                return Array.isArray(data) && data.length === 0 ? null : receipt(data);
+            });
+        },
+        recordAccepted: (input) => write("transactional_delivery_record_accepted", {
+            p_idempotency_key: input.idempotencyKey,
+            p_command_fingerprint: input.commandFingerprint,
+            p_delivery_reference: input.deliveryReference,
+        }),
+        recordFailed: (input) => write("transactional_delivery_record_failed", {
+            p_idempotency_key: input.idempotencyKey,
+            p_command_fingerprint: input.commandFingerprint,
+            p_error_code: input.errorCode,
+        }),
+        close: () => transactions.close(),
+    };
+}

package/dist/communications/preferencesToken.d.ts

@@ -0,0 +1,10 @@
+import type { CommunicationPurposeRegistry } from "./contracts/consent.js";
+export type LegacyCommunicationPreferencePurpose = "tester_program" | "marketing_launch_offer" | "marketing_newsletter";
+export interface CommunicationPreferenceTokenPayload<Purpose extends string = LegacyCommunicationPreferencePurpose> {
+    email: string;
+    purpose: Purpose;
+    expiresAt: number;
+}
+export declare function verifyCommunicationPreferenceToken(token: string, secret: string, nowMs?: number): CommunicationPreferenceTokenPayload | null;
+export declare function verifyCommunicationPreferenceToken<Purpose extends string>(token: string, secret: string, nowMs: number | undefined, registry: CommunicationPurposeRegistry<Purpose>): CommunicationPreferenceTokenPayload<Purpose> | null;
+export declare function createCommunicationPreferenceToken<Purpose extends string = LegacyCommunicationPreferencePurpose>(payload: CommunicationPreferenceTokenPayload<Purpose>, secret: string): string;

package/dist/communications/preferencesToken.js

@@ -0,0 +1,40 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export function verifyCommunicationPreferenceToken(token, secret, nowMs = Date.now(), registry) {
+    const parts = token.split(".");
+    if (parts.length !== 2 || !secret)
+        return null;
+    const [encoded, signature] = parts;
+    const expected = hmac(encoded, secret);
+    if (!safeEqual(signature, expected))
+        return null;
+    try {
+        const payload = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+        const email = typeof payload.email === "string" ? payload.email.trim().toLowerCase() : "";
+        const purpose = payload.purpose;
+        const expiresAt = typeof payload.expiresAt === "number" ? payload.expiresAt : 0;
+        if (!email.includes("@") || expiresAt < nowMs)
+            return null;
+        if (typeof purpose !== "string" || (registry ? !registry.has(purpose) :
+            purpose !== "tester_program" &&
+                purpose !== "marketing_launch_offer" &&
+                purpose !== "marketing_newsletter")) {
+            return null;
+        }
+        return { email, purpose, expiresAt };
+    }
+    catch {
+        return null;
+    }
+}
+export function createCommunicationPreferenceToken(payload, secret) {
+    const encoded = Buffer.from(JSON.stringify(payload)).toString("base64url");
+    return `${encoded}.${hmac(encoded, secret)}`;
+}
+function hmac(value, secret) {
+    return createHmac("sha256", secret).update(value).digest("hex");
+}
+function safeEqual(left, right) {
+    const leftBuffer = Buffer.from(left);
+    const rightBuffer = Buffer.from(right);
+    return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}

package/dist/communications/publicPreferenceToken.d.ts

@@ -0,0 +1,24 @@
+import type { CommunicationPurposeRegistry, CommunicationPurposeDefinition } from "./contracts/consent.js";
+import type { CommunicationPreferenceTokenPayload } from "./preferencesToken.js";
+export interface PublicPreferenceTokenSupabaseClient {
+    rpc(fn: string, args: Record<string, unknown>): Promise<{
+        data: unknown;
+        error?: unknown;
+    }>;
+}
+export type PublicPreferenceState = "denied" | "suppressed";
+export declare function createSupabasePublicPreferenceTokenPort(client: PublicPreferenceTokenSupabaseClient): {
+    updatePreference(payload: CommunicationPreferenceTokenPayload, state: PublicPreferenceState): Promise<{
+        updated: boolean;
+        email: string;
+        purpose: "marketing_launch_offer" | "marketing_newsletter" | "tester_program";
+        state: PublicPreferenceState;
+    }>;
+};
+/** The host owns persistence and any synchronization policy for registered purposes. */
+export declare function createRegisteredPublicPreferenceTokenPort<Purpose extends string>(input: {
+    registry: CommunicationPurposeRegistry<Purpose>;
+    persist: (payload: CommunicationPreferenceTokenPayload<Purpose>, state: PublicPreferenceState, definition: CommunicationPurposeDefinition<Purpose>) => Promise<unknown>;
+}): {
+    updatePreference(payload: CommunicationPreferenceTokenPayload<Purpose>, state: PublicPreferenceState): Promise<unknown>;
+};

package/dist/communications/publicPreferenceToken.js

@@ -0,0 +1,53 @@
+export function createSupabasePublicPreferenceTokenPort(client) {
+    return {
+        async updatePreference(payload, state) {
+            const contact = await client.rpc("communication_touch_contact", {
+                p_email: payload.email,
+                p_first_name: null,
+                p_last_name: null,
+                p_status: "active",
+                p_metadata: { source: "public_communication_preferences" },
+            });
+            if (contact.error || typeof contact.data !== "string") {
+                throw new Error("Communication contact write failed");
+            }
+            const event = await client.rpc("communication_record_permission_event", {
+                p_contact_id: contact.data,
+                p_purpose: payload.purpose,
+                p_state: state,
+                p_source: "public_communication_preferences",
+                p_source_ref: { route: "/api/bff/communications/preferences", purpose: payload.purpose },
+                p_reason: "user_preference_update",
+                p_metadata: {
+                    actorType: "contact_self_service",
+                    captureMethod: "preference_token",
+                },
+                p_captured_at: new Date().toISOString(),
+                p_create_sync_event: payload.purpose !== "tester_program",
+            });
+            if (event.error)
+                throw new Error("Communication preference write failed");
+            return {
+                updated: true,
+                email: payload.email,
+                // Keep the legacy adapter declaration expanded when the token default names a type alias.
+                purpose: payload.purpose,
+                state,
+            };
+        },
+    };
+}
+/** The host owns persistence and any synchronization policy for registered purposes. */
+export function createRegisteredPublicPreferenceTokenPort(input) {
+    const { registry, persist } = input;
+    return {
+        async updatePreference(payload, state) {
+            if (!registry.has(payload.purpose))
+                throw new Error("unregistered_communication_purpose");
+            if (state !== "denied" && state !== "suppressed")
+                throw new Error("communication_preference_state_invalid");
+            const definition = registry.purposes.find(item => item.id === payload.purpose);
+            return persist(payload, state, definition);
+        },
+    };
+}

package/dist/communications/resend/index.d.ts

@@ -0,0 +1,40 @@
+import { type EmailEgressPolicy } from "../emailEgress.js";
+import type { EmailTransport } from "../emailTransport.js";
+import { type EmailObservationPort } from "../emailObservation.js";
+import { type DeliveryReconciliationPort, type DeliveryReconciliationResult } from "../deliveryReconciliation.js";
+/** Opt-in Node sender. Every send obtains a fresh validated host egress decision. */
+export declare function createResendTransport(input: {
+    policy: EmailEgressPolicy;
+    environmentTagName: string;
+    fetch?: typeof fetch;
+}): EmailTransport;
+/** Poll existing IDs through the neutral runner; never retries a send. */
+export declare function runResendDeliveryReconciliation(input: {
+    port: DeliveryReconciliationPort;
+    now: string;
+    graceMinutes: number;
+    limit: number;
+    apiKey: string;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+}): Promise<DeliveryReconciliationResult>;
+/** Authenticate untouched bytes before decoding. now returns UTC seconds; receiver defaults to non-production. */
+export declare function createResendWebhookHandler(input: {
+    port: EmailObservationPort;
+    webhookSecret: string;
+    environmentTagName: string;
+    resolveReceiverEnvironmentTag?: () => "production" | "non_production";
+    now?: () => number;
+    receivedAt?: () => Date;
+}): (request: {
+    method?: string;
+    rawBody: string | Uint8Array;
+    headers: {
+        webhookId?: string;
+        timestamp?: string;
+        signature?: string;
+    };
+}) => Promise<{
+    status: number;
+    body: Record<string, unknown> | "ok";
+}>;

package/dist/communications/resend/index.js

@@ -0,0 +1,310 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { createGuardedEmailTransport } from "../emailEgress.js";
+import { processEmailObservation } from "../emailObservation.js";
+import { runDeliveryReconciliation } from "../deliveryReconciliation.js";
+/** Opt-in Node sender. Every send obtains a fresh validated host egress decision. */
+export function createResendTransport(input) {
+    return createGuardedEmailTransport({
+        providerKind: "resend",
+        policy: input.policy,
+        send: (message, context) => postResendEmail(message, context, input.environmentTagName, input.fetch ?? fetch),
+    });
+}
+const RESEND_ENDPOINT = "https://api.resend.com/emails";
+const PROVIDER_ERROR_MAX = 240;
+const PROVIDER_ERROR_CODE_MAX = 80;
+const EMAIL_ADDRESS_PATTERN = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+function truncate(value, max) {
+    return value.length > max ? `${value.slice(0, max - 1)}...` : value;
+}
+function sanitizeProviderText(value) {
+    return truncate(value.replace(EMAIL_ADDRESS_PATTERN, "[email]").replace(/\s+/g, " ").trim(), PROVIDER_ERROR_MAX);
+}
+function sanitizeProviderCode(value) {
+    return truncate(value.replace(/[^A-Za-z0-9._:-]/g, "_"), PROVIDER_ERROR_CODE_MAX);
+}
+function providerErrorFromBody(body, httpStatus) {
+    const errField = body.error;
+    if (typeof errField === "string")
+        return sanitizeProviderText(errField);
+    if (errField && typeof errField === "object") {
+        const message = errField.message;
+        if (typeof message === "string")
+            return sanitizeProviderText(message);
+    }
+    if (typeof body.message === "string")
+        return sanitizeProviderText(body.message);
+    return `Resend HTTP ${httpStatus}`;
+}
+function providerErrorCodeFromBody(body) {
+    const errField = body.error;
+    const errorRecord = errField && typeof errField === "object"
+        ? errField
+        : {};
+    const candidates = [
+        errorRecord.code,
+        errorRecord.name,
+        errorRecord.type,
+        body.code,
+        body.name,
+        body.type,
+    ];
+    const value = candidates.find((candidate) => typeof candidate === "string" && candidate.trim() !== "");
+    return typeof value === "string" ? sanitizeProviderCode(value) : null;
+}
+function providerErrorResponse(body, httpStatus) {
+    const providerErrorMessage = providerErrorFromBody(body, httpStatus);
+    const providerErrorCode = providerErrorCodeFromBody(body);
+    return {
+        http_status: httpStatus,
+        provider_error_message: providerErrorMessage,
+        ...(providerErrorCode ? { provider_error_code: providerErrorCode } : {}),
+    };
+}
+async function postResendEmail(input, context, environmentTagName, fetcher) {
+    const headers = {
+        Authorization: `Bearer ${context.credential}`,
+        "Content-Type": "application/json",
+    };
+    if (input.idempotencyKey !== undefined)
+        headers["Idempotency-Key"] = input.idempotencyKey;
+    if (context.mode === "sandbox_sink")
+        headers["X-Original-Recipient"] = context.intendedRecipient;
+    try {
+        const res = await fetcher(RESEND_ENDPOINT, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                from: input.from,
+                to: [context.recipient],
+                subject: input.subject,
+                html: input.html,
+                ...(input.text === undefined ? {} : { text: input.text }),
+                ...(input.replyTo === undefined ? {} : { reply_to: input.replyTo }),
+                ...(input.attachments === undefined ? {} : { attachments: input.attachments }),
+                tags: [{
+                        name: environmentTagName,
+                        value: context.environmentTag,
+                    }],
+            }),
+            signal: input.signal,
+        });
+        const parsed = await res.json().catch(() => ({}));
+        const body = typeof parsed === "object" && parsed !== null
+            ? parsed
+            : {};
+        if (!res.ok) {
+            const providerErrorMessage = providerErrorFromBody(body, res.status);
+            const providerErrorCode = providerErrorCodeFromBody(body);
+            return {
+                outcome: {
+                    ok: false,
+                    resendId: null,
+                    httpStatus: res.status,
+                    providerError: providerErrorMessage,
+                    providerErrorCode,
+                    aborted: false,
+                    egressMode: context.mode,
+                    egressReason: context.reason,
+                },
+                providerResponse: providerErrorResponse(body, res.status),
+            };
+        }
+        const id = typeof body.id === "string" ? body.id : null;
+        return {
+            outcome: {
+                ok: true,
+                resendId: id,
+                httpStatus: res.status,
+                providerError: null,
+                aborted: false,
+                egressMode: context.mode,
+                egressReason: context.reason,
+            },
+            providerResponse: { id },
+        };
+    }
+    catch (err) {
+        const aborted = input.signal?.aborted === true ||
+            (err instanceof Error && err.name === "AbortError");
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            outcome: {
+                ok: false,
+                resendId: null,
+                httpStatus: 0,
+                providerError: sanitizeProviderText(msg),
+                aborted,
+                egressMode: context.mode,
+                egressReason: context.reason,
+            },
+            providerResponse: { exception: true, aborted },
+        };
+    }
+}
+function readFirstRecipient(value) {
+    if (typeof value === "string" && value.includes("@"))
+        return value;
+    if (!Array.isArray(value))
+        return null;
+    return value.find((recipient) => typeof recipient === "string" && recipient.includes("@")) ?? null;
+}
+// Read-only status retrieval for the delivery reconciliation poller
+// (docs/platform/RUNTIME_AND_SELF_HOSTING.md Wave 4). No egress gating needed: this never
+// sends mail — it only reads the provider's view of an already-sent message.
+async function getResendEmail(input, fetcher) {
+    try {
+        const res = await fetcher(`${RESEND_ENDPOINT}/${encodeURIComponent(input.resendId)}`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${input.apiKey}` },
+            signal: input.signal,
+        });
+        const parsed = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            return {
+                ok: false,
+                httpStatus: res.status,
+                lastEvent: null,
+                recipientEmail: null,
+                providerError: providerErrorFromBody(parsed, res.status),
+            };
+        }
+        const lastEvent = typeof parsed.last_event === "string" ? parsed.last_event : null;
+        return {
+            ok: true,
+            httpStatus: res.status,
+            lastEvent,
+            recipientEmail: readFirstRecipient(parsed.to),
+            providerError: null,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            httpStatus: 0,
+            lastEvent: null,
+            recipientEmail: null,
+            providerError: error instanceof Error ? sanitizeProviderCode(error.message) : "fetch_failed",
+        };
+    }
+}
+/** Poll existing IDs through the neutral runner; never retries a send. */
+export function runResendDeliveryReconciliation(input) {
+    return runDeliveryReconciliation({
+        port: input.port, now: input.now, graceMinutes: input.graceMinutes, limit: input.limit,
+        readEmail: messageId => getResendEmail({ apiKey: input.apiKey, resendId: messageId, signal: input.signal }, input.fetch ?? fetch),
+        observationFor: read => {
+            const status = read.lastEvent;
+            if (!status || !["delivered", "delivery_delayed", "bounced", "complained", "failed"].includes(status))
+                return null;
+            return { eventType: `email.${status}`, terminal: ["bounced", "complained", "failed"].includes(status) };
+        },
+    });
+}
+const eventKinds = new Map([
+    ["email.sent", "sent"], ["email.delivered", "delivered"], ["email.delivery_delayed", "delivery_delayed"],
+    ["email.opened", "open"], ["email.clicked", "click"], ["email.bounced", "bounce"],
+    ["email.complained", "complaint"], ["email.failed", "failed"], ["email.suppressed", "suppressed"], ["email.scheduled", "scheduled"],
+]);
+/** Authenticate untouched bytes before decoding. now returns UTC seconds; receiver defaults to non-production. */
+export function createResendWebhookHandler(input) {
+    return async (request) => {
+        if (request.method === "OPTIONS")
+            return { status: 200, body: "ok" };
+        if (!verifyResendWebhookSignature({ ...request.headers, rawBody: request.rawBody, secret: input.webhookSecret, now: input.now })) {
+            return { status: 401, body: { error: "Invalid signature" } };
+        }
+        try {
+            const payload = JSON.parse(typeof request.rawBody === "string" ? request.rawBody : Buffer.from(request.rawBody).toString("utf8"));
+            const type = isRecord(payload) ? payload.type : null;
+            const data = isRecord(payload) ? payload.data : null;
+            if (typeof type !== "string" || !eventKinds.has(type))
+                return { status: 200, body: { ignored: true } };
+            const messageId = isRecord(data) && typeof data.email_id === "string" ? data.email_id : null;
+            if (!messageId)
+                return { status: 200, body: { ignored: true, reason: "missing_email_id" } };
+            const tag = readEnvironmentTag(data, input.environmentTagName);
+            if (tag && tag !== (input.resolveReceiverEnvironmentTag?.() ?? "non_production")) {
+                return { status: 200, body: { ignored: true, reason: "foreign_send_not_found" } };
+            }
+            const disposition = await processEmailObservation({
+                port: input.port, messageId,
+                observation: () => {
+                    const time = resolveEventTime(isRecord(payload) ? payload.created_at : null, request.headers.timestamp, input.receivedAt?.() ?? new Date());
+                    return { eventType: type, eventAt: time.eventAt, metadata: {
+                            providerEventId: request.headers.webhookId ?? null, eventMetadata: data ?? {},
+                            link: isRecord(data) && isRecord(data.click) && typeof data.click.link === "string" ? data.click.link : null,
+                            source: "resend-webhook", eventTimeSource: time.source,
+                        } };
+                },
+            });
+            return disposition.outcome === "send_not_found"
+                ? { status: 200, body: { ignored: true, reason: "send_not_found" } }
+                : { status: 200, body: { success: true } };
+        }
+        catch {
+            return { status: 500, body: { error: "Webhook processing failed" } };
+        }
+    };
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function readEnvironmentTag(data, tagName) {
+    if (!isRecord(data))
+        return null;
+    const tags = data.tags;
+    const value = Array.isArray(tags)
+        ? tags.find(entry => isRecord(entry) && entry.name === tagName)?.value
+        : isRecord(tags) ? tags[tagName] : null;
+    return value === "production" || value === "non_production" ? value : null;
+}
+function resolveEventTime(createdAt, timestamp, receivedAt) {
+    if (typeof createdAt === "string" && Number.isFinite(Date.parse(createdAt))) {
+        return { eventAt: new Date(createdAt).toISOString(), source: "provider_created_at" };
+    }
+    const seconds = Number(timestamp);
+    if (Number.isFinite(seconds) && seconds > 0)
+        return { eventAt: new Date(seconds * 1000).toISOString(), source: "svix_timestamp" };
+    return { eventAt: receivedAt.toISOString(), source: "received_at" };
+}
+function verifyResendWebhookSignature(input) {
+    const { webhookId, timestamp, signature, rawBody, secret } = input;
+    if (!webhookId || !timestamp || !signature || !secret)
+        return false;
+    const timestampSeconds = Number(timestamp);
+    if (!Number.isFinite(timestampSeconds))
+        return false;
+    const now = input.now ?? (() => Math.floor(Date.now() / 1000));
+    if (Math.abs(now() - timestampSeconds) > 300)
+        return false;
+    const secretKey = signingSecret(secret);
+    if (secretKey === null)
+        return false;
+    const expected = createHmac("sha256", secretKey)
+        .update(`${webhookId}.${timestamp}.`).update(rawBody)
+        .digest("base64");
+    return signature.split(" ").some((member) => timingSafeStringEqual(member, `v1,${expected}`) || timingSafeStringEqual(member, expected));
+}
+function signingSecret(secret) {
+    if (!secret.startsWith("whsec_"))
+        return secret;
+    // Svix encodes endpoint secrets after the whsec_ prefix. Buffer preserves the
+    // decoded bytes for node:crypto rather than treating the base64 text as a key.
+    // Buffer.from(base64) is deliberately permissive, so reject empty, malformed,
+    // or non-canonical input before it can silently become an empty/partial key.
+    const encoded = secret.slice("whsec_".length);
+    if (!encoded || !/^[A-Za-z0-9+/]+={0,2}$/.test(encoded) || encoded.length % 4 === 1)
+        return null;
+    const decoded = Buffer.from(encoded, "base64");
+    if (decoded.length === 0)
+        return null;
+    const canonicalPadded = decoded.toString("base64");
+    const canonicalUnpadded = canonicalPadded.replace(/=+$/, "");
+    return encoded === canonicalPadded || encoded === canonicalUnpadded ? decoded : null;
+}
+function timingSafeStringEqual(left, right) {
+    const leftBuffer = Buffer.from(left);
+    const rightBuffer = Buffer.from(right);
+    return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}

package/dist/communications/shipmentNotifications.d.ts

@@ -0,0 +1,34 @@
+import { z } from "./validation.js";
+export declare const shipmentNotificationEventSchema: z.ZodObject<{
+    orderId: z.ZodGUID;
+    clientId: z.ZodGUID;
+    status: z.ZodEnum<{
+        delivered: "delivered";
+        exception: "exception";
+        dispatched: "dispatched";
+        shipped: "shipped";
+    }>;
+    trackingNumbers: z.ZodArray<z.ZodString>;
+    trackingReferences: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        providerKind: z.ZodString;
+        carrierKind: z.ZodNullable<z.ZodString>;
+        service: z.ZodNullable<z.ZodString>;
+        trackingNumber: z.ZodString;
+        trackingUrl: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>>;
+    trackingUrl: z.ZodNullable<z.ZodString>;
+    occurredAt: z.ZodString;
+}, z.core.$strict>;
+export declare const shipmentNotificationPlanSchema: z.ZodObject<{
+    templateSlug: z.ZodEnum<{
+        "commerce-shipment-dispatched": "commerce-shipment-dispatched";
+        "commerce-shipment-delivered": "commerce-shipment-delivered";
+        "commerce-shipment-exception": "commerce-shipment-exception";
+    }>;
+    source: z.ZodLiteral<"shipment-status">;
+    idempotencyKey: z.ZodString;
+    shouldNotifyCustomer: z.ZodBoolean;
+}, z.core.$strict>;
+export declare function planShipmentNotification(event: ShipmentNotificationEvent): ShipmentNotificationPlan;
+export type ShipmentNotificationEvent = z.infer<typeof shipmentNotificationEventSchema>;
+export type ShipmentNotificationPlan = z.infer<typeof shipmentNotificationPlanSchema>;