@emulon/telegram 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Katsuba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,212 @@
+# @emulon/telegram
+
+A local Telegram Bot API for the polling-only slice selected in
+[ADR 0037](../../docs/decisions/0037-telegram-bot-api-polling-slice.md). The
+[compatibility manifest](src/compatibility.ts) is the authoritative tested
+scope. This release issues bots, authenticates their tokens, answers `getMe`,
+publishes plain or MarkdownV2 channel posts with `sendMessage` and delivers
+reaction counts through `getUpdates` polling; every other method the pinned
+client types returns an explicit 501.
+
+```ts
+import { Emulon } from 'emulon';
+import telegram from '@emulon/telegram';
+import { Bot } from 'grammy';
+
+await using env = await Emulon.start({
+  services: {
+    tg: telegram({
+      fixtures: {
+        channels: [{
+          id: -1001234567890,
+          title: 'Local News',
+          username: 'local_news',
+        }],
+      },
+    }),
+  },
+});
+const { token } = await env.services.tg.bots.create({
+  username: 'poster_bot',
+  firstName: 'Poster',
+});
+const bot = new Bot(token, { client: { apiRoot: env.endpoints.tg.api } });
+console.log(await bot.api.getMe());
+
+const post = await bot.api.sendMessage('@local_news', '*Hello*, world\\!', {
+  parse_mode: 'MarkdownV2',
+});
+console.log(post.message_id, post.text, post.entities);
+console.log(await env.services.tg.messages.list({ chatId: -1001234567890 }));
+```
+
+## Run the example
+
+From the repository root:
+
+```sh
+deno task example:telegram
+```
+
+The [example](../../examples/telegram/README.md) starts an instance with one
+channel, issues a bot, has it convert a Markdown post with `md-to-telegram`,
+split it and publish each part to `@local_news` as silent MarkdownV2 messages
+with link previews enabled, sets a reaction on the post and reads it back
+through `getUpdates`. It prints the published messages with their entities, the
+`message_reaction_count` update and the offset to store for the next run.
+
+## Connection and commands
+
+The endpoint URL is grammY's `apiRoot` as is, without a trailing slash; grammY
+requests `<apiRoot>/bot<token>/<method>`. For a running project configured with
+instance `tg`:
+
+```sh
+emulon tg bots create --username poster_bot --first-name Poster --json
+emulon tg messages list --chat-id -1001234567890 --limit 10 --json
+emulon tg reactions set --chat-id -1001234567890 --message-id 1 \
+  --reactions '[{"type":{"type":"emoji","emoji":"👍"},"total_count":3}]' --json
+emulon tg updates inspect --bot-id 7000000001 --json
+emulon tg compatibility get --json
+```
+
+`bots create` is the only output that contains a token, and it shows it once.
+Tokens are `<bot id>:<secret>` with a 256-bit random secret; the instance keeps
+only a SHA-256 verifier. A durable restart keeps issued tokens valid, and reset
+removes every bot, so earlier tokens fail even when a new bot gets the same ID.
+Bot usernames end in `bot` and share one case-insensitive namespace with channel
+usernames.
+
+`fixtures.channels` entries have a negative `-100…` `id`, a `title` and a
+`username` unique without regard to case.
+
+## Channel posts
+
+`sendMessage` posts to a configured channel addressed by its ID or by
+`@username`. It accepts `chat_id`, `text`, `parse_mode: "MarkdownV2"` (or no
+parse mode), `disable_notification` and `link_preview_options` with
+`is_disabled: false`; notifications and link previews are not simulated. Any
+other field, `is_disabled: true`, and the HTML and legacy Markdown parse modes
+fail with 501 rather than being ignored.
+
+MarkdownV2 is parsed the way Telegram parses it into text and entities whose
+offsets and lengths count UTF-16 code units: escapes, bold, italic, underline,
+strikethrough, spoilers, inline code, fenced code with a language, links, block
+quotations and expandable `**>…||` quotations, with Telegram's nesting rules.
+This covers everything `md-to-telegram` emits for MarkdownV2, including posts
+cut by its `splitMessage`; send each part as its own message. Custom emoji,
+date-time entities, `tg://` mentions, non-HTTP link targets and code spanning
+quoted lines are not emulated and fail with 400 `can't parse entities`, and no
+URL, mention or hashtag entities are detected automatically.
+
+Malformed markup fails with 400 `Bad Request: can't parse entities` before the
+length check; text longer than 4096 UTF-16 units after parsing fails with 400
+`Bad Request: message is too long`. A failed send writes nothing. Each
+successful send takes the next `message_id` of its channel in the same
+transaction as the write, so IDs increase without gaps across bots, concurrent
+calls and restarts.
+
+`messages list` (`messages.list`) takes a numeric `chatId` and an optional
+`limit` from 1 to 100 (default 100), and returns the most recent messages oldest
+first with the submitted `source`, `parseMode`, rendered `text` and `entities`.
+
+## Reaction polling
+
+A bot receives `message_reaction_count` updates only after it asks for them, as
+in Telegram: call `getUpdates` with
+`allowed_updates: ['message_reaction_count']` first. A reaction set before that
+never reaches the bot.
+
+A consumer that runs on a schedule keeps the offset between runs. On its first
+run it has none; each run drains until an empty batch, and that empty call with
+the new offset is what confirms the batch before it:
+
+```ts
+async function drain(bot: Bot, stored: number | undefined) {
+  let offset = stored;
+
+  while (true) {
+    const updates = await bot.api.getUpdates({
+      ...(offset === undefined ? {} : { offset }),
+      limit: 100,
+      timeout: 0,
+      allowed_updates: ['message_reaction_count'],
+    });
+
+    if (updates.length === 0) {
+      return offset; // store it for the next run
+    }
+
+    for (const update of updates) {
+      console.log(update.message_reaction_count?.reactions);
+    }
+
+    offset = updates.at(-1)!.update_id + 1;
+  }
+}
+
+let offset = await drain(bot, undefined); // subscribes, finds nothing
+await env.services.tg.reactions.set({
+  chatId: -1001234567890,
+  messageId: post.message_id,
+  reactions: [{ type: { type: 'emoji', emoji: '👍' }, total_count: 3 }],
+});
+offset = await drain(bot, offset); // prints the 👍 3 count
+```
+
+`reactions set` (`reactions.set`) replaces the absolute counts of a sent channel
+message with a list of Bot API `ReactionCount` objects: `emoji` reactions with
+one of the emoji the Bot API types, `custom_emoji` with a numeric ID, and
+`paid`, each at most once, with a nonnegative `total_count`. Zero counts are
+dropped. When the counts change, every bot subscribed at that moment gets one
+update with the chat, `message_id`, Unix `date` and the full `reactions` list,
+in the same transaction; setting the same counts again queues nothing. Counts
+are ordered by `total_count`, then paid, emoji and custom emoji.
+
+Each bot has its own durable queue with update IDs from 1. `getUpdates` takes
+`offset`, `limit` (1–100, default 100), `timeout` (seconds, default 0) and
+`allowed_updates`. A nonnegative offset confirms every smaller ID, a negative
+offset keeps only that many of the latest updates, and returning a batch
+confirms nothing. An omitted `allowed_updates` keeps the last list and an empty
+one restores Telegram's default, which leaves out reaction counts; a change
+never touches updates already queued. A positive `timeout` waits in real time
+and returns as soon as an update arrives. One `getUpdates` call per bot runs at
+a time; an overlapping call receives 409. Disconnecting ends a waiting poll, and
+reset or shutdown ends it with a 503 envelope rather than an empty batch.
+
+`updates inspect` (`updates.inspect`) takes a `botId` and an optional `limit`
+from 1 to 100, and returns the subscription, the number of pending updates and
+the oldest ones, without confirming anything or showing a token.
+
+## Envelopes
+
+Responses are Bot API envelopes: `{ "ok": true, "result": ... }` on success and
+`{ "ok": false, "error_code": ..., "description": ... }` with the same HTTP
+status on failure. The token is checked before the method: a malformed token
+receives 404 and a well-formed token of no issued bot 401. With a valid token,
+an unknown method receives 404 and a known but unimplemented one, including
+`setWebhook`, `deleteWebhook` and `getWebhookInfo`, 501. Only POST with a JSON
+object body is emulated. Descriptions are fixed and never contain the token, the
+path or request input.
+
+## Limitations
+
+The [compatibility manifest](src/compatibility.ts) lists every limitation; in
+short, this is not a general Bot API:
+
+- Only `getMe`, `sendMessage` and `getUpdates` exist; every other method,
+  including the webhook methods, returns 501. There is no webhook mode, so
+  updates arrive only by polling.
+- Bots post only to configured channels; there are no users, groups, private
+  chats, media, keyboards, inline mode or payments.
+- The only update type is `message_reaction_count`, and only the `reactions set`
+  command produces it; bots cannot set reactions.
+- MarkdownV2 is limited to what `md-to-telegram` emits, and error descriptions
+  are fixed, without the offset Telegram appends.
+- An overlapping `getUpdates` receives 409 instead of ending the earlier one.
+
+Tests use `grammy@1.44.0` and `md-to-telegram@0.1.1` on loopback and never reach
+Telegram. The consumer suite runs the complete publish-and-drain loop above
+through grammY, with reactions set by the CLI and SDK. Neither client is a
+dependency of this package, and the installed archive checks under Node and Deno
+assert that.

