@passflow/core 0.0.1 → 0.2.0

package/dist/lib/passflow.d.ts

@@ -1,15 +1,25 @@
-import { type AppSettings, type InvitationsPaginatedList, type InviteLinkResponse, type PassflowAuthorizationResponse, type PassflowConfig, PassflowFederatedAuthPayload, type PassflowPasskeyAuthenticateStartPayload, type PassflowPasskeyRegisterStartPayload, type PassflowPasskeySettings, type PassflowPasswordPolicySettings, type PassflowPasswordlessResponse, type PassflowPasswordlessSignInCompletePayload, type PassflowPasswordlessSignInPayload, type PassflowSendPasswordResetEmailPayload, type PassflowSettingsAll, type PassflowSignInPayload, type PassflowSignUpPayload, type PassflowSuccessResponse, type PassflowTenantResponse, type PassflowValidationResponse, type RequestInviteLinkPayload } from './api';
-import { TenantService } from './services';
+import { type AppSettings, type InvitationsPaginatedList, type InviteLinkResponse, type PassflowAuthorizationResponse, type PassflowConfig, PassflowFederatedAuthPayload, type PassflowPasskeyAuthenticateStartPayload, type PassflowPasskeyRegisterStartPayload, type PassflowPasskeySettings, type PassflowPasswordPolicySettings, type PassflowPasswordlessResponse, type PassflowPasswordlessSignInCompletePayload, type PassflowPasswordlessSignInPayload, type PassflowSendPasswordResetEmailPayload, type PassflowSettingsAll, type PassflowSignInPayload, type PassflowSignUpPayload, type PassflowSuccessResponse, type PassflowTenantResponse, type PassflowValidationResponse, type RequestInviteLinkPayload, type TwoFactorConfirmResponse, type TwoFactorDisableResponse, type TwoFactorRecoveryResponse, type TwoFactorRegenerateResponse, type TwoFactorSetupResponse, type TwoFactorStatusResponse, type TwoFactorVerifyResponse } from './api';
+import { TenantService, TwoFactorService } from './services';
 import { PassflowEvent, type PassflowSubscriber } from './store';
