@xbibzlibrary/telebibz 0.4.5 → 3.0.1

package/docs/ERRORS.md

@@ -1,194 +0,0 @@
-# Error handling guide (English)
-
-Every error path in telebibz, what it means, and how to handle it — from Telegram API errors to handler failures, timeouts, and shutdown.
-
-## Contents
-
-1. [The error taxonomy](#1-the-error-taxonomy)
-2. [TelegramError anatomy](#2-telegramerror-anatomy)
-3. [429 rate limits and the flood gate](#3-429-rate-limits-and-the-flood-gate)
-4. [Handler errors and `bot.catch()`](#4-handler-errors-and-botcatch)
-5. [handlerTimeout and `UpdateTimeoutError`](#5-handlertimeout-and-updatetimeouterror)
-6. [Event-based error observation](#6-event-based-error-observation)
-7. [Transport retries and network errors](#7-transport-retries-and-network-errors)
-8. [Error handling recipes](#8-error-handling-recipes)
-
-## 1. The error taxonomy
-
-Every Telegram API failure is a `TelegramError` with a `kind`:
-
-| `kind` | Subclass | Meaning | Typical trigger |
-|---|---|---|---|
-| `rate-limit` | `TelegramRateLimitError` | Telegram answered 429 | Sending too fast; `retryAfter` is set |
-| `authentication` | `TelegramAuthError` | Token invalid/revoked (401) | Wrong token, revoked bot, logout |
-| `validation` | `TelegramValidationError` | Bad request parameters (400) | Unknown `file_id`, malformed payload |
-| `network` | `TelegramNetworkError` | Transport-level failure | DNS, socket, non-JSON response, download failure |
-| `server` | — | Telegram server error (5xx) | Transient; retried automatically |
-| `retryable` | — | Other retryable Telegram error | Flood-wait variants |
-| `unknown` | — | Anything else | — |
-
-Check `kind` when the reaction should differ:
-
-```ts
-import { TelegramError, TelegramRateLimitError } from "@xbibzlibrary/telebibz";
-
-try {
-  await ctx.reply("hello");
-} catch (error) {
-  if (error instanceof TelegramError) {
-    switch (error.kind) {
-      case "rate-limit":   console.log(`slow down ${error.retryAfter}s`); break;
-      case "authentication": console.error("token problem — stopping"); break;
-      case "validation":   console.warn(error.message); break;
-      default:             console.error(error.message);
-    }
-  }
-}
-```
-
-`instanceof TelegramRateLimitError` works too when you only care about 429s.
-
-## 2. TelegramError anatomy
-
-```ts
-try {
-  await bot.api.methods.getChatMember({ chat_id: -100123, user_id: 42 });
-} catch (error) {
-  if (error instanceof TelegramError) {
-    error.kind;       // one of the seven kinds above
-    error.errorCode;  // Telegram error_code (400, 401, 429, …) when present
-    error.method;     // "getChatMember" — the failing call
-    error.payload;    // the payload that was sent
-    error.retryAfter; // seconds, only for 429 (from parameters.retry_after)
-    error.message;    // Telegram's description
-  }
-}
-```
-
-## 3. 429 rate limits and the flood gate
-
-You normally never see a 429, because the transport handles them for you:
-
-1. Telegram answers 429 with `parameters.retry_after`.
-2. The **flood gate** pauses *new* outgoing requests for exactly that window — protecting all in-flight traffic, not just the request that was rejected.
-3. The failed request is retried automatically, then the failure (if it persists) surfaces as `TelegramRateLimitError`.
-
-The flood gate is the **only** delay the library ever introduces — it is never a proactive cooldown. Tune or disable it per transport:
-
-```ts
-const bot = new Bot({
-  token: process.env.TELEGRAM_BOT_TOKEN!,
-  transportOptions: {
-    floodGate: false,   // handle 429s entirely yourself
-    retries: 3,         // retry count for 429/5xx/network errors
-    backoffMs: 250,     // exponential backoff base
-    maxBackoffMs: 8_000,
-    timeoutMs: 30_000,  // per-request timeout
-  },
-});
-```
-
-If you disable the gate, catch `TelegramRateLimitError` and honor `retryAfter` yourself — Telegram's word is final:
-
-```ts
-catch (error) {
-  if (error instanceof TelegramRateLimitError) {
-    await sleep((error.retryAfter ?? 1) * 1000);
-    return retry();
-  }
-  throw error;
-}
-```
-
-## 4. Handler errors and `bot.catch()`
-
-Without an error boundary, a throwing handler rejects `handleUpdate()` (and a webhook answers 500). With `bot.catch()`, failures are routed to one place:
-
-```ts
-bot.catch(async (error, ctx) => {
-  console.error("handler failed:", error);
-
-  if (error instanceof TelegramError && error.kind === "authentication") {
-    process.exitCode = 1;             // unrecoverable — let the supervisor restart
-    await bot.stop();
-    return;
-  }
-
-  await ctx.reply("❌ Terjadi kesalahan. Coba lagi."); // ctx is the failing update's context
-});
-```
-
-Key behaviors:
-- Only the failing update is affected — other chats keep processing concurrently.
-- Per-chat ordering is preserved: the next update of the same chat still waits for this one.
-- `broadcast()` failures are collected in the report instead of throwing.
-
-## 5. handlerTimeout and `UpdateTimeoutError`
-
-`handlerTimeout` (default **90 000 ms**, matching Telegraf) protects the pipeline from hung handlers:
-
-```ts
-const bot = new Bot({ token, handlerTimeout: 30_000 }); // 0 or Infinity disables
-```
-
-- The hung update's `handleUpdate()` promise rejects with `UpdateTimeoutError` and flows through `update:error` → `bot:error` → `bot.catch()`.
-- **The handler keeps running in the background** — sessions and conversations still complete their writes; the timeout only releases the pipeline.
-- Per-chat ordering is unaffected.
-
-## 6. Event-based error observation
-
-For metrics/ logging independent of the boundary, listen on the event bus:
-
-```ts
-bot.events.on("update:error", ({ update, error }) => {
-  metrics.increment("handler_errors", { updateId: (update as { update_id?: number }).update_id });
-});
-bot.events.on("bot:error", ({ error }) => log.error("bot error", { error }));
-bot.events.on("api:response", ({ method, durationMs }) => {
-  if (durationMs > 3_000) log.warn("slow api call", { method, durationMs });
-});
-```
-
-## 7. Transport retries and network errors
-
-`FetchTransport` retries automatically on: 429 (with Telegram's `retry_after`), 5xx, network errors, and non-JSON responses — with exponential backoff and jitter. After `retries` attempts the last error surfaces as `TelegramNetworkError` (with `status` and a truncated cause). Authentication errors (401) and validation errors (400) are **never** retried — retrying cannot fix them.
-
-## 8. Error handling recipes
-
-**Retry with backoff around a single call** (beyond transport retries):
-
-```ts
-async function withRetry<T>(run: () => Promise<T>, attempts = 3): Promise<T> {
-  for (let i = 0; i < attempts; i++) {
-    try { return await run(); }
-    catch (error) {
-      if (error instanceof TelegramError && ["authentication", "validation"].includes(error.kind)) throw error;
-      if (i === attempts - 1) throw error;
-      await new Promise((r) => setTimeout(r, 500 * 2 ** i));
-    }
-  }
-  throw new Error("unreachable");
-}
-```
-
-**Fail fast on bad tokens** (polling with an invalid token):
-
-```ts
-try {
-  await bot.start();
-} catch (error) {
-  if (error instanceof TelegramError && error.kind === "authentication") {
-    console.error("TELEGRAM_BOT_TOKEN is invalid or revoked");
-  }
-  throw error;
-}
-```
-
-**Graceful shutdown** — `stop()` drains in-flight handlers first:
-
-```ts
-process.on("SIGINT", () => { void bot.stop().then(() => process.exit(0)); });
-process.on("SIGTERM", () => { void bot.stop().then(() => process.exit(0)); });
-```
-
-Bahasa Indonesia: [ERRORS.id.md](ERRORS.id.md) · 简体中文: [ERRORS.zh-CN.md](ERRORS.zh-CN.md)

package/docs/ERRORS.zh-CN.md

@@ -1,194 +0,0 @@
-# 错误处理指南（简体中文）
-
-telebibz 中每一条错误路径、其含义与处理方式 —— 从 Telegram API 错误到 handler 失败、超时与关机。
-
-## 目录
-
-1. [错误分类](#1-错误分类)
-2. [TelegramError 解剖](#2-telegramerror-解剖)
-3. [429 限流与 flood gate](#3-429-限流与-flood-gate)
-4. [错误处理器与 `bot.catch()`](#4-错误处理器与-botcatch)
-5. [handlerTimeout 与 `UpdateTimeoutError`](#5-handlertimeout-与-updatetimeouterror)
-6. [基于事件的错误观测](#6-基于事件的错误观测)
-7. [传输层重试与网络错误](#7-传输层重试与网络错误)
-8. [错误处理配方](#8-错误处理配方)
-
-## 1. 错误分类
-
-每个 Telegram API 失败都是带 `kind` 的 `TelegramError`：
-
-| `kind` | 子类 | 含义 | 常见诱因 |
-|---|---|---|---|
-| `rate-limit` | `TelegramRateLimitError` | Telegram 返回 429 | 发送过快；`retryAfter` 有值 |
-| `authentication` | `TelegramAuthError` | token 无效/被吊销（401） | token 错误、bot 被吊销、logout |
-| `validation` | `TelegramValidationError` | 请求参数错误（400） | 未知的 `file_id`、损坏的负载 |
-| `network` | `TelegramNetworkError` | 传输层失败 | DNS、socket、非 JSON 响应、下载失败 |
-| `server` | — | Telegram 服务器错误（5xx） | 瞬时故障；自动重试 |
-| `retryable` | — | 其他可重试的 Telegram 错误 | flood-wait 变体 |
-| `unknown` | — | 其他 | — |
-
-当不同错误需要不同反应时，检查 `kind`：
-
-```ts
-import { TelegramError, TelegramRateLimitError } from "@xbibzlibrary/telebibz";
-
-try {
-  await ctx.reply("hello");
-} catch (error) {
-  if (error instanceof TelegramError) {
-    switch (error.kind) {
-      case "rate-limit":     console.log(`放慢 ${error.retryAfter}s`); break;
-      case "authentication": console.error("token 问题 —— 停机"); break;
-      case "validation":     console.warn(error.message); break;
-      default:               console.error(error.message);
-    }
-  }
-}
-```
-
-如果只关心 429，也可以用 `instanceof TelegramRateLimitError`。
-
-## 2. TelegramError 解剖
-
-```ts
-try {
-  await bot.api.methods.getChatMember({ chat_id: -100123, user_id: 42 });
-} catch (error) {
-  if (error instanceof TelegramError) {
-    error.kind;       // 上表七种 kind 之一
-    error.errorCode;  // Telegram 的 error_code（400、401、429……），如存在
-    error.method;     // "getChatMember" —— 失败的调用
-    error.payload;    // 发出的负载
-    error.retryAfter; // 秒数，仅 429（来自 parameters.retry_after）
-    error.message;    // Telegram 的描述
-  }
-}
-```
-
-## 3. 429 限流与 flood gate
-
-通常你根本见不到 429，因为传输层已经处理了：
-
-1. Telegram 返回带 `parameters.retry_after` 的 429。
-2. **flood gate** 在该时间窗内暂停*新的*外发请求 —— 保护整个流量，而不只是被拒绝的那个请求。
-3. 被拒请求自动重试；若仍失败，最终以 `TelegramRateLimitError` 抛出。
-
-flood gate 是本库引入的唯一暂停机制 —— 从不做主动冷却。可按传输层调整或关闭：
-
-```ts
-const bot = new Bot({
-  token: process.env.TELEGRAM_BOT_TOKEN!,
-  transportOptions: {
-    floodGate: false,   // 完全自行处理 429
-    retries: 3,         // 429/5xx/网络错误的重试次数
-    backoffMs: 250,     // 指数退避基数
-    maxBackoffMs: 8_000,
-    timeoutMs: 30_000,  // 单个请求超时
-  },
-});
-```
-
-关闭 gate 后，请捕获 `TelegramRateLimitError` 并遵守 `retryAfter` —— Telegram 说了算：
-
-```ts
-catch (error) {
-  if (error instanceof TelegramRateLimitError) {
-    await sleep((error.retryAfter ?? 1) * 1000);
-    return retry();
-  }
-  throw error;
-}
-```
-
-## 4. 错误处理器与 `bot.catch()`
-
-没有错误边界时，抛异常的 handler 会让 `handleUpdate()` 拒绝（webhook 则返回 500）。使用 `bot.catch()` 把失败引到一处：
-
-```ts
-bot.catch(async (error, ctx) => {
-  console.error("handler 失败：", error);
-
-  if (error instanceof TelegramError && error.kind === "authentication") {
-    process.exitCode = 1;             // 不可恢复 —— 交给监督进程重启
-    await bot.stop();
-    return;
-  }
-
-  await ctx.reply("❌ 出错了，请稍后再试。"); // ctx = 失败 update 的上下文
-});
-```
-
-关键行为：
-- 只有失败的 update 受影响 —— 其他 chat 继续并发处理。
-- 每 chat 顺序保持不变：同一 chat 的后续 update 仍会排队等待。
-- `broadcast()` 的失败收集在报告中，而不是抛异常。
-
-## 5. handlerTimeout 与 `UpdateTimeoutError`
-
-`handlerTimeout`（默认 **90 000 毫秒**，与 Telegraf 一致）保护流水线免受挂起 handler 的拖累：
-
-```ts
-const bot = new Bot({ token, handlerTimeout: 30_000 }); // 0 或 Infinity 表示禁用
-```
-
-- 挂起 update 的 `handleUpdate()` promise 抛出 `UpdateTimeoutError`，并依次流经 `update:error` → `bot:error` → `bot.catch()`。
-- **handler 仍在后台运行** —— session 与 conversation 照常完成写入；超时只释放流水线。
-- 每 chat 顺序不受影响。
-
-## 6. 基于事件的错误观测
-
-要独立于错误边界的指标/日志，监听事件总线：
-
-```ts
-bot.events.on("update:error", ({ update, error }) => {
-  metrics.increment("handler_errors", { updateId: (update as { update_id?: number }).update_id });
-});
-bot.events.on("bot:error", ({ error }) => log.error("bot error", { error }));
-bot.events.on("api:response", ({ method, durationMs }) => {
-  if (durationMs > 3_000) log.warn("慢速 API 调用", { method, durationMs });
-});
-```
-
-## 7. 传输层重试与网络错误
-
-`FetchTransport` 自动重试：429（遵守 Telegram 的 `retry_after`）、5xx、网络错误、非 JSON 响应 —— 采用指数退避加抖动。重试 `retries` 次后，最后一个错误以 `TelegramNetworkError` 抛出（含 `status` 与截断的 cause）。认证错误（401）和校验错误（400）**从不**重试 —— 重试无济于事。
-
-## 8. 错误处理配方
-
-**围绕单次调用的退避重试**（在传输层重试之外）：
-
-```ts
-async function withRetry<T>(run: () => Promise<T>, attempts = 3): Promise<T> {
-  for (let i = 0; i < attempts; i++) {
-    try { return await run(); }
-    catch (error) {
-      if (error instanceof TelegramError && ["authentication", "validation"].includes(error.kind)) throw error;
-      if (i === attempts - 1) throw error;
-      await new Promise((r) => setTimeout(r, 500 * 2 ** i));
-    }
-  }
-  throw new Error("unreachable");
-}
-```
-
-**token 无效时快速失败**（用错误 token 轮询）：
-
-```ts
-try {
-  await bot.start();
-} catch (error) {
-  if (error instanceof TelegramError && error.kind === "authentication") {
-    console.error("TELEGRAM_BOT_TOKEN 无效或已吊销");
-  }
-  throw error;
-}
-```
-
-**优雅关机** —— `stop()` 先排空在途 handler：
-
-```ts
-process.on("SIGINT", () => { void bot.stop().then(() => process.exit(0)); });
-process.on("SIGTERM", () => { void bot.stop().then(() => process.exit(0)); });
-```
-
-English: [ERRORS.md](ERRORS.md) · Bahasa Indonesia: [ERRORS.id.md](ERRORS.id.md)

package/docs/FILES.id.md

@@ -1,243 +0,0 @@
-# Bekerja dengan file: upload, download, validasi (Bahasa Indonesia)
-
-Panduan lengkap setiap alur file di telebibz: mengunduh file yang dikirim user, mengunggah file ke Telegram, mengirim ulang via `file_id`, memvalidasi unggahan, serta batasan dan jebakan Telegram Bot API.
-
-## Daftar isi
-
-1. [Download: satu panggilan dengan `downloadFile()`](#1-download-satu-panggilan-dengan-downloadfile)
-2. [Download: alur manual dengan `getFile()`](#2-download-alur-manual-dengan-getfile)
-3. [Penamaan property: `file_path` vs `filePath`](#3-penamaan-property-file_path-vs-filepath)
-4. [Upload: semua tipe sumber](#4-upload-semua-tipe-sumber)
-5. [Upload: validasi sebelum mengirim](#5-upload-validasi-sebelum-mengirim)
-6. [Media group dengan `attach://`](#6-media-group-dengan-attach)
-7. [Batasan dan masa berlaku](#7-batasan-dan-masa-berlaku)
-8. [Local Bot API server](#8-local-bot-api-server)
-9. [Menguji alur file tanpa jaringan](#9-menguji-alur-file-tanpa-jaringan)
-10. [Troubleshooting](#10-troubleshooting)
-
-## 1. Download: satu panggilan dengan `downloadFile()`
-
-`bot.downloadFile()` / `ctx.downloadFile()` me-resolve `file_id` lewat `getFile` lalu mengunduh byte mentahnya dalam satu panggilan:
-
-```ts
-bot.on("message:document", async (ctx) => {
-  const fileId = ctx.message.document.file_id;
-
-  // Unduh ke memori…
-  const file = await ctx.downloadFile(fileId);
-  console.log(file.fileName, file.sizeBytes, file.url);
-  // file.bytes adalah Uint8Array
-
-  // …atau langsung ke disk
-  const saved = await ctx.downloadFile(fileId, { destination: "downloads/report.pdf" });
-  console.log(`Tersimpan di ${saved.savedTo}`);
-});
-```
-
-Hasilnya (`DownloadedFile`) membawa semua yang dibutuhkan:
-
-| Field | Arti |
-|---|---|
-| `file` | Objek `File` Telegram yang dikembalikan `getFile` |
-| `bytes` | Byte mentah file (`Uint8Array`) |
-| `filePath` | `file_path` yang dipakai untuk unduhan |
-| `url` | URL unduhan langsung — valid **minimal 1 jam** |
-| `fileName` | Segmen path terakhir `filePath` (mis. `report.pdf`) |
-| `sizeBytes` | Panjang byte `bytes` |
-| `savedTo` | Path lokal, terisi saat Anda memberi `destination` |
-
-Error-nya presisi:
-- Telegram tidak mengembalikan `file_path` → `TelegramError` dengan `kind: "validation"`
-- Unduhan HTTP-nya sendiri gagal → `TelegramNetworkError` (lengkap dengan status)
-- `getFile` gagal (file_id salah, file terlalu besar) → `TelegramError` asli dari Telegram
-
-Keduanya menerima `AbortSignal`:
-
-```ts
-const controller = new AbortController();
-setTimeout(() => controller.abort(), 10_000);
-const file = await bot.downloadFile(fileId, { signal: controller.signal });
-```
-
-## 2. Download: alur manual dengan `getFile()`
-
-Kalau ingin membangun URL sendiri (mis. untuk HTTP client lain):
-
-```ts
-const file = await ctx.getFile(fileId);          // objek File Telegram
-if (!file.file_path) throw new Error("File tidak tersedia (di atas 20 MB atau kedaluwarsa)");
-
-const url = `https://api.telegram.org/file/bot${process.env.TELEGRAM_BOT_TOKEN}/${file.file_path}`;
-const response = await fetch(url);               // ← fetch — JANGAN createReadStream (tidak bisa membuka URL)
-if (!response.ok) throw new Error(`Unduhan gagal: HTTP ${response.status}`);
-const bytes = new Uint8Array(await response.arrayBuffer());
-```
-
-Tiga aturan yang terkandung di snippet ini:
-1. Prefix URL-nya `/file/bot<TOKEN>/` — **kata `bot` wajib ada**. Lupa menuliskannya adalah kesalahan paling umum dan hasilnya `404 Not Found`.
-2. `fetch` yang mengunduh byte; `fs.createReadStream()` hanya membuka **path lokal** — diberi URL ia akan crash dengan `ENOENT` pada stream error yang tidak tertangani.
-3. URL dijamin valid **minimal 1 jam**. Jangan pernah cache lama; panggil `getFile` lagi setelah kedaluwarsa.
-
-## 3. Penamaan property: `file_path` vs `filePath`
-
-Ini menjegal semua orang minimal sekali. Dua gaya penamaan ini milik layer yang berbeda:
-
-| Penamaan | Milik | Contoh |
-|---|---|---|
-| `snake_case` (`file_path`) | **Objek mentah Telegram** — hasil `getFile()`, `ctx.message.document`, `ctx.message.photo` | `file.file_path`, `document.file_id`, `photo.file_unique_id` |
-| `camelCase` (`filePath`) | **Tipe hasil telebibz** — `DownloadedFile` dan opsi library | `downloaded.filePath`, `downloaded.fileName`, `downloaded.sizeBytes` |
-
-```ts
-const file = await ctx.getFile(fileId);
-file.file_path;   // ✅ objek Telegram → snake_case
-file.filePath;    // ❌ undefined — itu nama milik DownloadedFile
-
-const downloaded = await ctx.downloadFile(fileId);
-downloaded.filePath;  // ✅ hasil library → camelCase
-downloaded.file_path; // ❌ undefined
-```
-
-Kalau cek "tidak ada path" Anda gagal padahal response yang di-log jelas memuat `file_path`, berarti Anda membaca property camelCase dari objek snake_case.
-
-## 4. Upload: semua tipe sumber
-
-Semua pengirim `replyWith*` dan panggilan API mentah menerima tipe `InputFile`. Kirim unggahan sebagai `{ source, filename? }`:
-
-```ts
-// Dari path di disk (absolut, ./, atau ../)
-await ctx.replyWithDocument({ source: "reports/q3.pdf", filename: "Q3-report.pdf" });
-
-// Dari byte mentah
-const bytes = new Uint8Array(await someFile.bytes());
-await ctx.replyWithDocument({ source: bytes, filename: "data.bin" });
-
-// Dari Blob atau File (File membawa namanya sendiri)
-await ctx.replyWithDocument({ source: new File([bytes], "photo.png") });
-
-// Dari web ReadableStream atau stream Node (dikuras otomatis)
-import { createReadStream } from "node:fs";
-await ctx.replyWithVideo({ source: createReadStream("clip.mp4"), filename: "clip.mp4" });
-```
-
-Catatan:
-- `filename` menimpa nama apa pun yang dimiliki sumber (untuk path, basename dipakai secara default).
-- **Anda tidak pernah merakit `FormData` sendiri.** Transport mendeteksi payload unggahan dan beralih ke multipart otomatis. `FormData` buatan tangan dengan stream Node pasti gagal (`append` butuh `Blob`) — selalu serahkan stream/byte ke library.
-- Nilai telanjang juga bisa: `await ctx.replyWithDocument(bytes)` (tanpa nama) atau file id Telegram yang sudah ada:
-
-```ts
-// Kirim ulang via file_id — tanpa unduh, tanpa upload, tanpa batas ukuran
-await ctx.replyWithDocument(ctx.message.document.file_id);
-```
-
-## 5. Upload: validasi sebelum mengirim
-
-`validateUpload()` / `assertValidUpload()` menegakkan aturan Anda sendiri sebelum satu byte pun keluar dari proses:
-
-```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("Penggunaan: /doc <path>"));
-
-  const info = await stat(filePath);
-  try {
-    assertValidUpload(
-      { sizeBytes: info.size, fileName: filePath },
-      {
-        maxBytes: 50 * 1024 * 1024,                       // batas dokumen Telegram
-        allowedExtensions: [".pdf", ".docx", ".pptx"],    // case-insensitive
-      },
-    );
-  } catch (error) {
-    if (error instanceof UploadValidationError) {
-      return void (await ctx.reply(`❌ ${error.message}`)); // mencantumkan semua pelanggaran
-    }
-    throw error;
-  }
-
-  await ctx.replyWithDocument({ source: filePath });
-});
-```
-
-`validateUpload()` mengembalikan daftar issue alih-alih melempar (array kosong = valid). Aturan MIME mendukung wildcard:
-
-```ts
-validateUpload({ mimeType: "image/png" }, { allowedMimeTypes: ["image/*"] }); // []
-```
-
-Aturan yang tersedia: `maxBytes`, `allowedMimeTypes` (persis atau wildcard `image/*`), `allowedExtensions` (titik opsional, case-insensitive).
-
-## 6. Media group dengan `attach://`
-
-`sendMediaGroup` menerima array JSON input media; file biner ikut sebagai **bagian form terpisah** yang direferensikan lewat `attach://<nama>`:
-
-```ts
-await ctx.replyWithMediaGroup([
-  { type: "photo", media: "attach://pic1" },
-  { type: "photo", media: "attach://pic2" },
-], { pic1: bytes1, pic2: bytes2 } as never);
-```
-
-Transport mendeteksi bagian biner dan beralih ke multipart otomatis; array `media` sendiri diserialisasi sebagai satu field JSON — persis kontrak Telegram.
-
-## 7. Batasan dan masa berlaku
-
-| Batasan | Nilai | Catatan |
-|---|---|---|
-| Unduhan via `getFile` | **20 MB** | File lebih besar: `getFile` gagal (HTTP 400 "file is too big") — bukan `file_path` kosong |
-| Upload foto | 10 MB | |
-| Upload file lain | 50 MB | |
-| Kirim ulang via `file_id` | **Tanpa batas** | File sudah ada di Telegram |
-| Kirim via URL | 5 MB foto / 20 MB lainnya | Telegram yang mengambil URL-nya |
-| Validitas URL unduhan | **≥ 1 jam** | Jalankan `getFile` lagi setelah kedaluwarsa |
-| Kehadiran `file_path` | Opsional di skema | Selalu cek sebelum dipakai |
-
-Batas upload milik Telegram, bukan library — `validateUpload()` adalah cara Anda menolak lebih awal dengan pesan yang ramah.
-
-## 8. Local Bot API server
-
-Menjalankan [local Bot API server](https://core.telegram.org/bots/api#using-a-local-bot-api-server) sendiri menghapus batas unduhan 20 MB dan mengizinkan upload hingga 2000 MB:
-
-```ts
-const bot = new Bot({
-  token: process.env.TELEGRAM_BOT_TOKEN!,
-  apiBaseUrl: "http://localhost:8081",   // opsi Bot API
-  transportOptions: { timeoutMs: 600_000 },
-});
-```
-
-`downloadFile()` dan `fileUrl()` memetakan `/bot<token>` ke `/file/bot<token>` di base URL mana pun, jadi unduhan juga bekerja lewat server lokal. Catatan: pada server lokal, `file_path` berupa **path absolut di disk server** — fetch URL-nya hanya bila server jarak jauh; baca path-nya langsung bila bot berjalan di mesin yang sama.
-
-## 9. Menguji alur file tanpa jaringan
-
-`MockTransport` (dari `@xbibzlibrary/telebibz/testing`) mengimplementasikan member download:
-
-```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"] — unduhan yang tercatat
-```
-
-Lihat [TESTING.id.md](TESTING.id.md) untuk panduan testing lengkap.
-
-## 10. Troubleshooting
-
-| Gejala | Penyebab | Perbaikan |
-|---|---|---|
-| "Gagal mendapatkan path file" padahal response yang di-log memuat `file_path` | Membaca `file.filePath`/`file.path` dari objek mentah Telegram | Pakai `file.file_path` (snake_case) — atau lewati manual sepenuhnya dengan `ctx.downloadFile()` |
-| `ENOENT … open 'https://…'` pada ReadStream | `createReadStream()` hanya membuka path lokal | Pakai `fetch(url)` untuk URL, atau `ctx.downloadFile()` |
-| URL unduhan mengembalikan 404 | Prefix `bot` hilang di `/file/bot<TOKEN>/` | Pakai field `url` dari `downloadFile()` — selalu dibangun dengan benar |
-| `getFile` mengembalikan HTTP 400 "file is too big" | File di atas 20 MB | Pakai local Bot API server, atau kirim ulang via `file_id` |
-| `FormData append: parameter 2 is not of type 'Blob'` | `FormData` buatan tangan berisi stream Node | Serahkan `{ source: stream, filename }` ke `replyWith*`; library yang mengurus multipart |
-| `file_path` tadinya ada, sekarang hilang | URL kedaluwarsa (>1 jam) | Panggil `getFile` lagi |
-| File terunduh 0 byte / salah | `file_id` milik bot lain | `file_id` bersifat per-bot; pakai id dari update bot Anda sendiri |
-
-English: [FILES.md](FILES.md) · 简体中文: [FILES.zh-CN.md](FILES.zh-CN.md)