# kcode-telegram-native-media
`kcode-telegram-native-media` is a focused Rust library for classifying Telegram message media, selecting stable provider renditions, resolving native-media metadata fallbacks, reporting media capabilities, and sending each supported native kind through its matching Telegram Bot API method.
## Public API
The crate exposes:
- `NativeMediaKind` with `parse`, `as_str`, `accepts_caption`, `fallback_mime`, and `default_file_name`;
- `InboundMedia`, whose fields expose the classified kind, Telegram file ID, declared size, retained text, MIME type, file name, duration, and user-facing size-limit label;
- `classify_message`;
- `is_retained_media_kind` and `is_audio_oriented`;
- `message_duration`;
- `send_native_media`;
- `NATIVE_MEDIA_KINDS`, `INBOUND_MEDIA_KINDS`, and `OUTBOUND_MEDIA_KINDS`.
The six native kinds are `photo`, `video`, `animation`, `audio`, `video_note`, and `sticker`. Voice notes and generic documents are classified and included in inbound capability reporting but are not native outbound kinds. Generic documents remain documents regardless of MIME type.
## Inbound classification
Classification preserves the established precedence:
1. voice note;
2. animation;
3. photo;
4. video;
5. audio;
6. video note;
7. sticker;
8. generic document.
Animation is checked before document because Telegram may expose an animation through a compatibility document representation.
Provider captions are retained for voice, animation, photo, video, audio, and document messages. Video notes retain no text. Stickers retain their emoji when supplied.
Telegram's unknown declared file-size sentinel is represented as no declared size. This crate does not download bytes or enforce a byte limit; callers use the returned file ID, declared size, and label for that work.
## Photo rendition selection
Telegram photos are provider renditions. `classify_message` selects the rendition with greatest pixel area, then greatest declared file size, then earliest provider order. Missing declared size sorts as zero. The selection is deterministic and does not claim to recover the sender's original upload.
## MIME and filename fallbacks
Voice defaults to `audio/ogg`. Photos default to JPEG, videos and video notes to MP4, and sticker MIME types follow the provider's static, animated, or video format.
Animation fallbacks recognize `.gif` and `.mp4`. Audio fallbacks recognize MP3, M4A/MP4, OGG/OGA/Opus, WAV, and FLAC. Unknown animation or audio formats use `application/octet-stream`.
Generated names use `telegram-{kind}-{message_id}.{extension}`, with underscores rendered as hyphens. The extension follows the resolved MIME type when recognized and otherwise uses the established kind-specific fallback. Documents without provider filenames use `telegram-file`.
## Predicates and returned-message metadata
`is_retained_media_kind` accepts voice, document, and all six native kinds. `is_audio_oriented` accepts voice, audio, and video note.
`message_duration` extracts provider-returned duration for video, animation, audio, and video-note messages. Photos and stickers have no duration.
## Native delivery
`send_native_media` maps each native kind exactly:
- photo to `sendPhoto`;
- video to `sendVideo`;
- animation to `sendAnimation`;
- audio to `sendAudio`;
- video note to `sendVideoNote`;
- sticker to `sendSticker`.
Photo, video, animation, and audio accept captions. Video notes and stickers do not. Optional Telegram reply parameters are forwarded to every native send method.
Every send delegates to exact-pinned `kcode-telegram-request-policy` 0.1.0 with the established labels `send_photo`, `send_video`, `send_animation`, `send_audio`, `send_video_note`, and `send_sticker`. The policy permits at most five total attempts and may duplicate an effectful send if Telegram accepted it but its response was lost. This crate provides no durable outbox, receipt, idempotency key, or exactly-once guarantee.
## Boundary
The crate owns no bot token construction, download, byte limit, persistence, SQLite schema or migration, identity, whitelist, session, group policy, batching, polling cursor, dispatch queue, archive, delivery reconciliation, host adoption, or deployment lifecycle. It operates only on supplied Teloxide message values, metadata, bytes, bot client, and reply parameters.
Direct production dependencies are exact-pinned. The literal package version in `Cargo.toml` is canonical. Standard validation includes formatting, build, Clippy with warnings denied, unit tests, and documentation tests.