@openlup/platform 0.26.0 → 0.28.0

package/src/commerce/oms/omsFulfillmentContractSchemas.ts

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import type { OmsReplacementChain } from "../contracts/omsTypes.js";
+import {
+datetimeSchema,
+nullableTextSchema,
+omsFulfillmentStatusSchema,
+omsInventoryStatusSchema,
+omsProviderOpsSlaStatusSchema,
+omsSubscriptionCycleStatusSchema,
+uuidSchema,
+} from "./omsContractBase.js";
+import { omsProviderEvidenceSchema } from "./omsProviderEvidenceSchemas.js";
+export type { OmsReplacementChain } from "../contracts/omsTypes.js";
+
+export const omsProviderOpsSlaSchema = z.object({
+  status: omsProviderOpsSlaStatusSchema,
+  dispatchedAt: datetimeSchema.nullable(),
+  deadlineAt: datetimeSchema.nullable(),
+  remainingOperationalMinutes: z.number().int().min(0).nullable(),
+}).strict();
+
+export const omsFulfillmentTrackingReferenceSchema = z.object({
+  providerKind: z.string().min(1),
+  trackingNumber: z.string().min(1),
+  trackingUrl: nullableTextSchema,
+  carrierKind: nullableTextSchema,
+  service: nullableTextSchema,
+  updatedAt: datetimeSchema.nullable(),
+}).strict();
+
+export const omsFulfillmentTimelineEventSchema = z.object({
+  eventType: z.string().min(1),
+  label: z.string().min(1),
+  occurredAt: datetimeSchema.nullable(),
+  source: z.enum(["webhook", "reconciliation", "manual", "simulator", "fulfillment", "dispatch", "provider"]),
+}).strict();
+
+export const omsSubscriptionContextSchema = z.object({
+  subscriptionId: uuidSchema.nullable(),
+  subscriptionCycleId: uuidSchema.nullable(),
+  subscriptionCycleStatus: omsSubscriptionCycleStatusSchema.nullable(),
+  // Operator-facing dates. `nextCycleAt` is `subscriptions.next_cycle_at` (the
+  // next CHARGE instant, not a delivery date); `cyclePaidAt` is this cycle's
+  // `subscription_cycles.paid_at`. Both nullable: `commerce_orders` has no
+  // `paid_at`, so one-time orders carry neither.
+  nextCycleAt: datetimeSchema.nullable(),
+  cyclePaidAt: datetimeSchema.nullable(),
+});
+
+export const omsInventorySummarySchema = z.object({
+  status: omsInventoryStatusSchema,
+  reservationId: uuidSchema.nullable(),
+  reservationStatus: z.enum(["reserved", "released", "consumed", "expired"]).nullable(),
+  expiresAt: datetimeSchema.nullable(),
+  locationId: uuidSchema.nullable(),
+  locationCode: z.string().nullable(),
+});
+
+export const omsFulfillmentSummarySchema = z.object({
+  fulfillmentOrderId: uuidSchema.nullable(),
+  status: omsFulfillmentStatusSchema.nullable(),
+  providerKind: nullableTextSchema.default(null),
+  latestOperationType: z.string().min(1).nullable(),
+  latestOperationAt: datetimeSchema.nullable(),
+  providerTrackingId: z.string().min(1).nullable(),
+  trackingUrl: nullableTextSchema.default(null),
+  carrierKind: nullableTextSchema.default(null),
+  service: nullableTextSchema.default(null),
+  trackingReferences: z.array(omsFulfillmentTrackingReferenceSchema).default([]),
+  trackingTimeline: z.array(omsFulfillmentTimelineEventSchema).default([]),
+  providerEvidence: z.array(omsProviderEvidenceSchema).optional().default([]),
+});
+
+/**
+ * The order's replacement chain, detail-only.
+ *
+ * ⛔ This is NOT a second fulfilment summary. `fulfillment` stays exactly what W3 collapsed it
+ * to - one row, the parcel currently representing the order, with every companion narrowed to
+ * that parcel's id. Widening those companions was measured and rejected: the dispatch refs,
+ * provider attempts and status evidence of a superseded parcel would then be read by the
+ * fulfilment health classifier, the fulfilment debug panel and the customer-step derivation,
+ * each of which would answer for the wrong parcel - a dispatch status of `created` for a
+ * replacement that has never been dispatched, or a customer step of `delivered` for a parcel
+ * that is still `created`.
+ *
+ * So the superseded parcels carry their own, deliberately small payload: what a support agent
+ * needs to answer "where did the first one go?" and to file a carrier claim. Tracking number,
+ * carrier, service, the two handover instants, and the parcel's own status.
+ */
+export const omsSupersededParcelSchema = z.object({
+  fulfillmentOrderId: uuidSchema,
+  sequenceNo: z.number().int().min(0),
+  status: omsFulfillmentStatusSchema.nullable(),
+  replacementReason: nullableTextSchema.default(null),
+  handedOverAt: datetimeSchema.nullable(),
+  deliveredAt: datetimeSchema.nullable(),
+  trackingReferences: z.array(omsFulfillmentTrackingReferenceSchema).default([]),
+}).strict();
+
+export const omsReplacementChainSchema = z.object({
+  // `sequenceNo` 0 is the ordinary order: one parcel, no replacement, nothing to disclose.
+  sequenceNo: z.number().int().min(0),
+  replacesFulfillmentOrderId: uuidSchema.nullable(),
+  replacementReason: nullableTextSchema.default(null),
+  supersededParcels: z.array(omsSupersededParcelSchema).default([]),
+}).strict();
+
+export const defaultOmsReplacementChain: OmsReplacementChain = {
+  sequenceNo: 0,
+  replacesFulfillmentOrderId: null,
+  replacementReason: null,
+  supersededParcels: [],
+};

