@solvapay/server 1.0.9-preview.1 → 1.0.9

package/dist/index.d.ts

@@ -49,6 +49,58 @@ type WebhookEvent = {
 
 interface components {
     schemas: {
+        SdkMerchantResponseDto: {
+            /**
+             * Brand name shown in UI
+             * @example Acme
+             */
+            displayName: string;
+            /**
+             * Legal entity name used in SCA mandate copy
+             * @example Acme Inc.
+             */
+            legalName: string;
+            /** @example support@acme.com */
+            supportEmail?: string;
+            /** @example https://acme.com/support */
+            supportUrl?: string;
+            /** @example https://acme.com/terms */
+            termsUrl?: string;
+            /** @example https://acme.com/privacy */
+            privacyUrl?: string;
+            /**
+             * ISO-3166 alpha-2 country code of the merchant
+             * @example US
+             */
+            country?: string;
+            /**
+             * ISO-4217 default settlement currency
+             * @example usd
+             */
+            defaultCurrency?: string;
+            /**
+             * Descriptor appearing on the customer card statement
+             * @example ACME INC
+             */
+            statementDescriptor?: string;
+            /**
+             * Absolute URL to the merchant logo
+             * @example https://cdn.acme.com/logo.png
+             */
+            logoUrl?: string;
+            /**
+             * Absolute URL to the square app icon / logomark. Consumed by MCP host chromes, mobile avatar slots, and any surface where the landscape `logoUrl` would need letterboxing.
+             * @example https://cdn.acme.com/icon.png
+             */
+            iconUrl?: string;
+        };
+        SdkPlatformConfigResponseDto: {
+            /**
+             * SolvaPay's platform Stripe publishable key for the authenticated provider's environment. Safe to expose browser-side; paired with the connected `accountId` returned from `create-payment-intent` for Stripe Connect direct charges. Omitted when not configured so callers can fall back cleanly to a hosted flow.
+             * @example pk_test_...
+             */
+            stripePublishableKey?: string;
+        };
         CreatePaymentIntentDto: {
             productRef?: string;
             customerRef: string;
@@ -1047,6 +1099,14 @@ interface components {
             /** @description Active purchases */
             purchases?: components["schemas"]["PurchaseInfo"][];
         };
+        UpdateCustomerRequest: {
+            /** Format: email */
+            email?: string;
+            name?: string;
+            telephone?: string;
+            metadata?: unknown;
+            externalRef?: string;
+        };
         CreateCustomerSessionResponse: {
             /**
              * Customer session ID/token
@@ -1180,6 +1240,53 @@ interface components {
     pathItems: never;
 }
 interface operations {
+    getMerchant: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Merchant identity */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SdkMerchantResponseDto"];
+                };
+            };
+            /** @description Provider not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    getPlatformConfig: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Platform config */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SdkPlatformConfigResponseDto"];
+                };
+            };
+        };
+    };
     PaymentIntentSdkController_getPaymentIntents: {
         parameters: {
             query?: {
@@ -2258,7 +2365,7 @@ interface operations {
             };
         };
     };
-    CustomerSdkController_getCustomerBalance: {
+    CustomerSdkController_getCustomer: {
         parameters: {
             query?: never;
             header?: never;
@@ -2270,13 +2377,13 @@ interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Customer balance retrieved successfully */
+            /** @description Customer retrieved successfully */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": unknown;
+                    "application/json": components["schemas"]["CustomerResponse"];
                 };
             };
             /** @description Customer not found */
@@ -2290,7 +2397,7 @@ interface operations {
             };
         };
     };
-    CustomerSdkController_getCustomer: {
+    CustomerSdkController_updateCustomer: {
         parameters: {
             query?: never;
             header?: never;
@@ -2300,9 +2407,14 @@ interface operations {
             };
             cookie?: never;
         };
-        requestBody?: never;
+        /** @description Fields to update (all optional) */
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["UpdateCustomerRequest"];
+            };
+        };
         responses: {
-            /** @description Customer retrieved successfully */
+            /** @description Customer updated successfully */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -2311,6 +2423,43 @@ interface operations {
                     "application/json": components["schemas"]["CustomerResponse"];
                 };
             };
