ab-ecosystem-sso 0.1.10 → 0.1.12

package/README.md

@@ -199,6 +199,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 +210,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
@@ -282,9 +300,9 @@ const subscription  = await getUserSubscription("your-project-id", token, "https
 | `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`. |
+| `getUserSubscription` | `GET /subscription` | The **raw** subscription object from the API (unmapped). |
 
-> `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.
+> `getUserProfile` and `getUserWallet` both read `/me`; `getUserWallet` just narrows the same response to the wallet balances. `getUserSubscription` returns the API response as-is (the unwrapped `data`), unlike the others which map to a friendly shape. All four throw `AccountApiError` on a non-2xx response.
 
 ---
 
@@ -344,11 +362,12 @@ 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) |
 | `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` |
+| `getUserSubscription(projectId, token, apiBaseUrl?)` | `GET /subscription` → raw subscription object |
 | `logout(options)` | `POST /auth/logout` + callbacks |
 | `logoutApi(projectId, token, apiBaseUrl?)` | `POST /auth/logout` |