@openlup/platform 0.26.0 → 0.28.0

package/dist/commerce/server/commerceCheckoutFailureHandler.js

@@ -0,0 +1,90 @@
+import { safeCommerceDiagnosticValue } from "./commerceDiagnostics.js";
+import { AcquisitionTermsError } from "../../pricing/index.js";
+import { CheckoutOrchestrationError } from "./commerceCheckoutOrchestrationError.js";
+import { tryCompensate } from "./commerceCheckoutCompensation.js";
+import { checkoutOrchestrationFailureDetails } from "./commerceDiagnostics.js";
+import { CheckoutOfferRefusedError } from "./checkoutOfferPolicyPort.js";
+import { isJourneyConsumedCheckoutConflict, isStockUnavailableCheckoutConflict, START_RUNTIME_SIMPLE_CONFLICTS } from "./checkoutConflictClassifiers.js";
+export function createCheckoutFailureHandler(bindings) {
+    const { sendBffError } = bindings.responder;
+    async function respondToCheckoutFailure(input) {
+        const { error, compensationPort, intent } = input;
+        bindings.logProviderFailure(error);
+        // A prepared provider attempt is money-in-flight, even when the PSP request
+        // threw. Its order can carry a reservation and provisional subscription, so
+        // classify the existing client conflict before generic compensation. Payment
+        // control reconciliation, never a browser retry, determines its outcome.
+        for (const conflict of START_RUNTIME_SIMPLE_CONFLICTS) {
+            if (conflict.match(error)) {
+                sendBffError(input.res, "CONFLICT", conflict.message, {
+                    details: { feature: "checkout", stage: "start_runtime", reason: conflict.reason },
+                });
+                return "rejected";
+            }
+        }
+        if (error instanceof AcquisitionTermsError && bindings.respondQuoteFailure(input.res, error))
+            return "rejected";
+        // Raised by the quote guard before any order draft exists, so there is nothing
+        // to compensate.
+        if (error instanceof CheckoutOfferRefusedError) {
+            sendBffError(input.res, "CONFLICT", "Checkout offer refused", {
+                details: { feature: "checkout", stage: "quote", reason: error.reason },
+            });
+            return "rejected";
+        }
+        if (isStockUnavailableCheckoutConflict(error)) {
+            if (error instanceof CheckoutOrchestrationError && error.orderIdForCompensation) {
+                await tryCompensate(compensationPort, intent.idempotencyKey, error.orderIdForCompensation, { cancellationReason: "checkout_stock_unavailable" });
+            }
+            sendBffError(input.res, "CONFLICT", "Stock unavailable", {
+                details: { feature: "checkout", stage: "start_runtime", reason: "stock_unavailable" },
+            });
+            return "rejected";
+        }
+        if (isJourneyConsumedCheckoutConflict(error)) {
+            // The journey key already finalized an order (completed out-of-band, e.g.
+            // via a recovery link); this submit minted a fresh draft that can never
+            // finalize under that key. Cancel the abandoned draft and tell the client
+            // to rotate its journey key — retrying unrotated can never succeed.
+            if (error instanceof CheckoutOrchestrationError && error.orderIdForCompensation) {
+                await tryCompensate(compensationPort, intent.idempotencyKey, error.orderIdForCompensation, { cancellationReason: "checkout_journey_consumed" });
+            }
+            sendBffError(input.res, "CONFLICT", "Checkout journey already completed", {
+                details: { feature: "checkout", stage: "start_runtime", reason: "journey_consumed" },
+            });
+            return "rejected";
+        }
+        if (error instanceof CheckoutOrchestrationError && error.reason === "inventory_admission_busy") {
+            sendBffError(input.res, "UPSTREAM_UNAVAILABLE", "Inventory admission temporarily unavailable", {
+                details: { feature: "checkout", stage: "start_runtime", reason: "inventory_admission_busy" },
+            });
+            return "error";
+        }
+        if (error instanceof CheckoutOrchestrationError && error.orderIdForCompensation) {
+            await tryCompensate(compensationPort, intent.idempotencyKey, error.orderIdForCompensation);
+        }
+        if (error instanceof CheckoutOrchestrationError &&
+            (error.reason === "promotion_code_price_changed" || error.reason === "acquisition_terms_changed")) {
+            const responded = await bindings.respondToPromotionCodePriceChange({
+                res: input.res,
+                quotePort: input.quotePort,
+                intent,
+                provisioned: input.provisioned,
+                checkoutKind: input.checkoutKind,
+                acceptedQuoteSnapshot: input.acceptedQuoteSnapshot,
+                expectedQuote: input.expectedQuote,
+                resolvePricingPolicy: input.resolvePricingPolicy,
+                recordQuote: input.recordQuote,
+            });
+            return responded ? "rejected" : "error";
+        }
+        const cause = safeCommerceDiagnosticValue(error instanceof Error ? error.message : String(error));
+        const orderId = error instanceof CheckoutOrchestrationError ? error.orderIdForCompensation : null;
+        console.error("checkout_orchestration_failed", JSON.stringify({ message: cause, orderIdForCompensation: orderId }));
+        sendBffError(input.res, "UPSTREAM_UNAVAILABLE", "Checkout failed", {
+            details: checkoutOrchestrationFailureDetails(cause, bindings.previewDiagnosticsEnabled()),
+        });
+        return "error";
+    }
+    return { respondToCheckoutFailure };
+}

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

