oicq-icalingua-plus-plus 1.26.26 → 1.26.28

package/http-api/api.js

@@ -6,6 +6,18 @@ let bot;
 class NotFoundError extends Error {}
 
 const available_actions = [
+    "getFavoriteList",
+    "getFavorite",
+    "addFavorite",
+    "editFavorite",
+    "deleteFavorite",
+    "getFavoriteGroups",
+    "addFavoriteGroup",
+    "editFavoriteGroup",
+    "deleteFavoriteGroup",
+    "setFavoriteGroup",
+    "getFavoriteSpace",
+
     "sendPrivateMsg",
     "sendGroupMsg",
     "sendDiscussMsg",

package/index.d.ts

@@ -54,9 +54,12 @@ export interface ConfBot {
     /** 强制使用算法计算T544，而不使用qsign(算法为8.9.50的0C05，混用版本可能导致风控) */
     force_algo_T544?: boolean,
 
-    /** 使用NT上线包，部分消息暂未支持 */
+    /** 使用 NT 上线包，部分消息暂未支持 */
     useNT?: boolean,
 
+    /** 使用 NT 协议上传图片，默认 false，运行时修改从下一次上传生效 */
+    useNTImage?: boolean,
+
     /** 强制使用旧版WT登录，即使当前APK支持NT登录 */
     forceWt?: boolean,
 
@@ -220,7 +223,7 @@ export interface MemberInfo extends MemberBaseInfo {
 export type MessageElem = TextElem | AtElem | FaceElem | BfaceElem | MfaceElem |
     ImgPttElem | LocationElem | MusicElem | ShareElem | JsonElem | XmlElem |
     AnonymousElem | ReplyElem | NodeElem | ShakeElem | PokeElem | FileElem | VideoElem |
-    MiraiElem | RawElem | MarkdownElem | ButtonElem;
+    MiraiElem | RawElem | MarkdownElem | ButtonElem | FlashTransferElem;
 
 export type Sendable = string | MessageElem | Iterable<MessageElem | string>
 
@@ -257,9 +260,10 @@ export interface BfaceElem {
     type: "bface",
     data: {
         file: string,
-        text: string
+        text: string,
         width?: number,
         height?: number,
+        type?: "png" | "gif",
     }
 }
 
@@ -293,6 +297,7 @@ export interface ImgPttElem {
         headers?: OutgoingHttpHeaders, //file为网络资源时请求头
         url?: string, //仅接收
         type?: "image" | "flash" | "face",
+        brief?: string, //传统语音预览文案
     }
 }
 
@@ -415,6 +420,23 @@ export interface MarkdownElem {
     }
 }
 
+/** 收到的 QQ 闪传卡片；发送请使用 sendFlashTransferMsg 或 FlashTransfer.send。 */
+export interface FlashTransferElem {
+    type: "qfile";
+    data: {
+        fileset_id: string;
+        name?: string;
+        file_size?: number | string;
+        expire_time?: number | string;
+        summary?: string;
+        thumbnail?: {
+            fileid: string;
+            url: string;
+            urls: { type: number; url: string }[];
+        };
+    };
+}
+
 /** Markdown按钮消息 */
 export interface ButtonElem {
     type: "button",
@@ -895,6 +917,165 @@ export class Gfs {
     download(fid: string): Promise<FileElem["data"]>;
 }
 
+////////// QQ flash transfer
+
+export interface FlashTransferOptions {
+    /** 单次 HTTP 请求超时，单位毫秒，默认 30000 */
+    timeout?: number;
+}
+
+export interface FlashTransferCreateOptions {
+    /** 有效期，单位秒，默认 7 天；服务端仍可能受账号配额限制 */
+    duration?: number;
+    /** 计划上传的普通文件总数，默认 1；upload 会按实际文件自动填写 */
+    total_file_count?: number;
+    /** 计划上传的总字节数，默认 0；upload 会自动填写 */
+    total_file_size?: number;
+    /** 顶层文件及目录的数量，默认与文件总数相同；upload 会自动填写 */
+    first_level_item_count?: number;
+}
+
+export interface FlashTransferTask {
+    fileset_id: string;
+    task_id: string;
+    share_link: string;
+    expire_time: number;
+    expire_left_time: number;
+}
+
+export interface FlashTransferMetadata {
+    cli_fileid: string;
+    name: string;
+    file_size: number | string;
+    parent_id?: string;
+    is_dir?: boolean;
+    cli_file_index?: number;
+    depth?: number;
+    file_type?: number;
+    /** 普通文件必需，十六进制摘要；目录无需填写 */
+    md5?: string;
+    sha1?: string;
+    is_cover?: boolean;
+    /** 目录直属子项数，普通文件为 0 */
+    file_count?: number;
+}
+
+export type FlashTransferUploadInput = MediaFile | { file: MediaFile; name?: string };
+
+export interface FlashTransferUploadSource {
+    name: string;
+    size: number;
+    md5: Buffer | string;
+    sha1: Buffer | string;
+}
+
+/** 由 applyUpload 返回，保留服务端的 IndexNode、存储参数和业务透传信息。 */
+export interface FlashTransferUploadTicket {
+    upload: Record<number, any>;
+    info: Record<number, any>;
+    ukey: string;
+    app_type: number;
+    /** sliceupload 使用的存储 appid */
+    appid: number;
+    biz_trans_info: Buffer;
+    storage_type: number;
+    storage_info: Buffer;
+}
+
+export interface FlashTransferUploadResult extends FlashTransferTask {
+    files: FlashTransferFile[];
+}
+
+export interface FlashTransferMessageTarget {
+    type: "private" | "group";
+    /** 私聊接受 QQ 号（需已有 UID 缓存）或 u_ 开头的 UID；群聊接受群号 */
+    target: number | string;
+}
+
+export interface FlashTransferMessageStatus {
+    /** 服务端返回的目标：私聊为 UID，群号保留十进制字符串 */
+    target: FlashTransferMessageTarget;
+    result: number;
+    message: string;
+}
+
+export interface FlashTransferFile {
+    name: string;
+    file_size: number | string;
+    srv_fileid: string;
+    cli_fileid: string;
+    sha1?: string;
+    physical: {
+        id: string;
+        [key: string]: any;
+    };
+    [key: string]: any;
+}
+
+export interface FlashTransferPage {
+    file_list: FlashTransferFile[];
+    is_end: boolean;
+    pagination_info: string;
+    [key: string]: any;
+}
+
+export interface FlashTransferDownload {
+    url: string;
+    [key: string]: any;
+}
+
+/** 与 Gfs 一样，以下方法会 reject；控制接口保留官网的 snake_case 字段。 */
+export class FlashTransfer {
+    private constructor();
+    /** 分享码或 https://qfile.qq.com/q/... 链接转换为文件集 ID */
+    resolve(code: string): Promise<string>;
+    /** 原生创建文件集，需要在线客户端；保留 task_id 用于完成提交 */
+    create(name: string, options?: FlashTransferCreateOptions): Promise<FlashTransferTask>;
+    /** 完整上传文件、目录或二进制数据，需要在线客户端；进度参数为数据传输百分比 */
+    upload(files: FlashTransferUploadInput | FlashTransferUploadInput[], name?: string, callback?: (percentage: string) => void, options?: FlashTransferCreateOptions): Promise<FlashTransferUploadResult>;
+    /** 分批登记目录及已计算摘要的文件，返回顺序与请求一致 */
+    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>;
+    /** 分片上传或秒传成功后同步单个文件，随后才能提交整个任务 */
+    completeFile(ticket: FlashTransferUploadTicket): Promise<void>;
+    /** 文件级完成同步之后提交整个任务，参数是 task_id */
+    submit(task_id: string): Promise<void>;
+    /** 由服务端生成并发送原生闪传卡片；任一目标失败则 reject，Error.send_status 保留全部结果 */
+    send(fileset_id: string, targets: FlashTransferMessageTarget | FlashTransferMessageTarget[]): Promise<FlashTransferMessageStatus[]>;
+    /** 查询文件集信息 */
+    stat(fileset_id: string): Promise<Record<string, any>>;
+    /** 查询目录的一页文件；pagination_info 使用服务端游标，count 为 1–100 */
+    dir(fileset_id: string, parent_id?: string, pagination_info?: string, count?: number): Promise<FlashTransferPage>;
+    /** 按服务端游标逐页遍历当前目录 */
+    files(fileset_id: string, parent_id?: string): AsyncGenerator<FlashTransferFile>;
+    /** 查询多个文件集的传输进度 */
+    progress(fileset_ids: string[]): Promise<Record<string, any>>;
+    /** 按 srv_fileid 查询文件集内指定文件的传输进度 */
+    fileProgress(fileset_id: string, srv_fileids: string[]): Promise<Record<string, any>>;
+    /** 查询指定目录的文件分类信息 */
+    category(fileset_id: string, parent_id?: string): Promise<Record<string, any>>;
+    /** 设置用户完成官方验证码后取得的 ticket 和 randstr，供下载请求使用 */
+    setCaptcha(ticket: string, randstr: string): void;
+    /** 参数可以是文件元数据，或 physical.id（不是 srv_fileid） */
+    getDownloadUrl(file: FlashTransferFile | string): Promise<FlashTransferDownload>;
+    /** 批量获取下载信息，每批最多 30 个文件，返回顺序与输入一致 */
+    getDownloadUrls(files: (FlashTransferFile | string)[]): Promise<FlashTransferDownload[]>;
+    /** 下载到指定路径，验证大小和可用的 SHA1，不覆盖已有文件 */
+    download(file: FlashTransferFile | string, target: string, callback?: (percentage: string) => void): Promise<{
+        path: string;
+        size: number;
+        sha1: string;
+    }>;
+    /** 底层 sliceupload 数据面；自动申请凭证并提交整个任务请使用 upload */
+    uploadFile(file: MediaFile, ukey: string, appid: number, name?: string, callback?: (percentage: string) => void): Promise<{
+        name: string;
+        size: number;
+        md5: string;
+        sha1: string;
+    }>;
+}
+
 //////////
 
 export type Domain = "tenpay.com"
@@ -911,6 +1092,7 @@ export type Domain = "tenpay.com"
     | "openmobile.qq.com"
     | "qun.qq.com"
     | "ti.qq.com"
+    | "weiyun.com"
     | "";
 
 export interface Sig {
@@ -1060,6 +1242,290 @@ export interface EventMap {
     "internal.input": (this: Client, data: { user_id: number, end: boolean }) => void;
 }
 
+////////// QQ favorites
+
+/** 收藏中的 uint64：安全整数返回 number，超出安全范围返回十进制字符串。 */
+export type FavoriteInteger = number | string;
+
+export interface FavoriteCollection {
+    cid: string;
+    type?: number;
+    status?: number;
+    author?: FavoriteAuthor;
+    bid?: number;
+    src_app_id?: number;
+    src_app_ver?: string;
+    category?: number;
+    create_time?: FavoriteInteger;
+    collect_time?: FavoriteInteger;
+    modify_time?: FavoriteInteger;
+    sequence?: FavoriteInteger;
+    biz_key?: string;
+    biz_data_list: string[]; /** Base64 编码的原始字节。 */
+    summary?: FavoriteCollectionSummary;
+    star_mark?: boolean;
+    star_time?: FavoriteInteger;
+    share_url?: string;
+    original_app_id?: number;
+    custom_group_id?: number;
+    security_beat?: number;
+    qzone_ugc_key?: string;
+}
+
+export interface FavoriteAuthor {
+    type?: number;
+    num_id?: FavoriteInteger;
+    str_id?: string;
+    group_id?: FavoriteInteger;
+    group_name?: string;
+}
+
+export interface FavoriteCollectionSummary {
+    text_summary?: FavoriteTextSummary;
+    link_summary?: FavoriteLinkSummary;
+    gallery_summary?: FavoriteGallerySummary;
+    audio_summary?: FavoriteAudioSummary;
+    video_summary?: FavoriteVideoSummary;
+    file_summary?: FavoriteFileSummary;
+    location_summary?: FavoriteLocationSummary;
+    rich_media_summary?: FavoriteRichMediaSummary;
+}
+
+export interface FavoriteTextSummary {
+    brief?: string;
+    has_emoji?: boolean;
+}
+
+export interface FavoriteLinkSummary {
+    uri?: string;
+    title?: string;
+    publisher?: string;
+    brief?: string;
+    pic_list: FavoritePicInfo[];
+    type?: number;
+    resource_uri?: string;
+}
+
+export interface FavoritePicInfo {
+    uri?: string;
+    md5?: string; /** Base64 编码的原始字节。 */
+    sha1?: string; /** Base64 编码的原始字节。 */
+    name?: string;
+    note?: string;
+    width?: number;
+    height?: number;
+    size?: number;
+    type?: number;
+    owner?: FavoriteAuthor;
+    pic_id?: string;
+}
+
+export interface FavoriteGallerySummary {
+    pic_list: FavoritePicInfo[];
+    notes?: string;
+}
+
+export interface FavoriteAudioSummary {
+    duration?: number;
+    stt?: string;
+    note?: string;
+}
+
+export interface FavoriteVideoSummary {
+    title?: string;
+    duration?: number;
+    format?: number;
+    category?: number;
+    preview_type?: number;
+    preview_pic_info?: FavoritePicInfo;
+    store_type?: number;
+    store_file_info?: FavoriteFileInfo;
+}
+
+export interface FavoriteFileInfo {
+    src?: number;
+    uid?: FavoriteInteger;
+    bid?: number;
+    fid?: string;
+    name?: string;
+    size?: FavoriteInteger;
+    md5?: string; /** Base64 编码的原始字节。 */
+    sha1?: string; /** Base64 编码的原始字节。 */
+    category?: number;
+}
+
+export interface FavoriteFileSummary {
+    file_info?: FavoriteFileInfo;
+    src_file_info?: FavoriteFileInfo;
+}
+
+export interface FavoriteLocationSummary {
+    name?: string;
+    latitude?: number;
+    longitude?: number;
+    altitude?: number;
+    address?: string;
+    note?: string;
+}
+
+export interface FavoriteRichMediaSummary {
+    title?: string;
+    sub_title?: string;
+    brief?: string;
+    pic_list: FavoritePicInfo[];
+    content_type?: number;
+    original_uri?: string;
+    publisher?: string;
+    rich_media_version?: number;
+}
+
+export interface FavoriteCollectionContent {
+    text_content?: FavoriteTextContent;
+    link_content?: FavoriteLinkContent;
+    gallery_content?: FavoriteGalleryContent;
+    audio_content?: FavoriteAudioContent;
+    video_content?: FavoriteVideoContent;
+    file_content?: FavoriteFileContent;
+    location_content?: FavoriteLocationContent;
+    rich_media_content?: FavoriteRichMediaContent;
+}
+
+export interface FavoriteTextContent {
+    data?: string;
+    has_emoji?: boolean;
+}
+
+export interface FavoriteLinkContent {
+}
+
+export interface FavoriteGalleryContent {
+}
+
+export interface FavoriteAudioContent {
+    data?: string; /** Base64 编码的原始字节。 */
+}
+
+export interface FavoriteVideoContent {
+}
+
+export interface FavoriteFileContent {
+}
+
+export interface FavoriteLocationContent {
+}
+
+export interface FavoriteRichMediaContent {
+    rich_media?: FavoriteRichMedia;
+    raw_data?: string; /** Base64 编码的原始字节。 */
+    biz_data_list: string[]; /** Base64 编码的原始字节。 */
+    pic_list: FavoritePicInfo[];
+    file_list: FavoriteFileInfo[];
+}
+
+export interface FavoriteRichMedia {
+    sections: FavoriteSection[];
+}
+
+export interface FavoriteSection {
+    items: FavoriteItem[];
+}
+
+export interface FavoriteItem {
+    item_type?: number;
+    parag?: FavoriteParagraph;
+    anchor?: FavoriteAnchor;
+    pic_info?: FavoritePicInfo;
+}
+
+export interface FavoriteParagraph {
+    content?: string;
+    style?: FavoriteStyle;
+}
+
+export interface FavoriteStyle {
+    color?: string;
+    font_family?: string;
+    font_weight?: string;
+    font_size?: string;
+}
+
+export interface FavoriteAnchor {
+    url?: string;
+    desc?: string;
+}
+
+export interface FavoriteCollectionFullInfo {
+    collection: FavoriteCollection;
+    content?: FavoriteCollectionContent;
+    /** 富文本 content_type 为 1/2 时，解压后的 HTML。 */
+    html?: string;
+}
+
+export interface FavoriteGetCollectionListMsgRsp {
+    collection_list: FavoriteCollection[];
+    total_count?: number;
+    result?: number;
+}
+
+export interface FavoriteGetCollectionFullInfoMsgRsp {
+    collection_full_info_list: FavoriteCollectionFullInfo[];
+}
+
+export interface FavoriteCustomGroupInfo {
+    custom_group_id?: number;
+    name?: string;
+    create_time?: number;
+    modify_time?: number;
+    total_count?: number;
+}
+
+export interface FavoriteGetCustomGroupMsgRsp {
+    modi_groupid_time?: number;
+    total_count?: number;
+    modi_group_time?: number;
+    customgroupinfo_list: FavoriteCustomGroupInfo[];
+    max_group_count?: number;
+}
+
+export interface FavoriteGetCollectorUserInfoRsp {
+    toatal_space?: FavoriteInteger;
+    used_space?: FavoriteInteger;
+}
+
+export interface FavoriteListOptions {
+    type?: number;
+    bid?: number;
+    category?: number;
+    /** 毫秒时间戳。 */
+    start_time?: number;
+    start_pos?: number;
+    /** 1~100，默认 20。 */
+    page_size?: number;
+    order_type?: 0 | 1;
+    sync_policy?: number;
+}
+export type FavoriteInput = ({ type?: "text"; text: string } |
+    { type: "link"; url: string; title?: string; publisher?: string; brief?: string } |
+    { type: "rich"; html: string; title?: string; brief?: string }) & {
+    bid?: number; category?: number; custom_group_id?: number;
+};
+export interface FavoriteChanges {
+    text?: string;
+    html?: string;
+    url?: string;
+    title?: string;
+    publisher?: string;
+    brief?: string;
+    category?: number;
+    custom_group_id?: number;
+    star_mark?: boolean;
+}
+export interface FavoriteItemResults {
+    /** 批量请求可能部分失败，必须检查 success 和每项 result。 */
+    success: boolean;
+    results: { id: string | number; result: number }[];
+}
+
 /**
  * 方法不会reject或抛出异常，使用retcode判断是否成功
  * @see {Ret}
@@ -1141,6 +1607,15 @@ export class Client extends EventEmitter {
     /** 私聊 */
     sendPrivateMsg(user_id: number, message: Sendable, auto_escape?: boolean): Promise<Ret<{ message_id: string }>>;
     sendFile(user_id: number, file: MediaFile, name?: string, process?: (percentage: string) => void): Promise<Ret<{ message_id: string }>>;
+    /** 发送原生闪传卡片；group=true 为群聊，返回逐目标状态，不提供 message_id */
+    sendFlashTransferMsg(recv_id: number | string, fileset_id: string, group?: boolean): Promise<Ret<{
+        fileset_id: string;
+        send_status: FlashTransferMessageStatus[];
+    }>>;
+    /** 上传单个文件或数组到同一文件集并发送闪传卡片；name为单文件名或批量文件集名称，group=true为群聊，不提供message_id */
+    sendFlashTransferFile(recv_id: number | string, file: MediaFile | MediaFile[], group?: boolean, name?: string, process?: (percentage: string) => void): Promise<Ret<FlashTransferUploadResult & {
+        send_status: FlashTransferMessageStatus[];
+    }>>;
     /** 群聊 */
     sendGroupMsg(group_id: number, message: Sendable, auto_escape?: boolean): Promise<Ret<{ message_id: string }>>;
     /** 群临时会话，大多数时候可以使用私聊达到同样效果 */
@@ -1288,6 +1763,88 @@ export class Client extends EventEmitter {
     /** 进入群文件系统 */
     acquireGfs(group_id: number): Gfs;
 
+    //----------QQ 收藏----------
+    /**
+     * 获取一页 QQ 收藏摘要，需要登录票据包含 weiyun.com 的 p_skey。
+     * @param options 筛选条件及分页参数；默认每页 20 条，时间使用毫秒。
+     * @returns 当前页收藏列表、总数及同步状态；result=215000 表示部分同步。
+     */
+    getFavoriteList(options?: FavoriteListOptions): Promise<Ret<FavoriteGetCollectionListMsgRsp>>;
+
+    /**
+     * 获取指定收藏的完整元数据和正文。
+     * @param cid 收藏 ID。
+     * @returns 收藏信息和正文；富文本 content_type 为 1/2 时额外返回解码后的 html。
+     */
+    getFavorite(cid: string): Promise<Ret<FavoriteCollectionFullInfo>>;
+
+    /**
+     * 增加文本、链接或 HTML 收藏。
+     * @param favorite 收藏内容；字符串按纯文本处理，对象可指定类型及所属分组。
+     * @returns 新收藏的 cid 与 collect_time。
+     */
+    addFavorite(favorite: FavoriteInput | string): Promise<Ret<{ cid: string; collect_time: FavoriteInteger }>>;
+
+    /**
+     * 编辑收藏，先读取详情再合并指定字段，保留其余元数据和资源。
+     * @param cid 收藏 ID。
+     * @param changes 需要修改的字段；type=1 支持文本正文，type=6 支持链接字段，type=8 支持 HTML。
+     * @returns 收藏 ID 与修改时间；其他类型支持元数据编辑。
+     */
+    editFavorite(cid: string, changes: FavoriteChanges): Promise<Ret<{ cid: string; modify_time: FavoriteInteger }>>;
+
+    /**
+     * 删除收藏，单次支持 1~10 项。
+     * @param cid 单个收藏 ID 或收藏 ID 列表。
+     * @returns 整体 success 与逐项 result；协议请求成功时仍可能存在部分失败。
+     */
+    deleteFavorite(cid: string | string[]): Promise<Ret<FavoriteItemResults>>;
+
+    /**
+     * 获取收藏分组及分组同步信息。
+     * @returns 分组列表、数量、同步时间及分组数量上限。
+     */
+    getFavoriteGroups(): Promise<Ret<FavoriteGetCustomGroupMsgRsp>>;
+
+    /**
+     * 增加收藏分组。
+     * @param name 非空分组名称。
+     * @returns 新分组 ID 与创建时间。
+     */
+    addFavoriteGroup(name: string): Promise<Ret<{ custom_group_id: number; create_time: number }>>;
+
+    /**
+     * 修改收藏分组名称。
+     * @param custom_group_id 分组 ID。
+     * @param name 新的非空分组名称。
+     * @returns 分组修改时间。
+     */
+    editFavoriteGroup(custom_group_id: number, name: string): Promise<Ret<{ modify_time: number }>>;
+
+    /**
+     * 删除收藏分组，单次支持 1~10 项。
+     * @param custom_group_id 单个分组 ID 或分组 ID 列表。
+     * @returns 删除时间、整体 success 与逐项 result；需检查部分失败。
+     */
+    deleteFavoriteGroup(custom_group_id: number | number[]): Promise<Ret<FavoriteItemResults & { del_time?: number }>>;
+
+    /**
+     * 设置收藏的所属分组，单次支持 1~10 条收藏。
+     * @param cid 单个收藏 ID 或收藏 ID 列表。
+     * @param custom_group_id 目标分组 ID。
+     * @returns 整体 success 与逐项 result；需检查部分失败。
+     */
+    setFavoriteGroup(cid: string | string[], custom_group_id: number): Promise<Ret<FavoriteItemResults>>;
+
+    /**
+     * 获取收藏空间使用情况。
+     * @returns 空间总量 total_space 与已用量 used_space，单位为字节。
+     */
+    getFavoriteSpace(): Promise<Ret<{ total_space: FavoriteInteger; used_space: FavoriteInteger }>>;
+
+    /** 进入 QQ 闪传协议接口 */
+    acquireFlashTransfer(options?: FlashTransferOptions): FlashTransfer;
+
     on<T extends keyof EventMap>(event: T, listener: EventMap[T]): this;
     on<S extends string | symbol>(event: S & Exclude<S, keyof EventMap>, listener: (this: Client, ...args: any[]) => void): this;