@mks2508/telegram-message-builder 0.2.0

package/src/keyboard/index.ts

@@ -0,0 +1,286 @@
+/**
+ * @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 class TelegramKeyboardBuilder {
+  private rows: IInlineKeyboardButton[][] | IKeyboardButton[][] = [];
+  private type: "inline" | "reply" | "force" = "inline";
+  private currentRow: IInlineKeyboardButton[] | IKeyboardButton[] = [];
+
+  private constructor(type: "inline" | "reply" | "force") {
+    this.type = type;
+  }
+
+  /**
+   * Create an inline keyboard builder
+   */
+  static inline(): TelegramKeyboardBuilder {
+    return new TelegramKeyboardBuilder("inline");
+  }
+
+  /**
+   * Create a reply keyboard builder
+   */
+  static reply(): TelegramKeyboardBuilder {
+    return new TelegramKeyboardBuilder("reply");
+  }
+
+  /**
+   * Create a force reply builder
+   */
+  static forceReply(): TelegramKeyboardBuilder {
+    return new TelegramKeyboardBuilder("force");
+  }
+
+  /**
+   * Add a URL button (inline only)
+   */
+  urlButton(text: string, url: string): this {
+    if (this.type !== "inline") {
+      throw new Error("urlButton is only available for inline keyboards");
+    }
+    this.currentRow.push({ text, url });
+    return this;
+  }
+
+  /**
+   * Add a callback button (inline only)
+   */
+  callbackButton(text: string, data: string): this {
+    if (this.type !== "inline") {
+      throw new Error("callbackButton is only available for inline keyboards");
+    }
+    this.currentRow.push({ text, callback_data: data });
+    return this;
+  }
+
+  /**
+   * Add a web app button (inline only)
+   */
+  webAppButton(text: string, url: string): this {
+    if (this.type !== "inline") {
+      throw new Error("webAppButton is only available for inline keyboards");
+    }
+    this.currentRow.push({ text, web_app: { url } });
+    return this;
+  }
+
+  /**
+   * Add a login button (inline only)
+   */
+  loginButton(
+    text: string,
+    url: string,
+    options?: {
+      forwardText?: string;
+      botUsername?: string;
+      requestWriteAccess?: boolean;
+    },
+  ): this {
+    if (this.type !== "inline") {
+      throw new Error("loginButton is only available for inline keyboards");
+    }
+    this.currentRow.push({
+      text,
+      login_url: {
+        url,
+        forward_text: options?.forwardText,
+        bot_username: options?.botUsername,
+        request_write_access: options?.requestWriteAccess,
+      },
+    });
+    return this;
+  }
+
+  /**
+   * Add a switch inline query button (inline only)
+   */
+  switchInlineQueryButton(text: string, query: string): this {
+    if (this.type !== "inline") {
+      throw new Error(
+        "switchInlineQueryButton is only available for inline keyboards",
+      );
+    }
+    this.currentRow.push({ text, switch_inline_query: query });
+    return this;
+  }
+
+  /**
+   * Add a switch inline query current chat button (inline only)
+   */
+  switchInlineQueryCurrentChatButton(text: string, query: string): this {
+    if (this.type !== "inline") {
+      throw new Error(
+        "switchInlineQueryCurrentChatButton is only available for inline keyboards",
+      );
+    }
+    this.currentRow.push({ text, switch_inline_query_current_chat: query });
+    return this;
+  }
+
+  /**
+   * Add a callback game button (inline only)
+   */
+  callbackGameButton(text: string, shortName: string): this {
+    if (this.type !== "inline") {
+      throw new Error(
+        "callbackGameButton is only available for inline keyboards",
+      );
+    }
+    this.currentRow.push({ text, callback_game: shortName });
+    return this;
+  }
+
+  /**
+   * Add a pay button (inline only)
+   */
+  payButton(text: string): this {
+    if (this.type !== "inline") {
+      throw new Error("payButton is only available for inline keyboards");
+    }
+    this.currentRow.push({ text, pay: text });
+    return this;
+  }
+
+  /**
+   * Add a text button (reply keyboard only)
+   */
+  textButton(text: string): this {
+    if (this.type !== "reply") {
+      throw new Error("textButton is only available for reply keyboards");
+    }
+    this.currentRow.push({ text });
+    return this;
+  }
+
+  /**
+   * Add a request contact button (reply keyboard only)
+   */
+  requestContactButton(text: string): this {
+    if (this.type !== "reply") {
+      throw new Error(
+        "requestContactButton is only available for reply keyboards",
+      );
+    }
+    this.currentRow.push({ text, request_contact: true });
+    return this;
+  }
+
+  /**
+   * Add a request location button (reply keyboard only)
+   */
+  requestLocationButton(text: string): this {
+    if (this.type !== "reply") {
+      throw new Error(
+        "requestLocationButton is only available for reply keyboards",
+      );
+    }
+    this.currentRow.push({ text, request_location: true });
+    return this;
+  }
+
+  /**
+   * Add a request poll button (reply keyboard only)
+   */
+  requestPollButton(text: string, pollType: string): this {
+    if (this.type !== "reply") {
+      throw new Error(
+        "requestPollButton is only available for reply keyboards",
+      );
+    }
+    this.currentRow.push({ text, request_poll: { type: pollType } });
+    return this;
+  }
+
+  /**
+   * Add a custom button to current row
+   */
+  button(button: IInlineKeyboardButton | IKeyboardButton): this {
+    this.currentRow.push(button);
+    return this;
+  }
+
+  /**
+   * Finish current row and start a new one
+   */
+  row(): this {
+    if (this.currentRow.length > 0) {
+      this.rows.push([...this.currentRow]);
+      this.currentRow = [];
+    }
+    return this;
+  }
+
+  /**
+   * Build inline keyboard markup
+   */
+  buildMarkup(): IInlineKeyboardMarkup {
+    // Add last row if not empty
+    if (this.currentRow.length > 0) {
+      this.rows.push([...this.currentRow]);
+    }
+
+    return { inline_keyboard: this.rows as IInlineKeyboardButton[][] };
+  }
+
+  /**
+   * Build reply keyboard markup
+   */
+  buildReplyMarkup(): IReplyKeyboardMarkup {
+    // Add last row if not empty
+    if (this.currentRow.length > 0) {
+      this.rows.push([...this.currentRow]);
+    }
+
+    return {
+      keyboard: this.rows as IKeyboardButton[][],
+      resize_keyboard: true,
+      one_time_keyboard: false,
+      selective: false,
+    };
+  }
+
+  /**
+   * Build force reply markup
+   */
+  buildForceReplyMarkup(): IForceReplyMarkup {
+    return { force_reply: true };
+  }
+
+  /**
+   * Build markup based on keyboard type
+   */
+  build(): IInlineKeyboardMarkup | IReplyKeyboardMarkup | IForceReplyMarkup {
+    switch (this.type) {
+      case "inline":
+        return this.buildMarkup();
+      case "reply":
+        return this.buildReplyMarkup();
+      case "force":
+        return this.buildForceReplyMarkup();
+    }
+  }
+}

