ab-ecosystem-sso 0.1.9 → 0.1.10

package/README.md

@@ -1,11 +1,29 @@
 # ab-ecosystem-sso
 
-Drop-in React auth & account UI for the partner-ecosystem **Auth-as-a-Service** backend — login, signup, forgot-password, two-factor, session validation, and a full Account Settings modal (profile, wallet, plans & add-ons, credit wallets), all wired to the `/api/v1/projects/:projectId/...` endpoints.
+Drop-in React auth & account UI for the partner-ecosystem **Auth-as-a-Service** backend. Ships production-ready screens — login (with 2FA), signup, forgot-password, session validation, and a full **Account Settings** modal (profile, wallet, plans & add-ons, credit wallets) — all wired to the `/api/v1/projects/:projectId/...` endpoints, plus low-level helpers (`getUser`, `logout`, `useSession`) for building your own UI.
 
-- ⚛️ React 18 / 19 components, shipped as ESM + CJS with TypeScript types.
-- 🎨 Self-contained, theme-aware styles (scoped so they won't leak into your app).
-- 🔌 Works declaratively (`<AccountSettings />`) or imperatively (`openAccountSettings()`).
-- 🧩 Low-level helpers (`getUser`, `logout`, `useSession`) for building your own UI.
+- ⚛️ React 18 / 19, shipped as ESM + CJS with full TypeScript types.
+- 🎨 Self-contained, theme-aware CSS that **won't leak into or be overridden by** your app.
+- 🔌 Use it declaratively (`<AccountSettings />`) or imperatively (`openAccountSettings()`).
+- 🧩 Every network call also available as a plain function for custom UIs.
+
+---
+
+## Table of contents
+
+- [Installation](#installation)
+- [Configuration basics](#configuration-basics)
+- [Auth screens](#auth-screens) — `Login` · `Signup` · `ForgotPassword`
+- [Session management](#session-management) — `SessionProvider`, enforce subscription
+- [Account Settings modal](#account-settings-modal) — `openAccountSettings` / `AccountSettings`
+- [Logout](#logout) — `logout` · `LogoutButton` · `logoutApi`
+- [Fetching the current user](#fetching-the-current-user) — `getUser`
+- [Fetching user data](#fetching-user-data) — `getUserProfile` · `getUserWallet` · `getUserCreditWallet` · `getUserSubscription`
+- [Two-factor setup](#two-factor-setup)
+- [Hooks](#hooks)
+- [Theming](#theming)
+- [API reference](#api-reference)
+- [TypeScript](#typescript)
 
 ---
 
@@ -15,35 +33,35 @@ Drop-in React auth & account UI for the partner-ecosystem **Auth-as-a-Service**
 npm install ab-ecosystem-sso
 ```
 
-`react` and `react-dom` are **peer dependencies** (v18 or v19) — make sure they're installed in your app.
+`react` and `react-dom` (v18 or v19) are **peer dependencies** — install them in your app.
 
 ### Import the stylesheet once
 
-The components ship a single CSS file. Import it once at your app's entry point:
-
 ```ts
 import "ab-ecosystem-sso/styles.css";
 ```
 
-Styles are scoped (Tailwind `sso:` prefix + a `[data-aas]` root on the settings modal) so they won't collide with your app's CSS.
+The CSS is scoped (a `[data-aas]` root + the `sso:` utility prefix) and shipped **unlayered**, so it never touches your app's elements and your app's resets (e.g. Tailwind's preflight) never override it. No extra `@layer` setup needed.
 
 ---
 
-## Configuration
+## Configuration basics
 
-Every component/function takes:
+Almost everything takes the same three inputs:
 
-| Prop | Description |
+| Input | Description |
 | --- | --- |
-| `projectId` | Your project id, e.g. `436582-forms.abprojects.com`. Required. |
-| `token` | The auth JWT (from the login response). Required for authenticated calls. |
-| `apiBaseUrl` | API origin override, e.g. `https://partner-api.example.com`. Falls back to the `VITE_AUTH_API_BASE_URL` env var. |
+| `projectId` | Your project id, e.g. `436582-forms.abprojects.com`. **Required.** |
+| `token` | The auth JWT from the login response. Required for authenticated calls. |
+| `apiBaseUrl` | API origin, e.g. `https://partner-api.example.com`. Falls back to the `VITE_AUTH_API_BASE_URL` env var. |
+
+You own the token: persist it (e.g. `localStorage`) on `onSuccess`, pass it back into the authenticated components/functions, and clear it on logout.
 
 ---
 
 ## Auth screens
 
-### Login
+### `Login`
 
 ```tsx
 import { Login } from "ab-ecosystem-sso";
@@ -56,9 +74,9 @@ function LoginPage() {
       apiBaseUrl="https://your-api"
       onSuccess={({ token, user }) => {
         localStorage.setItem("token", token);
-        window.location.href = "/dashboard";
+        navigate("/dashboard");
       }}
-      onError={(err) => console.error(err)}
+      onError={(err) => toast.error(err.message)}
       onForgotPassword={() => navigate("/forgot-password")}
       onSignupClick={() => navigate("/signup")}
     />
@@ -66,33 +84,35 @@ function LoginPage() {
 }
 ```
 
-`Login` fetches the project's `auth-config` (captcha, branding, which links to show) and renders accordingly. If the account has **2FA** enabled, it automatically shows a segmented 6-digit OTP step (with captcha when required) and completes the flow before calling `onSuccess`.
+`Login` first fetches the project's `auth-config` (captcha provider/site-key, branding, which links to show) and renders accordingly. If the account has **2FA** enabled it automatically shows a **segmented 6-digit OTP** step (with captcha when the project requires it), and only calls `onSuccess` after verification succeeds.
 
-### Signup & Forgot password
+### `Signup` and `ForgotPassword`
 
 ```tsx
 import { Signup, ForgotPassword } from "ab-ecosystem-sso";
 
-<Signup projectId="…" onSuccess={…} onLoginClick={() => navigate("/login")} />
+<Signup projectId="…" onSuccess={handleAuth} onLoginClick={() => navigate("/login")} />
 <ForgotPassword projectId="…" onBackToLogin={() => navigate("/login")} />
 ```
 
-### Common auth props
+### Shared auth props
 
 | Prop | Type | Notes |
 | --- | --- | --- |
-| `projectId` | `string` | Required. |
+| `projectId` | `string` | **Required.** |
 | `apiBaseUrl` | `string` | Optional API origin. |
 | `config` | `AuthConfig` | Pre-fetched auth-config to skip the internal request. |
-| `onSuccess` | `({ token, user }) => void` | Called on successful auth. |
-| `onError` | `(error: Error) => void` | Called on failure. |
-| `classNames` | `AuthClassNames` | Per-element class overrides (`input`, `button`, `card`, …). |
+| `onSuccess` | `({ token, user }) => void` | On successful auth. |
+| `onError` | `(error: Error) => void` | On failure. |
+| `classNames` | `AuthClassNames` | Per-element class overrides: `card`, `input`, `label`, `button`, `link`, `captcha`, `error`, … |
+
+Per-screen extras: `Login` adds `onForgotPassword` / `onSignupClick`; `Signup` adds `onLoginClick`; `ForgotPassword` adds `onBackToLogin`.
 
 ---
 
-## Session validation
+## Session management
 
-Wrap authenticated areas of your app in `SessionProvider`. It validates the token against `/me` and renders children only when the session is valid; otherwise it calls `onSessionInvalid` (navigate to login there).
+Wrap authenticated areas in `SessionProvider`. It validates the token against `/me` and renders children only when the session is valid; otherwise it calls `onSessionInvalid` (redirect to login there).
 
 ```tsx
 import { SessionProvider } from "ab-ecosystem-sso";
@@ -107,9 +127,17 @@ import { SessionProvider } from "ab-ecosystem-sso";
 </SessionProvider>
 ```
 
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `projectId` | `string` | **Required.** |
+| `token` | `string \| null` | Null ⇒ treated as signed-out. |
+| `onSessionInvalid` | `() => void` | Called on invalid/expired session or logout. |
+| `apiBaseUrl` | `string` | Optional. |
+| `enforceActiveSubscription` | `boolean` | See below. |
+
 ### Enforce an active subscription
 
-Pass `enforceActiveSubscription` and, once authenticated, the provider checks the user's subscription. If none is active it opens the Account Settings modal on the **Plans** section — and blocks closing until a subscription exists (re-checking on each close attempt).
+With `enforceActiveSubscription`, once authenticated the provider checks the user's subscription. If none is active it opens the Account Settings modal on the **Plans** section — and **blocks closing until a subscription exists** (it re-checks on every close attempt).
 
 ```tsx
 <SessionProvider … enforceActiveSubscription>
@@ -121,7 +149,7 @@ Pass `enforceActiveSubscription` and, once authenticated, the provider checks th
 
 ## Account Settings modal
 
-A full settings surface: **General** (profile), **Account** (email, change password, 2FA, sessions), **Wallet & Balance**, **Plans & Add-ons**, and **Credit Wallets**. It loads/saves via the live API when given `projectId` + `token`.
+A complete settings surface with these sections: **General** (profile), **Account** (email, change password, 2FA, sessions), **Wallet & Balance** (balances + transaction history), **Plans & Add-ons** (subscribe, multi-subscribe add-ons, markdown plan details), and **Credit Wallets** (per-wallet balance, logs, top-up). It loads and saves via the live API whenever `projectId` + `token` are supplied (otherwise it renders sample data).
 
 ### Imperative (recommended)
 
@@ -134,14 +162,14 @@ import { openAccountSettings } from "ab-ecosystem-sso";
   projectId: "your-project-id",
   token,
   apiBaseUrl: "https://your-api",
-  initialSection: "plans",     // optional
+  initialSection: "plans",             // optional
   onLogout: () => { localStorage.clear(); navigate("/login"); },
 })}>
   Settings
 </button>
 ```
 
-`openAccountSettings(options)` returns `{ close() }` to dismiss it programmatically.
+`openAccountSettings(options)` returns a handle: `{ close() }` to dismiss it programmatically.
 
 ### Declarative
 
@@ -161,7 +189,25 @@ const [open, setOpen] = useState(false);
 />
 ```
 
-`initialSection` is one of `"general" | "account" | "billing" | "wallet" | "plans" | "credits"`.
+### Props
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `open` | `boolean` | **Required** (declarative). |
+| `onOpenChange` | `(open: boolean) => void` | **Required** (declarative). |
+| `projectId` | `string` | Enables live API mode (with `token`). |
+| `token` | `string` | Bearer token. |
+| `apiBaseUrl` | `string` | Optional API origin. |
+| `initialSection` | `"general" \| "account" \| "wallet" \| "plans" \| "credits"` | First section shown. Default `"general"`. |
+| `title` | `string` | Modal heading. Default `"Settings"`. |
+| `data` | `Partial<AccountSettingsData>` | Override sample data (non-API mode / previews). |
+| `onLogout` | `() => void` | Sign-out action (closes the modal, then runs this). |
+| `onSaveProfile` | `(profile) => void` | Fires alongside the profile save. |
+| `onChangePassword` | `(data) => void` | Fires alongside the password change. |
+| `onChangePlan` | `(planId) => void` | Fires when a plan is subscribed. |
+| `onUpdateWhatsApp`, `onToggleTwoFactor`, `onRevokeSession`, `onAddFunds` | callbacks | Observers for the respective actions. |
+
+> In live mode the modal performs the API calls itself (save profile, change password, subscribe, recharge, etc.); the callbacks are observation hooks, not required wiring.
 
 ---
 
@@ -172,7 +218,7 @@ Three options, from most convenient to most raw:
 ```tsx
 import { LogoutButton, logout, logoutApi } from "ab-ecosystem-sso";
 
-// 1) Ready-made button (no SessionProvider needed in standalone mode)
+// 1) Ready-made button (works standalone, no SessionProvider needed)
 <LogoutButton
   projectId="your-project-id"
   token={token}
@@ -186,30 +232,63 @@ onClick={() => logout({
   token,
   apiBaseUrl: "https://your-api",
   onSuccess: () => { localStorage.clear(); navigate("/login"); },
+  onError: (e) => console.error(e),
 })}
 
 // 3) The raw endpoint call
 await logoutApi("your-project-id", token, "https://your-api");
 ```
 
-`logout` POSTs to `/auth/logout` and always runs `onSuccess` once the request settles — so the user is logged out client-side even if the server call fails (`onError` fires for observability). Inside a `SessionProvider`, `<LogoutButton />` (no props) uses the provider's logout instead.
+`logout` POSTs to `/auth/logout` and **always runs `onSuccess` once the request settles** — so the user is logged out client-side even if the server call fails (`onError` fires for observability). Inside a `SessionProvider`, `<LogoutButton />` with no props uses the provider's logout instead.
 
 ---
 
-## Fetch the current user
+## Fetching the current user
 
-Populate your own header/profile-dropdown from `/me`:
+Populate your own header / profile-dropdown from `/me`:
 
 ```tsx
 import { getUser } from "ab-ecosystem-sso";
 
 const res = await getUser("your-project-id", token, "https://your-api");
-const name = res.data.profile.name.first; // { success, data: { id, username, profile, mainWallet, coinWallet } }
+// res = { success, data: { id, username, profile: { name, email, address, … }, mainWallet, coinWallet } }
+const firstName = res.data.profile.name.first;
 ```
 
+`getUser` returns the raw response envelope and throws `AuthApiError` on a non-2xx response.
+
 ---
 
-## Two-factor setup (standalone)
+## Fetching user data
+
+When you want clean, ready-to-render data instead of the raw envelope, use these getters. Each **fetches and maps** in one call, and all share the same `(projectId, token, apiBaseUrl?)` signature.
+
+```ts
+import {
+  getUserProfile,
+  getUserWallet,
+  getUserCreditWallet,
+  getUserSubscription,
+} from "ab-ecosystem-sso";
+
+const profile       = await getUserProfile("your-project-id", token, "https://your-api");
+const { mainWallet, coinWallet } = await getUserWallet("your-project-id", token, "https://your-api");
+const creditWallets = await getUserCreditWallet("your-project-id", token, "https://your-api");
+const subscription  = await getUserSubscription("your-project-id", token, "https://your-api");
+```
+
+| Function | Endpoint | Returns |
+| --- | --- | --- |
+| `getUserProfile` | `GET /me` | `MappedProfile` — flat fields (name, `email`/`username`, address, phone, `mainWallet`/`coinWallet`). |
+| `getUserWallet` | `GET /me` | `UserWallets` — just `{ mainWallet, coinWallet }` balances. |
+| `getUserCreditWallet` | `GET /credit-wallets` | `CreditWallet[]` — each `{ id, label, balance, balanceFormatted, creditUnit, fundSource, rechargeable }`. |
+| `getUserSubscription` | `GET /subscription` | `MappedSubscription` — `planId` (empty if none), `status`, `renewsAt`, `subscribedIds`, `packageCounts`. |
+
+> `getUserProfile` and `getUserWallet` both read `/me`; `getUserWallet` just narrows the same response to the wallet balances. All four throw `AccountApiError` on a non-2xx response.
+
+---
+
+## Two-factor setup
 
 For a settings page outside the modal:
 
@@ -222,6 +301,7 @@ import { TwoFactorSetup } from "ab-ecosystem-sso";
   apiBaseUrl="https://your-api"
   onEnabled={() => …}
   onDisabled={() => …}
+  onError={(err) => …}
 />
 ```
 
@@ -239,22 +319,40 @@ import { TwoFactorSetup } from "ab-ecosystem-sso";
 
 ## Theming
 
-The UI reads CSS custom properties (design tokens), so you can retheme without touching the components. Override the `--aas-*` variables on `:root` (or a parent) after importing the stylesheet:
+The UI reads `--aas-*` CSS custom properties, so you can retheme without touching the components. Override them on `:root` (or any ancestor) after importing the stylesheet:
 
 ```css
 :root {
-  --aas-primary: #4f46e5;
-  --aas-primary-foreground: #ffffff;
-  --aas-background: #ffffff;
-  --aas-foreground: #0f172a;
-  --aas-muted: #f1f5f9;
-  --aas-muted-foreground: #64748b;
-  --aas-border: #e2e8f0;
-  --aas-radius: 0.5rem;
+  --aas-primary: oklch(0.55 0.22 265);
+  --aas-primary-foreground: oklch(0.99 0 0);
+  --aas-background: oklch(1 0 0);
+  --aas-foreground: oklch(0.15 0 0);
+  --aas-muted: oklch(0.97 0 0);
+  --aas-muted-foreground: oklch(0.55 0 0);
+  --aas-border: oklch(0.92 0 0);
+  --aas-radius: 0.625rem;
 }
 ```
 
-Styles are dark-mode/theme aware and scoped to the components, so they won't affect the rest of your app.
+The styles are theme-aware and scoped to the components — they won't affect the rest of your app, and your app's global resets can't override them.
+
+---
+
+## API reference
+
+Beyond the components, these functions are exported for building custom UIs:
+
+| Function | Endpoint |
+| --- | --- |
+| `getUser(projectId, token, apiBaseUrl?)` | `GET /me` (raw envelope) |
+| `getUserProfile(projectId, token, apiBaseUrl?)` | `GET /me` → `MappedProfile` |
+| `getUserWallet(projectId, token, apiBaseUrl?)` | `GET /me` → `UserWallets` |
+| `getUserCreditWallet(projectId, token, apiBaseUrl?)` | `GET /credit-wallets` → `CreditWallet[]` |
+| `getUserSubscription(projectId, token, apiBaseUrl?)` | `GET /subscription` → `MappedSubscription` |
+| `logout(options)` | `POST /auth/logout` + callbacks |
+| `logoutApi(projectId, token, apiBaseUrl?)` | `POST /auth/logout` |
+
+> The Account Settings modal also drives a wider set of endpoints internally — profile (`/me`, `/profile`), password (`/account`), 2FA, WhatsApp, plans/subscription (`/plans`, `/subscribe`, `/subscription`), wallet (`/wallet/logs`, `/recharge-links`), and credit wallets (`/credit-wallets`, `/credit-wallets/:id/logs`, `/credit-wallets/:id/recharge`). If you need any of these as standalone helpers, open an issue and they can be exported.
 
 ---
 
@@ -265,11 +363,13 @@ Everything is fully typed. Notable exports:
 ```ts
 import type {
   LoginProps, SignupProps, ForgotPasswordProps, AuthClassNames,
-  AccountSettingsProps, AccountSettingsSection,
+  AccountSettingsProps, AccountSettingsSection, AccountSettingsData, ProfileFormValues,
   OpenAccountSettingsOptions, AccountSettingsHandle,
   AuthConfig, CaptchaConfig, CardLayoutConfig,
-  LoginRequest, AuthResponse, LogoutOptions,
+  LoginRequest, SignupRequest, ForgotPasswordRequest, AuthResponse, LogoutOptions,
+  MappedProfile, WalletInfo, UserWallets, CreditWallet, MappedSubscription,
 } from "ab-ecosystem-sso";
+
 import { AuthApiError } from "ab-ecosystem-sso";
 ```