wx2tg-puppet 3.0.8 → 3.0.9

package/README.md

@@ -0,0 +1,37 @@
+# wx2tg-puppet
+
+微信机器人核心库。通过已有的 `WxBot` 配置服务端地址、设备类型和本地数据库。
+
+## 3.0.9：文件下载兼容
+
+- 支持服务端 v6.0.10 的 `DownloadFile` 二进制 `200/206` 响应，同时兼容旧版 JSON/Base64 响应。
+- 现有 `toolsApi.DownloadFile()` 仍返回 `Data.data.buffer`（Base64）和 `Data.BaseResponse.ret`，调用方无需为响应格式切换而修改解析逻辑。
+- `toolsApi.DownloadFileBinary()` 返回单个分片的 `Buffer`，保留 HTTP 状态与响应头。
+- `toolsApi.DownloadFileBuffer()` 下载完整文件，默认每次请求 512 KiB，按实际返回字节推进偏移；校验范围、总长度、非空数据和旧版业务状态。
+- `Message.toFileBox()` 的普通文件分片路径使用新下载器；原有超过 80 MiB 的 `DownloadFileMessage` 路径保留。图片、视频和其他 API 的 JSON 解析保持原样。
+
+```ts
+import {toolsApi} from 'wx2tg-puppet/dist/api/ToolsApi';
+
+// 使用当前登录账号及原始文件消息中的真实元数据；不要修改文件总长度。
+const buffer = await toolsApi.DownloadFileBuffer({
+  Wxid: 'your_logged_in_account',
+  UserName: 'original_conversation',
+  AttachId: 'original_attachment_id',
+  DataLen: originalFileSize,
+});
+```
+
+CDN 回退的首片可能需要等待整份文件接收完成，因此文件分片请求单独使用 180 秒超时；不会修改全局 Axios 配置。完整下载仅对临时网络错误及 HTTP 429/502/503/504 做有限重试，最多三次；业务拒绝、空内容和范围错误立即失败。
+
+失败会抛出 `FileDownloadError`，包含可用的 `httpStatus`、`businessCode` 和 `retryable`。不要把 HTTP 200 或外层 `Success=true` 当作文件下载成功；SDK 会继续检查原生返回码和内容。下载异常不会附带原始请求配置或附件密钥。
+
+## 验证与发布
+
+```sh
+npm run test:download
+npm pack --dry-run
+npm publish
+```
+
+回归使用本地模拟 HTTP 服务，包括二进制短分片、旧版 JSON、约 26 MiB 文件、范围与业务错误以及 `Message.toFileBox()`，不登录微信或访问真实文件。上述验证不代表真实 CDN 或 home 部署已通过。发布包仅包含 `dist`、README 和 npm 必需元数据。

package/dist/api/ToolsApi.d.ts