package/esm/auth/tokens.d.ts

@@ -0,0 +1,18 @@
+/** Bot tokens are `<id>:<secret>`; grammY puts the whole token in the path. */
+export interface ParsedToken {
+    botId: number;
+    token: string;
+}
+/** 32 random bytes: 256 bits, base64url without padding (43 characters). */
+export declare const secretBytes = 32;
+export declare function issueToken(botId: number): string;
+/**
+ * A token that cannot name a bot is malformed, which Telegram answers with 404
+ * rather than 401. The ID must be a canonical positive safe integer so one bot
+ * is never reachable through two spellings.
+ */
+export declare function parseToken(raw: string): ParsedToken | null;
+/** Only this digest of the full token is stored; the token is shown once. */
+export declare function verifier(token: string): Promise<string>;
+/** Compares every position, so timing does not reveal a matching prefix. */
+export declare function sameVerifier(actual: string, expected: string): boolean;

package/esm/auth/tokens.js

@@ -0,0 +1,42 @@
+/** 32 random bytes: 256 bits, base64url without padding (43 characters). */
+export const secretBytes = 32;
+const shape = /^([1-9][0-9]*):([A-Za-z0-9_-]+)$/;
+export function issueToken(botId) {
+    const bytes = crypto.getRandomValues(new Uint8Array(secretBytes));
+    const secret = btoa(String.fromCharCode(...bytes))
+        .replaceAll('+', '-')
+        .replaceAll('/', '_')
+        .replace(/=+$/, '');
+    return `${botId}:${secret}`;
+}
+/**
+ * A token that cannot name a bot is malformed, which Telegram answers with 404
+ * rather than 401. The ID must be a canonical positive safe integer so one bot
+ * is never reachable through two spellings.
+ */
+export function parseToken(raw) {
+    const match = shape.exec(raw);
+    if (!match) {
+        return null;
+    }
+    const botId = Number(match[1]);
+    return Number.isSafeInteger(botId) && String(botId) === match[1]
+        ? { botId, token: raw }
+        : null;
+}
+/** Only this digest of the full token is stored; the token is shown once. */
+export async function verifier(token) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(token));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** Compares every position, so timing does not reveal a matching prefix. */
+export function sameVerifier(actual, expected) {
+    if (actual.length !== expected.length) {
+        return false;
+    }
+    let difference = 0;
+    for (let i = 0; i < expected.length; i++) {
+        difference |= actual.charCodeAt(i) ^ expected.charCodeAt(i);
+    }
+    return difference === 0;
+}

