@proxy-checkout/server-js 0.0.2 → 0.0.3-prx-58.10.1

package/README.md

@@ -9,9 +9,12 @@ This package should expose the merchant-authenticated backend routes that exist
 | SDK method | HTTP endpoint | Purpose |
 | --- | --- | --- |
 | `proxy.sessions.create` | `POST /proxy_sessions` | Create a Proxy Elements session. |
+| `proxy.sessions.createHandoff` | `POST /proxy_sessions/handoff` | Create a Proxy session and atomically mark it ready for hosted payer handoff. |
+| `proxy.sessions.retrieve` | `GET /proxy_sessions/:id/merchant` | Retrieve current merchant-owned session state after a webhook or before creating PSP objects. |
 | `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. |
+| `proxy.sessions.payerOpened` | `POST /proxy_sessions/:id/payer_opened` | Record checkout open and read the current merchant session/cart state. |
+| `proxy.subscriptions.retrieve` | `GET /subscriptions/:id` | Retrieve current Proxy-linked subscription lifecycle state. |
 | `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. |
@@ -26,9 +29,11 @@ import { createProxyCheckoutServerClient } from "@proxy-checkout/server-js";
 
 const proxy = createProxyCheckoutServerClient({
   apiKey: process.env.PROXY_SECRET_KEY!,
+  publishableKey: process.env.PROXY_PUBLISHABLE_KEY!,
+  payHost: process.env.PROXY_PAY_HOST,
 });
 
