@proxy-checkout/server-js 0.0.3 → 0.0.4-pr-76.13.1

package/dist/cart.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Typed cart-snapshot validation.
+ *
+ * The cart snapshot is merchant-defined and opaque to Proxy, so the SDK keeps
+ * the shape app-owned but standardizes the parse step: pass a zod-style schema
+ * (or a plain validator function) and get a typed cart or a structured error.
+ */
+/** A zod-style schema (`{ parse }`) or a plain validator function. */
+export type ProxyCartValidator<TCart> = {
+    parse: (value: unknown) => TCart;
+} | ((value: unknown) => TCart);
+/** Run a cart snapshot through a validator, wrapping failures in a structured SDK error. */
+export declare function parseProxyCart<TCart>(cartSnapshot: unknown, validator: ProxyCartValidator<TCart>): TCart;
+/** Optional extraction of a buyer reference embedded in the typed cart, for consistency checks. */
+export interface ProxyCartParseOptions<TCart> {
+    readonly getBuyerReference?: (cart: TCart) => string | null | undefined;
+}

package/dist/cart.js

@@ -0,0 +1,23 @@
+/**
+ * Typed cart-snapshot validation.
+ *
+ * The cart snapshot is merchant-defined and opaque to Proxy, so the SDK keeps
+ * the shape app-owned but standardizes the parse step: pass a zod-style schema
+ * (or a plain validator function) and get a typed cart or a structured error.
+ */
+import { ProxyCheckoutValidationError } from "./errors.js";
+/** Run a cart snapshot through a validator, wrapping failures in a structured SDK error. */
+export function parseProxyCart(cartSnapshot, validator) {
+    try {
+        return typeof validator === "function"
+            ? validator(cartSnapshot)
+            : validator.parse(cartSnapshot);
+    }
+    catch (cause) {
+        throw new ProxyCheckoutValidationError("Proxy cart snapshot failed validation.", {
+            cause,
+            code: "cart_invalid",
+            field: "cart_snapshot",
+        });
+    }
+}

package/dist/client.d.ts

@@ -1,11 +1,18 @@
+import { ProxyEventsResource } from "./events.js";
 import { ProxySessionsResource } from "./sessions.js";
 import { ProxySubscriptionsResource } from "./subscriptions.js";
 import type { ProxyCheckoutServerClientOptions } from "./types.js";
+import { ProxyWebhooksResource } from "./webhook-handler.js";
 import { ProxyWebhookEndpointsResource } from "./webhooks.js";
 export declare class ProxyCheckoutServerClient {
     readonly apiHost: string;
     readonly sessions: ProxySessionsResource;
     readonly subscriptions: ProxySubscriptionsResource;
+    /** Current-state lifecycle resolver for signed webhook events. */
+    readonly events: ProxyEventsResource;
+    /** Webhook delivery handling: `handle`, `process`, `constructEvent`. */
+    readonly webhooks: ProxyWebhooksResource;
+    /** Webhook endpoint management API (create/list/rotate). */
     readonly webhookEndpoints: ProxyWebhookEndpointsResource;
     constructor(options: ProxyCheckoutServerClientOptions);
 }

package/dist/client.js

@@ -1,11 +1,18 @@
+import { ProxyEventsResource } from "./events.js";
 import { ProxyCheckoutHttpClient } from "./http-client.js";
 import { ProxySessionsResource } from "./sessions.js";
 import { ProxySubscriptionsResource } from "./subscriptions.js";
