watchdiff-core 0.2.4__tar.gz → 0.2.5__tar.gz

{watchdiff_core-0.2.4 → watchdiff_core-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: watchdiff-core
-Version: 0.2.4
+Version: 0.2.5
 Summary: Lightweight web change monitoring library - clean diffs, AI summaries, file/API/SSL/DB monitoring, structured alerts.
 Author: WatchDiff Contributors
 License: BSD-2-Clause
@@ -97,6 +97,14 @@ WatchDiff watches web pages, files, APIs, databases, and SSL certificates - then
 | Skip checks during downtime | `maintenance_windows=[MaintenanceWindow(from_="2026-01-15T02:00Z", to="2026-01-15T04:00Z")]` |
 | Restrict checks to business hours | `active_between=ActiveBetween(from_="09:00", to="17:00", days=[0,1,2,3,4], timezone="Europe/Paris")` |
 | Suppress noisy error alerts | `failure_policy=FailurePolicy(consecutive_failures=3, recovery_checks=2)` |
+| Run a callback on recovery | `on_recovery=lambda cfg: print(f"{cfg.label} is back")` |
+| Cap exponential backoff | `max_retry_delay=30.0` — retry delay never exceeds 30 s regardless of attempt count |
+| Alert on very first capture | `alert_on_first_check=True` — fires `on_change` even when no previous snapshot exists |
+| Add custom webhook headers | `webhook_headers={"X-Api-Key": "secret"}` — merged into every webhook POST |
+| Auto-delete old snapshots | `retention_days=30` — snapshots older than N days are pruned after each save |
+| Export history as JSON | `.export_reports_json(url)` / `.export_snapshots_json(url)` |
+| Show last stored snapshot from CLI | `watchdiff snapshot https://example.com` |
+| Remove orphan storage files from CLI | `watchdiff clean` — deletes snap/report files not referenced by any active watcher |
 | Send email on change | `alert=AlertConfig(email=EmailConfig(to="...", smtp=SmtpConfig(...)))` |
 | AI summary of changes | `ai_summary=True, ai_provider=AiProvider(type="gemini", api_key="...")` |
 | Customize the AI prompt | `ai_prompt="Summarize in French."` or `ai_prompt=lambda r: ...` |
@@ -159,6 +167,13 @@ WatchDiff watches web pages, files, APIs, databases, and SSL certificates - then
   - [Maintenance windows](#maintenance-windows)
   - [Active hours](#active-hours)
   - [Failure policy](#failure-policy)
+  - [Recovery callback](#recovery-callback)
+  - [Max retry delay](#max-retry-delay)
+  - [Alert on first check](#alert-on-first-check)
+  - [Webhook headers](#webhook-headers)
+  - [Retention days](#retention-days)
+  - [JSON export](#json-export)
+  - [Slack Block Kit](#slack-block-kit)
 - [API reference](#api-reference)
   - [`.watch()`](#watchurl--)
   - [`.watch_db()`](#watch_dbconnection_string-table--)
@@ -172,7 +187,7 @@ WatchDiff watches web pages, files, APIs, databases, and SSL certificates - then
   - [`.compare_urls()`](#compare_urlsurl_a-url_b--)
   - [`.start_status_server()` / `.stop_status_server()`](#start_status_serverport-host--stop_status_server)
   - [`.pause()` / `.resume()` / `.status()` / `.db_status()`](#pauseurl--resumeurl--status--db_status)
-  - [`.history()` / `.reports()` / `.clear()`](#historyurl--reportsurl--clearurl)
+  - [`.history()` / `.reports()` / `.clear()` / `.export_*_json()`](#historyurl--reportsurl--clearurl--export_json)
   - [`DiffReport`](#diffreport)
   - [`Change`](#change)
   - [`Snapshot`](#snapshot)
@@ -680,6 +695,8 @@ wd.watch(
 
 `SilenceInfo` fields: `url`, `label`, `seconds_since_last_change`.
 
+> **Note:** even without `on_silence`, WatchDiff logs a `WARNING` when the silence threshold is exceeded. `on_silence` is optional — `alert_if_no_change_after` alone is enough to surface stale feeds in your log stream.
+
 ### Error callback
 
 Receive a callback whenever a fetch fails, without crashing the watcher:
@@ -1078,6 +1095,19 @@ path = wd.export_snapshots_xlsx("https://example.com", dest="snapshots.xlsx")
 
 All export methods accept `url`, `target` (optional), `limit` (default 500), and `dest`.
 
+Reports CSV schema — **one row per change** (compatible with the TypeScript export):
+
+| Column | Description |
+|---|---|
+| `url` | Watched URL |
+| `label` | Watcher label |
+| `compared_at` | ISO 8601 timestamp of the diff |
+| `kind` | `added` \| `removed` \| `modified` |
+| `before` | Previous value (truncated to 500 chars) |
+| `after` | New value (truncated to 500 chars) |
+
+Snapshots CSV schema — one row per snapshot: `url`, `target`, `captured_at`, `checksum`, `content_preview`.
+
 ### Config file workflow
 
 Generate a ready-to-edit config file, then run all your watchers in one command:
@@ -1138,6 +1168,8 @@ Edit `watchdiff.config.json`:
 
 Config fields are validated on load — invalid URLs, unknown diff modes, out-of-range values, and wrong types are all caught with clear error messages before any monitoring starts.
 
+> **TypeScript config compatibility:** Python accepts both `watchers` and `watches` as the top-level array key, and normalises camelCase field names to snake_case automatically (`diffMode` → `diff_mode`, `ignoreSelectors` → `ignore_selectors`, `maxSnapshots` → `max_snapshots`, etc.). A config file generated by the TypeScript CLI loads without modification.
+
 ```bash
 # Explicit path
 watchdiff run --config watchdiff.config.json
@@ -1644,6 +1676,126 @@ Default: `consecutive_failures=3`, `recovery_checks=1`, `respect_retry_after=Fal
 
 > **Note:** the TypeScript port defaults `consecutiveFailures` to **1** (fire on the first error). Python defaults to **3**. A bare `FailurePolicy()` therefore behaves differently across the two implementations.
 
+## Recovery callback
+
+Run a function the moment a watcher exits failure mode and successfully fetches again.
+
+```python
+from watchdiff import WatchDiff, FailurePolicy
+
+wd = WatchDiff()
+wd.watch(
+    "https://example.com/status",
+    interval=30,
+    failure_policy=FailurePolicy(consecutive_failures=3, recovery_checks=2),
+    on_error=lambda exc, cfg: print(f"Failure: {exc}"),
+    on_recovery=lambda cfg: print(f"{cfg.label} recovered!"),
+)
+wd.start()
+```
+
+`on_recovery` fires once per recovery event — after `recovery_checks` consecutive successes satisfy the `FailurePolicy`. It is called with the `WatchConfig` of the recovered watcher.
+
+## Max retry delay
+
+Cap the exponential backoff delay so it never exceeds a given value:
+
+```python
+wd.watch(
+    "https://example.com",
+    retries=6,
+    retry_delay=1.0,      # base: 1 s, 2 s, 4 s, 8 s, 16 s, 32 s …
+    max_retry_delay=10.0, # …but never more than 10 s
+)
+```
+
+Without `max_retry_delay` the delay grows unboundedly as `retry_delay * 2^attempt`. Setting it avoids very long waits on high `retries` counts.
+
+## Alert on first check
+
+By default the first capture of a URL is stored silently — no alert fires because there is nothing to compare against. Enable `alert_on_first_check` to fire `on_change` (and webhooks) on that first capture anyway:
+
+```python
+wd.watch(
+    "https://example.com/products.json",
+    diff_mode="json",
+    alert_on_first_check=True,
+    on_change=lambda r: print("First snapshot:", r.summary()),
+)
+```
+
+The `DiffReport` is generated by comparing an empty snapshot against the first capture using the normal diff engine — so you get a realistic granular diff (one `ADDED` entry per line/word/key, depending on `diff_mode`) rather than a single blob entry.
+
+## Webhook headers
+
+Merge custom HTTP headers into every webhook POST fired by a watcher — useful for auth tokens or service-specific headers:
+
+```python
+wd.watch(
+    "https://example.com",
+    webhooks=["https://hooks.example.com/notify"],
+    webhook_headers={
+        "X-Api-Key":  "my-secret-token",
+        "X-Source":   "watchdiff",
+    },
+    on_change=lambda r: None,
+)
+```
+
+`webhook_headers` are merged on top of the service-specific headers WatchDiff already adds (e.g. `Content-Type`). They apply only to webhook requests, not to the monitoring fetch itself.
+
+## Retention days
+
+Automatically delete snapshots older than N days after every save:
+
+```python
+wd.watch(
+    "https://example.com",
+    retention_days=30,   # snapshots older than 30 days are removed after each check
+)
+```
+
+`retention_days` and `max_snapshots` can be combined — both pruning strategies run after each save. `retention_days` applies to both the JSON file store (`Store`) and the SQLite store (`SqliteStore`).
+
+## JSON export
+
+Export snapshots and diff reports as JSON for programmatic consumption:
+
+```python
+wd = WatchDiff()
+wd.watch("https://example.com/prices")
+# … after some checks …
+
+reports   = wd.export_reports_json("https://example.com/prices", limit=100)
+snapshots = wd.export_snapshots_json("https://example.com/prices", limit=50)
+
+import json
+print(json.dumps(reports, indent=2))
+```
+
+Both methods return a `list[dict]` (newest last). Each report dict matches `DiffReport.as_dict()`; each snapshot dict contains `url`, `target`, `captured_at`, `checksum`, and `content`.
+
+From the CLI:
+
+```bash
+# Print JSON to stdout
+watchdiff export https://example.com --format json
+watchdiff export https://example.com --type snapshots --format json
+
+# Write to file
+watchdiff export https://example.com --format json --output reports.json
+```
+
+## Slack Block Kit
+
+Slack webhook payloads now use the [Block Kit](https://api.slack.com/block-kit) format instead of plain `text`. Each message contains:
+
+- A **header** block — `WatchDiff — <watcher label>`
+- A **section** block — added/removed/modified counts (e.g. `*3 added*, *1 removed*`)
+- A **context** block — URL and timestamp
+
+The richer layout renders as an attachment card with a clear title and structured change list. No configuration needed; it is applied automatically to any `hooks.slack.com` webhook URL.
+
 ## API reference
 
 ### `WatchDiff`
@@ -1721,6 +1873,11 @@ Register a URL to monitor. All keyword arguments are optional. Returns `self` (c
 | `maintenance_windows` | `list[MaintenanceWindow]` | `[]` | One-time UTC time ranges during which checks are skipped |
 | `active_between` | `ActiveBetween \| None` | `None` | Restrict checks to a recurring daily/weekly time window |
 | `failure_policy` | `FailurePolicy \| None` | `None` | Gate `on_error` until N consecutive failures; require M consecutive successes to recover |
+| `on_recovery` | `Callable[[WatchConfig], None] \| None` | `None` | Called once when the watcher exits failure mode and successfully fetches again |
+| `max_retry_delay` | `float \| None` | `None` | Cap on the exponential backoff delay in seconds — `retry_delay * 2^attempt` is clamped to this value |
+| `alert_on_first_check` | `bool` | `False` | Fire `on_change` (and webhooks) on the very first capture even though there is no previous snapshot |
+| `webhook_headers` | `dict[str, str]` | `{}` | Extra HTTP headers merged into every webhook POST for this watcher |
+| `retention_days` | `int \| None` | `None` | Auto-delete snapshots older than N days after each save |
 
 ```python
 # Chainable
@@ -1959,12 +2116,16 @@ for s in wd.db_status():
     print(s.table, s.diff_mode, s.checks_count, s.changes_count, s.errors_count)
 ```
 
-#### `.history(url)` / `.reports(url)` / `.clear(url)`
+#### `.history(url)` / `.reports(url)` / `.clear(url)` / `.export_*_json()`
 
 ```python
 snaps   = wd.history("https://example.com", limit=10)
 reports = wd.reports("https://example.com", limit=10)
 wd.clear("https://example.com")
+
+# JSON export — returns list[dict] (newest last)
+reports_json   = wd.export_reports_json("https://example.com", limit=100)
+snapshots_json = wd.export_snapshots_json("https://example.com", limit=50)
 ```
 
 ### `DiffReport`
@@ -2329,11 +2490,15 @@ 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
+  snapshot  Show the last stored snapshot for a URL
+  export    Export history or reports to CSV, XLSX or JSON
   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
+  clean     Delete orphan snapshot/report files not referenced by any active watcher
   clear     Delete all stored data for a URL
+  pause     Guidance: pause a watcher via the Python API
+  resume    Guidance: resume a watcher via the Python API
 
 Options for run:
   --target           -t   CSS selector or XPath
@@ -2404,9 +2569,19 @@ Options for diff:
   --storage          -s   Storage directory
   --json                  Output raw JSON
 
+Options for snapshot:
+  --target           -t   CSS selector or XPath
+  --storage          -s   Storage directory
+  --json                  Output snapshot as JSON
+
+Options for clean:
+  --config           -c   Config file to read active watchers from (default watchdiff.config.json)
+  --storage          -s   Storage directory
+  --yes              -y   Skip confirmation prompt
+
 Options for export:
   --type                  What to export: reports | snapshots (default reports)
-  --format                Output format: csv | xlsx (default csv)
+  --format                Output format: csv | xlsx | json (default csv)
   --output           -o   Output file path (prints to stdout if omitted)
   --limit            -n   Max entries to export (default 500)
 

{watchdiff_core-0.2.4 → watchdiff_core-0.2.5}/README.md

@@ -49,6 +49,14 @@ WatchDiff watches web pages, files, APIs, databases, and SSL certificates - then
 | Skip checks during downtime | `maintenance_windows=[MaintenanceWindow(from_="2026-01-15T02:00Z", to="2026-01-15T04:00Z")]` |
 | Restrict checks to business hours | `active_between=ActiveBetween(from_="09:00", to="17:00", days=[0,1,2,3,4], timezone="Europe/Paris")` |
 | Suppress noisy error alerts | `failure_policy=FailurePolicy(consecutive_failures=3, recovery_checks=2)` |
+| Run a callback on recovery | `on_recovery=lambda cfg: print(f"{cfg.label} is back")` |
+| Cap exponential backoff | `max_retry_delay=30.0` — retry delay never exceeds 30 s regardless of attempt count |
+| Alert on very first capture | `alert_on_first_check=True` — fires `on_change` even when no previous snapshot exists |
+| Add custom webhook headers | `webhook_headers={"X-Api-Key": "secret"}` — merged into every webhook POST |
+| Auto-delete old snapshots | `retention_days=30` — snapshots older than N days are pruned after each save |
+| Export history as JSON | `.export_reports_json(url)` / `.export_snapshots_json(url)` |
+| Show last stored snapshot from CLI | `watchdiff snapshot https://example.com` |
+| Remove orphan storage files from CLI | `watchdiff clean` — deletes snap/report files not referenced by any active watcher |
 | Send email on change | `alert=AlertConfig(email=EmailConfig(to="...", smtp=SmtpConfig(...)))` |
 | AI summary of changes | `ai_summary=True, ai_provider=AiProvider(type="gemini", api_key="...")` |
 | Customize the AI prompt | `ai_prompt="Summarize in French."` or `ai_prompt=lambda r: ...` |
@@ -111,6 +119,13 @@ WatchDiff watches web pages, files, APIs, databases, and SSL certificates - then
   - [Maintenance windows](#maintenance-windows)
   - [Active hours](#active-hours)
   - [Failure policy](#failure-policy)
+  - [Recovery callback](#recovery-callback)
+  - [Max retry delay](#max-retry-delay)
+  - [Alert on first check](#alert-on-first-check)
+  - [Webhook headers](#webhook-headers)
+  - [Retention days](#retention-days)
+  - [JSON export](#json-export)
+  - [Slack Block Kit](#slack-block-kit)
 - [API reference](#api-reference)
   - [`.watch()`](#watchurl--)
   - [`.watch_db()`](#watch_dbconnection_string-table--)
@@ -124,7 +139,7 @@ WatchDiff watches web pages, files, APIs, databases, and SSL certificates - then
   - [`.compare_urls()`](#compare_urlsurl_a-url_b--)
   - [`.start_status_server()` / `.stop_status_server()`](#start_status_serverport-host--stop_status_server)
   - [`.pause()` / `.resume()` / `.status()` / `.db_status()`](#pauseurl--resumeurl--status--db_status)
-  - [`.history()` / `.reports()` / `.clear()`](#historyurl--reportsurl--clearurl)
+  - [`.history()` / `.reports()` / `.clear()` / `.export_*_json()`](#historyurl--reportsurl--clearurl--export_json)
   - [`DiffReport`](#diffreport)
   - [`Change`](#change)
   - [`Snapshot`](#snapshot)
@@ -632,6 +647,8 @@ wd.watch(
 
 `SilenceInfo` fields: `url`, `label`, `seconds_since_last_change`.
 
+> **Note:** even without `on_silence`, WatchDiff logs a `WARNING` when the silence threshold is exceeded. `on_silence` is optional — `alert_if_no_change_after` alone is enough to surface stale feeds in your log stream.
+
 ### Error callback
 
 Receive a callback whenever a fetch fails, without crashing the watcher:
@@ -1030,6 +1047,19 @@ path = wd.export_snapshots_xlsx("https://example.com", dest="snapshots.xlsx")
 
 All export methods accept `url`, `target` (optional), `limit` (default 500), and `dest`.
 
+Reports CSV schema — **one row per change** (compatible with the TypeScript export):
+
+| Column | Description |
+|---|---|
+| `url` | Watched URL |
+| `label` | Watcher label |
+| `compared_at` | ISO 8601 timestamp of the diff |
+| `kind` | `added` \| `removed` \| `modified` |
+| `before` | Previous value (truncated to 500 chars) |
+| `after` | New value (truncated to 500 chars) |
+
+Snapshots CSV schema — one row per snapshot: `url`, `target`, `captured_at`, `checksum`, `content_preview`.
+
 ### Config file workflow
 
 Generate a ready-to-edit config file, then run all your watchers in one command:
@@ -1090,6 +1120,8 @@ Edit `watchdiff.config.json`:
 
 Config fields are validated on load — invalid URLs, unknown diff modes, out-of-range values, and wrong types are all caught with clear error messages before any monitoring starts.
 
+> **TypeScript config compatibility:** Python accepts both `watchers` and `watches` as the top-level array key, and normalises camelCase field names to snake_case automatically (`diffMode` → `diff_mode`, `ignoreSelectors` → `ignore_selectors`, `maxSnapshots` → `max_snapshots`, etc.). A config file generated by the TypeScript CLI loads without modification.
+
 ```bash
 # Explicit path
 watchdiff run --config watchdiff.config.json
@@ -1596,6 +1628,126 @@ Default: `consecutive_failures=3`, `recovery_checks=1`, `respect_retry_after=Fal
 
 > **Note:** the TypeScript port defaults `consecutiveFailures` to **1** (fire on the first error). Python defaults to **3**. A bare `FailurePolicy()` therefore behaves differently across the two implementations.
 
+## Recovery callback
+
+Run a function the moment a watcher exits failure mode and successfully fetches again.
+
+```python
+from watchdiff import WatchDiff, FailurePolicy
+
+wd = WatchDiff()
+wd.watch(
+    "https://example.com/status",
+    interval=30,
+    failure_policy=FailurePolicy(consecutive_failures=3, recovery_checks=2),
+    on_error=lambda exc, cfg: print(f"Failure: {exc}"),
+    on_recovery=lambda cfg: print(f"{cfg.label} recovered!"),
+)
+wd.start()
+```
+
+`on_recovery` fires once per recovery event — after `recovery_checks` consecutive successes satisfy the `FailurePolicy`. It is called with the `WatchConfig` of the recovered watcher.
+
+## Max retry delay
+
+Cap the exponential backoff delay so it never exceeds a given value:
+
+```python
+wd.watch(
+    "https://example.com",
+    retries=6,
+    retry_delay=1.0,      # base: 1 s, 2 s, 4 s, 8 s, 16 s, 32 s …
+    max_retry_delay=10.0, # …but never more than 10 s
+)
+```
+
+Without `max_retry_delay` the delay grows unboundedly as `retry_delay * 2^attempt`. Setting it avoids very long waits on high `retries` counts.
+
+## Alert on first check
+
+By default the first capture of a URL is stored silently — no alert fires because there is nothing to compare against. Enable `alert_on_first_check` to fire `on_change` (and webhooks) on that first capture anyway:
+
+```python
+wd.watch(
+    "https://example.com/products.json",
+    diff_mode="json",
+    alert_on_first_check=True,
+    on_change=lambda r: print("First snapshot:", r.summary()),
+)
+```
+
+The `DiffReport` is generated by comparing an empty snapshot against the first capture using the normal diff engine — so you get a realistic granular diff (one `ADDED` entry per line/word/key, depending on `diff_mode`) rather than a single blob entry.
+
+## Webhook headers
+
+Merge custom HTTP headers into every webhook POST fired by a watcher — useful for auth tokens or service-specific headers:
+
+```python
+wd.watch(
+    "https://example.com",
+    webhooks=["https://hooks.example.com/notify"],
+    webhook_headers={
+        "X-Api-Key":  "my-secret-token",
+        "X-Source":   "watchdiff",
+    },
+    on_change=lambda r: None,
+)
+```
+
+`webhook_headers` are merged on top of the service-specific headers WatchDiff already adds (e.g. `Content-Type`). They apply only to webhook requests, not to the monitoring fetch itself.
+
+## Retention days
+
+Automatically delete snapshots older than N days after every save:
+
+```python
+wd.watch(
+    "https://example.com",
+    retention_days=30,   # snapshots older than 30 days are removed after each check
+)
+```
+
+`retention_days` and `max_snapshots` can be combined — both pruning strategies run after each save. `retention_days` applies to both the JSON file store (`Store`) and the SQLite store (`SqliteStore`).
+
+## JSON export
+
+Export snapshots and diff reports as JSON for programmatic consumption:
+
+```python
+wd = WatchDiff()
+wd.watch("https://example.com/prices")
+# … after some checks …
+
+reports   = wd.export_reports_json("https://example.com/prices", limit=100)
+snapshots = wd.export_snapshots_json("https://example.com/prices", limit=50)
+
+import json
+print(json.dumps(reports, indent=2))
+```
+
+Both methods return a `list[dict]` (newest last). Each report dict matches `DiffReport.as_dict()`; each snapshot dict contains `url`, `target`, `captured_at`, `checksum`, and `content`.
+
+From the CLI:
+
+```bash
+# Print JSON to stdout
+watchdiff export https://example.com --format json
+watchdiff export https://example.com --type snapshots --format json
+
+# Write to file
+watchdiff export https://example.com --format json --output reports.json
+```
+
+## Slack Block Kit
+
+Slack webhook payloads now use the [Block Kit](https://api.slack.com/block-kit) format instead of plain `text`. Each message contains:
+
+- A **header** block — `WatchDiff — <watcher label>`
+- A **section** block — added/removed/modified counts (e.g. `*3 added*, *1 removed*`)
+- A **context** block — URL and timestamp
+
+The richer layout renders as an attachment card with a clear title and structured change list. No configuration needed; it is applied automatically to any `hooks.slack.com` webhook URL.
+
 ## API reference
 
 ### `WatchDiff`
@@ -1673,6 +1825,11 @@ Register a URL to monitor. All keyword arguments are optional. Returns `self` (c
 | `maintenance_windows` | `list[MaintenanceWindow]` | `[]` | One-time UTC time ranges during which checks are skipped |
 | `active_between` | `ActiveBetween \| None` | `None` | Restrict checks to a recurring daily/weekly time window |
 | `failure_policy` | `FailurePolicy \| None` | `None` | Gate `on_error` until N consecutive failures; require M consecutive successes to recover |
+| `on_recovery` | `Callable[[WatchConfig], None] \| None` | `None` | Called once when the watcher exits failure mode and successfully fetches again |
+| `max_retry_delay` | `float \| None` | `None` | Cap on the exponential backoff delay in seconds — `retry_delay * 2^attempt` is clamped to this value |
+| `alert_on_first_check` | `bool` | `False` | Fire `on_change` (and webhooks) on the very first capture even though there is no previous snapshot |
+| `webhook_headers` | `dict[str, str]` | `{}` | Extra HTTP headers merged into every webhook POST for this watcher |
+| `retention_days` | `int \| None` | `None` | Auto-delete snapshots older than N days after each save |
 
 ```python
 # Chainable
@@ -1911,12 +2068,16 @@ for s in wd.db_status():
     print(s.table, s.diff_mode, s.checks_count, s.changes_count, s.errors_count)
 ```
 
-#### `.history(url)` / `.reports(url)` / `.clear(url)`
+#### `.history(url)` / `.reports(url)` / `.clear(url)` / `.export_*_json()`
 
 ```python
 snaps   = wd.history("https://example.com", limit=10)
 reports = wd.reports("https://example.com", limit=10)
 wd.clear("https://example.com")
+
+# JSON export — returns list[dict] (newest last)
+reports_json   = wd.export_reports_json("https://example.com", limit=100)
+snapshots_json = wd.export_snapshots_json("https://example.com", limit=50)
 ```
 
 ### `DiffReport`
@@ -2281,11 +2442,15 @@ 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
+  snapshot  Show the last stored snapshot for a URL
+  export    Export history or reports to CSV, XLSX or JSON
   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
+  clean     Delete orphan snapshot/report files not referenced by any active watcher
   clear     Delete all stored data for a URL
+  pause     Guidance: pause a watcher via the Python API
+  resume    Guidance: resume a watcher via the Python API
 
 Options for run:
   --target           -t   CSS selector or XPath
@@ -2356,9 +2521,19 @@ Options for diff:
   --storage          -s   Storage directory
   --json                  Output raw JSON
 
+Options for snapshot:
+  --target           -t   CSS selector or XPath
+  --storage          -s   Storage directory
+  --json                  Output snapshot as JSON
+
+Options for clean:
+  --config           -c   Config file to read active watchers from (default watchdiff.config.json)
+  --storage          -s   Storage directory
+  --yes              -y   Skip confirmation prompt
+
 Options for export:
   --type                  What to export: reports | snapshots (default reports)
-  --format                Output format: csv | xlsx (default csv)
+  --format                Output format: csv | xlsx | json (default csv)
   --output           -o   Output file path (prints to stdout if omitted)
   --limit            -n   Max entries to export (default 500)
 

{watchdiff_core-0.2.4 → watchdiff_core-0.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "watchdiff-core"
-version = "0.2.4"
+version = "0.2.5"
 description = "Lightweight web change monitoring library - clean diffs, AI summaries, file/API/SSL/DB monitoring, structured alerts."
 readme = "README.md"
 requires-python = ">=3.9"

{watchdiff_core-0.2.4 → watchdiff_core-0.2.5}/tests/test_watchdiff.py

@@ -224,7 +224,10 @@ class TestNotifier:
             webhooks=["https://hooks.slack.com/services/test"], webhook_retries=0
         ))
         payload = json.loads(httpx_mock.get_requests()[0].content)
-        assert "text" in payload
+        assert "blocks" in payload
+        block_types = [b["type"] for b in payload["blocks"]]
+        assert "header" in block_types
+        assert "section" in block_types
 
     def test_sends_generic_webhook(self, httpx_mock):
         httpx_mock.add_response(url="https://my-server.example.com/hook", status_code=200)