openclaw-plugin-yuanbao 2.12.0 → 2.13.1-beta.9

package/dist/api.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Aggregated export file
+ * 供 index.ts 通过 loadBundledEntryExportSync 懒加载引用
+ */
 export { yuanbaoPlugin } from "./src/channel.js";
 export { yuanbaoSetupPlugin } from "./src/channel.setup.js";
 export { initLogger } from "./src/logger.js";

package/dist/api.js

@@ -1,3 +1,7 @@
+/**
+ * Aggregated export file
+ * 供 index.ts 通过 loadBundledEntryExportSync 懒加载引用
+ */
 export { yuanbaoPlugin } from "./src/channel.js";
 export { yuanbaoSetupPlugin } from "./src/channel.setup.js";
 export { initLogger } from "./src/logger.js";

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("openclaw/plugin-sdk/channel-entry-contract").BundledChannelEntryContract<import("openclaw/plugin-sdk/channel-core").ChannelPlugin>;
+declare const _default: import("openclaw/plugin-sdk/channel-entry-contract").BundledChannelEntryContract<import("openclaw/plugin-sdk").ChannelPlugin>;
 export default _default;

package/dist/index.js

@@ -1,4 +1,6 @@
 import { defineBundledChannelEntry, loadBundledEntryExportSync, } from "openclaw/plugin-sdk/channel-entry-contract";
