@openclaw/qqbot 2026.5.2-beta.2 → 2026.5.3-beta.1

package/src/engine/api/media.ts

@@ -1,218 +0,0 @@
-/**
- * Media upload API for the QQ Open Platform (small-file direct upload).
- *
- * Key improvements:
- * - Unified `uploadMedia(scope, ...)` replaces `uploadC2CMedia` + `uploadGroupMedia`.
- * - Upload cache integration via composition (passed in constructor).
- * - Uses `withRetry` from the shared retry engine.
- *
- * Chunked upload for files above `LARGE_FILE_THRESHOLD` is tracked by
- * {@link ./media-chunked.ts}; this module currently handles only the
- * one-shot path.
- */
-
-import * as fs from "node:fs";
-import {
-  MediaFileType,
-  type ChatScope,
-  type UploadMediaResponse,
-  type MessageResponse,
-  type EngineLogger,
-} from "../types.js";
-import { ApiClient } from "./api-client.js";
-import { withRetry, UPLOAD_RETRY_POLICY } from "./retry.js";
-import { mediaUploadPath, messagePath, getNextMsgSeq } from "./routes.js";
-import { TokenManager } from "./token.js";
-
-/** Upload cache interface — the caller provides the implementation. */
-export interface UploadCacheAdapter {
-  computeHash: (data: string) => string;
-  get: (hash: string, scope: string, targetId: string, fileType: number) => string | null;
-  set: (
-    hash: string,
-    scope: string,
-    targetId: string,
-    fileType: number,
-    fileInfo: string,
-    fileUuid: string,
-    ttl: number,
-  ) => void;
-}
-
-/** File name sanitizer — injected to avoid importing platform-specific utils. */
-export type SanitizeFileNameFn = (name: string) => string;
-
-interface MediaApiConfig {
-  logger?: EngineLogger;
-  /** Upload cache adapter (optional, omit to disable caching). */
-  uploadCache?: UploadCacheAdapter;
-  /** File name sanitizer. */
-  sanitizeFileName?: SanitizeFileNameFn;
-}
-
-/**
- * Small-file media upload module.
- *
- * Handles base64 and URL-based uploads with optional caching and retry.
- */
-export class MediaApi {
-  private readonly client: ApiClient;
-  private readonly tokenManager: TokenManager;
-  private readonly logger?: EngineLogger;
-  private readonly cache?: UploadCacheAdapter;
-  private readonly sanitize: SanitizeFileNameFn;
-
-  constructor(client: ApiClient, tokenManager: TokenManager, config: MediaApiConfig = {}) {
-    this.client = client;
-    this.tokenManager = tokenManager;
-    this.logger = config.logger;
-    this.cache = config.uploadCache;
-    this.sanitize = config.sanitizeFileName ?? ((n) => n);
-  }
-
-  /**
-   * Upload media via base64, URL, buffer, or local file path to a C2C or Group target.
-   *
-   * The `localPath` and `buffer` branches are equivalent to `fileData` for the
-   * current one-shot implementation — the file is read and base64-encoded
-   * synchronously. They exist as first-class inputs so that a future chunked
-   * upload implementation can consume them without interface churn.
-   *
-   * @param scope - `'c2c'` or `'group'`.
-   * @param targetId - User openid or group openid.
-   * @param fileType - Media file type code.
-   * @param creds - Authentication credentials.
-   * @param opts - Upload options. Exactly one of `url`/`fileData`/`buffer`/`localPath`
-   *   must be supplied.
-   * @returns Upload result containing `file_info` for subsequent message sends.
-   */
-  async uploadMedia(
-    scope: ChatScope,
-    targetId: string,
-    fileType: MediaFileType,
-    creds: { appId: string; clientSecret: string },
-    opts: {
-      url?: string;
-      fileData?: string;
-      /**
-       * Raw bytes in memory. Currently re-encoded to base64 internally;
-       * reserved as a dedicated input for the future chunked uploader.
-       */
-      buffer?: Buffer;
-      /**
-       * On-disk path. Currently read + base64-encoded internally; reserved
-       * for streaming ingestion by the future chunked uploader.
-       */
-      localPath?: string;
-      srvSendMsg?: boolean;
-      fileName?: string;
-    },
-  ): Promise<UploadMediaResponse> {
-    const sources = [opts.url, opts.fileData, opts.buffer, opts.localPath].filter(
-      (v) => v !== undefined,
-    );
-    if (sources.length === 0) {
-      throw new Error(`uploadMedia: one of url/fileData/buffer/localPath is required`);
-    }
-    if (sources.length > 1) {
-      throw new Error(
-        `uploadMedia: url/fileData/buffer/localPath are mutually exclusive (got ${sources.length})`,
-      );
-    }
-
-    // One-shot path: materialize buffer/localPath into fileData.
-    // Future chunked-upload work will branch here on size and route
-    // buffer/localPath through streaming ingestion instead of base64 encoding.
-    let fileData = opts.fileData;
-    if (opts.buffer) {
-      fileData = opts.buffer.toString("base64");
-    } else if (opts.localPath) {
-      const buf = await fs.promises.readFile(opts.localPath);
-      fileData = buf.toString("base64");
-    }
-
-    // Check cache for base64 uploads.
-    if (fileData && this.cache) {
-      const hash = this.cache.computeHash(fileData);
-      const cached = this.cache.get(hash, scope, targetId, fileType);
-      if (cached) {
-        return { file_uuid: "", file_info: cached, ttl: 0 };
-      }
-    }
-
-    const body: Record<string, unknown> = {
-      file_type: fileType,
-      srv_send_msg: opts.srvSendMsg ?? false,
-    };
-    if (opts.url) {
-      body.url = opts.url;
-    } else if (fileData) {
-      body.file_data = fileData;
-    }
-    if (fileType === MediaFileType.FILE && opts.fileName) {
-      body.file_name = this.sanitize(opts.fileName);
-    }
-
-    const token = await this.tokenManager.getAccessToken(creds.appId, creds.clientSecret);
-    const path = mediaUploadPath(scope, targetId);
-
-    const result = await withRetry(
-      () =>
-        this.client.request<UploadMediaResponse>(token, "POST", path, body, {
-          redactBodyKeys: ["file_data"],
-          uploadRequest: true,
-        }),
-      UPLOAD_RETRY_POLICY,
-      undefined,
-      this.logger,
-    );
-
-    // Cache the result for future dedup.
-    if (fileData && result.file_info && result.ttl > 0 && this.cache) {
-      const hash = this.cache.computeHash(fileData);
-      this.cache.set(
-        hash,
-        scope,
-        targetId,
-        fileType,
-        result.file_info,
-        result.file_uuid,
-        result.ttl,
-      );
-    }
-
-    return result;
-  }
-
-  /**
-   * Send a media message (upload result → message) to a C2C or Group target.
-   *
-   * @param scope - `'c2c'` or `'group'`.
-   * @param targetId - User openid or group openid.
-   * @param fileInfo - `file_info` from a prior upload.
-   * @param creds - Authentication credentials.
-   * @param opts - Message options.
-   */
-  async sendMediaMessage(
-    scope: ChatScope,
-    targetId: string,
-    fileInfo: string,
-    creds: { appId: string; clientSecret: string },
-    opts?: {
-      msgId?: string;
-      content?: string;
-    },
-  ): Promise<MessageResponse> {
-    const token = await this.tokenManager.getAccessToken(creds.appId, creds.clientSecret);
-    const msgSeq = opts?.msgId ? getNextMsgSeq(opts.msgId) : 1;
-    const path = messagePath(scope, targetId);
-
-    return this.client.request<MessageResponse>(token, "POST", path, {
-      msg_type: 7,
-      media: { file_info: fileInfo },
-      msg_seq: msgSeq,
-      ...(opts?.content ? { content: opts.content } : {}),
-      ...(opts?.msgId ? { msg_id: opts.msgId } : {}),
-    });
-  }
-}

