@openlup/platform 0.25.0 → 0.27.0

package/dist/commerce/server/commerceRuntimeService.js

@@ -0,0 +1,186 @@
+import { CommerceRuntimeConflictError } from "../runtimeErrors.js";
+export function createCommerceRuntimeService(bindings) {
+    function createService({ orderPort, inventoryPort, paymentPort, readinessPort, executionPort = bindings.defaultExecutionPort, resolveExecutionPort, }) {
+        const pickExecutionPort = (providerKind) => resolveExecutionPort ? resolveExecutionPort(providerKind) : executionPort;
+        const startRuntime = async (request, resolvedExecutionPort) => {
+            const paymentProvider = request.paymentProvider ?? bindings.defaultPaymentProvider;
+            const providerFlow = request.providerFlow ?? bindings.defaultProviderFlow;
+            const executionPortForRequest = resolvedExecutionPort ?? pickExecutionPort(paymentProvider);
+            const order = await orderPort.finalizeOrderForCheckout(request);
+            const reservations = await inventoryPort.reserveOrderItems({
+                idempotencyKey: `${request.idempotencyKey}:inventory`,
+                order,
+                paymentStatus: "created",
+                metadata: request.metadata,
+            });
+            const targetKind = order.mode === "subscription_cycle" ? "subscription_cycle" : "one_time_order";
+            const intent = await paymentPort.createIntent({
+                idempotencyKey: `${request.idempotencyKey}:payment-intent`,
+                targetKind,
+                orderId: order.orderId,
+                subscriptionId: order.subscriptionId,
+                subscriptionCycleId: order.subscriptionCycleId,
+                amountMinor: order.total.amountMinor,
+                currency: order.total.currency,
+                metadata: {
+                    ...request.metadata,
+                    source: "commerce.runtime.hidden.v0",
+                    runtimeIdempotencyKey: request.idempotencyKey,
+                    ...bindings.paymentMetadataExtension(order),
+                },
+            });
+            // Attempt-scoped, not journey-scoped: a retry after a terminal decline —
+            // and above all a switch to another provider — needs a fresh provider
+            // attempt identity on the SAME order. Sequence 0 keeps the historic key
+            // byte-identical.
+            const attemptSequence = request.paymentAttemptSequence ?? 0;
+            const paymentExecutionIdempotencyKey = attemptSequence > 0
+                ? `${request.idempotencyKey}:payment-execution:attempt:${attemptSequence}`
+                : `${request.idempotencyKey}:payment-execution`;
+            const providerAttemptIdentity = bindings.buildProviderAttemptIdentity({
+                provider: paymentProvider,
+                localExecutionIdempotencyKey: paymentExecutionIdempotencyKey,
+                paymentIntentId: intent.paymentIntentId,
+                amountMinor: order.total.amountMinor,
+                currency: order.total.currency,
+                mode: order.mode,
+                orderRef: order.orderRef,
+            });
+            const executionInput = {
+                idempotencyKey: paymentExecutionIdempotencyKey,
+                providerIdempotencyKey: providerAttemptIdentity.providerIdempotencyKey,
+                providerRequestFingerprint: providerAttemptIdentity.providerRequestFingerprint,
+                paymentIntentId: intent.paymentIntentId,
+                amountMinor: order.total.amountMinor,
+                currency: order.total.currency,
+                mode: order.mode,
+                orderRef: order.orderRef,
+                providerFlow,
+                clientId: order.clientId,
+                ...bindings.executionSubject(order),
+                orderId: order.orderId,
+                paymentMethodRef: request.paymentMethodRef,
+                paymentMethodAliasType: request.paymentMethodAliasType,
+                paymentMethodRecurringModel: request.paymentMethodRecurringModel,
+                payer: request.providerPayer,
+                // The host execution adapter owns reusable-method policy.
+                saveForFutureUse: request.saveForFutureUse,
+                returnContext: request.returnContext,
+                transientProviderInput: bindings.transientProviderInput(request.paymentExecution),
+            };
+            if (bindings.requiresPreparedProviderAttempt(paymentProvider)) {
+                const preparedPaymentPort = bindings.preparedProviderAttemptPort(paymentPort, paymentProvider);
+                const preparedExecution = await bindings.executePreparedProviderAttempt({
+                    paymentPort: preparedPaymentPort,
+                    executionPort: executionPortForRequest,
+                    provider: paymentProvider,
+                    paymentIntentId: intent.paymentIntentId,
+                    executionInput,
+                    prepareIdempotencyKey: `${paymentExecutionIdempotencyKey}:prepare-attempt`,
+                    finalizeIdempotencyKey: `${paymentExecutionIdempotencyKey}:finalize-attempt`,
+                    providerIdempotencyKey: providerAttemptIdentity.providerIdempotencyKey,
+                    providerRequestFingerprint: providerAttemptIdentity.providerRequestFingerprint,
+                    providerFlow,
+                    paymentMethodRef: request.paymentMethodRef ?? null,
+                    prepareRequestPayload: {
+                        source: "commerce.runtime.provider-attempt.prepare.v0",
+                        providerIdempotencyKey: providerAttemptIdentity.providerIdempotencyKey,
+                        providerRequestFingerprint: providerAttemptIdentity.providerRequestFingerprint,
+                        providerFlow,
+                        paymentMethodRef: request.paymentMethodRef ?? null,
+                        recurringModel: bindings.preparedRecurringModel(request),
+                        // Audit only: recorded so a refusal can be attributed to an issuer
+                        // later. It is not part of the execution object, so it cannot reach
+                        // the provider request built below.
+                        declaredBankId: request.declaredBankId ?? null,
+                        amountMinor: order.total.amountMinor,
+                        currency: order.total.currency,
+                        orderRef: order.orderRef,
+                        runtimeIdempotencyKey: request.idempotencyKey,
+                    },
+                }).catch((error) => {
+                    if (!(bindings.isPreDispatch(error)))
+                        throw error;
+                    return bindings.reopenExhaustedPreDispatchAttempt({
+                        error, paymentPort, paymentExecutionIdempotencyKey,
+                        order, reservations, intent, provider: paymentProvider,
+                    });
+                });
+                if ("runtime" in preparedExecution)
+                    return preparedExecution;
+                return bindings.preserveProviderDispatchUncertainty(() => bindings.buildStartedRuntimeResponse({
+                    paymentExecutionIdempotencyKey,
+                    order,
+                    reservations,
+                    intent,
+                    execution: preparedExecution.execution,
+                    attempt: preparedExecution.attempt,
+                    continuationActionOrigin: "fresh_execution",
+                    paymentPort,
+                    readinessPort,
+                }), preparedExecution.attempt.paymentAttemptId);
+            }
+            const execution = await executionPortForRequest.execute(executionInput);
+            const attempt = await bindings.recordPaymentAttempt(paymentPort, {
+                idempotencyKey: `${request.idempotencyKey}:payment-attempt`,
+                paymentIntentId: intent.paymentIntentId,
+                execution,
+            });
+            return bindings.buildStartedRuntimeResponse({
+                paymentExecutionIdempotencyKey,
+                order,
+                reservations,
+                intent,
+                execution,
+                attempt,
+                continuationActionOrigin: null,
+                paymentPort,
+                readinessPort,
+            });
+        };
+        const applyPaymentResult = async (request) => {
+            const paymentResult = await paymentPort.applyResult(request);
+            if (paymentResult.orderId !== request.orderId) {
+                throw new CommerceRuntimeConflictError("Payment result order mismatch", {
+                    requestOrderId: request.orderId,
+                    paymentResultOrderId: paymentResult.orderId,
+                    paymentIntentId: request.paymentIntentId,
+                });
+            }
+            // Interactive PSP declines remain payable on the same order/payment
+            // intent. Releasing their stock here creates a paid-without-reservation
+            // path on the next recovery attempt. Expiry and genuinely terminal
+            // failures still release through this single boundary.
+            const shouldRelease = request.resultStatus === "expired" ||
+                (request.resultStatus === "failed" && paymentResult.kind !== "recoverable_decline");
+            const reservationRelease = shouldRelease
+                ? {
+                    attempted: true,
+                    ...(await inventoryPort.releaseOrderReservations({
+                        idempotencyKey: `${request.idempotencyKey}:inventory-release`,
+                        orderId: request.orderId,
+                        reason: `payment_${request.resultStatus}`,
+                    })),
+                }
+                : { attempted: false, releasedCount: 0 };
+            const readiness = shouldRelease
+                ? null
+                : await readinessPort.evaluateOrderReadiness({
+                    orderId: request.orderId,
+                    fallbackOrderItemCount: null,
+                    allOrderItemsHaveSku: true,
+                });
+            return bindings.resultResponseSchema.parse({
+                contractVersion: bindings.contractVersion,
+                paymentResult,
+                reservationRelease,
+                readiness,
+            });
+        };
+        return {
+            startRuntime,
+            applyPaymentResult,
+        };
+    }
+    return createService;
+}

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

