ab-ecosystem-sso 0.1.18 → 0.2.0

package/README.md

@@ -4,7 +4,11 @@ Drop-in React auth & account UI for the partner-ecosystem **Auth-as-a-Service**
 
 - ⚛️ 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.
+- 🌗 Built-in **light and dark mode** — per component, via a single `mode` prop.
 - 🔌 Use it declaratively (`<AccountSettings />`) or imperatively (`openAccountSettings()`).
+- 👥 **Multi-account aware** — account picker, account switching, invitations, roles & members.
+- 🔑 **Stores the session token for you** and falls back to it everywhere, so `token` props are optional.
+- 🧭 **Ships its own routes** — spread them into your router, or let the package match the path.
 - 🧩 Every network call also available as a plain function for custom UIs.
 
 ---
@@ -13,14 +17,20 @@ Drop-in React auth & account UI for the partner-ecosystem **Auth-as-a-Service**
 
 - [Installation](#installation)
 - [Configuration basics](#configuration-basics)
+- [Token handling](#token-handling) — storage, `getAuthHeader`, `authFetch`
+- [Routes](#routes) — `ssoRoutes` · `SsoAuthRoutes` · `SsoAuthPage`
 - [Auth screens](#auth-screens) — `Login` · `Signup` · `ForgotPassword` · `VerifyEmail`
 - [Session management](#session-management) — `SessionProvider`, enforce subscription
+- [Multiple accounts](#multiple-accounts) — account picker, switching, revoked access
+- [Invitations](#invitations) — `AcceptInvite`, invite links
+- [Team administration](#team-administration) — members · roles · invitations
 - [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)
+- [Light & dark mode](#light--dark-mode)
 - [Theming](#theming)
 - [API reference](#api-reference)
 - [TypeScript](#typescript)
@@ -59,6 +69,155 @@ You own the token: persist it (e.g. `localStorage`) on `onSuccess`, pass it back
 
 ---
 
+## Token handling
+
+**The package stores the session token for you.** Every screen that receives one — login, 2FA, account selection, account switching, signup, invite acceptance, magic links — writes it to `localStorage`, and every call the package makes falls back to it. So `token` props are optional now, and this is enough:
+
+```tsx
+<Login projectId="your-project-id" />          // token stored on success
+<AccountSettings open onOpenChange={setOpen} projectId="your-project-id" />
+<SessionProvider projectId="your-project-id">{children}</SessionProvider>
+```
+
+It's cleared on `logout()`, on `LogoutButton`, and whenever a session turns out to be invalid. Account switching **replaces** it, so later calls can't keep acting as the previous account.
+
+```ts
+import { configureTokenStorage } from "ab-ecosystem-sso";
+
+configureTokenStorage({ key: "authToken" });          // match an existing app's key
+configureTokenStorage({ storage: "sessionStorage" }); // per-tab instead of persistent
+configureTokenStorage({ enabled: false });            // opt out; you handle the token
+```
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `key` | `"ab-sso:accessToken"` | Namespaced on purpose — a bare `accessToken` collides with whatever your app already keeps under that name. |
+| `storage` | `"localStorage"` | Or `"sessionStorage"`, `"memory"`, `"none"`. |
+| `enabled` | `true` | `false` turns off both reading and writing. |
+
+Per component, `persistToken={false}` skips the write for that screen and `tokenStorageKey` overrides the key.
+
+> A bearer token in `localStorage` is readable by any script on your origin. That's the same thing most hosts were already doing by hand, but it is now the **default** — switch to `sessionStorage`, or turn it off, if your threat model says otherwise.
+
+Reading it back, and the helpers for your own calls:
+
+```ts
+import { getStoredToken, clearStoredToken, onStoredTokenChange } from "ab-ecosystem-sso";
+
+getStoredToken();                       // "" when signed out
+clearStoredToken();                     // sign out locally
+onStoredTokenChange((t) => …);          // fires on login / switch / logout (this tab)
+```
+
+Storage access throws in private windows and with site data blocked, so every read and write is guarded and falls back to an in-memory value for the life of the page — it degrades, it never throws at you.
+
+### Sending the token to your own backend
+
+The package **does not** patch your app's HTTP client, and that's deliberate: a blanket `fetch` patch would attach your bearer token to every outbound request on the page, third-party scripts included. Three explicit options instead, in order of how much they touch:
+
+**1. `getAuthHeader()`** — one line in whatever client you already have:
+
+```ts
+import { getAuthHeader } from "ab-ecosystem-sso";
+
+axios.interceptors.request.use((cfg) => {
+  cfg.headers = { ...cfg.headers, ...getAuthHeader() };
+  return cfg;
+});
+```
+
+**2. `authFetch()`** — a `fetch` wrapper that also handles the 401 split:
+
+```ts
+import { authFetch, configureAuthHandlers } from "ab-ecosystem-sso";
+
+configureAuthHandlers({
+  onUnauthorized: () => navigate("/login"),        // session gone
+  onAccountAccessLost: () => showAccountPicker(),  // A403: this account only
+});
+
+const res = await authFetch("/api/orders");
+```
+
+That second handler is the real win here: it's what makes ["access to one account was revoked"](#when-access-to-one-account-is-revoked) behave correctly for *your* endpoints too, not just ours. An `Authorization` header you set yourself is never overwritten, and the response body reaches you unread.
+
+**3. `installAuthInterceptor({ origins })`** — for apps with too many call sites to touch. It patches `fetch` and `XMLHttpRequest`, but only for an explicit allowlist:
+
+```ts
+import { installAuthInterceptor } from "ab-ecosystem-sso";
+
+const stop = installAuthInterceptor({
+  origins: ["self", "https://api.example.com"],   // "self" = your own origin (covers /api/…)
+  onUnauthorized: () => navigate("/login"),
+  onAccountAccessLost: () => showAccountPicker(),
+});
+```
+
+There is no wildcard and the allowlist is **required** — it throws without one. Anything not listed is left completely alone, which is what keeps the token away from analytics, CDNs and payment widgets. `stop()` restores the originals.
+
+---
+
+## Routes
+
+Six routes are load-bearing for any app embedding this package:
+
+| Path | Screen | Reached by |
+| --- | --- | --- |
+| `/login` | `Login` | your app, and the package's own redirects |
+| `/signup` | `Signup` | the login screen |
+| `/forgot-password` | `ForgotPassword` | the login screen |
+| `/reset-password` | `ForgotPassword` (reset step) | the emailed reset link |
+| `/verify/:token` | `VerifyEmail` | the emailed verification link |
+| `/accept-invite` | `AcceptInvite` | invite links (`inviteLinkBase`) |
+
+A library can't discover your app's routes — react-router keeps no readable registry at runtime, and Next's routes are filesystem and build-time — so the package publishes what it expects and gives you three ways to satisfy it.
+
+**Already have a router?** Spread the route objects in, so the screens sit inside your layouts and guards:
+
+```tsx
+import { ssoRoutes } from "ab-ecosystem-sso";
+import { useNavigate } from "react-router-dom";
+
+const navigate = useNavigate();
+createBrowserRouter([
+  ...ssoRoutes({ projectId: "your-project-id", onNavigate: navigate, redirectTo: "/dashboard" }),
+  ...appRoutes,
+]);
+```
+
+Pass `onNavigate` so the screens move through *your* router — the default `history.pushState` won't re-render it. Token-bearing routes are registered both bare and with a `:token` segment, since links arrive both ways.
+
+**No router?** Mount the whole set and let the package match the path:
+
+```tsx
+import { SsoAuthRoutes } from "ab-ecosystem-sso";
+
+<SsoAuthRoutes projectId="your-project-id" redirectTo="/dashboard" fallback={<App />} />
+```
+
+**File-based routing (Next)?** One tiny file per route:
+
+```tsx
+// app/login/page.tsx
+import { SsoAuthPage } from "ab-ecosystem-sso";
+export default () => <SsoAuthPage screen="login" projectId="your-project-id" />;
+```
+
+All three wire the screens to each other, store the token on success, and then leave for `redirectTo` (default `/`). A `?next=` parameter wins over `redirectTo` — and is rejected unless it's a same-site path, so the login screen can't be turned into an open redirect. Replace the whole behaviour with `onAuthenticated`.
+
+Paths aren't fixed:
+
+```ts
+import { configureSsoRoutes } from "ab-ecosystem-sso";
+configureSsoRoutes({ login: "/sign-in", acceptInvite: "/invite" });
+```
+
+`basePath="/auth"` mounts everything under a prefix. `getSsoRoutes()` returns what's in effect, and `SessionProvider` uses it for its default redirect (with `?next=` back to where the user was), so a remapped login route is honoured everywhere.
+
+> ⚠️ **Your server has to serve the app shell for these paths.** If `/accept-invite` isn't rewritten to `index.html`, the user gets a 404 before any JavaScript runs, and no client-side package can fix that. For a static SPA host that's a catch-all rewrite to `/index.html`; on nginx, `try_files $uri /index.html;`.
+
+---
+
 ## Auth screens
 
 ### `Login`
@@ -84,6 +243,8 @@ function LoginPage() {
 }
 ```
 
+The password field has a **show/hide (eye) toggle** — it always starts masked, and the same control appears on `Signup`, the `ForgotPassword` reset step, and the Account Settings change-password modal.
+
 `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.
 
 **Magic-link sign-in** works automatically: point your magic link at `/login#<access_token>` (a bare `/login#access_token=<token>` is also accepted). On mount, `Login` reads the token from the URL hash, validates it with a `/me` call, and — if valid — strips it from the URL and fires `onSuccess({ token, user })`, exactly like a password sign-in. While it validates, a loading state shows; if the token is invalid or expired, it falls back to the normal sign-in form with a short notice (and calls `onError`). No extra wiring needed beyond routing the link to your login page.
@@ -177,8 +338,11 @@ On success it calls `onVerified` (send the user to login) and shows a **Continue
 | `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`, … |
+| `mode` | `"light" \| "dark"` | Colour scheme. Default `"light"`. See [Light & dark mode](#light--dark-mode). |
+| `persistToken` | `boolean` | Store the issued token. Default `true`. See [Token handling](#token-handling). |
+| `tokenStorageKey` | `string` | Storage key override for this screen. |
 
-Per-screen extras: `Login` adds `onForgotPassword` / `onSignupClick`; `Signup` adds `onLoginClick` / `countries`; `ForgotPassword` adds `onBackToLogin` / `resetToken` / `onResetSuccess`; `VerifyEmail` adds `token` / `onVerified` / `onLoginClick` / `onSignupClick` (and has no `onSuccess`, since no session is created).
+Per-screen extras: `Login` adds `onForgotPassword` / `onSignupClick` / `client` (see [Multiple accounts](#multiple-accounts)); `Signup` adds `inviteToken` / `inviteEmail` (see [Invitations](#invitations)); `Signup` adds `onLoginClick` / `countries`; `ForgotPassword` adds `onBackToLogin` / `resetToken` / `onResetSuccess`; `VerifyEmail` adds `token` / `onVerified` / `onLoginClick` / `onSignupClick` (and has no `onSuccess`, since no session is created).
 
 ---
 
@@ -189,12 +353,9 @@ Wrap authenticated areas in `SessionProvider`. It validates the token against `/
 ```tsx
 import { SessionProvider } from "ab-ecosystem-sso";
 
-<SessionProvider
-  projectId="your-project-id"
-  token={token}
-  apiBaseUrl="https://your-api"
-  onSessionInvalid={() => navigate("/login")}
->
+// `token` and `onSessionInvalid` are both optional: it reads the stored token
+// and falls back to redirecting to the login route.
+<SessionProvider projectId="your-project-id" apiBaseUrl="https://your-api">
   <Dashboard />
 </SessionProvider>
 ```
@@ -202,10 +363,13 @@ import { SessionProvider } from "ab-ecosystem-sso";
 | Prop | Type | Notes |
 | --- | --- | --- |
 | `projectId` | `string` | **Required.** |
-| `token` | `string \| null` | Null ⇒ treated as signed-out. |
-| `onSessionInvalid` | `() => void` | Called on invalid/expired session or logout. |
+| `token` | `string \| null` | **Omit** to use the stored token; `null` states explicitly that there's no session. |
+| `onSessionInvalid` | `() => void` | Called on invalid/expired session or logout. Optional — defaults to redirecting to the login route with `?next=`. |
 | `apiBaseUrl` | `string` | Optional. |
 | `enforceActiveSubscription` | `boolean` | See below. |
+| `onTokenChange` | `(token: string) => void` | Receives a fresh token when the user switches account from the built-in picker. |
+| `onAccountAccessLost` | `({ message, code }) => void` | Access to *this* account was revoked/expired (`A403`) — handle it instead of the built-in picker. |
+| `mode` | `"light" \| "dark"` | Colour scheme for the built-in picker. |
 
 ### Enforce an active subscription
 
@@ -219,9 +383,167 @@ With `enforceActiveSubscription`, once authenticated the provider checks the use
 
 ---
 
+## Multiple accounts
+
+A login can belong to more than one account (their own, plus any they've been invited to). When it does, `/auth/login` and `/auth/verify-2fa` return **no token** — they return an account picker instead:
+
+```json
+{
+  "success": true,
+  "accountSelectionRequired": true,
+  "accounts": [{ "account_id": "66f…b2", "name": "Bob's Co", "is_owner": false, "role": "Manager", "access_expiry": null }],
+  "selectionTicket": "eyJ…"
+}
+```
+
+**`Login` handles this for you.** It renders the picker as a third step — exactly like the existing 2FA step — exchanges the chosen account's `selectionTicket` via `/auth/select-account`, and only then calls `onSuccess`, with the same `data.accessToken` shape a single-account login gives you (plus the chosen `account`). No change is needed in your `onSuccess`:
+
+```tsx
+<Login
+  projectId="your-project-id"
+  client="webapp"                        // optional: recorded on the session
+  onSuccess={(res) => save(res.data.accessToken)}
+/>
+```
+
+> ⚠️ If you were reading `data.accessToken` straight out of the login response in your own code, add the `accountSelectionRequired` branch — on that branch there is no token, and the `selectionTicket` is only valid for **five minutes**.
+
+### Switching account on a live session
+
+`AccountPicker` is also exported on its own. Given a `token` instead of a ticket it lists the accounts from `GET /accounts` and switches via `/auth/switch-account`, handing you a **fresh token** to store in place of the old one (the previous token stays valid until it expires or is logged out):
+
+```tsx
+import { AccountPicker } from "ab-ecosystem-sso";
+
+<AccountPicker
+  projectId="your-project-id"
+  token={token}
+  variant="list"                 // no card chrome — drops into a dropdown or panel
+  currentAccountId={accountId}   // marks the current one
+  onSelect={({ accessToken, account }) => save(accessToken, account.account_id)}
+/>
+```
+
+The Account Settings modal has this built in as an **Accounts** section — see [`onAccountSwitch`](#props).
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `projectId` | `string` | **Required.** |
+| `selectionTicket` | `string` | Ticket mode (post-login). Pass with `accounts`. |
+| `accounts` | `AccountOption[]` | The list to choose from; fetched automatically in session mode. |
+| `token` | `string` | Session mode — picking switches account instead. |
+| `client` | `string` | Recorded on the session by select-account, e.g. `"webapp"`. |
+| `variant` | `"card" \| "list"` | Full auth card (default) or a bare list. |
+| `currentAccountId` | `string` | Marks the account the session is already on. |
+| `onSelect` | `({ accessToken, account }) => void` | Called with the new token. |
+| `onCancel` / `cancelLabel` | `() => void` / `string` | Renders a secondary action under the list. |
+| `title` / `description` | `string` | Card copy overrides. |
+| `onError`, `classNames`, `mode`, `config`, `apiBaseUrl` | | As elsewhere. |
+
+### When access to one account is revoked
+
+If an owner revokes or expires a member's access, that member's **next request to any endpoint** fails with `401` and code `A403`. Their login is still fine — only that one account became unreachable — so this is **not** a logout.
+
+`SessionProvider` tells the two apart. Give it `onTokenChange` and it renders the account picker itself; give it `onAccountAccessLost` to handle the case yourself:
+
+```tsx
+<SessionProvider
+  projectId="your-project-id"
+  token={token}
+  onTokenChange={save}                       // picker appears, new token lands here
+  onSessionInvalid={() => navigate("/login")} // genuine logout
+>
+  <Dashboard />
+</SessionProvider>
+```
+
+`useSession()` also exposes `accountAccessLost` (`{ message, code } | null`). For your own fetch wrappers, `isAccountAccessError(err)` returns true for exactly this case:
+
+```ts
+import { isAccountAccessError } from "ab-ecosystem-sso";
+
+catch (err) {
+  if (isAccountAccessError(err)) showAccountPicker();
+  else if (err.status === 401) logout();
+}
+```
+
+---
+
+## Invitations
+
+An owner invites someone by email, and the backend returns a **link token** — it **sends no email**, so the link is yours to deliver. Build the invitee's route with `AcceptInvite`:
+
+```tsx
+import { AcceptInvite } from "ab-ecosystem-sso";
+
+// e.g. /accept-invite?token=…
+<AcceptInvite
+  projectId="your-project-id"
+  inviteToken={new URLSearchParams(location.search).get("token") ?? ""}
+  token={session}                              // if they're already signed in
+  onAccepted={({ accessToken }) => accessToken && save(accessToken)}
+  onNeedLogin={() => navigate("/login?next=/accept-invite" + location.search)}
+  onSuccess={(res) => save(res.data.accessToken)}  // the signup branch
+/>
+```
+
+It resolves the token first (`GET /invitations/:token`) and then renders whichever branch the backend asked for:
+
+- **`mode: "signup"`** — they have no login here yet. It renders `Signup` with `inviteToken` set and the invited address prefilled and read-only. This works even when the project has signups **disabled**, and the account is created already verified and active (no verification email).
+- **`mode: "accept"`** — they already log in here. With a `token` it shows the invite details and an accept button, then switches the session onto the joined account. Without one it calls `onNeedLogin` so you can route them through your own login and come back.
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `projectId` | `string` | **Required.** |
+| `inviteToken` | `string` | **Required** — the `token` from the link. |
+| `token` | `string` | A live session token; required by the `"accept"` branch. |
+| `switchOnAccept` | `boolean` | Switch onto the joined account after accepting. Default `true`. |
+| `onAccepted` | `({ accountId, accessToken }) => void` | After accepting. `accessToken` is the switched session. |
+| `onNeedLogin` | `(invitation) => void` | The invite needs an existing login and none was given. |
+| `onSuccess` | `(res) => void` | Forwarded to `Signup` on the signup branch. |
+| `countries`, `onError`, `classNames`, `mode`, `config`, `apiBaseUrl` | | As elsewhere. |
+
+The email is always rendered read-only: on signup the server takes it from the invite record and ignores anything posted, and on accept a mismatch is rejected ("This invitation was sent to a different email").
+
+---
+
+## Team administration
+
+Owners get three more Account Settings sections — **Members**, **Roles** and **Invitations** — on top of the usual ones. They need live API mode (`projectId` + `token`):
+
+```tsx
+openAccountSettings({
+  projectId: "your-project-id",
+  token,
+  initialSection: "members",
+  inviteLinkBase: "https://app.example.com/accept-invite",  // where invite links point
+  currentAccountId: accountId,
+  onAccountSwitch: ({ accessToken }) => save(accessToken),  // also enables the Accounts tab
+});
+```
+
+- **Members** — list active or revoked members; edit a member's role and access expiry; revoke access. Revoking leaves their login alone: only this account becomes unreachable, from their next request onward, and re-inviting the same person restores the membership.
+- **Roles** — create, edit and delete roles with a permission list (one per line). The server trims, uppercases, dedupes and sorts permissions (max 200), and they aren't validated against a catalogue yet, so a misspelled string simply grants nothing. **System** roles are assignable but neither editable nor deletable, and a role still held by anyone can't be deleted.
+- **Invitations** — create invites (email, member/user, role, access expiry), filter by status, and revoke pending ones. After creating one, the link is shown **once** with a copy button — the token is never returned again and no email is sent.
+
+Every endpoint behind these is **owner-only**. A non-owner gets `"Only the account owner can do this"`, which the sections display as-is rather than guessing at permissions client-side. Pass `isOwner={false}` to hide the tabs outright.
+
+The three panels are also exported for use in your own admin page:
+
+```tsx
+import { MembersSection, RolesSection, InvitationsSection } from "ab-ecosystem-sso";
+
+<MembersSection projectId="your-project-id" token={token} />
+```
+
+> They're styled for the settings modal, so render them inside an element carrying `data-aas` (and `data-aas-theme` for dark mode — see [Light & dark mode](#light--dark-mode)).
+
+---
+
 ## Account Settings modal
 
-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).
+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), **Credit Wallets** (per-wallet balance, logs, top-up), plus the owner-only **Members**, **Roles** and **Invitations** sections and an optional **Accounts** switcher (see [Team administration](#team-administration)). It loads and saves via the live API whenever `projectId` + `token` are supplied (otherwise it renders sample data).
 
 ### Imperative (recommended)
 
@@ -268,11 +590,17 @@ const [open, setOpen] = useState(false);
 | `open` | `boolean` | **Required** (declarative). |
 | `onOpenChange` | `(open: boolean) => void` | **Required** (declarative). |
 | `projectId` | `string` | Enables live API mode (with `token`). |
-| `token` | `string` | Bearer token. |
+| `token` | `string` | Bearer token. Optional — falls back to the stored one. |
 | `apiBaseUrl` | `string` | Optional API origin. |
-| `initialSection` | `"general" \| "account" \| "wallet" \| "plans" \| "credits"` | First section shown. Default `"general"`. |
+| `initialSection` | `AccountSettingsSection` | `"general"`, `"account"`, `"wallet"`, `"plans"`, `"credits"`, `"accounts"`, `"members"`, `"roles"` or `"invitations"`. Default `"general"`. |
+| `customComponents` | `AccountSettingsCustomPanel[]` | Add your own panels to the modal. See [Custom panels](#custom-panels). |
 | `syncUrlHash` | `boolean` | Mirror open state + active section in the URL hash. Default `true`. See [URL hash & refresh](#url-hash--refresh). |
 | `title` | `string` | Modal heading. Default `"Settings"`. |
+| `mode` | `"light" \| "dark"` | Colour scheme. Default `"light"`. See [Light & dark mode](#light--dark-mode). |
+| `isOwner` | `boolean` | Pass `false` to hide the Members / Roles / Invitations sections. Omitted ⇒ shown, and the API refuses non-owners with its own message. |
+| `inviteLinkBase` | `string` | Where invite links point; the token is appended as `?token=…`. Default `<origin>/accept-invite`. |
+| `onAccountSwitch` | `({ accessToken, accountId }) => void` | Enables the **Accounts** switcher. Store the fresh token in place of the old one. |
+| `currentAccountId` | `string` | Marked "Current" in the switcher. |
 | `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. |
@@ -282,6 +610,45 @@ const [open, setOpen] = useState(false);
 
 > 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.
 
+### Custom panels
+
+Add your own screens to the modal via `customComponents` — an array of `AccountSettingsCustomPanel`. Each entry renders a **trigger** (in the sidebar, pinned to the sidebar bottom, or in the header next to the close button) and shows its `component` in the modal body when activated.
+
+```tsx
+<AccountSettings
+  open={open}
+  onOpenChange={setOpen}
+  projectId="your-project-id"
+  token={token}
+  customComponents={[
+    {
+      id: "referrals",
+      location: "sidebar",            // "sidebar" | "sidebar-bottom" | "header"
+      label: "Referrals",
+      icon: <GiftIcon />,             // any node (an inline SVG works best)
+      component: <ReferralsPanel />,  // rendered in the modal body
+    },
+    {
+      id: "help",
+      location: "header",
+      label: "Help",
+      icon: <HelpIcon />,
+      component: <HelpCenter />,
+    },
+  ]}
+/>
+```
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | `string` | **Required**, unique. Tracks which panel is active. |
+| `location` | `"sidebar" \| "sidebar-bottom" \| "header"` | Where the trigger appears. Default `"sidebar"`. |
+| `label` | `string` | Sidebar text; header button tooltip + `aria-label`. |
+| `icon` | `ReactNode` | Optional trigger icon. |
+| `component` | `ReactNode` | Rendered in the body when the panel is active. |
+
+The same `customComponents` array works with the imperative `openAccountSettings({ customComponents: [...] })`. Panels are host-owned — they don't affect the URL hash, and activating one doesn't run the built-in section's API calls.
+
 ### URL hash & refresh
 
 While the modal is open it reflects the active section in the URL hash as `#settings-<section>` (e.g. `#settings-general`, `#settings-plans`), updating as the user switches tabs and clearing it on close. This means a **page refresh can re-open the modal on the same section**. It uses `history.replaceState`, so it never adds browser-history entries and never clobbers an unrelated `#anchor`. Opt out with `syncUrlHash={false}`.
@@ -329,7 +696,7 @@ onClick={() => logout({
 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 />` with no props uses the provider's logout instead.
+`<LogoutButton />` also takes `mode="dark"`. `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.
 
 ---
 
@@ -389,6 +756,7 @@ import { TwoFactorSetup } from "ab-ecosystem-sso";
   projectId="your-project-id"
   token={token}
   apiBaseUrl="https://your-api"
+  mode="dark"            // optional — "light" (default) or "dark"
   onEnabled={() => …}
   onDisabled={() => …}
   onError={(err) => …}
@@ -407,6 +775,58 @@ import { TwoFactorSetup } from "ab-ecosystem-sso";
 
 ---
 
+## Light & dark mode
+
+Every component renders in **light mode by default**. Pass `mode="dark"` to switch:
+
+```tsx
+<Login projectId="…" mode="dark" onSuccess={handleAuth} />
+<Signup projectId="…" mode="dark" onLoginClick={() => navigate("/login")} />
+<ForgotPassword projectId="…" mode="dark" />
+<VerifyEmail projectId="…" mode="dark" />
+<AccountSettings open={open} onOpenChange={setOpen} mode="dark" />
+<TwoFactorSetup projectId="…" token={token} mode="dark" />
+<LogoutButton mode="dark" />
+
+openAccountSettings({ projectId, token, mode: "dark" });
+```
+
+`mode` is **per component**, not global — each component root carries a
+`data-aas-theme="light" | "dark"` attribute and the palette inherits from there, so a dark
+login card and a light settings modal can coexist on the same page.
+
+Follow your app's own theme by passing the value you already track:
+
+```tsx
+const { theme } = useTheme();          // your app's theme state
+<Login projectId="…" mode={theme === "dark" ? "dark" : "light"} />
+```
+
+To follow the OS setting instead:
+
+```tsx
+import type { AuthMode } from "ab-ecosystem-sso";
+
+const [mode, setMode] = useState<AuthMode>(
+  () => (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light")
+);
+
+useEffect(() => {
+  const mq = window.matchMedia("(prefers-color-scheme: dark)");
+  const onChange = (e: MediaQueryListEvent) => setMode(e.matches ? "dark" : "light");
+  mq.addEventListener("change", onChange);
+  return () => mq.removeEventListener("change", onChange);
+}, []);
+
+<Login projectId="…" mode={mode} />
+```
+
+> The package deliberately does **not** read `prefers-color-scheme` itself — an auth screen
+> that silently disagrees with the host app's theme is worse than one that follows it, and only
+> your app knows which theme it's in.
+
+---
+
 ## Theming
 
 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:
@@ -424,6 +844,28 @@ The UI reads `--aas-*` CSS custom properties, so you can retheme without touchin
 }
 ```
 
+Dark mode is the same variables redeclared on `[data-aas-theme='dark']`, so retheming dark is symmetrical — override there and light stays untouched:
+
+```css
+[data-aas-theme="dark"] {
+  --aas-background: oklch(0.16 0.01 265);
+  --aas-card: oklch(0.21 0.01 265);
+  --aas-primary: oklch(0.72 0.17 265);
+  --aas-primary-foreground: oklch(0.16 0.01 265);
+}
+```
+
+Beyond the shadcn-style tokens above, a few extra ones exist so dark mode is a pure variable
+swap — override them to fine-tune either palette:
+
+| Token | Used for |
+| --- | --- |
+| `--aas-sidebar` | Account Settings sidebar panel. |
+| `--aas-hover` / `--aas-hover-strong` | Nav/icon-button hover and active fills. |
+| `--aas-overlay` / `--aas-overlay-strong` | The blur overlays on loading cards and settings sections. |
+| `--aas-success` / `--aas-success-bg` | "Verified" badges and credit amounts. |
+| `--aas-switch-track`, `--aas-switch-knob`, `--aas-switch-knob-on` | The settings toggle switch. |
+
 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.
 
 ---
@@ -443,6 +885,15 @@ Beyond the components, these functions are exported for building custom UIs:
 | `getUserWallet(projectId, token, apiBaseUrl?)` | `GET /me` → `UserWallets` |
 | `getUserCreditWallet(projectId, token, apiBaseUrl?)` | `GET /credit-wallets` → `CreditWallet[]` |
 | `getUserSubscription(projectId, token, apiBaseUrl?)` | `GET /subscription` → raw subscription object |
+| `selectAccountApi(projectId, { selection_ticket, account_id, client? }, apiBaseUrl?)` | `POST /auth/select-account` → `accessToken` (no auth; the ticket is the credential) |
+| `switchAccountApi(projectId, accountId, token, apiBaseUrl?)` | `POST /auth/switch-account` → a fresh `accessToken` |
+| `listAccountsApi(projectId, token, apiBaseUrl?)` | `GET /accounts` → `AccountOption[]` |
+| `getInvitationApi(projectId, inviteToken, apiBaseUrl?)` | `GET /invitations/:token` → `InvitationLookup` (no auth) |
+| `acceptInvitationApi(projectId, inviteToken, token, apiBaseUrl?)` | `POST /invitations/:token/accept` → `account_id` |
+| `listRolesApi` · `createRoleApi` · `updateRoleApi` · `deleteRoleApi` | `/account/roles` (owner only) |
+| `listInvitationsApi` · `createInvitationApi` · `revokeInvitationApi` | `/account/invites` (owner only) |
+| `listMembersApi` · `updateMemberApi` · `revokeMemberApi` | `/account/members` (owner only) |
+| `validateSession(projectId, token, apiBaseUrl?)` | `GET /me` → `{ valid, accountAccessLost, message, code }` |
 | `logout(options)` | `POST /auth/logout` + callbacks |
 | `logoutApi(projectId, token, apiBaseUrl?)` | `POST /auth/logout` |
 
@@ -456,15 +907,24 @@ Everything is fully typed. Notable exports:
 
 ```ts
 import type {
-  LoginProps, SignupProps, ForgotPasswordProps, VerifyEmailProps, AuthClassNames,
+  LoginProps, SignupProps, ForgotPasswordProps, VerifyEmailProps, AuthClassNames, AuthMode,
   AccountSettingsProps, AccountSettingsSection, AccountSettingsData, ProfileFormValues,
   OpenAccountSettingsOptions, AccountSettingsHandle,
   AuthConfig, CaptchaConfig, CardLayoutConfig,
   LoginRequest, SignupRequest, ForgotPasswordRequest, AuthResponse, LogoutOptions,
   MappedProfile, WalletInfo, UserWallets, CreditWallet, MappedSubscription,
+  AccountPickerProps, AcceptInviteProps,
+  AccountOption, SelectAccountRequest, AccessTokenResponse, InvitationLookup, SessionValidation,
+  Role, CreateRolePayload, UpdateRolePayload,
+  Invitation, InvitationStatus, CreateInvitePayload, CreatedInvite,
+  Member, MemberStatus, UpdateMemberPayload,
+  TokenStorageConfig, TokenStorageKind,
+  AuthFetchInit, AuthHandlers, AuthInterceptorOptions, UnauthorizedInfo,
+  SsoRoutePaths, SsoScreen, SsoRouteMatch, SsoRouteObject,
+  SsoScreenProps, SsoAuthPageProps, SsoAuthRoutesProps,
 } from "ab-ecosystem-sso";
 
-import { AuthApiError } from "ab-ecosystem-sso";
+import { AuthApiError, isAccountAccessError } from "ab-ecosystem-sso";
 ```
 
 ---