Initial Commit

openspec/changes/enterprise-telegram-client/proposal.md

@@ -0,0 +1,164 @@
+# OpenSpec Change: enterprise-telegram-client
+
+- **Change ID**: enterprise-telegram-client
+- **Package**: `@suaveplan/telegram-client`
+- **Category**: universal
+- **Target path**: `universal/social/telegram-client`
+- **Status**: IN PROGRESS
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/telegram-client.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/telegram-client` on the genesis branch from scratch at enterprise quality. The package provides a generic Telegram Bot API client: `sendMessage`, `sendPhoto`, `sendDocument`, `sendAudio`, `sendVideo`, `editMessageText`, `deleteMessage`, `answerCallbackQuery`, `answerInlineQuery`, `setWebhook`/`deleteWebhook`, `getUpdates` long-poll loop, inline keyboard builder, reply keyboard builder, and a `TelegramBot` facade. Injectable fetch; no `node-telegram-bot-api` dependency. Genesis adds structured errors, Zod schemas, OTel instrumentation, retry with circuit breaker, and `AbortSignal` cancellation.
+
+---
+
+## Current-state audit (genesis)
+
+The package does not exist on genesis yet — this is a fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `TelegramError`; `TELEGRAM.*` error codes |
+| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock` |
+| `@suaveplan/retry` (`workspace:^`) | Retry + circuit breaker for API calls |
+| `zod` (`catalog:forms`) | Schema validation |
+| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
+
+Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check` (all `catalog:testing`).
+
+---
+
+## Public API surface
+
+### `TelegramBot`
+
+```ts
+class TelegramBot {
+  constructor(options: TelegramBotOptions)
+
+  // Messaging
+  sendMessage(chatId: ChatId, text: string, options?: SendMessageOptions): Promise<TelegramMessage>
+  sendPhoto(chatId: ChatId, photo: string | Uint8Array, options?: SendMediaOptions): Promise<TelegramMessage>
+  sendDocument(chatId: ChatId, document: string | Uint8Array, options?: SendMediaOptions): Promise<TelegramMessage>
+  editMessageText(chatId: ChatId, messageId: number, text: string, options?: EditOptions): Promise<TelegramMessage>
+  deleteMessage(chatId: ChatId, messageId: number): Promise<void>
+  forwardMessage(toChatId: ChatId, fromChatId: ChatId, messageId: number): Promise<TelegramMessage>
+
+  // Callbacks and inline
+  answerCallbackQuery(callbackQueryId: string, options?: AnswerCallbackOptions): Promise<void>
+  answerInlineQuery(inlineQueryId: string, results: InlineQueryResult[]): Promise<void>
+
+  // Webhooks and polling
+  setWebhook(url: string, options?: WebhookOptions): Promise<void>
+  deleteWebhook(): Promise<void>
+  getUpdates(options?: GetUpdatesOptions): AsyncGenerator<TelegramUpdate>
+
+  // Bot info
+  getMe(): Promise<TelegramUser>
+}
+
+type ChatId = number | string
+
+interface TelegramBotOptions {
+  token: string
+  retryOptions?: RetryOptions
+  fetch?: typeof globalThis.fetch
+  clock?: Clock
+  logger?: LoggerLike
+}
+```
+
+### Keyboard builders
+
+```ts
+function inlineKeyboard(rows: InlineKeyboardButton[][]): InlineKeyboardMarkup
+function replyKeyboard(rows: KeyboardButton[][], options?: ReplyKeyboardOptions): ReplyKeyboardMarkup
+function removeKeyboard(): ReplyKeyboardRemove
+```
+
+### Error codes
+
+```ts
+type TelegramErrorCode =
+  | 'TELEGRAM_AUTH_FAILED'
+  | 'TELEGRAM_API_ERROR'
+  | 'TELEGRAM_RATE_LIMITED'
+  | 'TELEGRAM_CHAT_NOT_FOUND'
+  | 'TELEGRAM_MESSAGE_NOT_FOUND'
+  | 'TELEGRAM_WEBHOOK_FAILED'
+  | 'TELEGRAM_ABORTED'
+```
+
+---
+
+## Genesis additions
+
+1. **`TelegramError`** extends `SuaveplanError` with seven stable codes.
+2. **Zod schemas** for `TelegramMessage`, `TelegramUpdate`, `TelegramUser`, `SendMessageOptions`, `InlineKeyboardMarkup`, `ReplyKeyboardMarkup`, `InlineQueryResult`.
+3. **Long-poll loop** — `getUpdates` returns an `AsyncGenerator<TelegramUpdate>` that manages offset tracking and exits cleanly on `AbortSignal`.
+4. **Rate-limit handling** — Telegram returns 429 with `retry_after`; the client waits the prescribed delay before retrying.
+5. **OTel instrumentation** — span `telegram.api_call` with attribute `telegram.method`; counter `telegram.api_total`; histogram `telegram.api_duration_ms`.
+6. **Property-based tests** — keyboard builder produces valid nested JSON for arbitrary row/button configurations.
+
+---
+
+## File layout
+
+```text
+universal/social/telegram-client/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    constants/
+      index.ts
+    types/
+      common.ts
+      common.md
+    core/
+      telegram-bot/
+        telegram-bot.ts
+        telegram-bot.md
+        telegram-bot.types.ts
+        telegram-bot.test.ts
+        index.ts
+      api-caller/
+        api-caller.ts
+        api-caller.md
+        api-caller.test.ts
+        index.ts
+      update-poller/
+        update-poller.ts
+        update-poller.md
+        update-poller.test.ts
+        index.ts
+    keyboards/
+      keyboard-builder/
+        keyboard-builder.ts
+        keyboard-builder.md
+        keyboard-builder.test.ts
+        index.ts
+    __benchmarks__/
+      telegram-client.bench.ts
+  tests/
+    integration.test.ts
+    property.test.ts
+```
+
+---
+
+## Impact
+
+**Downstream consumers**: `@suaveplan/message-bridge`, `@suaveplan/notification-channel`.
+
+**Workspace dep prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/retry`.