@waaskey/react 0.3.2 → 0.4.1

package/dist/index.d.cts

@@ -1,8 +1,46 @@
-import { Waaskey, WaaskeyOptions, Chain, Balance, CreateWalletParams, CreateWalletOptions, Wallet, SendParams, SendResult, Signature, EmbeddedSession } from '@waaskey/sdk';
-export * from '@waaskey/sdk';
+import { EmbeddedSession, EndUser, Waaskey, WaaskeyOptions, Wallet, Chain, Balance, CreateWalletParams, CreateWalletOptions, SendParams, SendResult, Signature, PageQuery, WalletData, PasskeyCeremony } from '@waaskey/sdk';
+export { Analytics, AnalyticsEvent, AnalyticsEventType, AnalyticsSink, Auth, Balance, Balances, BroadcastOptions, BroadcastResult, CLIENT_WASM_VERSION, CeremonyParams, Chain, ChainConfig, ChainProvider, ClientWasmLoader, ClientWasmModule, CreateMemberWalletParams, CreateWalletOptions, CreateWalletParams, CreateWalletResponse, CustodyKind, CustodyType, DeviceCompleteReshareParams, DeviceCompleteReshareResult, DeviceKeygenParams, DeviceKeygenResult, DeviceReshareAssembleParams, DeviceReshareAssembleResult, DeviceReshareMaterial, DeviceSignParams, DeviceSignResult, EddsaAssembleRequest, EddsaCeremonyParams, EddsaKeygenParams, EddsaKeygenResult, EddsaSendSession, EddsaSignParams, EddsaSignResult, EmailStartResult, EmbeddedSession, EncryptedShareStore, EndUser, EvmRpcProvider, FactorEnrollment, FactorVerification, FirebaseAuthRequest, HttpAnalyticsSink, IndexedDbKeyValueStore, JoinCeremonyOptions, JoinSignCeremonyOptions, KeyValueStore, Member, MemberCeremony, MemberCeremonyJoinResponse, MemberCeremonyParams, MemberKeygenParams, MemberRole, MemberSession, MemberSignCeremony, MemberSignParams, Members, MembershipScope, MemoryKeyValueStore, MemoryPrimeStore, MpcCore, MpcCurve, Onramp, OnrampWidgetParams, OnrampWidgetUrl, Page, PageQuery, PasskeyAssertionJSON, PasskeyCeremony, PasskeyPrfEnrollOptions, PasskeyPrfResult, PasskeyPrfSecretProvider, PrfCeremony, PrimePool, PrimePoolOptions, PrimePoolStore, RecoverParams, RecoverSignParams, RecoverWalletResponse, Recovery, RecoveryChallengeResponse, RecoveryFactor, RecoveryRetrieveResponse, RecoveryShareInfo, RegisterRecoveryParams, Reshare, ReshareCompletionCeremony, ReshareCompletionParams, ReshareCompletionResult, ReshareWalletResponse, SendOptions, SendParams, SendResult, ShareStore, SignMessageResponse, SignOptions, SignRequestsQuery, SignSessionResponse, Signature, SignatureKind, SigningAssertionCeremony, SigningAssertionOptions, SigningRequestResponse, SigningRequestStatus, StepUpChallengeResponse, StepUpOperation, TokenBalanceOptions, TxStatus, VerifiedWasmLoaderOptions, Waaskey, WaaskeyError, WaaskeyErrorCode, WaaskeyErrorOptions, WaaskeyOptions, Wallet, WalletActionType, WalletBackupParams, WalletCeremony, WalletCurve, WalletData, WalletShareholder, WalletStatus, Wallets, WasmMpcCore, broadcast, createVerifiedClientWasmLoader, epochShareKey, formatUnits, generateRecoveryCode, getSigningAssertion, isNonCustodial, isPasskeyAssertionSupported, isPasskeySupported, isPrfSupported, loadClientWasm, memberShareKey, userBackupPendingKey, validateCustodyPolicy, verifyWasmIntegrity } from '@waaskey/sdk';
 import * as react from 'react';
 import { ReactNode, ReactElement } from 'react';
 
