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

package/README.md

@@ -4,7 +4,7 @@ Server-side Stripe adapter for Proxy Checkout. It owns the Stripe-specific integ
 
 - **`requiredMetadata(proxySession)`** — the `proxy_session_id` metadata Proxy needs on the Checkout Session, Subscription, and PaymentIntent.
 - **`assertCheckoutSessionBelongsToProxy` / `assertSubscriptionBelongsToProxy` / `assertPaymentIntentBelongsToProxy`** — provider-object ownership checks.
-- **`openCheckout(...)`** — records payer-opened, validates the typed cart, supplies required metadata, records the Proxy provider binding, and returns the client secret. The merchant only supplies an app-specific Stripe-session builder.
+- **`openCheckout(...)`** — records payer-opened, validates/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.
@@ -32,13 +32,11 @@ const checkout = await openCheckout({
   proxySessionId,
   cartSchema, // a zod-style schema, or any (value) => Cart validator
   validateCart: ({ cart }) => buildMerchantOffer(cart),
-  createCheckoutSession: ({ stripe, cart, metadata }) =>
-    stripe.checkout.sessions.create({
-      ...buildMerchantStripeParams(cart),
-      ui_mode: "embedded",
-      metadata: { ...metadata.checkoutSession },
-      subscription_data: { metadata: metadata.subscriptionData.metadata },
-    }),
+  buildCheckoutSessionParams: ({ cart, offer }) => ({
+    ...buildMerchantStripeParams(cart, offer),
+    mode: "subscription",
+    ui_mode: "custom",
+  }),
 });
 // checkout.clientSecret -> render Stripe Elements
 
@@ -55,4 +53,5 @@ await syncCheckoutCart({
 });
 ```
 
-See the [agentic delegated-checkout guide](https://github.com/linuslabs/proxy/blob/main/docs/integration/agentic-delegated-checkout-guide.md) for the full four-route integration recipe.
+Use the delegated-checkout guide from your Proxy onboarding materials for the
+full four-route integration recipe.

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/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 only when the SDK verified Proxy and Stripe are in a consistent state. */
+    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.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/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.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/{metadata.d.ts → cjs/metadata.d.ts}

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

package/dist/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.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>>;