package/src/commerce/oms/omsFulfillmentDebugSchemas.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import type { OmsFulfillmentDebug } from "../contracts/omsTypes.js";
+import { datetimeSchema,nullableTextSchema } from "./omsContractBase.js";
+export type { OmsFulfillmentDebug } from "../contracts/omsTypes.js";
+
+export const omsFulfillmentDebugStepSchema = z.object({
+  key: z.enum(["payment", "stock", "provider_stock", "fulfillment", "dispatch", "provider", "tracking", "communication"]),
+  status: z.enum(["ok", "pending", "missing", "warning", "blocked"]),
+  label: z.string().min(1),
+  value: nullableTextSchema,
+  evidenceAt: datetimeSchema.nullable(),
+  details: z.array(z.string()).default([]),
+}).strict();
+
+export const omsFulfillmentDebugSchema = z.object({
+  summary: z.string().min(1),
+  severity: z.enum(["ok", "watch", "action_required"]),
+  nextAction: z.enum([
+    "wait",
+    "create_fulfillment",
+    "retry_dispatch",
+    "reconcile",
+    "review_payment",
+    "review_stock",
+    "review_provider",
+    "contact_support",
+  ]),
+  blockers: z.array(z.string()).default([]),
+  steps: z.array(omsFulfillmentDebugStepSchema).default([]),
+}).strict();
+
+export const defaultOmsFulfillmentDebug: OmsFulfillmentDebug = {
+  summary: "No fulfillment data.",
+  severity: "watch",
+  nextAction: "wait",
+  blockers: [],
+  steps: [],
+};

