@proxy-checkout/stripe-server-js 0.0.0 → 0.0.1

package/dist/esm/metadata.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Required Stripe metadata placement + provider-object ownership assertions.
+ *
+ * Proxy correlates Stripe objects to a session solely through
+ * `metadata.proxy_session_id`. This module centralizes that placement so
+ * 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 { 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>>;
+/**
+ * The metadata each Stripe object must carry, ready to spread into Stripe params.
+ *
+ * - `checkoutSession` → `metadata` on `checkout.sessions.create`
+ * - `subscriptionData` → `subscription_data` for subscription-mode Checkout
+ * - `paymentIntentData` → `payment_intent_data` for payment-mode Checkout / PaymentIntents
+ */
+export interface ProxyStripeRequiredMetadata {
+    readonly checkoutSession: ProxySessionMetadata;
+    readonly paymentIntent: ProxySessionMetadata;
+    readonly paymentIntentData: {
+        readonly metadata: ProxySessionMetadata;
+    };
+    readonly subscription: ProxySessionMetadata;
+    readonly subscriptionData: {
+        readonly metadata: ProxySessionMetadata;
+    };
+}
+/** Build the required Stripe metadata placements for a Proxy session. */
+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. */
+export declare function assertSubscriptionBelongsToProxy(subscription: Pick<StripeSubscriptionLike, "metadata">, proxySessionId: string): void;
+/** Assert a Stripe PaymentIntent carries the expected `proxy_session_id` metadata. */
+export declare function assertPaymentIntentBelongsToProxy(paymentIntent: Pick<StripePaymentIntentLike, "metadata">, proxySessionId: string): void;

package/dist/{metadata.js → esm/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: {
+                    ...objectRecord(params.subscription_data),
+                    metadata: mergeProxyMetadata(metadataFromNestedParams(params.subscription_data), metadata, "subscription_data.metadata.proxy_session_id"),
+                },
+            }
+            : {}),
+        ...(params.mode === "payment" || params.payment_intent_data !== undefined
+            ? {
+                payment_intent_data: {
+                    ...objectRecord(params.payment_intent_data),
+                    metadata: mergeProxyMetadata(metadataFromNestedParams(params.payment_intent_data), 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,19 @@ 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,
+    };
+}
+function objectRecord(value) {
+    return typeof value === "object" && value !== null ? value : {};
+}
+function metadataFromNestedParams(value) {
+    return objectRecord(value).metadata;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * `openCheckout` — the payer-opened + provider-object creation workflow.
+ *
+ * It performs the Proxy protocol steps (record payer-opened, validate the cart,
+ * 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 { 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;
+        offer: TOffer;
+        proxySession: PayerOpenedResult;
+        stripe: TStripe;
+    }) => 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. */
+    readonly proxy: ProxyCheckoutServerClient;
+    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. */
+    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: ProxySessionProviderBinding;
+    readonly cart: TCart;
+    readonly checkoutSession: TSession;
+    readonly clientSecret: string | null;
+    readonly offer: TOffer;
+    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>>;

package/dist/esm/open-checkout.js

@@ -0,0 +1,207 @@
+/**
+ * `openCheckout` — the payer-opened + provider-object creation workflow.
+ *
+ * It performs the Proxy protocol steps (record payer-opened, validate the cart,
+ * 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 { assertCartBuyerReference, ProxyCheckoutValidationError } from "@proxy-checkout/server-js";
+import { ProxyStripeCartSyncError, 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");
+    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.
+    let cart = options.cartSchema || options.getCartBuyerReference
+        ? options.proxy.sessions.parseCart(proxySession, options.cartSchema ?? ((value) => value), { getBuyerReference: options.getCartBuyerReference })
+        : proxySession.cartSnapshot;
+    let offer = options.validateCart
+        ? await options.validateCart({ cart, session: proxySession })
+        : undefined;
+    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,
+            proxySession,
+            proxySessionId: proxySession.id,
+        };
+    }
+    let rollbackCart;
+    const reconciledCart = await options.reconcileCart?.({ cart, offer, session: proxySession });
+    if (reconciledCart) {
+        if (options.getCartBuyerReference !== undefined) {
+            assertCartBuyerReference(options.getCartBuyerReference(reconciledCart.cart), proxySession);
+        }
+        const priorCart = {
+            amountMinor: proxySession.amountMinor,
+            cartSnapshot: proxySession.cartSnapshot,
+            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,
+        };
+        cart = reconciledCart.cart;
+    }
+    try {
+        if (reconciledCart && options.validateCart) {
+            offer = await options.validateCart({ cart, session: proxySession });
+        }
+        const params = await options.buildCheckoutSessionParams({
+            cart,
+            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 recordOrReconcileProviderBinding({
+            checkoutSessionId: checkoutSession.id,
+            proxy: options.proxy,
+            proxySessionId: proxySession.id,
+            psp,
+            requestId: options.requestId,
+            stripe: options.stripe,
+            stripeRequestOptions: options.stripeRequestOptions,
+        });
+        return {
+            binding,
+            cart,
+            checkoutSession,
+            clientSecret: checkoutSession.client_secret ?? null,
+            offer,
+            proxySession,
+            proxySessionId: proxySession.id,
+        };
+    }
+    catch (cause) {
+        if (rollbackCart) {
+            await rollbackReconciledCart({
+                cause,
+                proxy: options.proxy,
+                proxySessionId: proxySession.id,
+                requestId: options.requestId,
+                rollbackCart,
+            });
+        }
+        throw cause;
+    }
+}
+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 rollbackReconciledCart(input) {
+    try {
+        await input.proxy.sessions.cart.set(input.proxySessionId, {
+            amountMinor: input.rollbackCart.amountMinor,
+            cartSnapshot: input.rollbackCart.cartSnapshot,
+            currency: input.rollbackCart.currency,
+            expectedCartVersion: input.rollbackCart.expectedCartVersion,
+            requestId: input.requestId,
+        });
+    }
+    catch (rollbackCause) {
+        throw new ProxyStripeCartSyncError("openCheckout failed after reconciling the Proxy cart, and the rollback failed; carts may be out of sync.", {
+            cause: input.cause,
+            code: "reconciliation_failed",
+            reconciled: false,
+            rollbackCause,
+        });
+    }
+}
+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, undefined, input.stripeRequestOptions);
+    assertCheckoutSessionBelongsToProxy(checkoutSession, input.proxySessionId);
+    return bindingFromSession(current);
+}
+function isProxyConflict(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "statusCode" in error &&
+        error.statusCode === 409);
+}

package/dist/esm/psp.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Provider (psp) identifier normalization, kept in lockstep with the Proxy API.
+ *
+ * The API normalizes the psp before persisting a provider binding
+ * (`psp.trim().toLowerCase()`), then compares stored bindings against that
+ * normalized value. The SDK must normalize identically before recording or
+ * validating a binding so a caller passing the same psp with different
+ * casing/whitespace for `openCheckout` vs `syncCheckoutCart` does not get a
+ * false `provider_binding_mismatch`.
+ */
+/** 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/esm/psp.js

@@ -0,0 +1,22 @@
+import { ProxyCheckoutValidationError } from "@proxy-checkout/server-js";
+/**
+ * Provider (psp) identifier normalization, kept in lockstep with the Proxy API.
+ *
+ * The API normalizes the psp before persisting a provider binding
+ * (`psp.trim().toLowerCase()`), then compares stored bindings against that
+ * normalized value. The SDK must normalize identically before recording or
+ * validating a binding so a caller passing the same psp with different
+ * casing/whitespace for `openCheckout` vs `syncCheckoutCart` does not get a
+ * false `provider_binding_mismatch`.
+ */
+/** Normalize and validate a psp identifier exactly as the Proxy API does before storing/comparing a binding. */
+export function normalizePsp(psp) {
+    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/esm/sync-checkout-cart.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `syncCheckoutCart` — coordinated Proxy + Stripe cart update.
+ *
+ * Validates ownership against the first-class Proxy provider binding (not just
+ * Stripe metadata), then updates the Proxy cart and the Stripe checkout in the
+ * safest order with deterministic rollback/reconciliation on failure.
+ */
+import { type JsonObject, type MerchantProxySession, type ProxyCartValidator, type ProxyCheckoutServerClient } from "@proxy-checkout/server-js";
+import type { StripeCheckoutSessionLike, StripeClientLike, StripeRequestOptionsWithoutIdempotencyLike } from "./types.js";
+/** The next cart, expressed both as Proxy state and the typed merchant cart. */
+export interface SyncedCart<TCart> {
+    readonly amountMinor: number;
+    readonly cart: TCart;
+    readonly cartSnapshot: JsonObject;
+    readonly currency: string;
+}
+export interface SyncCheckoutCartOptions<TStripe extends StripeClientLike, TCart, TInput> {
+    /** Compute the next cart from current state and the merchant input. */
+    readonly buildNextCart: (input: {
+        currentCart: TCart;
+        currentSession: MerchantProxySession;
+        input: TInput;
+    }) => Promise<SyncedCart<TCart>> | SyncedCart<TCart>;
+    /** Derive the Stripe `line_items` update from the next typed cart. */
+    readonly buildStripeLineItems: (cart: TCart) => unknown;
+    /** Optional schema validating the current cart snapshot into a typed cart. */
+    readonly cartSchema?: ProxyCartValidator<TCart>;
+    readonly checkoutSessionId: string;
+    /** Merchant-supplied change request (e.g. new interval/quantity). */
+    readonly input: TInput;
+    readonly proxy: ProxyCheckoutServerClient;
+    readonly proxySessionId: string;
+    /** Provider identifier the session must be bound under. Defaults to "stripe". */
+    readonly psp?: string;
+    readonly requestId?: string;
+    readonly stripe: TStripe;
+    /** Optional Stripe request options, e.g. Stripe Connect account scoping. */
+    readonly stripeRequestOptions?: StripeRequestOptionsWithoutIdempotencyLike;
+}
+export interface SyncCheckoutCartResult<TCart> {
+    readonly amountMinor: number;
+    readonly cart: TCart;
+    readonly cartSnapshot: JsonObject;
+    readonly checkoutSession: StripeCheckoutSessionLike;
+    readonly currency: string;
+}
+export declare function syncCheckoutCart<TStripe extends StripeClientLike, TCart, TInput>(options: SyncCheckoutCartOptions<TStripe, TCart, TInput>): Promise<SyncCheckoutCartResult<TCart>>;

package/dist/{sync-checkout-cart.js → esm/sync-checkout-cart.js}

@@ -8,15 +8,19 @@
 import { ProxyCheckoutValidationError, } from "@proxy-checkout/server-js";
 import { ProxyStripeCartSyncError } from "./errors.js";
 import { assertCheckoutSessionBelongsToProxy } from "./metadata.js";
+import { normalizePsp } from "./psp.js";
 export async function syncCheckoutCart(options) {
-    const psp = options.psp ?? "stripe";
+    // Normalize the same way the API does on store, so the binding comparison is
+    // normalized-to-normalized and a custom psp with differing casing/whitespace
+    // does not produce a false provider_binding_mismatch.
+    const psp = normalizePsp(options.psp ?? "stripe");
     const session = await options.proxy.sessions.retrieve(options.proxySessionId, {
         requestId: options.requestId,
     });
     // Ownership: validate against the stored binding first, then defensively
     // against the Stripe object's own metadata.
     assertSessionBoundTo(session, options.checkoutSessionId, psp);
-    const stripeSession = await options.stripe.checkout.sessions.retrieve(options.checkoutSessionId);
+    const stripeSession = await options.stripe.checkout.sessions.retrieve(options.checkoutSessionId, undefined, options.stripeRequestOptions);
     assertCheckoutSessionBelongsToProxy(stripeSession, options.proxySessionId);
     const currentCart = options.cartSchema
         ? options.proxy.sessions.parseCart(session, options.cartSchema)
@@ -29,41 +33,57 @@ export async function syncCheckoutCart(options) {
     const prior = {
         amountMinor: session.amountMinor,
         cartSnapshot: session.cartSnapshot,
+        cartVersion: session.cartVersion,
         currency: session.currency,
     };
+    const stripeUpdateParams = {
+        line_items: options.buildStripeLineItems(next.cart),
+    };
     // 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,
     });
+    const stripeUpdateOptions = buildStripeUpdateRequestOptions(options, proxyCartUpdate.cartVersion);
     let updatedCheckout;
     try {
-        updatedCheckout = await options.stripe.checkout.sessions.update(options.checkoutSessionId, {
-            line_items: options.buildStripeLineItems(next.cart),
-        });
+        updatedCheckout = await options.stripe.checkout.sessions.update(options.checkoutSessionId, stripeUpdateParams, stripeUpdateOptions);
     }
-    catch (cause) {
+    catch {
         try {
-            await options.proxy.sessions.cart.set(options.proxySessionId, {
-                amountMinor: prior.amountMinor,
-                cartSnapshot: prior.cartSnapshot,
-                currency: prior.currency,
-                requestId: options.requestId,
-            });
+            updatedCheckout = await options.stripe.checkout.sessions.update(options.checkoutSessionId, stripeUpdateParams, stripeUpdateOptions);
         }
-        catch (rollbackCause) {
-            throw new ProxyStripeCartSyncError("Stripe checkout update failed and the Proxy cart rollback failed; carts may be out of sync.", { cause, code: "reconciliation_failed", reconciled: false, rollbackCause });
+        catch (retryCause) {
+            try {
+                await options.proxy.sessions.cart.set(options.proxySessionId, {
+                    amountMinor: prior.amountMinor,
+                    cartSnapshot: prior.cartSnapshot,
+                    currency: prior.currency,
+                    expectedCartVersion: proxyCartUpdate.cartVersion,
+                    requestId: options.requestId,
+                });
+            }
+            catch (rollbackCause) {
+                throw new ProxyStripeCartSyncError("Stripe checkout update failed after an idempotent retry and the Proxy cart rollback failed; carts may be out of sync.", { cause: retryCause, code: "reconciliation_failed", reconciled: false, rollbackCause });
+            }
+            throw new ProxyStripeCartSyncError("Stripe checkout update failed after an idempotent retry; the Proxy cart rollback was attempted, but Stripe state may still be ambiguous.", { cause: retryCause, code: "stripe_update_failed", reconciled: false });
         }
-        throw new ProxyStripeCartSyncError("Stripe checkout update failed; the Proxy cart was rolled back to its prior state.", { cause, code: "stripe_update_failed", reconciled: true });
     }
     return {
         amountMinor: next.amountMinor,
         cart: next.cart,
         cartSnapshot: next.cartSnapshot,
         checkoutSession: updatedCheckout,
-        currency: next.currency,
+        currency: proxyCartUpdate.currency,
+    };
+}
+function buildStripeUpdateRequestOptions(options, cartVersion) {
+    return {
+        ...options.stripeRequestOptions,
+        idempotencyKey: `proxy-sync-checkout-cart:${options.proxySessionId}:${options.checkoutSessionId}:${cartVersion}`,
     };
 }
 function assertSessionBoundTo(session, checkoutSessionId, psp) {

package/dist/esm/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Minimal structural Stripe types.
+ *
+ * The adapter is dependency-free: merchants inject their own `Stripe` instance
+ * and objects, which are structurally compatible with these narrow interfaces.
+ * This avoids a runtime/build dependency on the `stripe` package while keeping
+ * the bits the adapter actually touches type-safe.
+ */
+export type StripeMetadataValue = string | number | null;
+export type StripeMetadata = Record<string, StripeMetadataValue> | null | undefined;
+export type StripeMetadataParam = Record<string, StripeMetadataValue> | undefined;
+export interface StripeCheckoutSessionLike {
+    readonly client_secret?: string | null;
+    readonly id: string;
+    readonly metadata?: StripeMetadata;
+}
+export interface StripeSubscriptionLike {
+    readonly id: string;
+    readonly metadata?: StripeMetadata;
+}
+export interface StripePaymentIntentLike {
+    readonly id: string;
+    readonly metadata?: StripeMetadata;
+}
+export interface StripeCheckoutSessionUpdateParams {
+    readonly line_items?: unknown;
+    readonly metadata?: StripeMetadataParam;
+}
+export type StripeCheckoutSessionCreateParams = object & {
+    readonly metadata?: StripeMetadataParam;
+    readonly mode?: "payment" | "setup" | "subscription";
+    readonly payment_intent_data?: unknown;
+    readonly subscription_data?: 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: unknown, options?: unknown): Promise<StripeCheckoutSessionLike>;
+    retrieve(id: string, params?: unknown, options?: unknown): Promise<StripeCheckoutSessionLike>;
+    update(id: string, params: unknown, options?: unknown): Promise<StripeCheckoutSessionLike>;
+}
+export interface StripeClientLike {
+    readonly checkout: {
+        readonly sessions: StripeCheckoutSessionsApiLike;
+    };
+}

package/dist/esm/version.d.ts

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

package/dist/{version.js → esm/version.js}

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