@cloudbase/manager-node 5.3.0 → 5.4.0-beta.2

package/lib/storage/index.js

@@ -16,6 +16,7 @@ const path_1 = __importDefault(require("path"));
 const make_dir_1 = __importDefault(require("make-dir"));
 const walkdir_1 = __importDefault(require("walkdir"));
 const micromatch_1 = __importDefault(require("micromatch"));
+const mime_types_1 = __importDefault(require("mime-types"));
 const cos_nodejs_sdk_v5_1 = __importDefault(require("cos-nodejs-sdk-v5"));
 const utils_1 = require("../utils");
 const error_1 = require("../error");
@@ -1258,6 +1259,1251 @@ class StorageService {
         // 限制总数量
         return results.slice(0, limit);
     }
+    /**
+     * 通过 CloudBase HTTP API 上传对象（Binary 直传）
+     * POST/PUT /v1/storages/object/:bucketId/*objectName
+     */
+    /* eslint-disable complexity */
+    async uploadObject(options) {
+        const { bucketId, objectName, localPath, body, contentType, contentLength, cacheControl, metadata, xRobotsTag, upsert = false, usePut = false, accessToken, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!objectName || typeof objectName !== 'string') {
+            throw new error_1.CloudBaseError('objectName 必须是非空字符串');
+        }
+        if (!accessToken || typeof accessToken !== 'string') {
+            throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
+        }
+        if (!localPath && !body) {
+            throw new error_1.CloudBaseError('localPath 与 body 至少提供一个');
+        }
+        if (localPath && body) {
+            throw new error_1.CloudBaseError('localPath 与 body 只能二选一');
+        }
+        // env / proxy
+        const authConfig = this.environment.getAuthConfig();
+        const { proxy } = authConfig;
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        // 路径编码：保留 "/" 层级，仅编码每段
+        const encodedBucketId = encodeURIComponent(bucketId);
+        const encodedObjectName = objectName
+            .split('/')
+            .map(seg => encodeURIComponent(seg))
+            .join('/');
+        const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/${encodedBucketId}/${encodedObjectName}`;
+        const method = usePut ? 'PUT' : 'POST';
+        // 推断文件大小
+        let fileSize = contentLength;
+        if (localPath) {
+            const resolvedPath = path_1.default.resolve(localPath);
+            (0, utils_1.checkFullAccess)(resolvedPath, true);
+            const stat = fs_1.default.statSync(resolvedPath);
+            if (!stat.isFile()) {
+                throw new error_1.CloudBaseError(`localPath 不是文件: ${localPath}`);
+            }
+            fileSize = stat.size;
+        }
+        else if (Buffer.isBuffer(body) && fileSize === undefined) {
+            fileSize = body.length;
+        }
+        // 文档约束：> 100MB 拒绝
+        const LIMIT_100MB = 100 * 1024 * 1024;
+        if (fileSize !== undefined && fileSize > LIMIT_100MB) {
+            throw new error_1.CloudBaseError('FileSizeLimitExceeded: 文件大小超过 100MB', {
+                code: 'FileSizeLimitExceeded'
+            });
+        }
+        const finalContentType = this.resolveUploadContentType({
+            contentType,
+            localPath,
+            objectName,
+            body
+        });
+        const headers = {
+            Authorization: `Bearer ${accessToken}`
+        };
+        if (finalContentType) {
+            headers['Content-Type'] = finalContentType;
+        }
+        if (fileSize !== undefined) {
+            headers['Content-Length'] = String(fileSize);
+        }
+        if (cacheControl !== undefined && cacheControl !== null) {
+            headers['Cache-Control'] =
+                typeof cacheControl === 'number' ? `max-age=${cacheControl}` : String(cacheControl);
+        }
+        if (metadata) {
+            // X-Metadata 放在 Header 里，具体大小限制由服务端/网关决定
+            headers['X-Metadata'] = Buffer.from(JSON.stringify(metadata), 'utf8').toString('base64');
+        }
+        if (upsert) {
+            headers['x-upsert'] = 'true';
+        }
+        if (xRobotsTag) {
+            headers['X-Robots-Tag'] = xRobotsTag;
+        }
+        // 组装 Body：文件二进制本身
+        const reqBody = localPath ? fs_1.default.createReadStream(path_1.default.resolve(localPath)) : body;
+        const res = await (0, utils_1.fetchStream)(url, {
+            method,
+            headers,
+            body: reqBody
+        }, proxy);
+        const text = await res.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (_a) {
+                if (!res.ok) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+                throw new error_1.CloudBaseError(`响应不是合法 JSON: ${text}`);
+            }
+        }
+        if (!res.ok) {
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '上传失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        if (!payload || !payload.Id || !payload.Key) {
+            throw new error_1.CloudBaseError('上传成功但响应格式异常：缺少 Id 或 Key');
+        }
+        return {
+            Id: payload.Id,
+            Key: payload.Key
+        };
+    }
+    /**
+     * 通过 CloudBase HTTP API 删除单个对象
+     * DELETE /v1/storages/object/:bucketId/*objectName
+     */
+    async deleteObject(options) {
+        const { bucketId, objectName, accessToken, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!objectName || typeof objectName !== 'string') {
+            throw new error_1.CloudBaseError('objectName 必须是非空字符串');
+        }
+        if (!accessToken || typeof accessToken !== 'string') {
+            throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const encodedBucketId = encodeURIComponent(bucketId);
+        const encodedObjectName = objectName
+            .split('/')
+            .map(seg => encodeURIComponent(seg))
+            .join('/');
+        const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/${encodedBucketId}/${encodedObjectName}`;
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: 'DELETE',
+            headers: {
+                Authorization: `Bearer ${accessToken}`
+            }
+        }, proxy);
+        const text = await res.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (_a) {
+                if (!res.ok) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+                throw new error_1.CloudBaseError(`响应不是合法 JSON: ${text}`);
+            }
+        }
+        if (!res.ok) {
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '删除失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        // 网关成功时返回 { message: 'Successfully deleted' }
+        return {
+            message: (payload === null || payload === void 0 ? void 0 : payload.message) || 'Successfully deleted'
+        };
+    }
+    /**
+     * 通过 CloudBase HTTP API 批量删除对象（单次最多 20 个）
+     * DELETE /v1/storages/object/:bucketId
+     */
+    async deleteObjects(options) {
+        const { bucketId, prefixes, accessToken, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!accessToken || typeof accessToken !== 'string') {
+            throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
+        }
+        if (!Array.isArray(prefixes) || prefixes.length === 0) {
+            throw new error_1.CloudBaseError('prefixes 必须是非空数组');
+        }
+        if (prefixes.length > 20) {
+            throw new error_1.CloudBaseError('prefixes 最多 20 个');
+        }
+        for (const name of prefixes) {
+            if (!name || typeof name !== 'string') {
+                throw new error_1.CloudBaseError('prefixes 中的每一项必须是非空字符串');
+            }
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const encodedBucketId = encodeURIComponent(bucketId);
+        const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/${encodedBucketId}`;
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: 'DELETE',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({ prefixes })
+        }, proxy);
+        const text = await res.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (_a) {
+                if (!res.ok) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+                throw new error_1.CloudBaseError(`响应不是合法 JSON: ${text}`);
+            }
+        }
+        if (!res.ok) {
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '批量删除失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        if (!Array.isArray(payload)) {
+            throw new error_1.CloudBaseError('批量删除响应格式异常：期望数组');
+        }
+        return payload;
+    }
+    /**
+     * 通过 CloudBase HTTP API 复制对象
+     * POST /v1/storages/object/copy
+     */
+    /* eslint-disable complexity */
+    async copyObject(options) {
+        const { bucketId, sourceKey, destinationKey, destinationBucket, metadata, userMetadata, copyMetadata, upsert, accessToken, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!sourceKey || typeof sourceKey !== 'string') {
+            throw new error_1.CloudBaseError('sourceKey 必须是非空字符串');
+        }
+        if (!destinationKey || typeof destinationKey !== 'string') {
+            throw new error_1.CloudBaseError('destinationKey 必须是非空字符串');
+        }
+        if (destinationBucket !== undefined &&
+            (typeof destinationBucket !== 'string' || !destinationBucket)) {
+            throw new error_1.CloudBaseError('destinationBucket 必须是非空字符串');
+        }
+        if (metadata !== undefined && (typeof metadata !== 'object' || metadata === null || Array.isArray(metadata))) {
+            throw new error_1.CloudBaseError('metadata 必须是对象');
+        }
+        if (userMetadata !== undefined && (typeof userMetadata !== 'object' || userMetadata === null || Array.isArray(userMetadata))) {
+            throw new error_1.CloudBaseError('userMetadata 必须是对象');
+        }
+        if (copyMetadata !== undefined && typeof copyMetadata !== 'boolean') {
+            throw new error_1.CloudBaseError('copyMetadata 必须是布尔值');
+        }
+        if (!accessToken || typeof accessToken !== 'string') {
+            throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/copy`;
+        const headers = {
+            Authorization: `Bearer ${accessToken}`,
+            'Content-Type': 'application/json'
+        };
+        if (upsert) {
+            headers['x-upsert'] = 'true';
+        }
+        // copyMetadata=false 时，userMetadata 通过 x-metadata 头整体替换目标对象的 user_metadata
+        if (copyMetadata === false && userMetadata) {
+            headers['x-metadata'] = Buffer.from(JSON.stringify(userMetadata)).toString('base64');
+        }
+        const body = {
+            bucketId,
+            sourceKey,
+            destinationKey
+        };
+        if (destinationBucket !== undefined)
+            body.destinationBucket = destinationBucket;
+        if (metadata !== undefined)
+            body.metadata = metadata;
+        if (copyMetadata !== undefined)
+            body.copyMetadata = copyMetadata;
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(body)
+        }, proxy);
+        const text = await res.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (_a) {
+                if (!res.ok) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+                throw new error_1.CloudBaseError(`响应不是合法 JSON: ${text}`);
+            }
+        }
+        if (!res.ok) {
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '复制失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        if (!payload || !payload.Id || !payload.Key) {
+            throw new error_1.CloudBaseError('复制成功但响应格式异常：缺少 Id 或 Key');
+        }
+        return payload;
+    }
+    /**
+     * 通过 CloudBase HTTP API 移动对象（复制后删除源对象，由服务端一次性完成）
+     * POST /v1/storages/object/move
+     */
+    async moveObject(options) {
+        const { bucketId, sourceKey, destinationKey, destinationBucket, accessToken, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!sourceKey || typeof sourceKey !== 'string') {
+            throw new error_1.CloudBaseError('sourceKey 必须是非空字符串');
+        }
+        if (!destinationKey || typeof destinationKey !== 'string') {
+            throw new error_1.CloudBaseError('destinationKey 必须是非空字符串');
+        }
+        if (destinationBucket !== undefined &&
+            (typeof destinationBucket !== 'string' || !destinationBucket)) {
+            throw new error_1.CloudBaseError('destinationBucket 必须是非空字符串');
+        }
+        if (!accessToken || typeof accessToken !== 'string') {
+            throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/move`;
+        const body = {
+            bucketId,
+            sourceKey,
+            destinationKey
+        };
+        if (destinationBucket !== undefined)
+            body.destinationBucket = destinationBucket;
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify(body)
+        }, proxy);
+        const text = await res.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (_a) {
+                if (!res.ok) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+                throw new error_1.CloudBaseError(`响应不是合法 JSON: ${text}`);
+            }
+        }
+        if (!res.ok) {
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '移动失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        if (!payload || !payload.Id || !payload.Key) {
+            throw new error_1.CloudBaseError('移动成功但响应格式异常：缺少 Id 或 Key');
+        }
+        return {
+            message: payload.message || 'Successfully moved',
+            Id: payload.Id,
+            Key: payload.Key
+        };
+    }
+    /**
+     * 通过 CloudBase HTTP API 列出对象
+     * POST /v1/storages/object/list/:bucketId
+     */
+    /* eslint-disable complexity */
+    async listObjects(options) {
+        const { bucketId, prefix, limit, cursor, withDelimiter, sortBy, accessToken, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (prefix !== undefined && typeof prefix !== 'string') {
+            throw new error_1.CloudBaseError('prefix 必须是字符串');
+        }
+        if (limit !== undefined) {
+            if (!Number.isInteger(limit)) {
+                throw new error_1.CloudBaseError('limit 必须是整数');
+            }
+            if (limit < 1 || limit > 1000) {
+                throw new error_1.CloudBaseError('limit 必须在 1 ~ 1000 之间');
+            }
+        }
+        if (cursor !== undefined && typeof cursor !== 'string') {
+            throw new error_1.CloudBaseError('cursor 必须是字符串');
+        }
+        if (withDelimiter !== undefined && typeof withDelimiter !== 'boolean') {
+            throw new error_1.CloudBaseError('withDelimiter 必须是布尔值');
+        }
+        if (!accessToken || typeof accessToken !== 'string') {
+            throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
+        }
+        if (sortBy !== undefined) {
+            if (typeof sortBy !== 'object' || sortBy === null || Array.isArray(sortBy)) {
+                throw new error_1.CloudBaseError('sortBy 必须是对象');
+            }
+            const allowedColumns = ['name', 'created_at', 'updated_at'];
+            const allowedOrders = ['asc', 'desc'];
+            if (sortBy.column !== undefined && !allowedColumns.includes(sortBy.column)) {
+                throw new error_1.CloudBaseError(`sortBy.column 非法，允许值：${allowedColumns.join('、')}`);
+            }
+            if (sortBy.order !== undefined) {
+                const normalizedOrder = String(sortBy.order).toLowerCase();
+                if (!allowedOrders.includes(normalizedOrder)) {
+                    throw new error_1.CloudBaseError(`sortBy.order 非法，允许值：${allowedOrders.join('、')}`);
+                }
+                sortBy.order = normalizedOrder;
+            }
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const encodedBucketId = encodeURIComponent(bucketId);
+        const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/list/${encodedBucketId}`;
+        const body = {};
+        if (prefix !== undefined)
+            body.prefix = prefix;
+        if (limit !== undefined)
+            body.limit = limit;
+        if (cursor !== undefined)
+            body.cursor = cursor;
+        if (withDelimiter !== undefined)
+            body.with_delimiter = withDelimiter;
+        if (sortBy !== undefined)
+            body.sortBy = sortBy;
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify(body)
+        }, proxy);
+        const text = await res.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (_a) {
+                if (!res.ok) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+                throw new error_1.CloudBaseError(`响应不是合法 JSON: ${text}`);
+            }
+        }
+        if (!res.ok) {
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '列出对象失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        if (!payload || !Array.isArray(payload.objects) || !Array.isArray(payload.folders)) {
+            throw new error_1.CloudBaseError('列出对象成功但响应格式异常：缺少 folders 或 objects 数组');
+        }
+        const result = Object.assign({ folders: payload.folders, objects: payload.objects, hasNext: Boolean(payload.hasNext), nextCursor: payload.nextCursor, nextCursorKey: payload.nextCursorKey }, payload);
+        return result;
+    }
+    /**
+     * 通过 CloudBase HTTP API 生成签名下载 URL
+     * POST /v1/storages/object/sign/:bucketId/*objectName
+     */
+    async signObject(options) {
+        const { bucketId, objectName, expiresIn, accessToken, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!objectName || typeof objectName !== 'string') {
+            throw new error_1.CloudBaseError('objectName 必须是非空字符串');
+        }
+        if (!Number.isInteger(expiresIn)) {
+            throw new error_1.CloudBaseError('expiresIn 必须是整数');
+        }
+        if (expiresIn < 1) {
+            throw new error_1.CloudBaseError('expiresIn 必须 >= 1');
+        }
+        if (!accessToken || typeof accessToken !== 'string') {
+            throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const encodedBucketId = encodeURIComponent(bucketId);
+        const encodedObjectName = objectName
+            .split('/')
+            .map(seg => encodeURIComponent(seg))
+            .join('/');
+        const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/sign/${encodedBucketId}/${encodedObjectName}`;
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({ expiresIn })
+        }, proxy);
+        const text = await res.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (_a) {
+                if (!res.ok) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+                throw new error_1.CloudBaseError(`响应不是合法 JSON: ${text}`);
+            }
+        }
+        if (!res.ok) {
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '生成签名 URL 失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        if (!payload || typeof payload.signedURL !== 'string' || !payload.signedURL) {
+            throw new error_1.CloudBaseError('生成签名 URL 成功但响应格式异常：缺少 signedURL');
+        }
+        return {
+            signedURL: payload.signedURL
+        };
+    }
+    /**
+     * 通过 CloudBase HTTP API 批量生成签名下载 URL
+     * POST /v1/storages/object/sign/:bucketId
+     */
+    async signObjects(options) {
+        const { bucketId, expiresIn, paths, accessToken, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!Number.isInteger(expiresIn)) {
+            throw new error_1.CloudBaseError('expiresIn 必须是整数');
+        }
+        if (expiresIn < 1) {
+            throw new error_1.CloudBaseError('expiresIn 必须 >= 1');
+        }
+        if (!Array.isArray(paths) || paths.length === 0) {
+            throw new error_1.CloudBaseError('paths 必须是非空数组');
+        }
+        if (paths.length > 500) {
+            throw new error_1.CloudBaseError('paths 最多 500 个');
+        }
+        for (const pathItem of paths) {
+            if (!pathItem || typeof pathItem !== 'string') {
+                throw new error_1.CloudBaseError('paths 中每一项必须是非空字符串');
+            }
+        }
+        if (!accessToken || typeof accessToken !== 'string') {
+            throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const encodedBucketId = encodeURIComponent(bucketId);
+        const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/sign/${encodedBucketId}`;
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({
+                expiresIn,
+                paths
+            })
+        }, proxy);
+        const text = await res.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (_a) {
+                if (!res.ok) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+                throw new error_1.CloudBaseError(`响应不是合法 JSON: ${text}`);
+            }
+        }
+        if (!res.ok) {
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '批量生成签名 URL 失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        if (!Array.isArray(payload)) {
+            throw new error_1.CloudBaseError('批量生成签名 URL 成功但响应格式异常：期望数组');
+        }
+        return payload;
+    }
+    /**
+     * 通过 CloudBase HTTP API 生成签名上传 URL
+     * POST /v1/storages/object/upload/sign/:bucketId/*objectName
+     */
+    async signUploadObject(options) {
+        const { bucketId, objectName, upsert = false, accessToken, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!objectName || typeof objectName !== 'string') {
+            throw new error_1.CloudBaseError('objectName 必须是非空字符串');
+        }
+        if (typeof upsert !== 'boolean') {
+            throw new error_1.CloudBaseError('upsert 必须是布尔值');
+        }
+        if (!accessToken || typeof accessToken !== 'string') {
+            throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const encodedBucketId = encodeURIComponent(bucketId);
+        const encodedObjectName = objectName
+            .split('/')
+            .map(seg => encodeURIComponent(seg))
+            .join('/');
+        const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/upload/sign/${encodedBucketId}/${encodedObjectName}`;
+        const headers = {
+            Authorization: `Bearer ${accessToken}`
+        };
+        if (upsert) {
+            headers['x-upsert'] = 'true';
+        }
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: 'POST',
+            headers
+        }, proxy);
+        const text = await res.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (_a) {
+                if (!res.ok) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+                throw new error_1.CloudBaseError(`响应不是合法 JSON: ${text}`);
+            }
+        }
+        if (!res.ok) {
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '生成签名上传 URL 失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        if (!payload || typeof payload.url !== 'string' || typeof payload.token !== 'string') {
+            throw new error_1.CloudBaseError('生成签名上传 URL 成功但响应格式异常：缺少 url 或 token');
+        }
+        return {
+            url: payload.url,
+            token: payload.token
+        };
+    }
+    /**
+     * 通过 CloudBase HTTP API 使用签名 URL 上传对象（无需 Authorization）
+     * PUT /v1/storages/object/upload/sign/:bucketId/*objectName?token=xxx
+     */
+    async uploadObjectBySign(options) {
+        const { bucketId, objectName, token, localPath, body, contentType, contentLength, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!objectName || typeof objectName !== 'string') {
+            throw new error_1.CloudBaseError('objectName 必须是非空字符串');
+        }
+        if (!token || typeof token !== 'string') {
+            throw new error_1.CloudBaseError('token 必须是非空字符串');
+        }
+        if (!localPath && !body) {
+            throw new error_1.CloudBaseError('localPath 与 body 至少提供一个');
+        }
+        if (localPath && body) {
+            throw new error_1.CloudBaseError('localPath 与 body 只能二选一');
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const encodedBucketId = encodeURIComponent(bucketId);
+        const encodedObjectName = objectName
+            .split('/')
+            .map(seg => encodeURIComponent(seg))
+            .join('/');
+        const encodedToken = encodeURIComponent(token);
+        const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/upload/sign/${encodedBucketId}/${encodedObjectName}?token=${encodedToken}`;
+        let fileSize = contentLength;
+        if (localPath) {
+            const resolvedPath = path_1.default.resolve(localPath);
+            (0, utils_1.checkFullAccess)(resolvedPath, true);
+            const stat = fs_1.default.statSync(resolvedPath);
+            if (!stat.isFile()) {
+                throw new error_1.CloudBaseError(`localPath 不是文件: ${localPath}`);
+            }
+            fileSize = stat.size;
+        }
+        else if (Buffer.isBuffer(body) && fileSize === undefined) {
+            fileSize = body.length;
+        }
+        const finalContentType = this.resolveUploadContentType({
+            contentType,
+            localPath,
+            objectName,
+            body
+        });
+        const headers = {};
+        if (finalContentType) {
+            headers['Content-Type'] = finalContentType;
+        }
+        if (fileSize !== undefined) {
+            headers['Content-Length'] = String(fileSize);
+        }
+        const reqBody = localPath ? fs_1.default.createReadStream(path_1.default.resolve(localPath)) : body;
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: 'PUT',
+            headers,
+            body: reqBody
+        }, proxy);
+        const text = await res.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (_a) {
+                if (!res.ok) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+                throw new error_1.CloudBaseError(`响应不是合法 JSON: ${text}`);
+            }
+        }
+        if (!res.ok) {
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '签名上传失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        if (!payload || typeof payload.Key !== 'string' || !payload.Key) {
+            throw new error_1.CloudBaseError('签名上传成功但响应格式异常：缺少 Key');
+        }
+        return {
+            Key: payload.Key
+        };
+    }
+    /**
+     * 通过 CloudBase HTTP API 下载对象（需认证）
+     * GET/HEAD /v1/storages/object/authenticated/:bucketId/*objectName
+     */
+    async downloadAuthenticatedObject(options) {
+        const { bucketId, objectName, method = 'GET', download, ifNoneMatch, ifModifiedSince, range, accessToken, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!objectName || typeof objectName !== 'string') {
+            throw new error_1.CloudBaseError('objectName 必须是非空字符串');
+        }
+        if (!accessToken || typeof accessToken !== 'string') {
+            throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
+        }
+        const normalizedMethod = String(method).toUpperCase();
+        const allowedMethods = ['GET', 'HEAD'];
+        if (!allowedMethods.includes(normalizedMethod)) {
+            throw new error_1.CloudBaseError('method 仅支持 GET 或 HEAD');
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const encodedBucketId = encodeURIComponent(bucketId);
+        const encodedObjectName = objectName
+            .split('/')
+            .map(seg => encodeURIComponent(seg))
+            .join('/');
+        let url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/authenticated/${encodedBucketId}/${encodedObjectName}`;
+        if (download !== undefined) {
+            if (typeof download !== 'string') {
+                throw new error_1.CloudBaseError('download 必须是字符串');
+            }
+            url += `?download=${encodeURIComponent(download)}`;
+        }
+        const headers = {
+            Authorization: `Bearer ${accessToken}`
+        };
+        if (ifNoneMatch !== undefined) {
+            if (typeof ifNoneMatch !== 'string') {
+                throw new error_1.CloudBaseError('ifNoneMatch 必须是字符串');
+            }
+            headers['If-None-Match'] = ifNoneMatch;
+        }
+        if (ifModifiedSince !== undefined) {
+            if (typeof ifModifiedSince !== 'string') {
+                throw new error_1.CloudBaseError('ifModifiedSince 必须是字符串');
+            }
+            headers['If-Modified-Since'] = ifModifiedSince;
+        }
+        if (range !== undefined) {
+            if (typeof range !== 'string') {
+                throw new error_1.CloudBaseError('range 必须是字符串');
+            }
+            headers.Range = range;
+        }
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: normalizedMethod,
+            headers
+        }, proxy);
+        if (!res.ok) {
+            const text = await res.text();
+            let payload = null;
+            if (text) {
+                try {
+                    payload = JSON.parse(text);
+                }
+                catch (_a) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+            }
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '下载对象失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        const responseHeaders = {};
+        res.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        return {
+            status: res.status,
+            headers: responseHeaders,
+            body: normalizedMethod === 'HEAD' ? null : res.body
+        };
+    }
+    /**
+     * 通过 CloudBase HTTP API 下载对象（可选认证）
+     * GET/HEAD /v1/storages/object/:bucketId/*objectName
+     */
+    async downloadObject(options) {
+        const { bucketId, objectName, method = 'GET', download, ifNoneMatch, ifModifiedSince, range, accessToken, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!objectName || typeof objectName !== 'string') {
+            throw new error_1.CloudBaseError('objectName 必须是非空字符串');
+        }
+        if (accessToken !== undefined && typeof accessToken !== 'string') {
+            throw new error_1.CloudBaseError('accessToken 必须是字符串');
+        }
+        const normalizedMethod = String(method).toUpperCase();
+        const allowedMethods = ['GET', 'HEAD'];
+        if (!allowedMethods.includes(normalizedMethod)) {
+            throw new error_1.CloudBaseError('method 仅支持 GET 或 HEAD');
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const encodedBucketId = encodeURIComponent(bucketId);
+        const encodedObjectName = objectName
+            .split('/')
+            .map(seg => encodeURIComponent(seg))
+            .join('/');
+        let url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/${encodedBucketId}/${encodedObjectName}`;
+        if (download !== undefined) {
+            if (typeof download !== 'string') {
+                throw new error_1.CloudBaseError('download 必须是字符串');
+            }
+            url += `?download=${encodeURIComponent(download)}`;
+        }
+        const headers = {};
+        if (accessToken) {
+            headers.Authorization = `Bearer ${accessToken}`;
+        }
+        if (ifNoneMatch !== undefined) {
+            if (typeof ifNoneMatch !== 'string') {
+                throw new error_1.CloudBaseError('ifNoneMatch 必须是字符串');
+            }
+            headers['If-None-Match'] = ifNoneMatch;
+        }
+        if (ifModifiedSince !== undefined) {
+            if (typeof ifModifiedSince !== 'string') {
+                throw new error_1.CloudBaseError('ifModifiedSince 必须是字符串');
+            }
+            headers['If-Modified-Since'] = ifModifiedSince;
+        }
+        if (range !== undefined) {
+            if (typeof range !== 'string') {
+                throw new error_1.CloudBaseError('range 必须是字符串');
+            }
+            headers.Range = range;
+        }
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: normalizedMethod,
+            headers
+        }, proxy);
+        if (!res.ok) {
+            const text = await res.text();
+            let payload = null;
+            if (text) {
+                try {
+                    payload = JSON.parse(text);
+                }
+                catch (_a) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+            }
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '下载对象失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        const responseHeaders = {};
+        res.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        return {
+            status: res.status,
+            headers: responseHeaders,
+            body: normalizedMethod === 'HEAD' ? null : res.body
+        };
+    }
+    /**
+     * 通过 CloudBase HTTP API 下载公开对象（无需认证）
+     * GET/HEAD /v1/storages/object/public/:bucketId/*objectName
+     */
+    async downloadPublicObject(options) {
+        const { bucketId, objectName, method = 'GET', download, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!objectName || typeof objectName !== 'string') {
+            throw new error_1.CloudBaseError('objectName 必须是非空字符串');
+        }
+        const normalizedMethod = String(method).toUpperCase();
+        const allowedMethods = ['GET', 'HEAD'];
+        if (!allowedMethods.includes(normalizedMethod)) {
+            throw new error_1.CloudBaseError('method 仅支持 GET 或 HEAD');
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const encodedBucketId = encodeURIComponent(bucketId);
+        const encodedObjectName = objectName
+            .split('/')
+            .map(seg => encodeURIComponent(seg))
+            .join('/');
+        let url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/public/${encodedBucketId}/${encodedObjectName}`;
+        if (download !== undefined) {
+            if (typeof download !== 'string') {
+                throw new error_1.CloudBaseError('download 必须是字符串');
+            }
+            url += `?download=${encodeURIComponent(download)}`;
+        }
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: normalizedMethod
+        }, proxy);
+        if (!res.ok) {
+            const text = await res.text();
+            let payload = null;
+            if (text) {
+                try {
+                    payload = JSON.parse(text);
+                }
+                catch (_a) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+            }
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '下载公开对象失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        const responseHeaders = {};
+        res.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        return {
+            status: res.status,
+            headers: responseHeaders,
+            body: normalizedMethod === 'HEAD' ? null : res.body
+        };
+    }
+    /**
+     * 通过 CloudBase HTTP API 使用签名 URL 下载对象（无需 Authorization）
+     * GET/HEAD /v1/storages/object/sign/:bucketId/*objectName?token=xxx
+     */
+    async downloadObjectBySign(options) {
+        const { bucketId, objectName, token, method = 'GET', download, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!objectName || typeof objectName !== 'string') {
+            throw new error_1.CloudBaseError('objectName 必须是非空字符串');
+        }
+        if (!token || typeof token !== 'string') {
+            throw new error_1.CloudBaseError('token 必须是非空字符串');
+        }
+        const normalizedMethod = String(method).toUpperCase();
+        const allowedMethods = ['GET', 'HEAD'];
+        if (!allowedMethods.includes(normalizedMethod)) {
+            throw new error_1.CloudBaseError('method 仅支持 GET 或 HEAD');
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const encodedBucketId = encodeURIComponent(bucketId);
+        const encodedObjectName = objectName
+            .split('/')
+            .map(seg => encodeURIComponent(seg))
+            .join('/');
+        let url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/sign/${encodedBucketId}/${encodedObjectName}?token=${encodeURIComponent(token)}`;
+        if (download !== undefined) {
+            if (typeof download !== 'string') {
+                throw new error_1.CloudBaseError('download 必须是字符串');
+            }
+            url += `&download=${encodeURIComponent(download)}`;
+        }
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: normalizedMethod
+        }, proxy);
+        if (!res.ok) {
+            const text = await res.text();
+            let payload = null;
+            if (text) {
+                try {
+                    payload = JSON.parse(text);
+                }
+                catch (_a) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+            }
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '通过签名 URL 下载对象失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        const responseHeaders = {};
+        res.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        return {
+            status: res.status,
+            headers: responseHeaders,
+            body: normalizedMethod === 'HEAD' ? null : res.body
+        };
+    }
+    /**
+     * 通过 CloudBase HTTP API 获取对象元信息（需认证）
+     * GET/HEAD /v1/storages/object/info/authenticated/:bucketId/*objectName
+     */
+    async getObjectInfoAuthenticated(options) {
+        const { bucketId, objectName, method = 'GET', accessToken, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!objectName || typeof objectName !== 'string') {
+            throw new error_1.CloudBaseError('objectName 必须是非空字符串');
+        }
+        if (!accessToken || typeof accessToken !== 'string') {
+            throw new error_1.CloudBaseError('accessToken 必须是非空字符串');
+        }
+        const normalizedMethod = String(method).toUpperCase();
+        const allowedMethods = ['GET', 'HEAD'];
+        if (!allowedMethods.includes(normalizedMethod)) {
+            throw new error_1.CloudBaseError('method 仅支持 GET 或 HEAD');
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const encodedBucketId = encodeURIComponent(bucketId);
+        const encodedObjectName = objectName
+            .split('/')
+            .map(seg => encodeURIComponent(seg))
+            .join('/');
+        const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/info/authenticated/${encodedBucketId}/${encodedObjectName}`;
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: normalizedMethod,
+            headers: {
+                Authorization: `Bearer ${accessToken}`
+            }
+        }, proxy);
+        if (!res.ok) {
+            const text = await res.text();
+            let payload = null;
+            if (text) {
+                try {
+                    payload = JSON.parse(text);
+                }
+                catch (_a) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+            }
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '获取对象元信息失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        const responseHeaders = {};
+        res.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        if (normalizedMethod === 'HEAD') {
+            return {
+                status: res.status,
+                headers: responseHeaders,
+                body: null
+            };
+        }
+        const text = await res.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (_b) {
+                throw new error_1.CloudBaseError(`响应不是合法 JSON: ${text}`);
+            }
+        }
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+            throw new error_1.CloudBaseError('获取对象元信息成功但响应格式异常：期望 JSON 对象');
+        }
+        return {
+            status: res.status,
+            headers: responseHeaders,
+            body: payload
+        };
+    }
+    /**
+     * 通过 CloudBase HTTP API 获取公开对象元信息（无需认证）
+     * GET /v1/storages/object/info/public/:bucketId/*objectName
+     */
+    async getObjectInfoPublic(options) {
+        const { bucketId, objectName, envId: envIdOverride } = options;
+        if (!bucketId || typeof bucketId !== 'string') {
+            throw new error_1.CloudBaseError('bucketId 必须是非空字符串');
+        }
+        if (!objectName || typeof objectName !== 'string') {
+            throw new error_1.CloudBaseError('objectName 必须是非空字符串');
+        }
+        const { env } = this.getStorageConfig();
+        const envId = envIdOverride || env;
+        const encodedBucketId = encodeURIComponent(bucketId);
+        const encodedObjectName = objectName
+            .split('/')
+            .map(seg => encodeURIComponent(seg))
+            .join('/');
+        const url = `https://${envId}.api.tcloudbasegateway.com/v1/storages/object/info/public/${encodedBucketId}/${encodedObjectName}`;
+        const { proxy } = this.environment.getAuthConfig();
+        const res = await (0, utils_1.fetchStream)(url, {
+            method: 'GET'
+        }, proxy);
+        if (!res.ok) {
+            const text = await res.text();
+            let payload = null;
+            if (text) {
+                try {
+                    payload = JSON.parse(text);
+                }
+                catch (_a) {
+                    throw new error_1.CloudBaseError(`HTTP_${res.status}: ${text}`);
+                }
+            }
+            const code = (payload === null || payload === void 0 ? void 0 : payload.Code) || (payload === null || payload === void 0 ? void 0 : payload.code) || `HTTP_${res.status}`;
+            const message = (payload === null || payload === void 0 ? void 0 : payload.Message) || (payload === null || payload === void 0 ? void 0 : payload.message) || res.statusText || '获取公开对象元信息失败';
+            throw new error_1.CloudBaseError(`${code}: ${message}`, {
+                code,
+                requestId: (payload === null || payload === void 0 ? void 0 : payload.RequestId) || (payload === null || payload === void 0 ? void 0 : payload.requestId)
+            });
+        }
+        const responseHeaders = {};
+        res.headers.forEach((value, key) => {
+            responseHeaders[key] = value;
+        });
+        const text = await res.text();
+        let payload = null;
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch (_b) {
+                throw new error_1.CloudBaseError(`响应不是合法 JSON: ${text}`);
+            }
+        }
+        if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+            throw new error_1.CloudBaseError('获取公开对象元信息成功但响应格式异常：期望 JSON 对象');
+        }
+        return {
+            status: res.status,
+            headers: responseHeaders,
+            body: payload
+        };
+    }
     /**
      * 获取 COS 配置
      */
