@alemonjs/qq-bot 2.1.31 → 2.1.33

package/lib/sdk/api.d.ts

@@ -1,9 +1,51 @@
 import { type AxiosRequestConfig } from 'axios';
-import { ApiRequestData, FileType } from './typing.js';
-export declare const BOTS_API_RUL = "https://bots.qq.com";
+import { ApiRequestData, FileType, GroupAction, SetMemberMuteState, StreamMessageData, UploadPartFinishData, UploadPrepareData } from './typing.js';
+import { QQBotConfig } from './config.js';
+export declare const BOTS_API_RUL = "https://api.bot.qq.com";
 export declare const API_URL_SANDBOX = "https://sandbox.api.sgroup.qq.com";
-export declare const API_URL = "https://api.sgroup.qq.com";
+export declare const API_URL = "https://api.bot.qq.com";
+export type QQBotConnectionState = 'idle' | 'connecting' | 'ready' | 'reconnecting' | 'offline' | 'stopped';
+export type QQBotConnectionStatus = {
+    state: QQBotConnectionState;
+    transport: 'websocket' | 'webhook' | 'proxy' | null;
+    reconnectAttempts: number;
+    heartbeatAcknowledged: boolean;
+    sessionId?: string;
+    sequence?: number;
+    resumed: boolean;
+    lastError?: string;
+};
+export type QQBotMediaHashes = {
+    sha256: string;
+    md5: string;
+    sha1: string;
+    md5_10m: string;
+};
 export declare class QQBotAPI {
+    #private;
+    protected readonly config: QQBotConfig;
+    constructor(options?: Record<string, unknown>);
+    getConnectionStatus(): QQBotConnectionStatus;
+    protected updateConnectionStatus(patch: Partial<QQBotConnectionStatus>): void;
+    setStreamLifecycleListener(listener?: (streamId: string) => void): void;
+    sendTyping(params: {
+        BotId?: string;
+        userOpenId: string;
+        msgId?: string;
+        durationSec?: number;
+    }): Promise<any>;
+    streamOpen(params: {
+        BotId?: string;
+        userOpenId: string;
+        msgId: string;
+        eventId?: string;
+    }): {
+        streamId: `${string}-${string}-${string}-${string}-${string}`;
+    };
+    streamUpdate(streamId: string, fullText: string): Promise<unknown>;
+    streamComplete(streamId: string): Promise<any>;
+    streamCancel(streamId: string): void;
+    protected cancelStreams(): void;
     getAuthentication(): Promise<any>;
     groupService(options: AxiosRequestConfig): Promise<any>;
     guildServer(options: AxiosRequestConfig): Promise<any>;
@@ -22,23 +64,94 @@ export declare class QQBotAPI {
         file_type: FileType;
         url?: string;
         file_data?: any;
+        upload_id?: string;
+        file_name?: string;
     }): Promise<{
         file_uuid: string;
         file_info: string;
         ttl: number;
+        id?: string;
+        raw_url?: string;
     }>;
     postRichMediaByGroup(openid: string, data: {
         srv_send_msg?: boolean;
         file_type: FileType;
         url?: string;
         file_data?: any;
+        upload_id?: string;
+        file_name?: string;
+    }): Promise<{
+        file_uuid: string;
+        file_info: string;
+        ttl: number;
+        id?: string;
+        raw_url?: string;
+    }>;
+    getMediaFileHashes(filePath: string): Promise<QQBotMediaHashes>;
+    postChunkedRichMedia(params: {
+        scope: 'group' | 'c2c';
+        targetId: string;
+        fileType: FileType;
+        data?: Buffer;
+        filePath?: string;
+        size?: number;
+        hashes?: QQBotMediaHashes;
+        name?: string;
+        onProgress?: (uploaded: number, total: number) => void;
     }): Promise<{
         file_uuid: string;
         file_info: string;
         ttl: number;
     }>;
     userMessageDelete(openid: string, message_id: string): Promise<any>;
