@xbibzlibrary/telebibz 3.1.3 → 3.1.4

package/CHANGELOG.md

@@ -1,11 +1,35 @@
 # Changelog
 
-## Unreleased — Telegram Bot API 10.3
+## Unreleased — Telegram Bot API 10.3 / Rich Messages
 
-- Vendored schema TypeScript `@grammyjs/types@5.0.0` (MIT), typed payload signatures, and an audited 185-method runtime registry kept in exact sync by tests; no new runtime dependency.
-- Rich-message builders/entities/blocks, live-photo and paid-media builders, guest-query/ephemeral/draft helpers, inline rich-article builder, and the `08-rich-message.js` example.
-- Typed `callApi(method, payload)` and Telegram schema exports; positive/negative TypeScript consumer checks run in CI and before automated npm release.
-- English/Indonesian documentation and npm publishing setup guidance updated; tests now 30 feature + 17 audit checks.
+### API surface and types
+
+- Added a runtime registry containing **185 Bot API method names**. An audit test compares the registry exactly with all vendored method signatures and rejects duplicates.
+- Vendored `@grammyjs/types@5.0.0` declarations (MIT; attribution/license in `NOTICE.md` and `types/telegram-bot-api/LICENSE`) for Bot API methods, objects, updates and payloads. These declarations add **no runtime dependency**; TypeScript is a development-only dependency for type tests.
+- `api.callApi(method, payload)` and `api.raw(...)` now provide method-specific parameter and result typing for all methods in the vendored schema. `TelegramTypes`, `TelegramMethodName`, `TelegramMethodPayload<M>`, `TelegramMethodResult<M>`, `TelegramApiMethods` and `TelegramApiPayloads` are exported. The dynamic API Proxy remains available but is not runtime schema validation.
+
+### Rich Message authoring
+
+- Added `rich.html()`, `rich.markdown()`, `rich.blocks()`, `inputRichMessage()`, and `RichMessageBuilder` (`html`, `markdown`, `blocks`, `add`, `media`, `rtl`, `skipEntityDetection`, `build`, `buildDraft`). Exactly one content mode—HTML, Markdown or blocks—is required.
+- Added RichText entity builders for bold/italic/underline/strikethrough/spoiler/marked/code/subscript/superscript, date-time, mentions, custom emoji, math, links, email/phone/card, hashtag/cashtag/bot command, anchors/references, and inline rich-text buttons.
+- Added block builders for paragraph, heading, preformatted text, footer, divider, math, anchor, list, block/expandable/pull quotations, collage, slideshow, table, details, map, animation, audio, document, photo, video, voice note, buttons and draft-only thinking blocks.
+- `rich.button()` now builds a `RichMessageButton` for the buttons block; `rich.buttonText()` builds the separate inline `RichTextButton` entity. Runtime validation checks the one-action rule, supported style/alignment and 1–8 button count. This correction followed a live Telegram parse error.
+- Added draft-safe `rich.draftHtml()`, `rich.draftMarkdown()`, `rich.draftBlocks()` and `RichMessageBuilder.buildDraft()`. They reject new `File` uploads; use existing Telegram file IDs for draft media.
+- Added animated custom emoji support via `rich.customEmoji(customEmojiId, alternativeText)` and rich-message embedding of media through `tg://...` references plus `media` entries.
+
+### Bot API 10.x helpers and media
+
+- Added/typed API and Context support for `sendRichMessage`, `editMessageText` with `rich_message`, `sendLivePhoto`, `sendMessageDraft`, `sendRichMessageDraft`, `answerGuestQuery`, ephemeral send/edit/delete methods, and `iq.richArticle()`.
+- Added live-photo and paid-media builders (`InputMediaBuilder.livePhoto()` and `InputPaidMediaBuilder.livePhoto()`). Existing multipart transport now has audit coverage for nested rich-media attachments.
+- Added Context helpers: `replyWithRichMessage`, `editRichMessage`, `replyWithLivePhoto`, `sendMessageDraft`, `sendRichMessageDraft`, `replyEphemeral`, `editEphemeralRichMessage`, ephemeral media/caption/reply-markup edits, and `deleteEphemeralMessage`.
+- Added `examples/08-rich-message.js` and expanded both English and Indonesian README sections with usage, helper catalogs, typing, media, drafts, animated emoji, limits/permissions and troubleshooting.
+
+### Verification, live-test findings and publishing
+
+- Automated suite: **30/30** existing feature checks + **18/18** audit checks (**48 total**); `npm run typecheck`, JavaScript syntax, workflow YAML, `npm pack --dry-run`, `git diff --check`, and `npm audit --omit=dev` pass.
+- Live smoke test: rich blocks, HTML/Markdown, animated custom emoji, plain/rich drafts, photo/audio/document/video/voice-note media blocks, collage/slideshow, standalone live photo, GIF with `sendAnimation`, and rich HTML media references succeeded. For a rich `animation` block, MP4 succeeded while GIF returned `RICH_MESSAGE_VIDEO_INVALID`; the same GIF worked with standalone `sendAnimation`.
+- Live ephemeral sends returned Telegram `BOT_NOT_ADMIN`; paid-media sending was not attempted because it can involve Telegram Stars. Callback execution and all 185 endpoints were not live-tested; see `VERIFIKASI-MENDALAM.md`. No bot token or user/chat identifier is recorded in repo documentation.
+- CI/release workflows now run TypeScript checks. Auto-publish remains gated by GitHub Environment `npm-release` and secret `NPM_TOKEN`; no credential is committed and no release is implied by this Unreleased entry.
 
 ## 3.1.0 — wizard: tombol pilihan + mode edit/delete (2026-09-13)
 

package/README.id.md

