@solvapay/react 1.0.8-preview.9 → 1.0.9

package/CHANGELOG.md

@@ -0,0 +1,209 @@
+# @solvapay/react changelog
+
+From `1.0.10` onwards this changelog is generated by
+[changesets](https://github.com/changesets/changesets) — prior entries
+are maintained by hand and are grouped by the first preview / stable
+release that contains them.
+
+## Unreleased
+
+## 1.0.9 — peer-dep rename: `@solvapay/mcp` → `@solvapay/mcp-core`
+
+The optional peer dependency that guards `@solvapay/react/mcp` types was
+renamed from `@solvapay/mcp` → `@solvapay/mcp-core` to match the
+reshuffled SolvaPay MCP package layout (framework-neutral contracts
+now live in `@solvapay/mcp-core`; the official
+`@modelcontextprotocol/sdk` adapter is `@solvapay/mcp`). No source
+changes — this is a rename of the `peerDependencies` /
+`peerDependenciesMeta` contract line only.
+
+Integrators who install the optional peer explicitly:
+
+```diff
+- pnpm add @solvapay/mcp
++ pnpm add @solvapay/mcp-core
+```
+
+Integrators who don't use `@solvapay/react/mcp` are unaffected.
+
+### `@solvapay/react/mcp` — per-view primitives + `<McpApp>` compound (minor, additive)
+
+The MCP App reference views (`checkout`, `account`, `topup`, `activate`) that
+previously lived in `examples/mcp-checkout-app` have been lifted into
+`@solvapay/react/mcp` as four composable primitives plus a thin compound
+wrapper:
+
+```tsx
+import '@solvapay/react/styles.css'
+import '@solvapay/react/mcp/styles.css'
+import { App } from '@modelcontextprotocol/ext-apps'
+import { McpApp } from '@solvapay/react/mcp'
+
+const app = new App({ name: 'my-mcp-app', version: '1.0.0' })
+createRoot(rootEl).render(<McpApp app={app} />)
+```
+
+Integrators who want a custom shell compose the primitives directly:
+
+```tsx
+import {
+  McpCheckoutView,
+  McpAccountView,
+  McpTopupView,
+  McpActivateView,
+  McpViewRouter,
+  fetchMcpBootstrap,
+  createMcpFetch,
+  createMcpAppAdapter,
+  useStripeProbe,
+} from '@solvapay/react/mcp'
+```
+
+Each view accepts a `classNames?: McpViewClassNames` partial for per-slot
+overrides; defaults render the `solvapay-mcp-*` classes from the new
+`@solvapay/react/mcp/styles.css` stylesheet. `<McpApp>` also takes a `views`
+map for per-screen component overrides without losing routing.
+
+### Seam fixes on primitives that the MCP views needed
+
+Three additive primitive changes landed alongside the lift:
+
+- **`<AmountPicker.Root emit="minor">`** — when set, `onChange` and
+  `Confirm.onConfirm` deliver the amount in minor units (respects
+  zero-decimal currencies like JPY). Default stays `'major'` for
+  back-compat. `useAmountPicker().resolvedAmountMinor` is a new sibling to
+  `resolvedAmount` for custom layouts. A new
+  `getMinorUnitsPerMajor(currency)` util is exported from
+  `@solvapay/react` for integrators doing conversions outside the picker.
+- **`<AmountPicker.Root selector={…}>`** — accepts an externally-owned
+  `UseTopupAmountSelectorReturn`, letting parent flows share state with
+  the inner picker. `ActivationFlow.AmountPicker` now threads the flow's
+  selector through this prop, so amounts picked in the sub-picker feed
+  straight into `useActivation().retry()` without the old workaround.
+- **`<LaunchCustomerPortalButton asChild>`** — renders the ready-state
+  anchor via `Slot` so consumers can substitute a real `<button>` inside
+  an anchor wrapper (matches the `ActivationFlow.ActivateButton`
+  convention). Loading / error fallback buttons are untouched.
+
+All three are additive — no consumer API moves or renames.
+
+### Plans vs balance transactions (minor, behavioural filtering)
+
+Credit top-ups now surface as balance transactions, not plans. `PurchaseInfo`
+gains a `metadata?: Record<string, unknown>` field, and two new utilities —
+`isPlanPurchase` / `isTopupPurchase` — classify structurally from
+`planSnapshot`. The classification is applied inside `usePurchase()` so every
+plan-shaped accessor is consistent:
+
+- `activePurchase`, `activePaidPurchase`, `hasPaidPurchase`, `hasProduct`,
+  and `cancelledPurchase` / `shouldShowCancelledNotice` (on
+  `usePurchaseStatus`) all skip balance transactions.
+- A new `balanceTransactions: PurchaseInfo[]` accessor on `usePurchase()`
+  returns the complement.
+- `purchases` (raw) is unchanged — the full ordering is still available for
+  integrators that classify themselves.
+
+`PurchaseInfo.planSnapshot.name` is now surfaced as a first-class field so
+`<CurrentPlanCard>` renders a real plan name ("Pro Monthly") instead of the
+opaque `planRef`. Legacy purchases without a snapshot name fall back to
+`productName`. The `planRef` is retained only as `data-solvapay-current-plan-ref`
+on the card root for QA hooks.
+
+`<CurrentPlanCard>` also uses `copy.currentPlan.cycleUnit` to render
+"500 kr / month" rather than "500 kr / monthly". Override any of
+`weekly` / `monthly` / `quarterly` / `yearly` in your copy bundle to localise
+the interval label.
+
+Behavioural note for integrators who previously relied on top-ups surfacing on
+`activePurchase`: drop to `purchases` (raw) to restore the old most-recent
+ordering, or read from `balanceTransactions` directly.
+
+### BREAKING: Unified `transport` replaces per-method provider overrides
+
+`SolvaPayProvider` now takes a single `config.transport: SolvaPayTransport`
+prop. The old per-method `SolvaPayProviderProps` overrides have been removed:
+
+- `checkPurchase`
+- `createPayment`
+- `processPayment`
+- `createTopupPayment`
+
+Consumers passing any of those props must migrate to `config.transport`.
+
+**Before:**
+
+```tsx
+<SolvaPayProvider
+  checkPurchase={myCheckPurchase}
+  createPayment={myCreatePayment}
+  processPayment={myProcessPayment}
+  createTopupPayment={myCreateTopupPayment}
+>
+  {children}
+</SolvaPayProvider>
+```
+
+**After:**
+
+```tsx
+const transport: SolvaPayTransport = {
+  checkPurchase: myCheckPurchase,
+  createPayment: myCreatePayment,
+  processPayment: myProcessPayment,
+  createTopupPayment: myCreateTopupPayment,
+  // ...plus every other required method; see types/transport.ts
+}
+
+<SolvaPayProvider config={{ transport }}>{children}</SolvaPayProvider>
+```
+
+HTTP consumers who never set those overrides are unaffected — the provider
+falls back to `createHttpTransport(config)` automatically.
+
+### Added: `@solvapay/react/mcp` subpath
+
+Ships `createMcpAppAdapter(app)` which returns a `SolvaPayTransport` that
+tunnels every data call through `app.callServerTool` instead of HTTP. Use it
+when hosting the React tree inside an MCP App, where direct HTTP to your
+backend is blocked by the host sandbox:
+
+```tsx
+import { createMcpAppAdapter } from '@solvapay/react/mcp'
+<SolvaPayProvider config={{ transport: createMcpAppAdapter(app) }}>
+  {children}
+</SolvaPayProvider>
+```
+
+See the [MCP App integration guide](https://docs.solvapay.com/sdks/typescript/guides/mcp-app)
+for the full walkthrough. Re-exports `MCP_TOOL_NAMES` so client and server
+share a single source of truth for tool names.
+
+### Added: account management components
+
+- `<CurrentPlanCard>` — plan-type-aware summary card (recurring / one-time /
+  usage-based), payment-method display, Update card + Cancel plan actions.
+  Returns `null` when there is no active purchase.
+- `<LaunchCustomerPortalButton>` — pre-fetches `createCustomerSession` on
+  mount and renders a real `<a target="_blank">` anchor (MCP sandbox-safe).
+- `<UpdatePaymentMethodButton mode="portal">` — thin wrapper around
+  `<LaunchCustomerPortalButton>`. The `mode` prop reserves space for a
+  future `"inline"` value without breaking the API.
+
+### Added: `usePaymentMethod` hook
+
+Fetches the customer's default payment method through
+`transport.getPaymentMethod()`. Transport-keyed single-flight cache, mirrors
+the `useMerchant` pattern. Returns `null` on error (graceful hide, no
+`onError` re-emit — the HTTP transport already invokes `config.onError`
+before throwing).
+
+### Fixed
+
+- `SolvaPayProvider` no longer flips `loading: true` for polling refetches
+  when the customer has no purchases yet. `usePurchase` now exposes a
+  separate `isRefetching` flag for background polls; gate initial skeletons
+  on `loading` and render subtle refresh indicators on `isRefetching`.
+- `LaunchCustomerPortalButton` captures `onError` via ref so parents passing
+  an inline arrow no longer re-fire the pre-fetch effect on every render.
+- `useMerchant`, `useProduct`, and `usePaymentMethod` no longer double-call
+  `config.onError` — the HTTP transport already calls it before throwing.

package/README.md

@@ -182,12 +182,10 @@ export default function App() {
 ```tsx
 import { SolvaPayProvider } from '@solvapay/react'
 import { createSupabaseAuthAdapter } from '@solvapay/react-supabase'
+import { supabase } from './lib/supabase'
 
 export default function App() {
-  const adapter = createSupabaseAuthAdapter({
-    supabaseUrl: process.env.NEXT_PUBLIC_SUPABASE_URL!,
-    supabaseAnonKey: process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
-  })
+  const adapter = createSupabaseAuthAdapter({ client: supabase })
 
   return (
     <SolvaPayProvider config={{ auth: { adapter } }}>
@@ -199,32 +197,175 @@ export default function App() {
 
 ### Fully Custom Implementation
 
+Every data-access call flows through `config.transport`. Build a custom one by
+spreading `createHttpTransport(config)` and overriding the methods you need:
+
 ```tsx
-import { SolvaPayProvider } from '@solvapay/react'
+import { SolvaPayProvider, createHttpTransport } from '@solvapay/react'
 
 export default function App() {
+  const transport = {
+    ...createHttpTransport(undefined),
+    createPayment: async ({ planRef, productRef }) => {
+      const res = await fetch('/api/custom/payment', {
+        method: 'POST',
+        body: JSON.stringify({ planRef, productRef }),
+      })
+      if (!res.ok) throw new Error('Failed to create payment')
+      return res.json()
+    },
+    checkPurchase: async () => {
+      const res = await fetch('/api/custom/purchase')
+      if (!res.ok) throw new Error('Failed to check purchase')
+      return res.json()
+    },
+  }
+
   return (
-    <SolvaPayProvider
-      createPayment={async ({ planRef, productRef }) => {
-        const res = await fetch('/api/custom/payment', {
-          method: 'POST',
-          body: JSON.stringify({ planRef, productRef }),
-        })
-        if (!res.ok) throw new Error('Failed to create payment')
-        return res.json()
-      }}
-      checkPurchase={async customerRef => {
-        const res = await fetch(`/api/custom/purchase?customerRef=${customerRef}`)
-        if (!res.ok) throw new Error('Failed to check purchase')
-        return res.json()
-      }}
-    >
+    <SolvaPayProvider config={{ transport }}>
+      <CheckoutPage />
+    </SolvaPayProvider>
+  )
+}
+```
+
+### MCP App
+
+For React trees hosted inside an MCP App (where Stripe.js and direct HTTP
+to your backend are both blocked by the host sandbox), use the MCP subpath:
+
+```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)
+
+export default function Root() {
+  return (
+    <SolvaPayProvider config={{ transport }}>
       <CheckoutPage />
     </SolvaPayProvider>
   )
 }
 ```
 
+The MCP server is expected to expose tools whose names match `MCP_TOOL_NAMES`
+from `@solvapay/react/mcp` — each transport method maps 1:1 to a tool call.
+
+### Managing plans in an MCP App
+
+Once a customer is paid, drop `<CurrentPlanCard />` into the UI and the
+SDK does the rest — plan name, price, next-billing / expiry line,
+payment-method summary (via `get_payment_method`), Update-card and
+Cancel-plan actions. The card returns `null` when there's no active
+purchase, so you can render it unconditionally:
+
+```tsx
+import { CurrentPlanCard } from '@solvapay/react'
+
+function Account() {
+  return <CurrentPlanCard />
+}
+```
+
+Behind the scenes:
+
+- Plan metadata comes from `usePurchase` (provider state, no extra fetch)
+- Payment-method line comes from `usePaymentMethod` → `transport.getPaymentMethod()`
+- `<UpdatePaymentMethodButton>` pre-fetches `transport.createCustomerSession()`
+  on mount and renders a real `<a target="_blank">` to the hosted portal —
+  MCP host sandboxes permit direct anchor clicks even though scripted
+  `window.open` after an async round-trip is blocked.
+- `<CancelPlanButton>` reuses Phase 1 behaviour — no new plumbing.
+
+If you want the bare portal-launch button on its own (e.g. in a top nav),
+use `<LaunchCustomerPortalButton />` directly.
+
+> `<PlanSwitcher>` (plan upgrade/downgrade with proration) and
+> `<PaymentMethodForm>` (inline Stripe Elements card update) are deferred
+> to follow-up PRs — see the plan in the SDK repo for scope. For plan
+> changes today, MCP apps use `<CancelPlanButton>` + `<CurrentPlanCard>`
+> + a fresh hosted checkout flow.
+
+## Building MCP Apps
+
+`@solvapay/react/mcp` ships a turnkey compound plus four composable
+primitives for SolvaPay MCP Apps built on
+[`@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps).
+
+### Quick start — `<McpApp>`
+
+```tsx
+import { createRoot } from 'react-dom/client'
+import { App } from '@modelcontextprotocol/ext-apps'
+import { McpApp } from '@solvapay/react/mcp'
+import '@solvapay/react/styles.css'
+import '@solvapay/react/mcp/styles.css'
+
+const app = new App({ name: 'my-mcp-app', version: '1.0.0' })
+createRoot(document.getElementById('root')!).render(<McpApp app={app} />)
+```
+
+`<McpApp>` handles `app.connect()`, calls the `open_*` tool matching the
+host's invocation context, mounts `<SolvaPayProvider>` with
+`createMcpAppAdapter(app)` + `createMcpFetch(transport)`, and routes to the
+correct per-view primitive.
+
+Pass `applyContext` to wire host theme / fonts / safe-area insets from the
+`ext-apps` helpers, override individual screens via `views`, and tweak
+per-slot styling via `classNames`:
+
+```tsx
+<McpApp
+  app={app}
+  applyContext={ctx => {
+    if (ctx?.theme) applyDocumentTheme(ctx.theme)
+  }}
+  views={{
+    account: MyCustomAccountScreen, // optional — one-off override
+  }}
+  classNames={{ card: 'my-card', button: 'my-btn' }}
+  onInitError={err => console.error('[mcp]', err)}
+/>
+```
+
+See [`examples/mcp-checkout-app`](../../examples/mcp-checkout-app) for the
+full host integration including the server-side `open_*` tool + UI resource
+registration.
+
+### Per-view primitives
+
+When you need a custom shell — your own provider mount, additional routes,
+a bespoke layout — compose the pieces directly:
+
+```tsx
+import {
+  createMcpAppAdapter,
+  createMcpFetch,
+  fetchMcpBootstrap,
+  McpCheckoutView,
+  McpAccountView,
+  McpTopupView,
+  McpPaywallView,
+  McpNudgeView,
+  McpViewRouter,
+  useStripeProbe,
+} from '@solvapay/react/mcp'
+```
+
+Every view accepts a `classNames?: McpViewClassNames` partial. Props are
+typed per-view (`McpCheckoutViewProps`, `McpAccountViewProps`,
+`McpTopupViewProps`, `McpPaywallViewProps`, `McpNudgeViewProps`).
+
+### Architecture ADR
+
+See [`docs/mcp-app-architecture.md`](./docs/mcp-app-architecture.md) for the
+hybrid-API decision record and the three primitive seam fixes
+(`AmountPicker emit="minor"` / `selector={…}`, `LaunchCustomerPortalButton asChild`)
+that landed with this lift.
+
 ## Components
 
 ### SolvaPayProvider
@@ -371,14 +512,42 @@ Access purchase status, active purchases, and helper functions.
 
 ```tsx
 const {
-  purchases, // Array of all purchases
+  purchases, // Array of all purchases (raw — plans + balance transactions)
+  balanceTransactions, // Credit top-ups and other non-plan rows
   loading, // Loading state
-  hasPaidPurchase, // Boolean: has any paid purchase
-  activePurchase, // Most recent active purchase
+  hasPaidPurchase, // Boolean: has any paid plan purchase
+  activePurchase, // Most recent active plan purchase
   refetch, // Function to refetch purchases
 } = usePurchase()
 ```
 
+#### Plans vs balance
+
+Plans and balance credits are orthogonal. A customer can hold at most one
+active plan and any number of balance transactions (credit top-ups today; gift
+credits, referral bonuses, refunds tomorrow).
+
+Every plan-shaped accessor — `activePurchase`, `activePaidPurchase`,
+`hasPaidPurchase`, `hasProduct`, plus `cancelledPurchase` /
+`shouldShowCancelledNotice` on `usePurchaseStatus` — filters out balance
+transactions. Top-ups surface on `balanceTransactions`, and the aggregate
+credit balance on `useBalance()`.
+
+Classification is structural (`isPlanPurchase` / `isTopupPurchase`): a purchase
+with no `planSnapshot` was never a plan. `metadata.purpose === 'credit_topup'`
+acts as a defense-in-depth guard.
+
+```tsx
+import { isPlanPurchase, isTopupPurchase } from '@solvapay/react'
+
+const plans = purchases.filter(isPlanPurchase)
+const topups = purchases.filter(isTopupPurchase)
+```
+
+If you previously relied on top-ups surfacing on `activePurchase` (e.g. "show
+the most recent transaction"), read from `purchases` or `balanceTransactions`
+directly.
+
 ### usePlans
 
 Fetch and manage available plans.
@@ -534,7 +703,7 @@ Lovable-style apps deploy React frontends against Supabase Edge Functions
       // …same pattern for every other endpoint
     },
     auth: {
-      adapter: createSupabaseAuthAdapter({ supabaseUrl, supabaseAnonKey }),
+      adapter: createSupabaseAuthAdapter({ client: supabase }),
     },
   }}
 >
