@downcity/plugins 1.0.4

package/bin/chat/channels/qq/QQGatewayClient.js

@@ -0,0 +1,381 @@
+/**
+ * QQGatewayClient：QQ 网关连接与发送客户端。
+ *
+ * 关键点（中文）
+ * - 这里专门负责 QQ Gateway WebSocket、心跳、自愈重连与状态持有。
+ * - 鉴权 / HTTP 探活 / 发送重试已经拆到旁路模块，当前文件只保留运行时编排。
+ * - QQBot 不再直接维护底层 ws / token 细节，只保留渠道编排职责。
+ */
+import WebSocket from "ws";
+import { fetchQqAccessToken, fetchQqGatewayUrl, testQqGatewayConnection, } from "./QQGatewayAuth.js";
+import { buildQqGatewayRuntimeStatus, resolveQqGatewayApiBase, resolveQqGatewayWsUrl, } from "./QQGatewaySupport.js";
+import { sendQqMessageWithRetry } from "./QQGatewaySend.js";
+import { connectQqGatewayWebSocket } from "./QQGatewayConnection.js";
+import { handleQqGatewayPayload, sendQqGatewayIdentify, } from "./QQGatewayProtocol.js";
+import { normalizeQqHeartbeatIntervalMs, sendQqGatewayHeartbeat, } from "./QQGatewayHeartbeat.js";
+/**
+ * QQ 网关客户端。
+ */
+export class QQGatewayClient {
+    rootPath;
+    logger;
+    appId;
+    appSecret;
+    useSandbox;
+    captureConfig;
+    onDispatch;
+    ws = null;
+    isRunning = false;
+    heartbeatInterval = null;
+    reconnectTimer = null;
+    wsContextId = "";
+    lastSeq = 0;
+    reconnectAttempts = 0;
+    maxReconnectAttempts = 5;
+    heartbeatIntervalMs = 30000;
+    lastHeartbeatSentAtMs = 0;
+    lastHeartbeatAckAtMs = 0;
+    pendingHeartbeatSinceMs = 0;
+    wsReadyAtMs = 0;
+    sendRequestTimeoutMs = 15000;
+    sendMaxAttempts = 3;
+    accessToken = "";
+    accessTokenExpires = 0;
+    AUTH_API_BASE = "https://bots.qq.com";
+    constructor(options) {
+        this.rootPath = options.rootPath;
+        this.logger = options.logger;
+        this.appId = options.appId;
+        this.appSecret = options.appSecret;
+        this.useSandbox = options.useSandbox;
+        this.captureConfig = options.captureConfig;
+        this.onDispatch = options.onDispatch;
+    }
+    /**
+     * 获取当前鉴权字符串。
+     */
+    async getAuthToken() {
+        const result = await fetchQqAccessToken({
+            logger: this.logger,
+            authApiBase: this.AUTH_API_BASE,
+            appId: this.appId,
+            appSecret: this.appSecret,
+            cachedAccessToken: this.accessToken,
+            cachedAccessTokenExpiresAtMs: this.accessTokenExpires,
+        });
+        this.accessToken = result.accessToken;
+        this.accessTokenExpires = result.accessTokenExpiresAtMs;
+        return `QQBot ${result.accessToken}`;
+    }
+    /**
+     * 获取网关状态快照。
+     */
+    getExecutorStatus() {
+        const readyState = typeof this.ws?.readyState === "number" ? this.ws.readyState : null;
+        return buildQqGatewayRuntimeStatus({
+            isRunning: this.isRunning,
+            wsReadyState: readyState,
+            wsContextId: this.wsContextId,
+            wsReadyAtMs: this.wsReadyAtMs,
+            heartbeatIntervalMs: this.heartbeatIntervalMs,
+            lastHeartbeatSentAtMs: this.lastHeartbeatSentAtMs,
+            lastHeartbeatAckAtMs: this.lastHeartbeatAckAtMs,
+            pendingHeartbeatSinceMs: this.pendingHeartbeatSinceMs,
+            reconnectAttempts: this.reconnectAttempts,
+            maxReconnectAttempts: this.maxReconnectAttempts,
+            reconnectScheduled: Boolean(this.reconnectTimer),
+            useSandbox: this.useSandbox,
+            appId: this.appId,
+        });
+    }
+    /**
+     * 执行 QQ 连通性测试。
+     */
+    async testConnection() {
+        return testQqGatewayConnection({
+            appId: this.appId,
+            appSecret: this.appSecret,
+            useSandbox: this.useSandbox,
+            apiBase: this.getApiBase(),
+            getAuthToken: () => this.getAuthToken(),
+            getExecutorStatus: () => this.getExecutorStatus(),
+            requestReconnect: (reason, delayMs) => {
+                this.requestReconnect(reason, delayMs);
+            },
+        });
+    }
+    /**
+     * 启动 QQ 网关。
+     */
+    async start() {
+        if (this.isRunning) {
+            this.logger.warn("QQ Gateway 已在运行中，跳过重复启动");
+            return;
+        }
+        this.isRunning = true;
+        this.reconnectAttempts = 0;
+        this.clearReconnectTimer();
+        this.resetWsLivenessState();
+        const gatewayUrl = await this.getGatewayUrl();
+        await this.connectWebSocket(gatewayUrl);
+    }
+    /**
+     * 停止 QQ 网关。
+     */
+    async stop() {
+        this.isRunning = false;
+        this.clearReconnectTimer();
+        this.stopHeartbeat();
+        this.resetWsLivenessState();
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+    }
+    /**
+     * 请求一次重连。
+     */
+    requestReconnect(reason, delayMs) {
+        this.scheduleReconnect(reason, delayMs);
+    }
+    /**
+     * 发送 QQ 消息。
+     */
+    async sendMessage(chatId, chatType, messageId, text, msgSeq = 1) {
+        try {
+            await sendQqMessageWithRetry({
+                logger: this.logger,
+                apiBase: this.getApiBase(),
+                chatId,
+                chatType,
+                messageId,
+                text,
+                msgSeq,
+                maxAttempts: this.sendMaxAttempts,
+                requestTimeoutMs: this.sendRequestTimeoutMs,
+                getAuthToken: () => this.getAuthToken(),
+                clearAccessTokenCache: () => this.clearAccessTokenCache(),
+                closeSocketForRecovery: (reason) => this.closeSocketForRecovery(reason),
+                scheduleReconnect: (reason, delayMs) => this.scheduleReconnect(reason, delayMs),
+            });
+        }
+        catch (error) {
+            this.logger.error("发送 QQ 消息失败", { error: String(error) });
+            throw error;
+        }
+    }
+    /**
+     * 获取 API 基础地址。
+     */
+    getApiBase() {
+        return resolveQqGatewayApiBase(this.useSandbox);
+    }
+    /**
+     * 获取默认 WebSocket Gateway。
+     */
+    getWsGateway() {
+        return resolveQqGatewayWsUrl(this.useSandbox);
+    }
+    /**
+     * 获取 Gateway 地址。
+     */
+    async getGatewayUrl() {
+        return fetchQqGatewayUrl({
+            logger: this.logger,
+            apiBase: this.getApiBase(),
+            authToken: await this.getAuthToken(),
+            fallbackWsGateway: this.getWsGateway(),
+        });
+    }
+    /**
+     * 重置网关活性状态。
+     */
+    resetWsLivenessState() {
+        this.wsContextId = "";
+        this.lastSeq = 0;
+        this.wsReadyAtMs = 0;
+        this.lastHeartbeatSentAtMs = 0;
+        this.lastHeartbeatAckAtMs = 0;
+        this.pendingHeartbeatSinceMs = 0;
+    }
+    /**
+     * 清理 token 缓存。
+     */
+    clearAccessTokenCache() {
+        this.accessToken = "";
+        this.accessTokenExpires = 0;
+    }
+    /**
+     * 清理重连定时器。
+     */
+    clearReconnectTimer() {
+        if (!this.reconnectTimer)
+            return;
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+    }
+    /**
+     * 计划一次重连。
+     */
+    scheduleReconnect(reason, delayMs) {
+        if (!this.isRunning)
+            return;
+        if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+            this.logger.error("QQ 重连次数已达上限，停止自动重连", {
+                reason,
+                reconnectAttempts: this.reconnectAttempts,
+                maxReconnectAttempts: this.maxReconnectAttempts,
+            });
+            return;
+        }
+        const delay = typeof delayMs === "number" && Number.isFinite(delayMs)
+            ? Math.max(0, Math.trunc(delayMs))
+            : 5000 * (this.reconnectAttempts + 1);
+        if (this.reconnectTimer) {
+            if (delay > 0)
+                return;
+            this.clearReconnectTimer();
+        }
+        this.reconnectAttempts += 1;
+        const attempt = this.reconnectAttempts;
+        this.logger.info(`QQ 准备重连（原因: ${reason}，第 ${attempt}/${this.maxReconnectAttempts} 次），${delay / 1000} 秒后执行`);
+        this.reconnectTimer = setTimeout(async () => {
+            this.reconnectTimer = null;
+            if (!this.isRunning)
+                return;
+            try {
+                this.clearAccessTokenCache();
+                const newGatewayUrl = await this.getGatewayUrl();
+                await this.connectWebSocket(newGatewayUrl);
+            }
+            catch (error) {
+                this.logger.error("QQ 重连失败", { error: String(error), reason });
+                this.scheduleReconnect("reconnect_failed");
+            }
+        }, delay);
+    }
+    /**
+     * 主动关闭当前 socket，交给 close 回调统一进入重连流程。
+     */
+    closeSocketForRecovery(reason) {
+        const ws = this.ws;
+        if (!ws)
+            return;
+        if (ws.readyState !== WebSocket.OPEN && ws.readyState !== WebSocket.CONNECTING) {
+            return;
+        }
+        this.logger.warn(`触发 QQ 链路自愈关闭: ${reason}`);
+        try {
+            ws.close();
+        }
+        catch (error) {
+            this.logger.debug("关闭 QQ WebSocket 失败（忽略）", {
+                error: String(error),
+                reason,
+            });
+        }
+    }
+    /**
+     * 建立 WebSocket 连接。
+     */
+    async connectWebSocket(gatewayUrl) {
+        await connectQqGatewayWebSocket({
+            gatewayUrl,
+            logger: this.logger,
+            captureConfig: this.captureConfig,
+            getCurrentSocket: () => this.ws,
+            setCurrentSocket: (ws) => {
+                this.ws = ws;
+            },
+            resetLivenessState: () => this.resetWsLivenessState(),
+            stopHeartbeat: () => this.stopHeartbeat(),
+            clearReconnectTimer: () => this.clearReconnectTimer(),
+            resetReconnectAttempts: () => {
+                this.reconnectAttempts = 0;
+            },
+            scheduleReconnect: (reason, delayMs) => this.scheduleReconnect(reason, delayMs),
+            handlePayload: async (payload) => {
+                await handleQqGatewayPayload({
+                    logger: this.logger,
+                    payload,
+                    setLastSeq: (seq) => {
+                        this.lastSeq = seq;
+                    },
+                    startHeartbeat: (intervalMs) => this.startHeartbeat(intervalMs),
+                    sendIdentify: async () => {
+                        await this.sendIdentify();
+                    },
+                    markReady: (contextId) => {
+                        this.wsContextId = contextId;
+                        this.wsReadyAtMs = Date.now();
+                    },
+                    markResumed: () => {
+                        this.wsReadyAtMs = Date.now();
+                    },
+                    markHeartbeatAck: () => {
+                        this.lastHeartbeatAckAtMs = Date.now();
+                        this.pendingHeartbeatSinceMs = 0;
+                    },
+                    clearAccessTokenCache: () => this.clearAccessTokenCache(),
+                    closeSocketForRecovery: (reason) => this.closeSocketForRecovery(reason),
+                    onDispatch: async (dispatch) => {
+                        await this.onDispatch(dispatch);
+                    },
+                });
+            },
+        });
+    }
+    /**
+     * 发送鉴权请求。
+     */
+    async sendIdentify() {
+        await sendQqGatewayIdentify({
+            socket: this.ws,
+            logger: this.logger,
+            getAuthToken: () => this.getAuthToken(),
+        });
+    }
+    /**
+     * 启动心跳。
+     */
+    startHeartbeat(intervalMs) {
+        this.stopHeartbeat();
+        this.heartbeatIntervalMs = normalizeQqHeartbeatIntervalMs(intervalMs);
+        this.pendingHeartbeatSinceMs = 0;
+        this.lastHeartbeatSentAtMs = 0;
+        this.sendHeartbeat();
+        this.heartbeatInterval = setInterval(() => {
+            this.sendHeartbeat();
+        }, this.heartbeatIntervalMs);
+    }
+    /**
+     * 发送单次心跳。
+     */
+    sendHeartbeat() {
+        sendQqGatewayHeartbeat({
+            socket: this.ws,
+            logger: this.logger,
+            lastSeq: this.lastSeq,
+            heartbeatIntervalMs: this.heartbeatIntervalMs,
+            wsReadyAtMs: this.wsReadyAtMs,
+            pendingHeartbeatSinceMs: this.pendingHeartbeatSinceMs,
+            markHeartbeatSent: (nowMs) => {
+                this.lastHeartbeatSentAtMs = nowMs;
+            },
+            markPendingHeartbeat: (nowMs) => {
+                this.pendingHeartbeatSinceMs = nowMs;
+            },
+            closeSocketForRecovery: (reason) => this.closeSocketForRecovery(reason),
+        });
+    }
+    /**
+     * 停止心跳。
+     */
+    stopHeartbeat() {
+        if (!this.heartbeatInterval)
+            return;
+        clearInterval(this.heartbeatInterval);
+        this.heartbeatInterval = null;
+    }
+}
+//# sourceMappingURL=QQGatewayClient.js.map