@@ -19,8 +19,8 @@ produksi yang *benar-benar dipakai*, dokumentasi 🇮🇩 Indonesia-first, dan n
 [![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=unduh%2Fbulan)](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/test-30%2F30%20lulus-brightgreen?style=for-the-badge&logo=checkmarx&logoColor=white)](#-test--bukti-live)
-[![size](https://img.shields.io/badge/kode-1.7k%20baris-orange?style=for-the-badge&logo=codeigniter&logoColor=white)](#-analitik--statistik)
+[![tests](https://img.shields.io/badge/test-48%2F48%20lulus-brightgreen?style=for-the-badge&logo=checkmarx&logoColor=white)](#-test--bukti-live)
+[![size](https://img.shields.io/badge/kode-2.1k%20baris-orange?style=for-the-badge&logo=codeigniter&logoColor=white)](#-analitik--statistik)
 [![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=kunjungan+repo)](https://github.com/XbibzOfficial777/telebibz)
 
@@ -38,7 +38,7 @@ produksi yang *benar-benar dipakai*, dokumentasi 🇮🇩 Indonesia-first, dan n
 |---|---|---|
 | ⚡ [Kenapa telebibz?](#kenapa) | 📊 [Matriks fitur vs grammY](#matriks) | 📥 [Instalasi & persyaratan](#instalasi) |
 | 🚀 [Mulai cepat](#mulai) | 🧠 [Cara kerja (arsitektur)](#arsitektur) | 📖 [Dokumentasi lengkap](#dokumentasi) |
-| 🎛️ [Handler & filter](#handler) | 💬 [Shortcut Context](#context) | 🔘 [Keyboard & tombol](#keyboard) |
+| 🎛️ [Handler & filter](#handler) | 💬 [Shortcut Context](#context) | 🧱 [Rich Message & Bot API 10.3](#rich-messages) |
 | 🍽️ [Menu interaktif](#menu) | 🧙 [Wizard (form + tombol + edit/delete)](#wizard) | ❓ [Mode inline](#inline) |
 | 📣 [Broadcast](#broadcast) | 📎 [File & media](#file) | 🛡️ [Keandalan & rate limit](#ratelimit) |
 | 🗃️ [Session](#session) | 🇮🇩 [Error manusiawi](#error) | 🕸️ [Webhook & serverless](#webhook) |
@@ -67,6 +67,8 @@ produksi yang *benar-benar dipakai*, dokumentasi 🇮🇩 Indonesia-first, dan n
 | Fitur | grammY | telebibz |
 |---|:---:|:---:|
 | Proxy API **segala metode** (auto-generated) | ✅ | ✅ |
+| **185 signature payload Bot API spesifik** (`callApi`) | ✅ | ✅ |
+| Rich Message: block, entity, draft, media, emoji bergerak | beragam per API | ✅ bawaan |
 | ~60 shortcut bertipe (sendMessage, banChatMember…) | ✅ | ✅ |
 | Context lengkap (~70 pintasan reply/edit/admin/react) | ✅ | ✅ |
 | Context flavor business (`business_connection_id` otomatis) | plugin | ✅ bawaan |
@@ -90,7 +92,7 @@ produksi yang *benar-benar dipakai*, dokumentasi 🇮🇩 Indonesia-first, dan n
 | Humanisasi error + saran (🇮🇩) | ❌ | ✅ `humanize()` |
 | Banner boot + log debug | ❌ | ✅ (`DEBUG=telebibz*`) |
 | Proxy HTTP(S) untuk VPS | ⚠️ manual | ✅ opsi `proxy` transport |
-| TypeScript | ✅ full | d.ts longgar (JS-first) |
+| TypeScript | ✅ full | ✅ tipe spesifik untuk 185 metode Bot API |
 | Bahasa dokumentasi | en | **🇬🇧 + 🇮🇩** |
 
 <a id="instalasi"></a>
@@ -268,63 +270,256 @@ Akun business: balasan dalam konteks business otomatis menyertakan
 `business_connection_id`.
 
 <a id="rich-messages"></a>
-### 🧱 Rich Messages, draft, live photo & pesan ephemeral (Bot API 10.3)
+### 🧱 Rich Message, emoji bergerak, media & draft (Bot API 10.3)
 
-TeleBibz menyediakan builder rich-message dan Context helper; untuk seluruh
-**185 metode Bot API** tersedia juga `ctx.api.callApi(method, payload)` yang bertipe,
-sementara proxy menerima metode baru lewat object payload.
+**Rich Message** adalah format Telegram terstruktur: satu pesan dapat memuat rich-text entities, heading, list, kutipan, tabel, peta, tombol, blok media, dan elemen lainnya. TeleBibz menyediakan builder dan shortcut Context; [referensi resmi Telegram Bot API](https://core.telegram.org/bots/api) tetap menjadi sumber otoritatif untuk batasan dan kelayakan fitur.
+
+> **Catatan cakupan:** schema memuat **185 nama metode Bot API** dan payload bertipe melalui `api.callApi()`. Ini tidak berarti seluruh 185 endpoint aman atau bermakna untuk dites live: sebagian memerlukan update nyata, hak admin, pembayaran, atau chat tertentu. Matriks live test dan batasannya ada di [`VERIFIKASI-MENDALAM.md`](VERIFIKASI-MENDALAM.md).
+
+#### 1. Pilih tepat satu mode konten
+
+Satu rich message harus memakai tepat satu sumber konten: `html`, `markdown`, atau `blocks`. Opsi seperti `media`, `is_rtl`, dan `skip_entity_detection` bersifat tambahan, bukan mode konten.
+
+```js
+const { TeleBibz, rich, RichMessageBuilder } = require('@xbibzlibrary/telebibz');
+const bot = new TeleBibz(process.env.BOT_TOKEN);
+
+bot.cmd('laporan', async (ctx) => {
+  const message = rich.blocks([
+    rich.heading('Laporan mingguan', 2),
+    rich.paragraph(['Pesanan: ', rich.bold('42'), ' · status ', rich.italic('siap')]),
+    rich.table([
+      [
+        { text: 'Metrik', is_header: true, align: 'left', valign: 'middle' },
+        { text: 'Nilai', is_header: true, align: 'right', valign: 'middle' },
+      ],
+      [
+        { text: 'Pendapatan', align: 'left', valign: 'middle' },
+        { text: 'Rp1.250.000', align: 'right', valign: 'middle' },
+      ],
+    ], { bordered: true, striped: true, compact: true, caption: 'Minggu ini' }),
+    rich.details('Informasi tambahan', [rich.paragraph('Bagian ini dapat dibuka.')]),
+    rich.buttons([
+      rich.button('Buka dashboard', { url: 'https://example.com' }, 'primary'),
+      rich.button('Konfirmasi', { callback_data: 'report:ack' }, 'success'),
+    ], 'center'),
+  ]);
+  return ctx.replyWithRichMessage(message);
+});
+
+bot.launch();
+```
+
+Konstruktor tingkat rendah: `rich.html(html, options)`, `rich.markdown(markdown, options)`, dan `rich.blocks(blocks, options)`. `inputRichMessage(content, options)` memvalidasi pemilihan satu mode. Untuk merakit pesan bertahap, gunakan `RichMessageBuilder`:
+
+```js
+const message = new RichMessageBuilder()
+  .blocks([rich.heading('Pengumuman', 2)])
+  .add(rich.paragraph('Blok berikutnya bisa ditambahkan.'))
+  .rtl(false)
+  .skipEntityDetection()
+  .build();
+await ctx.replyWithRichMessage(message);
+```
+
+Pada satu builder, pemanggilan `.html()`, `.markdown()`, atau `.blocks()` kedua akan error. Buat builder baru untuk mode lain. `.media()` digunakan bersama konten HTML/Markdown yang menunjuk media melalui tautan `tg://...`.
+
+#### 2. Rich-text entities
+
+Rich text dapat berupa string biasa, array campuran string dan objek entity, atau objek rich-text bertingkat. Helper yang tersedia:
+
+| Helper | Entity | Kegunaan |
+|---|---|---|
+| `rich.bold(text)`, `rich.italic(text)`, `rich.underline(text)`, `rich.strikethrough(text)` | penekanan | format teks inline |
+| `rich.spoiler(text)`, `rich.marked(text)`, `rich.code(text)` | spoiler / marked / code | teks tersembunyi atau teknis |
+| `rich.subscript(text)`, `rich.superscript(text)` | posisi huruf | rumus dan referensi |
+| `rich.dateTime(text, unixTime, format)` | tanggal/waktu | timestamp lokal atau relatif |
+| `rich.url(text, url)`, `rich.email(text, email)`, `rich.phone(text, phone)` | tautan/kontak | tautan atau informasi kontak |
+| `rich.mention(text, username)`, `rich.textMention(text, user)` | mention | username atau objek User |
+| `rich.hashtag(text, value)`, `rich.cashtag(text, value)`, `rich.botCommand(text, value)` | entity Telegram | tag dan command |
+| `rich.customEmoji(customEmojiId, alternativeText)` | custom emoji | custom emoji statis maupun bergerak |
+| `rich.mathText(expression)`, `rich.anchorText(name)`, `rich.anchorLink(text, name)`, `rich.reference(text, name)`, `rich.referenceLink(text, name)` | rumus/navigasi | teks panjang terstruktur |
+| `rich.buttonText(text, action, style)` | tombol di rich-text inline | entity tombol di dalam satu rangkaian teks |
+
+Contoh custom emoji bergerak (gunakan **ID custom emoji yang nyata** dan dapat dipakai bot):
+
+```js
+const emojiId = 'CUSTOM_EMOJI_ID';
+const [sticker] = await ctx.api.callApi('getCustomEmojiStickers', {
+  custom_emoji_ids: [emojiId],
+});
+if (!sticker) throw new Error('Custom emoji ID tidak ditemukan');
+await ctx.replyWithRichMessage(rich.blocks([
+  rich.paragraph(['Status build: ', rich.bold('lulus'), ' ', rich.customEmoji(emojiId, '👍')]),
+]));
+```
+
+Emoji Unicode biasa tidak otomatis menjadi emoji custom bergerak. ID harus valid dan dapat digunakan bot; Telegram dapat menolak ID atau fitur yang tidak tersedia bagi bot tersebut.
+
+#### 3. Katalog blok terstruktur
+
+Setiap helper menghasilkan objek `InputRichBlock`. Blok dapat disusun bertingkat sesuai schema Telegram.
+
+| Kelompok | Helper | Catatan |
+|---|---|---|
+| Teks | `paragraph(text)`, `heading(text, size)`, `pre(text, language)`, `footer(text)`, `divider()` | ukuran heading 1–6; `pre` dapat menyebut bahasa kode |
+| Rumus/navigasi | `mathBlock(expression)`, `anchor(name)` | pasangan entity inline tersedia untuk isi teks |
+| List/kutipan | `list(items)`, `quote(blocks, credit)`, `expandableQuote(text, credit)`, `pullQuote(text, credit)` | item list bisa string atau item terstruktur; kutipan dapat berisi blok lain |
+| Tabel/disclosure | `table(cells, options)`, `details(summary, blocks, open)` | tiap sel memberi `align` dan `valign`; opsi tabel: `bordered`, `striped`, `compact`, `caption` |
+| Lokasi | `map(location, zoom, width, height, caption, credit)` | `location` berbentuk `{ latitude, longitude }` |
+| Media | `animation(media, caption)`, `audio(media, caption)`, `document(media, caption)`, `photo(media, caption)`, `video(media, caption)`, `voiceNote(media, caption)` | `media` adalah objek `InputMedia*`; upload `File` dikumpulkan menjadi multipart `attach://` |
+| Tata letak | `collage(blocks, caption, credit)`, `slideshow(blocks, caption, credit)` | gabungkan blok media yang didukung menjadi galeri atau urutan |
+| Tombol | `buttons(buttons, align)`, `button(text, action, style)` | 1–8 tombol; `align`: `left`, `center`, atau `right` |
+| Khusus draft | `thinking(text)` | hanya untuk `sendRichMessageDraft`, bukan pesan rich yang disimpan |
+
+Setiap sel tabel berbentuk `{ text, align: 'left'|'center'|'right', valign: 'top'|'middle'|'bottom' }`; sel header dapat memakai `is_header: true`. Satu tombol harus memilih tepat satu aksi seperti `url`, `callback_data`, `web_app`, `copy_text`, atau `disabled`. `rich.button()` menghasilkan objek tombol untuk block `buttons`; `rich.buttonText()` menghasilkan bentuk entity RichText yang berbeda. Style `link` hanya berlaku untuk tombol callback.
+
+#### 4. Upload media di dalam rich message
+
+Gunakan `file_id` Telegram untuk file yang sudah ada di server, atau bungkus bytes/path/stream dengan `File`/`InputFile` agar transport membuat multipart upload:
+
+```js
+const fs = require('node:fs');
+const { File, InputMediaBuilder } = require('@xbibzlibrary/telebibz');
+const image = new File(fs.readFileSync('./hero.png'), 'hero.png');
+const video = new File(fs.readFileSync('./clip.mp4'), 'clip.mp4');
+
+await ctx.replyWithRichMessage(rich.blocks([
+  rich.paragraph('Contoh blok media:'),
+  rich.photo(InputMediaBuilder.photo(image)),
+  rich.video(InputMediaBuilder.video(video)),
+]));
+```
+
+HTML/Markdown dapat merujuk media menggunakan ID unik dan entri `media` yang cocok:
+
+```js
+const photo = new File(fs.readFileSync('./hero.png'), 'hero.png');
+await ctx.replyWithRichMessage(rich.html(
+  '<b>Foto utama</b><br><a href="tg://photo?id=hero">Buka foto</a>',
+  { media: [{ id: 'hero', media: InputMediaBuilder.photo(photo) }] },
+));
+```
+
+Live smoke test berhasil mengirim media multipart bertingkat, blok photo/audio/document/video/voice note, collage/slideshow, dan media reference HTML. Pada server Telegram yang diuji, MP4 diterima sebagai rich `animation`, sedangkan GIF pada blok itu menghasilkan `RICH_MESSAGE_VIDEO_INVALID`. Metode standalone `sendAnimation` menerima GIF yang sama. Jika blok rich animation ditolak, coba MP4. Live photo dikirim lewat metode terpisah, bukan tipe `InputRichBlock`.
+
+#### 5. Draft dan preview streaming
+
+Draft hanya preview sementara, bukan pesan chat yang tersimpan. Kirim pesan final secara terpisah untuk menyimpan jawaban. Blok `thinking` hanya untuk rich draft. Builder draft menolak upload baru melalui `File`; gunakan `file_id` Telegram jika draft perlu media.
 
 ```js
-const { rich, RichMessageBuilder } = require('@xbibzlibrary/telebibz');
-
-bot.cmd('laporan', (ctx) => ctx.replyWithRichMessage(rich.blocks([
-  rich.heading('Laporan', 2),
-  rich.paragraph(['Status: ', rich.bold('berhasil')]),
-  rich.table([
-    [{ text: 'Item', align: 'left', valign: 'middle', is_header: true },
-     { text: 'Total', align: 'right', valign: 'middle', is_header: true }],
-    [{ text: 'Pesanan', align: 'left', valign: 'middle' },
-     { text: '3', align: 'right', valign: 'middle' }],
-  ], { bordered: true, striped: true, compact: true }),
-  rich.details('Catatan', [rich.paragraph('Rincian tambahan')]),
-  rich.buttons([rich.button('Buka', { url: 'https://example.com' }, 'primary')]),
-])));
-
-// HTML, Markdown, blok berisi media, list, kutipan, peta, tabel, collage,
-// slideshow, button, rich-text entities (bold/customEmoji/dateTime, dll.) juga didukung.
-const content = new RichMessageBuilder().markdown('**Hai!**').rtl().build();
-await ctx.replyWithRichMessage(content);
-
-// Live photo: kedua file dapat berupa file_id atau InputFile.
-await ctx.replyWithLivePhoto('video-file-id', 'photo-file-id', { caption: 'Momen' });
-
-// Draft adalah preview sementara; kirim Rich Message final agar tersimpan.
-await ctx.sendRichMessageDraft(1, rich.draftBlocks([
-  rich.paragraph('Sedang menulis…'), rich.thinking('Memproses'),
-]), { can_stop: true, keep_on_stop: true });
-await ctx.replyWithRichMessage(rich.markdown('**Jawaban final**'));
-
-// Ephemeral: pesan hanya terlihat oleh penerima tertentu.
-await ctx.replyEphemeral('Pesan privat sementara', ctx.from.id);
-
-// Akses lengkap dan bertipe untuk metode/parameter Bot API (termasuk semua metode 10.3).
+bot.cmd('preview', async (ctx) => {
+  const draftId = Date.now(); // tidak nol dan unik untuk draft ini
+  await ctx.sendMessageDraft(draftId, 'Sedang menyiapkan jawaban…', { can_stop: true });
+  await ctx.sendRichMessageDraft(draftId + 1, rich.draftBlocks([
+    rich.paragraph(['Menyiapkan ', rich.bold('laporan Anda'), '…']),
+    rich.thinking('Mengumpulkan data'),
+  ]), { can_stop: true, keep_on_stop: true });
+  // Kirim jawaban final agar tersimpan:
+  return ctx.replyWithRichMessage(rich.markdown('**Laporan siap**'));
+});
+```
+
+Konstruktor khusus draft: `rich.draftHtml()`, `rich.draftMarkdown()`, `rich.draftBlocks()`, dan `new RichMessageBuilder()...buildDraft()`. Hasilnya mengikuti schema `sendRichMessageDraft` yang tidak menerima upload `File` baru. `sendMessageDraft` dan `sendRichMessageDraft` juga bisa dipanggil dengan payload object tepat melalui `ctx.api.callApi()`.
+
+#### 6. Live photo, paid media, ephemeral, dan edit
+
+**Live photo** mengirim pasangan video dan foto statis yang terkait. Keduanya bisa berupa `file_id` atau `File`/`InputFile`; URL tidak didukung oleh schema metode saat ini.
+
+```js
+await ctx.replyWithLivePhoto('VIDEO_FILE_ID', 'PHOTO_FILE_ID', { caption: 'Sebuah momen' });
+// Atau API mentah bertipe:
+await ctx.api.sendLivePhoto({ chat_id: ctx.chatId, live_photo: videoFile, photo: photoFile });
+```
+
+`InputMediaBuilder.livePhoto(video, photo)` dan `InputPaidMediaBuilder.livePhoto(video, photo)` membangun objek media. `sendPaidMedia` membutuhkan `star_count` antara 1 dan 25.000:
+
+```js
+const fs = require('node:fs');
+const { File, InputPaidMediaBuilder } = require('@xbibzlibrary/telebibz');
+const paidPhoto = new File(fs.readFileSync('./paid.png'), 'paid.png');
+await ctx.api.callApi('sendPaidMedia', {
+  chat_id: ctx.chatId,
+  star_count: 1,
+  media: [InputPaidMediaBuilder.photo(paidPhoto)],
+  caption: 'Contoh foto berbayar',
+});
+```
+
+Fitur ini membuat paywall/pembayaran sungguhan: jangan dites ke pengguna tanpa persetujuan dan periksa penggunaan Telegram Stars sebelum memublikasikan konten berbayar.
+
+**Pesan ephemeral** ditujukan ke penerima melalui `ephemeral_message_parameters`; kelayakannya bergantung pada aturan dan izin Telegram untuk bot/chat terkait. Helper Context meliputi `replyEphemeral(text, receiverUserId)`, `editEphemeralMessageText`, `editEphemeralRichMessage`, `editEphemeralMessageMedia`, `editEphemeralMessageCaption`, `editEphemeralMessageReplyMarkup`, dan `deleteEphemeralMessage`.
+
+```js
+await ctx.replyEphemeral('Pemberitahuan sementara', ctx.from.id);
+const sent = await ctx.api.callApi('sendRichMessage', {
+  chat_id: ctx.chatId,
+  rich_message: rich.blocks([rich.paragraph('Preview rich privat')]),
+  ephemeral_message_parameters: { receiver_user_id: ctx.from.id },
+});
+// Jika Telegram mengembalikan ephemeral_message_id, ID tersebut dapat dipakai untuk edit/hapus.
+if (sent.ephemeral_message_id) {
+  await ctx.editEphemeralRichMessage(ctx.from.id, sent.ephemeral_message_id,
+    rich.blocks([rich.paragraph('Pemberitahuan sementara diperbarui')]));
+}
+```
+
+Telegram bisa menolak dengan `BOT_NOT_ADMIN` atau error izin lain; baca `ApiError` yang diterima dan jangan menganggap payload lolos test lokal berarti bot pasti berhak mengirimnya.
+
+Untuk mengedit rich message biasa, gunakan `ctx.editRichMessage(content, extra)`. API di bawahnya adalah `editMessageText` dengan `rich_message` dan target `chat_id`/`message_id` (atau `inline_message_id`). Operasi edit mengubah pesan yang ada; gunakan pesan khusus test.
+
+#### 7. Shortcut Context dan metode Bot API modern
+
+| Helper | Fungsi / argumen |
+|---|---|
+| `ctx.replyWithRichMessage(content, extra?)` | kirim rich message tersimpan ke chat saat ini |
+| `ctx.editRichMessage(content, extra?)` | edit rich message saat ini; mendukung callback dan inline target |
+| `ctx.replyWithLivePhoto(video, photo, extra?)` | kirim live photo ke chat saat ini |
+| `ctx.sendMessageDraft(draftId, text, extra?)` | preview teks sementara |
+| `ctx.sendRichMessageDraft(draftId, richMessage, extra?)` | preview rich sementara |
+| `ctx.replyEphemeral(text, receiverUserId, extra?)` | kirim teks ephemeral ke penerima tertentu |
+| `ctx.guestQueryId`, `ctx.answerGuestQuery(result)` | proses update `guest_message` yang nyata |
+| `ctx.editEphemeralRichMessage(...)`, `ctx.deleteEphemeralMessage(...)` | edit/hapus pesan ephemeral milik penerima |
+
+Jawaban guest query membutuhkan `guest_query_id` dari update masuk yang asli; ID buatan tidak dapat dipakai untuk tes live yang bermakna. Artikel inline rich dapat dibuat dengan `iq.richArticle(id, title, richMessage, extra)` lalu dikembalikan saat menangani inline query sungguhan.
+
+#### 8. Akses penuh Bot API dengan tipe
+
+Semua **185 nama metode dan signature payload** pada schema Bot API vendored tersedia lewat `api.callApi()` dan `api.raw()` di TypeScript:
+
+```js
+// JavaScript maupun TypeScript: nama metode + object payload
 await ctx.api.callApi('sendRichMessage', {
   chat_id: ctx.chatId,
-  rich_message: rich.html('<b>Rich HTML</b>'),
+  rich_message: rich.markdown('**Halo**'),
+});
+
+await ctx.api.callApi('sendMessageDraft', {
+  chat_id: ctx.chatId,
+  draft_id: Date.now(),
+  text: 'Preview',
+  can_stop: false,
 });
 ```
 
-`RichMessageBuilder` menyediakan `.html()`, `.markdown()`, `.blocks()`, `.add()`,
-`.media()`, `.rtl()`, `.skipEntityDetection()`, `.build()`, dan `.buildDraft()`.
-`rich.draftHtml()`, `rich.draftMarkdown()`, dan `rich.draftBlocks()` menghasilkan
-konten draft-safe serta menolak upload `File` (draft dapat memakai file_id Telegram yang ada).
-Rich block builder mencakup
-paragraph/heading/pre/list/table/details/quote/map/media/buttons/thinking; block
-`thinking` hanya untuk `sendRichMessageDraft`. `InputMediaBuilder.livePhoto()` dan
-`InputPaidMediaBuilder.livePhoto()` membentuk payload media live photo. API raw modern lain tersedia lewat
-`ctx.api.sendMessageDraft()`, `ctx.api.answerGuestQuery()`, `ctx.api.editEphemeralMessage*()`
-dan `ctx.api.deleteEphemeralMessage()`. Tipe resmi Telegram dapat diakses sebagai
-`TelegramTypes`; rich input types diekspor langsung.
+Namespace `TelegramTypes` mengekspor tipe object Telegram. Alias yang berguna: `TelegramMethodName`, `TelegramMethodPayload<M>`, `TelegramMethodResult<M>`, `TelegramApiMethods`, dan `TelegramApiPayloads`. Proxy runtime juga menerima `ctx.api.metodeApaPun({ ...payload })` untuk metode baru, tetapi shorthand dinamis ini tidak memvalidasi schema saat runtime. Pengecekan TypeScript terjadi ketika compile saja. Jalankan `npm run typecheck` untuk memeriksa deklarasi dan contoh consumer.
+
+Deklarasi ini vendored dari `@grammyjs/types@5.0.0` berlisensi MIT (lihat [`NOTICE.md`](NOTICE.md) dan lisensi di folder types); tidak ada dependency runtime baru. Referensi/changelog Telegram resmi—bukan package vendored—tetap otoritas saat ada perbedaan field, izin, atau batasan.
+
+#### Batas payload dan pemecahan masalah
+
+Schema tipe Bot API 10.3 mencatat batas Rich Message berikut: **32.768 karakter UTF-8**, **500 block** (termasuk konten nested/list/tabel/kutipan/details), **16 level nesting**, **50 attachment media**, dan **20 kolom tabel**. Block map memakai zoom 0–24 dan lebar/tinggi 0–10.000; block tombol berisi 1–8 tombol. Batas Telegram dapat berubah, jadi cek [referensi resmi](https://core.telegram.org/bots/api) sebelum membuat payload besar. Server Telegram tetap validator terakhir.
+
+Error yang umum:
+
+- `RICH_MESSAGE_VIDEO_INVALID`: server yang diuji menolak GIF pada block Rich Message `animation`; coba MP4. Endpoint standalone `sendAnimation` menerima GIF tersebut.
+- `BOT_NOT_ADMIN` pada pesan ephemeral: respons ini terkait izin/kelayakan Telegram, bukan bukti bahwa bentuk JSON salah. Periksa akses bot/chat dan syarat metode resmi.
+- `chat not found`: pada private chat, penerima biasanya perlu membuka bot dan menekan **Start** sebelum bot dapat mengirim pesan.
+- Error upload: bungkus bytes/path/stream dengan `File`/`InputFile` dan pastikan tipe helper cocok dengan file.
+
+#### Hasil live test dan batasan
+
+Pada 2026-09-28, smoke test live dengan bot yang diberikan pengguna berhasil untuk rich blocks, HTML, Markdown, custom emoji bergerak, draft teks/rich, multipart media, blok photo/audio/document/video/voice-note, collage/slideshow, live photo, GIF melalui `sendAnimation`, dan HTML media reference. Ephemeral `sendMessage`/`sendRichMessage` ditolak Telegram dengan `BOT_NOT_ADMIN`; paid media tidak dikirim karena dapat melibatkan Stars; callback tidak diklik; seluruh 185 endpoint tidak dijalankan live. Rincian hasil dan batas cakupan ada di [`VERIFIKASI-MENDALAM.md`](VERIFIKASI-MENDALAM.md).
 
 <a id="keyboard"></a>
 ### 🔘 Keyboard & tombol
@@ -572,12 +767,12 @@ await bot.api.sendDiceCustom({ chat_id: 1, emoji: '🎲' });
 
 | Metrik | Nilai |
 |---|---|
-| 📦 Modul sumber | **16 file** di `lib/` |
-| 📝 Total baris kode | **±1.700** (tanpa build step) |
-| 🔌 Metode Bot API | **90+** — 75 shortcut bertipe + Proxy tanpa batas |
+| 📦 Modul sumber | **18 file** di `lib/` |
+| 📝 Total baris kode | **2.105** di `lib/` (tanpa build step) |
+| 🔌 Metode Bot API | **185 signature bertipe** lewat `api.callApi()` + dynamic Proxy |
 | ⌨️ Shortcut Context | **50+** (reply/edit/delete/admin/react…) |
-| 🧪 Test offline | **47/47 lulus**, termasuk transport HTTP lokal dan fitur Bot API 10.3 |
-| 🧩 Contoh siap jalan | **7** di `examples/` |
+| 🧪 Test offline | **48/48 lulus**, termasuk transport HTTP lokal dan fitur Bot API 10.3 |
+| 🧩 Contoh siap jalan | **8** di `examples/` |
 | 📦 Dependency runtime | **4** — semuanya terpakai & ter-test |
 
 ### ⬇️ Download & popularitas (live dari npm)
@@ -589,23 +784,27 @@ await bot.api.sendDiceCustom({ chat_id: 1, emoji: '🎲' });
 
 ### 📏 Peta ukuran modul (baris kode)
 
-```
-wizard.js      █████████████████████████ 247  ← form + tombol + edit/delete
-telebibz.js    ███████████████████▎      193  ← kelas utama & siklus hidup
-context.js     ███████████████████       190  ← ctx + 50-an shortcut
-composer.js    █████████████████▍        174  ← mesin middleware & filter
-api.js         ███████████████▍          154  ← 75 shortcut + Proxy + transformer
-net.js         ███████████▌              115  ← transport axios + multipart
-menus.js       █████████                  90  ← Menu/MenuContainer
-keyboard.js    ████████▎                  83  ← btn/url/kb + kelas fluent
-ratelimit.js   ██████                     61  ← autoRetry · throttler · limiter
-runner.js      ████▌                      45  ← polling tahan-409
-file.js        ████                       41  ← InputFile + InputMediaBuilder
-logger.js      ███▊                       38  ← log + banner
-session.js     ███▌                       36  ← session swappable
-errors.js      ███▌                       35  ← humanize error 🇮
-broadcast.js   ███▌                       35  ← blast aman rate-limit
-inline-query.js██▊                        28  ← matcher + builder hasil
+Angka berikut dihitung dari source terkini `lib/*.js`; ini informasi source, bukan ukuran bundle.
+
+```text
+context.js          250  accessor Context, reply, edit dan helper
+wizard.js           247  form terpandu, tombol, mode edit/delete
+telebibz.js         209  kelas bot, lifecycle dan dispatch update
+telegram-methods.js 192  registry runtime 185 nama metode Bot API
+composer.js         185  komposisi middleware dan filter
+rich.js             175  builder Rich Message, entity dan block
+api.js              168  adapter API, Proxy dan transformer
+net.js              115  transport HTTP dan multipart upload
+menus.js              90  Menu dan MenuContainer
+keyboard.js           83  builder keyboard dan fluent class
+ratelimit.js          74  retry, throttler dan limiter
+logger.js             68  log dan banner boot
+runner.js             54  polling dan retry
+file.js               48  File/InputFile dan media builder
+session.js            44  session storage swappable
+errors.js             35  terjemahan error
+broadcast.js          35  helper broadcast
+inline-query.js       33  pencocokan inline dan builder hasil
 ```
 
 ### 🗺️ Kesehatan repo
@@ -643,24 +842,23 @@ Jalankan dengan `BOT_TOKEN=123:abc node examples/01-quickstart.js`.
 ## 🔬 Test & Bukti Live
 
 ```bash
-npm test       # 47 test offline (mock + HTTP server lokal), tanpa token Telegram
+npm test       # 48 test offline (mock + HTTP server lokal), tanpa token Telegram
 npm run typecheck # cek declaration TypeScript + payload method-specific
 ```
 
-Audit saat ini tidak membutuhkan token Telegram. Versi repo sebelumnya mencatat
-**30 test offline + 10 test live** pada `@xbibzrat_bot`; pengujian live tersebut
-bersifat historis dan tidak diulang pada audit ini. Lihat [`VERIFIKASI-MENDALAM.md`](VERIFIKASI-MENDALAM.md)
-untuk matriks test, perbandingan Bot API 10.3, dan batasan yang tersisa.
+48 test otomatis dan `npm run typecheck` berjalan offline dengan mock tanpa token bot. Secara terpisah dilakukan live smoke test pada bot uji milik pengguna: rich blocks, HTML/Markdown, custom emoji bergerak, draft, blok media, collage/slideshow, live photo, dan referensi media multipart berhasil. Pengiriman ephemeral ditolak Telegram dengan `BOT_NOT_ADMIN`; paid media dan semua 185 endpoint tidak diuji live. Lihat [`VERIFIKASI-MENDALAM.md`](VERIFIKASI-MENDALAM.md) untuk matriks lengkap, batasan, serta hasil yang gagal.
 
 Log debug: `DEBUG=telebibz:net,telebibz:ratelimit node botkamu.js`.
 
 <a id="struktur"></a>
-## 📂 Struktur Repo (16 file inti)
+## 📂 Struktur Repo (18 modul JavaScript + tipe API vendored)
 
 | File | Peran |
 |---|---|
 | `lib/net.js` | transport axios keep-alive + multipart `attach://` |
 | `lib/api.js` | metode Bot API + Proxy segala metode + transformer |
+| `lib/rich.js` | entity Rich Message, builder block, helper draft-safe |
+| `lib/telegram-methods.js` | registry 185 nama metode Bot API |
 | `lib/composer.js` | middleware, filter `on('message:photo')`, `errorBoundary` |
 | `lib/context.js` | objek ctx + 50-an pintasan reply/edit/delete/callback |
 | `lib/session.js` | sesi per user:chat (storage swappable) |
@@ -674,11 +872,13 @@ Log debug: `DEBUG=telebibz:net,telebibz:ratelimit node botkamu.js`.
 | `lib/inline-query.js` | matcher query + builder hasil inline |
 | `lib/errors.js` | humanisasi error + saran |
 | `lib/logger.js` | log berbingkai + banner boot |
-| `index.js` / `index.d.ts` | pintu ekspor + tipe TypeScript |
+| `types/telegram-bot-api/` | tipe Bot API vendored (MIT), tanpa kode runtime |
+| `index.js` / `index.d.ts` | ekspor dan surface method/payload bertipe |
 
 <a id="changelog"></a>
 ## 🕐 Changelog
 
+- **Unreleased — Bot API 10.3** — rich message, emoji bergerak, draft, live photo, payload bertipe untuk 185 metode; 48 test offline dan live verification lebih luas. Detail: [`CHANGELOG.md`](CHANGELOG.md).
 - **3.1.0** — wizard: tombol pilihan (reply/inline), mode `edit`/`delete`, cleanup otomatis, helper programatis · test 24 → 30
 - **3.0.0** — parity grammY production-grade: axios keep-alive, transformer, menu, inline query, limiter
 - **2.0.0** — engine ditulis ulang dari nol, transport multipart, webhook Node murni

package/README.md

@@ -19,8 +19,8 @@ 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)
+[![tests](https://img.shields.io/badge/tests-48%2F48%20passing-brightgreen?style=for-the-badge&logo=checkmarx&logoColor=white)](#-testing--live-proof)
+[![size](https://img.shields.io/badge/code-2.1k%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)
 
@@ -38,7 +38,7 @@ dependencies that are *actually used*, and an Indonesia-first community.
 |---|---|---|
 | ⚡ [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) |
+| 🎛️ [Handlers & filters](#handlers) | 💬 [Context shortcuts](#context) | 🧱 [Rich Messages & Bot API 10.3](#rich-messages) |
 | ️ [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) |
@@ -66,6 +66,8 @@ dependencies that are *actually used*, and an Indonesia-first community.
 | Feature | grammY | telebibz |
 |---|:---:|:---:|
 | Proxy API for **any method** (auto-generated) | ✅ | ✅ |
+| **185 method-specific Bot API payload signatures** (`callApi`) | ✅ | ✅ |
+| Rich Messages: blocks, entities, drafts, media, animated emoji | varies by API | ✅ built-in |
 | ~60 typed shortcuts (sendMessage, banChatMember…) | ✅ | ✅ |
 | Full Context (~70 shortcuts reply/edit/admin/react) | ✅ | ✅ |
 | Business flavor (`business_connection_id` automatic) | plugin | ✅ built-in |
@@ -89,7 +91,7 @@ dependencies that are *actually used*, and an Indonesia-first community.
 | 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) |
+| TypeScript | ✅ full | ✅ method-specific types for 185 Bot API methods |
 | Documentation language | en | **🇬🇧 + 🇮🇩** |
 
 <a id="install"></a>
@@ -267,62 +269,256 @@ Business accounts: replies inside a business context automatically carry
 `business_connection_id`.
 
 <a id="rich-messages"></a>
-### 🧱 Rich Messages, drafts, live photos & ephemeral messages (Bot API 10.3)
+### 🧱 Rich Messages, animated emoji, media & drafts (Bot API 10.3)
 
-TeleBibz includes rich-message builders and Context helpers. All **185 Bot API
-methods** are also available through typed `ctx.api.callApi(method, payload)`;
-the proxy accepts newer methods using an object payload.
+A **Rich Message** is Telegram's structured message format: one message can combine rich-text entities, headings, lists, quotations, tables, maps, buttons, media blocks, and more. TeleBibz provides builders and Context shortcuts; the official [Telegram Bot API reference](https://core.telegram.org/bots/api) remains authoritative for current limits and eligibility.
+
+> **Coverage note:** the package includes a type-level registry for **185 Bot API methods** and typed payloads through `api.callApi()`. This does not mean all 185 endpoints can be safely or meaningfully tested live: many require real updates, admin rights, payments, or specific chats. See [`VERIFIKASI-MENDALAM.md`](VERIFIKASI-MENDALAM.md) for the live-test matrix and known limitations.
+
+#### 1. Choose exactly one content mode
+
+A rich message has exactly one content source: `html`, `markdown`, or `blocks`. Optional settings such as `media`, `is_rtl`, and `skip_entity_detection` do not count as content modes.
+
+```js
+const { TeleBibz, rich, RichMessageBuilder } = require('@xbibzlibrary/telebibz');
+const bot = new TeleBibz(process.env.BOT_TOKEN);
+
+bot.cmd('rich', async (ctx) => {
+  const message = rich.blocks([
+    rich.heading('Weekly report', 2),
+    rich.paragraph(['Orders: ', rich.bold('42'), ' · status ', rich.italic('ready')]),
+    rich.table([
+      [
+        { text: 'Metric', is_header: true, align: 'left', valign: 'middle' },
+        { text: 'Value', is_header: true, align: 'right', valign: 'middle' },
+      ],
+      [
+        { text: 'Revenue', align: 'left', valign: 'middle' },
+        { text: '$1,250', align: 'right', valign: 'middle' },
+      ],
+    ], { bordered: true, striped: true, compact: true, caption: 'This week' }),
+    rich.details('More information', [rich.paragraph('This section can be expanded.')]),
+    rich.buttons([
+      rich.button('Open dashboard', { url: 'https://example.com' }, 'primary'),
+      rich.button('Acknowledge', { callback_data: 'report:ack' }, 'success'),
+    ], 'center'),
+  ]);
+  return ctx.replyWithRichMessage(message);
+});
+
+bot.launch();
+```
+
+The lower-level constructors are `rich.html(html, options)`, `rich.markdown(markdown, options)`, and `rich.blocks(blocks, options)`. `inputRichMessage(content, options)` validates that one content mode is selected. `RichMessageBuilder` is useful when assembling a message incrementally:
+
+```js
+const message = new RichMessageBuilder()
+  .blocks([rich.heading('Notice', 2)])
+  .add(rich.paragraph('More blocks can be appended.'))
+  .rtl(false)
+  .skipEntityDetection()
+  .build();
+await ctx.replyWithRichMessage(message);
+```
+
+Calling `.html()`, `.markdown()`, or `.blocks()` more than once on the same builder is an error: create a new builder when you want a different mode. `.media()` is intended for HTML/Markdown content that references media by `tg://...` links.
+
+#### 2. Rich-text entities
+
+Rich text can be a plain string, an array mixing strings and entity objects, or a nested rich-text object. Common entity helpers include:
+
+| Helper | Entity produced | Typical use |
+|---|---|---|
+| `rich.bold(text)`, `rich.italic(text)`, `rich.underline(text)`, `rich.strikethrough(text)` | emphasis | inline formatting |
+| `rich.spoiler(text)`, `rich.marked(text)`, `rich.code(text)` | spoiler / marked / code | hidden or technical text |
+| `rich.subscript(text)`, `rich.superscript(text)` | script position | formulas and references |
+| `rich.dateTime(text, unixTime, format)` | date/time | localized or relative timestamp |
+| `rich.url(text, url)`, `rich.email(text, email)`, `rich.phone(text, phone)` | explicit links/contact | clickable or recognized values |
+| `rich.mention(text, username)`, `rich.textMention(text, user)` | user mention | username or user object |
+| `rich.hashtag(text, value)`, `rich.cashtag(text, value)`, `rich.botCommand(text, value)` | Telegram entities | searchable tags/commands |
+| `rich.customEmoji(customEmojiId, alternativeText)` | custom emoji | standard or animated custom emoji |
+| `rich.mathText(expression)`, `rich.anchorText(name)`, `rich.anchorLink(text, name)`, `rich.reference(text, name)`, `rich.referenceLink(text, name)` | formula/navigation | structured long-form text |
+| `rich.buttonText(text, action, style)` | inline rich-text button entity | a button inside a rich-text run |
+
+Example with an animated custom emoji (use a **real** custom emoji ID that Telegram returns for your bot):
+
+```js
+const emojiId = 'CUSTOM_EMOJI_ID';
+const [sticker] = await ctx.api.callApi('getCustomEmojiStickers', {
+  custom_emoji_ids: [emojiId],
+});
+if (!sticker) throw new Error('Unknown custom emoji ID');
+await ctx.replyWithRichMessage(rich.blocks([
+  rich.paragraph(['Build status: ', rich.bold('passed'), ' ', rich.customEmoji(emojiId, '👍')]),
+]));
+```
+
+A regular Unicode emoji is not automatically an animated custom emoji. The custom ID must be valid and usable by the bot; Telegram may reject unavailable IDs or features the bot is not eligible to use.
+
+#### 3. Structured block catalog
+
+Each block helper returns an `InputRichBlock` object. Blocks can be nested where the schema permits it.
+
+| Block family | Helpers | Notes |
+|---|---|---|
+| Text | `paragraph(text)`, `heading(text, size)`, `pre(text, language)`, `footer(text)`, `divider()` | heading size is 1–6; preformatted blocks can name a language |
+| Math/navigation | `mathBlock(expression)`, `anchor(name)` | use the corresponding rich-text formula/reference helpers for inline content |
+| Lists/quotes | `list(items)`, `quote(blocks, credit)`, `expandableQuote(text, credit)`, `pullQuote(text, credit)` | a list item may be a string or a structured item; quotations can contain nested blocks |
+| Tables/disclosure | `table(cells, options)`, `details(summary, blocks, open)` | each cell supplies `align` and `valign`; options: `bordered`, `striped`, `compact`, `caption` |
+| Location | `map(location, zoom, width, height, caption, credit)` | `location` is `{ latitude, longitude }` |
+| Media | `animation(media, caption)`, `audio(media, caption)`, `document(media, caption)`, `photo(media, caption)`, `video(media, caption)`, `voiceNote(media, caption)` | `media` is an `InputMedia*` object; `File` uploads are collected recursively into multipart `attach://` fields |
+| Layout | `collage(blocks, caption, credit)`, `slideshow(blocks, caption, credit)` | compose allowed media blocks into a gallery or sequence |
+| Buttons | `buttons(buttons, align)`, `button(text, action, style)` | 1–8 buttons; alignment is `left`, `center`, or `right` |
+| Draft-only | `thinking(text)` | use only in `sendRichMessageDraft`, not a persisted rich message |
+
+For `table`, each cell should look like `{ text, align: 'left'|'center'|'right', valign: 'top'|'middle'|'bottom' }`; header cells may set `is_header: true`. A button action must provide exactly one supported action field, such as `url`, `callback_data`, `web_app`, `copy_text`, or `disabled`. `rich.button()` returns the button object for a buttons block. `rich.buttonText()` returns the distinct inline entity shape. Link style is only valid for callback buttons.
+
+#### 4. Uploading media inside rich messages
+
+Use Telegram `file_id`s for files already on Telegram, or wrap bytes/path/stream in `File` (or `InputFile`) for multipart upload:
+
+```js
+const fs = require('node:fs');
+const { File, InputMediaBuilder } = require('@xbibzlibrary/telebibz');
+const image = new File(fs.readFileSync('./hero.png'), 'hero.png');
+const video = new File(fs.readFileSync('./clip.mp4'), 'clip.mp4');
+
+await ctx.replyWithRichMessage(rich.blocks([
+  rich.paragraph('Uploaded media blocks:'),
+  rich.photo(InputMediaBuilder.photo(image)),
+  rich.video(InputMediaBuilder.video(video)),
+]));
+```
+
+HTML/Markdown can refer to media by a unique ID and a matching `media` entry:
+
+```js
+const photo = new File(fs.readFileSync('./hero.png'), 'hero.png');
+await ctx.replyWithRichMessage(rich.html(
+  '<b>Hero image</b><br><a href="tg://photo?id=hero">Open photo</a>',
+  { media: [{ id: 'hero', media: InputMediaBuilder.photo(photo) }] },
+));
+```
+
+A successful live smoke test confirmed nested multipart media, photo/audio/document/video/voice-note blocks, collage/slideshow, and a rich HTML media reference. On the tested Bot API server, an MP4 worked in a rich `animation` block; a GIF in that block returned `RICH_MESSAGE_VIDEO_INVALID`. The standalone `sendAnimation` method did accept the same GIF. If a rich animation block is rejected, try MP4. Live-photo video/photo pairing is a separate API operation, not an `InputRichBlock` type.
+
+#### 5. Drafts and streaming previews
+
+Drafts are temporary previews, not stored chat messages. Send a final message separately to persist the completed answer. `thinking` blocks are for rich drafts only. Draft helpers reject `File` uploads; use existing Telegram file IDs if a draft needs media.
 
 ```js
-const { rich, RichMessageBuilder } = require('@xbibzlibrary/telebibz');
-
-bot.cmd('report', (ctx) => ctx.replyWithRichMessage(rich.blocks([
-  rich.heading('Report', 2),
-  rich.paragraph(['Status: ', rich.bold('success')]),
-  rich.table([
-    [{ text: 'Item', align: 'left', valign: 'middle', is_header: true },
-     { text: 'Total', align: 'right', valign: 'middle', is_header: true }],
-    [{ text: 'Orders', align: 'left', valign: 'middle' },
-     { text: '3', align: 'right', valign: 'middle' }],
-  ], { bordered: true, striped: true, compact: true }),
-  rich.details('Notes', [rich.paragraph('Additional details')]),
-  rich.buttons([rich.button('Open', { url: 'https://example.com' }, 'primary')]),
-])));
-
-// HTML, Markdown, media blocks, lists, quotes, maps, tables, collages,
-// slideshows, buttons and rich-text entities (bold/customEmoji/dateTime, etc.) are supported.
-const content = new RichMessageBuilder().markdown('**Hello!**').rtl().build();
-await ctx.replyWithRichMessage(content);
-
-// Live photo: both inputs may be Telegram file_ids or InputFile instances.
-await ctx.replyWithLivePhoto('video-file-id', 'photo-file-id', { caption: 'Moment' });
-
-// A draft is a temporary preview. Send the final rich message to persist it.
-await ctx.sendRichMessageDraft(1, rich.draftBlocks([
-  rich.paragraph('Writing…'), rich.thinking('Working'),
-]), { can_stop: true, keep_on_stop: true });
-await ctx.replyWithRichMessage(rich.markdown('**Final answer**'));
-
-// Ephemeral: visible only to a specific recipient.
-await ctx.replyEphemeral('A temporary private message', ctx.from.id);
-
-// Fully typed raw access to every Bot API method and its payload.
+bot.cmd('stream-preview', async (ctx) => {
+  const draftId = Date.now(); // non-zero and unique for this draft
+  await ctx.sendMessageDraft(draftId, 'Preparing a response…', { can_stop: true });
+  await ctx.sendRichMessageDraft(draftId + 1, rich.draftBlocks([
+    rich.paragraph(['Working on ', rich.bold('your report'), '…']),
+    rich.thinking('Collecting data'),
+  ]), { can_stop: true, keep_on_stop: true });
+  // Persist the final answer explicitly:
+  return ctx.replyWithRichMessage(rich.markdown('**Report ready**'));
+});
+```
+
+Draft constructors are `rich.draftHtml()`, `rich.draftMarkdown()`, `rich.draftBlocks()`, and `new RichMessageBuilder()...buildDraft()`. Their return types match `sendRichMessageDraft`'s no-new-upload schema. `sendMessageDraft` and `sendRichMessageDraft` also accept exact object payloads through `ctx.api.callApi()`.
+
+#### 6. Live photos, paid media, ephemeral messages, and editing
+
+**Live photo** sends a video and its corresponding still image. Both can be file IDs or `File`/`InputFile` values; URLs are not supported by the current method schema.
+
+```js
+await ctx.replyWithLivePhoto('VIDEO_FILE_ID', 'PHOTO_FILE_ID', { caption: 'A moment' });
+// Or raw typed API:
+await ctx.api.sendLivePhoto({ chat_id: ctx.chatId, live_photo: videoFile, photo: photoFile });
+```
+
+`InputMediaBuilder.livePhoto(video, photo)` and `InputPaidMediaBuilder.livePhoto(video, photo)` build media objects. `sendPaidMedia` requires a `star_count` from 1 to 25,000:
+
+```js
+const fs = require('node:fs');
+const { File, InputPaidMediaBuilder } = require('@xbibzlibrary/telebibz');
+const paidPhoto = new File(fs.readFileSync('./paid.png'), 'paid.png');
+await ctx.api.callApi('sendPaidMedia', {
+  chat_id: ctx.chatId,
+  star_count: 1,
+  media: [InputPaidMediaBuilder.photo(paidPhoto)],
+  caption: 'Paid photo sample',
+});
+```
+
+This is a real payment/paywall feature: do not test it on users without consent, and account for Telegram Stars before publishing paid content.
+
+An **ephemeral message** is addressed to a recipient using `ephemeral_message_parameters`; availability depends on Telegram's bot/chat eligibility and permissions. Context helpers include `replyEphemeral(text, receiverUserId)`, `editEphemeralMessageText`, `editEphemeralRichMessage`, `editEphemeralMessageMedia`, `editEphemeralMessageCaption`, `editEphemeralMessageReplyMarkup`, and `deleteEphemeralMessage`.
+
+```js
+await ctx.replyEphemeral('Temporary notice', ctx.from.id);
+const sent = await ctx.api.callApi('sendRichMessage', {
+  chat_id: ctx.chatId,
+  rich_message: rich.blocks([rich.paragraph('Private rich preview')]),
+  ephemeral_message_parameters: { receiver_user_id: ctx.from.id },
+});
+// If Telegram returns an ephemeral_message_id, it can be used with the edit/delete helpers.
+if (sent.ephemeral_message_id) {
+  await ctx.editEphemeralRichMessage(ctx.from.id, sent.ephemeral_message_id,
+    rich.blocks([rich.paragraph('Updated temporary notice')]));
+}
+```
+
+Telegram can reject requests with `BOT_NOT_ADMIN` or other permission errors; inspect the returned `ApiError` and do not treat a local payload test as proof of eligibility.
+
+Rich edits use `ctx.editRichMessage(content, extra)`. The underlying Bot API is `editMessageText` with `rich_message` and a target `chat_id`/`message_id` (or `inline_message_id`). These operations modify an existing message; use a message created for testing when validating them.
+
+#### 7. Context helpers and modern Bot API methods
+
+| Helper | Effect / arguments |
+|---|---|
+| `ctx.replyWithRichMessage(content, extra?)` | sends a persisted rich message to the current chat |
+| `ctx.editRichMessage(content, extra?)` | rich-edits the current message; callback and inline targets are handled |
+| `ctx.replyWithLivePhoto(video, photo, extra?)` | sends a live photo to the current chat |
+| `ctx.sendMessageDraft(draftId, text, extra?)` | streams a plain-text preview |
+| `ctx.sendRichMessageDraft(draftId, richMessage, extra?)` | streams a rich preview |
+| `ctx.replyEphemeral(text, receiverUserId, extra?)` | sends an ephemeral plain-text message |
+| `ctx.guestQueryId`, `ctx.answerGuestQuery(result)` | handles a real incoming `guest_message` update |
+| `ctx.editEphemeralRichMessage(...)`, `ctx.deleteEphemeralMessage(...)` | edits/deletes a recipient's ephemeral message |
+
+Guest query answers require the `guest_query_id` from an actual incoming guest update; it cannot be fabricated for a meaningful live test. Inline rich articles can be built with `iq.richArticle(id, title, richMessage, extra)` and returned while handling an actual inline query.
+
+#### 8. Complete typed Bot API access
+
+All **185 method names and payload signatures** in the vendored Bot API schema are available in TypeScript through `api.callApi()` and `api.raw()`:
+
+```js
+// JavaScript or TypeScript: method name + payload object
 await ctx.api.callApi('sendRichMessage', {
   chat_id: ctx.chatId,
-  rich_message: rich.html('<b>Rich HTML</b>'),
+  rich_message: rich.markdown('**Hello**'),
+});
+
+await ctx.api.callApi('sendMessageDraft', {
+  chat_id: ctx.chatId,
+  draft_id: Date.now(),
+  text: 'Preview',
+  can_stop: false,
 });
 ```
 
-`RichMessageBuilder` supports `.html()`, `.markdown()`, `.blocks()`, `.add()`,
-`.media()`, `.rtl()`, `.skipEntityDetection()`, `.build()`, and `.buildDraft()`.
-`rich.draftHtml()`, `rich.draftMarkdown()`, and `rich.draftBlocks()` return draft-safe content and reject `File` uploads (drafts may use existing Telegram file IDs). Rich block helpers cover
-paragraphs, headings, code, lists, tables, details, quotations, maps, media,
-buttons, and thinking. `InputMediaBuilder.livePhoto()` and
-`InputPaidMediaBuilder.livePhoto()` construct live-photo media payloads. The
-`thinking` block is only valid in `sendRichMessageDraft`. Other modern methods are available via
-`ctx.api.sendMessageDraft()`, `ctx.api.answerGuestQuery()`,
-`ctx.api.editEphemeralMessage*()`, and `ctx.api.deleteEphemeralMessage()`.
-Telegram types are available under `TelegramTypes`; rich input types are exported directly.
+The `TelegramTypes` namespace exports the vendored Telegram object types. Useful type aliases include `TelegramMethodName`, `TelegramMethodPayload<M>`, `TelegramMethodResult<M>`, `TelegramApiMethods`, and `TelegramApiPayloads`. The runtime proxy also permits `ctx.api.anyMethod({ ...payload })` for newly added methods, but that dynamic shorthand has no runtime schema validation. TypeScript checks happen at compile time only. Run `npm run typecheck` to validate declarations and consumer examples.
+
+The declarations are vendored from `@grammyjs/types@5.0.0` under MIT (see [`NOTICE.md`](NOTICE.md) and the vendored license); they add no runtime dependency. Telegram's official reference/changelog—not the vendored package—remains the authority when a field, permission, or limit differs.
+
+#### Limits and troubleshooting
+
+The Bot API 10.3 type schema documents these Rich Message ceilings: **32,768 UTF-8 characters**, **500 blocks** (including nested/list/table/quotation/details content), **16 nesting levels**, **50 media attachments**, and **20 table columns**. Map blocks use zoom 0–24 and width/height 0–10,000; the buttons block allows 1–8 buttons. Telegram can update limits, so check the [official reference](https://core.telegram.org/bots/api) before building large payloads. The server remains the final validator.
+
+Common failures:
+
+- `RICH_MESSAGE_VIDEO_INVALID`: the tested server rejected a GIF in a Rich Message `animation` block; try MP4. The standalone `sendAnimation` endpoint accepted the GIF.
+- `BOT_NOT_ADMIN` on ephemeral sends: this is a Telegram eligibility/permission response, not proof that the JSON shape is invalid. Verify bot/chat access and official method requirements.
+- `chat not found`: in a private chat, the user usually needs to open the bot and press **Start** before the bot can initiate a message.
+- Upload errors: wrap bytes, paths, or streams in `File`/`InputFile`; confirm the media helper's type matches the file.
+
+#### Live verification and limits
+
+On 2026-09-28, a live smoke test against a user-provided bot succeeded for rich blocks, HTML, Markdown, animated custom emoji, plain/rich drafts, multipart media, photo/audio/document/video/voice-note blocks, collage/slideshow, live photo, GIF via `sendAnimation`, and HTML media references. Ephemeral `sendMessage`/`sendRichMessage` failed with Telegram's `BOT_NOT_ADMIN`; paid media was not sent because it can involve Stars; callback buttons were not clicked; all 185 endpoints were not exercised live. See [`VERIFIKASI-MENDALAM.md`](VERIFIKASI-MENDALAM.md) for the exact outcomes and test boundaries.
 
 <a id="keyboards"></a>
 ### 🔘 Keyboards & buttons
@@ -570,12 +766,12 @@ await bot.api.sendDiceCustom({ chat_id: 1, emoji: '🎲' });
 
 | 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 |
+| 📦 Source modules | **18 files** in `lib/` |
+| 📝 Total lines of code | **2,105** in `lib/` (no build step) |
+| 🔌 Bot API methods | **185 typed method signatures** via `api.callApi()` + dynamic Proxy |
 | ⌨️ Context shortcuts | **50+** (reply/edit/delete/admin/react…) |
-| 🧪 Offline tests | **47/47 passing**, including local HTTP transport and Bot API 10.3 tests |
-| 🧩 Ready examples | **7** in `examples/` |
+| 🧪 Offline tests | **48/48 passing**, including local HTTP transport and Bot API 10.3 tests |
+| 🧩 Ready examples | **8** in `examples/` |
 | 📦 Runtime dependencies | **4** — all used, all tested |
 
 ### ⬇️ Downloads & popularity (live from npm)
@@ -587,23 +783,27 @@ await bot.api.sendDiceCustom({ chat_id: 1, emoji: '🎲' });
 
 ### 📏 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
+The figures below are generated from the current `lib/*.js` source. They are informational, not bundle-size measurements.
+
+```text
+context.js          250  Context accessors, replies, edits and helpers
+wizard.js           247  Guided forms, buttons, edit/delete modes
+telebibz.js         209  Bot class, lifecycle, update dispatch
+telegram-methods.js 192  Runtime registry for 185 API method names
+composer.js         185  Middleware composition and filters
+rich.js             175  Rich Message, entity and block builders
+api.js              168  Typed API adapters, Proxy and transformers
+net.js              115  HTTP transport and multipart upload
+menus.js              90  Menu and MenuContainer
+keyboard.js           83  Keyboard builders and fluent classes
+ratelimit.js          74  Retry, throttler and limiter
+logger.js             68  Logs and boot banner
+runner.js             54  Polling and retry handling
+file.js               48  File/InputFile and media builders
+session.js            44  Swappable session storage
+errors.js             35  Error translations
+broadcast.js          35  Broadcast helper
+inline-query.js       33  Inline matching and result builders
 ```
 
 ### 🗺️ Repo health
@@ -641,24 +841,23 @@ Run any of them with `BOT_TOKEN=123:abc node examples/01-quickstart.js`.
 ## 🔬 Testing & Live Proof
 
 ```bash
-npm test          # 47 offline checks, including local HTTP transport + Bot API 10.3 tests
+npm test          # 48 offline checks, including local HTTP transport + Bot API 10.3 tests
 npm run typecheck # verify declarations and method-specific Bot API payload types
 ```
 
-The current audit needs no Telegram token. An earlier release of this repository
-records **30 offline + 10 live checks** on `@xbibzrat_bot`; that live run is historical
-and was not repeated in the current audit. See [`VERIFIKASI-MENDALAM.md`](VERIFIKASI-MENDALAM.md)
-for the test matrix, Bot API 10.3 comparison, and remaining limitations.
+The 48 automated checks and `npm run typecheck` are offline/mocked and do not need a bot token. A separate live smoke test was performed with the owner's test bot: rich blocks, HTML/Markdown, animated custom emoji, drafts, media blocks, collage/slideshow, live photo, and multipart media references passed. Ephemeral sends were rejected by Telegram with `BOT_NOT_ADMIN`; paid media and all 185 endpoints were not tested live. See [`VERIFIKASI-MENDALAM.md`](VERIFIKASI-MENDALAM.md) for the exact matrix, known limits, and failures.
 
 Debug logging: `DEBUG=telebibz:net,telebibz:ratelimit node yourbot.js`.
 
 <a id="structure"></a>
-## 📂 Repo Structure (16 core files)
+## 📂 Repo Structure (18 JavaScript modules + vendored API types)
 
 | File | Role |
 |---|---|
 | `lib/net.js` | axios keep-alive transport + multipart `attach://` |
 | `lib/api.js` | Bot API methods + any-method Proxy + transformers |
+| `lib/rich.js` | Rich Message entities, block builders, draft-safe helpers |
+| `lib/telegram-methods.js` | registry of 185 Bot API method names |
 | `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) |
@@ -672,11 +871,13 @@ Debug logging: `DEBUG=telebibz:net,telebibz:ratelimit node yourbot.js`.
 | `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 |
+| `types/telegram-bot-api/` | vendored Bot API types (MIT); no runtime code |
+| `index.js` / `index.d.ts` | export door + typed method/payload surface |
 
 <a id="changelog"></a>
 ## 🕐 Changelog
 
+- **Unreleased — Bot API 10.3** — rich messages, animated emoji, drafts, live photos, all 185 typed method payloads; 48 offline checks and richer live verification. Details: [`CHANGELOG.md`](CHANGELOG.md).
 - **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

package/index.d.ts

@@ -1,6 +1,6 @@
 // Public TypeScript surface for @xbibzlibrary/telebibz.
 import type { ApiMethods, Opts } from './types/telegram-bot-api/methods.js';
-import type { InputRichBlock, InputRichMessage, InputRichMessageMedia } from './types/telegram-bot-api/rich.js';
+import type { InputRichBlock, InputRichBlockButtons, InputRichMessage, InputRichMessageMedia, RichMessageButton, RichTextButton } from './types/telegram-bot-api/rich.js';
 export * as TelegramTypes from './types/telegram-bot-api/mod.js';
 export type * from './types/telegram-bot-api/rich.js';
 
@@ -267,6 +267,9 @@ export const rich: {
   draftHtml(html: string, options?: Partial<InputRichMessage<TelegramFileInput>>): TelegramMethodPayload<'sendRichMessageDraft'>['rich_message'];
   draftMarkdown(markdown: string, options?: Partial<InputRichMessage<TelegramFileInput>>): TelegramMethodPayload<'sendRichMessageDraft'>['rich_message'];
   draftBlocks(blocks: InputRichBlock<TelegramFileInput>[], options?: Partial<InputRichMessage<TelegramFileInput>>): TelegramMethodPayload<'sendRichMessageDraft'>['rich_message'];
+  button(text: string, action: Record<string, unknown>, style?: 'danger' | 'success' | 'primary' | 'link'): RichMessageButton;
+  buttonText(text: string, action: Record<string, unknown>, style?: 'danger' | 'success' | 'primary' | 'link'): RichTextButton;
+  buttons(buttons: RichMessageButton[], align?: 'left' | 'center' | 'right'): InputRichBlockButtons;
   block(type: string, props?: Record<string, unknown>): InputRichBlock<TelegramFileInput>;
   [builder: string]: (...args: any[]) => any;
 };

package/lib/rich.js

@@ -40,6 +40,19 @@ function block(type, props = {}) {
 
 const textEntity = (type, text, extra = {}) => ({ type, text, ...extra });
 const caption = (text, credit) => ({ text, ...(credit !== undefined ? { credit } : {}) });
+function richMessageButton(text, action, style) {
+  if (!action || typeof action !== 'object') throw new TypeError('rich.button() membutuhkan satu jenis aksi button');
+  const keys = ['url', 'callback_data', 'web_app', 'login_url', 'switch_inline_query', 'switch_inline_query_current_chat', 'switch_inline_query_chosen_chat', 'copy_text', 'disabled'];
+  const defined = keys.filter((key) => Object.hasOwn(action, key));
+  if (defined.length !== 1) throw new TypeError('RichMessageButton harus memiliki tepat satu field aksi');
+  if (style !== undefined && !['danger', 'success', 'primary', 'link'].includes(style)) {
+    throw new TypeError('Style rich button harus danger, success, primary, atau link');
+  }
+  if (style === 'link' && defined[0] !== 'callback_data') {
+    throw new TypeError('Style link hanya didukung pada rich callback button');
+  }
+  return { text, ...action, ...(style ? { style } : {}) };
+}
 
 const rich = {
   html: (html, options = {}) => inputRichMessage({ html: String(html) }, options),
@@ -76,19 +89,8 @@ const rich = {
   anchorLink: (text, anchorName) => textEntity('anchor_link', text, { anchor_name: anchorName }),
   reference: (text, name) => textEntity('reference', text, { name }),
   referenceLink: (text, referenceName) => textEntity('reference_link', text, { reference_name: referenceName }),
-  button: (text, action, style) => {
-    if (!action || typeof action !== 'object') throw new TypeError('rich.button() membutuhkan satu jenis aksi button');
-    const keys = ['url', 'callback_data', 'web_app', 'login_url', 'switch_inline_query', 'switch_inline_query_current_chat', 'switch_inline_query_chosen_chat', 'copy_text', 'disabled'];
-    const defined = keys.filter((key) => Object.hasOwn(action, key));
-    if (defined.length !== 1) throw new TypeError('RichMessageButton harus memiliki tepat satu field aksi');
-    if (style !== undefined && !['danger', 'success', 'primary', 'link'].includes(style)) {
-      throw new TypeError('Style rich button harus danger, success, primary, atau link');
-    }
-    if (style === 'link' && defined[0] !== 'callback_data') {
-      throw new TypeError('Style link hanya didukung pada rich callback button');
-    }
-    return { type: 'button', button: { text, ...action, ...(style ? { style } : {}) } };
-  },
+  button: (text, action, style) => richMessageButton(text, action, style),
+  buttonText: (text, action, style) => ({ type: 'button', button: richMessageButton(text, action, style) }),
 
   // InputRichBlock builders.
   paragraph: (text) => block('paragraph', { text }),
@@ -130,6 +132,9 @@ const rich = {
   video: (video, captionText, credit) => block('video', { video, ...(captionText !== undefined ? { caption: caption(captionText, credit) } : {}) }),
   voiceNote: (voiceNote, captionText, credit) => block('voice_note', { voice_note: voiceNote, ...(captionText !== undefined ? { caption: caption(captionText, credit) } : {}) }),
   buttons: (buttons, align) => {
+    if (!Array.isArray(buttons) || buttons.length < 1 || buttons.length > 8) {
+      throw new RangeError('rich.buttons(): harus berisi 1–8 button');
+    }
     if (align !== undefined && !['left', 'center', 'right'].includes(align)) {
       throw new TypeError('rich.buttons(): align harus left, center, atau right');
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xbibzlibrary/telebibz",
-  "version": "3.1.3",
+  "version": "3.1.4",
   "description": "Telegram Bot API 10.3 framework: all 185 methods with typed payloads, rich messages, live photos, drafts, ephemeral messages, inline queries, sessions, webhooks, menus and wizards. Xbibz Technology ID",
   "main": "index.js",
   "types": "index.d.ts",

package/test/audit.test.js

@@ -261,7 +261,8 @@ async function main() {
     assert.equal(message.blocks[2].items[0].blocks[0].text, 'item satu');
     assert.equal(message.blocks[3].is_compact, true);
     assert.equal(message.blocks[4].is_open, true);
-    assert.equal(message.blocks[5].buttons[0].button.callback_data, 'ok');
+    assert.equal(message.blocks[5].buttons[0].callback_data, 'ok');
+    assert.deepEqual(rich.buttonText('Inline', { callback_data: 'inline' }), { type: 'button', button: { text: 'Inline', callback_data: 'inline' } });
     assert.deepEqual(new RichMessageBuilder().add(rich.paragraph('ok')).rtl().build(), { blocks: [{ type: 'paragraph', text: 'ok' }], is_rtl: true });
     assert.deepEqual(new RichMessageBuilder().markdown('draft').buildDraft(), { markdown: 'draft' });
     assert.deepEqual(rich.draftBlocks([rich.paragraph('partial'), rich.thinking('working')]), { blocks: [{ type: 'paragraph', text: 'partial' }, { type: 'thinking', text: 'working' }] });
@@ -269,11 +270,45 @@ async function main() {
     assert.throws(() => inputRichMessage({ html: 'x', markdown: 'y' }), /tepat satu/);
     assert.throws(() => rich.heading('bad', 7), /1–6/);
     assert.throws(() => rich.button('Link', { url: 'https://example.com' }, 'link'), /callback button/);
-    assert.throws(() => rich.buttons([], 'justify'), /align/);
+    assert.throws(() => rich.buttons([rich.button('OK', { callback_data: 'ok' })], 'justify'), /align/);
     assert.deepEqual(InputMediaBuilder.livePhoto('video', 'photo'), { type: 'live_photo', media: 'video', photo: 'photo' });
     assert.deepEqual(InputPaidMediaBuilder.livePhoto('video', 'photo'), { type: 'live_photo', media: 'video', photo: 'photo' });
   });
 
+  await test('Seluruh family RichText dan InputRichBlock builder memancarkan discriminant schema', () => {
+    const { rich } = require('..');
+    const entities = [
+      rich.bold('x'), rich.italic('x'), rich.underline('x'), rich.strikethrough('x'), rich.spoiler('x'),
+      rich.subscript('x'), rich.superscript('x'), rich.marked('x'), rich.code('x'), rich.dateTime('now', 1),
+      rich.textMention('x', { id: 1, is_bot: false, first_name: 'A' }), rich.customEmoji('emoji-id', '✨'),
+      rich.mathText('x'), rich.url('x', 'https://example.com'), rich.email('a@b.com', 'a@b.com'),
+      rich.phone('123', '+123'), rich.bankCard('1234', '1234'), rich.mention('@bot', 'bot'),
+      rich.hashtag('#test', 'test'), rich.cashtag('$TEST', 'TEST'), rich.botCommand('/start', 'start'),
+      rich.anchorText('anchor'), rich.anchorLink('link', 'anchor'), rich.reference('ref', 'anchor'),
+      rich.referenceLink('ref', 'anchor'), rich.buttonText('btn', { callback_data: 'cb' }),
+    ];
+    assert.deepEqual(entities.map((entity) => entity.type), [
+      'bold', 'italic', 'underline', 'strikethrough', 'spoiler', 'subscript', 'superscript', 'marked', 'code', 'date_time',
+      'text_mention', 'custom_emoji', 'mathematical_expression', 'url', 'email_address', 'phone_number', 'bank_card_number',
+      'mention', 'hashtag', 'cashtag', 'bot_command', 'anchor', 'anchor_link', 'reference', 'reference_link', 'button',
+    ]);
+    const media = (type) => ({ type, media: `${type}-file-id` });
+    const blocks = [
+      rich.paragraph('x'), rich.heading('x'), rich.pre('x'), rich.footer('x'), rich.divider(), rich.mathBlock('x'),
+      rich.anchor('a'), rich.list(['x']), rich.quote([rich.paragraph('x')]), rich.expandableQuote('x'), rich.pullQuote('x'),
+      rich.collage([rich.photo(media('photo'))]), rich.slideshow([rich.video(media('video'))]),
+      rich.table([[{ text: 'x', align: 'left', valign: 'middle' }]]), rich.details('s', [rich.paragraph('x')]),
+      rich.map({ latitude: 0, longitude: 0 }, 1, 100, 100), rich.animation(media('animation')), rich.audio(media('audio')),
+      rich.document(media('document')), rich.photo(media('photo')), rich.video(media('video')),
+      rich.voiceNote(media('voice_note')), rich.buttons([rich.button('x', { url: 'https://example.com' })]), rich.thinking('x'),
+    ];
+    assert.deepEqual(blocks.map((item) => item.type), [
+      'paragraph', 'heading', 'pre', 'footer', 'divider', 'mathematical_expression', 'anchor', 'list', 'blockquote',
+      'expandable_blockquote', 'pullquote', 'collage', 'slideshow', 'table', 'details', 'map', 'animation', 'audio',
+      'document', 'photo', 'video', 'voice_note', 'buttons', 'thinking',
+    ]);
+  });
+
   await test('Context memetakan rich send/edit, live photo, ephemeral dan draft ke payload Bot API', async () => {
     const { rich } = require('..');
     const calls = [];