@proxy-checkout/stripe-server-js 0.0.0-pr-76.18.1 → 0.0.0-pr-76.20.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 the typed cart, supplies required metadata, records the Proxy provider binding, and returns the client secret. The merchant only supplies an app-specific Stripe-session builder.
+- **`openCheckout(...)`** — records payer-opened, validates the typed cart, 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.
 - **`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.
@@ -32,13 +32,11 @@ const checkout = await openCheckout({
   proxySessionId,
   cartSchema, // a zod-style schema, or any (value) => Cart validator
   validateCart: ({ cart }) => buildMerchantOffer(cart),
-  createCheckoutSession: ({ stripe, cart, metadata }) =>
-    stripe.checkout.sessions.create({
-      ...buildMerchantStripeParams(cart),
-      ui_mode: "embedded",
-      metadata: { ...metadata.checkoutSession },
-      subscription_data: { metadata: metadata.subscriptionData.metadata },
-    }),
+  buildCheckoutSessionParams: ({ cart, offer }) => ({
+    ...buildMerchantStripeParams(cart, offer),
+    mode: "subscription",
+    ui_mode: "embedded",
+  }),
 });
 // checkout.clientSecret -> render Stripe Elements
 
@@ -55,4 +53,6 @@ await syncCheckoutCart({
 });
 ```
 
