@mks2508/telegram-message-builder 0.2.0 → 0.3.1

package/src/builder/media.d.ts

@@ -0,0 +1,352 @@
+/**
+ * @fileoverview Media Builder
+ * @description Fluent API for building media messages for Telegram Bot API
+ * @module telegram-message-builder/builder
+ *
+ * @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 { MediaSource, MediaType, IMediaCommonOptions, IMediaBuildResult, ParseMode } from "../types";
+/**
+ * Telegram Media Builder - Fluent API for building media messages
+ *
+ * Provides a type-safe, fluent interface for constructing media messages
+ * compatible with Telegram Bot API v9.3+.
+ *
+ * Supports all three Telegram parse modes (HTML, Markdown, MarkdownV2) for caption formatting.
+ *
+ * @example
+ * ```typescript
+ * // Simple photo with caption
+ * const photo = TelegramMediaBuilder.photo("photo.jpg")
+ *   .caption("My photo")
+ *   .build();
+ *
+ * // Video with caption and options
+ * const video = TelegramMediaBuilder.video("video.mp4")
+ *   .caption("My video")
+ *   .duration(120)
+ *   .thumbnail("thumb.jpg")
+ *   .setParseMode("markdown")
+ *   .build();
+ *
+ * // Document with custom options
+ * const doc = TelegramMediaBuilder.document("report.pdf")
+ *   .caption("Q4 Report")
+ *   .fileName("q4_2024.pdf")
+ *   .mimeType("application/pdf")
+ *   .build();
+ * ```
+ */
+export declare class TelegramMediaBuilder<T extends MediaType> {
+    protected source: MediaSource;
+    protected mediaType: T;
+    protected _caption?: string;
+    protected parseMode: ParseMode;
+    protected options: IMediaCommonOptions;
+    protected constructor(source: MediaSource, mediaType: T);
+    /**
+     * Create a photo message builder
+     *
+     * @param source - File ID, URL, Buffer, or file path
+     * @returns Photo media builder with thumbnail() method
+     *
+     * @example
+     * ```typescript
+     * const photo = TelegramMediaBuilder.photo("https://example.com/photo.jpg")
+     *   .caption("Beautiful sunset")
+     *   .thumbnail("thumb.jpg")
+     *   .build();
+     * ```
+     */
+    static photo(source: MediaSource): PhotoBuilder;
+    /**
+     * Create a video message builder
+     *
+     * @param source - File ID, URL, Buffer, or file path
+     * @returns Video media builder with duration(), width(), height(), thumbnail(), enableStreaming() methods
+     *
+     * @example
+     * ```typescript
+     * const video = TelegramMediaBuilder.video("video.mp4")
+     *   .caption("My video")
+     *   .duration(120)
+     *   .width(1920)
+     *   .height(1080)
+     *   .build();
+     * ```
+     */
+    static video(source: MediaSource): VideoBuilder;
+    /**
+     * Create a document message builder
+     *
+     * @param source - File ID, URL, Buffer, or file path
+     * @returns Document media builder with thumbnail(), fileName(), mimeType(), disableContentTypeDetection() methods
+     *
+     * @example
+     * ```typescript
+     * const doc = TelegramMediaBuilder.document("report.pdf")
+     *   .caption("Q4 Report")
+     *   .fileName("q4_2024.pdf")
+     *   .mimeType("application/pdf")
+     *   .build();
+     * ```
+     */
+    static document(source: MediaSource): DocumentBuilder;
+    /**
+     * Create an audio message builder
+     *
+     * @param source - File ID, URL, Buffer, or file path
+     * @returns Audio media builder with duration(), performer(), title(), thumbnail() methods
+     *
+     * @example
+     * ```typescript
+     * const audio = TelegramMediaBuilder.audio("song.mp3")
+     *   .caption("My favorite song")
+     *   .duration(180)
+     *   .performer("Artist Name")
+     *   .title("Song Title")
+     *   .build();
+     * ```
+     */
+    static audio(source: MediaSource): AudioBuilder;
+    /**
+     * Create a voice message builder
+     *
+     * @param source - File ID, URL, Buffer, or file path
+     * @returns Voice media builder with duration() method
+     *
+     * @example
+     * ```typescript
+     * const voice = TelegramMediaBuilder.voice("voice.ogg")
+     *   .caption("Listen to this")
+     *   .duration(30)
+     *   .build();
+     * ```
+     */
+    static voice(source: MediaSource): VoiceBuilder;
+    /**
+     * Set caption for the media
+     *
+     * @param text - Caption text (0-1024 characters)
+     * @returns This builder for chaining
+     */
+    caption(text: string): this;
+    /**
+     * Set parse mode for caption formatting
+     *
+     * @param mode - Parse mode (html, markdown, or markdownv2)
+     * @returns This builder for chaining
+     */
+    setParseMode(mode: ParseMode): this;
+    /**
+     * Set a custom option
+     *
+     * @param key - Option name
+     * @param value - Option value
+     * @returns This builder for chaining
+     */
+    setOption<K extends keyof IMediaCommonOptions>(key: K, value: IMediaCommonOptions[K]): this;
+    /**
+     * Set multiple options at once
+     *
+     * @param opts - Object with options to set
+     * @returns This builder for chaining
+     */
+    setOptions(opts: Partial<IMediaCommonOptions>): this;
+    /**
+     * Build the media message object
+     *
+     * @returns Complete media message ready for Telegram Bot API
+     */
+    build(): IMediaBuildResult;
+    /**
+     * Format caption based on current parse mode
+     *
+     * @param text - Caption text to format
+     * @returns Formatted caption
+     */
+    private formatCaption;
+}
+/**
+ * Photo-specific builder with convenience methods
+ *
+ * @example
+ * ```typescript
+ * const photo = TelegramMediaBuilder.photo("photo.jpg")
+ *   .caption("My photo")
+ *   .thumbnail("thumb.jpg")
+ *   .build();
+ * ```
+ */
+export declare class PhotoBuilder extends TelegramMediaBuilder<"photo"> {
+    /**
+     * Set thumbnail for the photo
+     *
+     * @param thumb - Thumbnail as Buffer or file path
+     * @returns This builder for chaining
+     */
+    thumbnail(thumb: Buffer | string): this;
+}
+/**
+ * Video-specific builder with convenience methods
+ *
+ * @example
+ * ```typescript
+ * const video = TelegramMediaBuilder.video("video.mp4")
+ *   .caption("My video")
+ *   .duration(120)
+ *   .width(1920)
+ *   .height(1080)
+ *   .thumbnail("thumb.jpg")
+ *   .enableStreaming()
+ *   .build();
+ * ```
+ */
+export declare class VideoBuilder extends TelegramMediaBuilder<"video"> {
+    /**
+     * Set video duration
+     *
+     * @param seconds - Duration in seconds
+     * @returns This builder for chaining
+     */
+    duration(seconds: number): this;
+    /**
+     * Set video width
+     *
+     * @param px - Width in pixels
+     * @returns This builder for chaining
+     */
+    width(px: number): this;
+    /**
+     * Set video height
+     *
+     * @param px - Height in pixels
+     * @returns This builder for chaining
+     */
+    height(px: number): this;
+    /**
+     * Set thumbnail for the video
+     *
+     * @param thumb - Thumbnail as Buffer or file path
+     * @returns This builder for chaining
+     */
+    thumbnail(thumb: Buffer | string): this;
+    /**
+     * Enable streaming for the video
+     *
+     * @returns This builder for chaining
+     */
+    enableStreaming(): this;
+}
+/**
+ * Document-specific builder with convenience methods
+ *
+ * @example
+ * ```typescript
+ * const doc = TelegramMediaBuilder.document("report.pdf")
+ *   .caption("Q4 Report")
+ *   .thumbnail("thumb.jpg")
+ *   .fileName("q4_2024.pdf")
+ *   .mimeType("application/pdf")
+ *   .disableContentTypeDetection()
+ *   .build();
+ * ```
+ */
+export declare class DocumentBuilder extends TelegramMediaBuilder<"document"> {
+    /**
+     * Set thumbnail for the document
+     *
+     * @param thumb - Thumbnail as Buffer or file path
+     * @returns This builder for chaining
+     */
+    thumbnail(thumb: Buffer | string): this;
+    /**
+     * Set original filename
+     *
+     * @param name - File name
+     * @returns This builder for chaining
+     */
+    fileName(name: string): this;
+    /**
+     * Set MIME type
+     *
+     * @param type - MIME type string
+     * @returns This builder for chaining
+     */
+    mimeType(type: string): this;
+    /**
+     * Disable automatic file type detection
+     *
+     * @returns This builder for chaining
+     */
+    disableContentTypeDetection(): this;
+}
+/**
+ * Audio-specific builder with convenience methods
+ *
+ * @example
+ * ```typescript
+ * const audio = TelegramMediaBuilder.audio("song.mp3")
+ *   .caption("My favorite song")
+ *   .duration(180)
+ *   .performer("Artist Name")
+ *   .title("Song Title")
+ *   .thumbnail("album_art.jpg")
+ *   .build();
+ * ```
+ */
+export declare class AudioBuilder extends TelegramMediaBuilder<"audio"> {
+    /**
+     * Set audio duration
+     *
+     * @param seconds - Duration in seconds
+     * @returns This builder for chaining
+     */
+    duration(seconds: number): this;
+    /**
+     * Set performer name
+     *
+     * @param name - Performer name
+     * @returns This builder for chaining
+     */
+    performer(name: string): this;
+    /**
+     * Set track title
+     *
+     * @param name - Track title
+     * @returns This builder for chaining
+     */
+    title(name: string): this;
+    /**
+     * Set thumbnail (album cover)
+     *
+     * @param thumb - Thumbnail as Buffer or file path
+     * @returns This builder for chaining
+     */
+    thumbnail(thumb: Buffer | string): this;
+}
+/**
+ * Voice-specific builder with convenience methods
+ *
+ * @example
+ * ```typescript
+ * const voice = TelegramMediaBuilder.voice("voice.ogg")
+ *   .caption("Listen to this")
+ *   .duration(30)
+ *   .build();
+ * ```
+ */
+export declare class VoiceBuilder extends TelegramMediaBuilder<"voice"> {
+    /**
+     * Set voice duration
+     *
+     * @param seconds - Duration in seconds
+     * @returns This builder for chaining
+     */
+    duration(seconds: number): this;
+}
+//# sourceMappingURL=media.d.ts.map

package/src/builder/media.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media.d.ts","sourceRoot":"","sources":["media.ts"],"names":[],"mappings":"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"}