@lark-apaas/http-client 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,323 @@
+/**
+ * 拦截器管理器（模仿 Axios 的 InterceptorManager）
+ */
+declare class InterceptorManager<T> {
+    private interceptors;
+    /**
+     * 添加拦截器
+     * @returns 拦截器 ID，用于后续移除
+     */
+    use(onFulfilled?: any, onRejected?: any): number;
+    /**
+     * 移除拦截器
+     */
+    eject(id: number): void;
+    /**
+     * 清空所有拦截器
+     */
+    clear(): void;
+    /**
+     * 遍历所有拦截器
+     */
+    forEach(fn: (interceptor: T) => void): void;
+}
+
+interface CustomClaims {
+    tenant_id?: number;
+    user_id?: string;
+    app_id?: string;
+    app_env?: string;
+    sandbox_id?: string;
+    access_key: string;
+}
+interface JWTClaims extends CustomClaims {
+    iss: string;
+    iat: number;
+    nbf: number;
+    exp: number;
+    jti: string;
+    [key: string]: any;
+}
+interface JWTConfig {
+    accessKey: string;
+    secretKey: string;
+    expireTimeMs: number;
+}
+interface JWTVerifyOptions {
+    /**
+     * 时钟容差（秒），用于处理服务器时间不同步的情况
+     * 默认 60 秒
+     */
+    clockTolerance?: number;
+    /**
+     * 是否跳过过期验证（仅用于调试）
+     * 默认 false
+     */
+    skipExpiration?: boolean;
+}
+declare const DEFAULT_JWT_EXPIRE_TIME_MS: number;
+declare const DEFAULT_CLOCK_TOLERANCE_SEC = 60;
+declare function generateJWTToken(customClaims: CustomClaims, config: JWTConfig): string;
+declare function parseJWTTokenWithVerify(tokenString: string, config: JWTConfig, options?: JWTVerifyOptions): JWTClaims;
+
+interface JWTManagerConfig extends JWTConfig {
+    /**
+     * 在过期前多久刷新 token（毫秒）
+     * 默认 5 分钟
+     */
+    refreshBeforeMs?: number;
+}
+/**
+ * JWT Token 管理器，负责 token 的生成、缓存和自动刷新
+ *
+ * 缓存策略：
+ * - 基于 claims 的哈希值作为缓存 key（支持多租户+多用户）
+ * - 在 token 过期前 refreshBeforeMs 时间内自动刷新
+ *
+ * @example
+ * ```typescript
+ * const manager = new JWTTokenManager({
+ *   accessKey: 'your-access-key',
+ *   secretKey: 'your-secret-key',
+ *   expireTimeMs: 30 * 60 * 1000,
+ *   refreshBeforeMs: 5 * 60 * 1000,
+ * });
+ *
+ * // 获取 token（会自动缓存）
+ * const token = manager.getToken({
+ *   access_key: 'your-access-key',
+ *   tenant_id: 1001,
+ *   user_id: 'user123',
+ * });
+ * ```
+ */
+declare class JWTTokenManager {
+    private cache;
+    private config;
+    constructor(config: JWTManagerConfig);
+    /**
+     * 获取 JWT token，优先使用缓存
+     *
+     * 如果缓存的 token 即将过期（距离过期时间小于 refreshBeforeMs），
+     * 则会生成新的 token 并更新缓存
+     *
+     * @param claims - JWT claims
+     * @returns JWT token 字符串
+     */
+    getToken(claims: CustomClaims): string;
+    /**
+     * 清除所有缓存的 token
+     */
+    clearCache(): void;
+    /**
+     * 清除特定 claims 的缓存
+     *
+     * @param claims - 要清除的 claims
+     */
+    clearCacheFor(claims: CustomClaims): void;
+    /**
+     * 生成缓存 key（基于关键的 claims 字段）
+     *
+     * 使用稳定的字段顺序确保相同 claims 生成相同 key
+     *
+     * @private
+     */
+    private getCacheKey;
+    /**
+     * 获取缓存统计信息（用于监控和调试）
+     *
+     * @returns 缓存统计信息
+     */
+    getCacheStats(): {
+        total: number;
+        valid: number;
+        expired: number;
+    };
+}
+
+type PlatformClaims = Omit<CustomClaims, 'access_key'>;
+interface PlatformPluginOptions {
+    enabled?: boolean;
+    baseURL?: string;
+    domainEnv?: string;
+    accessKeyEnv?: string;
+    secretKeyEnv?: string;
+    accessKey?: string;
+    secretKey?: string;
+    expireTimeMs?: number;
+    refreshBeforeMs?: number;
+    defaultClaims?: PlatformClaims;
+}
+interface PlatformRequestAuthConfig {
+    customClaims?: PlatformClaims;
+}
+declare function resolvePlatformBaseURL(options?: PlatformPluginOptions): string | undefined;
+type RequestInterceptorManager = {
+    use: (onFulfilled?: RequestInterceptor['onFulfilled'], onRejected?: RequestInterceptor['onRejected']) => number;
+    eject: (id: number) => void;
+};
+interface InterceptorHost {
+    request: RequestInterceptorManager;
+}
+declare function registerPlatformPlugin(interceptors: InterceptorHost, options: PlatformPluginOptions): JWTTokenManager | undefined;
+
+/**
+ * 清理后的请求配置（移除敏感信息）
+ */
+interface SafeRequestConfig extends Omit<RequestConfig, 'headers'> {
+    headers?: Record<string, string>;
+}
+/**
+ * HTTP 错误对象
+ *
+ * 注意：为了安全考虑，error.config 中的敏感 headers (如 Authorization, x-api-key)
+ * 会被替换为 '[REDACTED]'
+ */
+declare class HttpError extends Error {
+    readonly isHttpError: boolean;
+    response: Response | undefined;
+    config: SafeRequestConfig;
+    constructor(response: Response | undefined, config: RequestConfig, message?: string);
+}
+interface RequestConfig extends RequestInit {
+    url?: string;
+    params?: Record<string, any>;
+    timeout?: number;
+    baseURL?: string;
+    platformAuth?: PlatformRequestAuthConfig;
+}
+interface SecurityConfig {
+    /**
+     * 允许的 URL 协议白名单
+     * 默认: null (不限制)
+     * 设置为 ['http:', 'https:'] 可限制只允许 HTTP/HTTPS
+     */
+    allowedProtocols?: string[] | null;
+    /**
+     * 最大响应体大小（字节）
+     * 默认: 0 (不限制)
+     * 设置为正数可限制响应体大小，防止内存耗尽攻击
+     */
+    maxResponseSize?: number;
+    /**
+     * 是否启用严格模式（启用所有安全检查）
+     * 默认: false
+     * 启用后会自动设置：
+     * - allowedProtocols = ['http:', 'https:']
+     * - maxResponseSize = 50MB
+     */
+    strictMode?: boolean;
+}
+interface HttpClientConfig extends RequestConfig {
+    platform?: PlatformPluginOptions;
+    security?: SecurityConfig;
+}
+/**
+ * 请求拦截器函数
+ */
+type RequestInterceptor = {
+    onFulfilled?: (config: RequestConfig) => RequestConfig | Promise<RequestConfig>;
+    onRejected?: (error: any) => any;
+};
+/**
+ * 响应拦截器函数（fetch 风格）
+ */
+type ResponseInterceptor = {
+    onFulfilled?: (response: Response) => Response | Promise<Response>;
+    onRejected?: (error: any) => any;
+};
+
+/**
+ * 技术栈无关的 HTTP 客户端
+ *
+ * 设计理念：
+ * - 基于原生 fetch API，零依赖
+ * - 拦截器模式遵循 Axios 标准，AI 模型和开发者都熟悉
+ * - 可在任何 Node.js 环境使用（NestJS, Express, Koa, 纯 Node）
+ *
+ * @example
+ * ```typescript
+ * const client = new HttpClient({
+ *   baseURL: 'https://api.example.com',
+ *   timeout: 5000,
+ * });
+ *
+ * // 添加请求拦截器（类似 Axios）
+ * client.interceptors.request.use(
+ *   config => {
+ *     config.headers = config.headers || {};
+ *     config.headers['Authorization'] = 'Bearer token';
+ *     return config;
+ *   },
+ *   error => Promise.reject(error)
+ * );
+ *
+ * // 添加响应拦截器（类似 Axios）
+ * client.interceptors.response.use(
+ *   response => {
+ *     console.log('Response:', response.status);
+ *     return response;
+ *   },
+ *   error => {
+ *     if (error.response?.status === 401) {
+ *       // 处理未授权
+ *     }
+ *     return Promise.reject(error);
+ *   }
+ * );
+ *
+ * // 发起请求
+ * const response = await client.get('/users');
+ * console.log(response.data);
+ * ```
+ */
+declare class HttpClient {
+    private defaultConfig;
+    private securityConfig;
+    /**
+     * 拦截器管理器（API 与 Axios 一致）
+     */
+    interceptors: {
+        request: InterceptorManager<RequestInterceptor>;
+        response: InterceptorManager<ResponseInterceptor>;
+    };
+    constructor(config?: HttpClientConfig);
+    /**
+     * GET 请求
+     */
+    get(url: string, config?: RequestConfig): Promise<Response>;
+    /**
+     * POST 请求
+     */
+    post(url: string, data?: any, config?: RequestConfig): Promise<Response>;
+    /**
+     * PUT 请求
+     */
+    put(url: string, data?: any, config?: RequestConfig): Promise<Response>;
+    /**
+     * DELETE 请求
+     */
+    delete(url: string, config?: RequestConfig): Promise<Response>;
+    /**
+     * PATCH 请求
+     */
+    patch(url: string, data?: any, config?: RequestConfig): Promise<Response>;
+    /**
+     * 核心请求方法（fetch 风格）
+     */
+    request(config: RequestConfig): Promise<Response>;
+    /**
+     * 执行请求拦截器链
+     */
+    private runRequestInterceptors;
+    /**
+     * 执行响应拦截器链
+     */
+    private runResponseInterceptors;
+    /**
+     * 构建完整 URL（包含 baseURL 和 query params）
+     */
+    private buildUrl;
+}
+
+export { type CustomClaims, DEFAULT_CLOCK_TOLERANCE_SEC, DEFAULT_JWT_EXPIRE_TIME_MS, HttpClient, type HttpClientConfig, HttpError, type JWTClaims, type JWTConfig, type JWTVerifyOptions, type PlatformClaims, type PlatformPluginOptions, type PlatformRequestAuthConfig, type RequestConfig, type RequestInterceptor, type ResponseInterceptor, type SafeRequestConfig, type SecurityConfig, generateJWTToken, parseJWTTokenWithVerify, registerPlatformPlugin, resolvePlatformBaseURL };

