oicq-icalingua-plus-plus 1.26.29 → 1.26.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/http-api/api.js CHANGED
@@ -17,6 +17,7 @@ const available_actions = [
17
17
  "deleteFavoriteGroup",
18
18
  "setFavoriteGroup",
19
19
  "getFavoriteSpace",
20
+ "getFavoriteFileUrl",
20
21
 
21
22
  "sendPrivateMsg",
22
23
  "sendGroupMsg",
package/index.d.ts CHANGED
@@ -975,6 +975,22 @@ export interface FlashTransferUploadSource {
975
975
  sha1: Buffer | string;
976
976
  }
977
977
 
978
+ /** 客户端分片上传所需的凭证。 */
979
+ export interface FlashTransferUploadCredential {
980
+ ukey: string;
981
+ appid: number;
982
+ file_id: string;
983
+ }
984
+
985
+ /** 由远程 QQ 客户端执行控制操作,文件内容在上传方本地传输。 */
986
+ export interface FlashTransferUploadController<T extends FlashTransferUploadCredential = FlashTransferUploadCredential> {
987
+ create(name: string, options?: FlashTransferCreateOptions): Promise<FlashTransferTask>;
988
+ addFiles(task: FlashTransferTask, files: FlashTransferMetadata[]): Promise<FlashTransferFile[]>;
989
+ applyUpload(task: FlashTransferTask, file: FlashTransferFile, source: FlashTransferUploadSource): Promise<T>;
990
+ completeFile(ticket: T): Promise<void>;
991
+ submit(task_id: string): Promise<void>;
992
+ }
993
+
978
994
  /** 由 applyUpload 返回,保留服务端的 IndexNode、存储参数和业务透传信息。 */
979
995
  export interface FlashTransferUploadTicket {
980
996
  upload: Record<number, any>;
@@ -1033,6 +1049,8 @@ export interface FlashTransferDownload {
1033
1049
  /** 与 Gfs 一样,以下方法会 reject;控制接口保留官网的 snake_case 字段。 */
1034
1050
  export class FlashTransfer {
1035
1051
  private constructor();
1052
+ /** 文件在本机分片上传,创建、登记及完成提交由 control 执行;无需本机登录 QQ */
1053
+ static upload<T extends FlashTransferUploadCredential>(files: FlashTransferUploadInput | FlashTransferUploadInput[], control: FlashTransferUploadController<T>, name?: string, callback?: (percentage: string) => void, options?: FlashTransferCreateOptions & { timeout?: number }): Promise<FlashTransferUploadResult>;
1036
1054
  /** 分享码或 https://qfile.qq.com/q/... 链接转换为文件集 ID */
1037
1055
  resolve(code: string): Promise<string>;
1038
1056
  /** 原生创建文件集,需要在线客户端;保留 task_id 用于完成提交 */
@@ -1042,7 +1060,7 @@ export class FlashTransfer {
1042
1060
  /** 分批登记目录及已计算摘要的文件,返回顺序与请求一致 */
1043
1061
  addFiles(task: Pick<FlashTransferTask, "fileset_id" | "task_id">, files: FlashTransferMetadata[]): Promise<FlashTransferFile[]>;
1044
1062
  /** 底层上传申请;文件必须是 addFiles 返回的节点,source 提供其名称、大小及摘要 */
1045
- applyUpload(task: Pick<FlashTransferTask, "fileset_id">, file: FlashTransferFile, source: FlashTransferUploadSource): Promise<FlashTransferUploadTicket>;
1063
+ applyUpload(task: Pick<FlashTransferTask, "fileset_id">, file: FlashTransferFile, source: FlashTransferUploadSource): Promise<FlashTransferUploadTicket & FlashTransferUploadCredential>;
1046
1064
  /** 分片上传或秒传成功后同步单个文件,随后才能提交整个任务 */
1047
1065
  completeFile(ticket: FlashTransferUploadTicket): Promise<void>;
1048
1066
  /** 文件级完成同步之后提交整个任务,参数是 task_id */
@@ -1532,6 +1550,28 @@ export interface FavoriteItemResults {
1532
1550
  results: { id: string | number; result: number }[];
1533
1551
  }
1534
1552
 
1553
+ /** 收藏文件资源的临时下载凭据;headers 应随资源请求发送。 */
1554
+ export interface FavoriteDownload {
1555
+ /** 收藏 ID。 */
1556
+ cid: string;
1557
+ /** 文件 ID。 */
1558
+ fid: string;
1559
+ /** 收藏的原始协议类型,例如 5 视频、6 文件。 */
1560
+ type: number;
1561
+ /** 原始文件名。 */
1562
+ name: string;
1563
+ /** 文件大小,单位为字节;大整数以十进制字符串表示。 */
1564
+ size: FavoriteInteger;
1565
+ /** 临时资源地址,过期后应重新调用 getFavoriteFileUrl。 */
1566
+ url: string;
1567
+ /** 资源专用鉴权头,应与 url 一起使用。 */
1568
+ headers: Record<string, string>;
1569
+ /** 服务端是否要求下载后重命名文件。 */
1570
+ rename_file: boolean;
1571
+ /** 服务端返回的风险提示。 */
1572
+ risk_tips: string;
1573
+ }
1574
+
1535
1575
  /**
1536
1576
  * 方法不会reject或抛出异常,使用retcode判断是否成功
1537
1577
  * @see {Ret}
@@ -1794,7 +1834,7 @@ export class Client extends EventEmitter {
1794
1834
  /**
1795
1835
  * 编辑收藏,先读取详情再合并指定字段,保留其余元数据和资源。
1796
1836
  * @param cid 收藏 ID。
1797
- * @param changes 需要修改的字段;type=1 支持文本正文,type=6 支持链接字段,type=8 支持 HTML。
1837
+ * @param changes 需要修改的字段;type=1 支持文本正文,type=2 支持链接字段,type=8 支持 HTML。
1798
1838
  * @returns 收藏 ID 与修改时间;其他类型支持元数据编辑。
1799
1839
  */
1800
1840
  editFavorite(cid: string, changes: FavoriteChanges): Promise<Ret<{ cid: string; modify_time: FavoriteInteger }>>;
@@ -1842,6 +1882,15 @@ export class Client extends EventEmitter {
1842
1882
  */
1843
1883
  setFavoriteGroup(cid: string | string[], custom_group_id: number): Promise<Ret<FavoriteItemResults>>;
1844
1884
 
1885
+ /**
1886
+ * 获取收藏文件或视频的临时下载地址,需同时使用返回的资源鉴权头。
1887
+ * 语音与高清音频存储为内联音频数据,不适用此接口。
1888
+ * @param cid 收藏 ID。
1889
+ * @param fid 文件 ID;多附件收藏必须指定。
1890
+ * @returns 下载链接、文件信息、资源鉴权头及服务端重命名要求。
1891
+ */
1892
+ getFavoriteFileUrl(cid: string, fid?: string): Promise<Ret<FavoriteDownload>>;
1893
+
1845
1894
  /**
1846
1895
  * 获取收藏空间使用情况。
1847
1896
  * @returns 空间总量 total_space 与已用量 used_space,单位为字节。
package/index.js CHANGED
@@ -1,5 +1,6 @@
1
1
  "use strict";
2
2
  const { Client } = require("./lib/oicq");
3
+ const { FlashTransfer } = require("./lib/message/qfile");
3
4
  const { segment, cqcode } = require("./util");
4
5
  const { checkUin, NOOP } = require("./lib/common");
5
6
  const pb = require("./lib/algo/pb");
@@ -20,7 +21,7 @@ const constants = {
20
21
  }
21
22
 
22
23
  module.exports = {
23
- Client, createClient,
24
+ Client, createClient, FlashTransfer,
24
25
  segment, cqcode,
25
26
  /** @deprecated */
26
27
  setGlobalConfig: NOOP,
package/lib/client.js CHANGED
@@ -773,6 +773,16 @@ class Client extends EventEmitter {
773
773
  setFavoriteGroup(cid, custom_group_id) {
774
774
  return this._useProtocol(favorites.setFavoriteGroup, arguments);
775
775
  }
776
+ /**
777
+ * 获取收藏视频或文件的临时下载地址及资源鉴权头。
778
+ * @param {string} cid 收藏 ID
779
+ * @param {string} [fid] 文件 ID,多附件收藏需指定
780
+ * @returns {Promise<import("../").Ret<import("../").FavoriteDownload>>}
781
+ */
782
+ getFavoriteFileUrl(cid, fid) {
783
+ return this._useProtocol(favorites.getFavoriteFileUrl, arguments);
784
+ }
785
+
776
786
  /**
777
787
  * 获取收藏空间总量与已用量,单位为字节。
778
788
  * @returns {Promise<import("../").Ret<{total_space: import("../").FavoriteInteger, used_space: import("../").FavoriteInteger}>>}
@@ -307,7 +307,7 @@ async function editFavorite(cid, changes) {
307
307
  summary[8] = rich;
308
308
  }
309
309
  if (changes.url !== undefined || (collection[2] !== 8 && ["title", "publisher", "brief"].some(k => changes[k] !== undefined))) {
310
- if (collection[2] !== 6) throw new Error("Link fields can only edit a link favorite");
310
+ if (collection[2] !== 2) throw new Error("Link fields can only edit a link favorite");
311
311
  const link = fields(summary[2]);
312
312
  for (const [key, tag] of [["url", 1], ["title", 2], ["publisher", 3], ["brief", 4]])
313
313
  if (changes[key] !== undefined) link[tag] = changes[key];
@@ -413,6 +413,55 @@ async function setFavoriteGroup(cid, custom_group_id) {
413
413
  const result = await request(this, 20025, { 1: input, 2: uint(custom_group_id, "custom_group_id") });
414
414
  return result.result ? result : success(itemResults(result.data[1], input));
415
415
  }
416
+ /**
417
+ * 获取收藏文件或视频的临时下载地址,headers 包含该资源所需的鉴权信息。
418
+ * @this {import("./ref").Client}
419
+ * @param {string} cid 收藏 ID
420
+ * @param {string} [fid] 文件 ID;包含多个文件时必须指定
421
+ * @returns {import("./ref").ProtocolResponse}
422
+ */
423
+ async function getFavoriteFileUrl(cid, fid) {
424
+ if (fid !== undefined) string(fid, "fid");
425
+ const detail = await fullInfo(this, cid);
426
+ if (detail.result) return detail;
427
+ const collection = detail.data[1];
428
+ if (collection[3] !== undefined && collection[3] !== 1)
429
+ return error(-1, "Favorite is deleted or unavailable");
430
+ const summary = collection[15], content = detail.data[2];
431
+ const entries = [summary?.[6]?.[1], summary?.[5]?.[31], ...list(content?.[8]?.[5])];
432
+ const files = new Map(entries.filter(file => file && text(file[4])).map(file => [text(file[4]), file]));
433
+ const file = fid === undefined ? (files.size === 1 ? files.values().next().value : undefined) : files.get(fid);
434
+ if (!file) return error(-1, files.size > 1 && fid === undefined ? "Specify fid for a favorite containing multiple files" : "No downloadable file found in favorite");
435
+ const result = await request(this, 20014, { 1: cid, 2: file, 3: 0 });
436
+ if (result.result) return result;
437
+ const rsp = result.data, control = rsp[6];
438
+ const risk_tips = text(control?.[4]);
439
+ if (control && Number(control[1] || 0) !== 1)
440
+ return error(-1, risk_tips || "Server does not allow downloading this resource");
441
+ const https = Boolean(text(rsp[7]));
442
+ const host = text(https ? rsp[7] : rsp[2]);
443
+ if (!host || /[\s/\\?#@]/.test(host)) throw new Error("Invalid favorites download host");
444
+ const target = new global.URL(`${https ? "https" : "http"}://${host}`);
445
+ if (target.username || target.password || target.pathname !== "/" || target.search || target.hash || target.port)
446
+ throw new Error("Invalid favorites download host");
447
+ const port = uint(Number(https ? rsp[8] || 443 : rsp[3] || 80), "download port", 65535);
448
+ if (!port) throw new Error("Invalid favorites download port");
449
+ const token = rsp[1] && rsp[1].toBuffer();
450
+ if (!token || !token.length) throw new Error("Missing favorites download token");
451
+ const info = decode("FileInfo", file), name = info.name || "QQ_Favorite_File";
452
+ target.port = String(port);
453
+ target.pathname = "/ftn_handler/" + token.toString("hex").toUpperCase() + "/";
454
+ target.searchParams.set("fname", name);
455
+ const headers = {}, cookie_name = text(rsp[4]), cookie_value = text(rsp[5]);
456
+ if (cookie_name && cookie_value) {
457
+ if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(cookie_name) || /[;\r\n]/.test(cookie_value))
458
+ throw new Error("Invalid favorites download cookie");
459
+ headers.Cookie = `${cookie_name}=${cookie_value}`;
460
+ }
461
+ return success({ cid, fid: info.fid, type: Number(collection[2]), name, size: info.size ?? 0,
462
+ url: target.href, headers, rename_file: Number(control?.[3]) === 1, risk_tips });
463
+ }
464
+
416
465
  /**
417
466
  * 获取收藏空间总量与已用量,单位为字节。
418
467
  * @this {import("./ref").Client}
@@ -427,5 +476,5 @@ async function getFavoriteSpace() {
427
476
 
428
477
  module.exports = {
429
478
  getFavoriteList, getFavorite, addFavorite, editFavorite, deleteFavorite,
430
- getFavoriteGroups, addFavoriteGroup, editFavoriteGroup, deleteFavoriteGroup, setFavoriteGroup, getFavoriteSpace,
479
+ getFavoriteGroups, addFavoriteGroup, editFavoriteGroup, deleteFavoriteGroup, setFavoriteGroup, getFavoriteSpace, getFavoriteFileUrl,
431
480
  };
@@ -236,10 +236,11 @@ class FlashTransfer {
236
236
  * @param {Pick<import("../../").FlashTransferTask, "fileset_id">} task
237
237
  * @param {import("../../").FlashTransferFile} file
238
238
  * @param {import("../../").FlashTransferUploadSource} source
239
- * @returns {Promise<import("../../").FlashTransferUploadTicket>}
239
+ * @returns {Promise<import("../../").FlashTransferUploadTicket & import("../../").FlashTransferUploadCredential>}
240
240
  */
241
- applyUpload(task, file, source) {
242
- return native.applyUpload(this.c, source, native.getBizTransInfo(task, file), file.is_cover ? 23 : 22);
241
+ async applyUpload(task, file, source) {
242
+ const ticket = await native.applyUpload(this.c, source, native.getBizTransInfo(task, file), file.is_cover ? 23 : 22);
243
+ return { ...ticket, file_id: String(ticket.info[1][2]) };
243
244
  }
244
245
 
245
246
  /**
@@ -260,6 +261,39 @@ class FlashTransfer {
260
261
  */
261
262
  async upload(files, name, callback, options = {}) {
262
263
  native.checkOnline(this.c);
264
+ return this._upload(files, name, callback, options, this);
265
+ }
266
+
267
+ /**
268
+ * 文件在本机读取和上传,控制操作由调用方提供;无需在本机登录 QQ。
269
+ * @param {import("../../").FlashTransferUploadInput | import("../../").FlashTransferUploadInput[]} files
270
+ * @template {import("../../").FlashTransferUploadCredential} T
271
+ * @param {import("../../").FlashTransferUploadController<T>} control
272
+ * @param {string} [name]
273
+ * @param {(percentage: string) => void} [callback]
274
+ * @param {import("../../").FlashTransferCreateOptions & {timeout?: number}} [options]
275
+ * @returns {Promise<import("../../").FlashTransferUploadResult>}
276
+ */
277
+ static async upload(files, control, name, callback, options = {}) {
278
+ for (const method of ["create", "addFiles", "applyUpload", "completeFile", "submit"]) {
279
+ if (typeof control?.[method] !== "function")
280
+ throw new TypeError("upload controller has no " + method);
281
+ }
282
+ const { timeout, ...createOptions } = options;
283
+ return new FlashTransfer(undefined, { timeout })._upload(files, name, callback, createOptions, control);
284
+ }
285
+
286
+ /**
287
+ * @private
288
+ * @param {import("../../").FlashTransferUploadInput | import("../../").FlashTransferUploadInput[]} files
289
+ * @param {string} name
290
+ * @param {(percentage: string) => void} callback
291
+ * @param {import("../../").FlashTransferCreateOptions} options
292
+ * @template {import("../../").FlashTransferUploadCredential} T
293
+ * @param {import("../../").FlashTransferUploadController<T>} control
294
+ * @returns {Promise<import("../../").FlashTransferUploadResult>}
295
+ */
296
+ async _upload(files, name, callback, options, control) {
263
297
  if (callback !== undefined && typeof callback !== "function")
264
298
  throw new TypeError("upload callback must be a function");
265
299
  if (name !== undefined)
@@ -341,14 +375,14 @@ class FlashTransfer {
341
375
  }
342
376
  stage = "create";
343
377
  const total = [...sources.values()].reduce((size, source) => size + source.size, 0);
344
- task = await this.create(name || metadata[0].name, {
378
+ task = await control.create(name || metadata[0].name, {
345
379
  ...options,
346
380
  total_file_count: sources.size,
347
381
  total_file_size: total,
348
382
  first_level_item_count: metadata.filter(file => !file.parent_id).length,
349
383
  });
350
384
  stage = "add_files";
351
- const added = await this.addFiles(task, metadata);
385
+ const added = await control.addFiles(task, metadata);
352
386
  let transferred = 0, completed = 0;
353
387
  for (const file of added) {
354
388
  if (file.is_dir)
@@ -357,7 +391,7 @@ class FlashTransfer {
357
391
  if (!source)
358
392
  throw new FlashTransferError(-1, "upload response has an unknown client file id");
359
393
  stage = "apply_upload";
360
- const ticket = await this.applyUpload(task, file, source);
394
+ const ticket = await control.applyUpload(task, file, source);
361
395
  stage = "upload";
362
396
  if (ticket.ukey && source.size) {
363
397
  await uploadFile(source, ticket.ukey, ticket.appid, this._http, callback ? percentage => {
@@ -366,15 +400,15 @@ class FlashTransfer {
366
400
  }
367
401
  await source.close();
368
402
  stage = "complete_file";
369
- await this.completeFile(ticket);
370
- file.physical = { id: String(ticket.info[1][2]), status: 2 };
403
+ await control.completeFile(ticket);
404
+ file.physical = { id: String(ticket.file_id), status: 2 };
371
405
  transferred += source.size;
372
406
  ++completed;
373
407
  if (callback)
374
408
  callback((total ? transferred / total * 100 : completed / sources.size * 100).toFixed(2));
375
409
  }
376
410
  stage = "submit";
377
- await this.submit(task.task_id);
411
+ await control.submit(task.task_id);
378
412
  return { ...task, files: added };
379
413
  } catch (error) {
380
414
  if (error instanceof Error) {
package/package.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "oicq-icalingua-plus-plus",
3
3
  "app_name": "oicq-icalingua-plus-plus",
4
- "version": "1.26.29",
5
- "app_version": "1.26.29",
6
- "upday": "2026/11/14",
4
+ "version": "1.26.31",
5
+ "app_version": "1.26.31",
6
+ "upday": "2026/11/15",
7
7
  "protocol_version": "v11",
8
8
  "description": "oicq(https://github.com/takayama-lily/oicq) v1 for Icalingua++",
9
9
  "main": "index.js",