@proxy-checkout/server-js 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Linus Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @proxy-checkout/server-js
+
+Server-side JavaScript SDK for merchant backends calling Proxy merchant APIs.
+
+## Exposed API Endpoints
+
+This package should expose the merchant-authenticated backend routes that exist today:
+
+| SDK method | HTTP endpoint | Purpose |
+| --- | --- | --- |
+| `proxy.sessions.create` | `POST /proxy_sessions` | Create a Proxy Elements session. |
+| `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.
+
+## Usage
+
+```ts
+import { createProxyCheckoutServerClient } from "@proxy-checkout/server-js";
+
+const proxy = createProxyCheckoutServerClient({
+  apiKey: process.env.PROXY_SECRET_KEY!,
+});
+
+const session = await proxy.sessions.create({
+  amountMinor: 5000,
+  buyerReference: "buyer_123",
+  currency: "usd",
+  cartSnapshot: {
+    items: [{ product_id: "prod_123", quantity: 1 }],
+  },
+  idempotencyKey: "order_123",
+});
+
+await proxy.sessions.payerHandoff(session.id);
+```
+
+Production calls default to `https://api.proxycheckout.com`. Tests, local
+development, and previews can pass `apiHost`.
+
+## First Publish Decisions
+
+The first public package version is intentionally `0.0.1` because the SDK API is
+early and expected to change. The npm package is MIT-licensed under the
+package-scoped `LICENSE` file.
+
+The package metadata is intentionally shaped for a public npm package, but the
+first publish still needs explicit owner approval for:
+
+- release automation, provenance, dist tags, and rollback ownership.

package/dist/client.d.ts

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

package/dist/client.js

@@ -0,0 +1,18 @@
+import { ProxyCheckoutHttpClient } from "./http-client.js";
+import { ProxySessionsResource } from "./sessions.js";
+export class ProxyCheckoutServerClient {
+    apiHost;
+    sessions;
+    constructor(options) {
+        const httpClient = new ProxyCheckoutHttpClient({
+            apiHost: options.apiHost,
+            apiKey: options.apiKey,
+            fetchImpl: options.fetch,
+        });
+        this.apiHost = httpClient.apiHost;
+        this.sessions = new ProxySessionsResource(httpClient);
+    }
+}
+export function createProxyCheckoutServerClient(options) {
+    return new ProxyCheckoutServerClient(options);
+}

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+export interface ProxyCheckoutApiErrorDetails {
+    readonly code?: string;
+    readonly requestId?: string;
+    readonly responseBody: unknown;
+    readonly statusCode: number;
+}
+export declare class ProxyCheckoutApiError extends Error {
+    readonly name = "ProxyCheckoutApiError";
+    readonly code: string | undefined;
+    readonly requestId: string | undefined;
+    readonly responseBody: unknown;
+    readonly statusCode: number;
+    constructor(message: string, details: ProxyCheckoutApiErrorDetails);
+}
+export declare function toApiError(statusCode: number, responseBody: unknown, headerRequestId?: string): ProxyCheckoutApiError;

package/dist/errors.js

