@imweapp/openclaw-imwe 2026.4.12-alpha.1

package/src/proto/send.codec.ts

@@ -0,0 +1,535 @@
+/**
+ * send.codec.ts — 出站消息编码 + 发送响应解码
+ *
+ * 使用 protobufjs 运行时动态加载 .proto 文件进行编解码，
+ * .proto 文件是唯一的结构定义来源（proto/ 目录）。
+ *
+ * 发送消息四层包装（CLIENT_REQ 方向，对应文档 §一）：
+ *
+ *   第1层  PbPacket(type=CLIENT_REQ=0, request=PbRequest)
+ *            ↑ PbPacket.proto
+ *   第2层  PbRequest(path="/api/im/chat/bot", reqId, reqStamp, body)
+ *            ↑ PbPacket.proto
+ *   第3层  PbSingleChatMsgReqBody(fromId, toId, clientMsgId, envelopeType, e2eeFlag, envelope)
+ *            ↑ PbSingleChatMsg.proto
+ *   第4层  PbChatMsgEnvelope / PbChatOperationEnvelope（由 builder 纯函数产出）
+ *            ↑ PbChatMsg.proto + PbChatTextContent.proto 等
+ *
+ * 模块拆分：
+ *   - buildChatEnvelopeBytes / buildMediaEnvelopeBytes / buildMarkdownEnvelopeBytes
+ *     为纯函数，只产出"第 4 层"envelope 的 bytes，可供 E2EE 加密前独立使用。
+ *   - encodeSingleChatReqPacket 把任意 envelope bytes 包装为完整的
+ *     PbSingleChatMsgReqBody → PbRequest → PbPacket 三层外壳。
+ *   - encodeSendRequest / encodeMediaSendRequest / encodeMarkdownSendRequest /
+ *     encodeTypingSignalRequest 保留原签名，实现内部委托给上述纯函数，字节输出保持不变。
+ *
+ * 发送响应解码：
+ *   PbResponse → statusCode(200=成功) + body → PbMsgRspBody(serverMsgId)
+ */
+
+import { randomBytes } from 'node:crypto';
+import { getRegistry } from './registry.js';
+import type { ImweSendResponse } from '../types.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 出站多媒体消息类型
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 出站多媒体消息参数 */
+export type OutboundMediaParams = {
+  /** 接收方 userId */
+  to: string;
+  /** 发送方 ID（机器人 botAcctId） */
+  fromId?: string;
+  /** 调用方显式指定的客户端消息 ID（可选） */
+  clientMsgId?: string;
+  /** 媒体文件 URL */
+  url: string;
+  /** 媒体类型 */
+  mediaType: 'image' | 'video' | 'audio' | 'file';
+  /** 文件名（可选） */
+  fileName?: string;
+  /** 文件大小（字节，可选） */
+  fileSize?: number;
+  /** MIME 类型（可选，如 image/jpeg） */
+  mimeType?: string;
+  /** 图片/视频宽度（可选） */
+  width?: number;
+  /** 图片/视频高度（可选） */
+  height?: number;
+  /** 文字描述/caption（可选） */
+  caption?: string;
+  /** 图片 blurhash（可选） */
+  blurHash?: string;
+  /** AES-256 文件加密密钥（32 字节，E2EE 文件传输时提供） */
+  fileKey?: Uint8Array;
+  /** AES-CTR 初始向量（16 字节，E2EE 文件传输时提供） */
+  fileIv?: Uint8Array;
+  /** SHA256(plaintext) 小写十六进制摘要（E2EE 文件传输时提供） */
+  fileDigest?: string;
+  /** 明文文件长度（字节，E2EE 文件传输时提供） */
+  plaintextLength?: number;
+  /** 上传会话过期时间（毫秒时间戳，E2EE 文件传输时提供） */
+  expireTime?: number;
+  /** 操作凭证（E2EE 文件传输时提供，batchCompleteChunks 返回） */
+  opCreds?: string;
+  /** 密文长度（字节，E2EE 文件传输时提供，AES-CTR 下等于 plaintextLength） */
+  length?: number;
+};
+
+/** mediaType → PbChatFileMetaType 枚举值映射 */
+const MEDIA_TYPE_MAP: Record<OutboundMediaParams['mediaType'], number> = {
+  image: 1, // MEDIA_TYPE_IMAGE
+  video: 2, // MEDIA_TYPE_VIDEO
+  audio: 3, // MEDIA_TYPE_AUDIO
+  file: 4, // MEDIA_TYPE_FILE
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 出站 markdown 消息类型
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 出站 markdown 消息参数（与 OutboundMediaParams 风格对齐） */
+export type OutboundMarkdownParams = {
+  /** 接收方 userId */
+  to: string;
+  /** 发送方 ID（机器人 botAcctId），为空时平台从 ApiKey 解析 */
+  fromId?: string;
+  /** 调用方显式指定的 clientMsgId（测试/重发时使用） */
+  clientMsgId?: string;
+  /** markdown 正文，非空 */
+  markdown: string;
+  /** 摘要标题（可选） */
+  digest?: string;
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 内部工具
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 生成客户端消息 ID（UUID v4，32 字节十六进制，不带破折号）。
+ * 返回 32 个十六进制字符的字符串（不含 '-'），用于 clientMsgId 或 attachmentId。
+ * 使用随机字节并设置 UUID v4 的固定位以保证符合 UUID v4 的规范。
+ */
+export function genClientMsgId(): string {
+  const b = randomBytes(16);
+  // 设置 UUID v4 固定位：版本号 4 和变体位
+  b[6] = (b[6] & 0x0f) | 0x40;
+  b[8] = (b[8] & 0x3f) | 0x80;
+  return b.toString('hex'); // 32 个十六进制字符，不含 '-'
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 第 4 层：envelope bytes 构造器（纯函数，E2EE 加密前可独立使用）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 构造文本聊天信封的 PbChatMsgEnvelope bytes（textContent 分支，oneof 字段 3）。
+ *
+ * 只产出"第 4 层" envelope bytes，不涉及 clientMsgId / 外层包装，
+ * 可供 E2EE `encryptSingle` 的明文输入或 `encodeSingleChatReqPacket` 进一步包装。
+ *
+ * @param text     文本正文
+ * @param options  可选项：referenceClientMsgId（引用消息 ID）
+ * @returns        PbChatMsgEnvelope 编码后的 bytes
+ */
+export async function buildChatEnvelopeBytes(
+  text: string,
+  options?: { referenceClientMsgId?: string },
+): Promise<Uint8Array> {
+  const reg = await getRegistry();
+
+  // 第 4 层内层：PbChatTextContent → bytes（含可选的引用消息 ID）
+  const textContentMsg = reg.PbChatTextContent.create({
+    text,
+    ...(options?.referenceClientMsgId
+      ? { referenceClientMsgId: options.referenceClientMsgId }
+      : {}),
+  });
+  const textContentBytes = reg.PbChatTextContent.encode(textContentMsg).finish();
+
+  // 第 4 层外层：PbChatMsgEnvelope（textContent 是 oneof 字段 3）
+  // 通过 decode 再传入保证 oneof 语义正确
+  const envelopeMsg = reg.PbChatMsgEnvelope.create({
+    textContent: reg.PbChatTextContent.decode(textContentBytes),
+  });
+  return reg.PbChatMsgEnvelope.encode(envelopeMsg).finish();
+}
+
+/**
+ * 构造多媒体聊天信封的 PbChatMsgEnvelope bytes（richMediaContent / fileContent / audioContent 分支）。
+ *
+ * 只产出"第 4 层" envelope bytes，不涉及 clientMsgId / 外层包装。
+ * 调用方（或重发场景）只需关心媒体元信息，不需要提前确定 clientMsgId。
+ *
+ * 注意：内部会独立生成 attachmentId（与 clientMsgId 无关），保持与历史行为一致。
+ */
+export async function buildMediaEnvelopeBytes(params: OutboundMediaParams): Promise<Uint8Array> {
+  const reg = await getRegistry();
+  const attachmentId = genClientMsgId(); // 独立生成 attachmentId，保持历史行为
+
+  // 构造 PbChatFileMeta（含可选的 E2EE 加密字段）
+  const fileMeta = reg.PbChatFileMeta.create({
+    url: params.url,
+    fileType: params.mimeType ?? '',
+    mediaType: MEDIA_TYPE_MAP[params.mediaType],
+    attachmentId,
+    ...(params.fileKey ? { key: params.fileKey } : {}),
+    ...(params.fileIv ? { iv: params.fileIv } : {}),
+    ...(params.fileDigest ? { digest: params.fileDigest } : {}),
+    ...(params.plaintextLength != null ? { plaintextLength: params.plaintextLength } : {}),
+    ...(params.expireTime != null ? { expireTime: params.expireTime } : {}),
+    ...(params.opCreds ? { opCreds: params.opCreds } : {}),
+    ...(params.length != null ? { length: params.length } : {}),
+  });
+
+  let envelopeFields: Record<string, unknown>;
+
+  if (params.mediaType === 'audio') {
+    // 音频 → PbChatAudioContent → audioContent（oneof 字段 4）
+    const audioContent = reg.PbChatAudioContent.create({
+      meta: { attachmentId, duration: 0, fileMeta },
+    });
+    envelopeFields = { audioContent };
+  } else {
+    // 图片 / 视频 / 文件 → PbChatRichMediaContent
+    const richMedia = reg.PbChatRichMediaContent.create({
+      meta: [
+        {
+          attachmentId,
+          mediaType: MEDIA_TYPE_MAP[params.mediaType],
+          fileMeta,
+          ...(params.width != null ? { width: params.width } : {}),
+          ...(params.height != null ? { height: params.height } : {}),
+          ...(params.blurHash ? { blurHash: params.blurHash } : {}),
+          ...(params.fileName ? { fileName: params.fileName } : {}),
+          ...(params.fileSize != null ? { fileSize: params.fileSize } : {}),
+          ...(params.caption ? { caption: params.caption } : {}),
+        },
+      ],
+      ...(params.caption ? { caption: params.caption } : {}),
+    });
+
+    if (params.mediaType === 'file') {
+      envelopeFields = { fileContent: richMedia }; // oneof 字段 13
+    } else {
+      envelopeFields = { richMediaContent: richMedia }; // oneof 字段 9
+    }
+  }
+
+  const envelopeMsg = reg.PbChatMsgEnvelope.create(envelopeFields);
+  return reg.PbChatMsgEnvelope.encode(envelopeMsg).finish();
+}
+
+/**
+ * 构造 markdown 聊天信封的 PbChatMsgEnvelope bytes（markdownContent 分支，oneof 字段 16）。
+ *
+ * 只产出"第 4 层" envelope bytes。digest 缺省时写入 "" 以保证 proto3 默认值行为。
+ */
+export async function buildMarkdownEnvelopeBytes(
+  params: Pick<OutboundMarkdownParams, 'markdown' | 'digest'>,
+): Promise<Uint8Array> {
+  const reg = await getRegistry();
+
+  // 第 4 层内层：PbMarkdownContent → bytes
+  const markdownMsg = reg.PbMarkdownContent.create({
+    digest: params.digest ?? '',
+    markdown: params.markdown,
+  });
+  const markdownBytes = reg.PbMarkdownContent.encode(markdownMsg).finish();
+
+  // 第 4 层外层：PbChatMsgEnvelope（markdownContent 是 oneof 字段 16）
+  const envelopeMsg = reg.PbChatMsgEnvelope.create({
+    markdownContent: reg.PbMarkdownContent.decode(markdownBytes),
+  });
+  return reg.PbChatMsgEnvelope.encode(envelopeMsg).finish();
+}
+
+/**
+ * 构造 decryptError 操作信令的 PbChatOperationEnvelope bytes（decryptError 分支，oneof 字段 5）。
+ *
+ * 由"解密失败方"发回给"原发送方"的反向信令，走 `envelopeType=2` 操作消息通道。
+ * 只产出"第 4 层" envelope bytes；后续需要通过 `encodeSingleChatReqPacket`
+ * （配合 E2EE 加密）包装成完整 PbPacket 再发送。
+ *
+ * 字段方向语义：
+ *   - e2eeId       = 信令发送方自己的 e2eeId（= 解密失败消息的接收者设备）
+ *   - otherE2eeId  = 失败消息的原发送方 e2eeId（= 信令接收方）
+ *
+ * @param content decryptError 信令三元组
+ * @returns       PbChatOperationEnvelope 编码后的 bytes
+ */
+export async function buildDecryptErrorEnvelopeBytes(content: {
+  clientMsgId: string;
+  e2eeId: string;
+  otherE2eeId: string;
+}): Promise<Uint8Array> {
+  const reg = await getRegistry();
+
+  // 第 4 层内层：PbMessageDecryptErrorSendContent → bytes
+  const decryptErrorMsg = reg.PbMessageDecryptErrorSendContent.create({
+    clientMsgId: content.clientMsgId,
+    e2eeId: content.e2eeId,
+    otherE2eeId: content.otherE2eeId,
+  });
+  const decryptErrorBytes = reg.PbMessageDecryptErrorSendContent.encode(decryptErrorMsg).finish();
+
+  // 第 4 层外层：PbChatOperationEnvelope(decryptError) → bytes
+  // decryptError 是 oneof content 的字段 5，通过 decode 再传入保证 oneof 语义正确
+  const opEnvelopeMsg = reg.PbChatOperationEnvelope.create({
+    decryptError: reg.PbMessageDecryptErrorSendContent.decode(decryptErrorBytes),
+  });
+  return reg.PbChatOperationEnvelope.encode(opEnvelopeMsg).finish();
+}
+
+/**
+ * 构造已读操作信令的 PbChatOperationEnvelope bytes（msgRead 分支，oneof 字段 7）。
+ *
+ * 由插件在回复用户消息成功后发送，标记用户原始消息为已读。
+ * 走 `envelopeType=2` 操作消息通道，明文传输（`e2eeFlag=false`）。
+ */
+export async function buildMsgReadEnvelopeBytes(params: {
+  targetClientMsgIds: string[];
+  readStamp: number;
+}): Promise<Uint8Array> {
+  const reg = await getRegistry();
+
+  // 第 4 层内层：PbMsgReadStampSendContent → bytes
+  const msgReadMsg = reg.PbMsgReadStampSendContent.create({
+    clientMsgIds: params.targetClientMsgIds,
+    readStamp: params.readStamp,
+  });
+  const msgReadBytes = reg.PbMsgReadStampSendContent.encode(msgReadMsg).finish();
+
+  // 第 4 层外层：PbChatOperationEnvelope(msgRead) → bytes
+  // msgRead 是 oneof content 的字段 7，通过 decode 再传入保证 oneof 语义正确
+  const opEnvelopeMsg = reg.PbChatOperationEnvelope.create({
+    msgRead: reg.PbMsgReadStampSendContent.decode(msgReadBytes),
+  });
+  return reg.PbChatOperationEnvelope.encode(opEnvelopeMsg).finish();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 第 1~3 层：单聊请求包的通用装箱（E2EE / 明文共用入口）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 将任意 envelope bytes 包装为完整的 PbPacket(CLIENT_REQ) 二进制。
+ *
+ * 包装链路：
+ *   envelopeBytes
+ *     → PbSingleChatMsgReqBody(fromId, toId, clientMsgId, envelopeType, e2eeFlag, envelope)
+ *       → PbRequest(path="/api/im/chat/bot", reqId=clientMsgId, body)
+ *         → PbPacket(type=CLIENT_REQ=0, request)
+ *
+ * 适用场景：
+ *   - 明文单聊消息：传入 `buildChatEnvelopeBytes` 产出，`e2eeFlag=false`。
+ *   - E2EE 单聊消息：传入 `PbSingleChatMsgRecipients` bytes，`e2eeFlag=true` + `fromE2eeId`。
+ *   - 操作信令：传入 `PbChatOperationEnvelope` bytes，`envelopeType=2`。
+ *
+ * @param args.envelopeBytes 第 4 层信封的 bytes（明文 envelope 或 E2EE recipients bytes）
+ * @param args.envelopeType  信封类型，1=聊天消息（默认），2=操作信令
+ * @param args.fromE2eeId    发送方 e2eeId；仅在 `e2eeFlag=true` 时需要
+ */
+export async function encodeSingleChatReqPacket(args: {
+  fromId: string;
+  to: string;
+  clientMsgId: string;
+  envelopeBytes: Uint8Array;
+  e2eeFlag: boolean;
+  fromE2eeId?: string;
+  envelopeType?: 1 | 2;
+}): Promise<Uint8Array> {
+  const reg = await getRegistry();
+  const clientStamp = Date.now();
+  const envelopeType = args.envelopeType ?? 1;
+
+  // 第 3 层：PbSingleChatMsgReqBody → bytes
+  const reqBodyMsg = reg.PbSingleChatMsgReqBody.create({
+    fromId: args.fromId,
+    toId: args.to,
+    clientMsgId: args.clientMsgId,
+    clientStamp,
+    envelopeType,
+    e2eeFlag: args.e2eeFlag,
+    ...(args.fromE2eeId ? { fromE2eeId: args.fromE2eeId } : {}),
+    envelope: args.envelopeBytes,
+  });
+  const reqBodyBytes = reg.PbSingleChatMsgReqBody.encode(reqBodyMsg).finish();
+
+  // 第 2 层：PbRequest → bytes（path 对应文档 §一 请求体结构）
+  const requestMsg = reg.PbRequest.create({
+    path: '/api/im/chat/bot',
+    reqId: args.clientMsgId,
+    reqStamp: clientStamp,
+    body: reqBodyBytes,
+  });
+  const requestBytes = reg.PbRequest.encode(requestMsg).finish();
+
+  // 第 1 层：PbPacket(type=CLIENT_REQ=0) → bytes
+  const packetMsg = reg.PbPacket.create({
+    type: 0, // CLIENT_REQ
+    request: reg.PbRequest.decode(requestBytes),
+  });
+  return reg.PbPacket.encode(packetMsg).finish();
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 公开 API（保留既有签名，实现委托给纯函数）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 将发送参数编码为 imwe 协议四层包装的 protobuf 二进制（明文路径）。
+ *
+ * 首次调用时会触发 .proto 文件加载（约几毫秒），后续调用使用缓存。
+ *
+ * @param to     接收方 userId
+ * @param text   消息文本内容
+ * @param fromId 发送方 ID（机器人的 botAcctId，来自 getMe 响应）；为空时平台从 ApiKey 解析
+ * @returns 编码后的 protobuf 二进制，直接作为 HTTP 请求体发送
+ */
+export async function encodeSendRequest(
+  to: string,
+  text: string,
+  fromId = '',
+  options?: { referenceClientMsgId?: string; clientMsgId?: string },
+): Promise<Uint8Array> {
+  const clientMsgId = options?.clientMsgId ?? genClientMsgId();
+  const envelopeBytes = await buildChatEnvelopeBytes(
+    text,
+    options?.referenceClientMsgId
+      ? { referenceClientMsgId: options.referenceClientMsgId }
+      : undefined,
+  );
+  return encodeSingleChatReqPacket({
+    fromId,
+    to,
+    clientMsgId,
+    envelopeBytes,
+    e2eeFlag: false,
+  });
+}
+
+/**
+ * 将多媒体消息参数编码为 imwe 协议四层包装的 protobuf 二进制（明文路径）。
+ */
+export async function encodeMediaSendRequest(params: OutboundMediaParams): Promise<Uint8Array> {
+  const clientMsgId = params.clientMsgId ?? genClientMsgId();
+  const envelopeBytes = await buildMediaEnvelopeBytes(params);
+  return encodeSingleChatReqPacket({
+    fromId: params.fromId ?? '',
+    to: params.to,
+    clientMsgId,
+    envelopeBytes,
+    e2eeFlag: false,
+  });
+}
+
+/**
+ * 将 markdown 消息参数编码为 imwe 协议四层包装的 protobuf 二进制（明文路径）。
+ */
+export async function encodeMarkdownSendRequest(
+  params: OutboundMarkdownParams,
+): Promise<Uint8Array> {
+  const clientMsgId = params.clientMsgId ?? genClientMsgId();
+  const envelopeBytes = await buildMarkdownEnvelopeBytes({
+    markdown: params.markdown,
+    ...(params.digest !== undefined ? { digest: params.digest } : {}),
+  });
+  return encodeSingleChatReqPacket({
+    fromId: params.fromId ?? '',
+    to: params.to,
+    clientMsgId,
+    envelopeBytes,
+    e2eeFlag: false,
+  });
+}
+
+/**
+ * 将 typing signal 参数编码为 imwe 协议四层包装的 protobuf 二进制。
+ *
+ * 包装链路（从内到外）：
+ *   PbBotThinkingSignal(status, botImAcctId)
+ *     → PbChatOperationEnvelope(botThinking=...)
+ *       → PbSingleChatMsgReqBody(envelopeType=2, envelope=...)
+ *         → PbRequest(path="/api/im/chat/bot", body=...)
+ *           → PbPacket(type=CLIENT_REQ=0, request=...)
+ *
+ * typing signal 走操作消息通道（envelopeType=2），按 R14 保持明文。
+ *
+ * @param to          接收方 userId
+ * @param status      1=begin（开始输入），2=end（结束输入）
+ * @param botImAcctId Bot 的 imAcctId，标识哪个 bot 正在输入
+ * @param fromId      发送方 ID（机器人的 botAcctId）；为空时平台从 ApiKey 解析
+ * @returns 编码后的 protobuf 二进制，直接作为 HTTP 请求体发送
+ */
+export async function encodeTypingSignalRequest(
+  to: string,
+  status: 1 | 2,
+  botImAcctId: string,
+  fromId = '',
+): Promise<Uint8Array> {
+  const reg = await getRegistry();
+  const clientMsgId = genClientMsgId();
+
+  // 第 4 层内层：PbBotThinkingSignal → bytes
+  const signalMsg = reg.PbBotThinkingSignal.create({ status, botImAcctId });
+  const signalBytes = reg.PbBotThinkingSignal.encode(signalMsg).finish();
+
+  // 第 4 层外层：PbChatOperationEnvelope(botThinking) → bytes
+  // botThinking 是 oneof content 的字段 9，通过 decode 再传入保证 oneof 语义正确
+  const opEnvelopeMsg = reg.PbChatOperationEnvelope.create({
+    botThinking: reg.PbBotThinkingSignal.decode(signalBytes),
+  });
+  const opEnvelopeBytes = reg.PbChatOperationEnvelope.encode(opEnvelopeMsg).finish();
+
+  return encodeSingleChatReqPacket({
+    fromId,
+    to,
+    clientMsgId,
+    envelopeBytes: opEnvelopeBytes,
+    e2eeFlag: false,
+    envelopeType: 2,
+  });
+}
+
+/**
+ * 将平台返回的发送响应解码为 ImweSendResponse。
+ *
+ * 响应体结构（对应文档 §一）：
+ *   平台返回的 HTTP 响应体直接是 PbResponse 的 protobuf 二进制：
+ *     PbResponse.statusCode  200=成功，其他=失败
+ *     PbResponse.body        PbMsgRspBody 的 protobuf 二进制（含 serverMsgId）
+ *
+ * 注意：响应体不包含外层 PbPacket 包装，直接从 PbResponse 开始解码。
+ *
+ * @param bytes POST /api/im/open/bot/sendMessage 响应体的原始字节（PbResponse 编码）
+ * @returns 解码后的发送结果
+ */
+export async function decodeSendResponse(bytes: Uint8Array): Promise<ImweSendResponse> {
+  const reg = await getRegistry();
+
+  // 直接解码 PbResponse（响应体不含外层 PbPacket 包装）
+  const response = reg.PbResponse.decode(bytes) as unknown as {
+    statusCode: number | bigint;
+    body?: Uint8Array;
+  };
+
+  const statusCode = Number(response?.statusCode ?? 0);
+  const ok = statusCode === 200;
+
+  if (!ok || !response?.body?.length) {
+    return { ok };
+  }
+
+  // PbResponse.body → PbMsgRspBody（含 serverMsgId / serverStamp）
+  const rspBody = reg.PbMsgRspBody.decode(response.body) as unknown as {
+    serverMsgId?: string;
+  };
+
+  return {
+    ok,
+    ...(rspBody.serverMsgId ? { msgId: rspBody.serverMsgId } : {}),
+  };
+}