package/src/commerce/oms/omsFulfillmentHealthSchemas.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { uuidSchema } from "./omsContractBase.js";
+
+export const omsFulfillmentHealthSchema = z.object({
+  healthStatus: z.enum(["ok", "needs_attention", "blocked_uncertain", "local_ahead", "provider_ahead", "missing_local_commitment"]),
+  attentionReasons: z.array(z.enum([
+    "paid_order_missing_fulfillment",
+    "paid_order_missing_dispatch_ref",
+    "dispatch_submission_stale",
+    "dispatch_outcome_uncertain",
+    "dispatch_failed",
+    "dispatch_created_without_provider_order_id",
+    "dispatch_terminal_without_progress",
+    "dispatch_status_unknown",
+    "provider_exception_after_delivery",
+    "provider_exception_after_handover",
+    "provider_exception_before_handover",
+    "local_status_ahead_of_provider",
+    "provider_accepted_local_label_ack_missing",
+    "order_paid_outbox_discarded",
+    "order_paid_outbox_processed_without_fulfillment",
+    "order_paid_outbox_missing",
+  ])),
+  oldestAgeSeconds: z.number().int().nonnegative().nullable(),
+  dispatchRefId: uuidSchema.nullable().optional(),
+  dispatchStatus: z.string().nullable().optional(),
+  opaqueIds: z.object({
+    orderId: uuidSchema,
+    fulfillmentOrderId: uuidSchema.nullable(),
+    outboxEventId: uuidSchema.nullable(),
+    dispatchRefFulfillmentOrderId: uuidSchema.nullable(),
+    latestEvidenceFulfillmentOrderId: uuidSchema.nullable(),
+  }).strict(),
+}).strict();
+
+// The list-row projection of the health snapshot above: the two fields an
+// operator can act on, picked from the same schema so the vocabulary cannot
+// fork. The list path builds it from the provider evidence it already fetches
+// per page and never reads `outbox_events`, so a digest can never carry the
+// three `order_paid_outbox_*` reasons - the builder is told the outbox is
+// unread and answers `paid_order_missing_fulfillment` instead of naming an
+// outbox row it did not look at. The enum stays whole rather than being
+// narrowed here: the omission is a property of the input, not of the contract.
+export const omsFulfillmentHealthDigestSchema = omsFulfillmentHealthSchema
+  .pick({ healthStatus: true, attentionReasons: true })
+  .strict();

package/src/commerce/oms/omsPorts.ts

