feat: TelegramNotifier — recommended default notifier (rc2)

[cipher813]

Summary

Adds Telegram as the recommended default notifier in flow-doctor 0.5.0rc2.

Why Telegram becomes the default: for single-dev and small-team ops, Telegram beats SMTP / SES / Slack on setup cost (two-minute @BotFather flow vs. SMTP app password / SES verified identity / Slack workspace admin), routing (per-chat or per-thread is built in), and UX (mobile push is automatic). One bot fans out to N flows via chat_id and optional message_thread_id (forum topics in supergroups). Bot tokens rotate cleanly via @BotFather.

SMTP / SES (via existing EmailNotifier) / Slack / GitHub / S3 stay as alternates — the change is which notifier the README + builder examples lead with. No deprecations.

This also kills the orphan telegram_webhook_url field that was hiding in RemediationConfig with no first-class notifier behind it (will be cleaned up in a follow-up rc once we audit consumers).

Usage

from flow_doctor import FlowDoctor, TelegramNotifierConfig

fd = (
    FlowDoctor.builder("morning-signal")
    .add_notifier(TelegramNotifierConfig(
        bot_token=os.environ["FLOW_DOCTOR_TELEGRAM_BOT_TOKEN"],
        chat_id=-1001234567890,
        message_thread_id=42,  # optional — forum topic routing
    ))
    .with_dedup(cooldown_minutes=60)
    .build()
)

Or via env-only:

export FLOW_DOCTOR_TELEGRAM_BOT_TOKEN=...
export FLOW_DOCTOR_TELEGRAM_CHAT_ID=-1001234567890

fd = FlowDoctor.builder("morning-signal").add_notifier(
    TelegramNotifierConfig()  # all fields pulled from env
).build()

Implementation notes

• Bot API sendMessage via urllib (no requests dep — keeps the install lean).
• /getMe preflight at __init__ so a revoked token fails fast; bypassed by FLOW_DOCTOR_SKIP_PREFLIGHT=1 (same env-var contract as the other notifiers).
• 4096-char Telegram message limit handled with a [truncated] sentinel.
• send() returns "telegram:<chat_id>[:<thread>]" as the action target — never the bot token. Stored in actions.target for the audit trail.
• Numeric FLOW_DOCTOR_TELEGRAM_CHAT_ID env value auto-coerces to int (negative for supergroups / channels); @channelusername style stays str.

Test plan

• pytest tests/ → 376/376 pass (356 prior + 20 new Telegram tests).
• New tests cover: typed config round-trip through legacy NotifyChannelConfig, env-var coercion (int vs @channel str), missing-field ConfigError shape (mentions @BotFather + getUpdates), urllib POST URL + payload (chat_id / text / parse_mode / message_thread_id / disable_notification gating), target-id format, never-raises on API ok=false + network failure, message-length truncation, ActionType.TELEGRAM_ALERT dispatch end-to-end, preflight skip + 401-style auth failure.
• One pre-existing assertion in test_builder used "telegram" as an example unknown channel type — updated to "pagerduty".
• PyPI publish of 0.5.0rc2 after merge.
• Morning-signal cutover lands on top of 0.5.0rc2 in a separate PR (alpha-engine-morning-signal repo).

🤖 Generated with Claude Code