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

package/dist/esm/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,21 @@ export interface ProxySessionCartResult {
     readonly cartVersion: number;
     readonly currency: string;
 }
-export interface RecordProviderBindingInput extends ProxyCheckoutServerRequestOptions {
+interface RecordProviderBindingBaseInput extends ProxyCheckoutServerRequestOptions {
     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 +208,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 +221,4 @@ export declare class ProxySessionCartResource {
     constructor(httpClient: ProxyCheckoutHttpClient);
     set(proxySessionId: string, input: SetProxySessionCartInput): Promise<ProxySessionCartResult>;
 }
+export {};

package/dist/esm/sessions.js

@@ -1,5 +1,6 @@
 import { parseProxyCart } from "./cart.js";
 import { assertCartBuyerReference } from "./consistency.js";
+import { ProxyCheckoutValidationError } from "./errors.js";
 import { requireInteger, requireJsonObject, requireNullableString, requireString, } from "./response-validators.js";
 export const proxyCheckoutServerEndpoints = [
     {
@@ -136,9 +137,16 @@ export 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 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 }),
             provider_checkout_session_id: input.providerCheckoutSessionId,
             psp: input.psp,
         }, { requestId: input.requestId });
@@ -255,14 +263,24 @@ function toProxySessionHandoff(response) {
 }
 function toMerchantProxySession(response) {
     const body = requireJsonObject(response, "sessions.retrieve");
+    const status = requireString(body.status, "sessions.retrieve.status");
+    const currentAcquisitionAttempt = optionalAcquisitionSummary(body.current_acquisition_attempt, "sessions.retrieve.currentAcquisitionAttempt");
+    const providerCheckoutSessionId = 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: requireInteger(body.amount_minor, "sessions.retrieve.amountMinor"),
         beneficiaryContact: requireNullableContact(body.beneficiary_contact, "sessions.retrieve.beneficiaryContact"),
         buyerReference: requireString(body.buyer_reference, "sessions.retrieve.buyerReference"),
         cartSnapshot: requireJsonObject(body.cart_snapshot, "sessions.retrieve.cartSnapshot"),
         cartVersion: requireInteger(body.cart_version, "sessions.retrieve.cartVersion"),
+        completedAcquisitionAttemptId: optionalNullableString(body.completed_acquisition_attempt_id, "sessions.retrieve.completedAcquisitionAttemptId"),
         createdAt: requireString(body.created_at, "sessions.retrieve.createdAt"),
         currency: requireString(body.currency, "sessions.retrieve.currency"),
+        currentAcquisitionAttempt,
         expiresAt: requireString(body.expires_at, "sessions.retrieve.expiresAt"),
         id: requireString(body.id, "sessions.retrieve.id"),
         idempotencyKey: requireNullableString(body.idempotency_key, "sessions.retrieve.idempotencyKey"),
@@ -270,26 +288,33 @@ function toMerchantProxySession(response) {
         metadata: requireJsonObject(body.metadata, "sessions.retrieve.metadata"),
         payerContact: requireNullableContact(body.payer_contact, "sessions.retrieve.payerContact"),
         payerDestinationUrl: requireNullableString(body.payer_destination_url, "sessions.retrieve.payerDestinationUrl"),
-        providerCheckoutSessionId: requireNullableString(body.provider_checkout_session_id, "sessions.retrieve.providerCheckoutSessionId"),
+        presentationState,
+        providerCheckoutSessionId,
         providerCheckoutSessionPsp: requireNullableString(body.provider_checkout_session_psp, "sessions.retrieve.providerCheckoutSessionPsp"),
-        status: requireString(body.status, "sessions.retrieve.status"),
+        status,
         updatedAt: requireString(body.updated_at, "sessions.retrieve.updatedAt"),
     };
 }
 function toPayerOpenedResult(response) {
     const body = requireJsonObject(response, "sessions.payerOpened");
-    const status = 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 = 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: requireInteger(body.amount_minor, "sessions.payerOpened.amountMinor"),
         beneficiaryContact: requireNullableContact(body.beneficiary_contact, "sessions.payerOpened.beneficiaryContact"),
         buyerReference: requireString(body.buyer_reference, "sessions.payerOpened.buyerReference"),
         cartSnapshot: requireJsonObject(body.cart_snapshot, "sessions.payerOpened.cartSnapshot"),
         cartVersion: requireInteger(body.cart_version, "sessions.payerOpened.cartVersion"),
+        completedAcquisitionAttemptId: optionalNullableString(body.completed_acquisition_attempt_id, "sessions.payerOpened.completedAcquisitionAttemptId"),
         createdAt: requireString(body.created_at, "sessions.payerOpened.createdAt"),
         currency: requireString(body.currency, "sessions.payerOpened.currency"),
+        currentAcquisitionAttempt,
         expiresAt: requireString(body.expires_at, "sessions.payerOpened.expiresAt"),
         id: requireString(body.id, "sessions.payerOpened.id"),
         idempotencyKey: requireNullableString(body.idempotency_key, "sessions.payerOpened.idempotencyKey"),
@@ -297,12 +322,109 @@ function toPayerOpenedResult(response) {
         metadata: requireJsonObject(body.metadata, "sessions.payerOpened.metadata"),
         payerContact: requireNullableContact(body.payer_contact, "sessions.payerOpened.payerContact"),
         payerDestinationUrl: requireNullableString(body.payer_destination_url, "sessions.payerOpened.payerDestinationUrl"),
-        providerCheckoutSessionId: requireNullableString(body.provider_checkout_session_id, "sessions.payerOpened.providerCheckoutSessionId"),
+        presentationState,
+        providerCheckoutSessionId,
         providerCheckoutSessionPsp: requireNullableString(body.provider_checkout_session_psp, "sessions.payerOpened.providerCheckoutSessionPsp"),
         status,
         updatedAt: requireString(body.updated_at, "sessions.payerOpened.updatedAt"),
     };
 }