@@ -7,8 +7,12 @@ declare class ToolsApi {
     GetRealNameInfo(wxid: string): Promise<AxiosResponse<ApiResponse>>;
     /** 抢红包 */
     OpenHongBao(body: any): Promise<AxiosResponse<ApiResponse>>;
-    /** 文件下载 */
+    /** 文件分片：兼容旧 JSON 和 v6.0.10 二进制响应，保留 Data.data.buffer。 */
     DownloadFile(body: any): Promise<AxiosResponse<ApiResponse>>;
+    /** 获取原始二进制分片，HTTP 206 的范围会先被校验。 */
+    DownloadFileBinary(body: any): Promise<AxiosResponse<Buffer>>;
+    /** 按实际返回字节推进分片并拼接完整文件，不需要传 Section。 */
+    DownloadFileBuffer(body: any): Promise<Buffer>;
     /** 文件消息下载 */
     DownloadFileMessage(body: any): Promise<AxiosResponse<ApiResponse>>;
     /** 高清图片下载 */

package/dist/api/ToolsApi.js

@@ -1,7 +1,17 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toolsApi = void 0;
 const axiosInstance_1 = require("../utils/axiosInstance");
+const fileDownload_1 = require("../utils/fileDownload");
 class ToolsApi {
     /** 生成支付二维码 */
     GeneratePayQCode(wxid) {
@@ -15,9 +25,22 @@ class ToolsApi {
     OpenHongBao(body) {
         return axiosInstance_1.axiosInstance.post('/TenPay/OpenHongBao', body);
     }
-    /** 文件下载 */
+    /** 文件分片：兼容旧 JSON 和 v6.0.10 二进制响应，保留 Data.data.buffer。 */
     DownloadFile(body) {
-        return axiosInstance_1.axiosInstance.post('/Tools/DownloadFile', body);
+        return __awaiter(this, void 0, void 0, function* () {
+            return (0, fileDownload_1.legacyFileSection)(yield (0, fileDownload_1.fetchFileSection)(body), body);
+        });
+    }
+    /** 获取原始二进制分片，HTTP 206 的范围会先被校验。 */
+    DownloadFileBinary(body) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const section = yield (0, fileDownload_1.fetchFileSection)(body);
+            return Object.assign(Object.assign({}, section.response), { data: section.buffer });
+        });
+    }
+    /** 按实际返回字节推进分片并拼接完整文件，不需要传 Section。 */
+    DownloadFileBuffer(body) {
+        return (0, fileDownload_1.downloadFileBuffer)(body);
     }
     /** 文件消息下载 */
     DownloadFileMessage(body) {

package/dist/core/Message.js

@@ -559,37 +559,13 @@ class Message {
                 if (totalSize > LARGE_FILE_THRESHOLD) {
                     return yield this.downloadFileMessage();
                 }
-                // Get initial chunk size from first request
-                const firstChunk = FileChunkHelper_1.FileChunkHelper.getChunk(totalSize, 0);
-                if (!firstChunk)
-                    return null;
-                // @ts-ignore - Using any type for response due to mixed axios versions
-                const firstResp = yield retryDownload(() => ToolsApi_1.toolsApi.DownloadFile({
-                    "AppID": json.msg.appmsg.appid,
-                    "AttachId": json.msg.appmsg.appattach.attachid,
-                    "DataLen": totalSize,
-                    "Section": firstChunk,
-                    "UserName": this.msg.FromUserName,
-                    "Wxid": (config === null || config === void 0 ? void 0 : config.wxid) || ''
-                }));
-                const downloadedLength = firstResp.data.Data.data.iLen;
-                const chunks = FileChunkHelper_1.FileChunkHelper.calculateChunks(totalSize, downloadedLength);
-                let completeBuffer = Buffer.from(firstResp.data.Data.data.buffer, 'base64');
-                // Start from second chunk since we already have the first one
-                for (let i = 1; i < chunks.length; i++) {
-                    const chunk = chunks[i];
-                    // @ts-ignore - Using any type for response due to mixed axios versions
-                    const resp = yield retryDownload(() => ToolsApi_1.toolsApi.DownloadFile({
-                        "AppID": json.msg.appmsg.appid,
-                        "AttachId": json.msg.appmsg.appattach.attachid,
-                        "DataLen": totalSize,
-                        "Section": chunk,
-                        "UserName": this.msg.FromUserName,
-                        "Wxid": (config === null || config === void 0 ? void 0 : config.wxid) || ''
-                    }));
-                    const chunkData = Buffer.from(resp.data.Data.data.buffer, 'base64');
-                    completeBuffer = Buffer.concat([completeBuffer, chunkData]);
-                }
+                const completeBuffer = yield ToolsApi_1.toolsApi.DownloadFileBuffer({
+                    AppID: json.msg.appmsg.appid,
+                    AttachId: json.msg.appmsg.appattach.attachid,
+                    DataLen: totalSize,
+                    UserName: this.msg.FromUserName,
+                    Wxid: (config === null || config === void 0 ? void 0 : config.wxid) || ''
+                });
                 const fileBox = file_box_1.FileBox.fromBuffer(completeBuffer, json.msg.appmsg.title);
                 return fileBox;
             }

package/dist/utils/fileDownload.d.ts

@@ -0,0 +1,20 @@
+import { AxiosResponse } from 'axios';
+import { ApiResponse } from '../types/ApiResponse';
+export declare class FileDownloadError extends Error {
+    httpStatus?: number | undefined;
+    businessCode?: number | undefined;
+    retryable: boolean;
+    constructor(message: string, httpStatus?: number | undefined, businessCode?: number | undefined, retryable?: boolean);
+}
+interface FileSection {
+    response: AxiosResponse;
+    buffer: Buffer;
+    legacy?: ApiResponse;
+}
+/** Read bytes without invoking the shared JSON-only Axios transformer. */
+export declare function fetchFileSection(body: any): Promise<FileSection>;
+/** Preserve the existing SDK envelope for consumers using Data.data.buffer. */
+export declare function legacyFileSection(section: FileSection, body: any): AxiosResponse<ApiResponse>;
+/** Advance by actual received bytes; a successful short section is not EOF. */
+export declare function downloadFileBuffer(body: any): Promise<Buffer>;
+export {};

package/dist/utils/fileDownload.js

@@ -0,0 +1,176 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileDownloadError = void 0;
+exports.fetchFileSection = fetchFileSection;
+exports.legacyFileSection = legacyFileSection;
+exports.downloadFileBuffer = downloadFileBuffer;
+const json_bigint_1 = __importDefault(require("json-bigint"));
+const axiosInstance_1 = require("./axiosInstance");
+const parseJSON = (0, json_bigint_1.default)({ storeAsString: true });
+const FILE_TIMEOUT = 180000;
+const CHUNK_SIZE = 512 * 1024;
+class FileDownloadError extends Error {
+    constructor(message, httpStatus, businessCode, retryable = false) {
+        super(message);
+        this.httpStatus = httpStatus;
+        this.businessCode = businessCode;
+        this.retryable = retryable;
+        this.name = 'FileDownloadError';
+    }
+}
+exports.FileDownloadError = FileDownloadError;
+function requestRange(body) {
+    var _a, _b;
+    const total = body === null || body === void 0 ? void 0 : body.DataLen, start = (_a = body === null || body === void 0 ? void 0 : body.Section) === null || _a === void 0 ? void 0 : _a.StartPos, length = (_b = body === null || body === void 0 ? void 0 : body.Section) === null || _b === void 0 ? void 0 : _b.DataLen;
+    if (![total, start, length].every(Number.isSafeInteger) || total <= 0 || total > 0xffffffff || start < 0 || start >= total || length <= 0 || length > 0xffffffff) {
+        throw new FileDownloadError('Invalid file size or section range');
+    }
+    return { total, start, length: Math.min(length, total - start) };
+}
+function header(response, name) {
+    var _a, _b;
+    return String((_b = (_a = response.headers) === null || _a === void 0 ? void 0 : _a[name]) !== null && _b !== void 0 ? _b : '').trim();
+}
+function safeMessage(value, body) {
+    if (typeof value !== 'string')
+        return '';
+    let message = value;
+    for (const key of ['AttachId', 'Wxid', 'UserName', 'AppID']) {
+        const secret = body === null || body === void 0 ? void 0 : body[key];
+        if (typeof secret === 'string' && secret.length > 3)
+            message = message.split(secret).join('[redacted]');
+    }
+    return message.replace(/@cdn_\S+/g, '[redacted]')
+        .replace(/https?:\/\/\S+/gi, '[url redacted]')
+        .replace(/\b[a-f\d]{24,}\b/gi, '[redacted]')
+        .replace(/[A-Za-z\d+/=]{100,}/g, '[data redacted]')
+        .replace(/[\r\n]+/g, ' ').slice(0, 400);
+}
+function invalid(message) {
+    throw new FileDownloadError(message);
+}
+function decodeLegacy(data, body) {
+    var _a, _b;
+    const { total, start, length } = requestRange(body);
+    const payload = data === null || data === void 0 ? void 0 : data.Data, native = (_a = payload === null || payload === void 0 ? void 0 : payload.BaseResponse) !== null && _a !== void 0 ? _a : payload === null || payload === void 0 ? void 0 : payload.baseResponse;
+    if ((data === null || data === void 0 ? void 0 : data.Success) !== true || (data === null || data === void 0 ? void 0 : data.Code) !== 0 || ((native === null || native === void 0 ? void 0 : native.ret) !== undefined && native.ret !== 0)) {
+        const code = typeof (data === null || data === void 0 ? void 0 : data.Code) === 'number' ? data.Code : undefined;
+        throw new FileDownloadError(`File download rejected${code !== undefined ? ` (Code=${code})` : ''}${(native === null || native === void 0 ? void 0 : native.ret) !== undefined ? ` (ret=${native.ret})` : ''}: ${safeMessage(data === null || data === void 0 ? void 0 : data.Message, body)}`, 200, code);
+    }
+    const encoded = (_b = payload === null || payload === void 0 ? void 0 : payload.data) === null || _b === void 0 ? void 0 : _b.buffer;
+    if (typeof encoded !== 'string' || !encoded.length || !/^[A-Za-z\d+/]*={0,2}$/.test(encoded) || encoded.length % 4 === 1) {
+        return invalid('File download returned an empty or invalid Base64 section');
+    }
+    const bytes = Buffer.from(encoded, 'base64');
+    if (!bytes.length || bytes.length > length || bytes.toString('base64').replace(/=+$/, '') !== encoded.replace(/=+$/, '')) {
+        return invalid('File download returned an invalid section length');
+    }
+    for (const [value, expected] of [[payload.data.iLen, bytes.length], [payload.dataLen, bytes.length], [payload.totalLen, total], [payload.startPos, start]]) {
+        if (value !== undefined && value !== expected)
+            return invalid('File download section metadata does not match the requested range');
+    }
+    return bytes;
+}
+/** Read bytes without invoking the shared JSON-only Axios transformer. */
+function fetchFileSection(body) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { total, start, length } = requestRange(body);
+        let response;
+        try {
+            response = yield axiosInstance_1.axiosInstance.post('/Tools/DownloadFile', body, {
+                responseType: 'arraybuffer',
+                transformResponse: [data => data],
+                validateStatus: () => true,
+                timeout: FILE_TIMEOUT,
+                maxContentLength: Math.ceil(length * 4 / 3) + 64 * 1024,
+            });
+        }
+        catch (error) {
+            const errorCode = error === null || error === void 0 ? void 0 : error.code;
+            const code = typeof errorCode === 'string' && /^[A-Z_\d]+$/.test(errorCode) ? errorCode : 'NETWORK_ERROR';
+            throw new FileDownloadError(`File section request failed (${code})`, undefined, undefined, ['ECONNRESET', 'ECONNABORTED', 'ETIMEDOUT', 'EPIPE', 'EAI_AGAIN', 'ECONNREFUSED', 'NETWORK_ERROR'].includes(code));
+        }
+        const contentType = header(response, 'content-type').split(';')[0].toLowerCase();
+        const raw = response.data;
+        const bytes = Buffer.isBuffer(raw) ? raw : raw instanceof ArrayBuffer ? Buffer.from(raw) :
+            ArrayBuffer.isView(raw) ? Buffer.from(raw.buffer, raw.byteOffset, raw.byteLength) :
+                typeof raw === 'string' && contentType === 'application/json' ? Buffer.from(raw) : invalid('File download returned an unsupported response');
+        let json;
+        if (contentType === 'application/json' || (!contentType && bytes[0] === 123)) {
+            try {
+                json = parseJSON.parse(bytes.toString('utf8'));
+            }
+            catch (_a) {
+                return invalid(`File download returned invalid JSON (HTTP ${response.status})`);
+            }
+        }
+        if (response.status !== 200 && response.status !== 206) {
+            const code = typeof (json === null || json === void 0 ? void 0 : json.Code) === 'number' ? json.Code : undefined;
+            throw new FileDownloadError(`File download failed (HTTP ${response.status}${code !== undefined ? `, Code=${code}` : ''}): ${safeMessage(json === null || json === void 0 ? void 0 : json.Message, body)}`, response.status, code, [429, 502, 503, 504].includes(response.status));
+        }
+        if (json)
+            return { response, buffer: decodeLegacy(json, body), legacy: json };
+        if (contentType !== 'application/octet-stream' || !bytes.length || bytes.length > length) {
+            return invalid('File download returned an empty or invalid binary section');
+        }
+        const declared = header(response, 'content-length');
+        if (declared && (!/^\d+$/.test(declared) || Number(declared) !== bytes.length)) {
+            return invalid('File download Content-Length does not match received bytes');
+        }
+        if (response.status === 206) {
+            const range = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(header(response, 'content-range'));
+            if (!range || Number(range[1]) !== start || Number(range[2]) !== start + bytes.length - 1 || Number(range[3]) !== total) {
+                return invalid('File download Content-Range does not match the requested section');
+            }
+        }
+        else if (start !== 0 || bytes.length !== total) {
+            return invalid('File download returned HTTP 200 for an incomplete file');
+        }
+        return { response, buffer: bytes };
+    });
+}
+/** Preserve the existing SDK envelope for consumers using Data.data.buffer. */
+function legacyFileSection(section, body) {
+    var _a;
+    const { response, buffer, legacy } = section;
+    return Object.assign(Object.assign({}, response), { data: Object.assign(Object.assign({}, legacy), { Code: 0, Success: true, Message: (legacy === null || legacy === void 0 ? void 0 : legacy.Message) || '成功', Data: Object.assign(Object.assign({}, legacy === null || legacy === void 0 ? void 0 : legacy.Data), { BaseResponse: { ret: 0 }, totalLen: body.DataLen, startPos: body.Section.StartPos, dataLen: buffer.length, data: Object.assign(Object.assign({}, (_a = legacy === null || legacy === void 0 ? void 0 : legacy.Data) === null || _a === void 0 ? void 0 : _a.data), { iLen: buffer.length, buffer: buffer.toString('base64') }) }) }) });
+}
+/** Advance by actual received bytes; a successful short section is not EOF. */
+function downloadFileBuffer(body) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const total = body === null || body === void 0 ? void 0 : body.DataLen;
+        requestRange(Object.assign(Object.assign({}, body), { Section: { StartPos: 0, DataLen: CHUNK_SIZE } }));
+        const chunks = [];
+        let offset = 0;
+        while (offset < total) {
+            const request = Object.assign(Object.assign({}, body), { Section: { StartPos: offset, DataLen: Math.min(CHUNK_SIZE, total - offset) } });
+            let section;
+            for (let attempt = 0;; attempt++) {
+                try {
+                    section = yield fetchFileSection(request);
+                    break;
+                }
+                catch (error) {
+                    if (!(error instanceof FileDownloadError) || !error.retryable || attempt >= 2)
+                        throw error;
+                    yield new Promise(resolve => setTimeout(resolve, 1000 * (attempt + 1)));
+                }
+            }
+            chunks.push(section.buffer);
+            offset += section.buffer.length;
+        }
+        return Buffer.concat(chunks, total);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wx2tg-puppet",
-  "version": "3.0.8",
+  "version": "3.0.9",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -9,6 +9,7 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test:download": "npm run build && node --test tests/file-download.test.cjs",
     "start": "node dist/index.js",
     "dev": "ts-node src/index.ts",
     "test": "ts-node src/test.ts",