-See the [agentic delegated-checkout guide](https://github.com/linuslabs/proxy/blob/main/docs/integration/agentic-delegated-checkout-guide.md) for the full four-route integration recipe.
+Use the delegated-checkout guide from your Proxy onboarding materials for the
+full four-route integration recipe. Do not link customers or coding agents to
+the private Proxy repository from published package docs.

package/dist/errors.d.ts

@@ -4,6 +4,24 @@
  * restored to its prior state, so callers can react deterministically.
  */
 export type ProxyStripeCartSyncCode = "reconciliation_failed" | "stripe_update_failed";
+export type ProxyStripeOpenCheckoutCode = "provider_binding_failed";
+/**
+ * Raised after Stripe Checkout creation succeeds but the Proxy binding cannot
+ * be recorded or reconciled. The provider id is exposed so operators can find
+ * and expire/refund the orphaned provider object deterministically.
+ */
+export declare class ProxyStripeOpenCheckoutError extends Error {
+    readonly name = "ProxyStripeOpenCheckoutError";
+    readonly code: ProxyStripeOpenCheckoutCode;
+    readonly cause: unknown;
+    readonly providerCheckoutSessionId: string;
+    readonly reconciled = false;
+    constructor(message: string, details: {
+        cause: unknown;
+        code: ProxyStripeOpenCheckoutCode;
+        providerCheckoutSessionId: string;
+    });
+}
 export declare class ProxyStripeCartSyncError extends Error {
     readonly name = "ProxyStripeCartSyncError";
     readonly code: ProxyStripeCartSyncCode;

package/dist/errors.js

@@ -1,3 +1,21 @@
+/**
+ * Raised after Stripe Checkout creation succeeds but the Proxy binding cannot
+ * be recorded or reconciled. The provider id is exposed so operators can find
+ * and expire/refund the orphaned provider object deterministically.
+ */
+export class ProxyStripeOpenCheckoutError extends Error {
+    name = "ProxyStripeOpenCheckoutError";
+    code;
+    cause;
+    providerCheckoutSessionId;
+    reconciled = false;
+    constructor(message, details) {
+        super(message);
+        this.cause = details.cause;
+        this.code = details.code;
+        this.providerCheckoutSessionId = details.providerCheckoutSessionId;
+    }
+}
 export class ProxyStripeCartSyncError extends Error {
     name = "ProxyStripeCartSyncError";
     code;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { type ProxyStripeCartSyncCode, ProxyStripeCartSyncError, } from "./errors.js";
-export { assertCheckoutSessionBelongsToProxy, assertPaymentIntentBelongsToProxy, assertSubscriptionBelongsToProxy, PROXY_SESSION_METADATA_KEY, type ProxySessionMetadata, type ProxyStripeRequiredMetadata, requiredMetadata, } from "./metadata.js";
-export { type OpenCheckoutOptions, type OpenCheckoutResult, openCheckout, } from "./open-checkout.js";
+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 { normalizePsp } from "./psp.js";
 export { type SyncCheckoutCartOptions, type SyncCheckoutCartResult, type SyncedCart, syncCheckoutCart, } from "./sync-checkout-cart.js";
-export type { StripeCheckoutSessionLike, StripeCheckoutSessionsApiLike, StripeCheckoutSessionUpdateParams, StripeClientLike, StripeMetadata, StripePaymentIntentLike, StripeSubscriptionLike, } from "./types.js";
+export type { StripeCheckoutSessionCreateParams, StripeCheckoutSessionLike, StripeCheckoutSessionsApiLike, StripeCheckoutSessionUpdateParams, StripeClientLike, StripeMetadata, StripePaymentIntentLike, StripeRequestOptionsLike, StripeSubscriptionLike, } from "./types.js";
 export { proxyCheckoutStripeServerSdkName, proxyCheckoutStripeServerSdkVersion, } from "./version.js";

package/dist/index.js

@@ -1,5 +1,5 @@
-export { ProxyStripeCartSyncError, } from "./errors.js";
-export { assertCheckoutSessionBelongsToProxy, assertPaymentIntentBelongsToProxy, assertSubscriptionBelongsToProxy, PROXY_SESSION_METADATA_KEY, requiredMetadata, } from "./metadata.js";
+export { ProxyStripeCartSyncError, ProxyStripeOpenCheckoutError, } from "./errors.js";
+export { assertCheckoutSessionBelongsToProxy, assertPaymentIntentBelongsToProxy, assertSubscriptionBelongsToProxy, injectRequiredCheckoutSessionMetadata, 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/metadata.d.ts

@@ -6,7 +6,7 @@
  * customers never have to remember which Stripe objects need the key, and
  * provides assertions that a Stripe object actually belongs to a Proxy session.
  */
-import type { StripeCheckoutSessionLike, StripePaymentIntentLike, StripeSubscriptionLike } from "./types.js";
+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";
 export type ProxySessionMetadata = Readonly<Record<"proxy_session_id", string>>;
@@ -32,6 +32,12 @@ export interface ProxyStripeRequiredMetadata {
 export declare function requiredMetadata(proxySession: {
     id: string;
 }): ProxyStripeRequiredMetadata;
+/**
+ * Return Stripe Checkout Session create params with required Proxy metadata in
+ * every object Proxy may later need to correlate. Conflicting merchant-provided
+ * proxy metadata fails before any Stripe side effect.
+ */
+export declare function injectRequiredCheckoutSessionMetadata(params: StripeCheckoutSessionCreateParams, proxySessionId: string): StripeCheckoutSessionCreateParams;
 /** Assert a Stripe Checkout Session carries the expected `proxy_session_id` metadata. */
 export declare function assertCheckoutSessionBelongsToProxy(checkoutSession: Pick<StripeCheckoutSessionLike, "metadata">, proxySessionId: string): void;
 /** Assert a Stripe Subscription carries the expected `proxy_session_id` metadata. */

package/dist/metadata.js

@@ -20,6 +20,34 @@ export function requiredMetadata(proxySession) {
         subscriptionData: { metadata },
     };
 }
+/**
+ * Return Stripe Checkout Session create params with required Proxy metadata in
+ * every object Proxy may later need to correlate. Conflicting merchant-provided
+ * proxy metadata fails before any Stripe side effect.
+ */
+export function injectRequiredCheckoutSessionMetadata(params, proxySessionId) {
+    const metadata = { proxy_session_id: proxySessionId };
+    return {
+        ...params,
+        metadata: mergeProxyMetadata(params.metadata, metadata, "metadata.proxy_session_id"),
+        ...(params.mode === "subscription" || params.subscription_data !== undefined
+            ? {
+                subscription_data: {
+                    ...params.subscription_data,
+                    metadata: mergeProxyMetadata(params.subscription_data?.metadata, metadata, "subscription_data.metadata.proxy_session_id"),
+                },
+            }
+            : {}),
+        ...(params.mode === "payment" || params.payment_intent_data !== undefined
+            ? {
+                payment_intent_data: {
+                    ...params.payment_intent_data,
+                    metadata: mergeProxyMetadata(params.payment_intent_data?.metadata, metadata, "payment_intent_data.metadata.proxy_session_id"),
+                },
+            }
+            : {}),
+    };
+}
 /** Assert a Stripe Checkout Session carries the expected `proxy_session_id` metadata. */
 export function assertCheckoutSessionBelongsToProxy(checkoutSession, proxySessionId) {
     assertProxyMetadata(checkoutSession.metadata, proxySessionId, "Stripe checkout session");
@@ -38,3 +66,13 @@ function assertProxyMetadata(metadata, proxySessionId, objectLabel) {
         throw new ProxyCheckoutValidationError(`${objectLabel} metadata.${PROXY_SESSION_METADATA_KEY} (${value ?? "missing"}) does not match Proxy session ${proxySessionId}.`, { code: "provider_binding_mismatch", field: `metadata.${PROXY_SESSION_METADATA_KEY}` });
     }
 }
+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 });
+    }
+    return {
+        ...existing,
+        ...required,
+    };
+}

