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

package/dist/cjs/webhook-events.d.ts

@@ -7,18 +7,35 @@
  */
 export declare const PROXY_WEBHOOK_EVENT_TYPES: {
     readonly paymentAttemptCancelled: "payment_attempt.cancelled";
+    readonly paymentAttemptDisputed: "payment_attempt.disputed";
+    readonly paymentAttemptDisputeLost: "payment_attempt.dispute_lost";
+    readonly paymentAttemptDisputeWon: "payment_attempt.dispute_won";
     readonly paymentAttemptFailed: "payment_attempt.failed";
+    readonly paymentAttemptPartiallyRefunded: "payment_attempt.partially_refunded";
+    readonly paymentAttemptReconciliationRequired: "payment_attempt.reconciliation_required";
+    readonly paymentAttemptRefunded: "payment_attempt.refunded";
     readonly paymentAttemptSucceeded: "payment_attempt.succeeded";
+    readonly providerAcquisitionCancelled: "provider_acquisition.cancelled";
+    readonly providerAcquisitionExpired: "provider_acquisition.expired";
+    readonly providerAcquisitionFailed: "provider_acquisition.failed";
+    readonly providerAcquisitionReconciliationRequired: "provider_acquisition.reconciliation_required";
     readonly sessionCancelled: "proxy_session.cancelled";
     readonly sessionExpired: "proxy_session.expired";
     readonly sessionFailed: "proxy_session.failed";
     readonly sessionMerchantActionRequired: "proxy_session.merchant_action_required";
     readonly sessionPaid: "proxy_session.paid";
     readonly sessionProvisionable: "proxy_session.provisionable";
+    readonly shopifyFulfillmentObserved: "shopify.fulfillment_observed";
+    readonly shopifyRefundObserved: "shopify.refund_observed";
+    readonly shopifySubscriptionPaymentObserved: "shopify.subscription_payment_observed";
+    readonly shopifySubscriptionRefundObserved: "shopify.subscription_refund_observed";
     readonly subscriptionCancelled: "subscription.cancelled";
     readonly subscriptionCancelScheduled: "subscription.cancel_scheduled";
+    readonly subscriptionChanged: "subscription.changed";
+    readonly subscriptionConfigurationActionRequired: "subscription.configuration_action_required";
     readonly subscriptionPaymentFailed: "subscription.payment_failed";
     readonly subscriptionRenewed: "subscription.renewed";
+    readonly subscriptionTrialEnding: "subscription.trial_ending";
 };
 export type ProxyWebhookEventType = (typeof PROXY_WEBHOOK_EVENT_TYPES)[keyof typeof PROXY_WEBHOOK_EVENT_TYPES];
 /** True for `proxy_session.*` events. */
@@ -27,3 +44,7 @@ export declare function isProxySessionEvent(eventType: string): boolean;
 export declare function isProxySubscriptionEvent(eventType: string): boolean;
 /** True for `payment_attempt.*` events. */
 export declare function isProxyPaymentAttemptEvent(eventType: string): boolean;
+/** True for non-granting `provider_acquisition.*` progress wakeups. */
+export declare function isProxyProviderAcquisitionEvent(eventType: string): boolean;
+/** True for observation-only `shopify.*` commerce events. */
+export declare function isProxyShopifyEvent(eventType: string): boolean;

package/dist/cjs/webhook-events.js

@@ -11,20 +11,39 @@ exports.PROXY_WEBHOOK_EVENT_TYPES = void 0;
 exports.isProxySessionEvent = isProxySessionEvent;
 exports.isProxySubscriptionEvent = isProxySubscriptionEvent;
 exports.isProxyPaymentAttemptEvent = isProxyPaymentAttemptEvent;
