@krischoichoi/channel-telegram 0.6.0

package/lib/mapper.js

@@ -0,0 +1,314 @@
+import { textParts } from '@krischoichoi/channel-core';
+import { z } from 'zod';
+/** An untrusted Telegram update did not satisfy the canonical identity schema. */
+export class TelegramInboundValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TelegramInboundValidationError';
+    }
+}
+const telegramInteger = z.number().int().refine(Number.isSafeInteger, {
+    message: 'expected a safe integer',
+});
+const telegramChatSchema = z.object({
+    id: telegramInteger,
+    type: z.enum(['private', 'group', 'supergroup']),
+    first_name: z.string().optional(),
+    username: z.string().optional(),
+    title: z.string().optional(),
+}).passthrough();
+const telegramUserSchema = z.object({
+    id: telegramInteger,
+    is_bot: z.boolean().optional(),
+    first_name: z.string().optional(),
+    username: z.string().optional(),
+}).passthrough();
+const telegramMessageEntitySchema = z.object({
+    type: z.string(),
+    offset: telegramInteger.nonnegative(),
+    length: telegramInteger.nonnegative(),
+    user: telegramUserSchema.optional(),
+}).passthrough();
+const telegramPhotoSchema = z.object({
+    file_id: z.string(),
+    file_unique_id: z.string().optional(),
+    width: telegramInteger.optional(),
+    height: telegramInteger.optional(),
+    file_size: telegramInteger.nonnegative().optional(),
+}).passthrough();
+const telegramDocumentSchema = z.object({
+    file_id: z.string(),
+    file_name: z.string().optional(),
+    mime_type: z.string().optional(),
+    file_size: telegramInteger.nonnegative().optional(),
+}).passthrough();
+const telegramAudioSchema = z.object({
+    file_id: z.string(),
+    duration: telegramInteger.nonnegative().optional(),
+    mime_type: z.string().optional(),
+    file_name: z.string().optional(),
+}).passthrough();
+const telegramVoiceSchema = z.object({
+    file_id: z.string(),
+    duration: telegramInteger.nonnegative().optional(),
+    mime_type: z.string().optional(),
+}).passthrough();
+const telegramVideoSchema = z.object({
+    file_id: z.string(),
+    duration: telegramInteger.nonnegative().optional(),
+    mime_type: z.string().optional(),
+    file_name: z.string().optional(),
+}).passthrough();
+const telegramMessageSchema = z.object({
+    message_id: telegramInteger,
+    date: telegramInteger.optional(),
+    chat: telegramChatSchema,
+    from: telegramUserSchema,
+    text: z.string().optional(),
+    caption: z.string().optional(),
+    entities: z.array(telegramMessageEntitySchema).optional(),
+    caption_entities: z.array(telegramMessageEntitySchema).optional(),
+    message_thread_id: telegramInteger.optional(),
+    reply_to_message: z.object({ message_id: telegramInteger }).passthrough().optional(),
+    photo: z.array(telegramPhotoSchema).optional(),
+    document: telegramDocumentSchema.optional(),
+    audio: telegramAudioSchema.optional(),
+    voice: telegramVoiceSchema.optional(),
+    video: telegramVideoSchema.optional(),
+}).passthrough();
+const telegramMessageUpdateSchema = z.object({
+    update_id: telegramInteger.optional(),
+    message: telegramMessageSchema,
+}).passthrough();
+const telegramDedupSchema = z.object({
+    update_id: telegramInteger.optional(),
+    message: z.object({ message_id: telegramInteger.optional() }).passthrough().optional(),
+    callback_query: z.object({ id: z.string().optional() }).passthrough().optional(),
+}).passthrough();
+/** Message fields that carry metadata rather than content kind. */
+const TELEGRAM_META_KEYS = new Set([
+    'message_id', 'date', 'chat', 'from', 'reply_to_message',
+    'edit_date', 'media_group_id', 'message_thread_id', 'entities', 'caption',
+    'caption_entities', 'author_signature', 'is_automatic_forward',
+]);
+/** Stable hash for ids when the platform omits them. */
+export function simpleHash(input) {
+    let hash = 0;
+    for (let i = 0; i < input.length; i += 1) {
+        hash = (hash * 31 + input.charCodeAt(i)) | 0;
+    }
+    return Math.abs(hash).toString(36);
+}
+/** Map one raw Telegram update into the stable channel event shape. */
+export function mapInbound(raw, meta) {
+    const parsed = telegramMessageUpdateSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new TelegramInboundValidationError('telegram mapInbound: invalid message update');
+    }
+    const { message } = parsed.data;
+    const { chat, from } = message;
+    const sender = String(from.id);
+    // The chat id is the conversation id for both dm and group messages.
+    const conversationId = String(chat.id);
+    const messageId = String(message.message_id);
+    const conversationType = chat.type === 'group' || chat.type === 'supergroup' ? 'group' : 'dm';
+    const mentionedBot = conversationType === 'group'
+        ? messageMentionedBot(message, meta.bot)
+        : undefined;
+    return {
+        type: 'message.received',
+        channel: meta.channel,
+        accountId: meta.accountId,
+        conversation: {
+            id: conversationId,
+            // 'private' → dm; 'group'/'supergroup' → group keyed by the chat id.
+            // The schema rejects unsupported chat types rather than treating them as
+            // a private conversation.
+            type: chat.type === 'group' || chat.type === 'supergroup' ? 'group' : 'dm',
+            ...(message.message_thread_id !== undefined
+                ? { threadId: String(message.message_thread_id) }
+                : {}),
+        },
+        sender: { id: sender, name: from.first_name },
+        message: {
+            id: messageId,
+            content: partsFor(message),
+            ...(message.reply_to_message?.message_id !== undefined
+                ? { replyTo: String(message.reply_to_message.message_id) }
+                : {}),
+            // Telegram timestamps are Unix seconds; the contract uses ms.
+            createdAt: message.date !== undefined ? message.date * 1000 : Date.now(),
+            ...(mentionedBot !== undefined ? { activation: { mentionedBot } } : {}),
+        },
+        raw,
+    };
+}
+/** Telegram entity offsets use UTF-16 code units, matching JavaScript slice. */
+function messageMentionedBot(message, bot) {
+    if (!bot)
+        return undefined;
+    const sources = [
+        { text: message.text, entities: message.entities },
+        { text: message.caption, entities: message.caption_entities },
+    ];
+    for (const source of sources) {
+        if (!source.text || !source.entities)
+            continue;
+        for (const entity of source.entities) {
+            if (entity.type === 'text_mention' && entity.user?.id === bot.id)
+                return true;
+        }
+    }
+    const username = bot.username?.replace(/^@/, '').toLowerCase();
+    if (!username)
+        return false;
+    for (const source of sources) {
+        if (!source.text || !source.entities)
+            continue;
+        for (const entity of source.entities) {
+            const value = source.text.slice(entity.offset, entity.offset + entity.length);
+            if (entity.type === 'mention' && value.slice(1).toLowerCase() === username)
+                return true;
+            if (entity.type === 'bot_command') {
+                const addressedTo = value.slice(value.lastIndexOf('@') + 1).toLowerCase();
+                if (value.includes('@') && addressedTo === username)
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+function partsFor(message) {
+    if (typeof message.text === 'string') {
+        return textParts(message.text);
+    }
+    if (Array.isArray(message.photo) && message.photo.length > 0) {
+        // Telegram sends several sizes; the last entry is the largest. file_id is
+        // a platform-opaque handle, so it maps to `resourceRef` — never `url`,
+        // which is reserved for real http(s) URLs. The inbound processor resolves
+        // this reference through getFile before emitting the channel event.
+        const last = message.photo[message.photo.length - 1];
+        const resourceRef = last?.file_id;
+        return withCaption(message.caption, [{ type: 'image', resourceRef }]);
+    }
+    if (message.document) {
+        return withCaption(message.caption, [{
+                type: 'file',
+                resourceRef: message.document.file_id,
+                name: message.document.file_name,
+                mimeType: message.document.mime_type,
+            }]);
+    }
+    if (message.audio) {
+        return withCaption(message.caption, [{
+                type: 'audio',
+                resourceRef: message.audio.file_id,
+                durationMs: message.audio.duration !== undefined ? message.audio.duration * 1000 : undefined,
+                mimeType: message.audio.mime_type,
+            }]);
+    }
+    if (message.voice) {
+        return [{
+                type: 'audio',
+                resourceRef: message.voice.file_id,
+                durationMs: message.voice.duration !== undefined ? message.voice.duration * 1000 : undefined,
+                mimeType: message.voice.mime_type,
+            }];
+    }
+    if (message.video) {
+        return withCaption(message.caption, [{
+                type: 'video',
+                resourceRef: message.video.file_id,
+                durationMs: message.video.duration !== undefined ? message.video.duration * 1000 : undefined,
+                mimeType: message.video.mime_type,
+            }]);
+    }
+    return [{ type: 'unsupported', reason: `unsupported telegram message type '${messageKind(message)}'` }];
+}
+function withCaption(caption, parts) {
+    return typeof caption === 'string' && caption.length > 0
+        ? [...textParts(caption), ...parts]
+        : parts;
+}
+/** Best-effort content-kind name for the unsupported-part reason. */
+function messageKind(message) {
+    for (const key of Object.keys(message)) {
+        if (!TELEGRAM_META_KEYS.has(key))
+            return key;
+    }
+    return 'unknown';
+}
+/** Dedup identity for raw updates (update_id, then message_id). */
+export function dedupKey(raw) {
+    const parsed = telegramDedupSchema.safeParse(raw);
+    if (parsed.success) {
+        const update = parsed.data;
+        if (update.update_id !== undefined)
+            return `update-${update.update_id}`;
+        if (update.message?.message_id !== undefined)
+            return `message-${update.message.message_id}`;
+        if (update.callback_query?.id !== undefined)
+            return `callback-${update.callback_query.id}`;
+    }
+    return `telegram-${simpleHash(JSON.stringify(raw))}`;
+}
+/**
+ * Zod schema for a `callback_query` update. `callback_query.data` is UNTRUSTED
+ * client payload: it is validated as a plain string here and only ever echoed
+ * back as `InteractionReceived.action` (plan §5 / red line 5). The adapter never
+ * parses it into Harness question semantics — that interpretation belongs to
+ * `channel-harness`.
+ */
+const callbackQueryUpdateSchema = z.object({
+    update_id: telegramInteger.optional(),
+    callback_query: z.object({
+        id: z.string(),
+        from: telegramUserSchema,
+        message: z.object({
+            message_id: telegramInteger,
+            message_thread_id: telegramInteger.optional(),
+            chat: telegramChatSchema,
+        }).passthrough(),
+        data: z.string().optional(),
+        chat_instance: z.string().optional(),
+    }).passthrough(),
+}).loose();
+/** Whether a raw update carries a `callback_query` (message-bearing). */
+export function isCallbackQueryUpdate(raw) {
+    return callbackQueryUpdateSchema.safeParse(raw).success;
+}
+/**
+ * Map a validated `callback_query` update to `InteractionReceived`. Always run
+ * `isCallbackQueryUpdate` first; this function re-parses defensively and throws
+ * a clear error for a malformed tolerance so the adapter fails closed rather
+ * than emitting a fabricated interaction.
+ */
+export function mapCallbackQuery(raw, meta) {
+    const parsed = callbackQueryUpdateSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new TelegramInboundValidationError('telegram mapCallbackQuery: invalid callback_query payload');
+    }
+    const cq = parsed.data.callback_query;
+    const { chat, message_thread_id: threadId } = cq.message;
+    const { from } = cq;
+    const sender = String(from.id);
+    const conversationId = String(chat.id);
+    return {
+        type: 'interaction.received',
+        channel: meta.channel,
+        accountId: meta.accountId,
+        conversation: {
+            id: conversationId,
+            // 'private' → dm; 'group'/'supergroup' → group keyed by the chat id.
+            type: chat.type === 'group' || chat.type === 'supergroup' ? 'group' : 'dm',
+            ...(threadId !== undefined ? { threadId: String(threadId) } : {}),
+        },
+        sender: { id: sender, name: from.first_name },
+        interactionId: cq.id,
+        // The untrusted callback data is surfaced verbatim as the action; the
+        // adapter never interprets it (red line 5).
+        action: typeof cq.data === 'string' ? cq.data : '',
+        raw,
+    };
+}
+//# sourceMappingURL=mapper.js.map

package/lib/mapper.js.map

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

package/lib/media-hydrator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Telegram inbound media hydration.
+ *
+ * The pure mapper maps Telegram file_id values to the contract's
+ * `resourceRef` carrier (an opaque platform handle — never `url`). This module
+ * resolves those handles through the platform upstream (`getFile` +
+ * `/file/bot<token>/<file_path>`) and places the trusted bytes on
+ * `localData`, exactly like the official adapters' hydrators do for their
+ * platform URLs.
+ *
+ * Every transportable binary kind — `image`, `file`, `audio` and `video`
+ * (voice notes and audio messages both map to AudioPart, video messages to
+ * VideoPart) — is hydrated: Transport is transport, so a `resourceRef` is
+ * resolved into real bytes before emit for whichever binary part carries one.
+ * The download seam is generic for any supported file_id (photo / document /
+ * voice / audio / video).
+ *
+ * Failure handling follows the shared contract: a download failure never
+ * blocks text delivery. The part keeps its `resourceRef` and records a stable
+ * de-identified `ingressFailure` code via `toIngressFailureCode` from
+ * `@krischoichoi/channel-core` (shared `BodyTooLargeError` maps to 'too-large').
+ */
+import { type ChannelLogger, type MessagePart } from '@krischoichoi/channel-core';
+/** Platform file resolution seam (implemented by the upstream driver). */
+export interface TelegramFileResolver {
+    downloadFile(fileId: string, signal?: AbortSignal): Promise<{
+        data: Uint8Array;
+        mimeType?: string;
+        name?: string;
+    }>;
+}
+export interface TelegramMediaHydratorOptions {
+    /** Hard byte cap for one download. */
+    maxBytes: number;
+    /** External cancellation signal (from the adapter context). */
+    signal?: AbortSignal;
+    /** Optional logger for safe per-media failure diagnostics. */
+    logger?: Pick<ChannelLogger, 'warn'>;
+}
+/**
+ * Hydrate Telegram `resourceRef` bytes on `parts` in place. Returns the
+ * mutated array. Never throws — every download failure is recorded as
+ * `ingressFailure` on the part and the event still carries the text parts.
+ */
+export declare function hydrateTelegramParts(parts: MessagePart[], resolver: TelegramFileResolver, options: TelegramMediaHydratorOptions): Promise<MessagePart[]>;
+//# sourceMappingURL=media-hydrator.d.ts.map

package/lib/media-hydrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-hydrator.d.ts","sourceRoot":"","sources":["../src/media-hydrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,4BAA4B,CAAC;AAEpC,0EAA0E;AAC1E,MAAM,WAAW,oBAAoB;IACnC,YAAY,CACV,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,4BAA4B;IAC3C,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,WAAW,EAAE,EACpB,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,WAAW,EAAE,CAAC,CA6CxB"}

package/lib/media-hydrator.js

@@ -0,0 +1,85 @@
+/**
+ * Telegram inbound media hydration.
+ *
+ * The pure mapper maps Telegram file_id values to the contract's
+ * `resourceRef` carrier (an opaque platform handle — never `url`). This module
+ * resolves those handles through the platform upstream (`getFile` +
+ * `/file/bot<token>/<file_path>`) and places the trusted bytes on
+ * `localData`, exactly like the official adapters' hydrators do for their
+ * platform URLs.
+ *
+ * Every transportable binary kind — `image`, `file`, `audio` and `video`
+ * (voice notes and audio messages both map to AudioPart, video messages to
+ * VideoPart) — is hydrated: Transport is transport, so a `resourceRef` is
+ * resolved into real bytes before emit for whichever binary part carries one.
+ * The download seam is generic for any supported file_id (photo / document /
+ * voice / audio / video).
+ *
+ * Failure handling follows the shared contract: a download failure never
+ * blocks text delivery. The part keeps its `resourceRef` and records a stable
+ * de-identified `ingressFailure` code via `toIngressFailureCode` from
+ * `@krischoichoi/channel-core` (shared `BodyTooLargeError` maps to 'too-large').
+ */
+import { BodyTooLargeError, isHydratableBinaryPart, toIngressFailureCode, } from '@krischoichoi/channel-core';
+/**
+ * Hydrate Telegram `resourceRef` bytes on `parts` in place. Returns the
+ * mutated array. Never throws — every download failure is recorded as
+ * `ingressFailure` on the part and the event still carries the text parts.
+ */
+export async function hydrateTelegramParts(parts, resolver, options) {
+    const { maxBytes, signal, logger } = options;
+    await Promise.allSettled(parts.map(async (part) => {
+        // All four transportable binary kinds hydrate; anything else is ignored.
+        if (!isHydratableBinaryPart(part))
+            return;
+        const fileId = part.resourceRef;
+        if (typeof fileId !== 'string' || fileId.length === 0)
+            return;
+        // Trusted bytes already in hand take precedence — never re-download.
+        if (part.localData !== undefined || part.dataUri !== undefined)
+            return;
+        try {
+            const result = await resolver.downloadFile(fileId, signal);
+            if (result.data.byteLength > maxBytes) {
+                throw new BodyTooLargeError(maxBytes, `Telegram file ${result.data.byteLength} bytes exceeds the ${maxBytes} byte cap`);
+            }
+            part.localData = result.data;
+            // Actual downloaded bytes are authoritative over any previously-known
+            // size.
+            part.size = result.data.byteLength;
+            // Telegram's original message metadata is more authoritative than
+            // metadata reconstructed from the download response/path. Only fill
+            // missing hints so a generated file_path cannot replace a user name
+            // (photos carry no user-facing name, so image is left untouched).
+            if (part.mimeType === undefined && result.mimeType)
+                part.mimeType = result.mimeType;
+            if (part.type !== 'image' && part.name === undefined && result.name)
+                part.name = result.name;
+            // A successful hydration clears any previous failure marker.
+            delete part.ingressFailure;
+        }
+        catch (error) {
+            // Keep the resourceRef, record the stable de-identified failure code.
+            part.ingressFailure = toIngressFailureCode(error);
+            logger?.warn('[channel-telegram] media hydration failed', {
+                type: part.type,
+                failure: part.ingressFailure,
+                error: safeErrorDetails(error),
+            });
+        }
+    }));
+    return parts;
+}
+/** Keep diagnostics useful without allowing bearer paths or raw payloads into logs. */
+function safeErrorDetails(error) {
+    if (!(error instanceof Error))
+        return { message: 'unknown error' };
+    const value = error;
+    return {
+        name: value.name,
+        ...(typeof value.code === 'string' ? { code: value.code } : {}),
+        message: value.message.replace(/\/file\/bot[^/?#]+/g, '/file/bot<redacted>')
+            .replace(/\/bot[^/?#]+/g, '/bot<redacted>'),
+    };
+}
+//# sourceMappingURL=media-hydrator.js.map

package/lib/media-hydrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-hydrator.js","sourceRoot":"","sources":["../src/media-hydrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,GAGrB,MAAM,4BAA4B,CAAC;AAmBpC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAoB,EACpB,QAA8B,EAC9B,OAAqC;IAErC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAE7C,MAAM,OAAO,CAAC,UAAU,CACtB,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAiB,EAAE;QACtC,yEAAyE;QACzE,IAAI,CAAC,sBAAsB,CAAC,IAAI,CAAC;YAAE,OAAO;QAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC;QAChC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC9D,qEAAqE;QACrE,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;YAAE,OAAO;QAEvE,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAC3D,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,GAAG,QAAQ,EAAE,CAAC;gBACtC,MAAM,IAAI,iBAAiB,CACzB,QAAQ,EACR,iBAAiB,MAAM,CAAC,IAAI,CAAC,UAAU,sBAAsB,QAAQ,WAAW,CACjF,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC;YAC7B,sEAAsE;YACtE,QAAQ;YACR,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC;YACnC,kEAAkE;YAClE,oEAAoE;YACpE,oEAAoE;YACpE,kEAAkE;YAClE,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ;gBAAE,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;YACpF,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI;gBAAE,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;YAC7F,6DAA6D;YAC7D,OAAO,IAAI,CAAC,cAAc,CAAC;QAC7B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,sEAAsE;YACtE,IAAI,CAAC,cAAc,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;YAClD,MAAM,EAAE,IAAI,CAAC,2CAA2C,EAAE;gBACxD,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,cAAc;gBAC5B,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC;aAC/B,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CACH,CAAC;IAEF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,uFAAuF;AACvF,SAAS,gBAAgB,CAAC,KAAc;IACtC,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC;IACnE,MAAM,KAAK,GAAG,KAAmC,CAAC;IAClD,OAAO;QACL,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,GAAG,CAAC,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,qBAAqB,EAAE,qBAAqB,CAAC;aACzE,OAAO,CAAC,eAAe,EAAE,gBAAgB,CAAC;KAC9C,CAAC;AACJ,CAAC"}

package/lib/outbound.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Outbound sending: channel message → Telegram Bot API payload → upstream.
+ *
+ * Text messages go through the configured formatting renderer (Rich Markdown /
+ * HTML / MarkdownV2 / plain) and `sendMessage`; messages carrying sendable media
+ * bytes or references go through `sendMedia` with the message text rendered as a
+ * 1024-caption. Interactive `OutboundMessage.actions` map to a Telegram
+ * `InlineKeyboardMarkup` (plan §14). A binary part with no supported carrier
+ * fails closed so an attachment is never silently discarded as plain text.
+ *
+ * Formatting fallback is exact-once: only a `format`-kind error downgrades to
+ * plain; 401/403 / 429 / network / 5xx propagate (plan §20.9).
+ */
+import type { ChannelLogger, ChannelTarget, OutboundActionRow, OutboundMessage, SendResult } from '@krischoichoi/channel-core';
+import type { TelegramFormattingConfig } from './config.js';
+import type { TelegramUpstream } from './upstream.js';
+import type { TelegramInlineKeyboardMarkup } from './rich-message.js';
+export interface TelegramOutboundOptions {
+    /** Formatting policy controlling how text/captions are rendered. */
+    formatting?: Partial<TelegramFormattingConfig>;
+}
+export declare class OutboundSender {
+    private readonly upstream;
+    private readonly logger;
+    private readonly formatting;
+    constructor(upstream: TelegramUpstream, logger: ChannelLogger, options?: TelegramOutboundOptions);
+    send(target: ChannelTarget, message: OutboundMessage): Promise<SendResult>;
+    /** Send text through the configured renderer with exact-once fallback. */
+    private sendTextWithFormatting;
+    /** Send media with the text rendered as a ≤1024 caption (plain fallback). */
+    private sendMediaWithFormatting;
+}
+/**
+ * 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 declare function actionsToReplyMarkup(actions: OutboundActionRow[] | undefined): TelegramInlineKeyboardMarkup | undefined;
+//# sourceMappingURL=outbound.d.ts.map

package/lib/outbound.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound.d.ts","sourceRoot":"","sources":["../src/outbound.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EAEb,iBAAiB,EACjB,eAAe,EACf,UAAU,EACX,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAA2D,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC/G,OAAO,KAAK,EAEV,4BAA4B,EAG7B,MAAM,mBAAmB,CAAC;AAQ3B,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,UAAU,CAAC,EAAE,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAChD;AAED,qBAAa,cAAc;IAIvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA2B;gBAGnC,QAAQ,EAAE,gBAAgB,EAC1B,MAAM,EAAE,aAAa,EACtC,OAAO,GAAE,uBAA4B;IAKjC,IAAI,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAwChF,0EAA0E;YAC5D,sBAAsB;IAsCpC,6EAA6E;YAC/D,uBAAuB;CA2CtC;AA+BD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,SAAS,GAAG,4BAA4B,GAAG,SAAS,CAsBvH"}