+import { YUANBAO_PLUGIN_ID } from "./src/channel-shared.js";
+/** 懒加载注册工具 */
 function registerTools(api) {
     const register = loadBundledEntryExportSync(import.meta.url, {
         specifier: "./api.js",
@@ -6,6 +8,7 @@ function registerTools(api) {
     });
     register(api);
 }
+/** Lazy-load and register all slash commands */
 function registerCommands(api) {
     const yuanbaoUpgradeCommand = loadBundledEntryExportSync(import.meta.url, { specifier: "./api.js", exportName: "yuanbaoUpgradeCommand" });
     const yuanbaobotUpgradeCommand = loadBundledEntryExportSync(import.meta.url, { specifier: "./api.js", exportName: "yuanbaobotUpgradeCommand" });
@@ -14,6 +17,7 @@ function registerCommands(api) {
     api.registerCommand(yuanbaobotUpgradeCommand);
     api.registerCommand(logUploadCommandDefinition);
 }
+/** 懒加载初始化内置表情缓存 */
 function initBuiltinStickers() {
     const init = loadBundledEntryExportSync(import.meta.url, {
         specifier: "./api.js",
@@ -21,6 +25,7 @@ function initBuiltinStickers() {
     });
     init();
 }
+/** 懒加载初始化环境变量 */
 function initEnv(api) {
     const init = loadBundledEntryExportSync(import.meta.url, {
         specifier: "./api.js",
@@ -28,6 +33,7 @@ function initEnv(api) {
     });
     init(api);
 }
+/** 懒加载初始化日志 */
 function initLogger(api) {
     const init = loadBundledEntryExportSync(import.meta.url, {
         specifier: "./api.js",
@@ -36,7 +42,7 @@ function initLogger(api) {
     init(api);
 }
 export default defineBundledChannelEntry({
-    id: "openclaw-plugin-yuanbao",
+    id: YUANBAO_PLUGIN_ID,
     name: "YuanBao",
     description: "YuanBao channel plugin",
     importMetaUrl: import.meta.url,

package/dist/setup-entry.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("openclaw/plugin-sdk/channel-entry-contract").BundledChannelSetupEntryContract<import("openclaw/plugin-sdk/channel-core").ChannelPlugin>;
+declare const _default: import("openclaw/plugin-sdk/channel-entry-contract").BundledChannelSetupEntryContract<import("openclaw/plugin-sdk").ChannelPlugin>;
 export default _default;

package/dist/src/access/api.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Yuanbao API client.
+ *
+ * Backward-compatible re-export entry point.
+ * Implementation split into:
+ *   - http/request.ts  — Types, token cache, signing, auth headers, HTTP utilities
+ *   - http/main.ts     — Business APIs (uploadInfo / downloadUrl)
+ */
 export type { SignTokenData, AuthHeaders, CosUploadConfig, Log } from "./http/request.js";
 export { clearSignTokenCache, clearAllSignTokenCache, getTokenStatus, verifySignature, getSignToken, forceRefreshSignToken, getAuthHeaders, yuanbaoPost, yuanbaoGet, } from "./http/request.js";
 export { apiGetUploadInfo, apiGetDownloadUrl } from "./http/main.js";

package/dist/src/access/api.js

@@ -1,2 +1,10 @@
+/**
+ * Yuanbao API client.
+ *
+ * Backward-compatible re-export entry point.
+ * Implementation split into:
+ *   - http/request.ts  — Types, token cache, signing, auth headers, HTTP utilities
+ *   - http/main.ts     — Business APIs (uploadInfo / downloadUrl)
+ */
 export { clearSignTokenCache, clearAllSignTokenCache, getTokenStatus, verifySignature, getSignToken, forceRefreshSignToken, getAuthHeaders, yuanbaoPost, yuanbaoGet, } from "./http/request.js";
 export { apiGetUploadInfo, apiGetDownloadUrl } from "./http/main.js";

package/dist/src/access/http/bot-id-cache.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Lightweight botId cache shared between the HTTP sign-token client and
+ * account resolution.
+ *
+ * Kept in its own module (rather than inlined in `request.ts`) so that
+ * `accounts.ts` — which is on the `openclaw setup` / `openclaw configure`
+ * code path — can look up a previously-resolved botId without statically
+ * pulling in the full HTTP/crypto/env runtime stack.
+ */
+/** Read the last-known botId for an account, if any. */
 export declare function getCachedBotId(accountId: string): string | undefined;
+/** Record a botId obtained during sign-token exchange. */
 export declare function setCachedBotId(accountId: string, botId: string | undefined): void;
+/** Clear the cached botId (e.g. when tearing down an account). */
 export declare function clearCachedBotId(accountId: string): void;

package/dist/src/access/http/bot-id-cache.js

@@ -1,14 +1,26 @@
+/**
+ * Lightweight botId cache shared between the HTTP sign-token client and
+ * account resolution.
+ *
+ * Kept in its own module (rather than inlined in `request.ts`) so that
+ * `accounts.ts` — which is on the `openclaw setup` / `openclaw configure`
+ * code path — can look up a previously-resolved botId without statically
+ * pulling in the full HTTP/crypto/env runtime stack.
+ */
 const botIdCache = new Map();
+/** Read the last-known botId for an account, if any. */
 export function getCachedBotId(accountId) {
     const value = botIdCache.get(accountId);
     return value && value.length > 0 ? value : undefined;
 }
+/** Record a botId obtained during sign-token exchange. */
 export function setCachedBotId(accountId, botId) {
     if (!accountId || !botId) {
         return;
     }
     botIdCache.set(accountId, botId);
 }
+/** Clear the cached botId (e.g. when tearing down an account). */
 export function clearCachedBotId(accountId) {
     botIdCache.delete(accountId);
 }

package/dist/src/access/http/main.d.ts

@@ -1,4 +1,16 @@
+/**
+ * Yuanbao business API.
+ *
+ * Upload pre-sign config retrieval, resource download URL retrieval, etc.
+ * Auth and HTTP utilities are in request.ts.
+ */
 import type { ResolvedYuanbaoAccount } from "../../types.js";
 import type { Log, CosUploadConfig } from "./request.js";
+/**
+ * Get COS upload pre-sign config.
+ */
 export declare function apiGetUploadInfo(account: ResolvedYuanbaoAccount, fileName: string, fileId: string, log?: Log): Promise<CosUploadConfig>;
+/**
+ * Get COS download URL for a given resourceId.
+ */
 export declare function apiGetDownloadUrl(account: ResolvedYuanbaoAccount, resourceId: string, log?: Log): Promise<string>;

package/dist/src/access/http/main.js

@@ -1,6 +1,15 @@
+/**
+ * Yuanbao business API.
+ *
+ * Upload pre-sign config retrieval, resource download URL retrieval, etc.
+ * Auth and HTTP utilities are in request.ts.
+ */
 import { yuanbaoPost, yuanbaoGet } from "./request.js";
 const UPLOAD_INFO_PATH = "/api/resource/genUploadInfo";
 const DOWNLOAD_INFO_PATH = "/api/resource/v1/download";
+/**
+ * Get COS upload pre-sign config.
+ */
 export async function apiGetUploadInfo(account, fileName, fileId, log) {
     const data = await yuanbaoPost(account, UPLOAD_INFO_PATH, { fileName, fileId, docFrom: "localDoc", docOpenId: "" }, log);
     if (!data.bucketName || !data.location) {
@@ -8,6 +17,9 @@ export async function apiGetUploadInfo(account, fileName, fileId, log) {
     }
     return data;
 }
+/**
+ * Get COS download URL for a given resourceId.
+ */
 export async function apiGetDownloadUrl(account, resourceId, log) {
     const data = await yuanbaoGet(account, DOWNLOAD_INFO_PATH, { resourceId }, log);
     const downloadUrl = data.url ?? data.realUrl;

package/dist/src/access/http/request.d.ts

@@ -1,3 +1,4 @@
+/** Yuanbao HTTP request base layer — token cache, signature, auth headers, and HTTP utilities. */
 import type { ResolvedYuanbaoAccount } from "../../types.js";
 export { getCachedBotId } from "./bot-id-cache.js";
 export type SignTokenData = {

package/dist/src/access/http/request.js

@@ -1,3 +1,4 @@
+/** Yuanbao HTTP request base layer — token cache, signature, auth headers, and HTTP utilities. */
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { getOpenclawVersion, getOperationSystem, getPluginVersion } from "../../infra/env.js";
 import { createLog } from "../../logger.js";
@@ -10,6 +11,7 @@ const RETRYABLE_SIGN_CODE = 10099;
 const SIGN_MAX_RETRIES = 3;
 const SIGN_RETRY_DELAY_MS = 1000;
 const CACHE_REFRESH_MARGIN_MS = 5 * 60 * 1000;
+// Max safe setTimeout delay (ms): ~24 days, prevents 32-bit overflow
 const MAX_SAFE_TIMEOUT_MS = 24 * 24 * 3600 * 1000;
 const HTTP_AUTH_RETRY_MAX = 1;
 const tokenCacheMap = new Map();
@@ -46,8 +48,7 @@ export function getTokenStatus(accountId) {
 }
 function computeSignature(params) {
     const plain = params.nonce + params.timestamp + params.appKey + params.appSecret;
-    return createHmac("sha256", params.appSecret).update(plain)
-        .digest("hex");
+    return createHmac("sha256", params.appSecret).update(plain).digest("hex");
 }
 export function verifySignature(expected, actual) {
     const expectedBuf = Buffer.from(expected, "hex");
@@ -113,6 +114,7 @@ function scheduleTokenRefresh(account, durationSec, log) {
     if (existing) {
         clearTimeout(existing);
     }
+    // Clamp: min 60s, max MAX_SAFE_TIMEOUT_MS (prevent setTimeout 32-bit integer overflow)
     const rawMs = durationSec * 1000 - CACHE_REFRESH_MARGIN_MS;
     const refreshAfterMs = Math.min(Math.max(rawMs, 60_000), MAX_SAFE_TIMEOUT_MS);
     const clampedHint = rawMs > MAX_SAFE_TIMEOUT_MS ? ", clamped to max safe timeout" : "";
@@ -128,6 +130,7 @@ function scheduleTokenRefresh(account, durationSec, log) {
         }
         catch (err) {
             mlog.error(`[${account.accountId}][token-timer] scheduled refresh failed: ${String(err)}, retrying in 30s`);
+            // Retry after short delay on scheduled refresh failure to avoid losing the timer
             const retryTimer = setTimeout(async () => {
                 tokenRefreshTimers.delete(account.accountId);
                 try {
@@ -144,6 +147,7 @@ function scheduleTokenRefresh(account, durationSec, log) {
     tokenRefreshTimers.set(account.accountId, timer);
 }
 export async function getSignToken(account, log) {
+    // Static token takes priority
     if (account.token) {
         return {
             bot_id: account.botId || "",
@@ -160,6 +164,7 @@ export async function getSignToken(account, log) {
         tlog.info(`[${account.accountId}] using cached token (${remainSec}s remaining)`);
         return cached.data;
     }
+    // Singleflight: reuse in-flight request if one exists
     let fetchPromise = tokenFetchPromises.get(account.accountId);
     if (fetchPromise) {
         tlog.info(`[${account.accountId}] sign-token in progress, waiting for existing request`);
@@ -187,6 +192,7 @@ export async function forceRefreshSignToken(account, log) {
     const flog = createLog("http", log);
     flog.warn(`[${account.accountId}][force-refresh] clearing cache and re-signing token`);
     clearSignTokenCache(account.accountId);
+    // Also clear in-flight singleflight promise to ensure a fresh request
     tokenFetchPromises.delete(account.accountId);
     return getSignToken(account, log);
 }
@@ -222,6 +228,7 @@ export async function yuanbaoPost(account, path, body, log) {
             },
             body: JSON.stringify(body),
         });
+        // HTTP 401: token expired, force-refresh and retry once
         if (response.status === 401 && attempt < HTTP_AUTH_RETRY_MAX) {
             plog.warn(`[post][${account.accountId}] ${path} received 401, refreshing token and retrying (attempt=${attempt + 1})`);
             await forceRefreshSignToken(account, log);
@@ -251,6 +258,7 @@ export async function yuanbaoGet(account, path, params, log) {
                 ...authHeaders,
             },
         });
+        // HTTP 401: token expired, force-refresh and retry once
         if (response.status === 401 && attempt < HTTP_AUTH_RETRY_MAX) {
             glog.warn(`[get][${account.accountId}] ${path} received 401, refreshing token and retrying (attempt=${attempt + 1})`);
             await forceRefreshSignToken(account, log);

package/dist/src/access/ws/biz-codec.d.ts

@@ -1,3 +1,4 @@
+/** Business-layer Protobuf codec — encode/decode for business messages. */
 import type { YuanbaoInboundMessage, YuanbaoMsgBodyElement } from "../../types.js";
 import type { WsSendC2CMessageData, WsSendGroupMessageData, WsSendMessageResponse, WsSendPrivateHeartbeatData, WsSendGroupHeartbeatData, WsHeartbeatResponse, WsQueryGroupInfoData, WsQueryGroupInfoResponse, WsGetGroupMemberListData, WsGetGroupMemberListResponse, WsSyncInformationData, WsSyncInformationResponse } from "./types.js";
 export declare const BIZ_MSG_TYPES: {
@@ -21,21 +22,45 @@ export declare const BIZ_MSG_TYPES: {
 };
 export declare function encodeBizPB(key: string, value: Record<string, unknown>): Uint8Array | null;
 export declare function decodeBizPB(key: string, data: Uint8Array | ArrayBuffer): unknown;
+/** Convert TS MsgBodyElement[] to protobuf format. */
 export declare function toProtoMsgBody(elements: YuanbaoMsgBodyElement[]): Record<string, unknown>[];
+/** Convert protobuf format message body back to TS MsgBodyElement[]. */
 export declare function fromProtoMsgBody(elements: Array<Record<string, unknown>>): YuanbaoMsgBodyElement[];
+/** Encode a C2C send message request. */
 export declare function encodeSendC2CMessageReq(data: WsSendC2CMessageData): Uint8Array | null;
+/** Encode group message send request. */
 export declare function encodeSendGroupMessageReq(data: WsSendGroupMessageData): Uint8Array | null;
+/** Encode direct chat reply status heartbeat request. */
 export declare function encodeSendPrivateHeartbeatReq(data: WsSendPrivateHeartbeatData): Uint8Array | null;
+/** Encode group chat reply status heartbeat request. */
 export declare function encodeSendGroupHeartbeatReq(data: WsSendGroupHeartbeatData): Uint8Array | null;
+/** Decode inbound message proto bytes into YuanbaoInboundMessage. */
 export declare function decodeInboundMessage(data: Uint8Array | ArrayBuffer): YuanbaoInboundMessage | null;
+/** Decode C2C outbound response. */
 export declare function decodeSendC2CMessageRsp(data: Uint8Array | ArrayBuffer, msgId: string): WsSendMessageResponse | null;
+/** Decode group message outbound response. */
 export declare function decodeSendGroupMessageRsp(data: Uint8Array | ArrayBuffer, msgId: string): WsSendMessageResponse | null;
+/** Decode outbound response (compatible with both C2C and group). */
 export declare function decodeSendMessageRsp(data: Uint8Array | ArrayBuffer, msgId: string): WsSendMessageResponse | null;
+/** Encode query group info request. */
 export declare function encodeQueryGroupInfoReq(data: WsQueryGroupInfoData): Uint8Array | null;
+/** Decode query group info response. */
 export declare function decodeQueryGroupInfoRsp(data: Uint8Array | ArrayBuffer, msgId: string): WsQueryGroupInfoResponse | null;
+/** Encode get group member list request. */
 export declare function encodeGetGroupMemberListReq(data: WsGetGroupMemberListData): Uint8Array | null;
+/** Decode get group member list response. */
 export declare function decodeGetGroupMemberListRsp(data: Uint8Array | ArrayBuffer, msgId: string): WsGetGroupMemberListResponse | null;
+/**
+ * Decode direct chat reply status heartbeat response.
+ * Preserves request-side msgId for stable request-response correlation.
+ */
 export declare function decodeSendPrivateHeartbeatRsp(data: Uint8Array | ArrayBuffer, msgId: string): WsHeartbeatResponse | null;
+/**
+ * Decode group chat reply status heartbeat response.
+ * Carries original msgId for correct request-response matching.
+ */
 export declare function decodeSendGroupHeartbeatRsp(data: Uint8Array | ArrayBuffer, msgId: string): WsHeartbeatResponse | null;
+/** Encode SyncInformationReq (sync command list to backend). */
 export declare function encodeSyncInformationReq(data: WsSyncInformationData): Uint8Array | null;
+/** Decode SyncInformationRsp. */
 export declare function decodeSyncInformationRsp(data: Uint8Array | ArrayBuffer, msgId: string): WsSyncInformationResponse | null;

package/dist/src/access/ws/biz-codec.js

@@ -1,5 +1,7 @@
+/** Business-layer Protobuf codec — encode/decode for business messages. */
 import protobuf from "protobufjs";
 import { createLog } from "../../logger.js";
+import { EnumCLawMsgType } from "../../types.js";
 import bizDescriptor from "./proto/biz.json" with { type: "json" };
 let root = null;
 function getRoot() {
@@ -47,9 +49,11 @@ export function decodeBizPB(key, data) {
         return type.decode(buf);
     }
     catch {
+        // protobuf decode failure is expected, silently return null
         return null;
     }
 }
+/** Convert TS MsgBodyElement[] to protobuf format. */
 export function toProtoMsgBody(elements) {
     return elements.map((el) => {
         const c = el.msg_content;
@@ -72,6 +76,7 @@ export function toProtoMsgBody(elements) {
         };
     });
 }
+/** Convert protobuf format message body back to TS MsgBodyElement[]. */
 export function fromProtoMsgBody(elements) {
     if (!elements || !Array.isArray(elements)) {
         return [];
@@ -125,6 +130,7 @@ function toProtoLogExt(logExt, traceId) {
     const resolvedTraceId = traceId?.trim() || logExt?.trace_id?.trim();
     return resolvedTraceId ? { traceId: resolvedTraceId } : undefined;
 }
+/** Encode a C2C send message request. */
 export function encodeSendC2CMessageReq(data) {
     const logExt = toProtoLogExt(undefined, data.trace_id);
     const log = createLog("biz-codec");
@@ -144,6 +150,7 @@ export function encodeSendC2CMessageReq(data) {
         ...(logExt ? { logExt } : {}),
     });
 }
+/** Encode group message send request. */
 export function encodeSendGroupMessageReq(data) {
     const logExt = toProtoLogExt(undefined, data.trace_id);
     const log = createLog("biz-codec");
@@ -164,14 +171,17 @@ export function encodeSendGroupMessageReq(data) {
         ...(logExt ? { logExt } : {}),
     });
 }
+/** Encode direct chat reply status heartbeat request. */
 export function encodeSendPrivateHeartbeatReq(data) {
     return encodeBizPB(BIZ_MSG_TYPES.SendPrivateHeartbeatReq, {
+        // Dual-write fromAccount/fromtAccount for backward compatibility with old descriptor typo
         fromAccount: data.from_account,
         fromtAccount: data.from_account,
         toAccount: data.to_account,
         heartbeat: data.heartbeat,
     });
 }
+/** Encode group chat reply status heartbeat request. */
 export function encodeSendGroupHeartbeatReq(data) {
     return encodeBizPB(BIZ_MSG_TYPES.SendGroupHeartbeatReq, {
         fromAccount: data.from_account,
@@ -181,6 +191,7 @@ export function encodeSendGroupHeartbeatReq(data) {
         heartbeat: data.heartbeat,
     });
 }
+/** Decode inbound message proto bytes into YuanbaoInboundMessage. */
 export function decodeInboundMessage(data) {
     const decoded = decodeBizPB(BIZ_MSG_TYPES.InboundMessagePush, data);
     if (!decoded) {
@@ -220,6 +231,7 @@ export function decodeInboundMessage(data) {
         seq_id: seqId,
     };
 }
+/** Decode C2C outbound response. */
 export function decodeSendC2CMessageRsp(data, msgId) {
     const decoded = decodeBizPB(BIZ_MSG_TYPES.SendC2CMessageRsp, data);
     if (!decoded) {
@@ -231,6 +243,7 @@ export function decodeSendC2CMessageRsp(data, msgId) {
         message: decoded.message || "",
     };
 }
+/** Decode group message outbound response. */
 export function decodeSendGroupMessageRsp(data, msgId) {
     const decoded = decodeBizPB(BIZ_MSG_TYPES.SendGroupMessageRsp, data);
     if (!decoded) {
@@ -242,14 +255,18 @@ export function decodeSendGroupMessageRsp(data, msgId) {
         message: decoded.message || "",
     };
 }
+/** Decode outbound response (compatible with both C2C and group). */
 export function decodeSendMessageRsp(data, msgId) {
+    // C2C and group Rsp share the same structure (code + message); try C2C first
     return decodeSendC2CMessageRsp(data, msgId) ?? decodeSendGroupMessageRsp(data, msgId);
 }
+/** Encode query group info request. */
 export function encodeQueryGroupInfoReq(data) {
     return encodeBizPB(BIZ_MSG_TYPES.QueryGroupInfoReq, {
         groupCode: data.group_code,
     });
 }
+/** Decode query group info response. */
 export function decodeQueryGroupInfoRsp(data, msgId) {
     const decoded = decodeBizPB(BIZ_MSG_TYPES.QueryGroupInfoRsp, data);
     if (!decoded) {
@@ -270,11 +287,13 @@ export function decodeQueryGroupInfoRsp(data, msgId) {
             : undefined,
     };
 }
+/** Encode get group member list request. */
 export function encodeGetGroupMemberListReq(data) {
     return encodeBizPB(BIZ_MSG_TYPES.GetGroupMemberListReq, {
         groupCode: data.group_code,
     });
 }
+/** Decode get group member list response. */
 export function decodeGetGroupMemberListRsp(data, msgId) {
     const decoded = decodeBizPB(BIZ_MSG_TYPES.GetGroupMemberListRsp, data);
     if (!decoded) {
@@ -294,6 +313,10 @@ export function decodeGetGroupMemberListRsp(data, msgId) {
         member_list: memberList,
     };
 }
+/**
+ * Decode direct chat reply status heartbeat response.
+ * Preserves request-side msgId for stable request-response correlation.
+ */
 export function decodeSendPrivateHeartbeatRsp(data, msgId) {
     const decoded = decodeBizPB(BIZ_MSG_TYPES.SendPrivateHeartbeatRsp, data);
     if (!decoded) {
@@ -306,6 +329,10 @@ export function decodeSendPrivateHeartbeatRsp(data, msgId) {
         message: decoded.msg || "",
     };
 }
+/**
+ * Decode group chat reply status heartbeat response.
+ * Carries original msgId for correct request-response matching.
+ */
 export function decodeSendGroupHeartbeatRsp(data, msgId) {
     const decoded = decodeBizPB(BIZ_MSG_TYPES.SendGroupHeartbeatRsp, data);
     if (!decoded) {
@@ -318,6 +345,7 @@ export function decodeSendGroupHeartbeatRsp(data, msgId) {
         message: decoded.msg || "",
     };
 }
+/** Encode SyncInformationReq (sync command list to backend). */
 export function encodeSyncInformationReq(data) {
     return encodeBizPB(BIZ_MSG_TYPES.SyncInformationReq, {
         syncType: data.syncType,
@@ -326,6 +354,7 @@ export function encodeSyncInformationReq(data) {
         ...(data.commandData ? { commandData: data.commandData } : {}),
     });
 }
+/** Decode SyncInformationRsp. */
 export function decodeSyncInformationRsp(data, msgId) {
     const decoded = decodeBizPB(BIZ_MSG_TYPES.SyncInformationRsp, data);
     if (!decoded) {

package/dist/src/access/ws/client.d.ts

@@ -1,7 +1,11 @@
+/** WebSocket client — connection management, auth, heartbeat, and auto-reconnect. */
 import type { LogSink } from "../../logger.js";
 import type { WsClientCallbacks, WsClientConfig, WsClientState, WsConnectionConfig, WsSendMessageResponse, WsSendC2CMessageData, WsSendGroupMessageData, WsSendPrivateHeartbeatData, WsSendGroupHeartbeatData, WsHeartbeatResponse, WsQueryGroupInfoData, WsQueryGroupInfoResponse, WsGetGroupMemberListData, WsGetGroupMemberListResponse, WsSyncInformationData, WsSyncInformationResponse } from "./types.js";
+/** Outbound business commands */
 export declare const BIZ_CMD: {
+    /** Send C2C message */
     readonly SendC2CMessage: "send_c2c_message";
+    /** Send group message */
     readonly SendGroupMessage: "send_group_message";
     readonly QueryGroupInfo: "query_group_info";
     readonly GetGroupMemberList: "get_group_member_list";
@@ -9,6 +13,11 @@ export declare const BIZ_CMD: {
     readonly SendGroupHeartbeat: "send_group_heartbeat";
     readonly SyncInformation: "sync_information";
 };
+/**
+ * Yuanbao WebSocket client.
+ * Implements connection lifecycle, auth, heartbeat, auto-reconnect,
+ * send/receive, and request-response matching via msgId.
+ */
 export declare class YuanbaoWsClient {
     private connectionConfig;
     private readonly clientConfig;
@@ -33,35 +42,57 @@ export declare class YuanbaoWsClient {
         callbacks?: WsClientCallbacks;
         log?: LogSink;
     });
+    /** Update auth info (used for reconnect after token refresh). */
     updateAuth(auth: WsConnectionConfig["auth"]): void;
     connect(): void;
     disconnect(): void;
     getState(): WsClientState;
     getConnectId(): string | null;
+    /** Send raw binary data. */
     sendBinary(data: Uint8Array): boolean;
+    /** Send a business request and wait for the response matching the same msgId. */
     sendAndWait(cmd: string, module: string, data: Uint8Array, timeoutMs?: number): Promise<WsSendMessageResponse>;
     sendC2CMessage(data: WsSendC2CMessageData): Promise<WsSendMessageResponse>;
     sendGroupMessage(data: WsSendGroupMessageData): Promise<WsSendMessageResponse>;
+    /** Send a business request and wait for the response (supports custom decoders). */
     sendAndWaitWith<T>(cmd: string, module: string, data: Uint8Array, decoder: (data: Uint8Array | ArrayBuffer, msgId: string) => T | null, timeoutMs?: number): Promise<T>;
+    /** Query group info. */
     queryGroupInfo(data: WsQueryGroupInfoData): Promise<WsQueryGroupInfoResponse>;
+    /** Get group member list. */
     getGroupMemberList(data: WsGetGroupMemberListData): Promise<WsGetGroupMemberListResponse>;
+    /** Send direct-chat reply status heartbeat. */
     sendPrivateHeartbeat(data: WsSendPrivateHeartbeatData): Promise<WsHeartbeatResponse>;
+    /** Send group-chat reply status heartbeat. */
     sendGroupHeartbeat(data: WsSendGroupHeartbeatData): Promise<WsHeartbeatResponse>;
+    /** Sync information to the backend (command list, etc.). */
     syncInformation(data: WsSyncInformationData): Promise<WsSyncInformationResponse>;
+    /** Establish WebSocket connection and bind event handlers. */
     private doConnect;
     private onMessage;
     private handleConnMsg;
     private onResponse;
     private sendAuthBind;
+    /**
+     * Try triggering onAuthFailed callback for token refresh and reconnect.
+     * Uses the same scheduleReconnect delay strategy as close events.
+     */
     private tryAuthFailedRefresh;
+    /**
+     * After token signing failure, consume one reconnect attempt and retry after a delay.
+     * Avoids wasting a reconnect attempt on a connection with a known-expired token.
+     */
     private retryAuthRefreshAfterDelay;
+    /** Handle auth response: verify status code, start heartbeat, fire onReady. */
     private onAuthBindResponse;
     private startHeartbeat;
     private stopHeartbeat;
+    /** Schedule the next sendPing call without resetting heartbeatAckReceived (for consecutive timeout detection) */
     private scheduleNextPingCheck;
     private sendPing;
     private onPingResponse;
+    /** Handle a downstream push (cmdType=2). Sends ACK, handles kickout, dispatches events. */
     private onPush;
+    /** Handle a business response (cmdType=1, non-auth/ping). Matches pending requests by msgId. */
     private onBusinessResponse;
     private getReconnectDelay;
     private scheduleReconnect;