@@ -0,0 +1,37 @@
+import type { z } from "zod";
+import type { FinalizedCheckoutOrder, CommerceRuntimeReadinessPort } from "../contracts/index.js";
+import type { CheckoutRuntimeExecutionResult } from "./checkoutRuntimeTypes.js";
+export declare function createRuntimeStartResponse<Order extends FinalizedCheckoutOrder<string>, Reservation, PaymentPort, Execution extends CheckoutRuntimeExecutionResult, Readiness, Response>(bindings: {
+    contractVersion: string;
+    responseSchema: z.ZodType<Response>;
+    runtimeResponseExtension(order: Order): object;
+    finalizeDeclinedAttempt(port: PaymentPort, input: {
+        idempotencyKey: string;
+        orderId: string;
+        paymentIntentId: string;
+        fallbackAttemptId: string;
+        decline: NonNullable<Execution["providerDecline"]>;
+    }): Promise<{
+        paymentAttemptId: string;
+        status: string;
+    }>;
+}): {
+    buildStartedRuntimeResponse: (input: {
+        paymentExecutionIdempotencyKey: string;
+        order: Order;
+        reservations: Reservation[];
+        intent: {
+            paymentIntentId: string;
+            paymentId: string;
+            status: string;
+        };
+        execution: Execution;
+        attempt: {
+            paymentAttemptId: string;
+            status: string;
+        };
+        continuationActionOrigin: "fresh_execution" | null;
+        paymentPort: PaymentPort;
+        readinessPort: CommerceRuntimeReadinessPort<Readiness>;
+    }) => Promise<Response>;
+};

