@proxy-checkout/stripe-server-js 0.0.0-pr-76.31.1 → 0.0.0-pr-76.32.1

package/README.md

@@ -35,7 +35,7 @@ const checkout = await openCheckout({
   buildCheckoutSessionParams: ({ cart, offer }) => ({
     ...buildMerchantStripeParams(cart, offer),
     mode: "subscription",
-    ui_mode: "embedded",
+    ui_mode: "custom",
   }),
 });
 // checkout.clientSecret -> render Stripe Elements

package/dist/cjs/errors.d.cts

@@ -0,0 +1,38 @@
+/**
+ * Adapter-specific error raised when a Stripe/Proxy cart synchronization cannot
+ * complete cleanly. The `reconciled` flag is true only when the SDK verified the
+ * Proxy and Stripe carts are back in a consistent state.
+ */
+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;
+    /** True only when the SDK verified Proxy and Stripe are in a consistent state. */
+    readonly reconciled: boolean;
+    readonly cause: unknown;
+    readonly rollbackCause: unknown;
+    constructor(message: string, details: {
+        code: ProxyStripeCartSyncCode;
+        reconciled: boolean;
+        cause: unknown;
+        rollbackCause?: unknown;
+    });
+}

package/dist/cjs/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Adapter-specific error raised when a Stripe/Proxy cart synchronization cannot
+ * complete cleanly. The `reconciled` flag is true only when the SDK verified the
+ * Proxy and Stripe carts are back in a consistent state.
+ */
+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;
+    /** True only when the SDK verified Proxy and Stripe are in a consistent state. */
+    readonly reconciled: boolean;
+    readonly cause: unknown;
+    readonly rollbackCause: unknown;
+    constructor(message: string, details: {
+        code: ProxyStripeCartSyncCode;
+        reconciled: boolean;
+        cause: unknown;
+        rollbackCause?: unknown;
+    });
+}

package/dist/cjs/index.d.cts

@@ -0,0 +1,7 @@
+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 { StripeCheckoutSessionCreateParams, StripeCheckoutSessionLike, StripeCheckoutSessionsApiLike, StripeCheckoutSessionUpdateParams, StripeClientLike, StripeMetadata, StripePaymentIntentLike, StripeRequestOptionsLike, StripeSubscriptionLike, } from "./types.js";
+export { proxyCheckoutStripeServerSdkName, proxyCheckoutStripeServerSdkVersion, } from "./version.js";

package/dist/cjs/index.d.ts

@@ -0,0 +1,7 @@
+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 { StripeCheckoutSessionCreateParams, StripeCheckoutSessionLike, StripeCheckoutSessionsApiLike, StripeCheckoutSessionUpdateParams, StripeClientLike, StripeMetadata, StripePaymentIntentLike, StripeRequestOptionsLike, StripeSubscriptionLike, } from "./types.js";
+export { proxyCheckoutStripeServerSdkName, proxyCheckoutStripeServerSdkVersion, } from "./version.js";

package/dist/cjs/metadata.d.cts

@@ -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/cjs/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/cjs/open-checkout.d.cts

@@ -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/cjs/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/cjs/psp.d.cts

@@ -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/cjs/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/cjs/sync-checkout-cart.d.cts

@@ -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/cjs/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/cjs/types.d.cts

@@ -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/cjs/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/cjs/version.d.cts

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

package/dist/cjs/version.d.ts

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

package/dist/cjs/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.proxyCheckoutStripeServerSdkVersion = exports.proxyCheckoutStripeServerSdkName = void 0;
 exports.proxyCheckoutStripeServerSdkName = "@proxy-checkout/stripe-server-js";
-exports.proxyCheckoutStripeServerSdkVersion = "0.0.0-pr-76.31.1";
+exports.proxyCheckoutStripeServerSdkVersion = "0.0.0-pr-76.32.1";

package/dist/esm/version.d.ts

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

package/dist/esm/version.js

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

package/package.json

@@ -7,20 +7,25 @@
   "sideEffects": false,
   "type": "module",
   "types": "./dist/esm/index.d.ts",
-  "version": "0.0.0-pr-76.31.1",
+  "version": "0.0.0-pr-76.32.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.31.1"
+    "@proxy-checkout/server-js": "0.0.4-pr-76.32.1"
   },
   "exports": {
     ".": {
-      "import": "./dist/esm/index.js",
-      "require": "./dist/cjs/index.js",
-      "types": "./dist/esm/index.d.ts"
+      "import": {
+        "default": "./dist/esm/index.js",
+        "types": "./dist/esm/index.d.ts"
+      },
+      "require": {
+        "default": "./dist/cjs/index.js",
+        "types": "./dist/cjs/index.d.cts"
+      }
     }
   },
   "files": [