@proxy-checkout/server-js 0.0.2 → 0.0.3-pr-76.12.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/cart.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Typed cart-snapshot validation.
+ *
+ * The cart snapshot is merchant-defined and opaque to Proxy, so the SDK keeps
+ * the shape app-owned but standardizes the parse step: pass a zod-style schema
+ * (or a plain validator function) and get a typed cart or a structured error.
+ */
+/** A zod-style schema (`{ parse }`) or a plain validator function. */
+export type ProxyCartValidator<TCart> = {
+    parse: (value: unknown) => TCart;
+} | ((value: unknown) => TCart);
+/** Run a cart snapshot through a validator, wrapping failures in a structured SDK error. */
+export declare function parseProxyCart<TCart>(cartSnapshot: unknown, validator: ProxyCartValidator<TCart>): TCart;
+/** Optional extraction of a buyer reference embedded in the typed cart, for consistency checks. */
+export interface ProxyCartParseOptions<TCart> {
+    readonly getBuyerReference?: (cart: TCart) => string | null | undefined;
+}

package/dist/cart.js

@@ -0,0 +1,23 @@
+/**
+ * Typed cart-snapshot validation.
+ *
+ * The cart snapshot is merchant-defined and opaque to Proxy, so the SDK keeps
+ * the shape app-owned but standardizes the parse step: pass a zod-style schema
+ * (or a plain validator function) and get a typed cart or a structured error.
+ */
+import { ProxyCheckoutValidationError } from "./errors.js";
+/** Run a cart snapshot through a validator, wrapping failures in a structured SDK error. */
+export function parseProxyCart(cartSnapshot, validator) {
+    try {
+        return typeof validator === "function"
+            ? validator(cartSnapshot)
+            : validator.parse(cartSnapshot);
+    }
+    catch (cause) {
+        throw new ProxyCheckoutValidationError("Proxy cart snapshot failed validation.", {
+            cause,
+            code: "cart_invalid",
+            field: "cart_snapshot",
+        });
+    }
+}

package/dist/client.d.ts

@@ -1,9 +1,18 @@
+import { ProxyEventsResource } from "./events.js";
 import { ProxySessionsResource } from "./sessions.js";
+import { ProxySubscriptionsResource } from "./subscriptions.js";
 import type { ProxyCheckoutServerClientOptions } from "./types.js";
+import { ProxyWebhooksResource } from "./webhook-handler.js";
 import { ProxyWebhookEndpointsResource } from "./webhooks.js";
 export declare class ProxyCheckoutServerClient {
     readonly apiHost: string;
     readonly sessions: ProxySessionsResource;
+    readonly subscriptions: ProxySubscriptionsResource;
+    /** Current-state lifecycle resolver for signed webhook events. */
+    readonly events: ProxyEventsResource;
+    /** Webhook delivery handling: `handle`, `process`, `constructEvent`. */
+    readonly webhooks: ProxyWebhooksResource;
+    /** Webhook endpoint management API (create/list/rotate). */
     readonly webhookEndpoints: ProxyWebhookEndpointsResource;
     constructor(options: ProxyCheckoutServerClientOptions);
 }

package/dist/client.js

@@ -1,9 +1,18 @@
+import { ProxyEventsResource } from "./events.js";
 import { ProxyCheckoutHttpClient } from "./http-client.js";
 import { ProxySessionsResource } from "./sessions.js";