@@ -0,0 +1,36 @@
+export class ProxyCheckoutApiError extends Error {
+    name = "ProxyCheckoutApiError";
+    code;
+    requestId;
+    responseBody;
+    statusCode;
+    constructor(message, details) {
+        super(message);
+        this.code = details.code;
+        this.requestId = details.requestId;
+        this.responseBody = details.responseBody;
+        this.statusCode = details.statusCode;
+    }
+}
+export function toApiError(statusCode, responseBody, headerRequestId) {
+    const error = readApiError(responseBody);
+    const message = error.message ?? `Proxy API request failed with status ${statusCode}.`;
+    return new ProxyCheckoutApiError(message, {
+        code: error.code,
+        requestId: error.requestId ?? headerRequestId,
+        responseBody,
+        statusCode,
+    });
+}
+function readApiError(responseBody) {
+    const body = isRecord(responseBody) ? responseBody : undefined;
+    const error = body && isRecord(body.error) ? body.error : undefined;
+    return {
+        code: typeof error?.code === "string" ? error.code : undefined,
+        message: typeof error?.message === "string" ? error.message : undefined,
+        requestId: typeof error?.request_id === "string" ? error.request_id : undefined,
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/http-client.d.ts

@@ -0,0 +1,16 @@
+import type { JsonValue, ProxyCheckoutFetch } from "./types.js";
+export interface ProxyCheckoutRequestOptions {
+    readonly idempotencyKey?: string;
+    readonly requestId?: string;
+}
+export declare class ProxyCheckoutHttpClient {
+    readonly apiHost: string;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    constructor({ apiHost, apiKey, fetchImpl, }: {
+        apiHost?: string;
+        apiKey: string;
+        fetchImpl?: ProxyCheckoutFetch;
+    });
+    request(method: "POST" | "PUT", path: string, body: JsonValue, options?: ProxyCheckoutRequestOptions): Promise<unknown>;
+}

package/dist/http-client.js

@@ -0,0 +1,78 @@
+import { toApiError } from "./errors.js";
+import { proxyCheckoutServerSdkUserAgent } from "./version.js";
+export class ProxyCheckoutHttpClient {
+    apiHost;
+    apiKey;
+    fetchImpl;
+    constructor({ apiHost, apiKey, fetchImpl, }) {
+        assertSecretKey(apiKey);
+        const resolvedFetch = fetchImpl ?? globalThis.fetch;
+        if (typeof resolvedFetch !== "function") {
+            throw new Error("Proxy Checkout server SDK requires a fetch implementation.");
+        }
+        this.apiHost = normalizeApiHost(apiHost);
+        this.apiKey = apiKey;
+        this.fetchImpl = resolvedFetch;
+    }
+    async request(method, path, body, options = {}) {
+        const response = await this.fetchImpl(`${this.apiHost}${path}`, {
+            body: JSON.stringify(body),
+            headers: buildHeaders(this.apiKey, options),
+            method,
+        });
+        const responseBody = await readResponseBody(response);
+        if (!response.ok) {
+            const headerRequestId = response.headers.get("x-request-id") || undefined;
+            throw toApiError(response.status, responseBody, headerRequestId);
+        }
+        return responseBody;
+    }
+}
+function buildHeaders(apiKey, options) {
+    const headers = {
+        accept: "application/json",
+        authorization: `Bearer ${apiKey}`,
+        "content-type": "application/json",
+        "user-agent": proxyCheckoutServerSdkUserAgent,
+    };
+    if (options.idempotencyKey !== undefined) {
+        headers["idempotency-key"] = options.idempotencyKey;
+    }
+    if (options.requestId !== undefined) {
+        headers["x-request-id"] = options.requestId;
+    }
+    return headers;
+}
+async function readResponseBody(response) {
+    const text = await response.text();
+    if (!text) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function assertSecretKey(apiKey) {
+    if (!apiKey.startsWith("sk_test_") && !apiKey.startsWith("sk_live_")) {
+        throw new Error("Proxy Checkout secret key must start with sk_test_ or sk_live_.");
+    }
+}
+function normalizeApiHost(apiHost) {
+    if (apiHost === undefined) {
+        return "https://api.proxycheckout.com";
+    }
+    let url;
+    try {
+        url = new URL(apiHost);
+    }
+    catch {
+        throw new Error(`Invalid apiHost URL: ${apiHost}. Make sure it is an absolute HTTP or HTTPS URL.`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`Invalid apiHost URL: ${apiHost}. Make sure it is an absolute HTTP or HTTPS URL.`);
+    }
+    return `${url.origin}${url.pathname}`.replace(/\/$/, "");
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createProxyCheckoutServerClient, ProxyCheckoutServerClient, } from "./client.js";
+export { ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails } from "./errors.js";
+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";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createProxyCheckoutServerClient, ProxyCheckoutServerClient, } from "./client.js";
+export { ProxyCheckoutApiError } from "./errors.js";
+export { ProxySessionCartResource, ProxySessionsResource, proxyCheckoutServerEndpoints, } from "./sessions.js";
+export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";

package/dist/sessions.d.ts

@@ -0,0 +1,72 @@
+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 ProxySession {
+    readonly expiresAt: string;
+    readonly id: string;
+    readonly integrationMode: string;
+    readonly status: string;
+}
+export interface PayerOpenedResult {
+    readonly amountMinor: number;
+    readonly cartDetails: JsonObject;
+    readonly currency: string;
+}
+export interface PayerHandoffResult {
+    readonly status: "payer_handoff_pending" | "payer_opened";
+}
+export interface SetProxySessionCartInput extends ProxyCheckoutServerRequestOptions {
+    readonly amountMinor: number;
+    readonly cartSnapshot: JsonObject;
+    readonly currency: string;
+}
+export interface ProxySessionCartResult {
+    readonly amountMinor: number;
+    readonly cartSnapshot: JsonObject;
+    readonly currency: string;
+}
+export declare const proxyCheckoutServerEndpoints: readonly [{
+    readonly method: "POST";
+    readonly operation: "sessions.create";
+    readonly path: "/proxy_sessions";
+}, {
+    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";
+}];
+export declare class ProxySessionsResource {
+    private readonly httpClient;
+    readonly cart: ProxySessionCartResource;
+    constructor(httpClient: ProxyCheckoutHttpClient);
+    create(input: CreateProxySessionInput): Promise<ProxySession>;
+    payerHandoff(proxySessionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<PayerHandoffResult>;
+    payerOpened(proxySessionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<PayerOpenedResult>;
+}
+export declare class ProxySessionCartResource {
+    private readonly httpClient;
+    constructor(httpClient: ProxyCheckoutHttpClient);
+    set(proxySessionId: string, input: SetProxySessionCartInput): Promise<ProxySessionCartResult>;
+}

package/dist/sessions.js

@@ -0,0 +1,144 @@
+export const proxyCheckoutServerEndpoints = [
+    {
+        method: "POST",
+        operation: "sessions.create",
+        path: "/proxy_sessions",
+    },
+    {
+        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",
+    },
+];
+export class ProxySessionsResource {
+    httpClient;
+    cart;
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+        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 payerHandoff(proxySessionId, options = {}) {
+        const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/payer_handoff`, {}, options);
+        const body = 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);
+        const body = requireJsonObject(response, "sessions.payerOpened");
+        return {
+            amountMinor: requireInteger(body.amount_minor, "sessions.payerOpened.amountMinor"),
+            cartDetails: requireJsonObject(body.cart_details, "sessions.payerOpened"),
+            currency: requireString(body.currency, "sessions.payerOpened.currency"),
+        };
+    }
+}
+export 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 = requireJsonObject(response, "sessions.cart.set");
+        return {
+            amountMinor: requireInteger(body.amount_minor, "sessions.cart.set.amountMinor"),
+            cartSnapshot: requireJsonObject(body.cart_snapshot, "sessions.cart.set"),
+            currency: requireString(body.currency, "sessions.cart.set.currency"),
+        };
+    }
+}
+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,
+    };
+}
+function removeUndefinedValues(input) {
+    return Object.fromEntries(Object.entries(input).filter((entry) => entry[1] !== undefined));
+}
+function toProxySession(response) {
+    const body = requireJsonObject(response, "sessions.create");
+    const status = requireString(body.status, "sessions.create.status");
+    const integrationMode = requireString(body.integration_mode, "sessions.create.integrationMode");
+    return {
+        expiresAt: requireString(body.expires_at, "sessions.create.expiresAt"),
+        id: requireString(body.id, "sessions.create.id"),
+        integrationMode,
+        status,
+    };
+}
+function requireJsonObject(value, operation) {
+    if (!isRecord(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 requireInteger(value, field) {
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new Error(`Proxy API response field ${field} must be an integer.`);
+    }
+    return value;
+}
+function requirePayerHandoffStatus(value) {
+    const status = 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 isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/types.d.ts

@@ -0,0 +1,14 @@
+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;
+}
+export interface ProxyCheckoutServerRequestOptions {
+    readonly requestId?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/version.d.ts

@@ -0,0 +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";

package/dist/version.js

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

package/package.json

@@ -0,0 +1,53 @@
+{
+  "description": "Server-side JavaScript SDK for Proxy merchant API calls.",
+  "license": "MIT",
+  "module": "./dist/index.js",
+  "name": "@proxy-checkout/server-js",
+  "private": false,
+  "sideEffects": false,
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "version": "0.0.1",
+  "devDependencies": {
+    "@types/node": "^24.12.4",
+    "@vitest/coverage-v8": "4.1.7",
+    "typescript": "^6.0.3",
+    "vitest": "4.1.7"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "proxy-checkout",
+    "checkout",
+    "payments",
+    "sdk"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "sdks/server-js",
+    "type": "git",
+    "url": "git+https://github.com/linuslabs/proxy.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test:all": "vitest run",
+    "test:coverage": "vitest run --coverage.enabled --coverage.reportsDirectory=coverage/all",
+    "test:coverage:changed": "vitest run --coverage.enabled --coverage.reportsDirectory=coverage/changed",
+    "test:coverage:integration": "vitest run --project integration --coverage.enabled --coverage.reportsDirectory=coverage/integration",
+    "test:coverage:unit": "vitest run --project unit --coverage.enabled --coverage.reportsDirectory=coverage/unit",
+    "test:integration": "vitest run --project integration",
+    "test:unit": "vitest run --project unit",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}