hookrecon 0.9.2__tar.gz

hookrecon-0.9.2/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.12", "3.13", "3.14"]
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e .
+      - run: python -m unittest discover tests -v
+      - name: Exit-code smoke (no Stripe/DB needed)
+        shell: bash
+        # GitHub's bash runs with -e -o pipefail: a bare `cmd; rc=$?` dies on the
+        # expected non-zero exit, so every probe must use the `|| rc=$?` pattern.
+        run: |
+          cd "$(mktemp -d)"
+          rc=0
+          hookrecon check >/dev/null 2>&1 || rc=$?
+          [ "$rc" -eq 2 ] || { echo "missing config: expected exit 2, got $rc"; exit 1; }
+          echo '{not json' > hookrecon.config.json
+          rc=0
+          hookrecon check >/dev/null 2>&1 || rc=$?
+          [ "$rc" -eq 2 ] || { echo "malformed config: expected exit 2, got $rc"; exit 1; }
+          echo "exit-code smoke ok"

hookrecon-0.9.2/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    # One-time setup required before the first tag: on PyPI, open hookrecon ->
+    # Publishing -> add this GitHub repo as a "trusted publisher"
+    # (owner/repo: this repo, workflow: release.yml, environment: pypi).
+    # Trusted publishing uses OIDC — no API token stored in GitHub.
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # PyPI trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

hookrecon-0.9.2/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/

hookrecon-0.9.2/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 hookrecon contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note: hookrecon's Postgres dependency, psycopg, is LGPL-3.0-only. It is used
+here as an unmodified pip-installed dependency; hookrecon itself is MIT.

hookrecon-0.9.2/PKG-INFO