@@ -0,0 +1,165 @@
+import type { OmsReplacementRefusal } from "../contracts/omsTypes.js";
+import { neutralOmsCurrencyPolicy,type OmsCurrencyPolicy } from "../model/omsCurrency.js";
+export type { CommerceOmsHoldPort,CommerceOmsReadPort,OmsReplacementRefusal } from "../contracts/omsTypes.js";
+
+/**
+ * Every refusal `commerce_oms_request_replacement_shipment` can reach an operator with,
+ * as one closed vocabulary shared by the adapter that classifies it and the admin surface
+ * that renders a sentence for it. Two lists would drift, and the failure mode of drift is
+ * the operator reading advice about a hold when the warehouse is simply out of stock.
+ *
+ * The first group is the command's own `commerce_oms_replacement_*` names. The second is
+ * the reservation vocabulary raised THROUGH it: the command mints a fresh generation via
+ * `inventory_reserve_order`, and on a stock authority outside this system that call is the
+ * most likely legitimate refusal there is. Those errors never carried the command's prefix,
+ * so before this list they matched nothing, degraded to an upstream failure, and the
+ * operator was told to check holds that were not there.
+ *
+ * It stays an allowlist, not a translation table: a reason absent from it degrades to
+ * `unspecified_refusal`, so no database text can travel to a response, a log or a screen.
+ *
+ * ⛔ The exported names deliberately omit the `CommerceOms` prefix every other symbol in
+ * this file carries. `src/lib/commerceOmsBoundary.test.ts` forbids that token in production
+ * UI files outside a small allowlist, and the admin surface imports these three symbols.
+ * Renaming them is the honest way to keep that boundary guard intact; widening its allowlist
+ * to admit one more file would weaken the control instead of respecting it.
+ */
+export const OMS_REPLACEMENT_COMMAND_REFUSALS = [
+  "invalid_input",
+  "idempotency_conflict",
+  "order_not_found",
+  "order_not_replaceable",
+  "missing_client",
+  "missing_shipping_address",
+  "shipping_address_not_found",
+  "payment_not_succeeded",
+  "subscription_cycle_not_paid",
+  "no_parcel_to_replace",
+  "undispatched_replacement_exists",
+  "missing_order_items",
+  "missing_catalog_sku",
+  "missing_inventory_reservation",
+  "blocked_by_payment_not_succeeded_hold",
+  "blocked_by_inventory_review_hold",
+  "blocked_by_risk_review_hold",
+  "blocked_by_address_review_hold",
+  "blocked_by_manual_support_hold",
+] as const;
+
+export const OMS_REPLACEMENT_RESERVATION_REFUSALS = [
+  "inventory_external_provider_insufficient_available_stock",
+  "inventory_external_provider_stock_stale",
+  "inventory_external_provider_stock_missing",
+  "inventory_external_provider_sku_not_found",
+  "inventory_external_provider_location_missing",
+  "inventory_reservation_insufficient_available_stock",
+  "inventory_reservation_allocation_incomplete",
+  "inventory_reservation_payment_status_not_reservable",
+  "inventory_reservation_invalid_quantity",
+] as const;
+
+export const UNSPECIFIED_REPLACEMENT_REFUSAL = "unspecified_refusal";
+
+export const OMS_REPLACEMENT_REFUSALS = [
+  ...OMS_REPLACEMENT_COMMAND_REFUSALS,
+  ...OMS_REPLACEMENT_RESERVATION_REFUSALS,
+  UNSPECIFIED_REPLACEMENT_REFUSAL,
+] as const;
+
+/**
+ * Reads the refusal a replacement error carries, from any of the shapes a BFF error can
+ * legitimately arrive in. Returns null when the text names no refusal this vocabulary
+ * knows, which is the honest answer: the operator gets the generic sentence plus the raw
+ * detail to hand to the team, never a guess dressed as advice.
+ */
+export function readOmsReplacementRefusal(text: string): OmsReplacementRefusal | null {
+  const named = /commerce_oms_replacement_([a-z0-9_]+)/.exec(text)?.[1];
+  if (named) {
+    return (OMS_REPLACEMENT_COMMAND_REFUSALS as readonly string[]).includes(named)
+      ? named as OmsReplacementRefusal
+      : UNSPECIFIED_REPLACEMENT_REFUSAL;
+  }
+  // Exact membership only. A transport or permission failure that merely quotes a table
+  // name such as `inventory_reservations` must stay an upstream failure, not become a
+  // refusal the operator is asked to act on.
+  return OMS_REPLACEMENT_RESERVATION_REFUSALS.find((reason) => text.includes(reason)) ?? null;
+}
+
+export class CommerceOmsInvalidResponseError extends Error {
+  constructor() {
+    super("Commerce OMS returned invalid response");
+    this.name = "CommerceOmsInvalidResponseError";
+  }
+}
+
+export class CommerceOmsPersistenceError extends Error {
+  readonly details: Record<string, unknown>;
+
+  constructor(message = "Commerce OMS persistence failed", details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = "CommerceOmsPersistenceError";
+    this.details = details;
+  }
+}
+
+/**
+ * An order row came back from the database in a currency this deployment does
+ * not accept. The channel ingest rail is deliberately multi-currency, so such a
+ * row can genuinely exist; what it cannot do is reach the read model, whose
+ * money nodes are pinned to the platform's accepted set.
+ *
+ * A subclass rather than a new error family, so it inherits the persistence
+ * error's HTTP mapping untouched: this is still an upstream read that could not
+ * be served, and the operator-facing status must not move. The gain is entirely
+ * diagnostic - the failure now names the orders and the codes instead of
+ * surfacing as an anonymous validation error fifteen frames later.
+ */
+export class CommerceOmsUnsupportedCurrencyError extends CommerceOmsPersistenceError {
+  readonly orderIds: readonly string[];
+  readonly currencies: readonly string[];
+
+  constructor(offenders: ReadonlyArray<{ orderId: string; currency: string }>) {
+    const orderIds = offenders.map((offender) => offender.orderId);
+    const currencies = [...new Set(offenders.map((offender) => offender.currency))];
+    const described = offenders
+      .map((offender) => `order ${offender.orderId} has currency ${offender.currency}`)
+      .join(", ");
+    super(`${described}, not accepted by this deployment`, { orderIds, currencies });
+    this.name = "CommerceOmsUnsupportedCurrencyError";
+    this.orderIds = orderIds;
+    this.currencies = currencies;
+  }
+}
+
+/**
+ * Guards the one field of an order row that can break the OMS read.
+ *
+ * This is deliberately not a schema for the whole row. Of that row's ~22
+ * columns exactly one - `currency` - is both able to fail the read model and
+ * something the platform holds an opinion about; the rest would cost a new
+ * contract surface parsed once per row per page, and would only be coherent if
+ * the other cast row kinds on this path were validated too.
+ *
+ * It also deliberately refuses rather than filtering. Dropping the offending
+ * row would keep the page rendering while hiding a real customer order from the
+ * operator handling it - a worse failure than a named refusal.
+ */
+export function assertOmsOrderRowCurrency(
+  rows: ReadonlyArray<{ id: string; currency: string }>,
+  currency: OmsCurrencyPolicy = neutralOmsCurrencyPolicy,
+): void {
+  const offenders = rows
+    .filter((row) => !currency.accepts(row.currency))
+    .map((row) => ({ orderId: row.id, currency: row.currency }));
+  if (offenders.length) throw new CommerceOmsUnsupportedCurrencyError(offenders);
+}
+
+export class CommerceOmsConflictError extends Error {
+  readonly details: Record<string, unknown>;
+
+  constructor(message = "Commerce OMS conflict", details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = "CommerceOmsConflictError";
+    this.details = details;
+  }
+}