+            /** @description Invalid update payload */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Customer not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    CustomerSdkController_getCustomerBalance: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Customer reference identifier */
+                reference: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Customer balance retrieved successfully */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": unknown;
+                };
+            };
             /** @description Customer not found */
             404: {
                 headers: {
@@ -2435,6 +2584,43 @@ interface operations {
             };
         };
     };
+    PaymentMethodSdkController_getPaymentMethod: {
+        parameters: {
+            query: {
+                /** @description Customer reference (e.g. `customer_...`). */
+                customerRef: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The customer's default card, or `{ kind: 'none' }` when no card is on file. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @enum {string} */
+                        kind: "card";
+                        /** @example visa */
+                        brand: string;
+                        /** @example 4242 */
+                        last4: string;
+                        /** @example 12 */
+                        expMonth: number;
+                        /** @example 2030 */
+                        expYear: number;
+                    } | {
+                        /** @enum {string} */
+                        kind: "none";
+                    };
+                };
+            };
+        };
+    };
 }
 
 /**
@@ -2488,6 +2674,31 @@ interface ProcessPaymentResult {
     status: 'completed';
 }
 type ActivatePlanResult = components['schemas']['ActivatePlanResponseDto'];
+/**
+ * SDK-facing payment-method projection returned by
+ * `GET /v1/sdk/payment-method?customerRef=...`.
+ *
+ * Derived from the generated operation response so any backend shape
+ * change propagates through a single `npm run generate:types` run. The
+ * inline `oneOf` schema on the backend controller translates to a clean
+ * `{ kind: 'card', ... } | { kind: 'none' }` discriminated union here.
+ */
+type PaymentMethodInfo = operations['PaymentMethodSdkController_getPaymentMethod']['responses']['200']['content']['application/json'];
+/**
+ * SDK-facing merchant identity (source: GET /v1/sdk/merchant).
+ */
+type SdkMerchantResponse = components['schemas']['SdkMerchantResponseDto'];
+/**
+ * SDK-facing platform config (source: GET /v1/sdk/platform-config).
+ *
+ * Environment-aware platform values resolved against the authenticated
+ * provider. Primary consumer today is the MCP checkout app, which uses
+ * `stripePublishableKey` to boot Stripe.js for a CSP probe before a
+ * PaymentIntent exists.
+ */
+type SdkPlatformConfigResponse = components['schemas']['SdkPlatformConfigResponseDto'];
+/** SDK-facing product projection. Sourced from the existing OpenAPI spec. */
+type SdkProductResponse = components['schemas']['SdkProductResponse'];
 type McpBootstrapPlanInput = NonNullable<components['schemas']['McpBootstrapDto']['plans']>[number];
 type ToolPlanMappingInput = NonNullable<components['schemas']['McpBootstrapDto']['tools']>[number];
 type McpBootstrapRequest = components['schemas']['McpBootstrapDto'];
