oicq-icalingua-plus-plus 1.26.28 → 1.26.30

package/index.d.ts

@@ -960,7 +960,13 @@ export interface FlashTransferMetadata {
     file_count?: number;
 }
 
-export type FlashTransferUploadInput = MediaFile | { file: MediaFile; name?: string };
+export interface FlashTransferUploadDirectory {
+    name: string;
+    /** 虚拟目录的子项；文件仍从各自的源路径读取 */
+    children: FlashTransferUploadInput[];
+}
+
+export type FlashTransferUploadInput = MediaFile | { file: MediaFile; name?: string } | FlashTransferUploadDirectory;
 
 export interface FlashTransferUploadSource {
     name: string;
@@ -969,6 +975,22 @@ export interface FlashTransferUploadSource {
     sha1: Buffer | string;
 }
 
+/** 客户端分片上传所需的凭证。 */
+export interface FlashTransferUploadCredential {
+    ukey: string;
+    appid: number;
+    file_id: string;
+}
+
+/** 由远程 QQ 客户端执行控制操作，文件内容在上传方本地传输。 */
+export interface FlashTransferUploadController<T extends FlashTransferUploadCredential = FlashTransferUploadCredential> {
+    create(name: string, options?: FlashTransferCreateOptions): Promise<FlashTransferTask>;
+    addFiles(task: FlashTransferTask, files: FlashTransferMetadata[]): Promise<FlashTransferFile[]>;
+    applyUpload(task: FlashTransferTask, file: FlashTransferFile, source: FlashTransferUploadSource): Promise<T>;
+    completeFile(ticket: T): Promise<void>;
+    submit(task_id: string): Promise<void>;
+}
+
 /** 由 applyUpload 返回，保留服务端的 IndexNode、存储参数和业务透传信息。 */
 export interface FlashTransferUploadTicket {
     upload: Record<number, any>;
@@ -1027,6 +1049,8 @@ export interface FlashTransferDownload {
 /** 与 Gfs 一样，以下方法会 reject；控制接口保留官网的 snake_case 字段。 */
 export class FlashTransfer {
     private constructor();
+    /** 文件在本机分片上传，创建、登记及完成提交由 control 执行；无需本机登录 QQ */
+    static upload<T extends FlashTransferUploadCredential>(files: FlashTransferUploadInput | FlashTransferUploadInput[], control: FlashTransferUploadController<T>, name?: string, callback?: (percentage: string) => void, options?: FlashTransferCreateOptions & { timeout?: number }): Promise<FlashTransferUploadResult>;
     /** 分享码或 https://qfile.qq.com/q/... 链接转换为文件集 ID */
     resolve(code: string): Promise<string>;
     /** 原生创建文件集，需要在线客户端；保留 task_id 用于完成提交 */
@@ -1036,7 +1060,7 @@ export class FlashTransfer {
     /** 分批登记目录及已计算摘要的文件，返回顺序与请求一致 */
     addFiles(task: Pick<FlashTransferTask, "fileset_id" | "task_id">, files: FlashTransferMetadata[]): Promise<FlashTransferFile[]>;
     /** 底层上传申请；文件必须是 addFiles 返回的节点，source 提供其名称、大小及摘要 */
-    applyUpload(task: Pick<FlashTransferTask, "fileset_id">, file: FlashTransferFile, source: FlashTransferUploadSource): Promise<FlashTransferUploadTicket>;
+    applyUpload(task: Pick<FlashTransferTask, "fileset_id">, file: FlashTransferFile, source: FlashTransferUploadSource): Promise<FlashTransferUploadTicket & FlashTransferUploadCredential>;
     /** 分片上传或秒传成功后同步单个文件，随后才能提交整个任务 */
     completeFile(ticket: FlashTransferUploadTicket): Promise<void>;
     /** 文件级完成同步之后提交整个任务，参数是 task_id */

package/index.js

@@ -1,5 +1,6 @@
 "use strict";
 const { Client } = require("./lib/oicq");
+const { FlashTransfer } = require("./lib/message/qfile");
 const { segment, cqcode } = require("./util");
 const { checkUin, NOOP } = require("./lib/common");
 const pb = require("./lib/algo/pb");
@@ -20,7 +21,7 @@ const constants = {
 }
 
 module.exports = {
-    Client, createClient,
+    Client, createClient, FlashTransfer,
     segment, cqcode,
     /** @deprecated */
     setGlobalConfig: NOOP,

package/lib/message/qfile.js

@@ -236,10 +236,11 @@ class FlashTransfer {
      * @param {Pick<import("../../").FlashTransferTask, "fileset_id">} task
      * @param {import("../../").FlashTransferFile} file
      * @param {import("../../").FlashTransferUploadSource} source
-     * @returns {Promise<import("../../").FlashTransferUploadTicket>}
+     * @returns {Promise<import("../../").FlashTransferUploadTicket & import("../../").FlashTransferUploadCredential>}
      */
-    applyUpload(task, file, source) {
-        return native.applyUpload(this.c, source, native.getBizTransInfo(task, file), file.is_cover ? 23 : 22);
+    async applyUpload(task, file, source) {
+        const ticket = await native.applyUpload(this.c, source, native.getBizTransInfo(task, file), file.is_cover ? 23 : 22);
+        return { ...ticket, file_id: String(ticket.info[1][2]) };
     }
 
     /**
@@ -251,7 +252,7 @@ class FlashTransfer {
     }
 
     /**
-     * 本地文件、目录或 Buffer 的完整上传；直到文件同步和任务提交均成功才返回。
+     * 本地文件、目录、虚拟目录或 Buffer 的完整上传；直到文件同步和任务提交均成功才返回。
      * @param {import("../../").FlashTransferUploadInput | import("../../").FlashTransferUploadInput[]} files
      * @param {string} [name]
      * @param {(percentage: string) => void} [callback]
@@ -260,6 +261,39 @@ class FlashTransfer {
      */
     async upload(files, name, callback, options = {}) {
         native.checkOnline(this.c);
+        return this._upload(files, name, callback, options, this);
+    }
+
+    /**
+     * 文件在本机读取和上传，控制操作由调用方提供；无需在本机登录 QQ。
+     * @param {import("../../").FlashTransferUploadInput | import("../../").FlashTransferUploadInput[]} files
+     * @template {import("../../").FlashTransferUploadCredential} T
+     * @param {import("../../").FlashTransferUploadController<T>} control
+     * @param {string} [name]
+     * @param {(percentage: string) => void} [callback]
+     * @param {import("../../").FlashTransferCreateOptions & {timeout?: number}} [options]
+     * @returns {Promise<import("../../").FlashTransferUploadResult>}
+     */
+    static async upload(files, control, name, callback, options = {}) {
+        for (const method of ["create", "addFiles", "applyUpload", "completeFile", "submit"]) {
+            if (typeof control?.[method] !== "function")
+                throw new TypeError("upload controller has no " + method);
+        }
+        const { timeout, ...createOptions } = options;
+        return new FlashTransfer(undefined, { timeout })._upload(files, name, callback, createOptions, control);
+    }
+
+    /**
+     * @private
+     * @param {import("../../").FlashTransferUploadInput | import("../../").FlashTransferUploadInput[]} files
+     * @param {string} name
+     * @param {(percentage: string) => void} callback
+     * @param {import("../../").FlashTransferCreateOptions} options
+     * @template {import("../../").FlashTransferUploadCredential} T
+     * @param {import("../../").FlashTransferUploadController<T>} control
+     * @returns {Promise<import("../../").FlashTransferUploadResult>}
+     */
+    async _upload(files, name, callback, options, control) {
         if (callback !== undefined && typeof callback !== "function")
             throw new TypeError("upload callback must be a function");
         if (name !== undefined)
@@ -274,7 +308,7 @@ class FlashTransfer {
         let task;
         let stage = "hash";
         /**
-         * @param {import("../../").MediaFile} file
+         * @param {import("../../").MediaFile | import("../../").FlashTransferUploadDirectory} file
          * @param {string} [file_name]
          * @param {string} [parent_id]
          * @param {number} [depth=1]
@@ -283,9 +317,15 @@ class FlashTransfer {
         const collect = async (file, file_name, parent_id = "", depth = 1) => {
             if (file_name !== undefined)
                 file_name = checkString(file_name, "file name");
+            const virtual = !!file && typeof file === "object" && "children" in file;
+            if (virtual) {
+                if (!Array.isArray(file.children))
+                    throw new TypeError("directory children must be an array");
+                file_name = checkString(file_name || file.name, "directory name");
+            }
             const binary = file instanceof Uint8Array || file instanceof ArrayBuffer || file instanceof SharedArrayBuffer;
             let stat;
-            if (!binary) {
+            if (!virtual && !binary) {
                 if (typeof file !== "string")
                     throw new TypeError("upload source must be a local path or binary data");
                 file = path.resolve(file);
@@ -298,17 +338,19 @@ class FlashTransfer {
                 cli_fileid, parent_id, depth,
                 name: file_name || (!binary ? path.basename(file) : ""),
                 cli_file_index: metadata.length + 1,
-                is_dir: !!stat?.isDirectory(),
+                is_dir: virtual || !!stat?.isDirectory(),
                 file_size: 0,
                 file_count: 0,
             };
             metadata.push(meta);
             if (meta.is_dir) {
                 meta.file_type = 25;
-                const children = await fs.promises.readdir(file, { withFileTypes: true });
-                children.sort((a, b) => a.name.localeCompare(b.name));
+                const children = virtual ? file.children : (await fs.promises.readdir(file, { withFileTypes: true }))
+                    .sort((a, b) => a.name.localeCompare(b.name))
+                    .map(child => ({ file: path.join(file, child.name), name: child.name }));
                 for (const child of children) {
-                    const entry = await collect(path.join(file, child.name), child.name, cli_fileid, depth + 1);
+                    const input = child && typeof child === "object" && "file" in child ? child : { file: child };
+                    const entry = await collect(input.file, input.name, cli_fileid, depth + 1);
                     meta.file_size += entry.file_size;
                     ++meta.file_count;
                 }
@@ -333,14 +375,14 @@ class FlashTransfer {
             }
             stage = "create";
             const total = [...sources.values()].reduce((size, source) => size + source.size, 0);
-            task = await this.create(name || metadata[0].name, {
+            task = await control.create(name || metadata[0].name, {
                 ...options,
                 total_file_count: sources.size,
                 total_file_size: total,
                 first_level_item_count: metadata.filter(file => !file.parent_id).length,
             });
             stage = "add_files";
-            const added = await this.addFiles(task, metadata);
+            const added = await control.addFiles(task, metadata);
             let transferred = 0, completed = 0;
             for (const file of added) {
                 if (file.is_dir)
@@ -349,7 +391,7 @@ class FlashTransfer {
                 if (!source)
                     throw new FlashTransferError(-1, "upload response has an unknown client file id");
                 stage = "apply_upload";
-                const ticket = await this.applyUpload(task, file, source);
+                const ticket = await control.applyUpload(task, file, source);
                 stage = "upload";
                 if (ticket.ukey && source.size) {
                     await uploadFile(source, ticket.ukey, ticket.appid, this._http, callback ? percentage => {
@@ -358,15 +400,15 @@ class FlashTransfer {
                 }
                 await source.close();
                 stage = "complete_file";
-                await this.completeFile(ticket);
-                file.physical = { id: String(ticket.info[1][2]), status: 2 };
+                await control.completeFile(ticket);
+                file.physical = { id: String(ticket.file_id), status: 2 };
                 transferred += source.size;
                 ++completed;
                 if (callback)
                     callback((total ? transferred / total * 100 : completed / sources.size * 100).toFixed(2));
             }
             stage = "submit";
-            await this.submit(task.task_id);
+            await control.submit(task.task_id);
             return { ...task, files: added };
         } catch (error) {
             if (error instanceof Error) {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "oicq-icalingua-plus-plus",
   "app_name": "oicq-icalingua-plus-plus",
-  "version": "1.26.28",
-  "app_version": "1.26.28",
+  "version": "1.26.30",
+  "app_version": "1.26.30",
   "upday": "2026/11/14",
   "protocol_version": "v11",
   "description": "oicq(https://github.com/takayama-lily/oicq) v1 for Icalingua++",