@openlup/platform 0.26.0 → 0.28.0

package/dist/commerce/adapters/managed/oms/readQueries.js

@@ -0,0 +1,276 @@
+import { buildOmsOrderDetailResponse, buildOmsOrderListResponse } from "../../../model/omsReadModel.js";
+import { paymentStatusForOrder } from "../../../model/omsReadModelHelpers.js";
+import { ORDER_HEADER_MONEY_COLUMNS, ORDER_ITEM_MONEY_COLUMNS } from "../../../orderMoney.js";
+import { omsDeliveryContactResolutionSchema } from "../../../oms/omsContracts.js";
+import { assertOmsOrderRowCurrency, CommerceOmsPersistenceError } from "../../../oms/omsPorts.js";
+import { readAccountingOutbox } from "./accounting.js";
+import { readFulfillmentOrdersByOrderIds, readFulfillmentParcelsByOrderId, readShipmentRefsByOrderId, readShipmentRefsByOrderIds } from "./fulfillmentReads.js";
+import { readOrderPaidOutboxEvents } from "./outboxEvents.js";
+import { readActivePaymentAttempts } from "./paymentAttempts.js";
+import { readQueueSelection } from "./queueSelection.js";
+import { emptyOmsManagedReadProjections } from "./readProjections.js";
+import { distinctIds } from "./types.js";
+// `sales_channels(slug)` is the order's source channel, embedded through the only
+// foreign key between the two tables and mirroring the `inventory_locations(code)`
+// embed on the reservation read below. The channel id itself is deliberately not
+// selected: nothing on this read path addresses a channel by id, only by slug.
+const ORDER_COLUMNS = `id, order_number, client_id, status, mode, ${ORDER_HEADER_MONEY_COLUMNS}, metadata, created_at, updated_at, subscription_id, subscription_cycle_id, shipping_address_id, source_kind, source_order_ref, sales_channels(slug)`;
+const ORDER_ITEM_COLUMNS = `id, order_id, sku_id, quantity, ${ORDER_ITEM_MONEY_COLUMNS}, product_snapshot, variant_snapshot`;
+const ADDRESS_COLUMNS = "id, label, line1, line2, city, postal_code, country, recipient_name, contact_phone, company_name, tax_id, delivery_notes, courier_instructions";
+const INVOICE_COLUMNS = "id, order_id, invoice_ref, status, provider_kind, provider_invoice_number, total_gross_cents, currency, blocked_reason, updated_at";
+const COMMUNICATION_DELIVERY_COLUMNS = "id, purpose, template_slug, trigger_source, trigger_event, aggregate_type, aggregate_id, dedupe_key, status, provider_kind, provider_message_id, scheduled_due_at, expected_send_at, queued_at, first_attempt_at, sent_at, delivered_at, terminal_at, last_error_code, outbox_event_id, platform_job_run_id, email_send_id, metadata, created_at, updated_at";
+export async function listCommerceOmsOrders(client, request, options = {}) {
+    const projections = readProjections(options.projections);
+    const queue = await readQueueSelection(client, request, { currency: projections.model?.currency, projectResult: projections.projectQueue, matchSchema: projections.queueMatchSchema });
+    if (!queue.orderIds.length) {
+        return buildOmsOrderListResponse({
+            projections: projections.model,
+            orders: [],
+            paymentIntents: [],
+            paymentAttempts: [],
+            activeHoldCounts: {},
+            summaryCounts: queue.summaryCounts,
+            summaryTotals: queue.summaryTotals,
+            searchMatches: queue.matches,
+            totalCount: queue.totalCount,
+            page: request.page,
+            pageSize: request.pageSize,
+        });
+    }
+    const ordersResult = await client.query("commerce_orders").select(options.projections?.orderColumns ?? ORDER_COLUMNS).in("id", queue.orderIds);
+    if (ordersResult.error)
+        throw new CommerceOmsPersistenceError("Commerce OMS order list read failed");
+    const rowsById = new Map((ordersResult.data ?? []).map((order) => [order.id, order]));
+    const orders = queue.orderIds.map((id) => rowsById.get(id)).filter((order) => Boolean(order));
+    if (orders.length !== queue.orderIds.length)
+        throw new CommerceOmsPersistenceError("Commerce OMS queue order hydration mismatch");
+    // The cast above is the only thing asserting these rows' shape. Currency is
+    // the one column that can defeat the read model, so it is checked here where
+    // the order id is still in hand, not fifteen frames later inside a money node.
+    assertOmsOrderRowCurrency(orders, projections.model?.currency);
+    const orderIds = orders.map((order) => order.id);
+    const clientIds = distinctIds(orders.map((order) => order.client_id));
+    const related = await readListRelations(client, orders, orderIds, clientIds, projections);
+    const fulfillmentOrderIds = related.fulfillmentOrders.map((order) => order.id);
+    const [fulfillmentOperations, dispatchRefs, statusEvidence, accountingOutbox] = await Promise.all([
+        projections.readFulfillmentOperations(client, fulfillmentOrderIds),
+        projections.readProviderDispatchRefs(client, fulfillmentOrderIds),
+        projections.readProviderStatusEvidence(client, fulfillmentOrderIds),
+        readAccountingOutbox(client, related.invoices),
+    ]);
+    return buildOmsOrderListResponse({
+        orders,
+        paymentIntents: related.paymentIntents,
+        paymentAttempts: related.paymentAttempts,
+        activeHoldCounts: countHoldsByOrder(related.activeHolds),
+        activeHoldReasons: holdReasonsByOrder(related.activeHolds),
+        fulfillmentHealthDigests: projections.buildHealthDigests({ orders, paymentIntents: related.paymentIntents, fulfillmentOrders: related.fulfillmentOrders, dispatchRefs, statusEvidence }),
+        customers: related.customers,
+        identityExtras: related.identityExtras,
+        projections: projections.model,
+        orderItems: related.orderItems,
+        inventoryReservations: related.reservations,
+        fulfillmentOrders: related.fulfillmentOrders,
+        fulfillmentOperations,
+        shipmentExternalRefs: related.shipmentRefs,
+        providerDispatchRefs: dispatchRefs,
+        providerStatusEvidence: statusEvidence,
+        releasedProviderExceptionHolds: related.releasedProviderExceptionHolds,
+        accountingInvoices: related.invoices,
+        accountingOutbox,
+        subscriptionCycleStatuses: related.subscriptionCycleStatuses,
+        summaryCounts: queue.summaryCounts,
+        summaryTotals: queue.summaryTotals,
+        searchMatches: queue.matches,
+        totalCount: queue.totalCount,
+        page: request.page,
+        pageSize: request.pageSize,
+    });
+}
+export async function getCommerceOmsOrderDetail(client, request, options = {}) {
+    const orderResult = await client.query("commerce_orders").select(options.projections?.orderColumns ?? ORDER_COLUMNS).eq("id", request.orderId).maybeSingle();
+    if (orderResult.error)
+        throw new CommerceOmsPersistenceError("Commerce OMS order detail read failed");
+    if (!orderResult.data)
+        return null;
+    return readOrderDetail(client, orderResult.data, options);
+}
+/** Hydrate a bounded selection without repeating its canonical header query. */
+export async function getCommerceOmsOrderDetails(client, orderIds, options = {}) {
+    if (orderIds.length === 0)
+        return [];
+    if (orderIds.length > 25)
+        throw new CommerceOmsPersistenceError("Commerce OMS detail batch exceeds 25 orders");
+    const result = await client.query("commerce_orders").select(options.projections?.orderColumns ?? ORDER_COLUMNS).in("id", [...new Set(orderIds)]);
+    if (result.error)
+        throw new CommerceOmsPersistenceError("Commerce OMS order detail read failed");
+    const orders = new Map((result.data ?? []).map((order) => [order.id, order]));
+    return Promise.all(orderIds.map((id) => {
+        const order = orders.get(id);
+        return order ? readOrderDetail(client, order, options) : null;
+    }));
+}
+async function readOrderDetail(client, order, options) {
+    const projections = readProjections(options.projections);
+    assertOmsOrderRowCurrency([order], projections.model?.currency);
+    const [related, resolutionResult] = await Promise.all([
+        readDetailRelations(client, order, projections),
+        client.rpc("commerce_oms_resolve_delivery_contact_v1", { p_order_id: order.id }),
+    ]);
+    if (resolutionResult.error)
+        throw new CommerceOmsPersistenceError("Commerce OMS delivery contact resolution failed");
+    const contactResolution = omsDeliveryContactResolutionSchema.safeParse(resolutionResult.data);
+    if (!contactResolution.success)
+        throw new CommerceOmsPersistenceError("Commerce OMS delivery contact resolution was malformed");
+    const intent = related.intent;
+    // Every parcel, current first. Provider evidence stays keyed on the current
+    // parcel; widening it would attribute a sibling's state to the live shipment.
+    // Superseded parcels travel as separate support/claim nodes below.
+    const parcels = related.parcels;
+    const fulfillmentOrder = parcels[0] ?? null;
+    const invoice = related.invoice;
+    const fulfillmentOrderIds = fulfillmentOrder ? [fulfillmentOrder.id] : [];
+    const [attemptsResult, transitionsResult, fulfillmentOperations, providerAttempts, dispatchRefs, statusEvidence, releasedProviderExceptionHolds, outboxResult, orderPaidOutboxResult, communicationResult] = await Promise.all([
+        intent ? client.query("commerce_payment_attempts").select("id, status, provider, provider_attempt_id, next_action_kind, updated_at").eq("payment_intent_id", intent.id).order("created_at", { ascending: false }) : emptyRows(),
+        intent ? client.query("commerce_payment_state_transitions").select("id, transition_kind, from_status, to_status, reason, occurred_at").eq("payment_intent_id", intent.id).order("occurred_at", { ascending: false }) : emptyRows(),
+        projections.readFulfillmentOperations(client, fulfillmentOrderIds),
+        projections.readProviderAttempts(client, fulfillmentOrderIds),
+        projections.readProviderDispatchRefs(client, fulfillmentOrderIds),
+        projections.readProviderStatusEvidence(client, fulfillmentOrderIds),
+        projections.readReleasedProviderExceptionHolds(client, [order.id]),
+        invoice
+            ? client
+                .query("accounting_invoice_issue_outbox")
+                .select("invoice_id, status, attempt_count, next_attempt_at, last_error, created_at")
+                .eq("invoice_id", invoice.id)
+                .order("created_at", { ascending: false })
+            : emptyRows(),
+        readOrderPaidOutboxEvents(client, order.id),
+        client
+            .query("communication_email_deliveries")
+            .select(COMMUNICATION_DELIVERY_COLUMNS)
+            .eq("aggregate_type", "commerce_order")
+            .eq("aggregate_id", order.id)
+            .order("created_at", { ascending: false }),
+    ]);
+    if ([attemptsResult, transitionsResult, outboxResult, orderPaidOutboxResult, communicationResult].some((result) => result.error))
+        throw new CommerceOmsPersistenceError("Commerce OMS detail expansion read failed");
+    const inboundProviderEvents = await projections.readInboundEvents(client, { order, dispatchRefs });
+    const providerStockCurrent = await projections.readProviderStockCurrent(client, related.orderItems);
+    const paymentAttempts = (attemptsResult.data ?? []);
+    const fulfillmentHealth = projections.buildHealth({
+        order,
+        paymentStatus: paymentStatusForOrder(order.id, intent ? [intent] : []),
+        fulfillmentOrders: fulfillmentOrder ? [fulfillmentOrder] : [],
+        dispatchRefs,
+        statusEvidence,
+        orderPaidOutboxEvents: (orderPaidOutboxResult.data ?? []),
+    });
+    return buildOmsOrderDetailResponse({
+        order,
+        paymentIntent: intent,
+        paymentAttempts,
+        paymentTransitions: (transitionsResult.data ?? []),
+        holds: related.holds,
+        operations: related.operations,
+        customer: related.customer,
+        identityExtras: related.identityExtras,
+        projections: projections.model,
+        shippingAddress: related.shippingAddress,
+        accountingInvoice: invoice,
+        accountingOutbox: (outboxResult.data ?? []),
+        communicationDeliveries: (communicationResult.data ?? []),
+        orderItems: related.orderItems,
+        inventoryReservations: related.reservations,
+        fulfillmentOrders: fulfillmentOrder ? [fulfillmentOrder] : [],
+        supersededFulfillmentOrders: parcels.slice(1),
+        fulfillmentOperations,
+        shipmentExternalRefs: related.shipmentRefs,
+        providerAttempts,
+        providerDispatchRefs: dispatchRefs,
+        providerStatusEvidence: statusEvidence,
+        releasedProviderExceptionHolds,
+        fulfillmentHealth,
+        inboundProviderEvents,
+        providerStockCurrent,
+        subscriptionCycleStatus: related.cycleStatus,
+        subscriptionCyclePaidAt: related.cyclePaidAt, subscriptionNextCycleAt: related.subscriptionNextCycleAt,
+        actionFlags: options.actionFlags,
+        deliveryContactResolution: contactResolution.data,
+    });
+}
+async function readListRelations(client, orders, orderIds, clientIds, projections) {
+    const cycleIds = distinctIds(orders.map((order) => order.subscription_cycle_id ?? null));
+    const [intent, hold, releasedProviderExceptionHolds, customer, identityExtras, items, reservations, fulfillment, shipmentRefs, invoice, cycles] = await Promise.all([
+        orderIds.length ? client.query("commerce_payment_intents").select("id, order_id, payment_id, status, active_attempt_id, provider_payment_id, updated_at").in("order_id", orderIds) : emptyRows(),
+        orderIds.length ? client.query("commerce_order_holds").select("order_id, reason").in("order_id", orderIds).eq("status", "active") : emptyRows(),
+        projections.readReleasedProviderExceptionHolds(client, orderIds),
+        clientIds.length ? client.query("clients").select("id, email, first_name, last_name, phone, lifecycle_stage").in("id", clientIds) : emptyRows(),
+        projections.readIdentity(client, orders, "list"),
+        orderIds.length ? client.query("commerce_order_items").select(ORDER_ITEM_COLUMNS).in("order_id", orderIds) : emptyRows(),
+        orderIds.length ? client.query("inventory_reservations").select("id, order_id, order_item_id, quantity, status, expires_at, location_id, inventory_locations!inventory_reservations_location_id_fkey(code)").in("order_id", orderIds) : emptyRows(),
+        readFulfillmentOrdersByOrderIds(client, orderIds),
+        readShipmentRefsByOrderIds(client, orderIds),
+        orderIds.length ? client.query("accounting_invoices").select(projections.invoiceColumns ?? INVOICE_COLUMNS).in("order_id", orderIds).is("correction_of_invoice_id", null) : emptyRows(),
+        cycleIds.length ? client.query("subscription_cycles").select("id, status").in("id", cycleIds) : emptyRows(),
+    ]);
+    if (intent.error || hold.error || customer.error || items.error || reservations.error || fulfillment.error || shipmentRefs.error || invoice.error || cycles.error) {
+        throw new CommerceOmsPersistenceError("Commerce OMS related list read failed");
+    }
+    const paymentIntents = (intent.data ?? []);
+    const paymentAttempts = await readActivePaymentAttempts(client, paymentIntents);
+    return {
+        paymentIntents,
+        paymentAttempts,
+        activeHolds: (hold.data ?? []),
+        releasedProviderExceptionHolds,
+        customers: (customer.data ?? []),
+        identityExtras,
+        orderItems: (items.data ?? []),
+        reservations: (reservations.data ?? []),
+        fulfillmentOrders: (fulfillment.data ?? []),
+        shipmentRefs: (shipmentRefs.data ?? []),
+        invoices: (invoice.data ?? []).map(projections.mapInvoice),
+        subscriptionCycleStatuses: Object.fromEntries((cycles.data ?? []).map((cycle) => [cycle.id, cycle.status])),
+    };
+}
+async function readDetailRelations(client, order, projections) {
+    const [intent, holds, operations, items, cycle, reservations, fulfillment, shipmentRefs, customer, identityExtras, address, invoice, subscription] = await Promise.all([
+        client.query("commerce_payment_intents").select("id, order_id, payment_id, status, active_attempt_id, provider_payment_id, updated_at").eq("order_id", order.id).maybeSingle(),
+        client.query("commerce_order_holds").select("id, order_id, status, reason, note, created_at, released_at").eq("order_id", order.id).order("created_at", { ascending: false }),
+        client.query("commerce_order_operations").select("id, order_id, operation_type, hold_id, actor_user_id, occurred_at, payload").eq("order_id", order.id).order("occurred_at", { ascending: false }),
+        client.query("commerce_order_items").select(ORDER_ITEM_COLUMNS).eq("order_id", order.id),
+        order.subscription_cycle_id ? client.query("subscription_cycles").select("status, paid_at").eq("id", order.subscription_cycle_id).maybeSingle() : emptyOne(),
+        client.query("inventory_reservations").select("id, order_id, order_item_id, quantity, status, expires_at, location_id, inventory_locations!inventory_reservations_location_id_fkey(code)").eq("order_id", order.id).order("created_at", { ascending: false }),
+        readFulfillmentParcelsByOrderId(client, order.id),
+        readShipmentRefsByOrderId(client, order.id),
+        order.client_id ? client.query("clients").select("id, email, first_name, last_name, phone, lifecycle_stage").eq("id", order.client_id).maybeSingle() : emptyOne(),
+        projections.readIdentity(client, [order], "detail"),
+        order.shipping_address_id ? client.query("addresses").select(ADDRESS_COLUMNS).eq("id", order.shipping_address_id).maybeSingle() : emptyOne(),
+        client.query("accounting_invoices").select(projections.invoiceColumns ?? INVOICE_COLUMNS).eq("order_id", order.id).is("correction_of_invoice_id", null).maybeSingle(),
+        order.subscription_id ? client.query("subscriptions").select("next_cycle_at").eq("id", order.subscription_id).maybeSingle() : emptyOne(), // read-only display enrichment (next CHARGE date); deliberately absent from the error check below so a failure degrades to a dash instead of failing the whole detail
+    ]);
+    if (intent.error || holds.error || operations.error || items.error || cycle.error || reservations.error || fulfillment.error || shipmentRefs.error || customer.error || address.error || invoice.error) {
+        throw new CommerceOmsPersistenceError("Commerce OMS related detail read failed");
+    }
+    return {
+        intent: (intent.data ?? null),
+        holds: (holds.data ?? []),
+        operations: (operations.data ?? []),
+        orderItems: (items.data ?? []),
+        cycleStatus: (cycle.data?.status ?? null),
+        cyclePaidAt: (cycle.data?.paid_at ?? null), subscriptionNextCycleAt: (subscription.data?.next_cycle_at ?? null),
+        reservations: (reservations.data ?? []),
+        parcels: (fulfillment.data ?? []),
+        shipmentRefs: (shipmentRefs.data ?? []),
+        customer: (customer.data ?? null),
+        identityExtras: identityExtras[order.id],
+        shippingAddress: (address.data ?? null),
+        invoice: invoice.data ? projections.mapInvoice(invoice.data) : null,
+    };
+}
+function countHoldsByOrder(rows) { return rows.reduce((counts, row) => ({ ...counts, [row.order_id]: (counts[row.order_id] ?? 0) + 1 }), {}); }
+function holdReasonsByOrder(rows) { return rows.reduce((reasons, row) => ({ ...reasons, [row.order_id]: [...new Set([...(reasons[row.order_id] ?? []), row.reason])] }), {}); }
+function emptyRows() { return Promise.resolve({ data: [], error: null }); }
+function emptyOne() { return Promise.resolve({ data: null, error: null }); }
+function readProjections(projections) { return { ...emptyOmsManagedReadProjections, ...projections }; }

