@shrimp-kit/bridge

Telegram bridge with message routing, notification queue, and night silence mode.

Install

bun add @shrimp-kit/bridge

Features

• Long polling — Receive messages via Telegram Bot API
• Night silence — Queue notifications during night hours, flush in the morning
• Long message splitting — Automatically split messages > 4096 chars
• Message routing — Custom handler for incoming messages

Usage

Basic Setup

import { Logger } from "@shrimp-kit/core";
import { Bridge } from "@shrimp-kit/bridge";

const logger = new Logger({ name: "agent", level: "info" });

const bridge = new Bridge({
  config: {
    botToken: process.env.BOT_TOKEN!,
    chatId: Number(process.env.CHAT_ID!),
    parseMode: "HTML",  // optional
    retries: 3,         // optional
  },
  logger,
  nightHours: ["00:00", "08:00"],
  notifyQueuePath: "./data/notify-queue.json",
  onMessage: async (message) => {
    // Handle incoming Telegram messages
    console.log(`From ${message.from?.firstName}: ${message.text}`);
    return "Got it!"; // Reply (or null to skip)
  },
});

Sending Notifications

// Smart notify — respects night silence
await bridge.notify("Backup completed successfully!", "backup");
// During night hours → queued to notify-queue.json
// During day hours → sent immediately via Telegram

// Morning flush — send all queued notifications
const count = await bridge.flushNotifyQueue();
// → "3 notifications flushed"

Direct Telegram Client

For more control, use the TelegramClient directly:

import { TelegramClient } from "@shrimp-kit/bridge";

const client = new TelegramClient(
  { botToken: "...", chatId: 123456 },
  logger,
);

// Send message
await client.sendMessage(chatId, "Hello!");

// Send long message (auto-splits at 4096 chars)
await client.sendLongMessage(chatId, veryLongText);

// Send file
await client.sendFile(chatId, {
  filePath: "./report.pdf",
  caption: "Daily report",
});

// Get updates (long polling)
const updates = await client.getUpdates(lastUpdateId + 1, 30);

Polling for Messages

// Start long polling loop
await bridge.startPolling();

// Stop polling
bridge.stop();

Configuration

BridgeConfig

| Field | Type | Default | Description | |-------|------|---------|-------------| | botToken | string | — | Telegram Bot API token | | chatId | number | — | Default chat ID for notifications | | groupChatId | number? | — | Optional group chat ID | | parseMode | "HTML" \| "Markdown" \| "MarkdownV2" | — | Message parse mode | | timeout | number? | 30 | Request timeout in seconds | | retries | number? | 0 | Retry count on failure |

BridgeOptions

| Field | Type | Description | |-------|------|-------------| | config | BridgeConfig | Telegram config | | logger | Logger | Logger instance | | notifyQueuePath | string? | Path to night notification queue file | | nightHours | [string, string]? | Night window e.g. ["00:00", "08:00"] | | onMessage | MessageHandler? | Handler for incoming messages | | pollingTimeout | number? | Long polling timeout in seconds |

API Reference

Bridge

| Method | Returns | Description | |--------|---------|-------------| | startPolling() | Promise<void> | Start long polling loop | | stop() | void | Stop polling | | notify(text, source?) | Promise<void> | Send notification (respects night silence) | | flushNotifyQueue() | Promise<number> | Flush queued notifications | | getClient() | TelegramClient | Get underlying Telegram client |

See src/index.ts for all exports.