@doujins/payments-ui 0.0.18 → 0.1.2

package/README.md

@@ -0,0 +1,140 @@
+# Payments UI
+
+Reusable Solana + card checkout widgets for the Doujins billing stack. The package assumes the host application already handles user authentication and can supply API tokens for the Doujins Billing API (`/v1`).
+
+## Installation
+
+```bash
+pnpm install @doujins/payments-ui
+# or
+npm install @doujins/payments-ui
+```
+
+All builds ship precompiled JavaScript modules (`dist/index.js`, `dist/index.cjs`, `dist/index.d.ts`) and a single CSS bundle (`dist/styles.css`). Consumers must import both JS and CSS outputs.
+
+```ts
+import '@doujins/payments-ui/styles.css'
+import { BillingThemeProvider, PaymentExperience } from '@doujins/payments-ui'
+```
+
+## Quick start
+
+1. **Create the billing client** – this is the only API layer. Provide your billing + account base URLs plus an auth-token resolver. You can optionally pass a custom `fetch` implementation for SSR or retries.
+
+```ts
+import { createClient } from '@doujins/payments-ui'
+
+const billingClient = createClient({
+  billingBaseUrl: 'https://billing.example.com',
+  accountBaseUrl: 'https://accounts.example.com',
+  getAuthToken: async () => authStore.jwt,
+  defaultHeaders: {
+    'X-App-Version': appVersion,
+  },
+})
+```
+
+2. **Provide context + theme scope** – wrap all embedded Payments UI components in `BillingThemeProvider` and the exported `PaymentContext` so CSS variables and React Query state are scoped.
+
+```tsx
+import {
+  BillingThemeProvider,
+  PaymentProvider,
+} from '@doujins/payments-ui'
+
+const App = () => (
+  <BillingThemeProvider>
+    <PaymentProvider
+      config={{
+        endpoints: {
+          billingBaseUrl: 'https://billing.example.com',
+          accountBaseUrl: 'https://accounts.example.com',
+        },
+        getAuthToken: () => authStore.jwt,
+      }}
+    >
+      <SubscriptionCheckoutModal priceId="price_123" usdAmount={9.99} />
+    </PaymentProvider>
+  </BillingThemeProvider>
+)
+```
+
+3. **Drop in the widgets** – the main surface is `PaymentExperience`, but you can also use individual building blocks (`CardDetailsForm`, `StoredPaymentMethods`, `SolanaPaymentView`, etc.). Every component reads from the `PaymentProvider` context and automatically calls the lean client.
+
+```tsx
+<PaymentExperience
+  priceId="price_monthly"
+  usdAmount={14.99}
+  enableSolanaPay
+  onNewCardPayment={async ({ token, billing }) => {
+    await client.checkout({
+      price_id: 'price_monthly',
+      processor: 'mobius',
+      payment_token: token,
+      ...billing,
+    })
+  }}
+  onSavedMethodPayment={async ({ paymentMethodId }) => {
+    await client.checkout({
+      price_id: 'price_monthly',
+      processor: 'mobius',
+      payment_method_id: paymentMethodId,
+    })
+  }}
+/>
+```
+
+## Architecture
+
+- **Lean client only** – `createClient` is the single integration point. It handles auth-token injection, optional account vs billing base URLs, Solana endpoints, and list normalization. There are no “services” or `PaymentApp` instances to maintain.
+- **Scoped CSS theme** – `BillingThemeProvider` adds `payments-ui-root` around our components and defines CSS variables (`--background`, `--primary`, etc.) inside that scope. This prevents the host application's `:root` from being overridden.
+- **React Query + hooks** – Every exported hook (`usePaymentMethods`, `useSubscriptionActions`, `useSupportedTokens`, `useSolanaQrPayment`, etc.) talks directly to the client. There are no legacy contexts or Solana wallet-link flows to wire up.
+- **Solana QR-only** – The backend only exposes `/v1/solana/pay` + `/v1/solana/pay/:reference`, so the UI only renders the QR flow. Wallet-linking, verification, and direct-sign flows were removed to avoid confusing embedding apps.
+
+## API surface
+
+### `createClient(config)`
+- `billingBaseUrl` (required) – Billing API host (e.g. `https://billing.example.com`).
+- `billingBasePath` – defaults to `/v1`.
+- `accountBaseUrl`, `accountBasePath` – optional override for account endpoints (`/me/payment-methods` etc.).
+- `getAuthToken` – optional sync/async function returning the bearer token.
+- `defaultHeaders` – merged into every request.
+- `fetch` – optional custom fetch implementation.
+
+Helpers exposed by the client:
+- `listPaymentMethods`, `createPaymentMethod`, `updatePaymentMethod`, `deletePaymentMethod`, `activatePaymentMethod`
+- `checkout`, `cancelSubscription`
+- `getPaymentHistory`
+- `getSolanaTokens`, `createSolanaPayIntent`, `getSolanaPayStatus`
+- `getPaymentStatus`
+
+All helpers return typed promises and throw `ClientApiError` on non-OK responses (exposes `status`, `body`, `request`).
+
+### Hooks/components
+- `usePaymentMethods` – wraps React Query around the client and normalizes list responses to the old Stripe-like shape for convenience.
+- `useSubscriptionActions` – helper around `client.checkout` for card vs saved payment flows.
+- `SolanaPaymentView` – shows amount, token selector, and the QR flow. It uses `useSupportedTokens` and `useSolanaQrPayment` internally.
+- `PaymentExperience` – orchestrates card tabs, stored methods, and optionally toggles the Solana flow. It’s built entirely on the hooks listed above.
+
+## Styling
+- Import `@doujins/payments-ui/styles.css` once. It only scopes to `.payments-ui-root`, `.payments-ui-portal`, or `[data-payments-ui]` so host CSS remains untouched.
+- Wrap all embedded UI inside `BillingThemeProvider` (or manually add the `payments-ui-root` class/data attribute) so the CSS custom properties take effect.
+- The library uses Tailwind utility classes plus Radix primitives. If the host app already runs Tailwind, there’s no conflict because our CSS is namespaced via the wrapper.
+
+## Solana specifics
+- Supported tokens are fetched via `client.getSolanaTokens` (backed by `/v1/solana/tokens`). The UI caches tokens for 5 minutes and sorts them alphabetically.
+- QR intents call `client.createSolanaPayIntent`, which returns the exact payload from `/v1/solana/pay`. The UI handles countdown + polling via `client.getSolanaPayStatus` and stops when the backend reports `confirmed` or the QR expires.
+- `usePaymentStatus` can poll `/payment/status/:id` for extra confirmation if the host wants to display completion states elsewhere.
+
+## Removing legacy features
+- Solana wallet linking, direct wallet payments, flexform/CCBill dialogs, and Collect.js verification flows that do not exist on the backend were removed. Only card tokenization via Collect.js (for new cards) and Solana Pay QR remain.
+- There is no barcode/backward compatibility shim. Hosts must adopt `BillingThemeProvider`, `PaymentProvider`, and `createClient` to integrate the new widgets.
+
+## Development
+```bash
+pnpm install
+pnpm run typecheck
+pnpm run build
+```
+
+The build generates `dist/index.*` plus `dist/styles.css`. Consumers should import both the compiled JS and CSS bundle.