package/bin/chat/channels/qq/QQGatewayClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QQGatewayClient.js","sourceRoot":"","sources":["../../../../src/chat/channels/qq/QQGatewayClient.ts"],"names":[],"mappings":"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"}

package/bin/chat/channels/qq/QQGatewayConnection.d.ts

@@ -0,0 +1,65 @@
+/**
+ * QQ Gateway WebSocket 连接事件绑定。
+ *
+ * 关键点（中文）
+ * - 只负责创建 WebSocket、绑定 open/message/close/error 事件。
+ * - runtime 状态仍由 `QQGatewayClient` 持有，避免连接 helper 变成第二个状态源。
+ * - message 解析与原始事件捕获在这里完成，业务 payload 交回 client 编排。
+ */
+import WebSocket from "ws";
+import type { Logger } from "@downcity/agent/internal/utils/logger/Logger.js";
+import type { QQEventCaptureConfig, QQGatewayPayload } from "../../../chat/channels/qq/types/QqChannel.js";
+/**
+ * QQ Gateway WebSocket 连接参数。
+ */
+export interface ConnectQqGatewayWebSocketParams {
+    /**
+     * Gateway WebSocket URL。
+     */
+    gatewayUrl: string;
+    /**
+     * 日志器。
+     */
+    logger: Logger;
+    /**
+     * 原始事件捕获配置。
+     */
+    captureConfig: QQEventCaptureConfig;
+    /**
+     * 当前 WebSocket。
+     */
+    getCurrentSocket(): WebSocket | null;
+    /**
+     * 更新当前 WebSocket。
+     */
+    setCurrentSocket(ws: WebSocket | null): void;
+    /**
+     * 重置连接活性状态。
+     */
+    resetLivenessState(): void;
+    /**
+     * 停止心跳。
+     */
+    stopHeartbeat(): void;
+    /**
+     * 清理重连 timer。
+     */
+    clearReconnectTimer(): void;
+    /**
+     * 重置重连次数。
+     */
+    resetReconnectAttempts(): void;
+    /**
+     * 计划重连。
+     */
+    scheduleReconnect(reason: string, delayMs?: number): void;
+    /**
+     * 处理已解析的 Gateway payload。
+     */
+    handlePayload(payload: QQGatewayPayload): Promise<void>;
+}
+/**
+ * 建立 QQ Gateway WebSocket。
+ */
+export declare function connectQqGatewayWebSocket(params: ConnectQqGatewayWebSocketParams): Promise<void>;
+//# sourceMappingURL=QQGatewayConnection.d.ts.map