@@ -1405,6 +2651,87 @@ class StorageService {
         res.map(item => /Error/gi.test(Object.prototype.toString.call(item)) && resultErrorArr.push(item));
         return resultErrorArr;
     }
+    resolveUploadContentType(params) {
+        const { contentType, localPath, objectName, body } = params;
+        // 0. 用户显式指定优先
+        const trimmedContentType = contentType === null || contentType === void 0 ? void 0 : contentType.trim();
+        if (trimmedContentType) {
+            return this.assertValidContentType(trimmedContentType);
+        }
+        // 1. 扩展名推断（优先）
+        const byExt = this.inferMimeByExtension(localPath || objectName);
+        if (byExt)
+            return byExt;
+        // 2. magic bytes 二次识别
+        const byMagic = this.inferMimeByMagicBytes(localPath, body);
+        if (byMagic)
+            return byMagic;
+        return undefined;
+    }
+    inferMimeByExtension(filePathOrName) {
+        if (!filePathOrName)
+            return undefined;
+        const result = mime_types_1.default.lookup(filePathOrName);
+        return typeof result === 'string' ? result : undefined;
+    }
+    inferMimeByMagicBytes(localPath, body) {
+        let head;
+        try {
+            if (localPath) {
+                const fd = fs_1.default.openSync(path_1.default.resolve(localPath), 'r');
+                try {
+                    const buf = Buffer.alloc(512);
+                    const n = fs_1.default.readSync(fd, buf, 0, 512, 0);
+                    head = buf.slice(0, n);
+                }
+                finally {
+                    fs_1.default.closeSync(fd);
+                }
+            }
+            else if (Buffer.isBuffer(body)) {
+                head = body.slice(0, 512);
+            }
+        }
+        catch (_a) {
+            return undefined;
+        }
+        if (!head || head.length === 0)
+            return undefined;
+        const startsWith = (sig) => head.length >= sig.length && sig.every((b, i) => head[i] === b);
+        if (startsWith([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]))
+            return 'image/png';
+        if (startsWith([0xFF, 0xD8, 0xFF]))
+            return 'image/jpeg';
+        if (head.slice(0, 6).toString('ascii') === 'GIF87a' || head.slice(0, 6).toString('ascii') === 'GIF89a')
+            return 'image/gif';
+        if (head.slice(0, 4).toString('ascii') === 'RIFF' && head.slice(8, 12).toString('ascii') === 'WEBP')
+            return 'image/webp';
+        if (head.slice(0, 4).toString('ascii') === '%PDF')
+            return 'application/pdf';
+        if (startsWith([0x50, 0x4B, 0x03, 0x04]))
+            return 'application/zip';
+        if (startsWith([0x1F, 0x8B]))
+            return 'application/gzip';
+        if (head.length >= 262 && head.slice(257, 262).toString('ascii') === 'ustar')
+            return 'application/x-tar';
+        return undefined;
+    }
+    assertValidContentType(input) {
+        const ct = input.trim();
+        if (!ct)
+            throw new error_1.CloudBaseError('contentType 不能为空');
+        // 防 header 注入 / 控制字符
+        if (/[\u0000-\u001F\u007F]/.test(ct)) {
+            throw new error_1.CloudBaseError('contentType 非法：包含控制字符');
+        }
+        // 只校验主类型（; 后参数放宽）
+        const base = ct.split(';', 1)[0].trim();
+        const typeSubtypeRe = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+\/[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+        if (!typeSubtypeRe.test(base)) {
+            throw new error_1.CloudBaseError('contentType 非法：主类型格式不正确');
+        }
+        return ct;
+    }
 }
 exports.StorageService = StorageService;
 __decorate([
@@ -1494,3 +2821,51 @@ __decorate([
 __decorate([
     (0, utils_1.preLazy)()
 ], StorageService.prototype, "searchFiles", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "uploadObject", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "deleteObject", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "deleteObjects", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "copyObject", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "moveObject", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "listObjects", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "signObject", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "signObjects", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "signUploadObject", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "uploadObjectBySign", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "downloadAuthenticatedObject", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "downloadObject", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "downloadPublicObject", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "downloadObjectBySign", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "getObjectInfoAuthenticated", null);
+__decorate([
+    (0, utils_1.preLazy)()
+], StorageService.prototype, "getObjectInfoPublic", null);