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

package/dist/cjs/provider-acquisitions.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxyProviderAcquisitionsResource = exports.proxyCheckoutProviderAcquisitionEndpoints = void 0;
+const response_validators_js_1 = require("./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"];
+exports.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",
+    },
+];
+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 = (0, response_validators_js_1.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}]`));
+    }
+}
+exports.ProxyProviderAcquisitionsResource = ProxyProviderAcquisitionsResource;
+function parseReservation(value, operation) {
+    const body = (0, response_validators_js_1.requireJsonObject)(value, operation);
+    const stripe = (0, response_validators_js_1.requireJsonObject)(body.stripe, `${operation}.stripe`);
+    const idempotencyKeys = (0, response_validators_js_1.requireJsonObject)(stripe.idempotency_keys, `${operation}.stripe.idempotencyKeys`);
+    const metadata = (0, response_validators_js_1.requireJsonObject)(stripe.metadata, `${operation}.stripe.metadata`);
+    const contractVersion = (0, response_validators_js_1.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: (0, response_validators_js_1.requireString)(idempotencyKeys.root, `${operation}.stripe.idempotencyKeys.root`),
+                ...(setupIntent === undefined
+                    ? {}
+                    : {
+                        setupIntent: (0, response_validators_js_1.requireString)(setupIntent, `${operation}.stripe.idempotencyKeys.setupIntent`),
+                    }),
+            },
+            metadata: {
+                proxyAcquisitionAttemptId: (0, response_validators_js_1.requireString)(metadata.proxy_acquisition_attempt_id, `${operation}.stripe.metadata.proxyAcquisitionAttemptId`),
+                proxyContractVersion: contractVersion,
+                proxySessionId: (0, response_validators_js_1.requireString)(metadata.proxy_session_id, `${operation}.stripe.metadata.proxySessionId`),
+            },
+        },
+    };
+}
+function parseAcquisition(value, operation) {
+    const body = (0, response_validators_js_1.requireJsonObject)(value, operation);
+    return {
+        attemptNumber: (0, response_validators_js_1.requireInteger)(body.attempt_number, `${operation}.attemptNumber`),
+        checkoutUiMode: requireNullableEnum(body.checkout_ui_mode, `${operation}.checkoutUiMode`, providerAcquisitionObservedCheckoutUiModes),
+        commercialMode: requireEnum(body.commercial_mode, `${operation}.commercialMode`, providerAcquisitionCommercialModes),
+        completionRecordedAt: (0, response_validators_js_1.requireNullableString)(body.completion_recorded_at, `${operation}.completionRecordedAt`),
+        createdAt: (0, response_validators_js_1.requireString)(body.created_at, `${operation}.createdAt`),
+        directFeeBasisSource: (0, response_validators_js_1.requireNullableString)(body.direct_fee_basis_source, `${operation}.directFeeBasisSource`),
+        directMerchandiseCurrency: (0, response_validators_js_1.requireNullableString)(body.direct_merchandise_currency, `${operation}.directMerchandiseCurrency`),
+        directMerchandiseSubtotalMinor: (0, response_validators_js_1.requireNullableInteger)(body.direct_merchandise_subtotal_minor, `${operation}.directMerchandiseSubtotalMinor`),
+        id: (0, response_validators_js_1.requireString)(body.id, `${operation}.id`),
+        integrationPath: requireEnum(body.integration_path, `${operation}.integrationPath`, providerAcquisitionIntegrationPaths),
+        merchantPspConfigId: (0, response_validators_js_1.requireString)(body.merchant_psp_config_id, `${operation}.merchantPspConfigId`),
+        pricingMode: requireEnum(body.pricing_mode, `${operation}.pricingMode`, providerAcquisitionPricingModes),
+        providerCreatedAt: (0, response_validators_js_1.requireNullableString)(body.provider_created_at, `${operation}.providerCreatedAt`),
+        providerCustomerId: (0, response_validators_js_1.requireNullableString)(body.provider_customer_id, `${operation}.providerCustomerId`),
+        providerRetryNotAfter: (0, response_validators_js_1.requireString)(body.provider_retry_not_after, `${operation}.providerRetryNotAfter`),
+        providerRootObjectId: (0, response_validators_js_1.requireNullableString)(body.provider_root_object_id, `${operation}.providerRootObjectId`),
+        providerRootObjectType: requireNullableEnum(body.provider_root_object_type, `${operation}.providerRootObjectType`, providerAcquisitionObjectTypes),
+        providerSetupIntentId: (0, response_validators_js_1.requireNullableString)(body.provider_setup_intent_id, `${operation}.providerSetupIntentId`),
+        proxySessionId: (0, response_validators_js_1.requireString)(body.proxy_session_id, `${operation}.proxySessionId`),
+        psp: requireEnum(body.psp, `${operation}.psp`, providerAcquisitionPsps),
+        status: (0, response_validators_js_1.requireString)(body.status, `${operation}.status`),
+        statusReason: (0, response_validators_js_1.requireNullableString)(body.status_reason, `${operation}.statusReason`),
+        supersedesAttemptId: (0, response_validators_js_1.requireNullableString)(body.supersedes_attempt_id, `${operation}.supersedesAttemptId`),
+        updatedAt: (0, response_validators_js_1.requireString)(body.updated_at, `${operation}.updatedAt`),
+        version: (0, response_validators_js_1.requireInteger)(body.version, `${operation}.version`),
+    };
+}
+function requireEnum(value, field, values) {
+    const parsed = (0, response_validators_js_1.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);
+}

package/dist/cjs/sessions.d.cts

@@ -37,6 +37,7 @@ export interface ProxySessionHandoff extends ProxySession {
     readonly status: "payer_handoff_pending" | "payer_opened";
 }
 export interface MerchantProxySession {
+    readonly actionableNextStep: ProxySessionActionableNextStep;
     readonly amountMinor: number;
     readonly beneficiaryContact: {
         readonly email: string | null;
@@ -45,8 +46,10 @@ export interface MerchantProxySession {
     readonly buyerReference: string;
     readonly cartSnapshot: JsonObject;
     readonly cartVersion: number;
+    readonly completedAcquisitionAttemptId: string | null;
     readonly createdAt: string;
     readonly currency: string;
+    readonly currentAcquisitionAttempt: ProxySessionAcquisitionSummary | null;
     readonly expiresAt: string;
     readonly id: string;
     readonly idempotencyKey: string | null;
@@ -57,14 +60,27 @@ export interface MerchantProxySession {
         readonly phone: string | null;
     } | null;
     readonly payerDestinationUrl: string | null;
+    readonly presentationState: ProxySessionPresentationState;
     readonly providerCheckoutSessionId: string | null;
     readonly providerCheckoutSessionPsp: string | null;
     readonly status: string;
     readonly updatedAt: string;
 }
+export interface ProxySessionAcquisitionSummary {
+    readonly attemptNumber: number;
+    readonly checkoutUiMode: string | null;
+    readonly id: string;
+    readonly integrationPath: string;
+    readonly status: string;
+    readonly statusReason: string | null;
+}
+export type ProxySessionActionableNextStep = "already_paid" | "continue_payment" | "merchant_action_required" | "prepare_provider" | "unavailable";
 export interface PayerOpenedResult extends MerchantProxySession {
-    readonly status: "payer_opened";
+    readonly presentationState: ProxySessionPresentationState;
+    readonly status: ProxySessionViewStatus;
 }
+export type ProxySessionPresentationState = "action_required" | "already_paid" | "checkout_available" | "unavailable";
+export type ProxySessionViewStatus = "cancelled" | "created" | "expired" | "failed" | "merchant_action_required" | "paid" | "payer_handoff_pending" | "payer_opened" | "payment_pending" | "provisionable" | "provisioned" | "provisioning_failed";
 /** A merchant session with its cart snapshot validated against a merchant schema. */
 export interface TypedMerchantProxySession<TCart> extends MerchantProxySession {
     readonly cart: TCart;
@@ -84,10 +100,22 @@ export interface ProxySessionCartResult {
     readonly cartVersion: number;
     readonly currency: string;
 }
-export interface RecordProviderBindingInput extends ProxyCheckoutServerRequestOptions {
+interface RecordProviderBindingBaseInput extends ProxyCheckoutServerRequestOptions {
+    readonly expectedCartVersion?: number;
     readonly providerCheckoutSessionId: string;
-    readonly psp: string;
 }
+/**
+ * Input for the deprecated provider-binding compatibility adapter.
+ * Canonical Stripe literals require `commercialMode` at compile time; dynamic
+ * or untyped inputs remain protected by the matching runtime validation.
+ */
+export type RecordProviderBindingInput<TPsp extends string = string> = RecordProviderBindingBaseInput & {
+    readonly psp: TPsp;
+} & (Lowercase<TPsp> extends "stripe" ? {
+    readonly commercialMode: "one_time" | "subscription";
+} : {
+    readonly commercialMode?: "one_time" | "subscription";
+});
 export interface ProxySessionProviderBinding {
     readonly providerCheckoutSessionId: string;
     readonly proxySessionId: string;
@@ -181,8 +209,11 @@ export declare class ProxySessionsResource {
      * Bind a provider (PSP) checkout object to a Proxy session so later cart sync
      * can verify ownership. Idempotent for the same provider object; conflicts when
      * the session is already bound to a different one.
+     *
+     * @deprecated Prefer provider acquisition attempts or a provider-specific
+     * helper such as `@proxy-checkout/stripe-server-js` `openCheckout(...)`.
      */
-    recordProviderBinding(proxySessionId: string, input: RecordProviderBindingInput): Promise<ProxySessionProviderBinding>;
+    recordProviderBinding<const TPsp extends string>(proxySessionId: string, input: RecordProviderBindingInput<TPsp>): Promise<ProxySessionProviderBinding>;
     markProvisioned(proxySessionId: string, input?: MarkProxySessionProvisionedInput): Promise<ProxySessionProvisioningAcknowledgement>;
     markProvisioningFailed(proxySessionId: string, input: MarkProxySessionProvisioningFailedInput): Promise<ProxySessionProvisioningAcknowledgement>;
 }
@@ -191,3 +222,4 @@ export declare class ProxySessionCartResource {
     constructor(httpClient: ProxyCheckoutHttpClient);
     set(proxySessionId: string, input: SetProxySessionCartInput): Promise<ProxySessionCartResult>;
 }
+export {};

package/dist/cjs/sessions.d.ts

@@ -37,6 +37,7 @@ export interface ProxySessionHandoff extends ProxySession {
     readonly status: "payer_handoff_pending" | "payer_opened";
 }
 export interface MerchantProxySession {
+    readonly actionableNextStep: ProxySessionActionableNextStep;
     readonly amountMinor: number;
     readonly beneficiaryContact: {
         readonly email: string | null;
@@ -45,8 +46,10 @@ export interface MerchantProxySession {
     readonly buyerReference: string;
     readonly cartSnapshot: JsonObject;
     readonly cartVersion: number;
+    readonly completedAcquisitionAttemptId: string | null;
     readonly createdAt: string;
     readonly currency: string;
+    readonly currentAcquisitionAttempt: ProxySessionAcquisitionSummary | null;
     readonly expiresAt: string;
     readonly id: string;
     readonly idempotencyKey: string | null;
@@ -57,14 +60,27 @@ export interface MerchantProxySession {
         readonly phone: string | null;
     } | null;
     readonly payerDestinationUrl: string | null;
+    readonly presentationState: ProxySessionPresentationState;
     readonly providerCheckoutSessionId: string | null;
     readonly providerCheckoutSessionPsp: string | null;
     readonly status: string;
     readonly updatedAt: string;
 }
+export interface ProxySessionAcquisitionSummary {
+    readonly attemptNumber: number;
+    readonly checkoutUiMode: string | null;
+    readonly id: string;
+    readonly integrationPath: string;
+    readonly status: string;
+    readonly statusReason: string | null;
+}
+export type ProxySessionActionableNextStep = "already_paid" | "continue_payment" | "merchant_action_required" | "prepare_provider" | "unavailable";
 export interface PayerOpenedResult extends MerchantProxySession {
-    readonly status: "payer_opened";
+    readonly presentationState: ProxySessionPresentationState;
+    readonly status: ProxySessionViewStatus;
 }
+export type ProxySessionPresentationState = "action_required" | "already_paid" | "checkout_available" | "unavailable";
+export type ProxySessionViewStatus = "cancelled" | "created" | "expired" | "failed" | "merchant_action_required" | "paid" | "payer_handoff_pending" | "payer_opened" | "payment_pending" | "provisionable" | "provisioned" | "provisioning_failed";
 /** A merchant session with its cart snapshot validated against a merchant schema. */
 export interface TypedMerchantProxySession<TCart> extends MerchantProxySession {
     readonly cart: TCart;
@@ -84,10 +100,22 @@ export interface ProxySessionCartResult {
     readonly cartVersion: number;
     readonly currency: string;
 }
-export interface RecordProviderBindingInput extends ProxyCheckoutServerRequestOptions {
+interface RecordProviderBindingBaseInput extends ProxyCheckoutServerRequestOptions {
+    readonly expectedCartVersion?: number;
     readonly providerCheckoutSessionId: string;
-    readonly psp: string;
 }
+/**
+ * Input for the deprecated provider-binding compatibility adapter.
+ * Canonical Stripe literals require `commercialMode` at compile time; dynamic
+ * or untyped inputs remain protected by the matching runtime validation.
+ */
+export type RecordProviderBindingInput<TPsp extends string = string> = RecordProviderBindingBaseInput & {
+    readonly psp: TPsp;
+} & (Lowercase<TPsp> extends "stripe" ? {
+    readonly commercialMode: "one_time" | "subscription";
+} : {
+    readonly commercialMode?: "one_time" | "subscription";
+});
 export interface ProxySessionProviderBinding {
     readonly providerCheckoutSessionId: string;
     readonly proxySessionId: string;
@@ -181,8 +209,11 @@ export declare class ProxySessionsResource {
      * Bind a provider (PSP) checkout object to a Proxy session so later cart sync
      * can verify ownership. Idempotent for the same provider object; conflicts when
      * the session is already bound to a different one.
+     *
+     * @deprecated Prefer provider acquisition attempts or a provider-specific
+     * helper such as `@proxy-checkout/stripe-server-js` `openCheckout(...)`.
      */
-    recordProviderBinding(proxySessionId: string, input: RecordProviderBindingInput): Promise<ProxySessionProviderBinding>;
+    recordProviderBinding<const TPsp extends string>(proxySessionId: string, input: RecordProviderBindingInput<TPsp>): Promise<ProxySessionProviderBinding>;
     markProvisioned(proxySessionId: string, input?: MarkProxySessionProvisionedInput): Promise<ProxySessionProvisioningAcknowledgement>;
     markProvisioningFailed(proxySessionId: string, input: MarkProxySessionProvisioningFailedInput): Promise<ProxySessionProvisioningAcknowledgement>;
 }
@@ -191,3 +222,4 @@ export declare class ProxySessionCartResource {
     constructor(httpClient: ProxyCheckoutHttpClient);
     set(proxySessionId: string, input: SetProxySessionCartInput): Promise<ProxySessionCartResult>;
 }
+export {};

package/dist/cjs/sessions.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProxySessionCartResource = exports.ProxySessionsResource = exports.proxyCheckoutServerEndpoints = void 0;
 const cart_js_1 = require("./cart.js");
 const consistency_js_1 = require("./consistency.js");
+const errors_js_1 = require("./errors.js");
 const response_validators_js_1 = require("./response-validators.js");
 exports.proxyCheckoutServerEndpoints = [
     {
@@ -139,9 +140,19 @@ class ProxySessionsResource {
      * Bind a provider (PSP) checkout object to a Proxy session so later cart sync
      * can verify ownership. Idempotent for the same provider object; conflicts when
      * the session is already bound to a different one.
+     *
+     * @deprecated Prefer provider acquisition attempts or a provider-specific
+     * helper such as `@proxy-checkout/stripe-server-js` `openCheckout(...)`.
      */
     async recordProviderBinding(proxySessionId, input) {
+        if (input.psp.trim().toLowerCase() === "stripe" && input.commercialMode === undefined) {
+            throw new errors_js_1.ProxyCheckoutValidationError("Stripe provider bindings require commercialMode so Proxy can infer the acquisition safely.", { code: "commercial_mode_required", field: "commercialMode" });
+        }
         const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/provider_bindings`, {
+            ...(input.commercialMode === undefined ? {} : { commercial_mode: input.commercialMode }),
+            ...(input.expectedCartVersion === undefined
+                ? {}
+                : { expected_cart_version: input.expectedCartVersion }),
             provider_checkout_session_id: input.providerCheckoutSessionId,
             psp: input.psp,
         }, { requestId: input.requestId });
