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

package/dist/lifecycle.js

@@ -0,0 +1,91 @@
+/**
+ * SDK-owned normalization of Proxy session and subscription lifecycle.
+ *
+ * These helpers turn raw Proxy state into the small set of derived facts a
+ * merchant entitlement layer actually needs (`willRenew`, `accessEndsAt`,
+ * terminal/provisionable predicates) so every customer does not re-encode
+ * Proxy lifecycle semantics by hand.
+ */
+import { ProxyCheckoutValidationError } from "./errors.js";
+/** Session statuses that mean the payer has paid and entitlement may be granted. */
+export const PROVISIONABLE_SESSION_STATUSES = new Set(["paid", "provisionable"]);
+/** Session statuses that are terminal — no further lifecycle transitions occur. */
+export const TERMINAL_SESSION_STATUSES = new Set([
+    "cancelled",
+    "expired",
+    "failed",
+    "provisioned",
+    "provisioning_failed",
+]);
+/** Subscription statuses that mean the subscription is no longer active. */
+export const ENDED_SUBSCRIPTION_STATUSES = new Set([
+    "canceled",
+    "ended",
+    "incomplete_expired",
+]);
+/** Subscription statuses that indicate a payment problem on an otherwise live subscription. */
+export const AT_RISK_SUBSCRIPTION_STATUSES = new Set(["past_due", "unpaid"]);
+/** Parse a required ISO date from Proxy, throwing a structured error when missing/invalid. */
+export function requireProxyDate(value, field) {
+    const date = parseOptionalProxyDate(value, field);
+    if (date === null) {
+        throw new ProxyCheckoutValidationError(`Proxy date field ${field} is required.`, {
+            code: "invalid_date",
+            field,
+        });
+    }
+    return date;
+}
+/** Parse an optional ISO date from Proxy, returning null when absent and throwing when invalid. */
+export function parseOptionalProxyDate(value, field = "date") {
+    if (value === null || value === undefined || value === "") {
+        return null;
+    }
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw new ProxyCheckoutValidationError(`Proxy date field ${field} is not a valid date.`, {
+            code: "invalid_date",
+            field,
+        });
+    }
+    return date;
+}
+/** True once the payer has paid / the session is provisionable for entitlement. */
+export function isSessionProvisionable(session) {
+    return PROVISIONABLE_SESSION_STATUSES.has(session.status);
+}
+/** True once the session has reached a terminal state. */
+export function isSessionTerminal(session) {
+    return TERMINAL_SESSION_STATUSES.has(session.status);
+}
+/**
+ * Whether the subscription is expected to renew at the end of the current period.
+ * A subscription will not renew once it is scheduled to cancel or has ended.
+ */
+export function subscriptionWillRenew(subscription) {
+    if (subscription.cancelAtPeriodEnd) {
+        return false;
+    }
+    if (subscription.endedAt !== null) {
+        return false;
+    }
+    return !ENDED_SUBSCRIPTION_STATUSES.has(subscription.status);
+}
+/**
+ * The instant at which paid access should end given current subscription state.
+ * Prefers an explicit `endedAt` (hard stop) over the current period boundary.
+ * Returns null when neither is known.
+ */
+export function subscriptionAccessEndsAt(subscription) {
+    return (parseOptionalProxyDate(subscription.endedAt, "subscription.endedAt") ??
+        parseOptionalProxyDate(subscription.currentPeriodEnd, "subscription.currentPeriodEnd"));
+}
+/** True when the subscription has ended (cancelled / expired / explicitly ended). */
+export function isSubscriptionEnded(subscription) {
+    return subscription.endedAt !== null || ENDED_SUBSCRIPTION_STATUSES.has(subscription.status);
+}
+/** True when the subscription is live but has a payment problem (past_due / unpaid / failed). */
+export function isSubscriptionPaymentAtRisk(subscription) {
+    return (AT_RISK_SUBSCRIPTION_STATUSES.has(subscription.status) ||
+        subscription.latestPaymentStatus === "failed");
+}

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