package/esm/commands/mod.d.ts

@@ -0,0 +1,15 @@
+import { defineCommand } from 'emulon';
+import { z } from 'zod';
+import { type CreateInput, type IssuedBot } from '../model/bots.js';
+import { type ListInput, type StoredMessage } from '../model/messages.js';
+import { type ReactionsInput, type ReactionsResult } from '../model/reactions.js';
+import { type InspectInput, type QueueView } from '../model/updates.js';
+type Operation<I, O> = ReturnType<typeof defineCommand<z.ZodType<I, I>, z.ZodType<O, O>>>;
+export type Commands = {
+    'bots.create': Operation<CreateInput, IssuedBot>;
+    'messages.list': Operation<ListInput, StoredMessage[]>;
+    'reactions.set': Operation<ReactionsInput, ReactionsResult>;
+    'updates.inspect': Operation<InspectInput, QueueView>;
+};
+export declare const commands: Commands;
+export {};

package/esm/commands/mod.js

@@ -0,0 +1,52 @@
+import { defineCommand } from 'emulon';
+import { z } from 'zod';
+import { createBot, createInput, issuedSchema, } from '../model/bots.js';
+import { listInput, listMessages, storedSchema, } from '../model/messages.js';
+import { reactionsInput, reactionsResultSchema, setReactions, } from '../model/reactions.js';
+import { inspectInput, inspectUpdates, queueViewSchema, } from '../model/updates.js';
+export const commands = {
+    'bots.create': defineCommand({
+        description: 'Create a bot administering every configured channel and issue its token once (explicit secret output)',
+        input: createInput,
+        output: issuedSchema,
+        cli: {
+            path: ['bots', 'create'],
+            flags: { username: 'username', 'first-name': 'firstName' },
+        },
+        execute: (ctx, input) => createBot(ctx.store, input),
+    }),
+    'messages.list': defineCommand({
+        description: 'List the most recent messages of a channel by ID, oldest first',
+        input: listInput,
+        output: z.array(storedSchema),
+        cli: {
+            path: ['messages', 'list'],
+            flags: { 'chat-id': 'chatId', limit: 'limit' },
+        },
+        execute: (ctx, input) => listMessages(ctx.store, input),
+    }),
+    'reactions.set': defineCommand({
+        description: 'Replace the absolute reaction counts of a channel message and queue one update per subscribed bot when they change',
+        input: reactionsInput,
+        output: reactionsResultSchema,
+        cli: {
+            path: ['reactions', 'set'],
+            flags: {
+                'chat-id': 'chatId',
+                'message-id': 'messageId',
+                reactions: 'reactions',
+            },
+        },
+        execute: (ctx, input) => setReactions(ctx.store, input, ctx.clock.now()),
+    }),
+    'updates.inspect': defineCommand({
+        description: "Show a bot's pending updates and subscription without confirming them",
+        input: inspectInput,
+        output: queueViewSchema,
+        cli: {
+            path: ['updates', 'inspect'],
+            flags: { 'bot-id': 'botId', limit: 'limit' },
+        },
+        execute: (ctx, input) => inspectUpdates(ctx.store, input),
+    }),
+};

