@mks2508/telegram-message-builder 0.2.0 → 0.3.0

package/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,YAAY,EACV,SAAS,EACT,UAAU,EACV,QAAQ,EACR,eAAe,EACf,WAAW,EACX,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,YAAY,EACV,SAAS,EACT,UAAU,EACV,QAAQ,EACR,eAAe,EACf,WAAW,EACX,eAAe,GAChB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACV,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC"}

package/src/index.ts

@@ -17,6 +17,18 @@ export type {
   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/src/integration.test.ts

@@ -0,0 +1,523 @@
+import { describe, it, expect } from "bun:test";
+import { TelegramMessageBuilder } from "./builder";
+import { TelegramKeyboardBuilder } from "./keyboard";
+import * as fmt from "../src";
+
+describe("Integration Tests", () => {
+  describe("Message + Keyboard Combination", () => {
+    it("should build message with inline keyboard", () => {
+      const message = TelegramMessageBuilder.text()
+        .title("Choose an option")
+        .newline()
+        .line("Options", "Available below", { italic: true })
+        .build();
+
+      const keyboard = TelegramKeyboardBuilder.inline()
+        .urlButton("Visit Website", "https://example.com")
+        .row()
+        .callbackButton("Option 1", "opt_1")
+        .callbackButton("Option 2", "opt_2")
+        .buildMarkup();
+
+      expect(message.text).toContain("<b>Choose an option</b>");
+      expect(message.text).toContain("Options: <i>Available below</i>");
+      expect(keyboard.inline_keyboard).toBeDefined();
+      expect(keyboard.inline_keyboard?.length).toBeGreaterThan(0);
+    });
+
+    it("should build message with reply keyboard", () => {
+      const message = TelegramMessageBuilder.text()
+        .title("Menu")
+        .line("Please select an option", "", {})
+        .build();
+
+      const keyboard = TelegramKeyboardBuilder.reply()
+        .textButton("Option 1")
+        .row()
+        .textButton("Option 2")
+        .textButton("Option 3")
+        .buildReplyMarkup();
+
+      expect(message.text).toContain("<b>Menu</b>");
+      expect(keyboard.keyboard).toBeDefined();
+      expect(keyboard.keyboard?.length).toBe(2);
+      expect(keyboard.keyboard?.[1]?.length).toBe(2);
+    });
+  });
+
+  describe("Complex Real-World Messages", () => {
+    it("should build user profile message (HTML)", () => {
+      const message = TelegramMessageBuilder.text()
+        .title("👤 User Profile")
+        .newline()
+        .section("Personal Information")
+        .line("Name", "John Doe", { bold: true })
+        .line("Age", "30", { code: true })
+        .line("Status", "Active", { italic: true })
+        .line("Level", "Premium", { underline: true })
+        .newline()
+        .section("Statistics")
+        .line("Messages", "1,234")
+        .line("Score", "9,876")
+        .separator()
+        .codeBlock(
+          "const user = {\n  name: 'John Doe',\n  level: 'Premium'\n};",
+          "javascript",
+        )
+        .newline()
+        .listItem("✅ Verified")
+        .listItem("⭐ Premium Member")
+        .listItem("🏆 Top Contributor")
+        .newline()
+        .link("View Full Profile", "https://example.com/user/123")
+        .mention(123456, "John Doe")
+        .build();
+
+      expect(message.text).toContain("<b>👤 User Profile</b>");
+      expect(message.text).toContain("<u>Personal Information</u>");
+      expect(message.text).toContain("Name: <b>John Doe</b>");
+      expect(message.text).toContain("Age: <code>30</code>");
+      expect(message.text).toContain("Status: <i>Active</i>");
+      expect(message.text).toContain("Level: <u>Premium</u>");
+      expect(message.text).toContain("---");
+      expect(message.text).toContain("language-javascript");
+      expect(message.text).toContain("• ✅ Verified");
+      expect(message.text).toContain("View Full Profile");
+      expect(message.text).toContain("tg://user?id=123456");
+      expect(message.parse_mode).toBe("html");
+    });
+
+    it("should build same message in Markdown mode", () => {
+      const message = TelegramMessageBuilder.text()
+        .setParseMode("markdown")
+        .title("👤 User Profile")
+        .newline()
+        .section("Personal Information")
+        .line("Name", "John Doe", { bold: true })
+        .line("Status", "Active", { italic: true })
+        .build();
+
+      expect(message.text).toContain("*👤 User Profile*");
+      expect(message.text).toContain("Name: *John Doe*");
+      expect(message.text).toContain("Status: _Active_");
+      expect(message.parse_mode).toBe("markdown");
+    });
+
+    it("should build same message in MarkdownV2 mode", () => {
+      const message = TelegramMessageBuilder.text()
+        .setParseMode("markdownv2")
+        .title("👤 User Profile")
+        .newline()
+        .section("Personal Information")
+        .line("Name", "John Doe", { bold: true })
+        .line("Status", "Active", { italic: true })
+        .line("Level", "Premium", { underline: true })
+        .build();
+
+      expect(message.text).toContain("*👤 User Profile*");
+      expect(message.text).toContain("Name: *John Doe*");
+      expect(message.text).toContain("Status: _Active_");
+      expect(message.text).toContain("Level: __Premium__");
+      expect(message.parse_mode).toBe("markdownv2");
+    });
+
+    it("should build product listing message", () => {
+      const message = TelegramMessageBuilder.text()
+        .title("🛒 Product List")
+        .newline()
+        .section("Featured Products")
+        .listItem("Product A - $10")
+        .listItem("Product B - $20")
+        .listItem("Product C - $30")
+        .newline()
+        .section("Special Offers")
+        .line("Discount", "20% OFF", { bold: true })
+        .line("Code", "SAVE20", { code: true })
+        .separator()
+        .link("Shop Now", "https://example.com/shop")
+        .hashtag("deals")
+        .hashtag("sale")
+        .setOption("disable_web_page_preview", true)
+        .build();
+
+      expect(message.text).toContain("<b>🛒 Product List</b>");
+      expect(message.text).toContain("• Product A - $10");
+      expect(message.text).toContain("Discount: <b>20% OFF</b>");
+      expect(message.text).toContain("Code: <code>SAVE20</code>");
+      expect(message.text).toContain("Shop Now");
+      expect(message.text).toContain("#deals");
+      expect(message.text).toContain("#sale");
+      expect(message.disable_web_page_preview).toBe(true);
+    });
+
+    it("should build error message", () => {
+      const message = TelegramMessageBuilder.text()
+        .title("❌ Error Occurred")
+        .newline()
+        .line("Code", "ERR_500", { code: true })
+        .line("Message", "Internal server error", { bold: true })
+        .newline()
+        .section("Details")
+        .codeBlock("Error: Database connection failed\nat connect (db.js:42)")
+        .newline()
+        .line("Support", "@support", { italic: true })
+        .mention(123456, "Support Team")
+        .build();
+
+      expect(message.text).toContain("<b>❌ Error Occurred</b>");
+      expect(message.text).toContain("Code: <code>ERR_500</code>");
+      expect(message.text).toContain("Message: <b>Internal server error</b>");
+      expect(message.text).toContain(
+        "<pre><code>Error: Database connection failed",
+      );
+      expect(message.text).toContain("@support");
+      expect(message.text).toContain("tg://user?id=123456");
+    });
+
+    it("should build notification message", () => {
+      const message = TelegramMessageBuilder.text()
+        .title("🔔 New Notification")
+        .newline()
+        .line("Type", "System Update", { bold: true })
+        .line("Time", "2024-01-10 12:00", { code: true })
+        .newline()
+        .section("Message")
+        .text("A new update is available. Please update to the latest version.")
+        .newline()
+        .separator()
+        .link("Update Now", "https://example.com/update")
+        .link("Release Notes", "https://example.com/release-notes")
+        .setOptions({
+          disable_notification: false,
+          protect_content: true,
+        })
+        .build();
+
+      expect(message.text).toContain("<b>🔔 New Notification</b>");
+      expect(message.text).toContain("Type: <b>System Update</b>");
+      expect(message.text).toContain("Time: <code>2024-01-10 12:00</code>");
+      expect(message.text).toContain("A new update is available");
+      expect(message.text).toContain("Update Now");
+      expect(message.text).toContain("Release Notes");
+      expect(message.protect_content).toBe(true);
+      expect(message.disable_notification).toBe(false);
+    });
+  });
+
+  describe("Cross-Mode Message Consistency", () => {
+    it("should produce equivalent messages in all three modes", () => {
+      const htmlMessage = TelegramMessageBuilder.text()
+        .setParseMode("html")
+        .title("Welcome")
+        .line("Status", "Active", { bold: true })
+        .link("Click here", "https://example.com")
+        .build();
+
+      const mdMessage = TelegramMessageBuilder.text()
+        .setParseMode("markdown")
+        .title("Welcome")
+        .line("Status", "Active", { bold: true })
+        .link("Click here", "https://example.com")
+        .build();
+
+      const mdv2Message = TelegramMessageBuilder.text()
+        .setParseMode("markdownv2")
+        .title("Welcome")
+        .line("Status", "Active", { bold: true })
+        .link("Click here", "https://example.com")
+        .build();
+
+      // HTML mode
+      expect(htmlMessage.parse_mode).toBe("html");
+      expect(htmlMessage.text).toContain("<b>Welcome</b>");
+      expect(htmlMessage.text).toContain("Status: <b>Active</b>");
+      expect(htmlMessage.text).toContain(
+        '<a href="https://example.com">Click here</a>',
+      );
+
+      // Markdown mode
+      expect(mdMessage.parse_mode).toBe("markdown");
+      expect(mdMessage.text).toContain("*Welcome*");
+      expect(mdMessage.text).toContain("Status: *Active*");
+      expect(mdMessage.text).toContain("[Click here](https://example.com)");
+
+      // MarkdownV2 mode
+      expect(mdv2Message.parse_mode).toBe("markdownv2");
+      expect(mdv2Message.text).toContain("*Welcome*");
+      expect(mdv2Message.text).toContain("Status: *Active*");
+      expect(mdv2Message.text).toContain("[Click here](https://example.com)");
+    });
+  });
+
+  describe("Formatter Integration", () => {
+    it("should combine fmt helpers with builder", () => {
+      const customPart = `${fmt.bold("Custom")} ${fmt.italic("Part")}`;
+
+      const message = TelegramMessageBuilder.text()
+        .title("Main Title")
+        .newline()
+        .text(customPart)
+        .build();
+
+      expect(message.text).toContain("<b>Main Title</b>");
+      // Note: text() escapes HTML, so the customPart will be escaped
+      expect(message.text).toContain("&lt;b&gt;Custom&lt;/b&gt;");
+    });
+
+    it("should use raw() to preserve formatting in builder", () => {
+      // The title() method wraps its content, so raw() doesn't help here
+      // Instead, use bold() directly on the text without title()
+      const message = TelegramMessageBuilder.text()
+        .text(fmt.raw(fmt.bold("Main")))
+        .build();
+
+      // text() also escapes, so this will escape the bold tags
+      // This is the expected behavior - raw() is for combining formatters, not bypassing escaping in builder methods
+      expect(message.text).toContain("&lt;b&gt;Main&lt;/b&gt;");
+    });
+
+    it("should escape properly in all formatters", () => {
+      const message = TelegramMessageBuilder.text()
+        .title("<script>alert('xss')</script>")
+        .line("Key", "<b>Value</b>", { bold: true })
+        .codeBlock("<code>alert('xss')</code>")
+        .link("Click", "https://example.com?x=1&y=2")
+        .build();
+
+      expect(message.text).toContain("&lt;script&gt;");
+      expect(message.text).toContain("&lt;b&gt;Value&lt;/b&gt;");
+      expect(message.text).toContain("&lt;code&gt;");
+      expect(message.text).toContain("&amp;");
+    });
+  });
+
+  describe("Special Characters and Unicode", () => {
+    it("should handle emoji in all modes", () => {
+      const html = TelegramMessageBuilder.text()
+        .title("🎉 Success!")
+        .listItem("✅ Step 1")
+        .listItem("✅ Step 2")
+        .listItem("🏆 Complete!")
+        .build();
+
+      expect(html.text).toContain("🎉");
+      expect(html.text).toContain("✅");
+      expect(html.text).toContain("🏆");
+    });
+
+    it("should handle special characters in MarkdownV2", () => {
+      const message = TelegramMessageBuilder.text()
+        .setParseMode("markdownv2")
+        .title("Test")
+        .text("Text with * and _ and ~")
+        .build();
+
+      // text() should escape special characters in MDv2 mode
+      expect(message.text).toContain("\\*");
+      expect(message.text).toContain("\\_");
+      expect(message.text).toContain("\\~");
+    });
+
+    it("should handle RTL languages (Arabic, Hebrew)", () => {
+      const message = TelegramMessageBuilder.text()
+        .title("مرحبا")
+        .line("اسم", "محمد", { bold: true })
+        .line("משהו", "משהו", { italic: true })
+        .build();
+
+      expect(message.text).toContain("مرحبا");
+      expect(message.text).toContain("محمد");
+      expect(message.text).toContain("משהו");
+    });
+
+    it("should handle CJK languages (Chinese, Japanese, Korean)", () => {
+      const message = TelegramMessageBuilder.text()
+        .title("标题")
+        .line("名前", "名前", { bold: true })
+        .line("이름", "이름", { code: true })
+        .build();
+
+      expect(message.text).toContain("标题");
+      expect(message.text).toContain("名前");
+      expect(message.text).toContain("이름");
+    });
+  });
+
+  describe("Performance and Edge Cases", () => {
+    it("should handle very long messages", () => {
+      const longText = "a".repeat(4000);
+
+      const message = TelegramMessageBuilder.text()
+        .title("Long Message")
+        .text(longText)
+        .build();
+
+      expect(message.text.length).toBeGreaterThan(4000);
+      expect(message.text).toContain("<b>Long Message</b>");
+      expect(message.text).toContain(longText);
+    });
+
+    it("should handle empty builder", () => {
+      const message = TelegramMessageBuilder.text().build();
+      expect(message.text).toBe("");
+      expect(message.parse_mode).toBe("html");
+    });
+
+    it("should handle message with only newlines", () => {
+      const message = TelegramMessageBuilder.text().newline(5).build();
+
+      expect(message.text).toContain("\n\n");
+    });
+
+    it("should handle multiple consecutive separators", () => {
+      const message = TelegramMessageBuilder.text()
+        .separator()
+        .separator()
+        .separator()
+        .build();
+
+      const count = (message.text.match(/---/g) || []).length;
+      expect(count).toBe(3);
+    });
+
+    it("should handle all formatter types in single message", () => {
+      const message = TelegramMessageBuilder.text()
+        .title("Title")
+        .section("Section")
+        .line("A", "B", { bold: true })
+        .line("C", "D", { italic: true })
+        .line("E", "F", { code: true })
+        .line("G", "H", { underline: true })
+        .codeBlock("code")
+        .listItem("item")
+        .newline()
+        .separator()
+        .text("text")
+        .link("L", "https://example.com")
+        .mention(123, "User")
+        .hashtag("tag")
+        .setOption("opt", 1)
+        .build();
+
+      expect(message.text).toContain("<b>Title</b>");
+      expect(message.text).toContain("<u>Section</u>");
+      expect(message.text).toContain("A: <b>B</b>");
+      expect(message.text).toContain("C: <i>D</i>");
+      expect(message.text).toContain("E: <code>F</code>");
+      expect(message.text).toContain("G: <u>H</u>");
+      expect(message.text).toContain("<pre><code>code</code></pre>");
+      expect(message.text).toContain("• item");
+      expect(message.text).toContain("---");
+      expect(message.text).toContain("L");
+      expect(message.text).toContain("tg://user?id=123");
+      expect(message.text).toContain("#tag");
+      expect(message.opt).toBe(1);
+    });
+  });
+
+  describe("Real-World Use Cases", () => {
+    it("should build bot welcome message", () => {
+      const message = TelegramMessageBuilder.text()
+        .title("🤖 Welcome to ExampleBot")
+        .newline()
+        .section("Available Commands")
+        .listItem("/start - Start the bot")
+        .listItem("/help - Show help")
+        .listItem("/settings - Configure settings")
+        .newline()
+        .section("Quick Links")
+        .link("🌐 Website", "https://example.com")
+        .link("📖 Documentation", "https://docs.example.com")
+        .link("💬 Support", "https://t.me/support")
+        .newline()
+        .text("Use the buttons below or type a command to get started.")
+        .hashtag("ExampleBot")
+        .hashtag("Telegram")
+        .build();
+
+      expect(message.text).toContain("🤖 Welcome to ExampleBot");
+      expect(message.text).toContain("/start");
+      expect(message.text).toContain("Website");
+      expect(message.text).toContain("#ExampleBot");
+    });
+
+    it("should build order confirmation message", () => {
+      const orderId = "ORD-2024-001";
+      const items = "Item 1 x1, Item 2 x2";
+      const total = "$45.00";
+
+      const message = TelegramMessageBuilder.text()
+        .title("📦 Order Confirmation")
+        .newline()
+        .section("Order Details")
+        .line("Order ID", orderId, { code: true })
+        .line("Date", "2024-01-10", { code: true })
+        .newline()
+        .section("Items")
+        .text(items)
+        .newline()
+        .section("Payment")
+        .line("Total", total, { bold: true })
+        .line("Method", "Credit Card", { italic: true })
+        .separator()
+        .text("Thank you for your purchase! 🎉")
+        .newline()
+        .link("Track Order", "https://example.com/track/ORD-2024-001")
+        .mention(123456, "Support Team")
+        .setOptions({
+          disable_web_page_preview: true,
+        })
+        .build();
+
+      expect(message.text).toContain("📦 Order Confirmation");
+      expect(message.text).toContain("Order ID: <code>ORD-2024-001</code>");
+      expect(message.text).toContain("Total: <b>$45.00</b>");
+      expect(message.text).toContain("Thank you for your purchase!");
+      expect(message.text).toContain("Track Order");
+    });
+
+    it("should build analytics report message", () => {
+      const message = TelegramMessageBuilder.text()
+        .title("📊 Weekly Analytics Report")
+        .newline()
+        .section("Overview")
+        .line("Period", "Jan 1 - Jan 7, 2024", { code: true })
+        .line("Total Users", "1,234", { bold: true })
+        .line("Active Users", "987", { bold: true })
+        .line("Growth", "+15.3%", { italic: true })
+        .newline()
+        .section("Top Metrics")
+        .listItem("Messages sent: 45,678")
+        .listItem("Commands used: 12,345")
+        .listItem("Errors: 23")
+        .newline()
+        .codeBlock(
+          `{
+  "users": {
+    "new": 123,
+    "returning": 864,
+    "churned": 12
+  },
+  "engagement": {
+    "avg_session": "5m 32s",
+    "retention": "78.5%"
+  }
+}`,
+          "json",
+        )
+        .newline()
+        .link("View Full Report", "https://analytics.example.com")
+        .hashtag("analytics")
+        .hashtag("report")
+        .build();
+
+      expect(message.text).toContain("📊 Weekly Analytics Report");
+      expect(message.text).toContain("Total Users: <b>1,234</b>");
+      expect(message.text).toContain("Growth: <i>+15.3%</i>");
+      expect(message.text).toContain("Messages sent: 45,678");
+      expect(message.text).toContain("&quot;users&quot;:"); // HTML escaped quotes
+      expect(message.text).toContain("View Full Report");
+      expect(message.text).toContain("#analytics");
+    });
+  });
+});