-const session = await proxy.sessions.create({
+const handoff = await proxy.sessions.createHandoff({
   amountMinor: 5000,
   buyerReference: "buyer_123",
   currency: "usd",
@@ -38,7 +43,13 @@ const session = await proxy.sessions.create({
   idempotencyKey: "order_123",
 });
 
-await proxy.sessions.payerHandoff(session.id);
+console.log(handoff.handoffUrl);
+
+const currentSession = await proxy.sessions.retrieve(handoff.id);
+console.log(currentSession.buyerReference);
+
+const opened = await proxy.sessions.payerOpened(handoff.id);
+console.log(opened.buyerReference, opened.cartSnapshot);
 
 const endpoint = await proxy.webhookEndpoints.create({
   url: "https://example.com/proxy-webhooks",
@@ -48,16 +59,21 @@ const endpoint = await proxy.webhookEndpoints.create({
 console.log(endpoint.signingSecret);
 ```
 
-Verify outbound webhook signatures with the exact raw request body:
+Verify and parse outbound webhooks with the exact raw request body:
 
 ```ts
-import { verifyProxyWebhookSignature } from "@proxy-checkout/server-js";
+import { constructProxyWebhookEvent } from "@proxy-checkout/server-js";
 
-const ok = verifyProxyWebhookSignature({
+const event = constructProxyWebhookEvent({
   body: rawBodyBuffer,
   header: request.headers["proxy-signature"],
   secret: process.env.PROXY_WEBHOOK_SIGNING_SECRET!,
 });
+
+if (event.type === "subscription.renewed") {
+  const subscription = await proxy.subscriptions.retrieve(event.data.subscription_id);
+  console.log(subscription.currentPeriodEnd);
+}
 ```
 
 Production calls default to `https://api.proxycheckout.com`. Tests, local
@@ -65,7 +81,7 @@ development, and previews can pass `apiHost`.
 
 ## First Publish Decisions
 
-The first public package version is intentionally `0.0.1` because the SDK API is
+The first public package versions are intentionally `0.0.x` because the SDK API is
 early and expected to change. The npm package is MIT-licensed under the
 package-scoped `LICENSE` file.
 

package/dist/client.d.ts

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

package/dist/client.js

@@ -1,9 +1,11 @@
 import { ProxyCheckoutHttpClient } from "./http-client.js";
 import { ProxySessionsResource } from "./sessions.js";
+import { ProxySubscriptionsResource } from "./subscriptions.js";
 import { ProxyWebhookEndpointsResource } from "./webhooks.js";
 export class ProxyCheckoutServerClient {
     apiHost;
     sessions;
+    subscriptions;
     webhookEndpoints;
     constructor(options) {
         const httpClient = new ProxyCheckoutHttpClient({
@@ -12,7 +14,11 @@ export class ProxyCheckoutServerClient {
             fetchImpl: options.fetch,
         });
         this.apiHost = httpClient.apiHost;
-        this.sessions = new ProxySessionsResource(httpClient);
+        this.sessions = new ProxySessionsResource(httpClient, {
+            payHost: options.payHost,
+            publishableKey: options.publishableKey,
+        });
+        this.subscriptions = new ProxySubscriptionsResource(httpClient);
         this.webhookEndpoints = new ProxyWebhookEndpointsResource(httpClient);
     }
 }

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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 CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, ProxySessionsResource, proxyCheckoutServerEndpoints, type SetProxySessionCartInput, } from "./sessions.js";
+export { type MerchantProxySubscription, ProxySubscriptionsResource, proxyCheckoutSubscriptionEndpoints, } from "./subscriptions.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";
+export { type ConstructProxyWebhookEventInput, type CreateWebhookEndpointInput, constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, type ProxyWebhookEvent, proxyCheckoutWebhookEndpointEndpoints, type RotateWebhookEndpointSecretInput, type UpdateWebhookEndpointInput, type VerifyProxyWebhookSignatureInput, verifyProxyWebhookSignature, type WebhookEndpoint, type WebhookEndpointSecretResult, } from "./webhooks.js";

package/dist/index.js

@@ -1,5 +1,6 @@
 export { createProxyCheckoutServerClient, ProxyCheckoutServerClient, } from "./client.js";
 export { ProxyCheckoutApiError } from "./errors.js";
 export { ProxySessionCartResource, ProxySessionsResource, proxyCheckoutServerEndpoints, } from "./sessions.js";
+export { ProxySubscriptionsResource, proxyCheckoutSubscriptionEndpoints, } from "./subscriptions.js";
 export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";
-export { ProxyWebhookEndpointsResource, proxyCheckoutWebhookEndpointEndpoints, verifyProxyWebhookSignature, } from "./webhooks.js";
+export { constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, proxyCheckoutWebhookEndpointEndpoints, verifyProxyWebhookSignature, } from "./webhooks.js";

package/dist/response-validators.d.ts

@@ -0,0 +1,8 @@
+import type { JsonObject } from "./types.js";
+export declare function requireJsonObject(value: unknown, operation: string): JsonObject;
+export declare function requireString(value: unknown, field: string): string;
+export declare function requireNullableString(value: unknown, field: string): string | null;
+export declare function requireInteger(value: unknown, field: string): number;
+export declare function requireNullableInteger(value: unknown, field: string): number | null;
+export declare function requireBoolean(value: unknown, field: string): boolean;
+export declare function requireStringArrayOrNull(value: unknown, field: string): string[] | null;

package/dist/response-validators.js

@@ -0,0 +1,51 @@
+export function requireJsonObject(value, operation) {
+    if (!isRecord(value)) {
+        throw new Error(`Proxy API response for ${operation} must be a JSON object.`);
+    }
+    return value;
+}
+export function requireString(value, field) {
+    if (typeof value !== "string") {
+        throw new Error(`Proxy API response field ${field} must be a string.`);
+    }
+    return value;
+}
+export function requireNullableString(value, field) {
+    if (value === null) {
+        return null;
+    }
+    return requireString(value, field);
+}
+export 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;
+}
+export function requireNullableInteger(value, field) {
+    if (value === null) {
+        return null;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value)) {
+        throw new Error(`Proxy API response field ${field} must be an integer or null.`);
+    }
+    return value;
+}
+export function requireBoolean(value, field) {
+    if (typeof value !== "boolean") {
+        throw new Error(`Proxy API response field ${field} must be a boolean.`);
+    }
+    return value;
+}
+export function requireStringArrayOrNull(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;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/sessions.d.ts

@@ -16,16 +16,40 @@ export interface CreateProxySessionInput extends CreateProxySessionOptions {
         readonly phone?: string;
     };
 }
+export interface CreateProxySessionHandoffInput extends CreateProxySessionInput {
+    readonly payHost?: string;
+    readonly publishableKey?: string;
+}
 export interface ProxySession {
     readonly expiresAt: string;
     readonly id: string;
     readonly integrationMode: string;
     readonly status: string;
 }
-export interface PayerOpenedResult {
+export interface ProxySessionHandoff extends ProxySession {
+    readonly handoffUrl: string;
+    readonly status: "payer_handoff_pending" | "payer_opened";
+}
+export interface MerchantProxySession {
     readonly amountMinor: number;
-    readonly cartDetails: JsonObject;
+    readonly buyerReference: string;
+    readonly cartSnapshot: JsonObject;
+    readonly createdAt: string;
     readonly currency: string;
+    readonly expiresAt: string;
+    readonly id: string;
+    readonly idempotencyKey: string | null;
+    readonly integrationMode: string;
+    readonly metadata: JsonObject;
+    readonly payerContact: {
+        readonly email: string | null;
+        readonly phone: string | null;
+    } | null;
+    readonly status: string;
+    readonly updatedAt: string;
+}
+export interface PayerOpenedResult extends MerchantProxySession {
+    readonly status: "payer_opened";
 }
 export interface PayerHandoffResult {
     readonly status: "payer_handoff_pending" | "payer_opened";
@@ -44,6 +68,14 @@ export declare const proxyCheckoutServerEndpoints: readonly [{
     readonly method: "POST";
     readonly operation: "sessions.create";
     readonly path: "/proxy_sessions";
+}, {
+    readonly method: "POST";
+    readonly operation: "sessions.createHandoff";
+    readonly path: "/proxy_sessions/handoff";
+}, {
+    readonly method: "GET";
+    readonly operation: "sessions.retrieve";
+    readonly path: "/proxy_sessions/:id/merchant";
 }, {
     readonly method: "PUT";
     readonly operation: "sessions.cart.set";
@@ -59,9 +91,15 @@ export declare const proxyCheckoutServerEndpoints: readonly [{
 }];
 export declare class ProxySessionsResource {
     private readonly httpClient;
+    private readonly options;
     readonly cart: ProxySessionCartResource;
-    constructor(httpClient: ProxyCheckoutHttpClient);
+    constructor(httpClient: ProxyCheckoutHttpClient, options?: {
+        payHost?: string;
+        publishableKey?: string;
+    });
     create(input: CreateProxySessionInput): Promise<ProxySession>;
+    createHandoff(input: CreateProxySessionHandoffInput): Promise<ProxySessionHandoff>;
+    retrieve(proxySessionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<MerchantProxySession>;
     payerHandoff(proxySessionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<PayerHandoffResult>;
     payerOpened(proxySessionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<PayerOpenedResult>;
 }

package/dist/sessions.js

@@ -1,9 +1,20 @@
+import { requireInteger, requireJsonObject, requireNullableString, requireString, } from "./response-validators.js";
 export const 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",
@@ -22,9 +33,11 @@ export const proxyCheckoutServerEndpoints = [
 ];
 export class ProxySessionsResource {
     httpClient;
+    options;
     cart;
-    constructor(httpClient) {
+    constructor(httpClient, options = {}) {
         this.httpClient = httpClient;
+        this.options = options;
         this.cart = new ProxySessionCartResource(httpClient);
     }
     async create(input) {
@@ -34,6 +47,36 @@ export class ProxySessionsResource {
         });
         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);
+    }
     async payerHandoff(proxySessionId, options = {}) {
         const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/payer_handoff`, {}, options);
         const body = requireJsonObject(response, "sessions.payerHandoff");
@@ -43,12 +86,7 @@ export class ProxySessionsResource {
     }
     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"),
-        };
+        return toPayerOpenedResult(response);
     }
 }
 export class ProxySessionCartResource {
@@ -114,23 +152,67 @@ function toProxySession(response) {
         status,
     };
 }
-function requireJsonObject(value, operation) {
-    if (!isRecord(value)) {
-        throw new Error(`Proxy API response for ${operation} must be a JSON object.`);
-    }
-    return value;
+function toProxySessionHandoff(response) {
+    const body = requireJsonObject(response, "sessions.createHandoff");
+    const status = requirePayerHandoffStatus(body.status);
+    const integrationMode = requireString(body.integration_mode, "sessions.createHandoff.integrationMode");
+    return {
+        expiresAt: requireString(body.expires_at, "sessions.createHandoff.expiresAt"),
+        handoffUrl: "",
+        id: requireString(body.id, "sessions.createHandoff.id"),
+        integrationMode,
+        status,
+    };
+}
+function toMerchantProxySession(response) {
+    const body = requireJsonObject(response, "sessions.retrieve");
+    return {
+        amountMinor: requireInteger(body.amount_minor, "sessions.retrieve.amountMinor"),
+        buyerReference: requireString(body.buyer_reference, "sessions.retrieve.buyerReference"),
+        cartSnapshot: requireJsonObject(body.cart_snapshot, "sessions.retrieve.cartSnapshot"),
+        createdAt: requireString(body.created_at, "sessions.retrieve.createdAt"),
+        currency: requireString(body.currency, "sessions.retrieve.currency"),
+        expiresAt: requireString(body.expires_at, "sessions.retrieve.expiresAt"),
+        id: requireString(body.id, "sessions.retrieve.id"),
+        idempotencyKey: requireNullableString(body.idempotency_key, "sessions.retrieve.idempotencyKey"),
+        integrationMode: requireString(body.integration_mode, "sessions.retrieve.integrationMode"),
+        metadata: requireJsonObject(body.metadata, "sessions.retrieve.metadata"),
+        payerContact: requireNullablePayerContact(body.payer_contact),
+        status: requireString(body.status, "sessions.retrieve.status"),
+        updatedAt: requireString(body.updated_at, "sessions.retrieve.updatedAt"),
+    };
 }
-function requireString(value, field) {
-    if (typeof value !== "string") {
-        throw new Error(`Proxy API response field ${field} must be a string.`);
+function toPayerOpenedResult(response) {
+    const body = requireJsonObject(response, "sessions.payerOpened");
+    const status = requireString(body.status, "sessions.payerOpened.status");
+    if (status !== "payer_opened") {
+        throw new Error("Proxy API response field sessions.payerOpened.status is unsupported.");
     }
-    return value;
+    return {
+        amountMinor: requireInteger(body.amount_minor, "sessions.payerOpened.amountMinor"),
+        buyerReference: requireString(body.buyer_reference, "sessions.payerOpened.buyerReference"),
+        cartSnapshot: requireJsonObject(body.cart_snapshot, "sessions.payerOpened.cartSnapshot"),
+        createdAt: requireString(body.created_at, "sessions.payerOpened.createdAt"),
+        currency: requireString(body.currency, "sessions.payerOpened.currency"),
+        expiresAt: requireString(body.expires_at, "sessions.payerOpened.expiresAt"),
+        id: requireString(body.id, "sessions.payerOpened.id"),
+        idempotencyKey: requireNullableString(body.idempotency_key, "sessions.payerOpened.idempotencyKey"),
+        integrationMode: requireString(body.integration_mode, "sessions.payerOpened.integrationMode"),
+        metadata: requireJsonObject(body.metadata, "sessions.payerOpened.metadata"),
+        payerContact: requireNullablePayerContact(body.payer_contact, "sessions.payerOpened"),
+        status,
+        updatedAt: requireString(body.updated_at, "sessions.payerOpened.updatedAt"),
+    };
 }
-function requireInteger(value, field) {
-    if (typeof value !== "number" || !Number.isInteger(value)) {
-        throw new Error(`Proxy API response field ${field} must be an integer.`);
+function requireNullablePayerContact(value, operation = "sessions.retrieve") {
+    if (value === null) {
+        return null;
     }
-    return value;
+    const contact = requireJsonObject(value, `${operation}.payerContact`);
+    return {
+        email: requireNullableString(contact.email, `${operation}.payerContact.email`),
+        phone: requireNullableString(contact.phone, `${operation}.payerContact.phone`),
+    };
 }
 function requirePayerHandoffStatus(value) {
     const status = requireString(value, "sessions.payerHandoff.status");
@@ -139,6 +221,24 @@ function requirePayerHandoffStatus(value) {
     }
     throw new Error("Proxy API response field sessions.payerHandoff.status is unsupported.");
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+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/subscriptions.d.ts

@@ -0,0 +1,32 @@
+import type { ProxyCheckoutHttpClient } from "./http-client.js";
+import type { ProxyCheckoutServerRequestOptions } from "./types.js";
+export interface MerchantProxySubscription {
+    readonly buyerReference: string;
+    readonly cancelAtPeriodEnd: boolean;
+    readonly createdAt: string;
+    readonly currentPeriodEnd: string | null;
+    readonly currentPeriodStart: string | null;
+    readonly endedAt: string | null;
+    readonly id: string;
+    readonly latestInvoiceAmountMinor: number | null;
+    readonly latestInvoiceCurrency: string | null;
+    readonly latestInvoiceId: string | null;
+    readonly latestPaymentStatus: string | null;
+    readonly originalProxySessionId: string;
+    readonly providerCheckoutSessionId: string | null;
+    readonly providerSubscriptionId: string;
+    readonly psp: string;
+    readonly status: string;
+    readonly trialEnd: string | null;
+    readonly updatedAt: string;
+}
+export declare const proxyCheckoutSubscriptionEndpoints: readonly [{
+    readonly method: "GET";
+    readonly operation: "subscriptions.retrieve";
+    readonly path: "/subscriptions/:id";
+}];
+export declare class ProxySubscriptionsResource {
+    private readonly httpClient;
+    constructor(httpClient: ProxyCheckoutHttpClient);
+    retrieve(subscriptionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<MerchantProxySubscription>;
+}

package/dist/subscriptions.js

@@ -0,0 +1,41 @@
+import { requireBoolean, requireJsonObject, requireNullableInteger, requireNullableString, requireString, } from "./response-validators.js";
+export const proxyCheckoutSubscriptionEndpoints = [
+    {
+        method: "GET",
+        operation: "subscriptions.retrieve",
+        path: "/subscriptions/:id",
+    },
+];
+export class ProxySubscriptionsResource {
+    httpClient;
+    constructor(httpClient) {
+        this.httpClient = httpClient;
+    }
+    async retrieve(subscriptionId, options = {}) {
+        const response = await this.httpClient.request("GET", `/subscriptions/${encodeURIComponent(subscriptionId)}`, undefined, options);
+        return toMerchantProxySubscription(response);
+    }
+}
+function toMerchantProxySubscription(response) {
+    const body = requireJsonObject(response, "subscriptions.retrieve");
+    return {
+        buyerReference: requireString(body.buyer_reference, "subscriptions.retrieve.buyerReference"),
+        cancelAtPeriodEnd: requireBoolean(body.cancel_at_period_end, "subscriptions.retrieve.cancelAtPeriodEnd"),
+        createdAt: requireString(body.created_at, "subscriptions.retrieve.createdAt"),
+        currentPeriodEnd: requireNullableString(body.current_period_end, "subscriptions.retrieve.currentPeriodEnd"),
+        currentPeriodStart: requireNullableString(body.current_period_start, "subscriptions.retrieve.currentPeriodStart"),
+        endedAt: requireNullableString(body.ended_at, "subscriptions.retrieve.endedAt"),
+        id: requireString(body.id, "subscriptions.retrieve.id"),
+        latestInvoiceAmountMinor: requireNullableInteger(body.latest_invoice_amount_minor, "subscriptions.retrieve.latestInvoiceAmountMinor"),
+        latestInvoiceCurrency: requireNullableString(body.latest_invoice_currency, "subscriptions.retrieve.latestInvoiceCurrency"),
+        latestInvoiceId: requireNullableString(body.latest_invoice_id, "subscriptions.retrieve.latestInvoiceId"),
+        latestPaymentStatus: requireNullableString(body.latest_payment_status, "subscriptions.retrieve.latestPaymentStatus"),
+        originalProxySessionId: requireString(body.original_proxy_session_id, "subscriptions.retrieve.originalProxySessionId"),
+        providerCheckoutSessionId: requireNullableString(body.provider_checkout_session_id, "subscriptions.retrieve.providerCheckoutSessionId"),
+        providerSubscriptionId: requireString(body.provider_subscription_id, "subscriptions.retrieve.providerSubscriptionId"),
+        psp: requireString(body.psp, "subscriptions.retrieve.psp"),
+        status: requireString(body.status, "subscriptions.retrieve.status"),
+        trialEnd: requireNullableString(body.trial_end, "subscriptions.retrieve.trialEnd"),
+        updatedAt: requireString(body.updated_at, "subscriptions.retrieve.updatedAt"),
+    };
+}

package/dist/types.d.ts

@@ -8,6 +8,8 @@ export interface ProxyCheckoutServerClientOptions {
     readonly apiHost?: string;
     readonly apiKey: string;
     readonly fetch?: ProxyCheckoutFetch;
+    readonly payHost?: string;
+    readonly publishableKey?: string;
 }
 export interface ProxyCheckoutServerRequestOptions {
     readonly requestId?: string;

package/dist/version.d.ts

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

package/dist/version.js

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

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,15 @@ 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";
 export declare const proxyCheckoutWebhookEndpointEndpoints: readonly [{
     readonly method: "GET";
     readonly operation: "webhookEndpoints.list";
@@ -68,3 +77,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,6 @@
 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";
 export const proxyCheckoutWebhookEndpointEndpoints = [
     {
         method: "GET",
@@ -86,6 +88,26 @@ export function verifyProxyWebhookSignature(input) {
         .digest("hex");
     return parsed.signatures.some((signature) => timingSafeEqualString(expected, signature));
 }
+export function constructProxyWebhookEvent(input) {
+    if (!verifyProxyWebhookSignature(input)) {
+        throw new Error("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 +169,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-prx-58.10.1",
   "devDependencies": {
     "@types/node": "^24.12.4",
     "@vitest/coverage-v8": "4.1.7",