@solvapay/react 1.0.9-preview.1 → 1.0.9

package/dist/mcp/index.d.ts

@@ -0,0 +1,1013 @@
+import { s as SolvaPayTransport, t as PaywallStructuredContent, Q as SolvaPayProviderInitial, x as SolvaPayConfig } from '../index-onWNU7iT.js';
+import { TOOL_FOR_VIEW, SolvaPayMcpViewKind, NudgeSpec, BootstrapMerchant, BootstrapProduct, BootstrapPlan, BootstrapCustomer } from '@solvapay/mcp-core';
+export { MCP_TOOL_NAMES, McpToolName } from '@solvapay/mcp-core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React from 'react';
+import '@stripe/stripe-js';
+import '../adapters/auth.js';
+
+/**
+ * MCP App adapter — produces a `SolvaPayTransport` that routes every call
+ * through `app.callServerTool` instead of HTTP.
+ *
+ * Use with `SolvaPayProvider` when the React tree is hosted inside an
+ * MCP App (where Stripe.js and direct HTTP to your backend are both
+ * blocked by the host sandbox):
+ *
+ * ```tsx
+ * import { App } from '@modelcontextprotocol/ext-apps'
+ * import { SolvaPayProvider } from '@solvapay/react'
+ * import { createMcpAppAdapter } from '@solvapay/react/mcp'
+ *
+ * const app = new App({ name: 'solvapay', version: '1.0.0' })
+ * const transport = createMcpAppAdapter(app)
+ *
+ * <SolvaPayProvider config={{ transport }}>...</SolvaPayProvider>
+ * ```
+ *
+ * The adapter is tool-name-based: unimplemented tools surface as errors from
+ * the MCP server, which are re-thrown with the server's text payload as the
+ * message. Call sites can feature-detect by catching and matching.
+ */
+
+/**
+ * Minimal shape of `@modelcontextprotocol/sdk` `CallToolResult` — kept here
+ * so consumers don't need `@modelcontextprotocol/sdk` installed just to
+ * satisfy TypeScript when they use the adapter.
+ */
+interface CallToolResultLike$1 {
+    isError?: boolean;
+    structuredContent?: unknown;
+    content?: Array<{
+        type: string;
+        text?: string;
+    }>;
+}
+/**
+ * Minimal shape of `@modelcontextprotocol/ext-apps` `App` — see the package
+ * docs for the full interface. We only depend on `callServerTool`, so any
+ * object satisfying this shape works (easier to mock in tests).
+ */
+interface McpAppLike {
+    callServerTool: (input: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }) => Promise<CallToolResultLike$1>;
+}
+/**
+ * Wrap an MCP App (or any object implementing `callServerTool`) as a
+ * `SolvaPayTransport`. Every provider-level data-access call tunnels
+ * through `app.callServerTool(toolName, args)`.
+ */
+declare function createMcpAppAdapter(app: McpAppLike): SolvaPayTransport;
+
+/**
+ * Probe whether `@stripe/stripe-js` can mount inside the current MCP host
+ * sandbox. Compliant hosts (basic-host, ChatGPT) honour the declared
+ * `_meta.ui.csp.frameDomains` and Stripe loads normally; non-compliant
+ * hosts (Claude today — see anthropics/claude-ai-mcp#40) hardcode
+ * `frame-src 'self' blob: data:` and the nested card iframe is refused.
+ *
+ * We race `loadStripe()` against a 3s timeout — in the blocked case
+ * Stripe.js either throws a ContentSecurityPolicy error or the promise
+ * simply never resolves, and the timeout wins.
+ *
+ * Note on the key: `publishableKey` is SolvaPay's **platform** Stripe pk
+ * (same one the backend returns from `create_payment_intent`). It is used
+ * here only to satisfy `loadStripe()`'s validator so we can exercise
+ * `frameDomains` — we never feed it into `confirmPayment`. The real
+ * payment flow re-fetches the pk (and the connected `accountId`) from
+ * `create_payment_intent` and boots its own `Stripe` instance via the
+ * SDK's `useCheckout`/`useTopup`. SolvaPay is a Stripe Connect direct-
+ * charge platform, so all browser-side Stripe calls pair the platform
+ * pk with `{ stripeAccount: acct_XXX }`; the connected merchant's own
+ * publishable key is never involved.
+ */
+type StripeProbeState = 'loading' | 'ready' | 'blocked';
+declare function useStripeProbe(publishableKey: string | null): StripeProbeState;
+
+declare function useHostLocale(): string;
+
+interface ToolResultParams {
+    isError?: boolean;
+    content?: unknown;
+    structuredContent?: unknown;
+    _meta?: unknown;
+}
+interface AppWithToolResult {
+    getHostContext?: () => {
+        toolInfo?: {
+            tool?: {
+                name?: string;
+            };
+        };
+    } | undefined;
+    addEventListener?: (evt: string, handler: (params: ToolResultParams) => void) => void;
+    removeEventListener?: (evt: string, handler: (params: ToolResultParams) => void) => void;
+    ontoolresult?: ((params: ToolResultParams) => void) | undefined;
+}
+interface McpToolResult<T> {
+    structuredContent: T | null;
+    content: Array<{
+        type: string;
+        text?: string;
+    }>;
+    toolName: string | null;
+}
+declare function useMcpToolResult<T = unknown>(app: AppWithToolResult): McpToolResult<T>;
+
+/**
+ * Minimal shape of `@modelcontextprotocol/ext-apps` `App` needed by
+ * the bridge. Both methods are optional so older hosts (and tests)
+ * don't have to stub them — we feature-detect at call time.
+ */
+interface McpBridgeAppLike {
+    updateModelContext?: (params: {
+        content?: Array<{
+            type: 'text';
+            text: string;
+        }>;
+        structuredContent?: Record<string, unknown>;
+    }) => Promise<unknown> | void;
+    sendMessage?: (params: {
+        role: 'user';
+        content: Array<{
+            type: 'text';
+            text: string;
+        }>;
+    }) => Promise<unknown> | void;
+}
+interface NotifyModelContextParams {
+    /** Short, plain-text update ("User selected Pro"). */
+    text?: string;
+    /**
+     * Raw structured content passthrough for richer payloads.
+     * Overrides `text` if both are provided.
+     */
+    structuredContent?: Record<string, unknown>;
+}
+interface SendMessageParams {
+    /** User-visible follow-up copy ("Topped up $18. Ready to keep working."). */
+    text: string;
+}
+/**
+ * Success events the MCP bridge knows how to follow up in chat on.
+ * Extended via the `messageOnSuccess` prop — merchants return
+ * alternate copy (or `null` to suppress) per event.
+ */
+type McpSuccessEvent = {
+    kind: 'topup';
+    amountMinor: number;
+    currency: string;
+} | {
+    kind: 'plan-activated';
+    planName: string | null;
+};
+type McpMessageOnSuccess = (evt: McpSuccessEvent) => string | null;
+interface McpBridgeValue {
+    /**
+     * Emit `ui/update-model-context` to the host. Feature-detected —
+     * resolves as a no-op on hosts that don't implement the method.
+     * Errors are swallowed: a failed host update shouldn't break the
+     * committed user action that triggered it.
+     */
+    notifyModelContext: (params: NotifyModelContextParams) => Promise<void>;
+    /**
+     * Emit `ui/message` to the host. Feature-detected and error-safe
+     * for the same reason.
+     */
+    sendMessage: (params: SendMessageParams) => Promise<void>;
+    /**
+     * Phase 5 — post a user-visible follow-up after a committed success
+     * (topup completed, plan activated). Resolves the copy via the
+     * merchant's `messageOnSuccess` override (or a built-in default)
+     * and forwards to `sendMessage`. Returning `null` from
+     * `messageOnSuccess` suppresses the follow-up.
+     */
+    notifySuccess: (evt: McpSuccessEvent) => Promise<void>;
+}
+interface McpBridgeProviderProps {
+    app: McpBridgeAppLike;
+    /**
+     * Per-event override for the Phase-5 success follow-up copy.
+     * Return `null` to suppress the follow-up for that event. Defaults
+     * are provided for `topup` and `plan-activated`; hosts that don't
+     * support `ui/message` silently no-op via the feature-detect in
+     * `sendMessage`.
+     */
+    messageOnSuccess?: McpMessageOnSuccess;
+    children: React.ReactNode;
+}
+declare function McpBridgeProvider({ app, messageOnSuccess, children }: McpBridgeProviderProps): react_jsx_runtime.JSX.Element;
+declare function useMcpBridge(): McpBridgeValue;
+
+/**
+ * Bootstrap helper for SolvaPay MCP Apps.
+ *
+ * `fetchMcpBootstrap(app)` — kicks off the MCP session by invoking the
+ * `open_*` tool matching the host's invocation context and returns the
+ * view discriminator + bootstrap payload every view needs (merchant,
+ * product, plans, and customer snapshot).
+ */
+
+/**
+ * @deprecated Use `SolvaPayMcpViewKind` from `@solvapay/mcp-core` directly.
+ * Kept as a type alias so existing consumers don't break.
+ */
+type McpView = SolvaPayMcpViewKind;
+/**
+ * Bootstrap payload returned from `fetchMcpBootstrap`. Structurally
+ * compatible with `BootstrapPayload` from `@solvapay/mcp-core` but narrows
+ * `paywall` to the server-owned `PaywallStructuredContent` union so
+ * the client-side views can discriminate on `kind`.
+ */
+interface McpBootstrap {
+    view: SolvaPayMcpViewKind;
+    productRef: string;
+    stripePublishableKey: string | null;
+    returnUrl: string;
+    /**
+     * Set when the MCP host invokes `open_paywall` — the structured
+     * content gets forwarded on the bootstrap payload so the client
+     * doesn't have to re-fetch it. Only populated for `view: 'paywall'`.
+     */
+    paywall?: PaywallStructuredContent;
+    /**
+     * Upsell strip spec attached when `view: 'nudge'`. `McpNudgeView`
+     * renders `McpUpsellStrip` using this.
+     */
+    nudge?: NudgeSpec;
+    /**
+     * Merchant tool result data embedded alongside a nudge so the shell
+     * can preview it without a follow-up tool call. Only populated when
+     * `view: 'nudge'`.
+     */
+    data?: unknown;
+    /** Product-scoped snapshot — always present. */
+    merchant: BootstrapMerchant;
+    product: BootstrapProduct;
+    plans: BootstrapPlan[];
+    /** Per-customer snapshot — null when the bootstrap call was unauthenticated. */
+    customer: BootstrapCustomer | null;
+}
+/**
+ * Extended `McpAppLike` shape used by `fetchMcpBootstrap` — the base adapter
+ * only needs `callServerTool`, but the bootstrap helper also reads the
+ * host context to infer which `open_*` tool the host invoked.
+ *
+ * The return type is intentionally loose so the real
+ * `@modelcontextprotocol/ext-apps` `McpUiHostContext` is structurally
+ * assignable without forcing consumers into our narrower shape.
+ */
+interface McpAppBootstrapLike extends McpAppLike {
+    getHostContext: () => McpHostContextLike | undefined;
+}
+/**
+ * Structural shape of `McpUiHostContext` for the fields `fetchMcpBootstrap`
+ * reads. Loose on purpose — we only need `toolInfo?.tool?.name`.
+ */
+interface McpHostContextLike {
+    toolInfo?: {
+        tool?: {
+            name?: string;
+        };
+    };
+    [key: string]: unknown;
+}
+interface CallToolResultLike {
+    isError?: boolean;
+    structuredContent?: unknown;
+    content?: Array<{
+        type: string;
+        text?: string;
+    }>;
+}
+/**
+ * Names of the SolvaPay transport tools whose results resolve through
+ * the adapter promise returned by `callServerTool(...)`. `ui/notifications/
+ * tool-result` payloads for these tools are already awaited by the
+ * caller, so `<McpApp>` ignores them to avoid double-applying state.
+ *
+ * Derived from `MCP_TOOL_NAMES` minus the intent tools in
+ * `TOOL_FOR_VIEW`, so adding a new transport tool requires exactly one
+ * edit (in `@solvapay/mcp-core/tool-names`).
+ */
+declare const SOLVAPAY_TRANSPORT_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * True when `name` is one of SolvaPay's transport tools (payments,
+ * sessions, renewal, activation). `<McpApp>` uses this to gate its live
+ * `toolresult` subscription — transport tool notifications are ignored
+ * because the `callServerTool` adapter promise already carries the
+ * authoritative result.
+ */
+declare function isTransportToolName(name: string): boolean;
+/**
+ * Classification of the host-invoked tool that opened the widget iframe.
+ * Drives `<McpApp>`'s mount branching:
+ *
+ *  - `intent`  — one of `upgrade` / `manage_account` / `topup`. Call
+ *                the corresponding tool via `fetchMcpBootstrap`.
+ *  - `data`    — a merchant-registered paywalled tool (e.g.
+ *                `search_knowledge`). The host opened the widget from
+ *                its paywall/nudge result; wait for the initial
+ *                `ui/notifications/tool-result` instead of re-calling
+ *                the tool (which would consume another unit).
+ *  - `other`   — no tool info, or a SolvaPay transport tool as the
+ *                iframe entry point (rare). Fall back to the `upgrade`
+ *                intent tool for a fresh snapshot.
+ */
+type HostEntryClassification = {
+    kind: 'intent';
+    toolName: string;
+    view: keyof typeof TOOL_FOR_VIEW;
+} | {
+    kind: 'data';
+    toolName: string;
+} | {
+    kind: 'other';
+    toolName?: string;
+};
+/**
+ * Classify the host-invoked tool that opened the iframe. Reads
+ * `app.getHostContext()?.toolInfo?.tool?.name` and consults the
+ * `VIEW_FOR_TOOL` / `SOLVAPAY_TRANSPORT_TOOL_NAMES` tables.
+ *
+ * Exported so integrators who own their `<McpApp>` mount (or who build
+ * fully custom widgets) can branch the same way.
+ */
+declare function classifyHostEntry(app: McpAppBootstrapLike): HostEntryClassification;
+/**
+ * Kick off the MCP session by calling the `open_*` tool that matches the
+ * host's invocation context. Returns the bootstrap payload every view
+ * needs (product ref, publishable key, return url) along with the view
+ * discriminator so the top-level router can pick the right screen.
+ *
+ * Used for intent-tool iframe entries and for `refreshInitial` after a
+ * committed action (purchase, topup, etc.). Data-tool iframe entries
+ * (paywall/nudge) bypass this helper; `<McpApp>` consumes the initial
+ * `ui/notifications/tool-result` directly via
+ * `parseBootstrapFromToolResult` so the merchant tool is not re-called.
+ */
+declare function fetchMcpBootstrap(app: McpAppBootstrapLike): Promise<McpBootstrap>;
+/**
+ * Parse a raw `CallToolResult`-shaped payload into an `McpBootstrap`.
+ *
+ * Shared between `fetchMcpBootstrap` (client-initiated) and the live
+ * `ui/notifications/tool-result` subscription (`<McpApp>` Phase 3).
+ * Throws on missing product ref / invalid return URL so callers can
+ * surface the error to `onInitError` instead of half-applying state.
+ */
+declare function parseBootstrapFromToolResult(result: CallToolResultLike, toolName: string, fallbackView: SolvaPayMcpViewKind): McpBootstrap;
+/**
+ * Shape of the `ui/notifications/tool-result` params we care about.
+ * Loose on purpose — `McpUiToolResultNotification['params']` is
+ * structurally compatible.
+ */
+interface ToolResultNotificationParams {
+    isError?: boolean;
+    content?: Array<{
+        type: string;
+        text?: string;
+    }>;
+    structuredContent?: unknown;
+    _meta?: unknown;
+}
+type ToolResultListener = (params: ToolResultNotificationParams) => void;
+/**
+ * Subset of `@modelcontextprotocol/ext-apps` `App` events that
+ * `waitForInitialToolResult` subscribes to. Mirrors the contract in
+ * `hooks/useMcpToolResult.ts` so either entry point works with
+ * composable `addEventListener` hosts or legacy `ontoolresult` mocks.
+ */
+interface AppToolResultEvents {
+    addEventListener?: (evt: string, handler: ToolResultListener) => void;
+    removeEventListener?: (evt: string, handler: ToolResultListener) => void;
+    ontoolresult?: ToolResultListener | undefined;
+}
+interface WaitForInitialToolResultOptions {
+    /**
+     * How long to wait (ms) for the first non-error, non-transport
+     * `toolresult` notification before giving up. Defaults to 2000ms —
+     * the host is expected to fire the initial notification immediately
+     * after `ui/initialize`, so 2s is a generous budget.
+     */
+    timeoutMs?: number;
+    /**
+     * Optional signal to cancel the wait (e.g. component unmount). When
+     * aborted, the returned promise resolves with `timedOut: true`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Fallback `view` passed to `parseBootstrapFromToolResult` when the
+     * incoming payload doesn't carry a `structuredContent.view`. Defaults
+     * to `'paywall'` since data-tool entries are paywall/nudge by
+     * construction.
+     */
+    fallbackView?: SolvaPayMcpViewKind;
+}
+type WaitForInitialToolResultResult = {
+    timedOut: false;
+    bootstrap: McpBootstrap;
+    toolName: string | null;
+    params: ToolResultNotificationParams;
+} | {
+    timedOut: true;
+    bootstrap: null;
+    toolName: null;
+    params: null;
+};
+/**
+ * One-shot helper: subscribes to `toolresult`, resolves with the first
+ * non-error, non-transport payload parsed into an `McpBootstrap`, and
+ * unsubscribes.
+ *
+ * Intended for integrators who mount their own shell on top of
+ * `createMcpAppAdapter` and need the same "consume the initial
+ * tool-result payload" semantics `<McpApp>` uses internally. Subscribe
+ * **before** calling `app.connect()` to avoid missing the initial
+ * notification the host fires after `ui/initialize`.
+ *
+ * Parse errors are surfaced via the returned promise's rejection; a
+ * timeout resolves with `timedOut: true` rather than throwing.
+ */
+declare function waitForInitialToolResult(app: McpAppBootstrapLike & AppToolResultEvents, options?: WaitForInitialToolResultOptions): Promise<WaitForInitialToolResultResult>;
+
+/**
+ * Seed the module-level hook caches (`merchantCache`, `productCache`,
+ * `plansCache`, `paymentMethodCache`) from a `SolvaPayProviderInitial`
+ * snapshot so the MCP App shell never fires a first-mount fetch.
+ *
+ * Called from `<McpApp>` before rendering `<SolvaPayProvider>`. The
+ * seeded entries share the same 5-minute TTL as normal fetches — once
+ * expired the caches fall back to their existing behaviour (which, for
+ * MCP, returns the seeded value because the hooks' fetchers become
+ * no-ops after the read tools are dropped).
+ */
+
+/**
+ * Pre-populate the hook caches with the snapshot from the bootstrap
+ * payload. The caller passes the live `SolvaPayConfig` (the same object
+ * it hands to `<SolvaPayProvider>`) so every cache key is computed with
+ * the identical `createTransportCacheKey` logic the hooks use — that way
+ * the seeded entries match the keys `useMerchant` / `useProduct` /
+ * `usePlans` / `usePaymentMethod` read on first render.
+ */
+declare function seedMcpCaches(initial: SolvaPayProviderInitial, config: SolvaPayConfig): void;
+
+/**
+ * Per-element className overrides for `<Mcp*View>` primitives.
+ *
+ * Mirrors the `CurrentPlanCardClassNames` pattern — every key is optional,
+ * and any empty string falls through to the default `solvapay-mcp-*` class
+ * defined in `@solvapay/react/mcp/styles.css`. Integrators who ship their
+ * own CSS can disable defaults per-slot by assigning `''`.
+ */
+interface McpViewClassNames {
+    card?: string;
+    stack?: string;
+    heading?: string;
+    muted?: string;
+    button?: string;
+    linkButton?: string;
+    notice?: string;
+    error?: string;
+    awaitingHeader?: string;
+    balanceRow?: string;
+    amountPicker?: string;
+    amountOptions?: string;
+    amountOption?: string;
+    amountCustom?: string;
+    topupForm?: string;
+    activationFlow?: string;
+}
+/**
+ * Resolve a `McpViewClassNames` partial against the defaults — consumer
+ * overrides win when defined, empty strings disable a slot's class entirely,
+ * unset keys fall through to the default.
+ */
+declare function resolveMcpClassNames(overrides: McpViewClassNames | undefined): Required<McpViewClassNames>;
+
+interface McpAccountViewProps {
+    classNames?: McpViewClassNames;
+    /**
+     * Called when the user clicks the "Top up" link inside the balance
+     * row or Customer details card. The `<McpAppShell>` wires this to a
+     * tab switch so nothing re-mounts; consumers outside the shell can
+     * leave it unset.
+     */
+    onTopup?: () => void;
+    /**
+     * Called when the user clicks "Pick a plan" from the empty state or
+     * "Change plan" / "Upgrade" on the plan card. Wired by the shell to
+     * switch to the Plan tab.
+     */
+    onChangePlan?: () => void;
+    /**
+     * Skip the Customer + Seller detail cards. `<McpAppShell>` sets this
+     * to `true` at the `xl` breakpoint because the same cards render in
+     * the persistent right-hand sidebar.
+     */
+    hideDetailCards?: boolean;
+}
+declare function McpAccountView({ classNames, onTopup, onChangePlan, hideDetailCards, }: McpAccountViewProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Shared types and pure helpers for the MCP checkout state machine.
+ *
+ * The plan → amount → payment → success flow is used by both
+ * `<McpCheckoutView>` (the `activate_plan` surface) and
+ * `<McpPaywallView>` (the paywall surface) so the helpers live in a
+ * dedicated module to keep the state machine and step components slim.
+ */
+
+/**
+ * Structural subset of a bootstrap plan. Kept here so step components
+ * can type against it without pulling in the full `@solvapay/mcp`
+ * bootstrap types (which would create a dep cycle).
+ */
+interface BootstrapPlanLike {
+    reference?: string;
+    name?: string;
+    type?: string;
+    planType?: string;
+    price?: number;
+    currency?: string;
+    billingCycle?: string | null;
+    meterRef?: string | null;
+    creditsPerUnit?: number | null;
+    requiresPayment?: boolean;
+}
+
+interface McpCheckoutViewProps {
+    productRef: string;
+    /**
+     * Stripe publishable key used by `useStripeProbe` to detect CSP-blocked
+     * hosts. Pass `null` to skip the probe and render the hosted fallback
+     * directly (useful for tests or hosts known to refuse `js.stripe.com`).
+     */
+    publishableKey?: string | null;
+    returnUrl: string;
+    onPurchaseSuccess?: () => void;
+    /**
+     * Called when the view wants to bounce the customer to the
+     * dedicated Top up surface. Unused by the new activation flow
+     * (PAYG top-ups happen inline here) but kept as a prop for
+     * backward compatibility with integrators that wired it up.
+     */
+    onRequestTopup?: () => void;
+    /**
+     * True when the checkout view was reached via the paywall takeover.
+     * Drives the amber "Upgrade to continue" banner and the
+     * `"Stay on Free"` dismiss link on the plan-selection step. The
+     * brief's §6 invariant: "banner appears iff the customer hit the
+     * paywall."
+     */
+    fromPaywall?: boolean;
+    /**
+     * Paywall kind surfaced from `bootstrap.paywall.kind` when
+     * `fromPaywall` is true. Selects between the two banner copies:
+     * `'payment_required'` → quota-exhausted language;
+     * `'activation_required'` → tool-needs-a-paid-plan language.
+     */
+    paywallKind?: 'payment_required' | 'activation_required';
+    /**
+     * Product plans snapshot from `bootstrap.plans`. Used to locate
+     * the PAYG plan for the `popular` / `recommended` tag and sort
+     * the plan cards (PAYG first, then recurring ascending). Falls
+     * back to `PlanSelector`'s own `usePlans` fetch when omitted.
+     */
+    plans?: readonly BootstrapPlanLike[];
+    /**
+     * Invoked at the end of a successful activation — chained before
+     * `onClose()` so the host sees a re-seeded bootstrap if it
+     * re-invokes the original tool.
+     */
+    onRefreshBootstrap?: () => void | Promise<void>;
+    /**
+     * Ask the host to unmount the MCP app. Wired by `<McpApp>` to
+     * `app.requestTeardown()`. Used by `"Back to chat"` on the success
+     * surface and the `"Stay on Free"` dismiss link. When omitted,
+     * those affordances disappear.
+     */
+    onClose?: () => void;
+    classNames?: McpViewClassNames;
+    children?: React.ReactNode;
+}
+declare function McpCheckoutView({ productRef, publishableKey, returnUrl, onPurchaseSuccess, onRequestTopup: _onRequestTopup, fromPaywall, paywallKind, plans, onRefreshBootstrap, onClose, classNames, children, }: McpCheckoutViewProps): react_jsx_runtime.JSX.Element;
+
+interface McpPaywallViewProps {
+    content: PaywallStructuredContent;
+    /**
+     * Stripe publishable key. Passing a key enables the embedded checkout
+     * path once `useStripeProbe` reports `'ready'`. `null` forces the
+     * hosted-link fallback.
+     */
+    publishableKey?: string | null;
+    returnUrl: string;
+    classNames?: McpViewClassNames;
+    /** Consumers typically pass a function that dismisses the view after resolution. */
+    onResolved?: () => void;
+    /**
+     * Product plans snapshot from `bootstrap.plans`. Threaded through to
+     * the shared `EmbeddedCheckout` so the paywall surfaces the same
+     * PAYG-first sorted grid and `popular` tag as `McpCheckoutView`.
+     */
+    plans?: readonly BootstrapPlanLike[];
+    /**
+     * Secondary "Upgrade to <plan> — <price>" CTA rendered below the
+     * paywall's primary (top-up) flow. When set, the paywall view
+     * exposes two routes out of the gate — stay on usage-based by
+     * topping up, or switch to a recurring plan.
+     *
+     * `onClick` fires with the plan the shell derived from
+     * `bootstrap.plans` (first recurring, non-usage-based plan);
+     * consumers typically open `<McpCheckoutView>` for that plan.
+     */
+    upgradeCta?: {
+        label: string;
+        onClick: () => void;
+    };
+}
+declare function McpPaywallView({ content, publishableKey, returnUrl, classNames, onResolved, plans, upgradeCta, }: McpPaywallViewProps): react_jsx_runtime.JSX.Element;
+
+interface McpTopupViewProps {
+    publishableKey?: string | null;
+    returnUrl: string;
+    /**
+     * Called when the Stripe confirm succeeds. Receives the topped-up amount
+     * in minor units (respects zero-decimal currencies — yen not yen×100).
+     */
+    onTopupSuccess?: (amountMinor: number) => void;
+    /**
+     * Called when the user picks "Back to my account" at any step.
+     * Wired by the shell to switch tabs. `undefined` (the paywall
+     * branch) hides the outer back-link.
+     */
+    onBack?: () => void;
+    classNames?: McpViewClassNames;
+}
+declare function McpTopupView({ publishableKey, returnUrl, onTopupSuccess, onBack, classNames, }: McpTopupViewProps): react_jsx_runtime.JSX.Element;
+
+interface McpNudgeViewProps {
+    /**
+     * Full bootstrap snapshot with `nudge` + `data` populated by
+     * `buildPayableHandler`'s success branch.
+     */
+    bootstrap: McpBootstrap;
+    /** Invoked when the user clicks the upsell CTA. */
+    onCta?: () => void;
+    /** Invoked when the user dismisses the strip. */
+    onDismiss?: () => void;
+    classNames?: McpViewClassNames;
+}
+declare function McpNudgeView({ bootstrap, onCta, onDismiss, classNames }: McpNudgeViewProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * The set of surfaces the MCP shell can route to. Lives in its own tiny
+ * file so any module that needs the discriminated union can import it
+ * without cycling through `McpAppShell`.
+ *
+ * `bootstrap.view` (from the server's `open_*` tool response) is the
+ * load-bearing dispatch signal — the shell locks the rendered surface
+ * to whatever the bootstrap named for the invocation's lifetime. The
+ * only in-session surface mutation is the paywall/nudge CTA → checkout
+ * flip, modelled explicitly by the shell's `overrideView` state.
+ */
+type McpViewKind = 'checkout' | 'account' | 'topup' | 'paywall' | 'nudge';
+/**
+ * @deprecated Use `McpViewKind`. This alias exists for one minor
+ * version to give internal callers a grace window on the rename; the
+ * tab metaphor is gone — the shell is surface-routed now.
+ */
+type McpTabKind = McpViewKind;
+
+interface McpAppShellProps {
+    bootstrap: McpBootstrap;
+    views?: McpAppViewOverrides;
+    classNames?: McpViewClassNames;
+    /** Render the footer? Defaults to `true` when the merchant has any of support/terms/privacy URLs. */
+    footer?: boolean;
+    /**
+     * Refresh the bootstrap snapshot. Wired by `<McpApp>` to
+     * `SolvaPayProvider.refreshInitial`. The shell calls this once on
+     * mount so stale caches get re-seeded when the user re-opens the
+     * MCP app after backgrounding it. Errors are swallowed (soft signal).
+     */
+    onRefreshBootstrap?: () => void | Promise<void>;
+    /**
+     * Ask the host to unmount the MCP app. Wired by `<McpApp>` to
+     * `app.requestTeardown()`. The checkout view uses this for its
+     * `"Back to chat"` success CTA and the `"Stay on Free"` dismiss
+     * link. `undefined` hides those affordances so integrators that own
+     * their own mount can opt out.
+     */
+    onClose?: () => void;
+}
+declare function McpAppShell({ bootstrap, views, classNames, footer, onRefreshBootstrap, onClose, }: McpAppShellProps): react_jsx_runtime.JSX.Element;
+interface McpViewRouterProps {
+    /** Surface to render. */
+    view: McpViewKind;
+    bootstrap: McpBootstrap;
+    views?: McpAppViewOverrides;
+    classNames?: McpViewClassNames;
+    /** Whether the shell already renders the customer/seller cards in a sidebar. */
+    suppressDetailCards?: boolean;
+    /**
+     * True when the checkout view was reached via the paywall takeover
+     * (or the shell mounted with `bootstrap.view === 'paywall'`). Drives
+     * the "Upgrade to continue" banner and `"Stay on Free"` dismiss link
+     * inside `McpCheckoutView`.
+     */
+    fromPaywall?: boolean;
+    /**
+     * Called when a surface asks to swap to another surface in-session
+     * (only used by the paywall-dismiss and nudge-CTA handlers). The
+     * shell wires this to its `overrideView` state.
+     */
+    onSurfaceChange?: (next: McpViewKind) => void;
+    /**
+     * Paywall-specific upgrade handler forwarded as `upgradeCta.onClick`
+     * on `<McpPaywallView>`. Defaults to `onSurfaceChange?.('checkout')`.
+     */
+    onPaywallUpgrade?: () => void;
+    /** Nudge-specific CTA handler; defaults to `onSurfaceChange?.('checkout')`. */
+    onNudgeCta?: () => void;
+    /**
+     * Invoked when the account view's "Change plan" affordance fires.
+     * Clears the `fromPaywall` flag before swapping to `'checkout'` so
+     * the banner doesn't render in the change-plan flow.
+     */
+    onChangePlan?: () => void;
+    /**
+     * Forwarded to `McpCheckoutView`'s `"Back to chat"` success CTA so
+     * the shell can reseed its caches before the host unmounts.
+     */
+    onRefreshBootstrap?: () => void | Promise<void>;
+    /**
+     * Forwarded to `McpCheckoutView`'s `"Back to chat"` and
+     * `"Stay on Free"` affordances. Wired by `<McpApp>` to
+     * `app.requestTeardown()`.
+     */
+    onClose?: () => void;
+}
+/**
+ * Single `switch` on `McpViewKind` that resolves each view from the
+ * `views` override map and threads `bootstrap`-derived props through.
+ * Exported so integrators that own their own shell + provider mount
+ * can still get view dispatch for free.
+ */
+declare function McpViewRouter({ view, bootstrap, views, classNames, suppressDetailCards, fromPaywall, onSurfaceChange, onPaywallUpgrade, onNudgeCta, onChangePlan, onRefreshBootstrap, onClose, }: McpViewRouterProps): React.ReactNode;
+
+/**
+ * Minimal host-context shape `<McpApp>` reads. Kept loose so the real
+ * `@modelcontextprotocol/ext-apps` `McpUiHostContext` is structurally
+ * assignable; consumers pass the helpers from `ext-apps` via
+ * `applyContext` instead of depending on this shape directly.
+ */
+type McpUiHostContextLike = any;
+/**
+ * Subset of `@modelcontextprotocol/ext-apps` `App` that `<McpApp>` needs.
+ *
+ * Declared loosely so the real `App` is structurally assignable without
+ * forcing consumers to match our stricter internal typing. Any object
+ * satisfying these call signatures works (handy for tests).
+ */
+interface McpAppFull extends McpAppBootstrapLike, McpAppLike, McpBridgeAppLike {
+    connect: () => Promise<void>;
+    onhostcontextchanged?: any;
+    onteardown?: any;
+    /**
+     * Composable event subscription exposed by
+     * `@modelcontextprotocol/ext-apps` `App` (via `ProtocolWithEvents`).
+     * `<McpApp>` uses this to subscribe to `toolresult` so it can re-route
+     * when the host re-invokes an intent tool against a mounted widget.
+     * Kept optional so minimal test adapters can omit it — the code falls
+     * back to the legacy `ontoolresult` setter.
+     */
+    addEventListener?: (evt: string, handler: (params: any) => void) => void;
+    removeEventListener?: (evt: string, handler: (params: any) => void) => void;
+    ontoolresult?: any;
+    /**
+     * Fire-and-forget request asking the host to unmount the app. When
+     * approved, the host sends `ui/resource-teardown` back via
+     * `onteardown`. Exposed by the real `@modelcontextprotocol/ext-apps`
+     * `App` class — kept optional in the structural type so tests and
+     * minimal adapters don't have to stub it.
+     */
+    requestTeardown?: () => Promise<void> | void;
+}
+interface McpAppViewOverrides {
+    checkout?: React.ComponentType<McpCheckoutViewProps>;
+    account?: React.ComponentType<McpAccountViewProps>;
+    topup?: React.ComponentType<McpTopupViewProps>;
+    paywall?: React.ComponentType<McpPaywallViewProps>;
+    nudge?: React.ComponentType<McpNudgeViewProps>;
+}
+interface McpAppProps {
+    app: McpAppFull;
+    /**
+     * Optional override for the product ref returned by `fetchMcpBootstrap`.
+     * Useful when the client knows which product to target before the
+     * server bootstrap resolves — rarely needed.
+     */
+    productRef?: string;
+    /** Per-view component overrides, e.g. to replace just `account`. */
+    views?: McpAppViewOverrides;
+    /** Per-slot className overrides — forwarded to every built-in view. */
+    classNames?: McpViewClassNames;
+    /** Override the shell-level footer visibility heuristic. */
+    footer?: boolean;
+    /**
+     * Called with the bootstrap error if `app.connect()` or the `open_*`
+     * tool call fails. Consumers typically log it; the default UI already
+     * renders a human-readable error card.
+     */
+    onInitError?: (err: Error) => void;
+    /**
+     * Optional hook to apply host context updates (theme, fonts, safe-area
+     * insets). Defaults to a no-op; pass the helpers from
+     * `@modelcontextprotocol/ext-apps` when you want the turnkey behaviour.
+     *
+     * Kept as a prop instead of a hard import so the SDK doesn't depend on
+     * `@modelcontextprotocol/ext-apps` — host-context primitives live there.
+     */
+    applyContext?: (ctx: McpUiHostContextLike | undefined) => void;
+    /**
+     * Override for the shell's "close this app" handler. Defaults to
+     * `() => app.requestTeardown()`, which asks the host to unmount the
+     * iframe (see `@modelcontextprotocol/ext-apps` `App.requestTeardown`).
+     * Used by the checkout view's `"Back to chat"` and `"Stay on Free"`
+     * affordances; passing `undefined` hides those affordances.
+     */
+    onClose?: () => void;
+    /**
+     * Phase 5 — override the user-visible follow-up copy posted to the
+     * chat after a committed success (topup completed, plan activated).
+     * Return `null` to suppress a specific event; omit the prop entirely
+     * to use the SDK defaults. Hosts that don't support `ui/message`
+     * silently no-op regardless.
+     */
+    messageOnSuccess?: McpMessageOnSuccess;
+}
+declare function McpApp({ app, productRef: productRefOverride, views, classNames, footer, onInitError, applyContext, onClose, messageOnSuccess, }: McpAppProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pure derivation helpers that map a plan / active purchase onto the
+ * activation strategy + action-affordance shape the shell renders per
+ * plan type.
+ *
+ * Keeping these in a standalone module lets the hosted manage page
+ * share the same matrix as the MCP shell — "one plan-shape matrix,
+ * two surfaces" — and makes the 4 × 2 × 3 test matrix from the plan a
+ * pure-function target (no RTL needed).
+ */
+type PlanShape = 'free' | 'trial' | 'usage-based' | 'recurring-unlimited' | 'recurring-metered';
+/**
+ * Strategy the Plan tab uses when the user clicks a plan card:
+ *  - `activate` — free / trial / free-priced recurring: instant activation
+ *    via `ActivationFlow.Summary` + `ActivateButton`.
+ *  - `topup-first` — usage-based: ActivationFlow's `AmountPicker`
+ *    branch.
+ *  - `paid-checkout` — recurring with a non-zero price: mount
+ *    `PaymentFormGate` + `PaymentForm.*` for inline Stripe Elements.
+ */
+type ActivationStrategy = 'activate' | 'topup-first' | 'paid-checkout';
+interface PlanLike {
+    /** `'free' | 'trial' | 'usage-based' | 'recurring'`. */
+    planType?: string | null;
+    price?: number | null;
+    currency?: string | null;
+    meterRef?: string | null;
+    meterId?: string | null;
+    limit?: number | null;
+}
+interface PurchaseSnapshotLike {
+    planSnapshot?: PlanLike | null;
+    /** Whether the customer has a payment method on file. */
+    hasPaymentMethod?: boolean;
+}
+/**
+ * Map a `BootstrapPlan` / `PlanSnapshot` to its concrete shape. The
+ * four shapes are distinct in UX: each drives a different summary
+ * string, a different set of CTAs, and a different activity-strip
+ * variant.
+ */
+declare function resolvePlanShape(plan: PlanLike | null | undefined): PlanShape | null;
+/**
+ * Pick the activation strategy for a plan the user just clicked.
+ *
+ * Rules match the plan's pressure-test: free / trial activate instantly;
+ * usage-based always tops up first; zero-priced recurring activates
+ * instantly; paid recurring goes to Stripe checkout.
+ */
+declare function resolveActivationStrategy(plan: PlanLike | null | undefined): ActivationStrategy;
+/**
+ * Per-variant action flags for the Plan-active card. Only flags that
+ * are `true` render affordances — this collapses the "should we show
+ * Cancel?" boolean maze into a single resolver call.
+ *
+ * Rules from the plan:
+ *  - `topUp` — only on usage-based purchases.
+ *  - `cancel` — recurring (paid subscription) and free plans. PAYG
+ *    has no renewal to cancel.
+ *  - `changePlan` — always, when the product exposes more than one
+ *    plan.
+ *  - `managePortal` — only when the customer has a payment method on
+ *    file. Free plans that never charged a card skip this.
+ *  - `upgrade` — shown *instead of* `changePlan` when the active plan
+ *    is free AND at least one paid plan exists.
+ */
+interface PlanActions {
+    topUp: boolean;
+    cancel: boolean;
+    changePlan: boolean;
+    managePortal: boolean;
+    upgrade: boolean;
+}
+interface PlanActionsInput {
+    purchase: PurchaseSnapshotLike | null | undefined;
+    /** Total plans exposed on the product. */
+    planCount: number;
+    /** Number of paid plans (price > 0, not free) on the product. */
+    paidPlanCount: number;
+}
+declare function resolvePlanActions({ purchase, planCount, paidPlanCount }: PlanActionsInput): PlanActions;
+/**
+ * "Your activity" strip variant shown at the top of a surface when a
+ * returning customer has an active purchase. Hidden when the customer
+ * has no active purchase.
+ */
+type ActivityStripKind = 'none' | 'payg-balance' | 'recurring-unlimited-renew' | 'recurring-metered-usage' | 'free-usage';
+declare function resolveActivityStrip(purchase: PurchaseSnapshotLike | null | undefined): ActivityStripKind;
+
+interface BackLinkProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+    /** Visible label; typically `"Back to my account"` or `"Change amount"`. */
+    label: string;
+    /** Optional override for the arrow glyph (defaults to `←`). */
+    glyph?: string;
+}
+declare function BackLink({ label, glyph, className, onClick, ...rest }: BackLinkProps): react_jsx_runtime.JSX.Element;
+
+interface McpCustomerDetailsCardProps {
+    classNames?: McpViewClassNames;
+    /**
+     * When provided, a "Top up" text button is rendered next to the
+     * Credit balance row. Typically wired to switch the active tab in
+     * the `<McpAppShell>` so the in-iframe navigation stays shell-local.
+     */
+    onTopup?: () => void;
+    /**
+     * Hides the credit balance row even when a non-zero balance is
+     * present. Useful on an unlimited-plan customer whose `balance` is
+     * populated but semantically meaningless.
+     */
+    hideBalance?: boolean;
+}
+/**
+ * Customer details — name, email, customer reference (monospaced, the
+ * value users paste into support tickets). The credit balance row is
+ * only rendered when `balance > 0` to avoid a "0 credits" row on a
+ * brand-new account.
+ */
+declare function McpCustomerDetailsCard({ classNames, onTopup, hideBalance, }: McpCustomerDetailsCardProps): react_jsx_runtime.JSX.Element;
+interface McpSellerDetailsCardProps {
+    classNames?: McpViewClassNames;
+    /** Render the "Verified seller" trust badge next to the heading. */
+    showVerifiedBadge?: boolean;
+}
+/**
+ * Seller details — company name, legal entity, support email/URL,
+ * terms link. Compliance-relevant: a customer paying through the
+ * iframe should see who they're actually paying, to the same level of
+ * detail as hosted checkout.
+ *
+ * Currently pulls from `useMerchant()` only (no org number, postal
+ * address, or public website — those fields aren't on the SDK's
+ * `SdkMerchantResponseDto`). If / when the backend surfaces them, add
+ * them here.
+ */
+declare function McpSellerDetailsCard({ classNames, showVerifiedBadge, }: McpSellerDetailsCardProps): react_jsx_runtime.JSX.Element | null;
+
+interface McpUpsellStripProps {
+    nudge: NudgeSpec;
+    /**
+     * Invoked when the user clicks the CTA. Default CTA per kind is
+     * "Upgrade" / "Renew"; consumers wire this to `openUpgrade()` in
+     * their MCP App shell.
+     */
+    onCta?: () => void;
+    /**
+     * Invoked when the user dismisses the strip. The strip hides locally
+     * regardless of whether a handler is wired.
+     */
+    onDismiss?: () => void;
+    /** Suppress the dismiss button for sticky nudges. Defaults to false. */
+    hideDismiss?: boolean;
+    /** Override the default CTA label. */
+    ctaLabel?: string;
+    /** Override the root element class (intentionally narrow hook). */
+    className?: string;
+}
+declare function McpUpsellStrip({ nudge, onCta, onDismiss, hideDismiss, ctaLabel, className, }: McpUpsellStripProps): react_jsx_runtime.JSX.Element | null;
+
+export { type ActivationStrategy, type ActivityStripKind, type AppToolResultEvents, BackLink, type BackLinkProps, type HostEntryClassification, McpAccountView, type McpAccountViewProps, McpApp, type McpAppBootstrapLike, type McpAppFull, type McpAppLike, type McpAppProps, McpAppShell, type McpAppShellProps, type McpAppViewOverrides, type McpBootstrap, type McpBridgeAppLike, McpBridgeProvider, type McpBridgeProviderProps, type McpBridgeValue, McpCheckoutView, type McpCheckoutViewProps, McpCustomerDetailsCard, type McpCustomerDetailsCardProps, type McpMessageOnSuccess, McpNudgeView, type McpNudgeViewProps, McpPaywallView, type McpPaywallViewProps, McpSellerDetailsCard, type McpSellerDetailsCardProps, type McpSuccessEvent, type McpTabKind, type McpToolResult, McpTopupView, type McpTopupViewProps, type McpUiHostContextLike, McpUpsellStrip, type McpUpsellStripProps, type McpView, type McpViewClassNames, type McpViewKind, McpViewRouter, type McpViewRouterProps, type NotifyModelContextParams, type PlanActions, type PlanActionsInput, type PlanLike, type PlanShape, type PurchaseSnapshotLike, SOLVAPAY_TRANSPORT_TOOL_NAMES, type SendMessageParams, type StripeProbeState, type WaitForInitialToolResultOptions, type WaitForInitialToolResultResult, classifyHostEntry, createMcpAppAdapter, fetchMcpBootstrap, isTransportToolName, parseBootstrapFromToolResult, resolveActivationStrategy, resolveActivityStrip, resolveMcpClassNames, resolvePlanActions, resolvePlanShape, seedMcpCaches, useHostLocale, useMcpBridge, useMcpToolResult, useStripeProbe, waitForInitialToolResult };