@mks2508/telegram-message-builder 0.2.0 → 0.3.1

package/dist/types/media.types.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @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;
+    /** Thumbnail of the file sent */
+    thumb?: Buffer | string;
+    /** Duration of the media in seconds */
+    duration?: number;
+    /** Video width */
+    width?: number;
+    /** Video height */
+    height?: number;
+    /** Pass True to upload the video as a streaming video */
+    support_streaming?: boolean;
+    /** Original filename */
+    file_name?: string;
+    /** MIME type of the file */
+    mime_type?: string;
+    /** 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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mks2508/telegram-message-builder",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Telegram bot messaging utilities suite with focus on good DX. Template Strings Native. Keyboard Builder, Media Types Full Support, Zero Runtime Dependencies, Fully typed and schema validated, 100% telegraf compatible. Bot API v9.3+.",
   "type": "module",
   "main": "./dist/index.js",

package/src/builder/builder.d.ts

@@ -1,6 +1,29 @@
 import type { TelegramMessage, ParseMode } from "../types";
 /**
  * Telegram Message Builder - Fluent API for building formatted Telegram messages
+ *
+ * Supports all three Telegram parse modes: HTML, Markdown, and MarkdownV2
+ *
+ * @example
+ * ```typescript
+ * // HTML mode (default)
+ * const msg1 = TelegramMessageBuilder.text()
+ *   .title("Welcome")
+ *   .line("Status", "Active", { bold: true })
+ *   .build();
+ *
+ * // Markdown mode
+ * const msg2 = TelegramMessageBuilder.text()
+ *   .setParseMode("markdown")
+ *   .title("Welcome")
+ *   .build();
+ *
+ * // MarkdownV2 mode
+ * const msg3 = TelegramMessageBuilder.text()
+ *   .setParseMode("markdownv2")
+ *   .title("Welcome")
+ *   .build();
+ * ```
  */
 export declare class TelegramMessageBuilder {
     private parts;
@@ -9,6 +32,38 @@ export declare class TelegramMessageBuilder {
     private constructor();
     static text(): TelegramMessageBuilder;
     setParseMode(mode: ParseMode): this;
+    /**
+     * Formats text as bold based on current parse mode
+     */
+    private bold;
+    /**
+     * Formats text as italic based on current parse mode
+     */
+    private italic;
+    /**
+     * Formats text as underline based on current parse mode
+     */
+    private underline;
+    /**
+     * Formats text as code based on current parse mode
+     */
+    private code;
+    /**
+     * Formats text as code block based on current parse mode
+     */
+    private codeBlockFormat;
+    /**
+     * Creates a link based on current parse mode
+     */
+    private linkFormat;
+    /**
+     * Creates a mention based on current parse mode
+     */
+    private mentionFormat;
+    /**
+     * Creates a hashtag based on current parse mode
+     */
+    private hashtagFormat;
     title(text: string): this;
     section(text: string): this;
     line(key: string, value: string, opts?: {

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

@@ -1 +1 @@
-{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG3D;;GAEG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,OAAO,CAA+B;IAE9C,OAAO,eAEN;IAED,MAAM,CAAC,IAAI,IAAI,sBAAsB,CAEpC;IAED,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAGlC;IAED,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGxB;IAED,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAG1B;IAED,IAAI,CACF,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;QACL,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,GACA,IAAI,CAeN;IAED,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAG/C;IAED,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAG3B;IAED,OAAO,CAAC,KAAK,GAAE,MAAU,GAAG,IAAI,CAK/B;IAED,SAAS,IAAI,IAAI,CAGhB;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGvB;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAGpC;IAED,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAG3C;IAED,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAGzB;IAED,KAAK,IAAI,eAAe,CAMvB;IAED,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAG3C;IAED,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAGjD;IAED,YAAY,IAAI,SAAS,CAExB;CACF"}
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG3D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,sBAAsB;IACjC,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,OAAO,CAA+B;IAE9C,OAAO,eAEN;IAED,MAAM,CAAC,IAAI,IAAI,sBAAsB,CAEpC;IAED,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAGlC;IAED;;OAEG;IACH,OAAO,CAAC,IAAI;IAWZ;;OAEG;IACH,OAAO,CAAC,MAAM;IAWd;;OAEG;IACH,OAAO,CAAC,SAAS;IAWjB;;OAEG;IACH,OAAO,CAAC,IAAI;IAWZ;;OAEG;IACH,OAAO,CAAC,eAAe;IAWvB;;OAEG;IACH,OAAO,CAAC,UAAU;IAWlB;;OAEG;IACH,OAAO,CAAC,aAAa;IAWrB;;OAEG;IACH,OAAO,CAAC,aAAa;IAWrB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGxB;IAED,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAG1B;IAED,IAAI,CACF,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;QACL,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,GACA,IAAI,CAeN;IAED,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAG/C;IAED,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAG3B;IAED,OAAO,CAAC,KAAK,GAAE,MAAU,GAAG,IAAI,CAK/B;IAED,SAAS,IAAI,IAAI,CAGhB;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAGvB;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAGpC;IAED,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAG3C;IAED,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAGzB;IAED,KAAK,IAAI,eAAe,CAMvB;IAED,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAG3C;IAED,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAGjD;IAED,YAAY,IAAI,SAAS,CAExB;CACF"}

package/src/builder/builder.ts

@@ -3,6 +3,29 @@ import * as fmt from "../formatters";
 
 /**
  * Telegram Message Builder - Fluent API for building formatted Telegram messages
+ *
+ * Supports all three Telegram parse modes: HTML, Markdown, and MarkdownV2
+ *
+ * @example
+ * ```typescript
+ * // HTML mode (default)
+ * const msg1 = TelegramMessageBuilder.text()
+ *   .title("Welcome")
+ *   .line("Status", "Active", { bold: true })
+ *   .build();
+ *
+ * // Markdown mode
+ * const msg2 = TelegramMessageBuilder.text()
+ *   .setParseMode("markdown")
+ *   .title("Welcome")
+ *   .build();
+ *
+ * // MarkdownV2 mode
+ * const msg3 = TelegramMessageBuilder.text()
+ *   .setParseMode("markdownv2")
+ *   .title("Welcome")
+ *   .build();
+ * ```
  */
 export class TelegramMessageBuilder {
   private parts: string[] = [];
@@ -22,13 +45,125 @@ export class TelegramMessageBuilder {
     return this;
   }
 
+  /**
+   * Formats text as bold based on current parse mode
+   */
+  private bold(text: string): string {
+    switch (this.parseMode) {
+      case "html":
+        return fmt.bold(text);
+      case "markdown":
+        return fmt.boldMD(text);
+      case "markdownv2":
+        return fmt.boldMDv2(text);
+    }
+  }
+
+  /**
+   * Formats text as italic based on current parse mode
+   */
+  private italic(text: string): string {
+    switch (this.parseMode) {
+      case "html":
+        return fmt.italic(text);
+      case "markdown":
+        return fmt.italicMD(text);
+      case "markdownv2":
+        return fmt.italicMDv2(text);
+    }
+  }
+
+  /**
+   * Formats text as underline based on current parse mode
+   */
+  private underline(text: string): string {
+    switch (this.parseMode) {
+      case "html":
+        return fmt.underline(text);
+      case "markdown":
+        return fmt.underlineMD(text);
+      case "markdownv2":
+        return fmt.underlineMDv2(text);
+    }
+  }
+
+  /**
+   * Formats text as code based on current parse mode
+   */
+  private code(text: string): string {
+    switch (this.parseMode) {
+      case "html":
+        return fmt.code(text);
+      case "markdown":
+        return fmt.codeMD(text);
+      case "markdownv2":
+        return fmt.codeMDv2(text);
+    }
+  }
+
+  /**
+   * Formats text as code block based on current parse mode
+   */
+  private codeBlockFormat(text: string, language?: string): string {
+    switch (this.parseMode) {
+      case "html":
+        return fmt.codeBlock(text, language);
+      case "markdown":
+        return fmt.codeBlockMD(text, language);
+      case "markdownv2":
+        return fmt.codeBlockMDv2(text, language);
+    }
+  }
+
+  /**
+   * Creates a link based on current parse mode
+   */
+  private linkFormat(text: string, url: string): string {
+    switch (this.parseMode) {
+      case "html":
+        return fmt.link(text, url);
+      case "markdown":
+        return fmt.linkMD(text, url);
+      case "markdownv2":
+        return fmt.linkMDv2(text, url);
+    }
+  }
+
+  /**
+   * Creates a mention based on current parse mode
+   */
+  private mentionFormat(userId: number, name?: string): string {
+    switch (this.parseMode) {
+      case "html":
+        return fmt.mention(userId, name);
+      case "markdown":
+        return fmt.mentionMD(userId, name);
+      case "markdownv2":
+        return fmt.mentionMDv2(userId, name);
+    }
+  }
+
+  /**
+   * Creates a hashtag based on current parse mode
+   */
+  private hashtagFormat(tag: string): string {
+    switch (this.parseMode) {
+      case "html":
+        return fmt.hashtag(tag);
+      case "markdown":
+        return fmt.hashtagMD(tag);
+      case "markdownv2":
+        return fmt.hashtagMDv2(tag);
+    }
+  }
+
   title(text: string): this {
-    this.parts.push(fmt.bold(text));
+    this.parts.push(this.bold(text));
     return this;
   }
 
   section(text: string): this {
-    this.parts.push(fmt.underline(text));
+    this.parts.push(this.underline(text));
     return this;
   }
 
@@ -45,13 +180,13 @@ export class TelegramMessageBuilder {
     let formattedValue = value;
 
     if (opts?.bold) {
-      formattedValue = fmt.bold(value);
+      formattedValue = this.bold(value);
     } else if (opts?.italic) {
-      formattedValue = fmt.italic(value);
+      formattedValue = this.italic(value);
     } else if (opts?.code) {
-      formattedValue = fmt.code(value);
+      formattedValue = this.code(value);
     } else if (opts?.underline) {
-      formattedValue = fmt.underline(value);
+      formattedValue = this.underline(value);
     }
 
     this.parts.push(`${key}: ${formattedValue}`);
@@ -59,7 +194,7 @@ export class TelegramMessageBuilder {
   }
 
   codeBlock(text: string, language?: string): this {
-    this.parts.push(fmt.codeBlock(text, language));
+    this.parts.push(this.codeBlockFormat(text, language));
     return this;
   }
 
@@ -86,17 +221,17 @@ export class TelegramMessageBuilder {
   }
 
   link(text: string, url: string): this {
-    this.parts.push(fmt.link(text, url));
+    this.parts.push(this.linkFormat(text, url));
     return this;
   }
 
   mention(userId: number, name?: string): this {
-    this.parts.push(fmt.mention(userId, name));
+    this.parts.push(this.mentionFormat(userId, name));
     return this;
   }
 
   hashtag(tag: string): this {
-    this.parts.push(fmt.hashtag(tag));
+    this.parts.push(this.hashtagFormat(tag));
     return this;
   }
 

package/src/builder/index.d.ts

@@ -1,2 +1,3 @@
-export * from "./builder.ts";
+export * from "./builder";
+export * from "./media";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/src/builder/index.ts

@@ -1 +1,2 @@
-export * from "./builder.ts";
+export * from "./builder";
+export * from "./media";