+    groupMessageDelete(group_openid: string, message_id: string): Promise<any>;
     grouMessageDelte(group_openid: string, message_id: string): Promise<any>;
+    groupsInfo(group_openid: string): Promise<any>;
+    groupsBotState(group_openid: string): Promise<any>;
+    groupsMembersMessage(group_openid: string, member_openid: string): Promise<any>;
+    groupsJoinRequestList(group_openid: string, params?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<any>;
+    groupsApprovalJoinRequest(group_openid: string, member_openid: string, data: {
+        op: 'approve' | 'decline';
+        join_request_id?: string;
+        reject_reason?: string;
+        add_to_member_blacklist?: boolean;
+    }): Promise<any>;
+    groupsRestrictChatSetting(group_openid: string): Promise<any>;
+    groupsRestrictChatSettingPost(group_openid: string, data: {
+        members?: SetMemberMuteState[];
+    }): Promise<any>;
+    groupsJoinApprovalStrategies(params?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<any>;
+    groupsJoinApprovalStrategyCreate(data: {
+        group_openids?: string[];
+        group_ids?: string[];
+        is_enable?: 'on' | 'off';
+        expire_at?: string;
+        remark?: string;
+    }): Promise<any>;
+    groupsJoinApprovalStrategyPatch(strategy_id: string, data: {
+        is_enable?: 'on' | 'off';
+        expire_at?: string;
+        group_action?: GroupAction;
+        remark?: string;
+    }): Promise<any>;
+    groupsJoinApprovalStrategyDelete(strategy_id: string): Promise<any>;
+    groupsJoinApprovalStrategyExecute(strategy_id: string): Promise<any>;
+    groupsJoinApprovalStrategyWhitelistUsers(strategy_id: string, data: {
+        op: 'add' | 'del';
+        whitelist_users: string[];
+    }): Promise<any>;
+    usersUploadPrepare(userId: string, data: UploadPrepareData): Promise<any>;
+    groupUploadPrepare(groupId: string, data: UploadPrepareData): Promise<any>;
+    usersUploadPartFinish(userId: string, data: UploadPartFinishData): Promise<any>;
+    groupUploadPartFinish(groupId: string, data: UploadPartFinishData): Promise<any>;
+    uploadPartDirect(presignedUrl: string, part: Buffer): Promise<import("axios").AxiosResponse<any, any, {}>>;
+    streamMessages(userId: string, data: StreamMessageData): Promise<any>;
     channelsMessages(channel_id: string, message: {
         content?: string;
         embed?: any;

package/lib/sdk/api.js

@@ -1,18 +1,154 @@
 import axios from 'axios';
-import { config } from './config.js';
+import { QQBotConfig } from './config.js';
 import FormData from 'form-data';
 import { createPicFrom } from 'alemonjs/utils';
 import { createAxiosInstance } from './instance.js';
+import { randomUUID, createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { fileDataToBuffer, CHUNK_THRESHOLD, chunkedUpload } from '../upload.js';
 
-const BOTS_API_RUL = 'https://bots.qq.com';
+const BOTS_API_RUL = 'https://api.bot.qq.com';
 const API_URL_SANDBOX = 'https://sandbox.api.sgroup.qq.com';
-const API_URL = 'https://api.sgroup.qq.com';
-const msgMap = new Map();
+const API_URL = 'https://api.bot.qq.com';
 class QQBotAPI {
+    config;
+    #msgMap = new Map();
+    #streams = new Map();
+    #onStreamClosed;
+    #connectionStatus = {
+        state: 'idle',
+        transport: null,
+        reconnectAttempts: 0,
+        heartbeatAcknowledged: false,
+        resumed: false
+    };
+    constructor(options = {}) {
+        this.config = new QQBotConfig(options);
+    }
+    getConnectionStatus() {
+        return { ...this.#connectionStatus };
+    }
+    updateConnectionStatus(patch) {
+        this.#connectionStatus = { ...this.#connectionStatus, ...patch };
+    }
+    setStreamLifecycleListener(listener) {
+        this.#onStreamClosed = listener;
+    }
+    sendTyping(params) {
+        if (!params.userOpenId)
+            throw new Error('userOpenId is required');
+        return this.groupService({
+            url: `/v2/users/${params.userOpenId}/input_notify`,
+            method: 'post',
+            data: {
+                ...(params.msgId && { msg_id: params.msgId }),
+                input_second: Math.max(1, Math.min(Number(params.durationSec) || 30, 60))
+            }
+        });
+    }
+    streamOpen(params) {
+        if (!params.userOpenId || !params.msgId)
+            throw new Error('C2C streaming requires userOpenId and msgId');
+        const streamId = randomUUID();
+        const stream = {
+            userOpenId: params.userOpenId,
+            msgId: params.msgId,
+            eventId: params.eventId || params.msgId,
+            msgSeq: this.getMessageSeq(params.msgId),
+            index: 0,
+            lastSentAt: 0,
+            lastSentText: ''
+        };
+        stream.timer = setTimeout(() => this.streamCancel(streamId), 5 * 60 * 1000);
+        this.#streams.set(streamId, stream);
+        return { streamId };
+    }
+    async streamUpdate(streamId, fullText) {
+        const stream = this.#streams.get(streamId);
+        if (!stream)
+            throw new Error('Unknown or expired streamId');
+        stream.latest = fullText;
+        if (!stream.sendTask) {
+            stream.sendTask = (async () => {
+                let result;
+                while (stream.latest !== undefined && this.#streams.get(streamId) === stream) {
+                    const content = stream.latest;
+                    stream.latest = undefined;
+                    const wait = Math.max(0, 500 - (Date.now() - stream.lastSentAt));
+                    if (wait)
+                        await new Promise(resolve => setTimeout(resolve, wait));
+                    if (this.#streams.get(streamId) !== stream)
+                        break;
+                    stream.lastSentAt = Date.now();
+                    const response = await this.groupService({
+                        url: `/v2/users/${stream.userOpenId}/stream_messages`,
+                        method: 'post',
+                        data: {
+                            msg_id: stream.msgId,
+                            event_id: stream.eventId,
+                            msg_seq: stream.msgSeq,
+                            index: stream.index++,
+                            input_mode: 'replace',
+                            input_state: 1,
+                            content_type: 'markdown',
+                            content_raw: content,
+                            ...(stream.streamMessageId && { stream_msg_id: stream.streamMessageId })
+                        }
+                    });
+                    if (response?.id && !stream.streamMessageId)
+                        stream.streamMessageId = response.id;
+                    stream.lastSentText = content;
+                    result = response;
+                }
+                return result;
+            })().finally(() => {
+                if (this.#streams.get(streamId) === stream)
+                    stream.sendTask = undefined;
+            });
+        }
+        return stream.sendTask;
+    }
+    async streamComplete(streamId) {
+        const stream = this.#streams.get(streamId);
+        if (!stream)
+            throw new Error('Unknown or expired streamId');
+        try {
+            await stream.sendTask;
+            return await this.groupService({
+                url: `/v2/users/${stream.userOpenId}/stream_messages`,
+                method: 'post',
+                data: {
+                    msg_id: stream.msgId,
+                    event_id: stream.eventId,
+                    msg_seq: stream.msgSeq,
+                    index: stream.index++,
+                    input_mode: 'replace',
+                    input_state: 10,
+                    content_type: 'markdown',
+                    content_raw: stream.latest ?? stream.lastSentText,
+                    ...(stream.streamMessageId && { stream_msg_id: stream.streamMessageId })
+                }
+            });
+        }
+        finally {
+            this.streamCancel(streamId);
+        }
+    }
+    streamCancel(streamId) {
+        const stream = this.#streams.get(streamId);
+        if (stream?.timer)
+            clearTimeout(stream.timer);
+        if (this.#streams.delete(streamId))
+            this.#onStreamClosed?.(streamId);
+    }
+    cancelStreams() {
+        for (const streamId of this.#streams.keys())
+            this.streamCancel(streamId);
+    }
     getAuthentication() {
-        const app_id = config.get('app_id');
-        const secret = config.get('secret');
-        const baseUrlAppAccessToken = config.get('base_url_app_access_token');
+        const app_id = this.config.get('app_id');
+        const secret = this.config.get('secret');
+        const baseUrlAppAccessToken = this.config.get('base_url_app_access_token');
         const params = {
             url: '/app/getAppAccessToken'
         };
@@ -33,9 +169,9 @@ class QQBotAPI {
         });
     }
     groupService(options) {
-        const app_id = config.get('app_id');
-        const token = config.get('access_token');
-        const sandbox = config.get('sandbox');
+        const app_id = this.config.get('app_id');
+        const token = this.config.get('access_token');
+        const sandbox = this.config.get('sandbox');
         const service = axios.create({
             baseURL: sandbox ? API_URL_SANDBOX : API_URL,
             timeout: 20000,
@@ -50,7 +186,7 @@ class QQBotAPI {
         return this.groupService(options);
     }
     gateway() {
-        const baseUrlGateway = config.get('base_url_gateway');
+        const baseUrlGateway = this.config.get('base_url_gateway');
         const params = {
             url: '/gateway'
         };
@@ -75,13 +211,13 @@ class QQBotAPI {
         });
     }
     getMessageSeq(MessageId) {
-        let seq = msgMap.get(MessageId) || 0;
+        let seq = this.#msgMap.get(MessageId) || 0;
         seq++;
-        msgMap.set(MessageId, seq);
-        if (msgMap.size > 100) {
-            const firstKey = msgMap.keys().next().value;
+        this.#msgMap.set(MessageId, seq);
+        if (this.#msgMap.size > 100) {
+            const firstKey = this.#msgMap.keys().next().value;
             if (firstKey) {
-                msgMap.delete(firstKey);
+                this.#msgMap.delete(firstKey);
             }
         }
         return seq;
@@ -102,6 +238,10 @@ class QQBotAPI {
         });
     }
     postRichMediaByUser(openid, data) {
+        const fileBuffer = fileDataToBuffer(data.file_data);
+        if (!data.upload_id && fileBuffer && fileBuffer.byteLength > CHUNK_THRESHOLD) {
+            return chunkedUpload(this, 'user', openid, fileBuffer, { file_type: data.file_type, file_name: data.file_name, srv_send_msg: data.srv_send_msg });
+        }
         return this.groupService({
             url: `/v2/users/${openid}/files`,
             method: 'post',
@@ -109,6 +249,10 @@ class QQBotAPI {
         });
     }
     postRichMediaByGroup(openid, data) {
+        const fileBuffer = fileDataToBuffer(data.file_data);
+        if (!data.upload_id && fileBuffer && fileBuffer.byteLength > CHUNK_THRESHOLD) {
+            return chunkedUpload(this, 'group', openid, fileBuffer, { file_type: data.file_type, file_name: data.file_name, srv_send_msg: data.srv_send_msg });
+        }
         return this.groupService({
             url: `/v2/groups/${openid}/files`,
             method: 'post',
@@ -118,18 +262,247 @@ class QQBotAPI {
             }
         });
     }
+    async getMediaFileHashes(filePath) {
+        const sha256 = createHash('sha256');
+        const md5 = createHash('md5');
+        const sha1 = createHash('sha1');
+        const md5_10m = createHash('md5');
+        let firstBytes = 0;
+        const firstLimit = 10_002_432;
+        for await (const chunk of createReadStream(filePath)) {
+            const data = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            sha256.update(data);
+            md5.update(data);
+            sha1.update(data);
+            if (firstBytes < firstLimit) {
+                const length = Math.min(data.length, firstLimit - firstBytes);
+                md5_10m.update(data.subarray(0, length));
+                firstBytes += length;
+            }
+        }
+        return {
+            sha256: sha256.digest('hex'),
+            md5: md5.digest('hex'),
+            sha1: sha1.digest('hex'),
+            md5_10m: md5_10m.digest('hex')
+        };
+    }
+    async postChunkedRichMedia(params) {
+        const hasBuffer = Buffer.isBuffer(params.data);
+        const hasFile = Boolean(params.filePath);
+        if (hasBuffer === hasFile)
+            throw new Error('Chunked media requires exactly one of data or filePath');
+        const total = hasBuffer ? params.data.length : Number(params.size);
+        if (!Number.isSafeInteger(total) || total < 1)
+            throw new Error('Chunked media requires a valid file size');
+        const hashes = params.hashes || (hasBuffer ? this.#getMediaBufferHashes(params.data) : await this.getMediaFileHashes(params.filePath));
+        const prefix = params.scope === 'group' ? `/v2/groups/${params.targetId}` : `/v2/users/${params.targetId}`;
+        const prepared = await this.groupService({
+            url: `${prefix}/upload_prepare`,
+            method: 'post',
+            data: {
+                file_type: params.fileType,
+                file_name: params.name || 'file',
+                file_size: total,
+                md5: hashes.md5,
+                sha1: hashes.sha1,
+                md5_10m: hashes.md5_10m
+            }
+        });
+        let uploaded = 0;
+        for (const part of prepared.parts || []) {
+            const offset = (part.index - 1) * prepared.block_size;
+            const length = Math.min(prepared.block_size, total - offset);
+            if (length <= 0)
+                throw new Error(`QQ returned invalid upload part index: ${part.index}`);
+            const body = hasBuffer ? params.data.subarray(offset, offset + length) : undefined;
+            const partMd5 = body ? createHash('md5').update(body).digest('hex') : await this.#getFilePartHash(params.filePath, offset, length);
+            await this.#retry(() => axios.put(part.presigned_url, body || createReadStream(params.filePath, { start: offset, end: offset + length - 1 }), {
+                timeout: 300_000,
+                maxBodyLength: Infinity,
+                maxContentLength: Infinity,
+                headers: { 'Content-Length': String(length) }
+            }));
+            await this.#retry(() => this.groupService({
+                url: `${prefix}/upload_part_finish`,
+                method: 'post',
+                data: { upload_id: prepared.upload_id, part_index: part.index, block_size: length, md5: partMd5 }
+            }));
+            uploaded += length;
+            params.onProgress?.(uploaded, total);
+        }
+        return this.#retry(() => this.groupService({
+            url: `${prefix}/complete_upload`,
+            method: 'post',
+            data: { upload_id: prepared.upload_id }
+        }));
+    }
+    #getMediaBufferHashes(data) {
+        return {
+            sha256: createHash('sha256').update(data).digest('hex'),
+            md5: createHash('md5').update(data).digest('hex'),
+            sha1: createHash('sha1').update(data).digest('hex'),
+            md5_10m: createHash('md5').update(data.subarray(0, 10_002_432)).digest('hex')
+        };
+    }
+    async #getFilePartHash(filePath, start, length) {
+        const md5 = createHash('md5');
+        for await (const chunk of createReadStream(filePath, { start, end: start + length - 1 }))
+            md5.update(chunk);
+        return md5.digest('hex');
+    }
+    async #retry(operation, attempts = 3) {
+        let lastError;
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt + 1 < attempts)
+                    await new Promise(resolve => setTimeout(resolve, 250 * 2 ** attempt));
+            }
+        }
+        throw lastError;
+    }
     userMessageDelete(openid, message_id) {
         return this.groupService({
             url: `/v2/users/${openid}/messages/${message_id}`,
             method: 'delete'
         });
     }
