@solvapay/react 2.1.1 → 2.2.0-preview-11dbbe603cd1b9a44cc41b5eee3686bc4000f97f

package/dist/mcp/index.d.cts

@@ -1,4 +1,4 @@
-import { v as SolvaPayTransport, _ as SolvaPayProviderInitial, z as SolvaPayConfig, D as BootstrapPlanLike, H as Merchant } from '../shared-D0hmT1qU.cjs';
+import { w as SolvaPayTransport, _ as SolvaPayProviderInitial, D as SolvaPayConfig, B as BootstrapPlanLike, H as Merchant } from '../shared-BQbMyX5V.cjs';
 import { TOOL_FOR_VIEW, SolvaPayMcpViewKind, 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';
@@ -64,12 +64,20 @@ declare function createMcpAppAdapter(app: McpAppLike): SolvaPayTransport;
 
 /**
  * Probe whether `@stripe/stripe-js` can mount inside the current MCP host
- * sandbox. Compliant hosts (basic-host, ChatGPT, MCPJam) honour the
- * declared `_meta.ui.csp.frameDomains` and Stripe loads normally;
- * non-compliant hosts (Claude today — see anthropics/claude-ai-mcp#40)
+ * sandbox. Hosts that deliver the declared `_meta.ui.csp.frameDomains` to
+ * the widget document (basic-host, ChatGPT) let Stripe load normally.
+ * Reading `frameDomains` is not the same as the emitted policy surviving
+ * to the guest document — MCPJam currently reports a runtime mismatch
+ * between its effective CSP model and the browser's enforced policy.
+ * Non-compliant hosts (Claude today — see anthropics/claude-ai-mcp#40)
  * hardcode `frame-src 'self' blob: data:` and the nested Stripe iframes
  * are refused even though the parent script loads fine.
  *
+ * A second, harder constraint: sandbox flags are inherited by descendant
+ * frames. A chain missing `allow-same-origin` cannot host Stripe at all
+ * regardless of `frame-src` — Stripe's own inner iframe fails its
+ * `script-src 'self'` when the ancestor omits it.
+ *
  * ## Why `ready` alone is a lie on Claude
  *
  * Stripe's `PaymentElement` fires its `ready` event as soon as the
@@ -178,6 +186,25 @@ interface McpBridgeAppLike {
             text: string;
         }>;
     }) => Promise<unknown> | void;
+    /**
+     * `ui/open-link` — ask the host to open a URL in the user's browser.
+     * On hosts whose iframe sandbox omits `allow-popups` (Claude) this is
+     * the only way out of the frame: `<a target="_blank">` and
+     * `window.open()` are both dropped there without an error.
+     */
+    openLink?: (params: {
+        url: string;
+    }) => Promise<{
+        isError?: boolean;
+    } | undefined>;
+    /**
+     * Host capabilities resolved during `connect()`. `openLinks` gates
+     * `openLink` — a host can expose the method without declaring
+     * support, and calling it blind would swallow the click.
+     */
+    getHostCapabilities?: () => {
+        openLinks?: unknown;
+    } | undefined;
 }
 interface NotifyModelContextParams {
     /** Short, plain-text update ("User selected Pro"). */
@@ -351,11 +378,10 @@ 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`.
+ *  - `intent`  — the `account` viewer. Call it via `fetchMcpBootstrap`.
  *  - `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.
+ *                iframe entry point (rare). Fall back to the `account`
+ *                viewer for a fresh snapshot.
  *
  * The previous `data` kind was removed with the text-only paywall
  * refactor: payable merchant tools no longer advertise
@@ -363,7 +389,7 @@ declare function isTransportToolName(name: string): boolean;
  * silent success or a paywall response. If one of those ever fires
  * anyway (a legacy opt-in server), the classification falls through
  * to `other` and the shell asks `fetchMcpBootstrap` for a clean
- * `upgrade` snapshot.
+ * `account` snapshot.
  */
 type HostEntryClassification = {
     kind: 'intent';
@@ -523,6 +549,127 @@ declare function waitForInitialToolResult(app: McpAppBootstrapLike & AppToolResu
  */
 declare function seedMcpCaches(initial: SolvaPayProviderInitial, config: SolvaPayConfig): void;
 
+/**
+ * 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).
+ *
+ * The shape is derived from the wire's `options[]` through the
+ * `@solvapay/core` readers. These helpers previously keyed off
+ * `planType`, `meterRef`, `meterId`, and `limit`, none of which the
+ * backend sends: every plan fell through to the unknown branch, so a
+ * pay-as-you-go plan (which has no headline `price`) resolved to
+ * `'free'` and metered subscriptions were indistinguishable from
+ * unlimited ones.
+ */
+
+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';
+/**
+ * The subset of a plan — or of the plan snapshot frozen onto a purchase
+ * — that the shape derivation reads. A plan carries `requiresPayment`;
+ * a snapshot may not. Usage-counting and the rest come out of `options[]`.
+ */
+interface PlanLike {
+    /** Catalog / snapshot identifier used to match a purchase back to a live plan. */
+    reference?: string | null;
+    /** Composable pricing options: charges, billing cycle, limit, trial. */
+    options?: PricingOptionLike[] | null;
+    /** `false` marks a free plan. Only present on a plan, not a snapshot. */
+    requiresPayment?: boolean | null;
+    /** Derived headline amount; only a fallback for snapshots frozen before `options[]`. */
+    price?: number | null;
+    currency?: string | null;
+    /** Frozen on snapshots; usage-based when `options[]` is missing. */
+    isMetered?: boolean | 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
+ * shapes are distinct in UX: each drives a different summary string, a
+ * different set of CTAs, and a different activity-strip variant.
+ *
+ * A billing cycle is what separates a subscription from a one-off, and
+ * metering is what separates capped from unlimited. A paid plan with
+ * neither is a one-time purchase, which this matrix has no member for
+ * and folds into `'recurring-unlimited'` — the same bucket it landed in
+ * before, and the one that routes it to paid checkout.
+ */
+declare function resolvePlanShape(plan: PlanLike | null | undefined): PlanShape | null;
+/**
+ * Pick the activation strategy for a plan the user just clicked.
+ *
+ * Free and trial plans activate instantly, usage-based always tops up
+ * first, and everything else goes to Stripe checkout. A zero-priced
+ * plan needs no separate branch: it resolves to `'free'`, because
+ * charging nothing is what makes a plan free.
+ */
+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;
+}
+/**
+ * Overlay a live catalog plan onto a (possibly thin) purchase snapshot.
+ * Snapshots frozen without `options[]` collapse PAYG to `{ price: 0 }`,
+ * which `resolvePlanShape` reads as `'free'`. Prefer the snapshot's
+ * `options[]` when present; otherwise take them from the catalog match.
+ */
+declare function mergePlanSnapshot(snapshot: PlanLike | null | undefined, catalog: PlanLike | null | undefined): PlanLike | null;
+declare function findCatalogPlan(plans: readonly PlanLike[] | undefined, snapshot: PlanLike | null | undefined, planRef?: string | null): PlanLike | undefined;
+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;
+
 /**
  * Per-element className overrides for `<Mcp*View>` primitives.
  *
@@ -604,11 +751,17 @@ interface McpAccountViewProps {
      */
     onTopup?: () => void;
     /**
-     * Called when the user clicks "Pick a plan" from the empty state or
-     * "See plans" on the pay-as-you-go state. Wired by the shell to
-     * switch to the checkout surface.
+     * Called when the user clicks "Pick a plan" from the empty state,
+     * "See plans" on the credits-only state, or Upgrade / Change plan
+     * on an active plan. Wired by the shell to switch to checkout.
      */
     onChangePlan?: () => void;
+    /**
+     * Product catalog used to decide Upgrade vs Change plan and to
+     * format a PAYG rate when the purchase snapshot is thin. The shell
+     * passes `bootstrap.plans`.
+     */
+    plans?: readonly PlanLike[];
     /**
      * Skip the Customer + Seller detail cards. `<McpAppShell>` sets this
      * when it mounts the persistent right-hand sidebar (whenever
@@ -616,7 +769,7 @@ interface McpAccountViewProps {
      */
     hideDetailCards?: boolean;
 }
-declare function McpAccountView({ classNames, onTopup, onChangePlan, hideDetailCards, }: McpAccountViewProps): react_jsx_runtime.JSX.Element;
+declare function McpAccountView({ classNames, onTopup, onChangePlan, plans, hideDetailCards, }: McpAccountViewProps): react_jsx_runtime.JSX.Element;
 
 interface McpCheckoutViewProps {
     productRef: string;
@@ -694,9 +847,10 @@ declare function McpTopupView({ publishableKey, returnUrl, onTopupSuccess, onBac
  * The `paywall` / `nudge` kinds were removed as part of the text-only
  * paywall refactor: merchant paywall / nudge responses are plain text
  * narrations now, not widget surfaces. The iframe is only mounted for
- * the three deliberate intent tools.
+ * the `account` viewer (slash prompts remap onto it with a `view`).
  */
-type McpViewKind = 'checkout' | 'account' | 'topup';
+
+type McpViewKind = SolvaPayMcpViewKind;
 /**
  * @deprecated Use `McpViewKind`. This alias exists for one minor
  * version to give internal callers a grace window on the rename; the
@@ -865,115 +1019,6 @@ interface McpAppProps {
 }
 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).
- *
- * The shape is derived from the wire's `options[]` through the
- * `@solvapay/core` readers. These helpers previously keyed off
- * `planType`, `meterRef`, `meterId`, and `limit`, none of which the
- * backend sends: every plan fell through to the unknown branch, so a
- * pay-as-you-go plan (which has no headline `price`) resolved to
- * `'free'` and metered subscriptions were indistinguishable from
- * unlimited ones.
- */
-
-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';
-/**
- * The subset of a plan — or of the plan snapshot frozen onto a purchase
- * — that the shape derivation reads. A plan carries `requiresPayment`;
- * a snapshot may not. Usage-counting and the rest come out of `options[]`.
- */
-interface PlanLike {
-    /** Composable pricing options: charges, billing cycle, limit, trial. */
-    options?: PricingOptionLike[] | null;
-    /** `false` marks a free plan. Only present on a plan, not a snapshot. */
-    requiresPayment?: boolean | null;
-    /** Derived headline amount; only a fallback for snapshots frozen before `options[]`. */
-    price?: number | null;
-    currency?: string | 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
- * shapes are distinct in UX: each drives a different summary string, a
- * different set of CTAs, and a different activity-strip variant.
- *
- * A billing cycle is what separates a subscription from a one-off, and
- * metering is what separates capped from unlimited. A paid plan with
- * neither is a one-time purchase, which this matrix has no member for
- * and folds into `'recurring-unlimited'` — the same bucket it landed in
- * before, and the one that routes it to paid checkout.
- */
-declare function resolvePlanShape(plan: PlanLike | null | undefined): PlanShape | null;
-/**
- * Pick the activation strategy for a plan the user just clicked.
- *
- * Free and trial plans activate instantly, usage-based always tops up
- * first, and everything else goes to Stripe checkout. A zero-priced
- * plan needs no separate branch: it resolves to `'free'`, because
- * charging nothing is what makes a plan free.
- */
-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;
@@ -1106,11 +1151,13 @@ interface McpSellerDetailsCardProps {
     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.
+ * Seller details — company name, legal entity, support email/URL.
+ * Contact details are plain text (not anchors): mailto: and
+ * target=_blank both navigate the sandboxed widget iframe itself.
+ * Compliance-relevant: a customer paying through the iframe should
+ * see who they're actually paying, to the same level of detail as
+ * hosted checkout.
  */
 declare function McpSellerDetailsCard({ classNames, showVerifiedBadge, }: McpSellerDetailsCardProps): react_jsx_runtime.JSX.Element | null;
 
-export { type ActivationStrategy, type ActivityStripKind, AppHeader, type AppHeaderMode, type AppHeaderProps, type AppToolResultEvents, BackLink, type BackLinkProps, HOSTS_WITH_MERCHANT_CHROME, 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, McpHostInfoProvider, type McpHostInfoProviderProps, type McpMessageOnSuccess, McpSellerDetailsCard, type McpSellerDetailsCardProps, type McpSuccessEvent, type McpTabKind, type McpToolResult, McpTopupView, type McpTopupViewProps, type McpUiHostContextLike, 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, fetchMcpBootstrapViaResource, isTransportToolName, parseBootstrapFromToolResult, resolveActivationStrategy, resolveActivityStrip, resolveMcpClassNames, resolvePlanActions, resolvePlanShape, seedMcpCaches, useHostLocale, useHostName, useMcpBridge, useMcpToolResult, useStripeProbe, waitForInitialToolResult };
+export { type ActivationStrategy, type ActivityStripKind, AppHeader, type AppHeaderMode, type AppHeaderProps, type AppToolResultEvents, BackLink, type BackLinkProps, HOSTS_WITH_MERCHANT_CHROME, 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, McpHostInfoProvider, type McpHostInfoProviderProps, type McpMessageOnSuccess, McpSellerDetailsCard, type McpSellerDetailsCardProps, type McpSuccessEvent, type McpTabKind, type McpToolResult, McpTopupView, type McpTopupViewProps, type McpUiHostContextLike, 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, fetchMcpBootstrapViaResource, findCatalogPlan, isTransportToolName, mergePlanSnapshot, parseBootstrapFromToolResult, resolveActivationStrategy, resolveActivityStrip, resolveMcpClassNames, resolvePlanActions, resolvePlanShape, seedMcpCaches, useHostLocale, useHostName, useMcpBridge, useMcpToolResult, useStripeProbe, waitForInitialToolResult };