suaveplan/openspec/archive/2026-05-18-add-telegram-client/tasks.md

Tasks — Add @suaveplan/telegram-client

1. Spec authoring

• 1.1 Read ../suaveplan/enterprise/telegram-client.md end-to-end
• 1.2 Read openspec/specs/telegram-client/spec.md (does not exist yet — new cap)
• 1.3 Read openspec/templates/README.md (substitute for missing AGENTS.md)
• 1.4 Draft proposal.md from openspec/templates/proposal.md
• 1.5 Fill ## Source mapping — every requirement cites file/line or appears in the no-source table
• 1.6 Draft specs/telegram-client/spec.md from openspec/templates/spec-delta.md
• 1.7 Every requirement carries a **Verified by:** line naming concrete it(...) titles

2. Implementation

• 2.1 Scaffold package layout at packages/messaging/telegram-client/
• 2.2 Author src/types/telegram-bot-config.ts with Zod schema + runtime type
• 2.3 Author src/types/telegram-client.types.ts covering every upstream surface type
• 2.4 Author src/errors/telegram-client-error.ts with defineCodes + class
• 2.5 Author src/utils/build-bodies.ts (pure body / reply-markup builders)
• 2.6 Author src/utils/classify-error.ts (pure status + retry-after classifier)
• 2.7 Author src/core/telegram-bot-client/telegram-bot-client.ts (client, OTel, injectable fetch+clock)
• 2.8 Author barrel src/index.ts with explicit named exports + subpath exports
• 2.9 package.json with 0.1.0, sideEffects:false, subpath exports, deps
• 2.10 vite.config.ts + vitest.config.ts + tsconfig.lib.json + tsconfig.json
• 2.11 tests/setup/polyfills.ts and tests/dep-graph.test.ts
• 2.12 README.md at root, no category-level READMEs

3. Tests

• 3.1 Unit tests at src/core/telegram-bot-client/telegram-bot-client.test.ts covering every scenario
• 3.2 Pure-helper tests at src/utils/build-bodies.test.ts, src/utils/classify-error.test.ts
• 3.3 Error registry tests at src/errors/telegram-client-error.test.ts
• 3.4 Zod schema tests at src/types/telegram-bot-config.test.ts
• 3.5 Every it(...) carries { timeout: 5000 } (or 30000 for genuinely async)
• 3.6 No vi.mock, no globalThis.fetch spy — injectable fetch only

4. Documentation

• 4.1 Sibling .md for every implementation .ts (≥200 words, basic + advanced examples)
• 4.2 README links every co-located .md under ## Modules

5. Pre-archive verification (the 5-gate triple)

• 5.1 bun run check — Biome 0 errors / 0 warnings / 0 info
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/telegram-client — green
• 5.3 bunx turbo test:coverage --filter=@suaveplan/telegram-client — 100/100/100/100
• 5.4 bun scripts/openspec-conformance.ts @suaveplan/telegram-client — exit 0
• 5.5 bunx turbo build --filter=@suaveplan/telegram-client — green

6. Pre-archive 7-row checklist

• 6.1 Generics threaded; expectTypeOf assertions on every literal-type claim
• 6.2 Zod schemas wired at every declared boundary (config)
• 6.3 Every error code in error-codes.ts thrown by at least one production path
• 6.4 Strict-mode behaviors tested (Zod parse rejects)
• 6.5 OTel instruments emitted from production paths and asserted with a real in-memory MeterProvider
• 6.6 Lifecycle dedup — N/A (stateless client)
• 6.7 No retroactive tick — every box above reflects work done in this change

7. Archive

• 7.1 Fold spec delta into openspec/specs/telegram-client/spec.md
• 7.2 Move openspec/changes/add-telegram-client/ → openspec/archive/2026-05-18-add-telegram-client/