ab-ecosystem-sso 0.1.12 → 0.1.14

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).
 
 ---
 
@@ -363,6 +400,7 @@ 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` |
@@ -381,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,