@xbibzlibrary/telebibz 0.4.2 → 0.4.4

package/dist-cjs/src/api/transport.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FetchTransport = void 0;
 const promises_1 = require("node:fs/promises");
 const node_path_1 = require("node:path");
+const consumers_1 = require("node:stream/consumers");
 const errors_js_1 = require("./errors.js");
 class FetchTransport {
     baseUrl;
@@ -46,6 +47,37 @@ class FetchTransport {
         const retryAfterMs = Math.max(0, (data.parameters?.retry_after ?? 0) * 1000);
         this.floodUntil = Math.max(this.floodUntil, Date.now() + retryAfterMs);
     }
+    /** Direct-download URL for a `file_path` from `getFile` (`/bot<token>` → `/file/bot<token>`). */
+    fileUrl(filePath) {
+        const downloadBase = /\/bot[^/]+$/.test(this.baseUrl) ? this.baseUrl.replace(/\/bot([^/]+)$/, "/file/bot$1") : this.baseUrl;
+        return `${downloadBase}/${filePath}`;
+    }
+    /** Downloads the raw bytes behind a `file_path` from `getFile` (Telegram caps downloads at 20 MB). */
+    async download(filePath, signal) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(new Error("File download timed out")), Math.max(this.timeoutMs, 120_000));
+        const onAbort = () => controller.abort(signal?.reason);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            const response = await this.fetchImpl(this.fileUrl(filePath), { method: "GET", signal: controller.signal });
+            if (!response.ok) {
+                const bodyText = await response.text().catch(() => "");
+                throw new errors_js_1.TelegramNetworkError(`Failed to download ${filePath}: HTTP ${response.status} ${response.statusText || "request failed"}`, { method: "getFile", payload: { file_path: filePath }, status: response.status, cause: bodyText.slice(0, 512) });
+            }
+            return new Uint8Array(await response.arrayBuffer());
+        }
+        catch (error) {
+            if (error instanceof errors_js_1.TelegramNetworkError)
+                throw error;
+            if (signal?.aborted)
+                throw error;
+            throw new errors_js_1.TelegramNetworkError(`Failed to download ${filePath}: ${error instanceof Error ? error.message : String(error)}`, { method: "getFile", payload: { file_path: filePath }, cause: error });
+        }
+        finally {
+            clearTimeout(timeout);
+            signal?.removeEventListener("abort", onAbort);
+        }
+    }
     async request({ method, payload = {}, signal, timeoutMs }) {
         const effectiveTimeoutMs = timeoutMs ?? this.timeoutMs;
         const hasUpload = await containsUpload(payload);
@@ -149,10 +181,20 @@ function isRetryableNetworkError(error) {
 async function containsUpload(value) {
     if (value instanceof Uint8Array || value instanceof ArrayBuffer || value instanceof Blob)
         return true;
+    if (value instanceof ReadableStream)
+        return true;
     if (typeof value === "string")
         return false;
-    if (value && typeof value === "object" && "source" in value)
-        return containsUpload(value.source);
+    if (value && typeof value === "object" && "source" in value) {
+        const source = value.source;
+        // A path-like string source means the transport reads the file from disk
+        // and must switch to multipart — a plain string source is just a file_id.
+        if (typeof source === "string" && ((0, node_path_1.isAbsolute)(source) || source.startsWith("./") || source.startsWith("../")))
+            return true;
+        return containsUpload(source);
+    }
+    if (typeof value?.pipe === "function")
+        return true;
     if (Array.isArray(value)) {
         for (const item of value)
             if (await containsUpload(item))
@@ -165,6 +207,13 @@ async function containsUpload(value) {
     }
     return false;
 }
+/** Converts a Node.js or web ReadableStream to a Blob by draining it. */
+async function streamToBlob(stream) {
+    if (stream instanceof ReadableStream)
+        return new Blob([await new Response(stream).arrayBuffer()]);
+    const bytes = await (0, consumers_1.buffer)(stream);
+    return new Blob([bytes]);
+}
 async function appendFormValue(form, key, value) {
     if (value === undefined || value === null)
         return;
@@ -180,6 +229,10 @@ async function appendFormValue(form, key, value) {
         form.append(key, value);
         return;
     }
+    if (value instanceof ReadableStream || typeof value?.pipe === "function") {
+        form.append(key, await streamToBlob(value));
+        return;
+    }
     if (value && typeof value === "object" && "source" in value) {
         const upload = value;
         if (typeof upload.source === "string" && ((0, node_path_1.isAbsolute)(upload.source) || upload.source.startsWith("./") || upload.source.startsWith("../"))) {
@@ -188,6 +241,18 @@ async function appendFormValue(form, key, value) {
             form.append(key, new Blob([bytes]), upload.filename ?? (0, node_path_1.basename)(filePath));
             return;
         }
+        if (upload.filename !== undefined && upload.source instanceof Uint8Array) {
+            form.append(key, new Blob([upload.source]), upload.filename);
+            return;
+        }
+        if (upload.filename !== undefined && upload.source instanceof Blob) {
+            form.append(key, upload.source, upload.filename);
+            return;
+        }
+        if (upload.filename !== undefined && upload.source instanceof ArrayBuffer) {
+            form.append(key, new Blob([upload.source]), upload.filename);
+            return;
+        }
         return appendFormValue(form, key, upload.source);
     }
     if (typeof value === "string") {

package/dist-cjs/src/context/context.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Context = void 0;
+const promises_1 = require("node:fs/promises");
 class Context {
     update;
     api;
@@ -178,6 +179,20 @@ class Context {
     async getUserProfilePhotos(userId = this.from?.id, extra = {}) { if (!userId)
         throw new Error("No user in this update."); return this.api.call("getUserProfilePhotos", { user_id: userId, ...extra }); }
     async getFile(fileId) { return this.api.methods.getFile({ file_id: fileId }); }
+    /**
+     * Resolves `fileId` with `getFile` and downloads the raw bytes (see
+     * `Bot.downloadFile`). Pass `destination` to persist the bytes to a local
+     * file path. Prefer this over reading `file_path` manually — it throws
+     * precise `TelegramError`s when Telegram returns no path.
+     */
+    async downloadFile(fileId, options = {}) {
+        const downloaded = await this.api.downloadFile(fileId, options.signal !== undefined ? { signal: options.signal } : {});
+        if (options.destination !== undefined) {
+            await (0, promises_1.writeFile)(options.destination, downloaded.bytes);
+            return { ...downloaded, savedTo: options.destination };
+        }
+        return downloaded;
+    }
     // ─────────────────────────────────────────────────────────────────────────────
     // Admin & moderation (full Telegraf-parity surface; chat defaults to ctx.chat)
     // ─────────────────────────────────────────────────────────────────────────────

package/dist-cjs/src/core/bot.js

@@ -16,6 +16,7 @@ const broadcast_js_1 = require("../broadcast/broadcast.js");
 const concurrency_js_1 = require("../utils/concurrency.js");
 const webhook_reply_js_1 = require("./webhook-reply.js");
 const node_async_hooks_1 = require("node:async_hooks");
+const promises_1 = require("node:fs/promises");
 /** Thrown when a single update exceeds `handlerTimeout`; the handler keeps running in the background. */
 class UpdateTimeoutError extends Error {
     name = "UpdateTimeoutError";
@@ -264,6 +265,21 @@ class Bot {
     async getMe() { const me = await this.api.methods.getMe(); this.me = me; return me; }
     async setCommands(commands, scope, languageCode) { return this.api.call("setMyCommands", { commands, scope, language_code: languageCode }); }
     async deleteCommands(scope, languageCode) { return this.api.call("deleteMyCommands", { scope, language_code: languageCode }); }
+    /**
+     * Downloads a Telegram file by `file_id`: resolves it with `getFile`, then
+     * fetches the raw bytes via the transport's download endpoint. Pass
+     * `destination` to also persist the bytes to a local file path. The
+     * returned `url` is valid for at least one hour; Telegram caps downloads
+     * at 20 MB.
+     */
+    async downloadFile(fileId, options = {}) {
+        const downloaded = await this.api.downloadFile(fileId, options.signal !== undefined ? { signal: options.signal } : {});
+        if (options.destination !== undefined) {
+            await (0, promises_1.writeFile)(options.destination, downloaded.bytes);
+            return { ...downloaded, savedTo: options.destination };
+        }
+        return downloaded;
+    }
     /**
      * Handles a single update. Updates for different chats run in parallel;
      * updates for the same chat are processed strictly in arrival order so

package/dist-cjs/src/index.js

@@ -29,6 +29,7 @@ __exportStar(require("./queue/queue.js"), exports);
 __exportStar(require("./plugins/plugin.js"), exports);
 __exportStar(require("./webhook/handler.js"), exports);
 __exportStar(require("./utils/text.js"), exports);
+__exportStar(require("./utils/files.js"), exports);
 __exportStar(require("./utils/concurrency.js"), exports);
 __exportStar(require("./broadcast/broadcast.js"), exports);
 __exportStar(require("./state/conversation.js"), exports);

package/dist-cjs/src/testing.js

@@ -9,9 +9,15 @@ const bot_js_1 = require("./core/bot.js");
 const context_js_1 = require("./context/context.js");
 class MockTransport {
     calls = [];
+    /** Downloads recorded through `download()` (the `file_path` values, in order). */
+    downloads = [];
+    /** Bytes returned by `download()`; defaults to the UTF-8 encoding of the file path. */
+    downloadBytes;
     responses = new Map();
     respond(method, response) { this.responses.set(method, response); return this; }
     async request(request) { this.calls.push(request); const configured = this.responses.get(request.method); const data = typeof configured === "function" ? configured(request.payload) : configured ?? { ok: true, result: true }; return { status: data.ok ? 200 : (data.error_code ?? 500), headers: new Headers(), data: data }; }
+    fileUrl(filePath) { return `mock://files/${filePath}`; }
+    async download(filePath) { this.downloads.push(filePath); return this.downloadBytes ?? new TextEncoder().encode(filePath); }
 }
 exports.MockTransport = MockTransport;
 function createMockUpdate(overrides = {}) { return { update_id: 1, message: { message_id: 1, date: Date.now(), chat: { id: 1, type: "private" }, from: { id: 2, is_bot: false, first_name: "Test" }, text: "/start" }, ...overrides }; }

package/dist-cjs/src/utils/files.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * File-upload validation helpers. Telegram caps uploads at 50 MB for most
+ * methods (10 MB for photos) and rejects mismatches between content and
+ * declared type; these helpers let applications enforce their own limits
+ * before a byte leaves the process.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UploadValidationError = void 0;
+exports.validateUpload = validateUpload;
+exports.assertValidUpload = assertValidUpload;
+/** Thrown by {@link assertValidUpload} when an upload violates the rules. */
+class UploadValidationError extends Error {
+    name = "UploadValidationError";
+    issues;
+    constructor(issues) {
+        super(`Upload rejected: ${issues.map((issue) => issue.message).join("; ")}`);
+        this.issues = issues;
+    }
+}
+exports.UploadValidationError = UploadValidationError;
+function normalizeExtension(extension) {
+    const value = extension.trim().toLowerCase();
+    return value.startsWith(".") ? value.slice(1) : value;
+}
+function mimeMatches(pattern, mimeType) {
+    const normalizedPattern = pattern.trim().toLowerCase();
+    if (normalizedPattern.endsWith("/*"))
+        return mimeType.toLowerCase().startsWith(normalizedPattern.slice(0, -1));
+    return mimeType.toLowerCase() === normalizedPattern;
+}
+/**
+ * Validates an upload against the rules and returns every violation found
+ * (an empty array means the upload is acceptable).
+ */
+function validateUpload(upload, rules) {
+    const issues = [];
+    if (rules.maxBytes !== undefined && upload.sizeBytes !== undefined && upload.sizeBytes > rules.maxBytes) {
+        issues.push({ code: "too_large", field: "sizeBytes", message: `size ${upload.sizeBytes} bytes exceeds the ${rules.maxBytes} byte limit`, actual: upload.sizeBytes, limit: rules.maxBytes });
+    }
+    if (rules.allowedMimeTypes !== undefined && rules.allowedMimeTypes.length > 0 && upload.mimeType !== undefined && !rules.allowedMimeTypes.some((pattern) => mimeMatches(pattern, upload.mimeType))) {
+        issues.push({ code: "mime_not_allowed", field: "mimeType", message: `MIME type ${upload.mimeType} is not allowed (allowed: ${rules.allowedMimeTypes.join(", ")})`, actual: upload.mimeType, limit: rules.allowedMimeTypes.join(", ") });
+    }
+    if (rules.allowedExtensions !== undefined && rules.allowedExtensions.length > 0 && upload.fileName !== undefined) {
+        const extension = upload.fileName.includes(".") ? upload.fileName.slice(upload.fileName.lastIndexOf(".") + 1) : "";
+        const normalized = normalizeExtension(extension);
+        if (!normalized || !rules.allowedExtensions.some((allowed) => normalizeExtension(allowed) === normalized)) {
+            issues.push({ code: "extension_not_allowed", field: "fileName", message: `extension .${normalized || "?"} is not allowed (allowed: ${rules.allowedExtensions.join(", ")})`, actual: upload.fileName, limit: rules.allowedExtensions.join(", ") });
+        }
+    }
+    return issues;
+}
+/** Like {@link validateUpload} but throws {@link UploadValidationError} when any rule is violated. */
+function assertValidUpload(upload, rules) {
+    const issues = validateUpload(upload, rules);
+    if (issues.length > 0)
+        throw new UploadValidationError(issues);
+}

package/docs/API.id.md

@@ -274,6 +274,22 @@ deleteCommands(
 
 Jalan pintas ke `deleteMyCommands`.
 
+### `bot.downloadFile(fileId, options?)`
+
+```ts
+downloadFile(
+  fileId: string,
+  options?: { signal?: AbortSignal; destination?: string },
+): Promise<DownloadedFile>
+```
+
+Me-resolve `fileId` lewat `getFile`, lalu mengunduh byte mentahnya melalui endpoint download transport. Berikan `destination` untuk juga menyimpan byte ke path file lokal (`savedTo` terisi pada hasil). Melempar `TelegramError` (kind `validation`) saat Telegram tidak mengembalikan `file_path` atau transport tidak bisa mengunduh, dan `TelegramNetworkError` saat unduhan gagal. Telegram membatasi unduhan pada 20 MB; `url` hasilnya tetap valid minimal satu jam.
+
+```ts
+const file = await bot.downloadFile(photoFileId, { destination: "downloads/photo.jpg" });
+console.log(file.fileName, file.sizeBytes, file.url, file.savedTo);
+```
+
 ### `bot.handleUpdate(update)`
 
 ```ts
@@ -593,6 +609,37 @@ raw(
 
 Memanggil method string sembarang di transport. Gunakan ini untuk method Telegram atau parameter baru yang belum masuk `TelegramMethodMap`. Response `ok: false` tetap diubah menjadi `TelegramError`.
 
+### `api.downloadFile(fileId, options?)`
+
+```ts
+downloadFile(fileId: string, options?: { signal?: AbortSignal }): Promise<DownloadedFile>
+```
+
+Inti `bot.downloadFile` di level API client: me-resolve `getFile`, memvalidasi `file_path` tersedia, lalu mengunduh byte melalui transport.
+
+### `DownloadedFile`
+
+```ts
+interface DownloadedFile {
+  file: File;            // objek File Telegram dari getFile
+  bytes: Uint8Array;     // byte mentah file (maks 20 MB sesuai Telegram)
+  filePath: string;      // file_path yang dipakai untuk unduhan
+  url: string;           // URL unduhan langsung, valid minimal satu jam
+  fileName: string;      // segmen path terakhir dari filePath
+  sizeBytes: number;     // panjang byte
+  savedTo?: string;      // terisi saat Bot.downloadFile menyimpan file ke disk
+}
+```
+
+### `fetchTransport.fileUrl(filePath)` dan `fetchTransport.download(filePath, signal?)`
+
+```ts
+fileUrl(filePath: string): string
+download(filePath: string, signal?: AbortSignal): Promise<Uint8Array>
+```
+
+`FetchTransport` memetakan base URL `/bot<token>` ke endpoint download `/file/bot<token>`; `download` melakukan GET byte (batas bawah timeout 120 detik untuk file besar) dan melempar `TelegramNetworkError` saat HTTP gagal. Keduanya member opsional pada interface `Transport`, jadi transport kustom boleh menghilangkannya — `downloadFile` lalu gagal dengan error validasi yang jelas, bukan crash.
+
 ### Parameter dan hasil bertipe yang tersedia
 
 Tipe berikut dipetakan khusus pada rilis ini.
@@ -1498,6 +1545,27 @@ template("Halo {{ user.name }}", { user: { name: "Ayu" } });
 
 ---
 
+### `validateUpload(upload, rules)`
+
+```ts
+validateUpload(upload: UploadLike, rules: UploadRules): UploadValidationIssue[]
+```
+
+Memvalidasi unggahan sebelum dikirim: `maxBytes` (batas ukuran), `allowedMimeTypes` (persis atau wildcard seperti `image/*`), dan `allowedExtensions` (case-insensitive, dengan atau tanpa titik awal). Mengembalikan semua pelanggaran yang ditemukan — array kosong berarti unggahan diterima.
+
+### `assertValidUpload(upload, rules)`
+
+Aturan yang sama, tetapi melempar `UploadValidationError` (dengan seluruh `issues` terlampir) alih-alih mengembalikannya.
+
+```ts
+import { assertValidUpload } from "@xbibzlibrary/telebibz";
+
+assertValidUpload(
+  { sizeBytes: fileBytes.length, mimeType: "image/png", fileName: "logo.png" },
+  { maxBytes: 5_000_000, allowedMimeTypes: ["image/png", "image/jpeg"], allowedExtensions: [".png", ".jpg"] },
+);
+```
+
 ## 14. Testing utilities
 
 Import dari `@xbibzlibrary/telebibz/testing` atau root package.
@@ -1524,6 +1592,8 @@ const transport = new MockTransport()
   });
 ```
 
+`MockTransport` juga mengimplementasikan member download opsional: `download(filePath)` mencatat path ke `downloads` dan mengembalikan `downloadBytes` (default: encoding UTF-8 dari path), serta `fileUrl(filePath)` mengembalikan `mock://files/<filePath>` — sehingga `bot.downloadFile()` sepenuhnya bisa dites tanpa jaringan.
+
 ### `createMockUpdate(overrides?)`
 
 ```ts

package/docs/API.md

@@ -291,6 +291,22 @@ deleteCommands(
 
 Shortcut to `deleteMyCommands`.
 
+### `bot.downloadFile(fileId, options?)`
+
+```ts
+downloadFile(
+  fileId: string,
+  options?: { signal?: AbortSignal; destination?: string },
+): Promise<DownloadedFile>
+```
+
+Resolves `fileId` through `getFile`, then downloads the raw bytes via the transport's download endpoint. Pass `destination` to also persist the bytes to a local file path (`savedTo` is set on the result). Throws a `TelegramError` (kind `validation`) when Telegram returns no `file_path` or the transport cannot download, and a `TelegramNetworkError` when the download fails. Telegram caps downloads at 20 MB; the returned `url` stays valid for at least one hour.
+
+```ts
+const file = await bot.downloadFile(photoFileId, { destination: "downloads/photo.jpg" });
+console.log(file.fileName, file.sizeBytes, file.url, file.savedTo);
+```
+
 ### `bot.handleUpdate(update)`
 
 ```ts
@@ -610,6 +626,37 @@ raw(
 
 Calls an arbitrary method string on the transport. Use this for Telegram methods or new parameters not yet included in `TelegramMethodMap`. Responses with `ok: false` are still converted into a `TelegramError`.
 
+### `api.downloadFile(fileId, options?)`
+
+```ts
+downloadFile(fileId: string, options?: { signal?: AbortSignal }): Promise<DownloadedFile>
+```
+
+The API-client core of `bot.downloadFile`: resolves `getFile`, validates that a `file_path` came back, and downloads the bytes through the transport.
+
+### `DownloadedFile`
+
+```ts
+interface DownloadedFile {
+  file: File;            // Telegram File object from getFile
+  bytes: Uint8Array;     // raw file bytes (max 20 MB per Telegram)
+  filePath: string;      // file_path used for the download
+  url: string;           // direct download URL, valid for at least one hour
+  fileName: string;      // last path segment of filePath
+  sizeBytes: number;     // byte length of bytes
+  savedTo?: string;      // set when Bot.downloadFile persisted the file to disk
+}
+```
+
+### `fetchTransport.fileUrl(filePath)` and `fetchTransport.download(filePath, signal?)`
+
+```ts
+fileUrl(filePath: string): string
+download(filePath: string, signal?: AbortSignal): Promise<Uint8Array>
+```
+
+`FetchTransport` maps its `/bot<token>` base URL to the `/file/bot<token>` download endpoint; `download` GETs the bytes (timeout floor of 120 s for large files) and throws `TelegramNetworkError` on HTTP failure. Both are optional members of the `Transport` interface, so custom transports may omit them — `downloadFile` then fails with a precise validation error instead of crashing.
+
 ### Available typed parameters and results
 
 The following types are specially mapped in this release.
@@ -1532,6 +1579,27 @@ template("Halo {{ user.name }}", { user: { name: "Ayu" } });
 
 ---
 
+### `validateUpload(upload, rules)`
+
+```ts
+validateUpload(upload: UploadLike, rules: UploadRules): UploadValidationIssue[]
+```
+
+Validates an upload before it is sent: `maxBytes` (size limit), `allowedMimeTypes` (exact or wildcard like `image/*`), and `allowedExtensions` (case-insensitive, with or without the leading dot). Returns every violation found — an empty array means the upload is acceptable.
+
+### `assertValidUpload(upload, rules)`
+
+Same rules, but throws `UploadValidationError` (with all `issues` attached) instead of returning them.
+
+```ts
+import { assertValidUpload } from "@xbibzlibrary/telebibz";
+
+assertValidUpload(
+  { sizeBytes: fileBytes.length, mimeType: "image/png", fileName: "logo.png" },
+  { maxBytes: 5_000_000, allowedMimeTypes: ["image/png", "image/jpeg"], allowedExtensions: [".png", ".jpg"] },
+);
+```
+
 ## 14. Testing utilities
 
 Import dari `@xbibzlibrary/telebibz/testing` atau root package.
@@ -1558,6 +1626,8 @@ const transport = new MockTransport()
   });
 ```
 
+`MockTransport` also implements the optional download members: `download(filePath)` records the path into `downloads` and returns `downloadBytes` (default: the UTF-8 encoding of the path), and `fileUrl(filePath)` returns `mock://files/<filePath>` — so `bot.downloadFile()` is fully testable without network access.
+
 ### `createMockUpdate(overrides?)`
 
 ```ts

package/docs/API.zh-CN.md

@@ -274,6 +274,22 @@ deleteCommands(
 
 相当于 `deleteMyCommands` 的快捷方式。
 
+### `bot.downloadFile(fileId, options?)`
+
+```ts
+downloadFile(
+  fileId: string,
+  options?: { signal?: AbortSignal; destination?: string },
+): Promise<DownloadedFile>
+```
+
+通过 `getFile` 解析 `fileId`，再经由 transport 的下载端点获取原始字节。传入 `destination` 可同时把字节保存到本地文件路径（结果中的 `savedTo` 会被填充）。当 Telegram 未返回 `file_path` 或 transport 不支持下载时抛出 `TelegramError`（kind 为 `validation`）；下载失败时抛出 `TelegramNetworkError`。Telegram 限制单次下载 20 MB；返回的 `url` 至少一小时内有效。
+
+```ts
+const file = await bot.downloadFile(photoFileId, { destination: "downloads/photo.jpg" });
+console.log(file.fileName, file.sizeBytes, file.url, file.savedTo);
+```
+
 ### `bot.handleUpdate(update)`
 
 ```ts
@@ -593,6 +609,37 @@ raw(
 
 在 transport 上调用任意字符串方法。用于调用尚未包含在 `TelegramMethodMap` 的新的 Telegram 方法或参数。即使响应为 `ok: false`，也会被转换为 `TelegramError`。
 
+### `api.downloadFile(fileId, options?)`
+
+```ts
+downloadFile(fileId: string, options?: { signal?: AbortSignal }): Promise<DownloadedFile>
+```
+
+`bot.downloadFile` 的 API 客户端核心：解析 `getFile`、校验返回了 `file_path`，然后通过 transport 下载字节。
+
+### `DownloadedFile`
+
+```ts
+interface DownloadedFile {
+  file: File;            // getFile 返回的 Telegram File 对象
+  bytes: Uint8Array;     // 原始字节（Telegram 上限 20 MB）
+  filePath: string;      // 用于下载的 file_path
+  url: string;           // 直接下载 URL，至少一小时内有效
+  fileName: string;      // filePath 的最后一段
+  sizeBytes: number;     // bytes 的字节长度
+  savedTo?: string;      // 当 Bot.downloadFile 把文件写入磁盘时填充
+}
+```
+
+### `fetchTransport.fileUrl(filePath)` 与 `fetchTransport.download(filePath, signal?)`
+
+```ts
+fileUrl(filePath: string): string
+download(filePath: string, signal?: AbortSignal): Promise<Uint8Array>
+```
+
+`FetchTransport` 把 `/bot<token>` 基础 URL 映射为 `/file/bot<token>` 下载端点；`download` 以 GET 获取字节（大文件的 timeout 下限为 120 秒），HTTP 失败时抛出 `TelegramNetworkError`。两者都是 `Transport` 接口的可选成员，自定义 transport 可以省略 —— 此时 `downloadFile` 会以明确的校验错误失败，而不是崩溃。
+
 ### 可用的类型化参数和返回值
 
 以下类型在此发布版本中已被映射：
@@ -1492,6 +1539,27 @@ template("你好 {{ user.name }}", { user: { name: "Ayu" } });
 
 ---
 
+### `validateUpload(upload, rules)`
+
+```ts
+validateUpload(upload: UploadLike, rules: UploadRules): UploadValidationIssue[]
+```
+
+在发送前校验上传：`maxBytes`（大小上限）、`allowedMimeTypes`（精确或通配符如 `image/*`）、`allowedExtensions`（大小写不敏感，带不带前导点均可）。返回找到的全部违规 —— 空数组表示上传可接受。
+
+### `assertValidUpload(upload, rules)`
+
+规则相同，但不返回结果而是抛出 `UploadValidationError`（附带全部 `issues`）。
+
+```ts
+import { assertValidUpload } from "@xbibzlibrary/telebibz";
+
+assertValidUpload(
+  { sizeBytes: fileBytes.length, mimeType: "image/png", fileName: "logo.png" },
+  { maxBytes: 5_000_000, allowedMimeTypes: ["image/png", "image/jpeg"], allowedExtensions: [".png", ".jpg"] },
+);
+```
+
 ## 14. Testing utilities
 
 Import dari `@xbibzlibrary/telebibz/testing` atau root package.
@@ -1518,6 +1586,8 @@ const transport = new MockTransport()
   });
 ```
 
+`MockTransport` 同样实现了可选的下载成员：`download(filePath)` 把路径记录进 `downloads` 并返回 `downloadBytes`（默认为路径的 UTF-8 编码），`fileUrl(filePath)` 返回 `mock://files/<filePath>` —— 因此 `bot.downloadFile()` 无需网络即可完整测试。
+
 ### `createMockUpdate(overrides?)`
 
 ```ts

package/docs/STORAGE.id.md

@@ -0,0 +1,105 @@
+# Panduan cepat storage (Bahasa Indonesia)
+
+telebibz menyediakan interface `Storage<K, V>` generik dengan lima adapter. Core package **tanpa runtime dependency**: adapter Redis, SQL, dan Mongo menerima driver interface kecil yang sudah Anda punya, jadi Anda yang memilih driver dan versinya.
+
+Semua adapter memakai kontrak yang sama — `get` / `set` / `delete` / `has` / `clear` / `keys()` / `entries()` — ditambah **`update(key, updater, { ttlMs })`** yang menyalin penulisan per key sehingga update bersamaan ke key yang sama tidak pernah saling menimpa. TTL diatur per penulisan lewat `{ ttlMs }`.
+
+## MemoryStorage (default — tanpa konfigurasi)
+
+```ts
+import { Bot } from "@xbibzlibrary/telebibz";
+
+const bot = new Bot({ token: process.env.TELEGRAM_BOT_TOKEN! });
+// bot.session secara default adalah MemoryStorage<string, S>.
+```
+
+## JsonFileStorage (persistensi satu file, tetap tanpa dependency)
+
+```ts
+import { Bot, JsonFileStorage } from "@xbibzlibrary/telebibz";
+
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  session: new JsonFileStorage("state/sessions.json"),
+});
+```
+
+## RedisStorage (bawa client Anda sendiri)
+
+Adapter ini hanya butuh lima method callback-style yang dimiliki setiap client Redis — `node-redis` langsung cocok:
+
+```ts
+import { Bot, RedisStorage } from "@xbibzlibrary/telebibz";
+import { createClient } from "redis"; // driver dan versi pilihan Anda
+
+const redis = createClient({ url: process.env.REDIS_URL });
+await redis.connect();
+
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  session: new RedisStorage(redis, "mybot:"), // prefix untuk key Anda
+});
+// TTL per penulisan: await bot.session.set(key, value, { ttlMs: 24 * 60 * 60 * 1000 });
+// (kedaluwarsa PX Redis diterapkan otomatis.)
+```
+
+## SqlStorage (semua database SQL)
+
+Implementasikan driver lima method di atas library SQL Anda; contoh ini memakai `better-sqlite3`:
+
+```ts
+import { Bot, SqlStorage } from "@xbibzlibrary/telebibz";
+import Database from "better-sqlite3";
+
+const db = new Database("state/bot.db");
+db.exec("CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, value TEXT NOT NULL, expires_at INTEGER)");
+
+const storage = new SqlStorage({
+  async get(key) {
+    const row = db.prepare("SELECT value, expires_at FROM kv WHERE key = ?").get(key) as { value: string; expires_at: number | null } | undefined;
+    return row === undefined ? undefined : JSON.parse(row.value);
+  },
+  async set(key, value, expiresAt) {
+    db.prepare("INSERT INTO kv (key, value, expires_at) VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at")
+      .run(key, JSON.stringify(value), expiresAt ?? null);
+  },
+  async delete(key) { return db.prepare("DELETE FROM kv WHERE key = ?").run(key).changes > 0; },
+  async has(key) { return db.prepare("SELECT 1 FROM kv WHERE key = ?").get(key) !== undefined; },
+  async clear() { db.prepare("DELETE FROM kv").run(); },
+  async entries() {
+    const rows = db.prepare("SELECT key, value, expires_at FROM kv").all() as Array<{ key: string; value: string; expires_at: number | null }>;
+    return rows.map((row) => [row.key, JSON.parse(row.value), row.expiresAt ?? undefined] as [string, unknown, number | undefined]);
+  },
+});
+
+const bot = new Bot({ token: process.env.TELEGRAM_BOT_TOKEN!, session: storage });
+```
+
+## MongoStorage (bawa collection Anda sendiri)
+
+Adapter ini berbicara langsung dengan bentuk collection MongoDB standar — cukup kirim collection Anda:
+
+```ts
+import { Bot, MongoStorage } from "@xbibzlibrary/telebibz";
+import { MongoClient } from "mongodb";
+
+const client = new MongoClient(process.env.MONGODB_URL!);
+await client.connect();
+
+const bot = new Bot({
+  token: process.env.TELEGRAM_BOT_TOKEN!,
+  session: new MongoStorage(client.db("mybot").collection("sessions")),
+});
+```
+
+## Memilih
+
+| Adapter | Pakai saat | Persistensi | Dependency tambahan |
+|---|---|---|---|
+| `MemoryStorage` | bot satu proses, test | selama proses hidup | tidak ada |
+| `JsonFileStorage` | bot kecil, deploy sederhana | file di disk | tidak ada |
+| `RedisStorage` | multi-instance, state bersama | Redis | client Redis Anda |
+| `SqlStorage` | aplikasi berbasis SQL | semua database SQL | driver SQL Anda |
+| `MongoStorage` | stack Mongo yang sudah ada | MongoDB | driver Mongo Anda |
+
+Signature API lengkap: [API.id.md](API.id.md). English: [STORAGE.md](STORAGE.md) · 简体中文: [STORAGE.zh-CN.md](STORAGE.zh-CN.md).