package/dist/commerce/server/commerceRuntimeStartResponse.js

@@ -0,0 +1,56 @@
+export function createRuntimeStartResponse(bindings) {
+    async function buildStartedRuntimeResponse(input) {
+        let attempt = input.attempt;
+        if (input.execution.providerDecline) {
+            attempt = await bindings.finalizeDeclinedAttempt(input.paymentPort, {
+                idempotencyKey: `${input.paymentExecutionIdempotencyKey}:payment-declined`,
+                orderId: input.order.orderId,
+                paymentIntentId: input.intent.paymentIntentId,
+                fallbackAttemptId: attempt.paymentAttemptId,
+                decline: input.execution.providerDecline,
+            });
+        }
+        const readiness = await input.readinessPort.evaluateOrderReadiness({
+            orderId: input.order.orderId,
+            fallbackOrderItemCount: input.order.items.length,
+            allOrderItemsHaveSku: true,
+        });
+        return bindings.responseSchema.parse({
+            contractVersion: bindings.contractVersion,
+            runtime: {
+                orderId: input.order.orderId,
+                orderRef: input.order.orderRef,
+                mode: input.order.mode,
+                clientId: input.order.clientId,
+                ...bindings.runtimeResponseExtension(input.order),
+                shippingAddressId: input.order.shippingAddressId,
+                total: input.order.total,
+                finalizedReplayed: input.order.replayed,
+                reservations: input.reservations,
+                payment: {
+                    paymentIntentId: input.intent.paymentIntentId,
+                    paymentId: input.intent.paymentId,
+                    paymentAttemptId: attempt.paymentAttemptId,
+                    // finalizeDeclinedAttempt above already applied the canonical failed
+                    // result to the durable intent/payment/attempt. Reflect that result
+                    // instead of returning the stale pre-execution "created" snapshot.
+                    status: input.execution.providerDecline ? "failed" : input.intent.status,
+                    ...(input.execution.providerDecline?.mandateUnsupported ? { declineMandateUnsupported: true } : {}),
+                    attemptStatus: attempt.status,
+                    provider: input.execution.provider,
+                    providerAttemptId: input.execution.providerAttemptId,
+                    providerClientSecret: input.execution.clientSecret ?? null,
+                    providerRedirectUrl: input.execution.redirectUrl ?? null,
+                    providerNextActionKind: input.execution.nextActionKind ?? null,
+                    continuationActionOrigin: input.continuationActionOrigin,
+                },
+                readiness,
+                nextAction: {
+                    kind: "await_hidden_payment_result",
+                    provider: input.execution.provider,
+                },
+            },
+        });
+    }
+    return { buildStartedRuntimeResponse };
+}

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

