feat(telegram): inbound rich-message parsing (chat@4.31 4662309 — TG3/4)

Port the 4.31 inbound parse path for Bot API 10.1 rich messages.

parse_telegram_message:
- Render an inbound `rich_message` to markdown (rich_message_to_markdown)
  and plain text (rich_message_to_text) via the TG2 renderer.
- Faithful ?/??/|| precedence:
  - rich_markdown: presence (truthy) check on raw.rich_message
  - plain_text: `?? raw.text ?? raw.caption ?? (rich ? richMessageToText : "")`
    -- nullish chain ported as `is not None` (empty string short-circuits)
  - text: `content?.text ? content.text : applyTelegramEntities(...)`
    -- TRUTHY `?`, empty content.text falls through to entities
  - formatted: `content?.formatted ?? toAst(richMarkdown || text)`
    -- nullish for the supplied AST, TRUTHY-OR for richMarkdown || text
- New optional `content` arg (TelegramParsedContent) wires the outbound
  pre-rendered AST/text reuse; inbound callers pass None.

extract_attachments:
- Append media extracted from rich_message via rich_message_media,
  mapping each RichMedia onto Attachment (mimeType -> mime_type boundary),
  appended after the top-level photo/video/audio/voice/document/video_note.

Tests (tests/test_telegram_webhook.py): inbound rich text+AST, caption
precedence, rich-markdown-driven formatted, nested collage media (photo
largest size, video name/mime), animation image-vs-video by mime,
voice_note -> audio, list-block recursion, append ordering.

Author: patrick-chinchill

src/chat_sdk/adapters/telegram/adapter.py

@@ -29,6 +29,11 @@
     empty_telegram_inline_keyboard,
 )
 from chat_sdk.adapters.telegram.format_converter import TelegramFormatConverter
+from chat_sdk.adapters.telegram.rich import (
+    rich_message_media,
+    rich_message_to_markdown,
+    rich_message_to_text,
+)
 from chat_sdk.adapters.telegram.types import (
     TelegramAdapterConfig,
     TelegramApiResponse,
@@ -156,6 +161,20 @@ class ResolvedTelegramLongPollingConfig:
     timeout: int
 
 
+@dataclass
+class TelegramParsedContent:
+    """Pre-resolved formatted/plain text for a parsed Telegram message.
+
+    Supplied by the outbound post/edit/stream paths when the SDK already
+    rendered a rich message locally, so :meth:`parse_telegram_message`
+    reuses that AST/text instead of re-deriving it from the raw payload.
+    Port of upstream's ``content?`` argument to ``parseTelegramMessage``.
+    """
+
+    formatted: FormattedContent
+    text: str
+
+
 TelegramRuntimeMode = str  # "webhook" | "polling"
 
 _T = TypeVar("_T")
@@ -1975,11 +1994,37 @@ def parse_telegram_message(
         self,
         raw: TelegramMessage,
         thread_id: str,
+        content: TelegramParsedContent | None = None,
     ) -> Message:
         """Parse a Telegram message into a normalised :class:`Message`."""
-        plain_text = raw.get("text") or raw.get("caption") or ""
-        entities = raw.get("entities") or raw.get("caption_entities") or []
-        text = apply_telegram_entities(plain_text, entities)
+        rich_message = raw.get("rich_message")
+        # `raw.rich_message ? ... : ""` -- presence (truthy) check on the field.
+        rich_markdown = rich_message_to_markdown(rich_message) if rich_message else ""
+        # Upstream chains `??` here (nullish): an empty-string text/caption is a
+        # real value and short-circuits the chain. Port each `??` as `is not None`.
+        content_text = content.text if content is not None else None
+        raw_text = raw.get("text")
+        raw_caption = raw.get("caption")
+        if content_text is not None:
+            plain_text = content_text
+        elif raw_text is not None:
+            plain_text = raw_text
+        elif raw_caption is not None:
+            plain_text = raw_caption
+        elif rich_message:
+            plain_text = rich_message_to_text(rich_message)
+        else:
+            plain_text = ""
+        # `raw.entities ?? raw.caption_entities ?? []` -- nullish: present-but-empty
+        # entity lists are honoured rather than falling through to caption_entities.
+        entities = raw.get("entities")
+        if entities is None:
+            entities = raw.get("caption_entities")
+        if entities is None:
+            entities = []
+        # `content?.text ? content.text : applyTelegramEntities(...)` -- TRUTHY `?`:
+        # a present-but-empty `content.text` falls through to the entity-applied text.
+        text = content.text if content is not None and content.text else apply_telegram_entities(plain_text, entities)
 
         # Determine author -- Telegram uses 'from' key which is a reserved word
         from_user = cast(
@@ -2004,11 +2049,19 @@ def parse_telegram_message(
 
         edit_date = raw.get("edit_date")
 
+        # `content?.formatted ?? this.formatConverter.toAst(richMarkdown || text)`:
+        # `??` (nullish) for the supplied AST, then `richMarkdown || text` is a
+        # TRUTHY-OR -- a non-empty rendered rich markdown wins, else fall to text.
+        if content is not None and content.formatted is not None:
+            formatted = content.formatted
+        else:
+            formatted = self._format_converter.to_ast(rich_markdown or text)
+
         return Message(
             id=self.encode_message_id(str(raw["chat"]["id"]), raw["message_id"]),
             thread_id=thread_id,
             text=text,
-            formatted=self._format_converter.to_ast(text),
+            formatted=formatted,
             raw=raw,
             author=author,
             metadata=MessageMetadata(
@@ -2104,6 +2157,26 @@ def extract_attachments(self, raw: TelegramMessage) -> list[Attachment]:
                 )
             )
 
+        # Bot API 10.1 rich messages carry their media inline in the block tree
+        # (port of chat@4.31 4662309). `rich_message_media` walks the nested
+        # blocks (lists, blockquotes, collages, slideshows, details) and yields
+        # a flat `RichMedia` list; map each onto our `Attachment` shape. The
+        # `mimeType` -> `mime_type` rename is the only field-name boundary.
+        rich_message = raw.get("rich_message")
+        if rich_message:
+            for media in rich_message_media(rich_message):
+                attachments.append(
+                    self.create_attachment(
+                        media.type,
+                        media.file["file_id"],
+                        size=media.file.get("file_size"),
+                        width=media.width,
+                        height=media.height,
+                        name=media.name,
+                        mime_type=media.mime_type,
+                    )
+                )
+
         return attachments
 
     def create_attachment(