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

package/dist/cjs/webhook-handler.d.ts

@@ -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>;
+}

package/dist/cjs/webhooks.d.cts

@@ -0,0 +1,84 @@
+import type { ProxyCheckoutHttpClient } from "./http-client.js";
+import type { JsonObject, ProxyCheckoutServerRequestOptions } from "./types.js";
+export interface WebhookEndpoint {
+    readonly createdAt: string;
+    readonly eventSchemaVersion: string;
+    readonly eventTypes: string[] | null;
+    readonly id: string;
+    readonly previousSigningSecretExpiresAt: string | null;
+    readonly status: string;
+    readonly updatedAt: string;
+    readonly url: string;
+}
+export interface CreateWebhookEndpointInput extends ProxyCheckoutServerRequestOptions {
+    readonly eventTypes?: string[];
+    readonly url: string;
+}
+export interface UpdateWebhookEndpointInput extends ProxyCheckoutServerRequestOptions {
+    readonly eventTypes?: string[];
+    readonly status?: "active" | "inactive";
+    readonly url?: string;
+}
+export interface RotateWebhookEndpointSecretInput extends ProxyCheckoutServerRequestOptions {
+    readonly previousSigningSecretExpiresAt: Date | string;
+}
+export interface WebhookEndpointSecretResult {
+    readonly signingSecret: string;
+    readonly webhookEndpoint: WebhookEndpoint;
+}
+export interface VerifyProxyWebhookSignatureInput {
+    readonly body: Buffer | string;
+    readonly header: string | null | undefined;
+    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";
+    readonly path: "/webhook_endpoints";
+}, {
+    readonly method: "POST";
+    readonly operation: "webhookEndpoints.create";
+    readonly path: "/webhook_endpoints";
+}, {
+    readonly method: "GET";
+    readonly operation: "webhookEndpoints.get";
+    readonly path: "/webhook_endpoints/:id";
+}, {
+    readonly method: "PATCH";
+    readonly operation: "webhookEndpoints.update";
+    readonly path: "/webhook_endpoints/:id";
+}, {
+    readonly method: "POST";
+    readonly operation: "webhookEndpoints.archive";
+    readonly path: "/webhook_endpoints/:id/archive";
+}, {
+    readonly method: "POST";
+    readonly operation: "webhookEndpoints.rotateSecret";
+    readonly path: "/webhook_endpoints/:id/rotate_secret";
+}];
+export declare class ProxyWebhookEndpointsResource {
+    private readonly httpClient;
+    constructor(httpClient: ProxyCheckoutHttpClient);
+    list(options?: ProxyCheckoutServerRequestOptions): Promise<WebhookEndpoint[]>;
+    create(input: CreateWebhookEndpointInput): Promise<WebhookEndpointSecretResult>;
+    get(webhookEndpointId: string, options?: ProxyCheckoutServerRequestOptions): Promise<WebhookEndpoint>;
+    update(webhookEndpointId: string, input: UpdateWebhookEndpointInput): Promise<WebhookEndpoint>;
+    archive(webhookEndpointId: string, options?: ProxyCheckoutServerRequestOptions): Promise<WebhookEndpoint>;
+    rotateSecret(webhookEndpointId: string, input: RotateWebhookEndpointSecretInput): Promise<WebhookEndpointSecretResult>;
+}
+export declare function verifyProxyWebhookSignature(input: VerifyProxyWebhookSignatureInput): boolean;
+export declare function constructProxyWebhookEvent(input: ConstructProxyWebhookEventInput): ProxyWebhookEvent;

package/dist/cjs/webhooks.d.ts

