invoiceguard 0.1.0__py3-none-any.whl

invoiceguard/__init__.py

@@ -0,0 +1,7 @@
+"""InvoiceGuard — freelancer payment enforcement.
+
+Deposit links tied to a contract with a late-fee clause, then automated
+3-stage collections. Local-first, SQLite-backed, Apache-2.0.
+"""
+
+__version__ = "0.1.0"

invoiceguard/cli.py

@@ -0,0 +1,303 @@
+"""invoiceguard CLI — freelancer payment enforcement."""
+
+from __future__ import annotations
+
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+
+from . import __version__
+from .config import (CONFIG_TEMPLATE, config_path, db_path, load_config,
+                     templates_dir)
+from .contracts import render_contract
+from .db import DB
+from .dunning import check_due, money
+from .stripe_links import create_payment_link, default_due_date
+
+TEMPLATE_SOURCE = Path(__file__).resolve().parent / "email_templates"
+
+
+def _db() -> DB:
+    return DB(db_path())
+
+
+@click.group()
+@click.version_option(__version__)
+def cli():
+    """InvoiceGuard — deposit links + contract, then automated collections."""
+
+
+# -- init ----------------------------------------------------------------
+@cli.command()
+def init():
+    """Create ~/.invoiceguard (config template, DB, email templates)."""
+    cfg_path = config_path()
+    cfg_path.parent.mkdir(parents=True, exist_ok=True)
+    if not cfg_path.exists():
+        cfg_path.write_text(CONFIG_TEMPLATE, encoding="utf-8")
+        click.echo(f"wrote config template: {cfg_path}")
+    else:
+        click.echo(f"config already exists: {cfg_path}")
+
+    db = DB(db_path())  # creates tables
+    db.close()
+    click.echo(f"database ready: {db_path()}")
+
+    tdir = templates_dir()
+    tdir.mkdir(parents=True, exist_ok=True)
+    for src in TEMPLATE_SOURCE.glob("*.md"):
+        dest = tdir / src.name
+        if not dest.exists():
+            shutil.copy(src, dest)
+            click.echo(f"installed template: {dest}")
+    click.echo("done. Edit the config, then add a Stripe test key.")
+
+
+# -- client ---------------------------------------------------------------
+@cli.group()
+def client():
+    """Manage clients."""
+
+
+@client.command("add")
+@click.option("--name", required=True, help="Client name")
+@click.option("--email", default=None, help="Client email (for dunning)")
+def client_add(name, email):
+    """Add a client."""
+    db = _db()
+    cid = db.add_client(name, email)
+    db.close()
+    click.echo(f"client #{cid}: {name} <{email or 'no email'}>")
+
+
+@client.command("list")
+def client_list():
+    """List clients."""
+    db = _db()
+    rows = db.list_clients()
+    db.close()
+    for r in rows:
+        click.echo(f"#{r['id']:>3}  {r['name']:<30} {r['email'] or ''}")
+
+
+# -- project --------------------------------------------------------------
+@cli.group()
+def project():
+    """Manage projects (contract + terms)."""
+
+
+@project.command("create")
+@click.option("--client", "client_name", required=True,
+              help="Client name (must already exist)")
+@click.option("--title", required=True, help="Project title")
+@click.option("--amount", type=float, required=True,
+              help="Total project amount in currency units, e.g. 2000")
+@click.option("--currency", default="USD")
+@click.option("--deposit-pct", type=float, default=50.0)
+@click.option("--late-fee-pct", type=float, default=1.5)
+@click.option("--late-fee-grace-days", type=int, default=15)
+@click.option("--ack", is_flag=True, default=False,
+              help="Record the contract as acknowledged by the client")
+def project_create(client_name, title, amount, currency, deposit_pct,
+                   late_fee_pct, late_fee_grace_days, ack):
+    """Create a project and generate its contract (with late-fee clause)."""
+    db = _db()
+    clients = [c for c in db.list_clients() if c["name"] == client_name]
+    if not clients:
+        db.close()
+        raise click.ClickException(
+            f'no client named "{client_name}" — add them first '
+            f"with `invoiceguard client add`"
+        )
+    client = clients[0]
+    amount_cents = round(amount * 100)
+    contract = render_contract(
+        client["name"], client["email"], title, amount_cents, currency,
+        deposit_pct, late_fee_pct, late_fee_grace_days,
+    )
+    pid = db.add_project(
+        client["id"], title, amount_cents, currency, deposit_pct,
+        late_fee_pct, late_fee_grace_days, contract,
+    )
+    if ack:
+        db.ack_contract(pid)
+    db.close()
+    click.echo(f"project #{pid}: {title}")
+    click.echo(f"  client: {client['name']}")
+    click.echo(f"  amount: {money(amount_cents, currency)} "
+               f"(deposit {deposit_pct}% = "
+               f"{money(round(amount_cents * deposit_pct / 100), currency)})")
+    click.echo(f"  late fee: {late_fee_pct}%/mo after {late_fee_grace_days} days grace")
+    click.echo(f"  contract acknowledged: {'yes' if ack else 'no — run `invoiceguard project ack ' + str(pid) + '` after the client accepts'}")
+    click.echo("  --- contract preview ---")
+    click.echo(contract)
+
+
+@project.command("list")
+def project_list():
+    """List projects."""
+    db = _db()
+    rows = db.list_projects()
+    db.close()
+    for r in rows:
+        ack = "ack" if r["contract_ack"] else "no-ack"
+        click.echo(f"#{r['id']:>3}  {r['title']:<35} {r['client_name']:<20} "
+                   f"{money(r['amount_cents'], r['currency']):>12} [{ack}]")
+
+
+@project.command("ack")
+@click.argument("project_id", type=int)
+def project_ack(project_id):
+    """Record client acknowledgment of the contract (v1: paid deposit link)."""
+    db = _db()
+    if not db.get_project(project_id):
+        db.close()
+        raise click.ClickException(f"no project #{project_id}")
+    db.ack_contract(project_id)
+    db.close()
+    click.echo(f"project #{project_id}: contract acknowledged at "
+               f"{datetime.now(timezone.utc).isoformat()}")
+
+
+# -- invoice --------------------------------------------------------------
+@cli.group()
+def invoice():
+    """Manage invoices (Stripe payment links)."""
+
+
+@invoice.command("create")
+@click.option("--project", "project_id", type=int, required=True)
+@click.option("--kind", type=click.Choice(["deposit", "milestone", "final"]),
+              required=True)
+@click.option("--amount", type=float, default=None,
+              help="Override amount in currency units (default: kind-based)")
+@click.option("--due-days", type=int, default=7,
+              help="Days until due (default 7)")
+def invoice_create(project_id, kind, amount, due_days):
+    """Create a Stripe payment link for a deposit/milestone/final invoice."""
+    db = _db()
+    proj = db.get_project(project_id)
+    if not proj:
+        db.close()
+        raise click.ClickException(f"no project #{project_id}")
+
+    if amount is None:
+        if kind == "deposit":
+            amount_cents = round(proj["amount_cents"] * proj["deposit_pct"] / 100)
+        elif kind == "final":
+            amount_cents = proj["amount_cents"] - round(
+                proj["amount_cents"] * proj["deposit_pct"] / 100)
+        else:  # milestone
+            amount_cents = proj["amount_cents"]
+    else:
+        amount_cents = round(amount * 100)
+
+    due = (datetime.now(timezone.utc).date()
+           ).isoformat() if due_days <= 0 else default_due_date(due_days)
+    iid = db.add_invoice(project_id, kind, amount_cents, proj["currency"],
+                         status="draft", due_date=due)
+
+    cfg = load_config()
+    try:
+        inv = db.invoice_full(iid)
+        url, link_id = create_payment_link(inv, cfg.get("stripe_secret_key", ""))
+    except ValueError as e:
+        db.close()
+        raise click.ClickException(str(e))
+
+    db.update_invoice(
+        iid,
+        status="sent",
+        stripe_url=url,
+        stripe_session_id=link_id,
+        sent_at=datetime.now(timezone.utc).isoformat(),
+    )
+    db.close()
+    click.echo(f"invoice #{iid} ({kind}): {money(amount_cents, proj['currency'])}")
+    click.echo(f"  pay link: {url}")
+    click.echo(f"  due: {due}   status: sent")
+
+
+@invoice.command("list")
+def invoice_list():
+    """List invoices."""
+    db = _db()
+    rows = db.list_invoices()
+    db.close()
+    for r in rows:
+        click.echo(f"#{r['id']:>3}  {r['kind']:<9} {r['status']:<8} "
+                   f"{money(r['amount_cents'], r['currency']):>12}  "
+                   f"{r['project_title']:<30} due {r['due_date'] or '-'}")
+
+
+@invoice.command("mark-paid")
+@click.argument("invoice_id", type=int)
+def invoice_mark_paid(invoice_id):
+    """Manually mark an invoice as paid."""
+    db = _db()
+    inv = db.get_invoice(invoice_id)
+    if not inv:
+        db.close()
+        raise click.ClickException(f"no invoice #{invoice_id}")
+    db.update_invoice(invoice_id, status="paid",
+                      paid_at=datetime.now(timezone.utc).isoformat())
+    db.close()
+    click.echo(f"invoice #{invoice_id} marked paid")
+
+
+@invoice.command("void")
+@click.argument("invoice_id", type=int)
+def invoice_void(invoice_id):
+    """Void an invoice."""
+    db = _db()
+    inv = db.get_invoice(invoice_id)
+    if not inv:
+        db.close()
+        raise click.ClickException(f"no invoice #{invoice_id}")
+    db.update_invoice(invoice_id, status="void")
+    db.close()
+    click.echo(f"invoice #{invoice_id} voided")
+
+
+# -- dunning ---------------------------------------------------------------
+@cli.command("check-due")
+def check_due_cmd():
+    """Scan for overdue invoices and send the next dunning stage."""
+    db = _db()
+    cfg = load_config()
+    smtp_cfg = cfg.get("smtp") or {}
+    if not smtp_cfg.get("host") or "example.com" in str(smtp_cfg.get("host")):
+        db.close()
+        raise click.ClickException(
+            "SMTP is not configured — set smtp.host etc. in "
+            f"{config_path()} first."
+        )
+    results = check_due(db, smtp_cfg)
+    db.close()
+    if not results:
+        click.echo("nothing due — no emails sent")
+    for r in results:
+        click.echo(f"sent {r['stage']} to {r['to']} "
+                   f"(invoice #{r['invoice_id']})")
+
+
+# -- dashboard -------------------------------------------------------------
+@cli.command()
+@click.option("--port", type=int, default=8000, show_default=True,
+              help="Port to listen on")
+@click.option("--host", default="127.0.0.1", show_default=True,
+              help="Host to bind (keep 127.0.0.1: localhost only)")
+def dashboard(port, host):
+    """Launch the InvoiceGuard web dashboard (local web UI)."""
+    import uvicorn
+
+    from .web.main import app
+
+    click.echo(f"InvoiceGuard dashboard: http://{host}:{port}/")
+    uvicorn.run(app, host=host, port=port)
+
+
+def main():
+    cli()

