{"_id":"@afjs/telegram-bot-sdk","name":"@afjs/telegram-bot-sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@afjs/telegram-bot-sdk","version":"1.0.0","description":"Telegram Bot API的Node.js SDK","main":"dist/index.js","types":"dist/index.d.ts","type":"module","scripts":{"build":"tsdown","dev":"tsdown --watch","test":"echo \"Error: no test specified\" && exit 1","prepare":"pnpm build"},"keywords":["telegram","bot","api","sdk","webhook","messaging","nodejs"],"author":{"name":"tinsfox"},"license":"MIT","dependencies":{"ofetch":"^1.4.1"},"devDependencies":{"@types/node":"^20.19.12","tsdown":"^0.14.2","typescript":"^5.9.2"},"exports":{".":{"import":"./dist/index.js","require":"./dist/index.js","types":"./dist/index.d.ts"}},"_id":"@afjs/telegram-bot-sdk@1.0.0","gitHead":"719fc41eab126895aa1f3c766f9786ef84b3a4fe","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-Vq4dtA4BoVtq3tvPRk+D0vbdHNvML13B9cEj2bPqU96cAxI6zDleHsPUTlmL8EdOQC6IqwcKZzjpoJTPyQBePA==","shasum":"443d3d17916975bcf3276b67f894038b61b97b34","tarball":"https://registry.npmjs.org/@afjs/telegram-bot-sdk/-/telegram-bot-sdk-1.0.0.tgz","fileCount":11,"unpackedSize":252578,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCmc0jxy9hnChwGi/cWFa4WQ3EzcLloJ7jqhGFCEf+xpAIgSVmmo0O2zOtx0X7sh9Qn+NgDx3unGC3zxlvuTbPBsXM="}]},"_npmUser":{"name":"tinsfox","email":"menhuluy@gmail.com"},"directories":{},"maintainers":[{"name":"tinsfox","email":"menhuluy@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/telegram-bot-sdk_1.0.0_1762173884916_0.8685301678996886"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-03T12:44:44.811Z","1.0.0":"2025-11-03T12:44:45.141Z","modified":"2025-11-03T12:44:45.426Z"},"maintainers":[{"name":"tinsfox","email":"menhuluy@gmail.com"}],"description":"Telegram Bot API的Node.js SDK","keywords":["telegram","bot","api","sdk","webhook","messaging","nodejs"],"author":{"name":"tinsfox"},"license":"MIT","readme":"# Telegram Bot SDK\n\n[![npm version](https://badge.fury.io/js/%40afjs%2Ftelegram-bot-sdk.svg)](https://badge.fury.io/js/%40afjs%2Ftelegram-bot-sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n\n一个功能完整、类型安全的 Telegram Bot API Node.js SDK，基于 TypeScript 开发，提供简洁易用的 API 接口。\n\n**兼容性**：支持 Telegram Bot API 7.0+ 的所有功能，包括最新的消息类型、键盘、Webhook 和文件处理功能。\n\n## ✨ 特性\n\n- 🚀 **完整的 API 支持** - 支持 Telegram Bot API 的所有方法\n- 📝 **TypeScript 支持** - 完整的类型定义，提供优秀的开发体验\n- 🔄 **自动重试机制** - 内置请求重试和错误处理\n- 📁 **文件上传支持** - 支持各种文件类型的上传（图片、文档、音频等）\n- 🎯 **Webhook 支持** - 完整的 Webhook 设置和管理\n- 🛠️ **实用工具函数** - 丰富的辅助函数简化开发\n- 🎨 **键盘构建器** - 便捷的内联键盘和回复键盘构建\n- 🔐 **安全性** - 内置 Token 验证和安全处理\n- 📦 **轻量级** - 最小化依赖，高性能\n\n## 📦 安装\n\n### 系统要求\n\n- Node.js >= 18.0.0\n- 支持 ES Modules\n\n### 安装命令\n\n```bash\nnpm install @afjs/telegram-bot-sdk\n```\n\n```bash\nyarn add @afjs/telegram-bot-sdk\n```\n\n```bash\npnpm add @afjs/telegram-bot-sdk\n```\n\n## 🚀 快速开始\n\n### 基础使用\n\n```typescript\nimport { TelegramBot } from '@afjs/telegram-bot-sdk'\n\n// 创建机器人实例\nconst bot = new TelegramBot({\n  token: process.env.BOT_TOKEN!, // 从环境变量获取\n  timeout: 30000,\n  retries: 3\n})\n\n// 发送消息\nasync function sendMessage() {\n  try {\n    const chatId = process.env.CHAT_ID! // 从环境变量获取聊天 ID\n    const message = await bot.sendMessage({\n      chat_id: chatId,\n      text: '你好！这是来自 Telegram Bot SDK 的消息。'\n    })\n    console.log('消息已发送:', message.message_id)\n  } catch (error) {\n    if (error instanceof Error) {\n      console.error('发送失败:', error.message)\n\n      // 处理常见错误\n      if (error.message.includes('chat not found')) {\n        console.error('错误：聊天不存在，请检查 CHAT_ID')\n      } else if (error.message.includes('Unauthorized')) {\n        console.error('错误：Bot Token 无效，请检查 BOT_TOKEN')\n      }\n    } else {\n      console.error('未知错误:', error)\n    }\n  }\n}\n\nsendMessage()\n```\n\n### 获取机器人信息\n\n```typescript\nasync function getBotInfo() {\n  try {\n    const botInfo = await bot.getMe()\n    console.log('机器人信息:', botInfo)\n  } catch (error) {\n    console.error('获取信息失败:', error.message)\n  }\n}\n```\n\n## 📚 详细文档\n\n### 配置选项\n\n```typescript\ninterface BotConfig {\n  token: string        // 机器人 Token（必需）\n  baseUrl?: string     // API 基础 URL（可选，默认为官方 API）\n  timeout?: number     // 请求超时时间（毫秒，默认 30000）\n  retries?: number     // 重试次数（默认 0）\n}\n```\n\n### 消息发送\n\n#### 发送文本消息\n\n```typescript\nawait bot.sendMessage({\n  chat_id: chatId,\n  text: '这是一条文本消息',\n  parse_mode: 'HTML', // 支持 'HTML', 'MarkdownV2', 'Markdown'\n  disable_notification: false,\n  reply_markup: {\n    inline_keyboard: [[\n      { text: '按钮1', callback_data: 'btn1' },\n      { text: '按钮2', callback_data: 'btn2' }\n    ]]\n  }\n})\n```\n\n#### 发送图片\n\n```typescript\n// 发送网络图片\nawait bot.sendPhoto({\n  chat_id: chatId,\n  photo: 'https://example.com/image.jpg',\n  caption: '图片说明'\n})\n\n// 发送本地文件\nimport { readFileSync } from 'fs'\nconst imageBuffer = readFileSync('./image.jpg')\n\nawait bot.sendPhoto({\n  chat_id: chatId,\n  photo: imageBuffer,\n  caption: '本地图片'\n})\n```\n\n#### 发送文档\n\n```typescript\nawait bot.sendDocument({\n  chat_id: chatId,\n  document: documentBuffer, // Buffer 或文件 URL\n  caption: '文档说明',\n  disable_content_type_detection: false\n})\n```\n\n#### 发送其他媒体类型\n\n```typescript\n// 发送音频\nawait bot.sendAudio({\n  chat_id: chatId,\n  audio: audioBuffer,\n  duration: 180,\n  title: '音频标题',\n  performer: '演唱者'\n})\n\n// 发送视频\nawait bot.sendVideo({\n  chat_id: chatId,\n  video: videoBuffer,\n  duration: 60,\n  width: 1920,\n  height: 1080,\n  caption: '视频说明'\n})\n\n// 发送语音消息\nawait bot.sendVoice({\n  chat_id: chatId,\n  voice: voiceBuffer,\n  duration: 30\n})\n```\n\n### 键盘和按钮\n\n#### 内联键盘\n\n```typescript\nimport { createInlineKeyboard } from '@afjs/telegram-bot-sdk'\n\nconst keyboard = createInlineKeyboard([\n  [\n    { text: '选项1', callback_data: 'option1' },\n    { text: '选项2', callback_data: 'option2' }\n  ],\n  [\n    { text: '访问网站', url: 'https://example.com' }\n  ],\n  [\n    { text: '分享', switch_inline_query: 'share_text' }\n  ]\n])\n\nawait bot.sendMessage({\n  chat_id: chatId,\n  text: '请选择一个选项:',\n  reply_markup: keyboard\n})\n```\n\n#### 回复键盘\n\n```typescript\nimport { createReplyKeyboard } from '@afjs/telegram-bot-sdk'\n\nconst keyboard = createReplyKeyboard([\n  [{ text: '🔍 搜索' }, { text: '⚙️ 设置' }],\n  [{ text: '📊 统计' }, { text: '❓ 帮助' }],\n  [{ text: '🚪 退出' }]\n], {\n  resize_keyboard: true,\n  one_time_keyboard: true\n})\n\nawait bot.sendMessage({\n  chat_id: chatId,\n  text: '选择功能:',\n  reply_markup: keyboard\n})\n```\n\n#### 移除键盘\n\n```typescript\nimport { removeKeyboard } from '@afjs/telegram-bot-sdk'\n\nawait bot.sendMessage({\n  chat_id: chatId,\n  text: '键盘已移除',\n  reply_markup: removeKeyboard()\n})\n```\n\n### 处理更新\n\n#### 轮询方式\n\n```typescript\nasync function startPolling() {\n  let offset = 0\n\n  while (true) {\n    try {\n      const updates = await bot.getUpdates({\n        offset,\n        limit: 100,\n        timeout: 30\n      })\n\n      for (const update of updates) {\n        await handleUpdate(update)\n        offset = update.update_id + 1\n      }\n    } catch (error) {\n      console.error('获取更新失败:', error.message)\n      await new Promise(resolve => setTimeout(resolve, 5000))\n    }\n  }\n}\n\nasync function handleUpdate(update) {\n  if (update.message) {\n    await handleMessage(update.message)\n  }\n\n  if (update.callback_query) {\n    await handleCallbackQuery(update.callback_query)\n  }\n}\n```\n\n#### Webhook 方式\n\n```typescript\n// 设置 Webhook\nawait bot.setWebhook({\n  url: 'https://yourdomain.com/webhook',\n  secret_token: 'your_secret_token',\n  max_connections: 100,\n  allowed_updates: ['message', 'callback_query']\n})\n\n// 获取 Webhook 信息\nconst webhookInfo = await bot.getWebhookInfo()\nconsole.log('Webhook 信息:', webhookInfo)\n\n// 删除 Webhook\nawait bot.deleteWebhook()\n```\n\n### 实用工具函数\n\n#### 消息处理工具\n\n```typescript\nimport {\n  getMessageFromUpdate,\n  getUserIdFromUpdate,\n  getChatIdFromUpdate,\n  getTextFromMessage,\n  isCommand,\n  getCommandArgs\n} from '@afjs/telegram-bot-sdk'\n\n// 从更新中提取消息\nconst message = getMessageFromUpdate(update)\n\n// 提取用户ID和聊天ID\nconst userId = getUserIdFromUpdate(update)\nconst chatId = getChatIdFromUpdate(update)\n\n// 检查是否为命令\nif (isCommand(message, 'start')) {\n  const args = getCommandArgs(message)\n  console.log('命令参数:', args)\n}\n```\n\n#### 文本格式化工具\n\n```typescript\nimport {\n  escapeHTML,\n  escapeMarkdownV2,\n  formatMessage\n} from '@afjs/telegram-bot-sdk'\n\n// HTML 转义\nconst safeText = escapeHTML('<b>用户输入</b>')\n\n// MarkdownV2 转义\nconst markdownText = escapeMarkdownV2('*特殊字符*')\n\n// 自动格式化\nconst formatted = formatMessage('用户输入', 'HTML')\n```\n\n#### 验证工具\n\n```typescript\nimport {\n  isValidBotToken,\n  getBotIdFromToken,\n  isFileSizeValid\n} from '@afjs/telegram-bot-sdk'\n\n// 验证 Token 格式\nif (isValidBotToken(token)) {\n  const botId = getBotIdFromToken(token)\n  console.log('Bot ID:', botId)\n}\n\n// 验证文件大小\nif (isFileSizeValid(fileSize, 'photo')) {\n  // 文件大小符合要求\n}\n```\n\n#### 其他实用工具\n\n```typescript\nimport {\n  delay,\n  chunk,\n  truncateText,\n  formatFileSize,\n  generateRandomString\n} from '@afjs/telegram-bot-sdk'\n\n// 延迟执行\nawait delay(1000) // 等待1秒\n\n// 数组分块\nconst chunks = chunk([1, 2, 3, 4, 5], 2) // [[1, 2], [3, 4], [5]]\n\n// 截断文本\nconst short = truncateText('很长的文本...', 10) // \"很长的文本...\"\n\n// 格式化文件大小\nconst size = formatFileSize(1024) // \"1 KB\"\n\n// 生成随机字符串\nconst random = generateRandomString(10)\n```\n\n### 文件操作\n\n#### 获取文件信息\n\n```typescript\n// 获取文件信息\nconst file = await bot.getFile('file_id')\nconsole.log('文件路径:', file.file_path)\n\n// 获取文件下载链接\nconst downloadUrl = bot.getFileUrl(file.file_path)\nconsole.log('下载链接:', downloadUrl)\n```\n\n#### 文件上传\n\n```typescript\nimport { readFileSync } from 'fs'\n\n// 上传本地文件\nconst fileBuffer = readFileSync('./document.pdf')\nawait bot.sendDocument({\n  chat_id: chatId,\n  document: fileBuffer,\n  caption: 'PDF 文档'\n})\n\n// 上传网络文件\nawait bot.sendDocument({\n  chat_id: chatId,\n  document: 'https://example.com/document.pdf',\n  caption: '网络文档'\n})\n```\n\n### 消息管理\n\n#### 编辑消息\n\n```typescript\n// 编辑文本消息\nawait bot.editMessageText({\n  chat_id: chatId,\n  message_id: messageId,\n  text: '更新后的消息内容',\n  parse_mode: 'HTML'\n})\n```\n\n#### 删除消息\n\n```typescript\n// 删除单条消息\nawait bot.deleteMessage({\n  chat_id: chatId,\n  message_id: messageId\n})\n\n// 删除多条消息\nawait bot.deleteMessages({\n  chat_id: chatId,\n  message_ids: [messageId1, messageId2, messageId3]\n})\n```\n\n### 回调查询处理\n\n```typescript\nasync function handleCallbackQuery(callbackQuery) {\n  // 应答回调查询（必需）\n  await bot.answerCallbackQuery({\n    callback_query_id: callbackQuery.id,\n    text: '操作完成',\n    show_alert: false\n  })\n\n  // 处理回调数据\n  const data = callbackQuery.data\n  switch (data) {\n    case 'button1':\n      // 处理按钮1点击\n      break\n    case 'button2':\n      // 处理按钮2点击\n      break\n  }\n}\n```\n\n### 内联查询处理\n\n```typescript\nasync function handleInlineQuery(inlineQuery) {\n  const results = [\n    {\n      type: 'article',\n      id: '1',\n      title: '搜索结果1',\n      description: '描述信息',\n      input_message_content: {\n        message_text: '这是搜索结果1的内容'\n      }\n    }\n  ]\n\n  await bot.answerInlineQuery({\n    inline_query_id: inlineQuery.id,\n    results: results,\n    cache_time: 300\n  })\n}\n```\n\n### 投票功能\n\n```typescript\n// 创建投票\nawait bot.sendPoll({\n  chat_id: chatId,\n  question: '你最喜欢哪种编程语言？',\n  options: ['JavaScript', 'Python', 'Go', 'Rust'],\n  is_anonymous: false,\n  type: 'regular',\n  allows_multiple_answers: true\n})\n\n// 创建测验\nawait bot.sendPoll({\n  chat_id: chatId,\n  question: '2 + 2 = ?',\n  options: ['3', '4', '5', '6'],\n  type: 'quiz',\n  correct_option_id: 1,\n  explanation: '2 + 2 等于 4'\n})\n```\n\n### 位置和联系人\n\n```typescript\n// 发送位置\nawait bot.sendLocation({\n  chat_id: chatId,\n  latitude: 39.9042,\n  longitude: 116.4074,\n  live_period: 3600 // 实时位置持续时间（秒）\n})\n\n// 发送联系人\nawait bot.sendContact({\n  chat_id: chatId,\n  phone_number: '+1234567890',\n  first_name: 'John',\n  last_name: 'Doe'\n})\n```\n\n## 🔧 高级功能\n\n### 错误处理\n\n```typescript\nimport { TelegramBot } from '@afjs/telegram-bot-sdk'\n\nconst bot = new TelegramBot({\n  token: 'YOUR_TOKEN',\n  retries: 3,\n  timeout: 30000\n})\n\ntry {\n  await bot.sendMessage({\n    chat_id: 'invalid_chat_id',\n    text: 'Test message'\n  })\n} catch (error) {\n  if (error.message.includes('chat not found')) {\n    console.log('聊天不存在')\n  } else if (error.message.includes('bot was blocked')) {\n    console.log('机器人被用户屏蔽')\n  } else {\n    console.error('其他错误:', error.message)\n  }\n}\n```\n\n### 批量操作\n\n```typescript\nimport { chunk, delay } from '@afjs/telegram-bot-sdk'\n\n// 批量发送消息（避免触发限制）\nasync function sendBulkMessages(chatIds, message) {\n  const batches = chunk(chatIds, 30) // 每批30个\n\n  for (const batch of batches) {\n    const promises = batch.map(chatId =>\n      bot.sendMessage({ chat_id: chatId, text: message })\n        .catch(error => console.error(`发送到 ${chatId} 失败:`, error.message))\n    )\n\n    await Promise.allSettled(promises)\n    await delay(1000) // 批次间延迟1秒\n  }\n}\n```\n\n### 深度链接\n\n```typescript\nimport { buildDeepLink } from '@afjs/telegram-bot-sdk'\n\n// 创建深度链接\nconst deepLink = buildDeepLink('your_bot_username', 'start_parameter')\nconsole.log('深度链接:', deepLink)\n// 输出: https://t.me/your_bot_username?start=start_parameter\n```\n\n## 🌐 Serverless 环境使用\n\n### Cloudflare Workers\n\nTelegram Bot SDK 完全兼容 Cloudflare Workers 环境。以下是完整的实现示例：\n\n#### 基础设置\n\n```typescript\n// worker.ts\nimport { TelegramBot, isCommand, getCommandArgs, escapeHTML } from '@afjs/telegram-bot-sdk'\n\nexport interface Env {\n  BOT_TOKEN: string\n  WEBHOOK_SECRET?: string\n}\n\nexport default {\n  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {\n    const bot = new TelegramBot({\n      token: env.BOT_TOKEN,\n      timeout: 10000 // Cloudflare Workers 有执行时间限制\n    })\n\n    const url = new URL(request.url)\n\n    // 处理 Webhook\n    if (request.method === 'POST' && url.pathname === '/webhook') {\n      return handleWebhook(request, bot, env)\n    }\n\n    // 设置 Webhook\n    if (request.method === 'GET' && url.pathname === '/set-webhook') {\n      return setWebhook(bot, url.origin, env)\n    }\n\n    return new Response('Telegram Bot is running!', { status: 200 })\n  }\n}\n\nasync function handleWebhook(request: Request, bot: TelegramBot, env: Env): Promise<Response> {\n  try {\n    // 验证 Webhook Secret（强烈推荐）\n    if (env.WEBHOOK_SECRET) {\n      const secretHeader = request.headers.get('X-Telegram-Bot-Api-Secret-Token')\n      if (!secretHeader || secretHeader !== env.WEBHOOK_SECRET) {\n        console.warn('Webhook 验证失败:', {\n          expected: env.WEBHOOK_SECRET,\n          received: secretHeader,\n          headers: Object.fromEntries(request.headers.entries())\n        })\n        return new Response('Unauthorized - Invalid secret token', { status: 401 })\n      }\n      console.log('✅ Webhook Secret 验证成功')\n    } else {\n      console.warn('⚠️  未设置 WEBHOOK_SECRET，建议设置以提高安全性')\n    }\n\n    const update = await request.json()\n    await handleUpdate(update, bot)\n\n    return new Response('OK', { status: 200 })\n  } catch (error) {\n    console.error('Webhook 处理错误:', error)\n    return new Response('Internal Server Error', { status: 500 })\n  }\n}\n\nasync function setWebhook(bot: TelegramBot, origin: string, env: Env): Promise<Response> {\n  try {\n    const webhookUrl = `${origin}/webhook`\n\n    await bot.setWebhook({\n      url: webhookUrl,\n      secret_token: env.WEBHOOK_SECRET,\n      allowed_updates: ['message', 'callback_query', 'inline_query']\n    })\n\n    return new Response(`Webhook 已设置: ${webhookUrl}`, { status: 200 })\n  } catch (error) {\n    return new Response(`设置 Webhook 失败: ${error.message}`, { status: 500 })\n  }\n}\n\nasync function handleUpdate(update: any, bot: TelegramBot) {\n  if (update.message) {\n    await handleMessage(update.message, bot)\n  }\n\n  if (update.callback_query) {\n    await handleCallbackQuery(update.callback_query, bot)\n  }\n\n  if (update.inline_query) {\n    await handleInlineQuery(update.inline_query, bot)\n  }\n}\n\nasync function handleMessage(message: any, bot: TelegramBot) {\n  const chatId = message.chat.id\n  const text = message.text || ''\n\n  if (isCommand(message, 'start')) {\n    await bot.sendMessage({\n      chat_id: chatId,\n      text: `你好 ${escapeHTML(message.from.first_name)}！\\n\\n这个机器人运行在 Cloudflare Workers 上。\\n\\n可用命令:\\n/help - 帮助\\n/ping - 测试响应\\n/time - 当前时间`,\n      parse_mode: 'HTML'\n    })\n  } else if (isCommand(message, 'help')) {\n    await bot.sendMessage({\n      chat_id: chatId,\n      text: '🤖 <b>Serverless Telegram Bot</b>\\n\\n' +\n            '这是一个运行在 Cloudflare Workers 上的 Telegram 机器人示例。\\n\\n' +\n            '<b>可用命令:</b>\\n' +\n            '/start - 开始使用\\n' +\n            '/help - 显示帮助\\n' +\n            '/ping - 测试机器人响应\\n' +\n            '/time - 显示当前时间\\n' +\n            '/echo &lt;文本&gt; - 回显消息',\n      parse_mode: 'HTML'\n    })\n  } else if (isCommand(message, 'ping')) {\n    const startTime = Date.now()\n    await bot.sendMessage({\n      chat_id: chatId,\n      text: `🏓 Pong! 响应时间: ${Date.now() - startTime}ms`\n    })\n  } else if (isCommand(message, 'time')) {\n    await bot.sendMessage({\n      chat_id: chatId,\n      text: `🕐 当前时间: ${new Date().toISOString()}`\n    })\n  } else if (isCommand(message, 'echo')) {\n    const args = getCommandArgs(message)\n    const echoText = args.join(' ') || '请提供要回显的文本'\n    await bot.sendMessage({\n      chat_id: chatId,\n      text: `📢 ${escapeHTML(echoText)}`,\n      parse_mode: 'HTML'\n    })\n  } else if (text) {\n    // 处理普通消息\n    await bot.sendMessage({\n      chat_id: chatId,\n      text: '我收到了你的消息！使用 /help 查看可用命令。'\n    })\n  }\n}\n\nasync function handleCallbackQuery(callbackQuery: any, bot: TelegramBot) {\n  await bot.answerCallbackQuery({\n    callback_query_id: callbackQuery.id,\n    text: '操作完成'\n  })\n\n  // 处理回调数据\n  const data = callbackQuery.data\n  const chatId = callbackQuery.message.chat.id\n\n  switch (data) {\n    case 'button_clicked':\n      await bot.sendMessage({\n        chat_id: chatId,\n        text: '按钮被点击了！'\n      })\n      break\n  }\n}\n\nasync function handleInlineQuery(inlineQuery: any, bot: TelegramBot) {\n  const results = [\n    {\n      type: 'article',\n      id: '1',\n      title: 'Serverless Bot',\n      description: '来自 Cloudflare Workers 的问候',\n      input_message_content: {\n        message_text: '🚀 这条消息来自运行在 Cloudflare Workers 上的 Telegram Bot！'\n      }\n    }\n  ]\n\n  await bot.answerInlineQuery({\n    inline_query_id: inlineQuery.id,\n    results: results,\n    cache_time: 300\n  })\n}\n```\n\n#### wrangler.toml 配置\n\n```toml\nname = \"telegram-bot\"\nmain = \"src/worker.ts\"\ncompatibility_date = \"2024-01-01\"\n\n# 环境变量通过 wrangler secret 命令设置，不在此文件中配置\n# 使用命令：wrangler secret put BOT_TOKEN\n# 使用命令：wrangler secret put WEBHOOK_SECRET\n```\n\n#### 部署步骤\n\n```bash\n# 1. 安装 Wrangler CLI\nnpm install -g wrangler\n\n# 2. 登录 Cloudflare\nwrangler login\n\n# 3. 创建项目\nmkdir telegram-bot-worker\ncd telegram-bot-worker\nnpm init -y\n\n# 4. 安装依赖\nnpm install @afjs/telegram-bot-sdk\nnpm install -D @cloudflare/workers-types typescript\n\n# 5. 设置环境变量\nwrangler secret put BOT_TOKEN\nwrangler secret put WEBHOOK_SECRET\n\n# 6. 部署\nwrangler deploy\n\n# 7. 设置 Webhook（重要！）\n# 部署完成后，访问你的 Worker URL 来设置 Webhook\n# 例如：https://your-worker.your-subdomain.workers.dev/set-webhook\n# 或者使用 curl 命令直接设置：\ncurl -X POST \"https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"url\": \"https://your-worker.your-subdomain.workers.dev/webhook\",\n       \"secret_token\": \"your_webhook_secret\"\n     }'\n```\n\n#### 设置 Webhook 的几种方式\n\n**方式1：通过浏览器访问**\n```\nhttps://your-worker.your-subdomain.workers.dev/set-webhook\n```\n\n**方式2：使用 curl 命令**\n```bash\ncurl -X POST \"https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\n       \"url\": \"https://your-worker.your-subdomain.workers.dev/webhook\",\n       \"secret_token\": \"your_webhook_secret\",\n       \"allowed_updates\": [\"message\", \"callback_query\", \"inline_query\"]\n     }'\n```\n\n**方式3：使用 SDK 设置（推荐）**\n```typescript\n// setup-webhook.ts - 单独的设置脚本\nimport { TelegramBot } from '@afjs/telegram-bot-sdk'\n\nconst bot = new TelegramBot({\n  token: process.env.BOT_TOKEN! // 从环境变量获取\n})\n\nasync function setupWebhook() {\n  try {\n    const webhookUrl = process.env.WEBHOOK_URL! // 从环境变量获取 Webhook URL\n    const webhookSecret = process.env.WEBHOOK_SECRET! // 从环境变量获取密钥\n\n    await bot.setWebhook({\n      url: webhookUrl,\n      secret_token: webhookSecret,\n      allowed_updates: ['message', 'callback_query', 'inline_query'],\n      drop_pending_updates: true // 清除待处理的更新\n    })\n\n    console.log('✅ Webhook 设置成功')\n    console.log('Webhook URL:', webhookUrl)\n\n    // 验证 Webhook 设置\n    const webhookInfo = await bot.getWebhookInfo()\n    console.log('Webhook 信息:', {\n      url: webhookInfo.url,\n      pendingUpdateCount: webhookInfo.pending_update_count,\n      lastErrorDate: webhookInfo.last_error_date,\n      lastErrorMessage: webhookInfo.last_error_message\n    })\n  } catch (error) {\n    if (error instanceof Error) {\n      console.error('❌ Webhook 设置失败:', error.message)\n    } else {\n      console.error('❌ 未知错误:', error)\n    }\n  }\n}\n\nsetupWebhook()\n```\n\n### Vercel Edge Functions\n\n```typescript\n// api/webhook.ts\nimport { TelegramBot } from '@afjs/telegram-bot-sdk'\nimport type { NextRequest } from 'next/server'\n\nexport const config = {\n  runtime: 'edge'\n}\n\nexport default async function handler(req: NextRequest) {\n  if (req.method !== 'POST') {\n    return new Response('Method not allowed', { status: 405 })\n  }\n\n  // 验证 Webhook Secret\n  if (process.env.WEBHOOK_SECRET) {\n    const secretHeader = req.headers.get('X-Telegram-Bot-Api-Secret-Token')\n    if (!secretHeader || secretHeader !== process.env.WEBHOOK_SECRET) {\n      console.warn('Webhook 验证失败:', {\n        expected: process.env.WEBHOOK_SECRET,\n        received: secretHeader\n      })\n      return new Response('Unauthorized - Invalid secret token', { status: 401 })\n    }\n    console.log('✅ Webhook Secret 验证成功')\n  } else {\n    console.warn('⚠️  未设置 WEBHOOK_SECRET，建议设置以提高安全性')\n  }\n\n  const bot = new TelegramBot({\n    token: process.env.BOT_TOKEN!,\n    timeout: 10000\n  })\n\n  try {\n    const update = await req.json()\n\n    if (update.message) {\n      const chatId = update.message.chat.id\n      const text = update.message.text || ''\n\n      if (text.startsWith('/start')) {\n        await bot.sendMessage({\n          chat_id: chatId,\n          text: '你好！这是运行在 Vercel Edge Functions 上的机器人。'\n        })\n      }\n    }\n\n    return new Response('OK')\n  } catch (error) {\n    console.error('处理更新失败:', error)\n    return new Response('Internal Server Error', { status: 500 })\n  }\n}\n```\n\n```typescript\n// api/set-webhook.ts - 设置 Webhook 的端点\nimport { TelegramBot } from '@afjs/telegram-bot-sdk'\nimport type { NextRequest } from 'next/server'\n\nexport const config = {\n  runtime: 'edge'\n}\n\nexport default async function handler(req: NextRequest) {\n  if (req.method !== 'GET') {\n    return new Response('Method not allowed', { status: 405 })\n  }\n\n  const bot = new TelegramBot({\n    token: process.env.BOT_TOKEN!\n  })\n\n  try {\n    const url = new URL(req.url)\n    const webhookUrl = `${url.origin}/api/webhook`\n\n    await bot.setWebhook({\n      url: webhookUrl,\n      secret_token: process.env.WEBHOOK_SECRET,\n      allowed_updates: ['message', 'callback_query', 'inline_query']\n    })\n\n    return new Response(`✅ Webhook 已设置: ${webhookUrl}`)\n  } catch (error) {\n    return new Response(`❌ 设置失败: ${error.message}`, { status: 500 })\n  }\n}\n```\n\n#### Vercel 部署步骤\n\n```bash\n# 1. 创建 Next.js 项目\nnpx create-next-app@latest telegram-bot-vercel\ncd telegram-bot-vercel\n\n# 2. 安装依赖\nnpm install @afjs/telegram-bot-sdk\n\n# 3. 设置环境变量\nvercel env add BOT_TOKEN\nvercel env add WEBHOOK_SECRET\n\n# 4. 部署\nvercel deploy\n\n# 5. 设置 Webhook\n# 访问：https://your-app.vercel.app/api/set-webhook\n```\n\n### AWS Lambda\n\n```typescript\n// lambda/handler.ts\nimport { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda'\nimport { TelegramBot } from '@afjs/telegram-bot-sdk'\n\nconst bot = new TelegramBot({\n  token: process.env.BOT_TOKEN!,\n  timeout: 10000\n})\n\nexport const webhook = async (\n  event: APIGatewayProxyEvent\n): Promise<APIGatewayProxyResult> => {\n  try {\n    if (event.httpMethod !== 'POST') {\n      return {\n        statusCode: 405,\n        body: 'Method not allowed'\n      }\n    }\n\n    // 验证 Webhook Secret\n    if (process.env.WEBHOOK_SECRET) {\n      const secretHeader = event.headers['X-Telegram-Bot-Api-Secret-Token'] ||\n                          event.headers['x-telegram-bot-api-secret-token']\n      if (!secretHeader || secretHeader !== process.env.WEBHOOK_SECRET) {\n        console.warn('Webhook 验证失败:', {\n          expected: process.env.WEBHOOK_SECRET,\n          received: secretHeader,\n          headers: event.headers\n        })\n        return {\n          statusCode: 401,\n          body: 'Unauthorized - Invalid secret token'\n        }\n      }\n      console.log('✅ Webhook Secret 验证成功')\n    } else {\n      console.warn('⚠️  未设置 WEBHOOK_SECRET，建议设置以提高安全性')\n    }\n\n    const update = JSON.parse(event.body || '{}')\n\n    if (update.message) {\n      const chatId = update.message.chat.id\n      const text = update.message.text || ''\n\n      if (text.startsWith('/start')) {\n        await bot.sendMessage({\n          chat_id: chatId,\n          text: '你好！这是运行在 AWS Lambda 上的机器人。'\n        })\n      }\n    }\n\n    return {\n      statusCode: 200,\n      body: 'OK'\n    }\n  } catch (error) {\n    console.error('Lambda 处理错误:', error)\n    return {\n      statusCode: 500,\n      body: 'Internal Server Error'\n    }\n  }\n}\n\n// 设置 Webhook 的 Lambda 函数\nexport const setWebhook = async (\n  event: APIGatewayProxyEvent\n): Promise<APIGatewayProxyResult> => {\n  try {\n    const headers = event.headers\n    const host = headers.Host || headers.host\n    const stage = event.requestContext.stage\n    const webhookUrl = `https://${host}/${stage}/webhook`\n\n    await bot.setWebhook({\n      url: webhookUrl,\n      secret_token: process.env.WEBHOOK_SECRET,\n      allowed_updates: ['message', 'callback_query', 'inline_query']\n    })\n\n    return {\n      statusCode: 200,\n      body: JSON.stringify({\n        message: '✅ Webhook 设置成功',\n        url: webhookUrl\n      })\n    }\n  } catch (error) {\n    return {\n      statusCode: 500,\n      body: JSON.stringify({\n        error: '❌ Webhook 设置失败',\n        message: error.message\n      })\n    }\n  }\n}\n```\n\n#### serverless.yml 配置\n\n```yaml\nservice: telegram-bot\n\nprovider:\n  name: aws\n  runtime: nodejs18.x\n  region: us-east-1\n  environment:\n    BOT_TOKEN: ${env:BOT_TOKEN}\n    WEBHOOK_SECRET: ${env:WEBHOOK_SECRET}\n\nfunctions:\n  webhook:\n    handler: lambda/handler.webhook\n    events:\n      - http:\n          path: webhook\n          method: post\n          cors: true\n\n  setWebhook:\n    handler: lambda/handler.setWebhook\n    events:\n      - http:\n          path: set-webhook\n          method: get\n          cors: true\n\nplugins:\n  - serverless-offline\n```\n\n#### AWS Lambda 部署步骤\n\n```bash\n# 1. 安装 Serverless Framework\nnpm install -g serverless\n\n# 2. 创建项目\nserverless create --template aws-nodejs-typescript --path telegram-bot-lambda\ncd telegram-bot-lambda\n\n# 3. 安装依赖\nnpm install @afjs/telegram-bot-sdk\nnpm install -D @types/aws-lambda\n\n# 4. 配置 AWS 凭证\nserverless config credentials --provider aws --key YOUR_ACCESS_KEY --secret YOUR_SECRET_KEY\n\n# 5. 设置环境变量\nexport BOT_TOKEN=\"your_bot_token\"\nexport WEBHOOK_SECRET=\"your_webhook_secret\"\n\n# 6. 部署\nserverless deploy\n\n# 7. 设置 Webhook\n# 访问部署后的 URL：https://your-api-id.execute-api.region.amazonaws.com/dev/set-webhook\n```\n\n### Serverless 环境最佳实践\n\n#### 0. Webhook 设置（必需步骤）\n\n**重要：** 在 Serverless 环境中，必须先设置 Webhook，Telegram 才会将更新发送到你的函数。\n\n```typescript\n// 验证 Webhook 是否设置成功\nasync function checkWebhook() {\n  const bot = new TelegramBot({ token: process.env.BOT_TOKEN! })\n\n  try {\n    const webhookInfo = await bot.getWebhookInfo()\n    console.log('Webhook 状态:', {\n      url: webhookInfo.url,\n      hasCustomCertificate: webhookInfo.has_custom_certificate,\n      pendingUpdateCount: webhookInfo.pending_update_count,\n      lastErrorDate: webhookInfo.last_error_date,\n      lastErrorMessage: webhookInfo.last_error_message\n    })\n\n    if (!webhookInfo.url) {\n      console.warn('⚠️  Webhook 未设置！机器人无法接收消息。')\n    } else {\n      console.log('✅ Webhook 已正确设置')\n    }\n  } catch (error) {\n    console.error('检查 Webhook 失败:', error.message)\n  }\n}\n```\n\n**删除 Webhook（切换到轮询模式时）**\n```typescript\nasync function removeWebhook() {\n  const bot = new TelegramBot({ token: process.env.BOT_TOKEN! })\n\n  try {\n    await bot.deleteWebhook({ drop_pending_updates: true })\n    console.log('✅ Webhook 已删除')\n  } catch (error) {\n    console.error('删除 Webhook 失败:', error.message)\n  }\n}\n```\n\n#### 1. 超时设置\n\n```typescript\n// Serverless 环境通常有执行时间限制\nconst bot = new TelegramBot({\n  token: process.env.BOT_TOKEN!,\n  timeout: 8000, // 设置较短的超时时间\n  retries: 1     // 减少重试次数\n})\n```\n\n#### 2. 错误处理\n\n```typescript\nasync function handleUpdate(update: any, bot: TelegramBot) {\n  try {\n    // 处理更新逻辑\n    if (update.message) {\n      await handleMessage(update.message, bot)\n    }\n  } catch (error) {\n    console.error('处理更新失败:', error)\n    // 在 Serverless 环境中，不要抛出错误，而是记录并继续\n    // 避免导致 Webhook 重试\n  }\n}\n```\n\n#### 3. 状态管理\n\n```typescript\n// 在 Serverless 环境中，如果需要状态管理，使用外部存储\n// 例如：Redis、DynamoDB、Cloudflare KV、PostgreSQL 等\n// 注意：内存状态在每次函数调用后都会丢失\n\n// 示例：使用外部存储接口\ninterface StateStorage {\n  get(key: string): Promise<any>\n  set(key: string, value: any): Promise<void>\n}\n\nclass ServerlessBot {\n  constructor(private bot: TelegramBot, private storage: StateStorage) {}\n\n  async getUserState(userId: number): Promise<any> {\n    return await this.storage.get(`state:${userId}`)\n  }\n\n  async setUserState(userId: number, state: any): Promise<void> {\n    await this.storage.set(`state:${userId}`, state)\n  }\n}\n```\n\n#### 4. 批量操作优化\n\n```typescript\n// 在 Serverless 环境中避免长时间运行的批量操作\nasync function sendBulkMessages(chatIds: number[], message: string, bot: TelegramBot) {\n  // 限制批量大小\n  const maxBatch = 10\n  const batch = chatIds.slice(0, maxBatch)\n\n  const promises = batch.map(chatId =>\n    bot.sendMessage({ chat_id: chatId, text: message })\n      .catch(error => console.error(`发送失败 ${chatId}:`, error.message))\n  )\n\n  await Promise.allSettled(promises)\n\n  // 如果还有更多消息，可以触发另一个函数调用\n  if (chatIds.length > maxBatch) {\n    // 触发队列或另一个函数处理剩余消息\n  }\n}\n```\n\n#### 5. 冷启动优化\n\n```typescript\n// 在模块级别初始化机器人实例（Lambda 等环境）\nconst bot = new TelegramBot({\n  token: process.env.BOT_TOKEN!\n})\n\nexport const handler = async (event: any) => {\n  // 使用预初始化的机器人实例\n  // 减少冷启动时间\n}\n```\n\n### 环境变量配置\n\n不同 Serverless 平台的环境变量设置：\n\n```bash\n# Cloudflare Workers\nwrangler secret put BOT_TOKEN\n\n# Vercel\nvercel env add BOT_TOKEN\n\n# AWS Lambda (使用 Serverless Framework)\n# serverless.yml\nenvironment:\n  BOT_TOKEN: ${env:BOT_TOKEN}\n\n# Netlify\nnetlify env:set BOT_TOKEN your_token_here\n```\n\n## 📝 示例项目\n\n### 基础机器人\n\n```typescript\nimport { TelegramBot, isCommand, getCommandArgs } from '@afjs/telegram-bot-sdk'\n\nconst bot = new TelegramBot({\n  token: process.env.BOT_TOKEN!\n})\n\nasync function handleMessage(message) {\n  const chatId = message.chat.id\n\n  if (isCommand(message, 'start')) {\n    await bot.sendMessage({\n      chat_id: chatId,\n      text: '欢迎使用机器人！发送 /help 查看帮助。'\n    })\n  } else if (isCommand(message, 'help')) {\n    await bot.sendMessage({\n      chat_id: chatId,\n      text: '可用命令:\\n/start - 开始\\n/help - 帮助\\n/echo <文本> - 回显'\n    })\n  } else if (isCommand(message, 'echo')) {\n    const args = getCommandArgs(message)\n    const text = args.join(' ') || '请提供要回显的文本'\n    await bot.sendMessage({\n      chat_id: chatId,\n      text: `回显: ${text}`\n    })\n  }\n}\n\n// 启动轮询\nasync function startBot() {\n  let offset = 0\n\n  while (true) {\n    try {\n      const updates = await bot.getUpdates({ offset, timeout: 30 })\n\n      for (const update of updates) {\n        if (update.message) {\n          await handleMessage(update.message)\n        }\n        offset = update.update_id + 1\n      }\n    } catch (error) {\n      console.error('轮询错误:', error.message)\n      await new Promise(resolve => setTimeout(resolve, 5000))\n    }\n  }\n}\n\nstartBot()\n```\n\n### 完整示例\n\n查看 `examples/` 目录中的完整示例：\n\n- `basic.js` - 基础功能演示\n- `advanced.js` - 高级功能和完整机器人实现\n\n## 🔒 安全注意事项\n\n1. **保护 Bot Token**\n   ```typescript\n   // ❌ 不要在代码中硬编码 Token\n   const bot = new TelegramBot({ token: '123456:ABC-DEF...' })\n\n   // ✅ 使用环境变量\n   const bot = new TelegramBot({ token: process.env.BOT_TOKEN! })\n   ```\n\n2. **验证 Webhook Secret（重要）**\n   ```typescript\n   // 在 Serverless 环境中，必须验证 Webhook Secret\n   async function handleWebhook(request: Request) {\n     // 获取 Telegram 发送的 Secret Token\n     const secretHeader = request.headers.get('X-Telegram-Bot-Api-Secret-Token')\n\n     if (!secretHeader || secretHeader !== process.env.WEBHOOK_SECRET) {\n       console.warn('Webhook 验证失败 - 可能是恶意请求')\n       return new Response('Unauthorized', { status: 401 })\n     }\n\n     // 验证通过，处理更新\n     const update = await request.json()\n     // ... 处理逻辑\n   }\n   ```\n\n   **为什么需要验证 Webhook Secret？**\n   - 防止恶意用户向你的端点发送虚假更新\n   - 确保请求确实来自 Telegram 服务器\n   - 避免 DDoS 攻击和资源浪费\n\n3. **生成安全的 Webhook Secret**\n   ```typescript\n   import { generateRandomString } from '@afjs/telegram-bot-sdk'\n\n   // 生成强随机字符串作为 Secret\n   const webhookSecret = generateRandomString(32)\n   console.log('Webhook Secret:', webhookSecret)\n\n   // 或者使用 Node.js crypto 模块\n   import { randomBytes } from 'crypto'\n   const secret = randomBytes(32).toString('hex')\n   ```\n\n4. **验证用户输入**\n   ```typescript\n   import { escapeHTML } from '@afjs/telegram-bot-sdk'\n\n   // 转义用户输入以防止注入攻击\n   const safeText = escapeHTML(userInput)\n   ```\n\n5. **限制访问**\n   ```typescript\n   const ALLOWED_USERS = [123456789, 987654321]\n\n   if (!ALLOWED_USERS.includes(message.from.id)) {\n     return // 拒绝未授权用户\n   }\n   ```\n\n6. **IP 白名单（可选）**\n   ```typescript\n   // Telegram Webhook IP 范围（可选验证）\n   const TELEGRAM_IP_RANGES = [\n     '149.154.160.0/20',\n     '91.108.4.0/22'\n   ]\n\n   function isValidTelegramIP(ip: string): boolean {\n     // 实现 IP 范围检查逻辑\n     // 注意：Telegram 的 IP 可能会变化，不建议严格依赖\n     return true\n   }\n   ```\n\n## 📊 性能优化\n\n### 请求限制\n\nTelegram Bot API 有以下限制：\n- 每秒最多 30 条消息\n- 每分钟最多 20 条消息到同一个群组\n- 每秒最多 1 条消息到同一个用户\n\n```typescript\nimport { delay } from '@afjs/telegram-bot-sdk'\n\n// 添加延迟避免触发限制\nfor (const chatId of chatIds) {\n  await bot.sendMessage({ chat_id: chatId, text: 'Hello' })\n  await delay(100) // 延迟100ms\n}\n```\n\n### 批量处理\n\n```typescript\nimport { chunk } from '@afjs/telegram-bot-sdk'\n\n// 分批处理大量操作\nconst batches = chunk(largeArray, 10)\nfor (const batch of batches) {\n  await Promise.allSettled(\n    batch.map(item => processItem(item))\n  )\n}\n```\n\n## 🐛 故障排除\n\n### 常见错误\n\n1. **\"Unauthorized\" 错误**\n   - 检查 Bot Token 是否正确\n   - 确保 Token 没有过期\n\n2. **\"Chat not found\" 错误**\n   - 确保聊天 ID 正确\n   - 用户可能删除了与机器人的对话\n\n3. **\"Message is too long\" 错误**\n   - 消息长度不能超过 4096 字符\n   - 使用 `truncateText` 函数截断长文本\n\n4. **\"Too Many Requests\" 错误**\n   - 触发了 API 限制\n   - 添加延迟或减少请求频率\n\n### 调试技巧\n\n```typescript\n// 启用详细日志\nconst bot = new TelegramBot({\n  token: process.env.BOT_TOKEN!,\n  timeout: 30000\n})\n\n// 添加错误处理\nbot.sendMessage({ chat_id: chatId, text: 'test' })\n  .then(result => console.log('成功:', result))\n  .catch(error => console.error('失败:', error.message))\n```\n\n## 📄 许可证\n\n本项目采用 [MIT 许可证](LICENSE)。\n\n## 🔗 相关链接\n\n- [Telegram Bot API 官方文档](https://core.telegram.org/bots/api)\n- [创建 Telegram Bot 教程](https://core.telegram.org/bots#creating-a-new-bot)\n- [Telegram Bot API 更新日志](https://core.telegram.org/bots/api#recent-changes)\n","readmeFilename":"README.md","_rev":"1-88855233c5405714c56700732621a7c7"}