@@ -260,14 +271,24 @@ function toProxySessionHandoff(response) {
 }
 function toMerchantProxySession(response) {
     const body = (0, response_validators_js_1.requireJsonObject)(response, "sessions.retrieve");
+    const status = (0, response_validators_js_1.requireString)(body.status, "sessions.retrieve.status");
+    const currentAcquisitionAttempt = optionalAcquisitionSummary(body.current_acquisition_attempt, "sessions.retrieve.currentAcquisitionAttempt");
+    const providerCheckoutSessionId = (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_id, "sessions.retrieve.providerCheckoutSessionId");
+    const presentationState = proxySessionPresentationState(body.presentation_state, status);
     return {
+        actionableNextStep: proxySessionActionableNextStep(body.actionable_next_step, {
+            presentationState,
+            providerCheckoutSessionId,
+        }),
         amountMinor: (0, response_validators_js_1.requireInteger)(body.amount_minor, "sessions.retrieve.amountMinor"),
         beneficiaryContact: requireNullableContact(body.beneficiary_contact, "sessions.retrieve.beneficiaryContact"),
         buyerReference: (0, response_validators_js_1.requireString)(body.buyer_reference, "sessions.retrieve.buyerReference"),
         cartSnapshot: (0, response_validators_js_1.requireJsonObject)(body.cart_snapshot, "sessions.retrieve.cartSnapshot"),
         cartVersion: (0, response_validators_js_1.requireInteger)(body.cart_version, "sessions.retrieve.cartVersion"),
+        completedAcquisitionAttemptId: optionalNullableString(body.completed_acquisition_attempt_id, "sessions.retrieve.completedAcquisitionAttemptId"),
         createdAt: (0, response_validators_js_1.requireString)(body.created_at, "sessions.retrieve.createdAt"),
         currency: (0, response_validators_js_1.requireString)(body.currency, "sessions.retrieve.currency"),
+        currentAcquisitionAttempt,
         expiresAt: (0, response_validators_js_1.requireString)(body.expires_at, "sessions.retrieve.expiresAt"),
         id: (0, response_validators_js_1.requireString)(body.id, "sessions.retrieve.id"),
         idempotencyKey: (0, response_validators_js_1.requireNullableString)(body.idempotency_key, "sessions.retrieve.idempotencyKey"),
@@ -275,26 +296,33 @@ function toMerchantProxySession(response) {
         metadata: (0, response_validators_js_1.requireJsonObject)(body.metadata, "sessions.retrieve.metadata"),
         payerContact: requireNullableContact(body.payer_contact, "sessions.retrieve.payerContact"),
         payerDestinationUrl: (0, response_validators_js_1.requireNullableString)(body.payer_destination_url, "sessions.retrieve.payerDestinationUrl"),
-        providerCheckoutSessionId: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_id, "sessions.retrieve.providerCheckoutSessionId"),
+        presentationState,
+        providerCheckoutSessionId,
         providerCheckoutSessionPsp: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_psp, "sessions.retrieve.providerCheckoutSessionPsp"),
-        status: (0, response_validators_js_1.requireString)(body.status, "sessions.retrieve.status"),
+        status,
         updatedAt: (0, response_validators_js_1.requireString)(body.updated_at, "sessions.retrieve.updatedAt"),
     };
 }
 function toPayerOpenedResult(response) {
     const body = (0, response_validators_js_1.requireJsonObject)(response, "sessions.payerOpened");
-    const status = (0, response_validators_js_1.requireString)(body.status, "sessions.payerOpened.status");
-    if (status !== "payer_opened") {
-        throw new Error("Proxy API response field sessions.payerOpened.status is unsupported.");
-    }
+    const status = requireProxySessionViewStatus(body.status);
+    const currentAcquisitionAttempt = optionalAcquisitionSummary(body.current_acquisition_attempt, "sessions.payerOpened.currentAcquisitionAttempt");
+    const providerCheckoutSessionId = (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_id, "sessions.payerOpened.providerCheckoutSessionId");
+    const presentationState = proxySessionPresentationState(body.presentation_state, status);
     return {
+        actionableNextStep: proxySessionActionableNextStep(body.actionable_next_step, {
+            presentationState,
+            providerCheckoutSessionId,
+        }),
         amountMinor: (0, response_validators_js_1.requireInteger)(body.amount_minor, "sessions.payerOpened.amountMinor"),
         beneficiaryContact: requireNullableContact(body.beneficiary_contact, "sessions.payerOpened.beneficiaryContact"),
         buyerReference: (0, response_validators_js_1.requireString)(body.buyer_reference, "sessions.payerOpened.buyerReference"),
         cartSnapshot: (0, response_validators_js_1.requireJsonObject)(body.cart_snapshot, "sessions.payerOpened.cartSnapshot"),
         cartVersion: (0, response_validators_js_1.requireInteger)(body.cart_version, "sessions.payerOpened.cartVersion"),
+        completedAcquisitionAttemptId: optionalNullableString(body.completed_acquisition_attempt_id, "sessions.payerOpened.completedAcquisitionAttemptId"),
         createdAt: (0, response_validators_js_1.requireString)(body.created_at, "sessions.payerOpened.createdAt"),
         currency: (0, response_validators_js_1.requireString)(body.currency, "sessions.payerOpened.currency"),
+        currentAcquisitionAttempt,
         expiresAt: (0, response_validators_js_1.requireString)(body.expires_at, "sessions.payerOpened.expiresAt"),
         id: (0, response_validators_js_1.requireString)(body.id, "sessions.payerOpened.id"),
         idempotencyKey: (0, response_validators_js_1.requireNullableString)(body.idempotency_key, "sessions.payerOpened.idempotencyKey"),
@@ -302,12 +330,109 @@ function toPayerOpenedResult(response) {
         metadata: (0, response_validators_js_1.requireJsonObject)(body.metadata, "sessions.payerOpened.metadata"),
         payerContact: requireNullableContact(body.payer_contact, "sessions.payerOpened.payerContact"),
         payerDestinationUrl: (0, response_validators_js_1.requireNullableString)(body.payer_destination_url, "sessions.payerOpened.payerDestinationUrl"),
-        providerCheckoutSessionId: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_id, "sessions.payerOpened.providerCheckoutSessionId"),
+        presentationState,
+        providerCheckoutSessionId,
         providerCheckoutSessionPsp: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_psp, "sessions.payerOpened.providerCheckoutSessionPsp"),
         status,
         updatedAt: (0, response_validators_js_1.requireString)(body.updated_at, "sessions.payerOpened.updatedAt"),
     };
 }