package/src/commerce/oms/omsPrimitives.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+// OMS read money permits signed adjustments and rejects unknown fields.
+export const commerceMoneySchema = z.object({ amountMinor: z.number().int(), currency: z.string().regex(/^[A-Z]{3}$/) }).strict();

package/src/commerce/oms/omsProviderEvidenceSchemas.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { datetimeSchema,nullableTextSchema } from "./omsContractBase.js";
+
+export const omsProviderEvidenceSchema = z.object({
+  evidenceType: z.enum(["dispatch_ref", "provider_attempt", "status_evidence"]),
+  status: nullableTextSchema,
+  providerStatus: nullableTextSchema,
+  providerOrderId: nullableTextSchema,
+  evidenceKind: nullableTextSchema,
+  occurredAt: datetimeSchema.nullable(),
+  updatedAt: datetimeSchema.nullable(),
+  summary: nullableTextSchema,
+}).strict();

package/src/commerce/orderDraftErrors.ts

@@ -0,0 +1,28 @@
+/**
+ * The quote was valid when read, but the atomic order write could no longer
+ * claim its promotion. Callers must re-quote and surface `price_changed`.
+ */
+export class CommerceOrderDraftPriceChangedError extends Error {
+  readonly details: Record<string, unknown>;
+
+  constructor(
+    message = "Commerce order draft promotion changed",
+    details: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.name = "CommerceOrderDraftPriceChangedError";
+    this.details = details;
+  }
+}
+
+export type CommerceOrderDraftUnsupportedMoneyReason =
+  | "line_promotion_unsupported"
+  | "net_shipping_unsupported"
+  | "zero_payable_unsupported";
+
+export class CommerceOrderDraftUnsupportedMoneyError extends Error {
+  constructor(readonly reason: CommerceOrderDraftUnsupportedMoneyReason) {
+    super(`Commerce order draft money shape is unsupported: ${reason}`);
+    this.name = "CommerceOrderDraftUnsupportedMoneyError";
+  }
+}

package/src/commerce/orderEmailEligibility.ts