+exports.isProxyProviderAcquisitionEvent = isProxyProviderAcquisitionEvent;
+exports.isProxyShopifyEvent = isProxyShopifyEvent;
 exports.PROXY_WEBHOOK_EVENT_TYPES = {
     paymentAttemptCancelled: "payment_attempt.cancelled",
+    paymentAttemptDisputed: "payment_attempt.disputed",
+    paymentAttemptDisputeLost: "payment_attempt.dispute_lost",
+    paymentAttemptDisputeWon: "payment_attempt.dispute_won",
     paymentAttemptFailed: "payment_attempt.failed",
+    paymentAttemptPartiallyRefunded: "payment_attempt.partially_refunded",
+    paymentAttemptReconciliationRequired: "payment_attempt.reconciliation_required",
+    paymentAttemptRefunded: "payment_attempt.refunded",
     paymentAttemptSucceeded: "payment_attempt.succeeded",
+    providerAcquisitionCancelled: "provider_acquisition.cancelled",
+    providerAcquisitionExpired: "provider_acquisition.expired",
+    providerAcquisitionFailed: "provider_acquisition.failed",
+    providerAcquisitionReconciliationRequired: "provider_acquisition.reconciliation_required",
     sessionCancelled: "proxy_session.cancelled",
     sessionExpired: "proxy_session.expired",
     sessionFailed: "proxy_session.failed",
     sessionMerchantActionRequired: "proxy_session.merchant_action_required",
     sessionPaid: "proxy_session.paid",
     sessionProvisionable: "proxy_session.provisionable",
+    shopifyFulfillmentObserved: "shopify.fulfillment_observed",
+    shopifyRefundObserved: "shopify.refund_observed",
+    shopifySubscriptionPaymentObserved: "shopify.subscription_payment_observed",
+    shopifySubscriptionRefundObserved: "shopify.subscription_refund_observed",
     subscriptionCancelled: "subscription.cancelled",
     subscriptionCancelScheduled: "subscription.cancel_scheduled",
+    subscriptionChanged: "subscription.changed",
+    subscriptionConfigurationActionRequired: "subscription.configuration_action_required",
     subscriptionPaymentFailed: "subscription.payment_failed",
     subscriptionRenewed: "subscription.renewed",
+    subscriptionTrialEnding: "subscription.trial_ending",
 };
 const SESSION_EVENT_TYPES = new Set([
     exports.PROXY_WEBHOOK_EVENT_TYPES.sessionCancelled,
@@ -37,14 +56,35 @@ const SESSION_EVENT_TYPES = new Set([
 const SUBSCRIPTION_EVENT_TYPES = new Set([
     exports.PROXY_WEBHOOK_EVENT_TYPES.subscriptionCancelScheduled,
     exports.PROXY_WEBHOOK_EVENT_TYPES.subscriptionCancelled,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.subscriptionChanged,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.subscriptionConfigurationActionRequired,
     exports.PROXY_WEBHOOK_EVENT_TYPES.subscriptionPaymentFailed,
     exports.PROXY_WEBHOOK_EVENT_TYPES.subscriptionRenewed,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.subscriptionTrialEnding,
 ]);
 const PAYMENT_ATTEMPT_EVENT_TYPES = new Set([
     exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptCancelled,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptDisputeLost,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptDisputeWon,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptDisputed,
     exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptFailed,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptPartiallyRefunded,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptReconciliationRequired,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptRefunded,
     exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptSucceeded,
 ]);
+const PROVIDER_ACQUISITION_EVENT_TYPES = new Set([
+    exports.PROXY_WEBHOOK_EVENT_TYPES.providerAcquisitionCancelled,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.providerAcquisitionExpired,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.providerAcquisitionFailed,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.providerAcquisitionReconciliationRequired,
+]);
+const SHOPIFY_EVENT_TYPES = new Set([
+    exports.PROXY_WEBHOOK_EVENT_TYPES.shopifyFulfillmentObserved,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.shopifyRefundObserved,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.shopifySubscriptionPaymentObserved,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.shopifySubscriptionRefundObserved,
+]);
 /** True for `proxy_session.*` events. */
 function isProxySessionEvent(eventType) {
     return SESSION_EVENT_TYPES.has(eventType);
@@ -57,3 +97,11 @@ function isProxySubscriptionEvent(eventType) {
 function isProxyPaymentAttemptEvent(eventType) {
     return PAYMENT_ATTEMPT_EVENT_TYPES.has(eventType);
 }
+/** True for non-granting `provider_acquisition.*` progress wakeups. */
+function isProxyProviderAcquisitionEvent(eventType) {
+    return PROVIDER_ACQUISITION_EVENT_TYPES.has(eventType);
+}
+/** True for observation-only `shopify.*` commerce events. */
+function isProxyShopifyEvent(eventType) {
+    return SHOPIFY_EVENT_TYPES.has(eventType);
+}

package/dist/cjs/webhook-handler.d.cts

@@ -17,6 +17,7 @@ export type ProxyWebhookClaimResult = "claimed" | "duplicate" | "processing";
 export type ProxyWebhookOutcome = "duplicate" | "ignored" | "processed" | "processing";
 /** Compact, lifecycle-free audit record handed to a {@link ProxyWebhookStore}. */
 export interface ProxyWebhookProcessRecord {
+    readonly acquisitionAttemptId?: string | null;
     readonly kind: ResolvedProxyEventKind;
     readonly paymentAttemptId?: string | null;
     readonly sessionId: string | null;

package/dist/cjs/webhook-handler.d.ts

@@ -17,6 +17,7 @@ export type ProxyWebhookClaimResult = "claimed" | "duplicate" | "processing";
 export type ProxyWebhookOutcome = "duplicate" | "ignored" | "processed" | "processing";
 /** Compact, lifecycle-free audit record handed to a {@link ProxyWebhookStore}. */
 export interface ProxyWebhookProcessRecord {
+    readonly acquisitionAttemptId?: string | null;
     readonly kind: ResolvedProxyEventKind;
     readonly paymentAttemptId?: string | null;
     readonly sessionId: string | null;

package/dist/cjs/webhook-handler.js

@@ -198,6 +198,13 @@ function jsonResponse(status, body) {
 }
 function toProcessRecord(resolved) {
     switch (resolved.kind) {
+        case "acquisition_progress":
+            return {
+                acquisitionAttemptId: resolved.acquisition.id,
+                kind: resolved.kind,
+                sessionId: resolved.session.id,
+                subscriptionId: null,
+            };
         case "ignored":
             return {
                 kind: resolved.kind,

package/dist/esm/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/esm/client.js

@@ -1,5 +1,6 @@
 import { ProxyEventsResource } from "./events.js";
 import { ProxyCheckoutHttpClient } from "./http-client.js";
+import { ProxyProviderAcquisitionsResource } from "./provider-acquisitions.js";
 import { ProxySessionsResource } from "./sessions.js";
 import { ProxySubscriptionsResource } from "./subscriptions.js";
 import { ProxyWebhooksResource } from "./webhook-handler.js";
@@ -7,6 +8,7 @@ import { ProxyWebhookEndpointsResource } from "./webhooks.js";
 export class ProxyCheckoutServerClient {
     apiHost;
     sessions;
+    providerAcquisitions;
     subscriptions;
     /** Current-state lifecycle resolver for signed webhook events. */
     events;
@@ -25,8 +27,9 @@ export class ProxyCheckoutServerClient {
             payHost: options.payHost,
             publishableKey: options.publishableKey,
         });
+        this.providerAcquisitions = new ProxyProviderAcquisitionsResource(httpClient);
         this.subscriptions = new ProxySubscriptionsResource(httpClient, this.sessions);
-        this.events = new ProxyEventsResource(this.sessions, this.subscriptions);
+        this.events = new ProxyEventsResource(this.sessions, this.subscriptions, this.providerAcquisitions);
         this.webhooks = new ProxyWebhooksResource(this.events, this.sessions);
         this.webhookEndpoints = new ProxyWebhookEndpointsResource(httpClient);
     }

package/dist/esm/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/esm/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/esm/events.js

@@ -8,19 +8,24 @@
  */
 import { assertSubscriptionMatchesSession } from "./consistency.js";
 import { isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, subscriptionAccessEndsAt, subscriptionWillRenew, } from "./lifecycle.js";
-import { isProxyPaymentAttemptEvent, isProxySessionEvent, isProxySubscriptionEvent, } from "./webhook-events.js";
+import { isProxyPaymentAttemptEvent, isProxyProviderAcquisitionEvent, isProxySessionEvent, isProxySubscriptionEvent, } from "./webhook-events.js";
 export 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 (isProxyProviderAcquisitionEvent(event.type)) {
+            return this.resolveProviderAcquisitionEvent(event, options);
+        }
         if (isProxySubscriptionEvent(event.type)) {
             return this.resolveSubscriptionEvent(event, options);
         }
@@ -41,6 +46,28 @@ export 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/esm/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/esm/index.js

@@ -4,9 +4,10 @@ export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./c
 export { isProxySessionNotFoundError, PROXY_SESSION_NOT_FOUND_ERROR_CODE, ProxyCheckoutApiError, ProxyCheckoutValidationError, } from "./errors.js";
 export { ProxyEventsResource, } 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 { ProxyProviderAcquisitionsResource, proxyCheckoutProviderAcquisitionEndpoints, } from "./provider-acquisitions.js";
 export { ProxySessionCartResource, ProxySessionsResource, proxyCheckoutServerEndpoints, } from "./sessions.js";
 export { ProxySubscriptionsResource, proxyCheckoutSubscriptionEndpoints, } from "./subscriptions.js";
 export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";
-export { isProxyPaymentAttemptEvent, isProxySessionEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, } from "./webhook-events.js";
+export { isProxyPaymentAttemptEvent, isProxyProviderAcquisitionEvent, isProxySessionEvent, isProxyShopifyEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, } from "./webhook-events.js";
 export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, ProxyWebhooksResource, } from "./webhook-handler.js";
 export { constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, ProxyWebhookSignatureVerificationError, proxyCheckoutWebhookEndpointEndpoints, verifyProxyWebhookSignature, } from "./webhooks.js";

package/dist/esm/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 {};

package/dist/esm/provider-acquisitions.js

@@ -0,0 +1,164 @@
+import { requireInteger, requireJsonObject, requireNullableInteger, requireNullableString, requireString, } from "./response-validators.js";
+const providerAcquisitionCheckoutUiModes = ["custom", "embedded", "hosted"];
+const providerAcquisitionObservedCheckoutUiModes = [
+    ...providerAcquisitionCheckoutUiModes,
+    "unknown",
+];
+const providerAcquisitionCommercialModes = ["one_time", "subscription"];
+const providerAcquisitionIntegrationPaths = [
+    "checkout_session",
+    "direct_subscription",
+    "payment_intent",
+];
+const providerAcquisitionObjectTypes = [
+    "checkout_session",
+    "payment_intent",
+    "setup_intent",
+    "subscription",
+];
+const providerAcquisitionPricingModes = ["fixed", "provider_finalized"];
+const providerAcquisitionPsps = ["stripe"];
+export const proxyCheckoutProviderAcquisitionEndpoints = [
+    {
+        method: "POST",
+        operation: "providerAcquisitions.reserveProviderAcquisition",
+        path: "/proxy_sessions/:proxy_session_id/acquisition_attempts",
+    },
+    {
+        method: "POST",
+        operation: "providerAcquisitions.attachProviderAcquisitionObject",
+        path: "/proxy_sessions/:proxy_session_id/acquisition_attempts/:acquisition_attempt_id/provider_objects",
+    },
+    {
+        method: "POST",
+        operation: "providerAcquisitions.supersedeProviderAcquisition",
+        path: "/proxy_sessions/:proxy_session_id/acquisition_attempts/:acquisition_attempt_id/supersede",
+    },
+    {
+        method: "GET",
+        operation: "providerAcquisitions.listProviderAcquisitions",
+        path: "/proxy_sessions/:proxy_session_id/acquisition_attempts",
+    },
+];
+export class ProxyProviderAcquisitionsResource {
+    httpClient;
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    async reserveProviderAcquisition(proxySessionId, input) {
+        const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/acquisition_attempts`, {
+            ...(input.checkoutUiMode === undefined ? {} : { checkout_ui_mode: input.checkoutUiMode }),
+            commercial_mode: input.commercialMode,
+            integration_path: input.integrationPath,
+            ...(input.merchandiseSubtotalMinor === undefined
+                ? {}
+                : { merchandise_subtotal_minor: input.merchandiseSubtotalMinor }),
+            pricing_mode: input.pricingMode,
+            provider_options_fingerprint: input.providerOptionsFingerprint,
+        }, { requestId: input.requestId });
+        return parseReservation(response, "providerAcquisitions.reserveProviderAcquisition");
+    }
+    async attachProviderAcquisitionObject(proxySessionId, acquisitionAttemptId, input) {
+        const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/acquisition_attempts/${encodeURIComponent(acquisitionAttemptId)}/provider_objects`, {
+            expected_version: input.expectedVersion,
+            object_id: input.objectId,
+            object_type: input.objectType,
+            role: input.role,
+        }, { requestId: input.requestId });
+        return parseAcquisition(response, "providerAcquisitions.attachProviderAcquisitionObject");
+    }
+    async supersedeProviderAcquisition(proxySessionId, acquisitionAttemptId, input) {
+        const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/acquisition_attempts/${encodeURIComponent(acquisitionAttemptId)}/supersede`, {
+            expected_version: input.expectedVersion,
+            reason: input.reason,
+            replacement: {
+                ...(input.replacement.checkoutUiMode === undefined
+                    ? {}
+                    : { checkout_ui_mode: input.replacement.checkoutUiMode }),
+                integration_path: input.replacement.integrationPath,
+                provider_options_fingerprint: input.replacement.providerOptionsFingerprint,
+            },
+        }, { requestId: input.requestId });
+        return parseReservation(response, "providerAcquisitions.supersedeProviderAcquisition");
+    }
+    async listProviderAcquisitions(proxySessionId, options = {}) {
+        const response = await this.httpClient.request("GET", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/acquisition_attempts`, undefined, options);
+        const body = requireJsonObject(response, "providerAcquisitions.listProviderAcquisitions");
+        if (!Array.isArray(body.data)) {
+            throw new Error("Proxy API response field providerAcquisitions.listProviderAcquisitions.data must be an array.");
+        }
+        return body.data.map((value, index) => parseAcquisition(value, `providerAcquisitions.listProviderAcquisitions.data[${index}]`));
+    }
+}
+function parseReservation(value, operation) {
+    const body = requireJsonObject(value, operation);
+    const stripe = requireJsonObject(body.stripe, `${operation}.stripe`);
+    const idempotencyKeys = requireJsonObject(stripe.idempotency_keys, `${operation}.stripe.idempotencyKeys`);
+    const metadata = requireJsonObject(stripe.metadata, `${operation}.stripe.metadata`);
+    const contractVersion = requireString(metadata.proxy_contract_version, `${operation}.stripe.metadata.proxyContractVersion`);
+    if (contractVersion !== "2") {
+        throw new Error(`Proxy API response field ${operation}.stripe.metadata.proxyContractVersion is unsupported.`);
+    }
+    const setupIntent = idempotencyKeys.setup_intent;
+    return {
+        acquisitionAttempt: parseAcquisition(body.acquisition_attempt, `${operation}.acquisitionAttempt`),
+        stripe: {
+            idempotencyKeys: {
+                root: requireString(idempotencyKeys.root, `${operation}.stripe.idempotencyKeys.root`),
+                ...(setupIntent === undefined
+                    ? {}
+                    : {
+                        setupIntent: requireString(setupIntent, `${operation}.stripe.idempotencyKeys.setupIntent`),
+                    }),
+            },
+            metadata: {
+                proxyAcquisitionAttemptId: requireString(metadata.proxy_acquisition_attempt_id, `${operation}.stripe.metadata.proxyAcquisitionAttemptId`),
+                proxyContractVersion: contractVersion,
+                proxySessionId: requireString(metadata.proxy_session_id, `${operation}.stripe.metadata.proxySessionId`),
+            },
+        },
+    };
+}
+function parseAcquisition(value, operation) {
+    const body = requireJsonObject(value, operation);
+    return {
+        attemptNumber: requireInteger(body.attempt_number, `${operation}.attemptNumber`),
+        checkoutUiMode: requireNullableEnum(body.checkout_ui_mode, `${operation}.checkoutUiMode`, providerAcquisitionObservedCheckoutUiModes),
+        commercialMode: requireEnum(body.commercial_mode, `${operation}.commercialMode`, providerAcquisitionCommercialModes),
+        completionRecordedAt: requireNullableString(body.completion_recorded_at, `${operation}.completionRecordedAt`),
+        createdAt: requireString(body.created_at, `${operation}.createdAt`),
+        directFeeBasisSource: requireNullableString(body.direct_fee_basis_source, `${operation}.directFeeBasisSource`),
+        directMerchandiseCurrency: requireNullableString(body.direct_merchandise_currency, `${operation}.directMerchandiseCurrency`),
+        directMerchandiseSubtotalMinor: requireNullableInteger(body.direct_merchandise_subtotal_minor, `${operation}.directMerchandiseSubtotalMinor`),
+        id: requireString(body.id, `${operation}.id`),
+        integrationPath: requireEnum(body.integration_path, `${operation}.integrationPath`, providerAcquisitionIntegrationPaths),
+        merchantPspConfigId: requireString(body.merchant_psp_config_id, `${operation}.merchantPspConfigId`),
+        pricingMode: requireEnum(body.pricing_mode, `${operation}.pricingMode`, providerAcquisitionPricingModes),
+        providerCreatedAt: requireNullableString(body.provider_created_at, `${operation}.providerCreatedAt`),
+        providerCustomerId: requireNullableString(body.provider_customer_id, `${operation}.providerCustomerId`),
+        providerRetryNotAfter: requireString(body.provider_retry_not_after, `${operation}.providerRetryNotAfter`),
+        providerRootObjectId: requireNullableString(body.provider_root_object_id, `${operation}.providerRootObjectId`),
+        providerRootObjectType: requireNullableEnum(body.provider_root_object_type, `${operation}.providerRootObjectType`, providerAcquisitionObjectTypes),
+        providerSetupIntentId: requireNullableString(body.provider_setup_intent_id, `${operation}.providerSetupIntentId`),
+        proxySessionId: requireString(body.proxy_session_id, `${operation}.proxySessionId`),
+        psp: requireEnum(body.psp, `${operation}.psp`, providerAcquisitionPsps),
+        status: requireString(body.status, `${operation}.status`),
+        statusReason: requireNullableString(body.status_reason, `${operation}.statusReason`),
+        supersedesAttemptId: requireNullableString(body.supersedes_attempt_id, `${operation}.supersedesAttemptId`),
+        updatedAt: requireString(body.updated_at, `${operation}.updatedAt`),
+        version: requireInteger(body.version, `${operation}.version`),
+    };
+}
+function requireEnum(value, field, values) {
+    const parsed = requireString(value, field);
+    if (!isEnumValue(parsed, values)) {
+        throw new Error(`Proxy API response field ${field} must be one of: ${values.join(", ")}.`);
+    }
+    return parsed;
+}
+function requireNullableEnum(value, field, values) {
+    return value === null ? null : requireEnum(value, field, values);
+}
+function isEnumValue(value, values) {
+    return values.some((candidate) => candidate === value);
+}