+function optionalAcquisitionSummary(value, field) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const acquisition = (0, response_validators_js_1.requireJsonObject)(value, field);
+    return {
+        attemptNumber: (0, response_validators_js_1.requireInteger)(acquisition.attempt_number, `${field}.attemptNumber`),
+        checkoutUiMode: (0, response_validators_js_1.requireNullableString)(acquisition.checkout_ui_mode, `${field}.checkoutUiMode`),
+        id: (0, response_validators_js_1.requireString)(acquisition.id, `${field}.id`),
+        integrationPath: (0, response_validators_js_1.requireString)(acquisition.integration_path, `${field}.integrationPath`),
+        status: (0, response_validators_js_1.requireString)(acquisition.status, `${field}.status`),
+        statusReason: (0, response_validators_js_1.requireNullableString)(acquisition.status_reason, `${field}.statusReason`),
+    };
+}
+function optionalNullableString(value, field) {
+    return value === undefined ? null : (0, response_validators_js_1.requireNullableString)(value, field);
+}
+function proxySessionActionableNextStep(value, fallback) {
+    if (value === undefined) {
+        switch (fallback.presentationState) {
+            case "action_required":
+                return "merchant_action_required";
+            case "already_paid":
+                return "already_paid";
+            case "checkout_available":
+                return fallback.providerCheckoutSessionId === null
+                    ? "prepare_provider"
+                    : "continue_payment";
+            case "unavailable":
+                return "unavailable";
+        }
+    }
+    const step = (0, response_validators_js_1.requireString)(value, "sessions.actionableNextStep");
+    switch (step) {
+        case "already_paid":
+        case "continue_payment":
+        case "merchant_action_required":
+        case "prepare_provider":
+        case "unavailable":
+            return step;
+        default:
+            throw new Error("Proxy API response field sessions.actionableNextStep is unsupported.");
+    }
+}
+function proxySessionPresentationState(value, status) {
+    if (value === undefined) {
+        switch (requireProxySessionViewStatus(status)) {
+            case "payer_handoff_pending":
+            case "payer_opened":
+            case "payment_pending":
+                return "checkout_available";
+            case "paid":
+            case "provisionable":
+            case "provisioned":
+            case "provisioning_failed":
+                return "already_paid";
+            case "merchant_action_required":
+                return "action_required";
+            case "cancelled":
+            case "created":
+            case "expired":
+            case "failed":
+                return "unavailable";
+        }
+    }
+    const state = (0, response_validators_js_1.requireString)(value, "sessions.payerOpened.presentationState");
+    switch (state) {
+        case "action_required":
+        case "already_paid":
+        case "checkout_available":
+        case "unavailable":
+            return state;
+        default:
+            throw new Error("Proxy API response field sessions.payerOpened.presentationState is unsupported.");
+    }
+}
+function requireProxySessionViewStatus(value) {
+    const status = (0, response_validators_js_1.requireString)(value, "sessions.payerOpened.status");
+    switch (status) {
+        case "cancelled":
+        case "created":
+        case "expired":
+        case "failed":
+        case "merchant_action_required":
+        case "paid":
+        case "payer_handoff_pending":
+        case "payer_opened":
+        case "payment_pending":
+        case "provisionable":
+        case "provisioned":
+        case "provisioning_failed":
+            return status;
+        default:
+            throw new Error("Proxy API response field sessions.payerOpened.status is unsupported.");
+    }
+}
 function requireNullableContact(value, field) {
     if (value === null || value === undefined) {
         return null;

package/dist/cjs/version.d.cts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.8";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.8";
+export declare const proxyCheckoutServerSdkVersion = "0.1.0-prx-124.139.1";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.1.0-prx-124.139.1";

package/dist/cjs/version.d.ts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.8";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.8";
+export declare const proxyCheckoutServerSdkVersion = "0.1.0-prx-124.139.1";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.1.0-prx-124.139.1";

package/dist/cjs/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.proxyCheckoutServerSdkUserAgent = exports.proxyCheckoutServerSdkVersion = exports.proxyCheckoutServerSdkName = void 0;
 exports.proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-exports.proxyCheckoutServerSdkVersion = "0.0.8";
+exports.proxyCheckoutServerSdkVersion = "0.1.0-prx-124.139.1";
 exports.proxyCheckoutServerSdkUserAgent = `${exports.proxyCheckoutServerSdkName}/${exports.proxyCheckoutServerSdkVersion}`;

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

@@ -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;