@xbibzlibrary/telebibz 0.4.3 → 0.4.5

package/docs/FILES.md

@@ -0,0 +1,243 @@
+# Working with files: upload, download, validation (English)
+
+Complete guide to every file flow in telebibz: downloading files users send you, uploading files to Telegram, sending by `file_id`, validating uploads, and the limits and gotchas that come with the Telegram Bot API.
+
+## Contents
+
+1. [Download: one call with `downloadFile()`](#1-download-one-call-with-downloadfile)
+2. [Download: manual flow with `getFile()`](#2-download-manual-flow-with-getfile)
+3. [Property naming: `file_path` vs `filePath`](#3-property-naming-file_path-vs-filepath)
+4. [Upload: every source type](#4-upload-every-source-type)
+5. [Upload: validation before sending](#5-upload-validation-before-sending)
+6. [Media groups with `attach://`](#6-media-groups-with-attach)
+7. [Limits and lifetimes](#7-limits-and-lifetimes)
+8. [Local Bot API server](#8-local-bot-api-server)
+9. [Testing file flows without network](#9-testing-file-flows-without-network)
+10. [Troubleshooting](#10-troubleshooting)
+
+## 1. Download: one call with `downloadFile()`
+
+`bot.downloadFile()` / `ctx.downloadFile()` resolves the `file_id` through `getFile` and downloads the raw bytes in a single call:
+
+```ts
+bot.on("message:document", async (ctx) => {
+  const fileId = ctx.message.document.file_id;
+
+  // Downloads to memory…
+  const file = await ctx.downloadFile(fileId);
+  console.log(file.fileName, file.sizeBytes, file.url);
+  // file.bytes is a Uint8Array
+
+  // …or straight to disk
+  const saved = await ctx.downloadFile(fileId, { destination: "downloads/report.pdf" });
+  console.log(`Saved to ${saved.savedTo}`);
+});
+```
+
+The result (`DownloadedFile`) carries everything:
+
+| Field | Meaning |
+|---|---|
+| `file` | The Telegram `File` object returned by `getFile` |
+| `bytes` | Raw file bytes (`Uint8Array`) |
+| `filePath` | The `file_path` used for the download |
+| `url` | Direct download URL — valid for **at least 1 hour** |
+| `fileName` | Last path segment of `filePath` (e.g. `report.pdf`) |
+| `sizeBytes` | Byte length of `bytes` |
+| `savedTo` | Local path, set when you passed `destination` |
+
+Errors are precise:
+- Telegram returns no `file_path` → `TelegramError` with `kind: "validation"`
+- The HTTP download itself fails → `TelegramNetworkError` (with status)
+- `getFile` fails (bad `file_id`, file too big) → the original `TelegramError` from Telegram
+
+Both variants accept an `AbortSignal`:
+
+```ts
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 10_000);
+const file = await bot.downloadFile(fileId, { signal: controller.signal });
+```
+
+## 2. Download: manual flow with `getFile()`
+
+If you want to build the URL yourself (e.g. to hand it to another HTTP client):
+
+```ts
+const file = await ctx.getFile(fileId);          // Telegram File object
+if (!file.file_path) throw new Error("File unavailable (over 20 MB or expired)");
+
+const url = `https://api.telegram.org/file/bot${process.env.TELEGRAM_BOT_TOKEN}/${file.file_path}`;
+const response = await fetch(url);               // fetch — NEVER createReadStream (it cannot open URLs)
+if (!response.ok) throw new Error(`Download failed: HTTP ${response.status}`);
+const bytes = new Uint8Array(await response.arrayBuffer());
+```
+
+Three rules this snippet encodes:
+1. The URL prefix is `/file/bot<TOKEN>/` — **the word `bot` is required**. Forgetting it is the single most common mistake and yields `404 Not Found`.
+2. `fetch` downloads the bytes; `fs.createReadStream()` only opens **local paths** — passing it a URL crashes the process with `ENOENT` on an unhandled stream error.
+3. The URL is guaranteed valid for **at least 1 hour**. Never cache it long-term; call `getFile` again when it expires.
+
+## 3. Property naming: `file_path` vs `filePath`
+
+This trips everyone once. The two naming styles belong to different layers:
+
+| Naming | Belongs to | Examples |
+|---|---|---|
+| `snake_case` (`file_path`) | **Raw Telegram objects** — the result of `getFile()`, `ctx.message.document`, `ctx.message.photo` | `file.file_path`, `document.file_id`, `photo.file_unique_id` |
+| `camelCase` (`filePath`) | **telebibz result types** — `DownloadedFile` and library options | `downloaded.filePath`, `downloaded.fileName`, `downloaded.sizeBytes` |
+
+```ts
+const file = await ctx.getFile(fileId);
+file.file_path;   // ✅ Telegram object → snake_case
+file.filePath;    // ❌ undefined — this is the DownloadedFile name
+
+const downloaded = await ctx.downloadFile(fileId);
+downloaded.filePath;  // ✅ library result → camelCase
+downloaded.file_path; // ❌ undefined
+```
+
+If your "no file path" check fails while the logged response clearly contains `file_path`, you are reading a camelCase property from a snake_case object.
+
+## 4. Upload: every source type
+
+All `replyWith*` senders and raw API calls accept the `InputFile` type. Pass uploads as `{ source, filename? }`:
+
+```ts
+// From a path on disk (absolute, ./, or ../)
+await ctx.replyWithDocument({ source: "reports/q3.pdf", filename: "Q3-report.pdf" });
+
+// From raw bytes
+const bytes = new Uint8Array(await someFile.bytes());
+await ctx.replyWithDocument({ source: bytes, filename: "data.bin" });
+
+// From a Blob or File (File carries its own name)
+await ctx.replyWithDocument({ source: new File([bytes], "photo.png") });
+
+// From a web ReadableStream or a Node.js stream (drained automatically)
+import { createReadStream } from "node:fs";
+await ctx.replyWithVideo({ source: createReadStream("clip.mp4"), filename: "clip.mp4" });
+```
+
+Notes:
+- `filename` overrides whatever name the source would otherwise have (for paths, the basename is used by default).
+- **You never build `FormData` yourself.** The transport detects upload payloads and switches to multipart automatically. Hand-rolled `FormData` with Node streams fails (`append` requires a `Blob`) — always pass the stream/bytes to the library instead.
+- Bare values also work: `await ctx.replyWithDocument(bytes)` (no filename) or an existing Telegram file id:
+
+```ts
+// Re-send by file_id — no download, no upload, no size limit
+await ctx.replyWithDocument(ctx.message.document.file_id);
+```
+
+## 5. Upload: validation before sending
+
+`validateUpload()` / `assertValidUpload()` enforce your own rules before a byte leaves the process:
+
+```ts
+import { assertValidUpload, UploadValidationError } from "@xbibzlibrary/telebibz";
+
+bot.command("doc", async (ctx) => {
+  const filePath = ctx.message?.text?.split(/\s+/)[1];
+  if (!filePath) return void (await ctx.reply("Usage: /doc <path>"));
+
+  const info = await stat(filePath);
+  try {
+    assertValidUpload(
+      { sizeBytes: info.size, fileName: filePath },
+      {
+        maxBytes: 50 * 1024 * 1024,                       // Telegram document cap
+        allowedExtensions: [".pdf", ".docx", ".pptx"],    // case-insensitive
+      },
+    );
+  } catch (error) {
+    if (error instanceof UploadValidationError) {
+      return void (await ctx.reply(`❌ ${error.message}`)); // lists every violation
+    }
+    throw error;
+  }
+
+  await ctx.replyWithDocument({ source: filePath });
+});
+```
+
+`validateUpload()` returns issues instead of throwing (empty array = valid). MIME rules support wildcards:
+
+```ts
+validateUpload({ mimeType: "image/png" }, { allowedMimeTypes: ["image/*"] }); // []
+```
+
+Available rules: `maxBytes`, `allowedMimeTypes` (exact or `image/*` wildcards), `allowedExtensions` (dot optional, case-insensitive).
+
+## 6. Media groups with `attach://`
+
+`sendMediaGroup` takes a JSON array of input media; binary files ride along as **separate form parts** referenced by `attach://<name>`:
+
+```ts
+await ctx.replyWithMediaGroup([
+  { type: "photo", media: "attach://pic1" },
+  { type: "photo", media: "attach://pic2" },
+], { pic1: bytes1, pic2: bytes2 } as never);
+```
+
+The transport detects the binary parts and switches to multipart automatically; the `media` array itself is serialized as one JSON form field, exactly as Telegram requires.
+
+## 7. Limits and lifetimes
+
+| Limit | Value | Notes |
+|---|---|---|
+| Download via `getFile` | **20 MB** | Larger files: `getFile` fails (HTTP 400 "file is too big") — not an empty `file_path` |
+| Upload photos | 10 MB | |
+| Upload other files | 50 MB | |
+| Re-send by `file_id` | **No limit** | Telegram already has the file |
+| Send by URL | 5 MB photos / 20 MB other | Telegram fetches the URL itself |
+| Download URL validity | **≥ 1 hour** | Re-run `getFile` after expiry |
+| `file_path` presence | Optional in the schema | Always check before using it |
+
+Upload limits are Telegram's, not the library's — `validateUpload()` is how you reject early with a friendly message.
+
+## 8. Local Bot API server
+
+Running your own [local Bot API server](https://core.telegram.org/bots/api#using-a-local-bot-api-server) removes the 20 MB download cap and allows 2000 MB uploads:
+
+```ts
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  apiBaseUrl: "http://localhost:8081",   // Bot API option
+  transportOptions: { timeoutMs: 600_000 },
+});
+```
+
+`downloadFile()` and `fileUrl()` map `/bot<token>` to `/file/bot<token>` on any base URL, so downloads work against local servers too. Note: with a local server, `file_path` is an **absolute path on the server's disk** — fetch the URL only if the server is remote; read the path directly when your bot runs on the same machine.
+
+## 9. Testing file flows without network
+
+`MockTransport` (from `@xbibzlibrary/telebibz/testing`) implements the download members:
+
+```ts
+import { createTestBot } from "@xbibzlibrary/telebibz/testing";
+
+const { bot, transport } = createTestBot();
+transport.respond("getFile", { ok: true, result: { file_id: "F1", file_unique_id: "U1", file_path: "documents/a.pdf" } });
+transport.downloadBytes = new TextEncoder().encode("pdf-content");
+
+const file = await bot.downloadFile("F1");
+file.fileName;                         // "a.pdf"
+new TextDecoder().decode(file.bytes);  // "pdf-content"
+transport.downloads;                   // ["documents/a.pdf"] — the recorded download
+```
+
+See [TESTING.md](TESTING.md) for the full testing guide.
+
+## 10. Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| "Gagal mendapatkan path file" while the logged response contains `file_path` | Reading `file.filePath`/`file.path` from a raw Telegram object | Use `file.file_path` (snake_case) — or skip manual handling entirely with `ctx.downloadFile()` |
+| `ENOENT … open 'https://…'` on a ReadStream | `createReadStream()` only opens local paths | Use `fetch(url)` for URLs, or `ctx.downloadFile()` |
+| Download URL returns 404 | Missing `bot` prefix in `/file/bot<TOKEN>/` | Use the `url` field from `downloadFile()` — it is always built correctly |
+| `getFile` returns HTTP 400 "file is too big" | File over 20 MB | Use a local Bot API server, or re-send by `file_id` |
+| `FormData append: parameter 2 is not of type 'Blob'` | Hand-rolled `FormData` with a Node stream | Pass `{ source: stream, filename }` to `replyWith*` instead; the library handles multipart |
+| `file_path` was there, now it's gone | URL expired (>1 hour) | Call `getFile` again |
+| Downloaded file is 0 bytes / wrong | `file_id` belongs to another bot | `file_id`s are bot-scoped; use the id from your own bot's updates |
+
+Bahasa Indonesia: [FILES.id.md](FILES.id.md) · 简体中文: [FILES.zh-CN.md](FILES.zh-CN.md)

package/docs/FILES.zh-CN.md

@@ -0,0 +1,243 @@
+# 文件操作：上传、下载、校验（简体中文）
+
+telebibz 文件流程的完整指南：下载用户发来的文件、上传文件到 Telegram、通过 `file_id` 转发、上传前校验，以及 Telegram Bot API 的限制与陷阱。
+
+## 目录
+
+1. [下载：一次调用 `downloadFile()`](#1-下载一次调用-downloadfile)
+2. [下载：`getFile()` 手动流程](#2-下载getfile-手动流程)
+3. [属性命名：`file_path` 与 `filePath`](#3-属性命名file_path-与-filepath)
+4. [上传：所有来源类型](#4-上传所有来源类型)
+5. [上传：发送前校验](#5-上传发送前校验)
+6. [媒体组与 `attach://`](#6-媒体组与-attach)
+7. [限制与有效期](#7-限制与有效期)
+8. [本地 Bot API 服务器](#8-本地-bot-api-服务器)
+9. [离线测试文件流程](#9-离线测试文件流程)
+10. [故障排查](#10-故障排查)
+
+## 1. 下载：一次调用 `downloadFile()`
+
+`bot.downloadFile()` / `ctx.downloadFile()` 通过 `getFile` 解析 `file_id`，然后在一次调用中下载原始字节：
+
+```ts
+bot.on("message:document", async (ctx) => {
+  const fileId = ctx.message.document.file_id;
+
+  // 下载到内存……
+  const file = await ctx.downloadFile(fileId);
+  console.log(file.fileName, file.sizeBytes, file.url);
+  // file.bytes 是 Uint8Array
+
+  // ……或直接写入磁盘
+  const saved = await ctx.downloadFile(fileId, { destination: "downloads/report.pdf" });
+  console.log(`已保存到 ${saved.savedTo}`);
+});
+```
+
+返回的 `DownloadedFile` 携带你所需的一切：
+
+| 字段 | 含义 |
+|---|---|
+| `file` | `getFile` 返回的 Telegram `File` 对象 |
+| `bytes` | 文件原始字节（`Uint8Array`） |
+| `filePath` | 用于下载的 `file_path` |
+| `url` | 直接下载链接 —— **至少 1 小时**内有效 |
+| `fileName` | `filePath` 的最后一段（如 `report.pdf`） |
+| `sizeBytes` | `bytes` 的字节长度 |
+| `savedTo` | 本地路径，仅在传入 `destination` 时填充 |
+
+错误同样精确：
+- Telegram 未返回 `file_path` → `TelegramError`，`kind: "validation"`
+- HTTP 下载本身失败 → `TelegramNetworkError`（含状态码）
+- `getFile` 失败（file_id 错误、文件过大）→ Telegram 原始的 `TelegramError`
+
+两者都支持 `AbortSignal`：
+
+```ts
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 10_000);
+const file = await bot.downloadFile(fileId, { signal: controller.signal });
+```
+
+## 2. 下载：`getFile()` 手动流程
+
+如果你想自己构造 URL（例如交给其他 HTTP 客户端）：
+
+```ts
+const file = await ctx.getFile(fileId);          // Telegram File 对象
+if (!file.file_path) throw new Error("文件不可用（超过 20 MB 或已过期）");
+
+const url = `https://api.telegram.org/file/bot${process.env.TELEGRAM_BOT_TOKEN}/${file.file_path}`;
+const response = await fetch(url);               // ← 用 fetch —— 不要用 createReadStream（无法打开 URL）
+if (!response.ok) throw new Error(`下载失败：HTTP ${response.status}`);
+const bytes = new Uint8Array(await response.arrayBuffer());
+```
+
+这段代码隐含三条规则：
+1. URL 前缀是 `/file/bot<TOKEN>/` —— **`bot` 一词必不可少**。漏掉它是最常见的错误，结果是 `404 Not Found`。
+2. 字节由 `fetch` 下载；`fs.createReadStream()` 只能打开**本地路径** —— 传入 URL 会在流错误回调里抛出未捕获的 `ENOENT`。
+3. URL 保证**至少 1 小时**有效。不要长期缓存；过期后重新调用 `getFile`。
+
+## 3. 属性命名：`file_path` 与 `filePath`
+
+这个问题至少坑每个开发者一次。两种命名属于不同的层：
+
+| 命名 | 归属 | 示例 |
+|---|---|---|
+| `snake_case`（`file_path`） | **Telegram 原始对象** —— `getFile()` 的结果、`ctx.message.document`、`ctx.message.photo` | `file.file_path`、`document.file_id`、`photo.file_unique_id` |
+| `camelCase`（`filePath`） | **telebibz 的结果类型** —— `DownloadedFile` 和库选项 | `downloaded.filePath`、`downloaded.fileName`、`downloaded.sizeBytes` |
+
+```ts
+const file = await ctx.getFile(fileId);
+file.file_path;   // ✅ Telegram 对象 → snake_case
+file.filePath;    // ❌ undefined —— 那是 DownloadedFile 的字段名
+
+const downloaded = await ctx.downloadFile(fileId);
+downloaded.filePath;  // ✅ 库结果 → camelCase
+downloaded.file_path; // ❌ undefined
+```
+
+如果你明明在日志里看到了 `file_path`，"没有路径" 的检查却失败了，说明你在读 snake_case 对象上的 camelCase 属性。
+
+## 4. 上传：所有来源类型
+
+所有 `replyWith*` 发送器和原始 API 调用都接受 `InputFile` 类型。上传时传 `{ source, filename? }`：
+
+```ts
+// 来自磁盘路径（绝对、./ 或 ../ 均可）
+await ctx.replyWithDocument({ source: "reports/q3.pdf", filename: "Q3-report.pdf" });
+
+// 来自原始字节
+const bytes = new Uint8Array(await someFile.bytes());
+await ctx.replyWithDocument({ source: bytes, filename: "data.bin" });
+
+// 来自 Blob 或 File（File 自带文件名）
+await ctx.replyWithDocument({ source: new File([bytes], "photo.png") });
+
+// 来自 Web ReadableStream 或 Node 流（自动排空）
+import { createReadStream } from "node:fs";
+await ctx.replyWithVideo({ source: createReadStream("clip.mp4"), filename: "clip.mp4" });
+```
+
+注意：
+- `filename` 会覆盖来源自带的名称（路径默认取 basename）。
+- **你永远不需要自己拼 `FormData`。** 传输层检测到上传负载后自动切换 multipart。手工构造内含 Node 流的 `FormData` 必定失败（`append` 需要 `Blob`）—— 请始终把流/字节交给库。
+- 也可以传裸值：`await ctx.replyWithDocument(bytes)`（无文件名），或直接传已有的 Telegram file id：
+
+```ts
+// 通过 file_id 转发 —— 不下载、不上传、无大小限制
+await ctx.replyWithDocument(ctx.message.document.file_id);
+```
+
+## 5. 上传：发送前校验
+
+`validateUpload()` / `assertValidUpload()` 在字节离开进程之前强制执行你的规则：
+
+```ts
+import { assertValidUpload, UploadValidationError } from "@xbibzlibrary/telebibz";
+
+bot.command("doc", async (ctx) => {
+  const filePath = ctx.message?.text?.split(/\s+/)[1];
+  if (!filePath) return void (await ctx.reply("用法：/doc <路径>"));
+
+  const info = await stat(filePath);
+  try {
+    assertValidUpload(
+      { sizeBytes: info.size, fileName: filePath },
+      {
+        maxBytes: 50 * 1024 * 1024,                       // Telegram 文档上限
+        allowedExtensions: [".pdf", ".docx", ".pptx"],    // 大小写不敏感
+      },
+    );
+  } catch (error) {
+    if (error instanceof UploadValidationError) {
+      return void (await ctx.reply(`❌ ${error.message}`)); // 列出所有违规项
+    }
+    throw error;
+  }
+
+  await ctx.replyWithDocument({ source: filePath });
+});
+```
+
+`validateUpload()` 返回问题列表而不是抛异常（空数组 = 通过）。MIME 规则支持通配符：
+
+```ts
+validateUpload({ mimeType: "image/png" }, { allowedMimeTypes: ["image/*"] }); // []
+```
+
+可用规则：`maxBytes`、`allowedMimeTypes`（精确或 `image/*` 通配）、`allowedExtensions`（点号可选，大小写不敏感）。
+
+## 6. 媒体组与 `attach://`
+
+`sendMediaGroup` 接受 JSON 输入媒体数组；二进制文件作为**独立的表单部分**通过 `attach://<name>` 引用：
+
+```ts
+await ctx.replyWithMediaGroup([
+  { type: "photo", media: "attach://pic1" },
+  { type: "photo", media: "attach://pic2" },
+], { pic1: bytes1, pic2: bytes2 } as never);
+```
+
+传输层检测到二进制部分后自动切换 multipart；`media` 数组本身序列化为单个 JSON 字段 —— 与 Telegram 的契约完全一致。
+
+## 7. 限制与有效期
+
+| 限制 | 数值 | 说明 |
+|---|---|---|
+| 通过 `getFile` 下载 | **20 MB** | 更大的文件：`getFile` 直接失败（HTTP 400 "file is too big"）—— 不是 `file_path` 为空 |
+| 上传照片 | 10 MB | |
+| 上传其他文件 | 50 MB | |
+| 通过 `file_id` 转发 | **无限制** | 文件已在 Telegram 侧 |
+| 通过 URL 发送 | 照片 5 MB / 其他 20 MB | Telegram 侧抓取该 URL |
+| 下载链接有效期 | **≥ 1 小时** | 过期后重新调用 `getFile` |
+| `file_path` 是否存在 | schema 中为可选 | 使用前务必检查 |
+
+上传上限属于 Telegram 而非本库 —— `validateUpload()` 让你用友好的提示提前拒绝。
+
+## 8. 本地 Bot API 服务器
+
+自建[本地 Bot API 服务器](https://core.telegram.org/bots/api#using-a-local-bot-api-server)可解除 20 MB 下载限制，并允许最大 2000 MB 的上传：
+
+```ts
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  apiBaseUrl: "http://localhost:8081",   // Bot API 选项
+  transportOptions: { timeoutMs: 600_000 },
+});
+```
+
+`downloadFile()` 和 `fileUrl()` 会把 `/bot<token>` 映射为任意 base URL 下的 `/file/bot<token>`，下载同样走本地服务器。注意：本地服务器返回的 `file_path` 是**服务器磁盘上的绝对路径** —— 服务器远程时 fetch 该 URL，bot 与服务器同机时直接读取该路径。
+
+## 9. 离线测试文件流程
+
+`MockTransport`（来自 `@xbibzlibrary/telebibz/testing`）实现了下载成员：
+
+```ts
+import { createTestBot } from "@xbibzlibrary/telebibz/testing";
+
+const { bot, transport } = createTestBot();
+transport.respond("getFile", { ok: true, result: { file_id: "F1", file_unique_id: "U1", file_path: "documents/a.pdf" } });
+transport.downloadBytes = new TextEncoder().encode("pdf-content");
+
+const file = await bot.downloadFile("F1");
+file.fileName;                         // "a.pdf"
+new TextDecoder().decode(file.bytes);  // "pdf-content"
+transport.downloads;                   // ["documents/a.pdf"] —— 已记录的下载
+```
+
+完整测试指南见 [TESTING.zh-CN.md](TESTING.zh-CN.md)。
+
+## 10. 故障排查
+
+| 症状 | 原因 | 修复 |
+|---|---|---|
+| 日志里明明有 `file_path`，却报"无法获取文件路径" | 在 Telegram 原始对象上读取了 `file.filePath`/`file.path` | 使用 `file.file_path`（snake_case）—— 或干脆用 `ctx.downloadFile()` 跳过手动流程 |
+| ReadStream 报 `ENOENT … open 'https://…'` | `createReadStream()` 只能打开本地路径 | URL 用 `fetch(url)`，或使用 `ctx.downloadFile()` |
+| 下载 URL 返回 404 | `/file/bot<TOKEN>/` 中缺少 `bot` 前缀 | 使用 `downloadFile()` 的 `url` 字段 —— 它总是构造正确 |
+| `getFile` 返回 HTTP 400 "file is too big" | 文件超过 20 MB | 使用本地 Bot API 服务器，或通过 `file_id` 转发 |
+| `FormData append: parameter 2 is not of type 'Blob'` | 手工构造的 FormData 里放了 Node 流 | 把 `{ source: stream, filename }` 交给 `replyWith*`；multipart 由库处理 |
+| `file_path` 之前有值，现在没了 | 链接过期（>1 小时） | 重新调用 `getFile` |
+| 下载的文件为 0 字节 / 内容错误 | `file_id` 属于另一个 bot | `file_id` 与 bot 绑定；请使用你自己 bot 的 update 中的 id |
+
+English: [FILES.md](FILES.md) · Bahasa Indonesia: [FILES.id.md](FILES.id.md)

package/docs/GETTING_STARTED.id.md

@@ -80,6 +80,10 @@ Gunakan HTTPS untuk webhook, validasi secret webhook Telegram, simpan token di s
 
 - [Runnable examples](../examples/README.md)
 - [Referensi API lengkap](API.id.md)
-- [Webhook API](API.id.md#10-webhook)
-- [Conversation dan wizard](API.id.md#8-state-session-and-conversations)
+- [File: upload dan download](FILES.id.md)
+- [Penanganan error dan rate limit](ERRORS.id.md)
+- [Deployment webhook](WEBHOOK.id.md)
+- [Testing bot secara offline](TESTING.id.md)
+- [Migrasi dari Telegraf](MIGRATION_TELEGRAF.id.md)
+- [Cookbook produksi](COOKBOOK.id.md)
 - [Panduan kontribusi](../CONTRIBUTING.md)

package/docs/GETTING_STARTED.md

@@ -80,6 +80,10 @@ Use HTTPS for webhooks, verify the Telegram webhook secret, keep tokens in a sec
 
 - [Runnable examples](../examples/README.md)
 - [Complete API reference](API.md)
-- [Webhook API](API.md#10-webhook)
-- [Conversations and wizards](API.md#8-state-session-and-conversations)
+- [Files: upload and download](FILES.md)
+- [Error handling and rate limits](ERRORS.md)
+- [Webhook deployment](WEBHOOK.md)
+- [Testing your bot offline](TESTING.md)
+- [Migrating from Telegraf](MIGRATION_TELEGRAF.md)
+- [Production cookbook](COOKBOOK.md)
 - [Contribution guide](../CONTRIBUTING.md)

package/docs/GETTING_STARTED.zh-CN.md

@@ -80,6 +80,10 @@ Webhook 使用 HTTPS，验证 Telegram webhook secret，将 token 保存到 secr
 
 - [Runnable examples](../examples/README.md)
 - [完整 API 参考](API.zh-CN.md)
-- [Webhook API](API.zh-CN.md#10-webhook)
-- [Conversation 和 wizard](API.zh-CN.md#8-state-session-and-conversations)
+- [文件：上传与下载](FILES.zh-CN.md)
+- [错误处理与限流](ERRORS.zh-CN.md)
+- [Webhook 部署](WEBHOOK.zh-CN.md)
+- [离线测试你的 bot](TESTING.zh-CN.md)
+- [从 Telegraf 迁移](MIGRATION_TELEGRAF.zh-CN.md)
+- [生产实战手册](COOKBOOK.zh-CN.md)
 - [贡献指南](../CONTRIBUTING.md)

package/docs/MIGRATION_TELEGRAF.id.md

@@ -0,0 +1,147 @@
+# Migrasi dari Telegraf (Bahasa Indonesia)
+
+telebibz mengimplementasikan surface context dan opsi launch Telegraf secara sengaja, sehingga sebagian besar handler bisa dipindah dengan sedikit atau tanpa perubahan. Panduan ini memetakan setiap bagian bot Telegraf ke padanannya di telebibz.
+
+## Daftar isi
+
+1. [Side-by-side: satu bot utuh](#1-side-by-side-satu-bot-utuh)
+2. [Peta konsep](#2-peta-konsep)
+3. [Method Context](#3-method-context)
+4. [Opsi launch](#4-opsi-launch)
+5. [Scenes → Wizards](#5-scenes--wizards)
+6. [Penyimpanan session](#6-penyimpanan-session)
+7. [Webhook](#7-webhook)
+8. [Yang tidak punya ekuivalen langsung](#8-yang-tidak-punya-ekuivalen-langsung)
+
+## 1. Side-by-side: satu bot utuh
+
+**Telegraf**
+
+```ts
+import { Telegraf } from "telegraf";
+
+const bot = new Telegraf(process.env.TELEGRAM_BOT_TOKEN!);
+
+bot.use(async (ctx, next) => { console.time("update"); await next(); console.timeEnd("update"); });
+bot.start((ctx) => ctx.reply("Welcome!"));
+bot.command("help", (ctx) => ctx.reply("Help"));
+bot.action("menu:open", async (ctx) => { await ctx.answerCbQuery(); await ctx.reply("Menu"); });
+bot.on("message", (ctx) => ctx.reply("got it"));
+bot.catch((error) => console.error(error));
+
+bot.launch({ dropPendingUpdates: true });
+```
+
+**telebibz**
+
+```ts
+import { Bot } from "@xbibzlibrary/telebibz";
+
+const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
+
+bot.use(async (ctx, next) => { console.time("update"); await next(); console.timeEnd("update"); });
+bot.command("start", async (ctx) => { await ctx.reply("Welcome!"); });   // command bernama, bukan bot.start()
+bot.command("help", async (ctx) => { await ctx.reply("Help"); });
+bot.action("menu:open", async (ctx) => { await ctx.answerCallbackQuery(); await ctx.reply("Menu"); });
+bot.on("message", async (ctx) => { await ctx.reply("got it"); });
+bot.catch(async (error) => { console.error(error); });
+
+await bot.launch({ dropPendingUpdates: true });   // nama opsi sama
+```
+
+Hanya dua perbedaan mekanis: `bot.start(handler)` menjadi `bot.command("start", handler)`, dan `answerCbQuery()` menjadi `answerCallbackQuery()`.
+
+## 2. Peta konsep
+
+| Telegraf | telebibz | Catatan |
+|---|---|---|
+| `new Telegraf(token)` | `new Bot(token)` atau `new Bot({ token, ... })` | |
+| `bot.launch()` | `bot.launch()` / `bot.start()` | `mode: "polling"` eksplisit di `launch` |
+| `bot.stop()` | `bot.stop()` | telebibz men-drain handler yang sedang berjalan lebih dulu |
+| `bot.use(mw)` | `bot.use(mw)` | signature middleware sama `(ctx, next)` |
+| `bot.command(name, h)` | `bot.command(name, h)` | |
+| `bot.on(filter, h)` | `bot.on(filter, h)` | grammar filter sama (`message:photo`, array) |
+| `bot.hears(trigger, h)` | `bot.hears(trigger, h)` | string dan RegExp |
+| `bot.action(pattern, h)` | `bot.action(pattern, h)` | alias drop-in dari `bot.callback` |
+| `bot.catch(handler)` | `bot.catch(handler)` | menerima `(error, ctx)` |
+
+## 3. Method Context
+
+Setiap shortcut context Telegraf ada — termasuk yang di Telegraf diserahkan ke plugin:
+
+- **Balasan**: `reply`, `replyWithPhoto`, `replyWithDocument`, `replyWithVideo`, `replyWithAudio`, `replyWithVoice`, `replyWithAnimation`, `replyWithVideoNote`, `replyWithSticker`, `replyWithMediaGroup`, `replyWithLocation`, `replyWithVenue`, `replyWithContact`, `replyWithPoll`, `replyWithQuiz`, `replyWithDice`, `replyWithGame`, `replyWithInvoice`, `replyWithHTML`, `replyWithMarkdown` (+V2)
+- **Admin/moderasi**: `banChatMember`, `unbanChatMember`, `restrictChatMember`, `promoteChatMember`, `banChatSenderChat`, `unbanChatSenderChat`
+- **Chat**: `setChatTitle`, `setChatDescription`, `setChatPhoto`, `deleteChatPhoto`, `setChatPermissions`, `leaveChat`, `unpinAllChatMessages`, `setChatStickerSet`, `deleteChatStickerSet`
+- **Info**: `getChat`, `getChatAdministrators`, `getChatMemberCount`, `getChatMember`
+- **Invite link/join request**: `exportChatInviteLink`, `createChatInviteLink`, `editChatInviteLink`, `revokeChatInviteLink`, `approveChatJoinRequest`, `declineChatJoinRequest`
+- **Live location/poll/game**: `editMessageLiveLocation`, `stopMessageLiveLocation`, `stopPoll`, `setGameScore`, `getGameHighScores`
+- **Forum**: set topik lengkap (`createForumTopic` … `unhideGeneralForumTopic`)
+- **Baru, melampaui core Telegraf**: `getFile` (typed), `downloadFile`, `edit` (menulis ulang teks pesan saat ini), plus helper mandiri yang diekspor dari root paket — `validateUpload`/`assertValidUpload` — yang bukan method context
+
+Perbedaan penamaan yang harus diperbaiki saat porting: `answerCbQuery` → `answerCallbackQuery`; `ctx.telegram` → `ctx.api`; helper keyboard berasal dari root paket (`InlineKeyboard`, `ReplyKeyboard`, `removeKeyboard`, `forceReply`) alih-alih `Markup`.
+
+## 4. Opsi launch
+
+| Telegraf | telebibz |
+|---|---|
+| `launch({ dropPendingUpdates })` | `launch({ dropPendingUpdates })` — identik |
+| `handlerTimeout` (default 90 000) | `handlerTimeout` (default 90 000; `0` menonaktifkan) |
+| Opsi `contextType` | Opsi `contextType` — subclass `Context` Anda diinstansiasi untuk setiap update |
+| `webhookReply` (per-update) | `webhookReply` pada opsi handler / `handleUpdate` |
+| `telegraf.use(session(...))` | `new Bot({ session: new MemoryStorage() })` (atau JSON/Redis/SQL/Mongo) |
+
+## 5. Scenes → Wizards
+
+`WizardScene` + `Stage` milik Telegraf menjadi satu `Wizard` dengan step eksplisit dan tanpa kunci session global:
+
+```ts
+import { Bot, Wizard } from "@xbibzlibrary/telebibz";
+
+const wizard = new Wizard()
+  .step({ id: "ask-name", run: async (flow) => { flow.next(); await flow.ctx.reply("Nama?"); } })
+  .step({ id: "save", run: async (flow) => { await flow.ctx.reply(`Hai ${flow.ctx.message?.text}!`); } });
+
+const bot = new Bot(process.env.TELEGRAM_BOT_TOKEN!);
+bot.useWizard(wizard);                                    // menggantikan middleware Stage
+bot.command("start", async (ctx) => { await wizard.run(ctx); }); // menggantikan scene.enter()
+```
+
+- Kunci wizard diturunkan otomatis dari chat + pengirim — tanpa pengelolaan kunci manual.
+- `flow.set(key, value)` / `flow.get(key)` menggantikan `ctx.scene.session`.
+- `/cancel` membatalkan; conversation selesai otomatis setelah step terakhir.
+- Untuk graf non-linear, susun `ConversationManager` dengan router (telebibz sengaja menjadikan orkestrasi scene milik aplikasi; lihat "Design decisions" di FEATURE_MATRIX).
+
+## 6. Penyimpanan session
+
+Telegraf menyimpan session di memori secara default dan butuh plugin store untuk persistensi. telebibz menerima storage di constructor — ganti adapter, pertahankan kode:
+
+```ts
+import { Bot, MemoryStorage, JsonFileStorage, RedisStorage } from "@xbibzlibrary/telebibz";
+
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  session: new JsonFileStorage("state/sessions.json"),   // atau MemoryStorage / RedisStorage / SqlStorage / MongoStorage
+});
+```
+
+Resep wiring lengkap untuk setiap adapter: [STORAGE.id.md](STORAGE.id.md).
+
+## 7. Webhook
+
+```ts
+// Telegraf: webhookCallback(bot, app)
+// telebibz: framework eksplisit
+import { webhookCallback } from "@xbibzlibrary/telebibz";
+app.post("/telegram", webhookCallback(bot, "express", { secretToken: process.env.TELEGRAM_WEBHOOK_SECRET }));
+```
+
+`createWebhookHandler()` tambahan menyediakan handler Web-standard `Request → Response` untuk Bun/Deno/edge. Panduan deployment lengkap: [WEBHOOK.id.md](WEBHOOK.id.md).
+
+## 8. Yang tidak punya ekuivalen langsung
+
+- **Client low-level `bot.telegram`** — pakai `bot.api` (`call`, `raw`, `methods`, `downloadFile`); flood gate dan retry terpasang di transport, bukan dikonfigurasi per panggilan.
+- **Ekosistem plugin Telegraf** — port plugin sebagai objek `Plugin` dengan lifecycle eksplisit (`install`, `onStop`, `dispose`); plugin manager di-restart dengan bersih.
+- **`Composer.mount`/scene dinamis** — bangun dengan nesting `Router` dan `matchMode: "all"`.
+- **Rantai helper Markup** (`Markup.keyboard(...).resize()`) — pakai `new ReplyKeyboard().text("A").resized().build()`; payload sama, gaya builder.
+
+English: [MIGRATION_TELEGRAF.md](MIGRATION_TELEGRAF.md) · 简体中文: [MIGRATION_TELEGRAF.zh-CN.md](MIGRATION_TELEGRAF.zh-CN.md)