oicq-icalingua-plus-plus 1.26.29 → 1.26.30

package/index.d.ts

@@ -975,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>;
@@ -1033,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 用于完成提交 */
@@ -1042,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]) };
     }
 
     /**
@@ -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)
@@ -341,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)
@@ -357,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 => {
@@ -366,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.29",
-  "app_version": "1.26.29",
+  "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++",