package/bin/chat/channels/qq/QQGatewayConnection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QQGatewayConnection.d.ts","sourceRoot":"","sources":["../../../../src/chat/channels/qq/QQGatewayConnection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,SAA2B,MAAM,IAAI,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iDAAiD,CAAC;AAC9E,OAAO,KAAK,EACV,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAI/C;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,aAAa,EAAE,oBAAoB,CAAC;IACpC;;OAEG;IACH,gBAAgB,IAAI,SAAS,GAAG,IAAI,CAAC;IACrC;;OAEG;IACH,gBAAgB,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC;IAC7C;;OAEG;IACH,kBAAkB,IAAI,IAAI,CAAC;IAC3B;;OAEG;IACH,aAAa,IAAI,IAAI,CAAC;IACtB;;OAEG;IACH,mBAAmB,IAAI,IAAI,CAAC;IAC5B;;OAEG;IACH,sBAAsB,IAAI,IAAI,CAAC;IAC/B;;OAEG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1D;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzD;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,+BAA+B,GACtC,OAAO,CAAC,IAAI,CAAC,CAuDf"}

package/bin/chat/channels/qq/QQGatewayConnection.js

@@ -0,0 +1,110 @@
+/**
+ * QQ Gateway WebSocket 连接事件绑定。
+ *
+ * 关键点（中文）
+ * - 只负责创建 WebSocket、绑定 open/message/close/error 事件。
+ * - runtime 状态仍由 `QQGatewayClient` 持有，避免连接 helper 变成第二个状态源。
+ * - message 解析与原始事件捕获在这里完成，业务 payload 交回 client 编排。
+ */
+import WebSocket from "ws";
+import { captureQqWsPayload } from "./QQEventCapture.js";
+import { parseQqGatewayPayload } from "./QQGatewaySupport.js";
+/**
+ * 建立 QQ Gateway WebSocket。
+ */
+export async function connectQqGatewayWebSocket(params) {
+    params.logger.info(`正在连接 WebSocket: ${params.gatewayUrl}`);
+    closePreviousSocket(params.getCurrentSocket());
+    params.stopHeartbeat();
+    params.resetLivenessState();
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const resolveOnce = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve();
+        };
+        const rejectOnce = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+        };
+        const ws = new WebSocket(params.gatewayUrl);
+        params.setCurrentSocket(ws);
+        ws.on("open", () => {
+            if (params.getCurrentSocket() !== ws)
+                return;
+            params.logger.info("WebSocket 连接已建立");
+            params.resetReconnectAttempts();
+            params.clearReconnectTimer();
+            params.resetLivenessState();
+            resolveOnce();
+        });
+        ws.on("message", async (data) => {
+            if (params.getCurrentSocket() !== ws)
+                return;
+            await handleSocketMessage(params, data);
+        });
+        ws.on("close", (code, reason) => {
+            if (params.getCurrentSocket() !== ws)
+                return;
+            const reasonText = Buffer.isBuffer(reason)
+                ? reason.toString("utf-8")
+                : String(reason || "");
+            params.logger.warn(`WebSocket 连接关闭: ${code} - ${reasonText}`);
+            params.setCurrentSocket(null);
+            params.stopHeartbeat();
+            params.resetLivenessState();
+            params.scheduleReconnect(`ws_closed:${code}`);
+            rejectOnce(new Error(`QQ websocket closed before ready: ${code} ${reasonText}`));
+        });
+        ws.on("error", (error) => {
+            if (params.getCurrentSocket() !== ws)
+                return;
+            params.logger.error("WebSocket 错误", { error: String(error) });
+            rejectOnce(error);
+        });
+    });
+}
+/**
+ * 关闭旧 socket。
+ */
+function closePreviousSocket(previousWs) {
+    if (previousWs &&
+        (previousWs.readyState === WebSocket.OPEN ||
+            previousWs.readyState === WebSocket.CONNECTING)) {
+        try {
+            previousWs.close();
+        }
+        catch {
+            // 关键点（中文）：旧连接关闭失败不影响新连接建立。
+        }
+    }
+}
+/**
+ * 解析、捕获并分发一条 socket message。
+ */
+async function handleSocketMessage(params, data) {
+    try {
+        const payload = parseQqGatewayPayload(data);
+        if (!payload) {
+            params.logger.warn("收到无法解析的 QQ WebSocket 消息，已忽略");
+            return;
+        }
+        params.logger.debug(`收到 WebSocket 消息: op=${payload.op}, t=${payload.t || "N/A"}`);
+        await captureQqWsPayload({
+            config: params.captureConfig,
+            logger: params.logger,
+            payload,
+        });
+        await params.handlePayload(payload);
+    }
+    catch (error) {
+        params.logger.error("处理 WebSocket 消息失败", {
+            error: String(error),
+        });
+    }
+}
+//# sourceMappingURL=QQGatewayConnection.js.map

