@mks2508/telegram-message-builder 0.3.0 → 0.4.0

package/dist/builder/builder.d.ts

@@ -0,0 +1,87 @@
+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;
+    private parseMode;
+    private options;
+    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?: {
+        bold?: boolean;
+        italic?: boolean;
+        code?: boolean;
+        underline?: boolean;
+    }): this;
+    codeBlock(text: string, language?: string): this;
+    listItem(text: string): this;
+    newline(count?: number): this;
+    separator(): this;
+    text(text: string): this;
+    link(text: string, url: string): this;
+    mention(userId: number, name?: string): this;
+    hashtag(tag: string): this;
+    build(): TelegramMessage;
+    setOption(key: string, value: unknown): this;
+    setOptions(options: Record<string, unknown>): this;
+    getParseMode(): ParseMode;
+}

package/dist/builder/index.d.ts

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

package/dist/builder/media.d.ts

@@ -0,0 +1,351 @@
+/**
+ * @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;
+}

package/dist/formatters/index.d.ts

@@ -0,0 +1,86 @@
+import type { ParseMode } from "../types";
+import { boldMD, italicMD, codeMD, codeBlockMD, linkMD, mentionMD, hashtagMD, underlineMD, strikethroughMD, spoilerMD, emailMD, urlMD, customEmojiMD, rawMD } from "./markdown";
+import { boldMDv2, italicMDv2, underlineMDv2, strikethroughMDv2, spoilerMDv2, codeMDv2, codeBlockMDv2, linkMDv2, mentionMDv2, hashtagMDv2, emailMDv2, urlMDv2, customEmojiMDv2, rawMDv2, escapeMDv2 } from "./markdownv2";
+export * from "./markdown";
+export * from "./markdownv2";
+export declare function escapeHTML(text: string): string;
+export declare function escapeMarkdown(text: string): string;
+export declare function escapeMarkdownV2(text: string): string;
+export declare function bold(text: string): string;
+export declare function italic(text: string): string;
+export declare function underline(text: string): string;
+export declare function strikethrough(text: string): string;
+export declare function spoiler(text: string): string;
+export declare function code(text: string): string;
+export declare function pre(text: string): string;
+export declare function codeBlock(text: string, language?: string): string;
+export declare function link(text: string, url: string): string;
+export declare function mention(userId: number, name?: string): string;
+export declare function hashtag(tag: string): string;
+export declare function customEmoji(emojiId: string): string;
+export declare function email(email: string): string;
+export declare function url(link: string): string;
+/**
+ * Raw HTML string - bypasses escaping for combining pre-formatted content
+ *
+ * @example
+ * ```typescript
+ * // Instead of this (which escapes inner tags):
+ * fmt.bold(fmt.italic("Text")) // <b>&lt;i&gt;Text&lt;/i&gt;</b>
+ *
+ * // Use this:
+ * fmt.bold(fmt.raw(fmt.italic("Text"))) // <b><i>Text</i></b>
+ * ```
+ */
+export declare function raw(html: string): string;
+export declare function escape(text: string, mode?: ParseMode): string;
+export declare const fmt: {
+    bold: typeof bold;
+    italic: typeof italic;
+    underline: typeof underline;
+    strikethrough: typeof strikethrough;
+    spoiler: typeof spoiler;
+    code: typeof code;
+    pre: typeof pre;
+    codeBlock: typeof codeBlock;
+    link: typeof link;
+    mention: typeof mention;
+    hashtag: typeof hashtag;
+    email: typeof email;
+    url: typeof url;
+    customEmoji: typeof customEmoji;
+    escape: typeof escape;
+    escapeHTML: typeof escapeHTML;
+    escapeMarkdown: typeof escapeMarkdown;
+    escapeMarkdownV2: typeof escapeMarkdownV2;
+    raw: typeof raw;
+    boldMD: typeof boldMD;
+    italicMD: typeof italicMD;
+    codeMD: typeof codeMD;
+    codeBlockMD: typeof codeBlockMD;
+    linkMD: typeof linkMD;
+    mentionMD: typeof mentionMD;
+    hashtagMD: typeof hashtagMD;
+    underlineMD: typeof underlineMD;
+    strikethroughMD: typeof strikethroughMD;
+    spoilerMD: typeof spoilerMD;
+    emailMD: typeof emailMD;
+    urlMD: typeof urlMD;
+    customEmojiMD: typeof customEmojiMD;
+    rawMD: typeof rawMD;
+    boldMDv2: typeof boldMDv2;
+    italicMDv2: typeof italicMDv2;
+    underlineMDv2: typeof underlineMDv2;
+    strikethroughMDv2: typeof strikethroughMDv2;
+    spoilerMDv2: typeof spoilerMDv2;
+    codeMDv2: typeof codeMDv2;
+    codeBlockMDv2: typeof codeBlockMDv2;
+    linkMDv2: typeof linkMDv2;
+    mentionMDv2: typeof mentionMDv2;
+    hashtagMDv2: typeof hashtagMDv2;
+    emailMDv2: typeof emailMDv2;
+    urlMDv2: typeof urlMDv2;
+    customEmojiMDv2: typeof customEmojiMDv2;
+    rawMDv2: typeof rawMDv2;
+    escapeMDv2: typeof escapeMDv2;
+};

package/dist/formatters/markdown.d.ts