package/dist/open-checkout.d.ts

@@ -2,24 +2,22 @@
  * `openCheckout` — the payer-opened + provider-object creation workflow.
  *
  * It performs the Proxy protocol steps (record payer-opened, validate the cart,
- * supply required metadata, record the provider binding) and delegates only the
- * app-specific Stripe object creation to the merchant callback. This makes it
- * hard to create a Stripe checkout that is not correctly linked to a session.
+ * inject required metadata, create the Stripe Checkout Session, record the
+ * provider binding). Merchants provide only Stripe params, so the adapter owns
+ * metadata placement, idempotency, and binding reconciliation.
  */
-import type { PayerOpenedResult, ProxyCartValidator, ProxyCheckoutServerClient } from "@proxy-checkout/server-js";
-import type { ProxyStripeRequiredMetadata } from "./metadata.js";
-import type { StripeCheckoutSessionLike } from "./types.js";
-export interface OpenCheckoutOptions<TStripe, TCart, TOffer, TSession> {
-    /** Optional schema validating the session cart snapshot into a typed cart. */
-    readonly cartSchema?: ProxyCartValidator<TCart>;
-    /** Builds the Stripe checkout object. Must place `metadata.checkoutSession` (and subscription/payment-intent metadata) on the created object. */
-    readonly createCheckoutSession: (input: {
+import type { JsonObject, PayerOpenedResult, ProxyCartValidator, ProxyCheckoutServerClient, ProxySessionProviderBinding } from "@proxy-checkout/server-js";
+import type { StripeCheckoutSessionCreateParams, StripeCheckoutSessionLike, StripeClientLike, StripeRequestOptionsWithoutIdempotencyLike } from "./types.js";
+export interface OpenCheckoutOptions<TStripe extends StripeClientLike, TCart, TOffer> {
+    /** Builds app-specific Stripe Checkout Session params. Proxy metadata is injected by the SDK. */
+    readonly buildCheckoutSessionParams: (input: {
         cart: TCart;
-        metadata: ProxyStripeRequiredMetadata;
         offer: TOffer;
         proxySession: PayerOpenedResult;
         stripe: TStripe;
-    }) => Promise<TSession> | TSession;
+    }) => Promise<StripeCheckoutSessionCreateParams> | StripeCheckoutSessionCreateParams;
+    /** Optional schema validating the session cart snapshot into a typed cart. */
+    readonly cartSchema?: ProxyCartValidator<TCart>;
     /** Optional extractor used to assert the cart buyer reference matches the session. */
     readonly getCartBuyerReference?: (cart: TCart) => string | null | undefined;
     /** A Proxy server SDK client. */
@@ -27,17 +25,31 @@ export interface OpenCheckoutOptions<TStripe, TCart, TOffer, TSession> {
     readonly proxySessionId: string;
     /** Provider identifier recorded with the binding. Defaults to "stripe". */
     readonly psp?: string;
+    /** Optional cart reconciliation before Stripe creation. The SDK performs the versioned Proxy cart write. */
+    readonly reconcileCart?: (input: {
+        cart: TCart;
+        offer: TOffer;
+        session: PayerOpenedResult;
+    }) => OpenCheckoutReconciledCart<TCart> | Promise<OpenCheckoutReconciledCart<TCart>> | null | undefined;
     readonly requestId?: string;
-    /** The merchant's Stripe instance, forwarded to `createCheckoutSession`. */
+    /** The merchant's Stripe instance. */
     readonly stripe: TStripe;
+    /** Optional Stripe request options. The SDK owns the deterministic idempotency key. */
+    readonly stripeRequestOptions?: StripeRequestOptionsWithoutIdempotencyLike;
     /** Optional merchant cart validation that derives an app-specific offer. */
     readonly validateCart?: (input: {
         cart: TCart;
         session: PayerOpenedResult;
     }) => Promise<TOffer> | TOffer;
 }
+export interface OpenCheckoutReconciledCart<TCart> {
+    readonly amountMinor: number;
+    readonly cart: TCart;
+    readonly cartSnapshot: JsonObject;
+    readonly currency: string;
+}
 export interface OpenCheckoutResult<TCart, TOffer, TSession> {
-    readonly binding: Awaited<ReturnType<ProxyCheckoutServerClient["sessions"]["recordProviderBinding"]>>;
+    readonly binding: ProxySessionProviderBinding;
     readonly cart: TCart;
     readonly checkoutSession: TSession;
     readonly clientSecret: string | null;
@@ -45,4 +57,4 @@ export interface OpenCheckoutResult<TCart, TOffer, TSession> {
     readonly proxySession: PayerOpenedResult;
     readonly proxySessionId: string;
 }
-export declare function openCheckout<TStripe, TCart = unknown, TOffer = undefined, TSession extends StripeCheckoutSessionLike = StripeCheckoutSessionLike>(options: OpenCheckoutOptions<TStripe, TCart, TOffer, TSession>): Promise<OpenCheckoutResult<TCart, TOffer, TSession>>;
+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>>;

package/dist/open-checkout.js

@@ -2,43 +2,80 @@
  * `openCheckout` — the payer-opened + provider-object creation workflow.
  *
  * It performs the Proxy protocol steps (record payer-opened, validate the cart,
- * supply required metadata, record the provider binding) and delegates only the
- * app-specific Stripe object creation to the merchant callback. This makes it
- * hard to create a Stripe checkout that is not correctly linked to a session.
+ * inject required metadata, create the Stripe Checkout Session, record the
+ * provider binding). Merchants provide only Stripe params, so the adapter owns
+ * metadata placement, idempotency, and binding reconciliation.
  */
-import { assertCheckoutSessionBelongsToProxy, requiredMetadata } from "./metadata.js";
+import { ProxyCheckoutValidationError } from "@proxy-checkout/server-js";
+import { ProxyStripeOpenCheckoutError } from "./errors.js";
+import { assertCheckoutSessionBelongsToProxy, injectRequiredCheckoutSessionMetadata, } from "./metadata.js";
 import { normalizePsp } from "./psp.js";
 export async function openCheckout(options) {
     // Normalize the same way the API does on store, so the binding is recorded
     // under the normalized psp and later syncCheckoutCart validations compare
     // normalized-to-normalized.
     const psp = normalizePsp(options.psp ?? "stripe");
-    const proxySession = await options.proxy.sessions.payerOpened(options.proxySessionId, {
+    let proxySession = await options.proxy.sessions.payerOpened(options.proxySessionId, {
         requestId: options.requestId,
     });
     // Parse the cart (and run the buyer-reference check) whenever a schema OR a
     // buyer-reference extractor is provided, so the consistency check is never
     // silently skipped just because no custom schema was passed.
-    const cart = options.cartSchema || options.getCartBuyerReference
+    let cart = options.cartSchema || options.getCartBuyerReference
         ? options.proxy.sessions.parseCart(proxySession, options.cartSchema ?? ((value) => value), { getBuyerReference: options.getCartBuyerReference })
         : proxySession.cartSnapshot;
     const offer = options.validateCart
         ? await options.validateCart({ cart, session: proxySession })
         : undefined;
-    const metadata = requiredMetadata(proxySession);
-    const checkoutSession = await options.createCheckoutSession({
+    const reconciledCart = await options.reconcileCart?.({ cart, offer, session: proxySession });
+    if (reconciledCart) {
+        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,
+        });
+        proxySession = {
+            ...proxySession,
+            amountMinor: updatedCart.amountMinor,
+            cartSnapshot: updatedCart.cartSnapshot,
+            cartVersion: updatedCart.cartVersion,
+            currency: updatedCart.currency,
+            updatedAt: proxySession.updatedAt,
+        };
+        cart = reconciledCart.cart;
+    }
+    if (proxySession.providerCheckoutSessionId !== null) {
+        assertExistingBindingMatches(proxySession, psp);
+        const checkoutSession = (await options.stripe.checkout.sessions.retrieve(proxySession.providerCheckoutSessionId));
+        assertCheckoutSessionBelongsToProxy(checkoutSession, proxySession.id);
+        return {
+            binding: bindingFromSession(proxySession),
+            cart,
+            checkoutSession,
+            clientSecret: checkoutSession.client_secret ?? null,
+            offer,
+            proxySession,
+            proxySessionId: proxySession.id,
+        };
+    }
+    const params = await options.buildCheckoutSessionParams({
         cart,
-        metadata,
         offer,
         proxySession,
         stripe: options.stripe,
     });
+    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 options.proxy.sessions.recordProviderBinding(proxySession.id, {
-        providerCheckoutSessionId: checkoutSession.id,
+    const binding = await recordOrReconcileProviderBinding({
+        checkoutSessionId: checkoutSession.id,
+        proxy: options.proxy,
+        proxySessionId: proxySession.id,
         psp,
         requestId: options.requestId,
+        stripe: options.stripe,
     });
     return {
         binding,
@@ -50,3 +87,70 @@ export async function openCheckout(options) {
         proxySessionId: proxySession.id,
     };
 }
+function buildStripeRequestOptions(options, proxySessionId, psp) {
+    return {
+        ...options.stripeRequestOptions,
+        idempotencyKey: `proxy-open-checkout:${proxySessionId}:${psp}`,
+    };
+}
+function assertExistingBindingMatches(proxySession, psp) {
+    if (proxySession.providerCheckoutSessionId === null) {
+        return;
+    }
+    if (proxySession.providerCheckoutSessionPsp !== psp) {
+        throw new ProxyCheckoutValidationError(`Proxy session ${proxySession.id} is already bound under psp ${proxySession.providerCheckoutSessionPsp}.`, { code: "provider_binding_mismatch", field: "provider_checkout_session_psp" });
+    }
+}
+function bindingFromSession(proxySession) {
+    if (proxySession.providerCheckoutSessionId === null ||
+        proxySession.providerCheckoutSessionPsp === null) {
+        throw new Error("Proxy session is not bound to a provider checkout session.");
+    }
+    return {
+        providerCheckoutSessionId: proxySession.providerCheckoutSessionId,
+        proxySessionId: proxySession.id,
+        psp: proxySession.providerCheckoutSessionPsp,
+        updatedAt: proxySession.updatedAt,
+    };
+}
+async function recordOrReconcileProviderBinding(input) {
+    try {
+        return await input.proxy.sessions.recordProviderBinding(input.proxySessionId, {
+            providerCheckoutSessionId: input.checkoutSessionId,
+            psp: input.psp,
+            requestId: input.requestId,
+        });
+    }
+    catch (cause) {
+        const reconciled = await readReconciledBinding(input).catch(() => undefined);
+        if (reconciled) {
+            return reconciled;
+        }
+        if (isProxyConflict(cause)) {
+            throw cause;
+        }
+        throw new ProxyStripeOpenCheckoutError("Stripe Checkout Session was created but Proxy provider binding could not be recorded.", {
+            cause,
+            code: "provider_binding_failed",
+            providerCheckoutSessionId: input.checkoutSessionId,
+        });
+    }
+}
+async function readReconciledBinding(input) {
+    const current = await input.proxy.sessions.retrieve(input.proxySessionId, {
+        requestId: input.requestId,
+    });
+    if (current.providerCheckoutSessionId !== input.checkoutSessionId ||
+        current.providerCheckoutSessionPsp !== input.psp) {
+        return undefined;
+    }
+    const checkoutSession = await input.stripe.checkout.sessions.retrieve(input.checkoutSessionId);
+    assertCheckoutSessionBelongsToProxy(checkoutSession, input.proxySessionId);
+    return bindingFromSession(current);
+}
+function isProxyConflict(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "statusCode" in error &&
+        error.statusCode === 409);
+}

package/dist/psp.d.ts

@@ -8,5 +8,5 @@
  * casing/whitespace for `openCheckout` vs `syncCheckoutCart` does not get a
  * false `provider_binding_mismatch`.
  */
-/** Normalize a psp identifier exactly as the Proxy API does before storing/comparing a binding. */
+/** Normalize and validate a psp identifier exactly as the Proxy API does before storing/comparing a binding. */
 export declare function normalizePsp(psp: string): string;

package/dist/psp.js

@@ -1,3 +1,4 @@
+import { ProxyCheckoutValidationError } from "@proxy-checkout/server-js";
 /**
  * Provider (psp) identifier normalization, kept in lockstep with the Proxy API.
  *
@@ -8,7 +9,14 @@
  * casing/whitespace for `openCheckout` vs `syncCheckoutCart` does not get a
  * false `provider_binding_mismatch`.
  */
-/** Normalize a psp identifier exactly as the Proxy API does before storing/comparing a binding. */
+/** Normalize and validate a psp identifier exactly as the Proxy API does before storing/comparing a binding. */
 export function normalizePsp(psp) {
-    return psp.trim().toLowerCase();
+    const normalized = psp.trim().toLowerCase();
+    if (!/^[a-z0-9_]{1,32}$/.test(normalized)) {
+        throw new ProxyCheckoutValidationError("psp must be a short lowercase identifier", {
+            code: "provider_binding_mismatch",
+            field: "psp",
+        });
+    }
+    return normalized;
 }

package/dist/sync-checkout-cart.js

@@ -33,13 +33,15 @@ export async function syncCheckoutCart(options) {
     const prior = {
         amountMinor: session.amountMinor,
         cartSnapshot: session.cartSnapshot,
+        cartVersion: session.cartVersion,
         currency: session.currency,
     };
     // Update Proxy first; the API rejects a non-editable session before Stripe is touched.
-    await options.proxy.sessions.cart.set(options.proxySessionId, {
+    const proxyCartUpdate = await options.proxy.sessions.cart.set(options.proxySessionId, {
         amountMinor: next.amountMinor,
         cartSnapshot: next.cartSnapshot,
         currency: next.currency,
+        expectedCartVersion: session.cartVersion,
         requestId: options.requestId,
     });
     let updatedCheckout;
@@ -54,6 +56,7 @@ export async function syncCheckoutCart(options) {
                 amountMinor: prior.amountMinor,
                 cartSnapshot: prior.cartSnapshot,
                 currency: prior.currency,
+                expectedCartVersion: proxyCartUpdate.cartVersion,
                 requestId: options.requestId,
             });
         }

package/dist/types.d.ts

@@ -24,7 +24,29 @@ export interface StripeCheckoutSessionUpdateParams {
     readonly line_items?: unknown;
     readonly metadata?: Record<string, string>;
 }
+export interface StripeCheckoutSessionCreateParams {
+    readonly metadata?: Record<string, string>;
+    readonly mode?: string;
+    readonly payment_intent_data?: {
+        readonly metadata?: Record<string, string>;
+        readonly [key: string]: unknown;
+    };
+    readonly subscription_data?: {
+        readonly metadata?: Record<string, string>;
+        readonly [key: string]: unknown;
+    };
+    readonly [key: string]: unknown;
+}
+export interface StripeRequestOptionsLike {
+    readonly idempotencyKey?: string;
+    readonly [key: string]: unknown;
+}
+export interface StripeRequestOptionsWithoutIdempotencyLike {
+    readonly idempotencyKey?: never;
+    readonly [key: string]: unknown;
+}
 export interface StripeCheckoutSessionsApiLike {
+    create(params: StripeCheckoutSessionCreateParams, options?: StripeRequestOptionsLike): Promise<StripeCheckoutSessionLike>;
     retrieve(id: string, params?: unknown, options?: unknown): Promise<StripeCheckoutSessionLike>;
     update(id: string, params: StripeCheckoutSessionUpdateParams, options?: unknown): Promise<StripeCheckoutSessionLike>;
 }

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 export declare const proxyCheckoutStripeServerSdkName = "@proxy-checkout/stripe-server-js";
-export declare const proxyCheckoutStripeServerSdkVersion = "0.0.0-pr-76.18.1";
+export declare const proxyCheckoutStripeServerSdkVersion = "0.0.0-pr-76.20.1";

package/dist/version.js

@@ -1,2 +1,2 @@
 export const proxyCheckoutStripeServerSdkName = "@proxy-checkout/stripe-server-js";
-export const proxyCheckoutStripeServerSdkVersion = "0.0.0-pr-76.18.1";
+export const proxyCheckoutStripeServerSdkVersion = "0.0.0-pr-76.20.1";

package/package.json

@@ -7,13 +7,13 @@
   "sideEffects": false,
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.0.0-pr-76.18.1",
+  "version": "0.0.0-pr-76.20.1",
   "devDependencies": {
     "@types/node": "^24.12.4",
     "@vitest/coverage-v8": "4.1.7",
     "typescript": "^6.0.3",
     "vitest": "4.1.7",
-    "@proxy-checkout/server-js": "0.0.4-pr-76.18.1"
+    "@proxy-checkout/server-js": "0.0.4-pr-76.20.1"
   },
   "exports": {
     ".": {