package/esm/compatibility.d.ts

@@ -0,0 +1,2 @@
+import { type CompatibilityManifest } from 'emulon';
+export declare const compatibility: CompatibilityManifest;

package/esm/compatibility.js

@@ -0,0 +1,236 @@
+import { defineCompatibility } from 'emulon';
+export const compatibility = defineCompatibility({
+    'schemaVersion': 1,
+    'plugin': '@emulon/telegram',
+    'provider': {
+        'name': 'Telegram',
+        'api': 'Telegram Bot API',
+    },
+    'operations': [
+        {
+            'id': 'getMe',
+            'method': 'POST',
+            'path': '/bot:token/getMe',
+            'surface': 'api',
+            'version': 'bot-api',
+            'auth': [
+                'local-bot-token-path',
+            ],
+            'input': [],
+            'output': 'ok, result: id, is_bot, first_name, username, can_join_groups, can_read_all_group_messages, supports_inline_queries, can_connect_to_business, has_main_web_app, has_topics_enabled, allows_users_to_create_topics, can_manage_bots, supports_join_request_queries',
+            'events': [],
+            'cases': [
+                'telegram.bots.1',
+                'telegram.bots.2',
+                'telegram.bots.3',
+                'telegram.consumer.1',
+            ],
+        },
+        {
+            'id': 'sendMessage',
+            'method': 'POST',
+            'path': '/bot:token/sendMessage',
+            'surface': 'api',
+            'version': 'bot-api',
+            'auth': [
+                'local-bot-token-path',
+            ],
+            'input': [
+                'chat_id',
+                'text',
+                'parse_mode',
+                'disable_notification',
+                'link_preview_options',
+            ],
+            'output': 'ok, result: message_id, from, sender_chat, chat, date, text, entities',
+            'events': [],
+            'cases': [
+                'telegram.messages.1',
+                'telegram.messages.2',
+                'telegram.messages.3',
+                'telegram.consumer.1',
+            ],
+        },
+        {
+            'id': 'getUpdates',
+            'method': 'POST',
+            'path': '/bot:token/getUpdates',
+            'surface': 'api',
+            'version': 'bot-api',
+            'auth': [
+                'local-bot-token-path',
+            ],
+            'input': [
+                'offset',
+                'limit',
+                'timeout',
+                'allowed_updates',
+            ],
+            'output': 'ok, result: update_id, message_reaction_count: chat, message_id, date, reactions',
+            'events': [],
+            'cases': [
+                'telegram.updates.1',
+                'telegram.updates.2',
+                'telegram.updates.3',
+                'telegram.consumer.1',
+            ],
+        },
+    ],
+    'versions': [
+        {
+            'id': 'bot-api',
+            'accepted': [
+                'bot-api',
+            ],
+            'headers': [],
+            'missing': 'The Bot API has no version selector; the method set is the one typed by @grammyjs/types@3.28.0, the types package of grammy@1.44.0.',
+            'unknown': 'No version header is read; an unknown method returns a 404 Bot API envelope and a typed but unimplemented method returns 501.',
+        },
+    ],
+    'authentication': {
+        'flows': [
+            'local-bot-token-path',
+        ],
+        'keyFormats': [
+            '<bot id>:<256-bit base64url secret> in the bot<token> path segment',
+        ],
+        'ownership': 'One token authorizes one bot of one local instance; only a SHA-256 verifier is stored, reset removes bots so earlier tokens fail even when a bot ID is reused, and a durable restart keeps issued tokens valid.',
+        'unsupported': [
+            'Real Telegram bots and BotFather',
+            'Token revocation or regeneration commands',
+            'Test environment /test paths and local Bot API server modes',
+            'MTProto and user accounts',
+        ],
+    },
+    'events': [],
+    'webhooks': {
+        'signing': 'Unsupported: this slice is polling-only; setWebhook, deleteWebhook and getWebhookInfo return 501 and no webhook can be installed',
+        'id': 'Unsupported',
+        'body': 'Unsupported',
+        'success': 'Unsupported',
+        'timeoutMs': 0,
+        'retries': 'Unsupported',
+        'redelivery': 'Unsupported',
+        'recovery': 'Unsupported',
+        'cases': [],
+    },
+    'capabilities': [
+        'http',
+        'authorization',
+        'reset',
+    ],
+    'limitations': [
+        {
+            'id': 'telegram.limitation.1',
+            'description': 'Only getMe, sendMessage and getUpdates are implemented; every other method typed by @grammyjs/types@3.28.0, including setWebhook, deleteWebhook and getWebhookInfo, returns a 501 Bot API envelope',
+        },
+        {
+            'id': 'telegram.limitation.2',
+            'description': 'Only POST with an application/json object body; GET, query parameters, form and multipart bodies return 501, and any getMe parameter returns 501 instead of being ignored',
+        },
+        {
+            'id': 'telegram.limitation.3',
+            'description': 'getMe reports a bot without optional capabilities: can_join_groups is true and every other capability flag is false',
+        },
+        {
+            'id': 'telegram.limitation.4',
+            'description': 'Failures use fixed descriptions: 404 Not Found for a path that is not bot<token>/<method>, a malformed token or an unknown method; 401 Unauthorized for a well-formed token of no issued bot; 400 for a body that is not a JSON object',
+        },
+        {
+            'id': 'telegram.limitation.5',
+            'description': 'Bot IDs are allocated locally from 7000000001 upward and bot secrets are 43 base64url characters rather than the 35 of issued Telegram tokens',
+        },
+        {
+            'id': 'telegram.limitation.6',
+            'description': 'sendMessage targets configured channels only, by ID or @username; it accepts chat_id, text, parse_mode MarkdownV2 or none, disable_notification and link_preview_options with is_disabled false, without simulating notifications or link previews. Any other field, is_disabled true or another link preview option returns 501, as do the HTML and legacy Markdown parse modes',
+        },
+        {
+            'id': 'telegram.limitation.7',
+            'description': "MarkdownV2 covers escapes, bold, italic, underline, strikethrough, spoiler, inline code, fenced code with a language, links to http and https targets, block quotations and expandable block quotations, which is everything md-to-telegram@0.1.1 emits. Custom emoji, date-time entities, user mentions through tg:// links and other link schemes return 400 can't parse entities, as does code spanning quoted lines",
+        },
+        {
+            'id': 'telegram.limitation.8',
+            'description': 'Failures carry fixed descriptions without the offending character or offset Telegram appends; entities are only those written in markup, with no automatic url, mention or hashtag detection, and rendered text keeps leading and trailing whitespace',
+        },
+        {
+            'id': 'telegram.limitation.9',
+            'description': 'A link target without a scheme gets http://, and a target that is not a URL keeps its text without an entity; targets are normalized by the WHATWG URL parser, which can differ from Telegram in trailing slashes and percent-encoding',
+        },
+        {
+            'id': 'telegram.limitation.10',
+            'description': 'getUpdates only ever returns message_reaction_count updates, produced by the reactions set command for configured channel messages; there are no users, per-user message_reaction updates, channel_post or other update types, and no provider method sets reactions',
+        },
+        {
+            'id': 'telegram.limitation.11',
+            'description': 'getUpdates accepts only offset, limit, timeout and allowed_updates as JSON numbers and a list of update type names typed by @grammyjs/types@3.28.0; a limit outside 1 to 100, a non-integer or negative timeout and an unknown update type return 400 instead of being clamped or ignored, and any other parameter returns 501',
+        },
+        {
+            'id': 'telegram.limitation.12',
+            'description': 'One getUpdates call per bot may run at a time; an overlapping call receives the 409 Conflict envelope instead of ending the earlier one. A poll cancelled by reset or shutdown receives a 503 envelope, never an empty batch',
+        },
+        {
+            'id': 'telegram.limitation.13',
+            'description': 'reactions set accepts the reaction emoji typed by @grammyjs/types@3.28.0, numeric custom emoji IDs and paid reactions, and orders counts by total_count, then paid, emoji and custom emoji, then by emoji or ID; Telegram does not document its order',
+        },
+    ],
+    'verification': {
+        'mode': 'official-client',
+        'client': 'grammy@1.44.0',
+        'suites': [
+            {
+                'path': 'packages/telegram/tests/bot_cases.ts',
+                'cases': [
+                    'telegram.bots.1',
+                    'telegram.bots.2',
+                    'telegram.bots.3',
+                ],
+            },
+            {
+                'path': 'packages/telegram/tests/message_cases.ts',
+                'cases': [
+                    'telegram.messages.1',
+                    'telegram.messages.2',
+                    'telegram.messages.3',
+                ],
+            },
+            {
+                'path': 'packages/telegram/tests/update_cases.ts',
+                'cases': [
+                    'telegram.updates.1',
+                    'telegram.updates.2',
+                    'telegram.updates.3',
+                ],
+            },
+            {
+                'path': 'packages/telegram/tests/consumer_cases.ts',
+                'cases': [
+                    'telegram.consumer.1',
+                ],
+            },
+        ],
+        'sources': [
+            'https://core.telegram.org/bots/api',
+            'https://core.telegram.org/bots/api#making-requests',
+            'https://core.telegram.org/bots/api#getme',
+            'https://core.telegram.org/bots/api#sendmessage',
+            'https://core.telegram.org/bots/api#markdownv2-style',
+            'https://core.telegram.org/bots/api#messageentity',
+            'https://core.telegram.org/bots/api#getting-updates',
+            'https://core.telegram.org/bots/api#getupdates',
+            'https://core.telegram.org/bots/api#messagereactioncountupdated',
+            'https://core.telegram.org/bots/api#reactioncount',
+            'https://grammy.dev/ref/core/apiclientoptions',
+        ],
+        'retrieved': '2026-09-25',
+        'liveProviderCompared': false,
+    },
+    'details': {
+        'route': 'grammY builds <apiRoot>/bot<token>/<method>; the endpoint URL is apiRoot with no trailing slash. The token is validated before the method is resolved, and method names are case-insensitive.',
+        'envelopes': 'Success is HTTP 200 with {ok: true, result}; failure uses the matching HTTP status with {ok: false, error_code, description}, and no description contains the token, the path or caller input.',
+        'channels': 'fixtures.channels declares channels with a -100 prefixed negative ID, a title and a username unique without regard to case; bot usernames share that namespace.',
+        'messages': 'Every successful sendMessage allocates the next message_id of its chat in the transaction that stores the message, so IDs are gapless and monotone across bots, concurrent calls and durable restart; a failed send writes nothing. Malformed MarkdownV2 fails before the 4096 UTF-16 unit limit on rendered text. messages list returns the stored source and rendered text of up to the latest 100 messages of a channel, oldest first.',
+        'updates': 'Each bot has a durable queue with its own update IDs from 1 and a remembered allowed_updates. reactions set replaces the absolute counts of a message and, when they change, queues one message_reaction_count update for every bot subscribed at that moment, in the same transaction; an unchanged snapshot queues nothing and a reaction set before a bot subscribes never reaches it. A nonnegative offset confirms smaller IDs, a negative one keeps only the last updates, returning a batch confirms nothing, and updates inspect reads a queue without confirming it.',
+        'longPolling': 'A positive timeout waits that many seconds of real time, not the instance clock, and returns as soon as an update commits. A client disconnect ends the wait, and reset or shutdown ends it before waiting for requests to drain.',
+        'transportLimit': 'The host body limit answers oversized bodies with a plain 413 before the route runs, outside the Bot API envelope.',
+    },
+});