@@ -0,0 +1,339 @@
+Metadata-Version: 2.5
+Name: hookrecon
+Version: 0.9.2
+Summary: Find Stripe payments that never reached your database — read-only Stripe↔Postgres reconciliation CLI
+Project-URL: Repository, https://github.com/Vasram/hookrecon
+Project-URL: Issues, https://github.com/Vasram/hookrecon/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: psycopg[binary]<4,>=3.3
+Requires-Dist: stripe<17,>=16
+Description-Content-Type: text/markdown
+
+# hookrecon — find Stripe payments that never reached your database
+
+<!-- LAUNCH TODO — demo GIF (see instructions below, then delete this comment):
+<p align="center">
+  <img src="docs/hookrecon.gif"
+       alt="hookrecon finding Stripe payments that never reached the database — webhook failed, order missing"
+       width="720">
+</p>
+-->
+
+[![CI](https://github.com/Vasram/hookrecon/actions/workflows/ci.yml/badge.svg)](https://github.com/Vasram/hookrecon/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+<!-- LAUNCH TODO: pehli PyPI publish ke baad (tag v0.9.2 push → release.yml auto-publish) is
+     comment ko hata do — tab tak shields.io "package or version not found" (red) dikhata hai:
+[![PyPI](https://img.shields.io/pypi/v/hookrecon)](https://pypi.org/project/hookrecon/)
+-->
+
+**hookrecon is a read-only CLI that reconciles Stripe against your Postgres database.** It lists every completed payment whose webhook never made it into your app — with the amount, the customer's object id, and a deep link to the event in your Stripe dashboard. Zero install, zero signup, zero telemetry.
+
+> **The problem:** your customer pays, Stripe shows the payment as **succeeded** — but the order, subscription, or payment row never appears in your database. The webhook failed silently. It happens more often than anyone admits: a CDN or WAF answered Stripe with `200 OK` before the request ever reached your app, a deploy broke your handler, or your handler threw an error *after* acknowledging the event. [Stripe retries failed webhooks for up to 3 days](https://docs.stripe.com/webhooks/process-undelivered-events), then gives up forever. Nobody notices until a customer emails support.
+
+**If that's you right now** — payment succeeded but no order created, Stripe webhook not updating your database, webhooks silently failing in production, Stripe events missing after a deploy — **hookrecon finds every affected payment in one command**, along with the money involved.
+
+---
+
+## Why Stripe webhooks fail silently
+
+Your webhook handler *looks* healthy in the dashboard because most failures happen **after** something returns `200 OK`:
+
+| Failure mode | What actually happens |
+|---|---|
+| **CDN / WAF / proxy acks early** | Cloudflare or your load balancer returns `200 OK` to Stripe; the request never reaches your handler. Stripe marks the delivery *successful*. |
+| **Handler throws after acking** | Your code accepted the event, then crashed on the DB write (migration missing, RLS denied, connection pool exhausted). Stripe already got its `200`. |
+| **Deploy breaks the handler** | New version renamed a column, dropped an event type, or the signing-secret env var didn't survive the deploy. Every payment since then is missing. |
+| **Endpoint timeout** | Your handler does too much work before responding; Stripe times out and the retry chain starts — and gives up 3 days later. |
+
+Stripe's dashboard shows you *delivery* status — it cannot tell you whether the **payment reached your database**. That gap is exactly what hookrecon closes: it diff's Stripe's records against your own tables and tells you which completed payments never landed, how much money is involved, and where to click to fix each one.
+
+## Quick start (60 seconds)
+
+**1. Run it** — no Python needed on your machine (uv installs it automatically):
+
+```bash
+uvx hookrecon init
+```
+
+Prefer pipx or already have Python? `pipx install hookrecon` (needs Python 3.10+), then `hookrecon init`.
+
+**2. Answer 3 questions.** The wizard writes `hookrecon.config.json` pre-filled with the 3 canonical checks — you just edit the table and column names to match your schema.
+
+**3. Point it at your secrets** (env var *names* live in the config; the values never do):
+
+```bash
+export STRIPE_SECRET_KEY="sk_live_..."     # or rk_live_... restricted key — see Trust below
+export DATABASE_URL="postgresql://user:pass@host/db?sslmode=require"
+```
+
+**4. Reconcile:**
+
+```bash
+hookrecon check
+```
+
+`hookrecon doctor` runs the same preflight first — config, env vars, Stripe API, database connection, and a write-privilege audit — if anything is off, it tells you exactly what.
+
+## What you get
+
+```text
+hookrecon — Stripe ↔ database reconciliation
+Lookback: 7 days (Sep 24 – Oct 1) · 1,842 events scanned · live mode
+
+✗ completed checkout without order — 3 drifts, ≈ $249.00
+    evt_1P9xK…  cs_live…a1  $89.00   Sep 28  https://dashboard.stripe.com/events/evt_1P9…
+    evt_1P2mQ…  cs_live…b7  $120.00  Sep 30  https://dashboard.stripe.com/events/evt_1P2…
+    evt_1P8zL…  cs_live…c2  $40.00   Oct 1   https://dashboard.stripe.com/events/evt_1P8…
+    → Fix: open the event URL → "Resend" after fixing the handler, or insert the row manually.
+
+✓ paid invoice not in billing table — clean
+✗ captured payment without payment record — 1 drift, ≈ $12.00
+    …
+
+Summary: 4 drifts, ≈ $261.00 affected · run `hookrecon doctor` if any check errored.
+```
+
+Every drift row deep-links to the event in your Stripe dashboard — open it, fix your handler, hit **Resend**, and your app processes the payment like nothing happened.
+
+## How it works
+
+1. **Fetch** — `hookrecon` pulls recent Stripe events (`checkout.session.completed`, `invoice.payment_succeeded`, `payment_intent.succeeded`, or any types you configure) over your lookback window.
+2. **Diff** — for each event it runs *your* SQL (one read-only `SELECT` per check, bound as a parameterized query) against your database. **0 rows = the record the webhook should have created is missing = drift.**
+3. **Report** — drifts with amounts per currency, deep links, and exit codes your CI can act on.
+
+**What hookrecon is not:** it never writes to your database, never resends events itself, never hosts anything, and has no daemon. It's the diff tool — detection stays local and read-only, so you can trust it with production credentials.
+
+<details>
+<summary><strong>Under the hood — what happens when you run <code>check</code></strong></summary>
+
+1. **Load + validate config** — `hookrecon.config.json` is read and validated: each `sql` must be a single read-only `SELECT` referencing `$1`, check names must be unique, at most 20 distinct event types. Errors name the offending check and exit 2.
+2. **Resolve the key** — the secret comes from the env var *named* in your config; the key's prefix (`sk_test_`, `sk_live_`, `rk_…`) decides the mode shown in the report. Missing → exit 2 with a hint.
+3. **Fetch Stripe events** — `GET /v1/events` with `created ≥ now − lookback` and your configured types; auto-paginates, dedupes by event id, stops at `--limit` (and says so if it did).
+4. **Connect to Postgres** — your `DATABASE_URL`, one independent transaction per statement, nothing ever written.
+5. **Diff** — for every event matching a check: the `param` path (default `data.object.id`) is pulled out of the event, your SQL runs with that id bound as a parameterized query. **0 rows = drift**; an SQL error marks only that check as errored and the others continue.
+6. **Render** — the human table (or `--json`), money summed per currency, every drift deep-linked to its Stripe dashboard event.
+7. **Exit code** — `0` clean · `1` drift found · `2` couldn't run reliably. Cron/CI acts on the code, not the output.
+
+Nothing in these steps ever writes to your database or calls a Stripe write endpoint.
+</details>
+
+## The three commands
+
+| Command | What it does |
+|---|---|
+| `hookrecon init` | Interactive wizard: writes a starter `hookrecon.config.json` (3 canonical checks), prints the restricted-key recipe, ends with a `doctor` preflight |
+| `hookrecon check` | The product: fetches Stripe events, runs your per-check SQL, reports drift |
+| `hookrecon doctor` | Preflight only: env vars → Stripe events ping → DB connection → per-check SQL dry-run → write-privilege audit |
+
+`check` flags:
+
+| Flag | Meaning |
+|---|---|
+| `--since <Nd>` | Override the configured lookback (e.g. `30d`) |
+| `--json` | Machine-readable JSON report instead of the table (CI/cron-friendly) |
+| `--show-sql` | Print every SQL statement with its param before running it |
+| `--limit <n>` | Safety cap on Stripe events fetched (default 10000; warns if hit) |
+| `--quiet` | Only drift lines + summary, no banner |
+
+Exit codes — act on the code, not the output:
+
+| Exit | Meaning |
+|---|---|
+| `0` | Ran fully, no drift (also: `doctor` all green) |
+| `1` | Ran fully, **drift found** |
+| `2` | Could not run reliably — config/fatal error, or any check's SQL errored. Usage errors also exit 2 — same class. |
+
+`init` exits 0 once the config is written — even if the preflight that follows finds issues; it exits 2 only if `hookrecon.config.json` already exists.
+
+## Configuration reference
+
+`hookrecon init` writes this starter config — edit the table/column names, not the structure:
+
+```json
+{
+  "stripe": {
+    "apiKeyEnv": "STRIPE_SECRET_KEY",
+    "lookbackDays": 7
+  },
+  "database": {
+    "urlEnv": "DATABASE_URL"
+  },
+  "checks": [
+    {
+      "name": "completed checkout without order",
+      "event": "checkout.session.completed",
+      "sql": "SELECT 1 FROM orders WHERE stripe_session_id = $1",
+      "money": "data.object.amount_total",
+      "param": "data.object.id"
+    },
+    {
+      "name": "paid invoice not in billing table",
+      "event": "invoice.payment_succeeded",
+      "sql": "SELECT 1 FROM subscriptions WHERE stripe_invoice_id = $1",
+      "money": "data.object.amount_paid",
+      "param": "data.object.id"
+    },
+    {
+      "name": "captured payment without payment record",
+      "event": "payment_intent.succeeded",
+      "sql": "SELECT 1 FROM payments WHERE stripe_payment_intent_id = $1",
+      "money": "data.object.amount_received",
+      "param": "data.object.id"
+    }
+  ]
+}
+```
+
+| Field | Rules |
+|---|---|
+| `event` | Exact Stripe event type. Unknown types are allowed with a warning — but they're sent to Stripe as-is, so a typo'd type fails the fetch with a Stripe error. Max 20 distinct types (Stripe's own limit). |
+| `sql` | A single SELECT. **0 rows = drift** (the record is missing — the webhook never landed), **≥1 row = processed fine.** Your SQL must reference `$1` at least once — it is bound as a parameterized query, never string-interpolated. |
+| `param` | JSON path into the Stripe event, default `data.object.id`. |
+| `money` | Optional JSON path to an integer amount (minor units) for the "≈ $X affected" summary. Absent → that check contributes no money figure. |
+| `name` | Free text shown in the report — must be unique across checks. |
+
+**Suppress known false positives with your own `WHERE`** — imported customers, test orders, free-trial invoices:
+
+```json
+{
+  "name": "completed checkout without order (real customers only)",
+  "event": "checkout.session.completed",
+  "sql": "SELECT 1 FROM orders WHERE stripe_session_id = $1 AND customer_id NOT IN (SELECT id FROM test_accounts)"
+}
+```
+
+The SQL is yours — anything from a simple existence check to joins against your own tables works, as long as it's one read-only `SELECT` and returns 0 rows when something went missing.
+
+## Automation: cron, CI, and alerting
+
+`check` is built for unattended runs — exit code `1` means drift, `--json` gives you structured output:
+
+```bash
+# crontab — every hour, log the JSON report
+0 * * * * cd /srv/yourapp && hookrecon check --quiet --json >> /var/log/hookrecon.json 2>&1
+
+# Slack yourself only when there's drift
+hookrecon check --quiet --json | jq -e '.checks[] | select(.driftCount > 0)' \
+  || curl -s -X POST -d '{"text":"hookrecon found missing payments"}' $SLACK_WEBHOOK
+```
+
+GitHub Actions (secrets, not plaintext):
+
+```yaml
+- name: Stripe ↔ DB reconciliation
+  env:
+    STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
+    DATABASE_URL: ${{ secrets.DATABASE_URL }}
+  run: uvx hookrecon check --quiet
+```
+
+## Trust & security — why you can paste your DB URL into this
+
+The reason you'd hesitate is the reason this section exists:
+
+- **Read-only end to end.** hookrecon only issues `SELECT` statements to your database and only reads from Stripe's API. It never writes to your DB, never calls a Stripe write endpoint.
+- **The SELECT lint is a convenience, not a sandbox.** Postgres functions (`setval`, `dblink`, …) and sequence writes sit outside table privileges — a **read-only DB user is the real boundary**, and `doctor`'s audit tells you when you forgot one.
+- **No telemetry. No outbound calls except the Stripe API and your own database.** The source is a handful of small Python files — read it in one sitting.
+- **`--show-sql`.** Print every statement with its bound param before it runs. Verify exactly what happens.
+- **Write-privilege audit.** `doctor` extracts every table your checks touch and asks Postgres itself — `has_table_privilege(current_user, table, ...)` for INSERT/UPDATE/DELETE/TRUNCATE — which catches PUBLIC grants, inherited roles, and superusers that `information_schema` views miss. If the connected user *could* write, you get: *"⚠ connected user can WRITE to \<table\> — use a read-only user; hookrecon never writes, but don't take our word for it."*
+- **Secrets stay in env vars.** The config file stores env var *names* (`apiKeyEnv`, `urlEnv`), never values. Your key and DSN are never echoed. The config file is commit-safe.
+
+Give hookrecon a Postgres role that can only read:
+
+<details>
+<summary>Read-only Postgres user recipe</summary>
+
+```sql
+CREATE ROLE hookrecon_ro LOGIN PASSWORD 'choose-a-long-password';
+GRANT CONNECT ON DATABASE yourdb TO hookrecon_ro;
+GRANT USAGE ON SCHEMA public TO hookrecon_ro;
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO hookrecon_ro;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO hookrecon_ro;
+```
+
+Caveat: `ALTER DEFAULT PRIVILEGES` only covers tables created by the role that runs it. Run it as (or once per) whichever role creates your app's tables, so tables added later are readable too.
+</details>
+
+On the Stripe side, create a **restricted key** (Dashboard → Developers → API keys) with `Events: Read` — the only API hookrecon calls — plus Read on Checkout Sessions, Invoices, and Payment Intents if you keep the default checks. `doctor` pings `GET /v1/events?limit=1` rather than `/v1/balance` on purpose: the balance endpoint returns 403 for exactly this Events:Read-only key, while the events ping validates both auth and the one permission the tool actually needs.
+
+## Troubleshooting — every error, and its fix
+
+| You see | Why | Fix |
+|---|---|---|
+| `config file not found: hookrecon.config.json` | You're running from a directory that has no config — hookrecon reads it from the current directory | `cd` into your project folder, or run `hookrecon init` there once to create it |
+| `environment variable STRIPE_SECRET_KEY is not set` | The env var named in your config isn't set in this shell | Bash: `export STRIPE_SECRET_KEY="sk_..."` · PowerShell: `$env:STRIPE_SECRET_KEY = "sk_..."` · cmd: `set STRIPE_SECRET_KEY=sk_...` · persistent on Windows: `setx STRIPE_SECRET_KEY "sk_..."` then reopen the terminal |
+| `Invalid API Key provided` | Key typo'd, or test key against live expectations | Copy it again from Dashboard → Developers → API keys; check test vs live mode |
+| Stripe ping fails with a permissions/403 error | Restricted key is missing `Events: Read` (or the object reads your checks need) | Dashboard → Restricted keys → add `Events: Read` (+ Checkout Sessions / Invoices / Payment Intents: Read) |
+| `relation "orders" does not exist` | The check's SQL names a table your DB doesn't have (starter config uses example names) | Edit `hookrecon.config.json` — change `FROM orders` etc. to your real tables/columns, or delete checks you don't need |
+| `connection refused` / connection timeout | Wrong host/port, or SSL required | Append `?sslmode=require` to your `DATABASE_URL`; check firewall; for Neon/Supabase use their provided pooled connection string |
+| `the query has 0 placeholders but 1 parameters were passed` | Your check SQL doesn't use `$1` | Add it: `... WHERE your_stripe_id_column = $1` |
+| `SQL must start with SELECT` / `forbidden keyword 'UPDATE'` | The SQL lint rejected something that isn't one read-only SELECT | One `SELECT` statement only; filter with `WHERE`, no CTEs (`WITH`) in v1 |
+| `duplicate check name(s)` | Two checks share a `name` | Give each check a unique name |
+| `unknown config key 'urlenv' — ignored (typo?)` | A key in the config isn't recognized — likely a typo | Fix the spelling (e.g. `urlenv` → `urlEnv`); unknown keys are ignored, defaults apply |
+| `⚠ fetch stopped at --limit N — results are incomplete` | More events matched than `--limit` | Raise `--limit` or narrow `--since` |
+| `0 events in lookback — widen --since if this is unexpected` | No events matched — wrong mode? | Check the key: `sk_test_` sees only test-mode payments, `sk_live_` only live. Widen `--since` |
+| `hookrecon: command not found` (after install) | The install dir isn't on `PATH` | uv: add `%USERPROFILE%\.local\bin` to `PATH` · pipx: run `pipx ensurepath`, reopen the terminal |
+| `hookrecon.config.json already exists — not overwriting` | `init` never clobbers | Delete or rename the old file first |
+
+## FAQ
+
+**How long does Stripe retry failed webhooks?**
+Up to 3 days with exponential backoff. After that the event is marked failed and *never retried* — the payment stays completed in Stripe and permanently missing from your app unless someone notices. hookrecon sees events up to **30 days back** (Stripe's API retention), so run it within that window — hourly cron is the point.
+
+**My webhook returns 200 OK but my database isn't updated — how is that possible?**
+Because `200 OK` was sent by something that isn't your handler: a CDN/WAF/ingress acking early, or your handler crashing *after* acknowledging. Stripe sees success; your DB never got the write. That's the exact failure hookrecon detects.
+
+**How do I find Stripe payments missing from my database?**
+That's this tool: `uvx hookrecon check` diffs Stripe's completed payments against your tables and lists every one that never landed, with amounts and dashboard deep links.
+
+**Is it safe to give a CLI my production database URL?**
+That's the design center: run it as a read-only Postgres user (recipe above), watch `doctor`'s write-privilege audit confirm your grants, use `--show-sql` to see every statement before it runs. No telemetry, no third-party calls, config file holds env-var names only. The whole codebase is a few small Python files.
+
+**Does hookrecon support MySQL, MongoDB, or SQLite?**
+Postgres only in v1 — deliberately one dialect, done well. Open an issue if you need another; demand decides the roadmap.
+
+**Does it work with Shopify, Razorpay, or Paddle?**
+Stripe only in v1, for the same reason. Star/watch the repo if you want those first.
+
+**Why does it say 0 events?**
+Three usual reasons: your lookback window is too short (`--since 30d`), you're using a test key but looking for live payments (or vice versa), or your handler is actually working — `0 events` with no drift is a good result.
+
+**Why do $0 invoices show as drift?**
+Free trials legitimately fire `invoice.payment_succeeded` with `amount_paid: 0`. If you don't track trials in your billing table, suppress them with a `WHERE amount_paid`-style filter in your own SQL.
+
+**Can hookrecon fix the missing rows for me?**
+No — it's read-only by design, which is what makes it safe to point at production. Each drift row links to the event in Stripe's dashboard where **Resend** replays it to your (now-fixed) handler, or you insert the row manually.
+
+**Does it work with Stripe test mode?**
+Yes — it detects test keys and says so loudly, since test-mode results cover test-mode payments only.
+
+## Roadmap
+
+v1 is deliberately small. What gets built next is decided by demand, not speculation — [open an issue](../../issues) or star/watch the repo to vote with your attention:
+
+- MySQL / SQLite / MongoDB dialects
+- Shopify, Razorpay, Paddle gateways
+- A scheduled runner with alerting (the CLI stays free and dumb)
+- A "delivery status" side-report (events Stripe never delivered at all)
+
+## Contributing & development
+
+```bash
+git clone https://github.com/Vasram/hookrecon && cd hookrecon
+python -m pip install -e .
+python -m unittest discover tests
+```
+
+53 tests, no test frameworks beyond stdlib `unittest`, no network in the suite. Bug reports with your (redacted) config shape are the most useful contributions right now.
+
+## License
+
+[MIT](LICENSE) — the `psycopg` dependency is LGPL-3.0-only (unmodified pip dependency; see LICENSE).
+
+---
+
+*If hookrecon found money your database forgot, a ⭐ helps the next developer find it before their customers do.*

hookrecon-0.9.2/PLAN.md

@@ -0,0 +1,191 @@
+# hookrecon — Implementation Plan (Python)
+
+**Status:** DRAFT for review · **Date:** 2026-10-01 · **Source:** SRS v1.0 + verified investigation (Stripe docs, psycopg docs, packaging docs, PyPI/npm landscape). All facts below carry sources in §10.
+
+---
+
+## 0. SRS amendments — review these first
+
+The SRS said TypeScript. The stack pivots to Python; everything else in the SRS (3 commands, Postgres-only, read-only wedge, config spec, exit codes) stands. Investigation also surfaced four places where the SRS itself should change:
+
+| # | SRS says | Plan says | Why (verified) |
+|---|---|---|---|
+| A1 | TypeScript, Node ≥ 20, ESM; deps `stripe`, `pg`, `commander` | **Python ≥ 3.10**; deps `stripe>=16,<17`, `psycopg[binary]>=3.3,<4`, argparse (stdlib) | Owner decision. psycopg 3 is the recommended Postgres driver; argparse is stdlib (no commander equivalent needed). `uvx hookrecon` = npx parity: uv auto-downloads Python if missing. |
+| A2 | `doctor` pings Stripe via `GET /v1/balance` | Ping via **`GET /v1/events?limit=1`** | `/v1/balance` returns **403** on exactly the Events:Read-only restricted key the SRS's own recipe (§9.1) tells users to create. Events ping validates auth *and* the one permission the tool needs. |
+| A3 | Write-privilege audit via `information_schema.role_table_grants WHERE grantee = current_user` | Audit via **`has_table_privilege(current_user, tbl, priv)`** per table | `role_table_grants` misses grants to `PUBLIC` (the default on many managed Postgres setups) and inherited roles — i.e. it misses the most common real misconfiguration. `has_table_privilege` catches PUBLIC, inheritance, and superuser. |
+| A4 | Check SQL uses `$1` placeholder | Keep `$1` in **config** (SRS contract + Postgres culture), translate `$n → %s` at bind time | psycopg 3 only accepts `%s`/`%(name)s`; its extended protocol rewrites to server-side `$n` anyway. Translation is one regex, marked with a `ponytail:` ceiling comment. |
+| A5 | `node:test` + one test file | `unittest` (stdlib), same one-file spirit + one small SQL-lint file | Python mirror of §11; lint is a trust boundary so it gets its own asserts. |
+
+---
+
+## 1. Stack (final)
+
+| Decision | Choice | Notes |
+|---|---|---|
+| Language | Python ≥ 3.10, sync only (no asyncio) | Floor bound by psycopg 3 (`>=3.10`); stripe-python needs only 3.9. uvx users don't care about the floor; pipx users do. |
+| Distribution | **PyPI** + `uvx hookrecon` (primary), `pipx install hookrecon` (fallback) | uv's `python-downloads` is `automatic` — `uvx` works with **no Python installed**. Windows gets `.exe` shims (PATH note goes in README). |
+| Runtime deps | `stripe>=16,<17` · `psycopg[binary]>=3.3,<4` | `psycopg[binary]` wheels bundle libpq — no system Postgres client. psycopg is LGPL-3.0-only: fine for an MIT CLI (unmodified pip dependency); one README line. |
+| CLI parsing | `argparse` (stdlib) | 3 subcommands + flags fully covered. argparse exits **2** on usage errors — same class as SRS exit 2; document it. |
+| Config | `hookrecon.config.json` (unchanged) | No parser dep needed; stdlib `json`. |
+| Tests | `unittest` + `unittest.mock`-free fakes | SRS §11 mirrored: fake "run SQL" callable, no DB, no network, no framework. |
+| Build backend | hatchling | 2026 packaging recommendation for a single pure-Python package. |
+| Publish | PyPI **Trusted Publishing** (OIDC, `pypa/gh-action-pypi-publish`) via GitHub Actions on tag | No API tokens. |
+| Name | `hookrecon` | **Free on PyPI** (registry 404s today). Also free of conflicts on npm. Register at M6 publish time. |
+
+---
+
+## 2. Repository layout
+
+```
+hookrecon/
+  pyproject.toml            # hatchling, [project.scripts] hookrecon = "hookrecon.cli:main"
+  README.md                 # GIF at top (record at M4), restricted-key recipe, uvx line
+  LICENSE                   # MIT (+ one line noting psycopg dependency is LGPL)
+  .github/workflows/
+    ci.yml                  # unittest matrix: 3.10 / 3.12 / 3.13 × ubuntu + windows
+    release.yml             # tag → build → PyPI trusted publish
+  src/hookrecon/
+    __init__.py             # __version__
+    cli.py                  # argparse wiring + init/check/doctor orchestration
+    config.py               # load + validate hookrecon.config.json
+    stripe_client.py        # fetch events: pagination, dedupe, --limit, mode detect
+    db.py                   # connect, SELECT lint, $n→%s, run check SQL, dry-run, privilege audit
+    drift.py                # pure diff logic — the only nontrivial module (no I/O)
+    report.py               # ANSI table + JSON rendering, money formatting
+  tests/
+    drift_test.py           # SRS §11's four cases (fake sql fn) → shipped as test_drift.py
+    sql_test.py             # SELECT-lint + $n→%s translation (trust boundary) → test_sql.py
+```
+
+---
+
+## 3. Module design
+
+### `config.py` — load + validate
+- Resolve env-var **names** from config (defaults: `STRIPE_SECRET_KEY`, `DATABASE_URL`); values come only from the environment (SRS §9.5 — config file stays commit-safe).
+- Validate: `lookbackDays` positive int; `checks` non-empty; per check: `name`, `event`, `sql`, optional `param` (default `data.object.id`), optional `money`.
+- `event`: validated against a small known-list (the 3 canonical types); unknown types allowed with a warning.
+- Distinct event types across checks **> 20 → validation error** (Stripe `types` filter accepts max 20 per call; 3 canonical checks make this theoretical).
+- **SQL lint (trust boundary):** strip `--` and `/* */` comments → first token must be `SELECT` → reject `;` (except one optional trailing) → reject word-boundary write/DDL keywords (`INSERT UPDATE DELETE TRUNCATE DROP ALTER CREATE GRANT REVOKE COPY CALL DO VACUUM ANALYZE WITH`). `WITH`/CTEs rejected in v1 — users suppress false positives with plain `WHERE`, per SRS §7.
+- Any validation error → `exit 2` naming the offending check (SRS §7).
+
+### `stripe_client.py` — fetch events
+- Key from env (name from config). Mode detect by prefix (`rk_live_` / `sk_live_` / `rk_test_` / `rk_test_`) for the banner; **loud warning on test keys** (SRS §9.1).
+- `stripe.api_key = key`, then `stripe.Event.list(created={"gte": now - lookback}, types=[...], limit=100).auto_paging_iter()`.
+- Break at `--limit` (default 10000) → set `capped=True` → warn "results incomplete" in report.
+- **Dedupe by `event.id`** (pages can overlap while objects update mid-scan).
+- **Lookback > 30 days → warn**: "Stripe retains events for 30 days; older events are silently absent" — warn and continue (do not silently undercount).
+- Events converted with `.to_dict()`; a tiny hand-rolled path getter `get_path(obj, "data.object.amount_total")` (split `.`, walk dict) serves both `param` and `money`.
+
+### `db.py` — connection, binding, audit
+- `psycopg.connect(dsn)` — full `postgresql://…?sslmode=require` URL straight from env (psycopg accepts libpq conninfo/URI). On connect failure: show `pg` error verbatim + SSL hint (SRS §10).
+- **Binding:** lint (§ above) → `re.sub(r"\$\d+", "%s", sql)` → `conn.execute(sql, [param_value])`. `ponytail:` naive regex could match `$1` inside a string literal — acceptable ceiling; the read-only DB user is the real boundary.
+- **Free safety net:** psycopg 3's extended protocol refuses multi-statement strings at the driver level, so even a lint miss can't append `; DELETE …`.
+- **Table extraction for the audit:** `EXPLAIN (FORMAT JSON) <user SQL>` with the param bound — planner only, **never `ANALYZE`** (that executes) — walk the plan tree collecting `Relation Name`. Fallback: regex over `FROM|JOIN` if EXPLAIN errors. (Regex alone misses subqueries/quoted/schema-qualified names.)
+- **Privilege audit:** per extracted table —
+  `SELECT has_table_privilege(current_user, %s, 'INSERT'), … 'UPDATE', … 'DELETE', … 'TRUNCATE'`
+  Any true → print the SRS §9.2 warning verbatim-style: "⚠ connected user can WRITE to <table> — use a read-only user; hookrecon never writes, but don't take our word for it."
+- **Doctor dry-run:** run each check's SQL with dummy param `"hookrecon-doctor-probe"`; **no exception = pass** (row count is meaningless, ignore it). Exception = doctor fail with verbatim error, exit 2.
+
+### `drift.py` — pure diff (no I/O)
+- Inputs: deduped events (dicts), validated checks, a `run_sql(sql, param) -> rows` callable (injected — that's what makes it testable without DB/network).
+- Per check: events where `event["type"] == check.event` → per event: `param = get_path(event, check.param)`.
+  - Param path missing (possible: old events render at their creation-time API version) → **soft skip**: count per check as `skipped`, don't crash, shown in report/JSON.
+  - 0 rows from `run_sql` → drift record `{event_id, object_id, amount, currency, created, url}` where `url = https://dashboard.stripe.com/events/<event_id>` (0 rows = the record the webhook should have created is missing — corrected from this plan's original inverted wording after live acceptance testing); amount from `money` path or `null` if path absent (SRS §7: that check then contributes no money figure).
+  - `run_sql` raises → that check `status: "error"` with the message, other checks continue (SRS §8 step 3).
+- Money summary: sum per check per currency — currencies never merged (SRS §8 step 4).
+- Output: report dict matching the §8.4 JSON schema exactly.
+
+### `report.py` — rendering
+- ANSI by hand (SRS forbids color libs): `\x1b[31m` red, `\x1b[32m` green, `\x1b[1m` bold, `\x1b[2m` dim. Respect `NO_COLOR` and non-tty → plain text.
+- Table per SRS §8.3: banner (lookback, events scanned, mode) → per-check ✓/✗ blocks with drift rows (event id, object id, amount, date, dashboard URL) and the `→ Fix:` line → summary.
+- **Money formatting:** minor units → human string with a **zero-decimal currency guard** (`JPY KRW VND CLP XOF XAF BIF DJF GNF KMF MGA PYG RWF UGX VUV` — never ÷100). `ponytail:` fixed set; extend on complaint.
+- **$0 drifts are real:** free-trial invoices fire `invoice.payment_succeeded` with `amount_paid: 0` — render at $0.00; README tells users to suppress via WHERE filter.
+- Dates: human table in local time (event `created` is Unix seconds UTC); `--json` always ISO-8601 UTC.
+- `--json` → `json.dumps(report, indent=2)` per §8.4. `--quiet` → no banner, drift lines + summary only.
+
+### `cli.py` — wiring
+- argparse: subparsers `init` / `check` / `doctor`; `check` flags `--since <Nd> --json --show-sql --limit <n> --quiet` (flag `--since` overrides config `lookbackDays` — now defined).
+- `init`: `input()` wizard (Stripe key env name → DB URL env name → lookback days) → writes `hookrecon.config.json` pre-filled with the 3 canonical checks → prints the restricted-key recipe → runs doctor preflight.
+- `doctor`: env vars → Stripe events ping → DB `SELECT 1` → per-check dry-run → privilege audit. Exit 0 if all pass.
+- Exit codes: **0** clean (including the explicit "0 events — widen --since" case), **1** drift, **2** fatal/config/any-check-errored (+ argparse usage errors). Single `sys.exit(main())` at the end — always finish rendering before exiting (SRS §10).
+
+---
+
+## 4. Command flows (refined, logic unchanged from SRS §5/§8)
+
+- **init** = wizard → config file → key recipe → preflight.
+- **check** = load/validate config → resolve env → fetch events (§stripe_client) → pure diff (§drift) → money summary → render (§report) → exit code.
+- **doctor** = preflight only, ordered fail-soft with named failures, privilege audit last so it always gets shown.
+
+---
+
+## 5. Tests
+
+`tests/test_drift.py` — SRS §11's four, verbatim logic, `unittest.TestCase`, fake `run_sql`:
+1. 3 events, 1 has its DB row present → the other 2 are drifts, correct money sum, correct url shape.
+2. Duplicate event id → deduped, counted once.
+3. Check SQL raises → that check `status: "error"`, other checks still reconcile.
+4. `money` path absent → amount `null`, excluded from totals.
+
+`tests/test_sql.py` — the trust boundary:
+5. Valid SELECT passes; `UPDATE …`, `SELECT 1; DROP TABLE x`, CTE (`WITH …`), leading comment + SELECT passes.
+6. `$1`/`$2` → `%s`/`%s` translation; literal-heavy SQL untouched.
+
+Run: `python -m unittest discover tests` (or `python -m unittest` with default discovery). No fixtures, no mocks library, no pytest.
+
+---
+
+## 6. CI / release
+
+- `ci.yml`: matrix 3.10/3.12/3.13 × ubuntu/windows → `pip install -e .` → unittest → assert exit codes via a tiny scripted run of `--help`/config-error paths (no Stripe/DB in CI — SRS: "no e2e in CI").
+- `release.yml`: on tag → hatchling build → PyPI trusted publishing (OIDC). Trigger: manually, at M6.
+
+---
+
+## 7. Milestones (evenings-sized, Python-adjusted SRS §12)
+
+| Block | Deliverable |
+|---|---|
+| **M1** | Repo scaffold: pyproject (hatchling, entry point, deps), src-layout, `pip install -e .` runs; `config.py` + SQL lint; `drift.py` + both test files — all verifiable offline |
+| **M2** | `stripe_client.py` (pagination, dedupe, limit, mode detect, 30-day warning) wired into `check --json` against a test-mode key |
+| **M3** | `db.py`: connect, lint→translate→bind, per-check error isolation, `EXPLAIN` table extraction, privilege audit |
+| **M4** | `report.py`: ANSI table, money summary (zero-decimal guard), JSON schema, exit codes, `--show-sql`, `--quiet`; **record the README GIF here** |
+| **M5** | `doctor` (events ping, dry-run, audit) + `init` wizard |
+| **M6** | README (GIF first, uvx line, restricted-key recipe, trust section, LGPL note), MIT, CI + release workflows, **PyPI publish**, GitHub topics (§9) |
+
+---
+
+## 8. Acceptance checklist (definition of done)
+
+- [ ] `uvx hookrecon init` (or local `pip install -e .`) produces a working config against Stripe test mode + a Postgres with an `orders` table.
+- [ ] E2E demo: create a checkout session in test mode, "forget" the insert → `check` reports the drift with the correct amount.
+- [ ] `doctor` flags a write-privileged DB user (tested with both an owner user and a true read-only user).
+- [ ] Doctor passes against the SRS-prescribed restricted key (Events: Read only) — this is what A2 fixed.
+- [ ] All tests pass; exit codes 0/1/2 verified in CI.
+- [ ] `hookrecon` registered on PyPI; `uvx hookrecon --help` works on a machine without Python (uv downloads it).
+
+---
+
+## 9. SEO / distribution (per your note — ranking comes from repo description + README H1 + topics)
+
+- **Repo description:** `Find Stripe payments that never reached your database — read-only CLI, zero install: uvx hookrecon check`
+- **README H1 (exact):** `# hookrecon — find Stripe payments that never reached your database`
+- **First paragraph carries the search phrases:** "missing Stripe payments", "failed webhooks", "Stripe database reconciliation", "silent webhook failures".
+- **GitHub topics:** `stripe`, `webhook`, `reconciliation`, `postgres`, `cli`, `payments`, `drift-detection`, `python`, `stripe-webhooks`, `database`
+- **PyPI description** mirrors the README (PyPI ranks in Google for the same phrases).
+- GIF at top before launch (SRS §6 note).
+
+---
+
+## 10. Verified-fact sources
+
+Stripe [events/list](https://docs.stripe.com/api/events/list) (30-day retention, `types` ≤ 20, `delivery_success`) · [rate limits](https://docs.stripe.com/rate-limits) · [restricted keys](https://docs.stripe.com/keys/restricted-api-keys) + [403 changelog](https://docs.stripe.com/changelog/2016-10-19/insufficient-permissions-throw-403-error) · [Checkout Session](https://docs.stripe.com/api/checkout/sessions/object) / [Invoice](https://docs.stripe.com/api/invoices/object) / [PaymentIntent](https://docs.stripe.com/api/payment_intents/object) (money paths, nullability, $0 invoices) · [auto-pagination](https://docs.stripe.com/api/pagination/auto?lang=python) · [stripe-python](https://github.com/stripe/stripe-python) / [PyPI stripe 16](https://pypi.org/pypi/stripe/json) · psycopg [3 docs](https://www.psycopg.org/psycopg3/docs/basic/from_pg2.html) (%s only, multi-statement refusal) / [conninfo](https://www.psycopg.org/psycopg3/docs/api/conninfo.html) / [PyPI psycopg 3.3](https://pypi.org/pypi/psycopg/json) · Postgres [role_table_grants](https://www.postgresql.org/docs/current/infoschema-role-table-grants.html) (PUBLIC gap → `has_table_privilege`) · [read-only user recipe](https://www.crunchydata.com/blog/creating-a-read-only-postgres-user) · packaging [recommendations](https://packaging.python.org/guides/tool-recommendations) · [uv python downloads](https://docs.astral.sh/uv/concepts/python-versions/) (uvx needs no Python) · [PyPI trusted publishers](https://docs.pypi.org/trusted-publishers/) · landscape: `stripe-reconcile`/`stripe-reconciler`/`stripe-drift` = zero results on npm+PyPI; `hookrecon` free on PyPI; closest existing thing = [Stripe's own hand-rolled recipe](https://docs.stripe.com/webhooks/process-undelivered-events).
+
+---
+
+## 11. Deliberately excluded (one line each, revisit after dogfooding)
+
+- **`delivery_success=false` filter** (discovered in the events API): catches *never-acknowledged* webhooks — a different failure mode than hookrecon's target (handler acked 200 then failed, or WAF answered for it). The full-scan diff is the product; this could become a bonus section in the report later.
+- MySQL/SQLite/Mongo, other gateways, daemon/scheduler, replay — SRS non-goals, unchanged.
+- Concurrency/asyncio — 10k events × ~1 ms sequential queries is fine; add none.