+/**
+ * Where the end-user session is kept so a reload doesn't sign the user out. The SDK holds the
+ * session **in memory only** (`auth.restore` / `auth.logout`), so without one of these a refresh
+ * logs the user out.
+ *
+ * Persisting a bearer token in web storage means any XSS or malicious extension can read it —
+ * which is why the default is `'none'`. Opt in deliberately: `'session'` (tab-scoped, cleared when
+ * the tab closes) is the safer built-in; `'local'` survives restarts; or pass your own store to
+ * keep the token somewhere you control (e.g. an httpOnly cookie set by your backend).
+ */
+type SessionPersistence = 'none' | 'session' | 'local' | AuthSessionStore;
+/** A custom place to keep the session (see {@link SessionPersistence}). */
+interface AuthSessionStore {
+    load(): EmbeddedSession | undefined | Promise<EmbeddedSession | undefined>;
+    save(session: EmbeddedSession): void | Promise<void>;
+    clear(): void | Promise<void>;
+}
+/** Shared end-user auth state — one per provider, so a login anywhere is visible everywhere. */
+interface AuthStore {
+    /** The live session, or `undefined` when signed out. */
+    session?: EmbeddedSession;
+    /** The signed-in end-user (carried by the session; re-fetched by {@link refreshUser}). */
+    user?: EndUser;
+    /** The initial restore has settled — until then a persisted session may still arrive. */
+    ready: boolean;
+    /** A `me()` round-trip is in flight. */
+    loading: boolean;
+    error?: Error;
+    /** Adopt a session (or `undefined` to sign out) — restores it on the client and persists it. */
+    setSession: (session: EmbeddedSession | undefined) => void;
+    /** Re-fetch the end-user from the session token; clears the session if it is no longer valid. */
+    refreshUser: () => Promise<void>;
+    /** Sign out: clears the SDK session and the persisted copy. */
+    logout: () => void;
+}
+/** Context holding the shared {@link AuthStore}. Provided by `WaaskeyProvider`. */
+declare const AuthContext: react.Context<AuthStore | null>;
+
 /**
  * Design tokens for the Waaskey widget kit (#17). One source for colours, radius and
  * typography so every component (ConnectModal, WalletWidget, SignPrompt, FundWidget) and the
@@ -43,13 +81,22 @@ type WaaskeyProviderProps = ({
 }) & {
     /** Partial theme override (white-label) merged onto the default light theme. */
     theme?: Partial<WaasTheme>;
+    /** Where to keep the end-user session across reloads. Defaults to `'none'` (memory only). */
+    persistSession?: SessionPersistence;
     children?: ReactNode;
 };
 /**
- * Makes a {@link Waaskey} client (and the kit {@link WaasTheme}) available to the hooks and
- * components (`useWaaskey`/`useWaas`, `useTheme`, `<ConnectModal>`, `<WalletWidget>`, …).
- * Pass a `client` you built, or `options` to construct one (memoized). SSR-safe (no browser
- * APIs at construction). Written with `createElement` so the package needs no JSX build step.
+ * Makes a {@link Waaskey} client (and the kit {@link WaasTheme} + shared auth state) available to
+ * the hooks and components (`useWaaskey`/`useWaas`, `useAuth`, `useTheme`, `<ConnectModal>`,
+ * `<WalletWidget>`, …). Pass a `client` you built, or `options` to construct one. SSR-safe (no
+ * browser APIs at construction). Written with `createElement` so the package needs no JSX build step.
+ *
+ * The client is constructed **once** and kept as long as the options keep the same identity — the
+ * SDK holds the end-user session and the MPC/share state on the instance, so rebuilding it on every
+ * render would abandon a running ceremony. An inline `options={{ … }}` literal is therefore compared
+ * by the identity of its values, not by the identity of the object. When the options genuinely do
+ * change (the usual case: wiring the MPC core + share store once a session exists) the live session
+ * is re-adopted on the new client.
  */
 declare function WaaskeyProvider(props: WaaskeyProviderProps): ReactElement;
 /** Ergonomic alias of {@link WaaskeyProvider} — the documented kit entry point (`<WaasProvider>`). */
@@ -70,6 +117,9 @@ interface AsyncState<T> {
     error?: Error;
     loading: boolean;
 }
