@quantabit/sdk-config 1.0.0

package/dist/index.esm.js

@@ -0,0 +1,825 @@
+import { useState, useEffect, useCallback } from 'react';
+
+/**
+ * @quantabit/sdk-config - BaseApiClient
+ * 
+ * SDK API 客户端基类
+ * 封装所有通用的配置、请求、Token 管理逻辑
+ * 
+ * 使用方式：
+ * ```javascript
+ * import { BaseApiClient } from '@quantabit/sdk-config';
+ * 
+ * class MyApiClient extends BaseApiClient {
+ *   constructor(config = {}) {
+ *     super('/my-module', config);  // 只需传入模块路径
+ *   }
+ *   
+ *   // 专注于业务方法
+ *   async getList() {
+ *     return this.request('/list');
+ *   }
+ * }
+ * ```
+ */
+
+
+/**
+ * SDK API 客户端基类
+ * 所有 SDK 的 API 客户端都应继承此类
+ */
+class BaseApiClient {
+  /**
+   * 构造函数
+   * @param {string} modulePath - 模块路径，如 '/auth', '/points', '/wallet'
+   * @param {Object} config - 配置选项
+   * @param {string} config.baseUrl - 自定义基础 URL（覆盖全局配置）
+   * @param {number} config.timeout - 自定义超时时间（毫秒）
+   * @param {Function} config.onError - 错误回调
+   * @param {Function} config.getLanguage - 获取语言的函数
+   */
+  constructor(modulePath = '', config = {}) {
+    this.modulePath = modulePath;
+    this._customBaseUrl = config.baseUrl;
+    this._customTimeout = config.timeout;
+    this.token = null;
+    this.onError = config.onError;
+    this.getLanguage = config.getLanguage || (() => 'zh');
+    
+    // 从全局配置初始化
+    this._updateFromGlobalConfig(getConfig());
+    
+    // 订阅配置变更
+    this._unsubscribe = subscribeConfig((newConfig) => {
+      this._updateFromGlobalConfig(newConfig);
+    });
+  }
+
+  /**
+   * 从全局配置更新本地配置
+   * @private
+   */
+  _updateFromGlobalConfig(globalConfig) {
+    // 只有未自定义时才使用全局配置
+    if (!this._customBaseUrl) {
+      this.baseUrl = `${globalConfig.apiBaseUrl}${this.modulePath}`;
+    } else {
+      this.baseUrl = this._customBaseUrl;
+    }
+    
+    if (!this._customTimeout) {
+      this.timeout = globalConfig.timeout || 30000;
+    } else {
+      this.timeout = this._customTimeout;
+    }
+  }
+
+  /**
+   * 设置 Token
+   * @param {string} token - 访问令牌
+   */
+  setToken(token) {
+    this.token = token;
+  }
+
+  /**
+   * 设置基础 URL
+   * @param {string} url - 新的基础 URL
+   */
+  setBaseUrl(url) {
+    this._customBaseUrl = url;
+    this.baseUrl = url;
+  }
+
+  /**
+   * 获取当前使用的 Token
+   * 优先使用实例 Token，否则从存储获取
+   * @returns {string|null}
+   */
+  getToken() {
+    return this.token || getToken();
+  }
+
+  /**
+   * 发送 HTTP 请求
+   * @param {string} endpoint - API 端点（相对于 baseUrl）
+   * @param {Object} options - fetch 选项
+   * @returns {Promise<any>} 响应数据
+   */
+  async request(endpoint, options = {}) {
+    const url = `${this.baseUrl}${endpoint}`;
+    
+    // 构建请求头
+    const headers = {
+      'Content-Type': 'application/json',
+      'Accept-Language': this.getLanguage(),
+      ...options.headers,
+    };
+    
+    // 添加认证头
+    const token = this.getToken();
+    if (token) {
+      headers['Authorization'] = `Bearer ${token}`;
+    }
+
+    // 超时控制
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        ...options,
+        headers,
+        signal: controller.signal,
+      });
+      
+      clearTimeout(timeoutId);
+      
+      // 解析响应
+      const data = await response.json();
+      
+      // 处理错误响应
+      if (!response.ok) {
+        const error = new Error(data.message || data.detail || `HTTP ${response.status}`);
+        error.code = data.code || `HTTP_${response.status}`;
+        error.status = response.status;
+        error.data = data;
+        
+        this.onError?.(error);
+        logger.error(`${this.constructor.name} Error:`, error.message);
+        throw error;
+      }
+      
+      return data;
+    } catch (error) {
+      clearTimeout(timeoutId);
+      
+      // 处理超时错误
+      if (error.name === 'AbortError') {
+        const timeoutError = new Error('Request timeout');
+        timeoutError.code = 'TIMEOUT';
+        this.onError?.(timeoutError);
+        throw timeoutError;
+      }
+      
+      // 处理网络错误
+      if (error.name === 'TypeError' && error.message.includes('fetch')) {
+        const networkError = new Error('Network error');
+        networkError.code = 'NETWORK_ERROR';
+        this.onError?.(networkError);
+        throw networkError;
+      }
+      
+      throw error;
+    }
+  }
+
+  /**
+   * GET 请求便捷方法
+   * @param {string} endpoint - API 端点
+   * @param {Object} params - 查询参数
+   */
+  async get(endpoint, params = {}) {
+    const query = new URLSearchParams(params).toString();
+    const url = query ? `${endpoint}?${query}` : endpoint;
+    return this.request(url, { method: 'GET' });
+  }
+
+  /**
+   * POST 请求便捷方法
+   * @param {string} endpoint - API 端点
+   * @param {Object} data - 请求体数据
+   */
+  async post(endpoint, data = {}) {
+    return this.request(endpoint, {
+      method: 'POST',
+      body: JSON.stringify(data),
+    });
+  }
+
+  /**
+   * PUT 请求便捷方法
+   * @param {string} endpoint - API 端点
+   * @param {Object} data - 请求体数据
+   */
+  async put(endpoint, data = {}) {
+    return this.request(endpoint, {
+      method: 'PUT',
+      body: JSON.stringify(data),
+    });
+  }
+
+  /**
+   * DELETE 请求便捷方法
+   * @param {string} endpoint - API 端点
+   * @param {Object} data - 请求体数据（可选）
+   */
+  async delete(endpoint, data = null) {
+    const options = { method: 'DELETE' };
+    if (data) {
+      options.body = JSON.stringify(data);
+    }
+    return this.request(endpoint, options);
+  }
+
+  /**
+   * PATCH 请求便捷方法
+   * @param {string} endpoint - API 端点
+   * @param {Object} data - 请求体数据
+   */
+  async patch(endpoint, data = {}) {
+    return this.request(endpoint, {
+      method: 'PATCH',
+      body: JSON.stringify(data),
+    });
+  }
+
+  /**
+   * 销毁实例，取消配置订阅
+   */
+  destroy() {
+    if (this._unsubscribe) {
+      this._unsubscribe();
+      this._unsubscribe = null;
+    }
+  }
+}
+
+/**
+ * 创建 API 客户端的工厂函数
+ * 用于快速创建简单的 API 客户端
+ * 
+ * @param {string} modulePath - 模块路径
+ * @param {Object} methods - 方法定义对象
+ * @returns {BaseApiClient} API 客户端实例
+ * 
+ * @example
+ * const myApi = createApiClient('/my-module', {
+ *   getList: (client) => client.get('/list'),
+ *   create: (client, data) => client.post('/', data),
+ * });
+ */
+function createApiClient(modulePath, methods = {}) {
+  const client = new BaseApiClient(modulePath);
+  
+  // 绑定自定义方法
+  Object.entries(methods).forEach(([name, fn]) => {
+    client[name] = (...args) => fn(client, ...args);
+  });
+  
+  return client;
+}
+
+/**
+ * @quantabit/sdk-config
+ * 
+ * Qbit_DID SDK 统一配置管理
+ * 
+ * 所有 SDK 共享此配置，修改一处即可全局生效：
+ * - API 基础 URL
+ * - 超时时间
+ * - 认证配置
+ * - 调试模式
+ * 
+ * 使用方式：
+ * 1. 直接使用默认配置
+ *    import { getConfig } from '@quantabit/sdk-config';
+ *    const config = getConfig();
+ * 
+ * 2. 应用启动时初始化配置
+ *    import { initConfig } from '@quantabit/sdk-config';
+ *    initConfig({ apiBaseUrl: 'https://api.example.com' });
+ * 
+ * 3. 使用 React Hook
+ *    import { useSDKConfig } from '@quantabit/sdk-config';
+ *    const { config, setApiBaseUrl } = useSDKConfig();
+ */
+
+// ============ 默认配置 ============
+
+/**
+ * 默认 API 配置
+ * 注意：生产环境应通过 initConfig 覆盖这些值
+ */
+const DEFAULT_CONFIG = {
+  // === API 配置 ===
+  apiBaseUrl: '/api/v1',           // API 基础路径（相对路径，由后端代理）
+  apiFullUrl: '',                    // 完整 API URL（需通过 initConfig 配置）
+  
+  // === 超时配置 ===
+  timeout: 30000,                   // 请求超时（毫秒）
+  retryCount: 3,                    // 重试次数
+  retryDelay: 1000,                 // 重试延迟（毫秒）
+  
+  // === 认证配置 ===
+  tokenStorageKey: 'qbit_did_access_token',
+  refreshTokenStorageKey: 'qbit_did_refresh_token',
+  currentSessionKey: 'qbit_did_current',
+  autoRefreshToken: true,           // 自动刷新 Token
+  
+  // === WebSocket 配置 ===
+  wsBaseUrl: '',                     // WebSocket URL（需通过 initConfig 配置）
+  wsReconnect: true,
+  wsReconnectInterval: 3000,
+  
+  // === 调试配置 ===
+  debug: process.env.NODE_ENV !== 'production',
+  logLevel: 'info',                 // 'debug' | 'info' | 'warn' | 'error'
+  
+  // === 环境配置 ===
+  environment: process.env.NODE_ENV || 'development',
+  
+  // === 语言配置 ===
+  language: 'zh',                    // 默认语言
+  fallbackLanguage: 'en',            // 回退语言
+  supportedLanguages: ['zh', 'en', 'ja', 'ko'],  // 支持的语言
+  languageStorageKey: 'qbit_did_language',        // localStorage key
+};
+
+// ============ 配置状态 ============
+
+let _config = { ...DEFAULT_CONFIG };
+let _listeners = new Set();
+let _languageListeners = new Set();  // 语言变更监听器
+
+// ============ 核心函数 ============
+
+/**
+ * 获取当前配置
+ * @returns {object} 当前配置对象
+ */
+function getConfig() {
+  return { ..._config };
+}
+
+/**
+ * 初始化 SDK 配置
+ * 应在应用启动时调用一次
+ * 
+ * @param {object} options - 配置选项
+ * @param {string} options.apiBaseUrl - API 基础 URL（如 '/api/v1' 或完整 URL）
+ * @param {number} options.timeout - 请求超时时间（毫秒）
+ * @param {boolean} options.debug - 是否开启调试模式
+ * @param {string} options.environment - 环境标识
+ */
+function initConfig(options = {}) {
+  _config = {
+    ..._config,
+    ...options,
+  };
+  
+  // 如果提供了完整 URL，同时更新 apiFullUrl
+  if (options.apiBaseUrl && options.apiBaseUrl.startsWith('http')) {
+    _config.apiFullUrl = options.apiBaseUrl;
+    // 对于完整 URL，apiBaseUrl 保持原样
+  }
+  
+  // 通知所有监听者
+  _notifyListeners();
+  
+  if (_config.debug) {
+    console.log('[SDK Config] 配置已初始化:', _config);
+  }
+  
+  return _config;
+}
+
+/**
+ * 设置 API 基础 URL
+ * 便捷方法，用于动态切换 API 地址
+ * 
+ * @param {string} url - 新的 API URL
+ */
+function setApiBaseUrl(url) {
+  _config.apiBaseUrl = url;
+  if (url.startsWith('http')) {
+    _config.apiFullUrl = url;
+  }
+  _notifyListeners();
+  
+  if (_config.debug) {
+    console.log('[SDK Config] API URL 已更新:', url);
+  }
+}
+
+/**
+ * 设置 WebSocket URL
+ * 
+ * @param {string} url - 新的 WebSocket URL
+ */
+function setWsBaseUrl(url) {
+  _config.wsBaseUrl = url;
+  _notifyListeners();
+}
+
+/**
+ * 设置调试模式
+ * 
+ * @param {boolean} debug - 是否开启调试
+ */
+function setDebug(debug) {
+  _config.debug = debug;
+  _notifyListeners();
+}
+
+/**
+ * 重置为默认配置
+ */
+function resetConfig() {
+  _config = { ...DEFAULT_CONFIG };
+  _notifyListeners();
+}
+
+// ============ 配置监听 ============
+
+/**
+ * 订阅配置变更
+ * 
+ * @param {function} listener - 监听回调
+ * @returns {function} 取消订阅函数
+ */
+function subscribeConfig(listener) {
+  _listeners.add(listener);
+  return () => _listeners.delete(listener);
+}
+
+function _notifyListeners() {
+  const config = getConfig();
+  _listeners.forEach(listener => {
+    try {
+      listener(config);
+    } catch (err) {
+      console.error('[SDK Config] 监听器执行错误:', err);
+    }
+  });
+}
+
+// ============ 环境预设 ============
+
+/**
+ * 环境预设配置
+ * 快速切换不同环境的配置
+ */
+const ENVIRONMENT_PRESETS = {
+  development: {
+    apiBaseUrl: '/api/v1',
+    apiFullUrl: 'http://localhost:3000/api/v1',
+    wsBaseUrl: 'ws://localhost:3000/ws',
+    debug: true,
+    logLevel: 'debug',
+  },
+  staging: {
+    apiBaseUrl: '/api/v1',
+    apiFullUrl: '',   // 请通过 initWithEnvironment('staging', { apiFullUrl: '...' }) 配置
+    wsBaseUrl: '',    // 请通过 initWithEnvironment('staging', { wsBaseUrl: '...' }) 配置
+    debug: true,
+    logLevel: 'info',
+  },
+  production: {
+    apiBaseUrl: '/api/v1',
+    apiFullUrl: '',   // 请通过 initWithEnvironment('production', { apiFullUrl: '...' }) 配置
+    wsBaseUrl: '',    // 请通过 initWithEnvironment('production', { wsBaseUrl: '...' }) 配置
+    debug: false,
+    logLevel: 'error',
+  },
+};
+
+/**
+ * 使用环境预设初始化配置
+ * 
+ * @param {string} env - 环境名称 ('development' | 'staging' | 'production')
+ * @param {object} overrides - 额外覆盖配置
+ */
+function initWithEnvironment(env, overrides = {}) {
+  const preset = ENVIRONMENT_PRESETS[env];
+  if (!preset) {
+    console.warn(`[SDK Config] 未知环境: ${env}, 使用默认配置`);
+    return initConfig(overrides);
+  }
+  
+  return initConfig({
+    ...preset,
+    environment: env,
+    ...overrides,
+  });
+}
+
+/**
+ * React Hook: 获取和管理 SDK 配置
+ * 
+ * @example
+ * const { config, setApiBaseUrl, initConfig } = useSDKConfig();
+ * 
+ * // 读取配置
+ * console.log(config.apiBaseUrl);
+ * 
+ * // 动态修改 API URL
+ * setApiBaseUrl('https://new-api.example.com');
+ */
+function useSDKConfig() {
+  const [config, setConfigState] = useState(getConfig);
+  
+  useEffect(() => {
+    const unsubscribe = subscribeConfig(setConfigState);
+    return unsubscribe;
+  }, []);
+  
+  const updateConfig = useCallback((options) => {
+    initConfig(options);
+  }, []);
+  
+  const updateApiUrl = useCallback((url) => {
+    setApiBaseUrl(url);
+  }, []);
+  
+  const updateWsUrl = useCallback((url) => {
+    setWsBaseUrl(url);
+  }, []);
+  
+  const reset = useCallback(() => {
+    resetConfig();
+  }, []);
+  
+  return {
+    config,
+    initConfig: updateConfig,
+    setApiBaseUrl: updateApiUrl,
+    setWsBaseUrl: updateWsUrl,
+    resetConfig: reset,
+    initWithEnvironment,
+  };
+}
+
+// ============ 请求工具 ============
+
+/**
+ * 构建完整的 API URL
+ * 
+ * @param {string} endpoint - API 端点（如 '/auth/login'）
+ * @param {boolean} useFullUrl - 是否使用完整 URL
+ * @returns {string} 完整的 URL
+ */
+function buildApiUrl(endpoint, useFullUrl = false) {
+  const baseUrl = useFullUrl ? _config.apiFullUrl : _config.apiBaseUrl;
+  // 确保不会出现双斜杠
+  const cleanEndpoint = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+  const cleanBase = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+  return `${cleanBase}${cleanEndpoint}`;
+}
+
+/**
+ * 获取认证 Token
+ * 
+ * @returns {string|null} Token 或 null
+ */
+function getToken() {
+  if (typeof window === 'undefined') return null;
+  return localStorage.getItem(_config.tokenStorageKey);
+}
+
+/**
+ * 获取刷新 Token
+ * 
+ * @returns {string|null} Refresh Token 或 null
+ */
+function getRefreshToken() {
+  if (typeof window === 'undefined') return null;
+  return localStorage.getItem(_config.refreshTokenStorageKey);
+}
+
+/**
+ * 保存认证 Token
+ * 
+ * @param {string} accessToken - Access Token
+ * @param {string} refreshToken - Refresh Token（可选）
+ */
+function saveTokens(accessToken, refreshToken) {
+  if (typeof window === 'undefined') return;
+  localStorage.setItem(_config.tokenStorageKey, accessToken);
+  if (refreshToken) {
+    localStorage.setItem(_config.refreshTokenStorageKey, refreshToken);
+  }
+}
+
+/**
+ * 清除所有 Token
+ */
+function clearTokens() {
+  if (typeof window === 'undefined') return;
+  localStorage.removeItem(_config.tokenStorageKey);
+  localStorage.removeItem(_config.refreshTokenStorageKey);
+  localStorage.removeItem(_config.currentSessionKey);
+}
+
+/**
+ * 检查是否已认证
+ * 
+ * @returns {boolean} 是否有有效 Token
+ */
+function isAuthenticated() {
+  return !!getToken();
+}
+
+// ============ 日志工具 ============
+
+const LOG_LEVELS = { debug: 0, info: 1, warn: 2, error: 3 };
+
+/**
+ * SDK 日志工具
+ * 根据配置的日志级别输出日志
+ */
+const logger = {
+  debug: (...args) => {
+    if (_config.debug && LOG_LEVELS[_config.logLevel] <= LOG_LEVELS.debug) {
+      console.debug('[SDK]', ...args);
+    }
+  },
+  info: (...args) => {
+    if (_config.debug && LOG_LEVELS[_config.logLevel] <= LOG_LEVELS.info) {
+      console.info('[SDK]', ...args);
+    }
+  },
+  warn: (...args) => {
+    if (LOG_LEVELS[_config.logLevel] <= LOG_LEVELS.warn) {
+      console.warn('[SDK]', ...args);
+    }
+  },
+  error: (...args) => {
+    console.error('[SDK]', ...args);
+  },
+};
+
+// ============ 语言管理 ============
+
+/**
+ * 获取当前语言
+ * 优先从 localStorage 读取，否则使用默认配置
+ * 
+ * @returns {string} 当前语言代码
+ */
+function getLanguage() {
+  // SSR 安全检查
+  if (typeof window === 'undefined') {
+    return _config.language;
+  }
+  
+  // 尝试从 localStorage 读取
+  const stored = localStorage.getItem(_config.languageStorageKey);
+  if (stored && _config.supportedLanguages.includes(stored)) {
+    return stored;
+  }
+  
+  // 尝试从浏览器获取
+  const browserLang = navigator.language?.split('-')[0];
+  if (browserLang && _config.supportedLanguages.includes(browserLang)) {
+    return browserLang;
+  }
+  
+  return _config.language;
+}
+
+/**
+ * 设置全局语言
+ * 会通知所有订阅的 SDK 和组件
+ * 
+ * @param {string} lang - 语言代码 ('zh' | 'en' | 'ja' | 'ko')
+ * @returns {boolean} 是否设置成功
+ */
+function setLanguage(lang) {
+  // 验证语言代码
+  if (!_config.supportedLanguages.includes(lang)) {
+    logger.warn(`不支持的语言: ${lang}, 支持的语言: ${_config.supportedLanguages.join(', ')}`);
+    return false;
+  }
+  
+  const previousLang = _config.language;
+  _config.language = lang;
+  
+  // 持久化到 localStorage
+  if (typeof window !== 'undefined') {
+    localStorage.setItem(_config.languageStorageKey, lang);
+    
+    // 触发全局 CustomEvent，让不直接依赖此模块的 SDK 也能收到通知
+    try {
+      const event = new CustomEvent('qbit-did:language-change', {
+        detail: { language: lang, oldLanguage: previousLang }
+      });
+      window.dispatchEvent(event);
+    } catch (e) {
+      // 忽略事件触发错误
+    }
+  }
+  
+  // 通知所有语言监听器
+  _notifyLanguageListeners(lang, previousLang);
+  
+  if (_config.debug) {
+    console.log(`[SDK Config] 语言已切换: ${previousLang} -> ${lang}`);
+  }
+  
+  return true;
+}
+
+/**
+ * 初始化语言（应用启动时调用）
+ * 从 localStorage 或浏览器偏好读取
+ */
+function initLanguage() {
+  const detectedLang = getLanguage();
+  _config.language = detectedLang;
+  
+  if (_config.debug) {
+    console.log(`[SDK Config] 语言已初始化: ${detectedLang}`);
+  }
+  
+  return detectedLang;
+}
+
+/**
+ * 订阅语言变更
+ * 
+ * @param {function} listener - 回调函数 (newLang, oldLang) => void
+ * @returns {function} 取消订阅函数
+ */
+function subscribeLanguage(listener) {
+  _languageListeners.add(listener);
+  return () => _languageListeners.delete(listener);
+}
+
+function _notifyLanguageListeners(newLang, oldLang) {
+  _languageListeners.forEach(listener => {
+    try {
+      listener(newLang, oldLang);
+    } catch (err) {
+      console.error('[SDK Config] 语言监听器执行错误:', err);
+    }
+  });
+}
+
+/**
+ * React Hook: 获取和管理语言
+ * 
+ * @example
+ * const { language, setLanguage, supportedLanguages } = useLanguage();
+ * 
+ * // 切换语言
+ * setLanguage('en');
+ */
+function useLanguage() {
+  const [language, setLangState] = useState(getLanguage);
+  
+  useEffect(() => {
+    // 初始化语言
+    const currentLang = getLanguage();
+    setLangState(currentLang);
+    
+    // 订阅语言变更
+    const unsubscribe = subscribeLanguage((newLang) => {
+      setLangState(newLang);
+    });
+    
+    return unsubscribe;
+  }, []);
+  
+  const updateLanguage = useCallback((lang) => {
+    setLanguage(lang);
+  }, []);
+  
+  return {
+    language,
+    setLanguage: updateLanguage,
+    supportedLanguages: _config.supportedLanguages,
+    fallbackLanguage: _config.fallbackLanguage,
+  };
+}
+
+// ============ 导出 ============
+
+var index = {
+  getConfig,
+  initConfig,
+  setApiBaseUrl,
+  setWsBaseUrl,
+  setDebug,
+  resetConfig,
+  subscribeConfig,
+  initWithEnvironment,
+  ENVIRONMENT_PRESETS,
+  buildApiUrl,
+  getToken,
+  getRefreshToken,
+  saveTokens,
+  clearTokens,
+  isAuthenticated,
+  logger,
+  useSDKConfig,
+  // 语言管理
+  getLanguage,
+  setLanguage,
+  initLanguage,
+  subscribeLanguage,
+  useLanguage,
+};
+
+export { BaseApiClient, ENVIRONMENT_PRESETS, buildApiUrl, clearTokens, createApiClient, index as default, getConfig, getLanguage, getRefreshToken, getToken, initConfig, initLanguage, initWithEnvironment, isAuthenticated, logger, resetConfig, saveTokens, setApiBaseUrl, setDebug, setLanguage, setWsBaseUrl, subscribeConfig, subscribeLanguage, useLanguage, useSDKConfig };
+//# sourceMappingURL=index.esm.js.map