@solvapay/mcp-core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1167 @@
+import { ZodTypeAny } from 'zod';
+import { PurchaseCheckResult, PaymentMethodInfo, CustomerBalanceResult, GetUsageResult, SdkMerchantResponse, SdkProductResponse, components, PaywallStructuredContent, SolvaPay, PaywallError } from '@solvapay/server';
+
+/**
+ * Canonical MCP tool names for the SolvaPay transport + bootstrap tools.
+ *
+ * Single source of truth for `@solvapay/mcp-core`, `@solvapay/mcp`,
+ * `@solvapay/react/mcp/adapter`, and any third-party adapter (fastmcp,
+ * raw JSON-RPC, etc.). Adding a new tool means editing exactly one file.
+ */
+declare const MCP_TOOL_NAMES: {
+    readonly createPayment: "create_payment_intent";
+    readonly processPayment: "process_payment";
+    readonly createTopupPayment: "create_topup_payment_intent";
+    readonly cancelRenewal: "cancel_renewal";
+    readonly reactivateRenewal: "reactivate_renewal";
+    readonly activatePlan: "activate_plan";
+    readonly createCheckoutSession: "create_checkout_session";
+    readonly createCustomerSession: "create_customer_session";
+    readonly upgrade: "upgrade";
+    readonly manageAccount: "manage_account";
+    readonly topup: "topup";
+};
+type McpToolName = (typeof MCP_TOOL_NAMES)[keyof typeof MCP_TOOL_NAMES];
+
+/**
+ * Framework-neutral MCP contracts shared across every SolvaPay MCP adapter.
+ *
+ * These types are intentionally free of `@modelcontextprotocol/*` imports
+ * so adapters for `fastmcp`, or raw JSON-RPC servers can consume them
+ * without pulling in the official SDK.
+ *
+ * The `ZodTypeAny`-shaped `inputSchema` keeps zod as an optional peer.
+ * Adapters that don't use zod can still pass equivalent shapes.
+ */
+
+/**
+ * Merchant identity surfaced on every `BootstrapPayload`. Structural
+ * alias for the server's `SdkMerchantResponse` so the React shell can
+ * hydrate `<MandateText>` and the rest of the trust-signal surface
+ * without an extra fetch.
+ */
+type BootstrapMerchant = SdkMerchantResponse;
+/**
+ * Product projection surfaced on every `BootstrapPayload`. Structural
+ * alias for the server's `SdkProductResponse`.
+ */
+type BootstrapProduct = SdkProductResponse;
+/**
+ * Plan projection surfaced on every `BootstrapPayload`. Structural
+ * alias for the generated `Plan` schema so the embedded checkout can
+ * mount its plan picker from the snapshot.
+ */
+type BootstrapPlan = components['schemas']['Plan'];
+/**
+ * Per-customer snapshot surfaced on every `BootstrapPayload`. Null when
+ * unauthenticated; individual fields are null when the corresponding
+ * sub-read errored or doesn't apply.
+ */
+interface BootstrapCustomer {
+    ref: string;
+    purchase: PurchaseCheckResult | null;
+    paymentMethod: PaymentMethodInfo | null;
+    balance: CustomerBalanceResult | null;
+    usage: GetUsageResult | null;
+}
+/**
+ * MCP tool call result — a structural subset of the official SDK's
+ * `CallToolResult` that every framework produces. Kept local to avoid
+ * coupling to `@modelcontextprotocol/sdk/types.js` type churn.
+ */
+/**
+ * Routing hint surfaced on individual content blocks. Mirrors the MCP
+ * `Annotations.audience` field — hosts that honour it (ChatGPT Apps,
+ * Claude Desktop) hide `['assistant']`-tagged blocks from the user pane
+ * while still feeding them to the model. Hosts that don't honour it
+ * (e.g. MCP Inspector) render every block verbatim.
+ */
+interface SolvaPayContentAnnotations {
+    audience?: Array<'user' | 'assistant'>;
+    priority?: number;
+}
+interface SolvaPayCallToolResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+        annotations?: SolvaPayContentAnnotations;
+    } | {
+        type: 'image';
+        data: string;
+        mimeType: string;
+        annotations?: SolvaPayContentAnnotations;
+    } | {
+        type: 'resource';
+        resource: Record<string, unknown>;
+        annotations?: SolvaPayContentAnnotations;
+    }>;
+    structuredContent?: Record<string, unknown>;
+    isError?: boolean;
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Extra context passed into MCP tool handlers. Mirrors the `extra`
+ * parameter shape used by the official SDK's `registerTool` callback.
+ */
+interface McpToolExtra {
+    authInfo?: {
+        token?: string;
+        clientId?: string;
+        scopes?: string[];
+        expiresAt?: number;
+        extra?: Record<string, unknown>;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Options for the MCP adapter's `formatResponse` / `getCustomerRef`
+ * hooks. Used by `@solvapay/server`'s `McpAdapter` (backing
+ * `payable().mcp()`) and any descriptor-level customisation.
+ */
+interface McpAdapterOptions {
+    getCustomerRef?: (args: any, extra?: McpToolExtra) => string | Promise<string>;
+    transformResponse?: (result: any) => any;
+}
+/**
+ * Tool result shape returned by `payable().mcp(...)` when the paywall
+ * fires. Structurally compatible with `SolvaPayCallToolResult` so every
+ * framework adapter can return it directly.
+ */
+interface PaywallToolResult {
+    content?: Array<{
+        type: 'text' | 'image' | 'resource';
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+    isError?: boolean;
+    structuredContent?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Which view a SolvaPay MCP server knows how to bootstrap.
+ *
+ * Four kinds map to an intent `open_*`-style tool: `checkout`,
+ * `account`, `topup`, and `nudge` (opened implicitly when a successful
+ * paywalled tool response carries `options.nudge`). `paywall` has no
+ * dedicated tool — the gate response inlines the bootstrap payload on
+ * its `structuredContent`, and the React shell takes over the surface
+ * when it sees `view: 'paywall'`.
+ *
+ * The legacy `'about'`, `'activate'`, and `'usage'` surfaces were
+ * dropped with the three-mode refactor — About is now served by tool
+ * descriptions + docs resources, Activate merged into checkout's
+ * `PlanActivationDispatcher`, and Usage folds inline into the account
+ * view.
+ */
+type SolvaPayMcpViewKind = 'checkout' | 'account' | 'topup' | 'paywall' | 'nudge';
+declare const SOLVAPAY_MCP_VIEW_KINDS: readonly ["checkout", "account", "topup", "paywall", "nudge"];
+/**
+ * Minimal `kind`-tagged paywall content passed through `BootstrapPayload`
+ * when the host opens the paywall view. The full
+ * `PaywallStructuredContent` type lives in `@solvapay/server` (it's also
+ * consumed by the non-MCP react paywall primitives); this shape is a
+ * structural superset that adapters can forward without importing it.
+ */
+interface SolvaPayMcpPaywallContent {
+    kind: 'payment_required' | 'activation_required';
+    [key: string]: unknown;
+}
+/**
+ * Payload returned by every `open_*` bootstrap tool and consumed by the
+ * React MCP App shell to render the right view. Single source of truth —
+ * the react bootstrap (`@solvapay/react/mcp`) imports this type so field
+ * renames can't silently drift between server and client.
+ *
+ * Product-scoped fields (`merchant`, `product`, `plans`) are always
+ * present so the shell can render without firing follow-up read tools.
+ * `customer` is `null` when the call is unauthenticated; each nested
+ * field is `null` when the corresponding sub-read errored or doesn't
+ * apply (e.g. `paymentMethod: null` when no card is on file).
+ */
+interface BootstrapPayload {
+    view: SolvaPayMcpViewKind;
+    productRef: string;
+    stripePublishableKey: string | null;
+    returnUrl: string;
+    /** Only set for the `open_paywall` branch. */
+    paywall?: SolvaPayMcpPaywallContent;
+    /**
+     * Upsell strip spec attached when `view: 'nudge'`. Rendered above
+     * the merchant tool result by `McpNudgeView`.
+     */
+    nudge?: NudgeSpec;
+    /**
+     * Merchant tool result data embedded alongside a nudge so the shell
+     * can surface it without a follow-up tool call. Only set when
+     * `view: 'nudge'`.
+     */
+    data?: unknown;
+    merchant: BootstrapMerchant;
+    product: BootstrapProduct;
+    plans: BootstrapPlan[];
+    customer: BootstrapCustomer | null;
+}
+/**
+ * Content Security Policy allow-list inputs merged with the Stripe
+ * baseline by `SOLVAPAY_DEFAULT_CSP` / `mergeCsp`.
+ */
+interface SolvaPayMcpCsp {
+    resourceDomains?: string[];
+    connectDomains?: string[];
+    frameDomains?: string[];
+}
+/**
+ * MCP tool annotations — hints to hosts about the tool's behaviour.
+ * Structural subset of the official spec's `ToolAnnotations` so hosts
+ * can surface confirmation prompts (destructive actions) and filter
+ * tools appropriately (read-only vs. mutating).
+ *
+ * See https://modelcontextprotocol.io/specification for the full
+ * semantics. Hosts on pre-annotations SDK versions ignore the field
+ * without error — the wire shape is additive.
+ */
+interface SolvaPayToolAnnotations {
+    /** Human-readable title override (prefer the descriptor's `title`). */
+    title?: string;
+    /** Tool only retrieves data — no side effects on SolvaPay state. */
+    readOnlyHint?: boolean;
+    /** Tool has destructive / non-reversible side effects (charges, cancellations). */
+    destructiveHint?: boolean;
+    /** Repeated calls with the same args produce the same effect. */
+    idempotentHint?: boolean;
+    /** Tool interacts with external systems (true for every SolvaPay tool). */
+    openWorldHint?: boolean;
+}
+/**
+ * Brand-icon descriptor — mirrors the MCP spec's per-tool / per-resource
+ * `icons[]` element so hosts can swap the default globe / placeholder
+ * in the chrome strip for the merchant's own mark.
+ *
+ * Shape tracks the zod schema exposed by `@modelcontextprotocol/ext-apps`
+ * (see `app.d.ts` icon definitions). Newer MCP SDKs may surface `icons`
+ * as a top-level Tool field; until then we advertise them via
+ * `_meta.ui.icons` where ext-apps-aware hosts can discover them.
+ */
+interface SolvaPayToolIcon {
+    /** Absolute URL or `data:` URI for the icon asset. */
+    src: string;
+    /** MIME type, e.g. `'image/png'` / `'image/svg+xml'`. */
+    mimeType?: string;
+    /** Size hints, e.g. `['512x512']`. */
+    sizes?: string[];
+    /** Render only under the given host theme (defaults to both). */
+    theme?: 'light' | 'dark';
+}
+/**
+ * Merchant branding that hosts / iframes can use to replace the
+ * generic SolvaPay identity with the merchant's own mark. Pre-fetched
+ * by the integrator at server startup (e.g. via `getMerchantCore`) so
+ * `createSolvaPayMcpServer` stays synchronous.
+ */
+interface SolvaPayMerchantBranding {
+    /** Display name used as the MCP `Implementation.name`. */
+    brandName?: string;
+    /**
+     * Absolute URL to a square logomark (recommended 512×512 PNG or SVG).
+     * Preferred input for MCP host-chrome icon slots.
+     */
+    iconUrl?: string;
+    /**
+     * Absolute URL to a landscape logo. Used as a fallback when
+     * `iconUrl` isn't available — hosts that can only render a square
+     * mark may letterbox it.
+     */
+    logoUrl?: string;
+}
+/**
+ * Framework-neutral tool descriptor. Adapters translate this to their
+ * own registration API (`registerAppTool` on the official SDK,
+ * `tool.define` on `fastmcp`, etc.).
+ */
+interface SolvaPayToolDescriptor {
+    name: string;
+    title?: string;
+    description: string;
+    /**
+     * Zod raw shape — `{ fieldName: z.string() }`. Kept as `ZodTypeAny`
+     * valued so zod stays an optional peer. Empty object = no args.
+     */
+    inputSchema: Record<string, ZodTypeAny>;
+    meta?: Record<string, unknown>;
+    /**
+     * Portable MCP tool annotations surfaced on `tools/list`. Adapters
+     * that support the upstream `ToolAnnotations` field forward these
+     * verbatim; adapters that don't silently ignore them.
+     */
+    annotations?: SolvaPayToolAnnotations;
+    /**
+     * Brand icons surfaced on `tools/list`. Adapters include these on
+     * the tool advertisement so hosts can replace the default globe /
+     * placeholder in their chrome strip with the merchant's mark.
+     * Derived from `SolvaPayMerchantBranding` when the descriptor is
+     * built.
+     */
+    icons?: SolvaPayToolIcon[];
+    handler: (args: Record<string, unknown>, extra?: McpToolExtra) => Promise<SolvaPayCallToolResult>;
+}
+/**
+ * UI resource descriptor for the MCP App HTML bundle served alongside
+ * the tool surface.
+ */
+interface SolvaPayResourceDescriptor {
+    uri: string;
+    mimeType: string;
+    csp: Required<SolvaPayMcpCsp>;
+    readHtml: () => Promise<string>;
+}
+/**
+ * Docs-style resource descriptor — a static markdown / text blob the
+ * agent can `resources/read` for narrated context (e.g. the
+ * `docs://solvapay/overview.md` "start here" guide). Kept separate from
+ * `SolvaPayResourceDescriptor` because it has no CSP metadata and its
+ * body is plain text, not the UI shell HTML.
+ */
+interface SolvaPayDocsResourceDescriptor {
+    /** Stable URI — typically `docs://solvapay/<slug>.md`. */
+    uri: string;
+    /** Human-readable name surfaced in `resources/list`. */
+    name: string;
+    /** Optional short title for host UIs that distinguish it from `name`. */
+    title?: string;
+    /** Short one-liner surfaced in `resources/list` metadata. */
+    description: string;
+    /** MIME type, typically `text/markdown` or `text/plain`. */
+    mimeType: string;
+    /** Returns the body — sync or async. */
+    readBody: () => string | Promise<string>;
+}
+/**
+ * One MCP prompt — rendered as `/<name>` in hosts with slash-command
+ * support. Kept framework-neutral so every adapter (`@modelcontextprotocol/sdk`,
+ * `fastmcp`, raw JSON-RPC) can map it to their own `registerPrompt`
+ * shape.
+ *
+ * `argsSchema` matches the zod raw-shape shape the official SDK's
+ * `registerPrompt` accepts — a plain object of `z.*` fields. Adapters
+ * without zod-shape prompts can still call each field's `parse()`
+ * themselves.
+ */
+interface SolvaPayPromptDescriptor {
+    name: string;
+    title?: string;
+    description: string;
+    argsSchema?: Record<string, ZodTypeAny>;
+    handler: (args: Record<string, unknown>) => SolvaPayPromptResult | Promise<SolvaPayPromptResult>;
+}
+/**
+ * Minimal `GetPromptResult` shape — structural subset of the official
+ * SDK's type so adapters can forward it without importing
+ * `@modelcontextprotocol/sdk/types.js`.
+ */
+interface SolvaPayPromptResult {
+    messages: Array<{
+        role: 'user' | 'assistant';
+        content: {
+            type: 'text';
+            text: string;
+        };
+    }>;
+}
+/**
+ * View → intent-tool map, derived from `MCP_TOOL_NAMES` so a new view
+ * requires exactly one edit across the entire ecosystem.
+ *
+ * `paywall` has no dedicated intent tool — the paywall response carries
+ * the bootstrap payload directly (`paywallToolResult` merges it into
+ * `structuredContent`), so the shell renders the paywall view without
+ * re-invoking a tool.
+ */
+declare const TOOL_FOR_VIEW: {
+    readonly checkout: "upgrade";
+    readonly account: "manage_account";
+    readonly topup: "topup";
+};
+/**
+ * Inverse of `TOOL_FOR_VIEW` — intent-tool name → view kind.
+ */
+declare const VIEW_FOR_TOOL: Record<string, SolvaPayMcpViewKind>;
+/**
+ * @deprecated Use `TOOL_FOR_VIEW`. Kept as an alias so the rename lands
+ * without a simultaneous import update across the ecosystem.
+ */
+declare const OPEN_TOOL_FOR_VIEW: {
+    readonly checkout: "upgrade";
+    readonly account: "manage_account";
+    readonly topup: "topup";
+};
+/**
+ * @deprecated Use `VIEW_FOR_TOOL`.
+ */
+declare const VIEW_FOR_OPEN_TOOL: Record<string, SolvaPayMcpViewKind>;
+/**
+ * Inline upsell strip attached to a successful tool response. Rendered
+ * below the tool result by the host; dismissible, non-blocking.
+ *
+ * V1 ships three default kinds, each with a default CTA that opens the
+ * `upgrade` intent tool. `kind: 'custom'` is reserved for V1.1.
+ */
+interface NudgeSpec {
+    kind: 'low-balance' | 'cycle-ending' | 'approaching-limit';
+    message: string;
+}
+/**
+ * Intermediate content block emitted via `ctx.emit(block)`. Structural
+ * subset of `SolvaPayCallToolResult.content` entries — text, image, or
+ * resource.
+ */
+type ContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    data: string;
+    mimeType: string;
+} | {
+    type: 'resource';
+    resource: Record<string, unknown>;
+};
+/**
+ * Options for `ctx.respond(data, options?)`.
+ *
+ * `text` overrides the SDK's default narrator output for this response.
+ * `nudge` attaches an inline upsell strip.
+ * `units` is reserved for V1.1 variable-unit billing; V1 silently
+ * ignores the field (billing stays at one credit per tool call).
+ */
+interface ResponseOptions {
+    /** Override `content[0].text` with merchant-supplied text. */
+    text?: string;
+    /** Inline upsell strip rendered below the tool result. */
+    nudge?: NudgeSpec;
+    /**
+     * [V1.1] Units to bill for this call. Defaults to 1. Must be >= 0.
+     *
+     * V1 behaviour: field is accepted for forward compatibility but
+     * silently ignored. Billing stays fixed at one credit per tool call.
+     * V1.1 behaviour: threaded into `trackUsage` and applied by the backend.
+     */
+    units?: number;
+}
+/**
+ * Branded envelope returned by `ctx.respond(data, options?)`. The brand
+ * symbol is module-private — merchants never construct `ResponseResult`
+ * values directly. `buildPayableHandler` unwraps the envelope into a
+ * `SolvaPayCallToolResult` before shipping.
+ */
+interface ResponseResult<TData = unknown> {
+    /**
+     * Opaque brand marker — typed as `true` so the envelope is
+     * structurally distinguishable from raw merchant data even without
+     * the runtime symbol.
+     */
+    readonly __solvapayResponse: true;
+    readonly data: TData;
+    readonly options?: ResponseOptions;
+    /**
+     * Content blocks queued via `ctx.emit(block)` before the terminal
+     * `respond()` call. V1 flushes these into `content[]` at respond
+     * time; V1.1 emits them over SSE.
+     */
+    readonly emittedBlocks?: ContentBlock[];
+}
+/**
+ * Cached snapshot of customer state at handler invocation.
+ *
+ * Populated from the existing `LimitResponse` returned by
+ * `payable().mcp()`'s pre-check — zero additional fetch cost.
+ *
+ * IMPORTANT: values here may be up to 10 seconds stale after mutations
+ * (topup, plan change, cancel) within the same process. For fresh
+ * state, call `.fresh()`.
+ */
+interface CustomerSnapshot {
+    /** Backend customer ref (`cus_...`). */
+    readonly ref: string;
+    /** Credit balance in mils. 0 when the backend didn't surface a balance. */
+    readonly balance: number;
+    /** Remaining usage units before hitting the limit. `null` when unlimited. */
+    readonly remaining: number | null;
+    /** Whether the customer is within their usage limits at snapshot time. */
+    readonly withinLimits: boolean;
+    /**
+     * Active plan on the purchase. `null` when the customer has no
+     * active purchase or is on a free plan.
+     */
+    readonly plan: BootstrapPlan | null;
+    /**
+     * Force a fresh fetch bypassing the 10s limits cache.
+     * Returns a new snapshot; does NOT mutate the current one.
+     */
+    fresh(): Promise<CustomerSnapshot>;
+}
+/**
+ * Handler context passed as the second positional argument to merchant
+ * `registerPayable` handlers opting into the V1 `ctx` API.
+ *
+ * V1 surface: `customer`, `product`, `respond`, `gate`.
+ * Reserved (V1.1): `emit`, `progress`, `progressRaw`, `signal` — types
+ * ship in V1 so merchants can write forward-compatible code.
+ */
+interface ResponseContext {
+    /**
+     * Customer snapshot at handler invocation. See `CustomerSnapshot`
+     * for staleness semantics.
+     */
+    customer: CustomerSnapshot;
+    /** Read-only product configuration from the bootstrap payload. */
+    product: BootstrapProduct;
+    /** Build a response. Two forms, both valid. */
+    respond<TData>(data: TData): ResponseResult<TData>;
+    respond<TData>(data: TData, options: ResponseOptions): ResponseResult<TData>;
+    /**
+     * Explicitly trigger a paywall response. Handler execution stops
+     * and the adapter routes the gate through `formatGate` — the MCP
+     * transport emits a clean narration + `structuredContent` payload
+     * with `isError: false`, same shape as a pre-check gate outcome.
+     *
+     * Implemented as `throw new PaywallError(reason)` for the compat
+     * window; the adapter's catch block at the boundary unwraps it
+     * and delivers the transport response. Merchants who catch the
+     * error themselves can still rely on `instanceof PaywallError`.
+     *
+     * Rare — normally the SDK fires the paywall automatically via
+     * `payable().mcp()` pre-check.
+     */
+    gate(reason?: string): never;
+    /**
+     * [V1.1] Emit an intermediate content block.
+     *
+     * V1 behaviour: queued and flushed at the terminal `respond()`. No SSE.
+     * V1.1 behaviour: emits immediately over Streamable HTTP + SSE.
+     *
+     * Reserved so merchants can write forward-compatible streaming code
+     * today.
+     */
+    emit(block: ContentBlock): Promise<void>;
+    /**
+     * [V1.1] Emit a progress notification with a percent.
+     *
+     * V1 behaviour: no-op.
+     * V1.1 behaviour: sends `notifications/progress` if the client
+     * supplied a `progressToken`; no-op otherwise.
+     */
+    progress(options: {
+        percent: number;
+        message?: string;
+    }): Promise<void>;
+    /**
+     * [V1.1] Emit a progress notification with non-percent units.
+     *
+     * V1 behaviour: no-op.
+     * V1.1 behaviour: sends `notifications/progress` with raw
+     * progress/total.
+     */
+    progressRaw(options: {
+        progress: number;
+        total?: number;
+        message?: string;
+    }): Promise<void>;
+    /**
+     * [V1.1] AbortSignal that fires when the client cancels the tool call.
+     *
+     * V1 behaviour: always an unaborted signal.
+     * V1.1 behaviour: wired to the underlying transport cancellation.
+     *
+     * Merchants pass this to their upstream fetch/LLM/image-gen calls to
+     * cancel expensive operations when the client goes away.
+     */
+    signal: AbortSignal;
+}
+/**
+ * Merchant handler signature for `registerPayable`. Receives the
+ * parsed input `args` (typed from the tool's `schema` when provided)
+ * and a `ResponseContext` with `ctx.respond(...)`, `ctx.customer`,
+ * `ctx.gate(...)`, and the reserved streaming surface (`ctx.emit`,
+ * `ctx.progress`, `ctx.signal`).
+ *
+ * Must return the branded envelope produced by `ctx.respond(data, options?)`.
+ * Returning a raw value is a type error at compile time and throws a
+ * merchant-actionable error at runtime.
+ */
+type PayableHandler<TArgs = Record<string, unknown>, TData = unknown> = (args: TArgs, ctx: ResponseContext) => Promise<ResponseResult<TData>>;
+
+/**
+ * Narrator map — one function per intent tool that renders a sparse,
+ * text-friendly markdown summary of the bootstrap payload.
+ *
+ * Style rules (see the discoverable-UX plan for rationale):
+ *  1. First line is a single `**bold title**` — no headings.
+ *  2. Body uses `Label: value` rows (one per line). Inline `·`
+ *     separator for compound values. No bullet lists.
+ *  3. Commands on a single line as inline-code tokens.
+ *  4. External URLs go into `resource_link` blocks, not inline
+ *     markdown links.
+ *
+ * Missing fields skip their row entirely — we never emit `Balance: —`
+ * or `Customer: unknown`. A narrator returning just `title + 1 row`
+ * is still well-formed.
+ */
+
+interface NarratorOutput {
+    text: string;
+    links?: Array<{
+        uri: string;
+        name: string;
+    }>;
+}
+type IntentTool = 'upgrade' | 'manage_account' | 'topup' | 'activate_plan';
+interface PlanShape {
+    name?: string;
+    planType?: string;
+    price?: number;
+    currency?: string;
+    billingCycle?: string | null;
+    meterRef?: string | null;
+    limit?: number | null;
+}
+interface PurchaseShape {
+    planSnapshot?: PlanShape | null;
+    amount?: number;
+    currency?: string;
+    endDate?: string;
+}
+interface CustomerShape {
+    ref?: string;
+    balance?: {
+        credits?: number | null;
+        displayCurrency?: string;
+        displayExchangeRate?: number;
+    } | null;
+    usage?: {
+        used?: number;
+        limit?: number;
+        resetsAt?: string;
+    } | null;
+    purchase?: {
+        purchases?: PurchaseShape[];
+    } | null;
+}
+/**
+ * Human-readable balance summary used by the `'ui'` mode placeholder.
+ * Returns `null` when no balance is available so the caller can skip
+ * the segment entirely.
+ */
+declare function balanceSummary(customer: CustomerShape | null | undefined): string | null;
+declare function narrateManageAccount(data: BootstrapPayload): NarratorOutput;
+declare function narrateUpgrade(data: BootstrapPayload): NarratorOutput;
+declare function narrateTopup(data: BootstrapPayload): NarratorOutput;
+declare function narrateActivatePlan(data: BootstrapPayload): NarratorOutput;
+declare const NARRATORS: Record<IntentTool, (data: BootstrapPayload) => NarratorOutput>;
+/**
+ * One-line placeholder shown on UI-rendering hosts when the intent
+ * tool runs in `mode: 'ui'`. Gives the agent minimal grounding (what
+ * surface opened + balance when available) without flooding the user
+ * pane with the full narrated markdown that the iframe already covers.
+ */
+declare function uiPlaceholder(tool: IntentTool, data: BootstrapPayload): string;
+
+/**
+ * Shared building blocks for `buildSolvaPayDescriptors` and any hand-rolled
+ * SolvaPay MCP server that prefers to register tools directly.
+ *
+ * Lifted from the canonical example at `examples/mcp-checkout-app/src/server.ts`
+ * so every integrator gets the same behavior for price enrichment, synthetic
+ * `Request` construction, and tool-result wrapping.
+ */
+
+/**
+ * Augment a purchase with human-readable price strings so callers (LLMs
+ * rendering the JSON directly) don't have to reason about minor units.
+ *
+ * Raw `amount` / `originalAmount` / `currency` fields are preserved for
+ * programmatic consumers (e.g. the React transport).
+ */
+declare function enrichPurchase(purchase: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Default extractor for `customer_ref` out of the MCP OAuth bridge. Reads
+ * `extra.authInfo.extra.customer_ref` (what `auth-bridge.ts` populates) and
+ * trims it. Returns `null` when no ref is present.
+ */
+declare function defaultGetCustomerRef(extra?: McpToolExtra): string | null;
+interface BuildSolvaPayRequestOptions {
+    method?: string;
+    query?: Record<string, string | undefined>;
+    body?: unknown;
+    /**
+     * Override the customer ref that is forwarded as the `x-user-id` header.
+     * Defaults to reading `extra.authInfo.extra.customer_ref`.
+     */
+    getCustomerRef?: (extra?: McpToolExtra) => string | null;
+    /**
+     * Override the synthetic origin used in the request URL. Defaults to
+     * `http://solvapay-mcp-server.local/`.
+     */
+    origin?: string;
+}
+/**
+ * Build a synthetic Web `Request` the core `*Core` helpers can consume.
+ *
+ * The `x-user-id` header is what `getAuthenticatedUserCore` reads as the
+ * authoritative user identity, so forwarding the `customer_ref` from the
+ * MCP OAuth bridge keeps the entire flow headless.
+ */
+declare function buildSolvaPayRequest(extra: McpToolExtra | undefined, options?: BuildSolvaPayRequestOptions): Request;
+/**
+ * Wrap arbitrary data in a `SolvaPayCallToolResult`. Produces a `text`
+ * content block and `structuredContent` so both LLM-facing and tool-call
+ * consumers see a consistent shape.
+ */
+declare function toolResult(data: unknown): SolvaPayCallToolResult;
+/**
+ * Requested rendering mode per-call. Passed through the `mode` input
+ * arg of every intent tool.
+ *
+ * - `'ui'` (default) — emit a one-line placeholder in `content[0]`
+ *   alongside the UI resource ref on `_meta.ui`. Keeps UI-rendering
+ *   hosts (MCP Inspector, ChatGPT Apps, Claude Desktop) tidy — the
+ *   iframe already carries the rich detail. Agents get the full
+ *   `BootstrapPayload` on `structuredContent` for grounding.
+ * - `'text'` — strip the UI resource ref and emit the full narrated
+ *   markdown so CLI / text-only hosts get a human summary.
+ * - `'auto'` — emit both the narrated markdown and the UI resource
+ *   ref. The narrated block is annotated with `audience: ['assistant']`
+ *   so audience-aware hosts pass it to the model without showing it in
+ *   the user pane.
+ */
+type SolvaPayToolMode = 'ui' | 'text' | 'auto';
+declare function parseMode(raw: unknown): SolvaPayToolMode;
+/**
+ * Build a `SolvaPayCallToolResult` that respects the requested `mode`:
+ *
+ *  - `ui` (default) emits a one-line placeholder in `content[0]` and
+ *    keeps `_meta.ui.*` so UI-rendering hosts open the iframe without
+ *    a noisy narration beneath it. `structuredContent` still carries
+ *    the raw bootstrap payload so agents have full grounding.
+ *  - `text` emits the full narrated markdown (plus any
+ *    `resource_link` blocks) and strips `_meta.ui.*` so UI-capable
+ *    hosts render text-only for this call.
+ *  - `auto` emits both. The narrated text block is annotated with
+ *    `audience: ['assistant']` so audience-aware hosts still hide it
+ *    from the user pane while feeding it to the model.
+ *
+ * The narrator is picked by the `tool` name; unknown tools fall back
+ * to the JSON dump that `toolResult` produces today.
+ */
+declare function narratedToolResult(tool: IntentTool | string, data: BootstrapPayload, mode?: SolvaPayToolMode, baseMeta?: Record<string, unknown> | undefined): SolvaPayCallToolResult;
+/**
+ * Wrap an error payload (typically the result of `handleRouteError`) in a
+ * `SolvaPayCallToolResult` with `isError: true`.
+ */
+declare function toolErrorResult(error: {
+    error: string;
+    status: number;
+    details?: string;
+}): SolvaPayCallToolResult;
+/**
+ * Truncate a JSON preview to a max length so trace logs stay readable.
+ */
+declare function previewJson(value: unknown, max?: number): string;
+
+/**
+ * Canonical paywall `_meta.ui` envelope used by every SolvaPay MCP
+ * tool result. Centralising this shape means swapping the UI resource
+ * URI is a one-line builder call at every call site.
+ */
+interface PaywallUiMetaInput {
+    /** UI resource URI the MCP host opens to render the paywall view. */
+    resourceUri: string;
+}
+interface PaywallUiMeta {
+    ui: {
+        resourceUri: string;
+    };
+    [key: string]: unknown;
+}
+/**
+ * Build the `_meta` envelope attached to paywall tool results. Consumed
+ * by `paywallToolResult`, `buildPayableHandler`, and the descriptor
+ * registration layer so the shape stays in lockstep.
+ *
+ * The bootstrap payload itself now travels on `structuredContent` — this
+ * envelope only tells the host which UI resource to open.
+ */
+declare function buildPaywallUiMeta(input: PaywallUiMetaInput): PaywallUiMeta;
+
+/**
+ * Standalone `buildBootstrapPayload` factory — same logic `buildSolvaPayDescriptors`
+ * wires under the `open_*` tools, exposed separately so the paywall
+ * envelope (`paywallToolResult`, `buildPayableHandler`) can embed the
+ * full `BootstrapPayload` in `structuredContent` without duplicating
+ * the parallel fetch layout.
+ */
+
+interface CreateBuildBootstrapPayloadOptions {
+    solvaPay: SolvaPay;
+    productRef: string;
+    publicBaseUrl: string;
+    getCustomerRef?: (extra?: McpToolExtra) => string | null;
+}
+type BuildBootstrapPayloadFn = (view: SolvaPayMcpViewKind, extra: McpToolExtra | undefined, extras?: {
+    paywall?: PaywallStructuredContent;
+}) => Promise<BootstrapPayload>;
+/**
+ * Produce a reusable `buildBootstrapPayload(view, extra, extras?)` closure
+ * wired against the same SolvaPay instance + product as a
+ * `buildSolvaPayDescriptors` bundle.
+ *
+ * The returned function runs `getMerchant`, `getProduct`, `listPlans`,
+ * `checkPurchase`, `getPaymentMethod`, `getCustomerBalance`, `getUsage`
+ * in parallel, failing loudly when merchant or product can't load (the
+ * React shell can't render meaningfully without them) and degrading
+ * gracefully on per-customer sub-reads.
+ */
+declare function createBuildBootstrapPayload(options: CreateBuildBootstrapPayloadOptions): BuildBootstrapPayloadFn;
+
+/**
+ * Helper for hand-rolled MCP tool handlers that still want to attach the
+ * `_meta.ui` envelope + a full `BootstrapPayload` to paywall results
+ * without adopting `buildPayableHandler` / `registerPayableTool`
+ * wholesale.
+ */
+
+interface PaywallToolResultContext {
+    /** UI resource URI the MCP host should open to render the paywall view. */
+    resourceUri: string;
+    /**
+     * Builds the full `BootstrapPayload` that rides on
+     * `structuredContent` so the React shell can mount the paywall view
+     * from the gate response directly — no follow-up `open_paywall` call.
+     * Wire this from `buildSolvaPayDescriptors(...).buildBootstrapPayload`.
+     */
+    buildBootstrap?: BuildBootstrapPayloadFn;
+    /** Forwarded to `buildBootstrap` so customer-scoped fields resolve. */
+    extra?: McpToolExtra;
+}
+/**
+ * Convert a paywall gate (either a `PaywallError` or the underlying
+ * `PaywallStructuredContent` returned by `paywall.decide()`) into a
+ * `PaywallToolResult` carrying a full `BootstrapPayload` (so the
+ * React shell can render the paywall view immediately) and the
+ * `_meta.ui` envelope telling the host which resource to open.
+ *
+ * Prefer the gate-first form when you already have a
+ * `PaywallDecision` in hand:
+ *
+ * ```ts
+ * const decision = await solvaPay.paywall.decide(args, { product })
+ * if (decision.outcome === 'gate') {
+ *   return paywallToolResult(decision.gate, {
+ *     resourceUri: 'ui://my-app/mcp-app.html',
+ *     buildBootstrap,
+ *     extra,
+ *   })
+ * }
+ * ```
+ *
+ * The legacy `PaywallError`-first form continues to work for custom
+ * adapters that still `try/catch`:
+ *
+ * ```ts
+ * try {
+ *   return await solvaPay.payable({ product }).mcp(handler)(args, extra)
+ * } catch (err) {
+ *   if (err instanceof PaywallError) {
+ *     return paywallToolResult(err, {
+ *       resourceUri: 'ui://my-app/mcp-app.html',
+ *       buildBootstrap,
+ *       extra,
+ *     })
+ *   }
+ *   throw err
+ * }
+ * ```
+ */
+declare function paywallToolResult(errOrGate: PaywallError | PaywallStructuredContent, ctx: PaywallToolResultContext): Promise<PaywallToolResult>;
+
+/**
+ * Default Content Security Policy allow-list for SolvaPay MCP Apps.
+ *
+ * The Stripe baseline covers `js.stripe.com`, `api.stripe.com`, and the
+ * `hooks.stripe.com` 3DS frame. Adapters merge integrator-provided
+ * overrides on top via `mergeCsp`.
+ */
+
+declare const SOLVAPAY_DEFAULT_CSP: Required<SolvaPayMcpCsp>;
+/**
+ * Merge integrator CSP overrides on top of `SOLVAPAY_DEFAULT_CSP`.
+ * Deduplicates per domain list so repeated entries don't balloon the
+ * resulting `_meta.ui.csp` envelope.
+ */
+declare function mergeCsp(overrides: SolvaPayMcpCsp | undefined): Required<SolvaPayMcpCsp>;
+
+/**
+ * `buildSolvaPayDescriptors(options)` — framework-neutral tool surface
+ * builder that every SolvaPay MCP adapter (`@solvapay/mcp`, future
+ * `@solvapay/mcp-fastmcp`, raw JSON-RPC adapters) maps onto its own
+ * registration API.
+ *
+ * Body is lifted from the original
+ * `packages/server/src/mcp/server.ts#createSolvaPayMcpServer`. The only
+ * mechanical difference: instead of calling `registerAppTool(server, ...)`,
+ * we push `{ name, handler, ... }` onto a `tools[]` array the adapter
+ * iterates.
+ */
+
+interface BuildSolvaPayDescriptorsOptions {
+    /** Initialised SolvaPay instance. */
+    solvaPay: SolvaPay;
+    /** Default product ref for this MCP server (used when tool args omit it). */
+    productRef: string;
+    /** UI resource URI served by this server (e.g. `'ui://my-app/mcp-app.html'`). */
+    resourceUri: string;
+    /**
+     * Absolute filesystem path to the built HTML bundle referenced by
+     * `resourceUri`. Node-only convenience — dynamic-imports
+     * `node:fs/promises` internally. Provide `readHtml` instead for edge
+     * runtimes.
+     */
+    htmlPath?: string;
+    /**
+     * Edge-neutral alternative to `htmlPath`. One of `htmlPath` or
+     * `readHtml` must be provided.
+     */
+    readHtml?: () => Promise<string>;
+    /**
+     * Public `https://` origin used as `return_url` for Stripe confirmations.
+     * Required because MCP hosts set `window.location.origin` to `"null"`,
+     * which Stripe's `confirmPayment` validator rejects.
+     */
+    publicBaseUrl: string;
+    /** Which `open_*` tools to register. Defaults to every known view. */
+    views?: SolvaPayMcpViewKind[];
+    /** Additional CSP allow-lists merged with the Stripe baseline. */
+    csp?: SolvaPayMcpCsp;
+    /**
+     * Override customer-ref extraction. Defaults to reading
+     * `extra.authInfo.extra.customer_ref` (populated by the MCP OAuth
+     * bridge).
+     */
+    getCustomerRef?: (extra?: McpToolExtra) => string | null;
+    /**
+     * Fired for every tool call so integrators can add tracing / logging.
+     * Called before the core helper runs; the result is available on the
+     * `response` callback (`onToolResult`).
+     */
+    onToolCall?: (name: string, args: unknown, extra?: McpToolExtra) => void;
+    /** Fired after every tool call completes (success or error). */
+    onToolResult?: (name: string, result: SolvaPayCallToolResult, meta: {
+        durationMs: number;
+    }) => void;
+    /**
+     * Merchant branding used to personalise the MCP host chrome — when
+     * provided, every emitted tool descriptor carries an `icons[]` the
+     * adapter surfaces on `tools/list` so hosts can replace the default
+     * globe / placeholder with the merchant's mark. Prefer fetching the
+     * SDK merchant payload at server startup (`getMerchantCore` exposes
+     * `iconUrl` / `logoUrl` / `displayName`) and passing the result in.
+     */
+    branding?: SolvaPayMerchantBranding;
+}
+interface SolvaPayDescriptorBundle {
+    tools: SolvaPayToolDescriptor[];
+    resource: SolvaPayResourceDescriptor;
+    /**
+     * Slash-command prompts that hosts with prompt support (Claude
+     * Desktop, Cursor, etc.) surface as `/upgrade`, `/manage_account`,
+     * `/topup`, and `/activate_plan`. Hosts without prompt support
+     * silently ignore the list — registration is purely additive.
+     */
+    prompts: SolvaPayPromptDescriptor[];
+    /**
+     * Narrated docs resources — agent-facing "read me first" content
+     * served over `docs://solvapay/*`. Lives alongside the UI resource so
+     * agents can `resources/read` before trying a tool.
+     */
+    docsResources: SolvaPayDocsResourceDescriptor[];
+    /**
+     * Parallelised fetch of merchant + product + plans + (optional)
+     * customer snapshot that backs every `open_*` tool. Exposed so the
+     * paywall envelope (`paywallToolResult`, `buildPayableHandler`) can
+     * embed the full payload in its `structuredContent`.
+     */
+    buildBootstrapPayload: BuildBootstrapPayloadFn;
+}
+/**
+ * Build the framework-neutral SolvaPay tool + resource descriptors. The
+ * returned bundle is adapter-shaped — pass it to the registration helper
+ * exported by `@solvapay/mcp` (or any future adapter package).
+ */
+declare function buildSolvaPayDescriptors(options: BuildSolvaPayDescriptorsOptions): SolvaPayDescriptorBundle;
+/**
+ * Build the framework-neutral slash-command prompt descriptors for the
+ * five SolvaPay intent tools. Exposed standalone so adapters that don't
+ * want the full descriptor bundle (or want to register prompts on an
+ * already-built server) can still pick them up.
+ *
+ * Each prompt is intentionally one `user` message that mirrors how a
+ * human would invoke the intent — this makes slash-commands feel like
+ * natural shortcuts, and keeps the prompts compatible with text hosts
+ * that don't expose the MCP UI shell.
+ */
+declare function buildSolvaPayPrompts(options?: {
+    enabledViews?: Set<SolvaPayMcpViewKind>;
+}): SolvaPayPromptDescriptor[];
+
+/**
+ * Narrated overview for the SolvaPay MCP server — served verbatim at
+ * `docs://solvapay/overview.md` so agents can `resources/read` before
+ * calling any tool.
+ *
+ * Inlined as a TS constant (not a standalone `.md` file) because the
+ * package bundles via tsup — a markdown asset next to this file would
+ * need copy-on-build and runtime `fs` access, neither of which the
+ * framework-neutral `@solvapay/mcp` package should take on.
+ */
+declare const SOLVAPAY_OVERVIEW_URI = "docs://solvapay/overview.md";
+declare const SOLVAPAY_OVERVIEW_MIME_TYPE = "text/markdown";
+declare const SOLVAPAY_OVERVIEW_MARKDOWN = "# SolvaPay MCP server \u2014 overview\n\nThis MCP server connects a SolvaPay-protected product to your host so users can\nmanage their plan, usage, and billing **without leaving the chat**. It is\ndual-audience: every tool returns a UI bootstrap for hosts that render MCP UI\nresources (`basic-host`, Claude Desktop, ChatGPT, etc.) and a markdown summary\nwith clickable URLs for text-only hosts.\n\n## What the user can do\n\n- **Upgrade** \u2014 start or change a paid plan. `/upgrade` opens the embedded\n  checkout (Stripe Elements inline) on UI hosts and returns a hosted-checkout\n  URL on text hosts.\n- **Manage account** \u2014 current plan, balance, usage, payment method, cancel\n  or reactivate auto-renewal. Credits + usage are folded inline into the\n  account view. `/manage_account`.\n- **Top up credits** \u2014 add SolvaPay credits for usage-based plans.\n  `/topup`.\n- **Activate plan** \u2014 pick a plan from the list or activate a specific plan\n  by `planRef`. Free plans activate immediately, usage-based plans activate\n  when balance covers the configured usage, paid plans return the embedded\n  checkout or a hosted-checkout URL. `/activate_plan`.\n\n## How it fits together\n\nEach intent tool returns a full `BootstrapPayload` (merchant + product + plans\n+ customer snapshot) so the embedded UI never fires per-view read calls. When\na paywalled data tool hits the usage limit, its response carries the same\npayload with `view: \"paywall\"`, letting the host open the UI directly on the\npaywall screen \u2014 no second tool call required.\n\nAuth is handled by the SolvaPay OAuth bridge (see `createMcpOAuthBridge`). The\nbridge injects `customer_ref` onto every authenticated request; tools that\nneed an authenticated caller return `Unauthorized` when it is missing.\n\n## Also see\n\n- `docs://solvapay/overview.md` (this resource) \u2014 agent-facing narration.\n- `ui://<app>/mcp-app.html` \u2014 the embedded UI shell.\n- `tools/list` + `prompts/list` \u2014 programmatic discovery of the intent tools\n  and their slash-command shortcuts.\n- Documentation: https://docs.solvapay.com/sdks/typescript/guides/mcp-app.\n";
+
+/**
+ * `buildPayableHandler(solvaPay, ctx, handler)` — framework-neutral
+ * wrapper that produces an MCP tool handler enforcing the SolvaPay
+ * paywall, auto-attaching `_meta.ui` to paywall results, and (when a
+ * `buildBootstrap` is provided) embedding the full `BootstrapPayload`
+ * in `structuredContent` so the React shell can render the paywall
+ * view without a follow-up tool call.
+ *
+ * Merchant handlers receive a `ResponseContext` as their second
+ * argument and return the `ResponseResult` envelope produced by
+ * `ctx.respond(data, options?)`. `buildPayableHandler` unwraps the
+ * envelope — overlaying `options.text` / `options.nudge` and flushing
+ * queued `ctx.emit(...)` blocks into the terminal response.
+ *
+ * Every SolvaPay MCP adapter (`@solvapay/mcp`, future `fastmcp` /
+ * `fastmcp` adapters) wraps this in its framework-specific
+ * `registerTool` / `registerAppTool` call.
+ */
+
+interface BuildPayableHandlerContext {
+    /** SolvaPay product ref the tool is protected against. */
+    product: string;
+    /** UI resource URI the MCP host should open to render the paywall view. */
+    resourceUri: string;
+    /**
+     * Builds the full `BootstrapPayload` to embed on paywall results.
+     * Wire from `buildSolvaPayDescriptors(...).buildBootstrapPayload`.
+     */
+    buildBootstrap?: BuildBootstrapPayloadFn;
+    /**
+     * Override customer-ref extraction. Defaults to the MCP adapter's
+     * behavior (reads `extra.authInfo.extra.customer_ref`).
+     */
+    getCustomerRef?: (args: Record<string, unknown>, extra?: McpToolExtra) => string | Promise<string>;
+}
+/**
+ * Merchant handler contract: `(args, ctx) => ctx.respond(data, options?)`.
+ * `buildPayableHandler` unwraps the returned `ResponseResult` envelope
+ * into the adapter-facing `SolvaPayCallToolResult`.
+ */
+type MerchantHandler<TArgs, TResult> = (args: TArgs, ctx: ResponseContext) => Promise<ResponseResult<TResult>>;
+/**
+ * Build a paywall-protected MCP tool handler. Returned function is a
+ * `(args, extra) => Promise<SolvaPayCallToolResult>` that any MCP
+ * adapter can register directly.
+ *
+ * The handler:
+ *  1. Builds a `ResponseContext` from the pre-check `LimitResponseWithPlan`
+ *     and passes it as the second arg to the merchant handler.
+ *  2. Routes the call through `solvaPay.payable({ product }).mcp(wrappedBusinessLogic)`.
+ *  3. Detects paywall results via `isPaywallStructuredContent`.
+ *  4. Rewrites `structuredContent` as a full `BootstrapPayload` with
+ *     `view: 'paywall'` + the original gate content on `paywall`
+ *     (when `buildBootstrap` is provided — otherwise leaves the raw
+ *     gate content intact).
+ *  5. Stamps `_meta.ui = { resourceUri }` so the host knows which UI
+ *     resource to open.
+ *  6. Unwraps the merchant's `ResponseResult` envelope into the
+ *     terminal `SolvaPayCallToolResult`: applies `options.text` /
+ *     `options.nudge` overlays and flushes `ctx.emit(...)` blocks into
+ *     `content[]`.
+ *  7. Silently ignores `options.units` (V1 billing stays at one credit
+ *     per call; V1.1 will thread it into `trackUsage`).
+ */
+declare function buildPayableHandler<TArgs extends Record<string, unknown>, TResult>(solvaPay: SolvaPay, ctx: BuildPayableHandlerContext, handler: MerchantHandler<TArgs, TResult>): (args: Record<string, unknown>, extra?: McpToolExtra) => Promise<SolvaPayCallToolResult>;
+
+/**
+ * Framework-neutral OAuth discovery JSON builders. These are runtime-agnostic
+ * (no Node, no fetch, no Express) — both `@solvapay/mcp-express` and
+ * `@solvapay/mcp-fetch` import them to produce the well-known responses.
+ *
+ * Kept in `@solvapay/mcp-core` so third-party adapter authors (raw JSON-RPC,
+ * `fastmcp`, …) can reuse the exact same shapes with zero transitive deps.
+ */
+interface OAuthBridgePaths {
+    register?: string;
+    authorize?: string;
+    token?: string;
+    revoke?: string;
+}
+interface OAuthAuthorizationServerOptions {
+    publicBaseUrl: string;
+    paths?: OAuthBridgePaths;
+}
+declare const DEFAULT_OAUTH_PATHS: Required<OAuthBridgePaths>;
+declare function withoutTrailingSlash(value: string): string;
+declare function resolveOAuthPaths(paths?: OAuthBridgePaths): Required<OAuthBridgePaths>;
+declare function getOAuthProtectedResourceResponse(publicBaseUrl: string): {
+    resource: string;
+    authorization_servers: string[];
+    scopes_supported: string[];
+};
+declare function getOAuthAuthorizationServerResponse({ publicBaseUrl, paths, }: OAuthAuthorizationServerOptions): {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    registration_endpoint: string;
+    revocation_endpoint: string;
+    token_endpoint_auth_methods_supported: string[];
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    scopes_supported: string[];
+    code_challenge_methods_supported: string[];
+};
+
+/**
+ * MCP OAuth bearer-token helper utilities.
+ *
+ * These helpers are intentionally lightweight and do not verify JWT
+ * signatures. Use them after token validation (for example via
+ * `/v1/customer/auth/userinfo`).
+ */
+declare class McpBearerAuthError extends Error {
+    constructor(message: string);
+}
+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;
+
+/**
+ * Build an MCP `authInfo` envelope from an `Authorization: Bearer <jwt>`
+ * header. Populates `authInfo.extra.customer_ref` so downstream
+ * `getCustomerRef` extractors (adapter + descriptor handlers) can read
+ * the caller identity without re-parsing the token.
+ */
+
+interface BuildAuthInfoFromBearerOptions extends McpBearerCustomerRefOptions {
+    clientId?: string;
+    defaultScopes?: string[];
+    includePayload?: boolean;
+}
+declare function buildAuthInfoFromBearer(authorization?: string | null, options?: BuildAuthInfoFromBearerOptions): McpToolExtra['authInfo'] | null;
+
+export { type BootstrapCustomer, type BootstrapMerchant, type BootstrapPayload, type BootstrapPlan, type BootstrapProduct, type BuildAuthInfoFromBearerOptions, type BuildBootstrapPayloadFn, type BuildPayableHandlerContext, type BuildSolvaPayDescriptorsOptions, type BuildSolvaPayRequestOptions, type ContentBlock, type CreateBuildBootstrapPayloadOptions, type CustomerSnapshot, DEFAULT_OAUTH_PATHS, type IntentTool, MCP_TOOL_NAMES, type McpAdapterOptions, McpBearerAuthError, type McpBearerCustomerRefOptions, type McpToolExtra, type McpToolName, NARRATORS, type NarratorOutput, type NudgeSpec, type OAuthAuthorizationServerOptions, type OAuthBridgePaths, OPEN_TOOL_FOR_VIEW, type PayableHandler, type PaywallToolResult, type PaywallToolResultContext, type PaywallUiMeta, type PaywallUiMetaInput, type ResponseContext, type ResponseOptions, type ResponseResult, SOLVAPAY_DEFAULT_CSP, SOLVAPAY_MCP_VIEW_KINDS, SOLVAPAY_OVERVIEW_MARKDOWN, SOLVAPAY_OVERVIEW_MIME_TYPE, SOLVAPAY_OVERVIEW_URI, type SolvaPayCallToolResult, type SolvaPayDescriptorBundle, type SolvaPayDocsResourceDescriptor, type SolvaPayMcpCsp, type SolvaPayMcpPaywallContent, type SolvaPayMcpViewKind, type SolvaPayMerchantBranding, type SolvaPayPromptDescriptor, type SolvaPayPromptResult, type SolvaPayResourceDescriptor, type SolvaPayToolAnnotations, type SolvaPayToolDescriptor, type SolvaPayToolIcon, type SolvaPayToolMode, TOOL_FOR_VIEW, VIEW_FOR_OPEN_TOOL, VIEW_FOR_TOOL, balanceSummary, buildAuthInfoFromBearer, buildPayableHandler, buildPaywallUiMeta, buildSolvaPayDescriptors, buildSolvaPayPrompts, buildSolvaPayRequest, createBuildBootstrapPayload, decodeJwtPayload, defaultGetCustomerRef, enrichPurchase, extractBearerToken, getCustomerRefFromBearerAuthHeader, getCustomerRefFromJwtPayload, getOAuthAuthorizationServerResponse, getOAuthProtectedResourceResponse, mergeCsp, narrateActivatePlan, narrateManageAccount, narrateTopup, narrateUpgrade, narratedToolResult, parseMode, paywallToolResult, previewJson, resolveOAuthPaths, toolErrorResult, toolResult, uiPlaceholder, withoutTrailingSlash };