@proxy-checkout/server-js 0.0.1 → 0.0.2

package/README.md

@@ -12,10 +12,12 @@ This package should expose the merchant-authenticated backend routes that exist
 | `proxy.sessions.cart.set` | `PUT /proxy_sessions/:id/cart` | Replace the current cart snapshot before payment orchestration. |
 | `proxy.sessions.payerHandoff` | `POST /proxy_sessions/:id/payer_handoff` | Record merchant handoff issuance before the payer loads checkout. |
 | `proxy.sessions.payerOpened` | `POST /proxy_sessions/:id/payer_opened` | Record checkout open and read the current cart details. |
-
-The portal routes are intentionally excluded because they are Better Auth
-session-backed portal APIs. The PSP webhook route is also excluded because PSPs
-call it directly.
+| `proxy.webhookEndpoints.list` | `GET /webhook_endpoints` | List outbound merchant webhook endpoints. |
+| `proxy.webhookEndpoints.create` | `POST /webhook_endpoints` | Create an outbound endpoint and receive its one-time signing secret. |
+| `proxy.webhookEndpoints.get` | `GET /webhook_endpoints/:id` | Read one outbound endpoint. |
+| `proxy.webhookEndpoints.update` | `PATCH /webhook_endpoints/:id` | Update URL, event types, or active/inactive status. |
+| `proxy.webhookEndpoints.archive` | `POST /webhook_endpoints/:id/archive` | Archive an outbound endpoint. |
+| `proxy.webhookEndpoints.rotateSecret` | `POST /webhook_endpoints/:id/rotate_secret` | Rotate an outbound endpoint signing secret. |
 
 ## Usage
 
@@ -37,6 +39,25 @@ const session = await proxy.sessions.create({
 });
 
 await proxy.sessions.payerHandoff(session.id);
+
+const endpoint = await proxy.webhookEndpoints.create({
+  url: "https://example.com/proxy-webhooks",
+  eventTypes: ["proxy_session.paid", "proxy_session.expired"],
+});
+
+console.log(endpoint.signingSecret);
+```
+
+Verify outbound webhook signatures with the exact raw request body:
+
+```ts
+import { verifyProxyWebhookSignature } from "@proxy-checkout/server-js";
+
+const ok = verifyProxyWebhookSignature({
+  body: rawBodyBuffer,
+  header: request.headers["proxy-signature"],
+  secret: process.env.PROXY_WEBHOOK_SIGNING_SECRET!,
+});
 ```
 
 Production calls default to `https://api.proxycheckout.com`. Tests, local

package/dist/client.d.ts

@@ -1,8 +1,10 @@
 import { ProxySessionsResource } from "./sessions.js";
 import type { ProxyCheckoutServerClientOptions } from "./types.js";
+import { ProxyWebhookEndpointsResource } from "./webhooks.js";
 export declare class ProxyCheckoutServerClient {
     readonly apiHost: string;
     readonly sessions: ProxySessionsResource;
+    readonly webhookEndpoints: ProxyWebhookEndpointsResource;
     constructor(options: ProxyCheckoutServerClientOptions);
 }
 export declare function createProxyCheckoutServerClient(options: ProxyCheckoutServerClientOptions): ProxyCheckoutServerClient;

package/dist/client.js

@@ -1,8 +1,10 @@
 import { ProxyCheckoutHttpClient } from "./http-client.js";
 import { ProxySessionsResource } from "./sessions.js";
+import { ProxyWebhookEndpointsResource } from "./webhooks.js";
 export class ProxyCheckoutServerClient {
     apiHost;
     sessions;
+    webhookEndpoints;
     constructor(options) {
         const httpClient = new ProxyCheckoutHttpClient({
             apiHost: options.apiHost,
@@ -11,6 +13,7 @@ export class ProxyCheckoutServerClient {
         });
         this.apiHost = httpClient.apiHost;
         this.sessions = new ProxySessionsResource(httpClient);
+        this.webhookEndpoints = new ProxyWebhookEndpointsResource(httpClient);
     }
 }
 export function createProxyCheckoutServerClient(options) {

package/dist/http-client.d.ts

@@ -12,5 +12,5 @@ export declare class ProxyCheckoutHttpClient {
         apiKey: string;
         fetchImpl?: ProxyCheckoutFetch;
     });
-    request(method: "POST" | "PUT", path: string, body: JsonValue, options?: ProxyCheckoutRequestOptions): Promise<unknown>;
+    request(method: "GET" | "PATCH" | "POST" | "PUT", path: string, body?: JsonValue, options?: ProxyCheckoutRequestOptions): Promise<unknown>;
 }

package/dist/http-client.js

