@55387.ai/uniauth-client 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,500 @@
+/**
+ * HTTP Utilities for UniAuth Client SDK
+ * UniAuth 客户端 SDK HTTP 工具
+ *
+ * Provides robust HTTP request handling with:
+ * - Automatic retry with exponential backoff
+ * - Timeout handling
+ * - Request/response interceptors
+ */
+/**
+ * HTTP fetch options with retry configuration
+ */
+interface FetchWithRetryOptions extends RequestInit {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Base delay in ms between retries (default: 500) */
+    baseDelay?: number;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+    /** HTTP status codes that should trigger a retry (default: [408, 429, 500, 502, 503, 504]) */
+    retryStatusCodes?: number[];
+}
+/**
+ * Fetch with automatic retry and exponential backoff
+ * 带自动重试和指数退避的 fetch
+ *
+ * @param url - The URL to fetch
+ * @param options - Fetch options with retry configuration
+ * @returns The fetch response
+ * @throws Error if all retries fail
+ */
+declare function fetchWithRetry(url: string, options?: FetchWithRetryOptions): Promise<Response>;
+/**
+ * PKCE (Proof Key for Code Exchange) utilities
+ * PKCE 工具函数
+ */
+/**
+ * Generate a cryptographically random code verifier
+ * 生成加密随机的 code_verifier
+ */
+declare function generateCodeVerifier(): string;
+/**
+ * Generate code challenge from verifier using SHA-256
+ * 使用 SHA-256 从 verifier 生成 code_challenge
+ */
+declare function generateCodeChallenge(verifier: string): Promise<string>;
+/**
+ * Store PKCE code verifier for later use
+ * 存储 PKCE code_verifier 以供后续使用
+ */
+declare function storeCodeVerifier(verifier: string, storageKey?: string): void;
+/**
+ * Retrieve and clear stored PKCE code verifier
+ * 获取并清除存储的 PKCE code_verifier
+ */
+declare function getAndClearCodeVerifier(storageKey?: string): string | null;
+
+/**
+ * UniAuth Client SDK
+ * 统一认证前端 SDK
+ *
+ * Usage:
+ * ```typescript
+ * import { UniAuthClient } from '@uniauth/client';
+ *
+ * const auth = new UniAuthClient({
+ *   baseUrl: 'https://auth.example.com',
+ *   appKey: 'your-app-key',
+ * });
+ *
+ * // Send verification code
+ * await auth.sendCode('+8613800138000');
+ *
+ * // Login with code
+ * const result = await auth.loginWithCode('+8613800138000', '123456');
+ *
+ * // Get current user
+ * const user = await auth.getCurrentUser();
+ *
+ * // Logout
+ * await auth.logout();
+ * ```
+ */
+interface UniAuthConfig {
+    /** API base URL */
+    baseUrl: string;
+    /** Application key */
+    appKey?: string;
+    /** OAuth2 Client ID (for OAuth flows) */
+    clientId?: string;
+    /** Storage type for tokens */
+    storage?: 'localStorage' | 'sessionStorage' | 'memory';
+    /** Callback when tokens are refreshed */
+    onTokenRefresh?: (tokens: TokenPair) => void;
+    /** Callback when auth error occurs */
+    onAuthError?: (error: AuthError) => void;
+    /** Enable request retry with exponential backoff */
+    enableRetry?: boolean;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+}
+interface UserInfo {
+    id: string;
+    phone: string | null;
+    email: string | null;
+    nickname: string | null;
+    avatar_url: string | null;
+}
+interface TokenPair {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+}
+interface LoginResult {
+    user: UserInfo;
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    is_new_user: boolean;
+    /** MFA is required, use mfa_token with verifyMFA() */
+    mfa_required?: boolean;
+    /** Temporary token for MFA verification */
+    mfa_token?: string;
+    /** Available MFA methods */
+    mfa_methods?: string[];
+}
+interface SendCodeResult {
+    expires_in: number;
+    retry_after: number;
+}
+interface AuthError {
+    code: string;
+    message: string;
+}
+interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    message?: string;
+    error?: AuthError;
+}
+/**
+ * OAuth Provider Information
+ * OAuth 提供商信息
+ */
+interface OAuthProvider {
+    id: string;
+    name: string;
+    enabled: boolean;
+    icon?: string;
+}
+/**
+ * Auth state change callback
+ * 认证状态变更回调
+ */
+type AuthStateChangeCallback = (user: UserInfo | null, isAuthenticated: boolean) => void;
+/**
+ * Error codes for UniAuth operations
+ * UniAuth 操作错误码
+ */
+declare const AuthErrorCode: {
+    readonly SEND_CODE_FAILED: "SEND_CODE_FAILED";
+    readonly VERIFY_FAILED: "VERIFY_FAILED";
+    readonly LOGIN_FAILED: "LOGIN_FAILED";
+    readonly OAUTH_FAILED: "OAUTH_FAILED";
+    readonly MFA_REQUIRED: "MFA_REQUIRED";
+    readonly MFA_FAILED: "MFA_FAILED";
+    readonly REGISTER_FAILED: "REGISTER_FAILED";
+    readonly NOT_AUTHENTICATED: "NOT_AUTHENTICATED";
+    readonly TOKEN_EXPIRED: "TOKEN_EXPIRED";
+    readonly REFRESH_FAILED: "REFRESH_FAILED";
+    readonly CONFIG_ERROR: "CONFIG_ERROR";
+    readonly SSO_NOT_CONFIGURED: "SSO_NOT_CONFIGURED";
+    readonly INVALID_STATE: "INVALID_STATE";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+};
+type AuthErrorCodeType = typeof AuthErrorCode[keyof typeof AuthErrorCode];
+/**
+ * Custom error class for UniAuth operations
+ * UniAuth 操作自定义错误类
+ */
+declare class UniAuthError extends Error {
+    code: AuthErrorCodeType | string;
+    statusCode?: number;
+    details?: unknown;
+    constructor(code: AuthErrorCodeType | string, message: string, statusCode?: number, details?: unknown);
+}
+interface OAuth2AuthorizeOptions {
+    redirectUri: string;
+    scope?: string;
+    state?: string;
+    /** Use PKCE (recommended for public clients) */
+    usePKCE?: boolean;
+}
+interface OAuth2TokenResult {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token?: string;
+}
+/**
+ * SSO Configuration
+ * SSO 配置
+ */
+interface SSOConfig {
+    /** SSO service URL (e.g., https://sso.example.com) */
+    ssoUrl: string;
+    /** OAuth client ID for this application */
+    clientId: string;
+    /** Redirect URI after SSO login */
+    redirectUri: string;
+    /** OAuth scope (default: 'openid profile email') */
+    scope?: string;
+}
+/**
+ * SSO Login Options
+ * SSO 登录选项
+ */
+interface SSOLoginOptions {
+    /** Use PKCE (recommended, default: true) */
+    usePKCE?: boolean;
+    /** Custom state parameter */
+    state?: string;
+    /** Whether to use popup instead of redirect */
+    usePopup?: boolean;
+}
+/**
+ * UniAuth Client
+ * 统一认证客户端
+ */
+declare class UniAuthClient {
+    private config;
+    private storage;
+    private refreshPromise;
+    constructor(config: UniAuthConfig);
+    /**
+     * Send verification code to phone number
+     * 发送验证码到手机号
+     */
+    sendCode(phone: string, type?: 'login' | 'register' | 'reset'): Promise<SendCodeResult>;
+    /**
+     * Send verification code to email
+     * 发送验证码到邮箱
+     */
+    sendEmailCode(email: string, type?: 'login' | 'register' | 'reset' | 'email_verify'): Promise<SendCodeResult>;
+    /**
+     * Login with phone verification code
+     * 使用手机验证码登录
+     */
+    loginWithCode(phone: string, code: string): Promise<LoginResult>;
+    /**
+     * Login with email verification code
+     * 使用邮箱验证码登录
+     */
+    loginWithEmailCode(email: string, code: string): Promise<LoginResult>;
+    /**
+     * Login with email and password
+     * 使用邮箱密码登录
+     */
+    loginWithEmail(email: string, password: string): Promise<LoginResult>;
+    /**
+     * Handle OAuth callback (for social login)
+     * 处理 OAuth 回调（社交登录）
+     */
+    handleOAuthCallback(provider: string, code: string): Promise<LoginResult>;
+    /**
+     * Register with email and password
+     * 使用邮箱密码注册
+     */
+    registerWithEmail(email: string, password: string, nickname?: string): Promise<LoginResult>;
+    /**
+     * Verify MFA code to complete login
+     * 验证 MFA 验证码完成登录
+     *
+     * Call this after login returns mfa_required: true
+     * 当登录返回 mfa_required: true 时调用此方法
+     *
+     * @example
+     * ```typescript
+     * const result = await auth.loginWithCode(phone, code);
+     * if (result.mfa_required) {
+     *   const mfaCode = prompt('Enter MFA code:');
+     *   const finalResult = await auth.verifyMFA(result.mfa_token!, mfaCode);
+     * }
+     * ```
+     */
+    verifyMFA(mfaToken: string, code: string): Promise<LoginResult>;
+    /**
+     * Get available OAuth providers
+     * 获取可用的 OAuth 提供商列表
+     */
+    getOAuthProviders(): Promise<OAuthProvider[]>;
+    /**
+     * Start social login (redirect to OAuth provider)
+     * 开始社交登录（重定向到 OAuth 提供商）
+     *
+     * @param provider - OAuth provider ID (e.g., 'google', 'github', 'wechat')
+     * @param redirectUri - Where to redirect after OAuth (optional, uses default)
+     *
+     * @example
+     * ```typescript
+     * // Redirect user to Google login
+     * auth.startSocialLogin('google');
+     * ```
+     */
+    startSocialLogin(provider: string, redirectUri?: string): void;
+    private authStateCallbacks;
+    private currentUser;
+    /**
+     * Subscribe to auth state changes
+     * 订阅认证状态变更
+     *
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = auth.onAuthStateChange((user, isAuthenticated) => {
+     *   if (isAuthenticated) {
+     *     console.log('User logged in:', user);
+     *   } else {
+     *     console.log('User logged out');
+     *   }
+     * });
+     *
+     * // Later, to unsubscribe:
+     * unsubscribe();
+     * ```
+     */
+    onAuthStateChange(callback: AuthStateChangeCallback): () => void;
+    /**
+     * Notify all subscribers of auth state change
+     * 通知所有订阅者认证状态变更
+     */
+    private notifyAuthStateChange;
+    /**
+     * Get cached current user (sync, may be stale)
+     * 获取缓存的当前用户（同步，可能过时）
+     */
+    getCachedUser(): UserInfo | null;
+    /**
+     * Get access token synchronously (without refresh check)
+     * 同步获取访问令牌（不检查刷新）
+     */
+    getAccessTokenSync(): string | null;
+    /**
+     * Check if current token is valid (not expired)
+     * 检查当前令牌是否有效（未过期）
+     */
+    isTokenValid(): boolean;
+    /**
+     * Get current user info
+     * 获取当前用户信息
+     */
+    getCurrentUser(): Promise<UserInfo | null>;
+    /**
+     * Update user profile
+     * 更新用户资料
+     */
+    updateProfile(updates: Partial<Pick<UserInfo, 'nickname' | 'avatar_url'>>): Promise<UserInfo>;
+    /**
+     * Get access token (auto-refresh if needed)
+     * 获取访问令牌（如需要则自动刷新）
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * Check if user is authenticated
+     * 检查用户是否已认证
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Logout current session
+     * 登出当前会话
+     */
+    logout(): Promise<void>;
+    /**
+     * Logout from all devices
+     * 从所有设备登出
+     */
+    logoutAll(): Promise<void>;
+    /**
+     * Start OAuth2 authorization flow
+     * 开始 OAuth2 授权流程
+     */
+    startOAuth2Flow(options: OAuth2AuthorizeOptions): Promise<string>;
+    /**
+     * Exchange authorization code for tokens (OAuth2 client flow)
+     * 使用授权码换取令牌
+     */
+    exchangeOAuth2Code(code: string, redirectUri: string, clientSecret?: string): Promise<OAuth2TokenResult>;
+    private ssoConfig;
+    /**
+     * Configure SSO settings
+     * 配置 SSO 设置
+     *
+     * @example
+     * ```typescript
+     * auth.configureSso({
+     *   ssoUrl: 'https://sso.55387.xyz',
+     *   clientId: 'my-app',
+     *   redirectUri: 'https://my-app.com/auth/callback',
+     * });
+     * ```
+     */
+    configureSso(config: SSOConfig): void;
+    /**
+     * Start SSO login flow
+     * 开始 SSO 登录流程
+     *
+     * This will redirect the user to the SSO service.
+     * If the user already has an SSO session, they'll be automatically logged in (silent auth).
+     *
+     * @example
+     * ```typescript
+     * // Simple usage - redirects to SSO
+     * auth.loginWithSSO();
+     *
+     * // With options
+     * auth.loginWithSSO({ usePKCE: true });
+     * ```
+     */
+    loginWithSSO(options?: SSOLoginOptions): void;
+    /**
+     * Check if current URL is an SSO callback
+     * 检查当前 URL 是否是 SSO 回调
+     *
+     * @example
+     * ```typescript
+     * if (auth.isSSOCallback()) {
+     *   await auth.handleSSOCallback();
+     * }
+     * ```
+     */
+    isSSOCallback(): boolean;
+    /**
+     * Handle SSO callback and exchange code for tokens
+     * 处理 SSO 回调并交换授权码获取令牌
+     *
+     * Call this on your callback page after SSO redirects back.
+     *
+     * @returns LoginResult or null if callback handling failed
+     *
+     * @example
+     * ```typescript
+     * // In your callback page component
+     * useEffect(() => {
+     *   if (auth.isSSOCallback()) {
+     *     auth.handleSSOCallback()
+     *       .then(result => {
+     *         if (result) {
+     *           navigate('/dashboard');
+     *         }
+     *       })
+     *       .catch(err => console.error('SSO login failed:', err));
+     *   }
+     * }, []);
+     * ```
+     */
+    handleSSOCallback(): Promise<LoginResult | null>;
+    /**
+     * Check if user can be silently authenticated via SSO
+     * 检查用户是否可以通过 SSO 静默登录
+     *
+     * This starts a silent SSO flow using an iframe to check if user has an active SSO session.
+     *
+     * @returns Promise that resolves to true if silent auth succeeded
+     */
+    checkSSOSession(): Promise<boolean>;
+    private generateRandomState;
+    private storeState;
+    private getAndClearState;
+    /**
+     * Exchange SSO authorization code for tokens
+     * This is a private method used internally by handleSSOCallback
+     */
+    private exchangeSSOCode;
+    /**
+     * Refresh tokens
+     * 刷新令牌
+     */
+    private refreshTokens;
+    private doRefreshTokens;
+    /**
+     * Make an authenticated request
+     * 发起已认证的请求
+     */
+    private authenticatedRequest;
+    /**
+     * Make a request to the API with retry support
+     * 向 API 发起请求（支持重试）
+     */
+    private request;
+    /**
+     * Create an error object
+     * 创建错误对象
+     */
+    private createError;
+}
+
+export { type ApiResponse, type AuthError, AuthErrorCode, type AuthErrorCodeType, type AuthStateChangeCallback, type LoginResult, type OAuth2AuthorizeOptions, type OAuth2TokenResult, type OAuthProvider, type SSOConfig, type SSOLoginOptions, type SendCodeResult, type TokenPair, UniAuthClient, type UniAuthConfig, UniAuthError, type UserInfo, UniAuthClient as default, fetchWithRetry, generateCodeChallenge, generateCodeVerifier, getAndClearCodeVerifier, storeCodeVerifier };