@@ -2551,11 +2762,41 @@ interface SolvaPayClient {
     createCustomer?(params: components['schemas']['CreateCustomerRequest']): Promise<{
         customerRef: string;
     }>;
+    /**
+     * PATCH: /v1/sdk/customers/{customerRef}
+     * Update mutable customer fields. Used by `ensureCustomer` to backfill
+     * `externalRef` on an existing email-matched customer, and exposed
+     * directly for integrators who need it.
+     */
+    updateCustomer?(customerRef: string, params: {
+        email?: string;
+        name?: string;
+        telephone?: string;
+        metadata?: Record<string, unknown>;
+        externalRef?: string;
+    }): Promise<{
+        customerRef: string;
+    }>;
     getCustomer(params: {
         customerRef?: string;
         externalRef?: string;
         email?: string;
     }): Promise<CustomerResponseMapped>;
+    /**
+     * SDK-facing merchant identity (GET /v1/sdk/merchant).
+     * Returns the subset of provider fields safe for browser consumption —
+     * used by `<MandateText>`, `<CheckoutSummary>`, and trust signals.
+     */
+    getMerchant?(): Promise<SdkMerchantResponse>;
+    /**
+     * SDK-facing platform config (GET /v1/sdk/platform-config).
+     * Returns environment-aware browser-safe values (resolved sandbox/live
+     * against the authenticated provider). Primary consumer today is the
+     * MCP checkout app, which uses `stripePublishableKey` to boot Stripe.js
+     * for a CSP probe before a PaymentIntent exists.
+     */
+    getPlatformConfig?(): Promise<SdkPlatformConfigResponse>;
+    getProduct?(productRef: string): Promise<SdkProductResponse>;
     listProducts?(): Promise<Array<{
         reference: string;
         name: string;
@@ -2634,6 +2875,9 @@ interface SolvaPayClient {
     createCheckoutSession(params: operations['CheckoutSessionSdkController_createCheckoutSession']['requestBody']['content']['application/json']): Promise<components['schemas']['CreateCheckoutSessionResponse']>;
     createCustomerSession(params: components['schemas']['CreateCustomerSessionRequest']): Promise<components['schemas']['CreateCustomerSessionResponse']>;
     activatePlan?(params: components['schemas']['ActivatePlanDto']): Promise<ActivatePlanResult>;
+    getPaymentMethod?(params: {
+        customerRef: string;
+    }): Promise<PaymentMethodInfo>;
 }
 
 /**
@@ -2670,6 +2914,15 @@ type PaywallStructuredContent = {
     product: string;
     checkoutUrl: string;
     message: string;
+    /**
+     * Quota balance at the moment the paywall tripped. Optional so
+     * older server versions (pre-balance-on-payment_required) stay
+     * compatible; the React `PaywallNotice.Message` prefers this
+     * structured data over the raw `message` when available.
+     */
+    balance?: LimitActivationBalance;
+    /** Rich product context from checkLimits (name, ref, provider slug/id) */
+    productDetails?: LimitActivationProduct;
 } | {
     kind: 'activation_required';
     /** Product ref from paywall metadata (or env default) */
@@ -2686,18 +2939,47 @@ type PaywallStructuredContent = {
     productDetails?: LimitActivationProduct;
 };
 /**
- * MCP tool result with optional paywall information
+ * Runtime type guard for `PaywallStructuredContent`.
+ *
+ * Used by the MCP registration layer to detect paywall-shaped tool results
+ * coming out of `.mcp()` so it knows whether to attach the `_meta.ui`
+ * envelope that tells MCP hosts which UI resource to open.
+ *
+ * @since 1.0.9
  */
-interface PaywallToolResult {
-    content?: Array<{
-        type: 'text' | 'image' | 'resource';
-        text?: string;
-        data?: string;
-        mimeType?: string;
-    }>;
-    isError?: boolean;
-    structuredContent?: PaywallStructuredContent | Record<string, unknown>;
-}
+declare function isPaywallStructuredContent(value: unknown): value is PaywallStructuredContent;
+/**
+ * Discriminated union returned from `paywall.decide(args, metadata)` that
+ * surfaces the pre-check outcome as data instead of an exception.
+ *
+ * Replaces the throw-based `PaywallError` control flow adapters previously
+ * relied on: `allow` carries the resolved customer ref + fresh
+ * `LimitResponseWithPlan` so the handler can run, while `gate` carries the
+ * ready-to-serialise `PaywallStructuredContent` so the adapter's
+ * `formatGate` can emit the transport-specific paywall response.
+ *
+ * The `args` field on `allow` is the same shape passed in — threaded
+ * through so callers can hand it directly to the handler without having
+ * to hold onto a reference across the call.
+ *
+ * @since 1.1.0
+ */
+type PaywallDecision<T> = {
+    outcome: 'allow';
+    args: T;
+    limits: LimitResponseWithPlan;
+    customerRef: string;
+} | {
+    outcome: 'gate';
+    gate: PaywallStructuredContent;
+    /**
+     * The `LimitResponseWithPlan` consulted when the gate tripped. May
+     * be `null` on degraded paths that couldn't produce a fresh
+     * response (defensive — normal flow always populates this).
+     */
+    limits: LimitResponseWithPlan | null;
+    customerRef: string;
+};
 
 /**
  * Configuration Options Type Definitions
@@ -2738,16 +3020,33 @@ interface RetryOptions {
      */
     onRetry?: (error: Error, attempt: number) => void;
 }
+/**
+ * Extra context passed into MCP tool handlers — structural copy of
+ * `McpToolExtra` from `@solvapay/mcp` kept here to avoid a build-time
+ * circular dependency between `@solvapay/server` and `@solvapay/mcp`.
+ *
+ * The canonical version lives in `@solvapay/mcp/types.ts`. Keep the two
+ * in lockstep — a `vitest` snapshot in `@solvapay/mcp` guards the
+ * shape.
+ */
 interface McpToolExtra {
     authInfo?: {
-        token: string;
-        clientId: string;
-        scopes: string[];
+        token?: string;
+        clientId?: string;
+        scopes?: string[];
         expiresAt?: number;
         extra?: Record<string, unknown>;
     };
     [key: string]: unknown;
 }
+/**
+ * MCP adapter options — structural copy of `McpAdapterOptions` from
+ * `@solvapay/mcp`.
+ */
+interface McpAdapterOptions {
+    getCustomerRef?: (args: any, extra?: McpToolExtra) => string | Promise<string>;
+    transformResponse?: (result: any) => any;
+}
 /**
  * Options for configuring payable protection
  */
@@ -2803,19 +3102,6 @@ interface NextAdapterOptions {
      */
     transformResponse?: (result: any) => any;
 }
-/**
- * MCP adapter options for MCP servers
- */
-interface McpAdapterOptions {
-    /**
-     * Extract customer reference from MCP args
-     */
-    getCustomerRef?: (args: any, extra?: McpToolExtra) => string | Promise<string>;
-    /**
-     * Transform the response before wrapping in MCP format
-     */
-    transformResponse?: (result: any) => any;
-}
 
 /**
  * Virtual Tools for MCP Server Monetization
@@ -3575,30 +3861,48 @@ declare function createSolvaPayClient(opts: ServerClientOptions): SolvaPayClient
  */
 
 /**
- * Error thrown when a paywall is triggered (purchase required or usage limit exceeded).
+ * Error representing a paywall gate outcome (purchase required or usage
+ * limit exceeded).
  *
- * This error is automatically thrown by the paywall protection system when:
- * - Customer doesn't have required purchase
- * - Customer has exceeded usage limits
- * - Customer needs to upgrade their plan
+ * Soft-deprecated since 1.1.0 as the internal control-flow signal —
+ * `paywall.decide()` returns a typed `PaywallDecision<T>` union instead,
+ * and adapters route gate outcomes through `formatGate` without
+ * throwing. `PaywallError` is retained as a compat shim for three paths
+ * that keep working without migration:
  *
- * The error includes structured content with checkout URLs and metadata for
- * building custom paywall UIs.
+ *  1. `paywall.protect(handler, ...)` still throws `PaywallError` on
+ *     gate outcomes (the legacy throw-based API).
+ *  2. Merchant code that `throw new PaywallError(...)` (or
+ *     `ctx.gate(reason)`, which is implemented on top of
+ *     `PaywallError`) — caught at the adapter boundary and routed
+ *     through `formatGate` so transport responses stay consistent.
+ *  3. Custom third-party adapters that didn't implement `formatGate` —
+ *     `AbstractAdapter.formatGate` falls back to wrapping in
+ *     `PaywallError` and delegating to `formatError`.
  *
- * @example
+ * The error includes structured content with checkout URLs and metadata
+ * for building custom paywall UIs.
+ *
+ * @example Preferred (decide()/formatGate)
  * ```typescript
- * import { PaywallError } from '@solvapay/server';
+ * const decision = await solvaPay.paywall.decide(args, { product })
+ * if (decision.outcome === 'gate') {
+ *   return res.status(402).json(paywallErrorToClientPayload(
+ *     new PaywallError(decision.gate.message, decision.gate),
+ *   ))
+ * }
+ * ```
  *
+ * @example Compat (try/catch on throw-based legacy path)
+ * ```typescript
  * try {
  *   const result = await payable.http(createTask)(req, res);
  *   return result;
  * } catch (error) {
  *   if (error instanceof PaywallError) {
- *     // Custom paywall handling
  *     return res.status(402).json({
  *       error: error.message,
  *       checkoutUrl: error.structuredContent.checkoutUrl,
- *       // Additional metadata available in error.structuredContent
  *     });
  *   }
  *   throw error;
@@ -3606,6 +3910,7 @@ declare function createSolvaPayClient(opts: ServerClientOptions): SolvaPayClient
  * ```
  *
  * @see {@link PaywallStructuredContent} for the structured content format
+ * @see {@link PaywallDecision} for the preferred decision-based API
  * @since 1.0.0
  */
 declare class PaywallError extends Error {
@@ -3620,76 +3925,114 @@ declare class PaywallError extends Error {
 }
 /** JSON body shape for HTTP adapters and MCP text content (stable fields for clients). */
 declare function paywallErrorToClientPayload(error: PaywallError): Record<string, unknown>;
-
 /**
- * MCP OAuth helper utilities.
+ * Handler-scoped context passed as the optional second positional
+ * argument to handlers registered via `paywall.protect(...)`.
+ *
+ * Backwards-compatible: existing one-arg handlers `(args) => ...`
+ * ignore the second argument and continue to work.
  *
- * These helpers are intentionally lightweight and do not verify JWT signatures.
- * Use them after token validation (for example via /v1/customer/auth/userinfo).
+ * Consumed by `@solvapay/mcp`'s `buildPayableHandler` to construct the
+ * `ResponseContext` merchant tools receive as their second argument.
  */
-declare class McpBearerAuthError extends Error {
-    constructor(message: string);
+interface ProtectHandlerContext {
+    /** Resolved backend customer ref (`cus_...`). */
+    customerRef: string;
+    /**
+     * The `LimitResponseWithPlan` consulted at pre-check time. Sourced
+     * from either the fresh `checkLimits` call on cache-miss or the
+     * cached entry on cache-hit. `null` only when the paywall is
+     * operating in a degraded mode that couldn't produce a limit
+     * response (defensive; normal flow always populates this).
+     */
+    limits: LimitResponseWithPlan | null;
+    /**
+     * Transport-level extra passed through adapter chains (e.g. the MCP
+     * adapter's `extra` bag holding `authInfo`). Opaque to `protect()`
+     * itself; forwarded verbatim so adapter-aware handlers can use it.
+     */
+    extra?: unknown;
 }
-type McpBearerCustomerRefOptions = {
-    claimPriority?: string[];
-};
-declare function extractBearerToken(authorization?: string | null): string | null;
-declare function decodeJwtPayload(token: string): Record<string, unknown>;
-declare function getCustomerRefFromJwtPayload(payload: Record<string, unknown>, options?: McpBearerCustomerRefOptions): string;
-declare function getCustomerRefFromBearerAuthHeader(authorization?: string | null, options?: McpBearerCustomerRefOptions): string;
 
-interface BuildAuthInfoFromBearerOptions extends McpBearerCustomerRefOptions {
-    clientId?: string;
-    defaultScopes?: string[];
-    includePayload?: boolean;
-}
-declare function buildAuthInfoFromBearer(authorization?: string | null, options?: BuildAuthInfoFromBearerOptions): McpToolExtra['authInfo'] | null;
+/**
+ * Pure state engine that classifies a `LimitResponseWithPlan` into a
+ * recovery-tool-specific `PaywallState`, and produces the human-readable
+ * gate / nudge message templates the MCP transport ships as
+ * `content[0].text` on gate/nudge responses.
+ *
+ * This module has no UI dependencies — it's framework-neutral so
+ * `@solvapay/server`, `@solvapay/mcp-core`, and any HTTP adapter can
+ * reuse the classification + copy. The text-only paywall design puts
+ * the full narration (including a clickable `checkoutUrl` for
+ * terminal-first hosts) on `gate.message`, and names exactly one
+ * primary recovery tool so LLMs chain naturally toward it.
+ */
 
-type RequestLike = {
-    method?: string;
-    path?: string;
-    headers?: Record<string, string | string[] | undefined>;
-    body?: unknown;
-    auth?: unknown;
-};
-type ResponseLike = {
-    status: (code: number) => ResponseLike;
-    json: (payload: unknown) => void;
-    setHeader: (name: string, value: string) => void;
-};
-type NextLike = () => void;
-type Middleware = (req: RequestLike, res: ResponseLike, next: NextLike) => void;
-interface OAuthAuthorizationServerOptions {
-    apiBaseUrl: string;
-    productRef: string;
-}
-interface McpOAuthBridgeOptions {
-    publicBaseUrl: string;
-    apiBaseUrl: string;
-    productRef: string;
-    mcpPath?: string;
-    requireAuth?: boolean;
-    authInfo?: BuildAuthInfoFromBearerOptions;
-    protectedResourcePath?: string;
-    authorizationServerPath?: string;
-}
-declare function getOAuthProtectedResourceResponse(publicBaseUrl: string): {
-    resource: string;
-    authorization_servers: string[];
-    scopes_supported: string[];
-};
-declare function getOAuthAuthorizationServerResponse({ apiBaseUrl, productRef, }: OAuthAuthorizationServerOptions): {
-    issuer: string;
-    authorization_endpoint: string;
-    token_endpoint: string;
-    registration_endpoint: string;
-    token_endpoint_auth_methods_supported: string[];
-    response_types_supported: string[];
-    grant_types_supported: string[];
-    scopes_supported: string[];
-    code_challenge_methods_supported: string[];
+/**
+ * Discriminated union describing which recovery path the customer
+ * needs. Every state maps to exactly one primary recovery tool except
+ * `reactivation_required`, which surfaces two alternatives (rare).
+ */
+type PaywallState = {
+    kind: 'activation_required';
+} | {
+    kind: 'topup_required';
+} | {
+    kind: 'upgrade_required';
+} | {
+    kind: 'reactivation_required';
 };
-declare function createMcpOAuthBridge(options: McpOAuthBridgeOptions): Middleware[];
+/**
+ * Classify a `LimitResponseWithPlan` (or `null` on degraded paths) into
+ * a `PaywallState`. Pure — safe to call multiple times per request.
+ *
+ * Precedence:
+ *  1. `activationRequired === true` — trumps everything else; the
+ *     backend explicitly flagged that no plan is live yet.
+ *  2. Usage-based plan out of credits — the customer has a plan but
+ *     ran out, so a topup is the right action. "Out of credits" is
+ *     determined from (in order): the nested
+ *     `balance.creditBalance === 0` block, the top-level
+ *     `creditBalance === 0` field, or `remaining === 0` as a
+ *     fallback for older backend responses that omit both credit
+ *     fields on usage-based plans.
+ *  3. Everything else → `upgrade_required`, including:
+ *     - `limits === null` (defensive),
+ *     - no active plan on the product,
+ *     - recurring plan at period cap (`remaining <= 0`).
+ *
+ * `reactivation_required` is deferred — it needs a distinct backend
+ * signal (future `LimitResponse.inactivePurchaseRef`) which isn't
+ * emitted yet. Kept in the type so downstream code compiles against
+ * the full discriminated union; `classifyPaywallState` will never
+ * return it under current backend behaviour.
+ */
+declare function classifyPaywallState(limits: LimitResponseWithPlan | null): PaywallState;
+/**
+ * Produce the terminal-friendly gate message. Names exactly one
+ * recovery tool (`upgrade` / `topup` / `activate_plan`), except for
+ * the rare `reactivation_required` path which names two alternatives
+ * (`manage_account` / `upgrade`). Inlines `gate.checkoutUrl` when
+ * present so terminal-only MCP hosts (Claude Code, CLI clients) can
+ * open a browser directly.
+ *
+ * Kept as a pure string so the adapter layer can concatenate it with
+ * an optional narrator prefix without parsing structured copy.
+ */
+declare function buildGateMessage(state: PaywallState, gate: PaywallStructuredContent): string;
+/**
+ * Low-balance / approaching-cap nudge copy used as a plain text suffix
+ * on a successful merchant response (no `structuredContent` switch, no
+ * view switch). Mirrors the `buildGateMessage` surface so nudges feel
+ * like a softer version of the same text-only nudge path.
+ *
+ * Receives the `PaywallState` the classifier would have produced if
+ * the customer had tripped the gate. `upgrade_required` and
+ * `topup_required` are the only kinds that currently produce nudge
+ * copy; the others are no-ops (shouldn't happen — nudges only fire
+ * on successful calls).
+ */
+declare function buildNudgeMessage(state: PaywallState, limits: LimitResponseWithPlan | null): string;
 
 /**
  * Utility functions for the SolvaPay Server SDK
@@ -3785,8 +4128,16 @@ declare function handleRouteError(error: unknown, operationName: string, default
  * and name from authenticated requests. Works with any framework that uses
  * the standard Web API Request (Express, Fastify, Next.js, Edge Functions, etc.).
  *
- * Uses dynamic imports to avoid requiring @solvapay/auth at build time,
- * making it suitable for edge runtime environments.
+ * Resolution order:
+ * 1. `x-user-id` header — set by Next.js-style middleware (unchanged).
+ * 2. `Authorization: Bearer <jwt>` — verified via HS256 when a secret is
+ *    configured (`SOLVAPAY_JWT_SECRET` or `SUPABASE_JWT_SECRET`), or
+ *    unverified-decoded when no secret is configured. The unverified path
+ *    covers platforms that verify JWTs at the gateway (e.g. Supabase Edge
+ *    with `verify_jwt = true`, which is the default) and asymmetric signing
+ *    keys (ES256/RS256) that the SDK does not have keys for.
+ * 3. Set `SOLVAPAY_AUTH_STRICT=true` to require cryptographic verification
+ *    inside the handler (the unverified-decode fallback is then disabled).
  *
  * @param request - Standard Web API Request object
  * @param options - Configuration options
@@ -4106,6 +4457,21 @@ declare function activatePlanCore(request: Request, body: {
     includeName?: boolean;
 }): Promise<ActivatePlanResult | ErrorResult>;
 
+/**
+ * Payment-method helpers (core).
+ *
+ * Thin wrapper over `GET /v1/sdk/payment-method`. Extracts the authenticated
+ * user from the request via `syncCustomerCore`, then asks the SolvaPay API
+ * for the customer's default card. Returns `{ kind: 'none' }` gracefully
+ * when no card is on file; any other failure surfaces as an `ErrorResult`.
+ */
+
+declare function getPaymentMethodCore(request: Request, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<PaymentMethodInfo | ErrorResult>;
+
 /**
  * Plans Helper (Core)
  *
@@ -4116,13 +4482,42 @@ declare function activatePlanCore(request: Request, body: {
 
 type Plan = components['schemas']['Plan'];
 /**
- * List plans - core implementation
+ * List plans - core implementation.
+ *
+ * Pass `options.solvaPay` to route through a pre-configured SolvaPay instance
+ * (e.g. stub-backed in examples). When omitted, the helper reads
+ * `SOLVAPAY_SECRET_KEY` from environment and constructs a real API client.
  */
-declare function listPlansCore(request: Request): Promise<{
+declare function listPlansCore(request: Request, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<{
     plans: Plan[];
     productRef: string;
 } | ErrorResult>;
 
+/**
+ * Merchant Helper (Core)
+ *
+ * Generic helper for GET /api/merchant — returns the SDK-facing merchant
+ * identity used by `<MandateText>`, `<CheckoutSummary>`, and trust signals.
+ * Works with standard Web API Request (Express, Fastify, Next.js, Edge).
+ */
+
+declare function getMerchantCore(_request: Request, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<SdkMerchantResponse | ErrorResult>;
+
+/**
+ * Product Helper (Core)
+ *
+ * Generic helper for GET /api/get-product?productRef=...
+ * Returns a single product by reference, used by the `useProduct` React hook.
+ */
+
+declare function getProductCore(request: Request, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<SdkProductResponse | ErrorResult>;
+
 interface PurchaseCheckResult {
     customerRef: string;
     email?: string;
@@ -4154,6 +4549,33 @@ declare function checkPurchaseCore(request: Request, options?: {
     includeName?: boolean;
 }): Promise<PurchaseCheckResult | ErrorResult>;
 
+/**
+ * Usage snapshot derived from the authenticated customer's active purchase.
+ *
+ * Shape matches the backend's `UserInfoUsageDto` so the React `useUsage`
+ * hook gets a canonical set of fields regardless of transport.
+ */
+interface GetUsageResult {
+    meterRef: string | null;
+    total: number | null;
+    used: number;
+    remaining: number | null;
+    /** 0–100, rounded to 2dp. `null` when `total` is unknown. */
+    percentUsed: number | null;
+    periodStart?: string;
+    periodEnd?: string;
+    /** Raw purchase ref the usage belongs to (when a usage-based plan is active). */
+    purchaseRef?: string;
+}
+/**
+ * Fetch the authenticated customer's usage snapshot for the active purchase.
+ *
+ * Derives the values from `checkPurchaseCore` — no extra backend call.
+ * Returns `null` values when no usage-based plan is active.
+ */
+declare function getUsageCore(request: Request, options?: {
+    solvaPay?: SolvaPay;
+}): Promise<GetUsageResult | ErrorResult>;
 declare function trackUsageCore(request: Request, body: {
     actionType?: 'transaction' | 'api_call' | 'hour' | 'email' | 'storage' | 'custom';
     units?: number;
@@ -4221,4 +4643,4 @@ declare function verifyWebhook({ body, signature, secret, }: {
     secret: string;
 }): WebhookEvent;
 
-export { type ActivatePlanResult, type AuthenticatedUser, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type McpAdapterOptions, McpBearerAuthError, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolExtra, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableFunction, type PayableOptions, type PaywallArgs, PaywallError, type PaywallMetadata, type PaywallStructuredContent, type PaywallToolResult, type ProcessPaymentResult, type PurchaseCheckResult, type RegisterVirtualToolsMcpOptions, type RetryOptions, type ServerClientOptions, type SolvaPay, type SolvaPayClient, type ToolPlanMappingInput, VIRTUAL_TOOL_DEFINITIONS, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, buildAuthInfoFromBearer, cancelPurchaseCore, checkPurchaseCore, type components, createCheckoutSessionCore, createCustomerSessionCore, createMcpOAuthBridge, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, createVirtualTools, decodeJwtPayload, extractBearerToken, getAuthenticatedUserCore, getCustomerBalanceCore, getCustomerRefFromBearerAuthHeader, getCustomerRefFromJwtPayload, getOAuthAuthorizationServerResponse, getOAuthProtectedResourceResponse, handleRouteError, isErrorResult, jsonSchemaToZodRawShape, listPlansCore, paywallErrorToClientPayload, processPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, syncCustomerCore, trackUsageCore, verifyWebhook, withRetry };
+export { type ActivatePlanResult, type AuthenticatedUser, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type GetUsageResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type LimitResponseWithPlan, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableFunction, type PayableOptions, type PaymentMethodInfo, type PaywallArgs, type PaywallDecision, PaywallError, type PaywallMetadata, type PaywallState, type PaywallStructuredContent, type ProcessPaymentResult, type ProtectHandlerContext, type PurchaseCheckResult, type RegisterVirtualToolsMcpOptions, type RetryOptions, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, type ToolPlanMappingInput, VIRTUAL_TOOL_DEFINITIONS, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, buildGateMessage, buildNudgeMessage, cancelPurchaseCore, checkPurchaseCore, classifyPaywallState, type components, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, createVirtualTools, getAuthenticatedUserCore, getCustomerBalanceCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, jsonSchemaToZodRawShape, listPlansCore, paywallErrorToClientPayload, processPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, syncCustomerCore, trackUsageCore, verifyWebhook, withRetry };