package/src/engine/api/messages.ts

@@ -1,293 +0,0 @@
-/**
- * Message sending API for the QQ Open Platform.
- *
- * Key design improvements:
- * - Unified `sendMessage(scope, ...)` replaces `sendC2CMessage` + `sendGroupMessage`.
- * - `onMessageSent` hook is scoped to the instance, not a module-level global.
- * - Markdown support flag is per-instance, not a global Map.
- */
-
-import type {
-  ChatScope,
-  MessageResponse,
-  OutboundMeta,
-  EngineLogger,
-  InlineKeyboard,
-  StreamMessageRequest,
-} from "../types.js";
-import { formatErrorMessage } from "../utils/format.js";
-import { ApiClient } from "./api-client.js";
-import {
-  messagePath,
-  channelMessagePath,
-  dmMessagePath,
-  gatewayPath,
-  interactionPath,
-  getNextMsgSeq,
-  streamMessagePath,
-} from "./routes.js";
-import { TokenManager } from "./token.js";
-
-interface MessageApiConfig {
-  /** Whether the QQ Bot has markdown permission. */
-  markdownSupport: boolean;
-  /** Logger for diagnostics. */
-  logger?: EngineLogger;
-}
-
-type OnMessageSentCallback = (refIdx: string, meta: OutboundMeta) => void;
-
-/**
- * Message sending module.
- *
- * Usage:
- * ```ts
- * const api = new MessageApi(client, tokenMgr, { markdownSupport: true });
- * await api.sendMessage('c2c', openid, 'Hello!', { appId, clientSecret, msgId });
- * ```
- */
-export class MessageApi {
-  private readonly client: ApiClient;
-  private readonly tokenManager: TokenManager;
-  private readonly markdownSupport: boolean;
-  private readonly logger?: EngineLogger;
-  private messageSentHook: OnMessageSentCallback | null = null;
-
-  constructor(client: ApiClient, tokenManager: TokenManager, config: MessageApiConfig) {
-    this.client = client;
-    this.tokenManager = tokenManager;
-    this.markdownSupport = config.markdownSupport;
-    this.logger = config.logger;
-  }
-
-  /** Register a callback invoked when a sent message returns a ref_idx. */
-  onMessageSent(callback: OnMessageSentCallback): void {
-    this.messageSentHook = callback;
-  }
-
-  /**
-   * Notify the registered hook about a sent message.
-   * Use this for media sends that bypass `sendAndNotify`.
-   */
-  notifyMessageSent(refIdx: string, meta: OutboundMeta): void {
-    if (this.messageSentHook) {
-      try {
-        this.messageSentHook(refIdx, meta);
-      } catch (err) {
-        this.logger?.error?.(
-          `[qqbot:messages] onMessageSent hook error: ${formatErrorMessage(err)}`,
-        );
-      }
-    }
-  }
-
-  // ---- Unified message sending ----
-
-  /**
-   * Send a text message to a C2C or Group target.
-   *
-   * Automatically constructs the correct path, body format (markdown vs plain),
-   * and message sequence number.
-   */
-  async sendMessage(
-    scope: ChatScope,
-    targetId: string,
-    content: string,
-    creds: Credentials,
-    opts?: {
-      msgId?: string;
-      messageReference?: string;
-      inlineKeyboard?: InlineKeyboard;
-    },
-  ): Promise<MessageResponse> {
-    const token = await this.tokenManager.getAccessToken(creds.appId, creds.clientSecret);
-    const msgSeq = opts?.msgId ? getNextMsgSeq(opts.msgId) : 1;
-    const body = this.buildMessageBody(
-      content,
-      opts?.msgId,
-      msgSeq,
-      opts?.messageReference,
-      opts?.inlineKeyboard,
-    );
-    const path = messagePath(scope, targetId);
-    return this.sendAndNotify(creds.appId, token, "POST", path, body, { text: content });
-  }
-
-  /** Send a proactive (no msgId) message to a C2C or Group target. */
-  async sendProactiveMessage(
-    scope: ChatScope,
-    targetId: string,
-    content: string,
-    creds: Credentials,
-  ): Promise<MessageResponse> {
-    if (!content?.trim()) {
-      throw new Error("Proactive message content must not be empty");
-    }
-    const token = await this.tokenManager.getAccessToken(creds.appId, creds.clientSecret);
-    const body = this.buildProactiveBody(content);
-    const path = messagePath(scope, targetId);
-    return this.sendAndNotify(creds.appId, token, "POST", path, body, { text: content });
-  }
-
-  // ---- Channel / DM ----
-
-  /** Send a channel message. */
-  async sendChannelMessage(opts: {
-    channelId: string;
-    content: string;
-    creds: Credentials;
-    msgId?: string;
-  }): Promise<MessageResponse> {
-    const token = await this.tokenManager.getAccessToken(opts.creds.appId, opts.creds.clientSecret);
-    return this.client.request<MessageResponse>(token, "POST", channelMessagePath(opts.channelId), {
-      content: opts.content,
-      ...(opts.msgId ? { msg_id: opts.msgId } : {}),
-    });
-  }
-
-  /** Send a DM (guild direct message). */
-  async sendDmMessage(opts: {
-    guildId: string;
-    content: string;
-    creds: Credentials;
-    msgId?: string;
-  }): Promise<MessageResponse> {
-    const token = await this.tokenManager.getAccessToken(opts.creds.appId, opts.creds.clientSecret);
-    return this.client.request<MessageResponse>(token, "POST", dmMessagePath(opts.guildId), {
-      content: opts.content,
-      ...(opts.msgId ? { msg_id: opts.msgId } : {}),
-    });
-  }
-
-  // ---- C2C Input Notify ----
-
-  /** Send a typing indicator to a C2C user. */
-  async sendInputNotify(opts: {
-    openid: string;
-    creds: Credentials;
-    msgId?: string;
-    inputSecond?: number;
-  }): Promise<{ refIdx?: string }> {
-    const inputSecond = opts.inputSecond ?? 60;
-    const token = await this.tokenManager.getAccessToken(opts.creds.appId, opts.creds.clientSecret);
-    const msgSeq = opts.msgId ? getNextMsgSeq(opts.msgId) : 1;
-    const response = await this.client.request<{ ext_info?: { ref_idx?: string } }>(
-      token,
-      "POST",
-      messagePath("c2c", opts.openid),
-      {
-        msg_type: 6,
-        input_notify: { input_type: 1, input_second: inputSecond },
-        msg_seq: msgSeq,
-        ...(opts.msgId ? { msg_id: opts.msgId } : {}),
-      },
-    );
-    return { refIdx: response.ext_info?.ref_idx };
-  }
-
-  // ---- Interaction ----
-
-  /** Acknowledge an INTERACTION_CREATE event. */
-  async acknowledgeInteraction(
-    interactionId: string,
-    creds: Credentials,
-    code: 0 | 1 | 2 | 3 | 4 | 5 = 0,
-  ): Promise<void> {
-    const token = await this.tokenManager.getAccessToken(creds.appId, creds.clientSecret);
-    await this.client.request(token, "PUT", interactionPath(interactionId), { code });
-  }
-
-  // ---- Gateway ----
-
-  /** Get the WebSocket gateway URL. */
-  async getGatewayUrl(creds: Credentials): Promise<string> {
-    const token = await this.tokenManager.getAccessToken(creds.appId, creds.clientSecret);
-    const data = await this.client.request<{ url: string }>(token, "GET", gatewayPath());
-    return data.url;
-  }
-
-  /**
-   * Send a C2C stream message chunk (`/v2/users/{openid}/stream_messages`).
-   * Only supported for one-to-one chats.
-   */
-  async sendC2CStreamMessage(
-    creds: Credentials,
-    openid: string,
-    req: StreamMessageRequest,
-  ): Promise<MessageResponse> {
-    const token = await this.tokenManager.getAccessToken(creds.appId, creds.clientSecret);
-    const path = streamMessagePath(openid);
-    const body: Record<string, unknown> = {
-      input_mode: req.input_mode,
-      input_state: req.input_state,
-      content_type: req.content_type,
-      content_raw: req.content_raw,
-      event_id: req.event_id,
-      msg_id: req.msg_id,
-      msg_seq: req.msg_seq,
-      index: req.index,
-    };
-    if (req.stream_msg_id) {
-      body.stream_msg_id = req.stream_msg_id;
-    }
-    return this.client.request<MessageResponse>(token, "POST", path, body);
-  }
-
-  // ---- Internal ----
-
-  private async sendAndNotify(
-    appId: string,
-    accessToken: string,
-    method: string,
-    path: string,
-    body: unknown,
-    meta: OutboundMeta,
-  ): Promise<MessageResponse> {
-    const result = await this.client.request<MessageResponse>(accessToken, method, path, body);
-    if (result.ext_info?.ref_idx && this.messageSentHook) {
-      try {
-        this.messageSentHook(result.ext_info.ref_idx, meta);
-      } catch (err) {
-        this.logger?.error?.(
-          `[qqbot:messages] onMessageSent hook error: ${formatErrorMessage(err)}`,
-        );
-      }
-    }
-    return result;
-  }
-
-  private buildMessageBody(
-    content: string,
-    msgId: string | undefined,
-    msgSeq: number,
-    messageReference?: string,
-    inlineKeyboard?: InlineKeyboard,
-  ): Record<string, unknown> {
-    const body: Record<string, unknown> = this.markdownSupport
-      ? { markdown: { content }, msg_type: 2, msg_seq: msgSeq }
-      : { content, msg_type: 0, msg_seq: msgSeq };
-
-    if (msgId) {
-      body.msg_id = msgId;
-    }
-    if (messageReference && !this.markdownSupport) {
-      body.message_reference = { message_id: messageReference };
-    }
-    if (inlineKeyboard) {
-      body.keyboard = inlineKeyboard;
-    }
-    return body;
-  }
-
-  private buildProactiveBody(content: string): Record<string, unknown> {
-    return this.markdownSupport ? { markdown: { content }, msg_type: 2 } : { content, msg_type: 0 };
-  }
-}
-
-// ---- Shared helpers ----
-
-/** Credentials needed to authenticate API requests. */
-export interface Credentials {
-  appId: string;
-  clientSecret: string;
-}