---
phase: 17-telegram-scheduler
plan: "01"
subsystem: telegram-bot
tags: [telegram, bot, telego, long-polling, auth]
dependency_graph:
  requires: []
  provides: [pkg/bot/bot.go, pkg/bot/bot_test.go]
  affects: [cmd/stubs.go]
tech_stack:
  added: [github.com/mymmrac/telego@v1.8.0]
  patterns: [long-polling, chat-id-authorization, per-user-rate-limiting]
key_files:
  created: [pkg/bot/bot.go, pkg/bot/bot_test.go]
  modified: [go.mod, go.sum]
decisions:
  - "telego v1.8.0 promoted from indirect to direct dependency"
  - "Context cancellation for graceful shutdown rather than explicit StopLongPolling call"
  - "Rate limit cooldown: 60s for scan/verify/recon, 5s for other commands"
metrics:
  duration: 3min
  completed: "2026-04-06T14:28:15Z"
  tasks_completed: 2
  tasks_total: 2
  files_changed: 4
---

# Phase 17 Plan 01: Telegram Bot Package Foundation Summary

Telego v1.8.0 bot skeleton with long-polling lifecycle, chat-ID allowlist auth, per-user rate limiting, and 10 command handler stubs.

## What Was Built

### pkg/bot/bot.go
- `Config` struct with Token, AllowedChats, DB, ScanEngine, ReconEngine, ProviderRegistry, EncKey fields
- `Bot` struct wrapping telego.Bot with cancel func and rate limit state
- `New(cfg Config) (*Bot, error)` creates telego bot from token
- `Start(ctx context.Context) error` registers commands via SetMyCommands, starts long polling, dispatches updates
- `Stop()` cancels context to trigger graceful shutdown
- `isAllowed(chatID)` checks chat against allowlist (empty = allow all)
- `checkRateLimit(userID, cooldown)` enforces per-user command cooldowns
- `dispatch()` routes incoming messages to handlers with auth + rate limit checks
- `reply()` and `replyPlain()` helpers for MarkdownV2 and plain text responses
- Handler stubs for all 10 commands: scan, verify, recon, status, stats, providers, help, key, subscribe, unsubscribe

### pkg/bot/bot_test.go
- TestNew_EmptyToken: verifies error on empty token
- TestIsAllowed_EmptyList: verifies open access with no restrictions
- TestIsAllowed_RestrictedList: verifies allowlist filtering
- TestCheckRateLimit: verifies cooldown enforcement and per-user isolation

## Commits

| # | Hash | Message |
|---|------|---------|
| 1 | 0d00215 | feat(17-01): add telego dependency and create Bot package skeleton |
| 2 | 2d51d31 | test(17-01): add unit tests for Bot creation and auth filtering |

## Deviations from Plan

None - plan executed exactly as written.

## Known Stubs

| File | Function | Purpose | Resolved By |
|------|----------|---------|-------------|
| pkg/bot/bot.go | handleScan | Stub returning "Not yet implemented" | Plan 17-03 |
| pkg/bot/bot.go | handleVerify | Stub returning "Not yet implemented" | Plan 17-03 |
| pkg/bot/bot.go | handleRecon | Stub returning "Not yet implemented" | Plan 17-03 |
| pkg/bot/bot.go | handleStatus | Stub returning "Not yet implemented" | Plan 17-03 |
| pkg/bot/bot.go | handleStats | Stub returning "Not yet implemented" | Plan 17-03 |
| pkg/bot/bot.go | handleProviders | Stub returning "Not yet implemented" | Plan 17-03 |
| pkg/bot/bot.go | handleHelp | Stub returning "Not yet implemented" | Plan 17-03 |
| pkg/bot/bot.go | handleKey | Stub returning "Not yet implemented" | Plan 17-03 |
| pkg/bot/bot.go | handleSubscribe | Stub returning "Not yet implemented" | Plan 17-04 |
| pkg/bot/bot.go | handleUnsubscribe | Stub returning "Not yet implemented" | Plan 17-04 |

These stubs are intentional -- the plan's goal is the package foundation, not handler implementation.

## Self-Check: PASSED

- pkg/bot/bot.go: FOUND
- pkg/bot/bot_test.go: FOUND
- Commit 0d00215: FOUND
- Commit 2d51d31: FOUND
- go build ./pkg/bot/...: OK
- go test ./pkg/bot/...: 4/4 PASS
- telego v1.8.0 in go.mod: FOUND (direct)