@proxy-checkout/server-js 0.0.5 → 0.0.6

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/errors.d.cts

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

package/dist/cjs/errors.d.ts

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

package/dist/cjs/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";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.5";
+export declare const proxyCheckoutServerSdkVersion = "0.0.6";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.6";

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";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.5";
+export declare const proxyCheckoutServerSdkVersion = "0.0.6";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.6";

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";
+exports.proxyCheckoutServerSdkVersion = "0.0.6";
 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"> | undefined);
     /** Low-level: verify + construct the event without resolving lifecycle. */
     constructEvent(input: {
         body: Buffer | string;
@@ -86,4 +99,6 @@ export declare class ProxyWebhooksResource {
      * surface a 500 and Proxy retries.
      */
     handle(input: ProxyWebhookRequestInput, options: ProxyWebhookHandlerOptions): Promise<Response>;
+    private runResolvedHandler;
+    private requireSessionsResource;
 }

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"> | undefined);
     /** Low-level: verify + construct the event without resolving lifecycle. */
     constructEvent(input: {
         body: Buffer | string;
@@ -86,4 +99,6 @@ export declare class ProxyWebhooksResource {
      * surface a 500 and Proxy retries.
      */
     handle(input: ProxyWebhookRequestInput, options: ProxyWebhookHandlerOptions): Promise<Response>;
+    private runResolvedHandler;
+    private requireSessionsResource;
 }

package/dist/cjs/webhook-handler.js

@@ -10,13 +10,16 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProxyWebhooksResource = exports.PROXY_WEBHOOK_RETRY_AFTER_SECONDS = void 0;
+const errors_js_1 = require("./errors.js");
 const webhooks_js_1 = require("./webhooks.js");
 /** Seconds advertised in `Retry-After` when an event is already in flight. */
 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 +64,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.requireSessionsResource("mark provisioned").markProvisioned(resolved.session.id, {
+                    requestId: options.requestId,
+                });
+            }
         }
         catch (error) {
             if (store !== undefined) {
@@ -120,6 +128,36 @@ 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.requireSessionsResource("mark provisioning failed").markProvisioningFailed(resolved.session.id, {
+                errorCode: failure.errorCode,
+                errorMessage: failure.errorMessage,
+                metadata: failure.metadata,
+                requestId: options.requestId,
+            });
+            return true;
+        }
+    }
+    requireSessionsResource(operation) {
+        if (this.sessions) {
+            return this.sessions;
+        }
+        throw new errors_js_1.ProxyCheckoutValidationError(`ProxyWebhooksResource cannot ${operation} without a ProxySessionsResource. Construct webhooks via createProxyCheckoutServerClient or pass the sessions resource to new ProxyWebhooksResource(events, sessions).`, {
+            code: "webhook_sessions_resource_missing",
+        });
+    }
 }
 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/errors.d.ts

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

package/dist/esm/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";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.5";
+export declare const proxyCheckoutServerSdkVersion = "0.0.6";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.6";

package/dist/esm/version.js

@@ -1,3 +1,3 @@
 export const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export const proxyCheckoutServerSdkVersion = "0.0.5";
+export const proxyCheckoutServerSdkVersion = "0.0.6";
 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"> | undefined);
     /** Low-level: verify + construct the event without resolving lifecycle. */
     constructEvent(input: {
         body: Buffer | string;
@@ -86,4 +99,6 @@ export declare class ProxyWebhooksResource {
      * surface a 500 and Proxy retries.
      */
     handle(input: ProxyWebhookRequestInput, options: ProxyWebhookHandlerOptions): Promise<Response>;
+    private runResolvedHandler;
+    private requireSessionsResource;
 }

package/dist/esm/webhook-handler.js

@@ -7,13 +7,16 @@
  * verification, duplicate/in-flight handling, retryable responses, and
  * current-state retrieval so customer webhook routes stay tiny.
  */
+import { ProxyCheckoutValidationError } from "./errors.js";
 import { constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookSignatureVerificationError, } from "./webhooks.js";
 /** Seconds advertised in `Retry-After` when an event is already in flight. */
 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 +61,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.requireSessionsResource("mark provisioned").markProvisioned(resolved.session.id, {
+                    requestId: options.requestId,
+                });
+            }
         }
         catch (error) {
             if (store !== undefined) {
@@ -117,6 +125,36 @@ 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.requireSessionsResource("mark provisioning failed").markProvisioningFailed(resolved.session.id, {
+                errorCode: failure.errorCode,
+                errorMessage: failure.errorMessage,
+                metadata: failure.metadata,
+                requestId: options.requestId,
+            });
+            return true;
+        }
+    }
+    requireSessionsResource(operation) {
+        if (this.sessions) {
+            return this.sessions;
+        }
+        throw new ProxyCheckoutValidationError(`ProxyWebhooksResource cannot ${operation} without a ProxySessionsResource. Construct webhooks via createProxyCheckoutServerClient or pass the sessions resource to new ProxyWebhooksResource(events, sessions).`, {
+            code: "webhook_sessions_resource_missing",
+        });
+    }
 }
 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",
+  "version": "0.0.6",
   "devDependencies": {
     "@types/node": "^24.12.4",
     "@vitest/coverage-v8": "4.1.7",