@checkstack/notification-telegram-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# @checkstack/notification-telegram-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/notification-backend@0.0.2
+
+## 0.1.2
+
+### Patch Changes
+
+- a65e002: Add compile-time type safety for Lucide icon names
+
+  - Add `LucideIconName` type and `lucideIconSchema` Zod schema to `@checkstack/common`
+  - Update backend interfaces (`AuthStrategy`, `NotificationStrategy`, `IntegrationProvider`, `CommandDefinition`) to use `LucideIconName`
+  - Update RPC contracts to use `lucideIconSchema` for proper type inference across RPC boundaries
+  - Simplify `SocialProviderButton` to use `DynamicIcon` directly (removes 30+ lines of pascalCase conversion)
+  - Replace static `iconMap` in `SearchDialog` with `DynamicIcon` for dynamic icon rendering
+  - Add fallback handling in `DynamicIcon` when icon name isn't found
+  - Fix legacy kebab-case icon names to PascalCase: `mail`→`Mail`, `send`→`Send`, `github`→`Github`, `key-round`→`KeyRound`, `network`→`Network`, `AlertCircle`→`CircleAlert`
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/notification-backend@0.1.2
+  - @checkstack/common@0.2.0
+
+## 0.1.1
+
+### Patch Changes
+
+- @checkstack/notification-backend@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- b354ab3: # Strategy Instructions Support & Telegram Notification Plugin
+
+  ## Strategy Instructions Interface
+
+  Added `adminInstructions` and `userInstructions` optional fields to the `NotificationStrategy` interface. These allow strategies to export markdown-formatted setup guides that are displayed in the configuration UI:
+
+  - **`adminInstructions`**: Shown when admins configure platform-wide strategy settings (e.g., how to create API keys)
+  - **`userInstructions`**: Shown when users configure their personal settings (e.g., how to link their account)
+
+  ### Updated Components
+
+  - `StrategyConfigCard` now accepts an `instructions` prop and renders it before config sections
+  - `StrategyCard` passes `adminInstructions` to `StrategyConfigCard`
+  - `UserChannelCard` renders `userInstructions` when users need to connect
+
+  ## New Telegram Notification Plugin
+
+  Added `@checkstack/notification-telegram-backend` plugin for sending notifications via Telegram:
+
+  - Uses [grammY](https://grammy.dev/) framework for Telegram Bot API integration
+  - Sends messages with MarkdownV2 formatting and inline keyboard buttons for actions
+  - Includes comprehensive admin instructions for bot setup via @BotFather
+  - Includes user instructions for account linking
+
+  ### Configuration
+
+  Admins need to configure a Telegram Bot Token obtained from @BotFather.
+
+  ### User Linking
+
+  The strategy uses `contactResolution: { type: "custom" }` for Telegram Login Widget integration. Full frontend integration for the Login Widget is pending future work.
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/notification-backend@0.1.0

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@checkstack/notification-telegram-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./plugin-metadata": "./src/plugin-metadata.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/notification-backend": "workspace:*",
+    "grammy": "^1.35.0",
+    "telegramify-markdown": "^1.3.2",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "workspace:*",
+    "typescript": "^5.7.2"
+  }
+}

package/src/index.ts

