@proxy-checkout/stripe-server-js 0.0.0-pr-76.20.1 → 0.0.0-pr-76.22.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, 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 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.

package/dist/cjs/errors.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxyStripeCartSyncError = exports.ProxyStripeOpenCheckoutError = void 0;
+/**
+ * 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.
+ */
+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;
+    }
+}
+exports.ProxyStripeOpenCheckoutError = ProxyStripeOpenCheckoutError;
+class ProxyStripeCartSyncError extends Error {
+    name = "ProxyStripeCartSyncError";
+    code;
+    /** True when the Proxy cart was rolled back to its prior state after the failure. */
+    reconciled;
+    cause;
+    rollbackCause;
+    constructor(message, details) {
+        super(message);
+        this.code = details.code;
+        this.reconciled = details.reconciled;
+        this.cause = details.cause;
+        this.rollbackCause = details.rollbackCause;
+    }
+}
+exports.ProxyStripeCartSyncError = ProxyStripeCartSyncError;

package/dist/cjs/index.js

@@ -0,0 +1,22 @@
+"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;
+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; } });
+var metadata_js_1 = require("./metadata.js");
+Object.defineProperty(exports, "assertCheckoutSessionBelongsToProxy", { enumerable: true, get: function () { return metadata_js_1.assertCheckoutSessionBelongsToProxy; } });
+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_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");
+Object.defineProperty(exports, "openCheckout", { enumerable: true, get: function () { return open_checkout_js_1.openCheckout; } });
+var psp_js_1 = require("./psp.js");
+Object.defineProperty(exports, "normalizePsp", { enumerable: true, get: function () { return psp_js_1.normalizePsp; } });
+var sync_checkout_cart_js_1 = require("./sync-checkout-cart.js");
+Object.defineProperty(exports, "syncCheckoutCart", { enumerable: true, get: function () { return sync_checkout_cart_js_1.syncCheckoutCart; } });
+var version_js_1 = require("./version.js");
+Object.defineProperty(exports, "proxyCheckoutStripeServerSdkName", { enumerable: true, get: function () { return version_js_1.proxyCheckoutStripeServerSdkName; } });
+Object.defineProperty(exports, "proxyCheckoutStripeServerSdkVersion", { enumerable: true, get: function () { return version_js_1.proxyCheckoutStripeServerSdkVersion; } });

package/dist/cjs/metadata.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROXY_SESSION_METADATA_KEY = void 0;
+exports.requiredMetadata = requiredMetadata;
+exports.injectRequiredCheckoutSessionMetadata = injectRequiredCheckoutSessionMetadata;
+exports.assertCheckoutSessionBelongsToProxy = assertCheckoutSessionBelongsToProxy;
+exports.assertSubscriptionBelongsToProxy = assertSubscriptionBelongsToProxy;
+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";
+/** Build the required Stripe metadata placements for a Proxy session. */
+function requiredMetadata(proxySession) {
+    const metadata = { proxy_session_id: proxySession.id };
+    return {
+        checkoutSession: metadata,
+        paymentIntent: metadata,
+        paymentIntentData: { metadata },
+        subscription: metadata,
+        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.
+ */
+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. */
+function assertCheckoutSessionBelongsToProxy(checkoutSession, proxySessionId) {
+    assertProxyMetadata(checkoutSession.metadata, proxySessionId, "Stripe checkout session");
+}
+/** Assert a Stripe Subscription carries the expected `proxy_session_id` metadata. */
+function assertSubscriptionBelongsToProxy(subscription, proxySessionId) {
+    assertProxyMetadata(subscription.metadata, proxySessionId, "Stripe subscription");
+}
+/** Assert a Stripe PaymentIntent carries the expected `proxy_session_id` metadata. */
+function assertPaymentIntentBelongsToProxy(paymentIntent, proxySessionId) {
+    assertProxyMetadata(paymentIntent.metadata, proxySessionId, "Stripe payment intent");
+}
+function assertProxyMetadata(metadata, proxySessionId, objectLabel) {
+    const value = metadata?.[exports.PROXY_SESSION_METADATA_KEY];
+    if (value !== proxySessionId) {
+        throw new server_js_1.ProxyCheckoutValidationError(`${objectLabel} metadata.${exports.PROXY_SESSION_METADATA_KEY} (${value ?? "missing"}) does not match Proxy session ${proxySessionId}.`, { code: "provider_binding_mismatch", field: `metadata.${exports.PROXY_SESSION_METADATA_KEY}` });
+    }
+}
+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 });
+    }
+    return {
+        ...existing,
+        ...required,
+    };
+}
+function objectRecord(value) {
+    return typeof value === "object" && value !== null ? value : {};
+}
+function metadataFromNestedParams(value) {
+    return objectRecord(value).metadata;
+}