+import { ProxySubscriptionsResource } from "./subscriptions.js";
+import { ProxyWebhooksResource } from "./webhook-handler.js";
 import { ProxyWebhookEndpointsResource } from "./webhooks.js";
 export class ProxyCheckoutServerClient {
     apiHost;
     sessions;
+    subscriptions;
+    /** Current-state lifecycle resolver for signed webhook events. */
+    events;
+    /** Webhook delivery handling: `handle`, `process`, `constructEvent`. */
+    webhooks;
+    /** Webhook endpoint management API (create/list/rotate). */
     webhookEndpoints;
     constructor(options) {
         const httpClient = new ProxyCheckoutHttpClient({
@@ -12,7 +21,13 @@ 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.sessions);
+        this.events = new ProxyEventsResource(this.sessions, this.subscriptions);
+        this.webhooks = new ProxyWebhooksResource(this.events);
         this.webhookEndpoints = new ProxyWebhookEndpointsResource(httpClient);
     }
 }

package/dist/consistency.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Buyer-reference and session linkage consistency checks.
+ *
+ * Proxy current-state retrieval is the source of truth, but the SDK still
+ * guards that the records it stitches together actually belong to the same
+ * buyer and session before a merchant acts on them.
+ */
+import type { MerchantProxySession } from "./sessions.js";
+import type { MerchantProxySubscription } from "./subscriptions.js";
+/**
+ * Assert that a subscription belongs to the given original session and that the
+ * buyer references agree. Throws {@link ProxyCheckoutValidationError} otherwise.
+ */
+export declare function assertSubscriptionMatchesSession(subscription: Pick<MerchantProxySubscription, "buyerReference" | "id" | "originalProxySessionId">, session: Pick<MerchantProxySession, "buyerReference" | "id">): void;
+/**
+ * Assert that a cart-embedded buyer reference, when present, matches the session
+ * buyer reference. A `null`/`undefined` cart buyer reference is allowed (the
+ * cart simply does not carry one).
+ */
+export declare function assertCartBuyerReference(cartBuyerReference: string | null | undefined, session: Pick<MerchantProxySession, "buyerReference" | "id">): void;

package/dist/consistency.js

@@ -0,0 +1,32 @@
+/**
+ * Buyer-reference and session linkage consistency checks.
+ *
+ * Proxy current-state retrieval is the source of truth, but the SDK still
+ * guards that the records it stitches together actually belong to the same
+ * buyer and session before a merchant acts on them.
+ */
+import { ProxyCheckoutValidationError } from "./errors.js";
+/**
+ * Assert that a subscription belongs to the given original session and that the
+ * buyer references agree. Throws {@link ProxyCheckoutValidationError} otherwise.
+ */
+export function assertSubscriptionMatchesSession(subscription, session) {
+    if (subscription.originalProxySessionId !== session.id) {
+        throw new ProxyCheckoutValidationError(`Proxy subscription ${subscription.id} is not linked to session ${session.id}.`, { code: "subscription_session_mismatch", field: "original_proxy_session_id" });
+    }
+    if (subscription.buyerReference !== session.buyerReference) {
+        throw new ProxyCheckoutValidationError(`Proxy subscription ${subscription.id} buyer reference does not match session ${session.id}.`, { code: "buyer_reference_mismatch", field: "buyer_reference" });
+    }
+}
+/**
+ * Assert that a cart-embedded buyer reference, when present, matches the session
+ * buyer reference. A `null`/`undefined` cart buyer reference is allowed (the
+ * cart simply does not carry one).
+ */
+export function assertCartBuyerReference(cartBuyerReference, session) {
+    if (cartBuyerReference !== null &&
+        cartBuyerReference !== undefined &&
+        cartBuyerReference !== session.buyerReference) {
+        throw new ProxyCheckoutValidationError(`Proxy session ${session.id} cart buyer reference does not match the session buyer reference.`, { code: "buyer_reference_mismatch", field: "cart.buyerReference" });
+    }
+}

package/dist/errors.d.ts

@@ -4,6 +4,23 @@ export interface ProxyCheckoutApiErrorDetails {
     readonly responseBody: unknown;
     readonly statusCode: number;
 }
+export type ProxyCheckoutValidationCode = "buyer_reference_mismatch" | "cart_invalid" | "invalid_date" | "provider_binding_mismatch" | "subscription_session_mismatch";
+/**
+ * Raised when the SDK receives Proxy data it cannot safely normalize, for
+ * example an invalid date string, a cart snapshot that fails the merchant
+ * schema, or a buyer-reference / provider-binding consistency violation.
+ */
+export declare class ProxyCheckoutValidationError extends Error {
+    readonly name = "ProxyCheckoutValidationError";
+    readonly code: ProxyCheckoutValidationCode;
+    readonly field: string | undefined;
+    readonly cause: unknown;
+    constructor(message: string, details: {
+        code: ProxyCheckoutValidationCode;
+        field?: string;
+        cause?: unknown;
+    });
+}
 export declare class ProxyCheckoutApiError extends Error {
     readonly name = "ProxyCheckoutApiError";
     readonly code: string | undefined;

package/dist/errors.js

@@ -1,3 +1,20 @@
+/**
+ * Raised when the SDK receives Proxy data it cannot safely normalize, for
+ * example an invalid date string, a cart snapshot that fails the merchant
+ * schema, or a buyer-reference / provider-binding consistency violation.
+ */
+export class ProxyCheckoutValidationError extends Error {
+    name = "ProxyCheckoutValidationError";
+    code;
+    field;
+    cause;
+    constructor(message, details) {
+        super(message);
+        this.code = details.code;
+        this.field = details.field;
+        this.cause = details.cause;
+    }
+}
 export class ProxyCheckoutApiError extends Error {
     name = "ProxyCheckoutApiError";
     code;

package/dist/events.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Current-state lifecycle resolver for signed Proxy webhook events.
+ *
+ * A webhook is only a wakeup: this resolver re-reads the authoritative session
+ * and subscription state with the merchant secret key and returns a typed
+ * lifecycle decision. It never grants from webhook payload fields, and it
+ * classifies subscription events from current state rather than event order.
+ */
+import type { MerchantProxySession, ProxySessionsResource } from "./sessions.js";
+import type { MerchantProxySubscription, ProxySubscriptionsResource } from "./subscriptions.js";
+import type { ProxyCheckoutServerRequestOptions } from "./types.js";
+import type { ProxyWebhookEvent } from "./webhooks.js";
+export interface ResolveProxyEventOptions extends ProxyCheckoutServerRequestOptions {
+}
+interface ResolvedBase {
+    readonly event: ProxyWebhookEvent;
+}
+/**
+ * First paid/provisionable wakeup for a session. `subscription` is present when
+ * the event carried a subscription id; otherwise the merchant computes initial
+ * access from its own cart policy (`accessEndsAt`/`willRenew` are then null).
+ */
+export interface ResolvedInitialProvision extends ResolvedBase {
+    readonly accessEndsAt: Date | null;
+    readonly kind: "initial_provision";
+    readonly session: MerchantProxySession;
+    readonly subscription: MerchantProxySubscription | null;
+    readonly willRenew: boolean | null;
+}
+export interface ResolvedSubscriptionRenewed extends ResolvedBase {
+    readonly accessEndsAt: Date | null;
+    readonly kind: "subscription_renewed";
+    readonly session: MerchantProxySession;
+    readonly subscription: MerchantProxySubscription;
+    readonly willRenew: boolean;
+}
+export interface ResolvedSubscriptionCancelScheduled extends ResolvedBase {
+    readonly accessEndsAt: Date | null;
+    readonly kind: "subscription_cancel_scheduled";
+    readonly session: MerchantProxySession;
+    readonly subscription: MerchantProxySubscription;
+    readonly willRenew: false;
+}
+export interface ResolvedSubscriptionCancelled extends ResolvedBase {
+    readonly accessEndsAt: Date | null;
+    readonly kind: "subscription_cancelled";
+    readonly session: MerchantProxySession;
+    readonly subscription: MerchantProxySubscription;
+    readonly willRenew: false;
+}
+export interface ResolvedPaymentRisk extends ResolvedBase {
+    readonly accessEndsAt: Date | null;
+    readonly kind: "payment_risk";
+    readonly latestPaymentStatus: string | null;
+    readonly session: MerchantProxySession;
+    readonly subscription: MerchantProxySubscription;
+    readonly willRenew: boolean;
+}
+export interface ResolvedTerminalSession extends ResolvedBase {
+    readonly kind: "terminal_session";
+    readonly session: MerchantProxySession;
+}
+export interface ResolvedIgnored extends ResolvedBase {
+    readonly kind: "ignored";
+    readonly reason: string;
+    readonly sessionId: string | null;
+    readonly subscriptionId: string | null;
+}
+export type ResolvedProxyEvent = ResolvedInitialProvision | ResolvedSubscriptionRenewed | ResolvedSubscriptionCancelScheduled | ResolvedSubscriptionCancelled | ResolvedPaymentRisk | ResolvedTerminalSession | ResolvedIgnored;
+export type ResolvedProxyEventKind = ResolvedProxyEvent["kind"];
+export declare class ProxyEventsResource {
+    private readonly sessions;
+    private readonly subscriptions;
+    constructor(sessions: ProxySessionsResource, subscriptions: ProxySubscriptionsResource);
+    /**
+     * Resolve a signed webhook event into a current-state lifecycle decision by
+     * re-reading the authoritative session/subscription with the secret key.
+     */
+    resolveCurrentState(event: ProxyWebhookEvent, options?: ResolveProxyEventOptions): Promise<ResolvedProxyEvent>;
+    private resolveSessionEvent;
+    private resolveSubscriptionEvent;
+}
+export {};

package/dist/events.js

@@ -0,0 +1,147 @@
+/**
+ * Current-state lifecycle resolver for signed Proxy webhook events.
+ *
+ * A webhook is only a wakeup: this resolver re-reads the authoritative session
+ * and subscription state with the merchant secret key and returns a typed
+ * lifecycle decision. It never grants from webhook payload fields, and it
+ * classifies subscription events from current state rather than event order.
+ */
+import { assertSubscriptionMatchesSession } from "./consistency.js";
+import { isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, subscriptionAccessEndsAt, subscriptionWillRenew, } from "./lifecycle.js";
+import { isProxySessionEvent, isProxySubscriptionEvent } from "./webhook-events.js";
+export class ProxyEventsResource {
+    sessions;
+    subscriptions;
+    constructor(sessions, subscriptions) {
+        this.sessions = sessions;
+        this.subscriptions = subscriptions;
+    }
+    /**
+     * Resolve a signed webhook event into a current-state lifecycle decision by
+     * re-reading the authoritative session/subscription with the secret key.
+     */
+    async resolveCurrentState(event, options = {}) {
+        if (isProxySubscriptionEvent(event.type)) {
+            return this.resolveSubscriptionEvent(event, options);
+        }
+        if (isProxySessionEvent(event.type)) {
+            return this.resolveSessionEvent(event, options);
+        }
+        return ignored(event, `Event type ${event.type} is not a lifecycle event.`, {
+            sessionId: readEventString(event.data.proxy_session_id),
+            subscriptionId: readEventString(event.data.subscription_id),
+        });
+    }
+    async resolveSessionEvent(event, options) {
+        const sessionId = extractSessionId(event);
+        if (sessionId === null) {
+            return ignored(event, "Session event is missing proxy_session_id.", {
+                sessionId: null,
+                subscriptionId: readEventString(event.data.subscription_id),
+            });
+        }
+        const session = await this.sessions.retrieve(sessionId, options);
+        if (isSessionProvisionable(session)) {
+            const subscriptionId = readEventString(event.data.subscription_id);
+            let subscription = null;
+            if (subscriptionId !== null) {
+                subscription = await this.subscriptions.retrieve(subscriptionId, options);
+                assertSubscriptionMatchesSession(subscription, session);
+            }
+            return {
+                accessEndsAt: subscription === null ? null : subscriptionAccessEndsAt(subscription),
+                event,
+                kind: "initial_provision",
+                session,
+                subscription,
+                willRenew: subscription === null ? null : subscriptionWillRenew(subscription),
+            };
+        }
+        if (isSessionTerminal(session)) {
+            return { event, kind: "terminal_session", session };
+        }
+        return ignored(event, `Session ${session.id} status ${session.status} is not yet actionable.`, {
+            sessionId: session.id,
+            subscriptionId: null,
+        });
+    }
+    async resolveSubscriptionEvent(event, options) {
+        const subscriptionId = readEventString(event.data.subscription_id);
+        if (subscriptionId === null) {
+            return ignored(event, "Subscription event is missing subscription_id.", {
+                sessionId: readEventString(event.data.proxy_session_id),
+                subscriptionId: null,
+            });
+        }
+        const subscription = await this.subscriptions.retrieve(subscriptionId, options);
+        const session = await this.sessions.retrieve(subscription.originalProxySessionId, options);
+        assertSubscriptionMatchesSession(subscription, session);
+        const accessEndsAt = subscriptionAccessEndsAt(subscription);
+        if (isSubscriptionEnded(subscription)) {
+            return {
+                accessEndsAt,
+                event,
+                kind: "subscription_cancelled",
+                session,
+                subscription,
+                willRenew: false,
+            };
+        }
+        if (subscription.cancelAtPeriodEnd) {
+            return {
+                accessEndsAt,
+                event,
+                kind: "subscription_cancel_scheduled",
+                session,
+                subscription,
+                willRenew: false,
+            };
+        }
+        if (isSubscriptionPaymentAtRisk(subscription)) {
+            return {
+                accessEndsAt,
+                event,
+                kind: "payment_risk",
+                latestPaymentStatus: subscription.latestPaymentStatus,
+                session,
+                subscription,
+                willRenew: subscriptionWillRenew(subscription),
+            };
+        }
+        return {
+            accessEndsAt,
+            event,
+            kind: "subscription_renewed",
+            session,
+            subscription,
+            willRenew: subscriptionWillRenew(subscription),
+        };
+    }
+}
+function ignored(event, reason, ids) {
+    return {
+        event,
+        kind: "ignored",
+        reason,
+        sessionId: ids.sessionId,
+        subscriptionId: ids.subscriptionId,
+    };
+}
+/** Read the session id from an event, handling the nested `proxy_session.expired` payload. */
+function extractSessionId(event) {
+    const direct = readEventString(event.data.proxy_session_id);
+    if (direct !== null) {
+        return direct;
+    }
+    const nested = event.data.proxy_session;
+    if (isRecord(nested)) {
+        return readEventString(nested.id);
+    }
+    return null;
+}
+function readEventString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/index.d.ts

@@ -1,6 +1,13 @@
+export { type ProxyCartParseOptions, type ProxyCartValidator, parseProxyCart, } from "./cart.js";
 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 { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./consistency.js";
+export { ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails, type ProxyCheckoutValidationCode, ProxyCheckoutValidationError, } from "./errors.js";
+export { ProxyEventsResource, type ResolvedIgnored, type ResolvedInitialProvision, type ResolvedPaymentRisk, type ResolvedProxyEvent, type ResolvedProxyEventKind, type ResolvedSubscriptionCancelled, type ResolvedSubscriptionCancelScheduled, type ResolvedSubscriptionRenewed, type ResolvedTerminalSession, type ResolveProxyEventOptions, } from "./events.js";
+export { AT_RISK_SUBSCRIPTION_STATUSES, ENDED_SUBSCRIPTION_STATUSES, isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, PROVISIONABLE_SESSION_STATUSES, parseOptionalProxyDate, requireProxyDate, subscriptionAccessEndsAt, subscriptionWillRenew, TERMINAL_SESSION_STATUSES, } from "./lifecycle.js";
+export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";
+export { type MerchantProxySubscription, ProxySubscriptionsResource, type ProxySubscriptionWithSession, type ProxySubscriptionWithUntypedSession, 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 { isProxyPaymentAttemptEvent, isProxySessionEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, type ProxyWebhookEventType, } from "./webhook-events.js";
+export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
+export { type ConstructProxyWebhookEventInput, type CreateWebhookEndpointInput, constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, type ProxyWebhookEvent, ProxyWebhookSignatureVerificationError, proxyCheckoutWebhookEndpointEndpoints, type RotateWebhookEndpointSecretInput, type UpdateWebhookEndpointInput, type VerifyProxyWebhookSignatureInput, verifyProxyWebhookSignature, type WebhookEndpoint, type WebhookEndpointSecretResult, } from "./webhooks.js";

package/dist/index.js

@@ -1,5 +1,12 @@
+export { parseProxyCart, } from "./cart.js";
 export { createProxyCheckoutServerClient, ProxyCheckoutServerClient, } from "./client.js";
-export { ProxyCheckoutApiError } from "./errors.js";
+export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./consistency.js";
+export { ProxyCheckoutApiError, ProxyCheckoutValidationError, } from "./errors.js";
+export { ProxyEventsResource, } from "./events.js";
+export { AT_RISK_SUBSCRIPTION_STATUSES, ENDED_SUBSCRIPTION_STATUSES, isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, PROVISIONABLE_SESSION_STATUSES, parseOptionalProxyDate, requireProxyDate, subscriptionAccessEndsAt, subscriptionWillRenew, TERMINAL_SESSION_STATUSES, } from "./lifecycle.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 { isProxyPaymentAttemptEvent, isProxySessionEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, } from "./webhook-events.js";
+export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, ProxyWebhooksResource, } from "./webhook-handler.js";
+export { constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, ProxyWebhookSignatureVerificationError, proxyCheckoutWebhookEndpointEndpoints, verifyProxyWebhookSignature, } from "./webhooks.js";

package/dist/lifecycle.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 type { MerchantProxySession } from "./sessions.js";
+import type { MerchantProxySubscription } from "./subscriptions.js";
+/** Session statuses that mean the payer has paid and entitlement may be granted. */
+export declare const PROVISIONABLE_SESSION_STATUSES: Set<string>;
+/** Session statuses that are terminal — no further lifecycle transitions occur. */
+export declare const TERMINAL_SESSION_STATUSES: Set<string>;
+/** Subscription statuses that mean the subscription is no longer active. */
+export declare const ENDED_SUBSCRIPTION_STATUSES: Set<string>;
+/** Subscription statuses that indicate a payment problem on an otherwise live subscription. */
+export declare const AT_RISK_SUBSCRIPTION_STATUSES: Set<string>;
+/** Parse a required ISO date from Proxy, throwing a structured error when missing/invalid. */
+export declare function requireProxyDate(value: string | null | undefined, field: string): Date;
+/** Parse an optional ISO date from Proxy, returning null when absent and throwing when invalid. */
+export declare function parseOptionalProxyDate(value: string | null | undefined, field?: string): Date | null;
+/** True once the payer has paid / the session is provisionable for entitlement. */
+export declare function isSessionProvisionable(session: Pick<MerchantProxySession, "status">): boolean;
+/** True once the session has reached a terminal state. */
+export declare function isSessionTerminal(session: Pick<MerchantProxySession, "status">): boolean;
+/**
+ * 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 declare function subscriptionWillRenew(subscription: Pick<MerchantProxySubscription, "cancelAtPeriodEnd" | "endedAt" | "status">): boolean;
+/**
+ * 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 declare function subscriptionAccessEndsAt(subscription: Pick<MerchantProxySubscription, "currentPeriodEnd" | "endedAt">): Date | null;
+/** True when the subscription has ended (cancelled / expired / explicitly ended). */
+export declare function isSubscriptionEnded(subscription: Pick<MerchantProxySubscription, "endedAt" | "status">): boolean;
+/** True when the subscription is live but has a payment problem (past_due / unpaid / failed). */
+export declare function isSubscriptionPaymentAtRisk(subscription: Pick<MerchantProxySubscription, "latestPaymentStatus" | "status">): boolean;