@icanseeuanywhere/telekaf 4.16.4 → 4.16.6

package/README.md

@@ -26,40 +26,55 @@
 > This package tracks the latest Telegram Bot API releases and ships features ahead of the upstream package.
 > It is a drop-in replacement: just swap `npm install telegraf` → `npm install @icanseeuanywhere/telekaf` and change your imports from `'telegraf'` to `'@icanseeuanywhere/telekaf'`.
 
+
 ---
 
 ## 🆕 Rich Messages — Bot API 10.1
 
-> Added in **Bot API 10.1** (June 11, 2026). Rich Messages allow bots to send highly structured content — headings, lists, tables, media collages, code blocks, mathematical expressions, AI thinking blocks, and more — with seamless streaming support for AI-generated replies.
+> Added in **Bot API 10.1** (June 11, 2026). Rich Messages let bots send highly structured content using HTML or Markdown — headings, lists, tables, media collages, code blocks, math expressions, AI thinking blocks, and more — with streaming support for AI-generated replies.
 
 ### Table of Contents
 
-- [Quick Start](#rich-messages-quick-start)
+- [Quick Start](#quick-start)
 - [Sending Methods](#sending-methods)
-- [RichText — Inline Elements](#richtext--inline-elements)
-- [RichBlock — Block Elements](#richblock--block-elements)
-- [Builder API](#richmessagebuilder-api)
-- [RT Helpers](#rt-helpers)
+- [InputRichMessage Format](#inputrichmessage-format)
+- [RichHTMLBuilder](#richhtmlbuilder)
+  - [Text Formatting](#text-formatting-html)
+  - [Headings & Paragraphs](#headings--paragraphs)
+  - [Lists](#lists-html)
+  - [Code Blocks](#code-blocks)
+  - [Blockquote & Pull Quote](#blockquote--pull-quote)
+  - [Math](#math-html)
+  - [Media — Photo, Video, Audio](#media--photo-video-audio)
+  - [Collage & Slideshow](#collage--slideshow)
+  - [Map](#map)
+  - [Table](#table-html)
+  - [Details (Expandable)](#details-expandable)
+  - [Footnote References](#footnote-references-html)
+  - [Anchors & In-document Links](#anchors--in-document-links)
+  - [Special Elements](#special-elements)
+- [RichMarkdownBuilder](#richmarkdownbuilder)
 - [Streaming with sendRichMessageDraft](#streaming-with-sendrichmessagedraft)
+- [reply\_markup with Rich Messages](#reply_markup-with-rich-messages)
 - [Inline / Web App Queries](#inline--web-app-queries)
-- [TypeScript Usage](#typescript-usage-with-rich-messages)
+- [TypeScript](#typescript)
 
 ---
 
-### Rich Messages Quick Start
+### Quick Start
 
 ```ts
 import { Telegraf, RichMessage } from '@icanseeuanywhere/telekaf'
-const { RichMessageBuilder: Builder, RT } = RichMessage
+const { RichHTMLBuilder: HTML } = RichMessage
 
 const bot = new Telegraf(process.env.BOT_TOKEN)
 
 bot.command('hello', async (ctx) => {
-  const msg = new Builder()
-    .heading(1, RT.plain('Hello from Telegraf!'))
-    .paragraph(RT.plain('This is a '), RT.bold(RT.plain('rich message')), RT.plain(' example.'))
+  const msg = new HTML()
+    .heading(1, 'Hello World!')
+    .paragraph(HTML.bold('Rich Messages') + ' are now supported in Bot API 10.1.')
     .divider()
-    .preformatted('npm install telegraf', 'bash')
+    .ul('Headings', 'Lists', 'Tables', 'Media', 'Math', 'and more')
     .build()
 
   await ctx.sendRichMessage(msg)
@@ -74,478 +89,506 @@ process.once('SIGTERM', () => bot.stop('SIGTERM'))
 
 ### Sending Methods
 
-There are three ways to send rich messages:
-
 | Method | Description |
 |---|---|
 | `ctx.sendRichMessage(msg, extra?)` | Send a rich message to the current chat |
-| `ctx.replyWithRichMessageContent(msg, extra?)` | Reply to the current message with a rich message |
-| `ctx.sendRichMessageDraft(msg, extra?)` | Stream a partial rich message (for AI-generated replies) |
-| `ctx.telegram.sendRichMessage(chatId, msg, extra?)` | Explicit usage with chat ID |
-| `ctx.telegram.sendRichMessageDraft(chatId, msg, extra?)` | Explicit streaming with chat ID |
+| `ctx.replyWithRichMessageContent(msg, extra?)` | Send a rich message quoting the current message |
+| `ctx.sendRichMessageDraft(draftId, msg, extra?)` | Stream a partial draft (private chats only) |
+| `ctx.telegram.sendRichMessage(chatId, msg, extra?)` | Explicit call with chat ID |
+| `ctx.telegram.sendRichMessageDraft(chatId, draftId, msg, extra?)` | Explicit streaming with chat ID |
 
-```ts
-bot.on('message', async (ctx) => {
-  const msg = new Builder()
-    .paragraph(RT.plain('I am replying to your message!'))
-    .build()
+**`extra` options for `sendRichMessage`:**
 
-  // Sends and quotes the user's message
-  await ctx.replyWithRichMessageContent(msg)
+```ts
+await ctx.sendRichMessage(msg, {
+  message_thread_id: 123,           // for forum topics
+  direct_messages_topic_id: 456,    // for DM topics
+  disable_notification: true,
+  protect_content: true,
+  allow_paid_broadcast: false,
+  message_effect_id: 'effect_id',
+  reply_parameters: { message_id: ctx.message.message_id },
+  reply_markup: { inline_keyboard: [[{ text: 'OK', callback_data: 'ok' }]] },
 })
 ```
 
-The `extra` parameter accepts:
+---
+
+### InputRichMessage Format
+
+`InputRichMessage` uses **either** `html` or `markdown` — not both:
 
 ```ts
-{
-  message_thread_id?: number       // for forum topics
-  disable_notification?: boolean
-  protect_content?: boolean
-  reply_parameters?: ReplyParameters
-  reply_markup?: InlineKeyboardMarkup | ReplyKeyboardMarkup | ...
+// HTML format
+const msg: InputRichMessage = {
+  html: '<h1>Title</h1><p>Body text</p>',
+  is_rtl: false,
+  skip_entity_detection: false,
+}
+
+// Markdown format
+const msg: InputRichMessage = {
+  markdown: '# Title\n\nBody text',
 }
 ```
 
----
+Use the builders — `RichHTMLBuilder` or `RichMarkdownBuilder` — to construct these conveniently.
 
-### RichText — Inline Elements
+---
 
-`RichText` types are inline elements that compose the text inside paragraphs, headings, captions, etc.
+### RichHTMLBuilder
 
-#### Text Formatting
+Import and instantiate:
 
 ```ts
-RT.plain('normal text')
-RT.bold(RT.plain('bold'))
-RT.italic(RT.plain('italic'))
-RT.underline(RT.plain('underlined'))
-RT.strikethrough(RT.plain('crossed out'))
-RT.spoiler(RT.plain('hidden until tapped'))
-RT.marked(RT.plain('highlighted'))    // like a text marker
-RT.subscript(RT.plain('₂'))
-RT.superscript(RT.plain('²'))
-```
-
-Nesting is supported:
+import { RichMessage } from '@icanseeuanywhere/telekaf'
+const { RichHTMLBuilder: HTML } = RichMessage
 
-```ts
-RT.bold(RT.italic(RT.plain('bold and italic')))
-RT.underline(RT.strikethrough(RT.plain('underlined and crossed')))
+const msg = new HTML()
+  .heading(1, 'Title')
+  .paragraph('Content')
+  .build()  // returns InputRichMessage { html: '...' }
 ```
 
-#### Code & Math
-
-```ts
-RT.code(RT.plain('const x = 1'), 'javascript')  // inline code with language
-RT.math('E = mc^2')                              // inline mathematical expression
-```
+#### Text Formatting (HTML)
 
-#### Links & References
+Static inline helpers — return strings to embed inside block methods:
 
 ```ts
-RT.url('https://telegram.org', RT.plain('Telegram'))
-RT.email('hello@example.com', RT.plain('Send email'))
-RT.phone('+6281234567890', RT.plain('Call us'))
-RT.bankCard('4111111111111111')                   // bank card number (auto-formatted)
-RT.anchorLink('section-1', RT.plain('Jump to section'))  // link to an anchor in the same message
-```
-
-#### Mentions & Commands
+HTML.bold('bold text')                          // <b>bold text</b>
+HTML.italic('italic text')                      // <i>italic text</i>
+HTML.underline('underlined')                    // <u>underlined</u>
+HTML.strikethrough('crossed out')               // <s>crossed out</s>
+HTML.spoiler('hidden until tapped')             // <tg-spoiler>hidden</tg-spoiler>
+HTML.code('inline code')                        // <code>inline code</code>
+HTML.marked('highlighted')                      // <mark>highlighted</mark>
+HTML.sub('subscript')                           // <sub>subscript</sub>
+HTML.sup('superscript')                         // <sup>superscript</sup>
+
+HTML.url('https://t.me', 'Telegram')            // <a href="...">Telegram</a>
+HTML.email('hi@bot.com', 'Email us')            // <a href="mailto:...">Email us</a>
+HTML.phone('+6281234567', 'Call us')            // <a href="tel:...">Call us</a>
+HTML.mention(123456789, 'Alice')                // <a href="tg://user?id=...">Alice</a>
+HTML.customEmoji('5368324170671202286', '👍')   // <tg-emoji emoji-id="...">👍</tg-emoji>
+HTML.time(1647531900, 'wDT', '22:45 tomorrow') // <tg-time unix="..." format="...">...</tg-time>
+HTML.inlineMath('E = mc^2')                     // $E = mc^2$
+
+// Nesting
+HTML.bold(HTML.italic('bold italic'))
+HTML.underline(HTML.spoiler('underlined spoiler'))
+```
+
+#### Headings & Paragraphs
 
 ```ts
-RT.mention(RT.plain('John'), 123456789)           // mention by user_id
-RT.mention(RT.plain('@john'), undefined, 'john')  // mention by username
-RT.botCommand('/start')
-RT.botCommand('/search', 'mybot')                 // command for a specific bot
-RT.hashtag('telegraf')
-RT.cashtag('BTC')
+new HTML()
+  .heading(1, 'Main Title')
+  .heading(2, 'Subtitle')
+  .heading(3, HTML.bold('Bold heading'))
+  .heading(4, 'H4')
+  .heading(5, 'H5')
+  .heading(6, 'H6')
+  .paragraph('Normal paragraph text.')
+  .paragraph(HTML.bold('Bold') + ' and ' + HTML.italic('italic') + ' combined.')
+  .footer('Footer text — smaller and muted')
+  .divider()  // <hr/>
+  .build()
 ```
 
-#### Dates, Emojis & Anchors
+#### Lists (HTML)
 
 ```ts
-RT.dateTime(Date.now() / 1000)         // Unix timestamp — rendered as local time for user
-RT.customEmoji('5368324170671202286')  // custom emoji by ID
-RT.anchor('my-section')               // invisible anchor for deep linking
+new HTML()
+  // Unordered list
+  .ul('First item', 'Second item', HTML.bold('Bold item'))
+
+  // Ordered list
+  .ol('Step one', 'Step two', 'Step three')
+
+  // Task list (checkboxes)
+  .taskList(
+    { text: 'Completed task',  checked: true  },
+    { text: 'Pending task',    checked: false },
+    { text: HTML.bold('Important task'), checked: false },
+  )
+  .build()
 ```
 
-#### Footnote References
+#### Code Blocks
 
 ```ts
-const builder = new Builder()
-
-// Register a footnote — returns its numeric ID
-const refId = builder.reference(RT.url('https://source.com', RT.plain('Source')))
-
-builder.paragraph(
-  RT.plain('Some claim '),
-  RT.referenceLink(refId, RT.plain('[1]')),  // clickable footnote link
-  RT.plain(' is true.'),
-)
-
-await ctx.sendRichMessage(builder.build())
+new HTML()
+  .pre('npm install @icanseeuanywhere/telekaf', 'bash')
+  .pre('SELECT * FROM users WHERE active = 1;', 'sql')
+  .pre(
+`const bot = new Telegraf(token)
+bot.launch()`,
+    'javascript'
+  )
+  .pre('plain preformatted block without language')
+  .build()
 ```
 
----
-
-### RichBlock — Block Elements
-
-`RichBlock` types are block-level elements that form the structure of a rich message.
+Supported language identifiers: `javascript`, `typescript`, `python`, `bash`, `sql`, `json`, `html`, `css`, etc.
 
-#### Text Blocks
+#### Blockquote & Pull Quote
 
 ```ts
-// Paragraph
-new Builder().paragraph(RT.plain('First sentence. '), RT.bold(RT.plain('Bold part.')))
-
-// Section headings (h1–h6)
-new Builder()
-  .heading(1, RT.plain('Main Title'))
-  .heading(2, RT.plain('Sub-section'))
-  .heading(3, RT.plain('Sub-sub-section'))
-
-// Preformatted / code block
-new Builder().preformatted('SELECT * FROM users;', 'sql')
-new Builder().preformatted('plain preformatted block')
+new HTML()
+  // Standard block quotation
+  .blockQuote(HTML.italic('"To be or not to be."'))
+
+  // Pull quotation with attribution (cite)
+  .pullQuote(
+    HTML.italic('"Design is not just what it looks like."'),
+    'Steve Jobs'
+  )
 
-// Footer (smaller, muted text)
-new Builder().paragraph(RT.plain('Article body...'))
-// Footer block — add directly via .build() merge:
+  // Nested formatting inside quote
+  .blockQuote(
+    HTML.bold('Telekaf') + ' supports ' + HTML.marked('highlighted') +
+    ' and ' + HTML.spoiler('spoiler') + ' text inside quotes.'
+  )
+  .build()
 ```
 
-```ts
-import type { RichBlock } from '@icanseeuanywhere/telekaf/types'
+#### Math (HTML)
 
-const footer: RichBlock = {
-  type: 'footer',
-  texts: [RT.plain('Published by '), RT.bold(RT.plain('MyBot'))],
-}
+```ts
+new HTML()
+  // Inline math (embed inside paragraph)
+  .paragraph(
+    'The formula is: ' + HTML.inlineMath('a^2 + b^2 = c^2')
+  )
 
-const msg = new Builder()
-  .heading(1, RT.plain('News Title'))
-  .paragraph(RT.plain('Article body...'))
-  .divider()
+  // Block math expression
+  .mathBlock('\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}')
+  .mathBlock('F(x) = \\int_{-\\infty}^{x} f(t)\\,dt')
+  .mathBlock('E = mc^2')
   .build()
-
-// Append footer manually
-msg.blocks.push(footer)
-await ctx.sendRichMessage(msg)
 ```
 
-#### Lists
+#### Media — Photo, Video, Audio
 
 ```ts
-// Unordered list
-new Builder().list(false,
-  [{ type: 'paragraph', texts: [RT.plain('First item')] }],
-  [{ type: 'paragraph', texts: [RT.plain('Second item')] }],
-  [{ type: 'paragraph', texts: [RT.plain('Third item')] }],
-)
-
-// Ordered list
-new Builder().list(true,
-  [{ type: 'paragraph', texts: [RT.plain('Step one')] }],
-  [{ type: 'paragraph', texts: [RT.plain('Step two')] }],
-)
+new HTML()
+  // Photo
+  .photo('https://example.com/photo.jpg')
+  .photo('https://example.com/photo.jpg', 'Caption text')
+  .photo('https://example.com/photo.jpg', 'Spoiler photo', /* spoiler */ true)
+
+  // Video
+  .video('https://example.com/video.mp4')
+  .video('https://example.com/video.mp4', 'Caption text')
+  .video('https://example.com/video.mp4', 'Spoiler video', /* spoiler */ true)
+
+  // Audio / Voice note (.ogg for voice)
+  .audio('https://example.com/audio.mp3')
+  .audio('https://example.com/audio.mp3', 'Audio caption')
+
+  // With figcaption (HTML figure)
+  .raw('<figure><img src="https://example.com/photo.jpg"/><figcaption>Caption <b>bold</b></figcaption></figure>')
+  .build()
 ```
 
-#### Quotations
+You can also use a Telegram `file_id` in place of a URL once the file is uploaded.
 
-```ts
-// Block quotation
-new Builder().blockQuote(
-  { type: 'paragraph', texts: [RT.italic(RT.plain('To be or not to be.'))] },
-)
+#### Collage & Slideshow
 
-// Pull quotation (with optional caption)
-import type { RichBlock } from '@icanseeuanywhere/telekaf/types'
+```ts
+const img = (src) => `<img src="${src}"/>`
+const vid = (src) => `<video src="${src}"></video>`
+
+new HTML()
+  // Collage — displays as a grid
+  .collage(
+    img('https://example.com/photo1.jpg'),
+    img('https://example.com/photo2.jpg'),
+    vid('https://example.com/clip.mp4'),
+  )
 
-const pullQuote: RichBlock = {
-  type: 'pull_quotation',
-  blocks: [{ type: 'paragraph', texts: [RT.plain('Design is not just what it looks like.')] }],
-  caption: { type: 'caption', texts: [RT.plain('— Steve Jobs')] },
-}
+  // Slideshow — swipeable carousel
+  .slideshow(
+    img('https://example.com/photo1.jpg'),
+    img('https://example.com/photo2.jpg'),
+    img('https://example.com/photo3.jpg'),
+  )
+  .build()
 ```
 
-#### Media Blocks
+#### Map
 
 ```ts
-// Single photo
-new Builder().photo('AgACAgIAAxk...', { type: 'caption', texts: [RT.plain('A beautiful sunset')] })
-
-// Single video
-new Builder().video('BAACAgIAAxk...', { type: 'caption', texts: [RT.plain('Tutorial video')] })
-
-// Single audio
-new Builder().audio('CQACAgIAAxk...')
-
-// Voice note
-import type { RichBlock } from '@icanseeuanywhere/telekaf/types'
-const voiceBlock: RichBlock = {
-  type: 'voice_note',
-  file_id: 'AwACAgIAAxk...',
-}
-
-// Collage (multiple photos/videos in a grid)
-import type { RichBlock } from '@icanseeuanywhere/telekaf/types'
-const collage: RichBlock = {
-  type: 'collage',
-  media: [
-    { type: 'photo', file_id: 'AgACAgIA...' },
-    { type: 'photo', file_id: 'AgACAgIB...' },
-    { type: 'video', file_id: 'BAACAgIA...' },
-  ],
-  caption: { type: 'caption', texts: [RT.plain('Our gallery')] },
-}
-
-// Slideshow (swipeable gallery)
-const slideshow: RichBlock = {
-  type: 'slideshow',
-  media: [
-    { type: 'photo', file_id: 'AgACAgIA...' },
-    { type: 'photo', file_id: 'AgACAgIB...' },
-  ],
-}
+new HTML()
+  .map(-6.2088, 106.8456)                              // Jakarta
+  .map(48.8584, 2.2945, 16)                            // Paris, zoom 16
+  .map(51.5074, -0.1278, 14, 'Our office in London')   // with caption
+  .build()
 ```
 
-#### Table
+#### Table (HTML)
 
 ```ts
-import type { RichBlock } from '@icanseeuanywhere/telekaf/types'
-
-const table: RichBlock = {
-  type: 'table',
-  is_bordered: true,
-  is_striped: true,
-  cells: [
-    // Header row
+new HTML()
+  .table(
     [
-      { type: 'table_cell', is_header: true, content: [{ type: 'paragraph', texts: [RT.plain('Name')] }] },
-      { type: 'table_cell', is_header: true, content: [{ type: 'paragraph', texts: [RT.plain('Score')] }] },
+      ['Name',    'Version', 'Downloads'],   // header row (hasHeader: true)
+      ['telekaf', '4.16.5',  '—'        ],
+      ['telegraf','4.16.3',  '~120k/wk' ],
     ],
-    // Data rows
-    [
-      { type: 'table_cell', content: [{ type: 'paragraph', texts: [RT.plain('Alice')] }] },
-      { type: 'table_cell', content: [{ type: 'paragraph', texts: [RT.plain('98')] }] },
-    ],
-    [
-      { type: 'table_cell', content: [{ type: 'paragraph', texts: [RT.plain('Bob')] }] },
-      { type: 'table_cell', content: [{ type: 'paragraph', texts: [RT.plain('87')] }] },
-    ],
-  ],
-}
-
-await ctx.sendRichMessage({ blocks: [table] })
+    { bordered: true, striped: true, hasHeader: true }
+  )
+  .build()
 ```
 
-Column span and row span:
+For advanced table markup (colspan, rowspan, alignment), use `.raw()`:
 
 ```ts
-{ type: 'table_cell', colspan: 2, content: [{ type: 'paragraph', texts: [RT.plain('Merged cell')] }] }
-{ type: 'table_cell', rowspan: 3, align: 'center', content: [...] }
+new HTML()
+  .raw(
+    '<table bordered striped>' +
+      '<tr><th>Name</th><th colspan="2">Details</th></tr>' +
+      '<tr><td>Alice</td><td align="center">98</td><td align="right">Pass</td></tr>' +
+    '</table>'
+  )
+  .build()
 ```
 
-#### Expandable Details
+#### Details (Expandable)
 
 ```ts
-import type { RichBlock } from '@icanseeuanywhere/telekaf/types'
-
-const details: RichBlock = {
-  type: 'details',
-  header: [RT.plain('Click to expand')],
-  blocks: [
-    { type: 'paragraph', texts: [RT.plain('Hidden content revealed on tap.')] },
-  ],
-}
+new HTML()
+  // Collapsed by default
+  .details('Click to expand', '<p>Hidden content here.</p>')
+
+  // Open by default
+  .details(
+    HTML.bold('Changelog v4.16.5'),
+    '<ul><li>Fix InputRichMessage format</li><li>Add RichHTMLBuilder</li></ul>',
+    /* open */ true
+  )
+  .build()
 ```
 
-#### Map
+#### Footnote References (HTML)
 
 ```ts
-import type { RichBlock } from '@icanseeuanywhere/telekaf/types'
-
-const map: RichBlock = {
-  type: 'map',
-  latitude: -6.2088,
-  longitude: 106.8456,
-  zoom: 14,
-  caption: { type: 'caption', texts: [RT.plain('Our office in Jakarta')] },
-}
+new HTML()
+  .paragraph(
+    'Telekaf ' + HTML.ref('note-1', '[1]') + ' is based on Telegraf ' + HTML.ref('note-2', '[2]') + '.'
+  )
+  .divider()
+  .referenceDefinition('note-1', HTML.url('https://npmjs.com/package/@icanseeuanywhere/telekaf', 'telekaf on npm'))
+  .referenceDefinition('note-2', HTML.url('https://github.com/telegraf/telegraf', 'telegraf on GitHub'))
+  .build()
 ```
 
-#### Divider & Anchor
+#### Anchors & In-document Links
 
 ```ts
-new Builder().divider()  // horizontal rule
-
-import type { RichBlock } from '@icanseeuanywhere/telekaf/types'
-const anchor: RichBlock = { type: 'anchor', name: 'section-1' }  // jump target
+new HTML()
+  .raw(HTML.anchor('section-intro'))  // invisible anchor target
+  .heading(2, 'Introduction')
+  .paragraph('Jump to: ' + HTML.anchorLink('section-api', 'API Reference'))
+  .raw(HTML.anchor('section-api'))
+  .heading(2, 'API Reference')
+  .build()
 ```
 
-#### Mathematical Expression Block
+#### Special Elements
 
 ```ts
-import type { RichBlock } from '@icanseeuanywhere/telekaf/types'
-const mathBlock: RichBlock = {
-  type: 'mathematical_expression',
-  expression: '\\int_{-\\infty}^{\\infty} e^{-x^2} dx = \\sqrt{\\pi}',
-}
-```
-
-#### Thinking Block (AI reasoning)
+new HTML()
+  // AI thinking block (visible in sendRichMessageDraft)
+  .thinking(HTML.italic('Analyzing your request...'))
 
-Show a collapsible "thinking" section, useful for AI bots:
-
-```ts
-new Builder().thinking(
-  { type: 'paragraph', texts: [RT.plain('Let me reason through this step by step...')] },
-  { type: 'paragraph', texts: [RT.plain('First, I consider the user intent.')] },
-)
+  // Raw HTML for anything not covered by builder methods
+  .raw('<tg-map lat="41.9" long="12.5" zoom="14"/>')
+  .raw('<aside>Pull quote<cite>The Author</cite></aside>')
+  .build()
 ```
 
 ---
 
-### `RichMessageBuilder` API
+### RichMarkdownBuilder
 
-`RichMessageBuilder` is a fluent builder for constructing `InputRichMessage` objects.
+Same API surface as `RichHTMLBuilder` but produces Markdown output:
 
 ```ts
 import { RichMessage } from '@icanseeuanywhere/telekaf'
-const { RichMessageBuilder: Builder, RT } = RichMessage
-
-const msg = new Builder()
-  .heading(1, RT.plain('Title'))
-  .paragraph(RT.plain('Body text'))
-  .preformatted('code here', 'js')
+const { RichMarkdownBuilder: MD } = RichMessage
+
+const msg = new MD()
+  .heading(1, 'Rich Markdown')
+  .paragraph(
+    MD.bold('bold') + '  ' +
+    MD.italic('italic') + '  ' +
+    MD.strikethrough('strike') + '  ' +
+    MD.marked('==highlighted==') + '  ' +
+    MD.spoiler('||spoiler||') + '  ' +
+    MD.code('`code`')
+  )
   .divider()
-  .list(false,
-    [{ type: 'paragraph', texts: [RT.plain('Item A')] }],
-    [{ type: 'paragraph', texts: [RT.plain('Item B')] }],
+  .ul('Item 1', 'Item 2', MD.bold('Bold item'))
+  .ol('Step 1', 'Step 2', 'Step 3')
+  .taskList(
+    { text: 'Done',    checked: true  },
+    { text: 'Pending', checked: false },
   )
-  .blockQuote({ type: 'paragraph', texts: [RT.plain('Quote')] })
-  .thinking({ type: 'paragraph', texts: [RT.plain('AI reasoning...')] })
-  .photo('AgACAgIA...')
-  .video('BAACAgIA...')
-  .audio('CQACAgIA...')
-  .build()  // returns InputRichMessage
+  .divider()
+  .pre('console.log("hello")', 'javascript')
+  .divider()
+  .table(
+    ['Name', 'Score'],
+    [['Alice', '98'], ['Bob', '87']],
+    ['left', 'center'],
+  )
+  .divider()
+  .mathBlock('E = mc^2')
+  .divider()
+  .blockQuote(MD.italic('"Quote text"'), '— Author')
+  .divider()
+  .photo('https://example.com/photo.jpg', 'Photo caption')
+  .collage('https://example.com/1.jpg', 'https://example.com/2.jpg')
+  .slideshow('https://example.com/1.jpg', 'https://example.com/2.jpg')
+  .divider()
+  .details('Expand me', '### Hidden heading\n\n- item 1\n- item 2')
+  .divider()
+  .paragraph('See footnote' + MD.sup('[1]'))
+  .footnote('1', MD.url('https://t.me/kafk6', '@kafka'))
+  .build()
 ```
 
-#### Available builder methods
-
-| Method | Description |
-|---|---|
-| `.paragraph(...texts)` | Add a paragraph block |
-| `.heading(level, ...texts)` | Add a heading (h1–h6) |
-| `.preformatted(text, language?)` | Add a code/preformatted block |
-| `.divider()` | Add a horizontal divider |
-| `.list(isOrdered, ...items)` | Add an ordered or unordered list |
-| `.blockQuote(...blocks)` | Add a block quotation |
-| `.thinking(...blocks)` | Add an AI thinking block |
-| `.photo(fileId, caption?)` | Add a photo block |
-| `.video(fileId, caption?)` | Add a video block |
-| `.audio(fileId, caption?)` | Add an audio block |
-| `.reference(richText)` | Register a footnote, returns its numeric ID |
-| `.build()` | Returns the final `InputRichMessage` |
-
----
-
-### RT Helpers
-
-`RT` is a collection of factory functions for creating `RichText` nodes concisely.
+**All Markdown inline helpers:**
 
 ```ts
-import { RichMessage } from '@icanseeuanywhere/telekaf'
-const { RT } = RichMessage
-
-RT.plain('text')
-RT.bold(RT.plain('bold'))
-RT.italic(RT.plain('italic'))
-RT.underline(RT.plain('underline'))
-RT.strikethrough(RT.plain('strike'))
-RT.spoiler(RT.plain('spoiler'))
-RT.marked(RT.plain('highlight'))
-RT.subscript(RT.plain('sub'))
-RT.superscript(RT.plain('sup'))
-RT.code(RT.plain('x++'), 'cpp')
-RT.math('a^2 + b^2 = c^2')
-RT.url('https://t.me', RT.plain('Telegram'))
-RT.email('hi@bot.com')
-RT.phone('+1234567890')
-RT.bankCard('4111111111111111')
-RT.mention(RT.plain('Alice'), 123456789)
-RT.mention(RT.plain('@alice'), undefined, 'alice')
-RT.botCommand('/start')
-RT.botCommand('/help', 'mybot')
-RT.hashtag('news')
-RT.cashtag('ETH')
-RT.dateTime(1750000000)
-RT.customEmoji('5368324170671202286')
-RT.anchor('section-id')
-RT.anchorLink('section-id', RT.plain('Go to section'))
-RT.reference(1)                            // footnote number
-RT.referenceLink(1, RT.plain('[1]'))       // clickable footnote
+MD.bold('text')                    // **text**
+MD.italic('text')                  // *text*
+MD.underline('text')               // <u>text</u>
+MD.strikethrough('text')           // ~~text~~
+MD.spoiler('text')                 // ||text||
+MD.code('text')                    // `text`
+MD.marked('text')                  // ==text==
+MD.sub('text')                     // <sub>text</sub>
+MD.sup('text')                     // <sup>text</sup>
+MD.url('https://...', 'label')     // [label](url)
+MD.email('a@b.com', 'label')       // [label](mailto:a@b.com)
+MD.phone('+123', 'label')          // [label](tel:+123)
+MD.mention(123456789, 'Alice')     // [Alice](tg://user?id=123456789)
+MD.customEmoji('id', '👍')         // ![👍](tg://emoji?id=...)
+MD.time(1647531900, 'wDT')         // ![](tg://time?unix=...&format=wDT)
+MD.inlineMath('a^2')               // $a^2$
 ```
 
 ---
 
-### Streaming with `sendRichMessageDraft`
+### Streaming with sendRichMessageDraft
 
-`sendRichMessageDraft` allows bots to stream partial rich messages, enabling AI bots to show replies as they are generated — similar to how LLMs stream tokens.
+`sendRichMessageDraft` streams a partial rich message in private chats. The draft is ephemeral (30-second preview). You **must** finalize with `sendRichMessage` to persist it.
 
-```ts
-import { RichMessage } from '@icanseeuanywhere/telekaf'
-const { RichMessageBuilder: Builder, RT } = RichMessage
+- `chat_id` — private chat only (integer)
+- `draft_id` — non-zero integer; updates with the same `draft_id` are animated
 
+```ts
 bot.command('ai', async (ctx) => {
-  // Send an initial draft (partial content)
-  await ctx.sendRichMessageDraft(
-    new Builder()
-      .thinking({ type: 'paragraph', texts: [RT.plain('Analyzing your request...')] })
-      .build()
-  )
+  const DRAFT_ID = 1  // any non-zero integer
 
-  // Simulate streaming by sending updated drafts
   const steps = [
-    'Gathering information...',
-    'Processing data...',
-    'Composing response...',
+    'Reading your request...',
+    'Searching knowledge base...',
+    'Composing answer...',
   ]
 
+  // Stream thinking blocks
   for (const step of steps) {
-    await new Promise((r) => setTimeout(r, 800))
     await ctx.sendRichMessageDraft(
-      new Builder()
-        .thinking({ type: 'paragraph', texts: [RT.plain(step)] })
-        .build()
+      DRAFT_ID,
+      new HTML().thinking(HTML.italic(step)).build()
     )
+    await new Promise((r) => setTimeout(r, 900))
   }
 
-  // Send the final complete message
+  // Finalize — must call sendRichMessage after streaming
   await ctx.sendRichMessage(
-    new Builder()
-      .heading(2, RT.plain('Answer'))
-      .paragraph(RT.plain('Here is the final response from the AI.'))
+    new HTML()
+      .heading(2, '🤖 AI Response')
+      .paragraph('Here is the final answer from the AI.')
+      .divider()
+      .footer(HTML.url('https://t.me/kafk6', '@kafka'))
       .build()
   )
 })
 ```
 
+You can also call `sendRichMessageDraft` explicitly:
+
+```ts
+// Explicit
+await ctx.telegram.sendRichMessageDraft(
+  ctx.chat.id,   // private chat integer ID
+  42,            // draft_id
+  new HTML().thinking('Processing...').build(),
+  { message_thread_id: 123 }
+)
+```
+
+---
+
+### reply_markup with Rich Messages
+
+All `sendRichMessage` calls accept a `reply_markup` option with inline keyboards:
+
+```ts
+import { Markup } from '@icanseeuanywhere/telekaf'
+
+const msg = new HTML()
+  .heading(2, 'Choose an option')
+  .paragraph('Tap a button below:')
+  .build()
+
+await ctx.sendRichMessage(msg, {
+  reply_markup: Markup.inlineKeyboard([
+    [
+      Markup.button.callback('✅ Yes', 'answer:yes'),
+      Markup.button.callback('❌ No',  'answer:no'),
+    ],
+    [Markup.button.url('🌐 Visit', 'https://t.me/kafk6')],
+  ]).reply_markup,
+})
+
+bot.action('answer:yes', async (ctx) => {
+  await ctx.answerCbQuery('You chose Yes!')
+})
+```
+
+Or use `reply_markup` directly:
+
+```ts
+await ctx.sendRichMessage(msg, {
+  reply_markup: {
+    inline_keyboard: [
+      [{ text: 'Button 1', callback_data: 'btn1' }],
+      [{ text: 'Open URL', url: 'https://telegram.org' }],
+    ],
+  },
+})
+```
+
 ---
 
 ### Inline / Web App Queries
 
-`InputRichMessageContent` can be returned in results for inline queries, guest queries, and Web App queries.
+Use `InputRichMessageContent` as `input_message_content` in inline query results:
 
 ```ts
 import { RichMessage } from '@icanseeuanywhere/telekaf'
-const { RichMessageBuilder: Builder, RT } = RichMessage
+const { RichHTMLBuilder: HTML } = RichMessage
 
 bot.on('inline_query', async (ctx) => {
   const richContent: RichMessage.InputRichMessageContent = {
-    rich_message: new Builder()
-      .heading(1, RT.plain('Inline Result'))
-      .paragraph(RT.plain('This was sent from an inline query!'))
+    rich_message: new HTML()
+      .heading(1, 'Result from Inline Query')
+      .paragraph('Sent via ' + HTML.url('https://t.me/kafk6', '@kafka') + '.')
       .build(),
   }
 
@@ -562,47 +605,35 @@ bot.on('inline_query', async (ctx) => {
 
 ---
 
-### TypeScript Usage with Rich Messages
+### TypeScript
 
-All types are exported from `telegraf` under the `RichMessage` namespace:
+All types are exported under the `RichMessage` namespace:
 
 ```ts
 import { RichMessage } from '@icanseeuanywhere/telekaf'
+import type { ExtraSendRichMessage, ExtraSendRichMessageDraft } from '@icanseeuanywhere/telekaf/types'
 
-// Individual types
-const text: RichMessage.RichText = RT.bold(RT.plain('hello'))
-const block: RichMessage.RichBlock = { type: 'paragraph', texts: [text] }
-const msg: RichMessage.InputRichMessage = { blocks: [block] }
-const received: RichMessage.RichMessage = ctx.message.rich_message  // on incoming messages
-
-// All RichText types
-type RichText = RichMessage.RichText
-type RichTextBold = RichMessage.RichTextBold
-type RichTextItalic = RichMessage.RichTextItalic
-// ... etc
+// Builder types
+const builder: RichMessage.RichHTMLBuilder = new RichMessage.RichHTMLBuilder()
+const mdBuilder: RichMessage.RichMarkdownBuilder = new RichMessage.RichMarkdownBuilder()
 
-// All RichBlock types
-type RichBlock = RichMessage.RichBlock
-type RichBlockParagraph = RichMessage.RichBlockParagraph
-type RichBlockTable = RichMessage.RichBlockTable
-// ... etc
-
-// Extra types for sendRichMessage
-import type { ExtraSendRichMessage } from '@icanseeuanywhere/telekaf/types'
-```
+// Message types
+const input: RichMessage.InputRichMessage = { html: '<p>hello</p>' }
+const content: RichMessage.InputRichMessageContent = { rich_message: input }
+const received: RichMessage.RichMessage = ctx.message.rich_message
 
-You can also import types directly if needed:
+// Extra types
+const extra: ExtraSendRichMessage = {
+  disable_notification: true,
+  reply_markup: { inline_keyboard: [] },
+}
 
-```ts
-import type {
-  RichText,
-  RichBlock,
-  RichMessage,
-  InputRichMessage,
-  InputRichMessageContent,
-  RichMessageBuilder,
-  RT,
-} from '@icanseeuanywhere/telekaf/core/types/rich-message'
+// Custom context with rich message
+import { Context, Telegraf } from '@icanseeuanywhere/telekaf'
+interface MyCtx extends Context {
+  session?: { lastDraftId: number }
+}
+const bot = new Telegraf<MyCtx>(process.env.BOT_TOKEN)
 ```
 
 ---
@@ -795,7 +826,7 @@ process.once('SIGTERM', () => bot.stop('SIGTERM'))
 ### Webhooks
 
 ```TS
-import { Telegraf } from "telegraf";
+import { Telegraf } from "@icanseeuanywhere/telekaf";
 import { message } from '@icanseeuanywhere/telekaf/filters';
 
 const bot = new Telegraf(token);