package/dist/cjs/open-checkout.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * `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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openCheckout = openCheckout;
+const server_js_1 = require("@proxy-checkout/server-js");
+const errors_js_1 = require("./errors.js");
+const metadata_js_1 = require("./metadata.js");
+const psp_js_1 = require("./psp.js");
+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 = (0, psp_js_1.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;
+    const 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));
+        (0, metadata_js_1.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) {
+        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 {
+        const params = await options.buildCheckoutSessionParams({
+            cart,
+            offer,
+            proxySession,
+            stripe: options.stripe,
+        });
+        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,
+            proxy: options.proxy,
+            proxySessionId: proxySession.id,
+            psp,
+            requestId: options.requestId,
+            stripe: options.stripe,
+        });
+        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 server_js_1.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 errors_js_1.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 errors_js_1.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);
+    (0, metadata_js_1.assertCheckoutSessionBelongsToProxy)(checkoutSession, input.proxySessionId);
+    return bindingFromSession(current);
+}
+function isProxyConflict(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "statusCode" in error &&
+        error.statusCode === 409);
+}

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/psp.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePsp = normalizePsp;
+const server_js_1 = require("@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. */
+function normalizePsp(psp) {
+    const normalized = psp.trim().toLowerCase();
+    if (!/^[a-z0-9_]{1,32}$/.test(normalized)) {
+        throw new server_js_1.ProxyCheckoutValidationError("psp must be a short lowercase identifier", {
+            code: "provider_binding_mismatch",
+            field: "psp",
+        });
+    }
+    return normalized;
+}

package/dist/cjs/sync-checkout-cart.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * `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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncCheckoutCart = syncCheckoutCart;
+const server_js_1 = require("@proxy-checkout/server-js");
+const errors_js_1 = require("./errors.js");
+const metadata_js_1 = require("./metadata.js");
+const psp_js_1 = require("./psp.js");
+async function syncCheckoutCart(options) {
+    // 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 = (0, psp_js_1.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);
+    (0, metadata_js_1.assertCheckoutSessionBelongsToProxy)(stripeSession, options.proxySessionId);
+    const currentCart = options.cartSchema
+        ? options.proxy.sessions.parseCart(session, options.cartSchema)
+        : session.cartSnapshot;
+    const next = await options.buildNextCart({
+        currentCart,
+        currentSession: session,
+        input: options.input,
+    });
+    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.
+    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;
+    try {
+        updatedCheckout = await options.stripe.checkout.sessions.update(options.checkoutSessionId, {
+            line_items: options.buildStripeLineItems(next.cart),
+        });
+    }
+    catch (cause) {
+        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 errors_js_1.ProxyStripeCartSyncError("Stripe checkout update failed and the Proxy cart rollback failed; carts may be out of sync.", { cause, code: "reconciliation_failed", reconciled: false, rollbackCause });
+        }
+        throw new errors_js_1.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,
+    };
+}
+function assertSessionBoundTo(session, checkoutSessionId, psp) {
+    if (session.providerCheckoutSessionId !== checkoutSessionId ||
+        session.providerCheckoutSessionPsp !== psp) {
+        throw new server_js_1.ProxyCheckoutValidationError(`Proxy session ${session.id} is not bound to provider checkout session ${checkoutSessionId}.`, { code: "provider_binding_mismatch", field: "provider_checkout_session_id" });
+    }
+}

package/dist/cjs/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.proxyCheckoutStripeServerSdkVersion = exports.proxyCheckoutStripeServerSdkName = void 0;
+exports.proxyCheckoutStripeServerSdkName = "@proxy-checkout/stripe-server-js";
+exports.proxyCheckoutStripeServerSdkVersion = "0.0.0-pr-76.22.1";

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

@@ -33,16 +33,16 @@ export function injectRequiredCheckoutSessionMetadata(params, proxySessionId) {
         ...(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"),
+                    ...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: {
-                    ...params.payment_intent_data,
-                    metadata: mergeProxyMetadata(params.payment_intent_data?.metadata, metadata, "payment_intent_data.metadata.proxy_session_id"),
+                    ...objectRecord(params.payment_intent_data),
+                    metadata: mergeProxyMetadata(metadataFromNestedParams(params.payment_intent_data), metadata, "payment_intent_data.metadata.proxy_session_id"),
                 },
             }
             : {}),
@@ -76,3 +76,9 @@ function mergeProxyMetadata(existing, required, field) {
         ...required,
     };
 }
+function objectRecord(value) {
+    return typeof value === "object" && value !== null ? value : {};
+}
+function metadataFromNestedParams(value) {
+    return objectRecord(value).metadata;
+}

package/dist/{open-checkout.js → esm/open-checkout.js}