@@ -547,7 +716,7 @@ Lovable-style apps deploy React frontends against Supabase Edge Functions
 ```
 
 The matching Deno edge functions ship in
-[`@solvapay/supabase`](../../packages/supabase) — see
+[`@solvapay/fetch`](../../packages/fetch) — see
 [`examples/supabase-edge`](../../examples/supabase-edge) for one-liner
 `Deno.serve(handler)` files covering every handler including the new
 `get-merchant` and `get-product` endpoints.

package/dist/adapters/auth.d.cts

@@ -32,6 +32,19 @@ interface AuthAdapter {
      * return null and let the caller decide how to handle unauthenticated requests.
      */
     getUserId: () => Promise<string | null>;
+    /**
+     * Subscribe to auth-state changes. Optional.
+     *
+     * When provided, `SolvaPayProvider` calls `subscribe` on mount and
+     * triggers `detectAuth` every time the listener fires instead of
+     * only running `detectAuth` once. This is how reactive adapters such
+     * as `@solvapay/react-supabase` push sign-in / sign-out / token-refresh
+     * events into the SDK without the app having to reload.
+     *
+     * @param listener - Called with no arguments whenever auth state changes
+     * @returns An unsubscribe function the provider calls on cleanup
+     */
+    subscribe?: (listener: () => void) => () => void;
 }
 /**
  * Default auth adapter that only checks localStorage

package/dist/adapters/auth.d.ts

@@ -32,6 +32,19 @@ interface AuthAdapter {
      * return null and let the caller decide how to handle unauthenticated requests.
      */
     getUserId: () => Promise<string | null>;
+    /**
+     * Subscribe to auth-state changes. Optional.
+     *
+     * When provided, `SolvaPayProvider` calls `subscribe` on mount and
+     * triggers `detectAuth` every time the listener fires instead of
+     * only running `detectAuth` once. This is how reactive adapters such
+     * as `@solvapay/react-supabase` push sign-in / sign-out / token-refresh
+     * events into the SDK without the app having to reload.
+     *
+     * @param listener - Called with no arguments whenever auth state changes
+     * @returns An unsubscribe function the provider calls on cleanup
+     */
+    subscribe?: (listener: () => void) => () => void;
 }
 /**
  * Default auth adapter that only checks localStorage

package/dist/adapters/auth.js

@@ -1,6 +1,7 @@
 import {
   defaultAuthAdapter
 } from "../chunk-OUSEQRCT.js";
+import "../chunk-MLKGABMK.js";
 export {
   defaultAuthAdapter
 };