package/dist/index.d.ts

@@ -0,0 +1,323 @@
+/**
+ * 拦截器管理器（模仿 Axios 的 InterceptorManager）
+ */
+declare class InterceptorManager<T> {
+    private interceptors;
+    /**
+     * 添加拦截器
+     * @returns 拦截器 ID，用于后续移除
+     */
+    use(onFulfilled?: any, onRejected?: any): number;
+    /**
+     * 移除拦截器
+     */
+    eject(id: number): void;
+    /**
+     * 清空所有拦截器
+     */
+    clear(): void;
+    /**
+     * 遍历所有拦截器
+     */
+    forEach(fn: (interceptor: T) => void): void;
+}
+
+interface CustomClaims {
+    tenant_id?: number;
+    user_id?: string;
+    app_id?: string;
+    app_env?: string;
+    sandbox_id?: string;
+    access_key: string;
+}
+interface JWTClaims extends CustomClaims {
+    iss: string;
+    iat: number;
+    nbf: number;
+    exp: number;
+    jti: string;
+    [key: string]: any;
+}
+interface JWTConfig {
+    accessKey: string;
+    secretKey: string;
+    expireTimeMs: number;
+}
+interface JWTVerifyOptions {
+    /**
+     * 时钟容差（秒），用于处理服务器时间不同步的情况
+     * 默认 60 秒
+     */
+    clockTolerance?: number;
+    /**
+     * 是否跳过过期验证（仅用于调试）
+     * 默认 false
+     */
+    skipExpiration?: boolean;
+}
+declare const DEFAULT_JWT_EXPIRE_TIME_MS: number;
+declare const DEFAULT_CLOCK_TOLERANCE_SEC = 60;
+declare function generateJWTToken(customClaims: CustomClaims, config: JWTConfig): string;
+declare function parseJWTTokenWithVerify(tokenString: string, config: JWTConfig, options?: JWTVerifyOptions): JWTClaims;
+
+interface JWTManagerConfig extends JWTConfig {
+    /**
+     * 在过期前多久刷新 token（毫秒）
+     * 默认 5 分钟
+     */
+    refreshBeforeMs?: number;
+}
+/**
+ * JWT Token 管理器，负责 token 的生成、缓存和自动刷新
+ *
+ * 缓存策略：
+ * - 基于 claims 的哈希值作为缓存 key（支持多租户+多用户）
+ * - 在 token 过期前 refreshBeforeMs 时间内自动刷新
+ *
+ * @example
+ * ```typescript
+ * const manager = new JWTTokenManager({
+ *   accessKey: 'your-access-key',
+ *   secretKey: 'your-secret-key',
+ *   expireTimeMs: 30 * 60 * 1000,
+ *   refreshBeforeMs: 5 * 60 * 1000,
+ * });
+ *
+ * // 获取 token（会自动缓存）
+ * const token = manager.getToken({
+ *   access_key: 'your-access-key',
+ *   tenant_id: 1001,
+ *   user_id: 'user123',
+ * });
+ * ```
+ */
+declare class JWTTokenManager {
+    private cache;
+    private config;
+    constructor(config: JWTManagerConfig);
+    /**
+     * 获取 JWT token，优先使用缓存
+     *
+     * 如果缓存的 token 即将过期（距离过期时间小于 refreshBeforeMs），
+     * 则会生成新的 token 并更新缓存
+     *
+     * @param claims - JWT claims
+     * @returns JWT token 字符串
+     */
+    getToken(claims: CustomClaims): string;
+    /**
+     * 清除所有缓存的 token
+     */
+    clearCache(): void;
+    /**
+     * 清除特定 claims 的缓存
+     *
+     * @param claims - 要清除的 claims
+     */
+    clearCacheFor(claims: CustomClaims): void;
+    /**
+     * 生成缓存 key（基于关键的 claims 字段）
+     *
+     * 使用稳定的字段顺序确保相同 claims 生成相同 key
+     *
+     * @private
+     */
+    private getCacheKey;
+    /**
+     * 获取缓存统计信息（用于监控和调试）
+     *
+     * @returns 缓存统计信息
+     */
+    getCacheStats(): {
+        total: number;
+        valid: number;
+        expired: number;
+    };
+}
+
+type PlatformClaims = Omit<CustomClaims, 'access_key'>;
+interface PlatformPluginOptions {
+    enabled?: boolean;
+    baseURL?: string;
+    domainEnv?: string;
+    accessKeyEnv?: string;
+    secretKeyEnv?: string;
+    accessKey?: string;
+    secretKey?: string;
+    expireTimeMs?: number;
+    refreshBeforeMs?: number;
+    defaultClaims?: PlatformClaims;
+}
+interface PlatformRequestAuthConfig {
+    customClaims?: PlatformClaims;
+}
+declare function resolvePlatformBaseURL(options?: PlatformPluginOptions): string | undefined;
+type RequestInterceptorManager = {
+    use: (onFulfilled?: RequestInterceptor['onFulfilled'], onRejected?: RequestInterceptor['onRejected']) => number;
+    eject: (id: number) => void;
+};
+interface InterceptorHost {
+    request: RequestInterceptorManager;
+}
+declare function registerPlatformPlugin(interceptors: InterceptorHost, options: PlatformPluginOptions): JWTTokenManager | undefined;
+
+/**
+ * 清理后的请求配置（移除敏感信息）
+ */
+interface SafeRequestConfig extends Omit<RequestConfig, 'headers'> {
+    headers?: Record<string, string>;
+}
+/**
+ * HTTP 错误对象
+ *
+ * 注意：为了安全考虑，error.config 中的敏感 headers (如 Authorization, x-api-key)
+ * 会被替换为 '[REDACTED]'
+ */
+declare class HttpError extends Error {
+    readonly isHttpError: boolean;
+    response: Response | undefined;
+    config: SafeRequestConfig;
+    constructor(response: Response | undefined, config: RequestConfig, message?: string);
+}
+interface RequestConfig extends RequestInit {
+    url?: string;
+    params?: Record<string, any>;
+    timeout?: number;
+    baseURL?: string;
+    platformAuth?: PlatformRequestAuthConfig;
+}
+interface SecurityConfig {
+    /**
+     * 允许的 URL 协议白名单
+     * 默认: null (不限制)
+     * 设置为 ['http:', 'https:'] 可限制只允许 HTTP/HTTPS
+     */
+    allowedProtocols?: string[] | null;
+    /**
+     * 最大响应体大小（字节）
+     * 默认: 0 (不限制)
+     * 设置为正数可限制响应体大小，防止内存耗尽攻击
+     */
+    maxResponseSize?: number;
+    /**
+     * 是否启用严格模式（启用所有安全检查）
+     * 默认: false
+     * 启用后会自动设置：
+     * - allowedProtocols = ['http:', 'https:']
+     * - maxResponseSize = 50MB
+     */
+    strictMode?: boolean;
+}
+interface HttpClientConfig extends RequestConfig {
+    platform?: PlatformPluginOptions;
+    security?: SecurityConfig;
+}
+/**
+ * 请求拦截器函数
+ */
+type RequestInterceptor = {
+    onFulfilled?: (config: RequestConfig) => RequestConfig | Promise<RequestConfig>;
+    onRejected?: (error: any) => any;
+};
+/**
+ * 响应拦截器函数（fetch 风格）
+ */
+type ResponseInterceptor = {
+    onFulfilled?: (response: Response) => Response | Promise<Response>;
+    onRejected?: (error: any) => any;
+};
+
+/**
+ * 技术栈无关的 HTTP 客户端
+ *
+ * 设计理念：
+ * - 基于原生 fetch API，零依赖
+ * - 拦截器模式遵循 Axios 标准，AI 模型和开发者都熟悉
+ * - 可在任何 Node.js 环境使用（NestJS, Express, Koa, 纯 Node）
+ *
+ * @example
+ * ```typescript
+ * const client = new HttpClient({
+ *   baseURL: 'https://api.example.com',
+ *   timeout: 5000,
+ * });
+ *
+ * // 添加请求拦截器（类似 Axios）
+ * client.interceptors.request.use(
+ *   config => {
+ *     config.headers = config.headers || {};
+ *     config.headers['Authorization'] = 'Bearer token';
+ *     return config;
+ *   },
+ *   error => Promise.reject(error)
+ * );
+ *
+ * // 添加响应拦截器（类似 Axios）
+ * client.interceptors.response.use(
+ *   response => {
+ *     console.log('Response:', response.status);
+ *     return response;
+ *   },
+ *   error => {
+ *     if (error.response?.status === 401) {
+ *       // 处理未授权
+ *     }
+ *     return Promise.reject(error);
+ *   }
+ * );
+ *
+ * // 发起请求
+ * const response = await client.get('/users');
+ * console.log(response.data);
+ * ```
+ */
+declare class HttpClient {
+    private defaultConfig;
+    private securityConfig;
+    /**
+     * 拦截器管理器（API 与 Axios 一致）
+     */
+    interceptors: {
+        request: InterceptorManager<RequestInterceptor>;
+        response: InterceptorManager<ResponseInterceptor>;
+    };
+    constructor(config?: HttpClientConfig);
+    /**
+     * GET 请求
+     */
+    get(url: string, config?: RequestConfig): Promise<Response>;
+    /**
+     * POST 请求
+     */
+    post(url: string, data?: any, config?: RequestConfig): Promise<Response>;
+    /**
+     * PUT 请求
+     */
+    put(url: string, data?: any, config?: RequestConfig): Promise<Response>;
+    /**
+     * DELETE 请求
+     */
+    delete(url: string, config?: RequestConfig): Promise<Response>;
+    /**
+     * PATCH 请求
+     */
+    patch(url: string, data?: any, config?: RequestConfig): Promise<Response>;
+    /**
+     * 核心请求方法（fetch 风格）
+     */
+    request(config: RequestConfig): Promise<Response>;
+    /**
+     * 执行请求拦截器链
+     */
+    private runRequestInterceptors;
+    /**
+     * 执行响应拦截器链
+     */
+    private runResponseInterceptors;
+    /**
+     * 构建完整 URL（包含 baseURL 和 query params）
+     */
+    private buildUrl;
+}
+
+export { type CustomClaims, DEFAULT_CLOCK_TOLERANCE_SEC, DEFAULT_JWT_EXPIRE_TIME_MS, HttpClient, type HttpClientConfig, HttpError, type JWTClaims, type JWTConfig, type JWTVerifyOptions, type PlatformClaims, type PlatformPluginOptions, type PlatformRequestAuthConfig, type RequestConfig, type RequestInterceptor, type ResponseInterceptor, type SafeRequestConfig, type SecurityConfig, generateJWTToken, parseJWTTokenWithVerify, registerPlatformPlugin, resolvePlatformBaseURL };