[๐Ÿ‡ฌ๐Ÿ‡ง **English**](README.md) ยท [๐Ÿ‡ฎ **Indonesia**](README.id.md)
telebibz โ€” Telegram Bot Library

**The easiest Telegram bot library for Node.js โ€” full feature set on par with grammY.**
A standalone recode of [grammY](https://grammy.dev)'s elegant architecture, with production dependencies that are *actually used*, and an Indonesia-first community.
[![npm version](https://img.shields.io/npm/v/@xbibzlibrary/telebibz?style=for-the-badge&logo=npm&logoColor=white&color=CB3837&label=telebibz)](https://www.npmjs.com/package/@xbibzlibrary/telebibz) [![downloads](https://img.shields.io/npm/dm/@xbibzlibrary/telebibz?style=for-the-badge&logo=npm&logoColor=white&color=green&label=downloads%2Fmonth)](https://www.npmjs.com/package/@xbibzlibrary/telebibz) [![node](https://img.shields.io/node/v/@xbibzlibrary/telebibz?style=for-the-badge&logo=node.js&logoColor=white&color=339933&label=node)](https://nodejs.org) [![tests](https://img.shields.io/badge/tests-30%2F30%20passing-brightgreen?style=for-the-badge&logo=checkmarx&logoColor=white)](#-testing--live-proof) [![size](https://img.shields.io/badge/code-1.7k%20lines-orange?style=for-the-badge&logo=codeigniter&logoColor=white)](#-analytics--statistics) [![license](https://img.shields.io/npm/l/@xbibzlibrary/telebibz?style=for-the-badge&color=blue)](LICENSE) [![views](https://komarev.com/ghpvc/?username=XbibzOfficial777&repo=telebibz&style=for-the-badge&color=blueviolet&label=repo+views)](https://github.com/XbibzOfficial777/telebibz)
`//โ€”Xbibz Officialโ€”//`
--- ## ๐Ÿ“‘ Table of Contents | | | | |---|---|---| | โšก [Why telebibz?](#why) | ๐Ÿ“Š [Feature matrix vs grammY](#matrix) | ๐Ÿ“ฅ [Installation & requirements](#install) | | ๐Ÿš€ [Quick start](#quickstart) | ๐Ÿง  [How it works (architecture)](#architecture) | ๐Ÿ“– [Full documentation](#docs) | | ๐ŸŽ›๏ธ [Handlers & filters](#handlers) | ๐Ÿ’ฌ [Context shortcuts](#context) | ๐Ÿ”˜ [Keyboards & buttons](#keyboards) | | ๏ธ [Interactive menus](#menus) | ๐Ÿง™ [Wizard (forms + buttons + edit/delete)](#wizard) | โ“ [Inline mode](#inline) | | ๐Ÿ“ฃ [Broadcast](#broadcast) | ๐Ÿ“Ž [Files & media](#files) | ๐Ÿ›ก๏ธ [Reliability & rate limiting](#ratelimit) | | ๐Ÿ—ƒ๏ธ [Sessions](#sessions) | ๐Ÿ‡ฎ๐Ÿ‡ฉ [Human-readable errors](#errors) | ๐Ÿ•ธ๏ธ [Webhooks & serverless](#webhook) | | ๐Ÿ”Œ [Proxy transport](#proxy) | ๐Ÿงช [Transformers](#transformers) | ๐Ÿ“ˆ [Analytics & statistics](#analytics) | | ๐Ÿงฉ [Examples](#examples) | ๐Ÿ”ฌ [Testing](#testing) | ๐Ÿ“‚ [Repo structure](#structure) | | ๐Ÿ• [Changelog](#changelog) | ๐Ÿ“„ [License](#license) | | ## โšก Why telebibz? > [!TIP] > **One principle:** every feature that needs a plugin in grammY is **built in** here โ€” > wizard, menus, rate limiting, broadcast, file download โ€” and polling that *never dies* on 409. - ๐Ÿง  **The grammY API you already know** โ€” `bot.cmd()`, `bot.hears()`, `ctx.reply()`, middleware, transformers - ๐Ÿง™ **Built-in Wizard v3.1** โ€” question-and-answer forms with **choice buttons** (reply/inline) and **edit/delete** message modes - ๐Ÿ›ก๏ธ **Bulletproof** โ€” 429 auto-retry, throttler, per-user limiter, polling auto-retry on 409 conflict - ๐Ÿ‡ฎ๐Ÿ‡ฉ **Human-readable errors** โ€” every Telegram error is translated into a plain-language suggestion - ๐Ÿ”Œ **Proxy API for any method** โ€” `api.anyMethod({...})` works automatically, even for methods not released yet - ๐Ÿชถ **Light & honest** โ€” 4 dependencies, all genuinely used and tested ## ๐Ÿ“Š Feature Matrix โ€” grammY parity | Feature | grammY | telebibz | |---|:---:|:---:| | Proxy API for **any method** (auto-generated) | โœ… | โœ… | | ~60 typed shortcuts (sendMessage, banChatMemberโ€ฆ) | โœ… | โœ… | | Full Context (~70 shortcuts reply/edit/admin/react) | โœ… | โœ… | | Business flavor (`business_connection_id` automatic) | plugin | โœ… built-in | | Filters `on('message:photo' / ':text' / 'chat_type:private' โ€ฆ)` | โœ… | โœ… | | `cmd / hears / action / inlineQuery` | โœ… | โœ… (+ inlineQuery matcher) | | `branch / filter / drop / route / lazy / fork` | โœ… | โœ… | | Error boundary + catch | โœ… | โœ… (all shortcuts auto-protected) | | Session + swappable storage | โœ… | โœ… | | Transformer API (`api.config.use`) | โœ… | โœ… | | `auto-retry` on 429 honoring `retry_after` | plugin | โœ… built-in `autoRetry()` | | Throttler queue | plugin | โœ… built-in `throttler()` | | Per-user rate limit | plugin | โœ… built-in `limiter()` | | `InputFile` Buffer/path/stream + multipart `attach://` | โœ… | โœ… | | `InputMedia` builder + media groups | โœ… | โœ… `InputMediaBuilder` | | File download (`getFile`/`downloadFile`) | plugin | โœ… built-in | | Keyboard & InlineKeyboard fluent classes | โœ… | โœ… | | Interactive menus | plugin | โœ… built-in `Menu/MenuContainer` | | Wizard/conversations | plugin | โœ… built-in โ€” **+ choice buttons & `edit`/`delete` modes** | | 409-resilient long polling | โŒ (fatal crash) | โœ… built-in (auto-retry 5 s) | | Broadcast ready to use | โŒ | โœ… `bot.broadcast()` | | Humanized errors + suggestions | โŒ | โœ… `humanize()` | | Boot banner + debug logging | โŒ | โœ… (`DEBUG=telebibz*`) | | HTTP(S) proxy for VPS | โš ๏ธ manual | โœ… `proxy` transport option | | TypeScript | โœ… full | loose d.ts (JS-first) | | Documentation language | en | **๐Ÿ‡ฌ๐Ÿ‡ง + ๐Ÿ‡ฎ๐Ÿ‡ฉ** | ## ๐Ÿ“ฅ Installation & Requirements **Requirements:** Node.js โ‰ฅ 18 (uses global `FormData`/`Blob` for uploads). ```bash npm install @xbibzlibrary/telebibz # or yarn add @xbibzlibrary/telebibz # or pnpm add @xbibzlibrary/telebibz ``` **Runtime dependencies (all used, all tested):** | Package | Purpose | |---|---| | `axios ^1.20` | keep-alive transport + streaming `downloadFile` | | `mime-types ^3.0` | content-type detection for uploads | | `https-proxy-agent ^9.1` | VPS proxy transport option | | `debug ^4.4` | logging via `DEBUG=telebibz:net,telebibz:ratelimit` | Get your bot token from **@BotFather** โ†’ `/newbot`. The constructor validates the token format (`123456:ABCโ€ฆ`) and throws a helpful error if it's wrong. ## ๐Ÿš€ Quick Start ```js const { TeleBibz } = require('@xbibzlibrary/telebibz'); const bot = new TeleBibz('TOKEN_FROM_BOTFATHER'); bot.cmd('start', (ctx) => ctx.reply('Hello!')); bot.hears(/hello|hi/i, (ctx) => ctx.reply('hello there ๐Ÿ‘‹')); bot.hears('ping', (ctx) => ctx.reply('pong ๐Ÿ“')); bot.launch(); ``` ```bash BOT_TOKEN=123:abc node index.js ``` ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ ๐Ÿค– TeleBibz ON โ”‚ โ”‚ bot : @yourbot (id 123456) โ”‚ โ”‚ mode : long-polling โ”‚ โ”‚ library : telebibz 3.1.0 โ”‚ โ”‚ brand : //โ€”Xbibz Officialโ€”// โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โœ” waiting for updatesโ€ฆ (Ctrl+C to stop) ``` > [!NOTE] > **On a VPS:** if another bot instance is still polling (409 Conflict โ€” e.g. double > deploy or a hosting restart), telebibz **auto-retries every 5 seconds without > crashing** and boots the moment the lane is free. No PM2 babysitting needed. ## ๐Ÿง  How It Works (Architecture) ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” Telegram Bot API โ”€โ”€โ”€โ”€โ–บโ”‚ long polling (lib/runner.js) โ”‚ โ”‚ or webhook / handleUpdate (lib/telebibz.js)โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ raw update (JSON) โ–ผ Context(update, api, me) lib/context.js โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ Middleware tree `_root` (fixed order): โ”‚ โ”‚ 1. session() lib/session.js โ”‚ โ”‚ 2. wizard.middleware() lib/wizard.js โ”‚ โ”‚ 3. errorBoundary(reporter) โ”‚ โ”‚ โ””โ”€โ–บ your handlers: use/cmd/hears/action/on/ โ”‚ โ”‚ inlineQuery/Menu/wizard lib/composer.js โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ ctx.reply / ctx.api.* โ–ผ ApiBase + Proxy + transformer pipeline lib/api.js (api.config.use โ†’ autoRetry / throttler) โ”‚ โ–ผ axios transport: JSON or multipart attach:// lib/net.js โ”‚ โ–ผ https://api.telegram.org ``` **Lifecycle of one update** (e.g. `/start`): `getUpdates` โ†’ `pollLoop` โ†’ `handleUpdate` โ†’ new `Context` โ†’ session loads โ†’ wizard middleware (no active wizard โ†’ pass) โ†’ error boundary โ†’ your matched handler runs โ†’ `ctx.reply()` โ†’ transformer pipeline โ†’ axios โ†’ Telegram. Any thrown error becomes a `BotError` and flows to `opts.onError` or the humanized reporter. ## ๐Ÿ“– Full Documentation ### ๐Ÿ—๏ธ Constructor & options ```js const bot = new TeleBibz('TOKEN', { allowedUpdates: [...], // limit update types (default: common + Business types) onError: (err, ctx) {}, // custom error handler (default: humanized reporter) silent: false, // hide boot banner dropPending: false, // discard old updates on start session: { ... }, // { initial, getKey, storage } โ€” see Sessions transport: fn, // inject custom transport (testing / proxy) }); ``` ### ๐ŸŽ›๏ธ Handlers & filters ```js bot.cmd('ping', (ctx) => ctx.reply('pong')); // /ping bot.cmd(['a', 'b'], handler); // /a OR /b bot.start('Welcome!'); // shortcut: registers /start bot.hears('daftar', handler); // exact text "daftar" (case-insensitive) bot.hears(/kitt?y/i, handler); // any regex bot.on('message:photo', handler); // grammY-style filters bot.on([':text', 'chat_type:private'], handler); bot.action('menu:premium', handler); // callback_query data (string or RegExp) bot.inlineQuery(/kucing/i, handler); // inline mode (regex / string / '*') bot.use(middleware); // manual middleware ``` Composer combinators (grammY semantics): ```js bot.branch(pred, ifTrue, ifFalse); // pick a subtree by predicate bot.filter(pred, ...mw); // run only when pred(ctx) is true bot.drop(pred, ...mw); // skip when pred(ctx) is true bot.route('chat.type', { private: mwA, group: mwB }); // map ctxโ†’handler bot.lazy((ctx) => ctx.from.is_bot ? botMw : userMw); // build mw per update bot.fork(slowMw); // run in background, doesn't block next() ``` Filters supported by `on()`: update fields (`message`, `edited_message`, `callback_query`, `inline_query`, `my_chat_member`, โ€ฆ), message props (`message:photo`, `message:text`, `:caption`, `:document`, `:sticker`, `:media`, โ€ฆ), chat types (`chat_type:private/group/supergroup/channel`), plus `callback_query:data`, payments, reactions, join requests. Command handlers receive arguments in `ctx.match`: ```js bot.cmd('echo', (ctx) => ctx.reply(`args: ${ctx.match}`)); // /echo hello โ†’ "hello" ``` ### ๐Ÿ’ฌ Context shortcuts `ctx` wraps every update kind (message, edited, channel, business, callback, inlineโ€ฆ) with unified accessors: `chat`, `from`, `chatId`, `msgId`, `msg`, `senderChat`, `inlineMessageId`, `businessConnectionId`. | Category | Shortcuts | |---|---| | **Reply** | `reply`, `replyWithHTML`, `replyWithMarkdown`, `replyWithPhoto/Video/Audio/Document/Animation/Voice/VideoNote/Sticker/MediaGroup/Location/Venue/Contact/Poll/Dice/Invoice/ChatAction` | | **Edit & delete** | `editMessageText/Caption/Media/ReplyMarkup`, `deleteMessage`, `deleteMessages` โ€” callback-aware & inline-message aware | | **React** | `react('๐Ÿ‘')` | | **Forward/copy** | `forwardMessage(to)`, `copyMessage(to)` (defaults to current msg) | | **Callbacks & inline** | `answerCallbackQuery` (string or object), `answerInlineQuery` | | **Admin** | `banChatMember`, `restrictChatMember`, `promoteChatMember`, `banAuthor`, `restrictAuthor`, `getChat*`, `getAuthor`, `leaveChat`, `setChatTitle/Description`, `pin/unpinChatMessage` | | **Files** | `getFile()` (smart: largest photo), `downloadFile(dest)` | Business accounts: replies inside a business context automatically carry `business_connection_id`. ### ๐Ÿ”˜ Keyboards & buttons ```js const { btn, url, webApp, copy, kb, InlineKeyboard, Keyboard } = require('@xbibzlibrary/telebibz'); bot.cmd('menu', (ctx) => ctx.reply('Pick:', kb([ [btn('๐Ÿ’Ž Premium', 'prem', 'primary'), // blue/purple btn('โœ… Register', 'reg', 'success')], // green [url('๐ŸŒ Web', 'https://yoursite.com')], [btn('โŒ Close', 'close', 'danger', '5408846744727334338')], // red + ANIMATED ICON ]))); ``` - ๐ŸŽจ `style` colors (`primary`/`success`/`danger`) need Telegram apps from Feb 2026+ โ€” older apps render plain buttons, never an error. - โœจ `icon_custom_emoji_id` needs a Premium bot owner or a Fragment username. - Helpers: `copy(text, value)` (copy-to-clipboard), `webApp(text, link)`, `kb.confirm(yesData, noData)`, `kb.markup(rows)`. - Fluent classes: `new InlineKeyboard().text(...).url(...).row().text(...).build()` and `new Keyboard().text(...).requestContact(...).resized().build()` (real reply keyboards). ### ๐Ÿฝ๏ธ Interactive menus ```js const { Menu, MenuContainer } = require('@xbibzlibrary/telebibz'); const mc = new MenuContainer(); const main = mc.create('main'), more = mc.create('more'); main.text('๐Ÿ”” Toggle', async (ctx) => ctx.answerCallbackQuery('toggled!')) .row() .url('๐ŸŒ Web', 'https://x.com') .submenu('More โ–ถ', 'more'); more.back('โ—€๏ธ Back', 'main'); bot.use(mc); // button handlers registered automatically bot.cmd('cfg', (ctx) => ctx.reply('Menu:', { reply_markup: main.render(ctx) })); ``` Submenus swap the keyboard in place via `editMessageReplyMarkup`; stale button presses are answered with a friendly alert instead of crashing. ### ๐Ÿง™ Wizard โ€” conversation forms, zero boilerplate ```js bot.wizard('register', { steps: [ { key: 'name', ask: 'What is your name?' }, { key: 'age', ask: 'Age?', parse: Number, validate: (n) => (n > 0 && n < 120 ? null : 'Numbers only, please:') }, ], done: async (ans, ctx) => ctx.reply(`Done ${ans.name} (${ans.age})!`), }); // user runs /register โ†’ the bot asks until finished. // typing "cancel" / "batal" stops any time. Session is active automatically. ``` `bot.wizard(id, def, bindCommand = true)` also binds `/id` as the trigger; use `bot.wizardStart(ctx, id)` from any handler (button, menu, โ€ฆ). #### ๐Ÿ†• v3.1 โ€” choice buttons + `edit`/`delete` modes ```js bot.wizard('survey', { mode: 'edit', // 'send' (default) | 'edit' | 'delete' steps: [ // reply keyboard โ€” user taps, no typing { key: 'gender', ask: 'Gender?', buttons: ['๐Ÿ‘จ Male', '๐Ÿ‘ฉ Female'], onlyButtons: true }, // inline keyboard (callback) โ€” value may differ from label { key: 'island', ask: 'Which island?', inline: true, onlyButtons: true, buttons: [[{ text: '๐ŸŒ‹ Java', value: 'java' }, { text: '๐ŸŒด Sumatra', value: 'sumatra' }]] }, // free typing with validation (mode can be overridden per step) { key: 'age', ask: 'Age?', parse: Number, mode: 'send', validate: (n) => (n > 0 && n < 120 ? null : 'Numbers only:') }, ], done: async (ans, ctx) => ctx.reply(`Saved: ${JSON.stringify(ans)}`), }); ``` | Option | Level | Purpose | |---|:---:|---| | `buttons` | step | `['A','B']`, `[{text,value}]`, or explicit rows `[['A'],['B','C']]` | | `inline` | step | `true` โ†’ callback buttons (click = value, no typing) | | `onlyButtons` | step | `true`/string โ†’ reject free typing, must pick a button | | `mode` | def/step | `'send'` new message ยท `'edit'` one message edited in place ยท `'delete'` old question deleted first | | `cleanup` | def | delete the last question when done (default on with mode `'delete'`) | | `removeKeyboard` | def | dismiss the reply keyboard when done (default `true` if one was shown) | Programmatic helpers: `bot.wizardCancel(ctx)`, `bot.wizardEdit(ctx, text)`, `bot.wizardDelete(ctx)`, plus module `wizard` (`cancel/editAsk/deleteAsk`). Stale buttons (clicked after the wizard advanced/ended) get a safe alert โ€” the bot never crashes. `parse`/`validate` also apply to button values. ### โ“ Inline mode ```js const { iq } = require('@xbibzlibrary/telebibz'); bot.inlineQuery(/cat/i, async (ctx) => { await ctx.answerInlineQuery([ iq.article('1', 'A cat fact', { message_text: 'meong!' }), iq.photo('2', 'https://x/1.jpg'), ], { cache_time: 0 }); }); ``` Builders: `iq.article/photo/gif/video/audio/location/sticker`. ### ๐Ÿ“ฃ Broadcast (rate-limit safe) ```js const result = await bot.broadcast([111, 222, 333], 'Announcement!', { delay: 35 }); // โ†’ { terkirim: 3, gagal: 0, errors: [] } (blocked users are listed in errors) ``` `pesan` may be a string, a `sendMessage` payload object, or a function `(chatId) => payload` for per-recipient personalization. Default pacing is 35 ms (โ‰ˆ28 msg/s, safely under Telegram limits). ### ๐Ÿ“Ž Files & media ```js const { InputFile, InputMediaBuilder } = require('@xbibzlibrary/telebibz'); bot.cmd('foto', (ctx) => ctx.replyWithPhoto(new InputFile(buffer, 'x.jpg'))); bot.cmd('dok', (ctx) => ctx.replyWithDocument(new InputFile('/path/file.pdf'))); bot.cmd('album', (ctx) => ctx.replyWithMediaGroup([ InputMediaBuilder.photo('https://a/1.jpg'), InputMediaBuilder.photo('https://a/2.jpg', { caption: 'two' }), ])); bot.on('message:photo', async (ctx) => { const f = await ctx.getFile(); // largest photo size, automatic await ctx.downloadFile('./foto.jpg'); // streams to disk }); ``` `InputFile` accepts Buffer / Uint8Array / file path / fs stream / async iterable; uploads are sent as `multipart` with `attach://` anywhere in the payload (media groups, thumbnails, โ€ฆ). `api.downloadFile(file_id, dest)` works standalone too. ### ๐Ÿ›ก๏ธ Reliability & rate limiting ```js const { autoRetry, throttler, limiter } = require('@xbibzlibrary/telebibz'); bot.api.config.use(autoRetry()); // retry 429, honor retry_after (max 5) bot.api.config.use(throttler()); // global queue โ‰ค 28 calls/second bot.use(limiter({ windowMs: 2000, limit: 3, onExceeded })); // per-user anti-spam ``` Long polling is resilient by default: 409 conflicts retry every 5 s (`launch({ conflictDelay: 5000 })` to tune), network hiccups back off 1 s, `stop()` exits cleanly (`await bot.runPromise`). ### ๐Ÿ—ƒ๏ธ Sessions ```js const { session } = require('@xbibzlibrary/telebibz'); const bot = new TeleBibz(token, { session: { initial: () => ({ count: 0 }), getKey: (ctx) => `${ctx.from?.id}:${ctx.chat?.id}`, // default storage: myRedisAdapter, // { read(k), write(k,v), delete(k) } โ€” default: in-memory Map }, }); bot.on(':text', (ctx) => { ctx.session.count++; }); ``` `ctx.session` is always present, even without configuration. ### ๐Ÿ‡ฎ๐Ÿ‡ฉ Human-readable errors Every error is reported with an actionable suggestion: ``` โœ– Telegram error (403): Forbidden: bot was blocked by the user ๐Ÿ’ก saran: Bot diblokir pengguna โ€” jangan kirim ulang, hapus dari daftar broadcast. ``` `humanize(err)` returns `{ pesan, saran, method, code }` covering 15+ common Telegram errors (bad token, chat not found, rights, parse errors, rate limits, stale callbacks, oversize files, โ€ฆ). Override with `new TeleBibz(token, { onError: (err, ctx) => {} })`. ### ๐Ÿ•ธ๏ธ Webhooks & serverless ```js const http = require('http'); http.createServer((req, res) => req.url === '/tg' ? bot.webhook()(req, res) : res.end('ok') ).listen(8443); // any framework (Express/Fastify/Hono): mount the (req, res) handler from bot.webhook() // or serverless, directly: await bot.handleUpdate(req.body); // one raw update in โ†’ full pipeline ``` Remember `await bot.init()` first when you don't call `launch()` (it fetches bot info), and `setWebhook(url)` via `bot.api.setWebhook({ url })`. ### ๐Ÿ”Œ Proxy transport (VPS behind a proxy) ```js const { TeleBibz, createTransport } = require('@xbibzlibrary/telebibz'); const bot = new TeleBibz(token, { transport: createTransport(token, { proxy: 'http://user:pass@proxy:8080' }), }); ``` `createTransport(token, { apiRoot, proxy, timeoutMs, headers })` also lets you point at a local Bot API server. ### ๐Ÿงช Transformers (escape hatch) ```js bot.api.config.use(async (prev, method, payload) => { console.log('โ†’', method); // observe/modify every Bot API call return prev(method, payload); }); // any method, even unreleased ones (Proxy magic): await bot.api.sendDiceCustom({ chat_id: 1, emoji: '๐ŸŽฒ' }); ``` ## ๐Ÿ“ˆ Analytics & Statistics ### ๐Ÿ“Š This repo in numbers | Metric | Value | |---|---| | ๐Ÿ“ฆ Source modules | **16 files** in `lib/` | | ๐Ÿ“ Total lines of code | **~1,700** (no build step) | | ๐Ÿ”Œ Bot API methods | **90+** โ€” 75 typed shortcuts + unbounded Proxy | | โŒจ๏ธ Context shortcuts | **50+** (reply/edit/delete/admin/reactโ€ฆ) | | ๐Ÿงช Offline tests | **30/30 passing**, zero network | | ๐Ÿงฉ Ready examples | **7** in `examples/` | | ๐Ÿ“ฆ Runtime dependencies | **4** โ€” all used, all tested | ### โฌ‡๏ธ Downloads & popularity (live from npm) [![per day](https://img.shields.io/npm/dd/@xbibzlibrary/telebibz?style=flat-square&label=day&color=informational)](https://www.npmjs.com/package/@xbibzlibrary/telebibz) [![per week](https://img.shields.io/npm/dw/@xbibzlibrary/telebibz?style=flat-square&label=week&color=informational)](https://www.npmjs.com/package/@xbibzlibrary/telebibz) [![per month](https://img.shields.io/npm/dm/@xbibzlibrary/telebibz?style=flat-square&label=month&color=informational)](https://www.npmjs.com/package/@xbibzlibrary/telebibz) [![total](https://img.shields.io/npm/dt/@xbibzlibrary/telebibz?style=flat-square&label=total&color=informational)](https://www.npmjs.com/package/@xbibzlibrary/telebibz) ### ๐Ÿ“ Module size map (lines of code) ``` wizard.js โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 247 โ† forms + buttons + edit/delete telebibz.js โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–Ž 193 โ† main class & lifecycle context.js โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 190 โ† ctx + 50-ish shortcuts composer.js โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ– 174 โ† middleware engine & filters api.js โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ– 154 โ† 75 shortcuts + Proxy + transformers net.js โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–Œ 115 โ† axios transport + multipart menus.js โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 90 โ† Menu/MenuContainer keyboard.js โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–Ž 83 โ† btn/url/kb + fluent classes ratelimit.js โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 61 โ† autoRetry ยท throttler ยท limiter runner.js โ–ˆโ–ˆโ–ˆโ–ˆโ–Œ 45 โ† 409-resilient polling file.js โ–ˆโ–ˆโ–ˆโ–ˆ 41 โ† InputFile + InputMediaBuilder logger.js โ–ˆโ–ˆโ–ˆโ–Š 38 โ† logs + banner session.js โ–ˆโ–ˆโ–ˆโ–Œ 36 โ† swappable sessions errors.js โ–ˆโ–ˆโ–ˆโ–Œ 35 โ† humanized errors ๐Ÿ‡ฎ broadcast.js โ–ˆโ–ˆโ–ˆ 35 โ† rate-limit-safe blast inline-query.jsโ–ˆโ–ˆโ–Š 28 โ† matcher + result builders ``` ### ๐Ÿ—บ๏ธ Repo health
[![repo card](https://github-readme-stats.vercel.app/api/pin/?username=XbibzOfficial777&repo=telebibz&show_owner=false)](https://github.com/XbibzOfficial777/telebibz)
๐Ÿ“… Star history (click to open) ![Star History](https://api.star-history.com/svg?repos=XbibzOfficial777/telebibz&type=Date)
## ๐Ÿงฉ Ready Examples (`examples/`) | File | Content | |---|---| | `01-quickstart.js` | bot up in 6 lines | | `02-menu-tombol.js` | colored keyboard + animated icons | | `03-wizard.js` | registration form + **buttons + edit mode** | | `04-broadcast.js` | admin blast | | `05-kirim-file.js` | photos & documents from buffers | | `06-menu.js` | interactive menus + submenus | | `07-inline-query.js` | inline mode with result builders | Run any of them with `BOT_TOKEN=123:abc node examples/01-quickstart.js`. ## ๐Ÿ”ฌ Testing & Live Proof ```bash npm test # 30 cases, NO network (transport injected) ``` Validated **30/30 offline + 10 live** on the production bot `@xbibzrat_bot`: getMe ยท colored keyboards & real animated icons ยท multipart uploads (photo+document) ยท keyboard editing ยท broadcast ยท deleteMessage ยท polling 409 retry ยท wizard buttons & edit/delete. Debug logging: `DEBUG=telebibz:net,telebibz:ratelimit node yourbot.js`. ## ๐Ÿ“‚ Repo Structure (16 core files) | File | Role | |---|---| | `lib/net.js` | axios keep-alive transport + multipart `attach://` | | `lib/api.js` | Bot API methods + any-method Proxy + transformers | | `lib/composer.js` | middleware, `on('message:photo')` filters, `errorBoundary` | | `lib/context.js` | ctx object + 50-ish reply/edit/delete/callback shortcuts | | `lib/session.js` | per user:chat sessions (swappable storage) | | `lib/runner.js` | long polling: 409 retry, network backoff, drop pending | | `lib/wizard.js` | conversation forms + choice buttons + edit/delete modes | | `lib/menus.js` | `Menu`/`MenuContainer` interactive menus | | `lib/keyboard.js` | button builders + fluent `InlineKeyboard`/`Keyboard` | | `lib/ratelimit.js` | `autoRetry` 429 ยท `throttler` queue ยท per-user `limiter` | | `lib/broadcast.js` | rate-limit-safe blast | | `lib/file.js` | `File`/`InputFile` (Buffer/path/stream) + `InputMediaBuilder` | | `lib/inline-query.js` | query matcher + inline result builders | | `lib/errors.js` | humanized errors + suggestions | | `lib/logger.js` | framed logs + boot banner | | `index.js` / `index.d.ts` | export door + TypeScript types | ## ๐Ÿ• Changelog - **3.1.0** โ€” wizard: choice buttons (reply/inline), `edit`/`delete` modes, auto cleanup, programmatic helpers ยท tests 24 โ†’ 30 - **3.0.0** โ€” production-grade grammY parity: axios keep-alive, transformers, menus, inline query, limiter - **2.0.0** โ€” engine rewritten from scratch, multipart transport, native Node webhook - **1.0.0** โ€” grammY architecture recode > Full details in [`CHANGELOG.md`](CHANGELOG.md). Deep architecture study (๐Ÿ‡ฎ): [`ANALISIS-telebibz.md`](ANALISIS-telebibz.md). ## ๐Ÿ“„ License **MIT** ยฉ Xbibz Official โ€” architecture inspired by [grammY](https://grammy.dev) (MIT, see [`NOTICE.md`](NOTICE.md)). ---
**Made with โค๏ธ by //โ€”Xbibz Officialโ€”//** If telebibz helps you, a โญ on this repo means a lot. [![repo views](https://komarev.com/ghpvc/?username=XbibzOfficial777&repo=telebibz&style=flat-square&color=blueviolet&label=repo+views)](https://github.com/XbibzOfficial777/telebibz)