@openlup/platform 0.26.0 → 0.28.0

package/dist/commerce/outboxOrderDraftEmailPorts.d.ts

@@ -0,0 +1,207 @@
+export declare const OUTBOX_ORDER_CONFIRMATION_TEMPLATE_SLUG = "commerce-order-confirmation";
+export interface OrderRecipient {
+    email: string;
+    firstName: string | null;
+    country?: string | null;
+    contextName?: string | null;
+}
+export interface OrderRecipientPort {
+    resolve(orderUuid: string, signal: AbortSignal): Promise<OrderRecipient | null>;
+}
+export interface OrderPaymentLifecycleState {
+    orderStatus: string | null;
+    paymentStatus: string | null;
+    paymentUpdatedAt?: string | null;
+    hasPayment: boolean;
+    /** The activation sweep abandoned this order's provisional subscription: it writes
+     * `cancelled`, not `expired`, so the expired-checkout gate needs this to tell a swept
+     * first subscription from any other cancellation. Absent for every one-time order. */
+    subscriptionActivationAbandoned?: boolean;
+}
+export interface OrderPaymentLifecyclePort {
+    read(orderUuid: string, signal: AbortSignal): Promise<OrderPaymentLifecycleState | null>;
+}
+export interface OrderEmailLineItem {
+    name: string;
+    quantity: number;
+    lineTotalLabel: string;
+}
+export interface OrderEmailTotals {
+    subtotalLabel: string | null;
+    discountLabel: string | null;
+    totalLabel: string;
+    firstSubscription?: {
+        discountPercent?: number;
+        catalogLabel: string;
+        productPayableLabel: string;
+        shippingLabel: string | null;
+        shippingFree: boolean;
+    };
+}
+export interface OrderConfirmationEmailInput<Locale extends string = string> {
+    to: string;
+    firstName: string | null;
+    contextName?: string | null;
+    orderId: string;
+    outboxEventId: string;
+    items: OrderEmailLineItem[];
+    totals: OrderEmailTotals | null;
+    locale?: Locale;
+    signal: AbortSignal;
+}
+export interface TransactionalEmailSendOutcome {
+    ok: boolean;
+    messageId: string | null;
+    httpStatus: number;
+    providerError: string | null;
+    aborted: boolean;
+    providerErrorCode?: string | null;
+    /** Terminal intentional non-send; callers must not count it as sent. */
+    skipReason?: "admin_disabled" | "egress_suppressed" | null;
+}
+export declare const OUTBOX_ORDER_PAID_TEMPLATE_SLUG = "commerce-order-paid";
+export declare const OUTBOX_CHECKOUT_RECOVERY_TEMPLATE_SLUG = "commerce-checkout-recovery";
+export interface CheckoutRecoveryEmailInput<Locale extends string = string> {
+    to: string;
+    firstName: string | null;
+    contextName?: string | null;
+    orderId: string;
+    recoveryToken: string;
+    mode: string;
+    reminderHours: number;
+    linkSource?: "buyer_hatch";
+    outboxEventId: string;
+    locale?: Locale;
+    signal: AbortSignal;
+}
+export interface OrderPaidRawLine {
+    /** Frozen historical display label, or null for sparse legacy snapshots. */
+    label: string | null;
+    quantity: number;
+    lineTotalMinor: number;
+}
+export interface OrderPaidRawData {
+    currency: string;
+    subtotalMinor: number;
+    discountMinor: number;
+    totalMinor: number;
+    presentation?: unknown;
+    lines: OrderPaidRawLine[];
+}
+export interface OrderPaidLinesPort {
+    read(orderUuid: string, signal: AbortSignal): Promise<OrderPaidRawData | null>;
+}
+export interface OrderPaidConfirmationEmailInput<Locale extends string = string> {
+    to: string;
+    firstName: string | null;
+    contextName?: string | null;
+    orderId: string;
+    mode: string;
+    outboxEventId: string;
+    items: OrderEmailLineItem[];
+    totals: OrderEmailTotals | null;
+    parcelNote?: string | null;
+    locale?: Locale;
+    signal: AbortSignal;
+}
+export declare const OUTBOX_PAYMENT_FAILED_TEMPLATE_SLUG = "commerce-payment-failed";
+export interface PaymentFailedEmailInput<Locale extends string = string> {
+    to: string;
+    firstName: string | null;
+    orderId: string;
+    amountLabel: string | null;
+    recoveryToken: string;
+    mode: string;
+    outboxEventId: string;
+    locale?: Locale;
+    signal: AbortSignal;
+}
+export declare const OUTBOX_CHECKOUT_EXPIRED_TEMPLATE_SLUG = "commerce-checkout-expired";
+export interface CheckoutExpiredEmailInput<Locale extends string = string> {
+    to: string;
+    firstName: string | null;
+    orderId: string;
+    amountLabel: string | null;
+    /** Raw checkout-recovery token, emitted only in the outbox payload: the database
+     * stores only its hash, and the host renderer builds the recovery link. */
+    recoveryToken?: string | null;
+    outboxEventId: string;
+    locale?: Locale;
+    signal: AbortSignal;
+}
+export declare const OUTBOX_ORDER_CANCELED_TEMPLATE_SLUG = "commerce-order-canceled";
+export interface OrderCanceledEmailInput<Locale extends string = string> {
+    to: string;
+    firstName: string | null;
+    orderId: string;
+    amountLabel: string | null;
+    outboxEventId: string;
+    locale?: Locale;
+    signal: AbortSignal;
+}
+export declare const OUTBOX_ORDER_REFUNDED_TEMPLATE_SLUG = "commerce-order-refunded";
+export interface OrderRefundedEmailInput<Locale extends string = string> {
+    to: string;
+    firstName: string | null;
+    orderId: string;
+    amountLabel: string | null;
+    outboxEventId: string;
+    locale?: Locale;
+    signal: AbortSignal;
+}
+export declare const OUTBOX_SHIPMENT_DISPATCHED_TEMPLATE_SLUG = "commerce-shipment-dispatched";
+export interface ShipmentDispatchedEmailInput<Locale extends string = string> {
+    to: string;
+    firstName: string | null;
+    contextName?: string | null;
+    orderId: string;
+    trackingNumber: string | null;
+    trackingUrl: string | null;
+    outboxEventId: string;
+    locale?: Locale;
+    signal: AbortSignal;
+}
+export declare const OUTBOX_SHIPMENT_DELIVERED_TEMPLATE_SLUG = "commerce-shipment-delivered";
+export interface ShipmentDeliveredEmailInput<Locale extends string = string> {
+    to: string;
+    firstName: string | null;
+    contextName?: string | null;
+    orderId: string;
+    outboxEventId: string;
+    locale?: Locale;
+    signal: AbortSignal;
+}
+export declare const OUTBOX_SHIPMENT_EXCEPTION_TEMPLATE_SLUG = "commerce-shipment-exception";
+export interface ShipmentExceptionEmailInput<Locale extends string = string> {
+    to: string;
+    firstName: string | null;
+    orderId: string;
+    outboxEventId: string;
+    locale?: Locale;
+    signal: AbortSignal;
+}
+export declare const OUTBOX_RETURN_APPROVED_TEMPLATE_SLUG = "commerce-return-approved";
+export declare const OUTBOX_RETURN_REJECTED_TEMPLATE_SLUG = "commerce-return-rejected";
+export interface ReturnDecisionEmailInput<Locale extends string = string> {
+    to: string;
+    firstName: string | null;
+    orderId: string;
+    outboxEventId: string;
+    locale?: Locale;
+    signal: AbortSignal;
+}
+export interface TransactionalEmailPort<Locale extends string = string> {
+    findExistingSend(templateSlug: string, outboxEventId: string): Promise<boolean>;
+    sendReturnApprovedNotice(input: ReturnDecisionEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+    sendReturnRejectedNotice(input: ReturnDecisionEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+    sendOrderConfirmation(input: OrderConfirmationEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+    sendCheckoutRecovery(input: CheckoutRecoveryEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+    sendOrderPaidConfirmation(input: OrderPaidConfirmationEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+    sendPaymentFailedNotice(input: PaymentFailedEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+    sendCheckoutExpiredNotice(input: CheckoutExpiredEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+    sendOrderCanceledNotice(input: OrderCanceledEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+    sendOrderRefundedNotice(input: OrderRefundedEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+    sendShipmentDispatchedNotice(input: ShipmentDispatchedEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+    sendShipmentDeliveredNotice(input: ShipmentDeliveredEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+    sendShipmentExceptionNotice(input: ShipmentExceptionEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+}

package/dist/commerce/outboxOrderDraftEmailPorts.js

@@ -0,0 +1,12 @@
+export const OUTBOX_ORDER_CONFIRMATION_TEMPLATE_SLUG = "commerce-order-confirmation";
+export const OUTBOX_ORDER_PAID_TEMPLATE_SLUG = "commerce-order-paid";
+export const OUTBOX_CHECKOUT_RECOVERY_TEMPLATE_SLUG = "commerce-checkout-recovery";
+export const OUTBOX_PAYMENT_FAILED_TEMPLATE_SLUG = "commerce-payment-failed";
+export const OUTBOX_CHECKOUT_EXPIRED_TEMPLATE_SLUG = "commerce-checkout-expired";
+export const OUTBOX_ORDER_CANCELED_TEMPLATE_SLUG = "commerce-order-canceled";
+export const OUTBOX_ORDER_REFUNDED_TEMPLATE_SLUG = "commerce-order-refunded";
+export const OUTBOX_SHIPMENT_DISPATCHED_TEMPLATE_SLUG = "commerce-shipment-dispatched";
+export const OUTBOX_SHIPMENT_DELIVERED_TEMPLATE_SLUG = "commerce-shipment-delivered";
+export const OUTBOX_SHIPMENT_EXCEPTION_TEMPLATE_SLUG = "commerce-shipment-exception";
+export const OUTBOX_RETURN_APPROVED_TEMPLATE_SLUG = "commerce-return-approved";
+export const OUTBOX_RETURN_REJECTED_TEMPLATE_SLUG = "commerce-return-rejected";

package/dist/commerce/paymentContinuation.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export declare const checkoutContinuationJourneyIdSchema: z.ZodString;
+/** Shared client/server lifetime; terminal payment status still invalidates continuation. */
+export declare const CHECKOUT_PAYMENT_CONTINUATION_TTL_SECONDS: number;

package/dist/commerce/paymentContinuation.js

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export const checkoutContinuationJourneyIdSchema = z.string().regex(/^checkout:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i);
+/** Shared client/server lifetime; terminal payment status still invalidates continuation. */
+export const CHECKOUT_PAYMENT_CONTINUATION_TTL_SECONDS = 45 * 60;

package/dist/commerce/ports.d.ts

@@ -0,0 +1,8 @@
+/** Host-owned quote options are extended only with a server-bound offer. */
+export type CreateQuoteOptions<Options extends object> = Options & {
+    offerVersion?: string;
+};
+export interface CommerceQuotePort<Request, Response, Options extends object> {
+    createQuote(request: Request, options?: CreateQuoteOptions<Options>): Promise<Response>;
+    createServerAuthoritativeQuote?(request: Request, options?: CreateQuoteOptions<Options>): Promise<Response>;
+}

package/dist/commerce/ports.js

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

package/dist/commerce/recoveryDestination.d.ts

@@ -0,0 +1,3 @@
+import type { RecoveryDestinationPolicyInput, RecoveryDestinationIntent } from "./contracts/index.js";
+export declare function resolveRecoveryDestination(input: RecoveryDestinationPolicyInput): RecoveryDestinationIntent;
+export declare function hasSubscriptionRecoveryContext(input: Pick<RecoveryDestinationPolicyInput, "orderMode" | "hasOrderSubscription" | "requestedSubscriptionContext" | "clientHasLiveOrPendingSubscription">): boolean;

package/dist/commerce/recoveryDestination.js

@@ -0,0 +1,17 @@
+export function resolveRecoveryDestination(input) {
+    if (input.source === "subscription_dunning")
+        return "account_payment_recovery";
+    if (input.state === "recoverable")
+        return "checkout_recovery";
+    if (hasSubscriptionRecoveryContext(input))
+        return "account_payment_recovery";
+    if (input.state === "terminal_expired")
+        return "fresh_checkout";
+    return "fresh_checkout";
+}
+export function hasSubscriptionRecoveryContext(input) {
+    return input.orderMode === "subscription_cycle" ||
+        input.hasOrderSubscription === true ||
+        input.requestedSubscriptionContext === true ||
+        input.clientHasLiveOrPendingSubscription === true;
+}

package/dist/commerce/runtimeErrors.d.ts

@@ -0,0 +1,8 @@
+export declare class CommerceRuntimeConflictError extends Error {
+    readonly details: Record<string, unknown>;
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+export declare class CommerceRuntimePersistenceError extends Error {
+    readonly details: Record<string, unknown>;
+    constructor(message?: string, details?: Record<string, unknown>);
+}

package/dist/commerce/runtimeErrors.js

@@ -0,0 +1,16 @@
+export class CommerceRuntimeConflictError extends Error {
+    details;
+    constructor(message = "Commerce runtime conflict", details = {}) {
+        super(message);
+        this.name = "CommerceRuntimeConflictError";
+        this.details = details;
+    }
+}
+export class CommerceRuntimePersistenceError extends Error {
+    details;
+    constructor(message = "Commerce runtime persistence failed", details = {}) {
+        super(message);
+        this.name = "CommerceRuntimePersistenceError";
+        this.details = details;
+    }
+}

package/dist/commerce/salesChannelEnvelope.d.ts

@@ -0,0 +1,20 @@
+export interface CommerceSalesChannelEnvelope {
+    sourceKind: string | null;
+    sourceChannelSlug: string | null;
+    sourceOrderRef: string | null;
+}
+export interface CommerceSalesChannelRow {
+    source_kind?: string | null;
+    source_order_ref?: string | null;
+    sales_channels?: {
+        slug: string | null;
+    } | null;
+}
+export declare function projectCommerceSalesChannelEnvelope(row: CommerceSalesChannelRow): CommerceSalesChannelEnvelope;
+/** Host-bound read only; the inventory owner supplies exposure semantics. */
+export type CommerceChannelExposureReadPort = (skuId: string, signal: AbortSignal) => Promise<number>;
+export interface OrderBuyerCommsPolicy {
+    sourceKind: string;
+    buyerCommsOwner: string;
+}
+export declare function platformOwnsBuyerEmail(policy: OrderBuyerCommsPolicy | null): boolean;

package/dist/commerce/salesChannelEnvelope.js

@@ -0,0 +1,7 @@
+export function projectCommerceSalesChannelEnvelope(row) {
+    return { sourceKind: row.source_kind ?? null, sourceChannelSlug: row.sales_channels?.slug ?? null,
+        sourceOrderRef: row.source_order_ref ?? null };
+}
+export function platformOwnsBuyerEmail(policy) {
+    return policy === null || policy.buyerCommsOwner !== "channel";
+}

package/dist/commerce/schemas.d.ts

@@ -0,0 +1,174 @@
+import { z } from "zod";
+/** Preserve pricing validation and let the host extend cart locale policy. */
+export declare function createCommerceSchemas<Line extends z.ZodType, Currency extends z.ZodType<string>, Money extends z.ZodType, Quote extends z.ZodType, Version extends string>(input: {
+    cartLineInputSchema: Line;
+    commerceCurrencySchema: Currency;
+    commerceMoneySchema: Money;
+    createQuoteResponseSchema: Quote;
+    contractVersion: Version;
+}): {
+    createCartRequestSchema: z.ZodObject<{
+        lines: z.ZodArray<Line>;
+        clientId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    cartDraftSchema: z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<{
+            draft: "draft";
+        }>;
+        lines: z.ZodArray<Line>;
+        currency: Currency;
+    }, z.core.$strip>;
+    createCartResponseSchema: z.ZodObject<{
+        contractVersion: z.ZodLiteral<Version>;
+        cart: z.ZodObject<{
+            id: z.ZodString;
+            status: z.ZodEnum<{
+                draft: "draft";
+            }>;
+            lines: z.ZodArray<Line>;
+            currency: Currency;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    createCheckoutRequestSchema: z.ZodObject<{
+        cartId: z.ZodString;
+        successUrl: z.ZodString;
+        cancelUrl: z.ZodString;
+        idempotencyKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    createCheckoutResponseSchema: z.ZodObject<{
+        contractVersion: z.ZodLiteral<Version>;
+        checkout: z.ZodObject<{
+            id: z.ZodString;
+            cartId: z.ZodString;
+            status: z.ZodEnum<{
+                not_configured: "not_configured";
+                created: "created";
+                expired: "expired";
+            }>;
+            redirectUrl: z.ZodNullable<z.ZodString>;
+            paymentProviderSessionId: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    orderDraftSummarySchema: z.ZodObject<{
+        orderId: z.ZodString;
+        status: z.ZodEnum<{
+            draft: "draft";
+        }>;
+        paymentStatus: z.ZodLiteral<"not_started">;
+        idempotencyKey: z.ZodString;
+        quoteSnapshot: Quote;
+        replayed: z.ZodBoolean;
+    }, z.core.$strip>;
+    createOrderDraftRequestSchema: z.ZodObject<{
+        idempotencyKey: z.ZodString;
+        quoteSnapshot: Quote;
+    }, z.core.$strip>;
+    createOrderDraftResponseSchema: z.ZodObject<{
+        contractVersion: z.ZodLiteral<Version>;
+        orderDraft: z.ZodObject<{
+            orderId: z.ZodString;
+            status: z.ZodEnum<{
+                draft: "draft";
+            }>;
+            paymentStatus: z.ZodLiteral<"not_started">;
+            idempotencyKey: z.ZodString;
+            quoteSnapshot: Quote;
+            replayed: z.ZodBoolean;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    orderSummarySchema: z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<{
+            failed: "failed";
+            cancelled: "cancelled";
+            paid: "paid";
+            pending_payment: "pending_payment";
+            draft: "draft";
+            expired: "expired";
+            fulfillment_pending: "fulfillment_pending";
+            fulfilled: "fulfilled";
+            refunded: "refunded";
+        }>;
+        paymentStatus: z.ZodEnum<{
+            requires_action: "requires_action";
+            failed: "failed";
+            paid: "paid";
+            expired: "expired";
+            refunded: "refunded";
+            not_started: "not_started";
+            processing: "processing";
+            partially_refunded: "partially_refunded";
+            disputed: "disputed";
+        }>;
+        total: z.ZodNullable<Money>;
+        lines: z.ZodArray<Line>;
+    }, z.core.$strip>;
+    orderReadResponseSchema: z.ZodObject<{
+        contractVersion: z.ZodLiteral<Version>;
+        order: z.ZodObject<{
+            id: z.ZodString;
+            status: z.ZodEnum<{
+                failed: "failed";
+                cancelled: "cancelled";
+                paid: "paid";
+                pending_payment: "pending_payment";
+                draft: "draft";
+                expired: "expired";
+                fulfillment_pending: "fulfillment_pending";
+                fulfilled: "fulfilled";
+                refunded: "refunded";
+            }>;
+            paymentStatus: z.ZodEnum<{
+                requires_action: "requires_action";
+                failed: "failed";
+                paid: "paid";
+                expired: "expired";
+                refunded: "refunded";
+                not_started: "not_started";
+                processing: "processing";
+                partially_refunded: "partially_refunded";
+                disputed: "disputed";
+            }>;
+            total: z.ZodNullable<Money>;
+            lines: z.ZodArray<Line>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    paymentSummarySchema: z.ZodObject<{
+        id: z.ZodString;
+        orderId: z.ZodString;
+        status: z.ZodEnum<{
+            requires_action: "requires_action";
+            failed: "failed";
+            paid: "paid";
+            expired: "expired";
+            refunded: "refunded";
+            not_started: "not_started";
+            processing: "processing";
+            partially_refunded: "partially_refunded";
+            disputed: "disputed";
+        }>;
+        amount: z.ZodNullable<Money>;
+        providerReference: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    paymentStatusReadResponseSchema: z.ZodObject<{
+        contractVersion: z.ZodLiteral<Version>;
+        payment: z.ZodObject<{
+            id: z.ZodString;
+            orderId: z.ZodString;
+            status: z.ZodEnum<{
+                requires_action: "requires_action";
+                failed: "failed";
+                paid: "paid";
+                expired: "expired";
+                refunded: "refunded";
+                not_started: "not_started";
+                processing: "processing";
+                partially_refunded: "partially_refunded";
+                disputed: "disputed";
+            }>;
+            amount: z.ZodNullable<Money>;
+            providerReference: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+};

package/dist/commerce/schemas.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { cartStatusSchema, checkoutStatusSchema, commerceIdempotencyKeySchema, orderDraftStatusSchema, orderStatusSchema, paymentStatusSchema } from "./contractPrimitives.js";
+/** Preserve pricing validation and let the host extend cart locale policy. */
+export function createCommerceSchemas(input) {
+    const { cartLineInputSchema, commerceCurrencySchema, commerceMoneySchema, createQuoteResponseSchema } = input;
+    const createCartRequestSchema = z.object({
+        lines: z.array(cartLineInputSchema).min(1).max(50),
+        clientId: z.string().trim().min(1).optional(),
+    });
+    const cartDraftSchema = z.object({
+        id: z.string().regex(/^cart_[a-z0-9-]+$/),
+        status: cartStatusSchema,
+        lines: z.array(cartLineInputSchema).min(1),
+        currency: commerceCurrencySchema,
+    });
+    const createCartResponseSchema = z.object({
+        contractVersion: z.literal(input.contractVersion),
+        cart: cartDraftSchema,
+    });
+    const createCheckoutRequestSchema = z.object({
+        cartId: z.string().regex(/^cart_[a-z0-9-]+$/),
+        successUrl: z.string().url(),
+        cancelUrl: z.string().url(),
+        idempotencyKey: z.string().trim().min(8).max(120).optional(),
+    });
+    const createCheckoutResponseSchema = z
+        .object({
+        contractVersion: z.literal(input.contractVersion),
+        checkout: z.object({
+            id: z.string().regex(/^checkout_[a-z0-9-]+$/),
+            cartId: z.string().regex(/^cart_[a-z0-9-]+$/),
+            status: checkoutStatusSchema,
+            redirectUrl: z.string().url().nullable(),
+            paymentProviderSessionId: z.string().trim().min(1).nullable(),
+        }),
+    })
+        .refine(({ checkout }) => checkout.status === "not_configured"
+        ? checkout.redirectUrl === null && checkout.paymentProviderSessionId === null
+        : checkout.redirectUrl !== null, {
+        message: "checkout status must match redirect/provider fields",
+        path: ["checkout"],
+    });
+    const orderDraftSummarySchema = z.object({
+        orderId: z.string().regex(/^order_[a-z0-9-]+$/),
+        status: orderDraftStatusSchema,
+        paymentStatus: z.literal("not_started"),
+        idempotencyKey: commerceIdempotencyKeySchema,
+        quoteSnapshot: createQuoteResponseSchema,
+        replayed: z.boolean(),
+    });
+    const createOrderDraftRequestSchema = z.object({
+        idempotencyKey: commerceIdempotencyKeySchema,
+        quoteSnapshot: createQuoteResponseSchema,
+    });
+    // Customer identity is supplied out of band by trusted composition, never
+    // accepted from the public order-draft request body.
+    const createOrderDraftResponseSchema = z.object({
+        contractVersion: z.literal(input.contractVersion),
+        orderDraft: orderDraftSummarySchema,
+    });
+    const orderSummarySchema = z.object({
+        id: z.string().regex(/^order_[a-z0-9-]+$/),
+        status: orderStatusSchema,
+        paymentStatus: paymentStatusSchema,
+        total: commerceMoneySchema.nullable(),
+        lines: z.array(cartLineInputSchema).min(1),
+    });
+    const orderReadResponseSchema = z.object({
+        contractVersion: z.literal(input.contractVersion),
+        order: orderSummarySchema,
+    });
+    const paymentSummarySchema = z.object({
+        id: z.string().regex(/^payment_[a-z0-9-]+$/),
+        orderId: z.string().regex(/^order_[a-z0-9-]+$/),
+        status: paymentStatusSchema,
+        amount: commerceMoneySchema.nullable(),
+        providerReference: z.string().trim().min(1).nullable(),
+    });
+    const paymentStatusReadResponseSchema = z.object({
+        contractVersion: z.literal(input.contractVersion),
+        payment: paymentSummarySchema,
+    });
+    return { createCartRequestSchema, cartDraftSchema, createCartResponseSchema, createCheckoutRequestSchema, createCheckoutResponseSchema, orderDraftSummarySchema, createOrderDraftRequestSchema, createOrderDraftResponseSchema, orderSummarySchema, orderReadResponseSchema, paymentSummarySchema, paymentStatusReadResponseSchema };
+}

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

@@ -0,0 +1,21 @@
+import type { CheckoutCompensationPort } from "./commerceCheckoutCompensation.js";
+export interface CompensationRpcClient {
+    rpc(functionName: string, args: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: {
+            code?: string;
+        } | null;
+    }>;
+}
+/**
+ * Binds both cancellations to one service-role client. Compositions inject the
+ * result into the inventory reservation port, so the staying domain module
+ * never imports this adapter.
+ */
+export declare function createCheckoutCompensationRpcAdapter(client: CompensationRpcClient): Pick<CheckoutCompensationPort, "cancelAbandonedOrder" | "cancelUnstartedPromotionOrder">;
+export declare function cancelAbandonedCheckout(client: CompensationRpcClient, input: Parameters<CheckoutCompensationPort["cancelAbandonedOrder"]>[0]): Promise<{
+    cancelled: boolean;
+}>;
+export declare function cancelUnstartedPromotionCheckout(client: CompensationRpcClient, input: Parameters<CheckoutCompensationPort["cancelUnstartedPromotionOrder"]>[0]): Promise<{
+    cancelled: boolean;
+}>;

package/dist/commerce/server/checkoutCompensation.js

@@ -0,0 +1,32 @@
+import { CommerceRuntimePersistenceError } from "../runtimeErrors.js";
+/**
+ * Binds both cancellations to one service-role client. Compositions inject the
+ * result into the inventory reservation port, so the staying domain module
+ * never imports this adapter.
+ */
+export function createCheckoutCompensationRpcAdapter(client) {
+    return {
+        cancelAbandonedOrder: (input) => cancelAbandonedCheckout(client, input),
+        cancelUnstartedPromotionOrder: (input) => cancelUnstartedPromotionCheckout(client, input),
+    };
+}
+export async function cancelAbandonedCheckout(client, input) {
+    const { data, error } = await client.rpc("commerce_cancel_abandoned_checkout", {
+        p_idempotency_key: `${input.idempotencyKey}:abandon`,
+        p_order_id: input.orderId,
+        p_reason: input.reason,
+    });
+    if (error)
+        throw new CommerceRuntimePersistenceError("Checkout cancellation RPC failed", { code: error.code });
+    return { cancelled: data?.cancelled === true };
+}
+export async function cancelUnstartedPromotionCheckout(client, input) {
+    const { data, error } = await client.rpc("commerce_cancel_unstarted_promotion_order", {
+        p_idempotency_key: input.idempotencyKey,
+        p_order_id: input.orderId,
+        p_reason: input.reason,
+    });
+    if (error)
+        throw new CommerceRuntimePersistenceError("Promotion cancellation RPC failed", { code: error.code });
+    return { cancelled: data === true };
+}

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

@@ -0,0 +1,17 @@
+export declare function isStockUnavailableCheckoutConflict(error: unknown): boolean;
+export declare function isProviderAttemptInFlightCheckoutConflict(error: unknown): boolean;
+export declare function isJourneyConsumedCheckoutConflict(error: unknown): boolean;
+/**
+ * `start_runtime` conflicts that map to an identical `CONFLICT + reason` response with
+ * no compensation side effect — the FE resumes/handles each by its `reason`. Order is
+ * significant and preserved from the original inline branches. Stock-unavailable is
+ * intentionally NOT here: it additionally cancels the abandoned order, so the handler
+ * keeps that branch inline.
+ */
+export declare const START_RUNTIME_SIMPLE_CONFLICTS: ReadonlyArray<{
+    match: (error: unknown) => boolean;
+    message: string;
+    reason: string;
+}>;
+/** Scoped semantic details only; raw SQLSTATE does not authorize this classification. */
+export declare function isInventoryAdmissionBusy(error: unknown): boolean;