+
+/** Either a wallet id or an already-loaded {@link Wallet} — passing the object skips a `wallets.get`. */
+type WalletRef = string | Wallet;
 /** The {@link Waaskey} client from context. Throws if used outside {@link WaaskeyProvider}. */
 declare function useWaaskey(): Waaskey;
 /**
@@ -92,6 +142,11 @@ declare function useCreateWallet(): {
 declare function useWallet(id: string | undefined): AsyncState<Wallet> & {
     refresh: () => Promise<void>;
 };
+/** List the tenant's wallets, newest first (paginated); exposes `total` and `refresh`. */
+declare function useWallets(query?: PageQuery): AsyncState<WalletData[]> & {
+    total?: number;
+    refresh: () => Promise<void>;
+};
 /** Read an address's native balance on a chain, client-side (no backend); exposes `refresh`. */
 declare function useBalance(chain: Chain | undefined, address: string | undefined): AsyncState<Balance> & {
     refresh: () => Promise<void>;
@@ -108,7 +163,7 @@ type SendStatus = 'idle' | 'pending' | 'sent' | 'error';
  * the **signed raw tx** (`result.signedTx`) — WaaS never broadcasts; the client submits it
  * (e.g. `waaskey.broadcast(result.signedTx, { rpcUrl })` or your own node).
  */
-declare function useSend(walletId: string | undefined): {
+declare function useSend(wallet: WalletRef | undefined): {
     send: (params: SendParams) => Promise<SendResult>;
     status: SendStatus;
     result?: SendResult;
@@ -116,31 +171,83 @@ declare function useSend(walletId: string | undefined): {
     reset: () => void;
 };
 /** Load a wallet's signing activity (newest first) — raw signs and send/sweep signed txs; exposes `refresh`. */
-declare function useSignatures(walletId: string | undefined): AsyncState<Signature[]> & {
+declare function useSignatures(wallet: WalletRef | undefined): AsyncState<Signature[]> & {
     refresh: () => Promise<void>;
 };
 
-/** Step of the email-OTP login flow. */
+/** What {@link useAuth} exposes — the shared end-user auth state of the provider. */
+interface UseAuth {
+    /** The live session, or `undefined` when signed out. */
+    session?: EmbeddedSession;
+    /** The signed-in end-user. */
+    user?: EndUser;
+    isAuthenticated: boolean;
+    /**
+     * The initial session restore has settled. Gate your "signed out" UI on this — otherwise a
+     * persisted session makes the app flash the login screen on every reload.
+     */
+    ready: boolean;
+    /** A `me()` round-trip is in flight. */
+    loading: boolean;
+    error?: Error;
+    /** Adopt a session established elsewhere (e.g. from `<ConnectModal onConnect>`). */
+    setSession: (session: EmbeddedSession | undefined) => void;
+    /** Re-fetch the end-user; signs out if the session token is no longer accepted. */
+    refreshUser: () => Promise<void>;
+    /** Sign out — clears the SDK session and any persisted copy. */
+    logout: () => void;
+}
+/**
+ * The signed-in end-user, shared across the whole provider: a login through `useLogin` or
+ * `<ConnectModal>` updates every consumer of this hook, and (with `persistSession`) survives a
+ * reload. The SDK itself keeps the session in memory only, which is why this state lives here.
+ */
+declare function useAuth(): UseAuth;
+/** The signed-in end-user, or `undefined`. Sugar over {@link useAuth}. */
+declare function useUser(): EndUser | undefined;
+
+/**
+ * Step of the login flow. `'email'` is the identifier step — it collects an email **or** a phone
+ * number depending on the method the UI offers; `'code'` collects the one-time code.
+ */
 type LoginStep = 'email' | 'code' | 'done';
+/** How the end-user is signing in. */
+type LoginMethod = 'email' | 'phone' | 'google' | 'passkey';
 interface UseLogin {
     step: LoginStep;
-    /** The email entered at the first step. */
+    /** The method in progress (set by whichever `start*`/`loginWith*` was called). */
+    method: LoginMethod;
+    /** The email entered at the first step (empty for phone/social/passkey). */
     email: string;
+    /** The phone entered at the first step (empty for email/social/passkey). */
+    phone: string;
     /** The session once login completes. */
     session?: EmbeddedSession;
     loading: boolean;
     error?: Error;
     /** Send a one-time code to `email` (→ `code` step). */
     start: (email: string) => Promise<void>;
-    /** Verify the code (→ `done` step on success). */
+    /** Send a one-time code to `phone` (E.164) (→ `code` step). */
+    startPhone: (phone: string) => Promise<void>;
+    /** Verify the code for whichever identifier was started (→ `done` step on success). */
     verify: (code: string) => Promise<void>;
-    /** Back to the email step (clears error). */
+    /**
+     * Sign in with a Google ID token. Your app owns the Google button (Google Identity Services or
+     * `@react-oauth/google`) and hands the resulting `idToken` here — the kit ships no Google SDK.
+     */
+    loginWithGoogle: (idToken: string) => Promise<void>;
+    /** Sign in with a Firebase ID token (any Firebase provider). */
+    loginWithFirebase: (idToken: string) => Promise<void>;
+    /** Usernameless passkey (WebAuthn) sign-in. Needs `@simplewebauthn/browser`, or pass a `ceremony`. */
+    loginWithPasskey: (ceremony?: PasskeyCeremony) => Promise<void>;
+    /** Back to the identifier step (clears the entered values, the error and the session). */
     reset: () => void;
 }
 /**
- * Headless email-OTP login (#6/#13): drives `waaskey.auth.email.start` → `.verify`,
- * tracking `step`/`loading`/`error` so a UI (e.g. `<ConnectModal>`) — or a custom one —
- * can render all states. The established session is also held on `waaskey.auth`.
+ * Headless login (#6/#13) for every method the API supports — email OTP, phone OTP, Google,
+ * Firebase and passkey — tracking `step`/`loading`/`error` so a UI (e.g. `<ConnectModal>`) or a
+ * custom one can render all states. On success the session is published to the provider's shared
+ * auth state, so `useAuth()` sees it everywhere and `persistSession` stores it.
  */
 declare function useLogin(): UseLogin;
 
@@ -158,19 +265,30 @@ interface ConnectModalProps {
     open: boolean;
     /** Close requested (backdrop / ✕ / after connect). */
     onClose: () => void;
-    /** Called with the session once login completes. */
+    /** Called **once** with the session when login completes. */
     onConnect?: (session: EmbeddedSession) => void;
     /** Heading copy. */
     title?: string;
+    /**
+     * Sign-in methods to offer, in order. Defaults to `['email']`. The first identifier method
+     * (`'email'`/`'phone'`) is the default form; the rest render as alternatives.
+     */
+    methods?: LoginMethod[];
+    /**
+     * Required to offer `'google'`: resolve a Google ID token. Your app owns the Google button
+     * (Google Identity Services / `@react-oauth/google`) — the kit ships no Google SDK.
+     */
+    googleIdToken?: () => Promise<string>;
     theme?: ConnectModalTheme;
 }
 /**
- * Drop-in email-OTP login modal (#13). Runs `useLogin` (→ `waaskey.auth`), rendering the
- * email → code → done steps with loading/error states; calls `onConnect` with the session.
- * Themeable via inline tokens, accessible (labelled dialog, focus, Esc to close); written
- * with `createElement` so the package needs no JSX build step.
+ * Drop-in login modal (#13). Runs `useLogin` (→ `waaskey.auth`), rendering the identifier → code
+ * → done steps with loading/error states; calls `onConnect` with the session (which is also
+ * published to the provider's shared auth state, so `useAuth()` sees it). Supports email OTP,
+ * phone OTP, passkey and Google. Themeable via inline tokens, accessible (labelled dialog, focus,
+ * Esc to close); written with `createElement` so the package needs no JSX build step.
  */
-declare function ConnectModal({ open, onClose, onConnect, title, theme }: ConnectModalProps): ReactElement | null;
+declare function ConnectModal({ open, onClose, onConnect, title, methods, googleIdToken, theme }: ConnectModalProps): ReactElement | null;
 
 /** Per-instance theme override for {@link WalletWidget} (merged onto the provider theme). */
 type WalletWidgetTheme = Partial<WaasTheme>;
@@ -255,4 +373,4 @@ interface FundWidgetProps {
  */
 declare function FundWidget({ walletAddress, chainId, cryptoCurrency, fiatCurrency, fiatAmount, label, onComplete }: FundWidgetProps): ReactElement;
 
-export { type AsyncState, ConnectModal, type ConnectModalProps, type ConnectModalTheme, FundWidget, type FundWidgetProps, type LoginStep, type SendStatus, type SignOutcome, SignPrompt, type SignPromptProps, type SignRequest, ThemeContext, type UseLogin, WaasProvider, type WaasProviderProps, type WaasTheme, WaaskeyContext, WaaskeyProvider, type WaaskeyProviderProps, WalletWidget, type WalletWidgetProps, type WalletWidgetTheme, darkTheme, defaultTheme, lightTheme, resolveTheme, useBalance, useBalances, useCreateWallet, useLogin, useQrCode, useSend, useSignPrompt, useSignatures, useTheme, useWaas, useWaaskey, useWallet };
+export { type AsyncState, AuthContext, type AuthSessionStore, type AuthStore, ConnectModal, type ConnectModalProps, type ConnectModalTheme, FundWidget, type FundWidgetProps, type LoginMethod, type LoginStep, type SendStatus, type SessionPersistence, type SignOutcome, SignPrompt, type SignPromptProps, type SignRequest, ThemeContext, type UseAuth, type UseLogin, WaasProvider, type WaasProviderProps, type WaasTheme, WaaskeyContext, WaaskeyProvider, type WaaskeyProviderProps, type WalletRef, WalletWidget, type WalletWidgetProps, type WalletWidgetTheme, darkTheme, defaultTheme, lightTheme, resolveTheme, useAuth, useBalance, useBalances, useCreateWallet, useLogin, useQrCode, useSend, useSignPrompt, useSignatures, useTheme, useUser, useWaas, useWaaskey, useWallet, useWallets };

package/dist/index.d.ts

@@ -1,8 +1,46 @@
-import { Waaskey, WaaskeyOptions, Chain, Balance, CreateWalletParams, CreateWalletOptions, Wallet, SendParams, SendResult, Signature, EmbeddedSession } from '@waaskey/sdk';
-export * from '@waaskey/sdk';
+import { EmbeddedSession, EndUser, Waaskey, WaaskeyOptions, Wallet, Chain, Balance, CreateWalletParams, CreateWalletOptions, SendParams, SendResult, Signature, PageQuery, WalletData, PasskeyCeremony } from '@waaskey/sdk';
+export { Analytics, AnalyticsEvent, AnalyticsEventType, AnalyticsSink, Auth, Balance, Balances, BroadcastOptions, BroadcastResult, CLIENT_WASM_VERSION, CeremonyParams, Chain, ChainConfig, ChainProvider, ClientWasmLoader, ClientWasmModule, CreateMemberWalletParams, CreateWalletOptions, CreateWalletParams, CreateWalletResponse, CustodyKind, CustodyType, DeviceCompleteReshareParams, DeviceCompleteReshareResult, DeviceKeygenParams, DeviceKeygenResult, DeviceReshareAssembleParams, DeviceReshareAssembleResult, DeviceReshareMaterial, DeviceSignParams, DeviceSignResult, EddsaAssembleRequest, EddsaCeremonyParams, EddsaKeygenParams, EddsaKeygenResult, EddsaSendSession, EddsaSignParams, EddsaSignResult, EmailStartResult, EmbeddedSession, EncryptedShareStore, EndUser, EvmRpcProvider, FactorEnrollment, FactorVerification, FirebaseAuthRequest, HttpAnalyticsSink, IndexedDbKeyValueStore, JoinCeremonyOptions, JoinSignCeremonyOptions, KeyValueStore, Member, MemberCeremony, MemberCeremonyJoinResponse, MemberCeremonyParams, MemberKeygenParams, MemberRole, MemberSession, MemberSignCeremony, MemberSignParams, Members, MembershipScope, MemoryKeyValueStore, MemoryPrimeStore, MpcCore, MpcCurve, Onramp, OnrampWidgetParams, OnrampWidgetUrl, Page, PageQuery, PasskeyAssertionJSON, PasskeyCeremony, PasskeyPrfEnrollOptions, PasskeyPrfResult, PasskeyPrfSecretProvider, PrfCeremony, PrimePool, PrimePoolOptions, PrimePoolStore, RecoverParams, RecoverSignParams, RecoverWalletResponse, Recovery, RecoveryChallengeResponse, RecoveryFactor, RecoveryRetrieveResponse, RecoveryShareInfo, RegisterRecoveryParams, Reshare, ReshareCompletionCeremony, ReshareCompletionParams, ReshareCompletionResult, ReshareWalletResponse, SendOptions, SendParams, SendResult, ShareStore, SignMessageResponse, SignOptions, SignRequestsQuery, SignSessionResponse, Signature, SignatureKind, SigningAssertionCeremony, SigningAssertionOptions, SigningRequestResponse, SigningRequestStatus, StepUpChallengeResponse, StepUpOperation, TokenBalanceOptions, TxStatus, VerifiedWasmLoaderOptions, Waaskey, WaaskeyError, WaaskeyErrorCode, WaaskeyErrorOptions, WaaskeyOptions, Wallet, WalletActionType, WalletBackupParams, WalletCeremony, WalletCurve, WalletData, WalletShareholder, WalletStatus, Wallets, WasmMpcCore, broadcast, createVerifiedClientWasmLoader, epochShareKey, formatUnits, generateRecoveryCode, getSigningAssertion, isNonCustodial, isPasskeyAssertionSupported, isPasskeySupported, isPrfSupported, loadClientWasm, memberShareKey, userBackupPendingKey, validateCustodyPolicy, verifyWasmIntegrity } from '@waaskey/sdk';
 import * as react from 'react';
 import { ReactNode, ReactElement } from 'react';
 
+/**
+ * Where the end-user session is kept so a reload doesn't sign the user out. The SDK holds the
+ * session **in memory only** (`auth.restore` / `auth.logout`), so without one of these a refresh
+ * logs the user out.
+ *
+ * Persisting a bearer token in web storage means any XSS or malicious extension can read it —
+ * which is why the default is `'none'`. Opt in deliberately: `'session'` (tab-scoped, cleared when
+ * the tab closes) is the safer built-in; `'local'` survives restarts; or pass your own store to
+ * keep the token somewhere you control (e.g. an httpOnly cookie set by your backend).
+ */
+type SessionPersistence = 'none' | 'session' | 'local' | AuthSessionStore;
+/** A custom place to keep the session (see {@link SessionPersistence}). */
+interface AuthSessionStore {
+    load(): EmbeddedSession | undefined | Promise<EmbeddedSession | undefined>;
+    save(session: EmbeddedSession): void | Promise<void>;
+    clear(): void | Promise<void>;
+}
+/** Shared end-user auth state — one per provider, so a login anywhere is visible everywhere. */
+interface AuthStore {
+    /** The live session, or `undefined` when signed out. */
+    session?: EmbeddedSession;
+    /** The signed-in end-user (carried by the session; re-fetched by {@link refreshUser}). */
+    user?: EndUser;
+    /** The initial restore has settled — until then a persisted session may still arrive. */
+    ready: boolean;
+    /** A `me()` round-trip is in flight. */
+    loading: boolean;
+    error?: Error;
+    /** Adopt a session (or `undefined` to sign out) — restores it on the client and persists it. */
+    setSession: (session: EmbeddedSession | undefined) => void;
+    /** Re-fetch the end-user from the session token; clears the session if it is no longer valid. */
+    refreshUser: () => Promise<void>;
+    /** Sign out: clears the SDK session and the persisted copy. */
+    logout: () => void;
+}
+/** Context holding the shared {@link AuthStore}. Provided by `WaaskeyProvider`. */
+declare const AuthContext: react.Context<AuthStore | null>;
+
 /**
  * Design tokens for the Waaskey widget kit (#17). One source for colours, radius and
  * typography so every component (ConnectModal, WalletWidget, SignPrompt, FundWidget) and the
@@ -43,13 +81,22 @@ type WaaskeyProviderProps = ({
 }) & {
     /** Partial theme override (white-label) merged onto the default light theme. */
     theme?: Partial<WaasTheme>;
+    /** Where to keep the end-user session across reloads. Defaults to `'none'` (memory only). */
+    persistSession?: SessionPersistence;
     children?: ReactNode;
 };
 /**
- * Makes a {@link Waaskey} client (and the kit {@link WaasTheme}) available to the hooks and
- * components (`useWaaskey`/`useWaas`, `useTheme`, `<ConnectModal>`, `<WalletWidget>`, …).
- * Pass a `client` you built, or `options` to construct one (memoized). SSR-safe (no browser
- * APIs at construction). Written with `createElement` so the package needs no JSX build step.
+ * Makes a {@link Waaskey} client (and the kit {@link WaasTheme} + shared auth state) available to
+ * the hooks and components (`useWaaskey`/`useWaas`, `useAuth`, `useTheme`, `<ConnectModal>`,
+ * `<WalletWidget>`, …). Pass a `client` you built, or `options` to construct one. SSR-safe (no
+ * browser APIs at construction). Written with `createElement` so the package needs no JSX build step.
+ *
+ * The client is constructed **once** and kept as long as the options keep the same identity — the
+ * SDK holds the end-user session and the MPC/share state on the instance, so rebuilding it on every
+ * render would abandon a running ceremony. An inline `options={{ … }}` literal is therefore compared
+ * by the identity of its values, not by the identity of the object. When the options genuinely do
+ * change (the usual case: wiring the MPC core + share store once a session exists) the live session
+ * is re-adopted on the new client.
  */
 declare function WaaskeyProvider(props: WaaskeyProviderProps): ReactElement;
 /** Ergonomic alias of {@link WaaskeyProvider} — the documented kit entry point (`<WaasProvider>`). */
@@ -70,6 +117,9 @@ interface AsyncState<T> {
     error?: Error;
     loading: boolean;
 }
+
+/** Either a wallet id or an already-loaded {@link Wallet} — passing the object skips a `wallets.get`. */
+type WalletRef = string | Wallet;
 /** The {@link Waaskey} client from context. Throws if used outside {@link WaaskeyProvider}. */
 declare function useWaaskey(): Waaskey;
 /**
@@ -92,6 +142,11 @@ declare function useCreateWallet(): {
 declare function useWallet(id: string | undefined): AsyncState<Wallet> & {
     refresh: () => Promise<void>;
 };
+/** List the tenant's wallets, newest first (paginated); exposes `total` and `refresh`. */
+declare function useWallets(query?: PageQuery): AsyncState<WalletData[]> & {
+    total?: number;
+    refresh: () => Promise<void>;
+};
 /** Read an address's native balance on a chain, client-side (no backend); exposes `refresh`. */
 declare function useBalance(chain: Chain | undefined, address: string | undefined): AsyncState<Balance> & {
     refresh: () => Promise<void>;
@@ -108,7 +163,7 @@ type SendStatus = 'idle' | 'pending' | 'sent' | 'error';
  * the **signed raw tx** (`result.signedTx`) — WaaS never broadcasts; the client submits it
  * (e.g. `waaskey.broadcast(result.signedTx, { rpcUrl })` or your own node).
  */
-declare function useSend(walletId: string | undefined): {
+declare function useSend(wallet: WalletRef | undefined): {
     send: (params: SendParams) => Promise<SendResult>;
     status: SendStatus;
     result?: SendResult;
@@ -116,31 +171,83 @@ declare function useSend(walletId: string | undefined): {
     reset: () => void;
 };
 /** Load a wallet's signing activity (newest first) — raw signs and send/sweep signed txs; exposes `refresh`. */
-declare function useSignatures(walletId: string | undefined): AsyncState<Signature[]> & {
+declare function useSignatures(wallet: WalletRef | undefined): AsyncState<Signature[]> & {
     refresh: () => Promise<void>;
 };
 
-/** Step of the email-OTP login flow. */
+/** What {@link useAuth} exposes — the shared end-user auth state of the provider. */
+interface UseAuth {
+    /** The live session, or `undefined` when signed out. */
+    session?: EmbeddedSession;
+    /** The signed-in end-user. */
+    user?: EndUser;
+    isAuthenticated: boolean;
+    /**
+     * The initial session restore has settled. Gate your "signed out" UI on this — otherwise a
+     * persisted session makes the app flash the login screen on every reload.
+     */
+    ready: boolean;
+    /** A `me()` round-trip is in flight. */
+    loading: boolean;
+    error?: Error;
+    /** Adopt a session established elsewhere (e.g. from `<ConnectModal onConnect>`). */
+    setSession: (session: EmbeddedSession | undefined) => void;
+    /** Re-fetch the end-user; signs out if the session token is no longer accepted. */
+    refreshUser: () => Promise<void>;
+    /** Sign out — clears the SDK session and any persisted copy. */
+    logout: () => void;
+}
+/**
+ * The signed-in end-user, shared across the whole provider: a login through `useLogin` or
+ * `<ConnectModal>` updates every consumer of this hook, and (with `persistSession`) survives a
+ * reload. The SDK itself keeps the session in memory only, which is why this state lives here.
+ */
+declare function useAuth(): UseAuth;
+/** The signed-in end-user, or `undefined`. Sugar over {@link useAuth}. */
+declare function useUser(): EndUser | undefined;
+
+/**
+ * Step of the login flow. `'email'` is the identifier step — it collects an email **or** a phone
+ * number depending on the method the UI offers; `'code'` collects the one-time code.
+ */
 type LoginStep = 'email' | 'code' | 'done';
+/** How the end-user is signing in. */
+type LoginMethod = 'email' | 'phone' | 'google' | 'passkey';
 interface UseLogin {
     step: LoginStep;
-    /** The email entered at the first step. */
+    /** The method in progress (set by whichever `start*`/`loginWith*` was called). */
+    method: LoginMethod;
+    /** The email entered at the first step (empty for phone/social/passkey). */
     email: string;
+    /** The phone entered at the first step (empty for email/social/passkey). */
+    phone: string;
     /** The session once login completes. */
     session?: EmbeddedSession;
     loading: boolean;
     error?: Error;
     /** Send a one-time code to `email` (→ `code` step). */
     start: (email: string) => Promise<void>;
-    /** Verify the code (→ `done` step on success). */
+    /** Send a one-time code to `phone` (E.164) (→ `code` step). */
+    startPhone: (phone: string) => Promise<void>;
+    /** Verify the code for whichever identifier was started (→ `done` step on success). */
     verify: (code: string) => Promise<void>;
-    /** Back to the email step (clears error). */
+    /**
+     * Sign in with a Google ID token. Your app owns the Google button (Google Identity Services or
+     * `@react-oauth/google`) and hands the resulting `idToken` here — the kit ships no Google SDK.
+     */
+    loginWithGoogle: (idToken: string) => Promise<void>;
+    /** Sign in with a Firebase ID token (any Firebase provider). */
+    loginWithFirebase: (idToken: string) => Promise<void>;
+    /** Usernameless passkey (WebAuthn) sign-in. Needs `@simplewebauthn/browser`, or pass a `ceremony`. */
+    loginWithPasskey: (ceremony?: PasskeyCeremony) => Promise<void>;
+    /** Back to the identifier step (clears the entered values, the error and the session). */
     reset: () => void;
 }
 /**
- * Headless email-OTP login (#6/#13): drives `waaskey.auth.email.start` → `.verify`,
- * tracking `step`/`loading`/`error` so a UI (e.g. `<ConnectModal>`) — or a custom one —
- * can render all states. The established session is also held on `waaskey.auth`.
+ * Headless login (#6/#13) for every method the API supports — email OTP, phone OTP, Google,
+ * Firebase and passkey — tracking `step`/`loading`/`error` so a UI (e.g. `<ConnectModal>`) or a
+ * custom one can render all states. On success the session is published to the provider's shared
+ * auth state, so `useAuth()` sees it everywhere and `persistSession` stores it.
  */
 declare function useLogin(): UseLogin;
 
@@ -158,19 +265,30 @@ interface ConnectModalProps {
     open: boolean;
     /** Close requested (backdrop / ✕ / after connect). */
     onClose: () => void;
-    /** Called with the session once login completes. */
+    /** Called **once** with the session when login completes. */
     onConnect?: (session: EmbeddedSession) => void;
     /** Heading copy. */
     title?: string;
+    /**
+     * Sign-in methods to offer, in order. Defaults to `['email']`. The first identifier method
+     * (`'email'`/`'phone'`) is the default form; the rest render as alternatives.
+     */
+    methods?: LoginMethod[];
+    /**
+     * Required to offer `'google'`: resolve a Google ID token. Your app owns the Google button
+     * (Google Identity Services / `@react-oauth/google`) — the kit ships no Google SDK.
+     */
+    googleIdToken?: () => Promise<string>;
     theme?: ConnectModalTheme;
 }
 /**
- * Drop-in email-OTP login modal (#13). Runs `useLogin` (→ `waaskey.auth`), rendering the
- * email → code → done steps with loading/error states; calls `onConnect` with the session.
- * Themeable via inline tokens, accessible (labelled dialog, focus, Esc to close); written
- * with `createElement` so the package needs no JSX build step.
+ * Drop-in login modal (#13). Runs `useLogin` (→ `waaskey.auth`), rendering the identifier → code
+ * → done steps with loading/error states; calls `onConnect` with the session (which is also
+ * published to the provider's shared auth state, so `useAuth()` sees it). Supports email OTP,
+ * phone OTP, passkey and Google. Themeable via inline tokens, accessible (labelled dialog, focus,
+ * Esc to close); written with `createElement` so the package needs no JSX build step.
  */
-declare function ConnectModal({ open, onClose, onConnect, title, theme }: ConnectModalProps): ReactElement | null;
+declare function ConnectModal({ open, onClose, onConnect, title, methods, googleIdToken, theme }: ConnectModalProps): ReactElement | null;
 
 /** Per-instance theme override for {@link WalletWidget} (merged onto the provider theme). */
 type WalletWidgetTheme = Partial<WaasTheme>;
@@ -255,4 +373,4 @@ interface FundWidgetProps {
  */
 declare function FundWidget({ walletAddress, chainId, cryptoCurrency, fiatCurrency, fiatAmount, label, onComplete }: FundWidgetProps): ReactElement;
 
-export { type AsyncState, ConnectModal, type ConnectModalProps, type ConnectModalTheme, FundWidget, type FundWidgetProps, type LoginStep, type SendStatus, type SignOutcome, SignPrompt, type SignPromptProps, type SignRequest, ThemeContext, type UseLogin, WaasProvider, type WaasProviderProps, type WaasTheme, WaaskeyContext, WaaskeyProvider, type WaaskeyProviderProps, WalletWidget, type WalletWidgetProps, type WalletWidgetTheme, darkTheme, defaultTheme, lightTheme, resolveTheme, useBalance, useBalances, useCreateWallet, useLogin, useQrCode, useSend, useSignPrompt, useSignatures, useTheme, useWaas, useWaaskey, useWallet };
+export { type AsyncState, AuthContext, type AuthSessionStore, type AuthStore, ConnectModal, type ConnectModalProps, type ConnectModalTheme, FundWidget, type FundWidgetProps, type LoginMethod, type LoginStep, type SendStatus, type SessionPersistence, type SignOutcome, SignPrompt, type SignPromptProps, type SignRequest, ThemeContext, type UseAuth, type UseLogin, WaasProvider, type WaasProviderProps, type WaasTheme, WaaskeyContext, WaaskeyProvider, type WaaskeyProviderProps, type WalletRef, WalletWidget, type WalletWidgetProps, type WalletWidgetTheme, darkTheme, defaultTheme, lightTheme, resolveTheme, useAuth, useBalance, useBalances, useCreateWallet, useLogin, useQrCode, useSend, useSignPrompt, useSignatures, useTheme, useUser, useWaas, useWaaskey, useWallet, useWallets };