@55387.ai/uniauth-client 1.0.0

package/dist/index.js

@@ -0,0 +1,986 @@
+// src/http.ts
+var DEFAULT_RETRY_STATUS_CODES = [
+  408,
+  // Request Timeout
+  429,
+  // Too Many Requests
+  500,
+  // Internal Server Error
+  502,
+  // Bad Gateway
+  503,
+  // Service Unavailable
+  504
+  // Gateway Timeout
+];
+async function fetchWithRetry(url, options = {}) {
+  const {
+    maxRetries = 3,
+    baseDelay = 500,
+    timeout = 3e4,
+    retryStatusCodes = DEFAULT_RETRY_STATUS_CODES,
+    ...fetchOptions
+  } = options;
+  let lastError = null;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout);
+      const response = await fetch(url, {
+        ...fetchOptions,
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (retryStatusCodes.includes(response.status) && attempt < maxRetries) {
+        const retryAfter = response.headers.get("Retry-After");
+        const delay = retryAfter ? parseRetryAfter(retryAfter) : calculateBackoffDelay(attempt, baseDelay);
+        await sleep(delay);
+        continue;
+      }
+      return response;
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+      if (lastError.name === "AbortError" && attempt >= maxRetries) {
+        throw new Error(`Request timeout after ${timeout}ms`);
+      }
+      if (attempt < maxRetries) {
+        const delay = calculateBackoffDelay(attempt, baseDelay);
+        await sleep(delay);
+      }
+    }
+  }
+  throw lastError || new Error("Request failed after all retries");
+}
+function calculateBackoffDelay(attempt, baseDelay) {
+  const exponentialDelay = baseDelay * Math.pow(2, attempt);
+  const jitter = exponentialDelay * 0.25 * (Math.random() * 2 - 1);
+  return Math.min(exponentialDelay + jitter, 3e4);
+}
+function parseRetryAfter(value) {
+  const seconds = parseInt(value, 10);
+  if (!isNaN(seconds)) {
+    return seconds * 1e3;
+  }
+  const date = new Date(value);
+  if (!isNaN(date.getTime())) {
+    const delay = date.getTime() - Date.now();
+    return Math.max(delay, 0);
+  }
+  return 1e3;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function generateCodeVerifier() {
+  const array = new Uint8Array(32);
+  crypto.getRandomValues(array);
+  return base64UrlEncode(array);
+}
+async function generateCodeChallenge(verifier) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(verifier);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  return base64UrlEncode(new Uint8Array(digest));
+}
+function base64UrlEncode(array) {
+  let binary = "";
+  for (let i = 0; i < array.byteLength; i++) {
+    binary += String.fromCharCode(array[i]);
+  }
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function storeCodeVerifier(verifier, storageKey = "uniauth_pkce_verifier") {
+  if (typeof sessionStorage !== "undefined") {
+    sessionStorage.setItem(storageKey, verifier);
+  }
+}
+function getAndClearCodeVerifier(storageKey = "uniauth_pkce_verifier") {
+  if (typeof sessionStorage !== "undefined") {
+    const verifier = sessionStorage.getItem(storageKey);
+    sessionStorage.removeItem(storageKey);
+    return verifier;
+  }
+  return null;
+}
+
+// src/index.ts
+var AuthErrorCode = {
+  // Authentication errors
+  SEND_CODE_FAILED: "SEND_CODE_FAILED",
+  VERIFY_FAILED: "VERIFY_FAILED",
+  LOGIN_FAILED: "LOGIN_FAILED",
+  OAUTH_FAILED: "OAUTH_FAILED",
+  MFA_REQUIRED: "MFA_REQUIRED",
+  MFA_FAILED: "MFA_FAILED",
+  REGISTER_FAILED: "REGISTER_FAILED",
+  // Token errors
+  NOT_AUTHENTICATED: "NOT_AUTHENTICATED",
+  TOKEN_EXPIRED: "TOKEN_EXPIRED",
+  REFRESH_FAILED: "REFRESH_FAILED",
+  // Configuration errors
+  CONFIG_ERROR: "CONFIG_ERROR",
+  SSO_NOT_CONFIGURED: "SSO_NOT_CONFIGURED",
+  INVALID_STATE: "INVALID_STATE",
+  // Network errors
+  NETWORK_ERROR: "NETWORK_ERROR",
+  TIMEOUT: "TIMEOUT",
+  INTERNAL_ERROR: "INTERNAL_ERROR"
+};
+var UniAuthError = class _UniAuthError extends Error {
+  code;
+  statusCode;
+  details;
+  constructor(code, message, statusCode, details) {
+    super(message);
+    this.name = "UniAuthError";
+    this.code = code;
+    this.statusCode = statusCode;
+    this.details = details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _UniAuthError);
+    }
+  }
+};
+var LocalStorageAdapter = class {
+  accessTokenKey = "uniauth_access_token";
+  refreshTokenKey = "uniauth_refresh_token";
+  getAccessToken() {
+    if (typeof localStorage === "undefined") return null;
+    return localStorage.getItem(this.accessTokenKey);
+  }
+  setAccessToken(token) {
+    if (typeof localStorage === "undefined") return;
+    localStorage.setItem(this.accessTokenKey, token);
+  }
+  getRefreshToken() {
+    if (typeof localStorage === "undefined") return null;
+    return localStorage.getItem(this.refreshTokenKey);
+  }
+  setRefreshToken(token) {
+    if (typeof localStorage === "undefined") return;
+    localStorage.setItem(this.refreshTokenKey, token);
+  }
+  clear() {
+    if (typeof localStorage === "undefined") return;
+    localStorage.removeItem(this.accessTokenKey);
+    localStorage.removeItem(this.refreshTokenKey);
+  }
+};
+var SessionStorageAdapter = class {
+  accessTokenKey = "uniauth_access_token";
+  refreshTokenKey = "uniauth_refresh_token";
+  getAccessToken() {
+    if (typeof sessionStorage === "undefined") return null;
+    return sessionStorage.getItem(this.accessTokenKey);
+  }
+  setAccessToken(token) {
+    if (typeof sessionStorage === "undefined") return;
+    sessionStorage.setItem(this.accessTokenKey, token);
+  }
+  getRefreshToken() {
+    if (typeof sessionStorage === "undefined") return null;
+    return sessionStorage.getItem(this.refreshTokenKey);
+  }
+  setRefreshToken(token) {
+    if (typeof sessionStorage === "undefined") return;
+    sessionStorage.setItem(this.refreshTokenKey, token);
+  }
+  clear() {
+    if (typeof sessionStorage === "undefined") return;
+    sessionStorage.removeItem(this.accessTokenKey);
+    sessionStorage.removeItem(this.refreshTokenKey);
+  }
+};
+var MemoryStorageAdapter = class {
+  accessToken = null;
+  refreshToken = null;
+  getAccessToken() {
+    return this.accessToken;
+  }
+  setAccessToken(token) {
+    this.accessToken = token;
+  }
+  getRefreshToken() {
+    return this.refreshToken;
+  }
+  setRefreshToken(token) {
+    this.refreshToken = token;
+  }
+  clear() {
+    this.accessToken = null;
+    this.refreshToken = null;
+  }
+};
+var UniAuthClient = class {
+  config;
+  storage;
+  refreshPromise = null;
+  constructor(config) {
+    this.config = {
+      enableRetry: true,
+      timeout: 3e4,
+      ...config
+    };
+    switch (config.storage) {
+      case "sessionStorage":
+        this.storage = new SessionStorageAdapter();
+        break;
+      case "memory":
+        this.storage = new MemoryStorageAdapter();
+        break;
+      default:
+        this.storage = new LocalStorageAdapter();
+    }
+  }
+  /**
+   * Send verification code to phone number
+   * 发送验证码到手机号
+   */
+  async sendCode(phone, type = "login") {
+    const response = await this.request("/api/v1/auth/send-code", {
+      method: "POST",
+      body: JSON.stringify({ phone, type })
+    });
+    if (!response.success || !response.data) {
+      throw this.createError(response.error?.code || "SEND_CODE_FAILED", response.error?.message || "Failed to send code");
+    }
+    return response.data;
+  }
+  /**
+   * Send verification code to email
+   * 发送验证码到邮箱
+   */
+  async sendEmailCode(email, type = "login") {
+    const response = await this.request("/api/v1/auth/send-code", {
+      method: "POST",
+      body: JSON.stringify({ email, type })
+    });
+    if (!response.success || !response.data) {
+      throw this.createError(response.error?.code || "SEND_CODE_FAILED", response.error?.message || "Failed to send code");
+    }
+    return response.data;
+  }
+  /**
+   * Login with phone verification code
+   * 使用手机验证码登录
+   */
+  async loginWithCode(phone, code) {
+    const response = await this.request("/api/v1/auth/phone/verify", {
+      method: "POST",
+      body: JSON.stringify({ phone, code })
+    });
+    if (!response.success || !response.data) {
+      throw this.createError(response.error?.code || "VERIFY_FAILED", response.error?.message || "Failed to verify code");
+    }
+    if (!response.data.mfa_required) {
+      this.storage.setAccessToken(response.data.access_token);
+      this.storage.setRefreshToken(response.data.refresh_token);
+      this.notifyAuthStateChange(response.data.user);
+    }
+    return response.data;
+  }
+  /**
+   * Login with email verification code
+   * 使用邮箱验证码登录
+   */
+  async loginWithEmailCode(email, code) {
+    const response = await this.request("/api/v1/auth/email/verify", {
+      method: "POST",
+      body: JSON.stringify({ email, code })
+    });
+    if (!response.success || !response.data) {
+      throw this.createError(response.error?.code || "VERIFY_FAILED", response.error?.message || "Failed to verify code");
+    }
+    if (!response.data.mfa_required) {
+      this.storage.setAccessToken(response.data.access_token);
+      this.storage.setRefreshToken(response.data.refresh_token);
+      this.notifyAuthStateChange(response.data.user);
+    }
+    return response.data;
+  }
+  /**
+   * Login with email and password
+   * 使用邮箱密码登录
+   */
+  async loginWithEmail(email, password) {
+    const response = await this.request("/api/v1/auth/email/login", {
+      method: "POST",
+      body: JSON.stringify({ email, password })
+    });
+    if (!response.success || !response.data) {
+      throw this.createError(response.error?.code || "LOGIN_FAILED", response.error?.message || "Failed to login");
+    }
+    if (!response.data.mfa_required) {
+      this.storage.setAccessToken(response.data.access_token);
+      this.storage.setRefreshToken(response.data.refresh_token);
+      this.notifyAuthStateChange(response.data.user);
+    }
+    return response.data;
+  }
+  /**
+   * Handle OAuth callback (for social login)
+   * 处理 OAuth 回调（社交登录）
+   */
+  async handleOAuthCallback(provider, code) {
+    const response = await this.request("/api/v1/auth/oauth/callback", {
+      method: "POST",
+      body: JSON.stringify({ provider, code })
+    });
+    if (!response.success || !response.data) {
+      throw this.createError(response.error?.code || "OAUTH_FAILED", response.error?.message || "OAuth callback failed");
+    }
+    if (!response.data.mfa_required) {
+      this.storage.setAccessToken(response.data.access_token);
+      this.storage.setRefreshToken(response.data.refresh_token);
+      this.notifyAuthStateChange(response.data.user);
+    }
+    return response.data;
+  }
+  // ============================================
+  // Email Registration / 邮箱注册
+  // ============================================
+  /**
+   * Register with email and password
+   * 使用邮箱密码注册
+   */
+  async registerWithEmail(email, password, nickname) {
+    const response = await this.request("/api/v1/auth/email/register", {
+      method: "POST",
+      body: JSON.stringify({ email, password, nickname })
+    });
+    if (!response.success || !response.data) {
+      throw this.createError(response.error?.code || "REGISTER_FAILED", response.error?.message || "Failed to register");
+    }
+    this.storage.setAccessToken(response.data.access_token);
+    this.storage.setRefreshToken(response.data.refresh_token);
+    this.notifyAuthStateChange(response.data.user);
+    return response.data;
+  }
+  // ============================================
+  // MFA (Multi-Factor Authentication) / 多因素认证
+  // ============================================
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async verifyMFA(mfaToken, code) {
+    const response = await this.request("/api/v1/auth/mfa/verify-login", {
+      method: "POST",
+      body: JSON.stringify({ mfa_token: mfaToken, code })
+    });
+    if (!response.success || !response.data) {
+      throw this.createError(response.error?.code || "MFA_FAILED", response.error?.message || "MFA verification failed");
+    }
+    this.storage.setAccessToken(response.data.access_token);
+    this.storage.setRefreshToken(response.data.refresh_token);
+    this.notifyAuthStateChange(response.data.user);
+    return response.data;
+  }
+  // ============================================
+  // Social Login / 社交登录
+  // ============================================
+  /**
+   * Get available OAuth providers
+   * 获取可用的 OAuth 提供商列表
+   */
+  async getOAuthProviders() {
+    const response = await this.request("/api/v1/auth/oauth/providers", {
+      method: "GET"
+    });
+    if (!response.success || !response.data) {
+      return [];
+    }
+    return response.data.providers || [];
+  }
+  /**
+   * 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, redirectUri) {
+    const params = new URLSearchParams();
+    if (redirectUri) {
+      params.set("redirect_uri", redirectUri);
+    }
+    const query = params.toString();
+    const url = `${this.config.baseUrl}/api/v1/auth/oauth/${provider}/authorize${query ? "?" + query : ""}`;
+    if (typeof window !== "undefined") {
+      window.location.href = url;
+    }
+  }
+  // ============================================
+  // Auth State Management / 认证状态管理
+  // ============================================
+  authStateCallbacks = [];
+  currentUser = null;
+  /**
+   * 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) {
+    this.authStateCallbacks.push(callback);
+    return () => {
+      const index = this.authStateCallbacks.indexOf(callback);
+      if (index !== -1) {
+        this.authStateCallbacks.splice(index, 1);
+      }
+    };
+  }
+  /**
+   * Notify all subscribers of auth state change
+   * 通知所有订阅者认证状态变更
+   */
+  notifyAuthStateChange(user) {
+    this.currentUser = user;
+    const isAuthenticated = this.isAuthenticated();
+    for (const callback of this.authStateCallbacks) {
+      try {
+        callback(user, isAuthenticated);
+      } catch (error) {
+        console.error("Auth state callback error:", error);
+      }
+    }
+  }
+  /**
+   * Get cached current user (sync, may be stale)
+   * 获取缓存的当前用户（同步，可能过时）
+   */
+  getCachedUser() {
+    return this.currentUser;
+  }
+  /**
+   * Get access token synchronously (without refresh check)
+   * 同步获取访问令牌（不检查刷新）
+   */
+  getAccessTokenSync() {
+    return this.storage.getAccessToken();
+  }
+  /**
+   * Check if current token is valid (not expired)
+   * 检查当前令牌是否有效（未过期）
+   */
+  isTokenValid() {
+    const token = this.storage.getAccessToken();
+    if (!token) return false;
+    try {
+      const payload = JSON.parse(atob(token.split(".")[1]));
+      const exp = payload.exp * 1e3;
+      return Date.now() < exp;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Get current user info
+   * 获取当前用户信息
+   */
+  async getCurrentUser() {
+    if (!this.isAuthenticated()) {
+      return null;
+    }
+    try {
+      const response = await this.authenticatedRequest("/api/v1/user/me", {
+        method: "GET"
+      });
+      if (!response.success || !response.data) {
+        return null;
+      }
+      return response.data;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Update user profile
+   * 更新用户资料
+   */
+  async updateProfile(updates) {
+    const response = await this.authenticatedRequest("/api/v1/user/me", {
+      method: "PATCH",
+      body: JSON.stringify(updates)
+    });
+    if (!response.success || !response.data) {
+      throw this.createError(response.error?.code || "UPDATE_FAILED", response.error?.message || "Failed to update profile");
+    }
+    return response.data;
+  }
+  /**
+   * Get access token (auto-refresh if needed)
+   * 获取访问令牌（如需要则自动刷新）
+   */
+  async getAccessToken() {
+    const token = this.storage.getAccessToken();
+    if (!token) {
+      return null;
+    }
+    try {
+      const payload = JSON.parse(atob(token.split(".")[1]));
+      const exp = payload.exp * 1e3;
+      if (Date.now() > exp - 5 * 60 * 1e3) {
+        await this.refreshTokens();
+        return this.storage.getAccessToken();
+      }
+    } catch {
+    }
+    return token;
+  }
+  /**
+   * Check if user is authenticated
+   * 检查用户是否已认证
+   */
+  isAuthenticated() {
+    return !!this.storage.getAccessToken();
+  }
+  /**
+   * Logout current session
+   * 登出当前会话
+   */
+  async logout() {
+    const refreshToken = this.storage.getRefreshToken();
+    try {
+      await this.authenticatedRequest("/api/v1/auth/logout", {
+        method: "POST",
+        body: JSON.stringify({ refresh_token: refreshToken })
+      });
+    } finally {
+      this.storage.clear();
+      this.notifyAuthStateChange(null);
+    }
+  }
+  /**
+   * Logout from all devices
+   * 从所有设备登出
+   */
+  async logoutAll() {
+    try {
+      await this.authenticatedRequest("/api/v1/auth/logout-all", {
+        method: "POST"
+      });
+    } finally {
+      this.storage.clear();
+      this.notifyAuthStateChange(null);
+    }
+  }
+  // ============================================
+  // OAuth2 Client Methods (for integrating with other OAuth providers using UniAuth)
+  // OAuth2 客户端方法
+  // ============================================
+  /**
+   * Start OAuth2 authorization flow
+   * 开始 OAuth2 授权流程
+   */
+  async startOAuth2Flow(options) {
+    if (!this.config.clientId) {
+      throw this.createError("CONFIG_ERROR", "clientId is required for OAuth2 flow");
+    }
+    const params = new URLSearchParams({
+      client_id: this.config.clientId,
+      redirect_uri: options.redirectUri,
+      response_type: "code"
+    });
+    if (options.scope) {
+      params.set("scope", options.scope);
+    }
+    if (options.state) {
+      params.set("state", options.state);
+    }
+    if (options.usePKCE) {
+      const verifier = generateCodeVerifier();
+      const challenge = await generateCodeChallenge(verifier);
+      storeCodeVerifier(verifier);
+      params.set("code_challenge", challenge);
+      params.set("code_challenge_method", "S256");
+    }
+    return `${this.config.baseUrl}/api/v1/oauth2/authorize?${params.toString()}`;
+  }
+  /**
+   * Exchange authorization code for tokens (OAuth2 client flow)
+   * 使用授权码换取令牌
+   */
+  async exchangeOAuth2Code(code, redirectUri, clientSecret) {
+    if (!this.config.clientId) {
+      throw this.createError("CONFIG_ERROR", "clientId is required for OAuth2 flow");
+    }
+    const body = {
+      grant_type: "authorization_code",
+      client_id: this.config.clientId,
+      code,
+      redirect_uri: redirectUri
+    };
+    if (clientSecret) {
+      body.client_secret = clientSecret;
+    }
+    const codeVerifier = getAndClearCodeVerifier();
+    if (codeVerifier) {
+      body.code_verifier = codeVerifier;
+    }
+    const response = await fetchWithRetry(`${this.config.baseUrl}/api/v1/oauth2/token`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body),
+      maxRetries: this.config.enableRetry ? 3 : 0,
+      timeout: this.config.timeout
+    });
+    const data = await response.json();
+    if (data.error) {
+      throw this.createError(data.error, data.error_description || "Token exchange failed");
+    }
+    return data;
+  }
+  // ============================================
+  // SSO Methods (Cross-Domain Single Sign-On)
+  // SSO 方法（跨域单点登录）
+  // ============================================
+  ssoConfig = null;
+  /**
+   * 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) {
+    this.ssoConfig = {
+      scope: "openid profile email",
+      ...config
+    };
+  }
+  /**
+   * 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 = {}) {
+    if (!this.ssoConfig) {
+      throw this.createError("SSO_NOT_CONFIGURED", "SSO is not configured. Call configureSso() first.");
+    }
+    const { usePKCE = true, state } = options;
+    const stateValue = state || this.generateRandomState();
+    this.storeState(stateValue);
+    const params = new URLSearchParams({
+      client_id: this.ssoConfig.clientId,
+      redirect_uri: this.ssoConfig.redirectUri,
+      response_type: "code",
+      scope: this.ssoConfig.scope || "openid profile email",
+      state: stateValue
+    });
+    if (usePKCE) {
+      const verifier = generateCodeVerifier();
+      storeCodeVerifier(verifier);
+      generateCodeChallenge(verifier).then((challenge) => {
+        params.set("code_challenge", challenge);
+        params.set("code_challenge_method", "S256");
+        window.location.href = `${this.ssoConfig.ssoUrl}/api/v1/oauth2/authorize?${params.toString()}`;
+      });
+    } else {
+      window.location.href = `${this.ssoConfig.ssoUrl}/api/v1/oauth2/authorize?${params.toString()}`;
+    }
+  }
+  /**
+   * Check if current URL is an SSO callback
+   * 检查当前 URL 是否是 SSO 回调
+   * 
+   * @example
+   * ```typescript
+   * if (auth.isSSOCallback()) {
+   *   await auth.handleSSOCallback();
+   * }
+   * ```
+   */
+  isSSOCallback() {
+    if (typeof window === "undefined") return false;
+    const params = new URLSearchParams(window.location.search);
+    return !!(params.get("code") && params.get("state"));
+  }
+  /**
+   * 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));
+   *   }
+   * }, []);
+   * ```
+   */
+  async handleSSOCallback() {
+    if (!this.ssoConfig) {
+      throw this.createError("SSO_NOT_CONFIGURED", "SSO is not configured. Call configureSso() first.");
+    }
+    if (typeof window === "undefined") {
+      return null;
+    }
+    const params = new URLSearchParams(window.location.search);
+    const code = params.get("code");
+    const state = params.get("state");
+    const error = params.get("error");
+    const errorDescription = params.get("error_description");
+    if (error) {
+      throw this.createError(error, errorDescription || "SSO login failed");
+    }
+    const savedState = this.getAndClearState();
+    if (state && savedState && state !== savedState) {
+      throw this.createError("INVALID_STATE", "Invalid state parameter. Please try logging in again.");
+    }
+    if (!code) {
+      throw this.createError("NO_CODE", "No authorization code received.");
+    }
+    const tokenResult = await this.exchangeSSOCode(code, this.ssoConfig.redirectUri);
+    this.storage.setAccessToken(tokenResult.access_token);
+    if (tokenResult.refresh_token) {
+      this.storage.setRefreshToken(tokenResult.refresh_token);
+    }
+    const user = await this.getCurrentUser();
+    if (typeof window !== "undefined" && window.history) {
+      const cleanUrl = window.location.pathname;
+      window.history.replaceState({}, document.title, cleanUrl);
+    }
+    return {
+      user: user || { id: "", phone: null, email: null, nickname: null, avatar_url: null },
+      access_token: tokenResult.access_token,
+      refresh_token: tokenResult.refresh_token || "",
+      expires_in: tokenResult.expires_in,
+      is_new_user: false
+    };
+  }
+  /**
+   * 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
+   */
+  async checkSSOSession() {
+    if (!this.ssoConfig) {
+      return false;
+    }
+    if (this.isAuthenticated()) {
+      return true;
+    }
+    return false;
+  }
+  // Helper methods for SSO
+  generateRandomState() {
+    return Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
+  }
+  storeState(state) {
+    if (typeof localStorage !== "undefined") {
+      localStorage.setItem("uniauth_sso_state", state);
+    }
+  }
+  getAndClearState() {
+    if (typeof localStorage === "undefined") return null;
+    const state = localStorage.getItem("uniauth_sso_state");
+    localStorage.removeItem("uniauth_sso_state");
+    return state;
+  }
+  /**
+   * Exchange SSO authorization code for tokens
+   * This is a private method used internally by handleSSOCallback
+   */
+  async exchangeSSOCode(code, redirectUri) {
+    const baseUrl = this.ssoConfig?.ssoUrl || this.config.baseUrl;
+    const clientId = this.ssoConfig?.clientId || this.config.clientId;
+    if (!clientId) {
+      throw this.createError("CONFIG_ERROR", "clientId is required for OAuth2 flow");
+    }
+    const body = {
+      grant_type: "authorization_code",
+      client_id: clientId,
+      code,
+      redirect_uri: redirectUri
+    };
+    const codeVerifier = getAndClearCodeVerifier();
+    if (codeVerifier) {
+      body.code_verifier = codeVerifier;
+    }
+    const response = await fetchWithRetry(`${baseUrl}/api/v1/oauth2/token`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body),
+      maxRetries: this.config.enableRetry ? 3 : 0,
+      timeout: this.config.timeout
+    });
+    const data = await response.json();
+    if (data.error) {
+      throw this.createError(data.error, data.error_description || "Token exchange failed");
+    }
+    return data;
+  }
+  // ============================================
+  // Private Methods
+  // ============================================
+  /**
+   * Refresh tokens
+   * 刷新令牌
+   */
+  async refreshTokens() {
+    if (this.refreshPromise) {
+      return this.refreshPromise;
+    }
+    this.refreshPromise = this.doRefreshTokens();
+    try {
+      return await this.refreshPromise;
+    } finally {
+      this.refreshPromise = null;
+    }
+  }
+  async doRefreshTokens() {
+    const refreshToken = this.storage.getRefreshToken();
+    if (!refreshToken) {
+      return false;
+    }
+    try {
+      const response = await this.request("/api/v1/auth/refresh", {
+        method: "POST",
+        body: JSON.stringify({ refresh_token: refreshToken })
+      });
+      if (!response.success || !response.data) {
+        this.storage.clear();
+        this.config.onAuthError?.({
+          code: "REFRESH_FAILED",
+          message: response.error?.message || "Failed to refresh token"
+        });
+        return false;
+      }
+      this.storage.setAccessToken(response.data.access_token);
+      this.storage.setRefreshToken(response.data.refresh_token);
+      this.config.onTokenRefresh?.(response.data);
+      return true;
+    } catch (error) {
+      this.storage.clear();
+      this.config.onAuthError?.({
+        code: "REFRESH_ERROR",
+        message: error instanceof Error ? error.message : "Unknown error"
+      });
+      return false;
+    }
+  }
+  /**
+   * Make an authenticated request
+   * 发起已认证的请求
+   */
+  async authenticatedRequest(path, options = {}) {
+    const token = await this.getAccessToken();
+    if (!token) {
+      throw this.createError("NOT_AUTHENTICATED", "Not authenticated");
+    }
+    return this.request(path, {
+      ...options,
+      headers: {
+        ...options.headers,
+        Authorization: `Bearer ${token}`
+      }
+    });
+  }
+  /**
+   * Make a request to the API with retry support
+   * 向 API 发起请求（支持重试）
+   */
+  async request(path, options = {}) {
+    const url = `${this.config.baseUrl}${path}`;
+    const fetchOptions = {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        ...this.config.appKey && { "X-App-Key": this.config.appKey },
+        ...options.headers
+      },
+      maxRetries: this.config.enableRetry ? 3 : 0,
+      timeout: this.config.timeout
+    };
+    const response = await fetchWithRetry(url, fetchOptions);
+    const data = await response.json();
+    return data;
+  }
+  /**
+   * Create an error object
+   * 创建错误对象
+   */
+  createError(code, message, statusCode) {
+    return new UniAuthError(code, message, statusCode);
+  }
+};
+var index_default = UniAuthClient;
+export {
+  AuthErrorCode,
+  UniAuthClient,
+  UniAuthError,
+  index_default as default,
+  fetchWithRetry,
+  generateCodeChallenge,
+  generateCodeVerifier,
+  getAndClearCodeVerifier,
+  storeCodeVerifier
+};