package/src/keyboard.test.ts

@@ -0,0 +1,217 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { TelegramKeyboardBuilder } from "../src";
+
+describe("TelegramKeyboardBuilder", () => {
+  describe("Inline Keyboard", () => {
+    let builder: TelegramKeyboardBuilder;
+
+    beforeEach(() => {
+      builder = TelegramKeyboardBuilder.inline();
+    });
+
+    it("should create empty inline keyboard", () => {
+      const markup = builder.buildMarkup();
+      expect(markup.inline_keyboard).toEqual([]);
+    });
+
+    it("should add URL button", () => {
+      builder.urlButton("Google", "https://google.com");
+      const markup = builder.buildMarkup();
+      expect(markup.inline_keyboard).toEqual([
+        [{ text: "Google", url: "https://google.com" }],
+      ]);
+    });
+
+    it("should add callback button", () => {
+      builder.callbackButton("Click me", "action_1");
+      const markup = builder.buildMarkup();
+      expect(markup.inline_keyboard).toEqual([
+        [{ text: "Click me", callback_data: "action_1" }],
+      ]);
+    });
+
+    it("should add multiple buttons in one row", () => {
+      builder.urlButton("Google", "https://google.com");
+      builder.callbackButton("Click", "action");
+      const markup = builder.buildMarkup();
+      expect(markup.inline_keyboard).toHaveLength(1);
+      expect(markup.inline_keyboard[0]).toHaveLength(2);
+    });
+
+    it("should create multiple rows", () => {
+      builder.urlButton("Button 1", "https://example.com");
+      builder.row();
+      builder.callbackButton("Button 2", "action");
+      builder.row();
+      builder.urlButton("Button 3", "https://example.com");
+      const markup = builder.buildMarkup();
+      expect(markup.inline_keyboard).toHaveLength(3);
+      expect(markup.inline_keyboard[0]).toHaveLength(1);
+      expect(markup.inline_keyboard[1]).toHaveLength(1);
+      expect(markup.inline_keyboard[2]).toHaveLength(1);
+    });
+
+    it("should add web app button", () => {
+      builder.webAppButton("Open App", "https://example.com/app");
+      const markup = builder.buildMarkup();
+      expect(markup.inline_keyboard[0][0]).toMatchObject({
+        text: "Open App",
+        web_app: { url: "https://example.com/app" },
+      });
+    });
+
+    it("should add login button", () => {
+      builder.loginButton("Login", "https://example.com/login");
+      const markup = builder.buildMarkup();
+      expect(markup.inline_keyboard[0][0]).toMatchObject({
+        text: "Login",
+        login_url: { url: "https://example.com/login" },
+      });
+    });
+
+    it("should add switch inline query button", () => {
+      builder.switchInlineQueryButton("Search", "query");
+      const markup = builder.buildMarkup();
+      expect(markup.inline_keyboard[0][0]).toMatchObject({
+        text: "Search",
+        switch_inline_query: "query",
+      });
+    });
+
+    it("should add switch inline query current chat button", () => {
+      builder.switchInlineQueryCurrentChatButton("Search", "query");
+      const markup = builder.buildMarkup();
+      expect(markup.inline_keyboard[0][0]).toMatchObject({
+        text: "Search",
+        switch_inline_query_current_chat: "query",
+      });
+    });
+
+    it("should add callback game button", () => {
+      builder.callbackGameButton("Play", "my_game");
+      const markup = builder.buildMarkup();
+      expect(markup.inline_keyboard[0][0]).toMatchObject({
+        text: "Play",
+        callback_game: "my_game",
+      });
+    });
+
+    it("should add pay button", () => {
+      builder.payButton("Pay $10");
+      const markup = builder.buildMarkup();
+      expect(markup.inline_keyboard[0][0]).toMatchObject({
+        text: "Pay $10",
+        pay: "Pay $10",
+      });
+    });
+
+    it("should throw error when using reply keyboard methods on inline", () => {
+      expect(() => builder.textButton("Button")).toThrow();
+      expect(() => builder.requestContactButton("Contact")).toThrow();
+    });
+  });
+
+  describe("Reply Keyboard", () => {
+    let builder: TelegramKeyboardBuilder;
+
+    beforeEach(() => {
+      builder = TelegramKeyboardBuilder.reply();
+    });
+
+    it("should create empty reply keyboard", () => {
+      const markup = builder.buildReplyMarkup();
+      expect(markup.keyboard).toEqual([]);
+    });
+
+    it("should add text button", () => {
+      builder.textButton("Option 1");
+      const markup = builder.buildReplyMarkup();
+      expect(markup.keyboard).toEqual([[{ text: "Option 1" }]]);
+    });
+
+    it("should add request contact button", () => {
+      builder.requestContactButton("Share Contact");
+      const markup = builder.buildReplyMarkup();
+      expect(markup.keyboard).toEqual([
+        [{ text: "Share Contact", request_contact: true }],
+      ]);
+    });
+
+    it("should add request location button", () => {
+      builder.requestLocationButton("Share Location");
+      const markup = builder.buildReplyMarkup();
+      expect(markup.keyboard).toEqual([
+        [{ text: "Share Location", request_location: true }],
+      ]);
+    });
+
+    it("should add request poll button", () => {
+      builder.requestPollButton("Create Poll", "regular");
+      const markup = builder.buildReplyMarkup();
+      expect(markup.keyboard).toEqual([
+        [{ text: "Create Poll", request_poll: { type: "regular" } }],
+      ]);
+    });
+
+    it("should create multiple rows", () => {
+      builder.textButton("Button 1");
+      builder.row();
+      builder.textButton("Button 2");
+      builder.row();
+      builder.textButton("Button 3");
+      const markup = builder.buildReplyMarkup();
+      expect(markup.keyboard).toHaveLength(3);
+      expect(markup.keyboard[0]).toHaveLength(1);
+      expect(markup.keyboard[1]).toHaveLength(1);
+      expect(markup.keyboard[2]).toHaveLength(1);
+    });
+
+    it("should throw error when using inline keyboard methods on reply", () => {
+      expect(() => builder.urlButton("Google", "https://google.com")).toThrow();
+      expect(() => builder.callbackButton("Click", "action")).toThrow();
+    });
+  });
+
+  describe("Force Reply", () => {
+    it("should create force reply markup", () => {
+      const builder = TelegramKeyboardBuilder.forceReply();
+      const markup = builder.buildForceReplyMarkup();
+      expect(markup).toMatchObject({ force_reply: true });
+    });
+  });
+
+  describe("Combined Example", () => {
+    it("should build a complete inline keyboard", () => {
+      const markup = TelegramKeyboardBuilder.inline()
+        .urlButton("Google", "https://google.com")
+        .urlButton("GitHub", "https://github.com")
+        .row()
+        .callbackButton("✅ Yes", "yes")
+        .callbackButton("❌ No", "no")
+        .row()
+        .callbackButton("🔄 Refresh", "refresh")
+        .buildMarkup();
+
+      expect(markup.inline_keyboard).toHaveLength(3);
+      expect(markup.inline_keyboard[0]).toHaveLength(2);
+      expect(markup.inline_keyboard[1]).toHaveLength(2);
+      expect(markup.inline_keyboard[2]).toHaveLength(1);
+    });
+
+    it("should build a complete reply keyboard", () => {
+      const markup = TelegramKeyboardBuilder.reply()
+        .textButton("Option 1")
+        .textButton("Option 2")
+        .row()
+        .requestContactButton("Share Contact")
+        .row()
+        .requestLocationButton("Share Location")
+        .buildReplyMarkup();
+
+      expect(markup.keyboard).toHaveLength(3);
+      expect(markup.keyboard[0]).toHaveLength(2);
+      expect(markup.keyboard[1]).toHaveLength(1);
+      expect(markup.keyboard[2]).toHaveLength(1);
+    });
+  });
+});

package/src/types/constants.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 = "!";
+//# sourceMappingURL=constants.d.ts.map

package/src/types/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;GAEG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC"}

package/src/types/constants.ts

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

package/src/types/core.types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @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;
+}
+//# sourceMappingURL=core.types.d.ts.map

package/src/types/core.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.types.d.ts","sourceRoot":"","sources":["core.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,YAAY,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,qBAAqB;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uBAAuB;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,iCAAiC;IACjC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2BAA2B;IAC3B,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,8BAA8B;IAC9B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,wBAAwB;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,QAAS,SAAQ,UAAU;IAC1C,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mBAAmB;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,UAAU,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IACnC,8CAA8C;IAC9C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,+BAA+B;IAC/B,wBAAwB,CAAC,EAAE,OAAO,CAAC;IACnC,2BAA2B;IAC3B,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,sCAAsC;IACtC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gCAAgC;IAChC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,UAAU,EAAE,SAAS,CAAC;IACtB,0BAA0B;IAC1B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd"}

package/src/types/core.types.ts

@@ -0,0 +1,80 @@
+/**
+ * @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/src/types/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./core.types";
+export * from "./constants";
+export * from "./keyboard.types";
+//# sourceMappingURL=index.d.ts.map

package/src/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC"}