@mks2508/telegram-message-builder 0.2.0 → 0.3.0

package/src/formatters/markdown.d.ts

@@ -0,0 +1,179 @@
+/**
+ * @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;
+//# sourceMappingURL=markdown.d.ts.map

package/src/formatters/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["markdown.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7C;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEzC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/src/formatters/markdown.test.ts

@@ -0,0 +1,417 @@
+import { describe, it, expect } from "bun:test";
+import * as fmt from "..";
+
+describe("Markdown (Legacy) Formatters", () => {
+  describe("Text Formatting", () => {
+    it("should format bold text", () => {
+      const result = fmt.boldMD("Hello");
+      expect(result).toBe("*Hello*");
+    });
+
+    it("should format italic text", () => {
+      const result = fmt.italicMD("Hello");
+      expect(result).toBe("_Hello_");
+    });
+
+    it("should format code text", () => {
+      const result = fmt.codeMD("const x = 1");
+      expect(result).toBe("`const x = 1`");
+    });
+
+    it("should format code block without language", () => {
+      const result = fmt.codeBlockMD("const x = 1");
+      expect(result).toBe("const x = 1\n");
+    });
+
+    it("should format code block with language", () => {
+      const result = fmt.codeBlockMD("const x = 1", "javascript");
+      expect(result).toBe("javascript\nconst x = 1\n");
+    });
+
+    it("should format multiline code block", () => {
+      const code = "const x = 1;\nconst y = 2;";
+      const result = fmt.codeBlockMD(code);
+      expect(result).toBe("const x = 1;\nconst y = 2;\n");
+    });
+
+    it("should format underline (HTML fallback)", () => {
+      const result = fmt.underlineMD("Hello");
+      expect(result).toBe("<u>Hello</u>");
+    });
+
+    it("should format strikethrough (HTML fallback)", () => {
+      const result = fmt.strikethroughMD("Hello");
+      expect(result).toBe("<s>Hello</s>");
+    });
+
+    it("should format spoiler (HTML fallback)", () => {
+      const result = fmt.spoilerMD("Secret");
+      expect(result).toBe("<tg-spoiler>Secret</tg-spoiler>");
+    });
+  });
+
+  describe("Links and Mentions", () => {
+    it("should format link", () => {
+      const result = fmt.linkMD("Google", "https://google.com");
+      expect(result).toBe("[Google](https://google.com)");
+    });
+
+    it("should format mention without name", () => {
+      const result = fmt.mentionMD(123456);
+      expect(result).toBe("tg://user?id=123456");
+    });
+
+    it("should format mention with name (ignored in MD)", () => {
+      const result = fmt.mentionMD(123456, "John Doe");
+      expect(result).toBe("tg://user?id=123456");
+    });
+
+    it("should format hashtag", () => {
+      const result = fmt.hashtagMD("test");
+      expect(result).toBe("#test");
+    });
+
+    it("should format email link", () => {
+      const result = fmt.emailMD("test@example.com");
+      expect(result).toBe("[test@example.com](mailto:test@example.com)");
+    });
+
+    it("should format URL link", () => {
+      const result = fmt.urlMD("https://example.com");
+      expect(result).toBe("[https://example.com](https://example.com)");
+    });
+
+    it("should format custom emoji (HTML fallback)", () => {
+      const result = fmt.customEmojiMD("5368324170672642286");
+      expect(result).toContain('<tg-emoji emoji-id="5368324170672642286">');
+      expect(result).toContain("👻");
+    });
+  });
+
+  describe("Raw Helper", () => {
+    it("should return input unchanged", () => {
+      const markdown = "*Hello* _World_";
+      const result = fmt.rawMD(markdown);
+      expect(result).toBe(markdown);
+    });
+
+    it("should preserve complex markdown", () => {
+      const markdown = "[Link](url) `code` **bold**";
+      const result = fmt.rawMD(markdown);
+      expect(result).toBe(markdown);
+    });
+  });
+
+  describe("Combined Formatting", () => {
+    it("should format bold + italic", () => {
+      const result = `${fmt.boldMD("Bold")} ${fmt.italicMD("Italic")}`;
+      expect(result).toBe("*Bold* _Italic_");
+    });
+
+    it("should format link + code", () => {
+      const result = `${fmt.linkMD("Docs", "https://example.com")} - ${fmt.codeMD("v1.0")}`;
+      expect(result).toBe("[Docs](https://example.com) - `v1.0`");
+    });
+
+    it("should format complex message", () => {
+      const message = `${fmt.boldMD("Title")}\n\n${fmt.codeBlockMD("const x = 1;", "js")}\n\nLink: ${fmt.linkMD("Click", "https://example.com")}`;
+      expect(message).toContain("*Title*");
+      expect(message).toContain("js"); // language prefix
+      expect(message).toContain("const x = 1;");
+      expect(message).toContain("[Click](https://example.com)");
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle empty string", () => {
+      expect(fmt.boldMD("")).toBe("**"); // Empty string between asterisks
+      expect(fmt.italicMD("")).toBe("__"); // Empty string between underscores
+      expect(fmt.codeMD("")).toBe("``"); // Empty string between backticks
+    });
+
+    it("should handle special characters", () => {
+      const result = fmt.boldMD("Test [with] (special) chars");
+      expect(result).toBe("*Test [with] (special) chars*");
+    });
+
+    it("should handle unicode", () => {
+      const result = fmt.boldMD("🎉 Party! 🎊");
+      expect(result).toBe("*🎉 Party! 🎊*");
+    });
+
+    it("should handle very long text", () => {
+      const longText = "a".repeat(1000);
+      const result = fmt.boldMD(longText);
+      expect(result).toBe(`*${longText}*`);
+      expect(result.length).toBe(1002);
+    });
+  });
+});
+
+describe("MarkdownV2 Formatters", () => {
+  describe("Text Formatting", () => {
+    it("should format bold text", () => {
+      const result = fmt.boldMDv2("Hello");
+      expect(result).toBe("*Hello*");
+    });
+
+    it("should format italic text", () => {
+      const result = fmt.italicMDv2("Hello");
+      expect(result).toBe("_Hello_");
+    });
+
+    it("should format underline text", () => {
+      const result = fmt.underlineMDv2("Hello");
+      expect(result).toBe("__Hello__");
+    });
+
+    it("should format strikethrough text", () => {
+      const result = fmt.strikethroughMDv2("Hello");
+      expect(result).toBe("~Hello~");
+    });
+
+    it("should format spoiler text", () => {
+      const result = fmt.spoilerMDv2("Secret");
+      expect(result).toBe("||Secret||");
+    });
+
+    it("should format code text", () => {
+      const result = fmt.codeMDv2("const x = 1");
+      expect(result).toBe("`const x = 1`");
+    });
+
+    it("should format code block without language", () => {
+      const result = fmt.codeBlockMDv2("const x = 1");
+      expect(result).toBe("const x = 1\n");
+    });
+
+    it("should format code block with language", () => {
+      const result = fmt.codeBlockMDv2("const x = 1", "javascript");
+      expect(result).toBe("javascript\nconst x = 1\n");
+    });
+  });
+
+  describe("Links and Mentions", () => {
+    it("should format link", () => {
+      const result = fmt.linkMDv2("Google", "https://google.com");
+      expect(result).toBe("[Google](https://google.com)");
+    });
+
+    it("should format mention without name", () => {
+      const result = fmt.mentionMDv2(123456);
+      expect(result).toBe("[user](tg://user?id=123456)");
+    });
+
+    it("should format mention with custom name", () => {
+      const result = fmt.mentionMDv2(123456, "John Doe");
+      expect(result).toBe("[John Doe](tg://user?id=123456)");
+    });
+
+    it("should format hashtag", () => {
+      const result = fmt.hashtagMDv2("test");
+      expect(result).toBe("#test");
+    });
+
+    it("should format email link", () => {
+      const result = fmt.emailMDv2("test@example.com");
+      expect(result).toBe("[test@example.com](mailto:test@example.com)");
+    });
+
+    it("should format URL link", () => {
+      const result = fmt.urlMDv2("https://example.com");
+      expect(result).toBe("[https://example.com](https://example.com)");
+    });
+
+    it("should format custom emoji", () => {
+      const result = fmt.customEmojiMDv2("5368324170672642286");
+      expect(result).toContain("👻");
+      expect(result).toContain("5368324170672642286");
+    });
+  });
+
+  describe("Escape Function", () => {
+    it("should escape all reserved characters", () => {
+      const text = "_*[]()~`>#+-=|{}.!";
+      const result = fmt.escapeMDv2(text);
+      expect(result).toBe(
+        "\\_\\*\\[\\]\\(\\)\\~\\`\\>\\#\\+\\-\\=\\|\\{\\}\\.\\!",
+      );
+    });
+
+    it("should not escape regular text", () => {
+      const text = "Hello World 123";
+      const result = fmt.escapeMDv2(text);
+      expect(result).toBe("Hello World 123");
+    });
+
+    it("should escape mixed content", () => {
+      const text = "Click [here](url) for *bold* text";
+      const result = fmt.escapeMDv2(text);
+      expect(result).toContain("\\[");
+      expect(result).toContain("\\]");
+      expect(result).toContain("\\*");
+    });
+
+    it("should handle empty string", () => {
+      const result = fmt.escapeMDv2("");
+      expect(result).toBe("");
+    });
+
+    it("should escape repeated characters", () => {
+      const text = "***";
+      const result = fmt.escapeMDv2(text);
+      expect(result).toBe("\\*\\*\\*");
+    });
+  });
+
+  describe("Raw Helper", () => {
+    it("should return input unchanged", () => {
+      const markdown = "*Hello* _World_";
+      const result = fmt.rawMDv2(markdown);
+      expect(result).toBe(markdown);
+    });
+  });
+
+  describe("Combined Formatting", () => {
+    it("should format bold + italic + underline", () => {
+      const result = `${fmt.boldMDv2("Bold")} ${fmt.italicMDv2("Italic")} ${fmt.underlineMDv2("Underline")}`;
+      expect(result).toBe("*Bold* _Italic_ __Underline__");
+    });
+
+    it("should format strikethrough + spoiler", () => {
+      const result = `${fmt.strikethroughMDv2("Old")} ${fmt.spoilerMDv2("Secret")}`;
+      expect(result).toBe("~Old~ ||Secret||");
+    });
+
+    it("should format complex message", () => {
+      const message =
+        `${fmt.boldMDv2("Title")}\n\n` +
+        `${fmt.codeBlockMDv2("const x = 1;", "js")}\n\n` +
+        `Link: ${fmt.linkMDv2("Click", "https://example.com")}\n` +
+        `Mention: ${fmt.mentionMDv2(123456, "User")}\n` +
+        `Hashtag: ${fmt.hashtagMDv2("test")}`;
+
+      expect(message).toContain("*Title*");
+      expect(message).toContain("js"); // language prefix
+      expect(message).toContain("const x = 1;");
+      expect(message).toContain("[Click]");
+      expect(message).toContain("[User](tg://user?id=123456)");
+      expect(message).toContain("#test");
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle empty string", () => {
+      expect(fmt.boldMDv2("")).toBe("**"); // Empty string between asterisks
+      expect(fmt.italicMDv2("")).toBe("__"); // Empty string between underscores
+      expect(fmt.underlineMDv2("")).toBe("____"); // Empty string between double underscores
+      expect(fmt.strikethroughMDv2("")).toBe("~~"); // Empty string between tildes
+      expect(fmt.spoilerMDv2("")).toBe("||||"); // Empty string between double pipes
+    });
+
+    it("should handle special characters that need escaping", () => {
+      const text = "Text with [brackets] and (parens)";
+      const escaped = fmt.escapeMDv2(text);
+      expect(escaped).toContain("\\[");
+      expect(escaped).toContain("\\]");
+      expect(escaped).toContain("\\(");
+      expect(escaped).toContain("\\)");
+    });
+
+    it("should handle unicode", () => {
+      const result = fmt.boldMDv2("🎉 Party! 🎊");
+      expect(result).toBe("*🎉 Party! 🎊*");
+    });
+
+    it("should handle very long text", () => {
+      const longText = "a".repeat(1000);
+      const result = fmt.boldMDv2(longText);
+      expect(result).toBe(`*${longText}*`);
+      expect(result.length).toBe(1002);
+    });
+
+    it("should escape all reserved chars in formatter context", () => {
+      const text = "Text with * and _ and ~ and |";
+      const escaped = fmt.escapeMDv2(text);
+      expect(escaped).toContain("\\*");
+      expect(escaped).toContain("\\_");
+      expect(escaped).toContain("\\~");
+      expect(escaped).toContain("\\|");
+    });
+  });
+
+  describe("MarkdownV2-Specific Features", () => {
+    it("should format underline which is MDv2-only", () => {
+      const result = fmt.underlineMDv2("Important");
+      expect(result).toBe("__Important__");
+    });
+
+    it("should format strikethrough which is MDv2-only", () => {
+      const result = fmt.strikethroughMDv2("Deleted");
+      expect(result).toBe("~Deleted~");
+    });
+
+    it("should format spoiler which is MDv2-only", () => {
+      const result = fmt.spoilerMDv2("Surprise!");
+      expect(result).toBe("||Surprise!||");
+    });
+
+    it("should combine multiple MDv2-exclusive features", () => {
+      const result =
+        `${fmt.underlineMDv2("Under")} ` +
+        `${fmt.strikethroughMDv2("Strike")} ` +
+        `${fmt.spoilerMDv2("Spoiler")}`;
+      expect(result).toBe("__Under__ ~Strike~ ||Spoiler||");
+    });
+  });
+});
+
+describe("Markdown vs MarkdownV2 Comparison", () => {
+  it("should format bold the same way", () => {
+    expect(fmt.boldMD("Test")).toBe(fmt.boldMDv2("Test"));
+  });
+
+  it("should format italic the same way", () => {
+    expect(fmt.italicMD("Test")).toBe(fmt.italicMDv2("Test"));
+  });
+
+  it("should format code the same way", () => {
+    expect(fmt.codeMD("Test")).toBe(fmt.codeMDv2("Test"));
+  });
+
+  it("should format code block the same way", () => {
+    expect(fmt.codeBlockMD("Test")).toBe(fmt.codeBlockMDv2("Test"));
+    expect(fmt.codeBlockMD("Test", "js")).toBe(fmt.codeBlockMDv2("Test", "js"));
+  });
+
+  it("should differ in underline (MD uses HTML, MDv2 uses __)", () => {
+    expect(fmt.underlineMD("Test")).toBe("<u>Test</u>");
+    expect(fmt.underlineMDv2("Test")).toBe("__Test__");
+  });
+
+  it("should differ in strikethrough (MD uses HTML, MDv2 uses ~)", () => {
+    expect(fmt.strikethroughMD("Test")).toBe("<s>Test</s>");
+    expect(fmt.strikethroughMDv2("Test")).toBe("~Test~");
+  });
+
+  it("should differ in spoiler (MD uses HTML, MDv2 uses ||)", () => {
+    expect(fmt.spoilerMD("Test")).toBe("<tg-spoiler>Test</tg-spoiler>");
+    expect(fmt.spoilerMDv2("Test")).toBe("||Test||");
+  });
+
+  it("should differ in mention (MD is URL-only, MDv2 is link)", () => {
+    expect(fmt.mentionMD(123456, "John")).toBe("tg://user?id=123456");
+    expect(fmt.mentionMDv2(123456, "John")).toBe("[John](tg://user?id=123456)");
+  });
+
+  it("should have different escape functions", () => {
+    const text = "*_[]()~`>#+-=|{}.!";
+    const mdEscaped = fmt.escapeMarkdown(text);
+    const mdv2Escaped = fmt.escapeMarkdownV2(text);
+
+    expect(mdEscaped).not.toBe(mdv2Escaped);
+    expect(mdv2Escaped).toContain("\\~");
+    expect(mdv2Escaped).toContain("\\>");
+    expect(mdv2Escaped).toContain("\\#");
+  });
+});