-    grouMessageDelte(group_openid, message_id) {
+    groupMessageDelete(group_openid, message_id) {
         return this.groupService({
             url: `/v2/groups/${group_openid}/messages/${message_id}`,
             method: 'delete'
         });
     }
+    grouMessageDelte(group_openid, message_id) {
+        return this.groupMessageDelete(group_openid, message_id);
+    }
+    groupsInfo(group_openid) {
+        return this.groupService({
+            url: `/v2/groups/${group_openid}/info`,
+            method: 'get'
+        });
+    }
+    groupsBotState(group_openid) {
+        return this.groupService({
+            url: `/v2/groups/${group_openid}/bot_state`,
+            method: 'get'
+        });
+    }
+    groupsMembersMessage(group_openid, member_openid) {
+        return this.groupService({
+            url: `/v2/groups/${group_openid}/members/${member_openid}`,
+            method: 'get'
+        });
+    }
+    groupsJoinRequestList(group_openid, params) {
+        return this.groupService({
+            url: `/v2/groups/${group_openid}/join_request_list`,
+            method: 'get',
+            params
+        });
+    }
+    groupsApprovalJoinRequest(group_openid, member_openid, data) {
+        return this.groupService({
+            url: `/v2/groups/${group_openid}/approval_join_request/${member_openid}`,
+            method: 'post',
+            data
+        });
+    }
+    groupsRestrictChatSetting(group_openid) {
+        return this.groupService({
+            url: `/v2/groups/${group_openid}/restrict_chat_setting`,
+            method: 'get'
+        });
+    }
+    groupsRestrictChatSettingPost(group_openid, data) {
+        return this.groupService({
+            url: `/v2/groups/${group_openid}/restrict_chat_setting`,
+            method: 'post',
+            data
+        });
+    }
+    groupsJoinApprovalStrategies(params) {
+        return this.groupService({
+            url: '/v2/groups/join_approval_strategy',
+            method: 'get',
+            params
+        });
+    }
+    groupsJoinApprovalStrategyCreate(data) {
+        return this.groupService({
+            url: '/v2/groups/join_approval_strategy',
+            method: 'post',
+            data
+        });
+    }
+    groupsJoinApprovalStrategyPatch(strategy_id, data) {
+        return this.groupService({
+            url: `/v2/groups/join_approval_strategy/${strategy_id}`,
+            method: 'patch',
+            data
+        });
+    }
+    groupsJoinApprovalStrategyDelete(strategy_id) {
+        return this.groupService({
+            url: `/v2/groups/join_approval_strategy/${strategy_id}`,
+            method: 'delete'
+        });
+    }
+    groupsJoinApprovalStrategyExecute(strategy_id) {
+        return this.groupService({
+            url: `/v2/groups/join_approval_strategy/${strategy_id}/execute`,
+            method: 'post'
+        });
+    }
+    groupsJoinApprovalStrategyWhitelistUsers(strategy_id, data) {
+        return this.groupService({
+            url: `/v2/groups/join_approval_strategy/${strategy_id}/whitelist_users`,
+            method: 'post',
+            data
+        });
+    }
+    usersUploadPrepare(userId, data) {
+        return this.groupService({
+            url: `/v2/users/${userId}/upload_prepare`,
+            method: 'post',
+            data
+        });
+    }
+    groupUploadPrepare(groupId, data) {
+        return this.groupService({
+            url: `/v2/groups/${groupId}/upload_prepare`,
+            method: 'post',
+            data
+        });
+    }
+    usersUploadPartFinish(userId, data) {
+        return this.groupService({
+            url: `/v2/users/${userId}/upload_part_finish`,
+            method: 'post',
+            data
+        });
+    }
+    groupUploadPartFinish(groupId, data) {
+        return this.groupService({
+            url: `/v2/groups/${groupId}/upload_part_finish`,
+            method: 'post',
+            data
+        });
+    }
+    uploadPartDirect(presignedUrl, part) {
+        return axios.put(presignedUrl, part);
+    }
+    streamMessages(userId, data) {
+        return this.groupService({
+            url: `/v2/users/${userId}/stream_messages`,
+            method: 'post',
+            data
+        });
+    }
     async channelsMessages(channel_id, message, image) {
         const formdata = new FormData();
         for (const key in message) {