@proxy-checkout/server-js 0.0.5-prx-89.40.1 → 0.0.5-prx-93.45.1

package/dist/cjs/client.js

@@ -31,7 +31,7 @@ class ProxyCheckoutServerClient {
         });
         this.subscriptions = new subscriptions_js_1.ProxySubscriptionsResource(httpClient, this.sessions);
         this.events = new events_js_1.ProxyEventsResource(this.sessions, this.subscriptions);
-        this.webhooks = new webhook_handler_js_1.ProxyWebhooksResource(this.events);
+        this.webhooks = new webhook_handler_js_1.ProxyWebhooksResource(this.events, this.sessions);
         this.webhookEndpoints = new webhooks_js_1.ProxyWebhookEndpointsResource(httpClient);
     }
 }

package/dist/cjs/index.d.cts

@@ -4,10 +4,10 @@ export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./c
 export { 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 { 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 MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.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 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 { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
+export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookProvisioningFailure, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
 export { type ConstructProxyWebhookEventInput, type CreateWebhookEndpointInput, constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, type ProxyWebhookEvent, ProxyWebhookSignatureVerificationError, proxyCheckoutWebhookEndpointEndpoints, type RotateWebhookEndpointSecretInput, type UpdateWebhookEndpointInput, type VerifyProxyWebhookSignatureInput, verifyProxyWebhookSignature, type WebhookEndpoint, type WebhookEndpointSecretResult, } from "./webhooks.js";

package/dist/cjs/index.d.ts

@@ -4,10 +4,10 @@ export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./c
 export { 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 { 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 MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.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 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 { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
+export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookProvisioningFailure, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
 export { type ConstructProxyWebhookEventInput, type CreateWebhookEndpointInput, constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, type ProxyWebhookEvent, ProxyWebhookSignatureVerificationError, proxyCheckoutWebhookEndpointEndpoints, type RotateWebhookEndpointSecretInput, type UpdateWebhookEndpointInput, type VerifyProxyWebhookSignatureInput, verifyProxyWebhookSignature, type WebhookEndpoint, type WebhookEndpointSecretResult, } from "./webhooks.js";

package/dist/cjs/sessions.d.cts

@@ -86,6 +86,20 @@ export interface ProxySessionProviderBinding {
     readonly psp: string;
     readonly updatedAt: string;
 }
+export interface MarkProxySessionProvisionedInput extends ProxyCheckoutServerRequestOptions {
+    readonly fulfillmentReference?: string;
+    readonly metadata?: JsonObject;
+}
+export interface MarkProxySessionProvisioningFailedInput extends ProxyCheckoutServerRequestOptions {
+    readonly errorCode?: string;
+    readonly errorMessage: string;
+    readonly metadata?: JsonObject;
+}
+export interface ProxySessionProvisioningAcknowledgement {
+    readonly proxySessionId: string;
+    readonly status: "provisioned" | "provisioning_failed";
+    readonly updatedAt: string;
+}
 export declare const proxyCheckoutServerEndpoints: readonly [{
     readonly method: "POST";
     readonly operation: "sessions.create";
@@ -114,6 +128,14 @@ export declare const proxyCheckoutServerEndpoints: readonly [{
     readonly method: "POST";
     readonly operation: "sessions.providerBindings.create";
     readonly path: "/proxy_sessions/:id/provider_bindings";
+}, {
+    readonly method: "POST";
+    readonly operation: "sessions.markProvisioned";
+    readonly path: "/proxy_sessions/:id/provisioned";
+}, {
+    readonly method: "POST";
+    readonly operation: "sessions.markProvisioningFailed";
+    readonly path: "/proxy_sessions/:id/provisioning_failed";
 }];
 export declare class ProxySessionsResource {
     private readonly httpClient;
@@ -146,6 +168,8 @@ export declare class ProxySessionsResource {
      * the session is already bound to a different one.
      */
     recordProviderBinding(proxySessionId: string, input: RecordProviderBindingInput): Promise<ProxySessionProviderBinding>;
+    markProvisioned(proxySessionId: string, input?: MarkProxySessionProvisionedInput): Promise<ProxySessionProvisioningAcknowledgement>;
+    markProvisioningFailed(proxySessionId: string, input: MarkProxySessionProvisioningFailedInput): Promise<ProxySessionProvisioningAcknowledgement>;
 }
 export declare class ProxySessionCartResource {
     private readonly httpClient;

package/dist/cjs/sessions.d.ts

@@ -86,6 +86,20 @@ export interface ProxySessionProviderBinding {
     readonly psp: string;
     readonly updatedAt: string;
 }
+export interface MarkProxySessionProvisionedInput extends ProxyCheckoutServerRequestOptions {
+    readonly fulfillmentReference?: string;
+    readonly metadata?: JsonObject;
+}
+export interface MarkProxySessionProvisioningFailedInput extends ProxyCheckoutServerRequestOptions {
+    readonly errorCode?: string;
+    readonly errorMessage: string;
+    readonly metadata?: JsonObject;
+}
+export interface ProxySessionProvisioningAcknowledgement {
+    readonly proxySessionId: string;
+    readonly status: "provisioned" | "provisioning_failed";
+    readonly updatedAt: string;
+}
 export declare const proxyCheckoutServerEndpoints: readonly [{
     readonly method: "POST";
     readonly operation: "sessions.create";
@@ -114,6 +128,14 @@ export declare const proxyCheckoutServerEndpoints: readonly [{
     readonly method: "POST";
     readonly operation: "sessions.providerBindings.create";
     readonly path: "/proxy_sessions/:id/provider_bindings";
+}, {
+    readonly method: "POST";
+    readonly operation: "sessions.markProvisioned";
+    readonly path: "/proxy_sessions/:id/provisioned";
+}, {
+    readonly method: "POST";
+    readonly operation: "sessions.markProvisioningFailed";
+    readonly path: "/proxy_sessions/:id/provisioning_failed";
 }];
 export declare class ProxySessionsResource {
     private readonly httpClient;
@@ -146,6 +168,8 @@ export declare class ProxySessionsResource {
      * the session is already bound to a different one.
      */
     recordProviderBinding(proxySessionId: string, input: RecordProviderBindingInput): Promise<ProxySessionProviderBinding>;
+    markProvisioned(proxySessionId: string, input?: MarkProxySessionProvisionedInput): Promise<ProxySessionProvisioningAcknowledgement>;
+    markProvisioningFailed(proxySessionId: string, input: MarkProxySessionProvisioningFailedInput): Promise<ProxySessionProvisioningAcknowledgement>;
 }
 export declare class ProxySessionCartResource {
     private readonly httpClient;

package/dist/cjs/sessions.js

@@ -40,6 +40,16 @@ exports.proxyCheckoutServerEndpoints = [
         operation: "sessions.providerBindings.create",
         path: "/proxy_sessions/:id/provider_bindings",
     },
+    {
+        method: "POST",
+        operation: "sessions.markProvisioned",
+        path: "/proxy_sessions/:id/provisioned",
+    },
+    {
+        method: "POST",
+        operation: "sessions.markProvisioningFailed",
+        path: "/proxy_sessions/:id/provisioning_failed",
+    },
 ];
 class ProxySessionsResource {
     httpClient;
@@ -140,6 +150,21 @@ class ProxySessionsResource {
             updatedAt: (0, response_validators_js_1.requireString)(body.updated_at, "sessions.providerBindings.create.updatedAt"),
         };
     }
+    async markProvisioned(proxySessionId, input = {}) {
+        const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/provisioned`, removeUndefinedValues({
+            fulfillment_reference: input.fulfillmentReference,
+            metadata: input.metadata,
+        }), { requestId: input.requestId });
+        return toProvisioningAcknowledgement(response, "sessions.markProvisioned");
+    }
+    async markProvisioningFailed(proxySessionId, input) {
+        const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/provisioning_failed`, removeUndefinedValues({
+            error_code: input.errorCode,
+            error_message: input.errorMessage,
+            metadata: input.metadata,
+        }), { requestId: input.requestId });
+        return toProvisioningAcknowledgement(response, "sessions.markProvisioningFailed");
+    }
 }
 exports.ProxySessionsResource = ProxySessionsResource;
 class ProxySessionCartResource {
@@ -285,6 +310,18 @@ function requirePayerHandoffStatus(value) {
     }
     throw new Error("Proxy API response field sessions.payerHandoff.status is unsupported.");
 }
+function toProvisioningAcknowledgement(response, operation) {
+    const body = (0, response_validators_js_1.requireJsonObject)(response, operation);
+    const status = (0, response_validators_js_1.requireString)(body.status, `${operation}.status`);
+    if (status !== "provisioned" && status !== "provisioning_failed") {
+        throw new Error(`Proxy API response field ${operation}.status is unsupported.`);
+    }
+    return {
+        proxySessionId: (0, response_validators_js_1.requireString)(body.proxy_session_id, `${operation}.proxySessionId`),
+        status,
+        updatedAt: (0, response_validators_js_1.requireString)(body.updated_at, `${operation}.updatedAt`),
+    };
+}
 function buildHandoffUrl({ payHost, proxySessionId, publishableKey, }) {
     const url = new URL(`${normalizePayHost(payHost)}/s/${encodeURIComponent(proxySessionId)}`);
     url.searchParams.set("pk", publishableKey);

package/dist/cjs/version.d.cts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.5-prx-89.40.1";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.5-prx-89.40.1";
+export declare const proxyCheckoutServerSdkVersion = "0.0.5-prx-93.45.1";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.5-prx-93.45.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.5-prx-89.40.1";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.5-prx-89.40.1";
+export declare const proxyCheckoutServerSdkVersion = "0.0.5-prx-93.45.1";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.5-prx-93.45.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.5-prx-89.40.1";
+exports.proxyCheckoutServerSdkVersion = "0.0.5-prx-93.45.1";
 exports.proxyCheckoutServerSdkUserAgent = `${exports.proxyCheckoutServerSdkName}/${exports.proxyCheckoutServerSdkVersion}`;

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

@@ -8,6 +8,8 @@
  * current-state retrieval so customer webhook routes stay tiny.
  */
 import type { ProxyEventsResource, ResolvedProxyEvent, ResolvedProxyEventKind } from "./events.js";
+import type { ProxySessionsResource } from "./sessions.js";
+import type { JsonObject } from "./types.js";
 import { type ProxyWebhookEvent } from "./webhooks.js";
 /** Seconds advertised in `Retry-After` when an event is already in flight. */
 export declare const PROXY_WEBHOOK_RETRY_AFTER_SECONDS = 30;
@@ -33,6 +35,11 @@ export interface ProxyWebhookStore {
     /** Mark a claimed event processed (idempotency commit). */
     markProcessed(eventId: string, record: ProxyWebhookProcessRecord): Promise<void> | void;
 }
+export interface ProxyWebhookProvisioningFailure {
+    readonly errorCode?: string;
+    readonly errorMessage: string;
+    readonly metadata?: JsonObject;
+}
 export interface ProxyWebhookPayloadInput {
     readonly body: Buffer | string;
     readonly signature?: string | null;
@@ -44,6 +51,11 @@ export interface ProxyWebhookPayloadInput {
  */
 export type ProxyWebhookRequestInput = ProxyWebhookPayloadInput | Request;
 export interface ProxyWebhookHandlerOptions {
+    /**
+     * Optional classifier for non-retryable initial-provision failures. Return a
+     * failure payload only after the merchant knows retrying cannot grant access.
+     */
+    readonly classifyProvisioningFailure?: (error: unknown, resolved: ResolvedProxyEvent) => Promise<ProxyWebhookProvisioningFailure | null | undefined> | ProxyWebhookProvisioningFailure | null | undefined;
     /** Merchant entitlement callback, invoked once per claimed event after current-state resolution. */
     readonly onResolved: (resolved: ResolvedProxyEvent) => Promise<void> | void;
     /** Optional request id forwarded to the current-state retrieval calls. */
@@ -64,7 +76,8 @@ export interface ProxyWebhookProcessResult {
 }
 export declare class ProxyWebhooksResource {
     private readonly events;
-    constructor(events: ProxyEventsResource);
+    private readonly sessions;
+    constructor(events: ProxyEventsResource, sessions: Pick<ProxySessionsResource, "markProvisioned" | "markProvisioningFailed">);
     /** Low-level: verify + construct the event without resolving lifecycle. */
     constructEvent(input: {
         body: Buffer | string;
@@ -86,4 +99,5 @@ export declare class ProxyWebhooksResource {
      * surface a 500 and Proxy retries.
      */
     handle(input: ProxyWebhookRequestInput, options: ProxyWebhookHandlerOptions): Promise<Response>;
+    private runResolvedHandler;
 }

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

@@ -8,6 +8,8 @@
  * current-state retrieval so customer webhook routes stay tiny.
  */
 import type { ProxyEventsResource, ResolvedProxyEvent, ResolvedProxyEventKind } from "./events.js";
+import type { ProxySessionsResource } from "./sessions.js";
+import type { JsonObject } from "./types.js";
 import { type ProxyWebhookEvent } from "./webhooks.js";
 /** Seconds advertised in `Retry-After` when an event is already in flight. */
 export declare const PROXY_WEBHOOK_RETRY_AFTER_SECONDS = 30;
@@ -33,6 +35,11 @@ export interface ProxyWebhookStore {
     /** Mark a claimed event processed (idempotency commit). */
     markProcessed(eventId: string, record: ProxyWebhookProcessRecord): Promise<void> | void;
 }
+export interface ProxyWebhookProvisioningFailure {
+    readonly errorCode?: string;
+    readonly errorMessage: string;
+    readonly metadata?: JsonObject;
+}
 export interface ProxyWebhookPayloadInput {
     readonly body: Buffer | string;
     readonly signature?: string | null;
@@ -44,6 +51,11 @@ export interface ProxyWebhookPayloadInput {
  */
 export type ProxyWebhookRequestInput = ProxyWebhookPayloadInput | Request;
 export interface ProxyWebhookHandlerOptions {
+    /**
+     * Optional classifier for non-retryable initial-provision failures. Return a
+     * failure payload only after the merchant knows retrying cannot grant access.
+     */
+    readonly classifyProvisioningFailure?: (error: unknown, resolved: ResolvedProxyEvent) => Promise<ProxyWebhookProvisioningFailure | null | undefined> | ProxyWebhookProvisioningFailure | null | undefined;
     /** Merchant entitlement callback, invoked once per claimed event after current-state resolution. */
     readonly onResolved: (resolved: ResolvedProxyEvent) => Promise<void> | void;
     /** Optional request id forwarded to the current-state retrieval calls. */
@@ -64,7 +76,8 @@ export interface ProxyWebhookProcessResult {
 }
 export declare class ProxyWebhooksResource {
     private readonly events;
-    constructor(events: ProxyEventsResource);
+    private readonly sessions;
+    constructor(events: ProxyEventsResource, sessions: Pick<ProxySessionsResource, "markProvisioned" | "markProvisioningFailed">);
     /** Low-level: verify + construct the event without resolving lifecycle. */
     constructEvent(input: {
         body: Buffer | string;
@@ -86,4 +99,5 @@ export declare class ProxyWebhooksResource {
      * surface a 500 and Proxy retries.
      */
     handle(input: ProxyWebhookRequestInput, options: ProxyWebhookHandlerOptions): Promise<Response>;
+    private runResolvedHandler;
 }

package/dist/cjs/webhook-handler.js

@@ -15,8 +15,10 @@ const webhooks_js_1 = require("./webhooks.js");
 exports.PROXY_WEBHOOK_RETRY_AFTER_SECONDS = 30;
 class ProxyWebhooksResource {
     events;
-    constructor(events) {
+    sessions;
+    constructor(events, sessions) {
         this.events = events;
+        this.sessions = sessions;
     }
     /** Low-level: verify + construct the event without resolving lifecycle. */
     constructEvent(input) {
@@ -61,7 +63,12 @@ class ProxyWebhooksResource {
         let resolved;
         try {
             resolved = await this.events.resolveCurrentState(event, { requestId: options.requestId });
-            await options.onResolved(resolved);
+            const provisioningFailed = await this.runResolvedHandler(resolved, options);
+            if (!provisioningFailed && resolved.kind === "initial_provision") {
+                await this.sessions.markProvisioned(resolved.session.id, {
+                    requestId: options.requestId,
+                });
+            }
         }
         catch (error) {
             if (store !== undefined) {
@@ -120,6 +127,28 @@ class ProxyWebhooksResource {
         }
         return toWebhookResponse(result);
     }
+    async runResolvedHandler(resolved, options) {
+        try {
+            await options.onResolved(resolved);
+            return false;
+        }
+        catch (error) {
+            if (resolved.kind !== "initial_provision" || !options.classifyProvisioningFailure) {
+                throw error;
+            }
+            const failure = await options.classifyProvisioningFailure(error, resolved);
+            if (!failure) {
+                throw error;
+            }
+            await this.sessions.markProvisioningFailed(resolved.session.id, {
+                errorCode: failure.errorCode,
+                errorMessage: failure.errorMessage,
+                metadata: failure.metadata,
+                requestId: options.requestId,
+            });
+            return true;
+        }
+    }
 }
 exports.ProxyWebhooksResource = ProxyWebhooksResource;
 function toWebhookResponse(result) {

package/dist/esm/client.js

@@ -27,7 +27,7 @@ export class ProxyCheckoutServerClient {
         });
         this.subscriptions = new ProxySubscriptionsResource(httpClient, this.sessions);
         this.events = new ProxyEventsResource(this.sessions, this.subscriptions);
-        this.webhooks = new ProxyWebhooksResource(this.events);
+        this.webhooks = new ProxyWebhooksResource(this.events, this.sessions);
         this.webhookEndpoints = new ProxyWebhookEndpointsResource(httpClient);
     }
 }

package/dist/esm/index.d.ts

@@ -4,10 +4,10 @@ export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./c
 export { 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 { 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 MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.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 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 { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
+export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookProvisioningFailure, 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/sessions.d.ts

@@ -86,6 +86,20 @@ export interface ProxySessionProviderBinding {
     readonly psp: string;
     readonly updatedAt: string;
 }
+export interface MarkProxySessionProvisionedInput extends ProxyCheckoutServerRequestOptions {
+    readonly fulfillmentReference?: string;
+    readonly metadata?: JsonObject;
+}
+export interface MarkProxySessionProvisioningFailedInput extends ProxyCheckoutServerRequestOptions {
+    readonly errorCode?: string;
+    readonly errorMessage: string;
+    readonly metadata?: JsonObject;
+}
+export interface ProxySessionProvisioningAcknowledgement {
+    readonly proxySessionId: string;
+    readonly status: "provisioned" | "provisioning_failed";
+    readonly updatedAt: string;
+}
 export declare const proxyCheckoutServerEndpoints: readonly [{
     readonly method: "POST";
     readonly operation: "sessions.create";
@@ -114,6 +128,14 @@ export declare const proxyCheckoutServerEndpoints: readonly [{
     readonly method: "POST";
     readonly operation: "sessions.providerBindings.create";
     readonly path: "/proxy_sessions/:id/provider_bindings";
+}, {
+    readonly method: "POST";
+    readonly operation: "sessions.markProvisioned";
+    readonly path: "/proxy_sessions/:id/provisioned";
+}, {
+    readonly method: "POST";
+    readonly operation: "sessions.markProvisioningFailed";
+    readonly path: "/proxy_sessions/:id/provisioning_failed";
 }];
 export declare class ProxySessionsResource {
     private readonly httpClient;
@@ -146,6 +168,8 @@ export declare class ProxySessionsResource {
      * the session is already bound to a different one.
      */
     recordProviderBinding(proxySessionId: string, input: RecordProviderBindingInput): Promise<ProxySessionProviderBinding>;
+    markProvisioned(proxySessionId: string, input?: MarkProxySessionProvisionedInput): Promise<ProxySessionProvisioningAcknowledgement>;
+    markProvisioningFailed(proxySessionId: string, input: MarkProxySessionProvisioningFailedInput): Promise<ProxySessionProvisioningAcknowledgement>;
 }
 export declare class ProxySessionCartResource {
     private readonly httpClient;

package/dist/esm/sessions.js

@@ -37,6 +37,16 @@ export const proxyCheckoutServerEndpoints = [
         operation: "sessions.providerBindings.create",
         path: "/proxy_sessions/:id/provider_bindings",
     },
+    {
+        method: "POST",
+        operation: "sessions.markProvisioned",
+        path: "/proxy_sessions/:id/provisioned",
+    },
+    {
+        method: "POST",
+        operation: "sessions.markProvisioningFailed",
+        path: "/proxy_sessions/:id/provisioning_failed",
+    },
 ];
 export class ProxySessionsResource {
     httpClient;
@@ -137,6 +147,21 @@ export class ProxySessionsResource {
             updatedAt: requireString(body.updated_at, "sessions.providerBindings.create.updatedAt"),
         };
     }
+    async markProvisioned(proxySessionId, input = {}) {
+        const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/provisioned`, removeUndefinedValues({
+            fulfillment_reference: input.fulfillmentReference,
+            metadata: input.metadata,
+        }), { requestId: input.requestId });
+        return toProvisioningAcknowledgement(response, "sessions.markProvisioned");
+    }
+    async markProvisioningFailed(proxySessionId, input) {
+        const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/provisioning_failed`, removeUndefinedValues({
+            error_code: input.errorCode,
+            error_message: input.errorMessage,
+            metadata: input.metadata,
+        }), { requestId: input.requestId });
+        return toProvisioningAcknowledgement(response, "sessions.markProvisioningFailed");
+    }
 }
 export class ProxySessionCartResource {
     httpClient;
@@ -280,6 +305,18 @@ function requirePayerHandoffStatus(value) {
     }
     throw new Error("Proxy API response field sessions.payerHandoff.status is unsupported.");
 }
+function toProvisioningAcknowledgement(response, operation) {
+    const body = requireJsonObject(response, operation);
+    const status = requireString(body.status, `${operation}.status`);
+    if (status !== "provisioned" && status !== "provisioning_failed") {
+        throw new Error(`Proxy API response field ${operation}.status is unsupported.`);
+    }
+    return {
+        proxySessionId: requireString(body.proxy_session_id, `${operation}.proxySessionId`),
+        status,
+        updatedAt: requireString(body.updated_at, `${operation}.updatedAt`),
+    };
+}
 function buildHandoffUrl({ payHost, proxySessionId, publishableKey, }) {
     const url = new URL(`${normalizePayHost(payHost)}/s/${encodeURIComponent(proxySessionId)}`);
     url.searchParams.set("pk", publishableKey);

package/dist/esm/version.d.ts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.5-prx-89.40.1";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.5-prx-89.40.1";
+export declare const proxyCheckoutServerSdkVersion = "0.0.5-prx-93.45.1";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.5-prx-93.45.1";

package/dist/esm/version.js

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

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

@@ -8,6 +8,8 @@
  * current-state retrieval so customer webhook routes stay tiny.
  */
 import type { ProxyEventsResource, ResolvedProxyEvent, ResolvedProxyEventKind } from "./events.js";
+import type { ProxySessionsResource } from "./sessions.js";
+import type { JsonObject } from "./types.js";
 import { type ProxyWebhookEvent } from "./webhooks.js";
 /** Seconds advertised in `Retry-After` when an event is already in flight. */
 export declare const PROXY_WEBHOOK_RETRY_AFTER_SECONDS = 30;
@@ -33,6 +35,11 @@ export interface ProxyWebhookStore {
     /** Mark a claimed event processed (idempotency commit). */
     markProcessed(eventId: string, record: ProxyWebhookProcessRecord): Promise<void> | void;
 }
+export interface ProxyWebhookProvisioningFailure {
+    readonly errorCode?: string;
+    readonly errorMessage: string;
+    readonly metadata?: JsonObject;
+}
 export interface ProxyWebhookPayloadInput {
     readonly body: Buffer | string;
     readonly signature?: string | null;
@@ -44,6 +51,11 @@ export interface ProxyWebhookPayloadInput {
  */
 export type ProxyWebhookRequestInput = ProxyWebhookPayloadInput | Request;
 export interface ProxyWebhookHandlerOptions {
+    /**
+     * Optional classifier for non-retryable initial-provision failures. Return a
+     * failure payload only after the merchant knows retrying cannot grant access.
+     */
+    readonly classifyProvisioningFailure?: (error: unknown, resolved: ResolvedProxyEvent) => Promise<ProxyWebhookProvisioningFailure | null | undefined> | ProxyWebhookProvisioningFailure | null | undefined;
     /** Merchant entitlement callback, invoked once per claimed event after current-state resolution. */
     readonly onResolved: (resolved: ResolvedProxyEvent) => Promise<void> | void;
     /** Optional request id forwarded to the current-state retrieval calls. */
@@ -64,7 +76,8 @@ export interface ProxyWebhookProcessResult {
 }
 export declare class ProxyWebhooksResource {
     private readonly events;
-    constructor(events: ProxyEventsResource);
+    private readonly sessions;
+    constructor(events: ProxyEventsResource, sessions: Pick<ProxySessionsResource, "markProvisioned" | "markProvisioningFailed">);
     /** Low-level: verify + construct the event without resolving lifecycle. */
     constructEvent(input: {
         body: Buffer | string;
@@ -86,4 +99,5 @@ export declare class ProxyWebhooksResource {
      * surface a 500 and Proxy retries.
      */
     handle(input: ProxyWebhookRequestInput, options: ProxyWebhookHandlerOptions): Promise<Response>;
+    private runResolvedHandler;
 }

package/dist/esm/webhook-handler.js

@@ -12,8 +12,10 @@ import { constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookSignatu
 export const PROXY_WEBHOOK_RETRY_AFTER_SECONDS = 30;
 export class ProxyWebhooksResource {
     events;
-    constructor(events) {
+    sessions;
+    constructor(events, sessions) {
         this.events = events;
+        this.sessions = sessions;
     }
     /** Low-level: verify + construct the event without resolving lifecycle. */
     constructEvent(input) {
@@ -58,7 +60,12 @@ export class ProxyWebhooksResource {
         let resolved;
         try {
             resolved = await this.events.resolveCurrentState(event, { requestId: options.requestId });
-            await options.onResolved(resolved);
+            const provisioningFailed = await this.runResolvedHandler(resolved, options);
+            if (!provisioningFailed && resolved.kind === "initial_provision") {
+                await this.sessions.markProvisioned(resolved.session.id, {
+                    requestId: options.requestId,
+                });
+            }
         }
         catch (error) {
             if (store !== undefined) {
@@ -117,6 +124,28 @@ export class ProxyWebhooksResource {
         }
         return toWebhookResponse(result);
     }
+    async runResolvedHandler(resolved, options) {
+        try {
+            await options.onResolved(resolved);
+            return false;
+        }
+        catch (error) {
+            if (resolved.kind !== "initial_provision" || !options.classifyProvisioningFailure) {
+                throw error;
+            }
+            const failure = await options.classifyProvisioningFailure(error, resolved);
+            if (!failure) {
+                throw error;
+            }
+            await this.sessions.markProvisioningFailed(resolved.session.id, {
+                errorCode: failure.errorCode,
+                errorMessage: failure.errorMessage,
+                metadata: failure.metadata,
+                requestId: options.requestId,
+            });
+            return true;
+        }
+    }
 }
 function toWebhookResponse(result) {
     const headers = { "content-type": "application/json" };

package/package.json

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