@gakr-gakr/qqbot 0.1.0

package/src/engine/api/media.ts

@@ -0,0 +1,218 @@
+/**
+ * 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

@@ -0,0 +1,293 @@
+/**
+ * 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;
+}