@openlup/platform 0.26.0 → 0.28.0

package/dist/commerce/server/outboxDispatchRegistry.js

@@ -0,0 +1,184 @@
+import { composeOutboxHandlerDescriptors, assertOutboxRegistryDescriptors } from "./outboxDispatchRegistryComposition.js";
+import { createOutboxOrderDraftEmailHandler, outboxOrderDraftEmailDescriptor } from "./outboxOrderDraftEmailHandler.js";
+import { createOutboxCheckoutRecoveryEmailHandler, outboxCheckoutRecoveryEmailDescriptor } from "./outboxCheckoutRecoveryEmailHandler.js";
+import { createOutboxOrderPaidEmailHandler, outboxOrderPaidEmailDescriptor, } from "./outboxOrderPaidEmailHandler.js";
+import { createOutboxPaymentFailedEmailHandler, outboxPaymentFailedEmailDescriptor } from "./outboxPaymentFailedEmailHandler.js";
+import { createOutboxCheckoutExpiredEmailHandler, outboxCheckoutExpiredEmailDescriptor } from "./outboxCheckoutExpiredEmailHandler.js";
+import { createOutboxOrderRefundedEmailHandler, outboxOrderRefundedEmailDescriptor } from "./outboxOrderRefundedEmailHandler.js";
+import { createOutboxShipmentDispatchedEmailHandler, outboxShipmentDispatchedEmailDescriptor } from "./outboxShipmentDispatchedEmailHandler.js";
+import { createOutboxShipmentDeliveredEmailHandler, outboxShipmentDeliveredEmailDescriptor, } from "./outboxShipmentDeliveredEmailHandler.js";
+import { createOutboxShipmentExceptionEmailHandler, outboxShipmentExceptionEmailDescriptor } from "./outboxShipmentExceptionEmailHandler.js";
+import { createOutboxReturnApprovedEmailHandler, outboxReturnApprovedEmailDescriptor, createOutboxReturnRejectedEmailHandler, outboxReturnRejectedEmailDescriptor, } from "./outboxReturnEmailHandlers.js";
+import { createOutboxOrderPaidFulfillmentHandler, outboxOrderPaidFulfillmentDescriptor, } from "./outboxOrderPaidFulfillmentHandler.js";
+import { platformOwnsBuyerEmail, } from "../salesChannelEnvelope.js";
+function readOrderUuid(payload) {
+    const value = payload.orderUuid;
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+ * Wraps ONE buyer-facing email handler so a channel that owns buyer
+ * communication does not also get ours.
+ *
+ * WHY THE WRAPPER IS AT THE HANDLER AND NOT AT THE TRIGGER. The checkout email
+ * reconciler (`commerce_reconcile_checkout_email_outbox`) back-fills a `commerce.order.paid.email`
+ * row for EVERY order that reads `paid` and has none, keyed only on the order
+ * id — it does not look at `source_kind`, and outboxDispatchRuntime runs it
+ * inline immediately before the dispatch worker in the same invocation. A
+ * trigger-level or emitter-level suppression would therefore be undone on the
+ * very next reconcile pass, silently, and the buyer would get the email anyway.
+ * The dispatcher is the last place that can still decide.
+ *
+ * Recorded as `processed` rather than `discard` so the event settles once and
+ * never retries. `skipped` is one of the DELIVERY_LIFECYCLE_METADATA_KEYS below,
+ * so the email-delivery lifecycle trigger reads the suppression as a skip with a
+ * reason instead of leaving a delivery hanging — the same shape the
+ * carrier-owned delivered notice already uses.
+ */
+function suppressForChannel(handler, reader) {
+    if (!reader)
+        return handler;
+    return {
+        eventType: handler.eventType,
+        timeoutMs: handler.timeoutMs,
+        async handle(row, signal, execution) {
+            const orderUuid = readOrderUuid(row.payload);
+            // A payload with no usable order id is not a policy question. Hand it to
+            // the handler, whose own contract parse produces the right discard rather
+            // than this wrapper inventing a second failure mode for the same row.
+            if (orderUuid !== null) {
+                const policy = await reader.readOrderBuyerCommsPolicy(orderUuid);
+                if (!platformOwnsBuyerEmail(policy)) {
+                    return { kind: "processed", detail: { skipped: "channel_owns_buyer_comms" } };
+                }
+            }
+            return handler.handle(row, signal, execution);
+        },
+    };
+}
+export function describeCoreOutboxHandlers(selection) {
+    return [
+        ...(selection.transactionalEmail ? [
+            outboxOrderDraftEmailDescriptor, outboxCheckoutRecoveryEmailDescriptor,
+            outboxOrderPaidEmailDescriptor, outboxPaymentFailedEmailDescriptor,
+            outboxCheckoutExpiredEmailDescriptor, outboxOrderRefundedEmailDescriptor,
+            outboxShipmentDispatchedEmailDescriptor, outboxShipmentDeliveredEmailDescriptor,
+            outboxShipmentExceptionEmailDescriptor, outboxReturnApprovedEmailDescriptor,
+            outboxReturnRejectedEmailDescriptor,
+        ] : []),
+        ...(selection.fulfillmentEnabled ? [outboxOrderPaidFulfillmentDescriptor] : []),
+    ];
+}
+export function createOutboxDispatchRegistry(deps) {
+    // Applied to the buyer-facing set below. The four email handlers it is NOT
+    // applied to are structurally unreachable for a channel order on the ingest
+    // path this repository ships, and each is asserted rather than assumed:
+    //   - order-draft-created: emitted INSIDE `commerce_create_order_draft`.
+    //     `commerce_create_channel_order` writes the order header directly and
+    //     emits `channel.order.ingested`, so no draft event ever exists.
+    //   - checkout-recovery: minted from an expired-checkout recovery token, which
+    //     only the checkout-expiry path can create.
+    //   - checkout-expired and payment-failed: both key off a one-time order
+    //     reaching status `expired`/`failed`, and the ONLY writer of those statuses
+    //     for a one-time order is `commerce_payment_apply_result`. The ingest saga
+    //     calls `applySucceeded` and nothing else — the marketplace collected the
+    //     money before the order existed here, so there is no decline or session to
+    //     expire. Nothing sweeps a stale `draft` order to `expired` either.
+    // This is an argument about the CURRENT ingest path. A later wave that gives a
+    // channel order a decline or expiry rail must revisit this list, not assume it.
+    //
+    // `commerce.order.canceled` is absent from this enumeration because its email
+    // handler (outboxOrderCanceledEmailHandler.ts) is registered by NOTHING — the
+    // only claimant of that event type is the accounting reversal handler, which
+    // arrives through `extraHandlers` and must keep running for a channel order.
+    // Wrapping a handler this registry does not compose would be theatre; if that
+    // email is ever wired up, it belongs in the wrapped set.
+    const suppress = (handler) => suppressForChannel(handler, deps.transactionalEmail?.buyerCommsPolicyReader);
+    const handlers = [
+        ...(deps.transactionalEmail
+            ? [
+                createOutboxOrderDraftEmailHandler({
+                    runtime: deps.transactionalEmail.runtime,
+                    emailPort: deps.transactionalEmail.emailPort,
+                    recipientPort: deps.transactionalEmail.recipientPort,
+                    lifecyclePort: deps.transactionalEmail.lifecyclePort,
+                }),
+                createOutboxCheckoutRecoveryEmailHandler({
+                    runtime: deps.transactionalEmail.runtime,
+                    emailPort: deps.transactionalEmail.emailPort,
+                    recipientPort: deps.transactionalEmail.recipientPort,
+                    lifecyclePort: deps.transactionalEmail.lifecyclePort,
+                }),
+                suppress(createOutboxOrderPaidEmailHandler({
+                    runtime: deps.transactionalEmail.runtime,
+                    emailPort: deps.transactionalEmail.emailPort,
+                    recipientPort: deps.transactionalEmail.recipientPort,
+                    linesPort: deps.transactionalEmail.orderPaidLinesPort,
+                    describeParcel: deps.transactionalEmail.orderPaidParcelNote,
+                })),
+                createOutboxPaymentFailedEmailHandler({
+                    runtime: deps.transactionalEmail.runtime,
+                    emailPort: deps.transactionalEmail.emailPort,
+                    recipientPort: deps.transactionalEmail.recipientPort,
+                    lifecyclePort: deps.transactionalEmail.lifecyclePort,
+                }),
+                createOutboxCheckoutExpiredEmailHandler({
+                    runtime: deps.transactionalEmail.runtime,
+                    emailPort: deps.transactionalEmail.emailPort,
+                    recipientPort: deps.transactionalEmail.recipientPort,
+                    lifecyclePort: deps.transactionalEmail.lifecyclePort,
+                }),
+                suppress(createOutboxOrderRefundedEmailHandler({
+                    runtime: deps.transactionalEmail.runtime,
+                    emailPort: deps.transactionalEmail.emailPort,
+                    recipientPort: deps.transactionalEmail.recipientPort,
+                })),
+                suppress(createOutboxShipmentDispatchedEmailHandler({
+                    runtime: deps.transactionalEmail.runtime,
+                    emailPort: deps.transactionalEmail.emailPort,
+                    recipientPort: deps.transactionalEmail.recipientPort,
+                })),
+                suppress(createOutboxShipmentDeliveredEmailHandler({
+                    runtime: deps.transactionalEmail.runtime,
+                    emailPort: deps.transactionalEmail.emailPort,
+                    recipientPort: deps.transactionalEmail.recipientPort,
+                    providerKindReader: deps.transactionalEmail.deliveredProviderKindReader,
+                })),
+                suppress(createOutboxShipmentExceptionEmailHandler({
+                    runtime: deps.transactionalEmail.runtime,
+                    emailPort: deps.transactionalEmail.emailPort,
+                    recipientPort: deps.transactionalEmail.recipientPort,
+                })),
+                suppress(createOutboxReturnApprovedEmailHandler({
+                    runtime: deps.transactionalEmail.runtime,
+                    emailPort: deps.transactionalEmail.emailPort,
+                    recipientPort: deps.transactionalEmail.recipientPort,
+                })),
+                suppress(createOutboxReturnRejectedEmailHandler({
+                    runtime: deps.transactionalEmail.runtime,
+                    emailPort: deps.transactionalEmail.emailPort,
+                    recipientPort: deps.transactionalEmail.recipientPort,
+                })),
+            ]
+            : []),
+        ...(deps.fulfillmentEnabled && deps.fulfillmentPort
+            ? [
+                createOutboxOrderPaidFulfillmentHandler({
+                    fulfillmentPort: deps.fulfillmentPort,
+                    riskPort: deps.riskPort,
+                    isRiskEnabled: () => deps.riskEnabled === true,
+                }),
+            ]
+            : []),
+        ...(deps.extraHandlers ?? []),
+    ];
+    const registry = deps.uniqueRegistry(handlers);
+    const expected = deps.expectedDescriptors?.() ?? composeOutboxHandlerDescriptors([
+        ...describeCoreOutboxHandlers({
+            transactionalEmail: Boolean(deps.transactionalEmail),
+            fulfillmentEnabled: deps.fulfillmentEnabled && Boolean(deps.fulfillmentPort),
+        }),
+        ...(deps.extraHandlers ?? []).map(({ eventType, timeoutMs }) => ({ eventType, timeoutMs })),
+    ]);
+    assertOutboxRegistryDescriptors(registry, expected);
+    return registry;
+}

package/dist/commerce/server/outboxDispatchRegistryComposition.d.ts

@@ -0,0 +1,6 @@
+import type { OutboxHandlerDescriptor } from "@openlup/core/outbox";
+import type { OutboxHandlerRegistry } from "../outboxDispatchContracts.js";
+/** Preserve native registration order and the timeout sum of same-event handlers. */
+export declare function composeOutboxHandlerDescriptors(handlers: readonly OutboxHandlerDescriptor[]): OutboxHandlerDescriptor[];
+/** Refuse a different claim surface before a worker can call claimBatch. */
+export declare function assertOutboxRegistryDescriptors(registry: OutboxHandlerRegistry, expected: readonly OutboxHandlerDescriptor[]): void;

package/dist/commerce/server/outboxDispatchRegistryComposition.js

@@ -0,0 +1,23 @@
+/** Preserve native registration order and the timeout sum of same-event handlers. */
+export function composeOutboxHandlerDescriptors(handlers) {
+    const descriptors = new Map();
+    for (const handler of handlers) {
+        const existing = descriptors.get(handler.eventType);
+        descriptors.set(handler.eventType, {
+            eventType: handler.eventType,
+            timeoutMs: (existing?.timeoutMs ?? 0) + handler.timeoutMs,
+        });
+    }
+    return [...descriptors.values()];
+}
+/** Refuse a different claim surface before a worker can call claimBatch. */
+export function assertOutboxRegistryDescriptors(registry, expected) {
+    const actual = [...registry.entries()];
+    if (actual.length !== expected.length || actual.some(([key, handler], index) => {
+        const descriptor = expected[index];
+        return key !== descriptor.eventType || handler.eventType !== key
+            || handler.timeoutMs !== descriptor.timeoutMs
+            || !Number.isFinite(handler.timeoutMs) || handler.timeoutMs <= 0;
+    }))
+        throw new Error("outbox_registry_descriptor_mismatch");
+}

package/dist/commerce/server/outboxOrderDraftEmailHandler.d.ts

@@ -0,0 +1,14 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import type { OutboxHandler } from "../outboxDispatchContracts.js";
+import { OUTBOX_ORDER_CONFIRMATION_TEMPLATE_SLUG, type OrderPaymentLifecyclePort, type OrderRecipientPort, type TransactionalEmailPort } from "../outboxOrderDraftEmailPorts.js";
+export { OUTBOX_ORDER_CONFIRMATION_TEMPLATE_SLUG };
+export declare const outboxOrderDraftEmailDescriptor: Readonly<{
+    eventType: "commerce.order_draft.created";
+    timeoutMs: 10000;
+}>;
+export declare function createOutboxOrderDraftEmailHandler<Locale extends string>(deps: {
+    runtime: Pick<CommerceEmailRuntime<Locale>, "formatMoney" | "genericItemLabel" | "mapSendOutcome" | "parseOutboxPayload" | "resolveLocale">;
+    emailPort: TransactionalEmailPort<Locale>;
+    recipientPort: OrderRecipientPort;
+    lifecyclePort: OrderPaymentLifecyclePort;
+}): OutboxHandler;

package/dist/commerce/server/outboxOrderDraftEmailHandler.js

@@ -0,0 +1,130 @@
+import { z } from "zod";
+import { COMMERCE_ORDER_DRAFT_CREATED_EVENT_TYPE } from "../outboxEventSchemas.js";
+import { OUTBOX_ORDER_CONFIRMATION_TEMPLATE_SLUG, } from "../outboxOrderDraftEmailPorts.js";
+import { buildItems } from "../orderEmailLines.js";
+import { shouldSkipOrderDraftConfirmation } from "../orderEmailEligibility.js";
+export { OUTBOX_ORDER_CONFIRMATION_TEMPLATE_SLUG };
+const HANDLER_TIMEOUT_MS = 10_000;
+export const outboxOrderDraftEmailDescriptor = Object.freeze({
+    eventType: COMMERCE_ORDER_DRAFT_CREATED_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+// Frozen minimal parse (challenge R-m5): validate ONLY the fields this handler
+// consumes, with schemas owned HERE — never the live quote/order-draft zod
+// schemas. A producer-side schema deploy must not retro-DLQ in-flight events.
+// Everything except orderUuid/orderId is optional-tolerant: malformed lines or
+// totals degrade the email content, they never fail the event.
+const payloadSubsetSchema = z
+    .object({
+    orderUuid: z.guid(),
+    orderId: z.string().min(1),
+    orderDraftSnapshot: z.unknown().optional(),
+})
+    .passthrough();
+const moneySubsetSchema = z
+    .object({
+    amountMinor: z.number().int().nonnegative(),
+    currency: z.string().trim().min(1),
+})
+    .passthrough();
+const lineSubsetSchema = z
+    .object({
+    quantity: z.number().int().positive(),
+    productSlug: z.string().trim().min(1).optional(),
+    sku: z.string().trim().min(1).optional(),
+    lineSubtotalGross: moneySubsetSchema.optional(),
+})
+    .passthrough();
+const snapshotSubsetSchema = z
+    .object({
+    lines: z.array(z.unknown()).optional(),
+    totals: z
+        .object({
+        subtotalGross: z.unknown().optional(),
+        discountTotalGross: z.unknown().optional(),
+        totalGross: z.unknown().optional(),
+    })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+function extractLines(snapshot) {
+    const parsed = snapshotSubsetSchema.safeParse(snapshot);
+    if (!parsed.success || parsed.data.lines === undefined)
+        return [];
+    const lines = [];
+    for (const candidate of parsed.data.lines) {
+        const line = lineSubsetSchema.safeParse(candidate);
+        if (!line.success)
+            continue;
+        if (line.data.productSlug === undefined && line.data.sku === undefined)
+            continue;
+        lines.push({
+            label: null,
+            quantity: line.data.quantity,
+            lineSubtotalMinor: line.data.lineSubtotalGross?.amountMinor ?? null,
+            currency: line.data.lineSubtotalGross?.currency ?? null,
+        });
+    }
+    return lines;
+}
+function buildTotals(snapshot, runtime) {
+    const parsed = snapshotSubsetSchema.safeParse(snapshot);
+    if (!parsed.success || parsed.data.totals === undefined)
+        return null;
+    const total = moneySubsetSchema.safeParse(parsed.data.totals.totalGross);
+    if (!total.success)
+        return null;
+    const subtotal = moneySubsetSchema.safeParse(parsed.data.totals.subtotalGross);
+    const discount = moneySubsetSchema.safeParse(parsed.data.totals.discountTotalGross);
+    const currency = total.data.currency;
+    return {
+        // Omit the subtotal row when it cannot be parsed — do NOT fall back to the
+        // grand total, which would render "Subtotal = Total" alongside a separate
+        // discount line that no longer reconciles.
+        subtotalLabel: subtotal.success
+            ? runtime.formatMoney(subtotal.data.amountMinor, subtotal.data.currency)
+            : null,
+        discountLabel: discount.success && discount.data.amountMinor > 0
+            ? `-${runtime.formatMoney(discount.data.amountMinor, discount.data.currency)}`
+            : null,
+        totalLabel: runtime.formatMoney(total.data.amountMinor, currency),
+    };
+}
+export function createOutboxOrderDraftEmailHandler(deps) {
+    return {
+        ...outboxOrderDraftEmailDescriptor,
+        async handle(row, signal) {
+            const parsed = deps.runtime.parseOutboxPayload(payloadSubsetSchema, row.payload);
+            if (parsed.ok === false) {
+                return parsed.outcome;
+            }
+            const lifecycle = await deps.lifecyclePort.read(parsed.data.orderUuid, signal);
+            const skipReason = shouldSkipOrderDraftConfirmation(lifecycle);
+            if (skipReason) {
+                return { kind: "processed", detail: { skipped: skipReason } };
+            }
+            const recipient = await deps.recipientPort.resolve(parsed.data.orderUuid, signal);
+            if (recipient === null) {
+                return { kind: "processed", detail: { skipped: "recipient_unresolved" } };
+            }
+            const alreadySent = await deps.emailPort.findExistingSend(OUTBOX_ORDER_CONFIRMATION_TEMPLATE_SLUG, row.id);
+            if (alreadySent) {
+                return { kind: "processed", detail: { dedupe: "email_already_sent" } };
+            }
+            const lines = extractLines(parsed.data.orderDraftSnapshot);
+            const locale = deps.runtime.resolveLocale(recipient.country ?? null);
+            const outcome = await deps.emailPort.sendOrderConfirmation({
+                to: recipient.email,
+                firstName: recipient.firstName,
+                contextName: recipient.contextName ?? null,
+                orderId: parsed.data.orderId,
+                outboxEventId: row.id,
+                items: buildItems(lines, locale, deps.runtime),
+                totals: buildTotals(parsed.data.orderDraftSnapshot, deps.runtime),
+                locale,
+                signal,
+            });
+            return deps.runtime.mapSendOutcome(outcome);
+        },
+    };
+}

package/dist/commerce/server/outboxOrderPaidEmailHandler.d.ts

@@ -0,0 +1,21 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import type { OutboxHandler } from "../outboxDispatchContracts.js";
+import { OUTBOX_ORDER_PAID_TEMPLATE_SLUG, type OrderPaidLinesPort, type OrderRecipientPort, type TransactionalEmailPort } from "../outboxOrderDraftEmailPorts.js";
+export { OUTBOX_ORDER_PAID_TEMPLATE_SLUG };
+export declare const outboxOrderPaidEmailDescriptor: Readonly<{
+    eventType: "commerce.order.paid.email";
+    timeoutMs: 10000;
+}>;
+/**
+ * An adopter's note about the paid order's parcel, already localized, or null
+ * for none. Best-effort and inside this handler's timeout: a failure is logged
+ * and the receipt is sent without the note.
+ */
+export type OrderPaidParcelNoteReader<Locale extends string = string> = (orderUuid: string, locale: Locale, signal: AbortSignal) => Promise<string | null>;
+export declare function createOutboxOrderPaidEmailHandler<Locale extends string>(deps: {
+    runtime: Pick<CommerceEmailRuntime<Locale>, "formatMoney" | "genericItemLabel" | "mapSendOutcome" | "parseOutboxPayload" | "presentPaidOrder" | "resolveLocale">;
+    emailPort: TransactionalEmailPort<Locale>;
+    recipientPort: OrderRecipientPort;
+    linesPort: OrderPaidLinesPort;
+    describeParcel?: OrderPaidParcelNoteReader<Locale>;
+}): OutboxHandler;

package/dist/commerce/server/outboxOrderPaidEmailHandler.js

@@ -0,0 +1,93 @@
+import { z } from "zod";
+import { COMMERCE_ORDER_PAID_EMAIL_EVENT_TYPE } from "../outboxEventSchemas.js";
+import { OUTBOX_ORDER_PAID_TEMPLATE_SLUG, } from "../outboxOrderDraftEmailPorts.js";
+import { buildItems } from "../orderEmailLines.js";
+export { OUTBOX_ORDER_PAID_TEMPLATE_SLUG };
+const HANDLER_TIMEOUT_MS = 10_000;
+export const outboxOrderPaidEmailDescriptor = Object.freeze({
+    eventType: COMMERCE_ORDER_PAID_EMAIL_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+// Frozen minimal parse (mirror the order-draft handler): validate ONLY what this
+// handler consumes; a producer schema change must never retro-DLQ in-flight rows.
+const payloadSubsetSchema = z
+    .object({
+    orderUuid: z.guid(),
+    orderId: z.string().min(1),
+    mode: z.string().min(1).optional(),
+})
+    .passthrough();
+function totalsFrom(data, runtime) {
+    return {
+        subtotalLabel: runtime.formatMoney(data.subtotalMinor, data.currency),
+        discountLabel: data.discountMinor > 0 ? `−${runtime.formatMoney(data.discountMinor, data.currency)}` : null,
+        totalLabel: runtime.formatMoney(data.totalMinor, data.currency),
+    };
+}
+export function createOutboxOrderPaidEmailHandler(deps) {
+    return {
+        ...outboxOrderPaidEmailDescriptor,
+        async handle(row, signal) {
+            const parsed = deps.runtime.parseOutboxPayload(payloadSubsetSchema, row.payload);
+            if (parsed.ok === false) {
+                return parsed.outcome;
+            }
+            // Dedupe FIRST (cheap, recipient-independent): an already-sent event must not
+            // burn the recipient + lines reads (4 queries) on every reprocess/retry/preview
+            // drain — those passes were pure waste on the dupe path.
+            const alreadySent = await deps.emailPort.findExistingSend(OUTBOX_ORDER_PAID_TEMPLATE_SLUG, row.id);
+            if (alreadySent) {
+                return { kind: "processed", detail: { dedupe: "email_already_sent" } };
+            }
+            const recipient = await deps.recipientPort.resolve(parsed.data.orderUuid, signal);
+            if (recipient === null) {
+                return { kind: "processed", detail: { skipped: "recipient_unresolved" } };
+            }
+            // Items + totals from the DB. A genuine read error throws → worker retries.
+            // A missing order row means the paid order is not yet readable (replication
+            // lag): retry rather than send a contentless "receipt" with no items/totals.
+            const data = await deps.linesPort.read(parsed.data.orderUuid, signal);
+            if (data === null) {
+                return { kind: "retry", reason: "order_paid_data_unavailable" };
+            }
+            const presentation = deps.runtime.presentPaidOrder(data);
+            const rawLines = (data.lines ?? []).map((line) => ({
+                label: line.label,
+                quantity: line.quantity,
+                lineSubtotalMinor: presentation ? null : line.lineTotalMinor,
+                currency: data.currency,
+            }));
+            const locale = deps.runtime.resolveLocale(recipient.country ?? null);
+            const parcelNote = await readParcelNote(deps.describeParcel, parsed.data.orderUuid, locale, signal, row.id);
+            const outcome = await deps.emailPort.sendOrderPaidConfirmation({
+                to: recipient.email,
+                firstName: recipient.firstName,
+                contextName: recipient.contextName ?? null,
+                orderId: parsed.data.orderId,
+                mode: parsed.data.mode ?? "one_time",
+                outboxEventId: row.id,
+                items: buildItems(rawLines, locale, deps.runtime),
+                totals: presentation ?? totalsFrom(data, deps.runtime),
+                ...(parcelNote ? { parcelNote } : {}),
+                locale,
+                signal,
+            });
+            return deps.runtime.mapSendOutcome(outcome);
+        },
+    };
+}
+/**
+ * Asks the composed reader, if any, for the receipt's parcel note. A missing
+ * reader, an empty answer or a failure all mean no note: a failure is logged
+ * with the event id only, and the receipt is sent without the note.
+ */
+async function readParcelNote(describeParcel, orderUuid, locale, signal, eventId) {
+    if (!describeParcel)
+        return null;
+    try {
+        return (await describeParcel(orderUuid, locale, signal)) || null;
+    }
+    catch {
+        console.warn("[outbox-dispatch] order_paid_parcel_note_unavailable", eventId);
+        return null;
+    }
+}

package/dist/commerce/server/outboxOrderPaidFulfillmentHandler.d.ts

@@ -0,0 +1,3 @@
+import { createOutboxOrderPaidFulfillmentHandler } from "../../fulfillment/index.js";
+export { createOutboxOrderPaidFulfillmentHandler, outboxOrderPaidFulfillmentDescriptor } from "../../fulfillment/index.js";
+export type OrderPaidRiskAssessmentPort = NonNullable<Parameters<typeof createOutboxOrderPaidFulfillmentHandler>[0]["riskPort"]>;

package/dist/commerce/server/outboxOrderPaidFulfillmentHandler.js

@@ -0,0 +1 @@
+export { createOutboxOrderPaidFulfillmentHandler, outboxOrderPaidFulfillmentDescriptor } from "../../fulfillment/index.js";

package/dist/commerce/server/outboxOrderPaidFulfillmentPorts.d.ts

@@ -0,0 +1,3 @@
+import type { createOutboxOrderPaidFulfillmentHandler } from "../../fulfillment/index.js";
+export type OrderPaidFulfillmentPort = Parameters<typeof createOutboxOrderPaidFulfillmentHandler>[0]["fulfillmentPort"];
+export type OrderPaidFulfillmentResult = Awaited<ReturnType<OrderPaidFulfillmentPort["ensureFulfilledFromPaidOrder"]>>;

package/dist/commerce/server/outboxOrderPaidFulfillmentPorts.js

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

package/dist/commerce/server/outboxOrderRefundedEmailHandler.d.ts

@@ -0,0 +1,13 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import type { OutboxHandler } from "../outboxDispatchContracts.js";
+import { OUTBOX_ORDER_REFUNDED_TEMPLATE_SLUG, type OrderRecipientPort, type TransactionalEmailPort } from "../outboxOrderDraftEmailPorts.js";
+export { OUTBOX_ORDER_REFUNDED_TEMPLATE_SLUG };
+export declare const outboxOrderRefundedEmailDescriptor: Readonly<{
+    eventType: "commerce.order.refunded";
+    timeoutMs: 10000;
+}>;
+export declare function createOutboxOrderRefundedEmailHandler<Locale extends string>(deps: {
+    runtime: Pick<CommerceEmailRuntime<Locale>, "createTransactionalEmailHandler" | "formatMoney" | "resolveLocale">;
+    emailPort: TransactionalEmailPort<Locale>;
+    recipientPort: OrderRecipientPort;
+}): OutboxHandler;

package/dist/commerce/server/outboxOrderRefundedEmailHandler.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { COMMERCE_ORDER_REFUNDED_EVENT_TYPE } from "../outboxEventSchemas.js";
+import { OUTBOX_ORDER_REFUNDED_TEMPLATE_SLUG, } from "../outboxOrderDraftEmailPorts.js";
+export { OUTBOX_ORDER_REFUNDED_TEMPLATE_SLUG };
+const HANDLER_TIMEOUT_MS = 10_000;
+export const outboxOrderRefundedEmailDescriptor = Object.freeze({
+    eventType: COMMERCE_ORDER_REFUNDED_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+const payloadSubsetSchema = z
+    .object({
+    orderUuid: z.guid(),
+    orderId: z.string().min(1),
+    refundCents: z.number().int().nonnegative().optional(),
+    refundEvidenceVersion: z.string().optional(),
+    currency: z.string().trim().min(1).optional(),
+})
+    .passthrough();
+export function createOutboxOrderRefundedEmailHandler(deps) {
+    return deps.runtime.createTransactionalEmailHandler({
+        ...outboxOrderRefundedEmailDescriptor,
+        templateSlug: OUTBOX_ORDER_REFUNDED_TEMPLATE_SLUG,
+        schema: payloadSubsetSchema,
+        resolveKey: (payload) => payload.orderUuid,
+        recipientPort: deps.recipientPort,
+        findExistingSend: (slug, id) => deps.emailPort.findExistingSend(slug, id),
+        send: ({ payload, recipient, row, signal }) => {
+            const amountCents = payload.refundEvidenceVersion === "provider-refund.v2" ? payload.refundCents : undefined;
+            const amountLabel = amountCents !== undefined && payload.currency !== undefined
+                ? deps.runtime.formatMoney(amountCents, payload.currency)
+                : null;
+            return deps.emailPort.sendOrderRefundedNotice({
+                to: recipient.email,
+                firstName: recipient.firstName,
+                orderId: payload.orderId,
+                amountLabel,
+                outboxEventId: row.id,
+                locale: deps.runtime.resolveLocale(recipient.country ?? null),
+                signal,
+            });
+        },
+    });
+}

package/dist/commerce/server/outboxPaymentFailedEmailHandler.d.ts

@@ -0,0 +1,14 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import type { OutboxHandler } from "../outboxDispatchContracts.js";
+import { OUTBOX_PAYMENT_FAILED_TEMPLATE_SLUG, type OrderPaymentLifecyclePort, type OrderRecipientPort, type TransactionalEmailPort } from "../outboxOrderDraftEmailPorts.js";
+export { OUTBOX_PAYMENT_FAILED_TEMPLATE_SLUG };
+export declare const outboxPaymentFailedEmailDescriptor: Readonly<{
+    eventType: "commerce.payment.failed";
+    timeoutMs: 10000;
+}>;
+export declare function createOutboxPaymentFailedEmailHandler<Locale extends string>(deps: {
+    runtime: Pick<CommerceEmailRuntime<Locale>, "formatMoney" | "mapSendOutcome" | "parseOutboxPayload" | "resolveLocale">;
+    emailPort: TransactionalEmailPort<Locale>;
+    recipientPort: OrderRecipientPort;
+    lifecyclePort: OrderPaymentLifecyclePort;
+}): OutboxHandler;

package/dist/commerce/server/outboxPaymentFailedEmailHandler.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { COMMERCE_PAYMENT_FAILED_EVENT_TYPE } from "../outboxEventSchemas.js";
+import { OUTBOX_PAYMENT_FAILED_TEMPLATE_SLUG, } from "../outboxOrderDraftEmailPorts.js";
+import { shouldSkipPaymentFailedNotice } from "../orderEmailEligibility.js";
+export { OUTBOX_PAYMENT_FAILED_TEMPLATE_SLUG };
+const HANDLER_TIMEOUT_MS = 10_000;
+export const outboxPaymentFailedEmailDescriptor = Object.freeze({
+    eventType: COMMERCE_PAYMENT_FAILED_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+// Frozen minimal parse: only orderUuid/orderId are required; the amount fields
+// degrade the copy (no amount line) but never fail the event.
+const payloadSubsetSchema = z
+    .object({
+    orderUuid: z.guid(),
+    orderId: z.string().min(1),
+    recoveryToken: z.string().trim().min(1),
+    mode: z.string().optional(),
+    totalCents: z.number().int().nonnegative().optional(),
+    currency: z.string().trim().min(1).optional(),
+})
+    .passthrough();
+export function createOutboxPaymentFailedEmailHandler(deps) {
+    return {
+        ...outboxPaymentFailedEmailDescriptor,
+        async handle(row, signal, execution) {
+            const parsed = deps.runtime.parseOutboxPayload(payloadSubsetSchema, row.payload);
+            if (parsed.ok === false) {
+                return parsed.outcome;
+            }
+            execution?.setPhase("lifecycle");
+            const lifecycle = await deps.lifecyclePort.read(parsed.data.orderUuid, signal);
+            const skipReason = shouldSkipPaymentFailedNotice(lifecycle);
+            if (skipReason) {
+                return { kind: "processed", detail: { skipped: skipReason } };
+            }
+            execution?.setPhase("recipient");
+            const recipient = await deps.recipientPort.resolve(parsed.data.orderUuid, signal);
+            if (recipient === null) {
+                return { kind: "processed", detail: { skipped: "recipient_unresolved" } };
+            }
+            execution?.setPhase("dedupe");
+            const alreadySent = await deps.emailPort.findExistingSend(OUTBOX_PAYMENT_FAILED_TEMPLATE_SLUG, row.id);
+            if (alreadySent) {
+                return { kind: "processed", detail: { dedupe: "email_already_sent" } };
+            }
+            const payload = parsed.data;
+            const amountLabel = payload.totalCents !== undefined && payload.currency !== undefined
+                ? deps.runtime.formatMoney(payload.totalCents, payload.currency)
+                : null;
+            execution?.setPhase("email_send");
+            const outcome = await deps.emailPort.sendPaymentFailedNotice({
+                to: recipient.email,
+                firstName: recipient.firstName,
+                orderId: payload.orderId,
+                amountLabel,
+                recoveryToken: payload.recoveryToken,
+                mode: payload.mode ?? "one_time",
+                outboxEventId: row.id,
+                locale: deps.runtime.resolveLocale(recipient.country ?? null),
+                signal,
+            });
+            return deps.runtime.mapSendOutcome(outcome);
+        },
+    };
+}