@solvapay/react 1.0.9-preview.1 → 1.0.9

package/README.md

@@ -34,6 +34,126 @@ By default, `SolvaPayProvider` uses:
 - `/api/check-purchase` for purchase checks
 - `/api/create-payment-intent` for payment creation
 - `/api/process-payment` for payment processing
+- `/api/merchant` for merchant identity (`useMerchant`, `MandateText`)
+- `/api/get-product` for single-product lookup (`useProduct`, `CheckoutSummary`)
+
+## Golden path — `<CheckoutLayout>` one-liner
+
+`<CheckoutLayout>` handles the full flow: plan selection, payment (paid/free),
+and usage-based activation. For 90% of integrations this is the only
+component you need.
+
+```tsx
+import { SolvaPayProvider, CheckoutLayout } from '@solvapay/react'
+
+export function BuyNow({ email }: { email: string }) {
+  return (
+    <SolvaPayProvider>
+      <CheckoutLayout
+        productRef="prd_myapi"
+        prefillCustomer={{ email }}
+        requireTermsAcceptance
+        onResult={result => {
+          // result.kind === 'paid' | 'activated'
+        }}
+      />
+    </SolvaPayProvider>
+  )
+}
+```
+
+What happens based on what `<CheckoutLayout>` resolves:
+
+| Product shape | Flow |
+|---|---|
+| One active plan | Auto-skip selection → pay or activate |
+| Multiple plans | Styled `<PlanSelector>` → pay or activate |
+| Free plan (`requiresPayment: false`) | Skip Stripe entirely → `useActivation` |
+| Usage-based plan | `<ActivationFlow>` (summary → top-up → retry → activated) |
+
+Pass `planRef` explicitly to skip the selector and keep today's payment-only
+behavior byte-for-byte (backwards compatible with pre-selector integrations).
+
+### Skipping plan selection
+
+```tsx
+<CheckoutLayout
+  planRef="pln_premium"
+  productRef="prd_myapi"
+  prefillCustomer={{ email }}
+  requireTermsAcceptance
+  size="auto"
+  onSuccess={() => console.log('paid')}
+/>
+```
+
+The section below ("Drop-in checkout with `<CheckoutLayout>`") is the original
+single-plan form — still supported, still works the same.
+
+## Drop-in checkout with `<CheckoutLayout>`
+
+For a fixed plan checkout (summary, SCA mandate, Stripe PaymentElement,
+prefilled customer echo, optional terms checkbox):
+
+```tsx
+import { SolvaPayProvider, CheckoutLayout } from '@solvapay/react'
+
+export function BuyNow({ email }: { email: string }) {
+  return (
+    <SolvaPayProvider>
+      <CheckoutLayout
+        planRef="pln_premium"
+        productRef="prd_myapi"
+        prefillCustomer={{ email }}
+        requireTermsAcceptance
+        size="auto"
+        onSuccess={() => console.log('paid')}
+      />
+    </SolvaPayProvider>
+  )
+}
+```
+
+`size="auto"` uses a `ResizeObserver`, so the same component reflows cleanly
+in chat bubbles, phone viewports, and desktop iframes.
+
+## Composition: slot subcomponents
+
+When you need custom layout, compose `<PaymentForm>` with slot children:
+
+```tsx
+<PaymentForm planRef="pln_premium" productRef="prd_myapi" prefillCustomer={{ email }}>
+  <PaymentForm.Summary />
+  <PaymentForm.CustomerFields />
+  <PaymentForm.PaymentElement />
+  <PaymentForm.MandateText />
+  <PaymentForm.TermsCheckbox />
+  <PaymentForm.SubmitButton />
+</PaymentForm>
+```
+
+Passing no children keeps the current default tree for backwards compatibility.
+
+## Localization
+
+English ships by default. Swap the locale (which also flows through to Stripe
+Elements) and override any strings you like:
+
+```tsx
+import { SolvaPayProvider, CheckoutLayout, type PartialSolvaPayCopy } from '@solvapay/react'
+
+const svSECopy: PartialSolvaPayCopy = {
+  cta: { subscribe: 'Prenumerera', processing: 'Bearbetar...' },
+  terms: { checkboxLabel: 'Jag godkänner villkoren och integritetspolicyn' },
+}
+
+<SolvaPayProvider config={{ locale: 'sv-SE', copy: svSECopy }}>
+  <CheckoutLayout planRef="..." productRef="..." />
+</SolvaPayProvider>
+```
+
+Currency formatting is already locale-correct — `formatPrice` uses
+`Intl.NumberFormat` with the provider locale and the plan's `currency` field.
 
 ### Custom API Routes
 
