@proxy-checkout/stripe-server-js 0.0.1 → 0.1.0-prx-124.137.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 { 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 { 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/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) {
@@ -87,11 +98,14 @@ async function openCheckout(options) {
             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,
+            commercialMode,
             proxy: options.proxy,
             proxySessionId: proxySession.id,
             psp,
@@ -105,6 +119,7 @@ async function openCheckout(options) {
             checkoutSession,
             clientSecret: checkoutSession.client_secret ?? null,
             offer,
+            outcome: "ready",
             proxySession,
             proxySessionId: proxySession.id,
         };
@@ -122,6 +137,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 +218,7 @@ async function rollbackReconciledCart(input) {
 async function recordOrReconcileProviderBinding(input) {
     try {
         return await input.proxy.sessions.recordProviderBinding(input.proxySessionId, {
+            commercialMode: input.commercialMode,
             providerCheckoutSessionId: input.checkoutSessionId,
             psp: input.psp,
             requestId: input.requestId,
@@ -190,6 +239,20 @@ async function recordOrReconcileProviderBinding(input) {
         });
     }
 }
+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.137.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.137.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.137.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 { 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/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) {
@@ -84,11 +95,14 @@ export async function openCheckout(options) {
             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,
+            commercialMode,
             proxy: options.proxy,
             proxySessionId: proxySession.id,
             psp,
@@ -102,6 +116,7 @@ export async function openCheckout(options) {
             checkoutSession,
             clientSecret: checkoutSession.client_secret ?? null,
             offer,
+            outcome: "ready",
             proxySession,
             proxySessionId: proxySession.id,
         };
@@ -119,6 +134,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 +215,7 @@ async function rollbackReconciledCart(input) {
 async function recordOrReconcileProviderBinding(input) {
     try {
         return await input.proxy.sessions.recordProviderBinding(input.proxySessionId, {
+            commercialMode: input.commercialMode,
             providerCheckoutSessionId: input.checkoutSessionId,
             psp: input.psp,
             requestId: input.requestId,
@@ -187,6 +236,20 @@ async function recordOrReconcileProviderBinding(input) {
         });
     }
 }
+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.137.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.137.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.137.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.137.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",