Crate kcode_telegram_native_media

Expand description

§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:

voice note;
animation;
photo;
video;
audio;
video note;
sticker;
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.1 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.