@proxy-checkout/stripe-server-js 0.0.1 → 0.1.0-prx-124.139.1

package/README.md

@@ -4,7 +4,7 @@ Server-side Stripe adapter for Proxy Checkout. It owns the Stripe-specific integ
 
 - **`requiredMetadata(proxySession)`** — the `proxy_session_id` metadata Proxy needs on the Checkout Session, Subscription, and PaymentIntent.
 - **`assertCheckoutSessionBelongsToProxy` / `assertSubscriptionBelongsToProxy` / `assertPaymentIntentBelongsToProxy`** — provider-object ownership checks.
-- **`openCheckout(...)`** — records payer-opened, validates/reconciles the typed cart with rollback, injects required metadata, creates the Stripe Checkout Session with deterministic idempotency, records the Proxy provider binding, and returns the client secret. The merchant only supplies app-specific Stripe params.
+- **`openCheckout(...)`** — records payer-opened, validates/reconciles the typed cart with rollback, injects required metadata, creates or joins the Stripe Checkout Session with deterministic idempotency, and records the Proxy provider binding. It returns provider-create material only for a `ready` outcome; terminal outcomes retain the shared cart without starting Stripe.
 - **`syncCheckoutCart(...)`** — validates the stored Proxy provider binding, then updates the Proxy cart and the Stripe Checkout `line_items` in the safest order with deterministic rollback/reconciliation (`ProxyStripeCartSyncError`).
 
 PSP-agnostic primitives (sessions, subscriptions, webhooks, lifecycle) live in [`@proxy-checkout/server-js`](https://www.npmjs.com/package/@proxy-checkout/server-js). This package is an additive adapter on top and is dependency-free: you inject your own `Stripe` instance and your `@proxy-checkout/server-js` client.
@@ -38,19 +38,23 @@ const checkout = await openCheckout({
     ui_mode: "custom",
   }),
 });
