feat: add @chat-adapter/telegram package

packages/adapter-shared/src/card-utils.ts

@@ -11,7 +11,7 @@ import { convertEmojiPlaceholders } from "chat";
 /**
  * Supported platform names for adapter utilities.
  */
-export type PlatformName = "slack" | "gchat" | "teams" | "discord";
+export type PlatformName = "slack" | "gchat" | "teams" | "discord" | "telegram";
 
 /**
  * Button style mappings per platform.
@@ -27,6 +27,7 @@ export const BUTTON_STYLE_MAPPINGS: Record<
   gchat: { primary: "primary", danger: "danger" }, // Colors handled via buttonColor
   teams: { primary: "positive", danger: "destructive" },
   discord: { primary: "primary", danger: "danger" },
+  telegram: { primary: "primary", danger: "danger" },
 };
 
 /**

packages/adapter-telegram/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@chat-adapter/telegram",
+  "version": "0.0.0",
+  "description": "Telegram adapter for chat",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@chat-adapter/shared": "workspace:*",
+    "chat": "workspace:*",
+    "grammy": "^1.35.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vercel/chat.git",
+    "directory": "packages/adapter-telegram"
+  },
+  "homepage": "https://github.com/vercel/chat#readme",
+  "bugs": {
+    "url": "https://github.com/vercel/chat/issues"
+  },
+  "keywords": [
+    "chat",
+    "telegram",
+    "bot",
+    "adapter"
+  ],
+  "license": "MIT"
+}

packages/adapter-telegram/src/cards.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Tests for the Telegram card converter.
+ */
+
+import type { CardElement } from "chat";
+import { describe, expect, it } from "vitest";
+import { cardToFallbackText, cardToTelegram } from "./cards";
+
+describe("cardToTelegram", () => {
+  it("should convert card with title", () => {
+    const card: CardElement = {
+      type: "card",
+      title: "My Card",
+      children: [],
+    };
+
+    const result = cardToTelegram(card);
+    expect(result.text).toContain("My Card");
+  });
+
+  it("should convert card with subtitle", () => {
+    const card: CardElement = {
+      type: "card",
+      title: "Title",
+      subtitle: "Subtitle text",
+      children: [],
+    };
+
+    const result = cardToTelegram(card);
+    expect(result.text).toContain("Subtitle text");
+  });
+
+  it("should convert text children", () => {
+    const card: CardElement = {
+      type: "card",
+      children: [{ type: "text", content: "Hello world" }],
+    };
+
+    const result = cardToTelegram(card);
+    expect(result.text).toContain("Hello world");
+  });
+
+  it("should convert fields children", () => {
+    const card: CardElement = {
+      type: "card",
+      children: [
+        {
+          type: "fields",
+          children: [
+            { type: "field", label: "Name", value: "John" },
+            { type: "field", label: "Age", value: "30" },
+          ],
+        },
+      ],
+    };
+
+    const result = cardToTelegram(card);
+    expect(result.text).toContain("Name");
+    expect(result.text).toContain("John");
+    expect(result.text).toContain("Age");
+    expect(result.text).toContain("30");
+  });
+
+  it("should convert button actions to inline keyboard", () => {
+    const card: CardElement = {
+      type: "card",
+      children: [
+        {
+          type: "actions",
+          children: [
+            { type: "button", id: "btn-1", label: "Click me", value: "val1" },
+            {
+              type: "button",
+              id: "btn-2",
+              label: "Delete",
+              style: "danger",
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = cardToTelegram(card);
+    expect(result.reply_markup).toBeDefined();
+    expect(result.reply_markup?.inline_keyboard).toHaveLength(1);
+    expect(result.reply_markup?.inline_keyboard[0]).toHaveLength(2);
+    expect(result.reply_markup?.inline_keyboard[0]?.[0]).toEqual({
+      text: "Click me",
+      callback_data: "btn-1:val1",
+    });
+    expect(result.reply_markup?.inline_keyboard[0]?.[1]).toEqual({
+      text: "Delete",
+      callback_data: "btn-2",
+    });
+  });
+
+  it("should convert link buttons with URL", () => {
+    const card: CardElement = {
+      type: "card",
+      children: [
+        {
+          type: "actions",
+          children: [
+            {
+              type: "link-button",
+              label: "Visit",
+              url: "https://example.com",
+            },
+          ],
+        },
+      ],
+    };
+
+    const result = cardToTelegram(card);
+    expect(result.reply_markup?.inline_keyboard[0]?.[0]).toEqual({
+      text: "Visit",
+      url: "https://example.com",
+    });
+  });
+
+  it("should not include reply_markup when no actions", () => {
+    const card: CardElement = {
+      type: "card",
+      title: "No buttons",
+      children: [{ type: "text", content: "Just text" }],
+    };
+
+    const result = cardToTelegram(card);
+    expect(result.reply_markup).toBeUndefined();
+  });
+
+  it("should handle divider", () => {
+    const card: CardElement = {
+      type: "card",
+      children: [
+        { type: "text", content: "Before" },
+        { type: "divider" },
+        { type: "text", content: "After" },
+      ],
+    };
+
+    const result = cardToTelegram(card);
+    expect(result.text).toContain("Before");
+    expect(result.text).toContain("After");
+    expect(result.text).toContain("\\-\\-\\-");
+  });
+});
+
+describe("cardToFallbackText", () => {
+  it("should generate fallback text from card", () => {
+    const card: CardElement = {
+      type: "card",
+      title: "Alert",
+      children: [{ type: "text", content: "Something happened" }],
+    };
+
+    const result = cardToFallbackText(card);
+    expect(result).toContain("Alert");
+    expect(result).toContain("Something happened");
+  });
+});

packages/adapter-telegram/src/cards.ts

@@ -0,0 +1,153 @@
+/**
+ * Telegram inline keyboard converter for cross-platform cards.
+ *
+ * Converts CardElement to Telegram message text + inline keyboard markup.
+ * Telegram doesn't have rich cards like Slack Block Kit, so we render
+ * card content as formatted text with inline keyboard buttons for actions.
+ *
+ * @see https://core.telegram.org/bots/api#inlinekeyboardmarkup
+ */
+
+import { cardToFallbackText as sharedCardToFallbackText } from "@chat-adapter/shared";
+import type {
+  ActionsElement,
+  ButtonElement,
+  CardChild,
+  CardElement,
+  LinkButtonElement,
+} from "chat";
+import type { InlineKeyboardButton, InlineKeyboardMarkup } from "grammy/types";
+import { escapeMarkdownV2 } from "./markdown";
+
+/** Result of converting a card to Telegram format */
+export interface TelegramCardResult {
+  /** Inline keyboard markup for buttons */
+  reply_markup?: InlineKeyboardMarkup;
+  /** Formatted text content */
+  text: string;
+}
+
+/**
+ * Convert a CardElement to Telegram format (text + inline keyboard).
+ */
+export function cardToTelegram(card: CardElement): TelegramCardResult {
+  const textParts: string[] = [];
+  const keyboardRows: InlineKeyboardButton[][] = [];
+
+  if (card.title) {
+    textParts.push(`*${escapeMarkdownV2(card.title)}*`);
+  }
+
+  if (card.subtitle) {
+    textParts.push(escapeMarkdownV2(card.subtitle));
+  }
+
+  for (const child of card.children) {
+    const { text, buttons } = convertChild(child);
+    if (text) {
+      textParts.push(text);
+    }
+    if (buttons.length > 0) {
+      keyboardRows.push(buttons);
+    }
+  }
+
+  const result: TelegramCardResult = {
+    text: textParts.join("\n\n"),
+  };
+
+  if (keyboardRows.length > 0) {
+    result.reply_markup = {
+      inline_keyboard: keyboardRows,
+    };
+  }
+
+  return result;
+}
+
+function convertChild(child: CardChild): {
+  text: string;
+  buttons: InlineKeyboardButton[];
+} {
+  switch (child.type) {
+    case "text":
+      return { text: escapeMarkdownV2(child.content), buttons: [] };
+    case "fields":
+      return {
+        text: child.children
+          .map(
+            (f) =>
+              `*${escapeMarkdownV2(f.label)}*: ${escapeMarkdownV2(f.value)}`
+          )
+          .join("\n"),
+        buttons: [],
+      };
+    case "actions":
+      return { text: "", buttons: convertActions(child) };
+    case "section":
+      return convertSection(child);
+    case "divider":
+      return { text: escapeMarkdownV2("---"), buttons: [] };
+    case "image":
+      return {
+        text: child.alt
+          ? `[${escapeMarkdownV2(child.alt)}](${escapeMarkdownV2(child.url)})`
+          : escapeMarkdownV2(child.url),
+        buttons: [],
+      };
+    default:
+      return { text: "", buttons: [] };
+  }
+}
+
+function convertActions(element: ActionsElement): InlineKeyboardButton[] {
+  return element.children.map((child) => {
+    if (child.type === "link-button") {
+      return convertLinkButton(child);
+    }
+    return convertButton(child as ButtonElement);
+  });
+}
+
+function convertButton(button: ButtonElement): InlineKeyboardButton {
+  return {
+    text: button.label,
+    callback_data: button.value ? `${button.id}:${button.value}` : button.id,
+  };
+}
+
+function convertLinkButton(button: LinkButtonElement): InlineKeyboardButton {
+  return {
+    text: button.label,
+    url: button.url,
+  };
+}
+
+function convertSection(child: CardChild & { type: "section" }): {
+  text: string;
+  buttons: InlineKeyboardButton[];
+} {
+  const textParts: string[] = [];
+  const allButtons: InlineKeyboardButton[] = [];
+
+  for (const sectionChild of child.children) {
+    const { text, buttons } = convertChild(sectionChild);
+    if (text) {
+      textParts.push(text);
+    }
+    allButtons.push(...buttons);
+  }
+
+  return { text: textParts.join("\n"), buttons: allButtons };
+}
+
+/**
+ * Generate fallback text from a card element.
+ * Used when inline keyboards aren't supported or for notifications.
+ */
+export function cardToFallbackText(card: CardElement): string {
+  return sharedCardToFallbackText(card, {
+    boldFormat: "*",
+    lineBreak: "\n",
+  });
+}