@openlup/platform 0.26.0 → 0.28.0

package/src/commerce/server/outboxOrderPaidEmailHandler.ts

@@ -0,0 +1,147 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import { z } from "zod";
+import { COMMERCE_ORDER_PAID_EMAIL_EVENT_TYPE } from "../outboxEventSchemas.js";
+import type {
+  OutboxEventRow,
+  OutboxHandler,
+  OutboxHandlerOutcome,
+} from "../outboxDispatchContracts.js";
+import {
+  OUTBOX_ORDER_PAID_TEMPLATE_SLUG,
+  type OrderEmailTotals,
+  type OrderPaidLinesPort,
+  type OrderRecipientPort,
+  type TransactionalEmailPort,
+} from "../outboxOrderDraftEmailPorts.js";
+import { buildItems, type RawLine } 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,
+});
+
+/**
+ * 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>;
+
+// 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<Locale extends string>(data: {
+  currency: string;
+  subtotalMinor: number;
+  discountMinor: number;
+  totalMinor: number;
+}, runtime: Pick<CommerceEmailRuntime<Locale>, "formatMoney" | "genericItemLabel" | "mapSendOutcome" | "parseOutboxPayload" | "presentPaidOrder" | "resolveLocale">): OrderEmailTotals {
+  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<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 {
+  return {
+    ...outboxOrderPaidEmailDescriptor,
+    async handle(row: OutboxEventRow, signal: AbortSignal): Promise<OutboxHandlerOutcome> {
+      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: RawLine[] = (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<Locale extends string>(
+  describeParcel: OrderPaidParcelNoteReader<Locale> | undefined,
+  orderUuid: string,
+  locale: Locale,
+  signal: AbortSignal,
+  eventId: string,
+): Promise<string | null> {
+  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/src/commerce/server/outboxOrderPaidFulfillmentHandler.ts

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

package/src/commerce/server/outboxOrderPaidFulfillmentPorts.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/src/commerce/server/outboxOrderRefundedEmailHandler.ts

@@ -0,0 +1,58 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import { z } from "zod";
+import { COMMERCE_ORDER_REFUNDED_EVENT_TYPE } from "../outboxEventSchemas.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 };
+
+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<Locale extends string>(deps: {
+  runtime: Pick<CommerceEmailRuntime<Locale>, "createTransactionalEmailHandler" | "formatMoney" | "resolveLocale">;
+  emailPort: TransactionalEmailPort<Locale>;
+  recipientPort: OrderRecipientPort;
+}): OutboxHandler {
+  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/src/commerce/server/outboxPaymentFailedEmailHandler.ts

@@ -0,0 +1,99 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import { z } from "zod";
+import { COMMERCE_PAYMENT_FAILED_EVENT_TYPE } from "../outboxEventSchemas.js";
+import type {
+  OutboxEventRow,
+  OutboxHandler,
+  OutboxHandlerExecutionContext,
+  OutboxHandlerOutcome,
+} from "../outboxDispatchContracts.js";
+import {
+  OUTBOX_PAYMENT_FAILED_TEMPLATE_SLUG,
+  type OrderPaymentLifecyclePort,
+  type OrderRecipientPort,
+  type TransactionalEmailPort,
+} 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<Locale extends string>(deps: {
+  runtime: Pick<CommerceEmailRuntime<Locale>, "formatMoney" | "mapSendOutcome" | "parseOutboxPayload" | "resolveLocale">;
+  emailPort: TransactionalEmailPort<Locale>;
+  recipientPort: OrderRecipientPort;
+  lifecyclePort: OrderPaymentLifecyclePort;
+}): OutboxHandler {
+  return {
+    ...outboxPaymentFailedEmailDescriptor,
+    async handle(
+      row: OutboxEventRow,
+      signal: AbortSignal,
+      execution?: OutboxHandlerExecutionContext,
+    ): Promise<OutboxHandlerOutcome> {
+      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);
+    },
+  };
+}

package/src/commerce/server/outboxReturnEmailHandlers.ts

@@ -0,0 +1,92 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import { z } from "zod";
+import {
+  COMMERCE_RETURN_APPROVED_EVENT_TYPE,
+  COMMERCE_RETURN_REJECTED_EVENT_TYPE,
+} from "../outboxEventSchemas.js";
+import type { OutboxHandler } from "../outboxDispatchContracts.js";
+import {
+  OUTBOX_RETURN_APPROVED_TEMPLATE_SLUG,
+  OUTBOX_RETURN_REJECTED_TEMPLATE_SLUG,
+  type OrderRecipientPort,
+  type ReturnDecisionEmailInput,
+  type TransactionalEmailPort,
+  type TransactionalEmailSendOutcome,
+} from "../outboxOrderDraftEmailPorts.js";
+
+export { OUTBOX_RETURN_APPROVED_TEMPLATE_SLUG, OUTBOX_RETURN_REJECTED_TEMPLATE_SLUG };
+
+const HANDLER_TIMEOUT_MS = 10_000;
+
+export function describeOutboxReturnEmail(eventType: string) {
+  return { eventType, timeoutMs: HANDLER_TIMEOUT_MS };
+}
+
+export const outboxReturnApprovedEmailDescriptor = Object.freeze(describeOutboxReturnEmail(COMMERCE_RETURN_APPROVED_EVENT_TYPE));
+export const outboxReturnRejectedEmailDescriptor = Object.freeze(describeOutboxReturnEmail(COMMERCE_RETURN_REJECTED_EVENT_TYPE));
+
+const payloadSubsetSchema = z
+  .object({
+    orderUuid: z.guid(),
+    orderId: z.string().min(1),
+  })
+  .passthrough();
+
+// Both return-decision emails (approved / rejected) share the same payload, dedupe,
+// recipient resolution, and snooze/retry/discard ladder as the order-refunded email;
+// they differ only in event type, template slug, and which port method sends them.
+function createReturnDecisionEmailHandler<Locale extends string>(deps: {
+  runtime: Pick<CommerceEmailRuntime<Locale>, "createTransactionalEmailHandler" | "resolveLocale">;
+  emailPort: TransactionalEmailPort<Locale>;
+  recipientPort: OrderRecipientPort;
+  eventType: string;
+  templateSlug: string;
+  send: (
+    port: TransactionalEmailPort<Locale>,
+    input: ReturnDecisionEmailInput<Locale>,
+  ) => Promise<TransactionalEmailSendOutcome>;
+}): OutboxHandler {
+  return deps.runtime.createTransactionalEmailHandler({
+    ...describeOutboxReturnEmail(deps.eventType),
+    templateSlug: deps.templateSlug,
+    schema: payloadSubsetSchema,
+    resolveKey: (payload) => payload.orderUuid,
+    recipientPort: deps.recipientPort,
+    findExistingSend: (slug, id) => deps.emailPort.findExistingSend(slug, id),
+    send: ({ payload, recipient, row, signal }) =>
+      deps.send(deps.emailPort, {
+        to: recipient.email,
+        firstName: recipient.firstName,
+        orderId: payload.orderId,
+        outboxEventId: row.id,
+        locale: deps.runtime.resolveLocale(recipient.country ?? null),
+        signal,
+      }),
+  });
+}
+
+export function createOutboxReturnApprovedEmailHandler<Locale extends string>(deps: {
+  runtime: Pick<CommerceEmailRuntime<Locale>, "createTransactionalEmailHandler" | "resolveLocale">;
+  emailPort: TransactionalEmailPort<Locale>;
+  recipientPort: OrderRecipientPort;
+}): OutboxHandler {
+  return createReturnDecisionEmailHandler({
+    ...deps,
+    ...outboxReturnApprovedEmailDescriptor,
+    templateSlug: OUTBOX_RETURN_APPROVED_TEMPLATE_SLUG,
+    send: (port, input) => port.sendReturnApprovedNotice(input),
+  });
+}
+
+export function createOutboxReturnRejectedEmailHandler<Locale extends string>(deps: {
+  runtime: Pick<CommerceEmailRuntime<Locale>, "createTransactionalEmailHandler" | "resolveLocale">;
+  emailPort: TransactionalEmailPort<Locale>;
+  recipientPort: OrderRecipientPort;
+}): OutboxHandler {
+  return createReturnDecisionEmailHandler({
+    ...deps,
+    ...outboxReturnRejectedEmailDescriptor,
+    templateSlug: OUTBOX_RETURN_REJECTED_TEMPLATE_SLUG,
+    send: (port, input) => port.sendReturnRejectedNotice(input),
+  });
+}

package/src/commerce/server/outboxShipmentDeliveredEmailHandler.ts

@@ -0,0 +1,94 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import { z } from "zod";
+import { COMMERCE_SHIPMENT_DELIVERED_EVENT_TYPE } from "../outboxEventSchemas.js";
+import type {
+  OutboxEventRow,
+  OutboxHandler,
+  OutboxHandlerOutcome,
+} from "../outboxDispatchContracts.js";
+import {
+  OUTBOX_SHIPMENT_DELIVERED_TEMPLATE_SLUG,
+  type OrderRecipientPort,
+  type TransactionalEmailPort,
+} from "../outboxOrderDraftEmailPorts.js";
+
+export { OUTBOX_SHIPMENT_DELIVERED_TEMPLATE_SLUG };
+
+const HANDLER_TIMEOUT_MS = 10_000;
+
+export const outboxShipmentDeliveredEmailDescriptor = Object.freeze({
+  eventType: COMMERCE_SHIPMENT_DELIVERED_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+
+// Provider-aware notification policy (W6, folded into the kernel capability map in W8):
+// for providers whose carrier owns the delivery-progress notifications (incl. the
+// "delivered" notice), WE do not send our own "delivered" email — it would duplicate the
+// carrier's. We still own order-paid, invoice, exception, and the one branded "shipped"
+// (dispatched) email. The policy is read from the fulfillment capability map via the
+// shared `providerOwnsDeliveredNotification` helper (single source of truth).
+
+// Reads the order's normalized delivery providerKind (shared resolver, W2). Runtime
+// composition injects this for transactional email so provider-owned notices suppress ours.
+export interface DeliveredEmailProviderKindReader {
+  readSelectedProviderKind(orderUuid: string): Promise<string | null>;
+}
+
+const payloadSubsetSchema = z
+  .object({
+    orderUuid: z.guid(),
+    orderId: z.string().min(1),
+  })
+  .passthrough();
+
+export function createOutboxShipmentDeliveredEmailHandler<Locale extends string>(deps: {
+  runtime: Pick<CommerceEmailRuntime<Locale>, "mapSendOutcome" | "parseOutboxPayload" | "providerOwnsDeliveredNotification" | "resolveLocale">;
+  emailPort: TransactionalEmailPort<Locale>;
+  recipientPort: OrderRecipientPort;
+  // When provided, suppress OUR delivered email for carrier-owned providers.
+  providerKindReader?: DeliveredEmailProviderKindReader;
+}): OutboxHandler {
+  return {
+    ...outboxShipmentDeliveredEmailDescriptor,
+    async handle(row: OutboxEventRow, signal: AbortSignal): Promise<OutboxHandlerOutcome> {
+      const parsed = deps.runtime.parseOutboxPayload(payloadSubsetSchema, row.payload);
+      if (parsed.ok === false) {
+        return parsed.outcome;
+      }
+
+      // Provider-aware suppression: the carrier (via the 3PL) owns the delivered notice
+      // for these providers, so sending ours would duplicate it. Recorded as processed
+      // (not discarded) so the event settles and never retries.
+      if (deps.providerKindReader) {
+        const providerKind = await deps.providerKindReader.readSelectedProviderKind(parsed.data.orderUuid);
+        if (providerKind && deps.runtime.providerOwnsDeliveredNotification(providerKind)) {
+          return { kind: "processed", detail: { skipped: `carrier_owns_delivered:${providerKind}` } };
+        }
+      }
+
+      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_SHIPMENT_DELIVERED_TEMPLATE_SLUG,
+        row.id,
+      );
+      if (alreadySent) {
+        return { kind: "processed", detail: { dedupe: "email_already_sent" } };
+      }
+
+      const outcome = await deps.emailPort.sendShipmentDeliveredNotice({
+        to: recipient.email,
+        firstName: recipient.firstName,
+        contextName: recipient.contextName ?? null,
+        orderId: parsed.data.orderId,
+        outboxEventId: row.id,
+        locale: deps.runtime.resolveLocale(recipient.country ?? null),
+        signal,
+      });
+
+      return deps.runtime.mapSendOutcome(outcome);
+    },
+  };
+}

package/src/commerce/server/outboxShipmentDispatchedEmailHandler.ts

@@ -0,0 +1,112 @@
+import type { CommerceEmailRuntime } from "./emailRuntime.js";
+import { z } from "zod";
+import { COMMERCE_SHIPMENT_DISPATCHED_EVENT_TYPE } from "../outboxEventSchemas.js";
+import type { OutboxHandler } from "../outboxDispatchContracts.js";
+import {
+  OUTBOX_SHIPMENT_DISPATCHED_TEMPLATE_SLUG,
+  type OrderRecipientPort,
+  type TransactionalEmailPort,
+} from "../outboxOrderDraftEmailPorts.js";
+
+export { OUTBOX_SHIPMENT_DISPATCHED_TEMPLATE_SLUG };
+
+const HANDLER_TIMEOUT_MS = 10_000;
+
+export const outboxShipmentDispatchedEmailDescriptor = Object.freeze({
+  eventType: COMMERCE_SHIPMENT_DISPATCHED_EVENT_TYPE, timeoutMs: HANDLER_TIMEOUT_MS,
+});
+
+const trackingReferenceSchema = z
+  .object({
+    providerKind: z.string().trim().min(1).max(80).nullable().optional(),
+    carrierKind: z.string().trim().min(1).max(80).nullable().optional(),
+    service: z.string().trim().min(1).max(120).nullable().optional(),
+    trackingNumber: z.string().trim().min(1).max(160),
+    trackingUrl: z.string().url().max(500).nullable().optional(),
+  })
+  .strict();
+
+const payloadSubsetSchema = z
+  .object({
+    orderUuid: z.guid(),
+    orderId: z.string().min(1),
+    providerKind: z.string().trim().min(1).max(80).nullable().optional(),
+    carrierKind: z.string().trim().min(1).max(80).nullable().optional(),
+    service: z.string().trim().min(1).max(120).nullable().optional(),
+    trackingNumber: z.string().trim().min(1).nullable().optional(),
+    trackingUrl: z.string().url().max(500).nullable().optional(),
+    trackingReferences: z.array(trackingReferenceSchema).max(20).optional(),
+  })
+  .passthrough();
+
+export function createOutboxShipmentDispatchedEmailHandler<Locale extends string>(deps: {
+  runtime: Pick<CommerceEmailRuntime<Locale>, "carrierTrackingUrl" | "createTransactionalEmailHandler" | "legacyTrackingUrl" | "normalizeCarrierKind" | "resolveLocale">;
+  emailPort: TransactionalEmailPort<Locale>;
+  recipientPort: OrderRecipientPort;
+}): OutboxHandler {
+  return deps.runtime.createTransactionalEmailHandler({
+    ...outboxShipmentDispatchedEmailDescriptor,
+    templateSlug: OUTBOX_SHIPMENT_DISPATCHED_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 tracking = resolveCustomerTracking(payload, deps.runtime);
+      return deps.emailPort.sendShipmentDispatchedNotice({
+        to: recipient.email,
+        firstName: recipient.firstName,
+        contextName: recipient.contextName ?? null,
+        orderId: payload.orderId,
+        trackingNumber: tracking.trackingNumber,
+        trackingUrl: tracking.trackingUrl,
+        outboxEventId: row.id,
+        locale: deps.runtime.resolveLocale(recipient.country ?? null),
+        signal,
+      });
+    },
+  });
+}
+
+function resolveCustomerTracking<Locale extends string>(payload: z.infer<typeof payloadSubsetSchema>, runtime: Pick<CommerceEmailRuntime<Locale>, "carrierTrackingUrl" | "createTransactionalEmailHandler" | "legacyTrackingUrl" | "normalizeCarrierKind" | "resolveLocale">): {
+  trackingNumber: string | null;
+  trackingUrl: string | null;
+} {
+  const refs = (payload.trackingReferences ?? []).map((ref) => ({
+    providerKind: normalizeKind(ref.providerKind),
+    carrierKind: normalizeKind(ref.carrierKind),
+    service: ref.service ?? null,
+    trackingNumber: ref.trackingNumber,
+    trackingUrl: ref.trackingUrl ?? null,
+  }));
+  const legacyRef = payload.trackingNumber
+    ? {
+        providerKind: normalizeKind(payload.providerKind),
+        carrierKind: normalizeKind(payload.carrierKind),
+        service: payload.service ?? null,
+        trackingNumber: payload.trackingNumber,
+        trackingUrl: payload.trackingUrl ?? null,
+      }
+    : null;
+  const candidates = refs.length > 0 ? refs : legacyRef ? [legacyRef] : [];
+  const primary = candidates.find((ref) => ref.trackingUrl) ?? candidates[0] ?? null;
+  if (!primary) return { trackingNumber: null, trackingUrl: null };
+
+  // Persisted URL wins; otherwise the shared carrier registry builds one from
+  // the carrier kind (older shipment_external_refs rows predate URL persistence).
+  // The host retains its legacy fallback; unknown carriers remain number-only.
+  return {
+    trackingNumber: primary.trackingNumber,
+    trackingUrl:
+      primary.trackingUrl ??
+      runtime.carrierTrackingUrl(
+        runtime.normalizeCarrierKind({ carrierKind: primary.carrierKind, service: primary.service }),
+        primary.trackingNumber,
+      ) ??
+      runtime.legacyTrackingUrl(primary, refs.length > 0),
+  };
+}
+
+function normalizeKind(value: string | null | undefined): string | null {
+  return value?.trim().toLowerCase() || null;
+}