@mks2508/telegram-message-builder 0.2.0 → 0.3.1

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;