meeglesdk 0.1.0

package/dist/core/request.d.ts

@@ -0,0 +1,270 @@
+/**
+ * HTTP 请求处理器
+ * 100% 参考 Meego API 文档
+ *
+ * 请求头规范:
+ * - Content-Type: application/json
+ * - X-Plugin-Token: {plugin_access_token | user_access_token}
+ * - X-User-Key: {user_key} (使用 plugin_token 时必须)
+ * - X-IDEM-UUID: {unique-id} (幂等标识，可选)
+ */
+import type { Logger, PaginatedResult, PaginatedObjectResult } from '../types/common.js';
+import type { TokenManager } from './token-manager.js';
+import type { RateLimitConfig } from './rate-limiter.js';
+/** 请求方法 */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+/** 认证上下文（每个请求可独立指定） */
+export type AuthContext = {
+    type: 'user';
+    token: string;
+} | {
+    type: 'plugin';
+    token?: string;
+    userKey?: string;
+} | {
+    type: 'auto';
+    userKey?: string;
+};
+/** 响应数据校验器 */
+export type ResponseValidator<T> = (data: unknown) => data is T;
+/** 基础请求配置（不含响应验证器） */
+interface BaseRequestConfig {
+    /** HTTP 方法 */
+    method: HttpMethod;
+    /** API 路径（可包含路径参数如 :project_key） */
+    path: string;
+    /** 路径参数 */
+    pathParams?: Record<string, string>;
+    /** 查询参数 */
+    query?: Record<string, unknown>;
+    /** 请求体 */
+    body?: unknown;
+    /** 认证上下文（推荐显式传入） */
+    auth?: AuthContext;
+    /** 幂等键（可选） */
+    idempotencyKey?: string;
+    /** 请求超时（毫秒） */
+    timeout?: number;
+    /** 取消信号 */
+    signal?: AbortSignal;
+    /** 是否跳过重试 */
+    skipRetry?: boolean;
+    /** 重试配置（可选，覆盖默认配置） */
+    retry?: Partial<RetryConfig>;
+}
+/** 请求配置 */
+export interface RequestConfig<T = unknown> extends BaseRequestConfig {
+    /** 响应数据校验（可选） */
+    responseValidator?: ResponseValidator<T>;
+}
+/** 文件上传配置 */
+export interface UploadConfig<T = unknown> {
+    /** API 路径（可包含路径参数如 :project_key） */
+    path: string;
+    /** 路径参数 */
+    pathParams?: Record<string, string>;
+    /** 文件数据 (Blob/File/Buffer) */
+    file: Blob | File | Buffer;
+    /** 文件名 */
+    fileName: string;
+    /** 表单字段名（默认 'file'） */
+    fieldName?: string;
+    /** 额外的表单字段 */
+    formFields?: Record<string, string>;
+    /** 认证上下文 */
+    auth?: AuthContext;
+    /** 请求超时（毫秒） */
+    timeout?: number;
+    /** 上传文件大小上限（字节），默认 100,000,000 */
+    maxUploadSizeBytes?: number;
+    /** 上传文件大小下限（字节），默认 1（禁止空文件） */
+    minUploadSizeBytes?: number;
+    /** 是否跳过重试 */
+    skipRetry?: boolean;
+    /** 重试配置（可选，覆盖默认配置） */
+    retry?: Partial<RetryConfig>;
+    /** 响应数据校验（可选） */
+    responseValidator?: ResponseValidator<T>;
+}
+/** 文件下载配置 */
+export interface DownloadConfig {
+    /** API 路径 */
+    path: string;
+    /** 路径参数 */
+    pathParams?: Record<string, string>;
+    /** 请求体 */
+    body?: unknown;
+    /** 认证上下文 */
+    auth?: AuthContext;
+    /** 请求超时（毫秒） */
+    timeout?: number;
+    /** 取消信号 */
+    signal?: AbortSignal;
+    /** 下载进度回调 */
+    onProgress?: (progress: DownloadProgress) => void;
+    /** 分块回调（流式下载时可用于写文件） */
+    onChunk?: (chunk: Uint8Array, progress: DownloadProgress) => void;
+    /** 是否跳过重试 */
+    skipRetry?: boolean;
+    /** 重试配置（可选，覆盖默认配置） */
+    retry?: Partial<RetryConfig>;
+}
+/** 下载进度 */
+export interface DownloadProgress {
+    /** 已接收字节数 */
+    receivedBytes: number;
+    /** 总字节数（如响应头中包含 content-length） */
+    totalBytes?: number;
+    /** 进度 (0-1)，仅在 totalBytes 可用时计算 */
+    progress?: number;
+}
+/** 重试配置 */
+export interface RetryConfig {
+    /** 最大重试次数 */
+    maxRetries: number;
+    /** 初始重试延迟（毫秒） */
+    retryDelay: number;
+    /** 最大重试延迟（毫秒，默认 30000） */
+    maxRetryDelay?: number;
+    /** 可重试的错误码 */
+    retryableErrorCodes: number[];
+}
+/** 请求处理器选项 */
+export interface RequestHandlerOptions {
+    /** API 基础 URL */
+    baseURL: string;
+    /** Token 管理器 */
+    tokenManager: TokenManager;
+    /** Logger */
+    logger: Logger;
+    /** 默认超时（毫秒） */
+    timeout?: number;
+    /** 重试配置 */
+    retry?: Partial<RetryConfig>;
+    /** 本地限流（可选） */
+    rateLimit?: RateLimitConfig;
+}
+export declare class RequestHandler {
+    private readonly baseURL;
+    private readonly tokenManager;
+    private readonly logger;
+    private readonly timeout;
+    private readonly retryConfig;
+    private readonly rateLimitManager?;
+    constructor(options: RequestHandlerOptions);
+    /**
+     * 发送请求
+     */
+    request<T>(config: RequestConfig<T>): Promise<T>;
+    /**
+     * 发送分页请求
+     * 用于 pagination 与 data 同级的接口（如子任务搜索）
+     */
+    requestPaginated<T>(config: RequestConfig<T>): Promise<PaginatedResult<T>>;
+    /**
+     * 发送请求（自定义响应字段）
+     * 用于响应数据字段不是 data 的接口
+     */
+    requestWithResponseKey<T>(config: RequestConfig<T>, responseKey: string): Promise<T>;
+    /**
+     * 发送分页请求（data 为对象，pagination 与 data 同级）
+     */
+    requestWithPagination<T>(config: RequestConfig<T>): Promise<PaginatedObjectResult<T>>;
+    /**
+     * 构建请求头
+     */
+    private buildHeaders;
+    /**
+     * 解析路径参数
+     * 例如: /open_api/:project_key/work_item -> /open_api/my-project/work_item
+     */
+    private resolvePath;
+    private validatePathParams;
+    /**
+     * 构建查询字符串
+     */
+    private buildQueryString;
+    /**
+     * 判断是否应该重试
+     */
+    private shouldRetry;
+    /**
+     * 睡眠
+     */
+    private sleep;
+    /**
+     * 安全解析 JSON，将大整数转换为字符串
+     * 解决 JavaScript Number 无法精确表示超过 2^53-1 的整数问题
+     *
+     * 处理场景：
+     * - 对象属性值: {"id": 1234567890123456789}
+     * - 数组元素: [1234567890123456789]
+     * - 嵌套数组: [[1234567890123456789]]
+     * - 负数大整数: -1234567890123456789
+     */
+    private parseJsonSafely;
+    private getUploadFileSize;
+    /**
+     * 上传文件
+     * 使用 multipart/form-data 格式
+     */
+    upload<T>(config: UploadConfig<T>): Promise<T>;
+    /**
+     * 下载文件
+     * 返回二进制数据 (ArrayBuffer)
+     */
+    download(config: DownloadConfig): Promise<ArrayBuffer>;
+    /**
+     * 下载文件（流式）
+     * 返回 ReadableStream<Uint8Array>
+     */
+    downloadStream(config: DownloadConfig): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * 构建文件上传请求头 (不包含 Content-Type)
+     */
+    private buildHeadersForUpload;
+    /**
+     * 构建鉴权请求头
+     */
+    private buildAuthHeaders;
+    /**
+     * 构建请求上下文
+     */
+    private prepareRequest;
+    /**
+     * 执行带重试的请求
+     * @param config 基础请求配置（不含 responseValidator）
+     * @param executor 执行器函数，负责实际的请求解析
+     */
+    private executeWithRetry;
+    private executeWithRetryContext;
+    private resolveRetryConfig;
+    /**
+     * 执行单次请求（统一超时与错误处理）
+     */
+    private executeOnce;
+    /**
+     * 解析通用响应包裹
+     */
+    private parseEnvelope;
+    private validateResponse;
+    /**
+     * 验证数组响应的每个元素
+     * 用于分页响应，将单元素验证器应用于数组中的每个元素
+     */
+    private validateArrayResponse;
+    private parseDataResponse;
+    private parsePaginatedResponse;
+    private parsePaginatedObjectResponse;
+    private parseResponseKeyResponse;
+    private parseDownloadResponse;
+    private parseDownloadStreamResponse;
+    private getContentLength;
+    private buildDownloadProgress;
+    private emitDownloadProgress;
+    private readStreamToArrayBuffer;
+    private wrapStreamWithProgress;
+    private buildUrlWithResolvedPath;
+}
+export {};
+//# sourceMappingURL=request.d.ts.map

package/dist/core/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/core/request.ts"],"names":[],"mappings":"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"}