package/bin/chat/channels/qq/QQGatewayConnection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QQGatewayConnection.js","sourceRoot":"","sources":["../../../../src/chat/channels/qq/QQGatewayConnection.ts"],"names":[],"mappings":"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"}

package/bin/chat/channels/qq/QQGatewayHeartbeat.d.ts

@@ -0,0 +1,59 @@
+/**
+ * QQ Gateway 心跳发送辅助。
+ *
+ * 关键点（中文）
+ * - 只负责心跳 interval 归一化与单次 heartbeat payload 发送。
+ * - 心跳状态仍由 `QQGatewayClient` 持有，避免 helper 内部隐藏状态。
+ */
+import WebSocket from "ws";
+import type { Logger } from "@downcity/agent/internal/utils/logger/Logger.js";
+/**
+ * QQ Gateway heartbeat 发送参数。
+ */
+export interface SendQqGatewayHeartbeatParams {
+    /**
+     * 当前 socket。
+     */
+    socket: WebSocket | null;
+    /**
+     * 日志器。
+     */
+    logger: Logger;
+    /**
+     * 最近一次服务端序列号。
+     */
+    lastSeq: number;
+    /**
+     * 心跳间隔。
+     */
+    heartbeatIntervalMs: number;
+    /**
+     * WebSocket READY 时间。
+     */
+    wsReadyAtMs: number;
+    /**
+     * 待 ACK 心跳开始时间。
+     */
+    pendingHeartbeatSinceMs: number;
+    /**
+     * 标记心跳发送成功。
+     */
+    markHeartbeatSent(nowMs: number): void;
+    /**
+     * 标记待 ACK 心跳开始时间。
+     */
+    markPendingHeartbeat(nowMs: number): void;
+    /**
+     * 触发 socket 自愈关闭。
+     */
+    closeSocketForRecovery(reason: string): void;
+}
+/**
+ * 归一化心跳间隔。
+ */
+export declare function normalizeQqHeartbeatIntervalMs(intervalMs: number): number;
+/**
+ * 发送单次 QQ Gateway heartbeat。
+ */
+export declare function sendQqGatewayHeartbeat(params: SendQqGatewayHeartbeatParams): void;
+//# sourceMappingURL=QQGatewayHeartbeat.d.ts.map

package/bin/chat/channels/qq/QQGatewayHeartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QQGatewayHeartbeat.d.ts","sourceRoot":"","sources":["../../../../src/chat/channels/qq/QQGatewayHeartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,SAAS,MAAM,IAAI,CAAC;AAC3B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iDAAiD,CAAC;AAO9E;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;OAEG;IACH,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IACzB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,uBAAuB,EAAE,MAAM,CAAC;IAChC;;OAEG;IACH,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC;;OAEG;IACH,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C;;OAEG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9C;AAED;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAIzE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,IAAI,CAyCN"}