@@ -0,0 +1,131 @@
+import type { OrderPaymentLifecycleState } from "./outboxOrderDraftEmailPorts.js";
+
+/**
+ * Skip reason meaning "the payer is inside a live payment session right now".
+ * Exported because it is the one skip reason a caller must treat as TRANSIENT;
+ * every other reason in this module is a settled fact about the order.
+ */
+export const PAYMENT_SESSION_ACTIVE = "payment_session_active";
+
+const SUCCESSFUL_PAYMENT_STATUSES = new Set(["succeeded", "paid", "captured"]);
+const ACTIVE_PAYMENT_STATUSES = new Set(["pending", "requires_action", "created", "processing"]);
+const FRESH_PAYMENT_ACTIVITY_MS = 15 * 60 * 1000;
+
+export function shouldSkipOrderDraftConfirmation(
+  state: OrderPaymentLifecycleState | null,
+): string | null {
+  if (state === null) return "order_unavailable";
+  if (state.orderStatus !== "draft") return "order_no_longer_draft";
+  if (state.hasPayment) return "order_no_longer_draft";
+  if (state.paymentStatus && state.paymentStatus !== "not_started") return "order_no_longer_draft";
+  return null;
+}
+
+/**
+ * Eligibility for the checkout-recovery NUDGE only.
+ *
+ * `payment_session_active` below is a politeness rule: do not remind someone to
+ * pay while they are paying. It is correct here and wrong for a decline notice
+ * — see {@link shouldSkipPaymentFailedNotice}. A caller acting on this reason
+ * must defer rather than drop, because the nudge's emit key is once-per-order.
+ */
+export function shouldSkipCheckoutRecovery(
+  state: OrderPaymentLifecycleState | null,
+): string | null {
+  if (state === null) return "order_unavailable";
+  if (state.orderStatus !== "pending_payment") return "order_not_pending_payment";
+  if (state.paymentStatus && SUCCESSFUL_PAYMENT_STATUSES.has(state.paymentStatus)) {
+    return "order_already_paid";
+  }
+  if (
+    state.paymentStatus &&
+    ACTIVE_PAYMENT_STATUSES.has(state.paymentStatus) &&
+    isFreshPaymentActivity(state.paymentUpdatedAt)
+  ) {
+    return PAYMENT_SESSION_ACTIVE;
+  }
+  return null;
+}
+
+/**
+ * Eligibility for an OPERATOR-ISSUED recovery link.
+ *
+ * Deliberately not {@link shouldSkipCheckoutRecovery}. That gate is written for
+ * the cron nudge, and its first rule — leave `pending_payment` and we go quiet —
+ * is exactly wrong here. A human looked at the order and decided to send this
+ * link, and the orders they send it for are largely the ones that have ALREADY
+ * left `pending_payment`: `expired` is the ordinary case, and the redeem rail
+ * recreates such an order from its frozen quote when the customer opens the link.
+ * Reusing the cron gate would skip those as `order_not_pending_payment`, the
+ * operator would have promised an email that never arrives, and nothing anywhere
+ * would report a failure. The mint side has already run the full recovery
+ * eligibility for this order, so what is left here is only what can have changed
+ * between the mint and the send.
+ *
+ * What still suppresses: the order is gone, or the money is in. Both make the
+ * email actively wrong rather than merely late.
+ *
+ * `payment_session_active` behaves exactly as it does for the nudge, and for the
+ * same reason: do not tell someone to finish paying while they are paying. The
+ * caller must DEFER on it rather than drop, because a dropped operator link is
+ * the silent no-send this whole path is written to prevent.
+ */
+export function shouldSkipOperatorCheckoutRecovery(
+  state: OrderPaymentLifecycleState | null,
+): string | null {
+  if (state === null) return "order_unavailable";
+  if (state.orderStatus === "paid") return "order_already_paid";
+  if (state.paymentStatus && SUCCESSFUL_PAYMENT_STATUSES.has(state.paymentStatus)) {
+    return "order_already_paid";
+  }
+  if (
+    state.paymentStatus &&
+    ACTIVE_PAYMENT_STATUSES.has(state.paymentStatus) &&
+    isFreshPaymentActivity(state.paymentUpdatedAt)
+  ) {
+    return PAYMENT_SESSION_ACTIVE;
+  }
+  return null;
+}
+
+/**
+ * Eligibility for a recoverable payment-decline notice.
+ *
+ * Unlike a checkout reminder, a decline notice must not be suppressed by a live
+ * retry. Its producer key is once per order, so a later failed attempt cannot
+ * replace a notice that was consumed without sending.
+ *
+ * Suppress only when the order is unavailable, already paid, or no longer
+ * pending payment. The producer's claim delay lets successful retries settle
+ * before this lifecycle read; scheduling remains the producer/runtime's duty.
+ */
+export function shouldSkipPaymentFailedNotice(
+  state: OrderPaymentLifecycleState | null,
+): string | null {
+  if (state === null) return "order_unavailable";
+  if (state.orderStatus !== "pending_payment") return "order_not_pending_payment";
+  if (state.paymentStatus && SUCCESSFUL_PAYMENT_STATUSES.has(state.paymentStatus)) {
+    return "order_already_paid";
+  }
+  return null;
+}
+
+export function shouldSkipCheckoutExpired(
+  state: OrderPaymentLifecycleState | null,
+): string | null {
+  if (state === null) return "order_unavailable";
+  if (state.orderStatus === "expired") return null;
+  // ⛔ The activation sweep writes `cancelled`, never `expired`, so a first
+  // subscription abandoned at the 24h window would fail an `expired`-only gate
+  // and the buyer would hear nothing at all. Accepted ONLY with the sweep's own
+  // marker, so an ordinary cancellation still cannot reach this template.
+  if (state.orderStatus === "cancelled" && state.subscriptionActivationAbandoned === true) return null;
+  return "order_not_expired";
+}
+
+function isFreshPaymentActivity(value: string | null | undefined): boolean {
+  if (!value) return false;
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp)) return false;
+  return Date.now() - timestamp < FRESH_PAYMENT_ACTIVITY_MS;
+}

