@mks2508/telegram-message-builder 0.2.0 → 0.3.1

package/src/builder/media.ts

@@ -0,0 +1,484 @@
+/**
+ * @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";
+import * as fmt from "../formatters";
+
+/**
+ * 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 class TelegramMediaBuilder<T extends MediaType> {
+  protected source: MediaSource;
+  protected mediaType: T;
+  protected _caption?: string;
+  protected parseMode: ParseMode = "html";
+  protected options: IMediaCommonOptions = {};
+
+  protected constructor(source: MediaSource, mediaType: T) {
+    this.source = source;
+    this.mediaType = mediaType;
+  }
+
+  /**
+   * 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 {
+    return new PhotoBuilder(source, "photo");
+  }
+
+  /**
+   * 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 {
+    return new VideoBuilder(source, "video");
+  }
+
+  /**
+   * 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 {
+    return new DocumentBuilder(source, "document");
+  }
+
+  /**
+   * 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 {
+    return new AudioBuilder(source, "audio");
+  }
+
+  /**
+   * 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 {
+    return new VoiceBuilder(source, "voice");
+  }
+
+  /**
+   * Set caption for the media
+   *
+   * @param text - Caption text (0-1024 characters)
+   * @returns This builder for chaining
+   */
+  caption(text: string): this {
+    this._caption = text;
+    return this;
+  }
+
+  /**
+   * Set parse mode for caption formatting
+   *
+   * @param mode - Parse mode (html, markdown, or markdownv2)
+   * @returns This builder for chaining
+   */
+  setParseMode(mode: ParseMode): this {
+    this.parseMode = mode;
+    return 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 {
+    this.options[key] = value;
+    return this;
+  }
+
+  /**
+   * Set multiple options at once
+   *
+   * @param opts - Object with options to set
+   * @returns This builder for chaining
+   */
+  setOptions(opts: Partial<IMediaCommonOptions>): this {
+    this.options = { ...this.options, ...opts };
+    return this;
+  }
+
+  /**
+   * Build the media message object
+   *
+   * @returns Complete media message ready for Telegram Bot API
+   */
+  build(): IMediaBuildResult {
+    const result: IMediaBuildResult = {
+      media: this.source,
+      type: this.mediaType,
+    };
+
+    if (this._caption !== undefined) {
+      result.caption = this.formatCaption(this._caption);
+      result.parse_mode = this.parseMode;
+    }
+
+    // Merge in options
+    Object.assign(result, this.options);
+
+    return result;
+  }
+
+  /**
+   * Format caption based on current parse mode
+   *
+   * @param text - Caption text to format
+   * @returns Formatted caption
+   */
+  private formatCaption(text: string): string {
+    switch (this.parseMode) {
+      case "html":
+        return fmt.escapeHTML(text);
+      case "markdown":
+        return fmt.escapeMarkdown(text);
+      case "markdownv2":
+        return fmt.escapeMarkdownV2(text);
+    }
+  }
+}
+
+/**
+ * Photo-specific builder with convenience methods
+ *
+ * @example
+ * ```typescript
+ * const photo = TelegramMediaBuilder.photo("photo.jpg")
+ *   .caption("My photo")
+ *   .thumbnail("thumb.jpg")
+ *   .build();
+ * ```
+ */
+export 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 {
+    this.setOption("thumb", thumb);
+    return 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 class VideoBuilder extends TelegramMediaBuilder<"video"> {
+  /**
+   * Set video duration
+   *
+   * @param seconds - Duration in seconds
+   * @returns This builder for chaining
+   */
+  duration(seconds: number): this {
+    this.setOption("duration", seconds);
+    return this;
+  }
+
+  /**
+   * Set video width
+   *
+   * @param px - Width in pixels
+   * @returns This builder for chaining
+   */
+  width(px: number): this {
+    this.setOption("width", px);
+    return this;
+  }
+
+  /**
+   * Set video height
+   *
+   * @param px - Height in pixels
+   * @returns This builder for chaining
+   */
+  height(px: number): this {
+    this.setOption("height", px);
+    return this;
+  }
+
+  /**
+   * Set thumbnail for the video
+   *
+   * @param thumb - Thumbnail as Buffer or file path
+   * @returns This builder for chaining
+   */
+  thumbnail(thumb: Buffer | string): this {
+    this.setOption("thumb", thumb);
+    return this;
+  }
+
+  /**
+   * Enable streaming for the video
+   *
+   * @returns This builder for chaining
+   */
+  enableStreaming(): this {
+    this.setOption("support_streaming", true);
+    return 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 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 {
+    this.setOption("thumb", thumb);
+    return this;
+  }
+
+  /**
+   * Set original filename
+   *
+   * @param name - File name
+   * @returns This builder for chaining
+   */
+  fileName(name: string): this {
+    this.setOption("file_name", name);
+    return this;
+  }
+
+  /**
+   * Set MIME type
+   *
+   * @param type - MIME type string
+   * @returns This builder for chaining
+   */
+  mimeType(type: string): this {
+    this.setOption("mime_type", type);
+    return this;
+  }
+
+  /**
+   * Disable automatic file type detection
+   *
+   * @returns This builder for chaining
+   */
+  disableContentTypeDetection(): this {
+    this.setOption("disable_content_type_detection", true);
+    return 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 class AudioBuilder extends TelegramMediaBuilder<"audio"> {
+  /**
+   * Set audio duration
+   *
+   * @param seconds - Duration in seconds
+   * @returns This builder for chaining
+   */
+  duration(seconds: number): this {
+    this.setOption("duration", seconds);
+    return this;
+  }
+
+  /**
+   * Set performer name
+   *
+   * @param name - Performer name
+   * @returns This builder for chaining
+   */
+  performer(name: string): this {
+    this.setOption("performer", name);
+    return this;
+  }
+
+  /**
+   * Set track title
+   *
+   * @param name - Track title
+   * @returns This builder for chaining
+   */
+  title(name: string): this {
+    this.setOption("title", name);
+    return this;
+  }
+
+  /**
+   * Set thumbnail (album cover)
+   *
+   * @param thumb - Thumbnail as Buffer or file path
+   * @returns This builder for chaining
+   */
+  thumbnail(thumb: Buffer | string): this {
+    this.setOption("thumb", thumb);
+    return this;
+  }
+}
+
+/**
+ * Voice-specific builder with convenience methods
+ *
+ * @example
+ * ```typescript
+ * const voice = TelegramMediaBuilder.voice("voice.ogg")
+ *   .caption("Listen to this")
+ *   .duration(30)
+ *   .build();
+ * ```
+ */
+export class VoiceBuilder extends TelegramMediaBuilder<"voice"> {
+  /**
+   * Set voice duration
+   *
+   * @param seconds - Duration in seconds
+   * @returns This builder for chaining
+   */
+  duration(seconds: number): this {
+    this.setOption("duration", seconds);
+    return this;
+  }
+}