@@ -7,7 +7,7 @@
  * metadata placement, idempotency, and binding reconciliation.
  */
 import { ProxyCheckoutValidationError } from "@proxy-checkout/server-js";
-import { ProxyStripeOpenCheckoutError } from "./errors.js";
+import { ProxyStripeCartSyncError, ProxyStripeOpenCheckoutError } from "./errors.js";
 import { assertCheckoutSessionBelongsToProxy, injectRequiredCheckoutSessionMetadata, } from "./metadata.js";
 import { normalizePsp } from "./psp.js";
 export async function openCheckout(options) {
@@ -27,8 +27,29 @@ export async function openCheckout(options) {
     const 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));
+        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) {
+        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,
@@ -36,6 +57,10 @@ export async function openCheckout(options) {
             expectedCartVersion: proxySession.cartVersion,
             requestId: options.requestId,
         });
+        rollbackCart = {
+            ...priorCart,
+            expectedCartVersion: updatedCart.cartVersion,
+        };
         proxySession = {
             ...proxySession,
             amountMinor: updatedCart.amountMinor,
@@ -46,12 +71,26 @@ export async function openCheckout(options) {
         };
         cart = reconciledCart.cart;
     }
-    if (proxySession.providerCheckoutSessionId !== null) {
-        assertExistingBindingMatches(proxySession, psp);
-        const checkoutSession = (await options.stripe.checkout.sessions.retrieve(proxySession.providerCheckoutSessionId));
+    try {
+        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,
+        });
         return {
-            binding: bindingFromSession(proxySession),
+            binding,
             cart,
             checkoutSession,
             clientSecret: checkoutSession.client_secret ?? null,
@@ -60,32 +99,18 @@ export async function openCheckout(options) {
             proxySessionId: proxySession.id,
         };
     }
-    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,
-    });
-    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 {
@@ -113,6 +138,25 @@ function bindingFromSession(proxySession) {
         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, {

package/dist/{types.d.ts → esm/types.d.ts}

@@ -6,7 +6,9 @@
  * This avoids a runtime/build dependency on the `stripe` package while keeping
  * the bits the adapter actually touches type-safe.
  */
-export type StripeMetadata = Record<string, string | null> | null | undefined;
+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;
@@ -22,21 +24,14 @@ export interface StripePaymentIntentLike {
 }
 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;
-}
+    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;
@@ -46,9 +41,9 @@ export interface StripeRequestOptionsWithoutIdempotencyLike {
     readonly [key: string]: unknown;
 }
 export interface StripeCheckoutSessionsApiLike {
-    create(params: StripeCheckoutSessionCreateParams, options?: StripeRequestOptionsLike): Promise<StripeCheckoutSessionLike>;
+    create(params: unknown, options?: unknown): Promise<StripeCheckoutSessionLike>;
     retrieve(id: string, params?: unknown, options?: unknown): Promise<StripeCheckoutSessionLike>;
-    update(id: string, params: StripeCheckoutSessionUpdateParams, options?: unknown): Promise<StripeCheckoutSessionLike>;
+    update(id: string, params: unknown, options?: unknown): Promise<StripeCheckoutSessionLike>;
 }
 export interface StripeClientLike {
     readonly checkout: {

package/dist/{version.d.ts → esm/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.20.1";
+export declare const proxyCheckoutStripeServerSdkVersion = "0.0.0-pr-76.22.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-pr-76.20.1";
+export const proxyCheckoutStripeServerSdkVersion = "0.0.0-pr-76.22.1";

package/package.json

@@ -1,24 +1,27 @@
 {
   "description": "Server-side Stripe adapter for Proxy Checkout: required metadata, provider binding, openCheckout, and cart sync.",
   "license": "MIT",
-  "module": "./dist/index.js",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
   "name": "@proxy-checkout/stripe-server-js",
   "private": false,
   "sideEffects": false,
   "type": "module",
-  "types": "./dist/index.d.ts",
-  "version": "0.0.0-pr-76.20.1",
+  "types": "./dist/esm/index.d.ts",
+  "version": "0.0.0-pr-76.22.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-pr-76.20.1"
+    "@proxy-checkout/server-js": "0.0.4-pr-76.22.1"
   },
   "exports": {
     ".": {
-      "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/esm/index.d.ts"
     }
   },
   "files": [
@@ -45,7 +48,7 @@
     "url": "git+https://github.com/linuslabs/proxy.git"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node ../../tools/sdk/build-dual-package.mjs",
     "test:all": "vitest run",
     "test:coverage": "vitest run --coverage.enabled --coverage.reportsDirectory=coverage/all",
     "test:coverage:changed": "vitest run --coverage.enabled --coverage.reportsDirectory=coverage/changed",