@@ -1,3 +1,4 @@
+import { type ProxyCartParseOptions, type ProxyCartValidator } from "./cart.js";
 import type { ProxyCheckoutHttpClient } from "./http-client.js";
 import type { JsonObject, ProxyCheckoutServerRequestOptions } from "./types.js";
 export interface CreateProxySessionOptions extends ProxyCheckoutServerRequestOptions {
@@ -16,16 +17,46 @@ 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 providerCheckoutSessionId: string | null;
+    readonly providerCheckoutSessionPsp: string | null;
+    readonly status: string;
+    readonly updatedAt: string;
+}
+export interface PayerOpenedResult extends MerchantProxySession {
+    readonly status: "payer_opened";
+}
+/** A merchant session with its cart snapshot validated against a merchant schema. */
+export interface TypedMerchantProxySession<TCart> extends MerchantProxySession {
+    readonly cart: TCart;
 }
 export interface PayerHandoffResult {
     readonly status: "payer_handoff_pending" | "payer_opened";
@@ -40,10 +71,28 @@ export interface ProxySessionCartResult {
     readonly cartSnapshot: JsonObject;
     readonly currency: string;
 }
+export interface RecordProviderBindingInput extends ProxyCheckoutServerRequestOptions {
+    readonly providerCheckoutSessionId: string;
+    readonly psp: string;
+}
+export interface ProxySessionProviderBinding {
+    readonly providerCheckoutSessionId: string;
+    readonly proxySessionId: string;
+    readonly psp: string;
+    readonly updatedAt: string;
+}
 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";
@@ -56,14 +105,42 @@ export declare const proxyCheckoutServerEndpoints: readonly [{
     readonly method: "POST";
     readonly operation: "sessions.payerOpened";
     readonly path: "/proxy_sessions/:id/payer_opened";
+}, {
+    readonly method: "POST";
+    readonly operation: "sessions.providerBindings.create";
+    readonly path: "/proxy_sessions/:id/provider_bindings";
 }];
 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>;
+    /**
+     * Retrieve a session and validate its cart snapshot against a merchant schema,
+     * returning the session with a typed `cart`. Throws a structured error if the
+     * cart fails validation or its buyer reference disagrees with the session.
+     */
+    retrieveTyped<TCart>(proxySessionId: string, cartSchema: ProxyCartValidator<TCart>, options?: ProxyCheckoutServerRequestOptions & ProxyCartParseOptions<TCart>): Promise<TypedMerchantProxySession<TCart>>;
+    /**
+     * Validate the cart snapshot of an already-retrieved session against a merchant
+     * schema. When `getBuyerReference` is supplied, the cart buyer reference is
+     * asserted to match the session buyer reference.
+     */
+    parseCart<TCart>(session: MerchantProxySession, cartSchema: ProxyCartValidator<TCart>, options?: ProxyCartParseOptions<TCart>): TCart;
     payerHandoff(proxySessionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<PayerHandoffResult>;
     payerOpened(proxySessionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<PayerOpenedResult>;
+    /**
+     * Bind a provider (PSP) checkout object to a Proxy session so later cart sync
+     * can verify ownership. Idempotent for the same provider object; conflicts when
+     * the session is already bound to a different one.
+     */
+    recordProviderBinding(proxySessionId: string, input: RecordProviderBindingInput): Promise<ProxySessionProviderBinding>;
 }
 export declare class ProxySessionCartResource {
     private readonly httpClient;

package/dist/sessions.js

@@ -1,9 +1,22 @@
+import { parseProxyCart } from "./cart.js";
+import { assertCartBuyerReference } from "./consistency.js";
+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",
@@ -19,12 +32,19 @@ export const proxyCheckoutServerEndpoints = [
         operation: "sessions.payerOpened",
         path: "/proxy_sessions/:id/payer_opened",
     },
+    {
+        method: "POST",
+        operation: "sessions.providerBindings.create",
+        path: "/proxy_sessions/:id/provider_bindings",
+    },
 ];
 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 +54,57 @@ 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);
+    }
+    /**
+     * Retrieve a session and validate its cart snapshot against a merchant schema,
+     * returning the session with a typed `cart`. Throws a structured error if the
+     * cart fails validation or its buyer reference disagrees with the session.
+     */
+    async retrieveTyped(proxySessionId, cartSchema, options = {}) {
+        const session = await this.retrieve(proxySessionId, { requestId: options.requestId });
+        return { ...session, cart: this.parseCart(session, cartSchema, options) };
+    }
+    /**
+     * Validate the cart snapshot of an already-retrieved session against a merchant
+     * schema. When `getBuyerReference` is supplied, the cart buyer reference is
+     * asserted to match the session buyer reference.
+     */
+    parseCart(session, cartSchema, options = {}) {
+        const cart = parseProxyCart(session.cartSnapshot, cartSchema);
+        if (options.getBuyerReference !== undefined) {
+            assertCartBuyerReference(options.getBuyerReference(cart), session);
+        }
+        return cart;
+    }
     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,11 +114,24 @@ 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 toPayerOpenedResult(response);
