ab-ecosystem-sso 0.1.6 → 0.1.8

package/README.md

@@ -0,0 +1,280 @@
+# 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.
+
+- ⚛️ 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.
+
+---
+
+## Installation
+
+```bash
+npm install ab-ecosystem-sso
+```
+
+`react` and `react-dom` are **peer dependencies** (v18 or v19) — make sure they're installed 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.
+
+---
+
+## Configuration
+
+Every component/function takes:
+
+| Prop | 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. |
+
+---
+
+## Auth screens
+
+### Login
+
+```tsx
+import { Login } from "ab-ecosystem-sso";
+import "ab-ecosystem-sso/styles.css";
+
+function LoginPage() {
+  return (
+    <Login
+      projectId="your-project-id"
+      apiBaseUrl="https://your-api"
+      onSuccess={({ token, user }) => {
+        localStorage.setItem("token", token);
+        window.location.href = "/dashboard";
+      }}
+      onError={(err) => console.error(err)}
+      onForgotPassword={() => navigate("/forgot-password")}
+      onSignupClick={() => navigate("/signup")}
+    />
+  );
+}
+```
+
+`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`.
+
+### Signup & Forgot password
+
+```tsx
+import { Signup, ForgotPassword } from "ab-ecosystem-sso";
+
+<Signup projectId="…" onSuccess={…} onLoginClick={() => navigate("/login")} />
+<ForgotPassword projectId="…" onBackToLogin={() => navigate("/login")} />
+```
+
+### Common auth props
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `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`, …). |
+
+---
+
+## Session validation
+
+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).
+
+```tsx
+import { SessionProvider } from "ab-ecosystem-sso";
+
+<SessionProvider
+  projectId="your-project-id"
+  token={token}
+  apiBaseUrl="https://your-api"
+  onSessionInvalid={() => navigate("/login")}
+>
+  <Dashboard />
+</SessionProvider>
+```
+
+### 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).
+
+```tsx
+<SessionProvider … enforceActiveSubscription>
+  <Dashboard />
+</SessionProvider>
+```
+
+---
+
+## 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`.
+
+### Imperative (recommended)
+
+Open it from any click handler; it mounts into `<body>` and unmounts on close:
+
+```tsx
+import { openAccountSettings } from "ab-ecosystem-sso";
+
+<button onClick={() => openAccountSettings({
+  projectId: "your-project-id",
+  token,
+  apiBaseUrl: "https://your-api",
+  initialSection: "plans",     // optional
+  onLogout: () => { localStorage.clear(); navigate("/login"); },
+})}>
+  Settings
+</button>
+```
+
+`openAccountSettings(options)` returns `{ close() }` to dismiss it programmatically.
+
+### Declarative
+
+```tsx
+import { AccountSettings } from "ab-ecosystem-sso";
+
+const [open, setOpen] = useState(false);
+
+<AccountSettings
+  open={open}
+  onOpenChange={setOpen}
+  projectId="your-project-id"
+  token={token}
+  apiBaseUrl="https://your-api"
+  initialSection="general"
+  onLogout={() => { localStorage.clear(); navigate("/login"); }}
+/>
+```
+
+`initialSection` is one of `"general" | "account" | "billing" | "wallet" | "plans" | "credits"`.
+
+---
+
+## Logout
+
+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)
+<LogoutButton
+  projectId="your-project-id"
+  token={token}
+  apiBaseUrl="https://your-api"
+  onSuccess={() => { localStorage.clear(); navigate("/login"); }}
+/>
+
+// 2) A method to attach to any custom control (e.g. a profile-dropdown item)
+onClick={() => logout({
+  projectId: "your-project-id",
+  token,
+  apiBaseUrl: "https://your-api",
+  onSuccess: () => { localStorage.clear(); navigate("/login"); },
+})}
+
+// 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.
+
+---
+
+## Fetch the current user
+
+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 } }
+```
+
+---
+
+## Two-factor setup (standalone)
+
+For a settings page outside the modal:
+
+```tsx
+import { TwoFactorSetup } from "ab-ecosystem-sso";
+
+<TwoFactorSetup
+  projectId="your-project-id"
+  token={token}
+  apiBaseUrl="https://your-api"
+  onEnabled={() => …}
+  onDisabled={() => …}
+/>
+```
+
+---
+
+## Hooks
+
+| Hook | Returns |
+| --- | --- |
+| `useSession()` | `{ isAuthenticated, isValidating, logout }` — must be inside a `SessionProvider`. |
+| `useOptionalSession()` | Same, or `null` when there is no provider. |
+| `useAuthConfig()` | The project's auth-config (captcha, branding, card layout). |
+
+---
+
+## 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:
+
+```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;
+}
+```
+
+Styles are dark-mode/theme aware and scoped to the components, so they won't affect the rest of your app.
+
+---
+
+## TypeScript
+
+Everything is fully typed. Notable exports:
+
+```ts
+import type {
+  LoginProps, SignupProps, ForgotPasswordProps, AuthClassNames,
+  AccountSettingsProps, AccountSettingsSection,
+  OpenAccountSettingsOptions, AccountSettingsHandle,
+  AuthConfig, CaptchaConfig, CardLayoutConfig,
+  LoginRequest, AuthResponse, LogoutOptions,
+} from "ab-ecosystem-sso";
+import { AuthApiError } from "ab-ecosystem-sso";
+```
+
+---
+
+## License
+
+Proprietary — © combot.ltd. Internal partner-ecosystem use.