oicq-icalingua-plus-plus 1.26.30 → 1.26.31

package/http-api/api.js

@@ -17,6 +17,7 @@ const available_actions = [
     "deleteFavoriteGroup",
     "setFavoriteGroup",
     "getFavoriteSpace",
+    "getFavoriteFileUrl",
 
     "sendPrivateMsg",
     "sendGroupMsg",

package/index.d.ts

@@ -1550,6 +1550,28 @@ export interface FavoriteItemResults {
     results: { id: string | number; result: number }[];
 }
 
+/** 收藏文件资源的临时下载凭据；headers 应随资源请求发送。 */
+export interface FavoriteDownload {
+    /** 收藏 ID。 */
+    cid: string;
+    /** 文件 ID。 */
+    fid: string;
+    /** 收藏的原始协议类型，例如 5 视频、6 文件。 */
+    type: number;
+    /** 原始文件名。 */
+    name: string;
+    /** 文件大小，单位为字节；大整数以十进制字符串表示。 */
+    size: FavoriteInteger;
+    /** 临时资源地址，过期后应重新调用 getFavoriteFileUrl。 */
+    url: string;
+    /** 资源专用鉴权头，应与 url 一起使用。 */
+    headers: Record<string, string>;
+    /** 服务端是否要求下载后重命名文件。 */
+    rename_file: boolean;
+    /** 服务端返回的风险提示。 */
+    risk_tips: string;
+}
+
 /**
  * 方法不会reject或抛出异常，使用retcode判断是否成功
  * @see {Ret}
@@ -1812,7 +1834,7 @@ export class Client extends EventEmitter {
     /**
      * 编辑收藏，先读取详情再合并指定字段，保留其余元数据和资源。
      * @param cid 收藏 ID。
-     * @param changes 需要修改的字段；type=1 支持文本正文，type=6 支持链接字段，type=8 支持 HTML。
+     * @param changes 需要修改的字段；type=1 支持文本正文，type=2 支持链接字段，type=8 支持 HTML。
      * @returns 收藏 ID 与修改时间；其他类型支持元数据编辑。
      */
     editFavorite(cid: string, changes: FavoriteChanges): Promise<Ret<{ cid: string; modify_time: FavoriteInteger }>>;
@@ -1860,6 +1882,15 @@ export class Client extends EventEmitter {
      */
     setFavoriteGroup(cid: string | string[], custom_group_id: number): Promise<Ret<FavoriteItemResults>>;
 
+    /**
+     * 获取收藏文件或视频的临时下载地址，需同时使用返回的资源鉴权头。
+     * 语音与高清音频存储为内联音频数据，不适用此接口。
+     * @param cid 收藏 ID。
+     * @param fid 文件 ID；多附件收藏必须指定。
+     * @returns 下载链接、文件信息、资源鉴权头及服务端重命名要求。
+     */
+    getFavoriteFileUrl(cid: string, fid?: string): Promise<Ret<FavoriteDownload>>;
+
     /**
      * 获取收藏空间使用情况。
      * @returns 空间总量 total_space 与已用量 used_space，单位为字节。

package/lib/client.js

@@ -773,6 +773,16 @@ class Client extends EventEmitter {
     setFavoriteGroup(cid, custom_group_id) {
         return this._useProtocol(favorites.setFavoriteGroup, arguments);
     }
+    /**
+     * 获取收藏视频或文件的临时下载地址及资源鉴权头。
+     * @param {string} cid 收藏 ID
+     * @param {string} [fid] 文件 ID，多附件收藏需指定
+     * @returns {Promise<import("../").Ret<import("../").FavoriteDownload>>}
+     */
+    getFavoriteFileUrl(cid, fid) {
+        return this._useProtocol(favorites.getFavoriteFileUrl, arguments);
+    }
+
     /**
      * 获取收藏空间总量与已用量，单位为字节。
      * @returns {Promise<import("../").Ret<{total_space: import("../").FavoriteInteger, used_space: import("../").FavoriteInteger}>>}

package/lib/core/favorites.js

@@ -307,7 +307,7 @@ async function editFavorite(cid, changes) {
         summary[8] = rich;
     }
     if (changes.url !== undefined || (collection[2] !== 8 && ["title", "publisher", "brief"].some(k => changes[k] !== undefined))) {
-        if (collection[2] !== 6) throw new Error("Link fields can only edit a link favorite");
+        if (collection[2] !== 2) throw new Error("Link fields can only edit a link favorite");
         const link = fields(summary[2]);
         for (const [key, tag] of [["url", 1], ["title", 2], ["publisher", 3], ["brief", 4]])
             if (changes[key] !== undefined) link[tag] = changes[key];
@@ -413,6 +413,55 @@ async function setFavoriteGroup(cid, custom_group_id) {
     const result = await request(this, 20025, { 1: input, 2: uint(custom_group_id, "custom_group_id") });
     return result.result ? result : success(itemResults(result.data[1], input));
 }
+/**
+ * 获取收藏文件或视频的临时下载地址，headers 包含该资源所需的鉴权信息。
+ * @this {import("./ref").Client}
+ * @param {string} cid 收藏 ID
+ * @param {string} [fid] 文件 ID；包含多个文件时必须指定
+ * @returns {import("./ref").ProtocolResponse}
+ */
+async function getFavoriteFileUrl(cid, fid) {
+    if (fid !== undefined) string(fid, "fid");
+    const detail = await fullInfo(this, cid);
+    if (detail.result) return detail;
+    const collection = detail.data[1];
+    if (collection[3] !== undefined && collection[3] !== 1)
+        return error(-1, "Favorite is deleted or unavailable");
+    const summary = collection[15], content = detail.data[2];
+    const entries = [summary?.[6]?.[1], summary?.[5]?.[31], ...list(content?.[8]?.[5])];
+    const files = new Map(entries.filter(file => file && text(file[4])).map(file => [text(file[4]), file]));
+    const file = fid === undefined ? (files.size === 1 ? files.values().next().value : undefined) : files.get(fid);
+    if (!file) return error(-1, files.size > 1 && fid === undefined ? "Specify fid for a favorite containing multiple files" : "No downloadable file found in favorite");
+    const result = await request(this, 20014, { 1: cid, 2: file, 3: 0 });
+    if (result.result) return result;
+    const rsp = result.data, control = rsp[6];
+    const risk_tips = text(control?.[4]);
+    if (control && Number(control[1] || 0) !== 1)
+        return error(-1, risk_tips || "Server does not allow downloading this resource");
+    const https = Boolean(text(rsp[7]));
+    const host = text(https ? rsp[7] : rsp[2]);
+    if (!host || /[\s/\\?#@]/.test(host)) throw new Error("Invalid favorites download host");
+    const target = new global.URL(`${https ? "https" : "http"}://${host}`);
+    if (target.username || target.password || target.pathname !== "/" || target.search || target.hash || target.port)
+        throw new Error("Invalid favorites download host");
+    const port = uint(Number(https ? rsp[8] || 443 : rsp[3] || 80), "download port", 65535);
+    if (!port) throw new Error("Invalid favorites download port");
+    const token = rsp[1] && rsp[1].toBuffer();
+    if (!token || !token.length) throw new Error("Missing favorites download token");
+    const info = decode("FileInfo", file), name = info.name || "QQ_Favorite_File";
+    target.port = String(port);
+    target.pathname = "/ftn_handler/" + token.toString("hex").toUpperCase() + "/";
+    target.searchParams.set("fname", name);
+    const headers = {}, cookie_name = text(rsp[4]), cookie_value = text(rsp[5]);
+    if (cookie_name && cookie_value) {
+        if (!/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(cookie_name) || /[;\r\n]/.test(cookie_value))
+            throw new Error("Invalid favorites download cookie");
+        headers.Cookie = `${cookie_name}=${cookie_value}`;
+    }
+    return success({ cid, fid: info.fid, type: Number(collection[2]), name, size: info.size ?? 0,
+        url: target.href, headers, rename_file: Number(control?.[3]) === 1, risk_tips });
+}
+
 /**
  * 获取收藏空间总量与已用量，单位为字节。
  * @this {import("./ref").Client}
@@ -427,5 +476,5 @@ async function getFavoriteSpace() {
 
 module.exports = {
     getFavoriteList, getFavorite, addFavorite, editFavorite, deleteFavorite,
-    getFavoriteGroups, addFavoriteGroup, editFavoriteGroup, deleteFavoriteGroup, setFavoriteGroup, getFavoriteSpace,
+    getFavoriteGroups, addFavoriteGroup, editFavoriteGroup, deleteFavoriteGroup, setFavoriteGroup, getFavoriteSpace, getFavoriteFileUrl,
 };

package/package.json

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