# @effect-ak/tg-bot-client 中文文档

规范地址：https://npmcn.com/package/%40effect-ak/tg-bot-client/

版本：1\.13\.0
npm 元数据更新时间：2026-11-13T15:18:45.305Z
中文译文更新时间：2026-11-13T23:06:34.795Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40effect-ak/tg-bot-client
原文对照：https://npmcn.com/package/%40effect-ak/tg-bot-client/?lang=original
项目主页：https://tg-bot-sdk.website/
源码仓库：https://github.com/kondaurovDev/tg-bot-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：71.4 kB，22 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-12-10T12:36:54.144Z
- 最新版本发布：2026-11-13T15:18:44.914Z
- 近 30 天下载量：2995（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 20 个）

## 中文简介

Telegram Bot API 的安全 HTTP 客户端

## 安装

```sh
npm install @effect-ak/tg-bot-client
```

也可以使用：`pnpm add @effect-ak/tg-bot-client`、`yarn add @effect-ak/tg-bot-client`、`bun add @effect-ak/tg-bot-client`

## README

# @ affect-ak/tg-bot-客户端

[![NPM Version](https://img.shields.io/npm/v/%40effect-ak%2Ftg-bot-client)](https://www.npmjs.com/package/@effect-ak/tg-bot-client) ![NPM Downloads](https://img.shields.io/npm/dw/%40effect-ak%2Ftg-bot-client)

Telegram Bot API的Type-safe HTTP客户端. 一个 `execute` 方法覆盖每个 API 方法,文件被编码到 `FormData` 自动输入错误。 土著 `fetch`,零运行时间依赖性——运行在Node.js 18+, Bun, Deno, Cloudflare Workers,浏览器上.

类型来自 [`@effect-ak/tg-bot-api`](https://www.npmjs.com/package/@effect-ak/tg-bot-api); 机器人框架 [`@effect-ak/tg-bot`](https://www.npmjs.com/package/@effect-ak/tg-bot) 以此客户端为基础.

## 安装

```bash
npm install @effect-ak/tg-bot-client
```

Bot API 类型在子路径下被再导出,所以这是您唯一需要的软件包 :

```typescript
import { makeTgBotClient } from "@effect-ak/tg-bot-client"
import type { Message, Update } from "@effect-ak/tg-bot-client/api"
```

## 快速启动

```typescript
import { makeTgBotClient } from "@effect-ak/tg-bot-client"

const client = makeTgBotClient({ bot_token: "YOUR_BOT_TOKEN" })

// Method names are snake_case, exactly as in the official docs
const message = await client.execute("send_message", {
  chat_id: 123456789,
  text: "Hello!"
})
```

## API 表面

```typescript
makeTgBotClient({ bot_token, base_url?, timeout? }): TgBotClient

interface TgBotClient {
  execute(method, params, options?): Promise<Result>            // throws TgBotClientError
  executeSafe(method, params, options?): Promise<ClientResult>  // never throws
  getFile({ fileId }): Promise<TgFile>                          // download by file_id
  getFileSafe({ fileId }): Promise<ClientResult<TgFile>>
}

type ClientResult<T> = { ok: true; data: T } | { ok: false; error: ClientErrorReason }
type ClientErrorReason =
  | { _tag: "NotOkResponse"; errorCode?: number; details?: string }  // Telegram said ok:false
  | { _tag: "RequestTimeout"; timeoutMs: number }
  | { _tag: "NotJsonResponse" | "UnexpectedResponse" | "ClientInternalError" | "UnableToGetFile"; ... }
```

-   **方法和参数名称** 匹配 [https://core.telegram.org/bots/api (英语)](https://core.telegram.org/bots/api) 内 `snake_case` (单位:千美元)`send_message`, (中文(简体) ), `edit_message_text`, (中文(简体) ), `answer_callback_query`) (中文(简体) ). 两者都是自动完成的;返回类型是推断的.
-   **文件**: 通过 `{ file_content: Uint8Array, file_name: string }` (或 a 个) `Blob` 编号 : `File`在API接受的情况下 `InputFile` ——客户端自动切换到多段. 对象内的文件( album 项在 `send_media_group`贴纸, `set_my_profile_photo`) 工作方式相同:客户端上传各自作为自己的部分并发送 `attach://…` 参考文献。 或者通过一个 `file_id` / URL 字符串 .
-   **信件效果**数字 : `message_effect_id` 接受 emoji 键 `MESSAGE_EFFECTS` (单位:千美元)`"🔥" | "👍" | "👎" | "❤️" | "🎉" | "💩"`并被映射到真实的id.
-   **错误**数字 : `execute` 掷出 `TgBotClientError` (单位:千美元)`error.reason` 上面贴有标签的结合; `executeSafe` 返回结合 —— 选择一种风格并坚持它.
-   **选项**数字 : `{ timeout }` 每个呼叫; `base_url` 用于自动托管的 Bot API 服务器.

## 实例

```typescript
// Safe variant
const result = await client.executeSafe("get_chat", { chat_id: 1 })
if (!result.ok) console.error(result.error._tag)

// Upload a file
await client.execute("send_document", {
  chat_id,
  document: { file_content: new TextEncoder().encode("hi"), file_name: "hi.txt" },
  caption: "Generated on the fly"
})

// Download a file
const file = await client.getFile({ fileId })
file.content // ArrayBuffer
```

## 文档

-   指南 : **[tg-bot-sdk.website/客户/用户](https://tg-bot-sdk.website/client/usage/)**
-   Bot API 参考文献( 每方法一页) : [https://tg-bot-sdk.website/api/ 页面存档备份,存于互联网档案馆](https://tg-bot-sdk.website/api/)
-   对于 LLM/ 编码代理 : [https://tg-bot-sdk.website/llms.txt](https://tg-bot-sdk.website/llms.txt)

## 许可证

麻省理工学院

## 常见问题

### @effect-ak/tg-bot-client 是什么？

Telegram Bot API 的安全 HTTP 客户端

### 如何安装 @effect-ak/tg-bot-client？

在项目目录运行 npm install @effect-ak/tg-bot-client，或使用 pnpm add / yarn add / bun add。

### @effect-ak/tg-bot-client 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @effect-ak/tg-bot-client 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @effect-ak/tg-bot-client 可以商用吗？

@effect-ak/tg-bot-client 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @effect-ak/tg-bot-client 的下载量有多少？

根据 npm 官方下载统计，@effect-ak/tg-bot-client 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,995 次，日均约 100 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @effect-ak/tg-bot-client 还在维护吗？

最新版本 1\.13\.0 发布于 2026/11/13（今天）；至今共发布 48 个版本，其中过去 12 个月发布了 20 个；首次发布于 2024/12/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。