@starim-io/bot-sdk 0.1.4

package/dist/index.cjs

@@ -0,0 +1,1188 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var http = require('http');
+var crypto = require('crypto');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var path__default = /*#__PURE__*/_interopDefault(path);
+
+// src/errors.ts
+var StarIMApiError = class extends Error {
+  code;
+  statusCode;
+  responseBody;
+  constructor(opts) {
+    super(opts.message);
+    this.name = "StarIMApiError";
+    this.statusCode = opts.statusCode;
+    this.code = opts.code;
+    this.responseBody = opts.responseBody;
+  }
+};
+var StarIMSignatureError = class extends Error {
+  constructor(message = "Invalid X-StarIM-Signature") {
+    super(message);
+    this.name = "StarIMSignatureError";
+  }
+};
+async function putToS3(creds, body) {
+  const headers = {
+    "Content-Type": creds.contentType || "application/octet-stream"
+  };
+  const ac = new AbortController();
+  const to = setTimeout(() => ac.abort(), 12e4);
+  try {
+    const res = await fetch(creds.uploadUrl, {
+      method: creds.method || "PUT",
+      headers,
+      body,
+      signal: ac.signal
+    });
+    if (!res.ok) {
+      const t = await res.text().catch(() => "");
+      throw new Error(`S3 upload failed: ${res.status} ${t.slice(0, 200)}`);
+    }
+  } finally {
+    clearTimeout(to);
+  }
+}
+async function uploadBuffer(client, buffer, fileName, fileType) {
+  const creds = await client.issueUploadCredentials({
+    fileName,
+    fileSize: buffer.length,
+    fileType: fileType || "",
+    metadata: {}
+  });
+  await putToS3(creds, buffer);
+  return client.completeUpload({
+    key: creds.key,
+    fileName,
+    fileSize: buffer.length,
+    fileType: fileType || creds.contentType,
+    category: "bot",
+    isPublic: false
+  });
+}
+async function uploadFileFromPath(client, filePath, options) {
+  const buffer = await fs.promises.readFile(filePath);
+  const fileName = options?.fileName || path__default.default.basename(filePath);
+  return uploadBuffer(client, buffer, fileName, options?.fileType);
+}
+async function uploadFromUrl(client, sourceUrl, options) {
+  const res = await fetch(sourceUrl);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch ${sourceUrl}: ${res.status}`);
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  const fileName = options?.fileName || (() => {
+    try {
+      const u = new URL(sourceUrl);
+      return path__default.default.basename(u.pathname) || "download.bin";
+    } catch {
+      return "download.bin";
+    }
+  })();
+  return uploadBuffer(client, buf, fileName, options?.fileType || res.headers.get("content-type") || "");
+}
+async function sendPhotoFromPath(client, chatId, filePath, options) {
+  const done = await uploadFileFromPath(client, filePath, {
+    fileName: options?.fileName,
+    fileType: options?.fileType
+  });
+  return client.sendPhoto({
+    chat_id: chatId,
+    file_id: done.id,
+    caption: options?.caption
+  });
+}
+async function sendDocumentFromPath(client, chatId, filePath, options) {
+  const done = await uploadFileFromPath(client, filePath, {
+    fileName: options?.fileName,
+    fileType: options?.fileType
+  });
+  return client.sendDocument({
+    chat_id: chatId,
+    file_id: done.id,
+    caption: options?.caption
+  });
+}
+async function sendPhotoFromBuffer(client, chatId, buffer, options) {
+  const done = await uploadBuffer(client, buffer, options?.fileName || "image.bin", options?.fileType);
+  return client.sendPhoto({
+    chat_id: chatId,
+    file_id: done.id,
+    caption: options?.caption
+  });
+}
+async function sendPhotoFromUrl(client, chatId, sourceUrl, options) {
+  const done = await uploadFromUrl(client, sourceUrl, options);
+  return client.sendPhoto({
+    chat_id: chatId,
+    file_id: done.id,
+    caption: options?.caption
+  });
+}
+async function sendVideoFromUrl(client, chatId, sourceUrl, options) {
+  const done = await uploadFromUrl(client, sourceUrl, {
+    fileName: options?.fileName,
+    fileType: options?.fileType
+  });
+  return client.sendVideo({
+    chat_id: chatId,
+    file_id: done.id,
+    caption: options?.caption,
+    duration: options?.duration,
+    width: options?.width,
+    height: options?.height
+  });
+}
+
+// src/client.ts
+var DEFAULT_BASE = typeof process !== "undefined" && process.env.STARIM_API_BASE ? String(process.env.STARIM_API_BASE).replace(/\/+$/, "") : "https://api.starim.example/api/v1";
+function joinUrl(base, path2) {
+  const b = base.replace(/\/+$/, "");
+  const p = path2.startsWith("/") ? path2 : `/${path2}`;
+  return `${b}${p}`;
+}
+function unwrapData(body) {
+  if (!body || typeof body !== "object") return body;
+  const b = body;
+  if (b.success !== true) return body;
+  let d = b.data;
+  if (d && typeof d === "object") {
+    const inner = d;
+    if (inner.success === true && "data" in inner && typeof inner.data !== "undefined" && Object.keys(inner).length <= 5) {
+      d = inner.data;
+    }
+  }
+  return d;
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+var StarIMBotClient = class {
+  token;
+  baseUrl;
+  timeoutMs;
+  debug;
+  /** 暴露给上层（如 StarIMBot polling 链路）以记录非致命错误 */
+  logger;
+  files;
+  constructor(opts) {
+    if (!opts.token?.trim()) {
+      throw new Error("StarIMBotClient: token is required");
+    }
+    this.token = opts.token.trim();
+    this.baseUrl = (opts.baseUrl || DEFAULT_BASE).replace(/\/+$/, "");
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+    this.debug = !!opts.debug;
+    this.logger = opts.logger ?? console;
+    this.files = {
+      issueUploadCredentials: (p) => this.issueUploadCredentials(p),
+      completeUpload: (p) => this.completeUpload(p)
+    };
+  }
+  log(level, msg, meta) {
+    if (!this.debug) return;
+    this.logger[level](`[StarIMBotClient] ${msg}`, meta ?? "");
+  }
+  async request(method, path2, body, opts) {
+    const url = joinUrl(this.baseUrl, path2);
+    const auth = opts?.auth !== false;
+    const headers = {
+      Accept: "application/json"
+    };
+    if (auth) {
+      headers.Authorization = `Bearer ${this.token}`;
+    }
+    const hasBody = body !== void 0 && method !== "GET" && method !== "HEAD";
+    if (hasBody) {
+      headers["Content-Type"] = "application/json";
+    }
+    const effectiveTimeout = opts?.timeoutMs ?? this.timeoutMs;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), effectiveTimeout);
+    this.log("debug", `${method} ${path2}`);
+    let res;
+    try {
+      res = await fetch(url, {
+        method,
+        headers,
+        body: hasBody ? JSON.stringify(body) : void 0,
+        signal: ac.signal
+      });
+    } catch (e) {
+      clearTimeout(timer);
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new StarIMApiError({
+        message: msg.includes("abort") ? "Request timeout" : msg,
+        statusCode: 0,
+        responseBody: void 0
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const text = await res.text();
+    let json;
+    try {
+      json = text ? JSON.parse(text) : {};
+    } catch {
+      throw new StarIMApiError({
+        message: text.slice(0, 500) || "Invalid JSON response",
+        statusCode: res.status,
+        responseBody: text
+      });
+    }
+    if (!isPlainObject(json)) {
+      throw new StarIMApiError({
+        message: "Unexpected response shape",
+        statusCode: res.status,
+        responseBody: json
+      });
+    }
+    if (json.success === false) {
+      throw new StarIMApiError({
+        message: String(json.message || "Request failed"),
+        statusCode: res.status || Number(json.code) || 400,
+        code: json.code,
+        responseBody: json
+      });
+    }
+    if (!res.ok && json.success !== true) {
+      throw new StarIMApiError({
+        message: String(json.message || res.statusText || "HTTP error"),
+        statusCode: res.status,
+        code: json.code,
+        responseBody: json
+      });
+    }
+    if (json.success !== true) {
+      throw new StarIMApiError({
+        message: String(json.message || "Request failed"),
+        statusCode: res.status,
+        code: json.code,
+        responseBody: json
+      });
+    }
+    return unwrapData(json);
+  }
+  /** GET /bots/me */
+  getMe() {
+    return this.request("GET", "/bots/me");
+  }
+  /** GET /bots/getChat?chat_id= */
+  getChat(chat_id) {
+    const q = new URLSearchParams({ chat_id });
+    return this.request("GET", `/bots/getChat?${q.toString()}`);
+  }
+  getChatMember(chat_id, user_id) {
+    const q = new URLSearchParams({ chat_id, user_id });
+    return this.request("GET", `/bots/getChatMember?${q.toString()}`);
+  }
+  getChatMemberCount(chat_id) {
+    const q = new URLSearchParams({ chat_id });
+    return this.request("GET", `/bots/getChatMemberCount?${q.toString()}`);
+  }
+  getChatAdministrators(chat_id) {
+    const q = new URLSearchParams({ chat_id });
+    return this.request("GET", `/bots/getChatAdministrators?${q.toString()}`);
+  }
+  setChatTitle(chat_id, title) {
+    return this.request("POST", "/bots/setChatTitle", { chat_id, title });
+  }
+  setChatDescription(chat_id, description) {
+    return this.request("POST", "/bots/setChatDescription", { chat_id, description });
+  }
+  setChatPhoto(chat_id, photo) {
+    return this.request("POST", "/bots/setChatPhoto", { chat_id, photo });
+  }
+  pinChatMessage(body) {
+    return this.request("POST", "/bots/pinChatMessage", body);
+  }
+  unpinChatMessage(body) {
+    return this.request("POST", "/bots/unpinChatMessage", body);
+  }
+  unpinAllChatMessages(chat_id) {
+    return this.request("POST", "/bots/unpinAllChatMessages", { chat_id });
+  }
+  forwardMessage(body) {
+    return this.request("POST", "/bots/forwardMessage", body);
+  }
+  copyMessage(body) {
+    return this.request("POST", "/bots/copyMessage", body);
+  }
+  sendChatAction(chat_id, action) {
+    return this.request("POST", "/bots/sendChatAction", { chat_id, action });
+  }
+  getFile(file_id) {
+    const q = new URLSearchParams({ file_id });
+    return this.request("GET", `/bots/getFile?${q.toString()}`);
+  }
+  /** POST /bots/sendMessage */
+  sendMessage(params) {
+    return this.request("POST", "/bots/sendMessage", {
+      chat_id: params.chat_id,
+      text: params.text,
+      reply_markup: params.reply_markup
+    });
+  }
+  /** POST /bots/setMyCommands */
+  setMyCommands(params) {
+    return this.request("POST", "/bots/setMyCommands", {
+      commands: params.commands,
+      scope: params.scope,
+      language_code: params.language_code
+    });
+  }
+  /** GET /bots/getMyCommands */
+  getMyCommands(params) {
+    const q = new URLSearchParams();
+    if (params?.scope) q.set("scope", params.scope);
+    if (params?.language_code) q.set("language_code", params.language_code);
+    const suffix = q.toString() ? `?${q.toString()}` : "";
+    return this.request("GET", `/bots/getMyCommands${suffix}`);
+  }
+  /** POST /bots/deleteMyCommands */
+  deleteMyCommands(params) {
+    return this.request("POST", "/bots/deleteMyCommands", {
+      scope: params?.scope,
+      language_code: params?.language_code
+    });
+  }
+  /** POST /bots/setMyShortDescription · 设置短描述（≤120 字） */
+  setMyShortDescription(short_description) {
+    return this.request("POST", "/bots/setMyShortDescription", { short_description });
+  }
+  /** GET /bots/getMyShortDescription · 获取短描述 */
+  getMyShortDescription() {
+    return this.request("GET", "/bots/getMyShortDescription");
+  }
+  /** POST /bots/setMyDescription · 设置 Bot 主页大段「关于」文本（≤512 字） */
+  setMyDescription(description) {
+    return this.request("POST", "/bots/setMyDescription", { description });
+  }
+  /** GET /bots/getMyDescription · 获取 Bot 主页大段「关于」文本 */
+  getMyDescription() {
+    return this.request("GET", "/bots/getMyDescription");
+  }
+  setWebhook(params) {
+    const defaultAllowed = [
+      "message",
+      "edited_message",
+      "message_deleted",
+      "message_read",
+      "message_delivered",
+      "callback_query",
+      "inline_query",
+      "friend_request"
+    ];
+    return this.request("POST", "/bots/setWebhook", {
+      url: params.url,
+      secret_token: params.secret_token ?? "",
+      allowed_updates: params.allowed_updates ?? defaultAllowed,
+      allowed_ips: params.allowed_ips ?? []
+    });
+  }
+  deleteWebhook() {
+    return this.request("POST", "/bots/deleteWebhook", {});
+  }
+  /** GET /bots/getWebhookInfo */
+  getWebhookInfo() {
+    return this.request("GET", "/bots/getWebhookInfo");
+  }
+  /**
+   * POST /bots/getUpdates · 长轮询拉取 polling 模式 update。
+   *
+   * - 调本接口前请确保已 `deleteWebhook`，否则平台返回 409。
+   * - HTTP 客户端的超时会按 `timeout + 5s` 自动放宽，避免比服务端先断开。
+   *
+   * @example
+   * ```ts
+   * let offset = 0;
+   * while (true) {
+   *   const { updates } = await client.getUpdates({ timeout: 30, offset });
+   *   for (const u of updates) {
+   *     console.log(u);
+   *     if (typeof u.update_seq === 'number') offset = u.update_seq + 1;
+   *   }
+   * }
+   * ```
+   */
+  async getUpdates(params = {}) {
+    const timeoutSec = Math.min(50, Math.max(0, Number(params.timeout) || 0));
+    const httpTimeoutMs = (timeoutSec + 5) * 1e3;
+    const data = await this.request(
+      "POST",
+      "/bots/getUpdates",
+      {
+        offset: params.offset ?? 0,
+        limit: params.limit ?? 100,
+        timeout: timeoutSec,
+        allowed_updates: params.allowed_updates ?? []
+      },
+      { timeoutMs: httpTimeoutMs }
+    );
+    return { updates: Array.isArray(data?.updates) ? data.updates : [] };
+  }
+  sendPhoto(params) {
+    return this.request("POST", "/bots/sendPhoto", this.buildSendMediaBody(params));
+  }
+  sendDocument(params) {
+    return this.request("POST", "/bots/sendDocument", this.buildSendMediaBody(params));
+  }
+  sendVideo(params) {
+    return this.request("POST", "/bots/sendVideo", this.buildSendMediaBody(params));
+  }
+  sendAudio(params) {
+    return this.request("POST", "/bots/sendAudio", this.buildSendMediaBody(params));
+  }
+  sendVoice(params) {
+    return this.request("POST", "/bots/sendVoice", this.buildSendMediaBody(params));
+  }
+  sendVideoNote(params) {
+    return this.request("POST", "/bots/sendVideoNote", this.buildSendVideoNoteBody(params));
+  }
+  sendAnimation(params) {
+    return this.request("POST", "/bots/sendAnimation", this.buildSendMediaBody(params));
+  }
+  sendSticker(params) {
+    const body = {
+      chat_id: params.chat_id,
+      file_id: params.file_id
+    };
+    const w = Number(params.width);
+    if (params.width != null && Number.isFinite(w) && w > 0) {
+      body.width = w;
+    }
+    const h = Number(params.height);
+    if (params.height != null && Number.isFinite(h) && h > 0) {
+      body.height = h;
+    }
+    if (typeof params.thumbnail_url === "string" && params.thumbnail_url.trim()) {
+      body.thumbnail_url = params.thumbnail_url.trim();
+    }
+    return this.request("POST", "/bots/sendSticker", body);
+  }
+  sendDice(params) {
+    const body = { chat_id: params.chat_id };
+    if (params.emoji != null && String(params.emoji).trim()) {
+      body.emoji = String(params.emoji).trim();
+    }
+    if (params.reply_markup !== void 0) {
+      body.reply_markup = params.reply_markup;
+    }
+    return this.request("POST", "/bots/sendDice", body);
+  }
+  sendPoll(params) {
+    const body = {
+      chat_id: params.chat_id,
+      question: params.question,
+      options: params.options
+    };
+    if (params.is_anonymous !== void 0) {
+      body.is_anonymous = params.is_anonymous;
+    }
+    if (params.type !== void 0) {
+      body.type = params.type;
+    }
+    if (params.correct_option_id != null) {
+      body.correct_option_id = params.correct_option_id;
+    }
+    if (params.reply_markup !== void 0) {
+      body.reply_markup = params.reply_markup;
+    }
+    return this.request("POST", "/bots/sendPoll", body);
+  }
+  sendContact(params) {
+    const body = {
+      chat_id: params.chat_id,
+      phone_number: params.phone_number,
+      first_name: params.first_name
+    };
+    if (params.last_name != null) {
+      body.last_name = params.last_name;
+    }
+    if (params.reply_markup !== void 0) {
+      body.reply_markup = params.reply_markup;
+    }
+    return this.request("POST", "/bots/sendContact", body);
+  }
+  sendMediaGroup(params) {
+    const body = {
+      chat_id: params.chat_id,
+      media: params.media
+    };
+    if (params.reply_markup !== void 0) {
+      body.reply_markup = params.reply_markup;
+    }
+    return this.request("POST", "/bots/sendMediaGroup", body);
+  }
+  buildSendMediaBody(params) {
+    const body = {
+      chat_id: params.chat_id,
+      file_id: params.file_id,
+      caption: params.caption ?? ""
+    };
+    const d = Number(params.duration);
+    if (params.duration != null && Number.isFinite(d) && d > 0) {
+      body.duration = d;
+    }
+    if (typeof params.performer === "string" && params.performer.trim()) {
+      body.performer = params.performer.trim();
+    }
+    if (typeof params.title === "string" && params.title.trim()) {
+      body.title = params.title.trim();
+    }
+    if (typeof params.thumbnail_url === "string" && params.thumbnail_url.trim()) {
+      body.thumbnail_url = params.thumbnail_url.trim();
+    }
+    const w = Number(params.width);
+    if (params.width != null && Number.isFinite(w) && w > 0) {
+      body.width = w;
+    }
+    const h = Number(params.height);
+    if (params.height != null && Number.isFinite(h) && h > 0) {
+      body.height = h;
+    }
+    return body;
+  }
+  buildSendVideoNoteBody(params) {
+    const body = this.buildSendMediaBody(params);
+    const durRaw = params.duration != null ? params.duration : params.length;
+    const d = Number(durRaw);
+    if (durRaw != null && Number.isFinite(d) && d > 0) {
+      body.duration = d;
+    }
+    return body;
+  }
+  sendLocation(params) {
+    return this.request("POST", "/bots/sendLocation", {
+      chat_id: params.chat_id,
+      latitude: params.latitude,
+      longitude: params.longitude,
+      name: params.name ?? "",
+      address: params.address ?? ""
+    });
+  }
+  sendVenue(params) {
+    const body = {
+      chat_id: params.chat_id,
+      latitude: params.latitude,
+      longitude: params.longitude,
+      title: params.title,
+      address: params.address ?? ""
+    };
+    if (params.reply_markup !== void 0) {
+      body.reply_markup = params.reply_markup;
+    }
+    return this.request("POST", "/bots/sendVenue", body);
+  }
+  editMessage(params) {
+    return this.request("POST", "/bots/editMessage", {
+      message_id: params.message_id,
+      text: params.text,
+      content: params.content,
+      reply_markup: params.reply_markup
+    });
+  }
+  editMessageReplyMarkup(params) {
+    return this.request("POST", "/bots/editMessageReplyMarkup", {
+      message_id: params.message_id,
+      reply_markup: params.reply_markup ?? null
+    });
+  }
+  answerCallbackQuery(params) {
+    return this.request("POST", "/bots/answerCallbackQuery", {
+      callback_query_id: params.callback_query_id,
+      text: params.text ?? "",
+      show_alert: params.show_alert ?? false,
+      url: params.url ?? "",
+      cache_time: params.cache_time ?? 0
+    });
+  }
+  answerInlineQuery(params) {
+    return this.request("POST", "/bots/answerInlineQuery", {
+      inline_query_id: params.inline_query_id,
+      results: params.results,
+      cache_time: params.cache_time ?? 300,
+      is_personal: params.is_personal ?? false,
+      next_offset: params.next_offset ?? ""
+    });
+  }
+  /** POST /bots/answerFriendRequest · manual 模式下处理用户发起的好友申请 */
+  answerFriendRequest(params) {
+    return this.request("POST", "/bots/answerFriendRequest", {
+      friendship_id: params.friendship_id,
+      action: params.action
+    });
+  }
+  /** POST /bots/setMyFriendRequestMode · 配置当前机器人好友申请处理策略 */
+  setMyFriendRequestMode(params) {
+    return this.request("POST", "/bots/setMyFriendRequestMode", {
+      friend_request_mode: params.friend_request_mode
+    });
+  }
+  /** GET /bots/getMyFriendRequestMode · 获取当前机器人好友申请处理策略 */
+  getMyFriendRequestMode() {
+    return this.request("GET", "/bots/getMyFriendRequestMode");
+  }
+  /** GET /bots/getFriendRequests · 待处理好友申请（数据库 Friendship） */
+  getFriendRequests() {
+    return this.request("GET", "/bots/getFriendRequests");
+  }
+  kickChatMember(params) {
+    return this.request("POST", "/bots/kickChatMember", {
+      chat_id: params.chat_id,
+      user_id: params.user_id
+    });
+  }
+  banChatMember(params) {
+    return this.request("POST", "/bots/banChatMember", {
+      chat_id: params.chat_id,
+      user_id: params.user_id,
+      reason: params.reason ?? ""
+    });
+  }
+  unbanChatMember(params) {
+    return this.request("POST", "/bots/unbanChatMember", {
+      chat_id: params.chat_id,
+      user_id: params.user_id
+    });
+  }
+  deleteMessage(params) {
+    return this.request("POST", "/bots/deleteMessage", {
+      message_id: params.message_id
+    });
+  }
+  issueUploadCredentials(p) {
+    return this.request("POST", "/bots/files/upload-credentials", {
+      fileName: p.fileName,
+      fileSize: p.fileSize,
+      fileType: p.fileType ?? "",
+      checksum: p.checksum ?? "",
+      metadata: p.metadata ?? {}
+    });
+  }
+  completeUpload(p) {
+    return this.request("POST", "/bots/files/complete", {
+      key: p.key,
+      fileName: p.fileName,
+      fileSize: p.fileSize,
+      fileType: p.fileType ?? "",
+      checksum: p.checksum ?? "",
+      category: p.category ?? "bot",
+      isPublic: p.isPublic ?? false
+    });
+  }
+  /**
+   * 校验 Token（公开接口，不强制带 Bearer，仅 body.token）。
+   */
+  verifyToken() {
+    return this.request("POST", "/bots/verify-token", { token: this.token }, { auth: false });
+  }
+  /** 本地路径 → 上传 S3 → sendPhoto */
+  sendPhotoFromFile(chatId, filePath, options) {
+    return sendPhotoFromPath(this, chatId, filePath, options);
+  }
+  /** 本地路径 → 上传 S3 → sendDocument */
+  sendDocumentFromFile(chatId, filePath, options) {
+    return sendDocumentFromPath(this, chatId, filePath, options);
+  }
+};
+var SIG_PREFIX = "sha256=";
+var DEFAULT_TIMESTAMP_TOLERANCE_SEC = 300;
+function computeWebhookSignatureV2(secret, timestampSec, rawBody) {
+  const ts = String(timestampSec);
+  const raw = typeof rawBody === "string" ? Buffer.from(rawBody, "utf8") : rawBody;
+  const h = crypto.createHmac("sha256", secret);
+  h.update(ts);
+  h.update(".");
+  h.update(raw);
+  return h.digest("hex");
+}
+function timingSafeHexEqual(a, b) {
+  let bufA;
+  let bufB;
+  try {
+    bufA = Buffer.from(a, "hex");
+    bufB = Buffer.from(b, "hex");
+  } catch {
+    return false;
+  }
+  if (bufA.length !== bufB.length || bufA.length === 0) return false;
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+function parseSigHeader(value) {
+  const trimmed = value.trim();
+  if (!trimmed.toLowerCase().startsWith(SIG_PREFIX)) return null;
+  return trimmed.slice(SIG_PREFIX.length).trim();
+}
+function verifyWebhookSignature(secret, rawBody, signatureHeaderV2, timestampHeader, opts = {}) {
+  const tolerance = opts.timestampToleranceSec ?? DEFAULT_TIMESTAMP_TOLERANCE_SEC;
+  const nowSec = (opts.nowSec ?? (() => Math.floor(Date.now() / 1e3)))();
+  if (!signatureHeaderV2) {
+    throw new StarIMSignatureError("Missing X-StarIM-Signature-V2");
+  }
+  if (!timestampHeader) {
+    throw new StarIMSignatureError("Missing X-StarIM-Timestamp for V2 signature");
+  }
+  const ts = Number(timestampHeader);
+  if (!Number.isFinite(ts)) {
+    throw new StarIMSignatureError("Invalid X-StarIM-Timestamp");
+  }
+  if (Math.abs(nowSec - ts) > tolerance) {
+    throw new StarIMSignatureError(
+      `Timestamp out of tolerance window (\xB1${tolerance}s); possible replay`
+    );
+  }
+  const expected = parseSigHeader(signatureHeaderV2);
+  if (!expected) {
+    throw new StarIMSignatureError("Invalid X-StarIM-Signature-V2 format");
+  }
+  const actual = computeWebhookSignatureV2(secret, ts, rawBody);
+  if (!timingSafeHexEqual(actual, expected)) {
+    throw new StarIMSignatureError("V2 signature mismatch");
+  }
+}
+function headerValue(headers, name) {
+  const key = Object.keys(headers).find((k) => k.toLowerCase() === name.toLowerCase());
+  if (!key) return void 0;
+  const v = headers[key];
+  if (Array.isArray(v)) return v[0];
+  return v;
+}
+var LruDedupe = class {
+  constructor(maxSize) {
+    this.maxSize = maxSize;
+  }
+  order = [];
+  set = /* @__PURE__ */ new Set();
+  has(updateId) {
+    return this.set.has(updateId);
+  }
+  add(updateId) {
+    if (this.set.has(updateId)) return;
+    this.set.add(updateId);
+    this.order.push(updateId);
+    while (this.order.length > this.maxSize) {
+      const rm = this.order.shift();
+      if (rm) this.set.delete(rm);
+    }
+  }
+};
+function getRawBody(req) {
+  if (Buffer.isBuffer(req.rawBody)) return req.rawBody;
+  if (Buffer.isBuffer(req.body)) return req.body;
+  throw new StarIMSignatureError(
+    'Raw JSON body required for HMAC: use express.raw({ type: "*/*" }) or express.json({ verify: (req, buf) => { (req as any).rawBody = buf } })'
+  );
+}
+function processWebhook(req, opts) {
+  const raw = getRawBody(req);
+  const sigV2 = headerValue(req.headers, "x-starim-signature-v2");
+  const ts = headerValue(req.headers, "x-starim-timestamp");
+  verifyWebhookSignature(opts.secretToken, raw, sigV2, ts, opts.verify);
+  let update;
+  try {
+    update = JSON.parse(raw.toString("utf8"));
+  } catch {
+    throw new StarIMSignatureError("Invalid JSON body");
+  }
+  if (!update || typeof update !== "object" || typeof update.update_id !== "string") {
+    throw new StarIMSignatureError("Invalid Update payload");
+  }
+  const headerId = headerValue(req.headers, "x-starim-update-id");
+  if (headerId && headerId !== update.update_id) {
+    throw new StarIMSignatureError("X-StarIM-Update-Id does not match body.update_id");
+  }
+  let duplicate = false;
+  if (opts.dedupe) {
+    if (opts.dedupe.has(update.update_id)) {
+      duplicate = true;
+    } else {
+      opts.dedupe.add(update.update_id);
+    }
+  }
+  return { update, duplicate };
+}
+function webhookMiddleware(opts) {
+  return async (req, res, next) => {
+    try {
+      if (req.method && req.method !== "POST") {
+        res.statusCode = 405;
+        res.end("Method Not Allowed");
+        return;
+      }
+      const { update, duplicate } = processWebhook(req, {
+        secretToken: opts.secretToken,
+        dedupe: opts.dedupe,
+        verify: opts.verify
+      });
+      if (duplicate && !opts.invokeOnDuplicate) {
+        res.statusCode = 200;
+        res.end("ok");
+        return;
+      }
+      await opts.onUpdate(update, { rawBody: getRawBody(req), duplicate });
+      res.statusCode = 200;
+      res.end("ok");
+    } catch (e) {
+      if (e instanceof StarIMSignatureError) {
+        res.statusCode = 401;
+        res.end("unauthorized");
+        return;
+      }
+      if (typeof next === "function") {
+        next(e);
+        return;
+      }
+      res.statusCode = 500;
+      res.end("error");
+    }
+  };
+}
+
+// src/bot.ts
+function toNodeHeaders(h) {
+  const out = {};
+  for (const [k, v] of Object.entries(h)) {
+    out[k] = v;
+  }
+  return out;
+}
+async function readBody(req) {
+  const chunks = [];
+  for await (const chunk of req) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+var StarIMBot = class {
+  client;
+  secretToken;
+  dedupe;
+  handlers = /* @__PURE__ */ new Map();
+  commands = /* @__PURE__ */ new Map();
+  pollingActive = false;
+  pollingOffset = 0;
+  constructor(opts) {
+    this.secretToken = opts.secretToken;
+    this.client = new StarIMBotClient({
+      token: opts.token,
+      baseUrl: opts.baseUrl,
+      timeoutMs: opts.timeoutMs,
+      debug: opts.debug,
+      logger: opts.logger
+    });
+    this.dedupe = new LruDedupe(opts.dedupeSize ?? 1024);
+  }
+  on(type, handler) {
+    const key = type;
+    const list = this.handlers.get(key) ?? [];
+    list.push(handler);
+    this.handlers.set(key, list);
+    return this;
+  }
+  /**
+   * 仅匹配文本消息中以 `/name` 开头的命令（大小写不敏感）。
+   */
+  command(name, handler) {
+    const n = name.replace(/^\//, "").toLowerCase();
+    const list = this.commands.get(n) ?? [];
+    list.push(handler);
+    this.commands.set(n, list);
+    return this;
+  }
+  async dispatch(ctx) {
+    const { update } = ctx;
+    const type = update.type;
+    if (type === "message" && ctx.message.text) {
+      const text = ctx.message.text.trim();
+      const m = /^\/(\w+)/i.exec(text);
+      if (m) {
+        const cmd = m[1].toLowerCase();
+        const cmdHandlers = this.commands.get(cmd);
+        if (cmdHandlers?.length) {
+          for (const h of cmdHandlers) {
+            await h(ctx);
+          }
+          return;
+        }
+      }
+    }
+    const specific = this.handlers.get(type) ?? [];
+    for (const h of specific) {
+      await h(ctx);
+    }
+    const star = this.handlers.get("*") ?? [];
+    for (const h of star) {
+      await h(ctx);
+    }
+  }
+  /**
+   * Express / Connect 中间件：先挂载 express.raw（例如 type: application/json），再使用本回调。
+   */
+  webhookCallback() {
+    return async (req, res, next) => {
+      try {
+        if (req.method && req.method !== "POST") {
+          res.statusCode = 405;
+          res.end("Method Not Allowed");
+          return;
+        }
+        const { update, duplicate } = processWebhook(req, {
+          secretToken: this.secretToken,
+          dedupe: this.dedupe
+        });
+        if (duplicate) {
+          res.statusCode = 200;
+          res.end("ok");
+          return;
+        }
+        const ctx = this.createContext(update, getRaw(req), duplicate);
+        await this.dispatch(ctx);
+        res.statusCode = 200;
+        res.end("ok");
+      } catch (e) {
+        if (e instanceof StarIMSignatureError) {
+          res.statusCode = 401;
+          res.end("unauthorized");
+          return;
+        }
+        if (typeof next === "function") {
+          next(e);
+          return;
+        }
+        res.statusCode = 500;
+        res.end("error");
+      }
+    };
+  }
+  /**
+   * 长轮询模式：循环调用 getUpdates，把 update 喂给与 Webhook 相同的 dispatch 链路。
+   *
+   * 适用场景：
+   *  - 没有公网 IP / HTTPS 证书的本机开发；
+   *  - CI / 测试环境快速接入。
+   *
+   * 使用前请先 `await client.deleteWebhook()`，否则平台返回 409。
+   * 内部维护 offset、自动捕获错误并指数退避重试；调用 `stopPolling()` 优雅退出。
+   *
+   * @example
+   * ```ts
+   * await bot.client.deleteWebhook();
+   * await bot.startPolling({ timeout: 30 });
+   * ```
+   */
+  async startPolling(options = {}) {
+    if (this.pollingActive) return;
+    this.pollingActive = true;
+    this.pollingOffset = 0;
+    const timeoutSec = Math.min(50, Math.max(0, options.timeout ?? 30));
+    const limit = Math.min(100, Math.max(1, options.limit ?? 100));
+    const allowed = options.allowedUpdates ?? [];
+    const maxBackoff = Math.max(1, options.maxBackoffSec ?? 30);
+    let consecutiveErrors = 0;
+    while (this.pollingActive) {
+      try {
+        const { updates } = await this.client.getUpdates({
+          offset: this.pollingOffset,
+          limit,
+          timeout: timeoutSec,
+          allowed_updates: allowed
+        });
+        consecutiveErrors = 0;
+        for (const u of updates) {
+          if (typeof u.update_seq === "number") {
+            this.pollingOffset = Math.max(this.pollingOffset, u.update_seq + 1);
+          }
+          const uid = String(u.update_id);
+          if (this.dedupe.has(uid)) continue;
+          this.dedupe.add(uid);
+          const ctx = this.createContext(u, Buffer.alloc(0), false);
+          try {
+            await this.dispatch(ctx);
+          } catch (handlerErr) {
+            try {
+              this.client.logger?.error?.("[StarIMBot.polling] handler error", { error: handlerErr?.message });
+            } catch {
+            }
+          }
+        }
+      } catch (err) {
+        consecutiveErrors += 1;
+        const delay = Math.min(maxBackoff, Math.pow(2, Math.min(consecutiveErrors, 6))) * 1e3;
+        try {
+          this.client.logger?.warn?.("[StarIMBot.polling] getUpdates failed, backing off", {
+            error: err?.message,
+            delayMs: delay
+          });
+        } catch {
+        }
+        await new Promise((r) => setTimeout(r, delay));
+      }
+    }
+  }
+  /** 停止 startPolling 的循环（不会立刻打断当前 long-poll，等当次 RPC 返回后退出） */
+  stopPolling() {
+    this.pollingActive = false;
+  }
+  /**
+   * 内置 HTTP 服务，便于快速起 Webhook（生产环境建议使用反向代理 + TLS）。
+   */
+  start(options) {
+    const webhookPath = options.path ?? "/webhook";
+    const server = http.createServer(async (req, res) => {
+      try {
+        if (req.method !== "POST" || req.url?.split("?")[0] !== webhookPath) {
+          res.statusCode = 404;
+          res.end();
+          return;
+        }
+        const raw = await readBody(req);
+        const wreq = {
+          method: req.method,
+          headers: toNodeHeaders(req.headers),
+          body: raw,
+          rawBody: raw
+        };
+        const { update, duplicate } = processWebhook(wreq, {
+          secretToken: this.secretToken,
+          dedupe: this.dedupe
+        });
+        if (duplicate) {
+          res.statusCode = 200;
+          res.end("ok");
+          return;
+        }
+        const ctx = this.createContext(update, raw, duplicate);
+        await this.dispatch(ctx);
+        res.statusCode = 200;
+        res.end("ok");
+      } catch (e) {
+        if (e instanceof StarIMSignatureError) {
+          res.statusCode = 401;
+          res.end("unauthorized");
+          return;
+        }
+        res.statusCode = 500;
+        res.end("error");
+      }
+    });
+    return new Promise((resolve, reject) => {
+      server.listen(options.port, options.host ?? "0.0.0.0", () => resolve(server));
+      server.on("error", reject);
+    });
+  }
+  createContext(update, rawBody, duplicate) {
+    const flat = update;
+    if (update.type === "my_chat_member" && !update.my_chat_member && flat.chat && flat.from) {
+      update.my_chat_member = {
+        chat: flat.chat,
+        from: flat.from,
+        date: typeof update.date === "number" ? update.date : Math.floor(Date.now() / 1e3),
+        old_chat_member: flat.old_chat_member,
+        new_chat_member: flat.new_chat_member
+      };
+    }
+    if (update.type === "chat_member" && !update.chat_member && flat.chat && flat.from) {
+      update.chat_member = {
+        chat: flat.chat,
+        from: flat.from,
+        date: typeof update.date === "number" ? update.date : Math.floor(Date.now() / 1e3),
+        old_chat_member: flat.old_chat_member,
+        new_chat_member: flat.new_chat_member
+      };
+    }
+    if (update.type === "chat_join_request" && !update.chat_join_request && flat.chat && flat.from) {
+      update.chat_join_request = {
+        chat: flat.chat,
+        from: flat.from,
+        date: typeof update.date === "number" ? update.date : Math.floor(Date.now() / 1e3),
+        user_chat_id: flat.user_chat_id ?? "",
+        bio: flat.bio
+      };
+    }
+    const callbackQuery = update.callback_query;
+    const inlineQuery = update.inline_query;
+    const friendRequest = update.friend_request;
+    const myChatMember = update.my_chat_member;
+    const chatMember = update.chat_member;
+    const chatJoinRequest = update.chat_join_request;
+    const memberChat = myChatMember?.chat ?? chatMember?.chat ?? chatJoinRequest?.chat;
+    const message = update.message ?? callbackQuery?.message ?? {
+      message_id: "",
+      chat: memberChat ?? {
+        id: inlineQuery?.from?.id != null ? String(inlineQuery.from.id) : friendRequest?.from?.id != null ? String(friendRequest.from.id) : "",
+        type: "private"
+      },
+      date: Math.floor(Date.now() / 1e3)
+    };
+    const chat = message.chat;
+    return {
+      update,
+      rawBody,
+      duplicate,
+      client: this.client,
+      message,
+      chat,
+      callbackQuery,
+      inlineQuery,
+      friendRequest,
+      myChatMember,
+      chatMember,
+      chatJoinRequest,
+      reply: (text, options) => this.client.sendMessage({
+        chat_id: String(chat.id),
+        text,
+        reply_markup: options?.reply_markup
+      }),
+      answerCallback: (params = {}) => {
+        if (!callbackQuery?.id) {
+          return Promise.reject(new Error("answerCallback: current update is not callback_query"));
+        }
+        return this.client.answerCallbackQuery({
+          callback_query_id: callbackQuery.id,
+          ...params
+        });
+      },
+      answerInlineQuery: (params) => {
+        if (!inlineQuery?.id) {
+          return Promise.reject(new Error("answerInlineQuery: current update is not inline_query"));
+        }
+        return this.client.answerInlineQuery({
+          inline_query_id: inlineQuery.id,
+          ...params
+        });
+      }
+    };
+  }
+};
+function getRaw(req) {
+  if (Buffer.isBuffer(req.rawBody)) return req.rawBody;
+  if (Buffer.isBuffer(req.body)) return req.body;
+  throw new Error("webhookCallback: missing raw body");
+}
+
+exports.DEFAULT_TIMESTAMP_TOLERANCE_SEC = DEFAULT_TIMESTAMP_TOLERANCE_SEC;
+exports.LruDedupe = LruDedupe;
+exports.StarIMApiError = StarIMApiError;
+exports.StarIMBot = StarIMBot;
+exports.StarIMBotClient = StarIMBotClient;
+exports.StarIMSignatureError = StarIMSignatureError;
+exports.computeWebhookSignatureV2 = computeWebhookSignatureV2;
+exports.processWebhook = processWebhook;
+exports.sendDocumentFromPath = sendDocumentFromPath;
+exports.sendPhotoFromBuffer = sendPhotoFromBuffer;
+exports.sendPhotoFromPath = sendPhotoFromPath;
+exports.sendPhotoFromUrl = sendPhotoFromUrl;
+exports.sendVideoFromUrl = sendVideoFromUrl;
+exports.uploadFileFromPath = uploadFileFromPath;
+exports.uploadFromUrl = uploadFromUrl;
+exports.verifyWebhookSignature = verifyWebhookSignature;
+exports.webhookMiddleware = webhookMiddleware;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map