@@ -0,0 +1,178 @@
+/**
+ * @fileoverview Markdown (Legacy) Formatters
+ * @description Text formatting functions for Telegram's legacy Markdown parse mode
+ * @module telegram-message-builder/formatters
+ *
+ * @see {@link https://core.telegram.org/bots/api#formatting-options | Telegram Bot API - Formatting Options}
+ */
+/**
+ * Formats text as bold in Markdown
+ *
+ * @param text - The text to format
+ * @returns Bold formatted text
+ * @example
+ * ```typescript
+ * boldMD("Hello") // "*Hello*"
+ * ```
+ */
+export declare function boldMD(text: string): string;
+/**
+ * Formats text as italic in Markdown
+ *
+ * @param text - The text to format
+ * @returns Italic formatted text
+ * @example
+ * ```typescript
+ * italicMD("Hello") // "_Hello_"
+ * ```
+ */
+export declare function italicMD(text: string): string;
+/**
+ * Formats text as monospace code in Markdown
+ *
+ * @param text - The text to format
+ * @returns Code formatted text
+ * @example
+ * ```typescript
+ * codeMD("const x = 1") // "`const x = 1`"
+ * ```
+ */
+export declare function codeMD(text: string): string;
+/**
+ * Formats text as a code block in Markdown
+ *
+ * @param text - The code to format
+ * @param language - Optional programming language for syntax highlighting
+ * @returns Code block formatted text
+ * @example
+ * ```typescript
+ * codeBlockMD("console.log('Hello')") // "```console.log('Hello')```"
+ * codeBlockMD("const x = 1", "javascript") // "```javascript\nconst x = 1\n```"
+ * ```
+ */
+export declare function codeBlockMD(text: string, language?: string): string;
+/**
+ * Creates a link in Markdown format
+ *
+ * @param text - The link text
+ * @param url - The URL to link to
+ * @returns Link formatted text
+ * @example
+ * ```typescript
+ * linkMD("Google", "https://google.com") // "[Google](https://google.com)"
+ * ```
+ */
+export declare function linkMD(text: string, url: string): string;
+/**
+ * Creates a user mention link in Markdown format
+ *
+ * @param userId - The user's ID
+ * @param name - Optional display name
+ * @returns Mention formatted text
+ * @example
+ * ```typescript
+ * mentionMD(123456) // "tg://user?id=123456"
+ * mentionMD(123456, "John") // "tg://user?id=123456"
+ * ```
+ */
+export declare function mentionMD(userId: number, _name?: string): string;
+/**
+ * Creates a hashtag link in Markdown format
+ *
+ * @param tag - The hashtag text (without #)
+ * @returns Hashtag formatted text
+ * @example
+ * ```typescript
+ * hashtagMD("test") // "#test"
+ * ```
+ */
+export declare function hashtagMD(tag: string): string;
+/**
+ * Formats text as underline in Markdown (limited support)
+ *
+ * Note: Standard Markdown doesn't support underline. This uses HTML which
+ * may not work in all Telegram clients.
+ *
+ * @param text - The text to format
+ * @returns Underline formatted text (HTML fallback)
+ * @example
+ * ```typescript
+ * underlineMD("Hello") // "<u>Hello</u>"
+ * ```
+ */
+export declare function underlineMD(text: string): string;
+/**
+ * Formats text as strikethrough in Markdown (limited support)
+ *
+ * Note: Standard Markdown doesn't support strikethrough. This uses HTML which
+ * may not work in all Telegram clients.
+ *
+ * @param text - The text to format
+ * @returns Strikethrough formatted text (HTML fallback)
+ * @example
+ * ```typescript
+ * strikethroughMD("Hello") // "<s>Hello</s>"
+ * ```
+ */
+export declare function strikethroughMD(text: string): string;
+/**
+ * Formats text as spoiler in Markdown (limited support)
+ *
+ * Note: Standard Markdown doesn't support spoiler. This uses HTML which
+ * may not work in all Telegram clients.
+ *
+ * @param text - The text to format
+ * @returns Spoiler formatted text (HTML fallback)
+ * @example
+ * ```typescript
+ * spoilerMD("Secret") // "<tg-spoiler>Secret</tg-spoiler>"
+ * ```
+ */
+export declare function spoilerMD(text: string): string;
+/**
+ * Creates an email link in Markdown format
+ *
+ * @param email - The email address
+ * @returns Email link formatted text
+ * @example
+ * ```typescript
+ * emailMD("test@example.com") // "[test@example.com](mailto:test@example.com)"
+ * ```
+ */
+export declare function emailMD(email: string): string;
+/**
+ * Creates a URL link in Markdown format
+ *
+ * @param url - The URL
+ * @returns URL link formatted text
+ * @example
+ * ```typescript
+ * urlMD("https://example.com") // "[https://example.com](https://example.com)"
+ * ```
+ */
+export declare function urlMD(url: string): string;
+/**
+ * Creates a custom emoji in Markdown format (limited support)
+ *
+ * Note: Standard Markdown doesn't support custom emoji. This uses HTML which
+ * may not work in all Telegram clients.
+ *
+ * @param emojiId - The custom emoji ID
+ * @returns Custom emoji formatted text (HTML fallback)
+ * @example
+ * ```typescript
+ * customEmojiMD("5368324170672642286") // "<tg-emoji emoji-id=\"5368324170672642286\">👻</tg-emoji>"
+ * ```
+ */
+export declare function customEmojiMD(emojiId: string): string;
+/**
+ * Raw Markdown string - bypasses any automatic formatting
+ *
+ * @param markdown - Pre-formatted Markdown string
+ * @returns The Markdown string unchanged
+ * @example
+ * ```typescript
+ * rawMD("*Hello*") // "*Hello*"
+ * ```
+ */
+export declare function rawMD(markdown: string): string;