@@ -0,0 +1,55 @@
+import type { z } from "zod";
+import type { ConfiguratorIntent } from "../contracts/index.js";
+import type { CommerceQuotePort } from "../ports.js";
+import type { StarterTermsPort } from "./starterTermsPort.js";
+import type { CheckoutQuoteSnapshot } from "./checkoutQuoteTypes.js";
+export interface StarterDeclaration {
+    intervalDays: number;
+    delivery2DiscountBps: number;
+    acquisitionTerms?: {
+        revision: string;
+        delivery2DiscountBps: number;
+    };
+    steady: {
+        cadenceDays: number;
+        units: number;
+    };
+}
+export type StarterOfferGuardResult<Plan> = {
+    kind: "absent";
+} | {
+    kind: "rejected";
+    reason: string;
+} | {
+    kind: "minted";
+    plan: Plan;
+};
+export declare function withStarterPackContext<Snapshot extends CheckoutQuoteSnapshot, Plan>(snapshot: Snapshot, plan: Plan | null): Snapshot;
+export declare function createStarterOfferGuard<Intent extends ConfiguratorIntent, Provisioned extends {
+    clientId: string | null;
+}, Request, Snapshot extends CheckoutQuoteSnapshot, Plan>(bindings: {
+    declaration(intent: Intent): StarterDeclaration | undefined;
+    defaultTermsPort: StarterTermsPort<Intent, Snapshot>;
+    defaultDiscountBps: number;
+    discountMinor(input: {
+        bandSubtotalMinor: number;
+        listAnchorTotalMinor: number;
+        discountBps: number;
+    }): number | null;
+    planSchema: z.ZodType<Plan>;
+    aggregateBySku(entries: Intent["selectedVariants"]): Intent["selectedVariants"];
+    rescaleBasket(entries: Intent["selectedVariants"], units: number): Intent["selectedVariants"];
+    steadyIntent(intent: Intent, cadenceDays: number, units: number, variants: Intent["selectedVariants"]): Intent;
+    buildQuoteRequest(intent: Intent, provisioned: Provisioned): Request;
+}): {
+    resolveStarterOfferGuard: (input: {
+        flagEnabled: boolean;
+        intent: Intent;
+        provisioned: Provisioned;
+        authoritativeQuote: Snapshot;
+        quotePort: CommerceQuotePort<Request, Snapshot, import("../../pricing/index.js").CreateQuoteOptions>;
+        isFirstOrderEligible?: () => Promise<boolean>;
+        termsPort?: StarterTermsPort<Intent, Snapshot>;
+        offerVersion?: string;
+    }) => Promise<StarterOfferGuardResult<Plan>>;
+};

