devalerts 0.1.5__tar.gz → 0.2.0__tar.gz

{devalerts-0.1.5 → devalerts-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devalerts
-Version: 0.1.5
+Version: 0.2.0
 Summary: Send unhandled Python exceptions straight to a Telegram chat. No backend, no account, no database — just your own bot token.
 Keywords: telegram,error-tracking,exception-monitoring,alerts,logging,monitoring,asgi
 Author: sslinNn
@@ -77,7 +77,13 @@ chat instead of a log file nobody's watching.
 2. Message your bot once (or add it to a group) so it's allowed to message you back.
 3. Get your chat id — message [@userinfobot](https://t.me/userinfobot), or call
    `https://api.telegram.org/bot<TOKEN>/getUpdates` after step 2 and read `message.chat.id`.
-4. In your app, as early as possible:
+4. Verify it's wired up correctly before touching any code:
+
+   ```
+   uv run devalerts test --bot-token 123456:ABC-DEF... --chat-id 123456789
+   ```
+
+5. In your app, as early as possible:
 
 ```python
 import devalerts
@@ -109,6 +115,48 @@ uv run devalerts dashboard
 
 ![devalerts dashboard output](https://raw.githubusercontent.com/sslinNn/devalerts/main/docs/dashboard.svg)
 
+Pass `--json` for machine-readable output. Silence a noisy group without
+touching code — the `ID` column accepts any unique prefix:
+
+```
+uv run devalerts mute abc12345
+uv run devalerts unmute abc12345
+uv run devalerts clear abc12345   # or: devalerts clear --all
+```
+
+Unmuting resends the next occurrence with the accumulated skip count, same
+as a rate-limit window expiring.
+
+Error groups that keep piling up while suppressed are chronic: each such
+resend doubles the effective `rate_limit_seconds` for that group (capped at
+8x), so a crash loop backs itself off instead of paging you every window
+forever. A group that goes quiet and reappears once resets to the base rate
+immediately. The dashboard shows the active multiplier (`● sending ×4`).
+
+## Context: hostname and tags
+
+Every alert automatically includes the sending host, so you can tell which
+process/server it came from when one bot serves several:
+
+```python
+devalerts.init(bot_token="...", chat_id=123456789, tags={"env": "production"})
+```
+
+```
+🔴 ValueError: boom
+🖥️ prod-web-2 (env=production)
+```
+
+Add ad-hoc tags to a single call — they override `init()`'s tags on a key
+collision:
+
+```python
+devalerts.report(extra={"request_id": "abc123"})
+
+@devalerts.capture(extra={"job": "nightly-sync"})
+def run_job(): ...
+```
+
 ## Manually reporting a caught exception
 
 ```python
@@ -148,6 +196,24 @@ Only exceptions that actually escape as server errors get reported — routing
 404s and raised `HTTPException`s are already turned into responses by the
 framework before the middleware sees them.
 
+## Celery
+
+Same problem as ASGI apps: `init()`'s excepthook never sees exceptions raised
+inside a task, because Celery catches them itself to record the task's
+`FAILURE` state. Call `init_celery()` in addition to `init()`:
+
+```python
+devalerts.init(bot_token="...", chat_id=123456789)
+devalerts.init_celery()
+```
+
+This connects to Celery's `task_failure` signal (fired once a task has
+genuinely failed — retries exhausted or none configured, so retried tasks
+don't spam an alert per attempt) and reports through the same
+grouping/rate-limiting/redaction path as everything else, tagged with the
+task name and id automatically. Requires Celery to already be installed in
+the worker process — it's imported lazily, not a devalerts dependency.
+
 ## Why not Sentry?
 
 If you already run Sentry/Rollbar/etc., keep using it — devalerts isn't a
@@ -178,8 +244,8 @@ you want dedup state to survive restarts — it self-recreates otherwise.
 Yes — `init()` installs both `sys.excepthook` and `threading.excepthook`.
 
 **Works with Celery / background workers?**
-Yes, `init()` in the worker process the same way as in a web process. For
-tasks you catch yourself, use `report()` or `@devalerts.capture()`.
+Yes — call [`init_celery()`](#celery) in addition to `init()` to catch
+exceptions raised inside tasks, which the excepthook alone won't see.
 
 **Works on Windows / Linux / macOS?**
 Yes — stdlib only (`urllib`, `sqlite3`, `threading`), no OS-specific code
@@ -196,6 +262,9 @@ paths.
 - Basic secret redaction only (a few common token/key patterns) — do not
   rely on this for sensitive production data; scrub what you can before it
   ever reaches an exception message.
+- If Telegram delivery fails after retrying, the alert (already redacted, if
+  `redact=True`) is appended to `~/.devalerts/failed.log` instead of being
+  dropped — clean it up like any other local log file.
 
 ## What this does NOT do (by design)
 

{devalerts-0.1.5 → devalerts-0.2.0}/README.md

@@ -50,7 +50,13 @@ chat instead of a log file nobody's watching.
 2. Message your bot once (or add it to a group) so it's allowed to message you back.
 3. Get your chat id — message [@userinfobot](https://t.me/userinfobot), or call
    `https://api.telegram.org/bot<TOKEN>/getUpdates` after step 2 and read `message.chat.id`.
-4. In your app, as early as possible:
+4. Verify it's wired up correctly before touching any code:
+
+   ```
+   uv run devalerts test --bot-token 123456:ABC-DEF... --chat-id 123456789
+   ```
+
+5. In your app, as early as possible:
 
 ```python
 import devalerts
@@ -82,6 +88,48 @@ uv run devalerts dashboard
 
 ![devalerts dashboard output](https://raw.githubusercontent.com/sslinNn/devalerts/main/docs/dashboard.svg)
 
+Pass `--json` for machine-readable output. Silence a noisy group without
+touching code — the `ID` column accepts any unique prefix:
+
+```
+uv run devalerts mute abc12345
+uv run devalerts unmute abc12345
+uv run devalerts clear abc12345   # or: devalerts clear --all
+```
+
+Unmuting resends the next occurrence with the accumulated skip count, same
+as a rate-limit window expiring.
+
+Error groups that keep piling up while suppressed are chronic: each such
+resend doubles the effective `rate_limit_seconds` for that group (capped at
+8x), so a crash loop backs itself off instead of paging you every window
+forever. A group that goes quiet and reappears once resets to the base rate
+immediately. The dashboard shows the active multiplier (`● sending ×4`).
+
+## Context: hostname and tags
+
+Every alert automatically includes the sending host, so you can tell which
+process/server it came from when one bot serves several:
+
+```python
+devalerts.init(bot_token="...", chat_id=123456789, tags={"env": "production"})
+```
+
+```
+🔴 ValueError: boom
+🖥️ prod-web-2 (env=production)
+```
+
+Add ad-hoc tags to a single call — they override `init()`'s tags on a key
+collision:
+
+```python
+devalerts.report(extra={"request_id": "abc123"})
+
+@devalerts.capture(extra={"job": "nightly-sync"})
+def run_job(): ...
+```
+
 ## Manually reporting a caught exception
 
 ```python
@@ -121,6 +169,24 @@ Only exceptions that actually escape as server errors get reported — routing
 404s and raised `HTTPException`s are already turned into responses by the
 framework before the middleware sees them.
 
+## Celery
+
+Same problem as ASGI apps: `init()`'s excepthook never sees exceptions raised
+inside a task, because Celery catches them itself to record the task's
+`FAILURE` state. Call `init_celery()` in addition to `init()`:
+
+```python
+devalerts.init(bot_token="...", chat_id=123456789)
+devalerts.init_celery()
+```
+
+This connects to Celery's `task_failure` signal (fired once a task has
+genuinely failed — retries exhausted or none configured, so retried tasks
+don't spam an alert per attempt) and reports through the same
+grouping/rate-limiting/redaction path as everything else, tagged with the
+task name and id automatically. Requires Celery to already be installed in
+the worker process — it's imported lazily, not a devalerts dependency.
+
 ## Why not Sentry?
 
 If you already run Sentry/Rollbar/etc., keep using it — devalerts isn't a
@@ -151,8 +217,8 @@ you want dedup state to survive restarts — it self-recreates otherwise.
 Yes — `init()` installs both `sys.excepthook` and `threading.excepthook`.
 
 **Works with Celery / background workers?**
-Yes, `init()` in the worker process the same way as in a web process. For
-tasks you catch yourself, use `report()` or `@devalerts.capture()`.
+Yes — call [`init_celery()`](#celery) in addition to `init()` to catch
+exceptions raised inside tasks, which the excepthook alone won't see.
 
 **Works on Windows / Linux / macOS?**
 Yes — stdlib only (`urllib`, `sqlite3`, `threading`), no OS-specific code
@@ -169,6 +235,9 @@ paths.
 - Basic secret redaction only (a few common token/key patterns) — do not
   rely on this for sensitive production data; scrub what you can before it
   ever reaches an exception message.
+- If Telegram delivery fails after retrying, the alert (already redacted, if
+  `redact=True`) is appended to `~/.devalerts/failed.log` instead of being
+  dropped — clean it up like any other local log file.
 
 ## What this does NOT do (by design)
 

{devalerts-0.1.5 → devalerts-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "devalerts"
-version = "0.1.5"
+version = "0.2.0"
 description = "Send unhandled Python exceptions straight to a Telegram chat. No backend, no account, no database — just your own bot token."
 readme = "README.md"
 license = "MIT"
@@ -48,6 +48,7 @@ build-backend = "uv_build"
 
 [dependency-groups]
 dev = [
+    "celery>=5.3.0",
     "mypy>=1.19.1",
     "pre-commit>=4.3.0",
     "pytest>=8.4.2",

{devalerts-0.1.5 → devalerts-0.2.0}/src/devalerts/__init__.py

@@ -9,10 +9,11 @@ from types import TracebackType
 from typing import Callable, Literal, Optional, TypedDict
 
 from ._alert import _format_alert, _redact
+from ._celery import init_celery
 from ._store import _DEFAULT_RATE_LIMIT_SECONDS, _fingerprint, _should_send
 from ._telegram import _send_telegram_message
 
-__all__: list[str] = ["init", "report", "capture", "ASGIMiddleware"]
+__all__: list[str] = ["init", "report", "capture", "ASGIMiddleware", "init_celery"]
 
 _ExceptHook = Callable[
     [type[BaseException], BaseException, Optional[TracebackType]], object
@@ -25,6 +26,7 @@ class _State(TypedDict):
     chat_id: int | str | None
     redact: bool
     rate_limit_seconds: int
+    tags: dict[str, str]
     # Seeded with the real default hooks below (never None) -- _excepthook/
     # _threading_excepthook can only ever fire after init() has replaced
     # sys.excepthook/threading.excepthook, by which point these are always
@@ -38,12 +40,15 @@ _state: _State = {
     "chat_id": None,
     "redact": True,
     "rate_limit_seconds": _DEFAULT_RATE_LIMIT_SECONDS,
+    "tags": {},
     "prev_excepthook": sys.excepthook,
     "prev_threading_excepthook": threading.excepthook,
 }
 
 
-def _send_exception(exc_type, exc_value, tb) -> None:
+def _send_exception(
+    exc_type, exc_value, tb, extra: dict[str, str] | None = None
+) -> None:
     if _state["bot_token"] is None or _state["chat_id"] is None:
         print("devalerts: init() was not called, dropping alert", file=sys.stderr)
         return
@@ -53,7 +58,8 @@ def _send_exception(exc_type, exc_value, tb) -> None:
     )
     if not send:
         return
-    message = _format_alert(exc_type, exc_value, tb, skipped=skipped)
+    tags = {**_state["tags"], **(extra or {})}
+    message = _format_alert(exc_type, exc_value, tb, skipped=skipped, tags=tags)
     if _state["redact"]:
         message = _redact(message)
     _send_telegram_message(_state["bot_token"], _state["chat_id"], message)
@@ -87,12 +93,14 @@ def init(
     *,
     redact: bool = True,
     rate_limit_seconds: int = _DEFAULT_RATE_LIMIT_SECONDS,
+    tags: dict[str, str] | None = None,
 ) -> None:
     """Install a global exception hook that sends unhandled exceptions to Telegram."""
     _state["bot_token"] = bot_token
     _state["chat_id"] = chat_id
     _state["redact"] = redact
     _state["rate_limit_seconds"] = rate_limit_seconds
+    _state["tags"] = tags or {}
     # ponytail: guard against calling init() twice capturing our own hook as
     # "previous" -- that would make _excepthook chain to itself and recurse
     # forever on the next crash, violating "must never raise".
@@ -104,7 +112,9 @@ def init(
     threading.excepthook = _threading_excepthook
 
 
-def report(exc: BaseException | None = None) -> None:
+def report(
+    exc: BaseException | None = None, *, extra: dict[str, str] | None = None
+) -> None:
     """Manually send a caught exception to Telegram."""
     if exc is None:
         exc_type, exc_value, tb = sys.exc_info()
@@ -114,7 +124,7 @@ def report(exc: BaseException | None = None) -> None:
             )
     else:
         exc_type, exc_value, tb = type(exc), exc, exc.__traceback__
-    _send_exception(exc_type, exc_value, tb)
+    _send_exception(exc_type, exc_value, tb, extra=extra)
 
 
 class capture(contextlib.ContextDecorator):
@@ -122,12 +132,15 @@ class capture(contextlib.ContextDecorator):
     function, then re-raise it. Use ``@capture()`` on a function instead of wrapping
     its body in a manual ``try/except`` or ``with`` block."""
 
+    def __init__(self, *, extra: dict[str, str] | None = None) -> None:
+        self._extra = extra
+
     def __enter__(self) -> "capture":
         return self
 
     def __exit__(self, exc_type, exc_value, tb) -> Literal[False]:
         if exc_type is not None:
-            _send_exception(exc_type, exc_value, tb)
+            _send_exception(exc_type, exc_value, tb, extra=self._extra)
         return False
 
 

{devalerts-0.1.5 → devalerts-0.2.0}/src/devalerts/_alert.py

@@ -3,13 +3,27 @@
 from __future__ import annotations
 
 import re
+import socket
 import traceback
 
 _MAX_MESSAGE_LENGTH = 4096
 
 
-def _format_alert(exc_type, exc_value, tb, skipped: int = 0) -> str:
-    header = f"\U0001f534 {exc_type.__name__}: {exc_value}"
+def _format_context(tags: dict[str, str] | None) -> str:
+    try:
+        hostname = socket.gethostname()
+    except OSError:
+        hostname = "unknown-host"
+    line = f"🖥️ {hostname}"
+    if tags:
+        line += " (" + ", ".join(f"{key}={value}" for key, value in tags.items()) + ")"
+    return line
+
+
+def _format_alert(
+    exc_type, exc_value, tb, skipped: int = 0, tags: dict[str, str] | None = None
+) -> str:
+    header = f"\U0001f534 {exc_type.__name__}: {exc_value}\n{_format_context(tags)}"
     if skipped:
         header += f"\n⚠️ Повторилась ещё {skipped} раз(а) с последнего алерта"
     body = "".join(traceback.format_exception(exc_type, exc_value, tb))

devalerts-0.2.0/src/devalerts/_celery.py

@@ -0,0 +1,45 @@
+"""Optional Celery integration: report task failures that Celery's own trace
+machinery swallows before they ever reach sys.excepthook -- the same problem
+ASGIMiddleware solves for FastAPI/Starlette request errors."""
+
+from __future__ import annotations
+
+_connected = False
+
+
+def init_celery() -> None:
+    """Report Celery task failures to Telegram. Call in addition to init(),
+    which never sees exceptions raised inside a task -- Celery catches those
+    itself to record the task's FAILURE state.
+
+    Usage::
+
+        devalerts.init(bot_token="...", chat_id=123456789)
+        devalerts.init_celery()
+
+    Requires Celery to already be installed in the worker process (not a
+    devalerts dependency -- imported lazily here).
+    """
+    global _connected
+    if _connected:
+        return
+    from celery.signals import task_failure  # type: ignore[import-untyped]
+
+    task_failure.connect(_on_task_failure, weak=False)
+    _connected = True
+
+
+def _on_task_failure(
+    sender=None, task_id=None, exception=None, traceback=None, **_kwargs
+) -> None:
+    from . import _send_exception
+
+    if exception is None:
+        return
+    tags: dict[str, str] = {}
+    if task_id is not None:
+        tags["task_id"] = str(task_id)
+    if sender is not None:
+        tags["task"] = getattr(sender, "name", type(sender).__name__)
+    exc = exception.with_traceback(traceback) if traceback is not None else exception
+    _send_exception(type(exc), exc, exc.__traceback__, extra=tags)

devalerts-0.2.0/src/devalerts/_store.py

@@ -0,0 +1,191 @@
+"""Local SQLite state: fingerprint-based grouping, dedup, and rate limiting."""
+
+from __future__ import annotations
+
+import hashlib
+import sqlite3
+import sys
+import time
+import traceback
+from pathlib import Path
+
+_DB_PATH = Path.home() / ".devalerts" / "state.db"
+_RETENTION_SECONDS = 7 * 24 * 3600
+_DEFAULT_RATE_LIMIT_SECONDS = 300
+# ponytail: fixed cap, not configurable -- upgrade to an init() param if
+# users report the ceiling being wrong for their crash-loop cadence.
+_MAX_BACKOFF_MULTIPLIER = 8
+
+
+def _fingerprint(exc_type, tb) -> tuple[str, str]:
+    frames = traceback.extract_tb(tb)
+    location = f"{frames[-1].filename}:{frames[-1].lineno}" if frames else "unknown"
+    raw = f"{exc_type.__name__}:{location}"
+    return hashlib.sha1(raw.encode("utf-8")).hexdigest()[:16], location
+
+
+def _get_connection() -> sqlite3.Connection:
+    _DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(_DB_PATH, timeout=5)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS error_groups (
+            fingerprint TEXT PRIMARY KEY,
+            exc_type TEXT NOT NULL,
+            location TEXT NOT NULL,
+            first_seen REAL NOT NULL,
+            last_seen REAL NOT NULL,
+            last_sent REAL,
+            count_since_last_sent INTEGER NOT NULL DEFAULT 0,
+            total_count INTEGER NOT NULL DEFAULT 0,
+            rate_limit_seconds INTEGER,
+            muted INTEGER NOT NULL DEFAULT 0,
+            backoff_multiplier INTEGER NOT NULL DEFAULT 1
+        )
+        """
+    )
+    # ponytail: lazy migration for DBs created before these columns existed --
+    # ADD COLUMN has no "IF NOT EXISTS", so swallow the duplicate-column error
+    # on every subsequent call instead of tracking schema version.
+    for ddl in (
+        "ALTER TABLE error_groups ADD COLUMN rate_limit_seconds INTEGER",
+        "ALTER TABLE error_groups ADD COLUMN muted INTEGER NOT NULL DEFAULT 0",
+        "ALTER TABLE error_groups ADD COLUMN backoff_multiplier INTEGER NOT NULL DEFAULT 1",
+    ):
+        try:
+            conn.execute(ddl)
+        except sqlite3.OperationalError:
+            pass
+    return conn
+
+
+def _should_send(
+    fingerprint: str, exc_type_name: str, location: str, rate_limit_seconds: int
+) -> tuple[bool, int]:
+    now = time.time()
+    try:
+        conn = _get_connection()
+        try:
+            with conn:
+                row = conn.execute(
+                    "SELECT last_sent, count_since_last_sent, muted, backoff_multiplier "
+                    "FROM error_groups WHERE fingerprint = ?",
+                    (fingerprint,),
+                ).fetchone()
+                muted = bool(row[2]) if row else False
+                multiplier = row[3] if row else 1
+                effective_window = rate_limit_seconds * multiplier
+                if not muted and (
+                    row is None or row[0] is None or now - row[0] >= effective_window
+                ):
+                    send, skipped = True, (row[1] if row else 0)
+                    # Chronic (occurrences piled up while suppressed) doubles the
+                    # backoff, capped at _MAX_BACKOFF_MULTIPLIER; a single fresh
+                    # occurrence after a genuine quiet spell resets it to 1.
+                    new_multiplier = (
+                        min(multiplier * 2, _MAX_BACKOFF_MULTIPLIER) if skipped else 1
+                    )
+                    conn.execute(
+                        """
+                        INSERT INTO error_groups
+                            (fingerprint, exc_type, location, first_seen, last_seen,
+                             last_sent, count_since_last_sent, total_count,
+                             rate_limit_seconds, backoff_multiplier)
+                        VALUES (?, ?, ?, ?, ?, ?, 0, 1, ?, ?)
+                        ON CONFLICT(fingerprint) DO UPDATE SET
+                            last_seen = excluded.last_seen,
+                            last_sent = excluded.last_sent,
+                            count_since_last_sent = 0,
+                            total_count = total_count + 1,
+                            rate_limit_seconds = excluded.rate_limit_seconds,
+                            backoff_multiplier = excluded.backoff_multiplier
+                        """,
+                        (
+                            fingerprint,
+                            exc_type_name,
+                            location,
+                            now,
+                            now,
+                            now,
+                            rate_limit_seconds,
+                            new_multiplier,
+                        ),
+                    )
+                else:
+                    # Covers both "still rate-limited" and "muted" -- neither sends,
+                    # both keep counting so an eventual unmute/window-expiry reports
+                    # the accumulated skip count via count_since_last_sent.
+                    send, skipped = False, 0
+                    conn.execute(
+                        """
+                        UPDATE error_groups
+                        SET last_seen = ?, count_since_last_sent = count_since_last_sent + 1,
+                            total_count = total_count + 1, rate_limit_seconds = ?
+                        WHERE fingerprint = ?
+                        """,
+                        (now, rate_limit_seconds, fingerprint),
+                    )
+                conn.execute(
+                    "DELETE FROM error_groups WHERE last_seen < ?",
+                    (now - _RETENTION_SECONDS,),
+                )
+            return send, skipped
+        finally:
+            conn.close()
+    except (sqlite3.Error, OSError) as error:
+        # ponytail: dedup/rate-limit state must never block an alert -- fail
+        # open (send, as if this were the first occurrence) on any DB error.
+        print(
+            f"devalerts: dedup/rate-limit state error, sending anyway: {error}",
+            file=sys.stderr,
+        )
+        return True, 0
+
+
+def _match_fingerprints(prefix: str) -> list[str]:
+    """Fingerprints starting with prefix, for CLI mute/unmute/clear commands."""
+    conn = _get_connection()
+    try:
+        rows = conn.execute(
+            "SELECT fingerprint FROM error_groups WHERE fingerprint LIKE ? ESCAPE '\\'",
+            (
+                prefix.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
+                + "%",
+            ),
+        ).fetchall()
+    finally:
+        conn.close()
+    return [row[0] for row in rows]
+
+
+def _set_muted(fingerprint: str, muted: bool) -> None:
+    conn = _get_connection()
+    try:
+        with conn:
+            conn.execute(
+                "UPDATE error_groups SET muted = ? WHERE fingerprint = ?",
+                (int(muted), fingerprint),
+            )
+    finally:
+        conn.close()
+
+
+def _clear(fingerprint: str) -> None:
+    conn = _get_connection()
+    try:
+        with conn:
+            conn.execute(
+                "DELETE FROM error_groups WHERE fingerprint = ?", (fingerprint,)
+            )
+    finally:
+        conn.close()
+
+
+def _clear_all() -> None:
+    conn = _get_connection()
+    try:
+        with conn:
+            conn.execute("DELETE FROM error_groups")
+    finally:
+        conn.close()

devalerts-0.2.0/src/devalerts/_telegram.py

@@ -0,0 +1,72 @@
+"""Telegram Bot API delivery -- retries transient failures, logs to a local
+fallback file if every attempt fails. Never raises."""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+_TIMEOUT_SECONDS = 5
+_MAX_ATTEMPTS = 2
+_RETRY_BACKOFF_SECONDS = 1.0
+# ponytail: cap how long we'll honor Telegram's requested Retry-After --
+# beyond this we're blocking an excepthook that's about to exit the process,
+# so give up and fall back to the local log instead of stalling shutdown.
+_MAX_RETRY_AFTER_SECONDS = 10.0
+_FAILED_LOG_PATH = Path.home() / ".devalerts" / "failed.log"
+
+
+def _retry_after_seconds(error: urllib.error.HTTPError) -> float | None:
+    try:
+        body = json.loads(error.read())
+        retry_after = body.get("parameters", {}).get("retry_after")
+        return float(retry_after) if retry_after is not None else None
+    except (ValueError, AttributeError, TypeError):
+        return None
+
+
+def _log_failed_delivery(text: str) -> None:
+    try:
+        _FAILED_LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        with _FAILED_LOG_PATH.open("a", encoding="utf-8") as fh:
+            fh.write(f"--- {time.strftime('%Y-%m-%d %H:%M:%S')} ---\n{text}\n\n")
+    except OSError as error:
+        print(f"devalerts: failed to write fallback log: {error}", file=sys.stderr)
+
+
+def _send_telegram_message(bot_token: str, chat_id: int | str, text: str) -> bool:
+    url = f"https://api.telegram.org/bot{bot_token}/sendMessage"
+    payload = json.dumps({"chat_id": chat_id, "text": text}).encode("utf-8")
+    last_error: Exception | None = None
+
+    for attempt in range(_MAX_ATTEMPTS):
+        request = urllib.request.Request(
+            url,
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        wait: float = _RETRY_BACKOFF_SECONDS
+        try:
+            urllib.request.urlopen(request, timeout=_TIMEOUT_SECONDS)
+            return True
+        except urllib.error.HTTPError as error:
+            last_error = error
+            retry_after = _retry_after_seconds(error)
+            if retry_after is not None:
+                if retry_after > _MAX_RETRY_AFTER_SECONDS:
+                    break
+                wait = retry_after
+        except (urllib.error.URLError, OSError, ValueError) as error:
+            last_error = error
+
+        if attempt < _MAX_ATTEMPTS - 1:
+            time.sleep(wait)
+
+    print(f"devalerts: failed to send Telegram alert: {last_error}", file=sys.stderr)
+    _log_failed_delivery(text)
+    return False

devalerts-0.2.0/src/devalerts/cli.py

@@ -0,0 +1,317 @@
+"""CLI: `devalerts dashboard` reports grouped/rate-limited errors from the local
+state DB; `devalerts test` sends a one-off message to verify bot_token/chat_id."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sqlite3
+import sys
+import time
+from importlib.metadata import version as _pkg_version
+
+from ._store import (
+    _DB_PATH,
+    _DEFAULT_RATE_LIMIT_SECONDS,
+    _clear,
+    _clear_all,
+    _match_fingerprints,
+    _set_muted,
+)
+from ._telegram import _send_telegram_message
+
+_LOCATION_WIDTH = 34
+
+
+def _supports_unicode() -> bool:
+    encoding = getattr(sys.stdout, "encoding", None) or ""
+    try:
+        "─●…".encode(encoding)
+        return True
+    except (LookupError, UnicodeEncodeError, TypeError):
+        return False
+
+
+def _truncate(text: str, width: int, ellipsis: str) -> str:
+    """Keep the tail (file:line matters more than leading directories)."""
+    if len(text) <= width:
+        return text
+    keep = width - len(ellipsis)
+    return ellipsis + text[-keep:] if keep > 0 else ellipsis[:width]
+
+
+def _relative_time(ts: float, now: float) -> str:
+    delta = now - ts
+    if delta < 60:
+        return "just now"
+    if delta < 3600:
+        return f"{int(delta // 60)}m ago"
+    if delta < 86400:
+        return f"{int(delta // 3600)}h ago"
+    return f"{int(delta // 86400)}d ago"
+
+
+def _color_enabled() -> bool:
+    if os.environ.get("NO_COLOR") is not None or not sys.stdout.isatty():
+        return False
+    if sys.platform == "win32":
+        # ponytail: enable VT100 processing for legacy conhost.exe -- Windows
+        # Terminal / PowerShell 7 already support ANSI without this.
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+        handle = kernel32.GetStdHandle(-11)
+        mode = ctypes.c_uint32()
+        if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
+            return False
+        kernel32.SetConsoleMode(handle, mode.value | 0x0004)
+    return True
+
+
+class _Style:
+    def __init__(self, enabled: bool) -> None:
+        self._enabled = enabled
+
+    def _wrap(self, code: str, text: str) -> str:
+        return f"\033[{code}m{text}\033[0m" if self._enabled else text
+
+    def bold(self, text: str) -> str:
+        return self._wrap("1", text)
+
+    def dim(self, text: str) -> str:
+        return self._wrap("2", text)
+
+    def red(self, text: str) -> str:
+        return self._wrap("31", text)
+
+    def green(self, text: str) -> str:
+        return self._wrap("32", text)
+
+
+def _dashboard(as_json: bool = False) -> int:
+    if not _DB_PATH.exists():
+        print("[]" if as_json else "No errors recorded yet.")
+        return 0
+
+    conn = sqlite3.connect(_DB_PATH)
+    try:
+        rows = conn.execute(
+            "SELECT fingerprint, exc_type, location, last_seen, last_sent, total_count, "
+            "count_since_last_sent, rate_limit_seconds, muted, backoff_multiplier "
+            "FROM error_groups ORDER BY last_seen DESC"
+        ).fetchall()
+    finally:
+        conn.close()
+
+    if not rows:
+        print("[]" if as_json else "No errors recorded yet.")
+        return 0
+
+    now = time.time()
+
+    if as_json:
+        groups = []
+        for (
+            fingerprint,
+            exc_type,
+            location,
+            last_seen,
+            last_sent,
+            total_count,
+            count_since_last_sent,
+            rate_limit_seconds,
+            muted,
+            backoff_multiplier,
+        ) in rows:
+            limit = (
+                rate_limit_seconds
+                if rate_limit_seconds is not None
+                else _DEFAULT_RATE_LIMIT_SECONDS
+            ) * backoff_multiplier
+            rate_limited = (
+                not muted and last_sent is not None and now - last_sent < limit
+            )
+            groups.append(
+                {
+                    "fingerprint": fingerprint,
+                    "exc_type": exc_type,
+                    "location": location,
+                    "last_seen": last_seen,
+                    "last_sent": last_sent,
+                    "total_count": total_count,
+                    "count_since_last_sent": count_since_last_sent,
+                    "rate_limited": rate_limited,
+                    "muted": bool(muted),
+                    "backoff_multiplier": backoff_multiplier,
+                }
+            )
+        print(json.dumps(groups))
+        return 0
+
+    unicode_ok = _supports_unicode()
+    sep_char = "─" if unicode_ok else "-"
+    dot_char = "●" if unicode_ok else "*"
+    ellipsis = "…" if unicode_ok else "..."
+
+    style = _Style(_color_enabled())
+    type_width = max(len("TYPE"), *(len(r[1]) for r in rows))
+
+    header = (
+        f"  {'ID':<8}  {'TYPE':<{type_width}}  {'LOCATION':<{_LOCATION_WIDTH}}  "
+        f"{'LAST SEEN':<10}{'TOTAL':>6}   STATUS"
+    )
+    print(style.bold(header))
+    print("  " + sep_char * (len(header) - 2))
+
+    limited_count = 0
+    muted_count = 0
+    for (
+        fingerprint,
+        exc_type,
+        location,
+        last_seen,
+        last_sent,
+        total_count,
+        _count_since_last_sent,
+        rate_limit_seconds,
+        muted,
+        backoff_multiplier,
+    ) in rows:
+        backoff_suffix = f" ×{backoff_multiplier}" if backoff_multiplier > 1 else ""
+        if muted:
+            muted_count += 1
+            status = style.dim(f"{dot_char} muted")
+        else:
+            limit = (
+                rate_limit_seconds
+                if rate_limit_seconds is not None
+                else _DEFAULT_RATE_LIMIT_SECONDS
+            ) * backoff_multiplier
+            in_window = last_sent is not None and now - last_sent < limit
+            if in_window:
+                limited_count += 1
+                status = style.red(f"{dot_char} limited{backoff_suffix}")
+            else:
+                status = style.green(f"{dot_char} sending{backoff_suffix}")
+
+        row = (
+            f"  {style.dim(f'{fingerprint[:8]:<8}')}  "
+            f"{exc_type:<{type_width}}  "
+            f"{_truncate(location, _LOCATION_WIDTH, ellipsis):<{_LOCATION_WIDTH}}  "
+            f"{_relative_time(last_seen, now):<10}"
+            f"{total_count:>6}   {status}"
+        )
+        print(row)
+
+    plural = "" if len(rows) == 1 else "s"
+    print(
+        f"\n{len(rows)} error group{plural}, {limited_count} currently rate-limited, "
+        f"{muted_count} muted."
+    )
+    return 0
+
+
+def _resolve_fingerprint(prefix: str) -> str | None:
+    matches = _match_fingerprints(prefix)
+    if not matches:
+        print(f"No error group matches '{prefix}'.", file=sys.stderr)
+        return None
+    if len(matches) > 1:
+        print(
+            f"'{prefix}' matches {len(matches)} error groups, be more specific.",
+            file=sys.stderr,
+        )
+        return None
+    return matches[0]
+
+
+def _mute_command(prefix: str, muted: bool) -> int:
+    fingerprint = _resolve_fingerprint(prefix)
+    if fingerprint is None:
+        return 1
+    _set_muted(fingerprint, muted)
+    print(f"{'Muted' if muted else 'Unmuted'} {fingerprint[:8]}.")
+    return 0
+
+
+def _clear_command(prefix: str | None, clear_all: bool) -> int:
+    if clear_all:
+        _clear_all()
+        print("Cleared all error groups.")
+        return 0
+    # argparse's mutually exclusive group guarantees exactly one is set.
+    assert prefix is not None
+    fingerprint = _resolve_fingerprint(prefix)
+    if fingerprint is None:
+        return 1
+    _clear(fingerprint)
+    print(f"Cleared {fingerprint[:8]}.")
+    return 0
+
+
+def _test(bot_token: str, chat_id: str) -> int:
+    ok = _send_telegram_message(
+        bot_token,
+        chat_id,
+        "✅ devalerts test message -- bot_token and chat_id are wired up correctly.",
+    )
+    if not ok:
+        print("Failed to send test message (see error above).", file=sys.stderr)
+        return 1
+    print("Test message sent -- check your Telegram chat.")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="devalerts")
+    parser.add_argument(
+        "--version", action="version", version=f"devalerts {_pkg_version('devalerts')}"
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    dashboard_parser = subparsers.add_parser(
+        "dashboard", help="Show grouped/rate-limited errors"
+    )
+    dashboard_parser.add_argument(
+        "--json", action="store_true", help="Output as JSON instead of a table"
+    )
+    test_parser = subparsers.add_parser(
+        "test", help="Send a test message to verify bot_token/chat_id"
+    )
+    test_parser.add_argument("--bot-token", required=True)
+    test_parser.add_argument("--chat-id", required=True)
+    mute_parser = subparsers.add_parser("mute", help="Silence a specific error group")
+    mute_parser.add_argument(
+        "fingerprint", help="Fingerprint or unique prefix (dashboard ID column)"
+    )
+    unmute_parser = subparsers.add_parser(
+        "unmute", help="Re-enable alerts for a muted error group"
+    )
+    unmute_parser.add_argument("fingerprint", help="Fingerprint or unique prefix")
+    clear_parser = subparsers.add_parser(
+        "clear", help="Delete error group(s) from local state"
+    )
+    clear_target = clear_parser.add_mutually_exclusive_group(required=True)
+    clear_target.add_argument(
+        "fingerprint", nargs="?", help="Fingerprint or unique prefix"
+    )
+    clear_target.add_argument(
+        "--all", action="store_true", help="Delete all error groups"
+    )
+    args = parser.parse_args(argv)
+
+    if args.command == "dashboard":
+        return _dashboard(as_json=args.json)
+    if args.command == "test":
+        return _test(args.bot_token, args.chat_id)
+    if args.command == "mute":
+        return _mute_command(args.fingerprint, muted=True)
+    if args.command == "unmute":
+        return _mute_command(args.fingerprint, muted=False)
+    if args.command == "clear":
+        return _clear_command(args.fingerprint, args.all)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

devalerts-0.1.5/src/devalerts/_store.py

@@ -1,98 +0,0 @@
-"""Local SQLite state: fingerprint-based grouping, dedup, and rate limiting."""
-
-from __future__ import annotations
-
-import hashlib
-import sqlite3
-import sys
-import time
-import traceback
-from pathlib import Path
-
-_DB_PATH = Path.home() / ".devalerts" / "state.db"
-_RETENTION_SECONDS = 7 * 24 * 3600
-_DEFAULT_RATE_LIMIT_SECONDS = 300
-
-
-def _fingerprint(exc_type, tb) -> tuple[str, str]:
-    frames = traceback.extract_tb(tb)
-    location = f"{frames[-1].filename}:{frames[-1].lineno}" if frames else "unknown"
-    raw = f"{exc_type.__name__}:{location}"
-    return hashlib.sha1(raw.encode("utf-8")).hexdigest()[:16], location
-
-
-def _get_connection() -> sqlite3.Connection:
-    _DB_PATH.parent.mkdir(parents=True, exist_ok=True)
-    conn = sqlite3.connect(_DB_PATH, timeout=5)
-    conn.execute("PRAGMA journal_mode=WAL")
-    conn.execute(
-        """
-        CREATE TABLE IF NOT EXISTS error_groups (
-            fingerprint TEXT PRIMARY KEY,
-            exc_type TEXT NOT NULL,
-            location TEXT NOT NULL,
-            first_seen REAL NOT NULL,
-            last_seen REAL NOT NULL,
-            last_sent REAL,
-            count_since_last_sent INTEGER NOT NULL DEFAULT 0,
-            total_count INTEGER NOT NULL DEFAULT 0
-        )
-        """
-    )
-    return conn
-
-
-def _should_send(
-    fingerprint: str, exc_type_name: str, location: str, rate_limit_seconds: int
-) -> tuple[bool, int]:
-    now = time.time()
-    try:
-        conn = _get_connection()
-        try:
-            with conn:
-                row = conn.execute(
-                    "SELECT last_sent, count_since_last_sent FROM error_groups WHERE fingerprint = ?",
-                    (fingerprint,),
-                ).fetchone()
-                if row is None or row[0] is None or now - row[0] >= rate_limit_seconds:
-                    send, skipped = True, (row[1] if row else 0)
-                    conn.execute(
-                        """
-                        INSERT INTO error_groups
-                            (fingerprint, exc_type, location, first_seen, last_seen,
-                             last_sent, count_since_last_sent, total_count)
-                        VALUES (?, ?, ?, ?, ?, ?, 0, 1)
-                        ON CONFLICT(fingerprint) DO UPDATE SET
-                            last_seen = excluded.last_seen,
-                            last_sent = excluded.last_sent,
-                            count_since_last_sent = 0,
-                            total_count = total_count + 1
-                        """,
-                        (fingerprint, exc_type_name, location, now, now, now),
-                    )
-                else:
-                    send, skipped = False, 0
-                    conn.execute(
-                        """
-                        UPDATE error_groups
-                        SET last_seen = ?, count_since_last_sent = count_since_last_sent + 1,
-                            total_count = total_count + 1
-                        WHERE fingerprint = ?
-                        """,
-                        (now, fingerprint),
-                    )
-                conn.execute(
-                    "DELETE FROM error_groups WHERE last_seen < ?",
-                    (now - _RETENTION_SECONDS,),
-                )
-            return send, skipped
-        finally:
-            conn.close()
-    except (sqlite3.Error, OSError) as error:
-        # ponytail: dedup/rate-limit state must never block an alert -- fail
-        # open (send, as if this were the first occurrence) on any DB error.
-        print(
-            f"devalerts: dedup/rate-limit state error, sending anyway: {error}",
-            file=sys.stderr,
-        )
-        return True, 0

devalerts-0.1.5/src/devalerts/_telegram.py

@@ -1,25 +0,0 @@
-"""Telegram Bot API delivery -- never raises on network failure."""
-
-from __future__ import annotations
-
-import json
-import sys
-import urllib.error
-import urllib.request
-
-_TIMEOUT_SECONDS = 5
-
-
-def _send_telegram_message(bot_token: str, chat_id: int | str, text: str) -> None:
-    url = f"https://api.telegram.org/bot{bot_token}/sendMessage"
-    payload = json.dumps({"chat_id": chat_id, "text": text}).encode("utf-8")
-    request = urllib.request.Request(
-        url,
-        data=payload,
-        headers={"Content-Type": "application/json"},
-        method="POST",
-    )
-    try:
-        urllib.request.urlopen(request, timeout=_TIMEOUT_SECONDS)
-    except (urllib.error.URLError, OSError, ValueError) as error:
-        print(f"devalerts: failed to send Telegram alert: {error}", file=sys.stderr)

devalerts-0.1.5/src/devalerts/cli.py

@@ -1,156 +0,0 @@
-"""CLI: `devalerts dashboard` reports grouped/rate-limited errors from the local state DB."""
-
-from __future__ import annotations
-
-import argparse
-import os
-import sqlite3
-import sys
-import time
-
-from ._store import _DB_PATH, _DEFAULT_RATE_LIMIT_SECONDS
-
-_LOCATION_WIDTH = 34
-
-
-def _supports_unicode() -> bool:
-    encoding = getattr(sys.stdout, "encoding", None) or ""
-    try:
-        "─●…".encode(encoding)
-        return True
-    except (LookupError, UnicodeEncodeError, TypeError):
-        return False
-
-
-def _truncate(text: str, width: int, ellipsis: str) -> str:
-    """Keep the tail (file:line matters more than leading directories)."""
-    if len(text) <= width:
-        return text
-    keep = width - len(ellipsis)
-    return ellipsis + text[-keep:] if keep > 0 else ellipsis[:width]
-
-
-def _relative_time(ts: float, now: float) -> str:
-    delta = now - ts
-    if delta < 60:
-        return "just now"
-    if delta < 3600:
-        return f"{int(delta // 60)}m ago"
-    if delta < 86400:
-        return f"{int(delta // 3600)}h ago"
-    return f"{int(delta // 86400)}d ago"
-
-
-def _color_enabled() -> bool:
-    if os.environ.get("NO_COLOR") is not None or not sys.stdout.isatty():
-        return False
-    if sys.platform == "win32":
-        # ponytail: enable VT100 processing for legacy conhost.exe -- Windows
-        # Terminal / PowerShell 7 already support ANSI without this.
-        import ctypes
-
-        kernel32 = ctypes.windll.kernel32
-        handle = kernel32.GetStdHandle(-11)
-        mode = ctypes.c_uint32()
-        if not kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
-            return False
-        kernel32.SetConsoleMode(handle, mode.value | 0x0004)
-    return True
-
-
-class _Style:
-    def __init__(self, enabled: bool) -> None:
-        self._enabled = enabled
-
-    def _wrap(self, code: str, text: str) -> str:
-        return f"\033[{code}m{text}\033[0m" if self._enabled else text
-
-    def bold(self, text: str) -> str:
-        return self._wrap("1", text)
-
-    def dim(self, text: str) -> str:
-        return self._wrap("2", text)
-
-    def red(self, text: str) -> str:
-        return self._wrap("31", text)
-
-    def green(self, text: str) -> str:
-        return self._wrap("32", text)
-
-
-def _dashboard() -> int:
-    if not _DB_PATH.exists():
-        print("No errors recorded yet.")
-        return 0
-
-    conn = sqlite3.connect(_DB_PATH)
-    try:
-        rows = conn.execute(
-            "SELECT fingerprint, exc_type, location, last_seen, last_sent, total_count "
-            "FROM error_groups ORDER BY last_seen DESC"
-        ).fetchall()
-    finally:
-        conn.close()
-
-    if not rows:
-        print("No errors recorded yet.")
-        return 0
-
-    unicode_ok = _supports_unicode()
-    sep_char = "─" if unicode_ok else "-"
-    dot_char = "●" if unicode_ok else "*"
-    ellipsis = "…" if unicode_ok else "..."
-
-    style = _Style(_color_enabled())
-    now = time.time()
-    type_width = max(len("TYPE"), *(len(r[1]) for r in rows))
-
-    header = (
-        f"  {'ID':<8}  {'TYPE':<{type_width}}  {'LOCATION':<{_LOCATION_WIDTH}}  "
-        f"{'LAST SEEN':<10}{'TOTAL':>6}   STATUS"
-    )
-    print(style.bold(header))
-    print("  " + sep_char * (len(header) - 2))
-
-    limited_count = 0
-    for fingerprint, exc_type, location, last_seen, last_sent, total_count in rows:
-        # ponytail: dashboard runs in a separate process from init(), so it
-        # doesn't know the app's actual rate_limit_seconds -- uses the
-        # library default. Upgrade to persisting the configured value if
-        # apps commonly override it.
-        in_window = (
-            last_sent is not None and now - last_sent < _DEFAULT_RATE_LIMIT_SECONDS
-        )
-        if in_window:
-            limited_count += 1
-            status = style.red(f"{dot_char} limited")
-        else:
-            status = style.green(f"{dot_char} sending")
-
-        row = (
-            f"  {style.dim(f'{fingerprint[:8]:<8}')}  "
-            f"{exc_type:<{type_width}}  "
-            f"{_truncate(location, _LOCATION_WIDTH, ellipsis):<{_LOCATION_WIDTH}}  "
-            f"{_relative_time(last_seen, now):<10}"
-            f"{total_count:>6}   {status}"
-        )
-        print(row)
-
-    plural = "" if len(rows) == 1 else "s"
-    print(f"\n{len(rows)} error group{plural}, {limited_count} currently rate-limited.")
-    return 0
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog="devalerts")
-    subparsers = parser.add_subparsers(dest="command", required=True)
-    subparsers.add_parser("dashboard", help="Show grouped/rate-limited errors")
-    args = parser.parse_args(argv)
-
-    if args.command == "dashboard":
-        return _dashboard()
-    return 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())