[4.41/TG3b] Telegram outbound media groups: multi-file and multi-attachment sendMediaGroup #278

Summary

Split out of #227 (size): the outbound half of the Telegram media-group work. post_message still raises "Telegram adapter supports a single file upload per message" / "single attachment upload per message"; upstream sends 2–10 files or attachments as one sendMediaGroup.

The inbound half (polling acknowledgement and checkpoint, incoming albums) lands in the #227 PR.

Upstream change

• 8d7ccdb1 feat(telegram): support multiple file and attachment uploads (#605) — chat@4.34.0. Multiple files or attachments go out via sendMediaGroup. It requires 2–10 items and rejects an inline keyboard. Photos and videos may mix; documents and audio only group with their own type. The caption goes on the first item, uploads use attach://media{i} multipart parts, and the call returns the last sent message and caches all of them.

Scope

• post_message: remove the single-file and single-attachment errors (keep "mixing file uploads and attachments" and "Attachment upload payload is empty"). One file / attachment keeps send_document / send_attachment; 2+ go to new _send_document_media_group / _send_attachment_media_group.
• _validate_media_group_length (2–10, "Telegram media groups support 2-10 files") and _validate_attachment_media_group_types (file → document, audio → audio, else visual; more than one category raises). Reject reply_markup ("Telegram media groups do not support inline keyboards").
• ATTACHMENT_MEDIA_GROUP_TYPES (audio/file→document/image→photo/video) and TELEGRAM_MEDIA_GROUP_MIN = 2 (TELEGRAM_MEDIA_GROUP_MAX = 10 already exists after [4.41/TG3] Telegram polling & media: await handlers before advancing offset, media groups, multi-file uploads #227).
• aiohttp.FormData (lazy import) with chat_id, message_thread_id, a media JSON string of InputMedia items and media{i} file parts for binary payloads (URL-only attachments pass the URL as media). Caption + parse_mode on item 0 only, video width/height when integral, same MarkdownV2 → plain fallback as send_document (FormData rebuilt per attempt).
• Parse and cache every returned message; return the last.

Out of scope

• reply_parameters on media groups: [4.41/TG4] Telegram replies: replied-to context, reply-to-bot as mention, native replies, portable file data #228.

Tests

Port from packages/adapter-telegram/src/index.test.ts (not fidelity-mapped, see #78) into tests/test_telegram_api.py, replacing test_rejects_multiple_attachments:

• "posts multiple files as a Telegram media group"
• "posts and normalizes mixed image and video attachments as a Telegram media group"
• "rejects incompatible Telegram media group attachment types"
• "rejects Telegram media groups with more than 10 files"

("rejects mixed file uploads and attachments" and "rejects attachments without upload data" are already ported.) Python-specific: inline keyboard rejection and the MarkdownV2 → plain retry on sendMediaGroup.

Acceptance criteria

• post_message with 2–10 files or attachments issues one sendMediaGroup.
• Full validation from CLAUDE.md passes; CHANGELOG bullet under "Unreleased (4.41 wave)"; docs/UPSTREAM_SYNC.md Telegram [4.41/TG3] Telegram polling & media: await handlers before advancing offset, media groups, multi-file uploads #227 section updated.

Metadata

• Effort: S–M (~450 LOC including tests)
• Consumer impact: low (Telegram only)
• Suggested branch: sync/4.41-tg3b

Part of #184. Split from #227.