invoiceguard/config.py

@@ -0,0 +1,87 @@
+"""Configuration loading.
+
+Config lives at ~/.invoiceguard/config.yaml by default; the
+INVOICEGUARD_CONFIG environment variable overrides the path.
+Secrets may also be supplied via environment variables:
+
+    INVOICEGUARD_STRIPE_SECRET_KEY, INVOICEGUARD_STRIPE_WEBHOOK_SECRET,
+    INVOICEGUARD_SMTP_PASSWORD
+
+Env values always win over the YAML file — never the reverse.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import yaml
+
+DEFAULT_DIR = Path.home() / ".invoiceguard"
+DEFAULT_DB = DEFAULT_DIR / "invoiceguard.db"
+DEFAULT_TEMPLATES_DIR = DEFAULT_DIR / "templates"
+
+CONFIG_TEMPLATE = """\
+# InvoiceGuard configuration.
+# NEVER commit this file with real secrets (it is git-ignored upstream).
+
+# Stripe — get test keys at https://dashboard.stripe.com/test/apikeys
+stripe_secret_key: "sk_test_..."        # or env INVOICEGUARD_STRIPE_SECRET_KEY
+stripe_webhook_secret: "whsec_..."       # or env INVOICEGUARD_STRIPE_WEBHOOK_SECRET
+
+# SMTP — how dunning emails are sent
+smtp:
+  host: "smtp.example.com"              # e.g. smtp.gmail.com
+  port: 587
+  username: "you@example.com"
+  password: "APP_PASSWORD"              # or env INVOICEGUARD_SMTP_PASSWORD
+  from_addr: "you@example.com"
+  use_tls: true
+
+# Web-facing base URL (used to point the Stripe webhook at this app)
+app:
+  base_url: "http://localhost:8000"
+"""
+
+
+def config_path() -> Path:
+    override = os.environ.get("INVOICEGUARD_CONFIG")
+    if override:
+        return Path(override).expanduser()
+    return DEFAULT_DIR / "config.yaml"
+
+
+def db_path() -> Path:
+    return Path(os.environ.get("INVOICEGUARD_DB", str(DEFAULT_DB))).expanduser()
+
+
+def templates_dir() -> Path:
+    """Templates live next to the config file, so overrides stay together."""
+    return config_path().parent / "templates"
+
+
+def load_config() -> dict:
+    """Load merged config: YAML file first, then env overrides."""
+    cfg: dict = {}
+    path = config_path()
+    if path.exists():
+        with open(path) as f:
+            cfg = yaml.safe_load(f) or {}
+
+    # Env overrides (never hardcode secrets in the file or the code).
+    if os.environ.get("INVOICEGUARD_STRIPE_SECRET_KEY"):
+        cfg["stripe_secret_key"] = os.environ["INVOICEGUARD_STRIPE_SECRET_KEY"]
+    if os.environ.get("INVOICEGUARD_STRIPE_WEBHOOK_SECRET"):
+        cfg["stripe_webhook_secret"] = os.environ["INVOICEGUARD_STRIPE_WEBHOOK_SECRET"]
+    smtp = cfg.setdefault("smtp", {})
+    if os.environ.get("INVOICEGUARD_SMTP_PASSWORD"):
+        smtp["password"] = os.environ["INVOICEGUARD_SMTP_PASSWORD"]
+    return cfg
+
+
+def is_placeholder(value: str | None) -> bool:
+    """True when a value still looks like the template placeholder."""
+    if not value:
+        return True
+    v = value.strip()
+    return v.endswith("...") or v in {"sk_test_...", "whsec_...", "APP_PASSWORD", "you@example.com"}

invoiceguard/contracts.py

@@ -0,0 +1,67 @@
+"""Contract markdown generator.
+
+v1 contract signature = the client acknowledgment checkbox: the client
+acknowledges the contract by accepting (paying) the deposit link, and the
+freelancer records that with `invoiceguard project ack`.
+Real e-signature (typed name / drawn signature capture) is roadmap.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+
+CONTRACT_TEMPLATE = """\
+# Freelance Services Agreement
+
+**Project:** {title}
+**Client:** {client_name} ({client_email})
+**Date:** {date}
+
+## 1. Scope
+Work will be performed as agreed between the freelancer and the client
+for the project titled "{title}".
+
+## 2. Fee and payment
+Total project fee: **{amount} {currency}**.
+
+A deposit of **{deposit_pct}%** ({deposit_amount} {currency}) is due before
+work begins. The deposit is collected through an online payment link that
+also serves as the client's acknowledgment of this agreement: paying the deposit means the client has read and accepts these terms.
+
+## 3. Late fees
+If any invoice remains unpaid {grace_days} days after its due date, a late
+fee of **{late_fee_pct}% per month** on the overdue balance will apply from
+day {grace_days} + 1, compounding monthly until the balance is paid in full.
+The client acknowledges this clause by accepting the deposit link.
+
+> Late-fee clause: {late_fee_pct}% per month on overdue balances after {grace_days} days, client acknowledges by accepting the deposit link.
+
+## 4. Sign-off (v1)
+Client acknowledgment is recorded when the deposit payment link is paid.
+Recorded in InvoiceGuard as contract_ack = {ack}.
+"""
+
+
+def render_contract(client_name: str, client_email: str | None, title: str,
+                    amount_cents: int, currency: str, deposit_pct: float,
+                    late_fee_pct: float, late_fee_grace_days: int) -> str:
+    deposit_cents = round(amount_cents * deposit_pct / 100.0)
+    return CONTRACT_TEMPLATE.format(
+        title=title,
+        client_name=client_name,
+        client_email=client_email or "n/a",
+        date=date.today().isoformat(),
+        amount=_money(amount_cents, currency),
+        currency=currency,
+        deposit_pct=deposit_pct,
+        deposit_amount=_money(deposit_cents, currency),
+        late_fee_pct=late_fee_pct,
+        grace_days=late_fee_grace_days,
+        ack="1 (client paid the deposit link)",
+    )
+
+
+def _money(cents: int, currency: str) -> str:
+    if currency.upper() == "USD":
+        return f"${cents / 100:,.2f}"
+    return f"{cents / 100:,.2f} {currency.upper()}"

