@proxy-checkout/server-js 0.0.4-pr-76.21.1 → 0.0.4-pr-76.23.1

package/dist/cjs/sessions.js

@@ -0,0 +1,303 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxySessionCartResource = exports.ProxySessionsResource = exports.proxyCheckoutServerEndpoints = void 0;
+const cart_js_1 = require("./cart.js");
+const consistency_js_1 = require("./consistency.js");
+const response_validators_js_1 = require("./response-validators.js");
+exports.proxyCheckoutServerEndpoints = [
+    {
+        method: "POST",
+        operation: "sessions.create",
+        path: "/proxy_sessions",
+    },
+    {
+        method: "POST",
+        operation: "sessions.createHandoff",
+        path: "/proxy_sessions/handoff",
+    },
+    {
+        method: "GET",
+        operation: "sessions.retrieve",
+        path: "/proxy_sessions/:id/merchant",
+    },
+    {
+        method: "PUT",
+        operation: "sessions.cart.set",
+        path: "/proxy_sessions/:id/cart",
+    },
+    {
+        method: "POST",
+        operation: "sessions.payerHandoff",
+        path: "/proxy_sessions/:id/payer_handoff",
+    },
+    {
+        method: "POST",
+        operation: "sessions.payerOpened",
+        path: "/proxy_sessions/:id/payer_opened",
+    },
+    {
+        method: "POST",
+        operation: "sessions.providerBindings.create",
+        path: "/proxy_sessions/:id/provider_bindings",
+    },
+];
+class ProxySessionsResource {
+    httpClient;
+    options;
+    cart;
+    constructor(httpClient, options = {}) {
+        this.httpClient = httpClient;
+        this.options = options;
+        this.cart = new ProxySessionCartResource(httpClient);
+    }
+    async create(input) {
+        const response = await this.httpClient.request("POST", "/proxy_sessions", toCreateProxySessionBody(input), {
+            idempotencyKey: input.idempotencyKey,
+            requestId: input.requestId,
+        });
+        return toProxySession(response);
+    }
+    async createHandoff(input) {
+        const publishableKey = input.publishableKey ?? this.options.publishableKey;
+        if (!publishableKey) {
+            throw new Error("Proxy Checkout sessions.createHandoff requires a publishableKey option or input field.");
+        }
+        const payHost = input.payHost ?? this.options.payHost;
+        if (!payHost && this.httpClient.apiHost !== "https://api.proxycheckout.com") {
+            throw new Error("Proxy Checkout sessions.createHandoff requires a payHost option or input field when apiHost is overridden.");
+        }
+        const response = await this.httpClient.request("POST", "/proxy_sessions/handoff", {
+            ...toCreateProxySessionBody(input),
+            publishable_key: publishableKey,
+        }, {
+            idempotencyKey: input.idempotencyKey,
+            requestId: input.requestId,
+        });
+        const session = toProxySessionHandoff(response);
+        return {
+            ...session,
+            handoffUrl: buildHandoffUrl({
+                payHost,
+                proxySessionId: session.id,
+                publishableKey,
+            }),
+        };
+    }
+    async retrieve(proxySessionId, options = {}) {
+        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 = (0, cart_js_1.parseProxyCart)(session.cartSnapshot, cartSchema);
+        if (options.getBuyerReference !== undefined) {
+            (0, consistency_js_1.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 = (0, response_validators_js_1.requireJsonObject)(response, "sessions.payerHandoff");
+        return {
+            status: requirePayerHandoffStatus(body.status),
+        };
+    }
+    async payerOpened(proxySessionId, options = {}) {
+        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 = (0, response_validators_js_1.requireJsonObject)(response, "sessions.providerBindings.create");
+        return {
+            providerCheckoutSessionId: (0, response_validators_js_1.requireString)(body.provider_checkout_session_id, "sessions.providerBindings.create.providerCheckoutSessionId"),
+            proxySessionId: (0, response_validators_js_1.requireString)(body.proxy_session_id, "sessions.providerBindings.create.proxySessionId"),
+            psp: (0, response_validators_js_1.requireString)(body.psp, "sessions.providerBindings.create.psp"),
+            updatedAt: (0, response_validators_js_1.requireString)(body.updated_at, "sessions.providerBindings.create.updatedAt"),
+        };
+    }
+}
+exports.ProxySessionsResource = ProxySessionsResource;
+class ProxySessionCartResource {
+    httpClient;
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    async set(proxySessionId, input) {
+        const response = await this.httpClient.request("PUT", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/cart`, toProxySessionCartBody(input), {
+            requestId: input.requestId,
+        });
+        const body = (0, response_validators_js_1.requireJsonObject)(response, "sessions.cart.set");
+        return {
+            amountMinor: (0, response_validators_js_1.requireInteger)(body.amount_minor, "sessions.cart.set.amountMinor"),
+            cartSnapshot: (0, response_validators_js_1.requireJsonObject)(body.cart_snapshot, "sessions.cart.set"),
+            cartVersion: (0, response_validators_js_1.requireInteger)(body.cart_version, "sessions.cart.set.cartVersion"),
+            currency: (0, response_validators_js_1.requireString)(body.currency, "sessions.cart.set.currency"),
+        };
+    }
+}
+exports.ProxySessionCartResource = ProxySessionCartResource;
+function toCreateProxySessionBody(input) {
+    const body = {
+        amount_minor: input.amountMinor,
+        buyer_reference: input.buyerReference,
+        cart_snapshot: input.cartSnapshot,
+        currency: input.currency,
+    };
+    if (input.expiresAt !== undefined) {
+        body.expires_at =
+            input.expiresAt instanceof Date ? input.expiresAt.toISOString() : input.expiresAt;
+    }
+    if (input.integrationMode !== undefined) {
+        body.integration_mode = input.integrationMode;
+    }
+    if (input.metadata !== undefined) {
+        body.metadata = input.metadata;
+    }
+    if (input.payerContact !== undefined) {
+        body.payer_contact = removeUndefinedValues({
+            email: input.payerContact.email,
+            phone: input.payerContact.phone,
+        });
+    }
+    return body;
+}
+function toProxySessionCartBody(input) {
+    return {
+        amount_minor: input.amountMinor,
+        cart_snapshot: input.cartSnapshot,
+        currency: input.currency,
+        expected_cart_version: input.expectedCartVersion,
+    };
+}
+function removeUndefinedValues(input) {
+    return Object.fromEntries(Object.entries(input).filter((entry) => entry[1] !== undefined));
+}
+function toProxySession(response) {
+    const body = (0, response_validators_js_1.requireJsonObject)(response, "sessions.create");
+    const status = (0, response_validators_js_1.requireString)(body.status, "sessions.create.status");
+    const integrationMode = (0, response_validators_js_1.requireString)(body.integration_mode, "sessions.create.integrationMode");
+    return {
+        expiresAt: (0, response_validators_js_1.requireString)(body.expires_at, "sessions.create.expiresAt"),
+        id: (0, response_validators_js_1.requireString)(body.id, "sessions.create.id"),
+        integrationMode,
+        status,
+    };
+}
+function toProxySessionHandoff(response) {
+    const body = (0, response_validators_js_1.requireJsonObject)(response, "sessions.createHandoff");
+    const status = requirePayerHandoffStatus(body.status);
+    const integrationMode = (0, response_validators_js_1.requireString)(body.integration_mode, "sessions.createHandoff.integrationMode");
+    return {
+        expiresAt: (0, response_validators_js_1.requireString)(body.expires_at, "sessions.createHandoff.expiresAt"),
+        handoffUrl: "",
+        id: (0, response_validators_js_1.requireString)(body.id, "sessions.createHandoff.id"),
+        integrationMode,
+        status,
+    };
+}
+function toMerchantProxySession(response) {
+    const body = (0, response_validators_js_1.requireJsonObject)(response, "sessions.retrieve");
+    return {
+        amountMinor: (0, response_validators_js_1.requireInteger)(body.amount_minor, "sessions.retrieve.amountMinor"),
+        buyerReference: (0, response_validators_js_1.requireString)(body.buyer_reference, "sessions.retrieve.buyerReference"),
+        cartSnapshot: (0, response_validators_js_1.requireJsonObject)(body.cart_snapshot, "sessions.retrieve.cartSnapshot"),
+        cartVersion: (0, response_validators_js_1.requireInteger)(body.cart_version, "sessions.retrieve.cartVersion"),
+        createdAt: (0, response_validators_js_1.requireString)(body.created_at, "sessions.retrieve.createdAt"),
+        currency: (0, response_validators_js_1.requireString)(body.currency, "sessions.retrieve.currency"),
+        expiresAt: (0, response_validators_js_1.requireString)(body.expires_at, "sessions.retrieve.expiresAt"),
+        id: (0, response_validators_js_1.requireString)(body.id, "sessions.retrieve.id"),
+        idempotencyKey: (0, response_validators_js_1.requireNullableString)(body.idempotency_key, "sessions.retrieve.idempotencyKey"),
+        integrationMode: (0, response_validators_js_1.requireString)(body.integration_mode, "sessions.retrieve.integrationMode"),
+        metadata: (0, response_validators_js_1.requireJsonObject)(body.metadata, "sessions.retrieve.metadata"),
+        payerContact: requireNullablePayerContact(body.payer_contact),
+        providerCheckoutSessionId: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_id, "sessions.retrieve.providerCheckoutSessionId"),
+        providerCheckoutSessionPsp: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_psp, "sessions.retrieve.providerCheckoutSessionPsp"),
+        status: (0, response_validators_js_1.requireString)(body.status, "sessions.retrieve.status"),
+        updatedAt: (0, response_validators_js_1.requireString)(body.updated_at, "sessions.retrieve.updatedAt"),
+    };
+}
+function toPayerOpenedResult(response) {
+    const body = (0, response_validators_js_1.requireJsonObject)(response, "sessions.payerOpened");
+    const status = (0, response_validators_js_1.requireString)(body.status, "sessions.payerOpened.status");
+    if (status !== "payer_opened") {
+        throw new Error("Proxy API response field sessions.payerOpened.status is unsupported.");
+    }
+    return {
+        amountMinor: (0, response_validators_js_1.requireInteger)(body.amount_minor, "sessions.payerOpened.amountMinor"),
+        buyerReference: (0, response_validators_js_1.requireString)(body.buyer_reference, "sessions.payerOpened.buyerReference"),
+        cartSnapshot: (0, response_validators_js_1.requireJsonObject)(body.cart_snapshot, "sessions.payerOpened.cartSnapshot"),
+        cartVersion: (0, response_validators_js_1.requireInteger)(body.cart_version, "sessions.payerOpened.cartVersion"),
+        createdAt: (0, response_validators_js_1.requireString)(body.created_at, "sessions.payerOpened.createdAt"),
+        currency: (0, response_validators_js_1.requireString)(body.currency, "sessions.payerOpened.currency"),
+        expiresAt: (0, response_validators_js_1.requireString)(body.expires_at, "sessions.payerOpened.expiresAt"),
+        id: (0, response_validators_js_1.requireString)(body.id, "sessions.payerOpened.id"),
+        idempotencyKey: (0, response_validators_js_1.requireNullableString)(body.idempotency_key, "sessions.payerOpened.idempotencyKey"),
+        integrationMode: (0, response_validators_js_1.requireString)(body.integration_mode, "sessions.payerOpened.integrationMode"),
+        metadata: (0, response_validators_js_1.requireJsonObject)(body.metadata, "sessions.payerOpened.metadata"),
+        payerContact: requireNullablePayerContact(body.payer_contact, "sessions.payerOpened"),
+        providerCheckoutSessionId: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_id, "sessions.payerOpened.providerCheckoutSessionId"),
+        providerCheckoutSessionPsp: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_psp, "sessions.payerOpened.providerCheckoutSessionPsp"),
+        status,
+        updatedAt: (0, response_validators_js_1.requireString)(body.updated_at, "sessions.payerOpened.updatedAt"),
+    };
+}
+function requireNullablePayerContact(value, operation = "sessions.retrieve") {
+    if (value === null) {
+        return null;
+    }
+    const contact = (0, response_validators_js_1.requireJsonObject)(value, `${operation}.payerContact`);
+    return {
+        email: (0, response_validators_js_1.requireNullableString)(contact.email, `${operation}.payerContact.email`),
+        phone: (0, response_validators_js_1.requireNullableString)(contact.phone, `${operation}.payerContact.phone`),
+    };
+}
+function requirePayerHandoffStatus(value) {
+    const status = (0, response_validators_js_1.requireString)(value, "sessions.payerHandoff.status");
+    if (status === "payer_handoff_pending" || status === "payer_opened") {
+        return status;
+    }
+    throw new Error("Proxy API response field sessions.payerHandoff.status is unsupported.");
+}
+function buildHandoffUrl({ payHost, proxySessionId, publishableKey, }) {
+    const url = new URL(`${normalizePayHost(payHost)}/s/${encodeURIComponent(proxySessionId)}`);
+    url.searchParams.set("pk", publishableKey);
+    return url.toString();
+}
+function normalizePayHost(payHost) {
+    if (payHost === undefined) {
+        return "https://pay.proxycheckout.com";
+    }
+    let url;
+    try {
+        url = new URL(payHost);
+    }
+    catch {
+        throw new Error(`Invalid payHost URL: ${payHost}. Make sure it is an absolute HTTP or HTTPS URL.`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`Invalid payHost URL: ${payHost}. Make sure it is an absolute HTTP or HTTPS URL.`);
+    }
+    return `${url.origin}${url.pathname}`.replace(/\/$/, "");
+}

package/dist/cjs/subscriptions.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxySubscriptionsResource = exports.proxyCheckoutSubscriptionEndpoints = void 0;
+const consistency_js_1 = require("./consistency.js");
+const response_validators_js_1 = require("./response-validators.js");
+exports.proxyCheckoutSubscriptionEndpoints = [
+    {
+        method: "GET",
+        operation: "subscriptions.retrieve",
+        path: "/subscriptions/:id",
+    },
+];
+class ProxySubscriptionsResource {
+    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);
+        (0, consistency_js_1.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 };
+    }
+}
+exports.ProxySubscriptionsResource = ProxySubscriptionsResource;
+function toMerchantProxySubscription(response) {
+    const body = (0, response_validators_js_1.requireJsonObject)(response, "subscriptions.retrieve");
+    return {
+        buyerReference: (0, response_validators_js_1.requireString)(body.buyer_reference, "subscriptions.retrieve.buyerReference"),
+        cancelAtPeriodEnd: (0, response_validators_js_1.requireBoolean)(body.cancel_at_period_end, "subscriptions.retrieve.cancelAtPeriodEnd"),
+        createdAt: (0, response_validators_js_1.requireString)(body.created_at, "subscriptions.retrieve.createdAt"),
+        currentPeriodEnd: (0, response_validators_js_1.requireNullableString)(body.current_period_end, "subscriptions.retrieve.currentPeriodEnd"),
+        currentPeriodStart: (0, response_validators_js_1.requireNullableString)(body.current_period_start, "subscriptions.retrieve.currentPeriodStart"),
+        endedAt: (0, response_validators_js_1.requireNullableString)(body.ended_at, "subscriptions.retrieve.endedAt"),
+        id: (0, response_validators_js_1.requireString)(body.id, "subscriptions.retrieve.id"),
+        latestInvoiceAmountMinor: (0, response_validators_js_1.requireNullableInteger)(body.latest_invoice_amount_minor, "subscriptions.retrieve.latestInvoiceAmountMinor"),
+        latestInvoiceCurrency: (0, response_validators_js_1.requireNullableString)(body.latest_invoice_currency, "subscriptions.retrieve.latestInvoiceCurrency"),
+        latestInvoiceId: (0, response_validators_js_1.requireNullableString)(body.latest_invoice_id, "subscriptions.retrieve.latestInvoiceId"),
+        latestPaymentStatus: (0, response_validators_js_1.requireNullableString)(body.latest_payment_status, "subscriptions.retrieve.latestPaymentStatus"),
+        originalProxySessionId: (0, response_validators_js_1.requireString)(body.original_proxy_session_id, "subscriptions.retrieve.originalProxySessionId"),
+        providerCheckoutSessionId: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_id, "subscriptions.retrieve.providerCheckoutSessionId"),
+        providerSubscriptionId: (0, response_validators_js_1.requireString)(body.provider_subscription_id, "subscriptions.retrieve.providerSubscriptionId"),
+        psp: (0, response_validators_js_1.requireString)(body.psp, "subscriptions.retrieve.psp"),
+        status: (0, response_validators_js_1.requireString)(body.status, "subscriptions.retrieve.status"),
+        trialEnd: (0, response_validators_js_1.requireNullableString)(body.trial_end, "subscriptions.retrieve.trialEnd"),
+        updatedAt: (0, response_validators_js_1.requireString)(body.updated_at, "subscriptions.retrieve.updatedAt"),
+    };
+}

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/version.js

@@ -0,0 +1,6 @@
+"use strict";
+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.23.1";
+exports.proxyCheckoutServerSdkUserAgent = `${exports.proxyCheckoutServerSdkName}/${exports.proxyCheckoutServerSdkVersion}`;

package/dist/cjs/webhook-events.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROXY_WEBHOOK_EVENT_TYPES = void 0;
+exports.isProxySessionEvent = isProxySessionEvent;
+exports.isProxySubscriptionEvent = isProxySubscriptionEvent;
+exports.isProxyPaymentAttemptEvent = isProxyPaymentAttemptEvent;
+exports.PROXY_WEBHOOK_EVENT_TYPES = {
+    paymentAttemptCancelled: "payment_attempt.cancelled",
+    paymentAttemptDisputed: "payment_attempt.disputed",
+    paymentAttemptDisputeLost: "payment_attempt.dispute_lost",
+    paymentAttemptDisputeWon: "payment_attempt.dispute_won",
+    paymentAttemptFailed: "payment_attempt.failed",
+    paymentAttemptPartiallyRefunded: "payment_attempt.partially_refunded",
+    paymentAttemptRefunded: "payment_attempt.refunded",
+    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([
+    exports.PROXY_WEBHOOK_EVENT_TYPES.sessionCancelled,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.sessionExpired,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.sessionFailed,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.sessionMerchantActionRequired,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.sessionPaid,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.sessionProvisionable,
+]);
+const SUBSCRIPTION_EVENT_TYPES = new Set([
+    exports.PROXY_WEBHOOK_EVENT_TYPES.subscriptionCancelScheduled,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.subscriptionCancelled,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.subscriptionPaymentFailed,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.subscriptionRenewed,
+]);
+const PAYMENT_ATTEMPT_EVENT_TYPES = new Set([
+    exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptCancelled,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptDisputeLost,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptDisputeWon,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptDisputed,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptFailed,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptPartiallyRefunded,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptRefunded,
+    exports.PROXY_WEBHOOK_EVENT_TYPES.paymentAttemptSucceeded,
+]);
+/** True for `proxy_session.*` events. */
+function isProxySessionEvent(eventType) {
+    return SESSION_EVENT_TYPES.has(eventType);
+}
+/** True for `subscription.*` events. */
+function isProxySubscriptionEvent(eventType) {
+    return SUBSCRIPTION_EVENT_TYPES.has(eventType);
+}
+/** True for `payment_attempt.*` events. */
+function isProxyPaymentAttemptEvent(eventType) {
+    return PAYMENT_ATTEMPT_EVENT_TYPES.has(eventType);
+}

package/dist/cjs/webhook-handler.js

@@ -0,0 +1,177 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxyWebhooksResource = exports.PROXY_WEBHOOK_RETRY_AFTER_SECONDS = void 0;
+const webhooks_js_1 = require("./webhooks.js");
+/** Seconds advertised in `Retry-After` when an event is already in flight. */
+exports.PROXY_WEBHOOK_RETRY_AFTER_SECONDS = 30;
+class ProxyWebhooksResource {
+    events;
+    constructor(events) {
+        this.events = events;
+    }
+    /** Low-level: verify + construct the event without resolving lifecycle. */
+    constructEvent(input) {
+        return (0, webhooks_js_1.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 = (0, webhooks_js_1.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) {
+            try {
+                await store.markProcessed(event.id, toProcessRecord(resolved));
+            }
+            catch (error) {
+                // The fulfillment ran, but committing idempotency failed. Best-effort
+                // release the claim so the event is reclaimable on a later delivery
+                // instead of being stuck in the in-flight branch forever.
+                try {
+                    await store.markFailed(event.id, error);
+                }
+                catch {
+                    // Never let a store failure shadow the original markProcessed error.
+                }
+                throw error;
+            }
+        }
+        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 webhooks_js_1.ProxyWebhookSignatureVerificationError) {
+                return jsonResponse(400, {
+                    error: { code: "invalid_signature", message: error.message },
+                });
+            }
+            throw error;
+        }
+        return toWebhookResponse(result);
+    }
+}
+exports.ProxyWebhooksResource = ProxyWebhooksResource;
+function toWebhookResponse(result) {
+    const headers = { "content-type": "application/json" };
+    if (result.retryable) {
+        headers["retry-after"] = String(exports.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(webhooks_js_1.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";
+}