@mks2508/telegram-message-builder 0.3.0 → 0.4.0

package/dist/formatters/markdownv2.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @fileoverview MarkdownV2 Formatters
+ * @description Text formatting functions for Telegram's MarkdownV2 parse mode
+ * @module telegram-message-builder/formatters
+ *
+ * @see {@link https://core.telegram.org/bots/api#markdownv2-style | Telegram Bot API - MarkdownV2 Style}
+ */
+/**
+ * Formats text as bold in MarkdownV2
+ *
+ * @param text - The text to format
+ * @returns Bold formatted text
+ * @example
+ * ```typescript
+ * boldMDv2("Hello") // "*Hello*"
+ * ```
+ */
+export declare function boldMDv2(text: string): string;
+/**
+ * Formats text as italic in MarkdownV2
+ *
+ * @param text - The text to format
+ * @returns Italic formatted text
+ * @example
+ * ```typescript
+ * italicMDv2("Hello") // "_Hello_"
+ * ```
+ */
+export declare function italicMDv2(text: string): string;
+/**
+ * Formats text as underline in MarkdownV2
+ *
+ * @param text - The text to format
+ * @returns Underline formatted text
+ * @example
+ * ```typescript
+ * underlineMDv2("Hello") // "__Hello__"
+ * ```
+ */
+export declare function underlineMDv2(text: string): string;
+/**
+ * Formats text as strikethrough in MarkdownV2
+ *
+ * @param text - The text to format
+ * @returns Strikethrough formatted text
+ * @example
+ * ```typescript
+ * strikethroughMDv2("Hello") // "~Hello~"
+ * ```
+ */
+export declare function strikethroughMDv2(text: string): string;
+/**
+ * Formats text as spoiler in MarkdownV2
+ *
+ * @param text - The text to format
+ * @returns Spoiler formatted text
+ * @example
+ * ```typescript
+ * spoilerMDv2("Secret") // "||Secret||"
+ * ```
+ */
+export declare function spoilerMDv2(text: string): string;
+/**
+ * Formats text as monospace code in MarkdownV2
+ *
+ * @param text - The text to format
+ * @returns Code formatted text
+ * @example
+ * ```typescript
+ * codeMDv2("const x = 1") // "`const x = 1`"
+ * ```
+ */
+export declare function codeMDv2(text: string): string;
+/**
+ * Formats text as a code block in MarkdownV2
+ *
+ * @param text - The code to format
+ * @param language - Optional programming language for syntax highlighting
+ * @returns Code block formatted text
+ * @example
+ * ```typescript
+ * codeBlockMDv2("console.log('Hello')") // "```console.log('Hello')```"
+ * codeBlockMDv2("const x = 1", "javascript") // "```javascript\nconst x = 1\n```"
+ * ```
+ */
+export declare function codeBlockMDv2(text: string, language?: string): string;
+/**
+ * Creates a link in MarkdownV2 format
+ *
+ * @param text - The link text
+ * @param url - The URL to link to
+ * @returns Link formatted text
+ * @example
+ * ```typescript
+ * linkMDv2("Google", "https://google.com") // "[Google](https://google.com)"
+ * ```
+ */
+export declare function linkMDv2(text: string, url: string): string;
+/**
+ * Creates a user mention link in MarkdownV2 format
+ *
+ * @param userId - The user's ID
+ * @param name - Optional display name (ignored in MarkdownV2)
+ * @returns Mention formatted text
+ * @example
+ * ```typescript
+ * mentionMDv2(123456) // "[user](tg://user?id=123456)"
+ * mentionMDv2(123456, "John") // "[John](tg://user?id=123456)"
+ * ```
+ */
+export declare function mentionMDv2(userId: number, name?: string): string;
+/**
+ * Creates a hashtag link in MarkdownV2 format
+ *
+ * @param tag - The hashtag text (without #)
+ * @returns Hashtag formatted text
+ * @example
+ * ```typescript
+ * hashtagMDv2("test") // "#test"
+ * ```
+ */
+export declare function hashtagMDv2(tag: string): string;
+/**
+ * Creates an email link in MarkdownV2 format
+ *
+ * @param email - The email address
+ * @returns Email link formatted text
+ * @example
+ * ```typescript
+ * emailMDv2("test@example.com") // "[test@example.com](mailto:test@example.com)"
+ * ```
+ */
+export declare function emailMDv2(email: string): string;
+/**
+ * Creates a URL link in MarkdownV2 format
+ *
+ * @param url - The URL
+ * @returns URL link formatted text
+ * @example
+ * ```typescript
+ * urlMDv2("https://example.com") // "[https://example.com](https://example.com)"
+ * ```
+ */
+export declare function urlMDv2(url: string): string;
+/**
+ * Creates a custom emoji in MarkdownV2 format
+ *
+ * Note: Custom emoji syntax in MarkdownV2 uses a special format with the emoji
+ * ID wrapped in special syntax.
+ *
+ * @param emojiId - The custom emoji ID
+ * @returns Custom emoji formatted text
+ * @example
+ * ```typescript
+ * customEmojiMDv2("5368324170672642286") // "👻 [Custom emoji](tg://emoji?id=5368324170672642286)"
+ * ```
+ */
+export declare function customEmojiMDv2(emojiId: string): string;
+/**
+ * Raw MarkdownV2 string - bypasses any automatic formatting
+ *
+ * @param markdown - Pre-formatted MarkdownV2 string
+ * @returns The MarkdownV2 string unchanged
+ * @example
+ * ```typescript
+ * rawMDv2("*Hello*") // "*Hello*"
+ * ```
+ */
+export declare function rawMDv2(markdown: string): string;
+/**
+ * Pre-escapes text for safe use in MarkdownV2 formatting
+ *
+ * MarkdownV2 requires careful character escaping. This function escapes
+ * all reserved characters for safe use in formatted text.
+ *
+ * @param text - The text to escape
+ * @returns Escaped text safe for MarkdownV2
+ * @example
+ * ```typescript
+ * escapeMDv2("Hello_World") // "Hello\\_World"
+ * ```
+ */
+export declare function escapeMDv2(text: string): string;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./types";
+export * from "./formatters";
+export * from "./keyboard";
+export * from "./builder";
+export type { ParseMode, FormatOpts, LineOpts, TelegramMessage, BuildResult, ValidationError, } from "./types/core.types";
+export type { IInlineKeyboardMarkup, IInlineKeyboardButton, IReplyKeyboardMarkup, IKeyboardButton, IForceReplyMarkup, } from "./types/keyboard.types";
+export type { MediaSource, MediaType, IMediaCommonOptions, IMediaBuildResult, IPhotoOptions, IVideoOptions, IDocumentOptions, IAudioOptions, IVoiceOptions, } from "./types/media.types";
+export { fmt } from "./formatters";
+export { TelegramMessageBuilder } from "./builder";
+export { TelegramKeyboardBuilder } from "./keyboard";
+export { TelegramMediaBuilder } from "./builder";

package/dist/keyboard/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Keyboard Builders
+ * @description Fluent API for building Telegram keyboards
+ * @module telegram-message-builder/keyboard
+ */
+import type { IInlineKeyboardMarkup, IInlineKeyboardButton, IReplyKeyboardMarkup, IKeyboardButton, IForceReplyMarkup } from "../types";
+/**
+ * Telegram Keyboard Builder - Fluent API for building keyboards
+ *
+ * @example
+ * ```typescript
+ * const keyboard = TelegramKeyboardBuilder.inline()
+ *   .urlButton('Google', 'https://google.com')
+ *   .row()
+ *   .callbackButton('Yes', 'yes')
+ *   .callbackButton('No', 'no')
+ *   .buildMarkup()
+ * ```
+ */
+export declare class TelegramKeyboardBuilder {
+    private rows;
+    private type;
+    private currentRow;
+    private constructor();
+    /**
+     * Create an inline keyboard builder
+     */
+    static inline(): TelegramKeyboardBuilder;
+    /**
+     * Create a reply keyboard builder
+     */
+    static reply(): TelegramKeyboardBuilder;
+    /**
+     * Create a force reply builder
+     */
+    static forceReply(): TelegramKeyboardBuilder;
+    /**
+     * Add a URL button (inline only)
+     */
+    urlButton(text: string, url: string): this;
+    /**
+     * Add a callback button (inline only)
+     */
+    callbackButton(text: string, data: string): this;
+    /**
+     * Add a web app button (inline only)
+     */
+    webAppButton(text: string, url: string): this;
+    /**
+     * Add a login button (inline only)
+     */
+    loginButton(text: string, url: string, options?: {
+        forwardText?: string;
+        botUsername?: string;
+        requestWriteAccess?: boolean;
+    }): this;
+    /**
+     * Add a switch inline query button (inline only)
+     */
+    switchInlineQueryButton(text: string, query: string): this;
+    /**
+     * Add a switch inline query current chat button (inline only)
+     */
+    switchInlineQueryCurrentChatButton(text: string, query: string): this;
+    /**
+     * Add a callback game button (inline only)
+     */
+    callbackGameButton(text: string, shortName: string): this;
+    /**
+     * Add a pay button (inline only)
+     */
+    payButton(text: string): this;
+    /**
+     * Add a text button (reply keyboard only)
+     */
+    textButton(text: string): this;
+    /**
+     * Add a request contact button (reply keyboard only)
+     */
+    requestContactButton(text: string): this;
+    /**
+     * Add a request location button (reply keyboard only)
+     */
+    requestLocationButton(text: string): this;
+    /**
+     * Add a request poll button (reply keyboard only)
+     */
+    requestPollButton(text: string, pollType: string): this;
+    /**
+     * Add a custom button to current row
+     */
+    button(button: IInlineKeyboardButton | IKeyboardButton): this;
+    /**
+     * Finish current row and start a new one
+     */
+    row(): this;
+    /**
+     * Build inline keyboard markup
+     */
+    buildMarkup(): IInlineKeyboardMarkup;
+    /**
+     * Build reply keyboard markup
+     */
+    buildReplyMarkup(): IReplyKeyboardMarkup;
+    /**
+     * Build force reply markup
+     */
+    buildForceReplyMarkup(): IForceReplyMarkup;
+    /**
+     * Build markup based on keyboard type
+     */
+    build(): IInlineKeyboardMarkup | IReplyKeyboardMarkup | IForceReplyMarkup;
+}

package/dist/types/constants.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Constantes del package.
+ *
+ * @module
+ */
+/**
+ * Prefijo por defecto para saludos.
+ */
+export declare const DEFAULT_PREFIX = "Hello";
+/**
+ * Sufijo por defecto para saludos.
+ */
+export declare const DEFAULT_SUFFIX = "!";

package/dist/types/core.types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview Core types for Telegram Message Builder
+ * @description Defines the base types used throughout the message builder
+ * @module telegram-message-builder/types
+ */
+/**
+ * Parse mode for Telegram messages
+ */
+export type ParseMode = "html" | "markdown" | "markdownv2";
+/**
+ * Format options for inline formatting
+ */
+export interface FormatOpts {
+    /** Make text bold */
+    bold?: boolean;
+    /** Make text italic */
+    italic?: boolean;
+    /** Make text monospace (code) */
+    code?: boolean;
+    /** Make text underlined */
+    underline?: boolean;
+    /** Make text strikethrough */
+    strikethrough?: boolean;
+    /** Make text spoiler */
+    spoiler?: boolean;
+}
+/**
+ * Options for line formatting
+ */
+export interface LineOpts extends FormatOpts {
+    /** Custom format string instead of key: value */
+    format?: string;
+}
+/**
+ * Generic Telegram message type
+ */
+export interface TelegramMessage {
+    /** Message text */
+    text?: string;
+    /** Message caption (for media) */
+    caption?: string;
+    /** Parse mode for the message */
+    parse_mode?: ParseMode | undefined;
+    /** Reply markup (inline or reply keyboard) */
+    reply_markup?: unknown;
+    /** Disable web page preview */
+    disable_web_page_preview?: boolean;
+    /** Disable notification */
+    disable_notification?: boolean;
+    /** Protect content from forwarding */
+    protect_content?: boolean;
+    /** Reply to specific message */
+    reply_to_message_id?: number;
+}
+/**
+ * Build result
+ */
+export interface BuildResult {
+    /** Formatted message text or caption */
+    text: string;
+    /** Parse mode for the message */
+    parse_mode: ParseMode;
+    /** Reply markup if any */
+    reply_markup?: unknown;
+    /** Additional options */
+    options?: Record<string, unknown>;
+}
+/**
+ * Validation error
+ */
+export interface ValidationError {
+    message: string;
+    code: string;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./core.types";
+export * from "./constants";
+export * from "./keyboard.types";
+export * from "./media.types";

package/dist/types/keyboard-types.index.d.ts

@@ -0,0 +1 @@
+export * from "./keyboard.types";

package/dist/types/keyboard.types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @fileoverview Keyboard Types
+ * @description Types for inline and reply keyboards
+ * @module telegram-message-builder/types
+ */
+/**
+ * Inline keyboard button
+ */
+export interface IInlineKeyboardButton {
+    text: string;
+    url?: string;
+    callback_data?: string;
+    web_app?: {
+        url: string;
+    };
+    login_url?: {
+        url: string;
+        forward_text?: string;
+        bot_username?: string;
+        request_write_access?: boolean;
+    };
+    switch_inline_query?: string;
+    switch_inline_query_current_chat?: string;
+    callback_game?: string;
+    pay?: string;
+}
+/**
+ * Inline keyboard markup
+ */
+export interface IInlineKeyboardMarkup {
+    inline_keyboard: IInlineKeyboardButton[][];
+}
+/**
+ * Reply keyboard button
+ */
+export interface IKeyboardButton {
+    text: string;
+    request_contact?: boolean;
+    request_location?: boolean;
+    request_poll?: {
+        type: string;
+    };
+    request_chat?: {
+        chat_is_channel: boolean;
+        chat_is_forum?: boolean;
+        chat_has_username?: boolean;
+        chat_is_created: boolean;
+        user_administrator_rights?: number[];
+        bot_is_member?: boolean;
+    };
+    request_user?: {
+        request_id: number;
+        user_is_bot: boolean;
+        user_is_premium: boolean;
+    };
+    web_app?: {
+        url: string;
+    };
+}
+/**
+ * Reply keyboard markup
+ */
+export interface IReplyKeyboardMarkup {
+    keyboard: IKeyboardButton[][];
+    resize_keyboard?: boolean;
+    one_time_keyboard?: boolean;
+    input_field_placeholder?: string;
+    selective?: boolean;
+    is_persistent?: boolean;
+}
+/**
+ * Force reply markup
+ */
+export interface IForceReplyMarkup {
+    force_reply: true;
+    input_field_placeholder?: string;
+    selective?: boolean;
+}
+/**
+ * Reply parameters
+ */
+export interface IReplyParameters {
+    message_id: number;
+    allow_sending_without_reply?: boolean;
+    quote?: {
+        text: string;
+        entities?: unknown[];
+        parse_mode?: "html" | "markdown" | "markdownv2";
+        quote_position?: number;
+    };
+    quote_parse_mode?: "html" | "markdown" | "markdownv2";
+    quote_text?: string;
+    quote_entities?: unknown[];
+    quote_position?: number;
+}

package/dist/types/main.types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tipos del dominio principal.
+ *
+ * @module
+ */
+/**
+ * Opciones de configuracion para saludos.
+ */
+export interface IGreetOptions {
+    /**
+     * Prefijo del saludo (default: "Hello").
+     */
+    prefix?: string;
+    /**
+     * Sufijo del saludo (default: "!").
+     */
+    suffix?: string;
+}
+/**
+ * Callback para notificar eventos.
+ */
+export type IEventCallback = (event: string) => void;

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.3.0",
+  "version": "0.4.0",
   "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",