@@ -16,8 +16,8 @@ export class ProxyCheckoutHttpClient {
     }
     async request(method, path, body, options = {}) {
         const response = await this.fetchImpl(`${this.apiHost}${path}`, {
-            body: JSON.stringify(body),
-            headers: buildHeaders(this.apiKey, options),
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+            headers: buildHeaders(this.apiKey, options, body !== undefined),
             method,
         });
         const responseBody = await readResponseBody(response);
@@ -28,13 +28,15 @@ export class ProxyCheckoutHttpClient {
         return responseBody;
     }
 }
-function buildHeaders(apiKey, options) {
+function buildHeaders(apiKey, options, hasJsonBody) {
     const headers = {
         accept: "application/json",
         authorization: `Bearer ${apiKey}`,
-        "content-type": "application/json",
         "user-agent": proxyCheckoutServerSdkUserAgent,
     };
+    if (hasJsonBody) {
+        headers["content-type"] = "application/json";
+    }
     if (options.idempotencyKey !== undefined) {
         headers["idempotency-key"] = options.idempotencyKey;
     }

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export { ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails } from "./erro
 export { type CreateProxySessionInput, type CreateProxySessionOptions, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, ProxySessionsResource, proxyCheckoutServerEndpoints, type SetProxySessionCartInput, } from "./sessions.js";
 export type { JsonObject, JsonPrimitive, JsonValue, ProxyCheckoutFetch, ProxyCheckoutServerClientOptions, ProxyCheckoutServerRequestOptions, } from "./types.js";
 export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";
+export { type CreateWebhookEndpointInput, ProxyWebhookEndpointsResource, proxyCheckoutWebhookEndpointEndpoints, type RotateWebhookEndpointSecretInput, type UpdateWebhookEndpointInput, type VerifyProxyWebhookSignatureInput, verifyProxyWebhookSignature, type WebhookEndpoint, type WebhookEndpointSecretResult, } from "./webhooks.js";

package/dist/index.js

@@ -2,3 +2,4 @@ export { createProxyCheckoutServerClient, ProxyCheckoutServerClient, } from "./c
 export { ProxyCheckoutApiError } from "./errors.js";
 export { ProxySessionCartResource, ProxySessionsResource, proxyCheckoutServerEndpoints, } from "./sessions.js";
 export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";
+export { ProxyWebhookEndpointsResource, proxyCheckoutWebhookEndpointEndpoints, verifyProxyWebhookSignature, } from "./webhooks.js";

package/dist/version.d.ts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.1";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.1";
+export declare const proxyCheckoutServerSdkVersion = "0.0.2";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.2";

package/dist/version.js

@@ -1,3 +1,3 @@
 export const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export const proxyCheckoutServerSdkVersion = "0.0.1";
+export const proxyCheckoutServerSdkVersion = "0.0.2";
 export const proxyCheckoutServerSdkUserAgent = `${proxyCheckoutServerSdkName}/${proxyCheckoutServerSdkVersion}`;

package/dist/webhooks.d.ts

@@ -0,0 +1,70 @@
+import type { ProxyCheckoutHttpClient } from "./http-client.js";
+import type { 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 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;

package/dist/webhooks.js

@@ -0,0 +1,173 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+export const proxyCheckoutWebhookEndpointEndpoints = [
+    {
+        method: "GET",
+        operation: "webhookEndpoints.list",
+        path: "/webhook_endpoints",
+    },
+    {
+        method: "POST",
+        operation: "webhookEndpoints.create",
+        path: "/webhook_endpoints",
+    },
+    {
+        method: "GET",
+        operation: "webhookEndpoints.get",
+        path: "/webhook_endpoints/:id",
+    },
+    {
+        method: "PATCH",
+        operation: "webhookEndpoints.update",
+        path: "/webhook_endpoints/:id",
+    },
+    {
+        method: "POST",
+        operation: "webhookEndpoints.archive",
+        path: "/webhook_endpoints/:id/archive",
+    },
+    {
+        method: "POST",
+        operation: "webhookEndpoints.rotateSecret",
+        path: "/webhook_endpoints/:id/rotate_secret",
+    },
+];
+export class ProxyWebhookEndpointsResource {
+    httpClient;
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    async list(options = {}) {
+        const response = await this.httpClient.request("GET", "/webhook_endpoints", undefined, options);
+        const body = requireJsonObject(response, "webhookEndpoints.list");
+        const endpoints = body.webhook_endpoints;
+        if (!Array.isArray(endpoints)) {
+            throw new Error("Proxy API response field webhookEndpoints.list.webhookEndpoints must be an array.");
+        }
+        return endpoints.map(toWebhookEndpoint);
+    }
+    async create(input) {
+        const response = await this.httpClient.request("POST", "/webhook_endpoints", toWebhookEndpointBody(input), { requestId: input.requestId });
+        return toWebhookEndpointSecretResult(response, "webhookEndpoints.create");
+    }
+    async get(webhookEndpointId, options = {}) {
+        const response = await this.httpClient.request("GET", `/webhook_endpoints/${encodeURIComponent(webhookEndpointId)}`, undefined, options);
+        return toWebhookEndpointEnvelope(response, "webhookEndpoints.get");
+    }
+    async update(webhookEndpointId, input) {
+        const response = await this.httpClient.request("PATCH", `/webhook_endpoints/${encodeURIComponent(webhookEndpointId)}`, toWebhookEndpointBody(input), { requestId: input.requestId });
+        return toWebhookEndpointEnvelope(response, "webhookEndpoints.update");
+    }
+    async archive(webhookEndpointId, options = {}) {
+        const response = await this.httpClient.request("POST", `/webhook_endpoints/${encodeURIComponent(webhookEndpointId)}/archive`, undefined, options);
+        return toWebhookEndpointEnvelope(response, "webhookEndpoints.archive");
+    }
+    async rotateSecret(webhookEndpointId, input) {
+        const response = await this.httpClient.request("POST", `/webhook_endpoints/${encodeURIComponent(webhookEndpointId)}/rotate_secret`, {
+            previous_signing_secret_expires_at: input.previousSigningSecretExpiresAt instanceof Date
+                ? input.previousSigningSecretExpiresAt.toISOString()
+                : input.previousSigningSecretExpiresAt,
+        }, { requestId: input.requestId });
+        return toWebhookEndpointSecretResult(response, "webhookEndpoints.rotateSecret");
+    }
+}
+export function verifyProxyWebhookSignature(input) {
+    const parsed = parseSignatureHeader(input.header);
+    if (!parsed) {
+        return false;
+    }
+    const toleranceSeconds = input.toleranceSeconds ?? 300;
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (Math.abs(nowSeconds - parsed.timestamp) > toleranceSeconds) {
+        return false;
+    }
+    const body = typeof input.body === "string" ? input.body : input.body.toString("utf8");
+    const expected = createHmac("sha256", input.secret)
+        .update(`${parsed.timestamp}.${body}`)
+        .digest("hex");
+    return parsed.signatures.some((signature) => timingSafeEqualString(expected, signature));
+}
+function toWebhookEndpointBody(input) {
+    return {
+        ...(input.eventTypes === undefined ? {} : { event_types: input.eventTypes }),
+        ...(input.status === undefined ? {} : { status: input.status }),
+        ...(input.url === undefined ? {} : { url: input.url }),
+    };
+}
+function toWebhookEndpointSecretResult(response, operation) {
+    const body = requireJsonObject(response, operation);
+    return {
+        signingSecret: requireString(body.signing_secret, `${operation}.signingSecret`),
+        webhookEndpoint: toWebhookEndpoint(body.webhook_endpoint),
+    };
+}
+function toWebhookEndpointEnvelope(response, operation) {
+    const body = requireJsonObject(response, operation);
+    return toWebhookEndpoint(body.webhook_endpoint);
+}
+function toWebhookEndpoint(value) {
+    const body = requireJsonObject(value, "webhookEndpoint");
+    return {
+        createdAt: requireString(body.created_at, "webhookEndpoint.createdAt"),
+        eventSchemaVersion: requireString(body.event_schema_version, "webhookEndpoint.eventSchemaVersion"),
+        eventTypes: readStringArrayOrNull(body.event_types, "webhookEndpoint.eventTypes"),
+        id: requireString(body.id, "webhookEndpoint.id"),
+        previousSigningSecretExpiresAt: readStringOrNull(body.previous_signing_secret_expires_at, "webhookEndpoint.previousSigningSecretExpiresAt"),
+        status: requireString(body.status, "webhookEndpoint.status"),
+        updatedAt: requireString(body.updated_at, "webhookEndpoint.updatedAt"),
+        url: requireString(body.url, "webhookEndpoint.url"),
+    };
+}
+function parseSignatureHeader(header) {
+    if (!header) {
+        return undefined;
+    }
+    let timestamp;
+    const signatures = [];
+    for (const part of header.split(",")) {
+        const [rawKey, rawValue] = part.split("=", 2);
+        const key = rawKey?.trim();
+        const value = rawValue?.trim();
+        if (key === "t") {
+            timestamp = Number(value);
+        }
+        else if (key === "v1" && value) {
+            signatures.push(value);
+        }
+    }
+    if (timestamp === undefined || !Number.isSafeInteger(timestamp) || signatures.length === 0) {
+        return undefined;
+    }
+    return {
+        signatures,
+        timestamp,
+    };
+}
+function timingSafeEqualString(left, right) {
+    const leftBuffer = Buffer.from(left, "hex");
+    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.1",
+  "version": "0.0.2",
   "devDependencies": {
     "@types/node": "^24.12.4",
     "@vitest/coverage-v8": "4.1.7",