@xbibzlibrary/telebibz 0.1.19 → 0.3.1

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

@@ -1,12 +1,57 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Router = void 0;
+exports.Router = exports.UPDATE_FILTER_TYPES = void 0;
 const compose_js_1 = require("../middleware/compose.js");
 function testRegExp(expression, value) {
     expression.lastIndex = 0;
     return expression.test(value);
 }
+/** Update types accepted by `on()` filters, mirroring the Telegram `Update` object. */
+exports.UPDATE_FILTER_TYPES = [
+    "message",
+    "edited_message",
+    "channel_post",
+    "edited_channel_post",
+    "business_connection",
+    "business_message",
+    "edited_business_message",
+    "deleted_business_messages",
+    "guest_message",
+    "message_reaction",
+    "message_reaction_count",
+    "inline_query",
+    "chosen_inline_result",
+    "callback_query",
+    "shipping_query",
+    "pre_checkout_query",
+    "purchased_paid_media",
+    "poll",
+    "poll_answer",
+    "my_chat_member",
+    "chat_member",
+    "chat_join_request",
+    "chat_boost",
+    "removed_chat_boost",
+];
+const updateFilterTypes = new Set(exports.UPDATE_FILTER_TYPES);
+function assertValidFilter(filter) {
+    const type = filter.split(":", 1)[0] ?? "";
+    if (!updateFilterTypes.has(type))
+        throw new TypeError(`Unknown update type in filter "${filter}". Expected one of: ${exports.UPDATE_FILTER_TYPES.join(", ")}.`);
+}
+function matchesFilter(ctx, filter) {
+    const separator = filter.indexOf(":");
+    const type = separator < 0 ? filter : filter.slice(0, separator);
+    const field = separator < 0 ? undefined : filter.slice(separator + 1);
+    const payload = ctx.update[type];
+    if (payload === undefined || payload === null)
+        return false;
+    if (field === undefined || field === "")
+        return true;
+    return typeof payload === "object" && payload[field] !== undefined;
+}
 class Router {
+    middlewares = [];
     routes = [];
     sequence = 0;
     matchMode;
@@ -16,7 +61,7 @@ class Router {
     use(...middleware) {
         if (middleware.length === 0)
             return this;
-        this.routes.push({ priority: -1_000_000 + this.sequence++, matcher: () => true, middleware });
+        this.middlewares.push(...middleware);
         return this;
     }
     route(matcher, ...middleware) {
@@ -27,29 +72,61 @@ class Router {
     }
     command(name, ...middleware) {
         return this.route(async (ctx) => {
-            const text = ctx.message?.text;
+            const text = ctx.message?.text ?? ctx.message?.caption;
             if (!text?.startsWith("/"))
                 return false;
-            const command = text.slice(1).split(/[\s@]/, 1)[0] ?? "";
-            return typeof name === "string"
+            const parts = text.slice(1).split(/\s+/);
+            const commandWithBot = parts[0] ?? "";
+            const [command, botUsername] = commandWithBot.split("@");
+            if (botUsername && ctx.me?.username && botUsername.toLowerCase() !== ctx.me.username.toLowerCase()) {
+                return false;
+            }
+            const matched = typeof name === "string"
                 ? command === name.replace(/^\//, "")
-                : testRegExp(name, command);
+                : testRegExp(name, command ?? "");
+            if (matched) {
+                ctx.args = parts.slice(1);
+            }
+            return matched;
         }, ...middleware);
     }
     text(value, ...middleware) {
-        return this.route((ctx) => ctx.message?.text === value, ...middleware);
+        return this.route((ctx) => {
+            const text = ctx.message?.text ?? ctx.message?.caption;
+            return text === value;
+        }, ...middleware);
     }
     regex(expression, ...middleware) {
-        return this.route((ctx) => testRegExp(expression, ctx.message?.text ?? ""), ...middleware);
+        return this.route((ctx) => {
+            const text = ctx.message?.text ?? ctx.message?.caption ?? "";
+            const match = text.match(expression);
+            if (match) {
+                ctx.match = match;
+                return true;
+            }
+            return false;
+        }, ...middleware);
     }
     callback(pattern, ...middleware) {
         return this.route((ctx) => {
             const data = ctx.callbackQuery?.data ?? "";
-            return typeof pattern === "string"
-                ? pattern.endsWith("*")
-                    ? data.startsWith(pattern.slice(0, -1))
-                    : data === pattern
-                : testRegExp(pattern, data);
+            if (typeof pattern === "string") {
+                if (pattern.endsWith("*")) {
+                    const prefix = pattern.slice(0, -1);
+                    if (data.startsWith(prefix)) {
+                        ctx.params = { ...ctx.params, wildcard: data.slice(prefix.length) };
+                        return true;
+                    }
+                    return false;
+                }
+                return data === pattern;
+            }
+            const match = data.match(pattern);
+            if (match) {
+                ctx.match = match;
+                return true;
+            }
+            return false;
         }, ...middleware);
     }
     chat(chatId, ...middleware) {
@@ -58,6 +135,19 @@ class Router {
             return id !== undefined && (id === chatId || String(id) === String(chatId));
         }, ...middleware);
     }
+    /**
+     * Registers handlers for update types, with optional payload narrowing:
+     * `on("message")`, `on("message:photo")`, `on("callback_query:data")`,
+     * or an array such as `["message:text", "callback_query:data"]`.
+     */
+    on(filter, ...middleware) {
+        const filters = (Array.isArray(filter) ? filter : [filter]).map((value) => String(value));
+        if (filters.length === 0)
+            throw new Error("At least one update filter is required.");
+        for (const value of filters)
+            assertValidFilter(value);
+        return this.route((ctx) => filters.some((value) => matchesFilter(ctx, value)), ...middleware);
+    }
     predicate(matcher, ...middleware) {
         return this.route(matcher, ...middleware);
     }
@@ -67,18 +157,30 @@ class Router {
         });
     }
     async handle(ctx, terminal) {
-        const ordered = [...this.routes].sort((left, right) => left.priority - right.priority);
-        let matched = false;
-        for (const route of ordered) {
-            if (!(await route.matcher(ctx)))
-                continue;
-            matched = true;
-            await (0, compose_js_1.compose)(route.middleware)(ctx);
-            if (this.matchMode === "first")
-                break;
+        const routeDispatcher = async (currentCtx, next) => {
+            const ordered = [...this.routes].sort((left, right) => left.priority - right.priority);
+            let matched = false;
+            for (const route of ordered) {
+                if (!(await route.matcher(currentCtx)))
+                    continue;
+                matched = true;
+                await (0, compose_js_1.compose)(route.middleware)(currentCtx);
+                if (this.matchMode === "first")
+                    break;
+            }
+            if (!matched) {
+                if (terminal)
+                    await terminal();
+                else
+                    await next();
+            }
+        };
+        if (this.middlewares.length === 0) {
+            await routeDispatcher(ctx, async () => { });
+        }
+        else {
+            await (0, compose_js_1.compose)([...this.middlewares, routeDispatcher])(ctx);
         }
-        if (!matched)
-            await terminal?.();
     }
 }
 exports.Router = Router;

package/dist-cjs/src/state/forms.js

@@ -3,32 +3,35 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validators = exports.Form = void 0;
 class Form {
     fields = new Map();
-    values = {};
     field(definition) { this.fields.set(definition.name, definition); return this; }
-    async parse(input) { const issues = []; for (const [name, field] of this.fields) {
-        const raw = input[name];
-        if ((raw === undefined || raw === null || raw === "") && field.required) {
-            issues.push({ path: name, message: "Field is required", code: "required" });
-            continue;
+    async parse(input) {
+        const issues = [];
+        const values = {};
+        for (const [name, field] of this.fields) {
+            const raw = input[name];
+            if ((raw === undefined || raw === null || raw === "") && field.required) {
+                issues.push({ path: name, message: "Field is required", code: "required" });
+                continue;
+            }
+            if (raw === undefined || raw === null || raw === "")
+                continue;
+            try {
+                let value = field.parse(raw);
+                if (field.transform)
+                    value = await field.transform(value);
+                const error = await field.validate?.(value);
+                if (error)
+                    issues.push({ path: name, message: error, code: "invalid" });
+                else
+                    values[name] = value;
+            }
+            catch (error) {
+                issues.push({ path: name, message: error instanceof Error ? error.message : "Invalid value", code: "parse" });
+            }
         }
-        if (raw === undefined || raw === null || raw === "")
-            continue;
-        try {
-            let value = field.parse(raw);
-            if (field.transform)
-                value = await field.transform(value);
-            const error = await field.validate?.(value);
-            if (error)
-                issues.push({ path: name, message: error, code: "invalid" });
-            else
-                this.values[name] = value;
-        }
-        catch (error) {
-            issues.push({ path: name, message: error instanceof Error ? error.message : "Invalid value", code: "parse" });
-        }
-    } return issues.length ? { success: false, issues } : { success: true, data: this.values }; }
-    reset() { for (const key of Object.keys(this.values))
-        delete this.values[key]; }
+        return issues.length ? { success: false, issues } : { success: true, data: values };
+    }
+    reset() { }
 }
 exports.Form = Form;
 exports.validators = { string: (value) => { if (typeof value !== "string")

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

@@ -23,6 +23,20 @@ class MemoryStorage {
         }
         return entry.value;
     }
+    /**
+     * Reads the raw entry including expiry metadata. Intended for storage adapters
+     * (such as `JsonFileStorage`) that need to persist TTL information across restarts.
+     */
+    async readEntry(key) {
+        const entry = this.valuesMap.get(key);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt !== undefined && entry.expiresAt <= Date.now()) {
+            this.valuesMap.delete(key);
+            return undefined;
+        }
+        return entry.expiresAt === undefined ? { value: entry.value } : { value: entry.value, expiresAt: entry.expiresAt };
+    }
     async set(key, value, options = {}) {
         const expiresAt = expiration(options.ttlMs);
         this.valuesMap.set(key, expiresAt === undefined ? { value } : { value, expiresAt });
@@ -84,8 +98,12 @@ class JsonFileStorage {
         await this.ready;
         this.writeChain = this.writeChain.then(async () => {
             const output = {};
-            for await (const [key, value] of this.memory.entries())
-                output[key] = { value };
+            for await (const key of this.memory.keys()) {
+                const entry = await this.memory.readEntry(key);
+                if (entry === undefined)
+                    continue;
+                output[key] = entry.expiresAt === undefined ? { value: entry.value } : { value: entry.value, expiresAt: entry.expiresAt };
+            }
             await (0, promises_1.mkdir)((0, node_path_1.dirname)(this.filePath), { recursive: true });
             const temporary = `${this.filePath}.${process.pid}.tmp`;
             await (0, promises_1.writeFile)(temporary, JSON.stringify(output, null, 2), "utf8");

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

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Minimal concurrency primitives with zero dependencies.
+ *
+ * These helpers never add proactive delays: they only cap how many async tasks
+ * run at the same time. `Infinity` means fully parallel execution.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Limiter = void 0;
+exports.validateConcurrency = validateConcurrency;
+exports.mapWithConcurrency = mapWithConcurrency;
+function validateConcurrency(value, label = "concurrency") {
+    if (value === Infinity)
+        return;
+    if (!Number.isInteger(value) || value < 1)
+        throw new RangeError(`${label} must be a positive integer or Infinity`);
+}
+/** Promise semaphore: runs tasks immediately while a slot is free, queues the rest in FIFO order. */
+class Limiter {
+    limit;
+    active = 0;
+    waiters = [];
+    constructor(limit) {
+        this.limit = limit;
+        validateConcurrency(limit);
+    }
+    /** Number of tasks currently running. */
+    get activeCount() { return this.active; }
+    /** Number of tasks waiting for a free slot. */
+    get queuedCount() { return this.waiters.length; }
+    async run(task) {
+        if (this.active >= this.limit)
+            await new Promise((resolve) => { this.waiters.push(resolve); });
+        this.active += 1;
+        try {
+            return await task();
+        }
+        finally {
+            this.active -= 1;
+            this.waiters.shift()?.();
+        }
+    }
+}
+exports.Limiter = Limiter;
+/**
+ * Maps items through an async worker with a concurrency cap.
+ * Results keep the input order; `Infinity` runs everything in parallel.
+ */
+async function mapWithConcurrency(items, limit, worker) {
+    validateConcurrency(limit);
+    const results = new Array(items.length);
+    const limiter = new Limiter(limit);
+    await Promise.all(items.map((item, index) => limiter.run(async () => {
+        results[index] = await worker(item, index);
+    })));
+    return results;
+}

package/dist-cjs/src/webhook/handler.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createWebhookHandler = createWebhookHandler;
+exports.webhookCallback = webhookCallback;
 const node_crypto_1 = require("node:crypto");
 function createWebhookHandler(bot, options = {}) {
     const maxBodyBytes = options.maxBodyBytes ?? 1_048_576;
@@ -31,6 +32,91 @@ function createWebhookHandler(bot, options = {}) {
         }
     };
 }
+function webhookCallback(bot, _framework = "express", options = {}) {
+    const maxBodyBytes = options.maxBodyBytes ?? 1_048_576;
+    return async (req, res) => {
+        const rawReq = req;
+        const rawRes = res;
+        const sendResponse = (status, message) => {
+            if (rawRes && typeof rawRes.writeHead === "function" && typeof rawRes.end === "function") {
+                rawRes.writeHead(status, { "Content-Type": "text/plain" });
+                rawRes.end(message);
+                return;
+            }
+            const expressLike = rawRes;
+            if (typeof expressLike?.status === "function" && typeof expressLike.send === "function") {
+                expressLike.status(status).send(message);
+                return;
+            }
+            const koaLike = rawRes;
+            if (koaLike !== undefined) {
+                koaLike.status = status;
+                koaLike.body = message;
+            }
+        };
+        if (rawReq.method !== "POST") {
+            sendResponse(405, "Method Not Allowed");
+            return;
+        }
+        if (options.secretToken) {
+            if (!secureEqual(readHeader(rawReq, "x-telegram-bot-api-secret-token"), options.secretToken)) {
+                sendResponse(401, "Unauthorized");
+                return;
+            }
+        }
+        try {
+            let update;
+            if (typeof rawReq.arrayBuffer === "function") {
+                // Web-standard Request objects (e.g. Deno, Bun, WinterCG runtimes, or
+                // a converted fetch Request) expose the body through arrayBuffer().
+                // Checked before `body` because a Request's `body` is a ReadableStream.
+                const raw = await rawReq.arrayBuffer();
+                if (raw.byteLength > maxBodyBytes) {
+                    sendResponse(413, "Payload Too Large");
+                    return;
+                }
+                update = JSON.parse(new TextDecoder().decode(raw));
+            }
+            else if (rawReq.body && typeof rawReq.body === "object") {
+                update = rawReq.body;
+            }
+            else {
+                const chunks = [];
+                let totalBytes = 0;
+                for await (const chunk of rawReq) {
+                    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+                    totalBytes += buffer.length;
+                    if (totalBytes > maxBodyBytes) {
+                        sendResponse(413, "Payload Too Large");
+                        return;
+                    }
+                    chunks.push(buffer);
+                }
+                const raw = Buffer.concat(chunks).toString("utf8");
+                update = JSON.parse(raw);
+            }
+            if (!Number.isInteger(update?.update_id)) {
+                sendResponse(400, "Bad Request");
+                return;
+            }
+            await bot.handleUpdate(update);
+            sendResponse(200, "OK");
+        }
+        catch (error) {
+            await options.onError?.(error);
+            sendResponse(500, "Internal Server Error");
+        }
+    };
+}
+function readHeader(req, name) {
+    const headers = req.headers;
+    if (!headers || typeof headers !== "object")
+        return "";
+    if (typeof headers.get === "function")
+        return headers.get(name) ?? "";
+    const value = headers[name];
+    return Array.isArray(value) ? value[0] ?? "" : value ?? "";
+}
 function secureEqual(left, right) {
     const leftBuffer = Buffer.from(left, "utf8");
     const rightBuffer = Buffer.from(right, "utf8");

package/docs/API.id.md

@@ -68,11 +68,13 @@ type BotStatus =
 | `transportOptions` | `Omit<FetchTransportOptions, "baseUrl">` | `{}` | Timeout, retry, backoff, jitter, headers, dan fetch implementation. |
 | `session` | `Storage<string, S>` | storage baru | Penyimpanan session berdasarkan kunci chat/user; dapat memakai adapter persistent. |
 | `services` | `Record<string, unknown>` | `{}` | Dependency/service yang tersedia melalui `ctx.services`. |
+| `branding` | `boolean` | `true` | Pengalaman startup terminal: efek ketik, glass progress bar, banner rainbow animasi `Tele Bibz`, dan baris update yang mudah dibaca. Hanya dirender pada TTY interaktif. |
 | `polling.timeout` | `number` | `30` | Long-poll timeout dalam detik untuk `getUpdates`. |
 | `polling.limit` | `number` | `100` | Jumlah maksimum update per request polling. |
 | `polling.allowedUpdates` | `string[]` | `[]` | Filter update Telegram. |
 | `polling.retryDelayMs` | `number` | `500` | Delay awal ketika polling gagal. |
 | `polling.maxRetryDelayMs` | `number` | `30000` | Batas maksimum delay reconnect. |
+| `updates.concurrency` | `number` | `Infinity` | Batas jumlah update yang diproses bersamaan. Update selalu berjalan paralel antar chat dan tetap berurutan di dalam satu chat, sehingga burst 1000+ pesan tertangani sekaligus. |
 
 ### Konstruktor `Bot`
 
@@ -140,6 +142,30 @@ onRegex(expression: RegExp, handler: Middleware<Context<S>>): this
 
 Menangani message text menggunakan `RegExp`. Parameter route tidak diekstrak otomatis ke `ctx.params`; gunakan predicate atau middleware custom jika memerlukan ekstraksi.
 
+### `bot.on(filter, handler)`
+
+```ts
+on(filter: UpdateFilter | UpdateFilter[], handler: Middleware<Context<S>>): this
+```
+
+Mendaftarkan handler untuk tipe update, opsional dipersempit dengan field payload. Contoh: `"message"`, `"message:text"`, `"message:photo"`, `"edited_message"`, `"channel_post"`, `"callback_query"`, `"callback_query:data"`, `"inline_query"`, `"chat_member"`, `"message_reaction"`, atau array seperti `["message:text", "callback_query:data"]`. Tipe update tidak valid melempar `TypeError` saat registrasi.
+
+### `bot.hears(trigger, handler)`
+
+```ts
+hears(trigger: string | RegExp, handler: Middleware<Context<S>>): this
+```
+
+Menangani message text yang sama persis (string) atau yang cocok dengan `RegExp`.
+
+### `bot.catch(handler)`
+
+```ts
+catch(handler: (error: unknown, ctx: Context<S>) => void | Promise<void>): this
+```
+
+Mendaftarkan error boundary untuk handler update. Jika dipasang, kegagalan handler dicatat, dipancarkan sebagai `update:error`/`bot:error`, dan diteruskan ke handler ini alih-alih menolak `handleUpdate()` — webhook menjawab `200` dan polling berlanjut. Tanpa boundary, error dilempar ulang.
+
 ### `bot.usePlugin(plugin)`
 
 ```ts
@@ -176,7 +202,7 @@ launch(options?: {
 }): Promise<void>
 ```
 
-Menjalankan bot dalam mode polling. Saat mulai, lifecycle berpindah melalui `starting` lalu `running`, kemudian loop `getUpdates()` memproses setiap update secara berurutan. Kegagalan polling memancarkan `polling:reconnect` dan menggunakan backoff eksponensial.
+Menjalankan bot dalam mode polling. Saat mulai, lifecycle berpindah melalui `starting` lalu `running`, kemudian loop `getUpdates()` memproses setiap batch update secara konkuren: update dari chat berbeda berjalan paralel, sedangkan update dari chat yang sama menjaga urutan kedatangannya. Kegagalan polling memancarkan `polling:reconnect` dan menggunakan backoff eksponensial.
 
 Mode selain `"polling"` melempar error dan menyarankan penggunaan `createWebhookHandler()` untuk webhook.
 
@@ -253,8 +279,54 @@ handleUpdate(update: Update): Promise<void>
 
 Memproses satu update secara manual. Method menentukan kunci session dari `chat.id` dan `from.id`, membuat `Context`, memancarkan event `update` dan `message`, menjalankan middleware lalu router, dan menyimpan session setelah pipeline selesai.
 
+Update dari chat berbeda diproses paralel; update dari chat yang sama diserialisasi sesuai urutan kedatangan, sehingga session, wizard, dan conversation tidak pernah saling tumpang tindih dan penulisan session tidak pernah hilang. Burst update konkuren hanya memicu satu inisialisasi `getMe`.
+
 Error pipeline mengubah status bot menjadi `error`, memancarkan `bot:error`, lalu dilempar kembali.
 
+### `bot.handleUpdates(updates)`
+
+```ts
+handleUpdates(updates: readonly Update[]): Promise<void>
+```
+
+Menangani satu batch update sekaligus: setiap chat dalam batch langsung diproses — paralel antar chat, berurutan per chat — sehingga burst 1000 pesan tidak pernah terhambat oleh satu handler yang lambat. Kegagalan handler individual dicatat ke log, dipancarkan sebagai `update:error`, dan diteruskan ke error boundary `catch()`; kegagalan tersebut tidak pernah menolak promise ini. Loop polling memakai method ini untuk setiap batch `getUpdates`.
+
+### `bot.broadcast(chatIds, send, options?)`
+
+```ts
+broadcast(
+  chatIds: readonly ChatId[],
+  send: (chatId: ChatId) => Promise<unknown>,
+  options?: BroadcastOptions,
+): Promise<BroadcastReport>
+```
+
+Mengirim ke banyak chat secara paralel — dibuat untuk broadcast ke 1000+ user. Tidak ada cooldown proaktif: semua chat langsung dicoba sekaligus (sampai `options.concurrency`, default `Infinity`). Ketika Telegram menjawab 429, pengiriman otomatis diulang setelah tepat delay `retry_after` yang diperintahkan Telegram (maksimal `options.maxAttempts`, default `10`), sehingga burst tetap terkirim lengkap, bukan gagal. Error yang tidak bisa di-retry (misalnya chat yang tidak bisa dihubungi bot) dicatat per chat pada laporan yang dikembalikan.
+
+```ts
+const report = await bot.broadcast(
+  subscriberIds,
+  (chatId) => bot.api.methods.sendMessage({ chat_id: chatId, text: "Newsletter #42" }),
+  { onProgress: (progress) => console.log(`${progress.delivered}/${progress.total} terkirim`) },
+);
+console.log(`Terkirim ${report.delivered} dari ${report.total} dalam ${report.durationMs}ms`);
+for (const failure of report.failures) console.warn(`Gagal: ${failure.chatId} — ${failure.error}`);
+```
+
+#### `BroadcastOptions` dan `BroadcastReport`
+
+| Properti | Tipe | Default | Deskripsi |
+|---|---|---:|---|
+| `BroadcastOptions.concurrency` | `number` | `Infinity` | Berapa chat dikirimi pesan secara bersamaan. |
+| `BroadcastOptions.maxAttempts` | `number` | `10` | Percobaan per chat ketika Telegram menjawab 429. |
+| `BroadcastOptions.onProgress` | `(progress: BroadcastProgress) => void` | — | Dipanggil setelah setiap chat selesai. |
+| `BroadcastOptions.signal` | `AbortSignal` | — | Membatalkan pengiriman tertunda; pesan yang sudah terkirim tetap terkirim. |
+| `BroadcastReport.total` | `number` | — | Jumlah chat dalam sesi broadcast. |
+| `BroadcastReport.delivered` | `number` | — | Chat yang menerima pesan. |
+| `BroadcastReport.failed` | `number` | — | Chat yang tidak menerima. |
+| `BroadcastReport.durationMs` | `number` | — | Durasi total sesi broadcast. |
+| `BroadcastReport.failures` | `BroadcastFailure[]` | — | Catatan per chat `{ chatId, attempts, error, errorKind }`. |
+
 ### Contoh bot minimal
 
 ```ts
@@ -391,6 +463,7 @@ interface Transport {
 | `backoffMs` | `250` | Delay exponential awal. |
 | `maxBackoffMs` | `8000` | Batas delay transport. |
 | `jitter` | `0.2` | Variasi acak ±20% dari exponential delay. |
+| `floodGate` | `true` | Ketika Telegram menjawab 429, permintaan BARU ditunda sampai jendela `retry_after` yang diperintahkan Telegram berlalu. Bukan cooldown proaktif — penundaan satu-satunya hanyalah yang diminta Telegram sendiri. |
 | `headers` | `{}` | Header tambahan. |
 
 ### `new FetchTransport(options?)`
@@ -633,6 +706,22 @@ new Context<S>(options: ContextOptions<S>): Context<S>
 | `send` | `send(text, extra?): Promise<Message>` | Mengirim message ke chat update tanpa reply reference. |
 | `edit` | `edit(text, extra?): Promise<Message \| true>` | Mengedit message update menggunakan `editMessageText`. |
 | `delete` | `delete(): Promise<true>` | Menghapus message update. |
+| `replyWithHTML` | `replyWithHTML(text, extra?): Promise<Message>` | Membalas dengan `parse_mode: "HTML"`. |
+| `replyWithMarkdown` | `replyWithMarkdown(text, extra?): Promise<Message>` | Membalas dengan `parse_mode: "MarkdownV2"`. |
+| `replyWithPhoto` | `replyWithPhoto(photo, extra?): Promise<Message>` | Mengirim `sendPhoto` dengan quote-reply otomatis. |
+| `replyWithDocument` | `replyWithDocument(document, extra?): Promise<Message>` | Mengirim `sendDocument` dengan quote-reply otomatis. |
+| `replyWithAudio` | `replyWithAudio(audio, extra?): Promise<Message>` | Mengirim `sendAudio` dengan quote-reply otomatis. |
+| `replyWithVideo` | `replyWithVideo(video, extra?): Promise<Message>` | Mengirim `sendVideo` dengan quote-reply otomatis. |
+| `replyWithVoice` | `replyWithVoice(voice, extra?): Promise<Message>` | Mengirim `sendVoice` dengan quote-reply otomatis. |
+| `replyWithAnimation` | `replyWithAnimation(animation, extra?): Promise<Message>` | Mengirim `sendAnimation` dengan quote-reply otomatis. |
+| `replyWithVideoNote` | `replyWithVideoNote(videoNote, extra?): Promise<Message>` | Mengirim `sendVideoNote` dengan quote-reply otomatis. |
+| `replyWithSticker` | `replyWithSticker(sticker, extra?): Promise<Message>` | Mengirim `sendSticker` dengan quote-reply otomatis. |
+| `replyWithMediaGroup` | `replyWithMediaGroup(media, extra?): Promise<Message[]>` | Mengirim album via `sendMediaGroup` dengan quote-reply otomatis. |
+| `replyWithLocation` | `replyWithLocation(latitude, longitude, extra?): Promise<Message>` | Mengirim `sendLocation` dengan quote-reply otomatis. |
+| `replyWithVenue` | `replyWithVenue(latitude, longitude, title, address, extra?): Promise<Message>` | Mengirim `sendVenue` dengan quote-reply otomatis. |
+| `replyWithContact` | `replyWithContact(phoneNumber, firstName, extra?): Promise<Message>` | Mengirim `sendContact` dengan quote-reply otomatis. |
+| `replyWithPoll` | `replyWithPoll(question, options, extra?): Promise<Message>` | Mengirim `sendPoll` dengan quote-reply otomatis. |
+| `replyWithDice` | `replyWithDice(emoji?, extra?): Promise<Message>` | Mengirim `sendDice` dengan quote-reply otomatis. |
 | `copy` | `copy(fromChatId, messageId, extra?): Promise<unknown>` | Memanggil `copyMessage` ke chat context. |
 | `forward` | `forward(fromChatId, messageId, extra?): Promise<Message>` | Memanggil `forwardMessage` ke chat context. |
 | `pin` | `pin(messageId?, extra?): Promise<true>` | Memanggil `pinChatMessage`, default message id dari context. |
@@ -645,7 +734,7 @@ new Context<S>(options: ContextOptions<S>): Context<S>
 | `getFile` | `getFile(fileId): Promise<unknown>` | Mengambil file berdasarkan id. |
 | `withReplyMarkup` | `withReplyMarkup(markup): this` | Menyimpan markup di `ctx.state.reply_markup` dan mengembalikan context. Metode ini tidak otomatis mengirim message. |
 
-`reply`, `send`, `getChat`, dan beberapa helper lain melempar error ketika update tidak memiliki chat yang diperlukan. `edit` dan `delete` membutuhkan chat serta message.
+Semua pengirim `replyWith*` menerima parameter native Telegram sebagai `extra` dan otomatis me-quote message yang masuk. `reply_parameters` pada `extra` digabung dengan `message_id` otomatis, bukan menggantikannya. `reply`, `send`, `getChat`, dan beberapa helper lain melempar error ketika update tidak memiliki chat yang diperlukan. `edit` dan `delete` membutuhkan chat serta message.
 
 ---
 
@@ -956,6 +1045,20 @@ new Scheduler(): Scheduler
 
 Format cron penuh tidak didukung oleh built-in scheduler. Ekspresi selain `*/N` melempar `Error`.
 
+### `Limiter` dan `mapWithConcurrency`
+
+```ts
+new Limiter(limit: number): Limiter
+
+mapWithConcurrency<T, R>(
+  items: readonly T[],
+  limit: number,
+  worker: (item: T, index: number) => Promise<R>,
+): Promise<R[]>
+```
+
+`Limiter` adalah semaphore berbasis promise: task langsung berjalan selama ada slot kosong dan mengantre FIFO setelahnya. `limit` menerima bilangan bulat positif atau `Infinity` (sepenuhnya paralel — default library). `mapWithConcurrency` memetakan item melalui async worker dengan batas yang sama sambil menjaga urutan hasil. Primitif ini tidak menambahkan delay apa pun — hanya membatasi jumlah task yang berjalan bersamaan. `Limiter` mengekspos `activeCount` dan `queuedCount` untuk observability.
+
 ## 9. Plugin dan services
 
 ### `Plugin<Context>`
@@ -1263,7 +1366,20 @@ new Menu(id: string): Menu
 
 ## 12. Logging Terminal
 
-This package starts directly after Telegram API connectivity is established. The terminal prints a boxed telebibz attribution, an animated startup status when attached to a TTY, and structured colorful logs for lifecycle, API, polling, webhook, and update events. Set logger format to `json` for machine ingestion.
+Saat stdout adalah TTY interaktif, setiap `bot.start()` / `bot.launch()` memainkan urutan startup: efek ketik `Installing Dependencies......`, glass progress bar dengan kilau menyapu, dan banner ASCII rainbow animasi `Tele Bibz` (font figlet `Speed`) yang terus mengalir sampai bot terhubung, lalu diam dengan `✓ Connected as @<username>`.
+
+Setiap update yang ditangani bot dicatat dalam baris yang mudah dibaca:
+
+```text
+[ => ] Message From 123456789 John Doe 29/08/2026 15:04:05
+        ↳ Text: /start
+[ => ] Callback From 123456789 John Doe 29/08/2026 15:04:07
+        ↳ Data: menu:open
+```
+
+Teks pesan/command dibatasi 50 karakter; data tombol callback ditampilkan penuh. Error dicetak merah lengkap dengan stack. Nonaktifkan dengan `branding: false` pada `Bot`, atau set `logger.format: "json"` untuk log terstruktur — pada mode itu update masuk dikeluarkan sebagai entry `update.received`. Stdout non-interaktif (pipe, Docker, CI) otomatis fallback ke teks polos tanpa animasi.
+
+Helper branding tambahan yang diekspor untuk aplikasi: `runStartupSequence()`, `startTeleBibzBanner()`, `printTeleBibzBanner()`, `paintRainbow()`, dan `printStatusLine()`.
 
 ## 13. Utilitas Teks
 
@@ -1691,7 +1807,7 @@ Package memvendorkan declaration Telegram berlisensi MIT dan mengeksposnya sebag
 
 ## 19. Kompatibilitas dan batasan yang perlu diketahui
 
-Perpustakaan menargetkan Node.js `>=20`, menggunakan ESM sebagai module utama, serta menyediakan build CommonJS. Webhook membutuhkan runtime yang menyediakan Web `Request`, `Response`, `Headers`, `FormData`, `Blob`, dan `AbortController`; Node.js modern menyediakannya secara native.
+Perpustakaan menargetkan Node.js `>=22`, menggunakan ESM sebagai module utama, serta menyediakan build CommonJS. Webhook membutuhkan runtime yang menyediakan Web `Request`, `Response`, `Headers`, `FormData`, `Blob`, dan `AbortController`; Node.js modern menyediakannya secara native.
 
 Daftar method yang dihasilkan API dan peta method API bukanlah hal yang sama. `TelegramMethodName` mencakup 184 nama runtime, tetapi `TelegramMethodMap` hanya memiliki parameter/hasil yang bertipe khusus untuk subset yang tercantum pada bagian API client. Untuk method lain, gunakan `api.raw()` atau tambahkan deklarasi tipe di sisi aplikasi.