@@ -62,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 } }}>
@@ -79,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
@@ -251,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.
@@ -316,9 +605,122 @@ const {
 All components and hooks are fully typed. Import types as needed:
 
 ```tsx
-import type { PaymentFormProps, PurchaseStatus, PaymentIntentResult } from '@solvapay/react'
+import type {
+  PaymentFormProps,
+  PurchaseStatus,
+  PaymentIntentResult,
+  CheckoutResult,
+  PaymentResult,
+  ActivationResult,
+} from '@solvapay/react'
 ```
 
+## Plan lifecycle
+
+Beyond checkout itself, three thin styled-default components cover the
+post-purchase experience without requiring custom UI.
+
+### `<CancelPlanButton>`
+
+Wraps `usePurchaseActions.cancelRenewal` with a built-in confirm dialog,
+loading state, and plan-type-aware copy (subscription vs usage-based).
+Auto-reads the active purchase from `usePurchase()`.
+
+```tsx
+import { CancelPlanButton } from '@solvapay/react'
+
+<CancelPlanButton onCancelled={() => router.push('/')} />
+```
+
+Use `confirm={false}` for a single-click cancel, or pass a string to override
+the default copy. The render-prop form exposes `{ cancel, isCancelling,
+disabled, purchase }` for fully custom UI.
+
+### `<CancelledPlanNotice>`
+
+Surfaces automatically when the customer has a cancelled-but-still-active
+purchase. Renders the expiration date, days remaining, cancellation reason,
+and a reactivate CTA. Renders nothing when there's nothing to show.
+
+```tsx
+import { CancelledPlanNotice } from '@solvapay/react'
+
+<CancelledPlanNotice onReactivated={() => refetch()} />
+```
+
+### `<CreditGate>`
+
+Companion to `<PurchaseGate>` for usage-based flows. Blocks access when the
+customer's credit balance falls below a threshold; renders an embedded
+`<TopupForm>` by default.
+
+```tsx
+import { CreditGate } from '@solvapay/react'
+
+<CreditGate minCredits={10}>
+  <ExpensiveFeature />
+</CreditGate>
+```
+
+Customize via the `fallback` prop, or use the render-prop form
+(`children: ({ balance, hasCredits, topup }) => …`) for fully custom UI.
+
+## Server-side usage tracking
+
+There is intentionally no `useTrackUsage()` client hook. Client-reported usage
+is trivially gamed — a user can simply block the fetch to conserve credits.
+Instead, record usage from your server when the expensive work actually runs:
+
+```ts
+// app/api/do-thing/route.ts
+import { trackUsage } from '@solvapay/next'
+
+export async function POST(request: NextRequest) {
+  const result = await doTheExpensiveThing()
+  await trackUsage(request, { units: 1 })
+  return NextResponse.json(result)
+}
+```
+
+The same pattern works from a Supabase Edge Function — see below.
+
+## Using with Supabase Edge Functions
+
+Lovable-style apps deploy React frontends against Supabase Edge Functions
+(Deno runtime). The SDK's `api` URL overrides let the exact same
+`<CheckoutLayout>` drop-in work against `/functions/v1/*` routes:
+
+```tsx
+<SolvaPayProvider
+  config={{
+    api: {
+      checkPurchase: `${SUPABASE_URL}/functions/v1/check-purchase`,
+      createPayment: `${SUPABASE_URL}/functions/v1/create-payment-intent`,
+      processPayment: `${SUPABASE_URL}/functions/v1/process-payment`,
+      listPlans: `${SUPABASE_URL}/functions/v1/list-plans`,
+      getMerchant: `${SUPABASE_URL}/functions/v1/get-merchant`,
+      getProduct: `${SUPABASE_URL}/functions/v1/get-product`,
+      // …same pattern for every other endpoint
+    },
+    auth: {
+      adapter: createSupabaseAuthAdapter({ client: supabase }),
+    },
+  }}
+>
+  <CheckoutLayout
+    productRef="prd_myapi"
+    prefillCustomer={{ email }}
+    requireTermsAcceptance
+  />
+</SolvaPayProvider>
+```
+
+The matching Deno edge functions ship in
+[`@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.
+
 ## More Information
 
 See [`docs/contributing/architecture.md`](../../docs/contributing/architecture.md) for contributor

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
 };