npm package: @shrimp-kit/bridge
Description: > Telegram bridge with message routing, notification queue, and night silence mode.
Latest version: 0.1.0

# @shrimp-kit/bridge

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

## Install

```bash
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

```typescript
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

```typescript
// 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:

```typescript
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

```typescript
// 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`](./src/index.ts) for all exports.