@openlup/platform 0.25.0 → 0.27.0

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

@@ -0,0 +1,67 @@
+import type { z } from "zod";
+import type { HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { CheckoutKind, ConfiguratorIntentPersistencePort, ConfiguratorIntent as NeutralIntent } from "../contracts/index.js";
+import type { OrchestratedCheckoutResult } from "./commercePaidOrderOrchestration.js";
+import type { CheckoutQuoteSnapshot } from "./checkoutQuoteTypes.js";
+import type { CheckoutExecutionProvider } from "./checkoutRuntimeTypes.js";
+import { type CheckoutResumeGuardDeps } from "./commerceCheckoutResumeGuard.js";
+import type { ResolveSavedMethodResult } from "./commerceCheckoutSavedPaymentMethod.js";
+export declare function runBestEffortAccountLink(linkCustomerAccount: (email: string) => Promise<void>, email: string, context?: {
+    trigger: string;
+}): Promise<void>;
+export declare function createCheckoutHandlerHelpers<Intent extends NeutralIntent, Provisioned extends {
+    clientId: string;
+}, Snapshot extends CheckoutQuoteSnapshot, Response>(bindings: {
+    checkoutClientAction(input: {
+        provider: string;
+        status: "paid" | "processing" | "failed";
+        providerClientSecret: string | null;
+        providerRedirectUrl: string | null;
+    }): unknown;
+    responder: BffResponder;
+    responseSchema: z.ZodType<Response>;
+    statusUrl(orderId: string, paymentIntentId: string, clientId: string): string;
+    resolveResumeOpenOrderResponse(input: {
+        deps: CheckoutResumeGuardDeps;
+        clientId: string;
+        checkoutKind: CheckoutKind;
+        intent: Intent;
+        now: () => Date;
+    }): Promise<Response | null>;
+}): {
+    persistCheckoutIdentityOrRespond: (input: {
+        res: HttpResponse;
+        persistencePort: ConfiguratorIntentPersistencePort<Intent, Provisioned>;
+        resumeGuardDeps: CheckoutResumeGuardDeps;
+        intent: Intent;
+        checkoutKind: CheckoutKind;
+        now: () => Date;
+        previewDiagnosticsEnabled: boolean;
+        recordPersistStage: <T>(operation: () => Promise<T>) => Promise<T>;
+    }) => Promise<{
+        kind: "provisioned";
+        provisioned: Provisioned;
+    } | {
+        kind: "responded";
+        outcome: "error" | "rejected";
+    }>;
+    respondToSavedPaymentMethodRejection: (res: HttpResponse, reason: Extract<ResolveSavedMethodResult, {
+        kind: "rejected";
+    }>["reason"]) => void;
+    buildCheckoutSuccessResponse: (input: {
+        orchestrated: OrchestratedCheckoutResult<Snapshot>;
+        paymentProvider: CheckoutExecutionProvider;
+        checkoutKind: CheckoutKind;
+        intent: Intent;
+        clientId: string;
+    }) => Response;
+    respondToProvisionIdentityConflict: (input: {
+        res: HttpResponse;
+        persistencePort: ConfiguratorIntentPersistencePort<Intent, Provisioned>;
+        resumeGuardDeps: CheckoutResumeGuardDeps;
+        intent: Intent;
+        checkoutKind: CheckoutKind;
+        now: () => Date;
+    }) => Promise<void>;
+};

package/dist/commerce/server/commerceCheckoutHandlerHelpers.js

@@ -0,0 +1,155 @@
+import { projectPublicQuoteSnapshot } from "../../pricing/index.js";
+import { CHECKOUT_CONTRACT_VERSION } from "../checkoutSchemas.js";
+import { ConfiguratorIntentPersistenceConflictError } from "./configuratorIntentPersistenceHandler.js";
+import { safeCommerceDiagnosticValue } from "./commerceDiagnostics.js";
+import { subscriptionResponse } from "./commerceCheckoutResumeGuard.js";
+const ACCOUNT_LINK_TIMEOUT_MS = 1500;
+export async function runBestEffortAccountLink(linkCustomerAccount, email, context) {
+    let timeout = null;
+    try {
+        const outcome = await Promise.race([
+            linkCustomerAccount(email).then(() => "completed"),
+            new Promise((resolve) => {
+                timeout = setTimeout(() => resolve("timed_out"), ACCOUNT_LINK_TIMEOUT_MS);
+            }),
+        ]);
+        if (outcome === "timed_out") {
+            console.warn("checkout_account_link_timed_out", JSON.stringify({ ...context }));
+        }
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+export function createCheckoutHandlerHelpers(bindings) {
+    const { sendBffError, sendBffSuccess } = bindings.responder;
+    async function persistCheckoutIdentityOrRespond(input) {
+        const { res, persistencePort, resumeGuardDeps, intent, checkoutKind, now } = input;
+        try {
+            return {
+                kind: "provisioned",
+                provisioned: await input.recordPersistStage(() => persistencePort.persistIntent(intent)),
+            };
+        }
+        catch (error) {
+            if (error instanceof ConfiguratorIntentPersistenceConflictError) {
+                await respondToProvisionIdentityConflict({
+                    res,
+                    persistencePort,
+                    resumeGuardDeps,
+                    intent,
+                    checkoutKind,
+                    now,
+                });
+                return { kind: "responded", outcome: "rejected" };
+            }
+            const provisioningCause = safeCommerceDiagnosticValue(error instanceof Error ? error.message : String(error));
+            console.error("checkout_identity_provisioning_failed", JSON.stringify({ message: provisioningCause }));
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Checkout identity provisioning failed", {
+                details: {
+                    feature: "checkout",
+                    stage: "provision_identity",
+                    ...(input.previewDiagnosticsEnabled && provisioningCause
+                        ? { diagnostic: provisioningCause }
+                        : {}),
+                },
+            });
+            return { kind: "responded", outcome: "error" };
+        }
+    }
+    function respondToSavedPaymentMethodRejection(res, reason) {
+        if (reason === "saved_payment_method_resolver_unavailable") {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Saved payment method resolver is unavailable", {
+                details: { feature: "checkout", reason },
+            });
+            return;
+        }
+        if (reason === "saved_payment_method_session_required") {
+            sendBffError(res, "UNAUTHORIZED", "Customer session required", {
+                details: { feature: "checkout", reason },
+            });
+            return;
+        }
+        if (reason === "saved_payment_method_read_failed") {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Saved payment method read failed", {
+                details: { feature: "checkout", reason },
+            });
+            return;
+        }
+        sendBffError(res, "BAD_REQUEST", "Saved payment method is unavailable", {
+            details: { feature: "checkout", reason },
+        });
+    }
+    function buildCheckoutSuccessResponse(input) {
+        const { orchestrated, paymentProvider, checkoutKind, intent, clientId } = input;
+        const { orderId, paymentIntentId, providerClientSecret, providerPaymentId, providerRedirectUrl, status } = orchestrated;
+        const clientAction = bindings.checkoutClientAction({
+            provider: paymentProvider,
+            status,
+            providerClientSecret,
+            providerRedirectUrl,
+        });
+        const statusUrl = status === "processing"
+            ? bindings.statusUrl(orderId, paymentIntentId, clientId)
+            : undefined;
+        return bindings.responseSchema.parse({
+            contractVersion: CHECKOUT_CONTRACT_VERSION,
+            checkoutKind,
+            orderRef: `order_${orderId}`,
+            orderId,
+            status,
+            paymentIntentId,
+            ...(providerPaymentId ? { providerPaymentId } : {}),
+            clientId,
+            clientAction,
+            ...(statusUrl ? { statusUrl } : {}),
+            subscription: subscriptionResponse(intent, checkoutKind),
+            payment: { requiresReusablePaymentMethod: checkoutKind === "subscription_initial" },
+            authoritativeQuote: projectPublicQuoteSnapshot(orchestrated.quoteSnapshot),
+        });
+    }
+    async function respondToProvisionIdentityConflict(input) {
+        const { res, persistencePort, resumeGuardDeps, intent, checkoutKind, now } = input;
+        const existing = await resolveCompletedIdentity(persistencePort, intent.idempotencyKey);
+        if (existing) {
+            // No `acceptedQuote`: this path runs before any quote, and deliberately so.
+            // (persist-intent updates the identity in place), so what survives to this
+            // point is a double-submit race — same payload, twice — where resuming IS
+            // the duplicate-charge guard. See the parameter's docblock.
+            const resumeResponse = await bindings.resolveResumeOpenOrderResponse({
+                deps: resumeGuardDeps,
+                clientId: existing.clientId,
+                checkoutKind,
+                intent,
+                now,
+            });
+            if (resumeResponse) {
+                sendBffSuccess(res, resumeResponse, { contractVersion: CHECKOUT_CONTRACT_VERSION });
+                return;
+            }
+        }
+        console.warn("checkout_identity_provisioning_conflict", JSON.stringify({ stage: "provision_identity", resumed: false }));
+        sendBffError(res, "CONFLICT", "Checkout already submitted", {
+            details: {
+                feature: "checkout",
+                stage: "provision_identity",
+                reason: "checkout_already_submitted",
+            },
+        });
+    }
+    async function resolveCompletedIdentity(port, idempotencyKey) {
+        if (!port.findCompletedIdentity)
+            return null;
+        try {
+            return await port.findCompletedIdentity(idempotencyKey);
+        }
+        catch (error) {
+            console.warn("checkout_identity_conflict_lookup_failed", JSON.stringify({
+                message: safeCommerceDiagnosticValue(error instanceof Error ? error.message : String(error)),
+            }));
+            return null;
+        }
+    }
+    return { persistCheckoutIdentityOrRespond, respondToSavedPaymentMethodRejection, buildCheckoutSuccessResponse, respondToProvisionIdentityConflict };
+}

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