package/esm/format/markdown_v2.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Telegram MarkdownV2 parsing, modelled on the TDLib parser the Bot API uses:
+ * one left-to-right pass over the source with a stack of open entities, so
+ * nesting, escaping and delimiter ambiguity resolve the way Telegram resolves
+ * them. Offsets and lengths are UTF-16 code units of the rendered text, which
+ * is exactly how a JavaScript string counts.
+ */
+export type EntityType = 'bold' | 'italic' | 'underline' | 'strikethrough' | 'spoiler' | 'code' | 'pre' | 'text_link' | 'blockquote' | 'expandable_blockquote';
+/** A Bot API `MessageEntity` limited to the types this parser produces. */
+export interface MessageEntity {
+    type: EntityType;
+    offset: number;
+    length: number;
+    url?: string;
+    language?: string;
+}
+export interface ParsedText {
+    text: string;
+    entities: MessageEntity[];
+}
+/**
+ * Malformed or unsupported markup. It carries no detail: Telegram's own
+ * message names the offending character, which would echo caller input.
+ */
+export declare class MarkdownError extends Error {
+    constructor();
+}
+/**
+ * Link targets are unescaped verbatim. Telegram adds `http://` to a target
+ * without a scheme and silently drops a link it cannot read as a URL; mention,
+ * custom emoji, mail and other schemes are outside this emulator's scope and
+ * are refused rather than rendered differently.
+ */
+export declare function linkTarget(raw: string): string | null;
+export declare function parseMarkdownV2(source: string): ParsedText;