@xbibzlibrary/telebibz 3.1.2 → 3.1.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased — Telegram Bot API 10.3
+
+- 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.
+
 ## 3.1.0 — wizard: tombol pilihan + mode edit/delete (2026-09-13)
 
 - **Wizard mendukung tombol pilihan**: `step.buttons` sebagai reply keyboard

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Xbibz Official
+Copyright (c) 2026 Xbibz Technology ID
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/NOTICE.md

@@ -1,12 +1,19 @@
 # NOTICE
 
-telebibz v2 adalah recode mandiri (JavaScript, 0 dependency) atas konsep arsitektur
-Bot API framework **grammY** (https://github.com/grammyjs/grammY} — lisensi MIT).
+## Arsitektur dan implementasi JavaScript
 
-Setiap berkas sumber di lib/ ditulis ulang: net (transport multipart), api, composer
-(middleware/routing filter), context, session, runner (polling tahan-409), file,
-keyboard, wizard, broadcast, errors, logger.
+telebibz adalah recode mandiri dengan konsep arsitektur yang terinspirasi oleh
+Bot API framework **grammY** (https://github.com/grammyjs/grammY, lisensi MIT).
+Implementasi JavaScript pada `lib/` ditulis untuk repo ini; referensi tersebut
+adalah atribusi konseptual.
 
-Terima kasih untuk grammY & komunitasnya atas rancangan API yang elegan.
-Tidak ada kode grammY yang disalin verbatim; pemakaian nama "grammY" bersifat
-atribusi konseptual sesuai semangat lisensi MIT.
+## Type declarations Bot API
+
+Berkas deklarasi TypeScript pada `types/telegram-bot-api/` diambil dari
+[`@grammyjs/types` v5.0.0](https://github.com/grammyjs/types), proyek grammY
+berlisensi MIT. Salinan lisensinya ada di [`types/telegram-bot-api/LICENSE`](types/telegram-bot-api/LICENSE).
+Deklarasi tersebut digunakan sebagai model tipe Bot API 10.3; implementasi
+runtime telebibz tetap menggunakan transport dan proxy milik repo ini.
+
+Terima kasih kepada grammY dan komunitas Telegram bot atas dokumentasi dan
+rancangan API yang membantu proyek ini.

package/README.id.md

@@ -26,7 +26,7 @@ produksi yang *benar-benar dipakai*, dokumentasi 🇮🇩 Indonesia-first, dan n
 
 <br>
 
-`//—Xbibz Official—//`
+`Xbibz Technology ID`
 
 </div>
 
@@ -138,13 +138,14 @@ BOT_TOKEN=123:abc node index.js
 ```
 
 ```
-┌──────────────────────────────────┐
-│  🤖 TeleBibz ON                   │
-│  bot      : @botkamu (id 123456) │
-│  mode     : long-polling          │
-│  library  : telebibz 3.1.0        │
-│  brand    : //—Xbibz Official—//  │
-└──────────────────────────────────┘
+◆ DEVELOPER  Xbibz Technology ID
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃  🤖 TeleBibz ON                       ┃
+┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+┃  bot      : @botkamu (id 123456)      ┃
+┃  mode     : long-polling              ┃
+┃  library  : telebibz 3.1.2 (Node.js)  ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 ✔ menunggu update… (Ctrl+C untuk berhenti)
 ```
 
@@ -266,6 +267,65 @@ callback, inline…) dengan accessor seragam: `chat`, `from`, `chatId`, `msgId`,
 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)
+
+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.
+
+```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).
+await ctx.api.callApi('sendRichMessage', {
+  chat_id: ctx.chatId,
+  rich_message: rich.html('<b>Rich HTML</b>'),
+});
+```
+
+`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.
+
 <a id="keyboard"></a>
 ### 🔘 Keyboard & tombol
 
@@ -516,7 +576,7 @@ await bot.api.sendDiceCustom({ chat_id: 1, emoji: '🎲' });
 | 📝 Total baris kode | **±1.700** (tanpa build step) |
 | 🔌 Metode Bot API | **90+** — 75 shortcut bertipe + Proxy tanpa batas |
 | ⌨️ Shortcut Context | **50+** (reply/edit/delete/admin/react…) |
-| 🧪 Test offline | **30/30 lulus**, tanpa jaringan |
+| 🧪 Test offline | **47/47 lulus**, termasuk transport HTTP lokal dan fitur Bot API 10.3 |
 | 🧩 Contoh siap jalan | **7** di `examples/` |
 | 📦 Dependency runtime | **4** — semuanya terpakai & ter-test |
 
@@ -575,6 +635,7 @@ inline-query.js██▊                        28  ← matcher + builder hasil
 | `05-kirim-file.js` | foto & dokumen dari buffer |
 | `06-menu.js` | menu interaktif + submenu |
 | `07-inline-query.js` | mode inline dengan builder hasil |
+| `08-rich-message.js` | rich messages, live photo, draft, ephemeral, dan raw method API |
 
 Jalankan dengan `BOT_TOKEN=123:abc node examples/01-quickstart.js`.
 
@@ -582,13 +643,14 @@ Jalankan dengan `BOT_TOKEN=123:abc node examples/01-quickstart.js`.
 ## 🔬 Test & Bukti Live
 
 ```bash
-npm test   # 30 kasus, TANPA jaringan (transport disuntik)
+npm test       # 47 test offline (mock + HTTP server lokal), tanpa token Telegram
+npm run typecheck # cek declaration TypeScript + payload method-specific
 ```
 
-Tervalidasi **30/30 offline + 10 live** pada bot produksi `@xbibzrat_bot`:
-getMe · keyboard berwarna & ikon animasi asli · upload multipart
-(photo+document) · edit keyboard · broadcast · deleteMessage · polling 409
-retry · wizard tombol & edit/delete.
+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.
 
 Log debug: `DEBUG=telebibz:net,telebibz:ratelimit node botkamu.js`.
 
@@ -624,16 +686,23 @@ Log debug: `DEBUG=telebibz:net,telebibz:ratelimit node botkamu.js`.
 
 > Detail lengkap di [`CHANGELOG.md`](CHANGELOG.md). Studi arsitektur mendalam: [`ANALISIS-telebibz.md`](ANALISIS-telebibz.md).
 
+<a id="publishing"></a>
+## 📦 Publikasi npm otomatis
+
+Workflow `.github/workflows/auto-publish.yml` menerbitkan saat ada push ke `main` (kecuali commit rilis yang memuat `[skip release]`) atau manual dari branch `main` lewat **Actions → Auto publish to npm → Run workflow** (workflow menolak dispatch dari branch lain). Sebelum mengaktifkannya, buat GitHub Actions Environment bernama `npm-release`, lalu tambahkan secret **`NPM_TOKEN`** yang berizin menerbitkan `@xbibzlibrary/telebibz`. Token tidak disimpan di repo.
+
+Workflow memilih patch berikutnya berdasarkan versi yang lebih tinggi antara repo dan versi terbaru npm; lalu menjalankan test runtime, typecheck TypeScript, pemeriksaan sintaks JS, simulasi paket, dan audit dependency produksi. Workflow mem-publish sebagai paket publik, commit bump `package.json`/lockfile, membuat tag anotasi `vX.Y.Z`, dan GitHub Release. Validasi yang gagal menghentikan workflow sebelum publish. Konfigurasi ditinjau secara lokal; verifikasi Actions nyata dan publish memerlukan akses repo dan secret tersebut.
+
 <a id="lisensi"></a>
 ## 📄 Lisensi
 
-**MIT** © Xbibz Official — arsitektur terinspirasi [grammY](https://grammy.dev) (MIT, lihat [`NOTICE.md`](NOTICE.md)).
+**MIT** © Xbibz Technology ID — arsitektur terinspirasi [grammY](https://grammy.dev) (MIT, lihat [`NOTICE.md`](NOTICE.md)).
 
 ---
 
 <div align="center">
 
-**Dibuat dengan ❤️ oleh //—Xbibz Official—//**
+**Dibuat dengan ❤️ oleh Xbibz Technology ID**
 
 Kalau telebibz membantumu, bintang ⭐ repo ini sangat berarti.
 

package/README.md

@@ -26,7 +26,7 @@ dependencies that are *actually used*, and an Indonesia-first community.
 
 <br>
 
-`//—Xbibz Official—//`
+`Xbibz Technology ID`
 
 </div>
 
@@ -137,13 +137,14 @@ BOT_TOKEN=123:abc node index.js
 ```
 
 ```
-┌──────────────────────────────────┐
-│  🤖 TeleBibz ON                   │
-│  bot      : @yourbot (id 123456) │
-│  mode     : long-polling          │
-│  library  : telebibz 3.1.0        │
-│  brand    : //—Xbibz Official—//  │
-└──────────────────────────────────┘
+◆ DEVELOPER  Xbibz Technology ID
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃  🤖 TeleBibz ON                       ┃
+┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+┃  bot      : @yourbot (id 123456)      ┃
+┃  mode     : long-polling              ┃
+┃  library  : telebibz 3.1.2 (Node.js)  ┃
+┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 ✔ waiting for updates… (Ctrl+C to stop)
 ```
 
@@ -265,6 +266,64 @@ inline…) with unified accessors: `chat`, `from`, `chatId`, `msgId`, `msg`,
 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)
+
+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.
+
+```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.
+await ctx.api.callApi('sendRichMessage', {
+  chat_id: ctx.chatId,
+  rich_message: rich.html('<b>Rich HTML</b>'),
+});
+```
+
+`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.
+
 <a id="keyboards"></a>
 ### 🔘 Keyboards & buttons
 
@@ -515,7 +574,7 @@ await bot.api.sendDiceCustom({ chat_id: 1, emoji: '🎲' });
 | 📝 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 |
+| 🧪 Offline tests | **47/47 passing**, including local HTTP transport and Bot API 10.3 tests |
 | 🧩 Ready examples | **7** in `examples/` |
 | 📦 Runtime dependencies | **4** — all used, all tested |
 
@@ -574,6 +633,7 @@ inline-query.js██▊                        28  ← matcher + result builder
 | `05-kirim-file.js` | photos & documents from buffers |
 | `06-menu.js` | interactive menus + submenus |
 | `07-inline-query.js` | inline mode with result builders |
+| `08-rich-message.js` | rich messages, live photo, drafts, ephemeral messages, raw API |
 
 Run any of them with `BOT_TOKEN=123:abc node examples/01-quickstart.js`.
 
@@ -581,13 +641,14 @@ 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)
+npm test          # 47 offline checks, including local HTTP transport + Bot API 10.3 tests
+npm run typecheck # verify declarations and method-specific Bot API payload types
 ```
 
-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.
+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.
 
 Debug logging: `DEBUG=telebibz:net,telebibz:ratelimit node yourbot.js`.
 
@@ -623,16 +684,23 @@ Debug logging: `DEBUG=telebibz:net,telebibz:ratelimit node yourbot.js`.
 
 > Full details in [`CHANGELOG.md`](CHANGELOG.md). Deep architecture study (🇮): [`ANALISIS-telebibz.md`](ANALISIS-telebibz.md).
 
+<a id="publishing"></a>
+## 📦 Automated npm publishing
+
+`.github/workflows/auto-publish.yml` publishes on pushes to `main` (except release commits tagged with `[skip release]`) or manually on the `main` branch via **Actions → Auto publish to npm → Run workflow** (the job rejects dispatches from other branches). Before enabling it, configure a GitHub Actions Environment named `npm-release` and add the repository/environment secret **`NPM_TOKEN`** with permission to publish `@xbibzlibrary/telebibz`. No credential is stored in this repository.
+
+The workflow derives the next patch version from the greater of the checked-in version and npm's latest version, then runs runtime tests, TypeScript checks, JS syntax checks, package dry-run, and production dependency audit. It publishes publicly, commits the bumped `package.json`/lockfile, creates an annotated `vX.Y.Z` tag, and a GitHub release. A failed validation stops before publish. The CI/release workflows have been reviewed locally; a real GitHub Actions run and npm publish still require repository access and the secret.
+
 <a id="license"></a>
 ## 📄 License
 
-**MIT** © Xbibz Official — architecture inspired by [grammY](https://grammy.dev) (MIT, see [`NOTICE.md`](NOTICE.md)).
+**MIT** © Xbibz Technology ID — architecture inspired by [grammY](https://grammy.dev) (MIT, see [`NOTICE.md`](NOTICE.md)).
 
 ---
 
 <div align="center">
 
-**Made with ❤️ by //—Xbibz Official—//**
+**Made with ❤️ by Xbibz Technology ID**
 
 If telebibz helps you, a ⭐ on this repo means a lot.
 

package/examples/08-rich-message.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const { TeleBibz, rich } = require('..');
+const bot = new TeleBibz(process.env.BOT_TOKEN);
+
+bot.cmd('rich', (ctx) => ctx.replyWithRichMessage(rich.blocks([
+  rich.heading('Ringkasan transaksi', 2),
+  rich.paragraph(['Status: ', rich.bold('berhasil'), ' · ', rich.customEmoji('5368324170671202286', '✅')]),
+  rich.table([
+    [{ text: 'Item', is_header: true, align: 'left', valign: 'middle' }, { text: 'Jumlah', is_header: true, align: 'right', valign: 'middle' }],
+    [{ text: 'Pesanan #42', align: 'left', valign: 'middle' }, { text: 'Rp 125.000', align: 'right', valign: 'middle' }],
+  ], { bordered: true, striped: true, compact: true }),
+  rich.details('Rincian', [rich.paragraph('Diproses otomatis oleh bot.')]),
+  rich.buttons([
+    rich.button('Buka web', { url: 'https://example.com' }, 'primary'),
+    rich.button('Konfirmasi', { callback_data: 'confirm:42' }, 'success'),
+  ], 'center'),
+])));
+
+bot.action(/^confirm:\d+$/, (ctx) => ctx.answerCallbackQuery('Terkonfirmasi'));
+
+bot.cmd('draft', async (ctx) => {
+  const draftId = 1;
+  await ctx.sendRichMessageDraft(draftId, rich.draftBlocks([
+    rich.paragraph('Sedang menyusun jawaban…'),
+    rich.thinking('Menganalisis permintaan'),
+  ]), { can_stop: true, keep_on_stop: true });
+  // Draft Bot API hanya preview sementara. Kirim pesan final agar tersimpan.
+  await ctx.replyWithRichMessage(rich.markdown('**Jawaban final**\nSelesai diproses.'));
+});
+
+bot.cmd('privat', (ctx) => ctx.replyEphemeral('Pesan ini hanya terlihat oleh Anda.', ctx.from.id));
+
+bot.launch();