@@ -0,0 +1,9 @@
+/**
+ * Carries the order id only after inventory may need compensation. A nullable
+ * reason lets the handler distinguish safe conflicts from generic failures.
+ */
+export declare class CheckoutOrchestrationError extends Error {
+    readonly orderIdForCompensation: string | null;
+    readonly reason: string | null;
+    constructor(message: string, orderIdForCompensation: string | null, reason?: string | null);
+}

package/dist/commerce/server/commerceCheckoutOrchestrationError.js

@@ -0,0 +1,14 @@
+/**
+ * Carries the order id only after inventory may need compensation. A nullable
+ * reason lets the handler distinguish safe conflicts from generic failures.
+ */
+export class CheckoutOrchestrationError extends Error {
+    orderIdForCompensation;
+    reason;
+    constructor(message, orderIdForCompensation, reason = null) {
+        super(message);
+        this.name = "CheckoutOrchestrationError";
+        this.orderIdForCompensation = orderIdForCompensation;
+        this.reason = reason;
+    }
+}

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

@@ -0,0 +1,47 @@
+import type { HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { CheckoutKind, ConfiguratorIntent as NeutralIntent } from "../contracts/index.js";
+import type { CommerceQuotePort } from "../ports.js";
+import type { PricingPolicySnapshot } from "../../pricing/index.js";
+import type { CheckoutQuoteSnapshot } from "./checkoutQuoteTypes.js";
+export declare function createPromotionPriceChange<Intent extends NeutralIntent, Provisioned extends {
+    clientId: string;
+}, Request, Snapshot extends CheckoutQuoteSnapshot, Response>(bindings: {
+    responder: BffResponder;
+    buildQuoteRequest(intent: Intent, provisioned: Provisioned, policy?: PricingPolicySnapshot): Request;
+    buildCheckoutPriceChangedResponse(input: {
+        checkoutKind: CheckoutKind;
+        expectedQuote: {
+            totalGross: {
+                amountMinor: number;
+                currency: string;
+            };
+        };
+        authoritativeQuote: Snapshot;
+    }): Response;
+    respondQuoteFailure(res: HttpResponse, error: unknown): boolean;
+}): {
+    rejectMissingPromotionExpectedQuote: (input: {
+        res: HttpResponse;
+        enforced: boolean;
+        intent: Intent;
+        expectedQuote?: unknown;
+    }) => boolean;
+    respondToPromotionCodePriceChange: (input: {
+        res: HttpResponse;
+        quotePort: CommerceQuotePort<Request, Snapshot, import("../../pricing/index.js").CreateQuoteOptions>;
+        intent: Intent;
+        provisioned: Provisioned;
+        checkoutKind: CheckoutKind;
+        expectedQuote?: {
+            totalGross: {
+                amountMinor: number;
+                currency: string;
+            };
+            pricingPolicy?: PricingPolicySnapshot;
+        };
+        resolvePricingPolicy?: (request: Request) => PricingPolicySnapshot | undefined | Promise<PricingPolicySnapshot | undefined>;
+        acceptedQuoteSnapshot: Snapshot | null;
+        recordQuote: <T>(operation: () => Promise<T>) => Promise<T>;
+    }) => Promise<boolean>;
+};

package/dist/commerce/server/commerceCheckoutPromotionPriceChange.js

@@ -0,0 +1,43 @@
+import { CHECKOUT_CONTRACT_VERSION } from "../checkoutSchemas.js";
+import { safeCommerceDiagnosticValue } from "./commerceDiagnostics.js";
+export function createPromotionPriceChange(bindings) {
+    const { sendBffError, sendBffSuccess } = bindings.responder;
+    function rejectMissingPromotionExpectedQuote(input) {
+        if (!input.enforced || input.intent.promoCodes.length === 0 || input.expectedQuote)
+            return false;
+        sendBffError(input.res, "BAD_REQUEST", "Promotion checkout requires an expected quote", {
+            details: { feature: "checkout", reason: "promotion_expected_quote_missing" },
+        });
+        return true;
+    }
+    async function respondToPromotionCodePriceChange(input) {
+        let authoritativeQuote;
+        try {
+            const quoteRequest = bindings.buildQuoteRequest(input.intent, input.provisioned, input.expectedQuote?.pricingPolicy);
+            const pricingPolicy = await input.resolvePricingPolicy?.(quoteRequest);
+            const offerVersion = input.acceptedQuoteSnapshot?.quote.context?.offerVersion;
+            authoritativeQuote = await input.recordQuote(() => input.quotePort.createQuote(quoteRequest, {
+                clientId: input.provisioned.clientId,
+                ...(pricingPolicy ? { pricingPolicy } : {}),
+                ...(offerVersion ? { offerVersion } : {}),
+            }));
+        }
+        catch (error) {
+            if (bindings.respondQuoteFailure(input.res, error))
+                return true;
+            console.error("checkout_promotion_price_changed_requote_failed", safeCommerceDiagnosticValue(error instanceof Error ? error.message : String(error)));
+            sendBffError(input.res, "UPSTREAM_UNAVAILABLE", "Checkout failed", {
+                details: { feature: "checkout", stage: "quote" },
+            });
+            return false;
+        }
+        const expectedQuote = input.expectedQuote ?? {
+            totalGross: input.acceptedQuoteSnapshot?.quote.totalGross ?? authoritativeQuote.quote.totalGross,
+        };
+        sendBffSuccess(input.res, bindings.buildCheckoutPriceChangedResponse({
+            checkoutKind: input.checkoutKind, expectedQuote, authoritativeQuote,
+        }), { contractVersion: CHECKOUT_CONTRACT_VERSION });
+        return true;
+    }
+    return { rejectMissingPromotionExpectedQuote, respondToPromotionCodePriceChange };
+}

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

@@ -0,0 +1,34 @@
+import type { HttpRequest } from "../../http/index.js";
+export interface CheckoutPaymentExecution {
+    provider: string;
+    flow?: string;
+}
+export declare function createCheckoutClientAction<Embedded extends string>(embeddedProvider: Embedded, redirectProvider: string): (input: {
+    provider: string;
+    status: "paid" | "processing" | "failed";
+    providerClientSecret: string | null;
+    providerRedirectUrl: string | null;
+}) => {
+    kind: "none";
+    url?: undefined;
+} | {
+    clientSecret?: string | undefined;
+    kind: "provider_embedded";
+    provider: Embedded;
+    url?: undefined;
+} | {
+    kind: "redirect";
+    url: string;
+};
+export declare function providerPayerFromRequest(req: HttpRequest, intent: {
+    contact: {
+        email: string;
+        firstName: string;
+        lastName: string;
+    };
+}): {
+    email: string;
+    name: string;
+    ip: string | null;
+    userAgent: string | null;
+};

package/dist/commerce/server/commerceCheckoutProviderPayment.js

@@ -0,0 +1,37 @@
+export function createCheckoutClientAction(embeddedProvider, redirectProvider) {
+    function checkoutClientAction(input) {
+        if (input.status !== "processing")
+            return { kind: "none" };
+        if (input.provider === embeddedProvider) {
+            return {
+                kind: "provider_embedded",
+                provider: embeddedProvider,
+                ...(input.providerClientSecret ? { clientSecret: input.providerClientSecret } : {}),
+            };
+        }
+        if (input.provider === redirectProvider && input.providerRedirectUrl) {
+            return { kind: "redirect", url: input.providerRedirectUrl };
+        }
+        return { kind: "none" };
+    }
+    return checkoutClientAction;
+}
+export function providerPayerFromRequest(req, intent) {
+    return {
+        email: intent.contact.email,
+        name: `${intent.contact.firstName} ${intent.contact.lastName}`.trim(),
+        ip: firstHeader(req.headers["x-forwarded-for"])?.split(",")[0]?.trim() ??
+            firstHeader(req.headers["x-real-ip"]) ??
+            null,
+        userAgent: firstHeader(req.headers["user-agent"]) ?? null,
+    };
+}
+function firstHeader(value) {
+    if (typeof value === "string" && value.trim())
+        return value.trim();
+    if (Array.isArray(value)) {
+        const first = value.find((entry) => entry.trim());
+        return first?.trim() ?? null;
+    }
+    return null;
+}

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

@@ -0,0 +1,62 @@
+import type { z } from "zod";
+import { type PricingPolicySnapshot } from "../../pricing/index.js";
+import type { CheckoutKind, ConfiguratorIntent as NeutralIntent } from "../contracts/index.js";
+import type { CommerceQuotePort } from "../ports.js";
+import { type CheckoutOfferPolicyPort } from "./checkoutOfferPolicyPort.js";
+import type { CheckoutQuoteSnapshot, ExpectedCheckoutQuote } from "./checkoutQuoteTypes.js";
+import type { StarterOfferGuardResult } from "./commerceStarterOfferGuard.js";
+export type CheckoutQuoteGuardResult<Snapshot, Response> = {
+    kind: "accepted";
+    quoteSnapshot: Snapshot;
+} | {
+    kind: "price_changed";
+    response: Response;
+    starterOfferRejection?: string;
+};
+export declare function createCheckoutQuoteGuard<Intent extends NeutralIntent, Provisioned extends {
+    clientId: string;
+}, Request, Snapshot extends CheckoutQuoteSnapshot, Response, Terms, Plan>(bindings: {
+    buildQuoteRequest(intent: Intent, provisioned: Provisioned, policy?: PricingPolicySnapshot): Request;
+    responseSchema: z.ZodType<Response>;
+    resolveStarterOfferGuard(input: {
+        flagEnabled: boolean;
+        intent: Intent;
+        provisioned: Provisioned;
+        authoritativeQuote: Snapshot;
+        quotePort: CommerceQuotePort<Request, Snapshot, import("../../pricing/index.js").CreateQuoteOptions>;
+        isFirstOrderEligible?: () => Promise<boolean>;
+        termsPort?: Terms;
+        offerVersion?: string;
+    }): Promise<StarterOfferGuardResult<Plan>>;
+    withStarterPackContext(snapshot: Snapshot, plan: Plan | null): Snapshot;
+}): {
+    resolveCheckoutQuoteGuard: (input: {
+        quotePort: CommerceQuotePort<Request, Snapshot, import("../../pricing/index.js").CreateQuoteOptions>;
+        intent: Intent;
+        provisioned: Provisioned;
+        checkoutKind: CheckoutKind;
+        expectedQuote?: ExpectedCheckoutQuote;
+        recordQuoteStage: <T>(operation: () => Promise<T>) => Promise<T>;
+        resolvePricingPolicy?: (request: Request) => PricingPolicySnapshot | undefined | Promise<PricingPolicySnapshot | undefined>;
+        pricingEligibilityClientId?: string | null;
+        verifyPromotionAcceptance?: (input: {
+            token: string;
+            request: Request;
+            quote: Snapshot["quote"];
+            expectedTotal: {
+                amountMinor: number;
+                currency: string;
+            };
+        }) => boolean;
+        promotionAcceptanceToken?: string;
+        offerPolicy?: CheckoutOfferPolicyPort<Intent, Snapshot["quote"]>;
+        starterPackEnabled?: () => boolean;
+        isFirstOrderEligible?: () => Promise<boolean>;
+        starterTermsPort?: Terms;
+    }) => Promise<CheckoutQuoteGuardResult<Snapshot, Response>>;
+    buildCheckoutPriceChangedResponse: (input: {
+        checkoutKind: CheckoutKind;
+        expectedQuote: ExpectedCheckoutQuote;
+        authoritativeQuote: Snapshot;
+    }) => Response;
+};

package/dist/commerce/server/commerceCheckoutQuoteGuard.js

@@ -0,0 +1,106 @@
+import { acquisitionExpectationChanged, projectPublicQuoteSnapshot } from "../../pricing/index.js";
+import { hasShippingTerms } from "../../shipping/index.js";
+import { CHECKOUT_CONTRACT_VERSION } from "../checkoutSchemas.js";
+import { resolveCheckoutOffer, withCheckoutOfferContext } from "./checkoutOfferPolicyPort.js";
+export function createCheckoutQuoteGuard(bindings) {
+    async function resolveCheckoutQuoteGuard(input) {
+        const { quotePort, intent, provisioned, checkoutKind, expectedQuote, recordQuoteStage } = input;
+        const offer = await resolveCheckoutOffer(input.offerPolicy, intent, checkoutKind);
+        const quoteRequest = bindings.buildQuoteRequest(intent, provisioned, expectedQuote?.pricingPolicy);
+        const pricingPolicy = await input.resolvePricingPolicy?.(quoteRequest);
+        const pricingClientId = input.pricingEligibilityClientId ?? provisioned.clientId;
+        const authoritativeQuote = await recordQuoteStage(() => quotePort.createServerAuthoritativeQuote
+            ? quotePort.createServerAuthoritativeQuote(quoteRequest, {
+                clientId: pricingClientId,
+                ...(pricingPolicy ? { pricingPolicy } : {}),
+                ...(offer ? { offerVersion: offer.offerVersion } : {}),
+            })
+            : quotePort.createQuote(quoteRequest, {
+                clientId: pricingClientId,
+                ...(pricingPolicy ? { pricingPolicy } : {}),
+                ...(offer ? { offerVersion: offer.offerVersion } : {}),
+            }));
+        console.info("checkout_promo_eligibility_context", JSON.stringify({ promoEligibilityContext: "resolved_client" }));
+        const hasCurrentV2Promotion = authoritativeQuote.quote.discounts.some((discount) => discount.promotionEngineVersion === "promotion-engine.v2");
+        const requiresPromotionAcceptance = Boolean(input.promotionAcceptanceToken) || hasCurrentV2Promotion
+            || hasShippingTerms(authoritativeQuote.quote)
+            || authoritativeQuote.quote.context?.acquisitionTerms !== undefined;
+        const promotionAcceptanceValid = !requiresPromotionAcceptance || Boolean(expectedQuote && input.promotionAcceptanceToken && input.verifyPromotionAcceptance?.({
+            token: input.promotionAcceptanceToken,
+            request: quoteRequest,
+            quote: authoritativeQuote.quote,
+            expectedTotal: expectedQuote.totalGross,
+        }));
+        const priceAccepted = promotionAcceptanceValid
+            && (!expectedQuote || !quoteTotalChanged(expectedQuote, authoritativeQuote));
+        // The starter guard runs only once the price itself is accepted: a moved total
+        // is already a rejection, and re-quoting a steady package for a basket that is
+        // about to be refused would be pure waste.
+        const starter = priceAccepted
+            ? await bindings.resolveStarterOfferGuard({
+                flagEnabled: input.starterPackEnabled?.() ?? false,
+                intent,
+                provisioned,
+                authoritativeQuote,
+                quotePort,
+                isFirstOrderEligible: input.isFirstOrderEligible,
+                termsPort: input.starterTermsPort,
+                offerVersion: offer?.offerVersion,
+            })
+            : { kind: "absent" };
+        if (priceAccepted && starter.kind !== "rejected") {
+            const persisted = withoutPricingPolicyToken(authoritativeQuote);
+            return {
+                kind: "accepted",
+                quoteSnapshot: await withCheckoutOfferContext(offer, intent, bindings.withStarterPackContext(persisted, starter.kind === "minted" ? starter.plan : null)),
+            };
+        }
+        return {
+            kind: "price_changed",
+            ...(starter.kind === "rejected" ? { starterOfferRejection: starter.reason } : {}),
+            response: buildCheckoutPriceChangedResponse({
+                checkoutKind,
+                expectedQuote: expectedQuote ?? { totalGross: authoritativeQuote.quote.totalGross },
+                authoritativeQuote,
+            }),
+        };
+    }
+    function withoutPricingPolicyToken(snapshot) {
+        const policy = snapshot.quote.context?.pricingPolicy;
+        if (!policy?.pricingPolicyToken)
+            return snapshot;
+        const { pricingPolicyToken: _token, ...persistedPolicy } = policy;
+        return {
+            ...snapshot,
+            quote: {
+                ...snapshot.quote,
+                context: { ...snapshot.quote.context, pricingPolicy: persistedPolicy },
+            },
+        };
+    }
+    function buildCheckoutPriceChangedResponse(input) {
+        return bindings.responseSchema.parse({
+            contractVersion: CHECKOUT_CONTRACT_VERSION,
+            checkoutKind: input.checkoutKind,
+            status: "price_changed",
+            priceChanged: true,
+            expectedQuote: { totalGross: input.expectedQuote.totalGross },
+            authoritativeQuote: projectPublicQuoteSnapshot(input.authoritativeQuote),
+        });
+    }
+    function quoteTotalChanged(expectedQuote, authoritativeQuote) {
+        if (!expectedQuote)
+            return false;
+        const actualPolicy = authoritativeQuote.quote.context?.pricingPolicy;
+        const expectedPolicy = expectedQuote.pricingPolicy;
+        const historicalUnboundV1 = expectedPolicy?.offerPolicyVersion === "commerce.offer-policy.v1"
+            && expectedPolicy.promotionEngineVersion === "promotion-engine.v1"
+            && !expectedPolicy.pricingPolicyToken;
+        return (acquisitionExpectationChanged(expectedQuote.acquisitionTerms, authoritativeQuote.quote.context?.acquisitionTerms) ||
+            expectedQuote.totalGross.amountMinor !== authoritativeQuote.quote.totalGross.amountMinor ||
+            expectedQuote.totalGross.currency !== authoritativeQuote.quote.totalGross.currency ||
+            (expectedPolicy != null && !historicalUnboundV1 && (expectedPolicy.offerPolicyVersion !== actualPolicy?.offerPolicyVersion ||
+                expectedPolicy.promotionEngineVersion !== actualPolicy?.promotionEngineVersion)));
+    }
+    return { resolveCheckoutQuoteGuard, buildCheckoutPriceChangedResponse };
+}

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

@@ -0,0 +1,29 @@
+import type { z } from "zod";
+import type { CommerceCheckoutResumeDraftPort } from "../contracts/ports.js";
+interface ResumeResult {
+    data: unknown;
+    error: {
+        code?: string;
+        message?: string;
+        details?: string;
+    } | null;
+}
+interface ResumeQuery {
+    select(columns: string): ResumeQuery;
+    eq(column: string, value: unknown): ResumeQuery;
+    is(column: string, value: null): ResumeQuery;
+    gt(column: string, value: string): ResumeQuery;
+    single(): PromiseLike<ResumeResult>;
+    maybeSingle(): PromiseLike<ResumeResult>;
+}
+export interface CommerceCheckoutResumeClient {
+    from(table: "commerce_checkout_resume_drafts"): {
+        select(columns: string): ResumeQuery;
+        update(payload: Record<string, unknown>): ResumeQuery;
+        insert(payload: Record<string, unknown>): ResumeQuery;
+    };
+}
+export declare function createCommerceCheckoutResumeQueryPort<Section, State extends {
+    redactedFields: unknown;
+}, Draft>(client: CommerceCheckoutResumeClient, draftSchema: z.ZodType<Draft>): CommerceCheckoutResumeDraftPort<Section, State, Draft>;
+export {};