-// checkout.clientSecret -> render Stripe Elements
-
-// Cart edits go through the binding-validated sync helper.
-await syncCheckoutCart({
-  proxy,
-  stripe,
-  proxySessionId,
-  checkoutSessionId: checkout.checkoutSession.id,
-  cartSchema,
-  input: { interval: "year" },
-  buildNextCart: ({ currentCart, input }) => buildMerchantCart(currentCart, input),
-  buildStripeLineItems: (cart) => cart.lineItems,
-});
+if (checkout.outcome === "ready") {
+  // checkout.clientSecret -> render Stripe Elements
+
+  // Cart edits go through the binding-validated sync helper.
+  await syncCheckoutCart({
+    proxy,
+    stripe,
+    proxySessionId,
+    checkoutSessionId: checkout.checkoutSession.id,
+    cartSchema,
+    input: { interval: "year" },
+    buildNextCart: ({ currentCart, input }) => buildMerchantCart(currentCart, input),
+    buildStripeLineItems: (cart) => cart.lineItems,
+  });
+} else {
+  // Render checkout.cart plus checkout.outcome/sessionStatus. Do not start Stripe.
+}
 ```
 
 Use the delegated-checkout guide from your Proxy onboarding materials for the

package/dist/cjs/index.d.cts

@@ -1,6 +1,6 @@
 export { type ProxyStripeCartSyncCode, ProxyStripeCartSyncError, type ProxyStripeOpenCheckoutCode, ProxyStripeOpenCheckoutError, } from "./errors.js";
-export { assertCheckoutSessionBelongsToProxy, assertPaymentIntentBelongsToProxy, assertSubscriptionBelongsToProxy, injectRequiredCheckoutSessionMetadata, PROXY_SESSION_METADATA_KEY, type ProxySessionMetadata, type ProxyStripeRequiredMetadata, requiredMetadata, } from "./metadata.js";
-export { type OpenCheckoutOptions, type OpenCheckoutReconciledCart, type OpenCheckoutResult, openCheckout, } from "./open-checkout.js";
+export { assertCheckoutSessionBelongsToProxy, assertPaymentIntentBelongsToProxy, assertSubscriptionBelongsToProxy, injectRequiredCheckoutSessionMetadata, PROXY_INTEGRATION_PATH_METADATA_KEY, PROXY_SESSION_METADATA_KEY, type ProxySessionMetadata, type ProxyStripeRequiredMetadata, requiredMetadata, } from "./metadata.js";
+export { type OpenCheckoutOptions, type OpenCheckoutReconciledCart, type OpenCheckoutResponse, type OpenCheckoutResult, type OpenCheckoutTerminalResult, openCheckout, } from "./open-checkout.js";
 export { normalizePsp } from "./psp.js";
 export { type SyncCheckoutCartOptions, type SyncCheckoutCartResult, type SyncedCart, syncCheckoutCart, } from "./sync-checkout-cart.js";
 export type { StripeCheckoutSessionCreateParams, StripeCheckoutSessionLike, StripeCheckoutSessionsApiLike, StripeCheckoutSessionUpdateParams, StripeClientLike, StripeMetadata, StripePaymentIntentLike, StripeRequestOptionsLike, StripeSubscriptionLike, } from "./types.js";

package/dist/cjs/index.d.ts

@@ -1,6 +1,6 @@
 export { type ProxyStripeCartSyncCode, ProxyStripeCartSyncError, type ProxyStripeOpenCheckoutCode, ProxyStripeOpenCheckoutError, } from "./errors.js";
-export { assertCheckoutSessionBelongsToProxy, assertPaymentIntentBelongsToProxy, assertSubscriptionBelongsToProxy, injectRequiredCheckoutSessionMetadata, PROXY_SESSION_METADATA_KEY, type ProxySessionMetadata, type ProxyStripeRequiredMetadata, requiredMetadata, } from "./metadata.js";
-export { type OpenCheckoutOptions, type OpenCheckoutReconciledCart, type OpenCheckoutResult, openCheckout, } from "./open-checkout.js";
+export { assertCheckoutSessionBelongsToProxy, assertPaymentIntentBelongsToProxy, assertSubscriptionBelongsToProxy, injectRequiredCheckoutSessionMetadata, PROXY_INTEGRATION_PATH_METADATA_KEY, PROXY_SESSION_METADATA_KEY, type ProxySessionMetadata, type ProxyStripeRequiredMetadata, requiredMetadata, } from "./metadata.js";
+export { type OpenCheckoutOptions, type OpenCheckoutReconciledCart, type OpenCheckoutResponse, type OpenCheckoutResult, type OpenCheckoutTerminalResult, openCheckout, } from "./open-checkout.js";
 export { normalizePsp } from "./psp.js";
 export { type SyncCheckoutCartOptions, type SyncCheckoutCartResult, type SyncedCart, syncCheckoutCart, } from "./sync-checkout-cart.js";
 export type { StripeCheckoutSessionCreateParams, StripeCheckoutSessionLike, StripeCheckoutSessionsApiLike, StripeCheckoutSessionUpdateParams, StripeClientLike, StripeMetadata, StripePaymentIntentLike, StripeRequestOptionsLike, StripeSubscriptionLike, } from "./types.js";

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.proxyCheckoutStripeServerSdkVersion = exports.proxyCheckoutStripeServerSdkName = exports.syncCheckoutCart = exports.normalizePsp = exports.openCheckout = exports.requiredMetadata = exports.PROXY_SESSION_METADATA_KEY = exports.injectRequiredCheckoutSessionMetadata = exports.assertSubscriptionBelongsToProxy = exports.assertPaymentIntentBelongsToProxy = exports.assertCheckoutSessionBelongsToProxy = exports.ProxyStripeOpenCheckoutError = exports.ProxyStripeCartSyncError = void 0;
+exports.proxyCheckoutStripeServerSdkVersion = exports.proxyCheckoutStripeServerSdkName = exports.syncCheckoutCart = exports.normalizePsp = exports.openCheckout = exports.requiredMetadata = exports.PROXY_SESSION_METADATA_KEY = exports.PROXY_INTEGRATION_PATH_METADATA_KEY = exports.injectRequiredCheckoutSessionMetadata = exports.assertSubscriptionBelongsToProxy = exports.assertPaymentIntentBelongsToProxy = exports.assertCheckoutSessionBelongsToProxy = exports.ProxyStripeOpenCheckoutError = exports.ProxyStripeCartSyncError = void 0;
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "ProxyStripeCartSyncError", { enumerable: true, get: function () { return errors_js_1.ProxyStripeCartSyncError; } });
 Object.defineProperty(exports, "ProxyStripeOpenCheckoutError", { enumerable: true, get: function () { return errors_js_1.ProxyStripeOpenCheckoutError; } });
@@ -9,6 +9,7 @@ Object.defineProperty(exports, "assertCheckoutSessionBelongsToProxy", { enumerab
 Object.defineProperty(exports, "assertPaymentIntentBelongsToProxy", { enumerable: true, get: function () { return metadata_js_1.assertPaymentIntentBelongsToProxy; } });
 Object.defineProperty(exports, "assertSubscriptionBelongsToProxy", { enumerable: true, get: function () { return metadata_js_1.assertSubscriptionBelongsToProxy; } });
 Object.defineProperty(exports, "injectRequiredCheckoutSessionMetadata", { enumerable: true, get: function () { return metadata_js_1.injectRequiredCheckoutSessionMetadata; } });
+Object.defineProperty(exports, "PROXY_INTEGRATION_PATH_METADATA_KEY", { enumerable: true, get: function () { return metadata_js_1.PROXY_INTEGRATION_PATH_METADATA_KEY; } });
 Object.defineProperty(exports, "PROXY_SESSION_METADATA_KEY", { enumerable: true, get: function () { return metadata_js_1.PROXY_SESSION_METADATA_KEY; } });
 Object.defineProperty(exports, "requiredMetadata", { enumerable: true, get: function () { return metadata_js_1.requiredMetadata; } });
 var open_checkout_js_1 = require("./open-checkout.js");

package/dist/cjs/metadata.d.cts

@@ -9,6 +9,8 @@
 import type { StripeCheckoutSessionCreateParams, StripeCheckoutSessionLike, StripePaymentIntentLike, StripeSubscriptionLike } from "./types.js";
 /** The single metadata key Proxy reads to correlate a Stripe object to a session. */
 export declare const PROXY_SESSION_METADATA_KEY = "proxy_session_id";
+/** Server-owned marker that distinguishes Checkout-created child objects from direct objects. */
+export declare const PROXY_INTEGRATION_PATH_METADATA_KEY = "proxy_integration_path";
 export type ProxySessionMetadata = Readonly<Record<"proxy_session_id", string>>;
 /**
  * The metadata each Stripe object must carry, ready to spread into Stripe params.

package/dist/cjs/metadata.d.ts

@@ -9,6 +9,8 @@
 import type { StripeCheckoutSessionCreateParams, StripeCheckoutSessionLike, StripePaymentIntentLike, StripeSubscriptionLike } from "./types.js";
 /** The single metadata key Proxy reads to correlate a Stripe object to a session. */
 export declare const PROXY_SESSION_METADATA_KEY = "proxy_session_id";
+/** Server-owned marker that distinguishes Checkout-created child objects from direct objects. */
+export declare const PROXY_INTEGRATION_PATH_METADATA_KEY = "proxy_integration_path";
 export type ProxySessionMetadata = Readonly<Record<"proxy_session_id", string>>;
 /**
  * The metadata each Stripe object must carry, ready to spread into Stripe params.

package/dist/cjs/metadata.js

@@ -8,7 +8,7 @@
  * provides assertions that a Stripe object actually belongs to a Proxy session.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PROXY_SESSION_METADATA_KEY = void 0;
+exports.PROXY_INTEGRATION_PATH_METADATA_KEY = exports.PROXY_SESSION_METADATA_KEY = void 0;
 exports.requiredMetadata = requiredMetadata;
 exports.injectRequiredCheckoutSessionMetadata = injectRequiredCheckoutSessionMetadata;
 exports.assertCheckoutSessionBelongsToProxy = assertCheckoutSessionBelongsToProxy;
@@ -17,6 +17,8 @@ exports.assertPaymentIntentBelongsToProxy = assertPaymentIntentBelongsToProxy;
 const server_js_1 = require("@proxy-checkout/server-js");
 /** The single metadata key Proxy reads to correlate a Stripe object to a session. */
 exports.PROXY_SESSION_METADATA_KEY = "proxy_session_id";
+/** Server-owned marker that distinguishes Checkout-created child objects from direct objects. */
+exports.PROXY_INTEGRATION_PATH_METADATA_KEY = "proxy_integration_path";
 /** Build the required Stripe metadata placements for a Proxy session. */
 function requiredMetadata(proxySession) {
     const metadata = { proxy_session_id: proxySession.id };
@@ -35,14 +37,18 @@ function requiredMetadata(proxySession) {
  */
 function injectRequiredCheckoutSessionMetadata(params, proxySessionId) {
     const metadata = { proxy_session_id: proxySessionId };
+    const checkoutMetadata = {
+        ...metadata,
+        [exports.PROXY_INTEGRATION_PATH_METADATA_KEY]: "checkout_session",
+    };
     return {
         ...params,
-        metadata: mergeProxyMetadata(params.metadata, metadata, "metadata.proxy_session_id"),
+        metadata: mergeProxyMetadata(params.metadata, checkoutMetadata, "metadata"),
         ...(params.mode === "subscription" || params.subscription_data !== undefined
             ? {
                 subscription_data: {
                     ...objectRecord(params.subscription_data),
-                    metadata: mergeProxyMetadata(metadataFromNestedParams(params.subscription_data), metadata, "subscription_data.metadata.proxy_session_id"),
+                    metadata: mergeProxyMetadata(metadataFromNestedParams(params.subscription_data), checkoutMetadata, "subscription_data.metadata"),
                 },
             }
             : {}),
@@ -50,7 +56,7 @@ function injectRequiredCheckoutSessionMetadata(params, proxySessionId) {
             ? {
                 payment_intent_data: {
                     ...objectRecord(params.payment_intent_data),
-                    metadata: mergeProxyMetadata(metadataFromNestedParams(params.payment_intent_data), metadata, "payment_intent_data.metadata.proxy_session_id"),
+                    metadata: mergeProxyMetadata(metadataFromNestedParams(params.payment_intent_data), checkoutMetadata, "payment_intent_data.metadata"),
                 },
             }
             : {}),
@@ -75,9 +81,11 @@ function assertProxyMetadata(metadata, proxySessionId, objectLabel) {
     }
 }
 function mergeProxyMetadata(existing, required, field) {
-    const existingValue = existing?.[exports.PROXY_SESSION_METADATA_KEY];
-    if (existingValue !== undefined && existingValue !== required.proxy_session_id) {
-        throw new server_js_1.ProxyCheckoutValidationError(`Stripe metadata.${exports.PROXY_SESSION_METADATA_KEY} (${existingValue}) conflicts with Proxy session ${required.proxy_session_id}.`, { code: "provider_binding_mismatch", field });
+    for (const [key, requiredValue] of Object.entries(required)) {
+        const existingValue = existing?.[key];
+        if (existingValue !== undefined && existingValue !== requiredValue) {
+            throw new server_js_1.ProxyCheckoutValidationError(`Stripe ${field}.${key} (${existingValue}) conflicts with Proxy-required value ${requiredValue}.`, { code: "provider_binding_mismatch", field: `${field}.${key}` });
+        }
     }
     return {
         ...existing,

package/dist/cjs/open-checkout.d.cts

@@ -54,7 +54,28 @@ export interface OpenCheckoutResult<TCart, TOffer, TSession> {
     readonly checkoutSession: TSession;
     readonly clientSecret: string | null;
     readonly offer: TOffer;
+    readonly outcome: "ready";
     readonly proxySession: PayerOpenedResult;
     readonly proxySessionId: string;
 }
-export declare function openCheckout<TStripe extends StripeClientLike, TCart = unknown, TOffer = undefined, TSession extends StripeCheckoutSessionLike = StripeCheckoutSessionLike>(options: OpenCheckoutOptions<TStripe, TCart, TOffer>): Promise<OpenCheckoutResult<TCart, TOffer, TSession>>;
+export type OpenCheckoutTerminalResult<TCart> = {
+    readonly cart: TCart;
+    readonly outcome: "already_paid";
+    readonly proxySession: PayerOpenedResult;
+    readonly proxySessionId: string;
+    readonly sessionStatus: "paid" | "provisionable" | "provisioned" | "provisioning_failed";
+} | {
+    readonly cart: TCart;
+    readonly outcome: "action_required";
+    readonly proxySession: PayerOpenedResult;
+    readonly proxySessionId: string;
+    readonly sessionStatus: "merchant_action_required";
+} | {
+    readonly cart: TCart;
+    readonly outcome: "unavailable";
+    readonly proxySession: PayerOpenedResult;
+    readonly proxySessionId: string;
+    readonly sessionStatus: "cancelled" | "created" | "expired" | "failed";
+};
+export type OpenCheckoutResponse<TCart, TOffer, TSession> = OpenCheckoutResult<TCart, TOffer, TSession> | OpenCheckoutTerminalResult<TCart>;
+export declare function openCheckout<TStripe extends StripeClientLike, TCart = unknown, TOffer = undefined, TSession extends StripeCheckoutSessionLike = StripeCheckoutSessionLike>(options: OpenCheckoutOptions<TStripe, TCart, TOffer>): Promise<OpenCheckoutResponse<TCart, TOffer, TSession>>;

package/dist/cjs/open-checkout.d.ts

@@ -54,7 +54,28 @@ export interface OpenCheckoutResult<TCart, TOffer, TSession> {
     readonly checkoutSession: TSession;
     readonly clientSecret: string | null;
     readonly offer: TOffer;
+    readonly outcome: "ready";
     readonly proxySession: PayerOpenedResult;
     readonly proxySessionId: string;
 }
-export declare function openCheckout<TStripe extends StripeClientLike, TCart = unknown, TOffer = undefined, TSession extends StripeCheckoutSessionLike = StripeCheckoutSessionLike>(options: OpenCheckoutOptions<TStripe, TCart, TOffer>): Promise<OpenCheckoutResult<TCart, TOffer, TSession>>;
+export type OpenCheckoutTerminalResult<TCart> = {
+    readonly cart: TCart;
+    readonly outcome: "already_paid";
+    readonly proxySession: PayerOpenedResult;
+    readonly proxySessionId: string;
+    readonly sessionStatus: "paid" | "provisionable" | "provisioned" | "provisioning_failed";
+} | {
+    readonly cart: TCart;
+    readonly outcome: "action_required";
+    readonly proxySession: PayerOpenedResult;
+    readonly proxySessionId: string;
+    readonly sessionStatus: "merchant_action_required";
+} | {
+    readonly cart: TCart;
+    readonly outcome: "unavailable";
+    readonly proxySession: PayerOpenedResult;
+    readonly proxySessionId: string;
+    readonly sessionStatus: "cancelled" | "created" | "expired" | "failed";
+};
+export type OpenCheckoutResponse<TCart, TOffer, TSession> = OpenCheckoutResult<TCart, TOffer, TSession> | OpenCheckoutTerminalResult<TCart>;
+export declare function openCheckout<TStripe extends StripeClientLike, TCart = unknown, TOffer = undefined, TSession extends StripeCheckoutSessionLike = StripeCheckoutSessionLike>(options: OpenCheckoutOptions<TStripe, TCart, TOffer>): Promise<OpenCheckoutResponse<TCart, TOffer, TSession>>;

package/dist/cjs/open-checkout.js

@@ -27,6 +27,13 @@ async function openCheckout(options) {
     let cart = options.cartSchema || options.getCartBuyerReference
         ? options.proxy.sessions.parseCart(proxySession, options.cartSchema ?? ((value) => value), { getBuyerReference: options.getCartBuyerReference })
         : proxySession.cartSnapshot;
+    if (proxySession.presentationState !== "checkout_available") {
+        return terminalResultFromSession(proxySession, cart);
+    }
+    if (proxySession.status === "payment_pending" &&
+        proxySession.providerCheckoutSessionId === null) {
+        throw new server_js_1.ProxyCheckoutValidationError(`Proxy session ${proxySession.id} already has payment preparation in progress without a bound Stripe Checkout Session.`, { code: "provider_binding_missing", field: "provider_checkout_session_id" });
+    }
     let offer = options.validateCart
         ? await options.validateCart({ cart, session: proxySession })
         : undefined;
@@ -40,10 +47,14 @@ async function openCheckout(options) {
             checkoutSession,
             clientSecret: checkoutSession.client_secret ?? null,
             offer,
+            outcome: "ready",
             proxySession,
             proxySessionId: proxySession.id,
         };
     }
+    if (proxySession.currentAcquisitionAttempt !== null) {
+        throw new server_js_1.ProxyCheckoutValidationError(`Proxy session ${proxySession.id} already has acquisition ${proxySession.currentAcquisitionAttempt.id} in progress; openCheckout will not create an unrelated Stripe Checkout Session.`, { code: "provider_acquisition_in_progress", field: "current_acquisition_attempt" });
+    }
     let rollbackCart;
     const reconciledCart = await options.reconcileCart?.({ cart, offer, session: proxySession });
     if (reconciledCart) {
@@ -56,42 +67,91 @@ async function openCheckout(options) {
             cartVersion: proxySession.cartVersion,
             currency: proxySession.currency,
         };
-        const updatedCart = await options.proxy.sessions.cart.set(proxySession.id, {
-            amountMinor: reconciledCart.amountMinor,
-            cartSnapshot: reconciledCart.cartSnapshot,
-            currency: reconciledCart.currency,
-            expectedCartVersion: proxySession.cartVersion,
-            requestId: options.requestId,
-        });
-        rollbackCart = {
-            ...priorCart,
-            expectedCartVersion: updatedCart.cartVersion,
-        };
-        proxySession = {
-            ...proxySession,
-            amountMinor: updatedCart.amountMinor,
-            cartSnapshot: updatedCart.cartSnapshot,
-            cartVersion: updatedCart.cartVersion,
-            currency: updatedCart.currency,
-            updatedAt: proxySession.updatedAt,
-        };
+        try {
+            const updatedCart = await options.proxy.sessions.cart.set(proxySession.id, {
+                amountMinor: reconciledCart.amountMinor,
+                cartSnapshot: reconciledCart.cartSnapshot,
+                currency: reconciledCart.currency,
+                expectedCartVersion: proxySession.cartVersion,
+                requestId: options.requestId,
+            });
+            rollbackCart = {
+                ...priorCart,
+                expectedCartVersion: updatedCart.cartVersion,
+            };
+            proxySession = {
+                ...proxySession,
+                amountMinor: updatedCart.amountMinor,
+                cartSnapshot: updatedCart.cartSnapshot,
+                cartVersion: updatedCart.cartVersion,
+                currency: updatedCart.currency,
+                updatedAt: proxySession.updatedAt,
+            };
+        }
+        catch (cause) {
+            if (!isProxyConflict(cause)) {
+                throw cause;
+            }
+            const joined = await options.proxy.sessions.payerOpened(proxySession.id, {
+                requestId: options.requestId,
+            });
+            if (!sameCheckoutCart(joined, reconciledCart)) {
+                throw cause;
+            }
+            proxySession = joined;
+        }
         cart = reconciledCart.cart;
     }
     try {
         if (reconciledCart && options.validateCart) {
             offer = await options.validateCart({ cart, session: proxySession });
         }
+        const current = await options.proxy.sessions.payerOpened(proxySession.id, {
+            requestId: options.requestId,
+        });
+        if (current.presentationState !== "checkout_available") {
+            return terminalResultFromSession(current, cart);
+        }
+        if (!sameCheckoutCart(current, proxySession)) {
+            throw new server_js_1.ProxyCheckoutValidationError(`Proxy session ${proxySession.id} cart changed while Checkout was being prepared.`, { code: "cart_version_conflict", field: "cart_version" });
+        }
+        proxySession = current;
+        if (proxySession.providerCheckoutSessionId !== null) {
+            assertExistingBindingMatches(proxySession, psp);
+            const checkoutSession = (await options.stripe.checkout.sessions.retrieve(proxySession.providerCheckoutSessionId, undefined, options.stripeRequestOptions));
+            (0, metadata_js_1.assertCheckoutSessionBelongsToProxy)(checkoutSession, proxySession.id);
+            return {
+                binding: bindingFromSession(proxySession),
+                cart,
+                checkoutSession,
+                clientSecret: checkoutSession.client_secret ?? null,
+                offer,
+                outcome: "ready",
+                proxySession,
+                proxySessionId: proxySession.id,
+            };
+        }
+        if (proxySession.currentAcquisitionAttempt !== null) {
+            // A competing acquisition now owns the reconciled cart. Do not roll it
+            // back underneath that owner.
+            rollbackCart = undefined;
+            throw new server_js_1.ProxyCheckoutValidationError(`Proxy session ${proxySession.id} already has acquisition ${proxySession.currentAcquisitionAttempt.id} in progress; openCheckout will not create an unrelated Stripe Checkout Session.`, { code: "provider_acquisition_in_progress", field: "current_acquisition_attempt" });
+        }
         const params = await options.buildCheckoutSessionParams({
             cart,
             offer,
             proxySession,
             stripe: options.stripe,
         });
+        assertCheckoutAutomaticRecoveryDisabled(params, proxySession.id);
+        const commercialMode = checkoutCommercialMode(params, proxySession.id);
         const checkoutSession = (await options.stripe.checkout.sessions.create((0, metadata_js_1.injectRequiredCheckoutSessionMetadata)(params, proxySession.id), buildStripeRequestOptions(options, proxySession.id, psp)));
         // Fail closed if the merchant forgot to place proxy_session_id metadata.
         (0, metadata_js_1.assertCheckoutSessionBelongsToProxy)(checkoutSession, proxySession.id);
         const binding = await recordOrReconcileProviderBinding({
             checkoutSessionId: checkoutSession.id,
+            expectedCartVersion: proxySession.cartVersion,
+            commercialMode,
             proxy: options.proxy,
             proxySessionId: proxySession.id,
             psp,
@@ -105,6 +165,7 @@ async function openCheckout(options) {
             checkoutSession,
             clientSecret: checkoutSession.client_secret ?? null,
             offer,
+            outcome: "ready",
             proxySession,
             proxySessionId: proxySession.id,
         };
@@ -122,6 +183,39 @@ async function openCheckout(options) {
         throw cause;
     }
 }
+function terminalResultFromSession(proxySession, cart) {
+    const common = {
+        cart,
+        proxySession,
+        proxySessionId: proxySession.id,
+    };
+    switch (proxySession.presentationState) {
+        case "already_paid":
+            if (proxySession.status !== "paid" &&
+                proxySession.status !== "provisionable" &&
+                proxySession.status !== "provisioned" &&
+                proxySession.status !== "provisioning_failed") {
+                break;
+            }
+            return { ...common, outcome: "already_paid", sessionStatus: proxySession.status };
+        case "action_required":
+            if (proxySession.status !== "merchant_action_required") {
+                break;
+            }
+            return { ...common, outcome: "action_required", sessionStatus: proxySession.status };
+        case "unavailable":
+            if (proxySession.status !== "cancelled" &&
+                proxySession.status !== "created" &&
+                proxySession.status !== "expired" &&
+                proxySession.status !== "failed") {
+                break;
+            }
+            return { ...common, outcome: "unavailable", sessionStatus: proxySession.status };
+        case "checkout_available":
+            break;
+    }
+    throw new server_js_1.ProxyCheckoutValidationError(`Proxy session ${proxySession.id} returned an inconsistent presentation and lifecycle status.`, { code: "invalid_session_presentation", field: "presentation_state" });
+}
 function buildStripeRequestOptions(options, proxySessionId, psp) {
     return {
         ...options.stripeRequestOptions,
@@ -170,6 +264,8 @@ async function rollbackReconciledCart(input) {
 async function recordOrReconcileProviderBinding(input) {
     try {
         return await input.proxy.sessions.recordProviderBinding(input.proxySessionId, {
+            commercialMode: input.commercialMode,
+            expectedCartVersion: input.expectedCartVersion,
             providerCheckoutSessionId: input.checkoutSessionId,
             psp: input.psp,
             requestId: input.requestId,
@@ -190,6 +286,37 @@ async function recordOrReconcileProviderBinding(input) {
         });
     }
 }
+function sameCheckoutCart(actual, expected) {
+    return (actual.amountMinor === expected.amountMinor &&
+        actual.currency === expected.currency &&
+        canonicalJson(actual.cartSnapshot) === canonicalJson(expected.cartSnapshot));
+}
+function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+    }
+    if (typeof value === "object" && value !== null) {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function checkoutCommercialMode(params, proxySessionId) {
+    if (params.mode === "payment") {
+        return "one_time";
+    }
+    if (params.mode === "subscription") {
+        return "subscription";
+    }
+    throw new server_js_1.ProxyCheckoutValidationError(`Proxy session ${proxySessionId} requires Stripe Checkout mode payment or subscription.`, { code: "unsupported_provider_option", field: "mode" });
+}
+function assertCheckoutAutomaticRecoveryDisabled(params, proxySessionId) {
+    if (params.after_expiration?.recovery?.enabled === true) {
+        throw new server_js_1.ProxyCheckoutValidationError(`Proxy session ${proxySessionId} does not allow Stripe Checkout automatic recovery because replacement roots require explicit Proxy supersession.`, { code: "unsupported_provider_option", field: "after_expiration.recovery.enabled" });
+    }
+}
 async function readReconciledBinding(input) {
     const current = await input.proxy.sessions.retrieve(input.proxySessionId, {
         requestId: input.requestId,

package/dist/cjs/types.d.cts

@@ -27,6 +27,11 @@ export interface StripeCheckoutSessionUpdateParams {
     readonly metadata?: StripeMetadataParam;
 }
 export type StripeCheckoutSessionCreateParams = object & {
+    readonly after_expiration?: {
+        readonly recovery?: {
+            readonly enabled?: boolean;
+        };
+    };
     readonly metadata?: StripeMetadataParam;
     readonly mode?: "payment" | "setup" | "subscription";
     readonly payment_intent_data?: unknown;

package/dist/cjs/types.d.ts

@@ -27,6 +27,11 @@ export interface StripeCheckoutSessionUpdateParams {
     readonly metadata?: StripeMetadataParam;
 }
 export type StripeCheckoutSessionCreateParams = object & {
+    readonly after_expiration?: {
+        readonly recovery?: {
+            readonly enabled?: boolean;
+        };
+    };
     readonly metadata?: StripeMetadataParam;
     readonly mode?: "payment" | "setup" | "subscription";
     readonly payment_intent_data?: unknown;

package/dist/cjs/version.d.cts

@@ -1,2 +1,2 @@
 export declare const proxyCheckoutStripeServerSdkName = "@proxy-checkout/stripe-server-js";
-export declare const proxyCheckoutStripeServerSdkVersion = "0.0.1";
+export declare const proxyCheckoutStripeServerSdkVersion = "0.1.0-prx-124.139.1";

package/dist/cjs/version.d.ts

@@ -1,2 +1,2 @@
 export declare const proxyCheckoutStripeServerSdkName = "@proxy-checkout/stripe-server-js";
-export declare const proxyCheckoutStripeServerSdkVersion = "0.0.1";
+export declare const proxyCheckoutStripeServerSdkVersion = "0.1.0-prx-124.139.1";

package/dist/cjs/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.proxyCheckoutStripeServerSdkVersion = exports.proxyCheckoutStripeServerSdkName = void 0;
 exports.proxyCheckoutStripeServerSdkName = "@proxy-checkout/stripe-server-js";
-exports.proxyCheckoutStripeServerSdkVersion = "0.0.1";
+exports.proxyCheckoutStripeServerSdkVersion = "0.1.0-prx-124.139.1";

package/dist/esm/index.d.ts

@@ -1,6 +1,6 @@
 export { type ProxyStripeCartSyncCode, ProxyStripeCartSyncError, type ProxyStripeOpenCheckoutCode, ProxyStripeOpenCheckoutError, } from "./errors.js";
-export { assertCheckoutSessionBelongsToProxy, assertPaymentIntentBelongsToProxy, assertSubscriptionBelongsToProxy, injectRequiredCheckoutSessionMetadata, PROXY_SESSION_METADATA_KEY, type ProxySessionMetadata, type ProxyStripeRequiredMetadata, requiredMetadata, } from "./metadata.js";
-export { type OpenCheckoutOptions, type OpenCheckoutReconciledCart, type OpenCheckoutResult, openCheckout, } from "./open-checkout.js";
+export { assertCheckoutSessionBelongsToProxy, assertPaymentIntentBelongsToProxy, assertSubscriptionBelongsToProxy, injectRequiredCheckoutSessionMetadata, PROXY_INTEGRATION_PATH_METADATA_KEY, PROXY_SESSION_METADATA_KEY, type ProxySessionMetadata, type ProxyStripeRequiredMetadata, requiredMetadata, } from "./metadata.js";
+export { type OpenCheckoutOptions, type OpenCheckoutReconciledCart, type OpenCheckoutResponse, type OpenCheckoutResult, type OpenCheckoutTerminalResult, openCheckout, } from "./open-checkout.js";
 export { normalizePsp } from "./psp.js";
 export { type SyncCheckoutCartOptions, type SyncCheckoutCartResult, type SyncedCart, syncCheckoutCart, } from "./sync-checkout-cart.js";
 export type { StripeCheckoutSessionCreateParams, StripeCheckoutSessionLike, StripeCheckoutSessionsApiLike, StripeCheckoutSessionUpdateParams, StripeClientLike, StripeMetadata, StripePaymentIntentLike, StripeRequestOptionsLike, StripeSubscriptionLike, } from "./types.js";

package/dist/esm/index.js

@@ -1,5 +1,5 @@
 export { ProxyStripeCartSyncError, ProxyStripeOpenCheckoutError, } from "./errors.js";
-export { assertCheckoutSessionBelongsToProxy, assertPaymentIntentBelongsToProxy, assertSubscriptionBelongsToProxy, injectRequiredCheckoutSessionMetadata, PROXY_SESSION_METADATA_KEY, requiredMetadata, } from "./metadata.js";
+export { assertCheckoutSessionBelongsToProxy, assertPaymentIntentBelongsToProxy, assertSubscriptionBelongsToProxy, injectRequiredCheckoutSessionMetadata, PROXY_INTEGRATION_PATH_METADATA_KEY, PROXY_SESSION_METADATA_KEY, requiredMetadata, } from "./metadata.js";
 export { openCheckout, } from "./open-checkout.js";
 export { normalizePsp } from "./psp.js";
 export { syncCheckoutCart, } from "./sync-checkout-cart.js";

package/dist/esm/metadata.d.ts

@@ -9,6 +9,8 @@
 import type { StripeCheckoutSessionCreateParams, StripeCheckoutSessionLike, StripePaymentIntentLike, StripeSubscriptionLike } from "./types.js";
 /** The single metadata key Proxy reads to correlate a Stripe object to a session. */
 export declare const PROXY_SESSION_METADATA_KEY = "proxy_session_id";
+/** Server-owned marker that distinguishes Checkout-created child objects from direct objects. */
+export declare const PROXY_INTEGRATION_PATH_METADATA_KEY = "proxy_integration_path";
 export type ProxySessionMetadata = Readonly<Record<"proxy_session_id", string>>;
 /**
  * The metadata each Stripe object must carry, ready to spread into Stripe params.

package/dist/esm/metadata.js

@@ -9,6 +9,8 @@
 import { ProxyCheckoutValidationError } from "@proxy-checkout/server-js";
 /** The single metadata key Proxy reads to correlate a Stripe object to a session. */
 export const PROXY_SESSION_METADATA_KEY = "proxy_session_id";
+/** Server-owned marker that distinguishes Checkout-created child objects from direct objects. */
+export const PROXY_INTEGRATION_PATH_METADATA_KEY = "proxy_integration_path";
 /** Build the required Stripe metadata placements for a Proxy session. */
 export function requiredMetadata(proxySession) {
     const metadata = { proxy_session_id: proxySession.id };
@@ -27,14 +29,18 @@ export function requiredMetadata(proxySession) {
  */
 export function injectRequiredCheckoutSessionMetadata(params, proxySessionId) {
     const metadata = { proxy_session_id: proxySessionId };
+    const checkoutMetadata = {
+        ...metadata,
+        [PROXY_INTEGRATION_PATH_METADATA_KEY]: "checkout_session",
+    };
     return {
         ...params,
-        metadata: mergeProxyMetadata(params.metadata, metadata, "metadata.proxy_session_id"),
+        metadata: mergeProxyMetadata(params.metadata, checkoutMetadata, "metadata"),
         ...(params.mode === "subscription" || params.subscription_data !== undefined
             ? {
                 subscription_data: {
                     ...objectRecord(params.subscription_data),
-                    metadata: mergeProxyMetadata(metadataFromNestedParams(params.subscription_data), metadata, "subscription_data.metadata.proxy_session_id"),
+                    metadata: mergeProxyMetadata(metadataFromNestedParams(params.subscription_data), checkoutMetadata, "subscription_data.metadata"),
                 },
             }
             : {}),
@@ -42,7 +48,7 @@ export function injectRequiredCheckoutSessionMetadata(params, proxySessionId) {
             ? {
                 payment_intent_data: {
                     ...objectRecord(params.payment_intent_data),
-                    metadata: mergeProxyMetadata(metadataFromNestedParams(params.payment_intent_data), metadata, "payment_intent_data.metadata.proxy_session_id"),
+                    metadata: mergeProxyMetadata(metadataFromNestedParams(params.payment_intent_data), checkoutMetadata, "payment_intent_data.metadata"),
                 },
             }
             : {}),
@@ -67,9 +73,11 @@ function assertProxyMetadata(metadata, proxySessionId, objectLabel) {
     }
 }
 function mergeProxyMetadata(existing, required, field) {
-    const existingValue = existing?.[PROXY_SESSION_METADATA_KEY];
-    if (existingValue !== undefined && existingValue !== required.proxy_session_id) {
-        throw new ProxyCheckoutValidationError(`Stripe metadata.${PROXY_SESSION_METADATA_KEY} (${existingValue}) conflicts with Proxy session ${required.proxy_session_id}.`, { code: "provider_binding_mismatch", field });
+    for (const [key, requiredValue] of Object.entries(required)) {
+        const existingValue = existing?.[key];
+        if (existingValue !== undefined && existingValue !== requiredValue) {
+            throw new ProxyCheckoutValidationError(`Stripe ${field}.${key} (${existingValue}) conflicts with Proxy-required value ${requiredValue}.`, { code: "provider_binding_mismatch", field: `${field}.${key}` });
+        }
     }
     return {
         ...existing,

package/dist/esm/open-checkout.d.ts

@@ -54,7 +54,28 @@ export interface OpenCheckoutResult<TCart, TOffer, TSession> {
     readonly checkoutSession: TSession;
     readonly clientSecret: string | null;
     readonly offer: TOffer;
+    readonly outcome: "ready";
     readonly proxySession: PayerOpenedResult;
     readonly proxySessionId: string;
 }
-export declare function openCheckout<TStripe extends StripeClientLike, TCart = unknown, TOffer = undefined, TSession extends StripeCheckoutSessionLike = StripeCheckoutSessionLike>(options: OpenCheckoutOptions<TStripe, TCart, TOffer>): Promise<OpenCheckoutResult<TCart, TOffer, TSession>>;
+export type OpenCheckoutTerminalResult<TCart> = {
+    readonly cart: TCart;
+    readonly outcome: "already_paid";
+    readonly proxySession: PayerOpenedResult;
+    readonly proxySessionId: string;
+    readonly sessionStatus: "paid" | "provisionable" | "provisioned" | "provisioning_failed";
+} | {
+    readonly cart: TCart;
+    readonly outcome: "action_required";
+    readonly proxySession: PayerOpenedResult;
+    readonly proxySessionId: string;
+    readonly sessionStatus: "merchant_action_required";
+} | {
+    readonly cart: TCart;
+    readonly outcome: "unavailable";
+    readonly proxySession: PayerOpenedResult;
+    readonly proxySessionId: string;
+    readonly sessionStatus: "cancelled" | "created" | "expired" | "failed";
+};
+export type OpenCheckoutResponse<TCart, TOffer, TSession> = OpenCheckoutResult<TCart, TOffer, TSession> | OpenCheckoutTerminalResult<TCart>;
+export declare function openCheckout<TStripe extends StripeClientLike, TCart = unknown, TOffer = undefined, TSession extends StripeCheckoutSessionLike = StripeCheckoutSessionLike>(options: OpenCheckoutOptions<TStripe, TCart, TOffer>): Promise<OpenCheckoutResponse<TCart, TOffer, TSession>>;

package/dist/esm/open-checkout.js

@@ -24,6 +24,13 @@ export async function openCheckout(options) {
     let cart = options.cartSchema || options.getCartBuyerReference
         ? options.proxy.sessions.parseCart(proxySession, options.cartSchema ?? ((value) => value), { getBuyerReference: options.getCartBuyerReference })
         : proxySession.cartSnapshot;
+    if (proxySession.presentationState !== "checkout_available") {
+        return terminalResultFromSession(proxySession, cart);
+    }
+    if (proxySession.status === "payment_pending" &&
+        proxySession.providerCheckoutSessionId === null) {
+        throw new ProxyCheckoutValidationError(`Proxy session ${proxySession.id} already has payment preparation in progress without a bound Stripe Checkout Session.`, { code: "provider_binding_missing", field: "provider_checkout_session_id" });
+    }
     let offer = options.validateCart
         ? await options.validateCart({ cart, session: proxySession })
         : undefined;
@@ -37,10 +44,14 @@ export async function openCheckout(options) {
             checkoutSession,
             clientSecret: checkoutSession.client_secret ?? null,
             offer,
+            outcome: "ready",
             proxySession,
             proxySessionId: proxySession.id,
         };
     }
+    if (proxySession.currentAcquisitionAttempt !== null) {
+        throw new ProxyCheckoutValidationError(`Proxy session ${proxySession.id} already has acquisition ${proxySession.currentAcquisitionAttempt.id} in progress; openCheckout will not create an unrelated Stripe Checkout Session.`, { code: "provider_acquisition_in_progress", field: "current_acquisition_attempt" });
+    }
     let rollbackCart;
     const reconciledCart = await options.reconcileCart?.({ cart, offer, session: proxySession });
     if (reconciledCart) {
@@ -53,42 +64,91 @@ export async function openCheckout(options) {
             cartVersion: proxySession.cartVersion,
             currency: proxySession.currency,
         };
-        const updatedCart = await options.proxy.sessions.cart.set(proxySession.id, {
-            amountMinor: reconciledCart.amountMinor,
-            cartSnapshot: reconciledCart.cartSnapshot,
-            currency: reconciledCart.currency,
-            expectedCartVersion: proxySession.cartVersion,
-            requestId: options.requestId,
-        });
-        rollbackCart = {
-            ...priorCart,
-            expectedCartVersion: updatedCart.cartVersion,
-        };
-        proxySession = {
-            ...proxySession,
-            amountMinor: updatedCart.amountMinor,
-            cartSnapshot: updatedCart.cartSnapshot,
-            cartVersion: updatedCart.cartVersion,
-            currency: updatedCart.currency,
-            updatedAt: proxySession.updatedAt,
-        };
+        try {
+            const updatedCart = await options.proxy.sessions.cart.set(proxySession.id, {
+                amountMinor: reconciledCart.amountMinor,
+                cartSnapshot: reconciledCart.cartSnapshot,
+                currency: reconciledCart.currency,
+                expectedCartVersion: proxySession.cartVersion,
+                requestId: options.requestId,
+            });
+            rollbackCart = {
+                ...priorCart,
+                expectedCartVersion: updatedCart.cartVersion,
+            };
+            proxySession = {
+                ...proxySession,
+                amountMinor: updatedCart.amountMinor,
+                cartSnapshot: updatedCart.cartSnapshot,
+                cartVersion: updatedCart.cartVersion,
+                currency: updatedCart.currency,
+                updatedAt: proxySession.updatedAt,
+            };
+        }
+        catch (cause) {
+            if (!isProxyConflict(cause)) {
+                throw cause;
+            }
+            const joined = await options.proxy.sessions.payerOpened(proxySession.id, {
+                requestId: options.requestId,
+            });
+            if (!sameCheckoutCart(joined, reconciledCart)) {
+                throw cause;
+            }
+            proxySession = joined;
+        }
         cart = reconciledCart.cart;
     }
     try {
         if (reconciledCart && options.validateCart) {
             offer = await options.validateCart({ cart, session: proxySession });
         }
+        const current = await options.proxy.sessions.payerOpened(proxySession.id, {
+            requestId: options.requestId,
+        });
+        if (current.presentationState !== "checkout_available") {
+            return terminalResultFromSession(current, cart);
+        }
+        if (!sameCheckoutCart(current, proxySession)) {
+            throw new ProxyCheckoutValidationError(`Proxy session ${proxySession.id} cart changed while Checkout was being prepared.`, { code: "cart_version_conflict", field: "cart_version" });
+        }
+        proxySession = current;
+        if (proxySession.providerCheckoutSessionId !== null) {
+            assertExistingBindingMatches(proxySession, psp);
+            const checkoutSession = (await options.stripe.checkout.sessions.retrieve(proxySession.providerCheckoutSessionId, undefined, options.stripeRequestOptions));
+            assertCheckoutSessionBelongsToProxy(checkoutSession, proxySession.id);
+            return {
+                binding: bindingFromSession(proxySession),
+                cart,
+                checkoutSession,
+                clientSecret: checkoutSession.client_secret ?? null,
+                offer,
+                outcome: "ready",
+                proxySession,
+                proxySessionId: proxySession.id,
+            };
+        }
+        if (proxySession.currentAcquisitionAttempt !== null) {
+            // A competing acquisition now owns the reconciled cart. Do not roll it
+            // back underneath that owner.
+            rollbackCart = undefined;
+            throw new ProxyCheckoutValidationError(`Proxy session ${proxySession.id} already has acquisition ${proxySession.currentAcquisitionAttempt.id} in progress; openCheckout will not create an unrelated Stripe Checkout Session.`, { code: "provider_acquisition_in_progress", field: "current_acquisition_attempt" });
+        }
         const params = await options.buildCheckoutSessionParams({
             cart,
             offer,
             proxySession,
             stripe: options.stripe,
         });
+        assertCheckoutAutomaticRecoveryDisabled(params, proxySession.id);
+        const commercialMode = checkoutCommercialMode(params, proxySession.id);
         const checkoutSession = (await options.stripe.checkout.sessions.create(injectRequiredCheckoutSessionMetadata(params, proxySession.id), buildStripeRequestOptions(options, proxySession.id, psp)));
         // Fail closed if the merchant forgot to place proxy_session_id metadata.
         assertCheckoutSessionBelongsToProxy(checkoutSession, proxySession.id);
         const binding = await recordOrReconcileProviderBinding({
             checkoutSessionId: checkoutSession.id,
+            expectedCartVersion: proxySession.cartVersion,
+            commercialMode,
             proxy: options.proxy,
             proxySessionId: proxySession.id,
             psp,
@@ -102,6 +162,7 @@ export async function openCheckout(options) {
             checkoutSession,
             clientSecret: checkoutSession.client_secret ?? null,
             offer,
+            outcome: "ready",
             proxySession,
             proxySessionId: proxySession.id,
         };
@@ -119,6 +180,39 @@ export async function openCheckout(options) {
         throw cause;
     }
 }
+function terminalResultFromSession(proxySession, cart) {
+    const common = {
+        cart,
+        proxySession,
+        proxySessionId: proxySession.id,
+    };
+    switch (proxySession.presentationState) {
+        case "already_paid":
+            if (proxySession.status !== "paid" &&
+                proxySession.status !== "provisionable" &&
+                proxySession.status !== "provisioned" &&
+                proxySession.status !== "provisioning_failed") {
+                break;
+            }
+            return { ...common, outcome: "already_paid", sessionStatus: proxySession.status };
+        case "action_required":
+            if (proxySession.status !== "merchant_action_required") {
+                break;
+            }
+            return { ...common, outcome: "action_required", sessionStatus: proxySession.status };
+        case "unavailable":
+            if (proxySession.status !== "cancelled" &&
+                proxySession.status !== "created" &&
+                proxySession.status !== "expired" &&
+                proxySession.status !== "failed") {
+                break;
+            }
+            return { ...common, outcome: "unavailable", sessionStatus: proxySession.status };
+        case "checkout_available":
+            break;
+    }
+    throw new ProxyCheckoutValidationError(`Proxy session ${proxySession.id} returned an inconsistent presentation and lifecycle status.`, { code: "invalid_session_presentation", field: "presentation_state" });
+}
 function buildStripeRequestOptions(options, proxySessionId, psp) {
     return {
         ...options.stripeRequestOptions,
@@ -167,6 +261,8 @@ async function rollbackReconciledCart(input) {
 async function recordOrReconcileProviderBinding(input) {
     try {
         return await input.proxy.sessions.recordProviderBinding(input.proxySessionId, {
+            commercialMode: input.commercialMode,
+            expectedCartVersion: input.expectedCartVersion,
             providerCheckoutSessionId: input.checkoutSessionId,
             psp: input.psp,
             requestId: input.requestId,
@@ -187,6 +283,37 @@ async function recordOrReconcileProviderBinding(input) {
         });
     }
 }
+function sameCheckoutCart(actual, expected) {
+    return (actual.amountMinor === expected.amountMinor &&
+        actual.currency === expected.currency &&
+        canonicalJson(actual.cartSnapshot) === canonicalJson(expected.cartSnapshot));
+}
+function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+    }
+    if (typeof value === "object" && value !== null) {
+        return `{${Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+function checkoutCommercialMode(params, proxySessionId) {
+    if (params.mode === "payment") {
+        return "one_time";
+    }
+    if (params.mode === "subscription") {
+        return "subscription";
+    }
+    throw new ProxyCheckoutValidationError(`Proxy session ${proxySessionId} requires Stripe Checkout mode payment or subscription.`, { code: "unsupported_provider_option", field: "mode" });
+}
+function assertCheckoutAutomaticRecoveryDisabled(params, proxySessionId) {
+    if (params.after_expiration?.recovery?.enabled === true) {
+        throw new ProxyCheckoutValidationError(`Proxy session ${proxySessionId} does not allow Stripe Checkout automatic recovery because replacement roots require explicit Proxy supersession.`, { code: "unsupported_provider_option", field: "after_expiration.recovery.enabled" });
+    }
+}
 async function readReconciledBinding(input) {
     const current = await input.proxy.sessions.retrieve(input.proxySessionId, {
         requestId: input.requestId,

package/dist/esm/types.d.ts

@@ -27,6 +27,11 @@ export interface StripeCheckoutSessionUpdateParams {
     readonly metadata?: StripeMetadataParam;
 }
 export type StripeCheckoutSessionCreateParams = object & {
+    readonly after_expiration?: {
+        readonly recovery?: {
+            readonly enabled?: boolean;
+        };
+    };
     readonly metadata?: StripeMetadataParam;
     readonly mode?: "payment" | "setup" | "subscription";
     readonly payment_intent_data?: unknown;

package/dist/esm/version.d.ts

@@ -1,2 +1,2 @@
 export declare const proxyCheckoutStripeServerSdkName = "@proxy-checkout/stripe-server-js";
-export declare const proxyCheckoutStripeServerSdkVersion = "0.0.1";
+export declare const proxyCheckoutStripeServerSdkVersion = "0.1.0-prx-124.139.1";

package/dist/esm/version.js

@@ -1,2 +1,2 @@
 export const proxyCheckoutStripeServerSdkName = "@proxy-checkout/stripe-server-js";
-export const proxyCheckoutStripeServerSdkVersion = "0.0.1";
+export const proxyCheckoutStripeServerSdkVersion = "0.1.0-prx-124.139.1";

package/package.json

@@ -7,14 +7,14 @@
   "sideEffects": false,
   "type": "module",
   "types": "./dist/esm/index.d.ts",
-  "version": "0.0.1",
+  "version": "0.1.0-prx-124.139.1",
   "devDependencies": {
     "@types/node": "^24.12.4",
     "@vitest/coverage-v8": "4.1.7",
     "stripe": "^21.0.1",
     "typescript": "^6.0.3",
     "vitest": "4.1.7",
-    "@proxy-checkout/server-js": "0.0.4"
+    "@proxy-checkout/server-js": "0.1.0-prx-124.139.1"
   },
   "exports": {
     ".": {
@@ -41,7 +41,7 @@
     "sdk"
   ],
   "peerDependencies": {
-    "@proxy-checkout/server-js": ">=0.0.4-0 <0.1.0"
+    "@proxy-checkout/server-js": ">=0.1.0-0 <0.2.0"
   },
   "publishConfig": {
     "access": "public"
@@ -54,6 +54,7 @@
   "scripts": {
     "build": "node ../../scripts/sdk/build-dual-package.mjs",
     "test:all": "vitest run",
+    "test:ci": "pnpm run test:coverage",
     "test:coverage": "vitest run --coverage.enabled --coverage.reportsDirectory=coverage/all",
     "test:coverage:changed": "vitest run --coverage.enabled --coverage.reportsDirectory=coverage/changed",
     "test:coverage:integration": "vitest run --project integration --coverage.enabled --coverage.reportsDirectory=coverage/integration",