watchdiff-core 0.1.5__tar.gz → 0.1.6__tar.gz

{watchdiff_core-0.1.5 → watchdiff_core-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: watchdiff-core
-Version: 0.1.5
+Version: 0.1.6
 Summary: Lightweight web change monitoring library - clean diffs, structured alerts, no AI required.
 Author: WatchDiff Contributors
 License: GPL-3.0-or-later
@@ -73,6 +73,7 @@ No noisy HTML diffs. No external services. No AI black boxes.
 | Archive HTML on change | `archive_html=True` |
 | Screenshot on change | `screenshot_on_change=True, browser=True` |
 | Detect change spikes | `change_spike_window=60, change_spike_threshold=5` |
+| Alert on HTTP status change | `alert_on_status_change=True` (200→503, 503→200, etc.) |
 | Compare two different URLs | `.compare_urls(url_a, url_b)` / `watchdiff compare <urlA> <urlB>` |
 | Persist to SQLite | `WatchDiff(store=SqliteStore(".watchdiff.db"))` |
 | Export history | `.export_reports_csv(url)` / `.export_reports_xlsx(url)` |
@@ -105,6 +106,7 @@ No noisy HTML diffs. No external services. No AI black boxes.
   - [HTML archiving](#html-archiving)
   - [Screenshot on change](#screenshot-on-change)
   - [Change spike detection](#change-spike-detection)
+  - [HTTP status code monitoring](#http-status-code-monitoring)
   - [URL comparison](#url-comparison)
   - [XPath selectors](#xpath-selectors)
   - [SQLite storage backend](#sqlite-storage-backend)
@@ -197,6 +199,13 @@ watchdiff run https://example.com --interval 60 --status-port 9090
 
 # Show status from config file
 watchdiff status
+watchdiff status --json
+
+# Export history / reports
+watchdiff export https://example.com                                     # CSV to stdout
+watchdiff export https://example.com --output reports.csv               # write to file
+watchdiff export https://example.com --type snapshots --output snap.csv # snapshots
+watchdiff export https://example.com --format xlsx --output reports.xlsx # XLSX
 
 # Snapshot history and reports
 watchdiff history https://example.com
@@ -538,7 +547,7 @@ wd.start(block=False)
 
 statuses = wd.status()
 for s in statuses:
-    print(s.url, s.checks_count, s.changes_count, s.errors_count, s.paused)
+    print(s.url, s.checks_count, s.changes_count, s.errors_count, s.paused, s.last_status_code)
 ```
 
 `WatcherStatus` fields:
@@ -556,6 +565,7 @@ for s in statuses:
 | `checks_count` | `int` | Total checks since start |
 | `changes_count` | `int` | Total changes detected since start |
 | `errors_count` | `int` | Total fetch/parse errors since start |
+| `last_status_code` | `int` | Last HTTP status code (0 = unknown/unreachable) |
 
 Returns an empty list if `.start()` has not been called yet.
 
@@ -585,8 +595,9 @@ watchdiff_changes_total{url="...",label="..."} 3
 watchdiff_errors_total{url="...",label="..."} 0
 watchdiff_paused{url="...",label="..."} 0
 watchdiff_interval_seconds{url="...",label="..."} 300
-watchdiff_last_check_timestamp{url="...",label="..."} 1720000000.0
-watchdiff_last_change_timestamp{url="...",label="..."} 1719999000.0
+watchdiff_last_check_timestamp_seconds{url="...",label="..."} 1720000000.0
+watchdiff_last_change_timestamp_seconds{url="...",label="..."} 1719999000.0
+watchdiff_last_http_status{url="...",label="..."} 200
 ```
 
 ```bash
@@ -669,6 +680,40 @@ The spike alert fires at most once per window to avoid repeated callbacks.
 watchdiff run https://example.com --spike-window 60 --spike-threshold 5
 ```
 
+### HTTP status code monitoring
+
+Alert when the HTTP status code of a URL changes — detect outages (200→503), maintenance pages (200→503), or recoveries (503→200) independently of content changes.
+
+```python
+from watchdiff import WatchDiff, StatusChangeInfo
+
+def on_status_change(info: StatusChangeInfo) -> None:
+    print(f"[STATUS] {info.label}: {info.previous_status} → {info.current_status}")
+
+wd = WatchDiff()
+wd.watch(
+    "https://example.com",
+    interval=60,
+    alert_on_status_change=True,          # enable status change detection
+    on_status_change=on_status_change,    # optional callback
+    webhooks=["https://ntfy.sh/my-alerts"],  # webhook fires on status change too
+)
+wd.start()
+```
+
+**How it works:**
+- Status `0` means the URL is unreachable (network error, DNS failure, timeout)
+- The first check initialises the baseline — no alert is fired
+- Subsequent checks alert only when the code **changes** (e.g. 200 → 503, 503 → 200)
+- When `webhooks` are configured, a webhook is sent with `context: "http_status"` in the change payload
+- The current status is always visible in `.status()` as `last_status_code` and in the Prometheus metric `watchdiff_last_http_status`
+
+`StatusChangeInfo` fields: `url`, `label`, `previous_status`, `current_status`.
+
+```bash
+watchdiff run https://example.com --alert-on-status-change --webhook https://ntfy.sh/my-alerts
+```
+
 ### URL comparison
 
 Fetch two different URLs and compare their content in one shot — without setting up a watcher or storing snapshots.
@@ -860,6 +905,8 @@ Register a URL to monitor. All keyword arguments are optional. Returns `self` (c
 | `change_spike_window` | `int \| None` | `None` | Spike detection rolling window in seconds |
 | `change_spike_threshold` | `int \| None` | `None` | Alert when this many changes occur in the window |
 | `on_spike` | `Callable \| None` | `None` | Called with `SpikeInfo` when spike is detected |
+| `alert_on_status_change` | `bool` | `False` | Alert when HTTP status code changes (200→503, etc.) |
+| `on_status_change` | `Callable \| None` | `None` | Called with `StatusChangeInfo` on status code change |
 
 ```python
 # Chainable
@@ -1005,6 +1052,15 @@ info.changes_in_window # int — number of changes detected in the window
 info.window_seconds    # int — the configured window size
 ```
 
+### `StatusChangeInfo`
+
+```python
+info.url             # str
+info.label           # str
+info.previous_status # int — HTTP status code before the change (0 = was unreachable)
+info.current_status  # int — HTTP status code after the change (0 = now unreachable)
+```
+
 ### `StatusServer`
 
 ```python
@@ -1024,6 +1080,7 @@ Commands:
   compare   Fetch two URLs and compare their content
   check     Run a single check and print the result
   diff      Compare the last two stored snapshots for a URL
+  export    Export history or reports to CSV or XLSX
   status    Show snapshot state for all watchers in a config file
   history   Show snapshot history for a URL
   reports   Show diff reports for a URL
@@ -1048,6 +1105,10 @@ Options for run:
   --spike-window          Spike detection rolling window in seconds (0 = off)
   --spike-threshold       Number of changes to trigger a spike alert
   --status-port           Start HTTP status server on this port (0 = off)
+  --alert-on-status-change  Alert when HTTP status code changes
+  --alert-if-no-change    Fire silence alert after N seconds without change (0 = off)
+  --proxy                 Proxy URL (repeatable)
+  --user-agent            User-Agent string (repeatable)
   --webhook          -w   Webhook URL (repeatable)
   --log-format            Log format: text | json (default text)
   --verbose          -v   Enable debug logging
@@ -1071,9 +1132,16 @@ Options for diff:
   --storage          -s   Storage directory
   --json                  Output raw JSON
 
+Options for export:
+  --type                  What to export: reports | snapshots (default reports)
+  --format                Output format: csv | xlsx (default csv)
+  --output           -o   Output file path (prints to stdout if omitted)
+  --limit            -n   Max entries to export (default 500)
+
 Options for status:
   --storage          -s   Storage directory
   --config           -c   Config file to read URLs from
+  --json                  Output raw JSON
 
 Options for history / reports:
   --limit            -n   Number of entries to show (default 20)
@@ -1105,6 +1173,12 @@ Every CLI option can be set via environment variable — useful for Docker, CI,
 | `WATCHDIFF_SPIKE_WINDOW` | `--spike-window` | `60` |
 | `WATCHDIFF_SPIKE_THRESHOLD` | `--spike-threshold` | `5` |
 | `WATCHDIFF_STATUS_PORT` | `--status-port` | `9090` |
+| `WATCHDIFF_ALERT_ON_STATUS_CHANGE` | `--alert-on-status-change` | `true` |
+| `WATCHDIFF_ALERT_IF_NO_CHANGE` | `--alert-if-no-change` | `86400` |
+| `WATCHDIFF_PROXY` | `--proxy` | `http://proxy:8080` |
+| `WATCHDIFF_USER_AGENT` | `--user-agent` | `MyBot/1.0` |
+| `WATCHDIFF_TARGET` | `--target` | `.price` |
+| `WATCHDIFF_QUIET` | `--quiet` | `true` |
 | `WATCHDIFF_LOG_FORMAT` | `--log-format` | `json` |
 | `WATCHDIFF_VERBOSE` | `--verbose` | `true` |
 

{watchdiff_core-0.1.5 → watchdiff_core-0.1.6}/README.md

@@ -34,6 +34,7 @@ No noisy HTML diffs. No external services. No AI black boxes.
 | Archive HTML on change | `archive_html=True` |
 | Screenshot on change | `screenshot_on_change=True, browser=True` |
 | Detect change spikes | `change_spike_window=60, change_spike_threshold=5` |
+| Alert on HTTP status change | `alert_on_status_change=True` (200→503, 503→200, etc.) |
 | Compare two different URLs | `.compare_urls(url_a, url_b)` / `watchdiff compare <urlA> <urlB>` |
 | Persist to SQLite | `WatchDiff(store=SqliteStore(".watchdiff.db"))` |
 | Export history | `.export_reports_csv(url)` / `.export_reports_xlsx(url)` |
@@ -66,6 +67,7 @@ No noisy HTML diffs. No external services. No AI black boxes.
   - [HTML archiving](#html-archiving)
   - [Screenshot on change](#screenshot-on-change)
   - [Change spike detection](#change-spike-detection)
+  - [HTTP status code monitoring](#http-status-code-monitoring)
   - [URL comparison](#url-comparison)
   - [XPath selectors](#xpath-selectors)
   - [SQLite storage backend](#sqlite-storage-backend)
@@ -158,6 +160,13 @@ watchdiff run https://example.com --interval 60 --status-port 9090
 
 # Show status from config file
 watchdiff status
+watchdiff status --json
+
+# Export history / reports
+watchdiff export https://example.com                                     # CSV to stdout
+watchdiff export https://example.com --output reports.csv               # write to file
+watchdiff export https://example.com --type snapshots --output snap.csv # snapshots
+watchdiff export https://example.com --format xlsx --output reports.xlsx # XLSX
 
 # Snapshot history and reports
 watchdiff history https://example.com
@@ -499,7 +508,7 @@ wd.start(block=False)
 
 statuses = wd.status()
 for s in statuses:
-    print(s.url, s.checks_count, s.changes_count, s.errors_count, s.paused)
+    print(s.url, s.checks_count, s.changes_count, s.errors_count, s.paused, s.last_status_code)
 ```
 
 `WatcherStatus` fields:
@@ -517,6 +526,7 @@ for s in statuses:
 | `checks_count` | `int` | Total checks since start |
 | `changes_count` | `int` | Total changes detected since start |
 | `errors_count` | `int` | Total fetch/parse errors since start |
+| `last_status_code` | `int` | Last HTTP status code (0 = unknown/unreachable) |
 
 Returns an empty list if `.start()` has not been called yet.
 
@@ -546,8 +556,9 @@ watchdiff_changes_total{url="...",label="..."} 3
 watchdiff_errors_total{url="...",label="..."} 0
 watchdiff_paused{url="...",label="..."} 0
 watchdiff_interval_seconds{url="...",label="..."} 300
-watchdiff_last_check_timestamp{url="...",label="..."} 1720000000.0
-watchdiff_last_change_timestamp{url="...",label="..."} 1719999000.0
+watchdiff_last_check_timestamp_seconds{url="...",label="..."} 1720000000.0
+watchdiff_last_change_timestamp_seconds{url="...",label="..."} 1719999000.0
+watchdiff_last_http_status{url="...",label="..."} 200
 ```
 
 ```bash
@@ -630,6 +641,40 @@ The spike alert fires at most once per window to avoid repeated callbacks.
 watchdiff run https://example.com --spike-window 60 --spike-threshold 5
 ```
 
+### HTTP status code monitoring
+
+Alert when the HTTP status code of a URL changes — detect outages (200→503), maintenance pages (200→503), or recoveries (503→200) independently of content changes.
+
+```python
+from watchdiff import WatchDiff, StatusChangeInfo
+
+def on_status_change(info: StatusChangeInfo) -> None:
+    print(f"[STATUS] {info.label}: {info.previous_status} → {info.current_status}")
+
+wd = WatchDiff()
+wd.watch(
+    "https://example.com",
+    interval=60,
+    alert_on_status_change=True,          # enable status change detection
+    on_status_change=on_status_change,    # optional callback
+    webhooks=["https://ntfy.sh/my-alerts"],  # webhook fires on status change too
+)
+wd.start()
+```
+
+**How it works:**
+- Status `0` means the URL is unreachable (network error, DNS failure, timeout)
+- The first check initialises the baseline — no alert is fired
+- Subsequent checks alert only when the code **changes** (e.g. 200 → 503, 503 → 200)
+- When `webhooks` are configured, a webhook is sent with `context: "http_status"` in the change payload
+- The current status is always visible in `.status()` as `last_status_code` and in the Prometheus metric `watchdiff_last_http_status`
+
+`StatusChangeInfo` fields: `url`, `label`, `previous_status`, `current_status`.
+
+```bash
+watchdiff run https://example.com --alert-on-status-change --webhook https://ntfy.sh/my-alerts
+```
+
 ### URL comparison
 
 Fetch two different URLs and compare their content in one shot — without setting up a watcher or storing snapshots.
@@ -821,6 +866,8 @@ Register a URL to monitor. All keyword arguments are optional. Returns `self` (c
 | `change_spike_window` | `int \| None` | `None` | Spike detection rolling window in seconds |
 | `change_spike_threshold` | `int \| None` | `None` | Alert when this many changes occur in the window |
 | `on_spike` | `Callable \| None` | `None` | Called with `SpikeInfo` when spike is detected |
+| `alert_on_status_change` | `bool` | `False` | Alert when HTTP status code changes (200→503, etc.) |
+| `on_status_change` | `Callable \| None` | `None` | Called with `StatusChangeInfo` on status code change |
 
 ```python
 # Chainable
@@ -966,6 +1013,15 @@ info.changes_in_window # int — number of changes detected in the window
 info.window_seconds    # int — the configured window size
 ```
 
+### `StatusChangeInfo`
+
+```python
+info.url             # str
+info.label           # str
+info.previous_status # int — HTTP status code before the change (0 = was unreachable)
+info.current_status  # int — HTTP status code after the change (0 = now unreachable)
+```
+
 ### `StatusServer`
 
 ```python
@@ -985,6 +1041,7 @@ Commands:
   compare   Fetch two URLs and compare their content
   check     Run a single check and print the result
   diff      Compare the last two stored snapshots for a URL
+  export    Export history or reports to CSV or XLSX
   status    Show snapshot state for all watchers in a config file
   history   Show snapshot history for a URL
   reports   Show diff reports for a URL
@@ -1009,6 +1066,10 @@ Options for run:
   --spike-window          Spike detection rolling window in seconds (0 = off)
   --spike-threshold       Number of changes to trigger a spike alert
   --status-port           Start HTTP status server on this port (0 = off)
+  --alert-on-status-change  Alert when HTTP status code changes
+  --alert-if-no-change    Fire silence alert after N seconds without change (0 = off)
+  --proxy                 Proxy URL (repeatable)
+  --user-agent            User-Agent string (repeatable)
   --webhook          -w   Webhook URL (repeatable)
   --log-format            Log format: text | json (default text)
   --verbose          -v   Enable debug logging
@@ -1032,9 +1093,16 @@ Options for diff:
   --storage          -s   Storage directory
   --json                  Output raw JSON
 
+Options for export:
+  --type                  What to export: reports | snapshots (default reports)
+  --format                Output format: csv | xlsx (default csv)
+  --output           -o   Output file path (prints to stdout if omitted)
+  --limit            -n   Max entries to export (default 500)
+
 Options for status:
   --storage          -s   Storage directory
   --config           -c   Config file to read URLs from
+  --json                  Output raw JSON
 
 Options for history / reports:
   --limit            -n   Number of entries to show (default 20)
@@ -1066,6 +1134,12 @@ Every CLI option can be set via environment variable — useful for Docker, CI,
 | `WATCHDIFF_SPIKE_WINDOW` | `--spike-window` | `60` |
 | `WATCHDIFF_SPIKE_THRESHOLD` | `--spike-threshold` | `5` |
 | `WATCHDIFF_STATUS_PORT` | `--status-port` | `9090` |
+| `WATCHDIFF_ALERT_ON_STATUS_CHANGE` | `--alert-on-status-change` | `true` |
+| `WATCHDIFF_ALERT_IF_NO_CHANGE` | `--alert-if-no-change` | `86400` |
+| `WATCHDIFF_PROXY` | `--proxy` | `http://proxy:8080` |
+| `WATCHDIFF_USER_AGENT` | `--user-agent` | `MyBot/1.0` |
+| `WATCHDIFF_TARGET` | `--target` | `.price` |
+| `WATCHDIFF_QUIET` | `--quiet` | `true` |
 | `WATCHDIFF_LOG_FORMAT` | `--log-format` | `json` |
 | `WATCHDIFF_VERBOSE` | `--verbose` | `true` |
 

{watchdiff_core-0.1.5 → watchdiff_core-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "watchdiff-core"
-version = "0.1.5"
+version = "0.1.6"
 description = "Lightweight web change monitoring library - clean diffs, structured alerts, no AI required."
 readme = "README.md"
 requires-python = ">=3.9"

{watchdiff_core-0.1.5 → watchdiff_core-0.1.6}/watchdiff/__init__.py

@@ -1,6 +1,6 @@
 from watchdiff.core import WatchDiff
 from watchdiff.exporter import Exporter
-from watchdiff.models import BrowserOptions, DiffMode, SpikeInfo, WatchConfig
+from watchdiff.models import BrowserOptions, DiffMode, SpikeInfo, StatusChangeInfo, WatchConfig
 from watchdiff.status_server import StatusServer
 from watchdiff.store import SqliteStore, Store
 
@@ -10,6 +10,7 @@ __all__ = [
     "Exporter",
     "SqliteStore",
     "SpikeInfo",
+    "StatusChangeInfo",
     "StatusServer",
     "Store",
     "WatchConfig",

{watchdiff_core-0.1.5 → watchdiff_core-0.1.6}/watchdiff/cli/main.py

@@ -41,7 +41,8 @@ console = Console()
 # ---------------------------------------------------------------------------
 
 _URL_ARG      = typer.Argument(..., help="URL to monitor.")
-_TARGET_OPT   = typer.Option(None,    "--target",   "-t", help="CSS selector or XPath to watch.")
+_TARGET_OPT   = typer.Option(None,    "--target",   "-t", help="CSS selector or XPath to watch.",
+                              envvar="WATCHDIFF_TARGET")
 _INTERVAL_OPT = typer.Option(300,     "--interval", "-i", help="Seconds between checks.",
                               envvar="WATCHDIFF_INTERVAL")
 _STORAGE_OPT  = typer.Option(".watchdiff", "--storage", "-s", help="Storage directory.",
@@ -260,6 +261,18 @@ def cmd_run(
     status_port: int        = typer.Option(0, "--status-port",
                                            help="Start status HTTP server on this port (0 = off).",
                                            envvar="WATCHDIFF_STATUS_PORT"),
+    alert_on_status_change: bool = typer.Option(False, "--alert-on-status-change",
+                                           help="Alert when HTTP status code changes.",
+                                           envvar="WATCHDIFF_ALERT_ON_STATUS_CHANGE"),
+    alert_if_no_change: int = typer.Option(0, "--alert-if-no-change",
+                                           help="Fire silence alert after N seconds without change (0 = off).",
+                                           envvar="WATCHDIFF_ALERT_IF_NO_CHANGE"),
+    proxy: list[str]      = typer.Option([], "--proxy",
+                                           help="Proxy URL (repeatable).",
+                                           envvar="WATCHDIFF_PROXY"),
+    user_agent: list[str] = typer.Option([], "--user-agent",
+                                           help="User-Agent string (repeatable).",
+                                           envvar="WATCHDIFF_USER_AGENT"),
     config_file: str | None = typer.Option(None, "--config", "-c",
                                            help="Load watchers from a JSON config file."),
 ) -> None:
@@ -299,13 +312,18 @@ def cmd_run(
         ignore_numbers         = ignore_numbers,
         archive_html           = archive_html,
         screenshot_on_change   = screenshot,
-        change_spike_window    = spike_window or None,
-        change_spike_threshold = spike_threshold or None,
+        change_spike_window      = spike_window or None,
+        change_spike_threshold   = spike_threshold or None,
+        alert_on_status_change   = alert_on_status_change,
+        alert_if_no_change_after = alert_if_no_change or None,
+        proxies                  = proxy or [],
+        user_agents              = user_agent or [],
     )
     wd.on_change(_print_report)
 
-    cooldown_label  = f"{cooldown}s" if cooldown > 0 else "off"
-    dry_run_label   = "[yellow]dry-run[/]" if dry_run else "off"
+    cooldown_label       = f"{cooldown}s" if cooldown > 0 else "off"
+    dry_run_label        = "[yellow]dry-run[/]" if dry_run else "off"
+    status_change_label  = "[yellow]on[/]" if alert_on_status_change else "off"
     status_line = ""
     if status_port > 0:
         status_line = f"\nStatus API: [cyan]http://localhost:{status_port}/status[/]"
@@ -320,7 +338,8 @@ def cmd_run(
             f"Browser:   [yellow]{browser}[/]  "
             f"Cooldown:  [yellow]{cooldown_label}[/]\n"
             f"Retries:   [yellow]{retries}[/]  "
-            f"Dry-run:   {dry_run_label}"
+            f"Dry-run:   {dry_run_label}  "
+            f"Status alerts: {status_change_label}"
             f"{status_line}\n"
             f"Press [bold]Ctrl+C[/] to stop.",
             title="WatchDiff",
@@ -480,6 +499,7 @@ def cmd_status(
     storage: str            = _STORAGE_OPT,
     config_file: str | None = typer.Option(None, "--config", "-c",
                                             help="Config file to read URLs from."),
+    output_json: bool       = typer.Option(False, "--json", help="Output raw JSON."),
 ) -> None:
     """Show last snapshot info for all watched URLs (reads from config file)."""
     from watchdiff.store import Store
@@ -512,18 +532,32 @@ def cmd_status(
     table.add_column("Last snapshot", style="green")
     table.add_column("Snapshots",     justify="right")
 
+    rows = []
     for w in watchers:
-        url_w   = w["url"]
+        url_w    = w["url"]
         target_w = w.get("target")
         label_w  = w.get("label") or url_w
         snaps    = store.load_history(url_w, target_w, limit=9999)
         latest   = snaps[-1] if snaps else None
+        rows.append({
+            "label":         label_w,
+            "url":           url_w,
+            "target":        target_w,
+            "last_snapshot": latest.captured_at.isoformat() if latest else None,
+            "snapshots":     len(snaps),
+        })
+
+    if output_json:
+        typer.echo(json.dumps(rows, indent=2, ensure_ascii=False))
+        return
+
+    for row in rows:
         table.add_row(
-            label_w,
-            url_w,
-            target_w or "full page",
-            latest.captured_at.strftime("%Y-%m-%d %H:%M:%S") if latest else "-",
-            str(len(snaps)),
+            row["label"],
+            row["url"],
+            row["target"] or "full page",
+            row["last_snapshot"][:19].replace("T", " ") if row["last_snapshot"] else "-",
+            str(row["snapshots"]),
         )
 
     console.print(table)
@@ -593,6 +627,56 @@ def cmd_reports(
         )
 
 
+@app.command("export")
+def cmd_export(
+    url: str               = _URL_ARG,
+    target: str | None     = _TARGET_OPT,
+    storage: str           = _STORAGE_OPT,
+    output: str | None     = typer.Option(None, "--output", "-o",
+                                          help="Output file path (prints to stdout if omitted)."),
+    export_type: str       = typer.Option("reports", "--type",
+                                          help="What to export: reports | snapshots."),
+    export_format: str     = typer.Option("csv", "--format",
+                                          help="Output format: csv | xlsx."),
+    limit: int             = typer.Option(500, "--limit", "-n",
+                                          help="Max entries to export."),
+) -> None:
+    """Export snapshot history or diff reports to CSV or XLSX."""
+    from watchdiff.exporter import Exporter  # noqa: PLC0415
+    from watchdiff.store import Store        # noqa: PLC0415
+    from pathlib import Path as _Path        # noqa: PLC0415
+
+    if export_type not in ("reports", "snapshots"):
+        console.print("[red]--type must be 'reports' or 'snapshots'[/]")
+        raise typer.Exit(1)
+
+    if export_format not in ("csv", "xlsx"):
+        console.print("[red]--format must be 'csv' or 'xlsx'[/]")
+        raise typer.Exit(1)
+
+    store    = Store(storage)
+    exporter = Exporter(store)
+
+    if export_format == "csv":
+        if export_type == "reports":
+            result = exporter.reports_csv(url, target, limit=limit,
+                                          dest=_Path(output) if output else None)
+        else:
+            result = exporter.snapshots_csv(url, target, limit=limit,
+                                            dest=_Path(output) if output else None)
+        if not output:
+            typer.echo(result)
+        else:
+            console.print(f"[green]Exported[/] {export_type} to [yellow]{output}[/]")
+    else:
+        dest = _Path(output) if output else _Path(f"{export_type}.xlsx")
+        if export_type == "reports":
+            path = exporter.reports_xlsx(url, target, limit=limit, dest=dest)
+        else:
+            path = exporter.snapshots_xlsx(url, target, limit=limit, dest=dest)
+        console.print(f"[green]Exported[/] {export_type} to [yellow]{path}[/]")
+
+
 @app.command("clear")
 def cmd_clear(
     url: str           = _URL_ARG,
@@ -676,6 +760,7 @@ def _run_from_config(path: Path, on_change_cb: object) -> None:
             change_threshold         = w.get("change_threshold"),
             ignore_numbers           = w.get("ignore_numbers", False),
             alert_if_no_change_after = w.get("alert_if_no_change_after"),
+            alert_on_status_change   = w.get("alert_on_status_change", False),
         )
 
     wd.on_change(on_change_cb)  # type: ignore[arg-type]

{watchdiff_core-0.1.5 → watchdiff_core-0.1.6}/watchdiff/core.py

@@ -42,6 +42,7 @@ from watchdiff.models import (
     DiffReport,
     SilenceInfo,
     SpikeInfo,
+    StatusChangeInfo,
     WatchConfig,
     WatcherStatus,
 )
@@ -116,6 +117,8 @@ class WatchDiff:
         change_spike_window: int | None                                                        = None,
         change_spike_threshold: int | None                                                     = None,
         on_spike: Callable[[SpikeInfo], None] | None                                          = None,
+        alert_on_status_change: bool                                                           = False,
+        on_status_change: Callable[[StatusChangeInfo], None] | None                           = None,
     ) -> WatchDiff:
         """
         Register a URL to monitor.
@@ -198,6 +201,8 @@ class WatchDiff:
             change_spike_window      = change_spike_window,
             change_spike_threshold   = change_spike_threshold,
             on_spike                 = on_spike,
+            alert_on_status_change   = alert_on_status_change,
+            on_status_change         = on_status_change,
         )
         self._configs.append(config)
         return self

{watchdiff_core-0.1.5 → watchdiff_core-0.1.6}/watchdiff/fetcher/fetcher.py

@@ -66,6 +66,10 @@ def _backoff(attempt: int, retry_delay: float) -> float:
 class FetchError(Exception):
     """Raised when an HTTP request fails."""
 
+    def __init__(self, message: str, status_code: int = 0) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
 
 class Fetcher:
     """Synchronous HTTP fetcher with UA/proxy rotation and retry backoff."""
@@ -103,15 +107,16 @@ class Fetcher:
                     resp.raise_for_status()
                     return resp.text
             except httpx.HTTPStatusError as exc:
-                last_exc = FetchError(f"HTTP {exc.response.status_code} for {config.url}")
-                if exc.response.status_code not in _RETRYABLE_STATUS or attempt >= config.retries:
-                    raise FetchError(f"HTTP {exc.response.status_code} for {config.url}") from exc
+                code     = exc.response.status_code
+                last_exc = FetchError(f"HTTP {code} for {config.url}", status_code=code)
+                if code not in _RETRYABLE_STATUS or attempt >= config.retries:
+                    raise FetchError(f"HTTP {code} for {config.url}", status_code=code) from exc
             except httpx.RequestError as exc:
-                last_exc = FetchError(f"Request failed for {config.url}: {exc}")
+                last_exc = FetchError(f"Request failed for {config.url}: {exc}", status_code=0)
                 if attempt >= config.retries:
-                    raise FetchError(f"Request failed for {config.url}: {exc}") from exc
+                    raise FetchError(f"Request failed for {config.url}: {exc}", status_code=0) from exc
 
-        raise last_exc or FetchError(f"All retries exhausted for {config.url}")
+        raise last_exc or FetchError(f"All retries exhausted for {config.url}", status_code=0)
 
 
 class AsyncFetcher:
@@ -150,12 +155,13 @@ class AsyncFetcher:
                     resp.raise_for_status()
                     return resp.text
             except httpx.HTTPStatusError as exc:
-                last_exc = FetchError(f"HTTP {exc.response.status_code} for {config.url}")
-                if exc.response.status_code not in _RETRYABLE_STATUS or attempt >= config.retries:
-                    raise FetchError(f"HTTP {exc.response.status_code} for {config.url}") from exc
+                code     = exc.response.status_code
+                last_exc = FetchError(f"HTTP {code} for {config.url}", status_code=code)
+                if code not in _RETRYABLE_STATUS or attempt >= config.retries:
+                    raise FetchError(f"HTTP {code} for {config.url}", status_code=code) from exc
             except httpx.RequestError as exc:
-                last_exc = FetchError(f"Request failed for {config.url}: {exc}")
+                last_exc = FetchError(f"Request failed for {config.url}: {exc}", status_code=0)
                 if attempt >= config.retries:
-                    raise FetchError(f"Request failed for {config.url}: {exc}") from exc
+                    raise FetchError(f"Request failed for {config.url}: {exc}", status_code=0) from exc
 
-        raise last_exc or FetchError(f"All retries exhausted for {config.url}")
+        raise last_exc or FetchError(f"All retries exhausted for {config.url}", status_code=0)

{watchdiff_core-0.1.5 → watchdiff_core-0.1.6}/watchdiff/models.py

@@ -80,6 +80,9 @@ class WatchConfig:
     change_spike_window: int | None        = None     # spike detection window in seconds
     change_spike_threshold: int | None     = None     # alert when this many changes in window
     on_spike: Callable[[SpikeInfo], None] | None = None
+    # --- new in 0.1.6 ---
+    alert_on_status_change: bool                         = False
+    on_status_change: Callable[[StatusChangeInfo], None] | None = None
 
     def __post_init__(self) -> None:
         if not self.label:
@@ -261,3 +264,13 @@ class SpikeInfo:
     label: str
     changes_in_window: int
     window_seconds: int
+
+
+@dataclass
+class StatusChangeInfo:
+    """Payload passed to the on_status_change callback."""
+
+    url:             str
+    label:           str
+    previous_status: int
+    current_status:  int

{watchdiff_core-0.1.5 → watchdiff_core-0.1.6}/watchdiff/scheduler/scheduler.py

@@ -35,7 +35,7 @@ from pathlib import Path
 from watchdiff.cleaner import Cleaner
 from watchdiff.diff import DiffEngine
 from watchdiff.fetcher import AsyncFetcher, Fetcher
-from watchdiff.models import DiffReport, SilenceInfo, SpikeInfo, WatchConfig, WatcherStatus
+from watchdiff.models import DiffReport, SilenceInfo, SpikeInfo, StatusChangeInfo, WatchConfig, WatcherStatus
 from watchdiff.notifier import Notifier
 from watchdiff.parser import Parser, ParserError
 
@@ -75,6 +75,7 @@ class SyncScheduler:
         self._silence_fired: dict[str, bool]                         = {}
         self._recent_change_times: dict[str, list[float]]            = {}
         self._last_spike_at: dict[str, float]                        = {}
+        self._last_status_code: dict[str, int]                       = {}
 
     def add_global_callback(self, callback: Callable[[DiffReport], None]) -> None:
         """Register a callback called for every DiffReport (regardless of config)."""
@@ -146,6 +147,7 @@ class SyncScheduler:
                 checks_count      = self._checks_count.get(key, 0),
                 changes_count     = self._changes_count.get(key, 0),
                 errors_count      = self._errors_count.get(key, 0),
+                last_status_code  = self._last_status_code.get(key, 0),
             ))
         return result
 
@@ -167,6 +169,7 @@ class SyncScheduler:
         self._silence_fired[key]       = False
         self._recent_change_times[key] = []
         self._last_spike_at[key]       = 0.0
+        self._last_status_code[key]    = 0
 
         while not stop_event.is_set():
             if config.url not in self._paused:
@@ -203,6 +206,8 @@ class SyncScheduler:
         except Exception as exc:  # noqa: BLE001
             self._errors_count[key] = self._errors_count.get(key, 0) + 1
             logger.error("[%s] Fetch failed: %s", config.label, exc)
+            current_status = getattr(exc, "status_code", 0)
+            self._handle_status_change(key, current_status, config)
             if config.on_error:
                 try:
                     config.on_error(exc, config)
@@ -210,6 +215,8 @@ class SyncScheduler:
                     logger.warning("[%s] on_error callback error: %s", config.label, cb_exc)
             return None
 
+        self._handle_status_change(key, 200, config)
+
         cleaner = Cleaner(
             extra_selectors = config.ignore_selectors,
             extra_patterns  = extra_patterns,
@@ -367,6 +374,57 @@ class SyncScheduler:
             except Exception as exc:  # noqa: BLE001
                 logger.warning("[%s] on_silence callback error: %s", config.label, exc)
 
+    def _handle_status_change(self, key: str, current_status: int, config: WatchConfig) -> None:
+        prev = self._last_status_code.get(key, 0)
+        self._last_status_code[key] = current_status
+
+        if not config.alert_on_status_change or prev == 0 or prev == current_status:
+            return
+
+        label = (
+            f"recovered ({prev} → 200)"
+            if current_status == 200
+            else f"{prev} → {current_status or 'unreachable'}"
+        )
+        logger.warning("[%s] HTTP status changed: %s", config.label, label)
+
+        info = StatusChangeInfo(
+            url             = config.url,
+            label           = config.label or config.url,
+            previous_status = prev,
+            current_status  = current_status,
+        )
+
+        if config.on_status_change:
+            try:
+                config.on_status_change(info)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("[%s] on_status_change callback error: %s", config.label, exc)
+
+        if not config.dry_run and config.alert:
+            from watchdiff.models import Change, ChangeType, Snapshot  # noqa: PLC0415
+            from datetime import datetime, timezone  # noqa: PLC0415
+            now      = datetime.now(timezone.utc)
+            empty    = Snapshot(url=config.url, target=config.target, content="", raw_html="")
+            fake_report = DiffReport(
+                url         = config.url,
+                target      = config.target,
+                label       = config.label or config.url,
+                before      = empty,
+                after       = empty,
+                changes     = [Change(
+                    kind    = ChangeType.MODIFIED,
+                    before  = str(prev),
+                    after   = str(current_status) if current_status else "unreachable",
+                    context = "http_status",
+                )],
+                compared_at = now,
+            )
+            try:
+                self._notifier.notify(fake_report, config.alert)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("[%s] Status change webhook error: %s", config.label, exc)
+
     def _cooldown_ok(self, config: WatchConfig) -> bool:
         if config.cooldown <= 0:
             return True
@@ -402,6 +460,7 @@ class AsyncScheduler:
         self._silence_fired: dict[str, bool]                         = {}
         self._recent_change_times: dict[str, list[float]]            = {}
         self._last_spike_at: dict[str, float]                        = {}
+        self._last_status_code: dict[str, int]                       = {}
 
     def add_global_callback(self, callback: Callable[[DiffReport], None]) -> None:
         self._on_diff_callbacks.append(callback)
@@ -439,9 +498,10 @@ class AsyncScheduler:
                 last_check_at  = datetime.fromtimestamp(last_check, tz=timezone.utc) if last_check else None,
                 next_check_at  = datetime.fromtimestamp(next_check, tz=timezone.utc) if next_check else None,
                 last_change_at = datetime.fromtimestamp(last_change, tz=timezone.utc) if last_change else None,
-                checks_count   = self._checks_count.get(key, 0),
-                changes_count  = self._changes_count.get(key, 0),
-                errors_count   = self._errors_count.get(key, 0),
+                checks_count      = self._checks_count.get(key, 0),
+                changes_count     = self._changes_count.get(key, 0),
+                errors_count      = self._errors_count.get(key, 0),
+                last_status_code  = self._last_status_code.get(key, 0),
             ))
         return result
 
@@ -458,6 +518,7 @@ class AsyncScheduler:
         self._silence_fired[key]       = False
         self._recent_change_times[key] = []
         self._last_spike_at[key]       = 0.0
+        self._last_status_code[key]    = 0
 
         while True:
             if config.url not in self._paused:
@@ -494,6 +555,8 @@ class AsyncScheduler:
         except Exception as exc:  # noqa: BLE001
             self._errors_count[key] = self._errors_count.get(key, 0) + 1
             logger.error("[%s] Fetch failed: %s", config.label, exc)
+            current_status = getattr(exc, "status_code", 0)
+            await self._handle_status_change(key, current_status, config)
             if config.on_error:
                 try:
                     config.on_error(exc, config)
@@ -501,6 +564,8 @@ class AsyncScheduler:
                     logger.warning("[%s] on_error callback error: %s", config.label, cb_exc)
             return None
 
+        await self._handle_status_change(key, 200, config)
+
         cleaner = Cleaner(
             extra_selectors = config.ignore_selectors,
             extra_patterns  = extra_patterns,
@@ -658,6 +723,57 @@ class AsyncScheduler:
             except Exception as exc:  # noqa: BLE001
                 logger.warning("[%s] on_silence callback error: %s", config.label, exc)
 
+    async def _handle_status_change(self, key: str, current_status: int, config: WatchConfig) -> None:
+        prev = self._last_status_code.get(key, 0)
+        self._last_status_code[key] = current_status
+
+        if not config.alert_on_status_change or prev == 0 or prev == current_status:
+            return
+
+        label = (
+            f"recovered ({prev} → 200)"
+            if current_status == 200
+            else f"{prev} → {current_status or 'unreachable'}"
+        )
+        logger.warning("[%s] HTTP status changed: %s", config.label, label)
+
+        info = StatusChangeInfo(
+            url             = config.url,
+            label           = config.label or config.url,
+            previous_status = prev,
+            current_status  = current_status,
+        )
+
+        if config.on_status_change:
+            try:
+                config.on_status_change(info)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("[%s] on_status_change callback error: %s", config.label, exc)
+
+        if not config.dry_run and config.alert:
+            from watchdiff.models import Change, ChangeType, Snapshot  # noqa: PLC0415
+            from datetime import datetime, timezone  # noqa: PLC0415
+            now      = datetime.now(timezone.utc)
+            empty    = Snapshot(url=config.url, target=config.target, content="", raw_html="")
+            fake_report = DiffReport(
+                url         = config.url,
+                target      = config.target,
+                label       = config.label or config.url,
+                before      = empty,
+                after       = empty,
+                changes     = [Change(
+                    kind    = ChangeType.MODIFIED,
+                    before  = str(prev),
+                    after   = str(current_status) if current_status else "unreachable",
+                    context = "http_status",
+                )],
+                compared_at = now,
+            )
+            try:
+                self._notifier.notify(fake_report, config.alert)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("[%s] Status change webhook error: %s", config.label, exc)
+
     def _cooldown_ok(self, config: WatchConfig) -> bool:
         if config.cooldown <= 0:
             return True