+    }
+    /**
+     * Bind a provider (PSP) checkout object to a Proxy session so later cart sync
+     * can verify ownership. Idempotent for the same provider object; conflicts when
+     * the session is already bound to a different one.
+     */
+    async recordProviderBinding(proxySessionId, input) {
+        const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/provider_bindings`, {
+            provider_checkout_session_id: input.providerCheckoutSessionId,
+            psp: input.psp,
+        }, { requestId: input.requestId });
+        const body = requireJsonObject(response, "sessions.providerBindings.create");
         return {
-            amountMinor: requireInteger(body.amount_minor, "sessions.payerOpened.amountMinor"),
-            cartDetails: requireJsonObject(body.cart_details, "sessions.payerOpened"),
-            currency: requireString(body.currency, "sessions.payerOpened.currency"),
+            providerCheckoutSessionId: requireString(body.provider_checkout_session_id, "sessions.providerBindings.create.providerCheckoutSessionId"),
+            proxySessionId: requireString(body.proxy_session_id, "sessions.providerBindings.create.proxySessionId"),
+            psp: requireString(body.psp, "sessions.providerBindings.create.psp"),
+            updatedAt: requireString(body.updated_at, "sessions.providerBindings.create.updatedAt"),
         };
     }
 }
@@ -114,23 +198,72 @@ 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 requireString(value, field) {
-    if (typeof value !== "string") {
-        throw new Error(`Proxy API response field ${field} must be a string.`);
+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),
+        providerCheckoutSessionId: requireNullableString(body.provider_checkout_session_id, "sessions.retrieve.providerCheckoutSessionId"),
+        providerCheckoutSessionPsp: requireNullableString(body.provider_checkout_session_psp, "sessions.retrieve.providerCheckoutSessionPsp"),
+        status: requireString(body.status, "sessions.retrieve.status"),
+        updatedAt: requireString(body.updated_at, "sessions.retrieve.updatedAt"),
+    };
+}
+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"),
+        // No provider binding exists yet at payer-open; it is recorded after checkout creation.
+        providerCheckoutSessionId: null,
+        providerCheckoutSessionPsp: null,
+        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 +272,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,54 @@
+import type { ProxyCartParseOptions, ProxyCartValidator } from "./cart.js";
+import type { ProxyCheckoutHttpClient } from "./http-client.js";
+import type { MerchantProxySession, ProxySessionsResource, TypedMerchantProxySession } from "./sessions.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";
+}];
+/** A subscription paired with its verified original session (and optional typed cart). */
+export interface ProxySubscriptionWithSession<TCart> {
+    readonly cart: TCart;
+    readonly session: TypedMerchantProxySession<TCart>;
+    readonly subscription: MerchantProxySubscription;
+}
+export interface ProxySubscriptionWithUntypedSession {
+    readonly session: MerchantProxySession;
+    readonly subscription: MerchantProxySubscription;
+}
+export declare class ProxySubscriptionsResource {
+    private readonly httpClient;
+    private readonly sessions;
+    constructor(httpClient: ProxyCheckoutHttpClient, sessions: ProxySessionsResource);
+    retrieve(subscriptionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<MerchantProxySubscription>;
+    /**
+     * Retrieve a subscription together with the original Proxy session it was
+     * created from, asserting buyer/session linkage. When `cartSchema` is given the
+     * session cart is validated and returned typed.
+     */
+    retrieveWithOriginalSession(subscriptionId: string, options?: ProxyCheckoutServerRequestOptions): Promise<ProxySubscriptionWithUntypedSession>;
+    retrieveWithOriginalSession<TCart>(subscriptionId: string, options: ProxyCheckoutServerRequestOptions & ProxyCartParseOptions<TCart> & {
+        cartSchema: ProxyCartValidator<TCart>;
+    }): Promise<ProxySubscriptionWithSession<TCart>>;
+}

package/dist/subscriptions.js

@@ -0,0 +1,55 @@
+import { assertSubscriptionMatchesSession } from "./consistency.js";
+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;
+    sessions;
+    constructor(httpClient, sessions) {
+        this.httpClient = httpClient;
+        this.sessions = sessions;
+    }
+    async retrieve(subscriptionId, options = {}) {
+        const response = await this.httpClient.request("GET", `/subscriptions/${encodeURIComponent(subscriptionId)}`, undefined, options);
+        return toMerchantProxySubscription(response);
+    }
+    async retrieveWithOriginalSession(subscriptionId, options = {}) {
+        const requestOptions = { requestId: options.requestId };
+        const subscription = await this.retrieve(subscriptionId, requestOptions);
+        const session = await this.sessions.retrieve(subscription.originalProxySessionId, requestOptions);
+        assertSubscriptionMatchesSession(subscription, session);
+        if (options.cartSchema === undefined) {
+            return { session, subscription };
+        }
+        const cart = this.sessions.parseCart(session, options.cartSchema, options);
+        return { cart, session: { ...session, cart }, subscription };
+    }
+}
+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.1";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.1";
+export declare const proxyCheckoutServerSdkVersion = "0.0.3-pr-76.12.1";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.3-pr-76.12.1";

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.3-pr-76.12.1";
 export const proxyCheckoutServerSdkUserAgent = `${proxyCheckoutServerSdkName}/${proxyCheckoutServerSdkVersion}`;