+import { ProxyWebhooksResource } from "./webhook-handler.js";
 import { ProxyWebhookEndpointsResource } from "./webhooks.js";
 export class ProxyCheckoutServerClient {
     apiHost;
     sessions;
     subscriptions;
+    /** Current-state lifecycle resolver for signed webhook events. */
+    events;
+    /** Webhook delivery handling: `handle`, `process`, `constructEvent`. */
+    webhooks;
+    /** Webhook endpoint management API (create/list/rotate). */
     webhookEndpoints;
     constructor(options) {
         const httpClient = new ProxyCheckoutHttpClient({
@@ -18,7 +25,9 @@ export class ProxyCheckoutServerClient {
             payHost: options.payHost,
             publishableKey: options.publishableKey,
         });
-        this.subscriptions = new ProxySubscriptionsResource(httpClient);
+        this.subscriptions = new ProxySubscriptionsResource(httpClient, this.sessions);
+        this.events = new ProxyEventsResource(this.sessions, this.subscriptions);
+        this.webhooks = new ProxyWebhooksResource(this.events);
         this.webhookEndpoints = new ProxyWebhookEndpointsResource(httpClient);
     }
 }

package/dist/consistency.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Buyer-reference and session linkage consistency checks.
+ *
+ * Proxy current-state retrieval is the source of truth, but the SDK still
+ * guards that the records it stitches together actually belong to the same
+ * buyer and session before a merchant acts on them.
+ */
+import type { MerchantProxySession } from "./sessions.js";
+import type { MerchantProxySubscription } from "./subscriptions.js";
+/**
+ * Assert that a subscription belongs to the given original session and that the
+ * buyer references agree. Throws {@link ProxyCheckoutValidationError} otherwise.
+ */
+export declare function assertSubscriptionMatchesSession(subscription: Pick<MerchantProxySubscription, "buyerReference" | "id" | "originalProxySessionId">, session: Pick<MerchantProxySession, "buyerReference" | "id">): void;
+/**
+ * Assert that a cart-embedded buyer reference, when present, matches the session
+ * buyer reference. A `null`/`undefined` cart buyer reference is allowed (the
+ * cart simply does not carry one).
+ */
+export declare function assertCartBuyerReference(cartBuyerReference: string | null | undefined, session: Pick<MerchantProxySession, "buyerReference" | "id">): void;

package/dist/consistency.js

@@ -0,0 +1,32 @@
+/**
+ * Buyer-reference and session linkage consistency checks.
+ *
+ * Proxy current-state retrieval is the source of truth, but the SDK still
+ * guards that the records it stitches together actually belong to the same
+ * buyer and session before a merchant acts on them.
+ */
+import { ProxyCheckoutValidationError } from "./errors.js";
+/**
+ * Assert that a subscription belongs to the given original session and that the
+ * buyer references agree. Throws {@link ProxyCheckoutValidationError} otherwise.
+ */
+export function assertSubscriptionMatchesSession(subscription, session) {
+    if (subscription.originalProxySessionId !== session.id) {
+        throw new ProxyCheckoutValidationError(`Proxy subscription ${subscription.id} is not linked to session ${session.id}.`, { code: "subscription_session_mismatch", field: "original_proxy_session_id" });
+    }
+    if (subscription.buyerReference !== session.buyerReference) {
+        throw new ProxyCheckoutValidationError(`Proxy subscription ${subscription.id} buyer reference does not match session ${session.id}.`, { code: "buyer_reference_mismatch", field: "buyer_reference" });
+    }
+}
+/**
+ * Assert that a cart-embedded buyer reference, when present, matches the session
+ * buyer reference. A `null`/`undefined` cart buyer reference is allowed (the
+ * cart simply does not carry one).
+ */
+export function assertCartBuyerReference(cartBuyerReference, session) {
+    if (cartBuyerReference !== null &&
+        cartBuyerReference !== undefined &&
+        cartBuyerReference !== session.buyerReference) {
+        throw new ProxyCheckoutValidationError(`Proxy session ${session.id} cart buyer reference does not match the session buyer reference.`, { code: "buyer_reference_mismatch", field: "cart.buyerReference" });
+    }
+}

package/dist/errors.d.ts

@@ -4,6 +4,23 @@ 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";
+/**
+ * Raised when the SDK receives Proxy data it cannot safely normalize, for
+ * example an invalid date string, a cart snapshot that fails the merchant
+ * schema, or a buyer-reference / provider-binding consistency violation.
+ */
+export declare class ProxyCheckoutValidationError extends Error {
+    readonly name = "ProxyCheckoutValidationError";
+    readonly code: ProxyCheckoutValidationCode;
+    readonly field: string | undefined;
+    readonly cause: unknown;
+    constructor(message: string, details: {
+        code: ProxyCheckoutValidationCode;
+        field?: string;
+        cause?: unknown;
+    });
+}
 export declare class ProxyCheckoutApiError extends Error {
     readonly name = "ProxyCheckoutApiError";
     readonly code: string | undefined;

package/dist/errors.js

@@ -1,3 +1,20 @@
+/**
+ * Raised when the SDK receives Proxy data it cannot safely normalize, for
+ * example an invalid date string, a cart snapshot that fails the merchant
+ * schema, or a buyer-reference / provider-binding consistency violation.
+ */
+export class ProxyCheckoutValidationError extends Error {
+    name = "ProxyCheckoutValidationError";
+    code;
+    field;
+    cause;
+    constructor(message, details) {
+        super(message);
+        this.code = details.code;
+        this.field = details.field;
+        this.cause = details.cause;
+    }
+}
 export class ProxyCheckoutApiError extends Error {
     name = "ProxyCheckoutApiError";
     code;

package/dist/events.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Current-state lifecycle resolver for signed Proxy webhook events.
+ *
+ * A webhook is only a wakeup: this resolver re-reads the authoritative session
+ * and subscription state with the merchant secret key and returns a typed
+ * lifecycle decision. It never grants from webhook payload fields, and it
+ * classifies subscription events from current state rather than event order.
+ */
+import type { MerchantProxySession, ProxySessionsResource } from "./sessions.js";
+import type { MerchantProxySubscription, ProxySubscriptionsResource } from "./subscriptions.js";
+import type { ProxyCheckoutServerRequestOptions } from "./types.js";
+import type { ProxyWebhookEvent } from "./webhooks.js";
+export interface ResolveProxyEventOptions extends ProxyCheckoutServerRequestOptions {
+}
+interface ResolvedBase {
+    readonly event: ProxyWebhookEvent;
+}
+/**
+ * First paid/provisionable wakeup for a session. `subscription` is present when
+ * the event carried a subscription id; otherwise the merchant computes initial
+ * access from its own cart policy (`accessEndsAt`/`willRenew` are then null).
+ */
+export interface ResolvedInitialProvision extends ResolvedBase {
+    readonly accessEndsAt: Date | null;
+    readonly kind: "initial_provision";
+    readonly session: MerchantProxySession;
+    readonly subscription: MerchantProxySubscription | null;
+    readonly willRenew: boolean | null;
+}
+export interface ResolvedSubscriptionRenewed extends ResolvedBase {
+    readonly accessEndsAt: Date | null;
+    readonly kind: "subscription_renewed";
+    readonly session: MerchantProxySession;
+    readonly subscription: MerchantProxySubscription;
+    readonly willRenew: boolean;
+}
+export interface ResolvedSubscriptionCancelScheduled extends ResolvedBase {
+    readonly accessEndsAt: Date | null;
+    readonly kind: "subscription_cancel_scheduled";
+    readonly session: MerchantProxySession;
+    readonly subscription: MerchantProxySubscription;
+    readonly willRenew: false;
+}
+export interface ResolvedSubscriptionCancelled extends ResolvedBase {
+    readonly accessEndsAt: Date | null;
+    readonly kind: "subscription_cancelled";
+    readonly session: MerchantProxySession;
+    readonly subscription: MerchantProxySubscription;
+    readonly willRenew: false;
+}
+export interface ResolvedPaymentRisk extends ResolvedBase {
+    readonly accessEndsAt: Date | null;
+    readonly kind: "payment_risk";
+    readonly latestPaymentStatus: string | null;
+    readonly session: MerchantProxySession;
+    readonly subscription: MerchantProxySubscription;
+    readonly willRenew: boolean;
+}
+export interface ResolvedTerminalSession extends ResolvedBase {
+    readonly kind: "terminal_session";
+    readonly session: MerchantProxySession;
+}
+export interface ResolvedIgnored extends ResolvedBase {
+    readonly kind: "ignored";
+    readonly reason: string;
+    readonly sessionId: string | null;
+    readonly subscriptionId: string | null;
+}
+export type ResolvedProxyEvent = ResolvedInitialProvision | ResolvedSubscriptionRenewed | ResolvedSubscriptionCancelScheduled | ResolvedSubscriptionCancelled | ResolvedPaymentRisk | ResolvedTerminalSession | ResolvedIgnored;
+export type ResolvedProxyEventKind = ResolvedProxyEvent["kind"];
+export declare class ProxyEventsResource {
+    private readonly sessions;
+    private readonly subscriptions;
+    constructor(sessions: ProxySessionsResource, subscriptions: ProxySubscriptionsResource);
+    /**
+     * Resolve a signed webhook event into a current-state lifecycle decision by
+     * re-reading the authoritative session/subscription with the secret key.
+     */
+    resolveCurrentState(event: ProxyWebhookEvent, options?: ResolveProxyEventOptions): Promise<ResolvedProxyEvent>;
+    private resolveSessionEvent;
+    private resolveSubscriptionEvent;
+}
+export {};

package/dist/events.js

@@ -0,0 +1,147 @@
+/**
+ * Current-state lifecycle resolver for signed Proxy webhook events.
+ *
+ * A webhook is only a wakeup: this resolver re-reads the authoritative session
+ * and subscription state with the merchant secret key and returns a typed
+ * lifecycle decision. It never grants from webhook payload fields, and it
+ * classifies subscription events from current state rather than event order.
+ */
+import { assertSubscriptionMatchesSession } from "./consistency.js";
+import { isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, subscriptionAccessEndsAt, subscriptionWillRenew, } from "./lifecycle.js";
+import { isProxySessionEvent, isProxySubscriptionEvent } from "./webhook-events.js";
+export class ProxyEventsResource {
+    sessions;
+    subscriptions;
+    constructor(sessions, subscriptions) {
+        this.sessions = sessions;
+        this.subscriptions = subscriptions;
+    }
+    /**
+     * Resolve a signed webhook event into a current-state lifecycle decision by
+     * re-reading the authoritative session/subscription with the secret key.
+     */
+    async resolveCurrentState(event, options = {}) {
+        if (isProxySubscriptionEvent(event.type)) {
+            return this.resolveSubscriptionEvent(event, options);
+        }
+        if (isProxySessionEvent(event.type)) {
+            return this.resolveSessionEvent(event, options);
+        }
+        return ignored(event, `Event type ${event.type} is not a lifecycle event.`, {
+            sessionId: readEventString(event.data.proxy_session_id),
+            subscriptionId: readEventString(event.data.subscription_id),
+        });
+    }
+    async resolveSessionEvent(event, options) {
+        const sessionId = extractSessionId(event);
+        if (sessionId === null) {
+            return ignored(event, "Session event is missing proxy_session_id.", {
+                sessionId: null,
+                subscriptionId: readEventString(event.data.subscription_id),
+            });
+        }
+        const session = await this.sessions.retrieve(sessionId, options);
+        if (isSessionProvisionable(session)) {
+            const subscriptionId = readEventString(event.data.subscription_id);
+            let subscription = null;
+            if (subscriptionId !== null) {
+                subscription = await this.subscriptions.retrieve(subscriptionId, options);
+                assertSubscriptionMatchesSession(subscription, session);
+            }
+            return {
+                accessEndsAt: subscription === null ? null : subscriptionAccessEndsAt(subscription),
+                event,
+                kind: "initial_provision",
+                session,
+                subscription,
+                willRenew: subscription === null ? null : subscriptionWillRenew(subscription),
+            };
+        }
+        if (isSessionTerminal(session)) {
+            return { event, kind: "terminal_session", session };
+        }
+        return ignored(event, `Session ${session.id} status ${session.status} is not yet actionable.`, {
+            sessionId: session.id,
+            subscriptionId: null,
+        });
+    }
+    async resolveSubscriptionEvent(event, options) {
+        const subscriptionId = readEventString(event.data.subscription_id);
+        if (subscriptionId === null) {
+            return ignored(event, "Subscription event is missing subscription_id.", {
+                sessionId: readEventString(event.data.proxy_session_id),
+                subscriptionId: null,
+            });
+        }
+        const subscription = await this.subscriptions.retrieve(subscriptionId, options);
+        const session = await this.sessions.retrieve(subscription.originalProxySessionId, options);
+        assertSubscriptionMatchesSession(subscription, session);
+        const accessEndsAt = subscriptionAccessEndsAt(subscription);
+        if (isSubscriptionEnded(subscription)) {
+            return {
+                accessEndsAt,
+                event,
+                kind: "subscription_cancelled",
+                session,
+                subscription,
+                willRenew: false,
+            };
+        }
+        if (subscription.cancelAtPeriodEnd) {
+            return {
+                accessEndsAt,
+                event,
+                kind: "subscription_cancel_scheduled",
+                session,
+                subscription,
+                willRenew: false,
+            };
+        }
+        if (isSubscriptionPaymentAtRisk(subscription)) {
+            return {
+                accessEndsAt,
+                event,
+                kind: "payment_risk",
+                latestPaymentStatus: subscription.latestPaymentStatus,
+                session,
+                subscription,
+                willRenew: subscriptionWillRenew(subscription),
+            };
+        }
+        return {
+            accessEndsAt,
+            event,
+            kind: "subscription_renewed",
+            session,
+            subscription,
+            willRenew: subscriptionWillRenew(subscription),
+        };
+    }
+}
+function ignored(event, reason, ids) {
+    return {
+        event,
+        kind: "ignored",
+        reason,
+        sessionId: ids.sessionId,
+        subscriptionId: ids.subscriptionId,
+    };
+}
+/** Read the session id from an event, handling the nested `proxy_session.expired` payload. */
+function extractSessionId(event) {
+    const direct = readEventString(event.data.proxy_session_id);
+    if (direct !== null) {
+        return direct;
+    }
+    const nested = event.data.proxy_session;
+    if (isRecord(nested)) {
+        return readEventString(nested.id);
+    }
+    return null;
+}
+function readEventString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/index.d.ts

@@ -1,7 +1,13 @@
+export { type ProxyCartParseOptions, type ProxyCartValidator, parseProxyCart, } from "./cart.js";
 export { createProxyCheckoutServerClient, ProxyCheckoutServerClient, } from "./client.js";
-export { ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails } from "./errors.js";
-export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, ProxySessionsResource, proxyCheckoutServerEndpoints, type SetProxySessionCartInput, } from "./sessions.js";
-export { type MerchantProxySubscription, ProxySubscriptionsResource, proxyCheckoutSubscriptionEndpoints, } from "./subscriptions.js";
+export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./consistency.js";
+export { ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails, type ProxyCheckoutValidationCode, ProxyCheckoutValidationError, } from "./errors.js";
+export { ProxyEventsResource, type ResolvedIgnored, type ResolvedInitialProvision, 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 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 { type ConstructProxyWebhookEventInput, type CreateWebhookEndpointInput, constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, type ProxyWebhookEvent, proxyCheckoutWebhookEndpointEndpoints, type RotateWebhookEndpointSecretInput, type UpdateWebhookEndpointInput, type VerifyProxyWebhookSignatureInput, verifyProxyWebhookSignature, type WebhookEndpoint, type WebhookEndpointSecretResult, } from "./webhooks.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 { 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/index.js

@@ -1,6 +1,12 @@
+export { parseProxyCart, } from "./cart.js";
 export { createProxyCheckoutServerClient, ProxyCheckoutServerClient, } from "./client.js";
-export { ProxyCheckoutApiError } from "./errors.js";
+export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./consistency.js";
+export { ProxyCheckoutApiError, ProxyCheckoutValidationError, } from "./errors.js";
+export { ProxyEventsResource, } from "./events.js";
+export { AT_RISK_SUBSCRIPTION_STATUSES, ENDED_SUBSCRIPTION_STATUSES, isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, PROVISIONABLE_SESSION_STATUSES, parseOptionalProxyDate, requireProxyDate, subscriptionAccessEndsAt, subscriptionWillRenew, TERMINAL_SESSION_STATUSES, } from "./lifecycle.js";
 export { ProxySessionCartResource, ProxySessionsResource, proxyCheckoutServerEndpoints, } from "./sessions.js";
 export { ProxySubscriptionsResource, proxyCheckoutSubscriptionEndpoints, } from "./subscriptions.js";
 export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";
-export { constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, proxyCheckoutWebhookEndpointEndpoints, verifyProxyWebhookSignature, } from "./webhooks.js";
+export { isProxyPaymentAttemptEvent, isProxySessionEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, } from "./webhook-events.js";
+export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, ProxyWebhooksResource, } from "./webhook-handler.js";
+export { constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, ProxyWebhookSignatureVerificationError, proxyCheckoutWebhookEndpointEndpoints, verifyProxyWebhookSignature, } from "./webhooks.js";

package/dist/lifecycle.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SDK-owned normalization of Proxy session and subscription lifecycle.
+ *
+ * These helpers turn raw Proxy state into the small set of derived facts a
+ * merchant entitlement layer actually needs (`willRenew`, `accessEndsAt`,
+ * terminal/provisionable predicates) so every customer does not re-encode
+ * Proxy lifecycle semantics by hand.
+ */
+import type { MerchantProxySession } from "./sessions.js";
+import type { MerchantProxySubscription } from "./subscriptions.js";
+/** Session statuses that mean the payer has paid and entitlement may be granted. */
+export declare const PROVISIONABLE_SESSION_STATUSES: Set<string>;
+/** Session statuses that are terminal — no further lifecycle transitions occur. */
+export declare const TERMINAL_SESSION_STATUSES: Set<string>;
+/** Subscription statuses that mean the subscription is no longer active. */
+export declare const ENDED_SUBSCRIPTION_STATUSES: Set<string>;
+/** Subscription statuses that indicate a payment problem on an otherwise live subscription. */
+export declare const AT_RISK_SUBSCRIPTION_STATUSES: Set<string>;
+/** Parse a required ISO date from Proxy, throwing a structured error when missing/invalid. */
+export declare function requireProxyDate(value: string | null | undefined, field: string): Date;
+/** Parse an optional ISO date from Proxy, returning null when absent and throwing when invalid. */
+export declare function parseOptionalProxyDate(value: string | null | undefined, field?: string): Date | null;
+/** True once the payer has paid / the session is provisionable for entitlement. */
+export declare function isSessionProvisionable(session: Pick<MerchantProxySession, "status">): boolean;
+/** True once the session has reached a terminal state. */
+export declare function isSessionTerminal(session: Pick<MerchantProxySession, "status">): boolean;
+/**
+ * Whether the subscription is expected to renew at the end of the current period.
+ * A subscription will not renew once it is scheduled to cancel or has ended.
+ */
+export declare function subscriptionWillRenew(subscription: Pick<MerchantProxySubscription, "cancelAtPeriodEnd" | "endedAt" | "status">): boolean;
+/**
+ * The instant at which paid access should end given current subscription state.
+ * Prefers an explicit `endedAt` (hard stop) over the current period boundary.
+ * Returns null when neither is known.
+ */
+export declare function subscriptionAccessEndsAt(subscription: Pick<MerchantProxySubscription, "currentPeriodEnd" | "endedAt">): Date | null;
+/** True when the subscription has ended (cancelled / expired / explicitly ended). */
+export declare function isSubscriptionEnded(subscription: Pick<MerchantProxySubscription, "endedAt" | "status">): boolean;
+/** True when the subscription is live but has a payment problem (past_due / unpaid / failed). */
+export declare function isSubscriptionPaymentAtRisk(subscription: Pick<MerchantProxySubscription, "latestPaymentStatus" | "status">): boolean;

package/dist/lifecycle.js

@@ -0,0 +1,91 @@
+/**
+ * SDK-owned normalization of Proxy session and subscription lifecycle.
+ *
+ * These helpers turn raw Proxy state into the small set of derived facts a
+ * merchant entitlement layer actually needs (`willRenew`, `accessEndsAt`,
+ * terminal/provisionable predicates) so every customer does not re-encode
+ * Proxy lifecycle semantics by hand.
+ */
+import { ProxyCheckoutValidationError } from "./errors.js";
+/** Session statuses that mean the payer has paid and entitlement may be granted. */
+export const PROVISIONABLE_SESSION_STATUSES = new Set(["paid", "provisionable"]);
+/** Session statuses that are terminal — no further lifecycle transitions occur. */
+export const TERMINAL_SESSION_STATUSES = new Set([
+    "cancelled",
+    "expired",
+    "failed",
+    "provisioned",
+    "provisioning_failed",
+]);
+/** Subscription statuses that mean the subscription is no longer active. */
+export const ENDED_SUBSCRIPTION_STATUSES = new Set([
+    "canceled",
+    "ended",
+    "incomplete_expired",
+]);
+/** Subscription statuses that indicate a payment problem on an otherwise live subscription. */
+export const AT_RISK_SUBSCRIPTION_STATUSES = new Set(["past_due", "unpaid"]);
+/** Parse a required ISO date from Proxy, throwing a structured error when missing/invalid. */
+export function requireProxyDate(value, field) {
+    const date = parseOptionalProxyDate(value, field);
+    if (date === null) {
+        throw new ProxyCheckoutValidationError(`Proxy date field ${field} is required.`, {
+            code: "invalid_date",
+            field,
+        });
+    }
+    return date;
+}
+/** Parse an optional ISO date from Proxy, returning null when absent and throwing when invalid. */
+export function parseOptionalProxyDate(value, field = "date") {
+    if (value === null || value === undefined || value === "") {
+        return null;
+    }
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new ProxyCheckoutValidationError(`Proxy date field ${field} is not a valid date.`, {
+            code: "invalid_date",
+            field,
+        });
+    }
+    return date;
+}
+/** True once the payer has paid / the session is provisionable for entitlement. */
+export function isSessionProvisionable(session) {
+    return PROVISIONABLE_SESSION_STATUSES.has(session.status);
+}
+/** True once the session has reached a terminal state. */
+export function isSessionTerminal(session) {
+    return TERMINAL_SESSION_STATUSES.has(session.status);
+}
+/**
+ * Whether the subscription is expected to renew at the end of the current period.
+ * A subscription will not renew once it is scheduled to cancel or has ended.
+ */
+export function subscriptionWillRenew(subscription) {
+    if (subscription.cancelAtPeriodEnd) {
+        return false;
+    }
+    if (subscription.endedAt !== null) {
+        return false;
+    }
+    return !ENDED_SUBSCRIPTION_STATUSES.has(subscription.status);
+}
+/**
+ * The instant at which paid access should end given current subscription state.
+ * Prefers an explicit `endedAt` (hard stop) over the current period boundary.
+ * Returns null when neither is known.
+ */
+export function subscriptionAccessEndsAt(subscription) {
+    return (parseOptionalProxyDate(subscription.endedAt, "subscription.endedAt") ??
+        parseOptionalProxyDate(subscription.currentPeriodEnd, "subscription.currentPeriodEnd"));
+}
+/** True when the subscription has ended (cancelled / expired / explicitly ended). */
+export function isSubscriptionEnded(subscription) {
+    return subscription.endedAt !== null || ENDED_SUBSCRIPTION_STATUSES.has(subscription.status);
+}
+/** True when the subscription is live but has a payment problem (past_due / unpaid / failed). */
+export function isSubscriptionPaymentAtRisk(subscription) {
+    return (AT_RISK_SUBSCRIPTION_STATUSES.has(subscription.status) ||
+        subscription.latestPaymentStatus === "failed");
+}

package/dist/sessions.d.ts

@@ -1,3 +1,4 @@
+import { type ProxyCartParseOptions, type ProxyCartValidator } from "./cart.js";
 import type { ProxyCheckoutHttpClient } from "./http-client.js";
 import type { JsonObject, ProxyCheckoutServerRequestOptions } from "./types.js";
 export interface CreateProxySessionOptions extends ProxyCheckoutServerRequestOptions {
@@ -45,12 +46,18 @@ export interface MerchantProxySession {
         readonly email: string | null;
         readonly phone: string | null;
     } | null;
+    readonly providerCheckoutSessionId: string | null;
+    readonly providerCheckoutSessionPsp: string | null;
     readonly status: string;
     readonly updatedAt: string;
 }
 export interface PayerOpenedResult extends MerchantProxySession {
     readonly status: "payer_opened";
 }
+/** A merchant session with its cart snapshot validated against a merchant schema. */
+export interface TypedMerchantProxySession<TCart> extends MerchantProxySession {
+    readonly cart: TCart;
+}
 export interface PayerHandoffResult {
     readonly status: "payer_handoff_pending" | "payer_opened";
 }
@@ -64,6 +71,16 @@ export interface ProxySessionCartResult {
     readonly cartSnapshot: JsonObject;
     readonly currency: string;
 }
+export interface RecordProviderBindingInput extends ProxyCheckoutServerRequestOptions {
+    readonly providerCheckoutSessionId: string;
+    readonly psp: string;
+}
+export interface ProxySessionProviderBinding {
+    readonly providerCheckoutSessionId: string;
+    readonly proxySessionId: string;
+    readonly psp: string;
+    readonly updatedAt: string;
+}
 export declare const proxyCheckoutServerEndpoints: readonly [{
     readonly method: "POST";
     readonly operation: "sessions.create";
@@ -88,6 +105,10 @@ export declare const proxyCheckoutServerEndpoints: readonly [{
     readonly method: "POST";
     readonly operation: "sessions.payerOpened";
     readonly path: "/proxy_sessions/:id/payer_opened";
+}, {
+    readonly method: "POST";
+    readonly operation: "sessions.providerBindings.create";
+    readonly path: "/proxy_sessions/:id/provider_bindings";
 }];
 export declare class ProxySessionsResource {
     private readonly httpClient;
@@ -100,8 +121,26 @@ export declare class ProxySessionsResource {
     create(input: CreateProxySessionInput): Promise<ProxySession>;
     createHandoff(input: CreateProxySessionHandoffInput): Promise<ProxySessionHandoff>;
     retrieve(proxySessionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<MerchantProxySession>;
+    /**
+     * Retrieve a session and validate its cart snapshot against a merchant schema,
+     * returning the session with a typed `cart`. Throws a structured error if the
+     * cart fails validation or its buyer reference disagrees with the session.
+     */
+    retrieveTyped<TCart>(proxySessionId: string, cartSchema: ProxyCartValidator<TCart>, options?: ProxyCheckoutServerRequestOptions & ProxyCartParseOptions<TCart>): Promise<TypedMerchantProxySession<TCart>>;
+    /**
+     * Validate the cart snapshot of an already-retrieved session against a merchant
+     * schema. When `getBuyerReference` is supplied, the cart buyer reference is
+     * asserted to match the session buyer reference.
+     */
+    parseCart<TCart>(session: MerchantProxySession, cartSchema: ProxyCartValidator<TCart>, options?: ProxyCartParseOptions<TCart>): TCart;
     payerHandoff(proxySessionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<PayerHandoffResult>;
     payerOpened(proxySessionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<PayerOpenedResult>;
+    /**
+     * 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.
+     */
+    recordProviderBinding(proxySessionId: string, input: RecordProviderBindingInput): Promise<ProxySessionProviderBinding>;
 }
 export declare class ProxySessionCartResource {
     private readonly httpClient;

package/dist/sessions.js

@@ -1,3 +1,5 @@
+import { parseProxyCart } from "./cart.js";
+import { assertCartBuyerReference } from "./consistency.js";
 import { requireInteger, requireJsonObject, requireNullableString, requireString, } from "./response-validators.js";
 export const proxyCheckoutServerEndpoints = [
     {
@@ -30,6 +32,11 @@ export const proxyCheckoutServerEndpoints = [
         operation: "sessions.payerOpened",
         path: "/proxy_sessions/:id/payer_opened",
     },
+    {
+        method: "POST",
+        operation: "sessions.providerBindings.create",
+        path: "/proxy_sessions/:id/provider_bindings",
+    },
 ];
 export class ProxySessionsResource {
     httpClient;
@@ -77,6 +84,27 @@ export class ProxySessionsResource {
         const response = await this.httpClient.request("GET", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/merchant`, undefined, options);
         return toMerchantProxySession(response);
     }
+    /**
+     * Retrieve a session and validate its cart snapshot against a merchant schema,
+     * returning the session with a typed `cart`. Throws a structured error if the
+     * cart fails validation or its buyer reference disagrees with the session.
+     */
+    async retrieveTyped(proxySessionId, cartSchema, options = {}) {
+        const session = await this.retrieve(proxySessionId, { requestId: options.requestId });
+        return { ...session, cart: this.parseCart(session, cartSchema, options) };
+    }
+    /**
+     * Validate the cart snapshot of an already-retrieved session against a merchant
+     * schema. When `getBuyerReference` is supplied, the cart buyer reference is
+     * asserted to match the session buyer reference.
+     */
+    parseCart(session, cartSchema, options = {}) {
+        const cart = parseProxyCart(session.cartSnapshot, cartSchema);
+        if (options.getBuyerReference !== undefined) {
+            assertCartBuyerReference(options.getBuyerReference(cart), session);
+        }
+        return cart;
+    }
     async payerHandoff(proxySessionId, options = {}) {
         const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/payer_handoff`, {}, options);
         const body = requireJsonObject(response, "sessions.payerHandoff");
@@ -88,6 +116,24 @@ export class ProxySessionsResource {
         const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/payer_opened`, {}, options);
         return toPayerOpenedResult(response);
     }
+    /**
+     * 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.
+     */
+    async recordProviderBinding(proxySessionId, input) {
+        const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/provider_bindings`, {
+            provider_checkout_session_id: input.providerCheckoutSessionId,
+            psp: input.psp,
+        }, { requestId: input.requestId });
+        const body = requireJsonObject(response, "sessions.providerBindings.create");
+        return {
+            providerCheckoutSessionId: requireString(body.provider_checkout_session_id, "sessions.providerBindings.create.providerCheckoutSessionId"),
+            proxySessionId: requireString(body.proxy_session_id, "sessions.providerBindings.create.proxySessionId"),
+            psp: requireString(body.psp, "sessions.providerBindings.create.psp"),
+            updatedAt: requireString(body.updated_at, "sessions.providerBindings.create.updatedAt"),
+        };
+    }
 }
 export class ProxySessionCartResource {
     httpClient;
@@ -178,6 +224,8 @@ function toMerchantProxySession(response) {
         integrationMode: requireString(body.integration_mode, "sessions.retrieve.integrationMode"),
         metadata: requireJsonObject(body.metadata, "sessions.retrieve.metadata"),
         payerContact: requireNullablePayerContact(body.payer_contact),
+        providerCheckoutSessionId: requireNullableString(body.provider_checkout_session_id, "sessions.retrieve.providerCheckoutSessionId"),
+        providerCheckoutSessionPsp: requireNullableString(body.provider_checkout_session_psp, "sessions.retrieve.providerCheckoutSessionPsp"),
         status: requireString(body.status, "sessions.retrieve.status"),
         updatedAt: requireString(body.updated_at, "sessions.retrieve.updatedAt"),
     };
@@ -200,6 +248,9 @@ function toPayerOpenedResult(response) {
         integrationMode: requireString(body.integration_mode, "sessions.payerOpened.integrationMode"),
         metadata: requireJsonObject(body.metadata, "sessions.payerOpened.metadata"),
         payerContact: requireNullablePayerContact(body.payer_contact, "sessions.payerOpened"),
+        // No provider binding exists yet at payer-open; it is recorded after checkout creation.
+        providerCheckoutSessionId: null,
+        providerCheckoutSessionPsp: null,
         status,
         updatedAt: requireString(body.updated_at, "sessions.payerOpened.updatedAt"),
     };

package/dist/subscriptions.d.ts

@@ -1,4 +1,6 @@
+import type { ProxyCartParseOptions, ProxyCartValidator } from "./cart.js";
 import type { ProxyCheckoutHttpClient } from "./http-client.js";
+import type { MerchantProxySession, ProxySessionsResource, TypedMerchantProxySession } from "./sessions.js";
 import type { ProxyCheckoutServerRequestOptions } from "./types.js";
 export interface MerchantProxySubscription {
     readonly buyerReference: string;
@@ -25,8 +27,28 @@ export declare const proxyCheckoutSubscriptionEndpoints: readonly [{
     readonly operation: "subscriptions.retrieve";
     readonly path: "/subscriptions/:id";
 }];
+/** A subscription paired with its verified original session (and optional typed cart). */
+export interface ProxySubscriptionWithSession<TCart> {
+    readonly cart: TCart;
+    readonly session: TypedMerchantProxySession<TCart>;
+    readonly subscription: MerchantProxySubscription;
+}
+export interface ProxySubscriptionWithUntypedSession {
+    readonly session: MerchantProxySession;
+    readonly subscription: MerchantProxySubscription;
+}
 export declare class ProxySubscriptionsResource {
     private readonly httpClient;
-    constructor(httpClient: ProxyCheckoutHttpClient);
+    private readonly sessions;
+    constructor(httpClient: ProxyCheckoutHttpClient, sessions: ProxySessionsResource);
     retrieve(subscriptionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<MerchantProxySubscription>;
+    /**
+     * Retrieve a subscription together with the original Proxy session it was
+     * created from, asserting buyer/session linkage. When `cartSchema` is given the
+     * session cart is validated and returned typed.
+     */
+    retrieveWithOriginalSession(subscriptionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<ProxySubscriptionWithUntypedSession>;
+    retrieveWithOriginalSession<TCart>(subscriptionId: string, options: ProxyCheckoutServerRequestOptions & ProxyCartParseOptions<TCart> & {
+        cartSchema: ProxyCartValidator<TCart>;
+    }): Promise<ProxySubscriptionWithSession<TCart>>;
 }

package/dist/subscriptions.js

@@ -1,3 +1,4 @@
+import { assertSubscriptionMatchesSession } from "./consistency.js";
 import { requireBoolean, requireJsonObject, requireNullableInteger, requireNullableString, requireString, } from "./response-validators.js";
 export const proxyCheckoutSubscriptionEndpoints = [
     {
@@ -8,13 +9,26 @@ export const proxyCheckoutSubscriptionEndpoints = [
 ];
 export class ProxySubscriptionsResource {
     httpClient;
-    constructor(httpClient) {
+    sessions;
+    constructor(httpClient, sessions) {
         this.httpClient = httpClient;
+        this.sessions = sessions;
     }
     async retrieve(subscriptionId, options = {}) {
         const response = await this.httpClient.request("GET", `/subscriptions/${encodeURIComponent(subscriptionId)}`, undefined, options);
         return toMerchantProxySubscription(response);
     }
+    async retrieveWithOriginalSession(subscriptionId, options = {}) {
+        const requestOptions = { requestId: options.requestId };
+        const subscription = await this.retrieve(subscriptionId, requestOptions);
+        const session = await this.sessions.retrieve(subscription.originalProxySessionId, requestOptions);
+        assertSubscriptionMatchesSession(subscription, session);
+        if (options.cartSchema === undefined) {
+            return { session, subscription };
+        }
+        const cart = this.sessions.parseCart(session, options.cartSchema, options);
+        return { cart, session: { ...session, cart }, subscription };
+    }
 }
 function toMerchantProxySubscription(response) {
     const body = requireJsonObject(response, "subscriptions.retrieve");

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.3";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.3";
+export declare const proxyCheckoutServerSdkVersion = "0.0.4-pr-76.13.1";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.4-pr-76.13.1";

package/dist/version.js

@@ -1,3 +1,3 @@
 export const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export const proxyCheckoutServerSdkVersion = "0.0.3";
+export const proxyCheckoutServerSdkVersion = "0.0.4-pr-76.13.1";
 export const proxyCheckoutServerSdkUserAgent = `${proxyCheckoutServerSdkName}/${proxyCheckoutServerSdkVersion}`;

package/dist/webhook-events.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Canonical outbound Proxy webhook event types and predicates.
+ *
+ * These mirror the event types the Proxy API can deliver to merchant webhook
+ * endpoints. Use the predicates instead of comparing raw strings so customer
+ * integration code does not encode the event taxonomy by hand.
+ */
+export declare const PROXY_WEBHOOK_EVENT_TYPES: {
+    readonly paymentAttemptCancelled: "payment_attempt.cancelled";
+    readonly paymentAttemptFailed: "payment_attempt.failed";
+    readonly paymentAttemptSucceeded: "payment_attempt.succeeded";
+    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 subscriptionCancelled: "subscription.cancelled";
+    readonly subscriptionCancelScheduled: "subscription.cancel_scheduled";
+    readonly subscriptionPaymentFailed: "subscription.payment_failed";
+    readonly subscriptionRenewed: "subscription.renewed";
+};
+export type ProxyWebhookEventType = (typeof PROXY_WEBHOOK_EVENT_TYPES)[keyof typeof PROXY_WEBHOOK_EVENT_TYPES];
+/** True for `proxy_session.*` events. */
+export declare function isProxySessionEvent(eventType: string): boolean;
+/** True for `subscription.*` events. */
+export declare function isProxySubscriptionEvent(eventType: string): boolean;
+/** True for `payment_attempt.*` events. */
+export declare function isProxyPaymentAttemptEvent(eventType: string): boolean;

package/dist/webhook-events.js

@@ -0,0 +1,53 @@
+/**
+ * Canonical outbound Proxy webhook event types and predicates.
+ *
+ * These mirror the event types the Proxy API can deliver to merchant webhook
+ * endpoints. Use the predicates instead of comparing raw strings so customer
+ * integration code does not encode the event taxonomy by hand.
+ */
+export const PROXY_WEBHOOK_EVENT_TYPES = {
+    paymentAttemptCancelled: "payment_attempt.cancelled",
+    paymentAttemptFailed: "payment_attempt.failed",
+    paymentAttemptSucceeded: "payment_attempt.succeeded",
+    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",
+    subscriptionCancelled: "subscription.cancelled",
+    subscriptionCancelScheduled: "subscription.cancel_scheduled",
+    subscriptionPaymentFailed: "subscription.payment_failed",
+    subscriptionRenewed: "subscription.renewed",
+};
+const SESSION_EVENT_TYPES = new Set([
+    PROXY_WEBHOOK_EVENT_TYPES.sessionCancelled,
+    PROXY_WEBHOOK_EVENT_TYPES.sessionExpired,
+    PROXY_WEBHOOK_EVENT_TYPES.sessionFailed,
+    PROXY_WEBHOOK_EVENT_TYPES.sessionMerchantActionRequired,
+    PROXY_WEBHOOK_EVENT_TYPES.sessionPaid,
+    PROXY_WEBHOOK_EVENT_TYPES.sessionProvisionable,
+]);
+const SUBSCRIPTION_EVENT_TYPES = new Set([
+    PROXY_WEBHOOK_EVENT_TYPES.subscriptionCancelScheduled,
+    PROXY_WEBHOOK_EVENT_TYPES.subscriptionCancelled,
+    PROXY_WEBHOOK_EVENT_TYPES.subscriptionPaymentFailed,
+    PROXY_WEBHOOK_EVENT_TYPES.subscriptionRenewed,
+]);
+const PAYMENT_ATTEMPT_EVENT_TYPES = new Set([
+    PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptCancelled,
+    PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptFailed,
+    PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptSucceeded,
+]);
+/** True for `proxy_session.*` events. */
+export function isProxySessionEvent(eventType) {
+    return SESSION_EVENT_TYPES.has(eventType);
+}
+/** True for `subscription.*` events. */
+export function isProxySubscriptionEvent(eventType) {
+    return SUBSCRIPTION_EVENT_TYPES.has(eventType);
+}
+/** True for `payment_attempt.*` events. */
+export function isProxyPaymentAttemptEvent(eventType) {
+    return PAYMENT_ATTEMPT_EVENT_TYPES.has(eventType);
+}

package/dist/webhook-handler.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Server SDK webhook delivery handler.
+ *
+ * `handle` turns a verified Proxy webhook into a current-state lifecycle
+ * decision and runs the merchant's entitlement callback, with optional
+ * idempotency via a pluggable {@link ProxyWebhookStore}. It owns signature
+ * verification, duplicate/in-flight handling, retryable responses, and
+ * current-state retrieval so customer webhook routes stay tiny.
+ */
+import type { ProxyEventsResource, ResolvedProxyEvent, ResolvedProxyEventKind } from "./events.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;
+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 kind: ResolvedProxyEventKind;
+    readonly sessionId: string | null;
+    readonly subscriptionId: string | null;
+}
+/**
+ * Optional merchant-owned idempotency/audit store. The handler treats already
+ * processed events as success and concurrently in-flight events as retryable;
+ * it never classifies lifecycle itself.
+ */
+export interface ProxyWebhookStore {
+    /** Atomically claim an event id. Return "duplicate" if already processed, "processing" if in flight. */
+    claim(event: ProxyWebhookEvent): Promise<ProxyWebhookClaimResult> | ProxyWebhookClaimResult;
+    /** Mark a claimed event failed so it can be retried/reclaimed. */
+    markFailed(eventId: string, error: unknown): Promise<void> | void;
+    /** Mark a claimed event processed (idempotency commit). */
+    markProcessed(eventId: string, record: ProxyWebhookProcessRecord): Promise<void> | void;
+}
+export interface ProxyWebhookPayloadInput {
+    readonly body: Buffer | string;
+    readonly signature?: string | null;
+}
+/**
+ * A web `Request` (Next.js route handlers, Hono on Node) or an explicit
+ * body/signature pair (Express/Node). Signature verification uses `node:crypto`,
+ * so this targets Node-compatible runtimes — not Cloudflare Workers.
+ */
+export type ProxyWebhookRequestInput = ProxyWebhookPayloadInput | Request;
+export interface ProxyWebhookHandlerOptions {
+    /** 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. */
+    readonly requestId?: string;
+    /** Endpoint signing secret. */
+    readonly secret: string;
+    /** Optional idempotency/audit store. Omit for at-least-once delivery with idempotent fulfillment. */
+    readonly store?: ProxyWebhookStore;
+    /** Signature timestamp tolerance in seconds (default 300). */
+    readonly toleranceSeconds?: number;
+}
+export interface ProxyWebhookProcessResult {
+    readonly event: ProxyWebhookEvent;
+    readonly outcome: ProxyWebhookOutcome;
+    readonly resolved: ResolvedProxyEvent | null;
+    readonly retryable: boolean;
+    readonly statusCode: number;
+}
+export declare class ProxyWebhooksResource {
+    private readonly events;
+    constructor(events: ProxyEventsResource);
+    /** Low-level: verify + construct the event without resolving lifecycle. */
+    constructEvent(input: {
+        body: Buffer | string;
+        header: string | null | undefined;
+        secret: string;
+        toleranceSeconds?: number;
+    }): ProxyWebhookEvent;
+    /**
+     * Framework-agnostic processing. Verifies the signature, applies the store,
+     * resolves current state, runs `onResolved`, and returns response metadata.
+     * Throws {@link ProxyWebhookSignatureVerificationError} on a bad signature so
+     * non-Response frameworks (Express) can map it to 400.
+     */
+    process(input: ProxyWebhookRequestInput, options: ProxyWebhookHandlerOptions): Promise<ProxyWebhookProcessResult>;
+    /**
+     * Turnkey handler for web `Request` frameworks. Returns a `Response` with the
+     * right status (200 success/duplicate, 409 + `Retry-After` in flight, 400 on
+     * bad signature). Re-throws merchant `onResolved` errors so the platform can
+     * surface a 500 and Proxy retries.
+     */
+    handle(input: ProxyWebhookRequestInput, options: ProxyWebhookHandlerOptions): Promise<Response>;
+}

package/dist/webhook-handler.js

@@ -0,0 +1,159 @@
+/**
+ * Server SDK webhook delivery handler.
+ *
+ * `handle` turns a verified Proxy webhook into a current-state lifecycle
+ * decision and runs the merchant's entitlement callback, with optional
+ * idempotency via a pluggable {@link ProxyWebhookStore}. It owns signature
+ * verification, duplicate/in-flight handling, retryable responses, and
+ * current-state retrieval so customer webhook routes stay tiny.
+ */
+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) {
+        this.events = events;
+    }
+    /** Low-level: verify + construct the event without resolving lifecycle. */
+    constructEvent(input) {
+        return constructProxyWebhookEvent(input);
+    }
+    /**
+     * Framework-agnostic processing. Verifies the signature, applies the store,
+     * resolves current state, runs `onResolved`, and returns response metadata.
+     * Throws {@link ProxyWebhookSignatureVerificationError} on a bad signature so
+     * non-Response frameworks (Express) can map it to 400.
+     */
+    async process(input, options) {
+        const { body, signature } = await readWebhookPayload(input);
+        const event = constructProxyWebhookEvent({
+            body,
+            header: signature,
+            secret: options.secret,
+            toleranceSeconds: options.toleranceSeconds,
+        });
+        const { store } = options;
+        if (store !== undefined) {
+            const claim = await store.claim(event);
+            if (claim === "duplicate") {
+                return {
+                    event,
+                    outcome: "duplicate",
+                    resolved: null,
+                    retryable: false,
+                    statusCode: 200,
+                };
+            }
+            if (claim === "processing") {
+                return {
+                    event,
+                    outcome: "processing",
+                    resolved: null,
+                    retryable: true,
+                    statusCode: 409,
+                };
+            }
+        }
+        let resolved;
+        try {
+            resolved = await this.events.resolveCurrentState(event, { requestId: options.requestId });
+            await options.onResolved(resolved);
+        }
+        catch (error) {
+            if (store !== undefined) {
+                try {
+                    await store.markFailed(event.id, error);
+                }
+                catch {
+                    // Never let a store failure shadow the original fulfillment error.
+                }
+            }
+            throw error;
+        }
+        if (store !== undefined) {
+            await store.markProcessed(event.id, toProcessRecord(resolved));
+        }
+        return {
+            event,
+            outcome: resolved.kind === "ignored" ? "ignored" : "processed",
+            resolved,
+            retryable: false,
+            statusCode: 200,
+        };
+    }
+    /**
+     * Turnkey handler for web `Request` frameworks. Returns a `Response` with the
+     * right status (200 success/duplicate, 409 + `Retry-After` in flight, 400 on
+     * bad signature). Re-throws merchant `onResolved` errors so the platform can
+     * surface a 500 and Proxy retries.
+     */
+    async handle(input, options) {
+        let result;
+        try {
+            result = await this.process(input, options);
+        }
+        catch (error) {
+            if (error instanceof ProxyWebhookSignatureVerificationError) {
+                return jsonResponse(400, {
+                    error: { code: "invalid_signature", message: error.message },
+                });
+            }
+            throw error;
+        }
+        return toWebhookResponse(result);
+    }
+}
+function toWebhookResponse(result) {
+    const headers = { "content-type": "application/json" };
+    if (result.retryable) {
+        headers["retry-after"] = String(PROXY_WEBHOOK_RETRY_AFTER_SECONDS);
+    }
+    return new Response(JSON.stringify({ ok: !result.retryable, outcome: result.outcome }), {
+        headers,
+        status: result.statusCode,
+    });
+}
+function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        headers: { "content-type": "application/json" },
+        status,
+    });
+}
+function toProcessRecord(resolved) {
+    switch (resolved.kind) {
+        case "ignored":
+            return {
+                kind: resolved.kind,
+                sessionId: resolved.sessionId,
+                subscriptionId: resolved.subscriptionId,
+            };
+        case "terminal_session":
+            return { kind: resolved.kind, sessionId: resolved.session.id, subscriptionId: null };
+        case "initial_provision":
+            return {
+                kind: resolved.kind,
+                sessionId: resolved.session.id,
+                subscriptionId: resolved.subscription?.id ?? null,
+            };
+        default:
+            return {
+                kind: resolved.kind,
+                sessionId: resolved.session.id,
+                subscriptionId: resolved.subscription.id,
+            };
+    }
+}
+async function readWebhookPayload(input) {
+    if (isFetchRequest(input)) {
+        return {
+            body: await input.text(),
+            signature: input.headers.get(PROXY_SIGNATURE_HEADER),
+        };
+    }
+    const body = typeof input.body === "string" ? input.body : input.body.toString("utf8");
+    return { body, signature: input.signature ?? null };
+}
+function isFetchRequest(input) {
+    return typeof input.text === "function";
+}

package/dist/webhooks.d.ts

@@ -41,6 +41,10 @@ export interface ProxyWebhookEvent {
     readonly type: string;
 }
 export declare const PROXY_SIGNATURE_HEADER = "proxy-signature";
+/** Raised when a webhook payload fails signature verification. */
+export declare class ProxyWebhookSignatureVerificationError extends Error {
+    readonly name = "ProxyWebhookSignatureVerificationError";
+}
 export declare const proxyCheckoutWebhookEndpointEndpoints: readonly [{
     readonly method: "GET";
     readonly operation: "webhookEndpoints.list";

package/dist/webhooks.js

@@ -1,6 +1,10 @@
 import { createHmac, timingSafeEqual } from "node:crypto";
 import { requireStringArrayOrNull as readStringArrayOrNull, requireNullableString as readStringOrNull, requireJsonObject, requireString, } from "./response-validators.js";
 export const PROXY_SIGNATURE_HEADER = "proxy-signature";
+/** Raised when a webhook payload fails signature verification. */
+export class ProxyWebhookSignatureVerificationError extends Error {
+    name = "ProxyWebhookSignatureVerificationError";
+}
 export const proxyCheckoutWebhookEndpointEndpoints = [
     {
         method: "GET",
@@ -90,7 +94,7 @@ export function verifyProxyWebhookSignature(input) {
 }
 export function constructProxyWebhookEvent(input) {
     if (!verifyProxyWebhookSignature(input)) {
-        throw new Error("Proxy webhook signature verification failed.");
+        throw new ProxyWebhookSignatureVerificationError("Proxy webhook signature verification failed.");
     }
     const body = typeof input.body === "string" ? input.body : input.body.toString("utf8");
     let parsed;

package/package.json

@@ -7,7 +7,7 @@
   "sideEffects": false,
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.0.3",
+  "version": "0.0.4-pr-76.13.1",
   "devDependencies": {
     "@types/node": "^24.12.4",
     "@vitest/coverage-v8": "4.1.7",