meeglesdk 0.1.0

package/dist/core/request.js

@@ -0,0 +1,842 @@
+/**
+ * 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 { MeegoError, MeegoAuthError, MeegoNetworkError, MeegoTimeoutError, MeegoAbortError, ErrorCodes, } from './errors.js';
+import { RateLimitManager, normalizeRateLimitOptions } from './rate-limiter.js';
+class HttpStatusError extends Error {
+    status;
+    constructor(status, statusText) {
+        super(`HTTP error: ${status} ${statusText}`);
+        this.name = 'HttpStatusError';
+        this.status = status;
+        Object.setPrototypeOf(this, HttpStatusError.prototype);
+    }
+}
+/** 默认超时 30 秒 */
+const DEFAULT_TIMEOUT = 30000;
+/** 默认上传大小上限 100MB (10^6) */
+const DEFAULT_UPLOAD_MAX_BYTES = 100_000_000;
+/** 默认上传大小下限 1 字节（禁空文件） */
+const DEFAULT_UPLOAD_MIN_BYTES = 1;
+/** 默认最大重试延迟 30 秒 */
+const DEFAULT_MAX_RETRY_DELAY = 30000;
+/** 默认重试配置 */
+const DEFAULT_RETRY_CONFIG = {
+    maxRetries: 2,
+    retryDelay: 1000,
+    maxRetryDelay: DEFAULT_MAX_RETRY_DELAY,
+    retryableErrorCodes: [
+        ErrorCodes.API_REQUEST_FREQUENCY_LIMIT, // 10429
+        ErrorCodes.RPC_CALL_ERROR, // 50006
+    ],
+};
+export class RequestHandler {
+    baseURL;
+    tokenManager;
+    logger;
+    timeout;
+    retryConfig;
+    rateLimitManager;
+    constructor(options) {
+        this.baseURL = options.baseURL.replace(/\/$/, ''); // 移除尾部斜杠
+        this.tokenManager = options.tokenManager;
+        this.logger = options.logger;
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        this.retryConfig = {
+            ...DEFAULT_RETRY_CONFIG,
+            ...options.retry,
+        };
+        const rateLimitOptions = normalizeRateLimitOptions(options.rateLimit);
+        if (rateLimitOptions && rateLimitOptions.enabled !== false) {
+            this.rateLimitManager = new RateLimitManager(rateLimitOptions);
+        }
+    }
+    /**
+     * 发送请求
+     */
+    async request(config) {
+        return this.executeWithRetry(config, (context) => this.executeOnce(context, (response) => this.parseDataResponse(response, config.responseValidator)));
+    }
+    /**
+     * 发送分页请求
+     * 用于 pagination 与 data 同级的接口（如子任务搜索）
+     */
+    async requestPaginated(config) {
+        return this.executeWithRetry(config, (context) => this.executeOnce(context, (response) => this.parsePaginatedResponse(response, config.responseValidator)));
+    }
+    /**
+     * 发送请求（自定义响应字段）
+     * 用于响应数据字段不是 data 的接口
+     */
+    async requestWithResponseKey(config, responseKey) {
+        return this.executeWithRetry(config, (context) => this.executeOnce(context, (response) => this.parseResponseKeyResponse(response, responseKey, config.responseValidator)));
+    }
+    /**
+     * 发送分页请求（data 为对象，pagination 与 data 同级）
+     */
+    async requestWithPagination(config) {
+        return this.executeWithRetry(config, (context) => this.executeOnce(context, (response) => this.parsePaginatedObjectResponse(response, config.responseValidator)));
+    }
+    /**
+     * 构建请求头
+     */
+    async buildHeaders(auth, idempotencyKey) {
+        const headers = await this.buildAuthHeaders(auth);
+        headers['Content-Type'] = 'application/json';
+        // 幂等键
+        if (idempotencyKey) {
+            headers['X-IDEM-UUID'] = idempotencyKey;
+        }
+        return headers;
+    }
+    /**
+     * 解析路径参数
+     * 例如: /open_api/:project_key/work_item -> /open_api/my-project/work_item
+     */
+    resolvePath(path, params) {
+        this.validatePathParams(path, params);
+        if (!params) {
+            return path;
+        }
+        let resolvedPath = path;
+        for (const [key, value] of Object.entries(params)) {
+            const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            resolvedPath = resolvedPath.replace(new RegExp(`:${escapedKey}`, 'g'), encodeURIComponent(String(value)));
+        }
+        return resolvedPath;
+    }
+    validatePathParams(path, params) {
+        const matches = Array.from(path.matchAll(/:([^/]+)/g));
+        if (matches.length === 0) {
+            return;
+        }
+        const requiredKeys = matches.map((match) => match[1]);
+        const missingKeys = [];
+        const emptyKeys = [];
+        for (const key of requiredKeys) {
+            const value = params?.[key];
+            if (value === undefined || value === null) {
+                missingKeys.push(key);
+            }
+            else if (String(value).length === 0) {
+                emptyKeys.push(key);
+            }
+        }
+        if (missingKeys.length > 0) {
+            const message = `Missing required path params: ${missingKeys.join(', ')}`;
+            throw new MeegoError(`[${ErrorCodes.MISSING_PARAM}] ${message}`, ErrorCodes.MISSING_PARAM, message, { missing: missingKeys });
+        }
+        if (emptyKeys.length > 0) {
+            const message = `Empty path params: ${emptyKeys.join(', ')}`;
+            throw new MeegoError(`[${ErrorCodes.INVALID_PARAM}] ${message}`, ErrorCodes.INVALID_PARAM, message, { empty: emptyKeys });
+        }
+    }
+    /**
+     * 构建查询字符串
+     */
+    buildQueryString(query) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            if (value === undefined || value === null) {
+                continue;
+            }
+            if (Array.isArray(value)) {
+                // 数组参数
+                for (const item of value) {
+                    params.append(key, String(item));
+                }
+            }
+            else if (typeof value === 'object') {
+                // 对象参数，JSON 序列化
+                params.append(key, JSON.stringify(value));
+            }
+            else {
+                params.append(key, String(value));
+            }
+        }
+        return params.toString();
+    }
+    /**
+     * 判断是否应该重试
+     */
+    shouldRetry(error, retryableErrorCodes) {
+        if (error instanceof MeegoAbortError) {
+            return false;
+        }
+        if (error instanceof MeegoError) {
+            return retryableErrorCodes.includes(error.errCode);
+        }
+        if (error instanceof MeegoNetworkError) {
+            // 网络错误可以重试
+            return true;
+        }
+        if (error instanceof MeegoTimeoutError) {
+            // 超时可以重试
+            return true;
+        }
+        return false;
+    }
+    /**
+     * 睡眠
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * 安全解析 JSON，将大整数转换为字符串
+     * 解决 JavaScript Number 无法精确表示超过 2^53-1 的整数问题
+     *
+     * 处理场景：
+     * - 对象属性值: {"id": 1234567890123456789}
+     * - 数组元素: [1234567890123456789]
+     * - 嵌套数组: [[1234567890123456789]]
+     * - 负数大整数: -1234567890123456789
+     */
+    parseJsonSafely(text) {
+        // 匹配 JSON 中的大整数（16位及以上），并转换为字符串
+        // 覆盖场景：
+        // - 根级数字（无前缀）
+        // - 对象属性值/数组元素
+        // - 科学计数法（仅处理整数形式且指数为正）
+        const bigIntPattern = /(^|[{\[:,])(\s*)(-?\d{16,})(?=\s*(?:[,\]\}]|$))/g;
+        const scientificPattern = /(^|[{\[:,])(\s*)(-?\d+(?:\.\d+)?[eE][+-]?\d+)(?=\s*(?:[,\]\}]|$))/g;
+        const wrapScientific = (value) => {
+            if (value.includes('.')) {
+                return false;
+            }
+            const parts = value.split(/e/i);
+            if (parts.length !== 2) {
+                return false;
+            }
+            const exp = Number.parseInt(parts[1], 10);
+            if (!Number.isFinite(exp) || exp < 0) {
+                return false;
+            }
+            const digits = parts[0].replace(/^-/, '');
+            const totalDigits = digits.length + exp;
+            return totalDigits >= 16;
+        };
+        const safeText = text
+            .replace(bigIntPattern, '$1$2"$3"')
+            .replace(scientificPattern, (match, prefix, spacing, value) => wrapScientific(value) ? `${prefix}${spacing}"${value}"` : match);
+        return JSON.parse(safeText);
+    }
+    getUploadFileSize(file) {
+        if (Buffer.isBuffer(file)) {
+            return file.byteLength;
+        }
+        const maybeSize = file.size;
+        return typeof maybeSize === 'number' && Number.isFinite(maybeSize) ? maybeSize : undefined;
+    }
+    /**
+     * 上传文件
+     * 使用 multipart/form-data 格式
+     */
+    async upload(config) {
+        const { path, pathParams, file, fileName, fieldName = 'file', formFields, auth, timeout, maxUploadSizeBytes, minUploadSizeBytes, skipRetry, retry, responseValidator, } = config;
+        const fileSize = this.getUploadFileSize(file);
+        const maxBytes = maxUploadSizeBytes ?? DEFAULT_UPLOAD_MAX_BYTES;
+        const minBytes = minUploadSizeBytes ?? DEFAULT_UPLOAD_MIN_BYTES;
+        if (typeof fileSize === 'number' && fileSize < minBytes) {
+            const minMessage = minBytes === DEFAULT_UPLOAD_MIN_BYTES
+                ? 'Uploaded File Size Must Be Greater Than 0'
+                : `Uploaded File Size Must Be At Least ${minBytes} bytes`;
+            throw new MeegoError(`[${ErrorCodes.INVALID_PARAM}] ${minMessage}`, ErrorCodes.INVALID_PARAM, minMessage, { code: ErrorCodes.INVALID_PARAM, msg: minMessage });
+        }
+        if (typeof fileSize === 'number' && fileSize > maxBytes) {
+            const limitMessage = maxBytes === DEFAULT_UPLOAD_MAX_BYTES
+                ? 'Uploaded File Size Limit 100M'
+                : `Uploaded File Size Limit ${maxBytes} bytes`;
+            throw new MeegoError(`[${ErrorCodes.UPLOAD_FILE_SIZE_LIMIT_100M}] ${limitMessage}`, ErrorCodes.UPLOAD_FILE_SIZE_LIMIT_100M, limitMessage, { code: ErrorCodes.UPLOAD_FILE_SIZE_LIMIT_100M, msg: limitMessage });
+        }
+        const resolvedPath = this.resolvePath(path, pathParams);
+        const url = this.buildUrlWithResolvedPath(resolvedPath);
+        // 构建 FormData
+        const formData = new FormData();
+        // 添加文件
+        // 处理 Buffer (Node.js) 和 Blob/File (浏览器/Bun) 的兼容性
+        if (Buffer.isBuffer(file)) {
+            // Buffer 可能是底层 ArrayBuffer 的部分视图，需要使用正确的 offset 切片
+            // 使用 slice 获取独立的 ArrayBuffer 以确保兼容性
+            // 注意：Node.js Buffer 的 buffer 属性可能是 SharedArrayBuffer，但 slice 返回的是 ArrayBuffer
+            const arrayBuffer = file.buffer.slice(file.byteOffset, file.byteOffset + file.byteLength);
+            formData.append(fieldName, new Blob([arrayBuffer]), fileName);
+        }
+        else {
+            formData.append(fieldName, file, fileName);
+        }
+        // 添加额外字段
+        if (formFields) {
+            for (const [key, value] of Object.entries(formFields)) {
+                formData.append(key, value);
+            }
+        }
+        // 构建请求头 (不设置 Content-Type，让浏览器/运行时自动设置)
+        const headers = await this.buildHeadersForUpload(auth);
+        const rateLimitContext = this.rateLimitManager
+            ? { token: headers['X-Plugin-Token'], method: 'POST', path: resolvedPath }
+            : undefined;
+        const context = {
+            url,
+            requestInit: {
+                method: 'POST',
+                headers,
+                body: formData,
+            },
+            timeout: timeout ?? this.timeout,
+            rateLimitContext,
+        };
+        return this.executeWithRetryContext(context, { skipRetry, retry }, () => this.executeOnce(context, (response) => this.parseDataResponse(response, responseValidator), 'Upload failed'));
+    }
+    /**
+     * 下载文件
+     * 返回二进制数据 (ArrayBuffer)
+     */
+    async download(config) {
+        const { path, pathParams, body, auth, timeout, skipRetry, retry, signal, onProgress, onChunk } = config;
+        const resolvedPath = this.resolvePath(path, pathParams);
+        const url = this.buildUrlWithResolvedPath(resolvedPath);
+        // 构建请求头
+        const headers = await this.buildHeaders(auth, undefined);
+        const rateLimitContext = this.rateLimitManager
+            ? { token: headers['X-Plugin-Token'], method: 'POST', path: resolvedPath }
+            : undefined;
+        const context = {
+            url,
+            requestInit: {
+                method: 'POST',
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+            },
+            timeout: timeout ?? this.timeout,
+            rateLimitContext,
+            signal,
+        };
+        const progressOptions = { onProgress, onChunk, signal };
+        return this.executeWithRetryContext(context, { skipRetry, retry }, () => this.executeOnce(context, (response) => this.parseDownloadResponse(response, progressOptions), 'Download failed'));
+    }
+    /**
+     * 下载文件（流式）
+     * 返回 ReadableStream<Uint8Array>
+     */
+    async downloadStream(config) {
+        const { path, pathParams, body, auth, timeout, skipRetry, retry, signal, onProgress, onChunk } = config;
+        const resolvedPath = this.resolvePath(path, pathParams);
+        const url = this.buildUrlWithResolvedPath(resolvedPath);
+        // 构建请求头
+        const headers = await this.buildHeaders(auth, undefined);
+        const rateLimitContext = this.rateLimitManager
+            ? { token: headers['X-Plugin-Token'], method: 'POST', path: resolvedPath }
+            : undefined;
+        const context = {
+            url,
+            requestInit: {
+                method: 'POST',
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+            },
+            timeout: timeout ?? this.timeout,
+            rateLimitContext,
+            signal,
+        };
+        const progressOptions = { onProgress, onChunk, signal };
+        return this.executeWithRetryContext(context, { skipRetry, retry }, () => this.executeOnce(context, (response) => this.parseDownloadStreamResponse(response, progressOptions), 'Download failed'));
+    }
+    /**
+     * 构建文件上传请求头 (不包含 Content-Type)
+     */
+    async buildHeadersForUpload(auth) {
+        return this.buildAuthHeaders(auth);
+    }
+    /**
+     * 构建鉴权请求头
+     */
+    async buildAuthHeaders(auth) {
+        const headers = {};
+        const context = auth ?? { type: 'auto' };
+        if (context.type === 'user') {
+            if (!context.token) {
+                throw new MeegoAuthError(0, 'User token not available');
+            }
+            headers['X-Plugin-Token'] = context.token;
+            return headers;
+        }
+        if (context.type === 'plugin') {
+            const token = context.token ?? (await this.tokenManager.getPluginToken());
+            headers['X-Plugin-Token'] = token;
+            if (context.userKey) {
+                headers['X-User-Key'] = context.userKey;
+            }
+            else {
+                this.logger.debug('Plugin auth used without userKey');
+            }
+            return headers;
+        }
+        const userKey = context.userKey;
+        if (userKey) {
+            const userToken = await this.tokenManager.getUserToken(userKey);
+            if (userToken) {
+                headers['X-Plugin-Token'] = userToken;
+                return headers;
+            }
+            const pluginToken = await this.tokenManager.getPluginToken();
+            headers['X-Plugin-Token'] = pluginToken;
+            headers['X-User-Key'] = userKey;
+            return headers;
+        }
+        const pluginToken = await this.tokenManager.getPluginToken();
+        headers['X-Plugin-Token'] = pluginToken;
+        return headers;
+    }
+    /**
+     * 构建请求上下文
+     */
+    async prepareRequest(config) {
+        const { method, path, pathParams, query, body, auth, idempotencyKey, signal } = config;
+        const resolvedPath = this.resolvePath(path, pathParams);
+        const url = this.buildUrlWithResolvedPath(resolvedPath, query);
+        const headers = await this.buildHeaders(auth, idempotencyKey);
+        const rateLimitContext = this.rateLimitManager
+            ? { token: headers['X-Plugin-Token'], method, path: resolvedPath }
+            : undefined;
+        const requestInit = {
+            method,
+            headers,
+        };
+        if (body !== undefined) {
+            requestInit.body = JSON.stringify(body);
+        }
+        return { url, requestInit, rateLimitContext, signal };
+    }
+    /**
+     * 执行带重试的请求
+     * @param config 基础请求配置（不含 responseValidator）
+     * @param executor 执行器函数，负责实际的请求解析
+     */
+    async executeWithRetry(config, executor) {
+        const { url, requestInit, rateLimitContext, signal } = await this.prepareRequest(config);
+        const context = {
+            url,
+            requestInit,
+            timeout: config.timeout ?? this.timeout,
+            rateLimitContext,
+            signal,
+        };
+        return this.executeWithRetryContext(context, { skipRetry: config.skipRetry, retry: config.retry }, () => executor(context));
+    }
+    async executeWithRetryContext(context, options, executor) {
+        const retryConfig = this.resolveRetryConfig(options.retry);
+        const maxAttempts = options.skipRetry ? 1 : retryConfig.maxRetries + 1;
+        let lastError;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                return await executor();
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < maxAttempts && this.shouldRetry(error, retryConfig.retryableErrorCodes)) {
+                    const baseDelay = retryConfig.retryDelay * Math.pow(2, attempt - 1);
+                    const maxDelay = typeof retryConfig.maxRetryDelay === 'number' && Number.isFinite(retryConfig.maxRetryDelay)
+                        ? retryConfig.maxRetryDelay
+                        : undefined;
+                    const delay = maxDelay && maxDelay > 0 ? Math.min(baseDelay, maxDelay) : baseDelay;
+                    this.logger.warn(`Request failed, retrying in ${delay}ms (attempt ${attempt}/${maxAttempts})`, {
+                        url: context.url,
+                        error: error.message,
+                    });
+                    await this.sleep(delay);
+                    continue;
+                }
+                throw error;
+            }
+        }
+        throw lastError;
+    }
+    resolveRetryConfig(override) {
+        if (!override) {
+            return this.retryConfig;
+        }
+        return {
+            maxRetries: override.maxRetries ?? this.retryConfig.maxRetries,
+            retryDelay: override.retryDelay ?? this.retryConfig.retryDelay,
+            maxRetryDelay: override.maxRetryDelay ?? this.retryConfig.maxRetryDelay,
+            retryableErrorCodes: override.retryableErrorCodes ?? this.retryConfig.retryableErrorCodes,
+        };
+    }
+    /**
+     * 执行单次请求（统一超时与错误处理）
+     */
+    async executeOnce(context, parser, errorPrefix = 'Request failed') {
+        if (context.rateLimitContext && this.rateLimitManager) {
+            await this.rateLimitManager.acquire(context.rateLimitContext);
+        }
+        const controller = new AbortController();
+        let timedOut = false;
+        let abortedByUser = false;
+        const handleAbort = () => {
+            abortedByUser = true;
+            controller.abort();
+        };
+        if (context.signal) {
+            if (context.signal.aborted) {
+                abortedByUser = true;
+                controller.abort();
+            }
+            else {
+                context.signal.addEventListener('abort', handleAbort, { once: true });
+            }
+        }
+        const timeoutId = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, context.timeout);
+        let timeoutCleared = false;
+        const clearTimeoutOnce = () => {
+            if (!timeoutCleared) {
+                clearTimeout(timeoutId);
+                timeoutCleared = true;
+            }
+        };
+        try {
+            this.logger.debug('Sending request', {
+                url: context.url,
+                method: context.requestInit.method,
+            });
+            const response = await fetch(context.url, {
+                ...context.requestInit,
+                signal: controller.signal,
+            });
+            clearTimeoutOnce();
+            return await parser(response);
+        }
+        catch (error) {
+            clearTimeoutOnce();
+            if (error instanceof MeegoError) {
+                throw error;
+            }
+            if (error instanceof MeegoNetworkError) {
+                throw error;
+            }
+            if (error instanceof MeegoTimeoutError) {
+                throw error;
+            }
+            if (error instanceof Error && error.name === 'AbortError') {
+                if (timedOut) {
+                    throw new MeegoTimeoutError(context.timeout);
+                }
+                if (abortedByUser) {
+                    throw new MeegoAbortError();
+                }
+                throw new MeegoNetworkError('Request aborted', error);
+            }
+            if (error instanceof HttpStatusError) {
+                throw new MeegoNetworkError(error.message, error);
+            }
+            throw new MeegoNetworkError(`${errorPrefix}: ${error instanceof Error ? error.message : 'Unknown error'}`, error instanceof Error ? error : undefined);
+        }
+        finally {
+            clearTimeoutOnce();
+            if (context.signal) {
+                context.signal.removeEventListener('abort', handleAbort);
+            }
+        }
+    }
+    /**
+     * 解析通用响应包裹
+     */
+    async parseEnvelope(response) {
+        const text = await response.text();
+        if (!text) {
+            if (!response.ok) {
+                throw new HttpStatusError(response.status, response.statusText);
+            }
+            return { err_code: 0, err_msg: 'success', err: {}, data: null };
+        }
+        let result;
+        try {
+            result = this.parseJsonSafely(text);
+        }
+        catch (error) {
+            throw new MeegoNetworkError(`Failed to parse response: ${error instanceof Error ? error.message : 'Unknown error'}`, error instanceof Error ? error : undefined);
+        }
+        if (typeof result.err_code !== 'number' || typeof result.err_msg !== 'string') {
+            if (!response.ok) {
+                throw new HttpStatusError(response.status, response.statusText);
+            }
+            throw new MeegoNetworkError('Invalid response');
+        }
+        if (result.err_code !== 0) {
+            throw new MeegoError(`[${result.err_code}] ${result.err_msg}`, result.err_code, result.err_msg, result.err, response.status);
+        }
+        if (!response.ok) {
+            throw new HttpStatusError(response.status, response.statusText);
+        }
+        return result;
+    }
+    validateResponse(data, validator) {
+        if (!validator) {
+            return data;
+        }
+        try {
+            const valid = validator(data);
+            if (!valid) {
+                throw new Error('Response validator returned false');
+            }
+            return data;
+        }
+        catch (error) {
+            throw new MeegoNetworkError(`Response validation failed: ${error instanceof Error ? error.message : 'Unknown error'}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * 验证数组响应的每个元素
+     * 用于分页响应，将单元素验证器应用于数组中的每个元素
+     */
+    validateArrayResponse(data, itemValidator) {
+        if (!Array.isArray(data)) {
+            throw new MeegoNetworkError('Response validation failed: Expected array');
+        }
+        if (!itemValidator) {
+            return data;
+        }
+        try {
+            for (let i = 0; i < data.length; i++) {
+                const valid = itemValidator(data[i]);
+                if (!valid) {
+                    throw new Error(`Response validator returned false for item at index ${i}`);
+                }
+            }
+            return data;
+        }
+        catch (error) {
+            throw new MeegoNetworkError(`Response validation failed: ${error instanceof Error ? error.message : 'Unknown error'}`, error instanceof Error ? error : undefined);
+        }
+    }
+    async parseDataResponse(response, validator) {
+        const result = await this.parseEnvelope(response);
+        return this.validateResponse(result.data, validator);
+    }
+    async parsePaginatedResponse(response, validator) {
+        const result = await this.parseEnvelope(response);
+        // 对于分页响应，使用元素验证器验证数组中的每个元素
+        const data = this.validateArrayResponse(result.data, validator);
+        return {
+            data,
+            pagination: result.pagination,
+        };
+    }
+    async parsePaginatedObjectResponse(response, validator) {
+        const result = await this.parseEnvelope(response);
+        const data = this.validateResponse(result.data, validator);
+        return {
+            data,
+            pagination: result.pagination,
+        };
+    }
+    async parseResponseKeyResponse(response, responseKey, validator) {
+        const result = await this.parseEnvelope(response);
+        if (!(responseKey in result)) {
+            throw new MeegoError(`[-1] Response missing ${responseKey}`, -1, `Response missing ${responseKey}`, result.err, response.status);
+        }
+        return this.validateResponse(result[responseKey], validator);
+    }
+    async parseDownloadResponse(response, options) {
+        const contentType = response.headers.get('content-type') || '';
+        if (contentType.includes('application/json')) {
+            await this.parseEnvelope(response);
+            throw new MeegoError('Unexpected JSON response for download', 0, 'Unexpected response');
+        }
+        if (!response.ok) {
+            throw new HttpStatusError(response.status, response.statusText);
+        }
+        const totalBytes = this.getContentLength(response);
+        const progressOptions = options ?? {};
+        if (!response.body) {
+            const buffer = await response.arrayBuffer();
+            if (progressOptions.onProgress || progressOptions.onChunk) {
+                const receivedBytes = buffer.byteLength;
+                const progress = this.buildDownloadProgress(receivedBytes, totalBytes ?? receivedBytes);
+                this.emitDownloadProgress(progressOptions, progress, new Uint8Array(buffer));
+            }
+            return buffer;
+        }
+        if (!progressOptions.onProgress && !progressOptions.onChunk) {
+            return response.arrayBuffer();
+        }
+        return this.readStreamToArrayBuffer(response.body, progressOptions, totalBytes);
+    }
+    async parseDownloadStreamResponse(response, options) {
+        const contentType = response.headers.get('content-type') || '';
+        if (contentType.includes('application/json')) {
+            await this.parseEnvelope(response);
+            throw new MeegoError('Unexpected JSON response for download', 0, 'Unexpected response');
+        }
+        if (!response.ok) {
+            throw new HttpStatusError(response.status, response.statusText);
+        }
+        const totalBytes = this.getContentLength(response);
+        const progressOptions = options ?? {};
+        if (!response.body) {
+            const buffer = new Uint8Array(await response.arrayBuffer());
+            if (progressOptions.onProgress || progressOptions.onChunk) {
+                const receivedBytes = buffer.byteLength;
+                const progress = this.buildDownloadProgress(receivedBytes, totalBytes ?? receivedBytes);
+                this.emitDownloadProgress(progressOptions, progress, buffer);
+            }
+            return new ReadableStream({
+                start(controller) {
+                    controller.enqueue(buffer);
+                    controller.close();
+                },
+            });
+        }
+        return this.wrapStreamWithProgress(response.body, progressOptions, totalBytes);
+    }
+    getContentLength(response) {
+        const headerValue = response.headers.get('content-length');
+        if (!headerValue) {
+            return undefined;
+        }
+        const parsed = Number.parseInt(headerValue, 10);
+        return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined;
+    }
+    buildDownloadProgress(receivedBytes, totalBytes) {
+        const progress = typeof totalBytes === 'number' && totalBytes > 0 ? receivedBytes / totalBytes : undefined;
+        return { receivedBytes, totalBytes, progress };
+    }
+    emitDownloadProgress(options, progress, chunk) {
+        if (options.onProgress) {
+            try {
+                options.onProgress(progress);
+            }
+            catch (error) {
+                this.logger.warn('Download progress callback error', {
+                    callback: 'onProgress',
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                });
+            }
+        }
+        if (chunk && options.onChunk) {
+            try {
+                options.onChunk(chunk, progress);
+            }
+            catch (error) {
+                this.logger.warn('Download chunk callback error', {
+                    callback: 'onChunk',
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                });
+            }
+        }
+    }
+    async readStreamToArrayBuffer(stream, options, totalBytes) {
+        const reader = stream.getReader();
+        const chunks = [];
+        let receivedBytes = 0;
+        let aborted = false;
+        const handleAbort = () => {
+            aborted = true;
+            reader.cancel().catch(() => undefined);
+        };
+        if (options.signal) {
+            if (options.signal.aborted) {
+                handleAbort();
+                throw new MeegoAbortError();
+            }
+            options.signal.addEventListener('abort', handleAbort, { once: true });
+        }
+        try {
+            while (true) {
+                if (aborted || options.signal?.aborted) {
+                    throw new MeegoAbortError();
+                }
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                if (!value) {
+                    continue;
+                }
+                receivedBytes += value.byteLength;
+                const progress = this.buildDownloadProgress(receivedBytes, totalBytes);
+                this.emitDownloadProgress(options, progress, value);
+                chunks.push(value);
+            }
+        }
+        finally {
+            if (options.signal) {
+                options.signal.removeEventListener('abort', handleAbort);
+            }
+        }
+        const buffer = new Uint8Array(receivedBytes);
+        let offset = 0;
+        for (const chunk of chunks) {
+            buffer.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        return buffer.buffer;
+    }
+    wrapStreamWithProgress(stream, options, totalBytes) {
+        const reader = stream.getReader();
+        let receivedBytes = 0;
+        let abortHandler;
+        const cleanupAbortListener = () => {
+            if (options.signal && abortHandler) {
+                options.signal.removeEventListener('abort', abortHandler);
+                abortHandler = undefined;
+            }
+        };
+        return new ReadableStream({
+            start: (controller) => {
+                if (!options.signal) {
+                    return;
+                }
+                abortHandler = () => {
+                    cleanupAbortListener();
+                    reader.cancel().catch(() => undefined);
+                    controller.error(new MeegoAbortError());
+                };
+                if (options.signal.aborted) {
+                    abortHandler();
+                }
+                else {
+                    options.signal.addEventListener('abort', abortHandler, { once: true });
+                }
+            },
+            pull: async (controller) => {
+                const { done, value } = await reader.read();
+                if (done) {
+                    cleanupAbortListener();
+                    controller.close();
+                    return;
+                }
+                if (!value) {
+                    return;
+                }
+                receivedBytes += value.byteLength;
+                const progress = this.buildDownloadProgress(receivedBytes, totalBytes);
+                this.emitDownloadProgress(options, progress, value);
+                controller.enqueue(value);
+            },
+            cancel: async (reason) => {
+                cleanupAbortListener();
+                await reader.cancel(reason);
+            },
+        });
+    }
+    buildUrlWithResolvedPath(resolvedPath, query) {
+        let url = `${this.baseURL}${resolvedPath}`;
+        if (query && Object.keys(query).length > 0) {
+            const queryString = this.buildQueryString(query);
+            url += `?${queryString}`;
+        }
+        return url;
+    }
+}
+//# sourceMappingURL=request.js.map