@proxy-checkout/server-js 0.0.2 → 0.0.3-pr-76.12.1

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,84 @@
+/**
+ * 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 route handler, Hono, Cloudflare Worker) or an explicit body/signature pair (Express/Node). */
+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,154 @@
+/**
+ * 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) {
+                await store.markFailed(event.id, 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

@@ -1,5 +1,5 @@
 import type { ProxyCheckoutHttpClient } from "./http-client.js";
-import type { ProxyCheckoutServerRequestOptions } from "./types.js";
+import type { JsonObject, ProxyCheckoutServerRequestOptions } from "./types.js";
 export interface WebhookEndpoint {
     readonly createdAt: string;
     readonly eventSchemaVersion: string;
@@ -32,6 +32,19 @@ export interface VerifyProxyWebhookSignatureInput {
     readonly secret: string;
     readonly toleranceSeconds?: number;
 }
+export interface ConstructProxyWebhookEventInput extends VerifyProxyWebhookSignatureInput {
+}
+export interface ProxyWebhookEvent {
+    readonly data: JsonObject;
+    readonly id: string;
+    readonly schemaVersion: string;
+    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";
@@ -68,3 +81,4 @@ export declare class ProxyWebhookEndpointsResource {
     rotateSecret(webhookEndpointId: string, input: RotateWebhookEndpointSecretInput): Promise<WebhookEndpointSecretResult>;
 }
 export declare function verifyProxyWebhookSignature(input: VerifyProxyWebhookSignatureInput): boolean;
+export declare function constructProxyWebhookEvent(input: ConstructProxyWebhookEventInput): ProxyWebhookEvent;

package/dist/webhooks.js

@@ -1,4 +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",
@@ -86,6 +92,26 @@ export function verifyProxyWebhookSignature(input) {
         .digest("hex");
     return parsed.signatures.some((signature) => timingSafeEqualString(expected, signature));
 }
+export function constructProxyWebhookEvent(input) {
+    if (!verifyProxyWebhookSignature(input)) {
+        throw new ProxyWebhookSignatureVerificationError("Proxy webhook signature verification failed.");
+    }
+    const body = typeof input.body === "string" ? input.body : input.body.toString("utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        throw new Error("Proxy webhook body must be valid JSON.");
+    }
+    const event = requireJsonObject(parsed, "webhookEvent");
+    return {
+        data: requireJsonObject(event.data, "webhookEvent.data"),
+        id: requireString(event.id, "webhookEvent.id"),
+        schemaVersion: requireString(event.schema_version, "webhookEvent.schemaVersion"),
+        type: requireString(event.type, "webhookEvent.type"),
+    };
+}
 function toWebhookEndpointBody(input) {
     return {
         ...(input.eventTypes === undefined ? {} : { event_types: input.eventTypes }),
@@ -147,27 +173,3 @@ function timingSafeEqualString(left, right) {
     const rightBuffer = Buffer.from(right, "hex");
     return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
 }
-function requireJsonObject(value, operation) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new Error(`Proxy API response for ${operation} must be a JSON object.`);
-    }
-    return value;
-}
-function requireString(value, field) {
-    if (typeof value !== "string") {
-        throw new Error(`Proxy API response field ${field} must be a string.`);
-    }
-    return value;
-}
-function readStringOrNull(value, field) {
-    return value === null ? null : requireString(value, field);
-}
-function readStringArrayOrNull(value, field) {
-    if (value === null) {
-        return null;
-    }
-    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
-        throw new Error(`Proxy API response field ${field} must be an array or null.`);
-    }
-    return value;
-}

package/package.json

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