@imweapp/openclaw-imwe 2026.4.12-alpha.1

package/src/api-client.ts

@@ -0,0 +1,740 @@
+/**
+ * api-client.ts — imwe Open API HTTP 客户端
+ *
+ * 对应接口文档：docs/02-OpenAPI接口设计.md
+ * Base URL：/api/im/open/bot
+ *
+ * ── 传输格式 ──────────────────────────────────────────────────────────────────
+ *   sendMessage / pullMessages：application/x-protobuf
+ *   getMe 等 JSON 接口：        application/json
+ *
+ * ── 鉴权机制（文档 §1） ───────────────────────────────────────────────────────
+ *   每个请求携带三个 Header：
+ *     X-Api-Key:   API Key（ak_ 前缀）
+ *     X-Timestamp: 毫秒级时间戳字符串
+ *     X-Signature: Base64(HMAC-SHA256(apiSecret, signString))
+ *
+ *   签名原文（signString）：
+ *     {METHOD}&{PATH}&{TIMESTAMP}&{BODY_HASH}
+ *     BODY_HASH = hex(SHA-256(body))，body 为空时对空字符串 "" 哈希
+ *
+ * ── 设计原则 ──────────────────────────────────────────────────────────────────
+ *   - 纯函数，不持有状态
+ *   - Protobuf encode/decode 集中在 src/proto/codec.ts，此文件只负责 HTTP 传输
+ *   - 请求失败时抛出带 HTTP 状态码的 Error，由上层决定是否重试
+ */
+
+import { createHmac, createHash, randomUUID } from 'node:crypto';
+import {
+  decodeSendResponse,
+  encodeSendRequest,
+  encodeMediaSendRequest,
+  encodeMarkdownSendRequest,
+  encodeTypingSignalRequest,
+  decodeInboundPacket,
+  genClientMsgId,
+} from './proto/codec.js';
+import { decodeInboundPacketWithE2ee } from './proto/inbound.codec.js';
+import type { E2eeDecryptFn } from './proto/inbound.codec.js';
+import type { OutboundMediaParams } from './proto/codec.js';
+import { getRegistry } from './proto/registry.js';
+import type { ImweInboundMessage, ImweSendResponse } from './types.js';
+import { uploadMediaToStorage } from './media-upload.js';
+import { inferMediaType, inferMediaTypeFromMime } from './media-utils.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 签名工具（文档 §1.2）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 计算请求签名。
+ *
+ * 签名原文：{METHOD}&{PATH}&{TIMESTAMP}&{BODY_HASH}
+ *   - METHOD：HTTP 方法大写，固定为 "POST"
+ *   - PATH：请求路径，如 "/api/im/open/bot/sendMessage"
+ *   - TIMESTAMP：与 X-Timestamp Header 相同的毫秒时间戳字符串
+ *   - BODY_HASH：hex(SHA-256(body))，body 为空时对空字符串 "" 哈希
+ *
+ * 签名算法：Base64(HMAC-SHA256(apiSecret, signString))
+ *
+ * @param params.apiSecret  API Secret（创建机器人时返回，明文仅展示一次）
+ * @param params.method     HTTP 方法（大写），通常为 "POST"
+ * @param params.path       请求路径，如 "/api/im/open/bot/sendMessage"
+ * @param params.timestamp  毫秒时间戳字符串，与 X-Timestamp Header 一致
+ * @param params.body       请求体字节（Protobuf 二进制或 JSON 字符串的 UTF-8 编码）
+ * @returns Base64 编码的 HMAC-SHA256 签名字符串
+ */
+export function buildSignature(params: {
+  apiSecret: string;
+  method: string;
+  path: string;
+  timestamp: string;
+  body: Uint8Array;
+}): string {
+  // 1. 计算请求体的 SHA-256 哈希（小写 hex）
+  //    body 为空时对空字符串 "" 哈希（SHA-256("") 是固定值）
+  const bodyHash = createHash('sha256').update(params.body).digest('hex');
+
+  // 2. 拼接签名原文
+  const signString = [params.method, params.path, params.timestamp, bodyHash].join('&');
+
+  // 3. HMAC-SHA256 签名，输出 Base64
+  return createHmac('sha256', params.apiSecret).update(signString, 'utf8').digest('base64');
+}
+
+/**
+ * 构造鉴权 Header 集合。
+ *
+ * @param apiKey    API Key（ak_ 前缀）
+ * @param apiSecret API Secret
+ * @param method    HTTP 方法（大写）
+ * @param path      请求路径（含前导 /）
+ * @param body      请求体字节
+ * @returns 包含 X-Api-Key / X-Timestamp / X-Signature 的 Header 对象
+ */
+function buildAuthHeaders(
+  apiKey: string,
+  apiSecret: string,
+  method: string,
+  path: string,
+  body: Uint8Array,
+): Record<string, string> {
+  // 毫秒级时间戳（文档要求毫秒，服务端校验 5 分钟窗口）
+  const timestamp = String(Date.now());
+  const signature = buildSignature({ apiSecret, method, path, timestamp, body });
+  return {
+    'X-Api-Key': apiKey,
+    'X-Timestamp': timestamp,
+    'X-Signature': signature,
+    reqid: randomUUID().replaceAll('-', ''),
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// 内部工具：统一 HTTP 请求
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 发送 Protobuf 二进制请求，返回响应体字节。
+ *
+ * Content-Type: application/x-protobuf
+ * Accept:       application/x-protobuf
+ *
+ * @param apiBaseUrl  API 基础地址，如 https://api.imwe.example.com
+ * @param path        请求路径，如 /api/im/open/bot/sendMessage
+ * @param body        Protobuf 编码的请求体
+ * @param auth        鉴权凭证（apiKey + apiSecret）
+ * @param opts.timeoutMs  请求超时（毫秒），默认不超时
+ * @throws 非 2xx 响应时抛出包含状态码的 Error
+ */
+export async function postProto(
+  apiBaseUrl: string,
+  path: string,
+  body: Uint8Array,
+  auth: { apiKey: string; apiSecret: string },
+  opts?: { timeoutMs?: number },
+): Promise<Uint8Array> {
+  const url = `${apiBaseUrl.replace(/\/$/, '')}${path}`;
+
+  const controller = new AbortController();
+  const timer = opts?.timeoutMs ? setTimeout(() => controller.abort(), opts.timeoutMs) : null;
+
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-protobuf',
+        Accept: 'application/x-protobuf',
+        ...buildAuthHeaders(auth.apiKey, auth.apiSecret, 'POST', path, body),
+      },
+      body: body as BodyInit,
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      const errText = await res.text().catch(() => '');
+      throw new Error(`imwe API ${path} 返回 ${res.status}: ${errText}`);
+    }
+
+    const buf = await res.arrayBuffer();
+    return new Uint8Array(buf);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+}
+
+/**
+ * 发送 JSON 请求，返回解析后的 JSON 对象。
+ *
+ * Content-Type: application/json
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param path        请求路径
+ * @param body        请求体对象（会被 JSON.stringify）
+ * @param auth        鉴权凭证
+ * @param opts.timeoutMs  请求超时（毫秒）
+ * @throws 非 2xx 响应时抛出包含状态码的 Error
+ */
+export async function postJson<T>(
+  apiBaseUrl: string,
+  path: string,
+  body: Record<string, unknown>,
+  auth: { apiKey: string; apiSecret: string },
+  opts?: { timeoutMs?: number },
+): Promise<T> {
+  const url = `${apiBaseUrl.replace(/\/$/, '')}${path}`;
+  const bodyStr = JSON.stringify(body);
+  const bodyBytes = new TextEncoder().encode(bodyStr);
+
+  const controller = new AbortController();
+  const timer = opts?.timeoutMs ? setTimeout(() => controller.abort(), opts.timeoutMs) : null;
+
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        ...buildAuthHeaders(auth.apiKey, auth.apiSecret, 'POST', path, bodyBytes),
+      },
+      body: bodyStr,
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      const errText = await res.text().catch(() => '');
+      throw new Error(`imwe API ${path} 返回 ${res.status}: ${errText}`);
+    }
+
+    return res.json() as Promise<T>;
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// getMe — 获取当前机器人信息（文档 §三）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 机器人信息（对应 getMe 接口响应）
+ */
+export type BotInfo = {
+  /** 机器人记录 UUID */
+  id: string;
+  /** 机器人用户 ID，如 "bot_1776166649" */
+  botUserId: string;
+  /** 机器人 IM 账户 ID（mainAcctId），如 "bot_AC_bot_1776166649" */
+  botMainAcctId: string;
+  /**
+   * 机器人 IM 账户 ID（mainAcctId），如 "bot_AC_bot_1776166649"。
+   * pullMessages 时作为 PbBoxPullReq.boxId 使用。
+   */
+  botAcctId: string;
+  /** 创建者用户 ID */
+  creatorUserId: string;
+  /** 机器人名称 */
+  botName: string;
+  /** 机器人描述 */
+  description?: string;
+  /** 头像 URL */
+  avatarUrl?: string;
+  /** 状态：1=启用 */
+  status: number;
+  /** 是否启用 E2EE；未启用时服务端可能省略该字段 */
+  e2eeEnabled?: boolean;
+  /** 创建时间（毫秒时间戳） */
+  createTime: number;
+  /** 更新时间（毫秒时间戳） */
+  updateTime: number;
+};
+
+/**
+ * 获取当前机器人信息。
+ *
+ * 对应接口：POST /api/im/open/bot/getMe
+ * 返回的 botAcctId 是机器人的 mainAcctId，pullMessages 时作为 boxId 使用。
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param auth        鉴权凭证
+ * @returns 机器人信息
+ * @throws 鉴权失败或网络错误时抛出 Error
+ */
+export async function getMe(
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+): Promise<BotInfo> {
+  return postJson<BotInfo>(apiBaseUrl, '/api/im/open/bot/getMe', {}, auth);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// pullMessages — 事件箱拉取消息（文档 §二）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 事件箱拉取状态（用于增量同步）
+ */
+export type PullState = {
+  /**
+   * 下次拉取的起始序列号。
+   * 初始值为 0（从头同步），每次收到 milestone=true 的响应后更新为 endSeq+1。
+   *
+   * 使用 number 而非 bigint：protobufjs 的 uint64 字段期望 number 或 Long 对象，
+   * 传入原生 bigint 会触发 "Do not know how to serialize a BigInt" 错误。
+   * uint64 的安全整数范围（< 2^53）对事件箱序列号完全够用。
+   */
+  nextStartSeq: number;
+};
+
+/**
+ * 通过事件箱模式拉取机器人待处理消息。
+ *
+ * 对应接口：POST /api/im/open/bot/pullMessages
+ * 请求体：PbBoxPullReq（直接序列化，不包装在 PbPacket 中）
+ * 响应体：PbBoxPullRsp
+ *
+ * 增量拉取流程：
+ *   1. 首次调用：state.nextStartSeq=0，拉取全部历史消息
+ *   2. 响应 milestone=true：将 endSeq 落库，下次从 endSeq+1 开始
+ *   3. 响应 hasMore=true：立即继续拉取（调用方负责循环）
+ *   4. 响应 endSeq=0：无新消息
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param auth        鉴权凭证
+ * @param boxId       事件箱 ID（机器人的 botAcctId/mainAcctId，来自 getMe 响应）
+ * @param state       拉取状态（含 nextStartSeq，调用方负责持久化）
+ * @returns 解包后的消息列表、更新后的状态、是否还有更多数据
+ */
+export async function pullMessages(
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+  boxId: string,
+  state: PullState,
+  opts?: { e2eeDecrypt?: E2eeDecryptFn },
+): Promise<{ messages: ImweInboundMessage[]; state: PullState; hasMore: boolean }> {
+  const reg = await getRegistry();
+
+  // 构造 PbBoxPullReq
+  const reqMsg = reg.PbBoxPullReq.create({
+    boxId,
+    startSeq: state.nextStartSeq,
+  });
+  const requestBody = reg.PbBoxPullReq.encode(reqMsg).finish();
+
+  const responseBytes = await postProto(
+    apiBaseUrl,
+    '/api/im/open/bot/pullMessages',
+    requestBody,
+    auth,
+  );
+
+  // 解码 PbBoxPullRsp
+  // protobufjs 将 uint64 字段解码为 Long 对象（来自 long 包），用 Number() 转换为 number
+  const rsp = reg.PbBoxPullRsp.decode(responseBytes) as unknown as {
+    boxId: string;
+    startSeq: { toNumber(): number } | number;
+    endSeq: { toNumber(): number } | number;
+    milestone: boolean;
+    hasMore: boolean;
+    items: Array<{
+      path?: string;
+      reqId?: string;
+      reqStamp?: { toNumber(): number } | number;
+      body?: Uint8Array;
+    }>;
+  };
+
+  // Long 对象用 toNumber()，普通 number 直接用，统一转为 number
+  const toNum = (v: { toNumber(): number } | number | undefined): number =>
+    v == null ? 0 : typeof v === 'number' ? v : v.toNumber();
+
+  const endSeq = toNum(rsp.endSeq);
+  const hasMore = rsp.hasMore ?? false;
+
+  // milestone=true 且 endSeq>0 时更新游标，下次从 endSeq+1 开始
+  const nextStartSeq = rsp.milestone && endSeq > 0 ? endSeq + 1 : state.nextStartSeq;
+
+  // 解包每条消息：item.body → PbChatMsgDeliverBody → PbChatMsgEnvelope → text
+  const messages: ImweInboundMessage[] = [];
+  for (const item of rsp.items ?? []) {
+    if (!item.body || item.body.length === 0) {
+      continue;
+    }
+
+    // item.body 是 PbChatMsgDeliverBody 的字节，需要包装成 PbPacket(SERVER_REQ) 再走四层解包
+    // 按文档：items[].request.body 为 PbChatMsgDeliverBody
+    // 构造一个虚拟的 PbPacket(SERVER_REQ) 供 decodeInboundPacket 使用
+    const requestMsg = reg.PbRequest.create({
+      path: '/chat/deliver',
+      reqId: item.reqId ?? '',
+      reqStamp: toNum(item.reqStamp),
+      body: item.body,
+    });
+    const requestBytes = reg.PbRequest.encode(requestMsg).finish();
+
+    const packetMsg = reg.PbPacket.create({
+      type: 2, // SERVER_REQ
+      request: reg.PbRequest.decode(requestBytes),
+    });
+    const packetBytes = reg.PbPacket.encode(packetMsg).finish();
+
+    const result = opts?.e2eeDecrypt
+      ? await decodeInboundPacketWithE2ee(packetBytes, { e2eeDecrypt: opts.e2eeDecrypt })
+      : await decodeInboundPacket(packetBytes);
+    if (result.ok) {
+      messages.push(result.message);
+    }
+    // result.ok=false 时静默跳过（操作消息、非文本消息、decrypt-failed、operation-consumed 等）
+  }
+
+  return {
+    messages,
+    state: { nextStartSeq },
+    hasMore,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// sendMessage — 发送单聊消息（文档 §一）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 向用户发送单聊文字消息。
+ *
+ * 对应接口：POST /api/im/open/bot/sendMessage
+ * 请求体：PbPacket(CLIENT_REQ) 四层包装（由 encodeSendRequest 生成）
+ * 响应体：PbResponse 的 protobuf 二进制（statusCode + body），body 为 PbMsgRspBody
+ *
+ * 四层包装链路（由 send.codec.ts 负责）：
+ *   PbChatTextContent(text)
+ *     → PbChatMsgEnvelope(textContent)
+ *       → PbSingleChatMsgReqBody(fromId, toId, envelopeType=1, e2eeFlag=false, envelope)
+ *         → PbRequest(path="/api/im/chat/bot", body)
+ *           → PbPacket(type=CLIENT_REQ=0, request)
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param auth        鉴权凭证
+ * @param fromId      发送方 ID（机器人的 botAcctId，来自 getMe 响应）
+ * @param to          接收方用户 ID
+ * @param text        消息文本内容
+ * @returns 发送结果
+ */
+export async function sendTextMessage(
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+  fromId: string,
+  to: string,
+  text: string,
+  options?: { replyToId?: string; clientMsgId?: string },
+): Promise<ImweSendResponse> {
+  const clientMsgId = options?.clientMsgId ?? genClientMsgId();
+  // encodeSendRequest 负责四层包装，fromId 传入供 PbSingleChatMsgReqBody 使用
+  const requestBody = await encodeSendRequest(to, text, fromId, {
+    referenceClientMsgId: options?.replyToId,
+    clientMsgId,
+  });
+
+  const responseBytes = await postProto(
+    apiBaseUrl,
+    '/api/im/open/bot/sendMessage',
+    requestBody,
+    auth,
+  );
+
+  return {
+    ...(await decodeSendResponse(responseBytes)),
+    clientMsgId,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// sendMediaMessage — 发送多媒体消息（文档 §一）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 向用户发送多媒体消息（图片/视频/音频/文件）。
+ *
+ * 使用与 sendTextMessage 相同的 HTTP 接口和鉴权机制，
+ * 区别在于 PbChatMsgEnvelope 的 oneof 字段为 richMediaContent/fileContent/audioContent。
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param auth        鉴权凭证
+ * @param media       多媒体消息参数（含 to、url、mediaType 等）
+ * @returns 发送结果
+ */
+export async function sendMediaMessage(
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+  media: OutboundMediaParams,
+): Promise<ImweSendResponse> {
+  const clientMsgId = media.clientMsgId ?? genClientMsgId();
+  const requestBody = await encodeMediaSendRequest({
+    ...media,
+    clientMsgId,
+  });
+
+  const responseBytes = await postProto(
+    apiBaseUrl,
+    '/api/im/open/bot/sendMessage',
+    requestBody,
+    auth,
+  );
+
+  return {
+    ...(await decodeSendResponse(responseBytes)),
+    clientMsgId,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// sendMarkdownMessage — 发送 markdown 消息（文档 §一）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 向用户发送 markdown 格式消息。
+ *
+ * 使用与 sendTextMessage / sendMediaMessage 相同的 HTTP 接口和鉴权机制，
+ * 区别在于 PbChatMsgEnvelope 的 oneof 字段为 markdownContent（字段 16）。
+ *
+ * 四层包装链路（由 send.codec.ts::encodeMarkdownSendRequest 负责）：
+ *   PbMarkdownContent(digest, markdown)
+ *     → PbChatMsgEnvelope(markdownContent=...)
+ *       → PbSingleChatMsgReqBody(envelopeType=1, e2eeFlag=false)
+ *         → PbRequest(path="/api/im/chat/bot")
+ *           → PbPacket(type=CLIENT_REQ=0)
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param auth        鉴权凭证
+ * @param params      markdown 消息参数：fromId / to / markdown / digest? / clientMsgId?
+ * @returns 发送结果
+ */
+export async function sendMarkdownMessage(
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+  params: {
+    fromId: string;
+    to: string;
+    markdown: string;
+    digest?: string;
+    clientMsgId?: string;
+  },
+): Promise<ImweSendResponse> {
+  const clientMsgId = params.clientMsgId ?? genClientMsgId();
+  const requestBody = await encodeMarkdownSendRequest({
+    to: params.to,
+    fromId: params.fromId,
+    markdown: params.markdown,
+    digest: params.digest,
+    clientMsgId,
+  });
+
+  const responseBytes = await postProto(
+    apiBaseUrl,
+    '/api/im/open/bot/sendMessage',
+    requestBody,
+    auth,
+  );
+
+  return {
+    ...(await decodeSendResponse(responseBytes)),
+    clientMsgId,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// sendMediaMessageWithUpload — 上传并发送多媒体消息（deliver 回调专用）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 上传并发送多媒体消息。
+ *
+ * 与 sendMediaMessage 的区别：包含 uploadMediaToStorage 上传步骤。
+ * 与 sendImweMedia（send.ts）的区别：不走账号解析，直接接收已解析的连接参数。
+ * 适用于 monitor.ts 的 deliver 回调，此时账号信息已在上下文中。
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param auth        鉴权凭证
+ * @param fromId      发送方 ID（机器人的 botAcctId）
+ * @param to          接收方用户 ID
+ * @param mediaUrl    媒体文件 URL（本地路径或远程 URL）
+ * @param options     可选参数（caption 等）
+ * @returns 发送结果
+ */
+export async function sendMediaMessageWithUpload(
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+  fromId: string,
+  to: string,
+  mediaUrl: string,
+  options?: {
+    caption?: string;
+    /** 日志接口（可选） */
+    log?: { info?: (...args: unknown[]) => void; warn?: (...args: unknown[]) => void };
+  },
+): Promise<ImweSendResponse> {
+  const log = options?.log;
+
+  // 上传到平台存储
+  log?.info?.(`[sendMediaMessageWithUpload] 开始上传: mediaUrl=${mediaUrl.slice(0, 80)}, to=${to}`);
+  const uploadResult = await uploadMediaToStorage(mediaUrl, auth, apiBaseUrl, {
+    imMainAccId: to,
+    log,
+  });
+  log?.info?.(
+    `[sendMediaMessageWithUpload] 上传完成: url=${uploadResult.url.slice(0, 80)}, contentType=${uploadResult.contentType}, fileSize=${uploadResult.fileSize}`,
+  );
+
+  // 优先从上传结果的 contentType 推断媒体类型，回退到原始 URL 后缀推断
+  // 注意：不能用 uploadResult.url（CDN URL 可能无扩展名，会永远回退为 'file'）
+  const mediaType = uploadResult.contentType
+    ? inferMediaTypeFromMime(uploadResult.contentType)
+    : inferMediaType(mediaUrl);
+  log?.info?.(`[sendMediaMessageWithUpload] 推断 mediaType=${mediaType}, 准备发送`);
+
+  return sendMediaMessage(apiBaseUrl, auth, {
+    to,
+    fromId,
+    url: uploadResult.url,
+    mediaType,
+    mimeType: uploadResult.contentType,
+    fileSize: uploadResult.fileSize,
+    caption: options?.caption,
+    blurHash: uploadResult.blurHash,
+    width: uploadResult.width,
+    height: uploadResult.height,
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// uploadPreSignedUrl — 获取文件上传预签名地址（文档 §六）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 预签名上传地址响应 */
+export type PreSignedUrlResult = {
+  fileId: string;
+  preSignedUrl: string;
+  expireTime: number;
+};
+
+/**
+ * 获取文件上传的预签名 URL。
+ * 第三方使用该 URL 直传文件到对象存储（无需经过服务端中转）。
+ *
+ * @param apiBaseUrl    API 基础地址
+ * @param auth          鉴权凭证
+ * @param params        上传参数
+ */
+export async function uploadPreSignedUrl(
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+  params: {
+    imMainAccId: string;
+    fileName: string;
+    fileSize: number;
+    mimeType: string;
+    scene?: string;
+  },
+): Promise<PreSignedUrlResult> {
+  return postJson<PreSignedUrlResult>(
+    apiBaseUrl,
+    '/api/im/open/bot/uploadPreSignedUrl',
+    {
+      imMainAccId: params.imMainAccId,
+      fileName: params.fileName,
+      fileSize: params.fileSize,
+      mimeType: params.mimeType,
+      scene: params.scene ?? 'AI_GC',
+    },
+    auth,
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// uploadConfirm — 文件上传确认（文档 §七）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 上传确认响应 */
+export type UploadConfirmResult = {
+  fileUrl: string;
+  downloadUrl?: string;
+  expireTime?: number;
+};
+
+/**
+ * 文件上传到对象存储后，确认上传完成，获取文件访问地址。
+ *
+ * @param apiBaseUrl    API 基础地址
+ * @param auth          鉴权凭证
+ * @param params        确认参数
+ */
+export async function uploadConfirm(
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+  params: {
+    imMainAccId: string;
+    fileId: string;
+    scene?: string;
+  },
+): Promise<UploadConfirmResult> {
+  return postJson<UploadConfirmResult>(
+    apiBaseUrl,
+    '/api/im/open/bot/uploadConfirm',
+    {
+      imMainAccId: params.imMainAccId,
+      fileId: params.fileId,
+      needDownloadUrl: false,
+      scene: params.scene ?? 'AI_GC',
+    },
+    auth,
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// sendTypingSignal — 发送 typing indicator 信号（文档 §一，envelopeType=2）
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * 向用户发送 typing signal（正在输入指示器）。
+ *
+ * 使用与 sendTextMessage 相同的 HTTP 接口和鉴权机制，
+ * 区别在于 envelopeType=2 和 PbChatOperationEnvelope 信封。
+ *
+ * 四层包装链路（由 send.codec.ts 负责）：
+ *   PbBotThinkingSignal(status, botImAcctId)
+ *     → PbChatOperationEnvelope(botThinking=...)
+ *       → PbSingleChatMsgReqBody(fromId, toId, envelopeType=2, envelope=...)
+ *         → PbRequest(path="/api/im/chat/bot", body=...)
+ *           → PbPacket(type=CLIENT_REQ=0, request=...)
+ *
+ * @param apiBaseUrl  API 基础地址
+ * @param auth        鉴权凭证
+ * @param fromId      发送方 ID（机器人的 botAcctId，来自 getMe 响应）
+ * @param to          接收方用户 ID
+ * @param status      1=begin（开始输入），2=end（结束输入）
+ * @param botImAcctId Bot 的 imAcctId（通常等于 fromId / botAcctId）
+ * @returns 发送结果
+ */
+export async function sendTypingSignal(
+  apiBaseUrl: string,
+  auth: { apiKey: string; apiSecret: string },
+  fromId: string,
+  to: string,
+  status: 1 | 2,
+  botImAcctId: string,
+): Promise<ImweSendResponse> {
+  // encodeTypingSignalRequest 负责四层包装，fromId 传入供 PbSingleChatMsgReqBody 使用
+  const requestBody = await encodeTypingSignalRequest(to, status, botImAcctId, fromId);
+
+  const responseBytes = await postProto(
+    apiBaseUrl,
+    '/api/im/open/bot/sendMessage',
+    requestBody,
+    auth,
+  );
+
+  return decodeSendResponse(responseBytes);
+}