@krischoichoi/channel-telegram 0.6.0

package/lib/outbound.js

@@ -0,0 +1,215 @@
+import { ChannelError, ChannelSendError } from '@krischoichoi/channel-core';
+import { sendWithFallback } from './render/index.js';
+/** Maximum Telegram `callback_data` size (1–64 bytes, plan §11). */
+const CALLBACK_DATA_MAX_BYTES = 64;
+/** Telegram ForceReply input placeholder length (Bot API 10.2). */
+const FORCE_REPLY_PLACEHOLDER_MAX_CHARS = 64;
+export class OutboundSender {
+    upstream;
+    logger;
+    formatting;
+    constructor(upstream, logger, options = {}) {
+        this.upstream = upstream;
+        this.logger = logger;
+        this.formatting = { mode: 'auto', fallback: 'plain', ...options.formatting };
+    }
+    async send(target, message) {
+        try {
+            const replyMarkup = replyMarkupFor(message);
+            const media = collectSendableMedia(message.parts);
+            if (media.length > 0) {
+                let last;
+                for (const [index, item] of media.entries()) {
+                    // The first attachment carries the textual caption; controls belong
+                    // on the last message so SendResult.messageId is the interaction id.
+                    last = await this.sendMediaWithFormatting(target, item, index === 0 ? message : { ...message, text: undefined }, index === media.length - 1 ? replyMarkup : undefined);
+                }
+                if (!last)
+                    throw new ChannelSendError('telegram media send produced no message');
+                return { delivered: true, messageId: last.messageId, raw: last.raw };
+            }
+            const text = message.text ?? '';
+            if (!text) {
+                throw new ChannelSendError('telegram message has no sendable text or media');
+            }
+            const response = await this.sendTextWithFormatting(target, text, sendOptions(target, message), replyMarkup);
+            return { delivered: true, messageId: response.messageId, raw: response.raw };
+        }
+        catch (error) {
+            this.logger.error(`[channel-telegram] send failed to '${target.conversationId}'`, error instanceof Error ? error.message : error);
+            // Preserve TelegramApiError fields (kind/errorCode/retryAfter) and
+            // adapter-generated ChannelSendError diagnostics for outer policy.
+            if (error instanceof ChannelError)
+                throw error;
+            throw new ChannelSendError(`telegram send failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    /** Send text through the configured renderer with exact-once fallback. */
+    async sendTextWithFormatting(target, source, options, replyMarkup) {
+        const send = async (plan) => {
+            if (plan.kind === 'rich') {
+                let last;
+                for (const [index, text] of plan.texts.entries()) {
+                    last = await this.upstream.sendRichMessage(target.conversationId, { markdown: text }, options, { ...(replyMarkup && index === plan.texts.length - 1 ? { replyMarkup } : {}) });
+                }
+                if (!last)
+                    throw new ChannelSendError('telegram rich send produced no message');
+                return last;
+            }
+            let last;
+            for (const [index, chunk] of plan.chunks.entries()) {
+                last = await this.upstream.sendMessage(target.conversationId, chunk, options, {
+                    ...(plan.parseMode ? { parseMode: plan.parseMode } : {}),
+                    ...(replyMarkup && index === plan.chunks.length - 1 ? { replyMarkup } : {}),
+                });
+            }
+            if (!last)
+                throw new ChannelSendError('telegram text send produced no message');
+            return last;
+        };
+        return sendWithFallback(source, { mode: this.formatting.mode }, send);
+    }
+    /** Send media with the text rendered as a ≤1024 caption (plain fallback). */
+    async sendMediaWithFormatting(target, media, message, replyMarkup) {
+        const sendOptions = {
+            replyToMessageId: message.replyTo ?? target.replyToMessageId,
+            messageThreadId: target.threadId,
+        };
+        const sendWithoutCaption = async () => {
+            return this.upstream.sendMedia(target.conversationId, media, sendOptions, { ...(replyMarkup ? { replyMarkup } : {}) });
+        };
+        const caption = message.text ?? '';
+        if (!caption)
+            return sendWithoutCaption();
+        const plainCaption = markdownToPlainCaption(caption);
+        // Captions are rendered as plain text (rich/HTML media captions are out of
+        // scope); any format error falls back to the stripped caption once.
+        try {
+            return await this.upstream.sendMedia(target.conversationId, { ...media, caption: truncateCaption(plainCaption) }, sendOptions, { ...(replyMarkup ? { replyMarkup } : {}) });
+        }
+        catch (error) {
+            if (isFormattingFailure(error)) {
+                return this.upstream.sendMedia(target.conversationId, { ...media, caption: truncateCaption(markdownToPlainCaption(caption)) }, sendOptions, { ...(replyMarkup ? { replyMarkup } : {}) });
+            }
+            throw error;
+        }
+    }
+}
+/** Whether an error is a formatting failure eligible for plain fallback. */
+function isFormattingFailure(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        error.kind === 'format');
+}
+/** Plain caption text (stripped of markdown) for the fallback path. */
+function markdownToPlainCaption(source) {
+    return source
+        .replace(/\*\*(.+?)\*\*/g, '$1')
+        .replace(/\*(.+?)\*/g, '$1')
+        .replace(/`([^`]+)`/g, '$1')
+        .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1');
+}
+/** Caption cap: 1024 grapheme clusters (plan §7.1). */
+const CAPTION_MAX_GRAPHEMES = 1024;
+/** Truncate a caption to at most 1024 grapheme clusters, never mid-cluster. */
+function truncateCaption(text) {
+    const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+    const graphemes = [...segmenter.segment(text)].map((s) => s.segment);
+    if (graphemes.length <= CAPTION_MAX_GRAPHEMES)
+        return text;
+    return graphemes.slice(0, CAPTION_MAX_GRAPHEMES).join('');
+}
+/**
+ * Map `OutboundMessage.actions` to a Telegram `InlineKeyboardMarkup`.
+ *
+ * Each row becomes one inline-keyboard row; each action becomes a button with
+ * `text = label`, `callback_data = id` and the mapped style. An action id that
+ * exceeds Telegram's 64-byte `callback_data` cap fails closed (we cannot
+ * round-trip a truncated id), rather than silently dropping the button.
+ */
+export function actionsToReplyMarkup(actions) {
+    if (!actions || actions.length === 0)
+        return undefined;
+    const rows = [];
+    for (const row of actions) {
+        const buttons = [];
+        for (const action of row.actions) {
+            const idBytes = new TextEncoder().encode(action.id).byteLength;
+            if (idBytes > CALLBACK_DATA_MAX_BYTES) {
+                throw new ChannelSendError(`telegram action id exceeds ${CALLBACK_DATA_MAX_BYTES}-byte callback_data limit`);
+            }
+            buttons.push({
+                text: action.label,
+                callback_data: action.id,
+                ...(action.style && action.style !== 'default' ? { style: action.style } : {}),
+            });
+        }
+        if (buttons.length > 0)
+            rows.push(buttons);
+    }
+    if (rows.length === 0)
+        return undefined;
+    return { inline_keyboard: rows };
+}
+/**
+ * Convert every binary part to media. An unsupported carrier fails before
+ * delivery begins, so a message can never silently omit a later attachment.
+ */
+function collectSendableMedia(parts) {
+    const media = [];
+    for (const part of parts ?? []) {
+        switch (part.type) {
+            case 'image':
+            case 'file':
+            case 'audio':
+            case 'video': {
+                if (part.localData) {
+                    media.push({
+                        type: part.type,
+                        localData: part.localData,
+                        mimeType: part.mimeType,
+                        name: part.name,
+                    });
+                    break;
+                }
+                const ref = part.url ?? part.resourceRef;
+                if (ref) {
+                    media.push({ type: part.type, url: ref, mimeType: part.mimeType, name: part.name });
+                    break;
+                }
+                throw new ChannelSendError(`telegram ${part.type} media has no supported localData, url, or resourceRef carrier`);
+            }
+        }
+    }
+    return media;
+}
+/**
+ * Telegram does not permit ForceReply and an inline keyboard on the same
+ * message. Treat the generic contract as mutually exclusive so a caller never
+ * accidentally creates an uncorrelatable custom-answer prompt.
+ */
+function replyMarkupFor(message) {
+    if (message.replyPrompt) {
+        if (message.actions?.length) {
+            throw new ChannelSendError('telegram replyPrompt cannot be combined with inline actions');
+        }
+        const placeholder = message.replyPrompt.placeholder;
+        if (placeholder && [...placeholder].length > FORCE_REPLY_PLACEHOLDER_MAX_CHARS) {
+            throw new ChannelSendError(`telegram replyPrompt placeholder exceeds ${FORCE_REPLY_PLACEHOLDER_MAX_CHARS}-character limit`);
+        }
+        return {
+            force_reply: true,
+            ...(placeholder
+                ? { input_field_placeholder: placeholder }
+                : {}),
+        };
+    }
+    return actionsToReplyMarkup(message.actions);
+}
+function sendOptions(target, message) {
+    return {
+        replyToMessageId: message.replyTo ?? target.replyToMessageId,
+        messageThreadId: target.threadId,
+    };
+}
+//# sourceMappingURL=outbound.js.map

package/lib/outbound.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound.js","sourceRoot":"","sources":["../src/outbound.ts"],"names":[],"mappings":"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"}

package/lib/render/html.d.ts

@@ -0,0 +1,13 @@
+import { type MarkdownBlock } from './markdown.js';
+export declare function escapeHtml(text: string): string;
+/** Kept as a public helper; parsing now happens through mdast rather than regex. */
+export declare function inlineMarkdownToHtml(text: string): string;
+export declare function blockToHtml(block: MarkdownBlock): string;
+/**
+ * Oversized generated HTML degrades to escaped text chunks. Every returned
+ * chunk is independently valid Telegram HTML; no tag is left open across a
+ * message boundary.
+ */
+export declare function safeHtmlSplit(html: string, maxLength?: number): string[];
+export declare function renderHtml(source: string, limit?: number): string[];
+//# sourceMappingURL=html.d.ts.map

package/lib/render/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/render/html.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAIrE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C;AA6CD,oFAAoF;AACpF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAExD;AAID;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAW,GAAG,MAAM,EAAE,CAqB1E;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,SAAW,GAAG,MAAM,EAAE,CAoBrE"}

package/lib/render/html.js

@@ -0,0 +1,110 @@
+import { toString } from 'mdast-util-to-string';
+import { tokenizeMarkdown } from './markdown.js';
+import { blockToPlain } from './plain.js';
+import { splitByGraphemes } from './segment.js';
+export function escapeHtml(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function escapeAttr(value) {
+    return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}
+function childrenToHtml(node) {
+    return node.children.map(nodeToHtml).join('');
+}
+function nodeToHtml(node) {
+    switch (node.type) {
+        case 'text': return escapeHtml(node.value);
+        case 'strong': return `<b>${childrenToHtml(node)}</b>`;
+        case 'emphasis': return `<i>${childrenToHtml(node)}</i>`;
+        case 'delete': return `<s>${childrenToHtml(node)}</s>`;
+        case 'inlineCode': return `<code>${escapeHtml(node.value)}</code>`;
+        case 'code': return `<pre><code>${escapeHtml(node.value)}</code></pre>`;
+        case 'link': return `<a href="${escapeAttr(node.url)}">${childrenToHtml(node)}</a>`;
+        case 'image': return escapeHtml(node.alt ?? node.url);
+        case 'break': return '\n';
+        case 'heading': return `<b>${childrenToHtml(node)}</b>`;
+        case 'blockquote': return `<blockquote>${childrenToHtml(node)}</blockquote>`;
+        case 'paragraph': return childrenToHtml(node);
+        case 'list':
+            return node.children.map((item, index) => {
+                const marker = node.ordered ? `${(node.start ?? 1) + index}.` : '-';
+                return `${marker} ${childrenToHtml(item)}`;
+            }).join('\n');
+        case 'listItem': return childrenToHtml(node);
+        case 'table': return `<pre>${escapeHtml(toString(node))}</pre>`;
+        case 'tableRow': return node.children.map((cell) => toString(cell)).join(' | ');
+        case 'tableCell': return childrenToHtml(node);
+        case 'html': return escapeHtml(node.value);
+        case 'thematicBreak': return '---';
+        case 'footnoteDefinition': return childrenToHtml(node);
+        case 'footnoteReference': return escapeHtml(node.label ?? node.identifier);
+        case 'linkReference': return childrenToHtml(node);
+        case 'imageReference': return escapeHtml(node.alt ?? node.label ?? node.identifier);
+        case 'definition': return '';
+        case 'yaml': return escapeHtml(node.value);
+        case 'root': return childrenToHtml(node);
+    }
+}
+/** Kept as a public helper; parsing now happens through mdast rather than regex. */
+export function inlineMarkdownToHtml(text) {
+    const block = tokenizeMarkdown(text)[0];
+    return block ? nodeToHtml(block.node) : '';
+}
+export function blockToHtml(block) {
+    return nodeToHtml(block.node);
+}
+const HTML_MAX = 4096;
+/**
+ * Oversized generated HTML degrades to escaped text chunks. Every returned
+ * chunk is independently valid Telegram HTML; no tag is left open across a
+ * message boundary.
+ */
+export function safeHtmlSplit(html, maxLength = HTML_MAX) {
+    if (html.length <= maxLength)
+        return [html];
+    const plain = html
+        .replace(/<[^>]*>/g, '')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&amp;/g, '&');
+    const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+    const chunks = [];
+    let current = '';
+    for (const item of segmenter.segment(plain)) {
+        const escaped = escapeHtml(item.segment);
+        if (current && current.length + escaped.length > maxLength) {
+            chunks.push(current);
+            current = '';
+        }
+        current += escaped;
+    }
+    if (current)
+        chunks.push(current);
+    return chunks;
+}
+export function renderHtml(source, limit = HTML_MAX) {
+    if (!source)
+        return [];
+    const messages = [];
+    let buffer = '';
+    const flush = () => {
+        if (buffer)
+            messages.push(buffer);
+        buffer = '';
+    };
+    for (const block of tokenizeMarkdown(source)) {
+        const html = blockToHtml(block);
+        if (html.length > limit) {
+            flush();
+            messages.push(...splitByGraphemes(blockToPlain(block), limit).map(escapeHtml));
+            continue;
+        }
+        if (buffer && buffer.length + html.length + 1 > limit)
+            flush();
+        buffer += `${buffer ? '\n' : ''}${html}`;
+    }
+    flush();
+    return messages;
+}
+//# sourceMappingURL=html.js.map

package/lib/render/html.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.js","sourceRoot":"","sources":["../../src/render/html.ts"],"names":[],"mappings":"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"}

package/lib/render/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Renderer entry point (plan §Phase 2 / §20.9).
+ *
+ * `renderMessage(source, options)` turns Agent Markdown into a concrete
+ * outbound plan for one of the configured output modes. The plan is consumed by
+ * the adapter's buffered send path and by the rich streaming final edit — it
+ * never touches the network.
+ *
+ * The formatting fallback is contained here too: `sendWithFallback` tries the
+ * requested mode once and, ONLY on a `format`-kind `TelegramApiError`, retries
+ * the same content once as plain text. 401/403 / 429 / network / 5xx are never
+ * treated as a formatting problem (plan §20.9), so there is no infinite
+ * rich→plain→rich loop.
+ */
+import type { TelegramApiError } from '../api-error.js';
+export type RenderMode = 'auto' | 'rich-markdown' | 'html' | 'markdown-v2' | 'plain';
+/** A concrete, ready-to-send outbound plan for one message. */
+export type RenderPlan = {
+    kind: 'rich';
+    mode: Extract<RenderMode, 'auto' | 'rich-markdown'>;
+    texts: string[];
+} | {
+    kind: 'regular';
+    mode: Exclude<RenderMode, 'auto' | 'rich-markdown'>;
+    parseMode?: 'HTML' | 'MarkdownV2';
+    chunks: string[];
+};
+export interface RenderOptions {
+    mode: RenderMode;
+    /** Produce a caption-sized plan (1024) instead of the regular 4096. */
+    forCaption?: boolean;
+}
+/** Resolve the default renderer for the adapter's Bot API 10.2 baseline. */
+export declare function resolveMode(mode: RenderMode): Exclude<RenderMode, 'auto'>;
+/**
+ * Render Markdown source to a plan for the given mode.
+ *
+ * - `plain`:   plain fallback, 4096 (or 1024 caption) grapheme segments.
+ * - `html`:    Telegram-safe HTML, 4096, tags/entities never split.
+ * - `markdown-v2`: fully escaped MarkdownV2, 4096.
+ * - `rich-markdown`: block-aware Rich Message markdown, 32768 UTF-8 bytes.
+ * - `auto`: Rich Markdown (the adapter requires Bot API 10.2 or newer).
+ */
+export declare function renderMessage(source: string, options: RenderOptions): RenderPlan;
+/**
+ * Whether an error is a formatting failure that warrants a one-shot plain
+ * fallback. Only `format`-kind `TelegramApiError`s qualify; everything else
+ * (401/403 / 429 / network / 5xx) propagates (plan §20.9).
+ */
+export declare function isFormattingFailure(error: unknown): error is TelegramApiError;
+export type SendPlan = (plan: RenderPlan) => Promise<unknown>;
+/**
+ * Send a rendered plan with exactly-once formatting fallback:
+ *
+ * - try the requested mode;
+ * - if it throws a `format`-kind error and the requested mode was not already
+ *   plain, retry the SAME content once as plain text;
+ * - any other error, or a format error on the plain retry, rethrows unchanged.
+ *
+ * This guarantees the fallback runs at most once and can never enter an
+ * infinite rich→plain→rich loop.
+ */
+export declare function sendWithFallback(source: string, options: RenderOptions, send: SendPlan): Promise<unknown>;
+//# sourceMappingURL=index.d.ts.map

package/lib/render/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAKxD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,eAAe,GAAG,MAAM,GAAG,aAAa,GAAG,OAAO,CAAC;AAErF,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GACtF;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC;IACpD,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAClC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAEN,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,uEAAuE;IACvE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,EAAE,MAAM,CAAC,CAGzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,UAAU,CAmBhF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAM7E;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAY/G"}

package/lib/render/index.js

@@ -0,0 +1,76 @@
+import { renderRichMarkdown } from './markdown.js';
+import { renderHtml } from './html.js';
+import { renderMarkdownV2, renderPlain, renderPlainCaption } from './plain.js';
+/** Resolve the default renderer for the adapter's Bot API 10.2 baseline. */
+export function resolveMode(mode) {
+    if (mode === 'auto')
+        return 'rich-markdown';
+    return mode;
+}
+/**
+ * Render Markdown source to a plan for the given mode.
+ *
+ * - `plain`:   plain fallback, 4096 (or 1024 caption) grapheme segments.
+ * - `html`:    Telegram-safe HTML, 4096, tags/entities never split.
+ * - `markdown-v2`: fully escaped MarkdownV2, 4096.
+ * - `rich-markdown`: block-aware Rich Message markdown, 32768 UTF-8 bytes.
+ * - `auto`: Rich Markdown (the adapter requires Bot API 10.2 or newer).
+ */
+export function renderMessage(source, options) {
+    const mode = resolveMode(options.mode);
+    if (mode === 'plain') {
+        const texts = options.forCaption ? renderPlainCaption(source) : renderPlain(source);
+        return { kind: 'regular', mode: 'plain', chunks: texts };
+    }
+    if (mode === 'html') {
+        return { kind: 'regular', mode: 'html', parseMode: 'HTML', chunks: renderHtml(source) };
+    }
+    if (mode === 'markdown-v2') {
+        return {
+            kind: 'regular',
+            mode: 'markdown-v2',
+            parseMode: 'MarkdownV2',
+            chunks: renderMarkdownV2(source),
+        };
+    }
+    // rich-markdown
+    return { kind: 'rich', mode: 'rich-markdown', texts: renderRichMarkdown(source) };
+}
+/**
+ * Whether an error is a formatting failure that warrants a one-shot plain
+ * fallback. Only `format`-kind `TelegramApiError`s qualify; everything else
+ * (401/403 / 429 / network / 5xx) propagates (plan §20.9).
+ */
+export function isFormattingFailure(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        error.kind === 'format');
+}
+/**
+ * Send a rendered plan with exactly-once formatting fallback:
+ *
+ * - try the requested mode;
+ * - if it throws a `format`-kind error and the requested mode was not already
+ *   plain, retry the SAME content once as plain text;
+ * - any other error, or a format error on the plain retry, rethrows unchanged.
+ *
+ * This guarantees the fallback runs at most once and can never enter an
+ * infinite rich→plain→rich loop.
+ */
+export async function sendWithFallback(source, options, send) {
+    const requested = resolveMode(options.mode);
+    const first = renderMessage(source, options);
+    try {
+        return await send(first);
+    }
+    catch (error) {
+        if (!isFormattingFailure(error))
+            throw error;
+        // Only downgrade if we weren't already plain.
+        if (requested === 'plain')
+            throw error;
+        const plain = renderMessage(source, { ...options, mode: 'plain' });
+        return await send(plain);
+    }
+}
+//# sourceMappingURL=index.js.map

package/lib/render/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/render/index.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAoB/E,4EAA4E;AAC5E,MAAM,UAAU,WAAW,CAAC,IAAgB;IAC1C,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,eAAe,CAAC;IAC5C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc,EAAE,OAAsB;IAClE,MAAM,IAAI,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACpF,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC3D,CAAC;IACD,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;IAC1F,CAAC;IACD,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;QAC3B,OAAO;YACL,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,aAAa;YACnB,SAAS,EAAE,YAAY;YACvB,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC;SACjC,CAAC;IACJ,CAAC;IACD,gBAAgB;IAChB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;AACpF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAA4B,CAAC,IAAI,KAAK,QAAQ,CAChD,CAAC;AACJ,CAAC;AAID;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAc,EAAE,OAAsB,EAAE,IAAc;IAC3F,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,mBAAmB,CAAC,KAAK,CAAC;YAAE,MAAM,KAAK,CAAC;QAC7C,8CAA8C;QAC9C,IAAI,SAAS,KAAK,OAAO;YAAE,MAAM,KAAK,CAAC;QACvC,MAAM,KAAK,GAAG,aAAa,CAAC,MAAM,EAAE,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACnE,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC"}

package/lib/render/markdown.d.ts

@@ -0,0 +1,38 @@
+/** GFM-aware Markdown parsing and Telegram Rich Message segmentation. */
+import type { Root, RootContent } from 'mdast';
+interface BlockBase {
+    node: RootContent;
+    markdown: string;
+}
+/** Compatibility surface consumed by the plain and HTML renderers. */
+export type MarkdownBlock = (BlockBase & {
+    kind: 'code';
+    lang: string;
+    code: string;
+}) | (BlockBase & {
+    kind: 'heading';
+    level: number;
+    text: string;
+}) | (BlockBase & {
+    kind: 'table';
+    header: string[];
+    rows: string[][];
+}) | (BlockBase & {
+    kind: 'blockquote';
+    content: string;
+}) | (BlockBase & {
+    kind: 'list';
+    ordered: boolean;
+    items: string[];
+}) | (BlockBase & {
+    kind: 'paragraph';
+    text: string;
+});
+export declare function parseMarkdown(source: string): Root;
+export declare function tokenizeMarkdown(source: string): MarkdownBlock[];
+export declare function renderBlock(block: MarkdownBlock): string;
+/** Segment parsed blocks under Telegram's byte, block-count, and depth limits. */
+export declare function segmentRich(blocks: MarkdownBlock[], limit?: number): string[];
+export declare function renderRichMarkdown(source: string, limit?: number): string[];
+export { tokenizeMarkdown as tokenize };
+//# sourceMappingURL=markdown.d.ts.map

package/lib/render/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/render/markdown.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,OAAO,KAAK,EAAQ,IAAI,EAAE,WAAW,EAAmB,MAAM,OAAO,CAAC;AActE,UAAU,SAAS;IACjB,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,sEAAsE;AACtE,MAAM,MAAM,aAAa,GACrB,CAAC,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAC1D,CAAC,SAAS,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAC9D,CAAC,SAAS,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAA;CAAE,CAAC,GACnE,CAAC,SAAS,GAAG;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,GACrD,CAAC,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,GACjE,CAAC,SAAS,GAAG;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEtD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAKlD;AAkDD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,EAAE,CAGhE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAExD;AAmFD,kFAAkF;AAClF,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,KAAK,SAAwB,GAAG,MAAM,EAAE,CAiC5F;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,SAAwB,GAAG,MAAM,EAAE,CAE1F;AAED,OAAO,EAAE,gBAAgB,IAAI,QAAQ,EAAE,CAAC"}