suaveplan/openspec/changes/enterprise-telegram-client/tasks.md

Tasks: enterprise-telegram-client

Change ID: enterprise-telegram-client Package: @suaveplan/telegram-client Target path: universal/social/telegram-client Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/types, @suaveplan/retry

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create universal/social/telegram-client/ with src/, tests/, src/__benchmarks__/ and all feature subdirectories per the layout in proposal.md.
• Write package.json at version 0.1.0 with "type": "module", "sideEffects": false, correct exports map, dependencies, and devDependencies.
• Write tsconfig.json extending @suaveplan/typescript-config/library.json.
• Write vitest.config.ts using createTestConfig() from @suaveplan/testing/config.
• Add lint, typecheck, test, test:coverage, build, docs:check scripts.

---

2. Types + errors

• src/types/common.ts — TelegramBotOptions, SendMessageOptions, SendMediaOptions, EditOptions, AnswerCallbackOptions, GetUpdatesOptions, WebhookOptions, TelegramMessage, TelegramUpdate, TelegramUser, InlineQueryResult, InlineKeyboardMarkup, ReplyKeyboardMarkup, ReplyKeyboardRemove.
• src/types/common.md (≥200 words, both examples, API reference).
• src/error-codes.ts — TelegramErrorCode (7 codes), metadata, register, eager call.
• src/types/schemas.ts + schemas.md — Zod schemas.

---

3. Core modules

• src/core/api-caller/ — ApiCaller: calls https://api.telegram.org/bot{token}/method; parses JSON; throws TELEGRAM_API_ERROR on ok:false (with Telegram error_code and description); handles 429 with retry_after; wraps with @suaveplan/retry. Tests: success, ok:false, 429.
• src/core/telegram-bot/ — TelegramBot: implements all public methods. sendPhoto/sendDocument with URL string uses photo=url form data; with Uint8Array uses multipart/form-data. Tests: sendMessage text+HTML parse_mode, sendPhoto URL, editMessageText, deleteMessage, answerCallbackQuery, setWebhook, deleteWebhook, getMe.
• src/core/update-poller/ — getUpdates(options): AsyncGenerator<TelegramUpdate> that manages offset (last_update_id + 1); each iteration calls getUpdates API with timeout=25 (long-poll); on AbortSignal, finishes current batch and yields. Tests: yields updates in order, offset advances, abort exits generator cleanly.
• src/keyboards/keyboard-builder/ — inlineKeyboard, replyKeyboard, removeKeyboard: pure constructors. Tests: 2×2 inline, 3-button reply, remove, ForceReply.

---

4. OTel instrumentation

• Span telegram.api_call with attribute telegram.method; counter telegram.api_total; histogram telegram.api_duration_ms.

---

5. Property-based tests (tests/property.test.ts)

• Keyboard builder: for arbitrary row/button arrays, inlineKeyboard(rows) produces JSON with inline_keyboard array of same dimensions.

---

6. Benchmarks (src/__benchmarks__/telegram-client.bench.ts)

• inlineKeyboard construction for 10-row × 5-button keyboard 100 000 times.

---

7. Docs + verify

• One .md per implementation file (≥200 words, both examples, API reference). Root README.md.
• bunx turbo lint typecheck test --filter=@suaveplan/telegram-client — green.
• bunx turbo test:coverage --filter=@suaveplan/telegram-client — 100%.
• bun scripts/publish.ts --package @suaveplan/telegram-client.
• Archive: openspec/archive/2026-04-24-enterprise-telegram-client/.