package/dist/commerce/server/commerceStarterOfferGuard.js

@@ -0,0 +1,128 @@
+export function withStarterPackContext(snapshot, plan) {
+    if (!plan || !snapshot.quote.context)
+        return snapshot;
+    return { ...snapshot, quote: { ...snapshot.quote, context: { ...snapshot.quote.context, starterPack: plan } } };
+}
+export function createStarterOfferGuard(bindings) {
+    const TERMS_REFUSALS = {
+        basket_too_small: "starter_offer_basket_too_small",
+        basket_not_admitted: "starter_offer_basket_not_admitted",
+        demand_unknown: "starter_offer_demand_unknown",
+    };
+    const ACQUISITION_TEMPLATE_VERSION = 1;
+    async function resolveStarterOfferGuard(input) {
+        const declared = bindings.declaration(input.intent);
+        // Flag OFF and nothing declared is the overwhelmingly common case and must do
+        // exactly zero work — no quote, no read, no allocation.
+        if (!declared)
+            return { kind: "absent" };
+        if (!input.flagEnabled)
+            return { kind: "rejected", reason: "starter_offer_disabled" };
+        if (input.intent.mode !== "subscription") {
+            return { kind: "rejected", reason: "starter_offer_wrong_mode" };
+        }
+        // The terms of the effective basket, from the server's own quote. The default
+        // port is the arithmetic the client asks with (see `defaultStarterTermsPort`),
+        // so any disagreement below is a drifted ask, never a rounding difference.
+        const resolution = await (input.termsPort ?? bindings.defaultTermsPort).resolve({
+            intent: input.intent,
+            authoritativeQuote: input.authoritativeQuote,
+            ...(input.offerVersion ? { offerVersion: input.offerVersion } : {}),
+        });
+        if (resolution.kind === "refused") {
+            return { kind: "rejected", reason: TERMS_REFUSALS[resolution.reason] };
+        }
+        const { intervalDays, steadyCadenceDays: cadenceDays, steadyUnits: steadyUnits, graduationSizeConstraint, } = resolution.terms;
+        const acquisition = input.authoritativeQuote.quote.context?.acquisitionTerms;
+        const delivery2DiscountBps = acquisition?.delivery2DiscountBps ?? bindings.defaultDiscountBps;
+        if ((acquisition !== undefined && (declared.acquisitionTerms?.revision !== acquisition.revision ||
+            declared.acquisitionTerms.delivery2DiscountBps !== delivery2DiscountBps)) ||
+            declared.intervalDays !== intervalDays ||
+            declared.delivery2DiscountBps !== delivery2DiscountBps ||
+            declared.steady.cadenceDays !== cadenceDays ||
+            declared.steady.units !== steadyUnits) {
+            return { kind: "rejected", reason: "starter_offer_terms_drifted" };
+        }
+        if (!(await input.isFirstOrderEligible?.())) {
+            return { kind: "rejected", reason: "starter_offer_not_first_order" };
+        }
+        const bandSubtotalMinor = input.authoritativeQuote.quote.subtotalGross.amountMinor;
+        const discountMinor = bindings.discountMinor({
+            bandSubtotalMinor,
+            listAnchorTotalMinor: listAnchorTotalMinor(input.authoritativeQuote),
+            discountBps: delivery2DiscountBps,
+        });
+        if (discountMinor === null) {
+            return { kind: "rejected", reason: "starter_offer_uncollectable_delivery_2" };
+        }
+        const steadyQuote = await quoteSteadyPackage(input, steadyUnits, cadenceDays);
+        if (steadyQuote === null) {
+            return { kind: "rejected", reason: "starter_offer_steady_quote_failed" };
+        }
+        const parsed = bindings.planSchema.safeParse({
+            schemaVersion: "1",
+            starterIntervalDays: intervalDays,
+            basisTemplateVersion: ACQUISITION_TEMPLATE_VERSION,
+            delivery2: {
+                discountBps: delivery2DiscountBps,
+                discountMinor,
+                basisSubtotalMinor: bandSubtotalMinor,
+            },
+            graduation: {
+                cadenceDays,
+                sizeConstraint: graduationSizeConstraint ?? { kind: "unit_count", value: steadyUnits },
+                lines: steadyQuote.quote.lines.map((line, index) => ({
+                    sku: line.sku,
+                    qty: line.quantity,
+                    sortOrder: index,
+                    // Addons are never part of a graduation basket; the RPC deletes only
+                    // non-addon template lines, so an existing addon survives untouched.
+                    isAddon: false,
+                    quoteLine: frozenQuoteLine(line),
+                })),
+            },
+        });
+        if (!parsed.success)
+            return { kind: "rejected", reason: "starter_offer_plan_invalid" };
+        return { kind: "minted", plan: parsed.data };
+    }
+    function listAnchorTotalMinor(snapshot) {
+        const orderScoped = sumBaseUnit(snapshot.quote.pricingComponents);
+        if (orderScoped > 0)
+            return orderScoped;
+        return snapshot.quote.lines.reduce((total, line) => total + sumBaseUnit(line.pricingComponents), 0);
+    }
+    function sumBaseUnit(components) {
+        if (!components)
+            return 0;
+        return components
+            .filter((component) => component.componentType === "base_unit")
+            .reduce((total, component) => total + component.amountMinor, 0);
+    }
+    function frozenQuoteLine(line) {
+        const { pricingComponents: _dropped, ...rest } = line;
+        return { ...rest };
+    }
+    async function quoteSteadyPackage(input, steadyUnits, cadenceDays) {
+        const steadyVariants = bindings.rescaleBasket(bindings.aggregateBySku(input.intent.selectedVariants), steadyUnits);
+        // Fail closed on an unrepresentable basket (more distinct variants than units).
+        // Quoting it would mint a marker whose lines contradict the size it promises.
+        if (steadyVariants.reduce((total, v) => total + v.qty, 0) !== steadyUnits)
+            return null;
+        const steadyIntent = bindings.steadyIntent(input.intent, cadenceDays, steadyUnits, steadyVariants);
+        try {
+            // A bound offer prices its steady basket from its own list, like the checkout quote.
+            const quoted = await input.quotePort.createQuote(bindings.buildQuoteRequest(steadyIntent, input.provisioned), {
+                ...(input.provisioned.clientId ? { clientId: input.provisioned.clientId } : {}),
+                ...(input.offerVersion ? { offerVersion: input.offerVersion } : {}),
+                ...(input.authoritativeQuote.quote.context?.pricingPolicy
+                    ? { pricingPolicy: input.authoritativeQuote.quote.context.pricingPolicy } : {}),
+            });
+            return quoted.quote.lines.length > 0 ? quoted : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return { resolveStarterOfferGuard };
+}

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

@@ -0,0 +1,47 @@
+import type { z } from "zod";
+import type { ConfiguratorIntentPersistencePort } from "../contracts/ports.js";
+import type { CheckoutCommandPersistencePort } from "../contracts/runtimePorts.js";
+import type { RpcError } from "../contracts/omsTypes.js";
+interface ConfiguratorIntentIdentityQueryResult {
+    data: Array<{
+        response_payload?: unknown;
+    }> | null;
+    error: RpcError | null;
+}
+interface ConfiguratorIntentIdentityQuery {
+    eq(column: string, value: unknown): ConfiguratorIntentIdentityQuery;
+    limit(count: number): PromiseLike<ConfiguratorIntentIdentityQueryResult>;
+}
+interface ConfiguratorIntentIdentityTable {
+    select(columns: string): ConfiguratorIntentIdentityQuery;
+}
+/**
+ * The identity the ROUTE proved for this request, and the only identity the RPC
+ * is allowed to believe.
+ *
+ * ⛔ It is not read from the request body and never can be: `withVerifiedSubject`
+ * writes it last and unconditionally, so a payload that carries the key has it
+ * overwritten rather than honoured. A guest is `null`, which is a positive claim
+ * that nobody proved anything - not an absence the RPC may fill in.
+ */
+export interface ConfiguratorIntentPersistenceIdentity {
+    authenticatedUserId: string | null;
+}
+type PersistIntentPayload<Request, Command> = (Request | Command) & {
+    authenticatedUserId: string | null;
+};
+export interface ConfiguratorIntentRpcQueryClient<Request, Command> {
+    rpc(functionName: "commerce_configurator_persist_intent", args: {
+        p_intent: PersistIntentPayload<Request, Command>;
+    }): PromiseLike<{
+        data: unknown;
+        error: RpcError | null;
+    }>;
+    from(tableName: "commerce_idempotency_keys"): ConfiguratorIntentIdentityTable;
+}
+export declare function createConfiguratorIntentPersistenceRpcPort<Request extends object, Response, Command extends object, Persistence>(client: ConfiguratorIntentRpcQueryClient<Request, Command>, bindings: {
+    responseSchema: z.ZodType<Response>;
+    decodeCommandResponse(data: unknown): Persistence;
+    normalizePhoneToE164(phone: string, country: unknown): string | null;
+}, identity?: ConfiguratorIntentPersistenceIdentity): ConfiguratorIntentPersistencePort<Request, Response> & CheckoutCommandPersistencePort<Command, Persistence>;
+export {};

package/dist/commerce/server/configuratorIntentPersistence.js

@@ -0,0 +1,85 @@
+import { ConfiguratorIntentPersistenceConflictError } from "./configuratorIntentPersistenceHandler.js";
+/** Scope used by the persist-intent RPC for its idempotency-key rows. */
+const CONFIGURATOR_INTENT_SCOPE = "commerce_configurator_intent";
+export function createConfiguratorIntentPersistenceRpcPort(client, bindings, identity = { authenticatedUserId: null }) {
+    return {
+        async persistIntent(request) {
+            const { data, error } = await client.rpc("commerce_configurator_persist_intent", {
+                p_intent: withVerifiedSubject(withCanonicalIntentPhone(request), identity),
+            });
+            if (error)
+                throw mapRpcError(error);
+            return bindings.responseSchema.parse(data);
+        },
+        async persistCheckoutCommand(command) {
+            const { data, error } = await client.rpc("commerce_configurator_persist_intent", {
+                p_intent: withVerifiedSubject(withCanonicalCommandPhone(command), identity),
+            });
+            if (error)
+                throw mapRpcError(error);
+            return bindings.decodeCommandResponse(data);
+        },
+        async findCompletedIdentity(idempotencyKey) {
+            // Read back the identity the RPC stored on the COMPLETED key. The RPC writes
+            // the full response object into `response_payload`, so it validates against
+            // the same schema persistIntent returns. A different/missing row -> null,
+            // which the caller treats as "cannot resume -> 409".
+            const { data, error } = await client
+                .from("commerce_idempotency_keys")
+                .select("response_payload")
+                .eq("scope", CONFIGURATOR_INTENT_SCOPE)
+                .eq("idempotency_key", idempotencyKey)
+                .eq("status", "completed")
+                .limit(1);
+            if (error) {
+                throw new Error(`Configurator intent identity lookup failed: ${error.message ?? "query failed"}`);
+            }
+            const payload = data?.[0]?.response_payload;
+            if (!payload)
+                return null;
+            const parsed = bindings.responseSchema.safeParse(payload);
+            return parsed.success ? parsed.data : null;
+        },
+    };
+    // Canonicalization is fail-open: an unparseable non-empty phone is preserved verbatim.
+    function canonicalPhoneRewrite(contact, address) {
+        const phone = contact?.phone;
+        if (typeof phone !== "string" || phone.trim() === "")
+            return null;
+        const country = address?.country;
+        const canonical = bindings.normalizePhoneToE164(phone, country) ?? phone;
+        return canonical === phone ? null : canonical;
+    }
+    /**
+     * Stamp the route-verified subject onto the payload, LAST.
+     *
+     * The RPC resolves its client row by e-mail, and an e-mail typed into an
+     * anonymous request is a client-supplied object identifier - knowing one is not
+     * authorization to edit the record it names. This is the single line that decides
+     * whose identity the database is allowed to write, so it overwrites rather than
+     * defaults: a caller who puts `authenticatedUserId` in the body gets it replaced.
+     */
+    function withVerifiedSubject(payload, identity) {
+        return { ...payload, authenticatedUserId: identity.authenticatedUserId };
+    }
+    function withCanonicalIntentPhone(request) {
+        const phone = canonicalPhoneRewrite(request.contact, request.address);
+        if (phone === null)
+            return request;
+        return { ...request, contact: { ...request.contact, phone } };
+    }
+    function withCanonicalCommandPhone(command) {
+        const phone = canonicalPhoneRewrite(command.customer, command.shippingAddress);
+        if (phone === null)
+            return command;
+        return { ...command, customer: { ...command.customer, phone } };
+    }
+}
+function mapRpcError(error) {
+    const text = [error.message, error.details, error.hint].filter(Boolean).join(" ");
+    if (error.code === "23505" ||
+        /configurator_intent_.*(?:conflict|invalid|missing)/.test(text)) {
+        return new ConfiguratorIntentPersistenceConflictError("Configurator intent persistence conflict", { code: error.code });
+    }
+    return new Error(`Configurator intent persistence RPC failed: ${text}`);
+}

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

@@ -0,0 +1,14 @@
+import type { z } from "zod";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { ConfiguratorIntentPersistencePort } from "../contracts/index.js";
+export declare class ConfiguratorIntentPersistenceConflictError extends Error {
+    readonly details: Record<string, unknown>;
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+export declare function createConfiguratorIntentPersistenceHandler<Request, Response>({ persistencePort, responder, requestSchema, responseSchema, }: {
+    persistencePort: ConfiguratorIntentPersistencePort<Request, Response>;
+    responder: BffResponder;
+    requestSchema: z.ZodType<Request>;
+    responseSchema: z.ZodType<Response>;
+}): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/commerce/server/configuratorIntentPersistenceHandler.js

@@ -0,0 +1,42 @@
+export class ConfiguratorIntentPersistenceConflictError extends Error {
+    details;
+    constructor(message = "Configurator intent idempotency conflict", details = {}) {
+        super(message);
+        this.name = "ConfiguratorIntentPersistenceConflictError";
+        this.details = details;
+    }
+}
+export function createConfiguratorIntentPersistenceHandler({ persistencePort, responder, requestSchema, responseSchema, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+    return async function handler(req, res) {
+        if (req.method !== "POST") {
+            sendMethodNotAllowed(res, ["POST"]);
+            return;
+        }
+        const request = requestSchema.safeParse(req.body);
+        if (!request.success) {
+            sendBffError(res, "BAD_REQUEST", "Invalid configurator intent", {
+                details: request.error.flatten(),
+            });
+            return;
+        }
+        try {
+            const persisted = await persistencePort.persistIntent(request.data);
+            const response = responseSchema.safeParse(persisted);
+            if (!response.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Configurator intent persistence returned invalid response");
+                return;
+            }
+            sendBffSuccess(res, response.data, {
+                contractVersion: "commerce.configurator_intent_persistence.v1",
+            });
+        }
+        catch (error) {
+            if (error instanceof ConfiguratorIntentPersistenceConflictError) {
+                sendBffError(res, "CONFLICT", error.message, { details: error.details });
+                return;
+            }
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Configurator intent persistence failed");
+        }
+    };
+}