ab-ecosystem-sso 0.1.11 → 0.1.13

package/README.md

@@ -13,7 +13,7 @@ Drop-in React auth & account UI for the partner-ecosystem **Auth-as-a-Service**
 
 - [Installation](#installation)
 - [Configuration basics](#configuration-basics)
-- [Auth screens](#auth-screens) — `Login` · `Signup` · `ForgotPassword`
+- [Auth screens](#auth-screens) — `Login` · `Signup` · `ForgotPassword` · `VerifyEmail`
 - [Session management](#session-management) — `SessionProvider`, enforce subscription
 - [Account Settings modal](#account-settings-modal) — `openAccountSettings` / `AccountSettings`
 - [Logout](#logout) — `logout` · `LogoutButton` · `logoutApi`
@@ -86,6 +86,8 @@ function LoginPage() {
 
 `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.
+
 ### `Signup` and `ForgotPassword`
 
 ```tsx
@@ -95,6 +97,41 @@ import { Signup, ForgotPassword } from "ab-ecosystem-sso";
 <ForgotPassword projectId="…" onBackToLogin={() => navigate("/login")} />
 ```
 
+### `VerifyEmail`
+
+The email-verification screen for a `/verify/:token` route — the link you email to new users. It shows a captcha (site key from the project's auth-config), then posts the captcha + token to `/auth/verify-email`.
+
+```tsx
+import { VerifyEmail } from "ab-ecosystem-sso";
+
+// e.g. React Router: <Route path="/verify/:token" element={<VerifyPage />} />
+function VerifyPage() {
+  const { token } = useParams();
+  return (
+    <VerifyEmail
+      projectId="your-project-id"
+      apiBaseUrl="https://your-api"
+      token={token}
+      onVerified={() => navigate("/login")}
+      onLoginClick={() => navigate("/login")}
+      onSignupClick={() => navigate("/signup")}
+      onError={(err) => console.error(err)}
+    />
+  );
+}
+```
+
+On success it calls `onVerified` (send the user to login) and shows a **Continue to sign in** button. On failure it shows a **Verification failed** card with the reason plus **Go to sign in** / **Go to sign up** buttons. Verification counts as successful only when the response is 2xx **and** `success: true`.
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `token` | `string` | The token from your route params. Falls back to the last path segment of the URL. |
+| `onVerified` | `() => void` | Fires once the email is verified. |
+| `onLoginClick` | `() => void` | Navigate to login (shown on success and failure). |
+| `onSignupClick` | `() => void` | Navigate to signup (shown on failure). |
+
+> Prefer passing `token` from your router. The URL fallback only exists so the component works on a plain `/verify/:token` page with no router wired up.
+
 ### Shared auth props
 
 | Prop | Type | Notes |
@@ -106,7 +143,7 @@ import { Signup, ForgotPassword } from "ab-ecosystem-sso";
 | `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`.
+Per-screen extras: `Login` adds `onForgotPassword` / `onSignupClick`; `Signup` adds `onLoginClick`; `ForgotPassword` adds `onBackToLogin`; `VerifyEmail` adds `token` / `onVerified` / `onLoginClick` / `onSignupClick` (and has no `onSuccess`, since no session is created).
 
 ---
 
@@ -199,6 +236,7 @@ const [open, setOpen] = useState(false);
 | `token` | `string` | Bearer token. |
 | `apiBaseUrl` | `string` | Optional API origin. |
 | `initialSection` | `"general" \| "account" \| "wallet" \| "plans" \| "credits"` | First section shown. Default `"general"`. |
+| `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"`. |
 | `data` | `Partial<AccountSettingsData>` | Override sample data (non-API mode / previews). |
 | `onLogout` | `() => void` | Sign-out action (closes the modal, then runs this). |
@@ -209,6 +247,23 @@ 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.
 
+### 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}`.
+
+- **Declarative** `<AccountSettings>`: keep it mounted (even while closed) and wire `open`/`onOpenChange` normally — on load it reads the hash and calls `onOpenChange(true)` for you.
+- **Imperative** `openAccountSettings()`: call `restoreAccountSettings()` once on app load to re-open it after a refresh:
+
+  ```tsx
+  import { restoreAccountSettings } from "ab-ecosystem-sso";
+
+  useEffect(() => {
+    restoreAccountSettings({ projectId: "your-project-id", token, apiBaseUrl: "https://your-api" });
+  }, []);
+  ```
+
+  It opens the modal (on the hash's section) only when a `#settings-*` hash is present, and returns the modal handle (or `null`).
+
 ---
 
 ## Logout
@@ -344,6 +399,8 @@ Beyond the components, these functions are exported for building custom UIs:
 
 | Function | Endpoint |
 | --- | --- |
+| `getAuthConfig(projectId, apiBaseUrl?)` | `GET /auth-config` → `AuthConfig` (captcha, branding, card layout; no token) |
+| `verifyEmailApi(projectId, { token, captchaToken }, apiBaseUrl?)` | `POST /auth/verify-email` |
 | `getUser(projectId, token, apiBaseUrl?)` | `GET /me` (raw envelope) |
 | `getUserProfile(projectId, token, apiBaseUrl?)` | `GET /me` → `MappedProfile` |
 | `getUserWallet(projectId, token, apiBaseUrl?)` | `GET /me` → `UserWallets` |
@@ -362,7 +419,7 @@ Everything is fully typed. Notable exports:
 
 ```ts
 import type {
-  LoginProps, SignupProps, ForgotPasswordProps, AuthClassNames,
+  LoginProps, SignupProps, ForgotPasswordProps, VerifyEmailProps, AuthClassNames,
   AccountSettingsProps, AccountSettingsSection, AccountSettingsData, ProfileFormValues,
   OpenAccountSettingsOptions, AccountSettingsHandle,
   AuthConfig, CaptchaConfig, CardLayoutConfig,