@solvapay/react 1.0.9-preview.1 → 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/CONTRIBUTING.md

@@ -0,0 +1,117 @@
+# Contributing to @solvapay/react
+
+This package ships two tiers:
+
+- **`@solvapay/react`** — default tree. Drop-in components (`CheckoutLayout`, `PaymentForm`, …) that render a golden-path UI. Internally, they are thin shims over the primitives.
+- **`@solvapay/react/primitives`** — unstyled compound primitives. Consumers compose these to build fully custom UIs.
+
+This file is the canonical contract for primitives until the cross-repo Mintlify docs land. Every primitive you add or edit MUST follow these rules.
+
+## Primitive contract
+
+### Compound API
+
+Every primitive is a compound: a `Root` plus named subcomponents.
+
+```tsx
+<PlanSelector.Root>
+  <PlanSelector.Heading />
+  <PlanSelector.Grid>
+    <PlanSelector.Card>
+      <PlanSelector.CardName />
+      <PlanSelector.CardPrice />
+    </PlanSelector.Card>
+  </PlanSelector.Grid>
+</PlanSelector.Root>
+```
+
+- Export subcomponents as properties on the `Root` (`PlanSelector.Card`) **and** as named exports from `./primitives` for tree-shake-friendly use.
+- No render-prop children. No `classNames` prop. No `unstyled` flag.
+
+### `asChild`
+
+Every leaf subcomponent accepts `asChild?: boolean`. When `true`, it renders its single child via `<Slot>` and merges props/ref onto the child.
+
+```tsx
+<PlanSelector.Card asChild>
+  <Card>{/* shadcn/ui card */}</Card>
+</PlanSelector.Card>
+```
+
+Use `Slot` from `./primitives/slot`. Refs are merged via `composeRefs`; event handlers are chained via `composeEventHandlers` (consumer runs first; `preventDefault()` skips the primitive handler).
+
+### `data-state` vocabulary
+
+Every stateful subcomponent emits a `data-state` attribute from a fixed, documented vocabulary. States are driven by context (`PlanSelectionContext`, `PaymentFormContext`), never by subcomponent-local state.
+
+| Primitive | `data-state` values |
+| --- | --- |
+| `PlanSelector.Card` | `idle` \| `selected` \| `current` \| `disabled` |
+| `PaymentForm.SubmitButton` | `idle` \| `processing` \| `disabled` |
+| `ActivationFlow.Root` | `summary` \| `activating` \| `selectAmount` \| `topupPayment` \| `retrying` \| `activated` \| `error` |
+| `CreditGate.Root` | `allowed` \| `blocked` \| `loading` |
+| `PurchaseGate.Root` | `allowed` \| `blocked` \| `loading` |
+| `CancelledPlanNotice.Root` | `active` \| `expired` |
+| `CancelPlanButton` | `idle` \| `cancelling` |
+| `BalanceBadge` | `loading` \| `zero` \| `low` \| `ok` |
+| `AmountPicker.Option` | `idle` \| `selected` \| `disabled` |
+
+Secondary flags use `data-<flag>` (e.g. `data-free`, `data-popular`, `data-has-reason`).
+
+### Opaque selectors
+
+Every primitive root emits `data-solvapay-<primitive>` (and subcomponents emit `data-solvapay-<primitive>-<part>` when they need to be targetable). Do not rely on internal class names; those are not a public API.
+
+### `.Loading` and `.Error`
+
+Every async primitive exposes `.Loading` and `.Error` subcomponents that render when the context reports loading/error. They render `null` otherwise. Always provide a fallback UI path — don't rely on consumers remembering to add them.
+
+### Errors self-heal
+
+Throw structured errors from `src/utils/errors.ts` for wiring mistakes:
+
+- `MissingProviderError` — primitive rendered outside `<SolvaPayProvider>`.
+- `MissingEnvVarError` — required env var not set.
+- `MissingApiRouteError` — backend route not installed.
+- `MissingProductRefError` — primitive needs `productRef` and none was provided.
+
+Each error includes `code`, `message` (fix + docs URL), and `docsUrl`.
+
+## Prohibited patterns
+
+When touching a primitive, these must stay gone:
+
+- `classNames` prop, `unstyled` prop, `RenderArgs` / function-child overloads.
+- Inline `style={{ ... }}` inside `src/primitives/**`.
+- `next/*` imports (the package must bundle on Vite/Remix).
+- `as any`, `as unknown as ...` except when unavoidable; justify with a comment.
+- Implicit `enum`; use union types.
+
+## TDD checklist per primitive
+
+Write the primitive and its test file in the same commit. Every primitive test covers:
+
+1. **Default render** — subcomponents render the expected DOM.
+2. **`asChild` composition** — refs merge, handlers chain, `data-*` + `aria-*` forward to the child element.
+3. **`data-state` transitions** — context-driven state flips the attribute correctly.
+4. **`.Loading` / `.Error`** — rendered when context signals loading/error.
+5. **Provider-missing + env-missing** — the correct structured error class is thrown with its docs URL.
+
+Delete legacy tests that assert on `classNames` / function-child / `RenderArgs` **before** landing the rewrite.
+
+## Adding a new primitive (checklist)
+
+1. Write the test file following the TDD checklist above.
+2. Create `src/primitives/<Name>.tsx` with `Root` + subcomponents + `asChild` + `data-state`.
+3. Re-export from `src/primitives/index.ts`.
+4. If the primitive is part of the default tree, update the shim in `src/components/<Name>.tsx` to render it with the golden-path children.
+5. Update the `data-state` table in this file if you introduce a new state.
+6. Keep the package-local README cheat sheet in sync.
+
+## Commands
+
+```bash
+pnpm --filter @solvapay/react test        # run the primitive + component tests
+pnpm --filter @solvapay/react build       # tsup build (top-level + primitives entry)
+pnpm --filter @solvapay/react lint        # eslint
+```