@@ -0,0 +1,84 @@
+import type { ProxyCheckoutHttpClient } from "./http-client.js";
+import type { JsonObject, ProxyCheckoutServerRequestOptions } from "./types.js";
+export interface WebhookEndpoint {
+    readonly createdAt: string;
+    readonly eventSchemaVersion: string;
+    readonly eventTypes: string[] | null;
+    readonly id: string;
+    readonly previousSigningSecretExpiresAt: string | null;
+    readonly status: string;
+    readonly updatedAt: string;
+    readonly url: string;
+}
+export interface CreateWebhookEndpointInput extends ProxyCheckoutServerRequestOptions {
+    readonly eventTypes?: string[];
+    readonly url: string;
+}
+export interface UpdateWebhookEndpointInput extends ProxyCheckoutServerRequestOptions {
+    readonly eventTypes?: string[];
+    readonly status?: "active" | "inactive";
+    readonly url?: string;
+}
+export interface RotateWebhookEndpointSecretInput extends ProxyCheckoutServerRequestOptions {
+    readonly previousSigningSecretExpiresAt: Date | string;
+}
+export interface WebhookEndpointSecretResult {
+    readonly signingSecret: string;
+    readonly webhookEndpoint: WebhookEndpoint;
+}
+export interface VerifyProxyWebhookSignatureInput {
+    readonly body: Buffer | string;
+    readonly header: string | null | undefined;
+    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";
+    readonly path: "/webhook_endpoints";
+}, {
+    readonly method: "POST";
+    readonly operation: "webhookEndpoints.create";
+    readonly path: "/webhook_endpoints";
+}, {
+    readonly method: "GET";
+    readonly operation: "webhookEndpoints.get";
+    readonly path: "/webhook_endpoints/:id";
+}, {
+    readonly method: "PATCH";
+    readonly operation: "webhookEndpoints.update";
+    readonly path: "/webhook_endpoints/:id";
+}, {
+    readonly method: "POST";
+    readonly operation: "webhookEndpoints.archive";
+    readonly path: "/webhook_endpoints/:id/archive";
+}, {
+    readonly method: "POST";
+    readonly operation: "webhookEndpoints.rotateSecret";
+    readonly path: "/webhook_endpoints/:id/rotate_secret";
+}];
+export declare class ProxyWebhookEndpointsResource {
+    private readonly httpClient;
+    constructor(httpClient: ProxyCheckoutHttpClient);
+    list(options?: ProxyCheckoutServerRequestOptions): Promise<WebhookEndpoint[]>;
+    create(input: CreateWebhookEndpointInput): Promise<WebhookEndpointSecretResult>;
+    get(webhookEndpointId: string, options?: ProxyCheckoutServerRequestOptions): Promise<WebhookEndpoint>;
+    update(webhookEndpointId: string, input: UpdateWebhookEndpointInput): Promise<WebhookEndpoint>;
+    archive(webhookEndpointId: string, options?: ProxyCheckoutServerRequestOptions): Promise<WebhookEndpoint>;
+    rotateSecret(webhookEndpointId: string, input: RotateWebhookEndpointSecretInput): Promise<WebhookEndpointSecretResult>;
+}
+export declare function verifyProxyWebhookSignature(input: VerifyProxyWebhookSignatureInput): boolean;
+export declare function constructProxyWebhookEvent(input: ConstructProxyWebhookEventInput): ProxyWebhookEvent;

package/dist/esm/version.d.ts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.4-pr-76.31.1";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.4-pr-76.31.1";
+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/esm/version.js

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

package/package.json

@@ -7,7 +7,7 @@
   "sideEffects": false,
   "type": "module",
   "types": "./dist/esm/index.d.ts",
-  "version": "0.0.4-pr-76.31.1",
+  "version": "0.0.4-pr-76.32.1",
   "devDependencies": {
     "@types/node": "^24.12.4",
     "@vitest/coverage-v8": "4.1.7",
@@ -16,9 +16,14 @@
   },
   "exports": {
     ".": {
-      "import": "./dist/esm/index.js",
-      "require": "./dist/cjs/index.js",
-      "types": "./dist/esm/index.d.ts"
+      "import": {
+        "default": "./dist/esm/index.js",
+        "types": "./dist/esm/index.d.ts"
+      },
+      "require": {
+        "default": "./dist/cjs/index.js",
+        "types": "./dist/cjs/index.d.cts"
+      }
     }
   },
   "files": [