-import { type TokenType } from './token-service';
+import { type TokenType } from './token';
 import type { ParsedTokens, SessionParams, Tokens } from './types';
 export declare class Passflow {
+    /**
+     * SDK version string.
+     * Useful for debugging and reporting version-specific issues.
+     * @example
+     * ```typescript
+     * console.log('Using Passflow SDK version:', Passflow.version);
+     * ```
+     */
+    static readonly version: string;
     private authApi;
     private appApi;
     private userApi;
     private settingApi;
-    private tenantAPI;
-    private invitationAPI;
+    private tenantApi;
+    private invitationApi;
+    private twoFactorApi;
     private scopes;
     private createTenantForNewUser;
     private doRefreshTokens;
@@ -21,7 +31,9 @@ export declare class Passflow {
     private tenantService;
     private invitationService;
     private tokenCacheService;
+    private twoFactorService;
     tenant: TenantService;
+    twoFactor: TwoFactorService;
     private createSessionCallback?;
     private expiredSessionCallback?;
     error?: Error;
@@ -29,42 +41,646 @@ export declare class Passflow {
     url: string;
     appId?: string;
     constructor(config: PassflowConfig);
+    /**
+     * Update the appId and propagate it to all API clients.
+     * This ensures that all future API requests use the new appId in their headers.
+     *
+     * @param appId - The new application ID to set
+     *
+     * @example
+     * ```typescript
+     * // Update appId after discovery
+     * passflow.setAppId('discovered-app-id-123');
+     * ```
+     */
+    setAppId(appId: string): void;
+    /**
+     * Configure session callbacks and check current session status.
+     *
+     * **WARNING**: Calling this method multiple times will overwrite previously registered callbacks.
+     * Only the most recent `createSession` and `expiredSession` callbacks will be active.
+     *
+     * @param params - Session configuration parameters
+     * @param params.createSession - Callback invoked when a valid session exists or is created
+     * @param params.expiredSession - Callback invoked when no valid session exists
+     * @param params.doRefresh - Whether to automatically refresh expired tokens (default: false)
+     * @returns Promise that resolves when session check is complete
+     *
+     * @example
+     * ```typescript
+     * await passflow.session({
+     *   createSession: async ({ tokens, parsedTokens }) => {
+     *     console.log('User is authenticated', parsedTokens?.access_token?.sub);
+     *     // Initialize user session in your app
+     *   },
+     *   expiredSession: async () => {
+     *     console.log('User session expired');
+     *     // Redirect to login or show login modal
+     *   },
+     *   doRefresh: true // Automatically refresh tokens if expired
+     * });
+     * ```
+     */
     session: ({ createSession, expiredSession, doRefresh }: SessionParams) => Promise<void>;
     private submitSessionCheck;
-    subscribe(s: PassflowSubscriber, t?: PassflowEvent[]): void;
-    unsubscribe(s: PassflowSubscriber, t?: PassflowEvent[]): void;
+    /**
+     * Subscribe to Passflow authentication events.
+     *
+     * @param subscriber - Subscriber function that receives event type and payload
+     * @param events - Optional array of specific events to listen for. If omitted, subscribes to all events.
+     *
+     * @example
+     * ```typescript
+     * // Subscribe to all events
+     * passflow.subscribe((event, payload) => {
+     *   console.log('Event:', event, payload);
+     * });
+     *
+     * // Subscribe to specific events only
+     * passflow.subscribe(
+     *   (event, payload) => {
+     *     if (event === PassflowEvent.SignIn) {
+     *       console.log('User signed in', payload.tokens);
+     *     }
+     *   },
+     *   [PassflowEvent.SignIn, PassflowEvent.SignOut]
+     * );
+     * ```
+     */
+    subscribe(subscriber: PassflowSubscriber, events?: PassflowEvent[]): void;
+    /**
+     * Unsubscribe from Passflow authentication events.
+     *
+     * @param subscriber - The subscriber function to remove
+     * @param events - Optional array of specific events to unsubscribe from. If omitted, unsubscribes from all events.
+     *
+     * @example
+     * ```typescript
+     * const subscriber = (event, payload) => console.log(event, payload);
+     *
+     * // Subscribe
+     * passflow.subscribe(subscriber);
+     *
+     * // Later, unsubscribe
+     * passflow.unsubscribe(subscriber);
+     * ```
+     */
+    unsubscribe(subscriber: PassflowSubscriber, events?: PassflowEvent[]): void;
+    /**
+     * Handle OAuth redirect callback and extract tokens from URL query parameters.
+     * This method should be called on the redirect page after authentication.
+     *
+     * @returns Tokens object if found in URL, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * // On your redirect page (e.g., /auth/callback)
+     * const tokens = passflow.handleTokensRedirect();
+     * if (tokens) {
+     *   console.log('Authentication successful', tokens.access_token);
+     *   // Tokens are automatically saved to storage
+     * }
+     * ```
+     */
     handleTokensRedirect(): Tokens | undefined;
     private checkAndSetTokens;
     private checkErrorsFromURL;
+    private cleanupUrlParams;
     private setTokensToCacheFromLocalStorage;
-    getTokensCache(): Tokens | undefined;
-    getTokensCacheWithRefresh(): Promise<Tokens | undefined>;
-    getParsedTokenCache(): ParsedTokens | undefined;
-    tokensCacheIsExpired(): boolean;
+    /**
+     * Get cached tokens from memory without triggering a refresh.
+     *
+     * @returns Cached tokens or undefined if not cached
+     *
+     * @example
+     * ```typescript
+     * const tokens = passflow.getCachedTokens();
+     * if (tokens) {
+     *   console.log('Access token:', tokens.access_token);
+     * }
+     * ```
+     */
+    getCachedTokens(): Tokens | undefined;
+    /**
+     * Get cached tokens from memory and automatically refresh if expired.
+     *
+     * @returns Promise resolving to tokens or undefined
+     *
+     * @example
+     * ```typescript
+     * const tokens = await passflow.getTokensWithRefresh();
+     * // Tokens are guaranteed to be valid or undefined
+     * ```
+     */
+    getTokensWithRefresh(): Promise<Tokens | undefined>;
+    /**
+     * Get parsed JWT tokens with decoded claims.
+     *
+     * @returns Parsed token objects with decoded payloads
+     *
+     * @example
+     * ```typescript
+     * const parsed = passflow.getParsedTokens();
+     * if (parsed?.access_token) {
+     *   console.log('User ID:', parsed.access_token.sub);
+     *   console.log('Expires at:', new Date(parsed.access_token.exp * 1000));
+     * }
+     * ```
+     */
+    getParsedTokens(): ParsedTokens | undefined;
+    /**
+     * Check if the cached tokens are expired.
+     *
+     * @returns True if tokens are expired, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (passflow.areTokensExpired()) {
+     *   await passflow.refreshToken();
+     * }
+     * ```
+     */
+    areTokensExpired(): boolean;
+    /**
+     * Check if the user is currently authenticated with valid tokens.
+     *
+     * @returns True if user has valid, non-expired tokens
+     *
+     * @example
+     * ```typescript
+     * if (passflow.isAuthenticated()) {
+     *   console.log('User is logged in');
+     * } else {
+     *   console.log('User needs to sign in');
+     * }
+     * ```
+     */
     isAuthenticated(): boolean;
+    /**
+     * Sign in a user with email/username and password.
+     *
+     * @param payload - Sign-in credentials and options
+     * @param payload.email - User's email or username
+     * @param payload.password - User's password
+     * @param payload.scopes - Optional scopes to request (defaults to SDK scopes)
+     * @returns Promise with authorization response containing tokens
+     * @throws {PassflowError} If authentication fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const response = await passflow.signIn({
+     *     email: 'user@example.com',
+     *     password: 'secure-password'
+     *   });
+     *   console.log('Signed in successfully', response.access_token);
+     * } catch (error) {
+     *   console.error('Sign in failed', error.message);
+     * }
+     * ```
+     */
     signIn(payload: PassflowSignInPayload): Promise<PassflowAuthorizationResponse>;
+    /**
+     * Register a new user account with email and password.
+     *
+     * @param payload - Registration details
+     * @param payload.email - User's email address
+     * @param payload.password - User's password
+     * @param payload.username - Optional username
+     * @param payload.scopes - Optional scopes to request
+     * @returns Promise with authorization response containing tokens
+     * @throws {PassflowError} If registration fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const response = await passflow.signUp({
+     *     email: 'newuser@example.com',
+     *     password: 'secure-password',
+     *     username: 'newuser'
+     *   });
+     *   console.log('Account created', response.access_token);
+     * } catch (error) {
+     *   console.error('Sign up failed', error.message);
+     * }
+     * ```
+     */
     signUp(payload: PassflowSignUpPayload): Promise<PassflowAuthorizationResponse>;
+    /**
+     * Initiate passwordless authentication by sending a magic link or OTP.
+     *
+     * @param payload - Passwordless sign-in configuration
+     * @param payload.email - User's email address
+     * @param payload.method - Delivery method ('email' or 'sms')
+     * @returns Promise with response indicating if the code was sent
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * // Send magic link via email
+     * const response = await passflow.passwordlessSignIn({
+     *   email: 'user@example.com',
+     *   method: 'email'
+     * });
+     * console.log('Magic link sent:', response.success);
+     * ```
+     */
     passwordlessSignIn(payload: PassflowPasswordlessSignInPayload): Promise<PassflowPasswordlessResponse>;
+    /**
+     * Complete passwordless authentication by verifying the OTP or token.
+     *
+     * @param payload - Verification payload
+     * @param payload.email - User's email address
+     * @param payload.code - Verification code from email/SMS
+     * @param payload.scopes - Optional scopes to request
+     * @returns Promise with validation response containing tokens
+     * @throws {PassflowError} If verification fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const response = await passflow.passwordlessSignInComplete({
+     *     email: 'user@example.com',
+     *     code: '123456'
+     *   });
+     *   console.log('Passwordless sign-in complete', response.access_token);
+     * } catch (error) {
+     *   console.error('Invalid code', error.message);
+     * }
+     * ```
+     */
     passwordlessSignInComplete(payload: PassflowPasswordlessSignInCompletePayload): Promise<PassflowValidationResponse>;
+    /**
+     * Centralized error handler for all public methods.
+     * Creates proper ErrorPayload, distinguishes PassflowError from generic Error,
+     * notifies error event, and re-throws the error.
+     *
+     * @param error - The error to handle
+     * @param context - Context description for the error
+     * @throws The original error after handling
+     */
+    private handleError;
+    /**
+     * Sign out the current user and clear all tokens.
+     *
+     * @returns Promise that resolves when sign-out is complete
+     * @throws {PassflowError} If sign-out request fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await passflow.logOut();
+     *   console.log('User signed out successfully');
+     *   // Redirect to login page
+     * } catch (error) {
+     *   console.error('Sign out failed', error.message);
+     * }
+     * ```
+     */
     logOut(): Promise<void>;
+    /**
+     * Initiate federated authentication (OAuth) with a popup window.
+     *
+     * @param payload - Federated authentication configuration
+     * @param payload.provider - OAuth provider (e.g., 'google', 'github', 'microsoft')
+     * @param payload.scopes - Optional scopes to request
+     *
+     * @example
+     * ```typescript
+     * // Sign in with Google using a popup
+     * passflow.federatedAuthWithPopup({
+     *   provider: 'google'
+     * });
+     *
+     * // Listen for the result via subscribe
+     * passflow.subscribe((event, payload) => {
+     *   if (event === PassflowEvent.SignIn) {
+     *     console.log('OAuth sign-in successful', payload.tokens);
+     *   }
+     * });
+     * ```
+     */
     federatedAuthWithPopup(payload: PassflowFederatedAuthPayload): void;
+    /**
+     * Initiate federated authentication (OAuth) with a full-page redirect.
+     *
+     * @param payload - Federated authentication configuration
+     * @param payload.provider - OAuth provider (e.g., 'google', 'github', 'microsoft')
+     * @param payload.scopes - Optional scopes to request
+     * @param payload.redirectUrl - URL to redirect to after authentication
+     *
+     * @example
+     * ```typescript
+     * // Sign in with GitHub using redirect
+     * passflow.federatedAuthWithRedirect({
+     *   provider: 'github',
+     *   redirectUrl: window.location.origin + '/auth/callback'
+     * });
+     * ```
+     */
     federatedAuthWithRedirect(payload: PassflowFederatedAuthPayload): void;
+    /**
+     * Reset the SDK state by clearing all tokens and optionally throwing an error.
+     *
+     * @param error - Optional error message to throw after reset
+     * @throws {Error} If error message is provided
+     *
+     * @example
+     * ```typescript
+     * // Clear tokens without error
+     * passflow.reset();
+     *
+     * // Clear tokens and throw error
+     * try {
+     *   passflow.reset('Session expired');
+     * } catch (error) {
+     *   console.error('Reset error:', error.message);
+     * }
+     * ```
+     */
     reset(error?: string): void;
+    /**
+     * Refresh the access token using the refresh token.
+     *
+     * @returns Promise with new authorization response containing refreshed tokens
+     * @throws {Error} If no refresh token is found
+     * @throws {PassflowError} If refresh request fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const response = await passflow.refreshToken();
+     *   console.log('Token refreshed', response.access_token);
+     * } catch (error) {
+     *   console.error('Failed to refresh token', error.message);
+     *   // Redirect to login
+     * }
+     * ```
+     */
     refreshToken(): Promise<PassflowAuthorizationResponse>;
+    /**
+     * Send a password reset email to the user.
+     *
+     * @param payload - Password reset request
+     * @param payload.email - User's email address
+     * @returns Promise with success response
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await passflow.sendPasswordResetEmail({
+     *     email: 'user@example.com'
+     *   });
+     *   console.log('Password reset email sent');
+     * } catch (error) {
+     *   console.error('Failed to send reset email', error.message);
+     * }
+     * ```
+     */
     sendPasswordResetEmail(payload: PassflowSendPasswordResetEmailPayload): Promise<PassflowSuccessResponse>;
+    /**
+     * Reset password using a reset token (typically from URL after clicking email link).
+     *
+     * @param newPassword - The new password to set
+     * @param scopes - Optional scopes to request after reset
+     * @returns Promise with authorization response containing new tokens
+     * @throws {PassflowError} If reset fails
+     *
+     * @example
+     * ```typescript
+     * // On password reset page (e.g., /reset-password?token=xyz)
+     * try {
+     *   const response = await passflow.resetPassword('new-secure-password');
+     *   console.log('Password reset successful', response.access_token);
+     * } catch (error) {
+     *   console.error('Password reset failed', error.message);
+     * }
+     * ```
+     */
     resetPassword(newPassword: string, scopes?: string[]): Promise<PassflowAuthorizationResponse>;
+    /**
+     * Get application settings and configuration.
+     *
+     * @returns Promise with app settings including branding, features, and config
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const settings = await passflow.getAppSettings();
+     * console.log('App name:', settings.name);
+     * console.log('Passwordless enabled:', settings.passwordless_enabled);
+     * ```
+     */
     getAppSettings(): Promise<AppSettings>;
+    /**
+     * Get all Passflow settings including password policy, passkey settings, etc.
+     *
+     * @returns Promise with all settings
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const settings = await passflow.getSettingsAll();
+     * console.log('Password policy:', settings.password_policy);
+     * console.log('Passkey settings:', settings.passkey);
+     * ```
+     */
     getSettingsAll(): Promise<PassflowSettingsAll>;
+    /**
+     * Get password policy settings (min length, complexity requirements, etc.).
+     *
+     * @returns Promise with password policy configuration
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const policy = await passflow.getPasswordPolicySettings();
+     * console.log('Min length:', policy.min_length);
+     * console.log('Require uppercase:', policy.require_uppercase);
+     * ```
+     */
     getPasswordPolicySettings(): Promise<PassflowPasswordPolicySettings>;
+    /**
+     * Get passkey (WebAuthn) configuration settings.
+     *
+     * @returns Promise with passkey settings
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const passkeySettings = await passflow.getPasskeySettings();
+     * console.log('Passkeys enabled:', passkeySettings.enabled);
+     * console.log('User verification:', passkeySettings.user_verification);
+     * ```
+     */
     getPasskeySettings(): Promise<PassflowPasskeySettings>;
+    /**
+     * Register a new user with a passkey (WebAuthn).
+     *
+     * @param payload - Passkey registration configuration
+     * @param payload.email - User's email address
+     * @param payload.username - Optional username
+     * @param payload.scopes - Optional scopes to request
+     * @returns Promise with authorization response containing tokens
+     * @throws {PassflowError} If passkey registration fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const response = await passflow.passkeyRegister({
+     *     email: 'user@example.com',
+     *     username: 'myusername'
+     *   });
+     *   console.log('Passkey registered', response.access_token);
+     * } catch (error) {
+     *   console.error('Passkey registration failed', error.message);
+     * }
+     * ```
+     */
     passkeyRegister(payload: PassflowPasskeyRegisterStartPayload): Promise<PassflowAuthorizationResponse>;
+    /**
+     * Authenticate a user with a passkey (WebAuthn).
+     *
+     * @param payload - Passkey authentication configuration
+     * @param payload.email - Optional user email to pre-fill
+     * @param payload.scopes - Optional scopes to request
+     * @returns Promise with authorization response containing tokens
+     * @throws {PassflowError} If passkey authentication fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   // Let user select from available passkeys
+     *   const response = await passflow.passkeyAuthenticate({});
+     *   console.log('Passkey sign-in successful', response.access_token);
+     * } catch (error) {
+     *   console.error('Passkey authentication failed', error.message);
+     * }
+     * ```
+     */
     passkeyAuthenticate(payload: PassflowPasskeyAuthenticateStartPayload): Promise<PassflowAuthorizationResponse>;
+    /**
+     * Manually set tokens (useful after custom authentication flows).
+     * This will save tokens to storage, update cache, and trigger SignIn event.
+     *
+     * @param tokensData - Tokens object to set
+     * @param tokensData.access_token - JWT access token
+     * @param tokensData.refresh_token - Optional refresh token
+     * @param tokensData.id_token - Optional ID token
+     * @param tokensData.scopes - Token scopes
+     *
+     * @example
+     * ```typescript
+     * // Set tokens from a custom auth flow
+     * passflow.setTokens({
+     *   access_token: 'eyJhbGci...',
+     *   refresh_token: 'eyJhbGci...',
+     *   id_token: 'eyJhbGci...',
+     *   scopes: ['id', 'offline', 'email']
+     * });
+     * ```
+     */
     setTokens(tokensData: Tokens): void;
+    /**
+     * Get current tokens from storage, optionally refreshing if expired.
+     *
+     * @param doRefresh - If true, automatically refresh expired tokens (default: false)
+     * @returns Promise with tokens or undefined if not authenticated
+     *
+     * @example
+     * ```typescript
+     * // Get tokens without refresh
+     * const tokens = await passflow.getTokens();
+     *
+     * // Get tokens and auto-refresh if expired
+     * const freshTokens = await passflow.getTokens(true);
+     * ```
+     */
     getTokens(doRefresh?: boolean): Promise<Tokens | undefined>;
+    /**
+     * Get a specific token from storage by type.
+     *
+     * @param tokenType - Type of token to retrieve ('access_token', 'refresh_token', 'id_token')
+     * @returns Token string or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const accessToken = passflow.getToken('access_token');
+     * if (accessToken) {
+     *   // Use token for API calls
+     *   fetch('/api/data', {
+     *     headers: { Authorization: `Bearer ${accessToken}` }
+     *   });
+     * }
+     * ```
+     */
     getToken(tokenType: TokenType): string | undefined;
+    /**
+     * Get list of passkeys registered for the current user.
+     *
+     * @returns Promise with array of user's passkeys
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const passkeys = await passflow.getUserPasskeys();
+     * passkeys.forEach(passkey => {
+     *   console.log('Passkey:', passkey.name, passkey.id);
+     * });
+     * ```
+     */
     getUserPasskeys(): Promise<import("./api").PassflowUserPasskey[]>;
+    /**
+     * Rename a user's passkey to a friendly name.
+     *
+     * @param name - New friendly name for the passkey
+     * @param passkeyId - ID of the passkey to rename
+     * @returns Promise with success response
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * await passflow.renameUserPasskey('My MacBook Pro', 'passkey-123');
+     * console.log('Passkey renamed successfully');
+     * ```
+     */
     renameUserPasskey(name: string, passkeyId: string): Promise<PassflowSuccessResponse>;
+    /**
+     * Delete a passkey from the user's account.
+     *
+     * @param passkeyId - ID of the passkey to delete
+     * @returns Promise with success response
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * await passflow.deleteUserPasskey('passkey-123');
+     * console.log('Passkey deleted successfully');
+     * ```
+     */
     deleteUserPasskey(passkeyId: string): Promise<PassflowSuccessResponse>;
+    /**
+     * Add a new passkey to the current user's account (requires active session).
+     *
+     * @param options - Optional passkey configuration
+     * @param options.relyingPartyId - Optional RP ID for the passkey
+     * @param options.passkeyUsername - Optional username to associate with passkey
+     * @param options.passkeyDisplayName - Optional display name for the passkey
+     * @returns Promise that resolves when passkey is added
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * // Add passkey with default settings
+     * await passflow.addUserPasskey();
+     *
+     * // Add passkey with custom display name
+     * await passflow.addUserPasskey({
+     *   passkeyDisplayName: 'My iPhone'
+     * });
+     * ```
+     */
     addUserPasskey(options?: {
         relyingPartyId?: string;
         passkeyUsername?: string;
@@ -84,6 +700,26 @@ export declare class Passflow {
      * @returns Promise with tenant response
      */
     createTenant(name: string, refreshToken?: boolean): Promise<PassflowTenantResponse>;
+    /**
+     * Request an invitation link for a user to join a tenant.
+     *
+     * @param payload - Invitation request configuration
+     * @param payload.email - Email address to send invitation to
+     * @param payload.tenantID - Tenant ID for the invitation
+     * @param payload.send_to_email - Whether to send email automatically (default: true)
+     * @returns Promise with invitation link response
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const invitation = await passflow.requestInviteLink({
+     *   email: 'newuser@example.com',
+     *   tenantID: 'tenant-123',
+     *   send_to_email: true
+     * });
+     * console.log('Invitation link:', invitation.link);
+     * ```
+     */
     requestInviteLink(payload: RequestInviteLinkPayload): Promise<InviteLinkResponse>;
     /**
      * Gets a list of active invitations
@@ -96,20 +732,345 @@ export declare class Passflow {
         skip?: number | string;
         limit?: number | string;
     }): Promise<InvitationsPaginatedList>;
+    /**
+     * Delete an invitation by its token.
+     *
+     * @param token - Invitation token to delete
+     * @returns Promise with success response
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * await passflow.deleteInvitation('invitation-token-123');
+     * console.log('Invitation deleted');
+     * ```
+     */
     deleteInvitation(token: string): Promise<PassflowSuccessResponse>;
+    /**
+     * Resend an invitation email.
+     *
+     * @param token - Invitation token to resend
+     * @returns Promise with success response
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * await passflow.resendInvitation('invitation-token-123');
+     * console.log('Invitation email resent');
+     * ```
+     */
     resendInvitation(token: string): Promise<PassflowSuccessResponse>;
+    /**
+     * Get invitation details and link by invitation ID.
+     *
+     * @param invitationID - Invitation ID to retrieve
+     * @returns Promise with invitation link response
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const invitation = await passflow.getInvitationLink('invitation-123');
+     * console.log('Invitation link:', invitation.link);
+     * ```
+     */
     getInvitationLink(invitationID: string): Promise<InviteLinkResponse>;
+    /**
+     * Generate an authentication redirect URL for hosted login.
+     *
+     * @param options - Redirect URL configuration
+     * @param options.url - Optional custom Passflow server URL
+     * @param options.redirectUrl - URL to redirect to after authentication
+     * @param options.scopes - Optional scopes to request
+     * @param options.appId - Optional app ID to use
+     * @returns Authentication redirect URL
+     *
+     * @example
+     * ```typescript
+     * const authUrl = passflow.authRedirectUrl({
+     *   redirectUrl: window.location.origin + '/auth/callback',
+     *   scopes: ['id', 'email', 'offline']
+     * });
+     * console.log('Auth URL:', authUrl);
+     * // Use this URL for custom navigation logic
+     * ```
+     */
     authRedirectUrl(options?: {
         url?: string;
         redirectUrl?: string;
         scopes?: string[];
         appId?: string;
     }): string;
+    /**
+     * Redirect to the Passflow hosted login page.
+     *
+     * @param options - Redirect configuration
+     * @param options.url - Optional custom Passflow server URL
+     * @param options.redirectUrl - URL to redirect to after authentication
+     * @param options.scopes - Optional scopes to request
+     * @param options.appId - Optional app ID to use
+     *
+     * @example
+     * ```typescript
+     * // Redirect to hosted login page
+     * passflow.authRedirect({
+     *   redirectUrl: window.location.origin + '/auth/callback'
+     * });
+     * ```
+     */
     authRedirect(options?: {
         url?: string;
         redirectUrl?: string;
         scopes?: string[];
         appId?: string;
     }): void;
+    /**
+     * Get the current token delivery mode.
+     * Returns the mode determined by the server (json_body, cookie, or mobile).
+     *
+     * @returns The current token delivery mode
+     *
+     * @example
+     * ```typescript
+     * import { TokenDeliveryMode } from '@passflow/core';
+     *
+     * const mode = passflow.getDeliveryMode();
+     * if (mode === TokenDeliveryMode.Cookie) {
+     *   console.log('Using cookie-based authentication');
+     * } else {
+     *   console.log('Using JSON body authentication');
+     * }
+     * ```
+     */
+    getDeliveryMode(): import('./token/delivery-manager').TokenDeliveryMode;
+    /**
+     * Restore and validate session for cookie mode on page load.
+     * Only applicable when using cookie-based token delivery.
+     * Validates that HttpOnly cookies are still valid with the server.
+     *
+     * This method is automatically called on SDK initialization for cookie mode,
+     * but can be called manually to re-validate the session.
+     *
+     * @returns Promise resolving to true if session is valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Check if session is valid (useful after page reload)
+     * const isValid = await passflow.restoreSession();
+     * if (isValid) {
+     *   console.log('Session restored successfully');
+     * } else {
+     *   console.log('Session expired, please sign in again');
+     * }
+     * ```
+     */
+    restoreSession(): Promise<boolean>;
+    /**
+     * Get the current 2FA enrollment status for the authenticated user.
+     *
+     * @returns Promise with 2FA status including enabled state and policy
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const status = await passflow.getTwoFactorStatus();
+     * console.log('2FA enabled:', status.enabled);
+     * console.log('Recovery codes remaining:', status.recovery_codes_remaining);
+     * ```
+     */
+    getTwoFactorStatus(): Promise<TwoFactorStatusResponse>;
+    /**
+     * Begin the 2FA setup process for the authenticated user.
+     * Returns a secret and QR code to scan with an authenticator app.
+     *
+     * @returns Promise with setup response containing secret and QR code
+     * @throws {PassflowError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const setup = await passflow.beginTwoFactorSetup();
+     * console.log('Scan this QR code:', setup.qr_code);
+     * console.log('Or enter this secret:', setup.secret);
+     * ```
+     */
+    beginTwoFactorSetup(): Promise<TwoFactorSetupResponse>;
+    /**
+     * Confirm 2FA setup by verifying a TOTP code from the authenticator app.
+     * Returns recovery codes that MUST be saved by the user.
+     *
+     * @param code - 6-digit TOTP code from authenticator app
+     * @returns Promise with confirmation response including recovery codes
+     * @throws {PassflowError} If verification fails
+     *
+     * @example
+     * ```typescript
+     * const result = await passflow.confirmTwoFactorSetup('123456');
+     * console.log('SAVE THESE RECOVERY CODES:', result.recovery_codes);
+     * // Display recovery codes to user for safekeeping
+     * ```
+     */
+    confirmTwoFactorSetup(code: string): Promise<TwoFactorConfirmResponse>;
+    /**
+     * Verify a TOTP code during login when 2FA is required.
+     * Completes the authentication process and saves tokens.
+     *
+     * @param code - 6-digit TOTP code from authenticator app
+     * @returns Promise with verification response containing tokens
+     * @throws {PassflowError} If verification fails
+     *
+     * @example
+     * ```typescript
+     * // After signIn returns requires_2fa: true
+     * if (passflow.isTwoFactorVerificationRequired()) {
+     *   const response = await passflow.verifyTwoFactor('123456');
+     *   console.log('Authentication complete', response.access_token);
+     * }
+     * ```
+     */
+    verifyTwoFactor(code: string): Promise<TwoFactorVerifyResponse>;
+    /**
+     * Use a recovery code for authentication when TOTP is unavailable.
+     * Completes the authentication process and saves tokens.
+     *
+     * @param code - Recovery code from the list provided during setup
+     * @returns Promise with recovery response containing tokens and remaining codes count
+     * @throws {PassflowError} If recovery code is invalid
+     *
+     * @example
+     * ```typescript
+     * // After signIn returns requires_2fa: true
+     * const result = await passflow.useTwoFactorRecoveryCode('ABCD-1234');
+     * console.log('Authenticated with recovery code');
+     * console.log(`${result.remaining_recovery_codes} recovery codes remaining`);
+     * ```
+     */
+    useTwoFactorRecoveryCode(code: string): Promise<TwoFactorRecoveryResponse>;
+    /**
+     * Disable 2FA for the authenticated user.
+     * Requires verification with a current TOTP code.
+     *
+     * @param code - Current 6-digit TOTP code for verification
+     * @returns Promise with success response
+     * @throws {PassflowError} If verification fails
+     *
+     * @example
+     * ```typescript
+     * await passflow.disableTwoFactor('123456');
+     * console.log('2FA disabled successfully');
+     * ```
+     */
+    disableTwoFactor(code: string): Promise<TwoFactorDisableResponse>;
+    /**
+     * Regenerate recovery codes for the authenticated user.
+     * Old recovery codes will be invalidated. Requires verification with a current TOTP code.
+     *
+     * @param code - Current 6-digit TOTP code for verification
+     * @returns Promise with response containing new recovery codes
+     * @throws {PassflowError} If verification fails
+     *
+     * @example
+     * ```typescript
+     * const result = await passflow.regenerateTwoFactorRecoveryCodes('123456');
+     * console.log('New recovery codes:', result.recovery_codes);
+     * // Display new recovery codes to user for safekeeping
+     * ```
+     */
+    regenerateTwoFactorRecoveryCodes(code: string): Promise<TwoFactorRegenerateResponse>;
+    /**
+     * Check if 2FA verification is currently required (local state check).
+     * Returns true if user has signed in but needs to complete 2FA verification.
+     *
+     * @returns True if 2FA verification is pending, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (passflow.isTwoFactorVerificationRequired()) {
+     *   // Show 2FA code input UI
+     *   console.log('Please enter your 2FA code');
+     * }
+     * ```
+     */
+    isTwoFactorVerificationRequired(): boolean;
+    /**
+     * Get configured TOTP digit count for the current app
+     * @returns Number of digits (6 or 8) configured for TOTP codes
+     *
+     * @example
+     * ```typescript
+     * const digits = passflow.getTotpDigits();
+     * console.log(`TOTP codes should be ${digits} digits`);
+     * ```
+     */
+    getTotpDigits(): 6 | 8;
+    /**
+     * Validate a magic link token for 2FA setup.
+     * Used when a user clicks on an admin-generated magic link to set up 2FA.
+     *
+     * The magic link creates a scoped session that can ONLY be used for 2FA setup,
+     * not for regular authentication.
+     *
+     * @param token - Magic link token from URL parameter
+     * @returns Promise with validation response containing scoped session or error
+     *
+     * @example
+     * ```typescript
+     * // On the magic link landing page (e.g., /2fa-setup/:token)
+     * const urlToken = extractTokenFromUrl();
+     * const result = await passflow.validateTwoFactorSetupMagicLink(urlToken);
+     *
+     * if (result.success) {
+     *   console.log('Magic link validated');
+     *   console.log('User ID:', result.userId);
+     *   console.log('Session expires in:', result.expiresIn, 'seconds');
+     *   // Show 2FA setup form
+     * } else {
+     *   console.error('Validation failed:', result.error?.message);
+     *   // Show error UI
+     * }
+     * ```
+     */
+    validateTwoFactorSetupMagicLink(token: string): Promise<import('./api/model').TwoFactorSetupMagicLinkValidationResponse>;
+    /**
+     * Get the current magic link session (if any).
+     * Used by React SDK components to access session data.
+     *
+     * @returns Active magic link session or null if none/expired
+     *
+     * @example
+     * ```typescript
+     * const session = passflow.getMagicLinkSession();
+     * if (session) {
+     *   console.log('Active session for user:', session.userId);
+     *   console.log('Expires at:', new Date(session.expiresAt));
+     * }
+     * ```
+     */
+    getMagicLinkSession(): import('./api/model').TwoFactorSetupMagicLinkSession | null;
+    /**
+     * Check if a magic link session is currently active.
+     *
+     * @returns True if magic link session is active and not expired
+     *
+     * @example
+     * ```typescript
+     * if (passflow.hasMagicLinkSession()) {
+     *   // User can proceed with 2FA setup
+     * } else {
+     *   // Redirect to error page or request new link
+     * }
+     * ```
+     */
+    hasMagicLinkSession(): boolean;
+    /**
+     * Clear the magic link session.
+     * Called after successful 2FA setup or on error.
+     *
+     * @example
+     * ```typescript
+     * // After 2FA setup is complete
+     * passflow.clearMagicLinkSession();
+     * // Redirect to sign-in
+     * ```
+     */
+    clearMagicLinkSession(): void;
 }
 //# sourceMappingURL=passflow.d.ts.map