@proxy-checkout/server-js 0.0.8 → 0.1.0-prx-124.139.1

package/README.md

@@ -44,7 +44,9 @@ const handoff = await proxy.sessions.createHandoff({
   cartSnapshot: {
     items: [{ product_id: "prod_123", quantity: 1 }],
   },
-  idempotencyKey: "order_123",
+  // Stable merchant purchase-request id: reuse for retries and every payer
+  // invited to this order; use a new id for a genuinely new purchase.
+  idempotencyKey: "proxy-session:purchase_request_123",
   // Optional: omit in normal production flows to use the dashboard default.
   // Preview/staging/multi-origin environments may override the merchant payer page.
   payerDestinationUrl: "https://preview.example.com/checkout",
@@ -74,6 +76,8 @@ For delegated checkout, prefer the high-level flow:
 
 Use `payerHandoff`, `payerOpened`, raw event construction, or manual provisioning acknowledgements only for custom integrations that cannot use the default helpers.
 
+The legacy `proxy.sessions.recordProviderBinding(...)` compatibility adapter is deprecated. If a custom Stripe integration still calls it directly, pass canonical `psp: "stripe"` plus `commercialMode: "one_time"` for Checkout `mode: "payment"` or `commercialMode: "subscription"` for Checkout `mode: "subscription"`. Current TypeScript callers receive that requirement at compile time; `openCheckout(...)` derives it automatically.
+
 `proxy.webhooks.handle(...)` automatically marks successful initial provisioning as provisioned after `onResolved` completes. Return a fulfillment reference and/or metadata from `onResolved` when you want that acknowledgement to record the merchant-side access row:
 
 ```ts
@@ -97,6 +101,10 @@ await proxy.webhooks.handle(request, {
 
 For pre-account purchases, create a durable pending entitlement before `sessions.createHandoff(...)`, use that pending entitlement id as `buyerReference`, pass the future recipient's contact as `beneficiaryContact`, and claim the entitlement after signup/login with your own high-entropy claim token. Store only the token hash on the pending entitlement; use `sessionStorage` or an emailed merchant-owned claim link to carry the plaintext token to the authenticated claim endpoint. Treat `proxy_session_id` as public correlation, not as a claim secret.
 
+Keep purchase identity separate from beneficiary identity. Create a durable merchant purchase-request/order row before `createHandoff`, derive `idempotencyKey` from that row's stable non-PII id, and store the returned Proxy session/handoff on it. Reuse the row and one handoff across HTTP retries and every invited payer. `buyerReference` identifies the entitlement recipient; it is not, by itself, an order key. A repeated purchase by the same beneficiary needs a new purchase-request id even if its offer and amount are unchanged. Do not derive the key from email, payer identity, Stripe Customer id, amount alone, or a per-retry random value.
+
+One shared handoff supports simultaneous viewers. Opening never grants checkout ownership or a viewer lease. All authorized viewers can render the same cart/current state; identical provider preparation joins the same order-scoped acquisition, and a completed session remains readable while further provider creation is refused.
+
 Verify and parse outbound webhooks with the exact raw request body:
 
 ```ts
@@ -114,6 +122,10 @@ if (event.type === "subscription.renewed") {
 }
 ```
 
+`PROXY_WEBHOOK_EVENT_TYPES` and the `isProxy*Event` predicates also cover initial payment refunds
+and observation-only Shopify reconciliation/renewal/refund/fulfillment events. Shopify observation events do not
+initiate a commerce mutation or imply provisioning; inspect their verified `event.data` payload.
+
 Production calls default to `https://api.proxycheckout.com`. Tests, local
 development, and previews can pass `apiHost`.
 

package/dist/cjs/client.d.cts

@@ -1,4 +1,5 @@
 import { ProxyEventsResource } from "./events.js";
+import { ProxyProviderAcquisitionsResource } from "./provider-acquisitions.js";
 import { ProxySessionsResource } from "./sessions.js";
 import { ProxySubscriptionsResource } from "./subscriptions.js";
 import type { ProxyCheckoutServerClientOptions } from "./types.js";
@@ -7,6 +8,7 @@ import { ProxyWebhookEndpointsResource } from "./webhooks.js";
 export declare class ProxyCheckoutServerClient {
     readonly apiHost: string;
     readonly sessions: ProxySessionsResource;
+    readonly providerAcquisitions: ProxyProviderAcquisitionsResource;
     readonly subscriptions: ProxySubscriptionsResource;
     /** Current-state lifecycle resolver for signed webhook events. */
     readonly events: ProxyEventsResource;

package/dist/cjs/client.d.ts

@@ -1,4 +1,5 @@
 import { ProxyEventsResource } from "./events.js";
+import { ProxyProviderAcquisitionsResource } from "./provider-acquisitions.js";
 import { ProxySessionsResource } from "./sessions.js";
 import { ProxySubscriptionsResource } from "./subscriptions.js";
 import type { ProxyCheckoutServerClientOptions } from "./types.js";
@@ -7,6 +8,7 @@ import { ProxyWebhookEndpointsResource } from "./webhooks.js";
 export declare class ProxyCheckoutServerClient {
     readonly apiHost: string;
     readonly sessions: ProxySessionsResource;
+    readonly providerAcquisitions: ProxyProviderAcquisitionsResource;
     readonly subscriptions: ProxySubscriptionsResource;
     /** Current-state lifecycle resolver for signed webhook events. */
     readonly events: ProxyEventsResource;

package/dist/cjs/client.js

@@ -4,6 +4,7 @@ exports.ProxyCheckoutServerClient = void 0;
 exports.createProxyCheckoutServerClient = createProxyCheckoutServerClient;
 const events_js_1 = require("./events.js");
 const http_client_js_1 = require("./http-client.js");
+const provider_acquisitions_js_1 = require("./provider-acquisitions.js");
 const sessions_js_1 = require("./sessions.js");
 const subscriptions_js_1 = require("./subscriptions.js");
 const webhook_handler_js_1 = require("./webhook-handler.js");
@@ -11,6 +12,7 @@ const webhooks_js_1 = require("./webhooks.js");
 class ProxyCheckoutServerClient {
     apiHost;
     sessions;
+    providerAcquisitions;
     subscriptions;
     /** Current-state lifecycle resolver for signed webhook events. */
     events;
@@ -29,8 +31,9 @@ class ProxyCheckoutServerClient {
             payHost: options.payHost,
             publishableKey: options.publishableKey,
         });
+        this.providerAcquisitions = new provider_acquisitions_js_1.ProxyProviderAcquisitionsResource(httpClient);
         this.subscriptions = new subscriptions_js_1.ProxySubscriptionsResource(httpClient, this.sessions);
-        this.events = new events_js_1.ProxyEventsResource(this.sessions, this.subscriptions);
+        this.events = new events_js_1.ProxyEventsResource(this.sessions, this.subscriptions, this.providerAcquisitions);
         this.webhooks = new webhook_handler_js_1.ProxyWebhooksResource(this.events, this.sessions);
         this.webhookEndpoints = new webhooks_js_1.ProxyWebhookEndpointsResource(httpClient);
     }

package/dist/cjs/errors.d.cts

@@ -4,7 +4,7 @@ export interface ProxyCheckoutApiErrorDetails {
     readonly responseBody: unknown;
     readonly statusCode: number;
 }
-export type ProxyCheckoutValidationCode = "buyer_reference_mismatch" | "cart_invalid" | "invalid_date" | "provider_binding_mismatch" | "subscription_session_mismatch" | "webhook_sessions_resource_missing";
+export type ProxyCheckoutValidationCode = "buyer_reference_mismatch" | "cart_invalid" | "cart_version_conflict" | "commercial_mode_required" | "invalid_date" | "invalid_session_presentation" | "provider_acquisition_in_progress" | "provider_binding_missing" | "provider_binding_mismatch" | "subscription_session_mismatch" | "unsupported_provider_option" | "webhook_sessions_resource_missing";
 /**
  * Raised when the SDK receives Proxy data it cannot safely normalize, for
  * example an invalid date string, a cart snapshot that fails the merchant

package/dist/cjs/errors.d.ts

@@ -4,7 +4,7 @@ export interface ProxyCheckoutApiErrorDetails {
     readonly responseBody: unknown;
     readonly statusCode: number;
 }
-export type ProxyCheckoutValidationCode = "buyer_reference_mismatch" | "cart_invalid" | "invalid_date" | "provider_binding_mismatch" | "subscription_session_mismatch" | "webhook_sessions_resource_missing";
+export type ProxyCheckoutValidationCode = "buyer_reference_mismatch" | "cart_invalid" | "cart_version_conflict" | "commercial_mode_required" | "invalid_date" | "invalid_session_presentation" | "provider_acquisition_in_progress" | "provider_binding_missing" | "provider_binding_mismatch" | "subscription_session_mismatch" | "unsupported_provider_option" | "webhook_sessions_resource_missing";
 /**
  * Raised when the SDK receives Proxy data it cannot safely normalize, for
  * example an invalid date string, a cart snapshot that fails the merchant

package/dist/cjs/events.d.cts

@@ -6,6 +6,7 @@
  * lifecycle decision. It never grants from webhook payload fields, and it
  * classifies subscription events from current state rather than event order.
  */
+import type { ProviderAcquisition, ProxyProviderAcquisitionsResource } from "./provider-acquisitions.js";
 import type { MerchantProxySession, ProxySessionsResource } from "./sessions.js";
 import type { MerchantProxySubscription, ProxySubscriptionsResource } from "./subscriptions.js";
 import type { ProxyCheckoutServerRequestOptions } from "./types.js";
@@ -66,23 +67,30 @@ export interface ResolvedPaymentAttempt extends ResolvedBase {
     readonly sessionId: string | null;
     readonly subscriptionId: string | null;
 }
+export interface ResolvedAcquisitionProgress extends ResolvedBase {
+    readonly acquisition: ProviderAcquisition;
+    readonly kind: "acquisition_progress";
+    readonly session: MerchantProxySession;
+}
 export interface ResolvedIgnored extends ResolvedBase {
     readonly kind: "ignored";
     readonly reason: string;
     readonly sessionId: string | null;
     readonly subscriptionId: string | null;
 }
-export type ResolvedProxyEvent = ResolvedInitialProvision | ResolvedSubscriptionRenewed | ResolvedSubscriptionCancelScheduled | ResolvedSubscriptionCancelled | ResolvedPaymentRisk | ResolvedTerminalSession | ResolvedPaymentAttempt | ResolvedIgnored;
+export type ResolvedProxyEvent = ResolvedInitialProvision | ResolvedSubscriptionRenewed | ResolvedSubscriptionCancelScheduled | ResolvedSubscriptionCancelled | ResolvedPaymentRisk | ResolvedTerminalSession | ResolvedPaymentAttempt | ResolvedAcquisitionProgress | ResolvedIgnored;
 export type ResolvedProxyEventKind = ResolvedProxyEvent["kind"];
 export declare class ProxyEventsResource {
     private readonly sessions;
     private readonly subscriptions;
-    constructor(sessions: ProxySessionsResource, subscriptions: ProxySubscriptionsResource);
+    private readonly providerAcquisitions;
+    constructor(sessions: ProxySessionsResource, subscriptions: ProxySubscriptionsResource, providerAcquisitions: ProxyProviderAcquisitionsResource);
     /**
      * Resolve a signed webhook event into a current-state lifecycle decision by
      * re-reading the authoritative session/subscription with the secret key.
      */
     resolveCurrentState(event: ProxyWebhookEvent, options?: ResolveProxyEventOptions): Promise<ResolvedProxyEvent>;
+    private resolveProviderAcquisitionEvent;
     private resolveSessionEvent;
     private resolveSubscriptionEvent;
 }

package/dist/cjs/events.d.ts

@@ -6,6 +6,7 @@
  * lifecycle decision. It never grants from webhook payload fields, and it
  * classifies subscription events from current state rather than event order.
  */
+import type { ProviderAcquisition, ProxyProviderAcquisitionsResource } from "./provider-acquisitions.js";
 import type { MerchantProxySession, ProxySessionsResource } from "./sessions.js";
 import type { MerchantProxySubscription, ProxySubscriptionsResource } from "./subscriptions.js";
 import type { ProxyCheckoutServerRequestOptions } from "./types.js";
@@ -66,23 +67,30 @@ export interface ResolvedPaymentAttempt extends ResolvedBase {
     readonly sessionId: string | null;
     readonly subscriptionId: string | null;
 }
+export interface ResolvedAcquisitionProgress extends ResolvedBase {
+    readonly acquisition: ProviderAcquisition;
+    readonly kind: "acquisition_progress";
+    readonly session: MerchantProxySession;
+}
 export interface ResolvedIgnored extends ResolvedBase {
     readonly kind: "ignored";
     readonly reason: string;
     readonly sessionId: string | null;
     readonly subscriptionId: string | null;
 }
-export type ResolvedProxyEvent = ResolvedInitialProvision | ResolvedSubscriptionRenewed | ResolvedSubscriptionCancelScheduled | ResolvedSubscriptionCancelled | ResolvedPaymentRisk | ResolvedTerminalSession | ResolvedPaymentAttempt | ResolvedIgnored;
+export type ResolvedProxyEvent = ResolvedInitialProvision | ResolvedSubscriptionRenewed | ResolvedSubscriptionCancelScheduled | ResolvedSubscriptionCancelled | ResolvedPaymentRisk | ResolvedTerminalSession | ResolvedPaymentAttempt | ResolvedAcquisitionProgress | ResolvedIgnored;
 export type ResolvedProxyEventKind = ResolvedProxyEvent["kind"];
 export declare class ProxyEventsResource {
     private readonly sessions;
     private readonly subscriptions;
-    constructor(sessions: ProxySessionsResource, subscriptions: ProxySubscriptionsResource);
+    private readonly providerAcquisitions;
+    constructor(sessions: ProxySessionsResource, subscriptions: ProxySubscriptionsResource, providerAcquisitions: ProxyProviderAcquisitionsResource);
     /**
      * Resolve a signed webhook event into a current-state lifecycle decision by
      * re-reading the authoritative session/subscription with the secret key.
      */
     resolveCurrentState(event: ProxyWebhookEvent, options?: ResolveProxyEventOptions): Promise<ResolvedProxyEvent>;
+    private resolveProviderAcquisitionEvent;
     private resolveSessionEvent;
     private resolveSubscriptionEvent;
 }

package/dist/cjs/events.js

@@ -15,15 +15,20 @@ const webhook_events_js_1 = require("./webhook-events.js");
 class ProxyEventsResource {
     sessions;
     subscriptions;
-    constructor(sessions, subscriptions) {
+    providerAcquisitions;
+    constructor(sessions, subscriptions, providerAcquisitions) {
         this.sessions = sessions;
         this.subscriptions = subscriptions;
+        this.providerAcquisitions = providerAcquisitions;
     }
     /**
      * Resolve a signed webhook event into a current-state lifecycle decision by
      * re-reading the authoritative session/subscription with the secret key.
      */
     async resolveCurrentState(event, options = {}) {
+        if ((0, webhook_events_js_1.isProxyProviderAcquisitionEvent)(event.type)) {
+            return this.resolveProviderAcquisitionEvent(event, options);
+        }
         if ((0, webhook_events_js_1.isProxySubscriptionEvent)(event.type)) {
             return this.resolveSubscriptionEvent(event, options);
         }
@@ -44,6 +49,28 @@ class ProxyEventsResource {
             subscriptionId: readEventString(event.data.subscription_id),
         });
     }
+    async resolveProviderAcquisitionEvent(event, options) {
+        const sessionId = extractSessionId(event);
+        const acquisitionAttemptId = readEventString(event.data.provider_acquisition_attempt_id);
+        if (sessionId === null || acquisitionAttemptId === null) {
+            return ignored(event, "Provider acquisition event is missing current-state identifiers.", {
+                sessionId,
+                subscriptionId: null,
+            });
+        }
+        const [session, acquisitions] = await Promise.all([
+            this.sessions.retrieve(sessionId, options),
+            this.providerAcquisitions.listProviderAcquisitions(sessionId, options),
+        ]);
+        const acquisition = acquisitions.find((candidate) => candidate.id === acquisitionAttemptId);
+        if (!acquisition) {
+            return ignored(event, `Provider acquisition ${acquisitionAttemptId} is no longer visible for session ${sessionId}.`, { sessionId, subscriptionId: null });
+        }
+        if (acquisition.proxySessionId !== session.id) {
+            throw new Error("Proxy provider acquisition current state disagreed with its session");
+        }
+        return { acquisition, event, kind: "acquisition_progress", session };
+    }
     async resolveSessionEvent(event, options) {
         const sessionId = extractSessionId(event);
         if (sessionId === null) {

package/dist/cjs/index.d.cts

@@ -2,12 +2,13 @@ export { type ProxyCartParseOptions, type ProxyCartValidator, parseProxyCart, }
 export { createProxyCheckoutServerClient, ProxyCheckoutServerClient, } from "./client.js";
 export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./consistency.js";
 export { isProxySessionNotFoundError, PROXY_SESSION_NOT_FOUND_ERROR_CODE, ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails, type ProxyCheckoutValidationCode, ProxyCheckoutValidationError, } from "./errors.js";
-export { ProxyEventsResource, type ResolvedIgnored, type ResolvedInitialProvision, type ResolvedPaymentAttempt, type ResolvedPaymentRisk, type ResolvedProxyEvent, type ResolvedProxyEventKind, type ResolvedSubscriptionCancelled, type ResolvedSubscriptionCancelScheduled, type ResolvedSubscriptionRenewed, type ResolvedTerminalSession, type ResolveProxyEventOptions, } from "./events.js";
+export { ProxyEventsResource, type ResolvedAcquisitionProgress, type ResolvedIgnored, type ResolvedInitialProvision, type ResolvedPaymentAttempt, type ResolvedPaymentRisk, type ResolvedProxyEvent, type ResolvedProxyEventKind, type ResolvedSubscriptionCancelled, type ResolvedSubscriptionCancelScheduled, type ResolvedSubscriptionRenewed, type ResolvedTerminalSession, type ResolveProxyEventOptions, } from "./events.js";
 export { AT_RISK_SUBSCRIPTION_STATUSES, ENDED_SUBSCRIPTION_STATUSES, isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, PROVISIONABLE_SESSION_STATUSES, parseOptionalProxyDate, requireProxyDate, subscriptionAccessEndsAt, subscriptionWillRenew, TERMINAL_SESSION_STATUSES, } from "./lifecycle.js";
-export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MarkProxySessionProvisionedInput, type MarkProxySessionProvisioningFailedInput, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, type ProxySessionProvisioningAcknowledgement, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";
+export { type AttachProviderAcquisitionObjectInput, type ProviderAcquisition, type ProviderAcquisitionCheckoutUiMode, type ProviderAcquisitionCommercialMode, type ProviderAcquisitionIntegrationPath, type ProviderAcquisitionObjectType, type ProviderAcquisitionObservedCheckoutUiMode, type ProviderAcquisitionPricingMode, type ProviderAcquisitionReservation, ProxyProviderAcquisitionsResource, proxyCheckoutProviderAcquisitionEndpoints, type ReserveProviderAcquisitionInput, type SupersedeProviderAcquisitionInput, } from "./provider-acquisitions.js";
+export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MarkProxySessionProvisionedInput, type MarkProxySessionProvisioningFailedInput, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, type ProxySessionAcquisitionSummary, type ProxySessionActionableNextStep, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionPresentationState, type ProxySessionProviderBinding, type ProxySessionProvisioningAcknowledgement, ProxySessionsResource, type ProxySessionViewStatus, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";
 export { type MerchantProxySubscription, ProxySubscriptionsResource, type ProxySubscriptionWithSession, type ProxySubscriptionWithUntypedSession, proxyCheckoutSubscriptionEndpoints, } from "./subscriptions.js";
 export type { JsonObject, JsonPrimitive, JsonValue, ProxyCheckoutFetch, ProxyCheckoutServerClientOptions, ProxyCheckoutServerRequestOptions, } from "./types.js";
 export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";
-export { isProxyPaymentAttemptEvent, isProxySessionEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, type ProxyWebhookEventType, } from "./webhook-events.js";
+export { isProxyPaymentAttemptEvent, isProxyProviderAcquisitionEvent, isProxySessionEvent, isProxyShopifyEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, type ProxyWebhookEventType, } from "./webhook-events.js";
 export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookProvisioningFailure, type ProxyWebhookProvisioningSuccess, type ProxyWebhookProvisioningSuccessResult, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
 export { type ConstructProxyWebhookEventInput, type CreateWebhookEndpointInput, constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, type ProxyWebhookEvent, ProxyWebhookSignatureVerificationError, proxyCheckoutWebhookEndpointEndpoints, type RotateWebhookEndpointSecretInput, type UpdateWebhookEndpointInput, type VerifyProxyWebhookSignatureInput, verifyProxyWebhookSignature, type WebhookEndpoint, type WebhookEndpointSecretResult, } from "./webhooks.js";

package/dist/cjs/index.d.ts

@@ -2,12 +2,13 @@ export { type ProxyCartParseOptions, type ProxyCartValidator, parseProxyCart, }
 export { createProxyCheckoutServerClient, ProxyCheckoutServerClient, } from "./client.js";
 export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./consistency.js";
 export { isProxySessionNotFoundError, PROXY_SESSION_NOT_FOUND_ERROR_CODE, ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails, type ProxyCheckoutValidationCode, ProxyCheckoutValidationError, } from "./errors.js";
-export { ProxyEventsResource, type ResolvedIgnored, type ResolvedInitialProvision, type ResolvedPaymentAttempt, type ResolvedPaymentRisk, type ResolvedProxyEvent, type ResolvedProxyEventKind, type ResolvedSubscriptionCancelled, type ResolvedSubscriptionCancelScheduled, type ResolvedSubscriptionRenewed, type ResolvedTerminalSession, type ResolveProxyEventOptions, } from "./events.js";
+export { ProxyEventsResource, type ResolvedAcquisitionProgress, type ResolvedIgnored, type ResolvedInitialProvision, type ResolvedPaymentAttempt, type ResolvedPaymentRisk, type ResolvedProxyEvent, type ResolvedProxyEventKind, type ResolvedSubscriptionCancelled, type ResolvedSubscriptionCancelScheduled, type ResolvedSubscriptionRenewed, type ResolvedTerminalSession, type ResolveProxyEventOptions, } from "./events.js";
 export { AT_RISK_SUBSCRIPTION_STATUSES, ENDED_SUBSCRIPTION_STATUSES, isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, PROVISIONABLE_SESSION_STATUSES, parseOptionalProxyDate, requireProxyDate, subscriptionAccessEndsAt, subscriptionWillRenew, TERMINAL_SESSION_STATUSES, } from "./lifecycle.js";
-export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MarkProxySessionProvisionedInput, type MarkProxySessionProvisioningFailedInput, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, type ProxySessionProvisioningAcknowledgement, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";
+export { type AttachProviderAcquisitionObjectInput, type ProviderAcquisition, type ProviderAcquisitionCheckoutUiMode, type ProviderAcquisitionCommercialMode, type ProviderAcquisitionIntegrationPath, type ProviderAcquisitionObjectType, type ProviderAcquisitionObservedCheckoutUiMode, type ProviderAcquisitionPricingMode, type ProviderAcquisitionReservation, ProxyProviderAcquisitionsResource, proxyCheckoutProviderAcquisitionEndpoints, type ReserveProviderAcquisitionInput, type SupersedeProviderAcquisitionInput, } from "./provider-acquisitions.js";
+export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MarkProxySessionProvisionedInput, type MarkProxySessionProvisioningFailedInput, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, type ProxySessionAcquisitionSummary, type ProxySessionActionableNextStep, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionPresentationState, type ProxySessionProviderBinding, type ProxySessionProvisioningAcknowledgement, ProxySessionsResource, type ProxySessionViewStatus, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";
 export { type MerchantProxySubscription, ProxySubscriptionsResource, type ProxySubscriptionWithSession, type ProxySubscriptionWithUntypedSession, proxyCheckoutSubscriptionEndpoints, } from "./subscriptions.js";
 export type { JsonObject, JsonPrimitive, JsonValue, ProxyCheckoutFetch, ProxyCheckoutServerClientOptions, ProxyCheckoutServerRequestOptions, } from "./types.js";
 export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";
-export { isProxyPaymentAttemptEvent, isProxySessionEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, type ProxyWebhookEventType, } from "./webhook-events.js";
+export { isProxyPaymentAttemptEvent, isProxyProviderAcquisitionEvent, isProxySessionEvent, isProxyShopifyEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, type ProxyWebhookEventType, } from "./webhook-events.js";
 export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookProvisioningFailure, type ProxyWebhookProvisioningSuccess, type ProxyWebhookProvisioningSuccessResult, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
 export { type ConstructProxyWebhookEventInput, type CreateWebhookEndpointInput, constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, type ProxyWebhookEvent, ProxyWebhookSignatureVerificationError, proxyCheckoutWebhookEndpointEndpoints, type RotateWebhookEndpointSecretInput, type UpdateWebhookEndpointInput, type VerifyProxyWebhookSignatureInput, verifyProxyWebhookSignature, type WebhookEndpoint, type WebhookEndpointSecretResult, } from "./webhooks.js";

package/dist/cjs/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifyProxyWebhookSignature = exports.proxyCheckoutWebhookEndpointEndpoints = exports.ProxyWebhookSignatureVerificationError = exports.ProxyWebhookEndpointsResource = exports.PROXY_SIGNATURE_HEADER = exports.constructProxyWebhookEvent = exports.ProxyWebhooksResource = exports.PROXY_WEBHOOK_RETRY_AFTER_SECONDS = exports.PROXY_WEBHOOK_EVENT_TYPES = exports.isProxySubscriptionEvent = exports.isProxySessionEvent = exports.isProxyPaymentAttemptEvent = exports.proxyCheckoutServerSdkVersion = exports.proxyCheckoutServerSdkUserAgent = exports.proxyCheckoutServerSdkName = exports.proxyCheckoutSubscriptionEndpoints = exports.ProxySubscriptionsResource = exports.proxyCheckoutServerEndpoints = exports.ProxySessionsResource = exports.ProxySessionCartResource = exports.TERMINAL_SESSION_STATUSES = exports.subscriptionWillRenew = exports.subscriptionAccessEndsAt = exports.requireProxyDate = exports.parseOptionalProxyDate = exports.PROVISIONABLE_SESSION_STATUSES = exports.isSubscriptionPaymentAtRisk = exports.isSubscriptionEnded = exports.isSessionTerminal = exports.isSessionProvisionable = exports.ENDED_SUBSCRIPTION_STATUSES = exports.AT_RISK_SUBSCRIPTION_STATUSES = exports.ProxyEventsResource = exports.ProxyCheckoutValidationError = exports.ProxyCheckoutApiError = exports.PROXY_SESSION_NOT_FOUND_ERROR_CODE = exports.isProxySessionNotFoundError = exports.assertSubscriptionMatchesSession = exports.assertCartBuyerReference = exports.ProxyCheckoutServerClient = exports.createProxyCheckoutServerClient = exports.parseProxyCart = void 0;
+exports.verifyProxyWebhookSignature = exports.proxyCheckoutWebhookEndpointEndpoints = exports.ProxyWebhookSignatureVerificationError = exports.ProxyWebhookEndpointsResource = exports.PROXY_SIGNATURE_HEADER = exports.constructProxyWebhookEvent = exports.ProxyWebhooksResource = exports.PROXY_WEBHOOK_RETRY_AFTER_SECONDS = exports.PROXY_WEBHOOK_EVENT_TYPES = exports.isProxySubscriptionEvent = exports.isProxyShopifyEvent = exports.isProxySessionEvent = exports.isProxyProviderAcquisitionEvent = exports.isProxyPaymentAttemptEvent = exports.proxyCheckoutServerSdkVersion = exports.proxyCheckoutServerSdkUserAgent = exports.proxyCheckoutServerSdkName = exports.proxyCheckoutSubscriptionEndpoints = exports.ProxySubscriptionsResource = exports.proxyCheckoutServerEndpoints = exports.ProxySessionsResource = exports.ProxySessionCartResource = exports.proxyCheckoutProviderAcquisitionEndpoints = exports.ProxyProviderAcquisitionsResource = exports.TERMINAL_SESSION_STATUSES = exports.subscriptionWillRenew = exports.subscriptionAccessEndsAt = exports.requireProxyDate = exports.parseOptionalProxyDate = exports.PROVISIONABLE_SESSION_STATUSES = exports.isSubscriptionPaymentAtRisk = exports.isSubscriptionEnded = exports.isSessionTerminal = exports.isSessionProvisionable = exports.ENDED_SUBSCRIPTION_STATUSES = exports.AT_RISK_SUBSCRIPTION_STATUSES = exports.ProxyEventsResource = exports.ProxyCheckoutValidationError = exports.ProxyCheckoutApiError = exports.PROXY_SESSION_NOT_FOUND_ERROR_CODE = exports.isProxySessionNotFoundError = exports.assertSubscriptionMatchesSession = exports.assertCartBuyerReference = exports.ProxyCheckoutServerClient = exports.createProxyCheckoutServerClient = exports.parseProxyCart = void 0;
 var cart_js_1 = require("./cart.js");
 Object.defineProperty(exports, "parseProxyCart", { enumerable: true, get: function () { return cart_js_1.parseProxyCart; } });
 var client_js_1 = require("./client.js");
@@ -29,6 +29,9 @@ Object.defineProperty(exports, "requireProxyDate", { enumerable: true, get: func
 Object.defineProperty(exports, "subscriptionAccessEndsAt", { enumerable: true, get: function () { return lifecycle_js_1.subscriptionAccessEndsAt; } });
 Object.defineProperty(exports, "subscriptionWillRenew", { enumerable: true, get: function () { return lifecycle_js_1.subscriptionWillRenew; } });
 Object.defineProperty(exports, "TERMINAL_SESSION_STATUSES", { enumerable: true, get: function () { return lifecycle_js_1.TERMINAL_SESSION_STATUSES; } });
+var provider_acquisitions_js_1 = require("./provider-acquisitions.js");
+Object.defineProperty(exports, "ProxyProviderAcquisitionsResource", { enumerable: true, get: function () { return provider_acquisitions_js_1.ProxyProviderAcquisitionsResource; } });
+Object.defineProperty(exports, "proxyCheckoutProviderAcquisitionEndpoints", { enumerable: true, get: function () { return provider_acquisitions_js_1.proxyCheckoutProviderAcquisitionEndpoints; } });
 var sessions_js_1 = require("./sessions.js");
 Object.defineProperty(exports, "ProxySessionCartResource", { enumerable: true, get: function () { return sessions_js_1.ProxySessionCartResource; } });
 Object.defineProperty(exports, "ProxySessionsResource", { enumerable: true, get: function () { return sessions_js_1.ProxySessionsResource; } });
@@ -42,7 +45,9 @@ Object.defineProperty(exports, "proxyCheckoutServerSdkUserAgent", { enumerable:
 Object.defineProperty(exports, "proxyCheckoutServerSdkVersion", { enumerable: true, get: function () { return version_js_1.proxyCheckoutServerSdkVersion; } });
 var webhook_events_js_1 = require("./webhook-events.js");
 Object.defineProperty(exports, "isProxyPaymentAttemptEvent", { enumerable: true, get: function () { return webhook_events_js_1.isProxyPaymentAttemptEvent; } });
+Object.defineProperty(exports, "isProxyProviderAcquisitionEvent", { enumerable: true, get: function () { return webhook_events_js_1.isProxyProviderAcquisitionEvent; } });
 Object.defineProperty(exports, "isProxySessionEvent", { enumerable: true, get: function () { return webhook_events_js_1.isProxySessionEvent; } });
+Object.defineProperty(exports, "isProxyShopifyEvent", { enumerable: true, get: function () { return webhook_events_js_1.isProxyShopifyEvent; } });
 Object.defineProperty(exports, "isProxySubscriptionEvent", { enumerable: true, get: function () { return webhook_events_js_1.isProxySubscriptionEvent; } });
 Object.defineProperty(exports, "PROXY_WEBHOOK_EVENT_TYPES", { enumerable: true, get: function () { return webhook_events_js_1.PROXY_WEBHOOK_EVENT_TYPES; } });
 var webhook_handler_js_1 = require("./webhook-handler.js");

package/dist/cjs/provider-acquisitions.d.cts

@@ -0,0 +1,106 @@
+import type { ProxyCheckoutHttpClient } from "./http-client.js";
+import type { ProxyCheckoutServerRequestOptions } from "./types.js";
+declare const providerAcquisitionCheckoutUiModes: readonly ["custom", "embedded", "hosted"];
+declare const providerAcquisitionObservedCheckoutUiModes: readonly ["custom", "embedded", "hosted", "unknown"];
+declare const providerAcquisitionCommercialModes: readonly ["one_time", "subscription"];
+declare const providerAcquisitionIntegrationPaths: readonly ["checkout_session", "direct_subscription", "payment_intent"];
+declare const providerAcquisitionObjectTypes: readonly ["checkout_session", "payment_intent", "setup_intent", "subscription"];
+declare const providerAcquisitionPricingModes: readonly ["fixed", "provider_finalized"];
+export type ProviderAcquisitionCheckoutUiMode = (typeof providerAcquisitionCheckoutUiModes)[number];
+export type ProviderAcquisitionObservedCheckoutUiMode = (typeof providerAcquisitionObservedCheckoutUiModes)[number];
+export type ProviderAcquisitionCommercialMode = (typeof providerAcquisitionCommercialModes)[number];
+export type ProviderAcquisitionIntegrationPath = (typeof providerAcquisitionIntegrationPaths)[number];
+export type ProviderAcquisitionObjectType = (typeof providerAcquisitionObjectTypes)[number];
+export type ProviderAcquisitionPricingMode = (typeof providerAcquisitionPricingModes)[number];
+export interface ProviderAcquisition {
+    readonly attemptNumber: number;
+    readonly checkoutUiMode: ProviderAcquisitionObservedCheckoutUiMode | null;
+    readonly commercialMode: ProviderAcquisitionCommercialMode;
+    readonly completionRecordedAt: string | null;
+    readonly createdAt: string;
+    readonly directFeeBasisSource: string | null;
+    readonly directMerchandiseCurrency: string | null;
+    readonly directMerchandiseSubtotalMinor: number | null;
+    readonly id: string;
+    readonly integrationPath: ProviderAcquisitionIntegrationPath;
+    readonly merchantPspConfigId: string;
+    readonly pricingMode: ProviderAcquisitionPricingMode;
+    readonly providerCreatedAt: string | null;
+    /** Stripe Customer ID retained only as a merchant-authenticated diagnostic. */
+    readonly providerCustomerId: string | null;
+    readonly providerRetryNotAfter: string;
+    readonly providerRootObjectId: string | null;
+    readonly providerRootObjectType: ProviderAcquisitionObjectType | null;
+    readonly providerSetupIntentId: string | null;
+    readonly proxySessionId: string;
+    readonly psp: "stripe";
+    readonly status: string;
+    readonly statusReason: string | null;
+    readonly supersedesAttemptId: string | null;
+    readonly updatedAt: string;
+    readonly version: number;
+}
+export interface ProviderAcquisitionReservation {
+    readonly acquisitionAttempt: ProviderAcquisition;
+    readonly stripe: {
+        readonly idempotencyKeys: {
+            readonly root: string;
+            readonly setupIntent?: string;
+        };
+        readonly metadata: {
+            readonly proxyAcquisitionAttemptId: string;
+            readonly proxyContractVersion: "2";
+            readonly proxySessionId: string;
+        };
+    };
+}
+export interface ReserveProviderAcquisitionInput extends ProxyCheckoutServerRequestOptions {
+    readonly checkoutUiMode?: ProviderAcquisitionCheckoutUiMode;
+    readonly commercialMode: ProviderAcquisitionCommercialMode;
+    readonly integrationPath: ProviderAcquisitionIntegrationPath;
+    /** Optional server-only direct PaymentIntent percentage basis; omit to use verified provider gross. */
+    readonly merchandiseSubtotalMinor?: number;
+    readonly pricingMode: ProviderAcquisitionPricingMode;
+    readonly providerOptionsFingerprint: string;
+}
+export interface AttachProviderAcquisitionObjectInput extends ProxyCheckoutServerRequestOptions {
+    readonly expectedVersion: number;
+    readonly objectId: string;
+    readonly objectType: ProviderAcquisitionObjectType;
+    readonly role: "root" | "setup_intent";
+}
+export interface SupersedeProviderAcquisitionInput extends ProxyCheckoutServerRequestOptions {
+    readonly expectedVersion: number;
+    readonly reason: string;
+    readonly replacement: {
+        readonly checkoutUiMode?: ProviderAcquisitionCheckoutUiMode;
+        readonly integrationPath: ProviderAcquisitionIntegrationPath;
+        readonly providerOptionsFingerprint: string;
+    };
+}
+export declare const proxyCheckoutProviderAcquisitionEndpoints: readonly [{
+    readonly method: "POST";
+    readonly operation: "providerAcquisitions.reserveProviderAcquisition";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts";
+}, {
+    readonly method: "POST";
+    readonly operation: "providerAcquisitions.attachProviderAcquisitionObject";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts/:acquisition_attempt_id/provider_objects";
+}, {
+    readonly method: "POST";
+    readonly operation: "providerAcquisitions.supersedeProviderAcquisition";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts/:acquisition_attempt_id/supersede";
+}, {
+    readonly method: "GET";
+    readonly operation: "providerAcquisitions.listProviderAcquisitions";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts";
+}];
+export declare class ProxyProviderAcquisitionsResource {
+    private readonly httpClient;
+    constructor(httpClient: ProxyCheckoutHttpClient);
+    reserveProviderAcquisition(proxySessionId: string, input: ReserveProviderAcquisitionInput): Promise<ProviderAcquisitionReservation>;
+    attachProviderAcquisitionObject(proxySessionId: string, acquisitionAttemptId: string, input: AttachProviderAcquisitionObjectInput): Promise<ProviderAcquisition>;
+    supersedeProviderAcquisition(proxySessionId: string, acquisitionAttemptId: string, input: SupersedeProviderAcquisitionInput): Promise<ProviderAcquisitionReservation>;
+    listProviderAcquisitions(proxySessionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<ProviderAcquisition[]>;
+}
+export {};

package/dist/cjs/provider-acquisitions.d.ts

@@ -0,0 +1,106 @@
+import type { ProxyCheckoutHttpClient } from "./http-client.js";
+import type { ProxyCheckoutServerRequestOptions } from "./types.js";
+declare const providerAcquisitionCheckoutUiModes: readonly ["custom", "embedded", "hosted"];
+declare const providerAcquisitionObservedCheckoutUiModes: readonly ["custom", "embedded", "hosted", "unknown"];
+declare const providerAcquisitionCommercialModes: readonly ["one_time", "subscription"];
+declare const providerAcquisitionIntegrationPaths: readonly ["checkout_session", "direct_subscription", "payment_intent"];
+declare const providerAcquisitionObjectTypes: readonly ["checkout_session", "payment_intent", "setup_intent", "subscription"];
+declare const providerAcquisitionPricingModes: readonly ["fixed", "provider_finalized"];
+export type ProviderAcquisitionCheckoutUiMode = (typeof providerAcquisitionCheckoutUiModes)[number];
+export type ProviderAcquisitionObservedCheckoutUiMode = (typeof providerAcquisitionObservedCheckoutUiModes)[number];
+export type ProviderAcquisitionCommercialMode = (typeof providerAcquisitionCommercialModes)[number];
+export type ProviderAcquisitionIntegrationPath = (typeof providerAcquisitionIntegrationPaths)[number];
+export type ProviderAcquisitionObjectType = (typeof providerAcquisitionObjectTypes)[number];
+export type ProviderAcquisitionPricingMode = (typeof providerAcquisitionPricingModes)[number];
+export interface ProviderAcquisition {
+    readonly attemptNumber: number;
+    readonly checkoutUiMode: ProviderAcquisitionObservedCheckoutUiMode | null;
+    readonly commercialMode: ProviderAcquisitionCommercialMode;
+    readonly completionRecordedAt: string | null;
+    readonly createdAt: string;
+    readonly directFeeBasisSource: string | null;
+    readonly directMerchandiseCurrency: string | null;
+    readonly directMerchandiseSubtotalMinor: number | null;
+    readonly id: string;
+    readonly integrationPath: ProviderAcquisitionIntegrationPath;
+    readonly merchantPspConfigId: string;
+    readonly pricingMode: ProviderAcquisitionPricingMode;
+    readonly providerCreatedAt: string | null;
+    /** Stripe Customer ID retained only as a merchant-authenticated diagnostic. */
+    readonly providerCustomerId: string | null;
+    readonly providerRetryNotAfter: string;
+    readonly providerRootObjectId: string | null;
+    readonly providerRootObjectType: ProviderAcquisitionObjectType | null;
+    readonly providerSetupIntentId: string | null;
+    readonly proxySessionId: string;
+    readonly psp: "stripe";
+    readonly status: string;
+    readonly statusReason: string | null;
+    readonly supersedesAttemptId: string | null;
+    readonly updatedAt: string;
+    readonly version: number;
+}
+export interface ProviderAcquisitionReservation {
+    readonly acquisitionAttempt: ProviderAcquisition;
+    readonly stripe: {
+        readonly idempotencyKeys: {
+            readonly root: string;
+            readonly setupIntent?: string;
+        };
+        readonly metadata: {
+            readonly proxyAcquisitionAttemptId: string;
+            readonly proxyContractVersion: "2";
+            readonly proxySessionId: string;
+        };
+    };
+}
+export interface ReserveProviderAcquisitionInput extends ProxyCheckoutServerRequestOptions {
+    readonly checkoutUiMode?: ProviderAcquisitionCheckoutUiMode;
+    readonly commercialMode: ProviderAcquisitionCommercialMode;
+    readonly integrationPath: ProviderAcquisitionIntegrationPath;
+    /** Optional server-only direct PaymentIntent percentage basis; omit to use verified provider gross. */
+    readonly merchandiseSubtotalMinor?: number;
+    readonly pricingMode: ProviderAcquisitionPricingMode;
+    readonly providerOptionsFingerprint: string;
+}
+export interface AttachProviderAcquisitionObjectInput extends ProxyCheckoutServerRequestOptions {
+    readonly expectedVersion: number;
+    readonly objectId: string;
+    readonly objectType: ProviderAcquisitionObjectType;
+    readonly role: "root" | "setup_intent";
+}
+export interface SupersedeProviderAcquisitionInput extends ProxyCheckoutServerRequestOptions {
+    readonly expectedVersion: number;
+    readonly reason: string;
+    readonly replacement: {
+        readonly checkoutUiMode?: ProviderAcquisitionCheckoutUiMode;
+        readonly integrationPath: ProviderAcquisitionIntegrationPath;
+        readonly providerOptionsFingerprint: string;
+    };
+}
+export declare const proxyCheckoutProviderAcquisitionEndpoints: readonly [{
+    readonly method: "POST";
+    readonly operation: "providerAcquisitions.reserveProviderAcquisition";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts";
+}, {
+    readonly method: "POST";
+    readonly operation: "providerAcquisitions.attachProviderAcquisitionObject";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts/:acquisition_attempt_id/provider_objects";
+}, {
+    readonly method: "POST";
+    readonly operation: "providerAcquisitions.supersedeProviderAcquisition";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts/:acquisition_attempt_id/supersede";
+}, {
+    readonly method: "GET";
+    readonly operation: "providerAcquisitions.listProviderAcquisitions";
+    readonly path: "/proxy_sessions/:proxy_session_id/acquisition_attempts";
+}];
+export declare class ProxyProviderAcquisitionsResource {
+    private readonly httpClient;
+    constructor(httpClient: ProxyCheckoutHttpClient);
+    reserveProviderAcquisition(proxySessionId: string, input: ReserveProviderAcquisitionInput): Promise<ProviderAcquisitionReservation>;
+    attachProviderAcquisitionObject(proxySessionId: string, acquisitionAttemptId: string, input: AttachProviderAcquisitionObjectInput): Promise<ProviderAcquisition>;
+    supersedeProviderAcquisition(proxySessionId: string, acquisitionAttemptId: string, input: SupersedeProviderAcquisitionInput): Promise<ProviderAcquisitionReservation>;
+    listProviderAcquisitions(proxySessionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<ProviderAcquisition[]>;
+}
+export {};