+function optionalAcquisitionSummary(value, field) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const acquisition = requireJsonObject(value, field);
+    return {
+        attemptNumber: requireInteger(acquisition.attempt_number, `${field}.attemptNumber`),
+        checkoutUiMode: requireNullableString(acquisition.checkout_ui_mode, `${field}.checkoutUiMode`),
+        id: requireString(acquisition.id, `${field}.id`),
+        integrationPath: requireString(acquisition.integration_path, `${field}.integrationPath`),
+        status: requireString(acquisition.status, `${field}.status`),
+        statusReason: requireNullableString(acquisition.status_reason, `${field}.statusReason`),
+    };
+}
+function optionalNullableString(value, field) {
+    return value === undefined ? null : 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 = 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 = 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 = 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/esm/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.137.1";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.1.0-prx-124.137.1";

package/dist/esm/version.js

@@ -1,3 +1,3 @@
 export const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export const proxyCheckoutServerSdkVersion = "0.0.8";
+export const proxyCheckoutServerSdkVersion = "0.1.0-prx-124.137.1";
 export const proxyCheckoutServerSdkUserAgent = `${proxyCheckoutServerSdkName}/${proxyCheckoutServerSdkVersion}`;

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

@@ -7,18 +7,38 @@
  */
 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 providerAcquisitionPrepared: "provider_acquisition.prepared";
+    readonly providerAcquisitionProcessing: "provider_acquisition.processing";
+    readonly providerAcquisitionReconciliationRequired: "provider_acquisition.reconciliation_required";
+    readonly providerAcquisitionRequiresAction: "provider_acquisition.requires_action";
     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 +47,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/esm/webhook-events.js

@@ -7,18 +7,38 @@
  */
 export const 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",
+    providerAcquisitionPrepared: "provider_acquisition.prepared",
+    providerAcquisitionProcessing: "provider_acquisition.processing",
+    providerAcquisitionReconciliationRequired: "provider_acquisition.reconciliation_required",
+    providerAcquisitionRequiresAction: "provider_acquisition.requires_action",
     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([
     PROXY_WEBHOOK_EVENT_TYPES.sessionCancelled,
@@ -31,14 +51,38 @@ const SESSION_EVENT_TYPES = new Set([
 const SUBSCRIPTION_EVENT_TYPES = new Set([
     PROXY_WEBHOOK_EVENT_TYPES.subscriptionCancelScheduled,
     PROXY_WEBHOOK_EVENT_TYPES.subscriptionCancelled,
+    PROXY_WEBHOOK_EVENT_TYPES.subscriptionChanged,
+    PROXY_WEBHOOK_EVENT_TYPES.subscriptionConfigurationActionRequired,
     PROXY_WEBHOOK_EVENT_TYPES.subscriptionPaymentFailed,
     PROXY_WEBHOOK_EVENT_TYPES.subscriptionRenewed,
+    PROXY_WEBHOOK_EVENT_TYPES.subscriptionTrialEnding,
 ]);
 const PAYMENT_ATTEMPT_EVENT_TYPES = new Set([
     PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptCancelled,
+    PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptDisputeLost,
+    PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptDisputeWon,
+    PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptDisputed,
     PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptFailed,
+    PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptPartiallyRefunded,
+    PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptReconciliationRequired,
+    PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptRefunded,
     PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptSucceeded,
 ]);
+const PROVIDER_ACQUISITION_EVENT_TYPES = new Set([
+    PROXY_WEBHOOK_EVENT_TYPES.providerAcquisitionCancelled,
+    PROXY_WEBHOOK_EVENT_TYPES.providerAcquisitionExpired,
+    PROXY_WEBHOOK_EVENT_TYPES.providerAcquisitionFailed,
+    PROXY_WEBHOOK_EVENT_TYPES.providerAcquisitionPrepared,
+    PROXY_WEBHOOK_EVENT_TYPES.providerAcquisitionProcessing,
+    PROXY_WEBHOOK_EVENT_TYPES.providerAcquisitionReconciliationRequired,
+    PROXY_WEBHOOK_EVENT_TYPES.providerAcquisitionRequiresAction,
+]);
+const SHOPIFY_EVENT_TYPES = new Set([
+    PROXY_WEBHOOK_EVENT_TYPES.shopifyFulfillmentObserved,
+    PROXY_WEBHOOK_EVENT_TYPES.shopifyRefundObserved,
+    PROXY_WEBHOOK_EVENT_TYPES.shopifySubscriptionPaymentObserved,
+    PROXY_WEBHOOK_EVENT_TYPES.shopifySubscriptionRefundObserved,
+]);
 /** True for `proxy_session.*` events. */
 export function isProxySessionEvent(eventType) {
     return SESSION_EVENT_TYPES.has(eventType);
@@ -51,3 +95,11 @@ export function isProxySubscriptionEvent(eventType) {
 export function isProxyPaymentAttemptEvent(eventType) {
     return PAYMENT_ATTEMPT_EVENT_TYPES.has(eventType);
 }
+/** True for non-granting `provider_acquisition.*` progress wakeups. */
+export function isProxyProviderAcquisitionEvent(eventType) {
+    return PROVIDER_ACQUISITION_EVENT_TYPES.has(eventType);
+}
+/** True for observation-only `shopify.*` commerce events. */
+export function isProxyShopifyEvent(eventType) {
+    return SHOPIFY_EVENT_TYPES.has(eventType);
+}

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

@@ -194,6 +194,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/package.json

@@ -7,7 +7,7 @@
   "sideEffects": false,
   "type": "module",
   "types": "./dist/esm/index.d.ts",
-  "version": "0.0.8",
+  "version": "0.1.0-prx-124.137.1",
   "devDependencies": {
     "@types/node": "^24.12.4",
     "@vitest/coverage-v8": "4.1.7",