ab-ecosystem-sso 0.1.18 → 0.2.0

package/dist/index.d.ts

@@ -1,7 +1,214 @@
 import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
-export declare function AccountSettings({ open, onOpenChange, initialSection, syncUrlHash, data, title, projectId, token, apiBaseUrl, onSaveProfile, onUpdateWhatsApp, onChangePassword, onToggleTwoFactor, onRevokeSession, onAddFunds, onChangePlan, onLogout, }: AccountSettingsProps): JSX_2.Element | null;
+/**
+ * POST /invitations/:token/accept — joins the inviting account using an
+ * existing login. The caller's login email must match the invite. Follow it
+ * with `switchAccountApi` on the returned `account_id` to drop the user
+ * straight into the new account.
+ */
+export declare function acceptInvitationApi(projectId: string, inviteToken: string, token: string, apiBaseUrl?: string): Promise<string>;
+
+/**
+ * The invitee side of an invitation link — drop it on your
+ * `/accept-invite?token=…` route.
+ *
+ * It resolves the token first (`GET /invitations/:token`) and then renders the
+ * branch the backend asked for:
+ *
+ * - `mode: "signup"` — no login here yet, so it renders `Signup` with the
+ *   invite token and the invited address prefilled and read-only.
+ * - `mode: "accept"` — they already have a login. Given a `token` it shows the
+ *   invite details and an accept button (then switches the session onto the new
+ *   account); without one it calls `onNeedLogin` so you can route them through
+ *   your own login first.
+ *
+ * ```tsx
+ * <AcceptInvite
+ *   projectId="…"
+ *   inviteToken={new URLSearchParams(location.search).get('token') ?? ''}
+ *   token={session}
+ *   onAccepted={({ accessToken }) => accessToken && save(accessToken)}
+ *   onNeedLogin={() => navigate('/login?next=' + encodeURIComponent(location.href))}
+ * />
+ * ```
+ */
+export declare function AcceptInvite(props: AcceptInviteProps): JSX_2.Element;
+
+export declare interface AcceptInviteProps {
+    projectId: string;
+    /** The `token` query param from the invite link. */
+    inviteToken: string;
+    /**
+     * A live session token, when the invitee is already signed in here. Required
+     * for the `"accept"` branch — without it the screen asks them to sign in
+     * first (see {@link onNeedLogin}).
+     */
+    token?: string;
+    /**
+     * After accepting with an existing login, switch the session onto the joined
+     * account straight away (that's `/auth/switch-account`, which returns a fresh
+     * token). Defaults to `true`.
+     */
+    switchOnAccept?: boolean;
+    /**
+     * Called once the invitation has been accepted. `accessToken` is present when
+     * the session was switched onto the new account — store it in place of the
+     * old token.
+     */
+    onAccepted?: (result: {
+        accountId: string;
+        accessToken?: string;
+    }) => void;
+    /**
+     * Called when the invite needs an existing login and none was given — send
+     * the user to your login route, then come back here with `token` set.
+     */
+    onNeedLogin?: (invitation: InvitationLookup) => void;
+    /** Forwarded to the embedded `Signup` on the "signup" branch. */
+    onSuccess?: (data: unknown) => void;
+    onError?: (error: Error) => void;
+    /** Forwarded to the embedded `Signup` on the "signup" branch. */
+    countries?: CountryOption[];
+    classNames?: AuthClassNames;
+    mode?: AuthMode;
+    config?: AuthConfig;
+    apiBaseUrl?: string;
+    /** Persist the token issued when the session switches onto the joined account. Default `true`. */
+    persistToken?: boolean;
+    tokenStorageKey?: string;
+}
+
+/** `{ data: { accessToken } }` from select-account / switch-account. */
+export declare interface AccessTokenResponse {
+    success?: boolean;
+    message?: string;
+    data?: {
+        accessToken?: string;
+        [key: string]: unknown;
+    };
+}
+
+/**
+ * One account the user can sign in to, as returned by the login picker and by
+ * `GET /accounts` (both are built by the same backend helper, so the two lists
+ * can't disagree).
+ */
+export declare interface AccountOption {
+    account_id: string;
+    name: string;
+    /** True for the user's own account; owners also get the roles/members admin. */
+    is_owner: boolean;
+    /** Role title, or null for an owner / a member with no role. */
+    role: string | null;
+    /** ISO date the member's access lapses, or null for no expiry. */
+    access_expiry: string | null;
+}
+
+/**
+ * Lets a user pick which account to open. It serves both halves of the
+ * multi-account flow:
+ *
+ * **After login** — pass the `selectionTicket` + `accounts` from a response
+ * that came back with `accountSelectionRequired`. Picking exchanges the ticket
+ * for a session token. (`Login` renders this step itself, so you only need
+ * this when you handle the branch in your own `onSuccess`.)
+ *
+ * ```tsx
+ * <AccountPicker
+ *   projectId="…"
+ *   selectionTicket={res.selectionTicket}
+ *   accounts={res.accounts}
+ *   onSelect={({ accessToken }) => save(accessToken)}
+ * />
+ * ```
+ *
+ * **On a live session** — pass `token` instead. The list comes from
+ * `GET /accounts` and picking switches the session, handing you a fresh token
+ * to store in place of the old one.
+ *
+ * ```tsx
+ * <AccountPicker projectId="…" token={token} variant="list"
+ *   currentAccountId={accountId}
+ *   onSelect={({ accessToken }) => save(accessToken)} />
+ * ```
+ */
+export declare function AccountPicker(props: AccountPickerProps): JSX_2.Element;
+
+export declare interface AccountPickerProps {
+    projectId: string;
+    /**
+     * Ticket mode (straight after login). The `selectionTicket` from a login or
+     * verify-2fa response that came back with `accountSelectionRequired`, plus
+     * the `accounts` it listed. Picking one exchanges the ticket for a session
+     * token via `/auth/select-account`.
+     *
+     * The ticket lives **five minutes**; after that the user has to log in again.
+     */
+    selectionTicket?: string;
+    /** The accounts to choose from. In session mode they're fetched instead. */
+    accounts?: AccountOption[];
+    /**
+     * Session mode (account switcher). A live session token: the list is loaded
+     * from `GET /accounts` and picking calls `/auth/switch-account`, which issues
+     * a **fresh token** — store it in place of the old one. The previous token
+     * stays valid until it expires or is logged out.
+     */
+    token?: string;
+    /** Recorded on the session by select-account, e.g. "webapp". */
+    client?: string;
+    /** "card" (default) renders the full auth card; "list" renders just the list. */
+    variant?: 'card' | 'list';
+    /** Card heading. Defaults to "Choose an account". */
+    title?: string;
+    /** Card subheading. */
+    description?: string;
+    /** Highlights the account the session is already on (session mode). */
+    currentAccountId?: string;
+    /** Called with the new token once an account has been chosen. */
+    onSelect?: (result: {
+        accessToken: string;
+        account: AccountOption;
+    }) => void;
+    onError?: (error: Error) => void;
+    /** Renders a secondary action under the list (e.g. "Back to sign in"). */
+    onCancel?: () => void;
+    cancelLabel?: string;
+    classNames?: AuthClassNames;
+    mode?: AuthMode;
+    config?: AuthConfig;
+    apiBaseUrl?: string;
+    /**
+     * Persist the issued token. Default `true` — important here, since
+     * switch-account returns a *fresh* token that has to replace the old one.
+     */
+    persistToken?: boolean;
+    tokenStorageKey?: string;
+}
+
+export declare function AccountSettings({ open, onOpenChange, initialSection, customComponents, syncUrlHash, data, title, mode, isOwner, inviteLinkBase, onAccountSwitch, currentAccountId, projectId, token: tokenProp, apiBaseUrl, onSaveProfile, onUpdateWhatsApp, onChangePassword, onToggleTwoFactor, onRevokeSession, onAddFunds, onChangePlan, onLogout, }: AccountSettingsProps): JSX_2.Element | null;
+
+/** Where a custom panel's trigger appears in the modal chrome. */
+export declare type AccountSettingsCustomLocation = 'sidebar' | 'sidebar-bottom' | 'header';
+
+/**
+ * A host-supplied panel added to the Account Settings modal. Its trigger appears
+ * in the sidebar (as a nav item), pinned to the bottom of the sidebar, or in the
+ * header next to the close button; activating it renders `component` in the modal
+ * body in place of the built-in sections.
+ */
+export declare interface AccountSettingsCustomPanel {
+    /** Stable id — used to track which panel is active. Must be unique. */
+    id: string;
+    /** Trigger placement. Defaults to "sidebar". */
+    location?: AccountSettingsCustomLocation;
+    /** Trigger text (sidebar label / header button tooltip + aria-label). */
+    label: string;
+    /** Optional trigger icon (an inline SVG or any node). */
+    icon?: ReactNode;
+    /** Rendered in the modal body when this panel is active. */
+    component: ReactNode;
+}
 
 export declare interface AccountSettingsData {
     user: {
@@ -85,6 +292,12 @@ export declare interface AccountSettingsProps {
     onOpenChange: (open: boolean) => void;
     /** Section to show first. Defaults to "general". */
     initialSection?: AccountSettingsSection;
+    /**
+     * Host-supplied panels added to the modal. Each renders a trigger in the
+     * sidebar, sidebar bottom, or header, and shows its `component` in the body
+     * when activated. See {@link AccountSettingsCustomPanel}.
+     */
+    customComponents?: AccountSettingsCustomPanel[];
     /**
      * Sync the open state + active section to the URL hash as `#settings-<section>`,
      * so a page refresh re-opens the modal on the same section. The hash is cleared
@@ -95,9 +308,35 @@ export declare interface AccountSettingsProps {
     data?: Partial<AccountSettingsData>;
     /** Modal heading shown above the nav. Defaults to "Settings". */
     title?: string;
+    /** Colour scheme — `"light"` (default) or `"dark"`. */
+    mode?: AuthMode;
+    /**
+     * Show the owner-only Members / Roles / Invitations sections. Those endpoints
+     * are owner-only and answer a non-owner with "Only the account owner can do
+     * this", which the sections display — so the default is to show the tabs and
+     * let the API be the authority. Pass `false` to hide them outright.
+     */
+    isOwner?: boolean;
+    /**
+     * Where invite links point; the token is appended as `?token=…`. Defaults to
+     * `<your origin>/accept-invite`. Build that route with `AcceptInvite`.
+     */
+    inviteLinkBase?: string;
+    /**
+     * Enables the **Accounts** section (the account switcher). Called with a
+     * fresh token after `/auth/switch-account` — store it in place of the old
+     * one. Without this prop the switcher is hidden, since there'd be nowhere to
+     * put the new token.
+     */
+    onAccountSwitch?: (result: {
+        accessToken: string;
+        accountId: string;
+    }) => void;
+    /** The account the session is currently on — marked "Current" in the switcher. */
+    currentAccountId?: string;
     /** When provided (with token), the component loads/saves via the live API instead of sample data. */
     projectId?: string;
-    /** Bearer token for API calls. */
+    /** Bearer token for API calls. Omit to use the one stored at login. */
     token?: string;
     /** API base URL override (defaults to VITE_AUTH_API_BASE_URL). */
     apiBaseUrl?: string;
@@ -121,11 +360,17 @@ export declare interface AccountSettingsProps {
     onLogout?: () => void;
 }
 
-export declare type AccountSettingsSection = 'general' | 'account' | 'billing' | 'wallet' | 'plans' | 'credits';
+export declare type AccountSettingsSection = 'general' | 'account' | 'billing' | 'wallet' | 'plans' | 'credits'
+/** Account switcher — only shown when `onAccountSwitch` is given. */
+| 'accounts'
+/** Owner-only team administration. */
+| 'members' | 'roles' | 'invitations';
 
 export declare class AuthApiError extends Error {
     code: string | undefined;
-    constructor(code: string | undefined, fallbackMessage: string);
+    /** HTTP status, when the caller had one to hand (select/switch answer 401). */
+    status: number | undefined;
+    constructor(code: string | undefined, fallbackMessage: string, status?: number);
 }
 
 /** CSS class overrides for all auth component sub-elements */
@@ -157,6 +402,18 @@ export declare interface AuthComponentBaseProps {
     onError?: (error: Error) => void;
     /** API base URL override */
     apiBaseUrl?: string;
+    /** Colour scheme — `"light"` (default) or `"dark"`. */
+    mode?: AuthMode;
+    /**
+     * Persist the issued session token so the rest of the package (and your own
+     * calls, via `getAuthHeader`) can use it without being handed one. Default
+     * `true`. Set `false` to keep handling the token entirely yourself.
+     *
+     * Configure the key/storage globally with `configureTokenStorage()`.
+     */
+    persistToken?: boolean;
+    /** Storage key override for this component. Default `"ab-sso:accessToken"`. */
+    tokenStorageKey?: string;
 }
 
 export declare interface AuthConfig {
@@ -178,6 +435,54 @@ export declare interface AuthErrorResponse {
     errors?: Record<string, string[]>;
 }
 
+/**
+ * `fetch` with the session token attached and 401 handling wired in.
+ *
+ * ```ts
+ * const res = await authFetch("/api/orders");
+ * ```
+ *
+ * An `Authorization` header you set yourself is never overwritten. Everything
+ * else behaves exactly like `fetch`, including the returned unread body.
+ */
+export declare function authFetch(input: RequestInfo | URL, init?: AuthFetchInit): Promise<Response>;
+
+export declare interface AuthFetchInit extends RequestInit {
+    /** Token override; defaults to the stored session token. */
+    token?: string;
+}
+
+export declare interface AuthHandlers {
+    /**
+     * The session is no longer valid (401, and not the account-access case) —
+     * send the user to login.
+     */
+    onUnauthorized?: (info: UnauthorizedInfo) => void;
+    /**
+     * Access to *this account* was revoked or expired (`A403`). The login is
+     * still good: show the account picker rather than logging out.
+     */
+    onAccountAccessLost?: (info: UnauthorizedInfo) => void;
+}
+
+export declare interface AuthInterceptorOptions extends AuthHandlers {
+    /**
+     * **Required.** Origins allowed to receive the token — your own API hosts.
+     * `"self"` means the page's own origin (covers relative URLs like
+     * `/api/...`). There is no wildcard: anything not listed is left untouched,
+     * which is what keeps the token away from third-party scripts.
+     */
+    origins: string[];
+}
+
+/**
+ * Colour scheme for a rendered component. Defaults to `"light"`.
+ *
+ * Each component root carries `data-aas-theme`, so modes are per-component —
+ * a dark login card and a light settings modal can coexist on one page.
+ */
+export declare type AuthMode = 'light' | 'dark';
+
 export declare function AuthProvider({ projectId, config: externalConfig, apiBaseUrl, children, }: AuthProviderProps): JSX_2.Element;
 
 declare interface AuthProviderProps {
@@ -188,11 +493,34 @@ declare interface AuthProviderProps {
     children: ReactNode;
 }
 
+/**
+ * Response of `/auth/login` and `/auth/verify-2fa`.
+ *
+ * It has **three** branches, which must be checked in this order:
+ *  1. `twoFactorRequired` — collect an OTP and call `/auth/verify-2fa`.
+ *  2. `accountSelectionRequired` — the user belongs to more than one account;
+ *     there is no token yet. Let them pick from `accounts`, then exchange
+ *     `selectionTicket` via `/auth/select-account` (the ticket lives 5 minutes).
+ *  3. otherwise — signed in, token at `data.accessToken`.
+ */
 export declare interface AuthResponse {
+    success?: boolean;
+    message?: string;
+    /** Present on a completed login; the session token is `data.accessToken`. */
+    data?: {
+        accessToken?: string;
+        [key: string]: unknown;
+    };
     token: string;
     user: unknown;
     /** If true, the user must complete 2FA (re-sending email + password + OTP + captcha) */
     twoFactorRequired?: boolean;
+    /** If true, no token was issued — the user must choose an account first. */
+    accountSelectionRequired?: boolean;
+    /** The accounts to choose from. Only present with `accountSelectionRequired`. */
+    accounts?: AccountOption[];
+    /** Short-lived (5 min) credential for `/auth/select-account`. */
+    selectionTicket?: string;
 }
 
 export declare interface CaptchaConfig {
@@ -212,6 +540,34 @@ export declare interface CardLayoutConfig {
     signupEnabled: boolean;
 }
 
+/** Removes the stored token. Called by logout and on an invalid session. */
+export declare function clearStoredToken(options?: TokenAccessOptions): void;
+
+/**
+ * Registers what should happen when a call made through `authFetch` (or an
+ * installed interceptor) comes back unauthorized. Call it once at bootstrap.
+ */
+export declare function configureAuthHandlers(next: AuthHandlers): void;
+
+/**
+ * Remaps any of the paths, for apps whose routes differ (`/sign-in` instead of
+ * `/login`, say). Call it once at bootstrap — `SessionProvider` and
+ * `SsoAuthRoutes` both read the result.
+ */
+export declare function configureSsoRoutes(overrides: Partial<SsoRoutePaths>): void;
+
+/**
+ * Overrides how the token is stored, for the whole package. Call it once
+ * before rendering (e.g. next to your app's bootstrap).
+ *
+ * ```ts
+ * configureTokenStorage({ key: 'authToken' });           // match an existing app
+ * configureTokenStorage({ storage: 'sessionStorage' });  // per-tab only
+ * configureTokenStorage({ enabled: false });             // opt out entirely
+ * ```
+ */
+export declare function configureTokenStorage(options: Partial<TokenStorageConfig>): void;
+
 /** A country option for the signup country dropdown. */
 export declare interface CountryOption {
     /** ISO 3166-1 alpha-2 country code, e.g. "US". */
@@ -219,6 +575,47 @@ export declare interface CountryOption {
     name: string;
 }
 
+/**
+ * The one and only time the invite `token` is returned — it never appears in
+ * the list. Build the link yourself as
+ * `{your-frontend}/accept-invite?token={token}`; **no email is sent.**
+ */
+export declare interface CreatedInvite {
+    id: string;
+    email: string;
+    token: string;
+    /** Link expiry — 72 hours out. */
+    expires_at?: string;
+}
+
+export declare function createInvitationApi(projectId: string, payload: CreateInvitePayload, token?: string, apiBaseUrl?: string): Promise<CreatedInvite>;
+
+export declare interface CreateInvitePayload {
+    email: string;
+    /** "member" (default) or "user". */
+    type?: 'member' | 'user';
+    /** Role id, or null/omitted for no permissions. */
+    role?: string | null;
+    /** Future ISO date, or null/omitted for no expiry. */
+    access_expiry?: string | null;
+}
+
+export declare function createRoleApi(projectId: string, payload: CreateRolePayload, token?: string, apiBaseUrl?: string): Promise<{
+    id: string;
+}>;
+
+export declare interface CreateRolePayload {
+    title: string;
+    description?: string;
+    /**
+     * Permission strings. The server trims, uppercases, dedupes and sorts them,
+     * so "billing.view", "BILLING.VIEW" and " user.list " are stored as
+     * BILLING.VIEW + USER.LIST. Max 200 after dedupe. They are not validated
+     * against a catalogue yet — an unknown string simply grants nothing.
+     */
+    permission?: string[];
+}
+
 export declare interface CreditWallet {
     id: string;
     label: string;
@@ -234,6 +631,15 @@ export declare interface CreditWallet {
     rechargeable: boolean;
 }
 
+/** The defaults. `inviteLinkBase` and the backend's email links assume these. */
+export declare const DEFAULT_SSO_ROUTES: SsoRoutePaths;
+
+/**
+ * Refused while the role is still assigned, with
+ * "This role is assigned to N members. Reassign them first."
+ */
+export declare function deleteRoleApi(projectId: string, roleId: string, token?: string, apiBaseUrl?: string): Promise<unknown>;
+
 declare function fetchAuthConfig(projectId: string, apiBaseUrl?: string): Promise<AuthConfig>;
 export { fetchAuthConfig }
 export { fetchAuthConfig as getAuthConfig }
@@ -257,6 +663,16 @@ export declare interface ForgotPasswordRequest {
     captchaToken?: string;
 }
 
+/**
+ * `Authorization` header for the given token, falling back to the stored one.
+ * Returns an empty object when there is no token, so it's safe to spread.
+ *
+ * ```ts
+ * fetch(url, { headers: { ...getAuthHeader(), 'Content-Type': 'application/json' } });
+ * ```
+ */
+export declare function getAuthHeader(token?: string): Record<string, string>;
+
 /**
  * GET /currency — the currencies enabled for the project (shown in signup).
  * Response envelope: `{ success, data: [{ name, code }] }`. No token required.
@@ -264,44 +680,161 @@ export declare interface ForgotPasswordRequest {
  */
 export declare function getCurrenciesApi(projectId: string, apiBaseUrl?: string): Promise<ProjectCurrency[]>;
 
+/**
+ * GET /invitations/:token — resolves an invite link. No auth. Call it before
+ * rendering anything so you know whether to collect a password (`mode:
+ * "signup"`) or just have them accept (`mode: "accept"`).
+ */
+export declare function getInvitationApi(projectId: string, inviteToken: string, apiBaseUrl?: string): Promise<InvitationLookup>;
+
+/** The paths currently in effect. */
+export declare function getSsoRoutes(): SsoRoutePaths;
+
+/**
+ * The stored session token, or `""` when there is none (not signed in, storage
+ * disabled, or persistence turned off).
+ */
+export declare function getStoredToken(options?: TokenAccessOptions): string;
+
+/** The storage settings currently in effect. */
+export declare function getTokenStorageConfig(): TokenStorageConfig;
+
 /**
  * Fetches the current user from GET /api/v1/projects/:projectId/me.
  * Returns the raw response envelope, e.g.
  *   { success, data: { id, username, profile: { name, email, address, ... }, mainWallet, coinWallet } }
  * Throws AuthApiError on a non-2xx response.
  */
-export declare function getUser(projectId: string, token: string, apiBaseUrl?: string): Promise<Record<string, unknown>>;
+export declare function getUser(projectId: string, token?: string, apiBaseUrl?: string): Promise<Record<string, unknown>>;
 
 /**
  * GET /credit-wallets → the user's credit wallets (mapped CreditWallet[]).
  * Alias of `getCreditWalletsApi` with a consumer-friendly name.
  */
-export declare function getUserCreditWallet(projectId: string, token: string, apiBaseUrl?: string): Promise<CreditWallet[]>;
+export declare function getUserCreditWallet(projectId: string, token?: string, apiBaseUrl?: string): Promise<CreditWallet[]>;
 
 /**
  * GET /me → the user's profile as flat, display-ready fields (MappedProfile).
  * Includes name, email/username, address, phone, language and wallet summaries.
  */
-export declare function getUserProfile(projectId: string, token: string, apiBaseUrl?: string): Promise<MappedProfile>;
+export declare function getUserProfile(projectId: string, token?: string, apiBaseUrl?: string): Promise<MappedProfile>;
 
 /**
  * GET /subscription → the user's active subscription, as returned by the API
  * (unmodified). `request()` unwraps the `{ success, data }` envelope, so this
  * resolves to the raw subscription `data` object.
  */
-export declare function getUserSubscription(projectId: string, token: string, apiBaseUrl?: string): Promise<unknown>;
+export declare function getUserSubscription(projectId: string, token?: string, apiBaseUrl?: string): Promise<unknown>;
 
 /**
  * GET /me → just the wallet balances ({ mainWallet, coinWallet }).
  * A convenience over `getUserProfile` when you only need the balances.
  */
-export declare function getUserWallet(projectId: string, token: string, apiBaseUrl?: string): Promise<UserWallets>;
+export declare function getUserWallet(projectId: string, token?: string, apiBaseUrl?: string): Promise<UserWallets>;
+
+/**
+ * Attaches the session token to requests your app makes to the listed origins,
+ * by patching `fetch` and `XMLHttpRequest`.
+ *
+ * Prefer `getAuthHeader()` or `authFetch()` — this exists for apps with too
+ * many call sites to touch. The allowlist is mandatory precisely because a
+ * blanket patch would hand your bearer token to every third-party endpoint the
+ * page talks to.
+ *
+ * ```ts
+ * const stop = installAuthInterceptor({
+ *   origins: ["self", "https://api.example.com"],
+ *   onUnauthorized: () => navigate("/login"),
+ *   onAccountAccessLost: () => showAccountPicker(),
+ * });
+ * ```
+ *
+ * Returns a function that restores the originals. Calling it twice is a no-op:
+ * the second install replaces the first.
+ */
+export declare function installAuthInterceptor(options: AuthInterceptorOptions): () => void;
+
+export declare interface Invitation {
+    id: string;
+    email: string;
+    type?: 'member' | 'user' | string;
+    role?: {
+        id: string;
+        title: string;
+    } | null;
+    access_expiry?: string | null;
+    status?: InvitationStatus | string;
+    /** When the invite link stops working (72 hours after creation). */
+    invite_expires_at?: string;
+    created_at?: string;
+}
+
+/**
+ * `GET /invitations/:token` — what an invite link resolves to. Call this before
+ * rendering anything, and branch on `mode`:
+ *   "signup" → collect a password and POST `/auth/signup` with `inviteToken`.
+ *   "accept" → the person already has a login here; sign them in, then POST
+ *              `/invitations/:token/accept`.
+ */
+export declare interface InvitationLookup {
+    /** The invited address. Render it read-only — a different one is ignored/rejected. */
+    email: string;
+    /** Display name of the account owner who sent the invite. */
+    invited_by: string;
+    /** Role title they'll be given, or null for no permissions. */
+    role: string | null;
+    access_expiry: string | null;
+    mode: 'signup' | 'accept';
+}
+
+export declare function InvitationsSection({ projectId, token, apiBaseUrl, inviteLinkBase }: InvitationsSectionProps): JSX_2.Element;
+
+export declare interface InvitationsSectionProps extends TeamSectionProps {
+    /**
+     * Where invite links point. The token is appended as `?token=…`.
+     * Defaults to `<your origin>/accept-invite`.
+     */
+    inviteLinkBase?: string;
+}
+
+/** Invite status as reported by the API. A lapsed pending invite reports "expired" immediately. */
+export declare type InvitationStatus = 'pending' | 'accepted' | 'expired' | 'revoked';
+
+/**
+ * True when an error means "this account is no longer reachable" — revoked or
+ * expired member access, a disabled account, or an account that doesn't belong
+ * to this product. The backend answers 401 with code `A403`.
+ *
+ * Treat it as "send the user back to the account picker", **not** as a logout:
+ * their login is intact and their other accounts still work.
+ */
+export declare function isAccountAccessError(error: unknown): boolean;
+
+/**
+ * GET /accounts — every account the caller can reach, for an account switcher.
+ * Built by the same backend helper as the login picker, so the two agree.
+ */
+export declare function listAccountsApi(projectId: string, token: string, apiBaseUrl?: string): Promise<AccountOption[]>;
+
+declare type Listener = (token: string) => void;
+
+export declare function listInvitationsApi(projectId: string, token?: string, status?: InvitationStatus, apiBaseUrl?: string): Promise<Invitation[]>;
+
+/** Defaults to active members; pass "revoked" to list revoked ones. */
+export declare function listMembersApi(projectId: string, token?: string, status?: MemberStatus, apiBaseUrl?: string): Promise<Member[]>;
+
+export declare function listRolesApi(projectId: string, token?: string, apiBaseUrl?: string): Promise<Role[]>;
 
 export declare function Login(props: LoginProps): JSX_2.Element;
 
 export declare interface LoginProps extends AuthComponentBaseProps {
     onForgotPassword?: () => void;
     onSignupClick?: () => void;
+    /**
+     * Client identifier recorded on the session when the user picks an account
+     * (sent as `client` to `/auth/select-account`), e.g. `"webapp"`.
+     */
+    client?: string;
 }
 
 export declare interface LoginRequest {
@@ -325,11 +858,13 @@ export declare function logout(options: LogoutOptions): Promise<void>;
 
 export declare function logoutApi(projectId: string, token: string, apiBaseUrl?: string): Promise<void>;
 
-export declare function LogoutButton({ className, children, projectId, token, apiBaseUrl, onSuccess, onError, }: LogoutButtonProps): JSX_2.Element;
+export declare function LogoutButton({ className, children, mode, projectId, token, apiBaseUrl, onSuccess, onError, }: LogoutButtonProps): JSX_2.Element;
 
 declare interface LogoutButtonProps {
     className?: string;
     children?: React.ReactNode;
+    /** Colour scheme — "light" (default) or "dark". */
+    mode?: AuthMode;
     /**
      * Standalone mode: when `projectId` + `token` are supplied the button calls
      * POST /api/v1/projects/:projectId/auth/logout directly (no SessionProvider
@@ -346,7 +881,8 @@ declare interface LogoutButtonProps {
 
 export declare interface LogoutOptions {
     projectId: string;
-    token: string;
+    /** Omit to use the stored session token. */
+    token?: string;
     apiBaseUrl?: string;
     /** Called after the logout request completes — clear local state / redirect here. */
     onSuccess?: () => void;
@@ -393,6 +929,51 @@ export declare interface MappedSubscription {
     packageCounts: Record<string, number>;
 }
 
+/**
+ * Resolves a pathname to one of the auth screens, or null when it's not ours.
+ *
+ * Matching is prefix-based for the token-bearing routes, so both
+ * `/verify/<token>` and `/reset-password?token=<token>` work, and exact for the
+ * rest — `/login` must not swallow the host's `/login-help`.
+ */
+export declare function matchSsoRoute(pathname: string, search?: string, options?: {
+    basePath?: string;
+    routes?: Partial<SsoRoutePaths>;
+}): SsoRouteMatch | null;
+
+export declare interface Member {
+    /** Membership id — this is what update/revoke take. */
+    id: string;
+    /** The person's login profile id (not the membership). */
+    user_id?: string;
+    name?: string;
+    email?: string;
+    type?: 'member' | 'user' | string;
+    role?: {
+        id: string;
+        title: string;
+    } | null;
+    access_expiry?: string | null;
+    expired?: boolean;
+    status?: MemberStatus | string;
+    joined_at?: string;
+    revoked_at?: string | null;
+}
+
+export declare function MembersSection({ projectId, token, apiBaseUrl }: TeamSectionProps): JSX_2.Element;
+
+export declare type MemberStatus = 'active' | 'revoked';
+
+/**
+ * Subscribes to token changes made through this module (login, switch-account,
+ * logout, …). Returns an unsubscribe function.
+ *
+ * This fires for changes made *in this tab*. It deliberately does not listen to
+ * the cross-tab `storage` event — syncing sessions between tabs is a host
+ * decision, not something a component library should impose.
+ */
+export declare function onStoredTokenChange(listener: Listener): () => void;
+
 /**
  * Imperatively open the Account Settings modal from anywhere — e.g. a button
  * or menu item's onClick. Mounts the modal into a detached container appended
@@ -441,6 +1022,9 @@ export declare interface ProjectCurrency {
     code: string;
 }
 
+/** Reads `accessToken` out of any of the envelope shapes the auth endpoints return. */
+export declare function readAccessTokenFrom(response: unknown): string;
+
 /**
  * POST /auth/reset-password — sets a new password using the reset token from the
  * emailed link. Body: { token, password, captchaToken }.
@@ -470,20 +1054,80 @@ export declare interface ResetPasswordRequest {
  */
 export declare function restoreAccountSettings(options?: OpenAccountSettingsOptions): AccountSettingsHandle | null;
 
+/** Only works on a *pending* invite — revoking an accepted one is a member operation. */
+export declare function revokeInvitationApi(projectId: string, inviteId: string, token?: string, apiBaseUrl?: string): Promise<unknown>;
+
+/**
+ * Revokes this account's access for the member. Their login is untouched — only
+ * this account becomes unreachable and it disappears from their picker, on
+ * their next request rather than when their token expires. Re-inviting the same
+ * person reactivates the existing row.
+ */
+export declare function revokeMemberApi(projectId: string, memberId: string, token?: string, apiBaseUrl?: string): Promise<unknown>;
+
+/** A role as returned by `GET /account/roles`. */
+export declare interface Role {
+    id: string;
+    title: string;
+    description?: string;
+    /** Permission strings, stored uppercased + deduped + sorted by the server. */
+    permission: string[];
+    /** Platform-provided role: assignable, but not editable or deletable. */
+    is_system?: boolean;
+    /** Live count of members holding this role — use it to warn before deleting. */
+    members?: number;
+}
+
+export declare function RolesSection({ projectId, token, apiBaseUrl }: TeamSectionProps): JSX_2.Element;
+
+/**
+ * POST /auth/select-account — exchanges a login `selectionTicket` for a session
+ * token on the chosen account.
+ *
+ * Unauthenticated: the ticket *is* the credential, and it expires after five
+ * minutes (then the user has to log in again). Pass the caller's own
+ * `account_id` to enter their own account.
+ */
+export declare function selectAccountApi(projectId: string, data: SelectAccountRequest, apiBaseUrl?: string): Promise<string>;
+
+/** Body of `POST /auth/select-account` — unauthenticated; the ticket is the credential. */
+export declare interface SelectAccountRequest {
+    selection_ticket: string;
+    account_id: string;
+    /** Free-form client identifier recorded on the session, e.g. "webapp". */
+    client?: string;
+}
+
 declare interface SessionContextValue {
     isAuthenticated: boolean;
     isValidating: boolean;
     logout: () => Promise<void>;
+    /**
+     * Set when the session was rejected because *this account* is no longer
+     * reachable (member access revoked or expired, account disabled) — the login
+     * itself is still valid. Null in every other state.
+     */
+    accountAccessLost: {
+        message?: string;
+        code?: string;
+    } | null;
 }
 
-export declare function SessionProvider({ projectId, token, onSessionInvalid, apiBaseUrl, enforceActiveSubscription, children, }: SessionProviderProps): JSX_2.Element;
+export declare function SessionProvider({ projectId, token: tokenProp, onSessionInvalid: onSessionInvalidProp, apiBaseUrl, enforceActiveSubscription, onAccountAccessLost, onTokenChange, mode, children, }: SessionProviderProps): JSX_2.Element;
 
 declare interface SessionProviderProps {
     projectId: string;
-    /** The auth token (from login response) — typically stored in localStorage by the consumer */
-    token: string | null;
-    /** Called when session is invalid or user logs out — navigate to login page here */
-    onSessionInvalid: () => void;
+    /**
+     * The session token. **Omit it** to use the token the package stored at
+     * login; pass `null` to state explicitly that there is no session.
+     */
+    token?: string | null;
+    /**
+     * Called when the session is invalid or the user logged out — navigate to
+     * your login route here. Optional: with no handler the provider sends the
+     * browser to the package's login route (see `SSO_ROUTES`).
+     */
+    onSessionInvalid?: () => void;
     apiBaseUrl?: string;
     /**
      * When true, after the session validates we fetch the user's subscription; if
@@ -491,9 +1135,50 @@ declare interface SessionProviderProps {
      * so they can subscribe. The modal stays open but the user can still close it.
      */
     enforceActiveSubscription?: boolean;
+    /**
+     * Called when the session is rejected with `A403` — the member's access to
+     * **this** account was revoked or expired, or the account was disabled. Their
+     * login is intact and their other accounts still work, so this is not a
+     * logout: send them back to the account picker.
+     *
+     * Leave it unset to let the provider render the picker itself (see
+     * {@link onTokenChange}).
+     */
+    onAccountAccessLost?: (info: {
+        message?: string;
+        code?: string;
+    }) => void;
+    /**
+     * Called with a fresh token when the user switches account from the
+     * built-in picker. Store it in place of the old one — without this the
+     * provider has nowhere to hand the new session, so it falls back to
+     * `onSessionInvalid`.
+     */
+    onTokenChange?: (token: string) => void;
+    /** Colour scheme for the built-in picker — "light" (default) or "dark". */
+    mode?: AuthMode;
     children: ReactNode;
 }
 
+/** Outcome of {@link validateSession}. */
+export declare interface SessionValidation {
+    valid: boolean;
+    /**
+     * The session failed *because this account is no longer reachable* (member
+     * access revoked or expired, account disabled). The login itself is still
+     * good, so the user should be sent back to the account picker rather than
+     * logged out. See `isAccountAccessError`.
+     */
+    accountAccessLost: boolean;
+    /** Backend message, when it sent one. */
+    message?: string;
+    /** Backend error code — `A403` for the revoked/expired case. */
+    code?: string;
+}
+
+/** Writes the token. A falsy token clears it, so this is safe to call blindly. */
+export declare function setStoredToken(token: string, options?: TokenAccessOptions): void;
+
 /** Every section that can appear in the hash. Order is not significant. */
 export declare const SETTINGS_SECTIONS: AccountSettingsSection[];
 
@@ -501,6 +1186,21 @@ export declare function Signup(props: SignupProps): JSX_2.Element;
 
 export declare interface SignupProps extends AuthComponentBaseProps {
     onLoginClick?: () => void;
+    /**
+     * Invitation token from an invite link. Sent as `inviteToken`, which lets the
+     * signup through even when the project has signups disabled and creates the
+     * account already verified and active (no verification email).
+     *
+     * `AcceptInvite` sets this for you; pass it yourself only if you're building
+     * the invite screen by hand.
+     */
+    inviteToken?: string;
+    /**
+     * The invited address, from `GET /invitations/:token`. Prefills the email
+     * field and makes it read-only — the server takes the address from the
+     * invite record regardless of what's posted.
+     */
+    inviteEmail?: string;
     /**
      * Custom country list for the country dropdown. When provided it replaces the
      * built-in list; each entry must be `{ code, name }`. Falls back to the
@@ -515,18 +1215,238 @@ export declare interface SignupRequest {
     email: string;
     password: string;
     phoneNumber?: string;
+    /** Country calling code without the `+`, e.g. "91". */
+    dialCode?: string;
     country?: string;
     currency?: string;
     captchaToken?: string;
+    /**
+     * Invitation token, when the user is signing up from an invite link. The
+     * server then takes the email from the invite record and **ignores** the
+     * `email` field here; signup is also allowed even when the project has
+     * signups disabled, and the account is created already verified.
+     */
+    inviteToken?: string;
+}
+
+/**
+ * Renders a single auth screen, wired up for routing: sibling links navigate,
+ * and a successful sign-in stores the token and leaves for `redirectTo`.
+ *
+ * Built for file-based routing — one tiny file per route:
+ *
+ * ```tsx
+ * // app/login/page.tsx
+ * export default () => <SsoAuthPage screen="login" projectId="…" />;
+ * ```
+ */
+export declare function SsoAuthPage({ screen, routeToken, ...props }: SsoAuthPageProps): JSX_2.Element;
+
+export declare interface SsoAuthPageProps extends SsoScreenProps {
+    /** Which screen to render. */
+    screen: SsoScreen;
+    /**
+     * Token from the URL for the reset / verify / invite screens. Pass it when
+     * your router already parsed it (Next's `params`/`searchParams`); omitted,
+     * it's read from `window.location`.
+     */
+    routeToken?: string;
+}
+
+/**
+ * Mounts every auth route without needing a router: it matches
+ * `window.location.pathname` itself and renders the right screen, or
+ * `fallback` when the path isn't one of ours.
+ *
+ * ```tsx
+ * <SsoAuthRoutes projectId="…" redirectTo="/dashboard" fallback={<App />} />
+ * ```
+ *
+ * If you *do* have a router, prefer `ssoRoutes()` so the screens live inside
+ * your layouts and guards.
+ */
+export declare function SsoAuthRoutes({ fallback, ...props }: SsoAuthRoutesProps): JSX_2.Element;
+
+export declare interface SsoAuthRoutesProps extends SsoScreenProps {
+    /** Rendered when the current path isn't one of the auth routes. Default `null`. */
+    fallback?: ReactNode;
+}
+
+/**
+ * Default navigation: a `history.pushState` plus an event so `SsoAuthRoutes`
+ * re-renders.
+ *
+ * This is right for apps with **no** router. If you have one, pass its
+ * navigate through `onNavigate` instead — react-router and friends own their
+ * own history and won't notice a pushState from outside.
+ */
+export declare function ssoNavigate(to: string): void;
+
+export declare interface SsoRouteMatch {
+    /** Which screen the path resolves to. */
+    screen: SsoScreen;
+    /** Token carried by the URL (reset / verify / invite links). */
+    token: string;
+}
+
+export declare interface SsoRouteObject {
+    /** Path, prefixed with `basePath` when one is given. */
+    path: string;
+    /** The screen, ready to mount. */
+    element: ReactNode;
+    /** Which screen this is, in case you need to wrap or reorder them. */
+    screen: SsoScreen;
+}
+
+/**
+ * The routes every app embedding this package needs.
+ *
+ * A library can't discover a host app's routes — react-router keeps no readable
+ * registry at runtime and Next's routes are filesystem/build-time — so instead
+ * of guessing, the package publishes the paths it expects and gives you two
+ * ways to satisfy them: spread `ssoRoutes()` into your own router, or mount
+ * `<SsoAuthRoutes />` and let the package match the path itself.
+ *
+ * ⚠️ Whichever you pick, **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.
+ */
+export declare interface SsoRoutePaths {
+    login: string;
+    signup: string;
+    forgotPassword: string;
+    /** Target of the emailed reset link. Token read from `?token=` or a trailing segment. */
+    resetPassword: string;
+    /** Target of the emailed verification link, e.g. `/verify/<token>`. */
+    verifyEmail: string;
+    /** Target of invite links — see `inviteLinkBase` on the settings modal. */
+    acceptInvite: string;
+}
+
+/**
+ * The auth screens as plain route objects, to spread into your own router.
+ * Shaped to drop straight into react-router:
+ *
+ * ```tsx
+ * const navigate = useNavigate();
+ * createBrowserRouter([
+ *   ...ssoRoutes({ projectId: '…', onNavigate: navigate }),
+ *   ...appRoutes,
+ * ]);
+ * ```
+ *
+ * Pass `onNavigate` so the screens move through *your* router — the default
+ * `pushState` won't re-render it. Token-bearing routes are registered with a
+ * `:token` segment as well as the bare path, since the links arrive both ways.
+ */
+export declare function ssoRoutes(options: SsoScreenProps): SsoRouteObject[];
+
+export declare type SsoScreen = 'login' | 'signup' | 'forgot-password' | 'reset-password' | 'verify-email' | 'accept-invite';
+
+export declare interface SsoScreenProps {
+    projectId: string;
+    apiBaseUrl?: string;
+    /** Pre-fetched config, to skip the internal auth-config request. */
+    config?: AuthConfig;
+    mode?: AuthMode;
+    classNames?: AuthClassNames;
+    /** Custom country list for the signup screen. */
+    countries?: CountryOption[];
+    /** Client identifier recorded on the session when an account is chosen. */
+    client?: string;
+    /** Persist the issued token. Default `true`. */
+    persistToken?: boolean;
+    tokenStorageKey?: string;
+    /**
+     * Live session token, used by the accept-invite "accept" branch. Defaults to
+     * the stored token, so an already-signed-in user can accept straight away.
+     */
+    token?: string;
+    /** Where to go after a successful sign-in. Default `"/"`; a safe `?next=` wins. */
+    redirectTo?: string;
+    /**
+     * Replaces the default post-auth behaviour (a full navigation to
+     * `redirectTo`, so the host app boots with the stored token). Use it to hook
+     * into your own router instead.
+     */
+    onAuthenticated?: (result: unknown) => void;
+    onError?: (error: Error) => void;
+    /** How to move between auth screens. Defaults to {@link ssoNavigate}. */
+    onNavigate?: (to: string) => void;
+    /** Prefix the routes are mounted under, e.g. `"/auth"`. */
+    basePath?: string;
+    /** Path overrides for this mount, on top of `configureSsoRoutes()`. */
+    routes?: Partial<SsoRoutePaths>;
 }
 
-export declare function TwoFactorSetup({ projectId, token, apiBaseUrl, className, onEnabled, onDisabled, onError, }: TwoFactorSetupProps): JSX_2.Element;
+/**
+ * POST /auth/switch-account — swaps a *live* session onto another account the
+ * user belongs to, returning a fresh token. The old token stays valid until it
+ * expires or is logged out, so replace whatever you stored with the new one.
+ */
+export declare function switchAccountApi(projectId: string, accountId: string, token: string, apiBaseUrl?: string): Promise<string>;
+
+export declare interface TeamSectionProps {
+    projectId: string;
+    /** Omit to use the stored session token. */
+    token?: string;
+    apiBaseUrl?: string;
+}
+
+declare interface TokenAccessOptions {
+    /** Key override for this call. */
+    key?: string;
+    /** Storage override for this call. */
+    storage?: TokenStorageKind;
+}
+
+export declare interface TokenStorageConfig {
+    /** Storage key. Default `"ab-sso:accessToken"`. */
+    key: string;
+    /** Where the token is kept. Default `"localStorage"`. */
+    storage: TokenStorageKind;
+    /** Master switch for reading *and* writing. Default `true`. */
+    enabled: boolean;
+}
+
+/**
+ * Session-token storage.
+ *
+ * The package persists the token itself so hosts don't have to re-implement it
+ * in every app. Everything funnels through here so there is exactly one key,
+ * one place that writes it, and one place that clears it.
+ *
+ * Design notes:
+ *
+ * - **One key, namespaced by default** (`ab-sso:accessToken`). A bare
+ *   `accessToken` collides with whatever the host app already keeps under that
+ *   very common name; set `key` if you need to match an existing app.
+ * - **Every token source writes here** — login, verify-2fa, select-account,
+ *   switch-account, signup, accept-invite and the magic-link path. Missing one
+ *   is worse than persisting nothing: `switch-account` in particular issues a
+ *   *fresh* token, and a stale stored copy means the user silently keeps acting
+ *   as the previous account.
+ * - **Storage can fail.** Private windows, disabled site data and quota errors
+ *   all throw on access, so every read/write is guarded and falls back to an
+ *   in-memory value that lasts for the page's lifetime.
+ *
+ * A bearer token in `localStorage` is readable by any script on the origin.
+ * That is the same thing hosts were doing by hand, but it is now the default —
+ * use `configureTokenStorage({ storage: 'sessionStorage' })`, or
+ * `{ enabled: false }` to opt out entirely and keep handling it yourself.
+ */
+export declare type TokenStorageKind = 'localStorage' | 'sessionStorage' | 'memory' | 'none';
+
+export declare function TwoFactorSetup({ projectId, token: tokenProp, apiBaseUrl, className, mode, onEnabled, onDisabled, onError, }: TwoFactorSetupProps): JSX_2.Element;
 
 declare interface TwoFactorSetupProps {
     projectId: string;
-    token: string;
+    /** Session token. Omit to use the one the package stored at login. */
+    token?: string;
     apiBaseUrl?: string;
     className?: string;
+    /** Colour scheme — "light" (default) or "dark". */
+    mode?: AuthMode;
     onEnabled?: () => void;
     onDisabled?: () => void;
     onError?: (error: Error) => void;
@@ -546,6 +1466,35 @@ export declare interface TwoFactorVerifySetupRequest {
     secret: string;
 }
 
+export declare interface UnauthorizedInfo {
+    /** The request that came back unauthorized. */
+    url: string;
+    status: number;
+    message?: string;
+    code?: string;
+}
+
+export declare function updateMemberApi(projectId: string, memberId: string, payload: UpdateMemberPayload, token?: string, apiBaseUrl?: string): Promise<unknown>;
+
+/**
+ * Partial. Pass `role: null` to strip permissions and `access_expiry: null` to
+ * remove an expiry — omitting a field leaves it alone, so the two cases are
+ * genuinely different and the body is built from the keys actually present.
+ */
+export declare interface UpdateMemberPayload {
+    role?: string | null;
+    access_expiry?: string | null;
+}
+
+export declare function updateRoleApi(projectId: string, roleId: string, payload: UpdateRolePayload, token?: string, apiBaseUrl?: string): Promise<unknown>;
+
+/** Partial — omitted fields are left alone; `permission` replaces the array wholesale. */
+export declare interface UpdateRolePayload {
+    title?: string;
+    description?: string;
+    permission?: string[];
+}
+
 export declare function useAuthConfig(): AuthConfigContextValue;
 
 /** Like {@link useSession} but returns null instead of throwing when there is no provider. */
@@ -561,6 +1510,13 @@ export declare interface UserWallets {
 
 export declare function useSession(): SessionContextValue;
 
+/**
+ * GET /me, but reporting *why* a session was rejected instead of just a
+ * boolean — `SessionProvider` needs to tell "logged out" apart from "this one
+ * account went away".
+ */
+export declare function validateSession(projectId: string, token: string, apiBaseUrl?: string): Promise<SessionValidation>;
+
 /**
  * Email-verification screen for a `/verify/:token` route.
  *