package/dist/commerce/adapters/managed/oms/types.d.ts

@@ -0,0 +1,2 @@
+export type { CommerceOmsRpcClient, CommerceOmsStore, ManagedQueryBuilder, ManagedQueryResult, RpcError } from "../../../contracts/omsTypes.js";
+export declare function distinctIds(values: Array<string | null | undefined>): string[];

package/dist/commerce/adapters/managed/oms/types.js

@@ -0,0 +1,7 @@
+// Every read in this directory fans out to a follow-up query keyed on ids it just
+// collected, so all three needed the same two steps: drop the rows that carry no
+// id, and ask for each id once. `compact` was the wrong name for that - it also
+// de-duplicates, which the trim-only helpers elsewhere deliberately do not.
+export function distinctIds(values) {
+    return [...new Set(values.filter((value) => Boolean(value)))];
+}

package/dist/commerce/checkoutCommandSchemas.d.ts

@@ -0,0 +1,89 @@
+import { z } from "zod";
+export declare const CHECKOUT_COMMAND_V1 = "commerce.checkout_command.v1";
+export declare const REFERENCE_CHECKOUT_V1 = "commerce.reference_checkout.v1";
+export declare function createCheckoutCommandSchemas<IntentStatus extends z.ZodType<string>, AttemptStatus extends z.ZodType<string>>(schemas: {
+    sku: z.ZodType<string, string>;
+    paymentIntentStatus: IntentStatus;
+    paymentAttemptStatus: AttemptStatus;
+}): {
+    checkoutCommandV1Schema: z.ZodObject<{
+        version: z.ZodLiteral<"commerce.checkout_command.v1">;
+        idempotencyKey: z.ZodString;
+        mode: z.ZodEnum<{
+            one_time: "one_time";
+            subscription: "subscription";
+        }>;
+        lines: z.ZodArray<z.ZodObject<{
+            sku: z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+            quantity: z.ZodNumber;
+        }, z.core.$strict>>;
+        customer: z.ZodObject<{
+            firstName: z.ZodString;
+            lastName: z.ZodString;
+            email: z.ZodString;
+            phone: z.ZodString;
+        }, z.core.$strict>;
+        shippingAddress: z.ZodObject<{
+            street: z.ZodString;
+            postalCode: z.ZodString;
+            city: z.ZodString;
+            country: z.ZodString;
+        }, z.core.$strict>;
+        currency: z.ZodString;
+        cadenceDays: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    referenceCheckoutRequestSchema: z.ZodObject<{
+        command: z.ZodObject<{
+            version: z.ZodLiteral<"commerce.checkout_command.v1">;
+            idempotencyKey: z.ZodString;
+            mode: z.ZodEnum<{
+                one_time: "one_time";
+                subscription: "subscription";
+            }>;
+            lines: z.ZodArray<z.ZodObject<{
+                sku: z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+                quantity: z.ZodNumber;
+            }, z.core.$strict>>;
+            customer: z.ZodObject<{
+                firstName: z.ZodString;
+                lastName: z.ZodString;
+                email: z.ZodString;
+                phone: z.ZodString;
+            }, z.core.$strict>;
+            shippingAddress: z.ZodObject<{
+                street: z.ZodString;
+                postalCode: z.ZodString;
+                city: z.ZodString;
+                country: z.ZodString;
+            }, z.core.$strict>;
+            currency: z.ZodString;
+            cadenceDays: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    referenceCheckoutResponseSchema: z.ZodObject<{
+        version: z.ZodLiteral<"commerce.reference_checkout.v1">;
+        orderId: z.ZodGUID;
+        clientId: z.ZodGUID;
+        paymentIntentId: z.ZodGUID;
+        paymentAttemptId: z.ZodNullable<z.ZodGUID>;
+        paymentStatus: IntentStatus;
+        paymentAttemptStatus: z.ZodNullable<AttemptStatus>;
+        replayed: z.ZodBoolean;
+        total: z.ZodObject<{
+            amountMinor: z.ZodNumber;
+            currency: z.ZodString;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+};
+/**
+ * The persistence result deliberately carries only IDs already owned by the
+ * composed persistence adapter. A subject is optional for a generic checkout.
+ */
+export interface CheckoutCommandPersistenceResult {
+    idempotencyKey: string;
+    clientId: string;
+    subjectId: string | null;
+    shippingAddressId: string;
+    replayed: boolean;
+}
+export type CheckoutCommandV1 = z.output<ReturnType<typeof createCheckoutCommandSchemas>["checkoutCommandV1Schema"]>;

package/dist/commerce/checkoutCommandSchemas.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { commerceIdempotencyKeySchema } from "./contractPrimitives.js";
+export const CHECKOUT_COMMAND_V1 = "commerce.checkout_command.v1";
+export const REFERENCE_CHECKOUT_V1 = "commerce.reference_checkout.v1";
+const isoCurrencySchema = z.string().regex(/^[A-Z]{3}$/);
+export function createCheckoutCommandSchemas(schemas) {
+    const checkoutCommandV1Schema = z
+        .object({
+        version: z.literal(CHECKOUT_COMMAND_V1),
+        idempotencyKey: commerceIdempotencyKeySchema,
+        mode: z.enum(["one_time", "subscription"]),
+        lines: z.array(z.object({
+            sku: schemas.sku,
+            quantity: z.number().int().positive().max(99),
+        }).strict()).min(1).max(50),
+        customer: z.object({
+            firstName: z.string().trim().min(1).max(80),
+            lastName: z.string().trim().min(1).max(80),
+            email: z.string().trim().email().max(160),
+            phone: z.string().trim().min(6).max(32),
+        }).strict(),
+        shippingAddress: z.object({
+            street: z.string().trim().min(3).max(160),
+            postalCode: z.string().trim().min(3).max(16),
+            city: z.string().trim().min(2).max(120),
+            country: z.string().trim().regex(/^[A-Z]{2}$/),
+        }).strict(),
+        currency: isoCurrencySchema,
+        cadenceDays: z.number().int().positive().max(120).optional(),
+    })
+        .strict()
+        .superRefine((command, ctx) => {
+        if (command.mode === "subscription" && command.cadenceDays === undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "subscription checkout command requires cadenceDays",
+                path: ["cadenceDays"],
+            });
+        }
+        if (command.mode === "one_time" && command.cadenceDays !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: "one-time checkout command does not accept cadenceDays",
+                path: ["cadenceDays"],
+            });
+        }
+    });
+    /**
+     * The local reference-store BFF accepts only the neutral command. Payment
+     * provider selection stays inside trusted server composition.
+     */
+    const referenceCheckoutRequestSchema = z.object({
+        command: checkoutCommandV1Schema,
+    }).strict();
+    const referenceCheckoutResponseSchema = z.object({
+        version: z.literal(REFERENCE_CHECKOUT_V1),
+        orderId: z.guid(),
+        clientId: z.guid(),
+        paymentIntentId: z.guid(),
+        paymentAttemptId: z.guid().nullable(),
+        paymentStatus: schemas.paymentIntentStatus,
+        paymentAttemptStatus: schemas.paymentAttemptStatus.nullable(),
+        replayed: z.boolean(),
+        total: z.object({
+            amountMinor: z.number().int().nonnegative(),
+            currency: isoCurrencySchema,
+        }).strict(),
+    }).strict();
+    return { checkoutCommandV1Schema, referenceCheckoutRequestSchema, referenceCheckoutResponseSchema };
+}

package/dist/commerce/checkoutHelpers.d.ts

@@ -0,0 +1,21 @@
+export interface OrderDeliveryContactInput {
+    recipientName: string;
+    contactEmail: string;
+    contactPhone: string;
+    line1: string;
+    line2?: string | null;
+    city: string;
+    postalCode: string;
+    country: string;
+    selectedDelivery?: unknown;
+    deliveryInstructions?: string | null;
+    courierInstructions?: string | null;
+}
+/**
+ * Complete order-owned delivery authority. Profile and address-book rows can
+ * keep serving defaults, but fulfillment must not reconstruct an order's
+ * recipient from those mutable records after checkout.
+ */
+export declare function buildOrderDeliveryContact(input: OrderDeliveryContactInput): Record<string, unknown>;
+export declare function uuidFromOrderRef(orderRef: string): string;
+export declare function messageOf(error: unknown, stage: string): string;

package/dist/commerce/checkoutHelpers.js

@@ -0,0 +1,29 @@
+/**
+ * Complete order-owned delivery authority. Profile and address-book rows can
+ * keep serving defaults, but fulfillment must not reconstruct an order's
+ * recipient from those mutable records after checkout.
+ */
+export function buildOrderDeliveryContact(input) {
+    return {
+        schemaVersion: 1,
+        source: "checkout_submission",
+        revision: 1,
+        recipientName: input.recipientName.trim(),
+        contactEmail: input.contactEmail,
+        contactPhone: input.contactPhone,
+        line1: input.line1,
+        line2: input.line2 ?? null,
+        city: input.city,
+        postalCode: input.postalCode,
+        country: input.country,
+        selectedDelivery: input.selectedDelivery ?? null,
+        deliveryInstructions: input.deliveryInstructions ?? null,
+        courierInstructions: input.courierInstructions ?? null,
+    };
+}
+export function uuidFromOrderRef(orderRef) {
+    return orderRef.replace(/^order_/, "");
+}
+export function messageOf(error, stage) {
+    return error instanceof Error ? `${stage}: ${error.message}` : `${stage}: unknown`;
+}

package/dist/commerce/checkoutResumeSchemas.d.ts

@@ -0,0 +1,158 @@
+import { z } from "zod";
+export declare const CHECKOUT_RESUME_CONTRACT_VERSION = "commerce.checkout_resume.v1";
+export declare const checkoutResumeTokenSchema: z.ZodString;
+export declare const checkoutResumeModeSchema: z.ZodEnum<{
+    one_time: "one_time";
+    subscription: "subscription";
+}>;
+export declare const checkoutResumeCompletionCoreSchema: z.ZodObject<{
+    productSelection: z.ZodDefault<z.ZodBoolean>;
+    cadence: z.ZodDefault<z.ZodBoolean>;
+    account: z.ZodDefault<z.ZodBoolean>;
+    shipping: z.ZodDefault<z.ZodBoolean>;
+    billing: z.ZodDefault<z.ZodBoolean>;
+    payment: z.ZodDefault<z.ZodBoolean>;
+    review: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare function createCheckoutResumeSchemas<Section extends z.ZodType<string>, Redacted extends z.ZodType<string>, Completion extends z.ZodType>(input: {
+    sectionSchema: Section;
+    redactedFieldSchema: Redacted;
+    completionSchema: Completion;
+    productSlugSchema: z.ZodType<string, string>;
+    skuSchema: z.ZodType<string, string>;
+    additionalForbiddenKeys?: readonly string[];
+}): {
+    checkoutResumeDraftStateSchema: z.ZodObject<{
+        version: z.ZodLiteral<"commerce.checkout_resume.v1">;
+        mode: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+            one_time: "one_time";
+            subscription: "subscription";
+        }>>>;
+        cadenceDays: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+        cart: z.ZodDefault<z.ZodObject<{
+            items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                sku: z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+                productSlug: z.ZodDefault<z.ZodNullable<z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>>;
+                variantId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                quantity: z.ZodNumber;
+            }, z.core.$strict>>>;
+        }, z.core.$strict>>;
+        completion: Completion;
+        redactedFields: z.ZodDefault<z.ZodArray<Redacted>>;
+    }, z.core.$strict>;
+    checkoutResumeUpsertRequestSchema: z.ZodObject<{
+        resumeToken: z.ZodOptional<z.ZodString>;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+        lastSectionId: Section;
+        draftState: z.ZodObject<{
+            version: z.ZodLiteral<"commerce.checkout_resume.v1">;
+            mode: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+                one_time: "one_time";
+                subscription: "subscription";
+            }>>>;
+            cadenceDays: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+            cart: z.ZodDefault<z.ZodObject<{
+                items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    sku: z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+                    productSlug: z.ZodDefault<z.ZodNullable<z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>>;
+                    variantId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                    quantity: z.ZodNumber;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>>;
+            completion: Completion;
+            redactedFields: z.ZodDefault<z.ZodArray<Redacted>>;
+        }, z.core.$strict>;
+        ttlMinutes: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>;
+    checkoutResumeReadRequestSchema: z.ZodObject<{
+        resumeToken: z.ZodString;
+    }, z.core.$strict>;
+    checkoutResumeDraftSchema: z.ZodObject<{
+        id: z.ZodGUID;
+        contractVersion: z.ZodLiteral<"commerce.checkout_resume.v1">;
+        lastSectionId: Section;
+        draftState: z.ZodObject<{
+            version: z.ZodLiteral<"commerce.checkout_resume.v1">;
+            mode: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+                one_time: "one_time";
+                subscription: "subscription";
+            }>>>;
+            cadenceDays: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+            cart: z.ZodDefault<z.ZodObject<{
+                items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                    sku: z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+                    productSlug: z.ZodDefault<z.ZodNullable<z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>>;
+                    variantId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                    quantity: z.ZodNumber;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>>;
+            completion: Completion;
+            redactedFields: z.ZodDefault<z.ZodArray<Redacted>>;
+        }, z.core.$strict>;
+        expiresAt: z.ZodString;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        replayed: z.ZodBoolean;
+    }, z.core.$strict>;
+    checkoutResumeUpsertResponseSchema: z.ZodObject<{
+        contractVersion: z.ZodLiteral<"commerce.checkout_resume.v1">;
+        resumeToken: z.ZodString;
+        draft: z.ZodObject<{
+            id: z.ZodGUID;
+            contractVersion: z.ZodLiteral<"commerce.checkout_resume.v1">;
+            lastSectionId: Section;
+            draftState: z.ZodObject<{
+                version: z.ZodLiteral<"commerce.checkout_resume.v1">;
+                mode: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+                    one_time: "one_time";
+                    subscription: "subscription";
+                }>>>;
+                cadenceDays: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+                cart: z.ZodDefault<z.ZodObject<{
+                    items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                        sku: z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+                        productSlug: z.ZodDefault<z.ZodNullable<z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>>;
+                        variantId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                        quantity: z.ZodNumber;
+                    }, z.core.$strict>>>;
+                }, z.core.$strict>>;
+                completion: Completion;
+                redactedFields: z.ZodDefault<z.ZodArray<Redacted>>;
+            }, z.core.$strict>;
+            expiresAt: z.ZodString;
+            createdAt: z.ZodString;
+            updatedAt: z.ZodString;
+            replayed: z.ZodBoolean;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    checkoutResumeReadResponseSchema: z.ZodObject<{
+        contractVersion: z.ZodLiteral<"commerce.checkout_resume.v1">;
+        draft: z.ZodObject<{
+            id: z.ZodGUID;
+            contractVersion: z.ZodLiteral<"commerce.checkout_resume.v1">;
+            lastSectionId: Section;
+            draftState: z.ZodObject<{
+                version: z.ZodLiteral<"commerce.checkout_resume.v1">;
+                mode: z.ZodDefault<z.ZodNullable<z.ZodEnum<{
+                    one_time: "one_time";
+                    subscription: "subscription";
+                }>>>;
+                cadenceDays: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+                cart: z.ZodDefault<z.ZodObject<{
+                    items: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                        sku: z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+                        productSlug: z.ZodDefault<z.ZodNullable<z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>>;
+                        variantId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+                        quantity: z.ZodNumber;
+                    }, z.core.$strict>>>;
+                }, z.core.$strict>>;
+                completion: Completion;
+                redactedFields: z.ZodDefault<z.ZodArray<Redacted>>;
+            }, z.core.$strict>;
+            expiresAt: z.ZodString;
+            createdAt: z.ZodString;
+            updatedAt: z.ZodString;
+            replayed: z.ZodBoolean;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+};