invoiceguard/db.py

@@ -0,0 +1,213 @@
+"""SQLite persistence.
+
+THIS SCHEMA IS THE CONTRACT shared with the dashboard app — do not
+change column names or types without coordinating with the dashboard
+worker. Additive migrations only.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from datetime import datetime, timezone
+from pathlib import Path
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS clients(
+    id INTEGER PRIMARY KEY,
+    name TEXT NOT NULL,
+    email TEXT,
+    created_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS projects(
+    id INTEGER PRIMARY KEY,
+    client_id INTEGER NOT NULL REFERENCES clients(id),
+    title TEXT NOT NULL,
+    amount_cents INTEGER NOT NULL,
+    currency TEXT NOT NULL DEFAULT 'USD',
+    deposit_pct REAL NOT NULL DEFAULT 50.0,
+    late_fee_pct REAL NOT NULL DEFAULT 1.5,
+    late_fee_grace_days INTEGER NOT NULL DEFAULT 15,
+    contract_md TEXT NOT NULL,
+    contract_ack INTEGER NOT NULL DEFAULT 0,
+    contract_ack_at TEXT,
+    created_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS invoices(
+    id INTEGER PRIMARY KEY,
+    project_id INTEGER NOT NULL REFERENCES projects(id),
+    kind TEXT NOT NULL,
+    amount_cents INTEGER NOT NULL,
+    currency TEXT NOT NULL DEFAULT 'USD',
+    status TEXT NOT NULL DEFAULT 'draft',
+    stripe_url TEXT,
+    stripe_session_id TEXT,
+    due_date TEXT,
+    sent_at TEXT,
+    paid_at TEXT,
+    created_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS dunning_events(
+    id INTEGER PRIMARY KEY,
+    invoice_id INTEGER NOT NULL REFERENCES invoices(id),
+    stage TEXT NOT NULL,
+    sent_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_invoices_status_due
+    ON invoices(status, due_date);
+CREATE INDEX IF NOT EXISTS idx_dunning_invoice_stage
+    ON dunning_events(invoice_id, stage);
+"""
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class DB:
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.conn = sqlite3.connect(str(self.path))
+        self.conn.row_factory = sqlite3.Row
+        self.conn.execute("PRAGMA foreign_keys = ON")
+        self.conn.executescript(SCHEMA)
+
+    # -- clients -----------------------------------------------------
+    def add_client(self, name: str, email: str | None = None) -> int:
+        cur = self.conn.execute(
+            "INSERT INTO clients(name, email, created_at) VALUES (?, ?, ?)",
+            (name, email, now_iso()),
+        )
+        self.conn.commit()
+        return cur.lastrowid
+
+    def get_client(self, client_id: int) -> sqlite3.Row | None:
+        return self.conn.execute(
+            "SELECT * FROM clients WHERE id = ?", (client_id,)
+        ).fetchone()
+
+    def list_clients(self) -> list[sqlite3.Row]:
+        return self.conn.execute(
+            "SELECT * FROM clients ORDER BY id"
+        ).fetchall()
+
+    # -- projects ----------------------------------------------------
+    def add_project(self, client_id: int, title: str, amount_cents: int,
+                    currency: str = "USD", deposit_pct: float = 50.0,
+                    late_fee_pct: float = 1.5, late_fee_grace_days: int = 15,
+                    contract_md: str = "") -> int:
+        cur = self.conn.execute(
+            """INSERT INTO projects(client_id, title, amount_cents, currency,
+               deposit_pct, late_fee_pct, late_fee_grace_days, contract_md,
+               created_at)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (client_id, title, amount_cents, currency, deposit_pct,
+             late_fee_pct, late_fee_grace_days, contract_md, now_iso()),
+        )
+        self.conn.commit()
+        return cur.lastrowid
+
+    def get_project(self, project_id: int) -> sqlite3.Row | None:
+        return self.conn.execute(
+            "SELECT * FROM projects WHERE id = ?", (project_id,)
+        ).fetchone()
+
+    def list_projects(self) -> list[sqlite3.Row]:
+        return self.conn.execute(
+            """SELECT p.*, c.name AS client_name
+               FROM projects p JOIN clients c ON c.id = p.client_id
+               ORDER BY p.id"""
+        ).fetchall()
+
+    def ack_contract(self, project_id: int) -> None:
+        self.conn.execute(
+            "UPDATE projects SET contract_ack = 1, contract_ack_at = ? "
+            "WHERE id = ?",
+            (now_iso(), project_id),
+        )
+        self.conn.commit()
+
+    # -- invoices ----------------------------------------------------
+    def add_invoice(self, project_id: int, kind: str, amount_cents: int,
+                    currency: str = "USD", status: str = "draft",
+                    due_date: str | None = None) -> int:
+        cur = self.conn.execute(
+            """INSERT INTO invoices(project_id, kind, amount_cents, currency,
+               status, due_date, created_at)
+               VALUES (?, ?, ?, ?, ?, ?, ?)""",
+            (project_id, kind, amount_cents, currency, status, due_date,
+             now_iso()),
+        )
+        self.conn.commit()
+        return cur.lastrowid
+
+    def get_invoice(self, invoice_id: int) -> sqlite3.Row | None:
+        return self.conn.execute(
+            "SELECT * FROM invoices WHERE id = ?", (invoice_id,)
+        ).fetchone()
+
+    def list_invoices(self) -> list[sqlite3.Row]:
+        return self.conn.execute(
+            """SELECT i.*, p.title AS project_title, c.name AS client_name
+               FROM invoices i
+               JOIN projects p ON p.id = i.project_id
+               JOIN clients c ON c.id = p.client_id
+               ORDER BY i.id"""
+        ).fetchall()
+
+    def update_invoice(self, invoice_id: int, **fields) -> None:
+        sets = ", ".join(f"{k} = ?" for k in fields)
+        self.conn.execute(
+            f"UPDATE invoices SET {sets} WHERE id = ?",
+            (*fields.values(), invoice_id),
+        )
+        self.conn.commit()
+
+    def invoice_full(self, invoice_id: int) -> dict | None:
+        """Invoice joined with project + client, as a plain dict."""
+        row = self.conn.execute(
+            """SELECT i.*, p.title AS project_title, p.late_fee_pct,
+                      p.late_fee_grace_days, p.contract_ack,
+                      c.name AS client_name, c.email AS client_email
+               FROM invoices i
+               JOIN projects p ON p.id = i.project_id
+               JOIN clients c ON c.id = p.client_id
+               WHERE i.id = ?""",
+            (invoice_id,),
+        ).fetchone()
+        return dict(row) if row else None
+
+    # -- dunning -----------------------------------------------------
+    def record_dunning(self, invoice_id: int, stage: str) -> None:
+        self.conn.execute(
+            "INSERT INTO dunning_events(invoice_id, stage, sent_at) "
+            "VALUES (?, ?, ?)",
+            (invoice_id, stage, now_iso()),
+        )
+        self.conn.commit()
+
+    def sent_stages(self, invoice_id: int) -> set[str]:
+        rows = self.conn.execute(
+            "SELECT stage FROM dunning_events WHERE invoice_id = ?",
+            (invoice_id,),
+        ).fetchall()
+        return {r["stage"] for r in rows}
+
+    def overdue_invoices(self) -> list[dict]:
+        """Invoices still (sent|overdue) and past due_date."""
+        rows = self.conn.execute(
+            """SELECT i.*, p.title AS project_title, p.late_fee_pct,
+                      p.late_fee_grace_days, c.name AS client_name,
+                      c.email AS client_email
+               FROM invoices i
+               JOIN projects p ON p.id = i.project_id
+               JOIN clients c ON c.id = p.client_id
+               WHERE i.status IN ('sent', 'overdue')
+                 AND i.due_date IS NOT NULL
+                 AND date(i.due_date) <= date('now')
+               ORDER BY i.due_date"""
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    def close(self) -> None:
+        self.conn.close()