package/src/commerce/orderEmailLines.ts

@@ -0,0 +1,22 @@
+import type { OrderEmailLineItem } from "./outboxOrderDraftEmailPorts.js";
+
+export interface RawLine {
+  label: string | null;
+  quantity: number;
+  lineSubtotalMinor: number | null;
+  currency: string | null;
+}
+
+export interface OrderEmailLinePresentation<Locale extends string = string> {
+  formatMoney(amountMinor: number, currency: string): string;
+  genericItemLabel(locale: Locale): string;
+}
+
+export function buildItems<Locale extends string>(lines: RawLine[], locale: Locale, presentation: OrderEmailLinePresentation<Locale>): OrderEmailLineItem[] {
+  return lines.map((line) => {
+    const name = line.label ?? presentation.genericItemLabel(locale);
+    const lineTotalLabel = line.lineSubtotalMinor !== null && line.currency !== null
+      ? presentation.formatMoney(line.lineSubtotalMinor, line.currency) : "";
+    return { name, quantity: line.quantity, lineTotalLabel };
+  });
+}

package/src/commerce/orderFeedbackContracts.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+
+// Contract for the public order-feedback (post-delivery review) submit BFF.
+// No login: the opaque token from the review-email link is the only credential.
+export const ORDER_FEEDBACK_SUBMIT_RPC_NAME = "submit_order_feedback";
+export const ORDER_FEEDBACK_CHECK_RPC_NAME = "check_order_feedback_token";
+
+export const orderFeedbackTokenCheckRequestSchema = z
+  .object({ token: z.string().min(1).max(128) })
+  .strict();
+export type OrderFeedbackTokenCheckRequest = z.infer<typeof orderFeedbackTokenCheckRequestSchema>;
+
+export const orderFeedbackTokenCheckStatusSchema = z.enum([
+  "ready",
+  "already_submitted",
+  "not_found",
+]);
+export type OrderFeedbackTokenCheckStatus = z.infer<typeof orderFeedbackTokenCheckStatusSchema>;
+
+export const orderFeedbackTokenCheckResponseSchema = z
+  .object({ status: orderFeedbackTokenCheckStatusSchema })
+  .strict();
+export type OrderFeedbackTokenCheckResponse = z.infer<typeof orderFeedbackTokenCheckResponseSchema>;
+
+export const orderFeedbackSubmitRequestSchema = z
+  .object({
+    token: z.string().min(1).max(128),
+    rating: z.number().int().min(1).max(5),
+    comment: z.string().max(2000).optional(),
+  })
+  .strict();
+
+export type OrderFeedbackSubmitRequest = z.infer<typeof orderFeedbackSubmitRequestSchema>;
+
+// The RPC reports outcome without ever exposing the row, so the form can show
+// the right state (submitted / already submitted / unknown token).
+export const orderFeedbackSubmitStatusSchema = z.enum([
+  "submitted",
+  "already_submitted",
+  "not_found",
+]);
+export type OrderFeedbackSubmitStatus = z.infer<typeof orderFeedbackSubmitStatusSchema>;
+
+export const orderFeedbackSubmitResponseSchema = z
+  .object({ status: orderFeedbackSubmitStatusSchema })
+  .strict();
+export type OrderFeedbackSubmitResponse = z.infer<typeof orderFeedbackSubmitResponseSchema>;