@proxy-checkout/server-js 0.0.4-pr-76.30.1 → 0.0.4-pr-76.32.1

package/dist/cjs/sessions.d.cts

@@ -0,0 +1,152 @@
+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 {
+    readonly idempotencyKey?: string;
+}
+export interface CreateProxySessionInput extends CreateProxySessionOptions {
+    readonly amountMinor: number;
+    readonly buyerReference: string;
+    readonly cartSnapshot: JsonObject;
+    readonly currency: string;
+    readonly expiresAt?: Date | string;
+    readonly integrationMode?: "elements";
+    readonly metadata?: JsonObject;
+    readonly payerContact?: {
+        readonly email?: string;
+        readonly phone?: string;
+    };
+}
+export interface CreateProxySessionHandoffInput extends CreateProxySessionInput {
+    readonly payHost?: string;
+    readonly publishableKey?: string;
+}
+export interface ProxySession {
+    readonly expiresAt: string;
+    readonly id: string;
+    readonly integrationMode: string;
+    readonly status: string;
+}
+export interface ProxySessionHandoff extends ProxySession {
+    readonly handoffUrl: string;
+    readonly status: "payer_handoff_pending" | "payer_opened";
+}
+export interface MerchantProxySession {
+    readonly amountMinor: number;
+    readonly buyerReference: string;
+    readonly cartSnapshot: JsonObject;
+    readonly cartVersion: number;
+    readonly createdAt: string;
+    readonly currency: string;
+    readonly expiresAt: string;
+    readonly id: string;
+    readonly idempotencyKey: string | null;
+    readonly integrationMode: string;
+    readonly metadata: JsonObject;
+    readonly payerContact: {
+        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";
+}
+export interface SetProxySessionCartInput extends ProxyCheckoutServerRequestOptions {
+    readonly amountMinor: number;
+    readonly cartSnapshot: JsonObject;
+    readonly currency: string;
+    readonly expectedCartVersion: number;
+}
+export interface ProxySessionCartResult {
+    readonly amountMinor: number;
+    readonly cartSnapshot: JsonObject;
+    readonly cartVersion: number;
+    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";
+    readonly path: "/proxy_sessions";
+}, {
+    readonly method: "POST";
+    readonly operation: "sessions.createHandoff";
+    readonly path: "/proxy_sessions/handoff";
+}, {
+    readonly method: "GET";
+    readonly operation: "sessions.retrieve";
+    readonly path: "/proxy_sessions/:id/merchant";
+}, {
+    readonly method: "PUT";
+    readonly operation: "sessions.cart.set";
+    readonly path: "/proxy_sessions/:id/cart";
+}, {
+    readonly method: "POST";
+    readonly operation: "sessions.payerHandoff";
+    readonly path: "/proxy_sessions/:id/payer_handoff";
+}, {
+    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;
+    private readonly options;
+    readonly cart: ProxySessionCartResource;
+    constructor(httpClient: ProxyCheckoutHttpClient, options?: {
+        payHost?: string;
+        publishableKey?: string;
+    });
+    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;
+    constructor(httpClient: ProxyCheckoutHttpClient);
+    set(proxySessionId: string, input: SetProxySessionCartInput): Promise<ProxySessionCartResult>;
+}

package/dist/cjs/sessions.d.ts

@@ -0,0 +1,152 @@
+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 {
+    readonly idempotencyKey?: string;
+}
+export interface CreateProxySessionInput extends CreateProxySessionOptions {
+    readonly amountMinor: number;
+    readonly buyerReference: string;
+    readonly cartSnapshot: JsonObject;
+    readonly currency: string;
+    readonly expiresAt?: Date | string;
+    readonly integrationMode?: "elements";
+    readonly metadata?: JsonObject;
+    readonly payerContact?: {
+        readonly email?: string;
+        readonly phone?: string;
+    };
+}
+export interface CreateProxySessionHandoffInput extends CreateProxySessionInput {
+    readonly payHost?: string;
+    readonly publishableKey?: string;
+}
+export interface ProxySession {
+    readonly expiresAt: string;
+    readonly id: string;
+    readonly integrationMode: string;
+    readonly status: string;
+}
+export interface ProxySessionHandoff extends ProxySession {
+    readonly handoffUrl: string;
+    readonly status: "payer_handoff_pending" | "payer_opened";
+}
+export interface MerchantProxySession {
+    readonly amountMinor: number;
+    readonly buyerReference: string;
+    readonly cartSnapshot: JsonObject;
+    readonly cartVersion: number;
+    readonly createdAt: string;
+    readonly currency: string;
+    readonly expiresAt: string;
+    readonly id: string;
+    readonly idempotencyKey: string | null;
+    readonly integrationMode: string;
+    readonly metadata: JsonObject;
+    readonly payerContact: {
+        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";
+}
+export interface SetProxySessionCartInput extends ProxyCheckoutServerRequestOptions {
+    readonly amountMinor: number;
+    readonly cartSnapshot: JsonObject;
+    readonly currency: string;
+    readonly expectedCartVersion: number;
+}
+export interface ProxySessionCartResult {
+    readonly amountMinor: number;
+    readonly cartSnapshot: JsonObject;
+    readonly cartVersion: number;
+    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";
+    readonly path: "/proxy_sessions";
+}, {
+    readonly method: "POST";
+    readonly operation: "sessions.createHandoff";
+    readonly path: "/proxy_sessions/handoff";
+}, {
+    readonly method: "GET";
+    readonly operation: "sessions.retrieve";
+    readonly path: "/proxy_sessions/:id/merchant";
+}, {
+    readonly method: "PUT";
+    readonly operation: "sessions.cart.set";
+    readonly path: "/proxy_sessions/:id/cart";
+}, {
+    readonly method: "POST";
+    readonly operation: "sessions.payerHandoff";
+    readonly path: "/proxy_sessions/:id/payer_handoff";
+}, {
+    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;
+    private readonly options;
+    readonly cart: ProxySessionCartResource;
+    constructor(httpClient: ProxyCheckoutHttpClient, options?: {
+        payHost?: string;
+        publishableKey?: string;
+    });
+    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;
+    constructor(httpClient: ProxyCheckoutHttpClient);
+    set(proxySessionId: string, input: SetProxySessionCartInput): Promise<ProxySessionCartResult>;
+}

package/dist/cjs/subscriptions.d.cts

@@ -0,0 +1,54 @@
+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;
+    readonly cancelAtPeriodEnd: boolean;
+    readonly createdAt: string;
+    readonly currentPeriodEnd: string | null;
+    readonly currentPeriodStart: string | null;
+    readonly endedAt: string | null;
+    readonly id: string;
+    readonly latestInvoiceAmountMinor: number | null;
+    readonly latestInvoiceCurrency: string | null;
+    readonly latestInvoiceId: string | null;
+    readonly latestPaymentStatus: string | null;
+    readonly originalProxySessionId: string;
+    readonly providerCheckoutSessionId: string | null;
+    readonly providerSubscriptionId: string;
+    readonly psp: string;
+    readonly status: string;
+    readonly trialEnd: string | null;
+    readonly updatedAt: string;
+}
+export declare const proxyCheckoutSubscriptionEndpoints: readonly [{
+    readonly method: "GET";
+    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;
+    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/cjs/subscriptions.d.ts

@@ -0,0 +1,54 @@
+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;
+    readonly cancelAtPeriodEnd: boolean;
+    readonly createdAt: string;
+    readonly currentPeriodEnd: string | null;
+    readonly currentPeriodStart: string | null;
+    readonly endedAt: string | null;
+    readonly id: string;
+    readonly latestInvoiceAmountMinor: number | null;
+    readonly latestInvoiceCurrency: string | null;
+    readonly latestInvoiceId: string | null;
+    readonly latestPaymentStatus: string | null;
+    readonly originalProxySessionId: string;
+    readonly providerCheckoutSessionId: string | null;
+    readonly providerSubscriptionId: string;
+    readonly psp: string;
+    readonly status: string;
+    readonly trialEnd: string | null;
+    readonly updatedAt: string;
+}
+export declare const proxyCheckoutSubscriptionEndpoints: readonly [{
+    readonly method: "GET";
+    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;
+    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/cjs/types.d.cts

@@ -0,0 +1,16 @@
+export type JsonPrimitive = boolean | null | number | string;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+export type ProxyCheckoutFetch = (input: Request | URL | string, init?: RequestInit) => Promise<Response>;
+export interface ProxyCheckoutServerClientOptions {
+    readonly apiHost?: string;
+    readonly apiKey: string;
+    readonly fetch?: ProxyCheckoutFetch;
+    readonly payHost?: string;
+    readonly publishableKey?: string;
+}
+export interface ProxyCheckoutServerRequestOptions {
+    readonly requestId?: string;
+}

package/dist/cjs/types.d.ts

@@ -0,0 +1,16 @@
+export type JsonPrimitive = boolean | null | number | string;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+export type ProxyCheckoutFetch = (input: Request | URL | string, init?: RequestInit) => Promise<Response>;
+export interface ProxyCheckoutServerClientOptions {
+    readonly apiHost?: string;
+    readonly apiKey: string;
+    readonly fetch?: ProxyCheckoutFetch;
+    readonly payHost?: string;
+    readonly publishableKey?: string;
+}
+export interface ProxyCheckoutServerRequestOptions {
+    readonly requestId?: string;
+}

package/dist/cjs/version.d.cts

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

package/dist/cjs/version.d.ts

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

package/dist/cjs/version.js

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

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

@@ -0,0 +1,34 @@
+/**
+ * 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 paymentAttemptDisputed: "payment_attempt.disputed";
+    readonly paymentAttemptDisputeLost: "payment_attempt.dispute_lost";
+    readonly paymentAttemptDisputeWon: "payment_attempt.dispute_won";
+    readonly paymentAttemptFailed: "payment_attempt.failed";
+    readonly paymentAttemptPartiallyRefunded: "payment_attempt.partially_refunded";
+    readonly paymentAttemptRefunded: "payment_attempt.refunded";
+    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/cjs/webhook-events.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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 paymentAttemptDisputed: "payment_attempt.disputed";
+    readonly paymentAttemptDisputeLost: "payment_attempt.dispute_lost";
+    readonly paymentAttemptDisputeWon: "payment_attempt.dispute_won";
+    readonly paymentAttemptFailed: "payment_attempt.failed";
+    readonly paymentAttemptPartiallyRefunded: "payment_attempt.partially_refunded";
+    readonly paymentAttemptRefunded: "payment_attempt.refunded";
+    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/cjs/webhook-handler.d.cts

@@ -0,0 +1,89 @@
+/**
+ * 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 paymentAttemptId?: string | null;
+    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>;
+}