@icanseeuanywhere/telekaf 4.16.3

package/README.md

@@ -0,0 +1,978 @@
+<header>
+
+<div align="center">
+<img src="docs/assets/logo.svg" alt="logo" height="90" align="center">
+<h1 align="center">telegraf.js</h1>
+
+<p>Modern Telegram Bot API framework for Node.js</p>
+
+<a href="https://core.telegram.org/bots/api">
+	<img src="https://img.shields.io/badge/Bot%20API-v10.1-f36caf.svg?style=flat-square" alt="Bot API Version" />
+</a>
+<a href="https://packagephobia.com/result?p=telegraf,node-telegram-bot-api">
+	<img src="https://flat.badgen.net/packagephobia/install/telegraf" alt="install size" />
+</a>
+<a href="https://github.com/telegraf/telegraf">
+	<img src="https://img.shields.io/github/languages/top/telegraf/telegraf?style=flat-square&logo=github" alt="GitHub top language" />
+</a>
+<a href="https://telegram.me/TelegrafJSChat">
+	<img src="https://img.shields.io/badge/English%20chat-grey?style=flat-square&logo=telegram" alt="English chat" />
+</a>
+</div>
+
+</header>
+
+> **telekaf** (`@icanseeuanywhere/telekaf`) is an up-to-date fork of [telegraf](https://github.com/telegraf/telegraf) — the popular Telegram Bot framework for Node.js.
+> 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.
+
+### Table of Contents
+
+- [Quick Start](#rich-messages-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)
+- [Streaming with sendRichMessageDraft](#streaming-with-sendrichmessagedraft)
+- [Inline / Web App Queries](#inline--web-app-queries)
+- [TypeScript Usage](#typescript-usage-with-rich-messages)
+
+---
+
+### Rich Messages Quick Start
+
+```ts
+import { Telegraf, RichMessage } from '@icanseeuanywhere/telekaf'
+const { RichMessageBuilder: Builder, RT } = 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.'))
+    .divider()
+    .preformatted('npm install telegraf', 'bash')
+    .build()
+
+  await ctx.sendRichMessage(msg)
+})
+
+bot.launch()
+process.once('SIGINT', () => bot.stop('SIGINT'))
+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 |
+
+```ts
+bot.on('message', async (ctx) => {
+  const msg = new Builder()
+    .paragraph(RT.plain('I am replying to your message!'))
+    .build()
+
+  // Sends and quotes the user's message
+  await ctx.replyWithRichMessageContent(msg)
+})
+```
+
+The `extra` parameter accepts:
+
+```ts
+{
+  message_thread_id?: number       // for forum topics
+  disable_notification?: boolean
+  protect_content?: boolean
+  reply_parameters?: ReplyParameters
+  reply_markup?: InlineKeyboardMarkup | ReplyKeyboardMarkup | ...
+}
+```
+
+---
+
+### RichText — Inline Elements
+
+`RichText` types are inline elements that compose the text inside paragraphs, headings, captions, etc.
+
+#### Text Formatting
+
+```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:
+
+```ts
+RT.bold(RT.italic(RT.plain('bold and italic')))
+RT.underline(RT.strikethrough(RT.plain('underlined and crossed')))
+```
+
+#### Code & Math
+
+```ts
+RT.code(RT.plain('const x = 1'), 'javascript')  // inline code with language
+RT.math('E = mc^2')                              // inline mathematical expression
+```
+
+#### Links & References
+
+```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
+
+```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')
+```
+
+#### Dates, Emojis & Anchors
+
+```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
+```
+
+#### Footnote References
+
+```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())
+```
+
+---
+
+### RichBlock — Block Elements
+
+`RichBlock` types are block-level elements that form the structure of a rich message.
+
+#### Text Blocks
+
+```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')
+
+// Footer (smaller, muted text)
+new Builder().paragraph(RT.plain('Article body...'))
+// Footer block — add directly via .build() merge:
+```
+
+```ts
+import type { RichBlock } from '@icanseeuanywhere/telekaf/types'
+
+const footer: RichBlock = {
+  type: 'footer',
+  texts: [RT.plain('Published by '), RT.bold(RT.plain('MyBot'))],
+}
+
+const msg = new Builder()
+  .heading(1, RT.plain('News Title'))
+  .paragraph(RT.plain('Article body...'))
+  .divider()
+  .build()
+
+// Append footer manually
+msg.blocks.push(footer)
+await ctx.sendRichMessage(msg)
+```
+
+#### Lists
+
+```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')] }],
+)
+```
+
+#### Quotations
+
+```ts
+// Block quotation
+new Builder().blockQuote(
+  { type: 'paragraph', texts: [RT.italic(RT.plain('To be or not to be.'))] },
+)
+
+// Pull quotation (with optional caption)
+import type { RichBlock } from '@icanseeuanywhere/telekaf/types'
+
+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')] },
+}
+```
+
+#### Media Blocks
+
+```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...' },
+  ],
+}
+```
+
+#### Table
+
+```ts
+import type { RichBlock } from '@icanseeuanywhere/telekaf/types'
+
+const table: RichBlock = {
+  type: 'table',
+  is_bordered: true,
+  is_striped: true,
+  cells: [
+    // Header row
+    [
+      { 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')] }] },
+    ],
+    // 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] })
+```
+
+Column span and row span:
+
+```ts
+{ type: 'table_cell', colspan: 2, content: [{ type: 'paragraph', texts: [RT.plain('Merged cell')] }] }
+{ type: 'table_cell', rowspan: 3, align: 'center', content: [...] }
+```
+
+#### Expandable Details
+
+```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.')] },
+  ],
+}
+```
+
+#### Map
+
+```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')] },
+}
+```
+
+#### Divider & Anchor
+
+```ts
+new Builder().divider()  // horizontal rule
+
+import type { RichBlock } from '@icanseeuanywhere/telekaf/types'
+const anchor: RichBlock = { type: 'anchor', name: 'section-1' }  // jump target
+```
+
+#### Mathematical Expression Block
+
+```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)
+
+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.')] },
+)
+```
+
+---
+
+### `RichMessageBuilder` API
+
+`RichMessageBuilder` is a fluent builder for constructing `InputRichMessage` objects.
+
+```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')
+  .divider()
+  .list(false,
+    [{ type: 'paragraph', texts: [RT.plain('Item A')] }],
+    [{ type: 'paragraph', texts: [RT.plain('Item B')] }],
+  )
+  .blockQuote({ type: 'paragraph', texts: [RT.plain('Quote')] })
+  .thinking({ type: 'paragraph', texts: [RT.plain('AI reasoning...')] })
+  .photo('AgACAgIA...')
+  .video('BAACAgIA...')
+  .audio('CQACAgIA...')
+  .build()  // returns InputRichMessage
+```
+
+#### 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.
+
+```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
+```
+
+---
+
+### 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.
+
+```ts
+import { RichMessage } from '@icanseeuanywhere/telekaf'
+const { RichMessageBuilder: Builder, RT } = RichMessage
+
+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()
+  )
+
+  // Simulate streaming by sending updated drafts
+  const steps = [
+    'Gathering information...',
+    'Processing data...',
+    'Composing response...',
+  ]
+
+  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()
+    )
+  }
+
+  // Send the final complete message
+  await ctx.sendRichMessage(
+    new Builder()
+      .heading(2, RT.plain('Answer'))
+      .paragraph(RT.plain('Here is the final response from the AI.'))
+      .build()
+  )
+})
+```
+
+---
+
+### Inline / Web App Queries
+
+`InputRichMessageContent` can be returned in results for inline queries, guest queries, and Web App queries.
+
+```ts
+import { RichMessage } from '@icanseeuanywhere/telekaf'
+const { RichMessageBuilder: Builder, RT } = 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!'))
+      .build(),
+  }
+
+  await ctx.answerInlineQuery([
+    {
+      type: 'article',
+      id: '1',
+      title: 'Rich Message Result',
+      input_message_content: richContent,
+    },
+  ])
+})
+```
+
+---
+
+### TypeScript Usage with Rich Messages
+
+All types are exported from `telegraf` under the `RichMessage` namespace:
+
+```ts
+import { RichMessage } from '@icanseeuanywhere/telekaf'
+
+// 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
+
+// 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'
+```
+
+You can also import types directly if needed:
+
+```ts
+import type {
+  RichText,
+  RichBlock,
+  RichMessage,
+  InputRichMessage,
+  InputRichMessageContent,
+  RichMessageBuilder,
+  RT,
+} from '@icanseeuanywhere/telekaf/core/types/rich-message'
+```
+
+---
+
+## For 3.x users
+
+- [3.x docs](https://telegraf.js.org/v3)
+- [4.0 release notes](https://github.com/telegraf/telegraf/releases/tag/v4.0.0)
+
+## Introduction
+
+Bots are special [Telegram](https://telegram.org) accounts designed to handle messages automatically.
+Users can interact with bots by sending them command messages in private or group chats.
+These accounts serve as an interface for code running somewhere on your server.
+
+Telegraf is a library that makes it simple for you to develop your own Telegram bots using JavaScript or [TypeScript](https://www.typescriptlang.org/).
+
+### Features
+
+- Full [Telegram Bot API 10.1](https://core.telegram.org/bots/api) support with **Rich Messages**
+- [Excellent TypeScript typings](https://github.com/telegraf/telegraf/releases/tag/v4.0.0)
+- [Lightweight](https://packagephobia.com/result?p=telegraf,node-telegram-bot-api)
+- [AWS **λ**](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-prog-model-handler.html)
+  / [Firebase](https://firebase.google.com/products/functions/)
+  / [Glitch](https://glitch.com/edit/#!/dashing-light)
+  / [Fly.io](https://fly.io/docs/languages-and-frameworks/node)
+  / Whatever ready
+- `http/https/fastify/Connect.js/express.js` compatible webhooks
+- Extensible
+
+### Example
+
+```js
+const { Telegraf } = require('@icanseeuanywhere/telekaf')
+const { message } = require('@icanseeuanywhere/telekaf/filters')
+
+const bot = new Telegraf(process.env.BOT_TOKEN)
+bot.start((ctx) => ctx.reply('Welcome'))
+bot.help((ctx) => ctx.reply('Send me a sticker'))
+bot.on(message('sticker'), (ctx) => ctx.reply('👍'))
+bot.hears('hi', (ctx) => ctx.reply('Hey there'))
+bot.launch()
+
+// Enable graceful stop
+process.once('SIGINT', () => bot.stop('SIGINT'))
+process.once('SIGTERM', () => bot.stop('SIGTERM'))
+```
+
+```js
+const { Telegraf } = require('@icanseeuanywhere/telekaf')
+
+const bot = new Telegraf(process.env.BOT_TOKEN)
+bot.command('oldschool', (ctx) => ctx.reply('Hello'))
+bot.command('hipster', Telegraf.reply('λ'))
+bot.launch()
+
+// Enable graceful stop
+process.once('SIGINT', () => bot.stop('SIGINT'))
+process.once('SIGTERM', () => bot.stop('SIGTERM'))
+```
+
+For additional bot examples see the new [`docs repo`](https://github.com/feathers-studio/telegraf-docs/).
+
+### Resources
+
+- [Getting started](#getting-started)
+- [API reference](https://telegraf.js.org/modules.html)
+- Telegram groups (sorted by number of members):
+  - [English](https://t.me/TelegrafJSChat)
+  - [Russian](https://t.me/telegrafjs_ru)
+  - [Uzbek](https://t.me/botjs_uz)
+  - [Ethiopian](https://t.me/telegraf_et)
+- [GitHub Discussions](https://github.com/telegraf/telegraf/discussions)
+- [Dependent repositories](https://libraries.io/npm/telegraf/dependent_repositories)
+
+## Getting started
+
+### Telegram token
+
+To use the [Telegram Bot API](https://core.telegram.org/bots/api),
+you first have to [get a bot account](https://core.telegram.org/bots)
+by [chatting with BotFather](https://core.telegram.org/bots#6-botfather).
+
+BotFather will give you a _token_, something like `123456789:AbCdefGhIJKlmNoPQRsTUVwxyZ`.
+
+### Installation
+
+```shellscript
+$ npm install @icanseeuanywhere/telekaf
+```
+
+or
+
+```shellscript
+$ yarn add @icanseeuanywhere/telekaf
+```
+
+or
+
+```shellscript
+$ pnpm add @icanseeuanywhere/telekaf
+```
+
+### `Telegraf` class
+
+[`Telegraf`] instance represents your bot. It's responsible for obtaining updates and passing them to your handlers.
+
+Start by [listening to commands](https://telegraf.js.org/classes/Telegraf-1.html#command) and [launching](https://telegraf.js.org/classes/Telegraf-1.html#launch) your bot.
+
+### `Context` class
+
+`ctx` you can see in every example is a [`Context`] instance.
+[`Telegraf`] creates one for each incoming update and passes it to your middleware.
+It contains the `update`, `botInfo`, and `telegram` for making arbitrary Bot API requests,
+as well as shorthand methods and getters.
+
+This is probably the class you'll be using the most.
+
+<!--
+TODO: Verify and update list
+Here is a list of
+
+#### Known middleware
+
+- [Internationalization](https://github.com/telegraf/telegraf-i18n)—simplifies selecting the right translation to use when responding to a user.
+- [Redis powered session](https://github.com/telegraf/telegraf-session-redis)—store session data using Redis.
+- [Local powered session (via lowdb)](https://github.com/RealSpeaker/telegraf-session-local)—store session data in a local file.
+- [Rate-limiting](https://github.com/telegraf/telegraf-ratelimit)—apply rate limitting to chats or users.
+- [Bottleneck powered throttling](https://github.com/KnightNiwrem/telegraf-throttler)—apply throttling to both incoming updates and outgoing API calls.
+- [Menus via inline keyboards](https://github.com/EdJoPaTo/telegraf-inline-menu)—simplify creating interfaces based on menus.
+- [Stateless Questions](https://github.com/EdJoPaTo/telegraf-stateless-question)—create stateless questions to Telegram users working in privacy mode.
+- [Natural language processing via wit.ai](https://github.com/telegraf/telegraf-wit)
+- [Natural language processing via recast.ai](https://github.com/telegraf/telegraf-recast)
+- [Multivariate and A/B testing](https://github.com/telegraf/telegraf-experiments)—add experiments to see how different versions of a feature are used.
+- [Powerfull bot stats via Mixpanel](https://github.com/telegraf/telegraf-mixpanel)
+- [statsd integration](https://github.com/telegraf/telegraf-statsd)
+- [and more...](https://www.npmjs.com/search?q=telegraf-)
+-->
+
+#### Shorthand methods
+
+```js
+import { Telegraf } from '@icanseeuanywhere/telekaf'
+import { message } from '@icanseeuanywhere/telekaf/filters'
+
+const bot = new Telegraf(process.env.BOT_TOKEN)
+
+bot.command('quit', async (ctx) => {
+  // Explicit usage
+  await ctx.telegram.leaveChat(ctx.message.chat.id)
+
+  // Using context shortcut
+  await ctx.leaveChat()
+})
+
+bot.on(message('text'), async (ctx) => {
+  // Explicit usage
+  await ctx.telegram.sendMessage(ctx.message.chat.id, `Hello ${ctx.state.role}`)
+
+  // Using context shortcut
+  await ctx.reply(`Hello ${ctx.state.role}`)
+})
+
+bot.on('callback_query', async (ctx) => {
+  // Explicit usage
+  await ctx.telegram.answerCbQuery(ctx.callbackQuery.id)
+
+  // Using context shortcut
+  await ctx.answerCbQuery()
+})
+
+bot.on('inline_query', async (ctx) => {
+  const result = []
+  // Explicit usage
+  await ctx.telegram.answerInlineQuery(ctx.inlineQuery.id, result)
+
+  // Using context shortcut
+  await ctx.answerInlineQuery(result)
+})
+
+bot.launch()
+
+// Enable graceful stop
+process.once('SIGINT', () => bot.stop('SIGINT'))
+process.once('SIGTERM', () => bot.stop('SIGTERM'))
+```
+
+## Production
+
+### Webhooks
+
+```TS
+import { Telegraf } from "telegraf";
+import { message } from '@icanseeuanywhere/telekaf/filters';
+
+const bot = new Telegraf(token);
+
+bot.on(message("text"), ctx => ctx.reply("Hello"));
+
+// Start webhook via launch method (preferred)
+bot.launch({
+  webhook: {
+    // Public domain for webhook; e.g.: example.com
+    domain: webhookDomain,
+
+    // Port to listen on; e.g.: 8080
+    port: port,
+
+    // Optional path to listen for.
+    // `bot.secretPathComponent()` will be used by default
+    path: webhookPath,
+
+    // Optional secret to be sent back in a header for security.
+    // e.g.: `crypto.randomBytes(64).toString("hex")`
+    secretToken: randomAlphaNumericString,
+  },
+});
+```
+
+Use `createWebhook()` if you want to attach Telegraf to an existing http server.
+
+<!-- global bot, tlsOptions -->
+
+```TS
+import { createServer } from "http";
+
+createServer(await bot.createWebhook({ domain: "example.com" })).listen(3000);
+```
+
+```TS
+import { createServer } from "https";
+
+createServer(tlsOptions, await bot.createWebhook({ domain: "example.com" })).listen(8443);
+```
+
+- [AWS Lambda example integration](https://github.com/feathers-studio/telegraf-docs/tree/master/examples/functions/aws-lambda)
+- [Google Cloud Functions example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/functions/google-cloud-function.ts)
+- [`express` example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/webhook/express.ts)
+- [`fastify` example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/webhook/fastify.ts)
+- [`koa` example integration](https://github.com/feathers-studio/telegraf-docs/blob/master/examples/webhook/koa.ts)
+- [NestJS framework integration module](https://github.com/bukhalo/nestjs-telegraf)
+- [Cloudflare Workers integration module](https://github.com/Tsuk1ko/cfworker-middware-telegraf)
+- Use [`bot.handleUpdate`](https://telegraf.js.org/classes/Telegraf-1.html#handleupdate) to write new integrations
+
+### Error handling
+
+If middleware throws an error or times out, Telegraf calls `bot.handleError`. If it rethrows, update source closes, and then the error is printed to console and process terminates. If it does not rethrow, the error is swallowed.
+
+Default `bot.handleError` always rethrows. You can overwrite it using `bot.catch` if you need to.
+
+⚠️ Swallowing unknown errors might leave the process in invalid state!
+
+ℹ️ In production, `systemd` or [`pm2`](https://www.npmjs.com/package/pm2) can restart your bot if it exits for any reason.
+
+## Advanced topics
+
+### Working with files
+
+Supported file sources:
+
+- `Existing file_id`
+- `File path`
+- `Url`
+- `Buffer`
+- `ReadStream`
+
+Also, you can provide an optional name of a file as `filename` when you send the file.
+
+<!-- global bot, fs -->
+
+```js
+bot.on('message', async (ctx) => {
+  // resend existing file by file_id
+  await ctx.replyWithSticker('123123jkbhj6b')
+
+  // send file
+  await ctx.replyWithVideo(Input.fromLocalFile('/path/to/video.mp4'))
+
+  // send stream
+  await ctx.replyWithVideo(
+    Input.fromReadableStream(fs.createReadStream('/path/to/video.mp4'))
+  )
+
+  // send buffer
+  await ctx.replyWithVoice(Input.fromBuffer(Buffer.alloc()))
+
+  // send url via Telegram server
+  await ctx.replyWithPhoto(Input.fromURL('https://picsum.photos/200/300/'))
+
+  // pipe url content
+  await ctx.replyWithPhoto(
+    Input.fromURLStream('https://picsum.photos/200/300/?random', 'kitten.jpg')
+  )
+})
+```
+
+### Middleware
+
+In addition to `ctx: Context`, each middleware receives `next: () => Promise<void>`.
+
+As in Koa and some other middleware-based libraries,
+`await next()` will call next middleware and wait for it to finish:
+
+```TS
+import { Telegraf } from '@icanseeuanywhere/telekaf';
+import { message } from '@icanseeuanywhere/telekaf/filters';
+
+const bot = new Telegraf(process.env.BOT_TOKEN);
+
+bot.use(async (ctx, next) => {
+  console.time(`Processing update ${ctx.update.update_id}`);
+  await next() // runs next middleware
+  // runs after next middleware finishes
+  console.timeEnd(`Processing update ${ctx.update.update_id}`);
+})
+
+bot.on(message('text'), (ctx) => ctx.reply('Hello World'));
+bot.launch();
+
+// Enable graceful stop
+process.once('SIGINT', () => bot.stop('SIGINT'));
+process.once('SIGTERM', () => bot.stop('SIGTERM'));
+```
+
+With this simple ability, you can:
+
+- extract information from updates and then `await next()` to avoid disrupting other middleware,
+- like [`Composer`] and [`Router`], `await next()` for updates you don't wish to handle,
+- like [`session`] and [`Scenes`], [extend the context](#extending-context) by mutating `ctx` before `await next()`,
+- [intercept API calls](https://github.com/telegraf/telegraf/discussions/1267#discussioncomment-254525),
+- reuse [other people's code](https://www.npmjs.com/search?q=telegraf-),
+- do whatever **you** come up with!
+
+[`Telegraf`]: https://telegraf.js.org/classes/Telegraf-1.html
+[`Composer`]: https://telegraf.js.org/classes/Composer.html
+[`Context`]: https://telegraf.js.org/classes/Context.html
+[`Router`]: https://telegraf.js.org/classes/Router.html
+[`session`]: https://telegraf.js.org/modules.html#session
+[`Scenes`]: https://telegraf.js.org/modules/Scenes.html
+
+### Usage with TypeScript
+
+Telegraf is written in TypeScript and therefore ships with declaration files for the entire library.
+Moreover, it includes types for the complete Telegram API via the [`typegram`](https://github.com/KnorpelSenf/typegram) package.
+While most types of Telegraf's API surface are self-explanatory, there's some notable things to keep in mind.
+
+#### Extending `Context`
+
+The exact shape of `ctx` can vary based on the installed middleware.
+Some custom middleware might register properties on the context object that Telegraf is not aware of.
+Consequently, you can change the type of `ctx` to fit your needs in order for you to have proper TypeScript types for your data.
+This is done through Generics:
+
+```ts
+import { Context, Telegraf } from '@icanseeuanywhere/telekaf'
+
+// Define your own context type
+interface MyContext extends Context {
+  myProp?: string
+  myOtherProp?: number
+}
+
+// Create your bot and tell it about your context type
+const bot = new Telegraf<MyContext>('SECRET TOKEN')
+
+// Register middleware and launch your bot as usual
+bot.use((ctx, next) => {
+  // Yay, `myProp` is now available here as `string | undefined`!
+  ctx.myProp = ctx.chat?.first_name?.toUpperCase()
+  return next()
+})
+// ...
+```