@mks2508/telegram-message-builder 0.2.0 → 0.3.0

package/src/types/media.types.ts

@@ -0,0 +1,178 @@
+/**
+ * @fileoverview Media Types
+ * @description Type definitions for media messages in Telegram Bot API
+ * @module telegram-message-builder/types
+ *
+ * @see {@link https://core.telegram.org/bots/api#sendphoto | Telegram Bot API - sendPhoto}
+ * @see {@link https://core.telegram.org/bots/api#sendvideo | Telegram Bot API - sendVideo}
+ * @see {@link https://core.telegram.org/bots/api#senddocument | Telegram Bot API - sendDocument}
+ * @see {@link https://core.telegram.org/bots/api#sendaudio | Telegram Bot API - sendAudio}
+ * @see {@link https://core.telegram.org/bots/api#sendvoice | Telegram Bot API - sendVoice}
+ */
+
+import type { ParseMode } from "./core.types";
+import type { IInlineKeyboardMarkup, IReplyParameters } from "./keyboard.types";
+
+/**
+ * Media source - can represent various input formats
+ *
+ * - `string` as file_id - Existing uploaded file on Telegram servers
+ * - `string` as URL - HTTPS URL to fetch file from
+ * - `Buffer` - Binary data for upload
+ * - `string` as file path - Local file path for upload
+ *
+ * @example
+ * ```typescript
+ * const fileId: MediaSource = "AgACAgIAAxkBAAI...";
+ * const url: MediaSource = "https://example.com/photo.jpg";
+ * const buffer: MediaSource = Buffer.from(...);
+ * const filePath: MediaSource = "/path/to/photo.jpg";
+ * ```
+ */
+export type MediaSource = string | Buffer;
+
+/**
+ * Common media options shared across all media types
+ *
+ * Includes all possible options from all media types to allow
+ * flexible setOption() usage while maintaining type safety.
+ */
+export interface IMediaCommonOptions {
+  /** List of special entities in the caption */
+  caption_entities?: unknown[];
+  /** Show caption above media (True by default) */
+  show_caption_above_media?: boolean;
+  /** Disable automatic file type detection (documents only) */
+  disable_content_type_detection?: boolean;
+  /** Protect contents from forwarding/saving */
+  protect_content?: boolean;
+  /** Reply parameters for replying to messages */
+  reply_parameters?: IReplyParameters;
+  /** Inline keyboard attached to the message */
+  reply_markup?: IInlineKeyboardMarkup;
+
+  // Photo/Video/Document/Audio options
+  /** Thumbnail of the file sent */
+  thumb?: Buffer | string;
+
+  // Video/Audio/Voice options
+  /** Duration of the media in seconds */
+  duration?: number;
+
+  // Video options
+  /** Video width */
+  width?: number;
+  /** Video height */
+  height?: number;
+  /** Pass True to upload the video as a streaming video */
+  support_streaming?: boolean;
+
+  // Document options
+  /** Original filename */
+  file_name?: string;
+  /** MIME type of the file */
+  mime_type?: string;
+
+  // Audio options
+  /** Performer of the audio */
+  performer?: string;
+  /** Track name of the audio */
+  title?: string;
+}
+
+/**
+ * Photo-specific options
+ */
+export interface IPhotoOptions extends IMediaCommonOptions {
+  /** Thumbnail of the file sent */
+  thumb?: Buffer | string;
+}
+
+/**
+ * Video-specific options
+ */
+export interface IVideoOptions extends IMediaCommonOptions {
+  /** Duration of the video in seconds */
+  duration?: number;
+  /** Video width */
+  width?: number;
+  /** Video height */
+  height?: number;
+  /** Thumbnail of the video */
+  thumb?: Buffer | string;
+  /** Pass True to upload the video as a streaming video */
+  support_streaming?: boolean;
+}
+
+/**
+ * Document-specific options
+ */
+export interface IDocumentOptions extends IMediaCommonOptions {
+  /** Thumbnail of the document */
+  thumb?: Buffer | string;
+  /** Original filename */
+  file_name?: string;
+  /** MIME type of the file */
+  mime_type?: string;
+}
+
+/**
+ * Audio-specific options
+ */
+export interface IAudioOptions extends IMediaCommonOptions {
+  /** Duration of the audio in seconds */
+  duration?: number;
+  /** Performer of the audio */
+  performer?: string;
+  /** Track name of the audio */
+  title?: string;
+  /** Thumbnail of the album cover */
+  thumb?: Buffer | string;
+}
+
+/**
+ * Voice-specific options
+ */
+export interface IVoiceOptions extends IMediaCommonOptions {
+  /** Duration of the voice message in seconds */
+  duration?: number;
+}
+
+/**
+ * Media message types supported by Telegram
+ */
+export type MediaType = "photo" | "video" | "document" | "audio" | "voice";
+
+/**
+ * Complete media message interface
+ */
+export interface IMediaMessage {
+  /** Media source (file_id, URL, Buffer, or file path) */
+  media: MediaSource;
+  /** Type of media */
+  type: MediaType;
+  /** Caption for the media */
+  caption?: string;
+  /** Parse mode for caption formatting */
+  parse_mode?: ParseMode;
+  /** Additional options */
+  options: IMediaCommonOptions;
+}
+
+/**
+ * Result from TelegramMediaBuilder.build()
+ *
+ * Compatible with Telegram Bot API send* methods
+ */
+export interface IMediaBuildResult {
+  /** Media source */
+  media: MediaSource;
+  /** Media type */
+  type: MediaType;
+  /** Caption with formatting applied based on parse_mode */
+  caption?: string;
+  /** Parse mode used for caption */
+  parse_mode?: ParseMode;
+  /** Additional Telegram-specific options */
+  [key: string]: unknown;
+}