@@ -0,0 +1,216 @@
+import { z } from "zod";
+import { Bot } from "grammy";
+import {
+  createBackendPlugin,
+  configString,
+  Versioned,
+  type NotificationStrategy,
+  type NotificationSendContext,
+  type NotificationDeliveryResult,
+} from "@checkstack/backend-api";
+import { notificationStrategyExtensionPoint } from "@checkstack/notification-backend";
+import { pluginMetadata } from "./plugin-metadata";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Configuration Schema
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Admin configuration for Telegram strategy.
+ */
+const telegramConfigSchemaV1 = z.object({
+  botToken: configString({ "x-secret": true }).describe(
+    "Telegram Bot API Token from @BotFather"
+  ),
+});
+
+type TelegramConfig = z.infer<typeof telegramConfigSchemaV1>;
+
+/**
+ * User configuration for Telegram - users provide their own chat ID.
+ */
+const telegramUserConfigSchema = z.object({
+  chatId: z.string().describe("Your Telegram Chat ID"),
+});
+
+type TelegramUserConfig = z.infer<typeof telegramUserConfigSchema>;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Instructions
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const adminInstructions = `
+## Setup a Telegram Bot
+
+1. Open [@BotFather](https://t.me/BotFather) in Telegram
+2. Send \`/newbot\` and follow the prompts to create your bot
+3. Copy the **Bot Token** (format: \`123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11\`)
+4. Send \`/setdomain\` to BotFather and set your domain (e.g., \`yourdomain.com\`)
+
+> **Note**: The domain must match where Checkstack is hosted for the Login Widget to work.
+`.trim();
+
+const userInstructions = `
+## Get Your Telegram Chat ID
+
+1. Start a chat with your organization's notification bot
+2. Send any message to the bot
+3. Open [@userinfobot](https://t.me/userinfobot) and send \`/start\` to get your Chat ID
+4. Enter your Chat ID in the field above and save
+
+> **Note**: Make sure you've messaged the notification bot before sending a notification, or the bot won't be able to reach you.
+`.trim();
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Telegram Strategy Implementation
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const telegramifyMarkdown = require("telegramify-markdown") as (
+  markdown: string,
+  unsupportedTagsStrategy?: "escape" | "remove" | "keep"
+) => string;
+
+/**
+ * Telegram notification strategy using grammY.
+ */
+const telegramStrategy: NotificationStrategy<
+  TelegramConfig,
+  TelegramUserConfig
+> = {
+  id: "telegram",
+  displayName: "Telegram",
+  description: "Send notifications via Telegram bot messages",
+  icon: "Send",
+
+  config: new Versioned({
+    version: 1,
+    schema: telegramConfigSchemaV1,
+  }),
+
+  // User-config resolution - users enter their chat ID manually
+  contactResolution: { type: "user-config", field: "chatId" },
+
+  userConfig: new Versioned({
+    version: 1,
+    schema: telegramUserConfigSchema,
+  }),
+
+  adminInstructions,
+  userInstructions,
+
+  async send(
+    context: NotificationSendContext<TelegramConfig, TelegramUserConfig>
+  ): Promise<NotificationDeliveryResult> {
+    const { userConfig, notification, strategyConfig } = context;
+
+    if (!strategyConfig.botToken) {
+      return {
+        success: false,
+        error: "Telegram bot token not configured",
+      };
+    }
+
+    if (!userConfig?.chatId) {
+      return {
+        success: false,
+        error: "User has not configured their Telegram chat ID",
+      };
+    }
+
+    try {
+      // Create bot instance
+      const bot = new Bot(strategyConfig.botToken);
+
+      // Build message body using telegramify-markdown for proper escaping and conversion
+      let messageBody = "";
+      if (notification.body) {
+        messageBody = telegramifyMarkdown(notification.body, "escape");
+      }
+
+      // Build title (bold) with proper escaping
+      const messageTitle = telegramifyMarkdown(
+        `**${notification.title}**`,
+        "escape"
+      );
+
+      // Add importance indicator
+      const importanceEmoji = {
+        info: "ℹ️",
+        warning: "⚠️",
+        critical: "🚨",
+      };
+      let messageText = `${
+        importanceEmoji[notification.importance]
+      } ${messageTitle}`;
+      if (messageBody) {
+        messageText += `\n\n${messageBody}`;
+      }
+
+      // Build inline keyboard for action button
+      const actionUrl = notification.action?.url;
+
+      // Don't show action button for localhost URLs (Telegram rejects them)
+      // Instead, add as inline link in the message
+      const isLocalhost =
+        actionUrl?.includes("localhost") || actionUrl?.includes("127.0.0.1");
+
+      if (notification.action && actionUrl && isLocalhost) {
+        // Add action as plain text (Telegram won't make localhost links clickable anyway)
+        // This makes it easier to copy the URL for debugging
+        const plainTextAction = `📎 ${notification.action.label}:\n${actionUrl}\n\n_Note: Telegram blocks localhost URLs, so no inline button is shown._`;
+        messageText += `\n\n${telegramifyMarkdown(plainTextAction, "escape")}`;
+      }
+
+      const inlineKeyboard =
+        notification.action && actionUrl && !isLocalhost
+          ? {
+              inline_keyboard: [
+                [
+                  {
+                    text: notification.action.label,
+                    url: actionUrl,
+                  },
+                ],
+              ],
+            }
+          : undefined;
+
+      // Send the message
+      const result = await bot.api.sendMessage(userConfig.chatId, messageText, {
+        parse_mode: "MarkdownV2",
+        reply_markup: inlineKeyboard,
+      });
+
+      return {
+        success: true,
+        externalId: String(result.message_id),
+      };
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : "Unknown Telegram API error";
+      return {
+        success: false,
+        error: `Failed to send Telegram message: ${message}`,
+      };
+    }
+  },
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Plugin Definition
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    // Get the notification strategy extension point
+    const extensionPoint = env.getExtensionPoint(
+      notificationStrategyExtensionPoint
+    );
+
+    // Register the Telegram strategy with our plugin metadata
+    extensionPoint.addStrategy(telegramStrategy, pluginMetadata);
+  },
+});

package/src/plugin-metadata.ts

@@ -0,0 +1,5 @@
+import type { PluginMetadata } from "@checkstack/common";
+
+export const pluginMetadata: PluginMetadata = {
+  pluginId: "notification-telegram",
+};

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json"
+}