@@ -0,0 +1,213 @@
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { ConfiguratorIntent, CheckoutKind, CommerceResumableOrderReadPort } from "../contracts/index.js";
+import type { CheckoutContinuationAction } from "./checkoutPaymentContinuationCredential.js";
+import { providerPayerFromRequest } from "./commerceCheckoutProviderPayment.js";
+import type { ResolveSavedMethodResult } from "./commerceCheckoutSavedPaymentMethod.js";
+import type { CheckoutTimingOutcome, CheckoutTimingStage } from "./commerceCheckoutTiming.js";
+import type { CheckoutQuoteSnapshot, ExpectedCheckoutQuote } from "./checkoutQuoteTypes.js";
+import type { OrchestratedCheckoutResult, CheckoutStageRecorder } from "./commercePaidOrderOrchestration.js";
+import type { CheckoutExecutionProvider } from "./checkoutRuntimeTypes.js";
+import type { CheckoutResumeGuardDeps } from "./commerceCheckoutResumeGuard.js";
+interface CheckoutHandlerDependencies {
+    persistencePort: unknown;
+    quotePort: unknown;
+    orderDraftPort: unknown;
+    runtimePort: unknown;
+    compensationPort: unknown;
+    savedPaymentMethodResolverPort?: unknown;
+    customerDefaultsPort?: unknown;
+    resumableOrderPort?: CommerceResumableOrderReadPort;
+    resumeWindowMinutes?: number;
+    linkCustomerAccount?: (email: string) => Promise<void>;
+    verifyPromotionAcceptance?: unknown;
+    promotionAcceptanceEnforced?: boolean;
+    now?: () => Date;
+    resolvePricingPolicy?: unknown;
+    resolvePricingEligibilityClientId?: (email: string) => Promise<string | null>;
+    starterPackEnabled?: () => boolean;
+    isFirstOrderEligible?: (clientId: string | null) => Promise<boolean>;
+    offerPolicy?: unknown;
+    starterTermsPort?: unknown;
+    mintPaymentContinuationCookie?: unknown;
+}
+type RecordOperation = <T>(operation: () => Promise<T>) => Promise<T>;
+interface CheckoutHandlerData<Intent> {
+    intent: Intent;
+    paymentProvider: CheckoutExecutionProvider;
+    paymentAttemptSequence?: number;
+    returnContext: "public" | "account";
+    paymentExecution?: unknown;
+    declaredBankId?: string;
+    invoicePreference: unknown;
+    expectedQuote?: ExpectedCheckoutQuote & {
+        promotionAcceptanceToken?: string;
+    };
+}
+export declare function createCommerceCheckoutHandler<Deps extends CheckoutHandlerDependencies, Intent extends ConfiguratorIntent, Provisioned extends {
+    clientId: string;
+}, Data extends CheckoutHandlerData<Intent>, Snapshot extends CheckoutQuoteSnapshot, Defaults, Result extends OrchestratedCheckoutResult<Snapshot>, Response extends {
+    status: string;
+    clientAction?: CheckoutContinuationAction;
+}, MethodKind extends string = string, RecurringModel extends string = string>(bindings: {
+    responder: BffResponder;
+    mintPaymentContinuationOnFreshAction(input: {
+        mint?: Deps["mintPaymentContinuationCookie"];
+        res: HttpResponse;
+        journeyId: string;
+        clientId: string;
+        requestRail: string;
+        response: Response;
+        result: Result;
+    }): void;
+    mintCheckoutRefusalContinuation(input: {
+        mint?: Deps["mintPaymentContinuationCookie"];
+        res: HttpResponse;
+        journeyId: string;
+        clientId: string;
+        requestRail: string;
+        response: Response;
+        result: Result;
+    }): void;
+    createCheckoutTimingLogger(req: HttpRequest): {
+        record: <T>(stage: CheckoutTimingStage, operation: () => Promise<T>) => Promise<T>;
+        log(stage: CheckoutTimingStage, outcome: CheckoutTimingOutcome): void;
+    };
+    previewCheckoutDiagnosticsEnabled(): boolean;
+    admitCheckoutRequest(input: {
+        req: HttpRequest;
+        res: HttpResponse;
+        deps: Deps;
+        record: <T>(stage: "rate_limit" | "risk_blocklist", operation: () => Promise<T>) => Promise<T>;
+    }): Promise<{
+        kind: "accepted";
+        data: Data;
+        intent: Intent;
+        checkoutKind: CheckoutKind;
+    } | {
+        kind: "responded";
+        outcome: "rejected" | "error";
+    }>;
+    persistCheckoutIdentityOrRespond(input: {
+        res: HttpResponse;
+        persistencePort: Deps["persistencePort"];
+        resumeGuardDeps: CheckoutResumeGuardDeps;
+        intent: Intent;
+        checkoutKind: CheckoutKind;
+        now: () => Date;
+        previewDiagnosticsEnabled: boolean;
+        recordPersistStage: RecordOperation;
+    }): Promise<{
+        kind: "provisioned";
+        provisioned: Provisioned;
+    } | {
+        kind: "responded";
+        outcome: "error" | "rejected";
+    }>;
+    resolveSavedPaymentMethodForCheckout(input: {
+        req: HttpRequest;
+        paymentExecution: Data["paymentExecution"];
+        clientId: string;
+        savedPaymentMethodResolverPort: Deps["savedPaymentMethodResolverPort"];
+        now: () => Date;
+        recordStage: <T>(stage: "payment_method_ref", operation: () => Promise<T>) => Promise<T>;
+    }): Promise<ResolveSavedMethodResult<MethodKind, RecurringModel>>;
+    respondToSavedPaymentMethodRejection(res: HttpResponse, reason: Extract<ResolveSavedMethodResult, {
+        kind: "rejected";
+    }>["reason"]): void;
+    readCheckoutCustomerDefaultsOrRespond(input: {
+        res: HttpResponse;
+        port: Deps["customerDefaultsPort"];
+        clientId: string;
+        checkoutKind: CheckoutKind;
+        recordStage: RecordOperation;
+    }): Promise<{
+        kind: "read";
+        snapshot: Defaults | null;
+    } | {
+        kind: "responded";
+    }>;
+    resolveCheckoutQuoteOrContinuation(input: {
+        quotePort: Deps["quotePort"];
+        intent: Intent;
+        provisioned: Provisioned;
+        deps: CheckoutResumeGuardDeps;
+        invoicePreference: Data["invoicePreference"];
+        now: () => Date;
+        offerPolicy: Deps["offerPolicy"];
+        starterTermsPort: Deps["starterTermsPort"];
+        checkoutKind: CheckoutKind;
+        expectedQuote: Data["expectedQuote"];
+        promotionAcceptanceToken?: string;
+        verifyPromotionAcceptance: Deps["verifyPromotionAcceptance"];
+        recordQuoteStage: RecordOperation;
+        resolvePricingPolicy: Deps["resolvePricingPolicy"];
+        pricingEligibilityClientId?: string | null;
+        starterPackEnabled?: () => boolean;
+        isFirstOrderEligible?: () => Promise<boolean>;
+    }): Promise<{
+        kind: "accepted";
+        quoteSnapshot: Snapshot;
+    } | {
+        kind: "price_changed";
+        response: Response;
+        starterOfferRejection?: string;
+    } | {
+        kind: "resumed";
+        response: Response;
+    }>;
+    resolveResumeOpenOrderResponse(input: {
+        deps: CheckoutResumeGuardDeps;
+        clientId: string;
+        checkoutKind: CheckoutKind;
+        intent: Intent;
+        acceptedQuote: Snapshot["quote"];
+        now: () => Date;
+    }): Promise<Response | null>;
+    orchestratePaidOrder(input: {
+        intent: Intent;
+        provisioned: Provisioned;
+        checkoutKind: CheckoutKind;
+        quotePort: Deps["quotePort"];
+        orderDraftPort: Deps["orderDraftPort"];
+        runtimePort: Deps["runtimePort"];
+        customerDefaultsSnapshot: Defaults | null;
+        paymentProvider: Data["paymentProvider"];
+        paymentAttemptSequence: Data["paymentAttemptSequence"];
+        returnContext: Data["returnContext"];
+        paymentExecution: Data["paymentExecution"];
+        declaredBankId: Data["declaredBankId"];
+        paymentMethodRef?: string;
+        paymentMethodAliasType?: MethodKind;
+        paymentMethodRecurringModel?: RecurringModel;
+        invoicePreference: Data["invoicePreference"];
+        quoteSnapshot: Snapshot;
+        providerPayer: ReturnType<typeof providerPayerFromRequest>;
+        onPaymentStarted?: (event: {
+            email: string;
+        }) => Promise<void>;
+        recordStage: CheckoutStageRecorder;
+        now: () => Date;
+    }): Promise<Result>;
+    buildCheckoutSuccessResponse(input: {
+        orchestrated: Result;
+        paymentProvider: Data["paymentProvider"];
+        checkoutKind: CheckoutKind;
+        intent: Intent;
+        clientId: string;
+    }): Response;
+    respondToCheckoutFailure(input: {
+        error: unknown;
+        compensationPort: Deps["compensationPort"];
+        intent: Intent;
+        res: HttpResponse;
+        quotePort: Deps["quotePort"];
+        provisioned: Provisioned;
+        checkoutKind: CheckoutKind;
+        acceptedQuoteSnapshot: Snapshot | null;
+        expectedQuote: Data["expectedQuote"];
+        resolvePricingPolicy: Deps["resolvePricingPolicy"];
+        recordQuote: RecordOperation;
+    }): Promise<CheckoutTimingOutcome>;
+}): (deps: Deps) => (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export {};

package/dist/commerce/server/commerceCheckoutHandler.js

@@ -0,0 +1,196 @@
+import { CHECKOUT_CONTRACT_VERSION } from "../checkoutSchemas.js";
+import { providerPayerFromRequest } from "./commerceCheckoutProviderPayment.js";
+import { runBestEffortAccountLink } from "./commerceCheckoutHandlerHelpers.js";
+export function createCommerceCheckoutHandler(bindings) {
+    const { sendBffError, sendBffSuccess } = bindings.responder;
+    function createHandler(deps) {
+        const { persistencePort, quotePort, orderDraftPort, runtimePort, compensationPort, savedPaymentMethodResolverPort, customerDefaultsPort, resumableOrderPort, resumeWindowMinutes, linkCustomerAccount, verifyPromotionAcceptance, promotionAcceptanceEnforced = false, now = () => new Date(), resolvePricingPolicy, resolvePricingEligibilityClientId, starterPackEnabled, offerPolicy, starterTermsPort, isFirstOrderEligible, mintPaymentContinuationCookie, } = deps;
+        return async function handler(req, res) {
+            const timing = bindings.createCheckoutTimingLogger(req);
+            let totalOutcome = "error";
+            try {
+                const admission = await bindings.admitCheckoutRequest({
+                    req,
+                    res,
+                    deps,
+                    record: timing.record,
+                });
+                if (admission.kind === "responded") {
+                    totalOutcome = admission.outcome;
+                    return;
+                }
+                const { data, intent, checkoutKind } = admission;
+                let pricingEligibilityClientId;
+                if (resolvePricingEligibilityClientId) {
+                    try {
+                        pricingEligibilityClientId = await resolvePricingEligibilityClientId(intent.contact.email);
+                    }
+                    catch {
+                        sendBffError(res, "UPSTREAM_UNAVAILABLE", "Checkout customer eligibility read failed", {
+                            details: { feature: "checkout", stage: "customer_eligibility" },
+                        });
+                        return;
+                    }
+                }
+                const identity = await bindings.persistCheckoutIdentityOrRespond({
+                    res,
+                    persistencePort,
+                    resumeGuardDeps: { resumableOrderPort, resumeWindowMinutes },
+                    intent,
+                    checkoutKind,
+                    now,
+                    previewDiagnosticsEnabled: bindings.previewCheckoutDiagnosticsEnabled(),
+                    recordPersistStage: (operation) => timing.record("persist_intent", operation),
+                });
+                if (identity.kind === "responded") {
+                    totalOutcome = identity.outcome;
+                    return;
+                }
+                const provisioned = identity.provisioned;
+                let paymentMethodRef;
+                let paymentMethodAliasType;
+                let paymentMethodRecurringModel;
+                const savedMethodResult = await bindings.resolveSavedPaymentMethodForCheckout({
+                    req,
+                    paymentExecution: data.paymentExecution,
+                    clientId: provisioned.clientId,
+                    savedPaymentMethodResolverPort,
+                    now,
+                    recordStage: timing.record,
+                });
+                if (savedMethodResult.kind === "rejected") {
+                    bindings.respondToSavedPaymentMethodRejection(res, savedMethodResult.reason);
+                    totalOutcome = "rejected";
+                    return;
+                }
+                if (savedMethodResult.kind === "resolved") {
+                    paymentMethodRef = savedMethodResult.paymentMethodRef;
+                    paymentMethodAliasType = savedMethodResult.paymentMethodAliasType;
+                    paymentMethodRecurringModel = savedMethodResult.paymentMethodRecurringModel;
+                }
+                const defaults = await bindings.readCheckoutCustomerDefaultsOrRespond({ res, port: customerDefaultsPort, clientId: provisioned.clientId, checkoutKind, recordStage: (operation) => timing.record("customer_defaults", operation) });
+                if (defaults.kind === "responded")
+                    return;
+                const customerDefaultsSnapshot = defaults.snapshot;
+                let acceptedQuoteSnapshot = null;
+                try {
+                    const quoteGuard = await bindings.resolveCheckoutQuoteOrContinuation({
+                        quotePort,
+                        intent,
+                        provisioned,
+                        deps: { resumableOrderPort, resumeWindowMinutes },
+                        invoicePreference: data.invoicePreference,
+                        now,
+                        offerPolicy,
+                        starterTermsPort,
+                        checkoutKind,
+                        expectedQuote: data.expectedQuote,
+                        promotionAcceptanceToken: data.expectedQuote?.promotionAcceptanceToken,
+                        verifyPromotionAcceptance,
+                        recordQuoteStage: (operation) => timing.record("quote", operation),
+                        resolvePricingPolicy,
+                        pricingEligibilityClientId,
+                        starterPackEnabled,
+                        ...(isFirstOrderEligible
+                            ? {
+                                isFirstOrderEligible: () => isFirstOrderEligible(pricingEligibilityClientId ?? provisioned.clientId),
+                            }
+                            : {}),
+                    });
+                    if (quoteGuard.kind === "resumed") {
+                        sendBffSuccess(res, quoteGuard.response, { contractVersion: CHECKOUT_CONTRACT_VERSION });
+                        totalOutcome = "success";
+                        return;
+                    }
+                    if (quoteGuard.kind === "price_changed") {
+                        if (quoteGuard.starterOfferRejection) {
+                            console.info("checkout_starter_offer_rejected", JSON.stringify({ reason: quoteGuard.starterOfferRejection }));
+                        }
+                        sendBffSuccess(res, quoteGuard.response, { contractVersion: CHECKOUT_CONTRACT_VERSION });
+                        totalOutcome = "rejected";
+                        return;
+                    }
+                    acceptedQuoteSnapshot = quoteGuard.quoteSnapshot;
+                    // Deliberately AFTER the quote. The duplicate-charge guard has to answer
+                    // "may I re-offer this order" against the money the buyer was just
+                    // shown, and before this it could only answer against the order alone —
+                    // which is how a changed cart got re-offered at its old total.
+                    const resumeResponse = await bindings.resolveResumeOpenOrderResponse({
+                        deps: { resumableOrderPort, resumeWindowMinutes },
+                        clientId: provisioned.clientId,
+                        checkoutKind,
+                        intent,
+                        acceptedQuote: quoteGuard.quoteSnapshot.quote,
+                        now,
+                    });
+                    if (resumeResponse) {
+                        sendBffSuccess(res, resumeResponse, { contractVersion: CHECKOUT_CONTRACT_VERSION });
+                        totalOutcome = "success";
+                        return;
+                    }
+                    const orchestrated = await bindings.orchestratePaidOrder({
+                        intent,
+                        provisioned,
+                        checkoutKind,
+                        quotePort,
+                        orderDraftPort,
+                        runtimePort,
+                        customerDefaultsSnapshot,
+                        paymentProvider: data.paymentProvider,
+                        paymentAttemptSequence: data.paymentAttemptSequence,
+                        returnContext: data.returnContext,
+                        paymentExecution: data.paymentExecution,
+                        declaredBankId: data.declaredBankId,
+                        paymentMethodRef, paymentMethodAliasType, paymentMethodRecurringModel,
+                        invoicePreference: data.invoicePreference,
+                        quoteSnapshot: quoteGuard.quoteSnapshot,
+                        providerPayer: providerPayerFromRequest(req, intent),
+                        onPaymentStarted: linkCustomerAccount
+                            ? async ({ email }) => {
+                                await runBestEffortAccountLink(linkCustomerAccount, email);
+                            }
+                            : undefined,
+                        recordStage: timing.record,
+                        now,
+                    });
+                    const response = bindings.buildCheckoutSuccessResponse({
+                        orchestrated,
+                        paymentProvider: data.paymentProvider,
+                        checkoutKind,
+                        intent,
+                        clientId: provisioned.clientId,
+                    });
+                    const continuationInput = {
+                        mint: mintPaymentContinuationCookie,
+                        res, journeyId: intent.idempotencyKey, clientId: provisioned.clientId,
+                        requestRail: data.paymentProvider, response, result: orchestrated,
+                    };
+                    bindings.mintPaymentContinuationOnFreshAction(continuationInput);
+                    bindings.mintCheckoutRefusalContinuation(continuationInput);
+                    sendBffSuccess(res, response, { contractVersion: CHECKOUT_CONTRACT_VERSION });
+                    totalOutcome = "success";
+                }
+                catch (error) {
+                    totalOutcome = await bindings.respondToCheckoutFailure({
+                        error,
+                        compensationPort,
+                        intent,
+                        res,
+                        quotePort,
+                        provisioned,
+                        checkoutKind,
+                        acceptedQuoteSnapshot,
+                        expectedQuote: data.expectedQuote,
+                        resolvePricingPolicy,
+                        recordQuote: (operation) => timing.record("quote", operation),
+                    });
+                    return;
+                }
+            }
+            finally {
+                timing.log("total", totalOutcome);
+            }
+        };
+    }
+    return createHandler;
+}

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

@@ -0,0 +1,58 @@
+import type { z } from "zod";
+import type { HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { CheckoutKind, ConfiguratorIntent } from "../contracts/index.js";
+export interface CheckoutRateLimitDecision {
+    allowed: boolean;
+    reason?: "ip_quota" | "email_quota";
+}
+export interface CheckoutAdmissionRequest {
+    method?: string;
+    body?: unknown;
+    headers: Record<string, string | string[] | undefined>;
+}
+type CheckoutAdmissionResponse = HttpResponse;
+export interface CheckoutAdmissionDeps<Intent> {
+    checkRateLimit: (req: CheckoutAdmissionRequest, intent: Intent, paymentAttemptSequence: number | undefined) => Promise<CheckoutRateLimitDecision>;
+    rateLimitMessage: (reason: "ip_quota" | "email_quota" | undefined) => string;
+    checkRiskBlocklist?: (req: CheckoutAdmissionRequest, intent: Intent) => Promise<{
+        blocked: boolean;
+    }>;
+    subscriptionCheckoutContractEnabled?: () => boolean;
+    deliveryRequired?: () => boolean;
+    promotionAcceptanceEnforced?: boolean;
+    offerPolicy?: unknown;
+}
+export declare function createCheckoutAdmission<Intent extends ConfiguratorIntent, Data extends {
+    intent: Intent;
+    expectedQuote?: unknown;
+    paymentAttemptSequence?: number;
+}>(bindings: {
+    requestSchema: z.ZodType<Data>;
+    responder: BffResponder;
+    minimumOrderUnits?: number;
+    deliveryAllowed(intent: Intent): boolean;
+    respondDeliveryRequired(res: HttpResponse): void;
+    rejectMissingPromotionExpectedQuote(input: {
+        res: HttpResponse;
+        enforced: boolean;
+        intent: Intent;
+        expectedQuote?: unknown;
+    }): boolean;
+}): {
+    admitCheckoutRequest: (input: {
+        req: CheckoutAdmissionRequest;
+        res: CheckoutAdmissionResponse;
+        deps: CheckoutAdmissionDeps<Intent>;
+        record: <T>(stage: "rate_limit" | "risk_blocklist", operation: () => Promise<T>) => Promise<T>;
+    }) => Promise<{
+        kind: "accepted";
+        data: Data;
+        intent: Intent;
+        checkoutKind: CheckoutKind;
+    } | {
+        kind: "responded";
+        outcome: "error" | "rejected";
+    }>;
+};
+export {};

package/dist/commerce/server/commerceCheckoutHandlerAdmission.js

@@ -0,0 +1,94 @@
+export function createCheckoutAdmission(bindings) {
+    const { sendBffError, sendMethodNotAllowed } = bindings.responder;
+    async function admitCheckoutRequest(input) {
+        const { req, res, deps } = input;
+        if (req.method !== "POST") {
+            sendMethodNotAllowed(res, ["POST"]);
+            return { kind: "responded", outcome: "rejected" };
+        }
+        const parsed = bindings.requestSchema.safeParse(req.body);
+        if (!parsed.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid checkout request", {
+                details: parsed.error.flatten(),
+            });
+            return { kind: "responded", outcome: "rejected" };
+        }
+        const intent = parsed.data.intent;
+        // An untrusted minimum cannot waive the host floor without an offer resolver.
+        if (bindings.minimumOrderUnits !== undefined && !deps.offerPolicy) {
+            const selectedUnits = intent.selectedVariants.reduce((total, variant) => total + variant.qty, 0);
+            const reason = selectedUnits < bindings.minimumOrderUnits
+                ? `selected variants require at least ${bindings.minimumOrderUnits} total units`
+                : intent.minimumUnits !== undefined || intent.offerVersion !== undefined
+                    ? "offer_version_unsupported" : null;
+            if (reason) {
+                sendBffError(res, "BAD_REQUEST", "Invalid checkout request", {
+                    details: { formErrors: [], fieldErrors: { intent: [reason] } },
+                });
+                return { kind: "responded", outcome: "rejected" };
+            }
+        }
+        const checkoutKind = checkoutKindForIntent(intent);
+        if (bindings.rejectMissingPromotionExpectedQuote({
+            res,
+            enforced: deps.promotionAcceptanceEnforced ?? false,
+            intent,
+            expectedQuote: parsed.data.expectedQuote,
+        })) {
+            return { kind: "responded", outcome: "rejected" };
+        }
+        if ((deps.deliveryRequired?.() ?? false) && !bindings.deliveryAllowed(intent)) {
+            bindings.respondDeliveryRequired(res);
+            return { kind: "responded", outcome: "rejected" };
+        }
+        if (checkoutKind === "subscription_initial" &&
+            !(deps.subscriptionCheckoutContractEnabled?.() ?? false)) {
+            sendBffError(res, "BAD_REQUEST", "Subscription checkout contract is disabled", {
+                details: {
+                    feature: "checkout",
+                    featureFlag: "COMMERCE_V2_W11_SUBSCRIPTION_CHECKOUT_CONTRACT_ENABLED",
+                    reason: "subscription_checkout_contract_disabled",
+                },
+            });
+            return { kind: "responded", outcome: "rejected" };
+        }
+        let decision;
+        try {
+            decision = await input.record("rate_limit", () => deps.checkRateLimit(req, intent, parsed.data.paymentAttemptSequence));
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Checkout rate limit unavailable", {
+                details: { feature: "checkout", reason: "rate_limit_unavailable" },
+            });
+            return { kind: "responded", outcome: "error" };
+        }
+        if (!decision.allowed) {
+            sendBffError(res, "RATE_LIMITED", deps.rateLimitMessage(decision.reason), {
+                details: { feature: "checkout", reason: decision.reason ?? "ip_quota" },
+            });
+            return { kind: "responded", outcome: "rejected" };
+        }
+        if (deps.checkRiskBlocklist) {
+            try {
+                const risk = await input.record("risk_blocklist", () => deps.checkRiskBlocklist(req, intent));
+                if (risk.blocked) {
+                    sendBffError(res, "FORBIDDEN", "Checkout cannot be completed", {
+                        details: { feature: "checkout", reason: "risk_blocked_checkout" },
+                    });
+                    return { kind: "responded", outcome: "rejected" };
+                }
+            }
+            catch {
+                sendBffError(res, "UPSTREAM_UNAVAILABLE", "Checkout risk check unavailable", {
+                    details: { feature: "checkout", reason: "risk_check_unavailable" },
+                });
+                return { kind: "responded", outcome: "error" };
+            }
+        }
+        return { kind: "accepted", data: parsed.data, intent, checkoutKind };
+    }
+    function checkoutKindForIntent(intent) {
+        return intent.mode === "subscription" ? "subscription_initial" : "one_time";
+    }
+    return { admitCheckoutRequest };
+}