quints 0.2.0__tar.gz → 0.4.0__tar.gz

{quints-0.2.0 → quints-0.4.0}/.gitignore

@@ -6,6 +6,7 @@ build/
 *.egg-info/
 .pytest_cache/
 .ruff_cache/
+site/
 .env
 .DS_Store
 .claude/settings.local.json

{quints-0.2.0 → quints-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quints
-Version: 0.2.0
+Version: 0.4.0
 Summary: Swiss VAT & accounting toolkit for plain-text (beancount) books: MWST reports and quarterly settlement, Bezugsteuer helpers, BAZG daily FX rates, QR-bill invoicing, KMU statutory statements, and statement importers (UBS MT940, Wise, Stripe) that draft into a staging area
 License: GPL-2.0-only
 License-File: LICENSE
@@ -11,7 +11,7 @@ Requires-Dist: beancount>=3.2.0
 Requires-Dist: beangulp-mt940>=0.1.0
 Requires-Dist: beangulp-stripe>=0.1.0
 Requires-Dist: beangulp-wise[sca]>=0.1.0
-Requires-Dist: beanprice-bazg>=0.1.0
+Requires-Dist: beanprice-bazg>=0.2.0
 Requires-Dist: fava>=1.30
 Requires-Dist: pydantic>=2.7
 Requires-Dist: python-stdnum>=1.20
@@ -27,7 +27,9 @@ Description-Content-Type: text/markdown
 
 Swiss VAT & accounting toolkit for plain-text ([beancount](https://github.com/beancount/beancount)) books.
 
-Everything a Swiss micro-company (GmbH/AG) needs on top of beancount + Fava:
+![quints init scaffolds sample books, quints check validates them, and quints mwst prints the Form-310 VAT return](https://raw.githubusercontent.com/sealambda/quints/main/docs/assets/quickstart.gif)
+
+Everything a Swiss micro-company (GmbH, AG, or Einzelfirma) needs on top of beancount + Fava:
 
 - **MWST**: quarterly VAT report mapped to the ESTV form Ziffern, settlement
   transactions, VAT status, and Bezugsteuer (reverse-charge, Art. 45 ff. MWSTG)

{quints-0.2.0 → quints-0.4.0}/README.md

@@ -2,7 +2,9 @@
 
 Swiss VAT & accounting toolkit for plain-text ([beancount](https://github.com/beancount/beancount)) books.
 
-Everything a Swiss micro-company (GmbH/AG) needs on top of beancount + Fava:
+![quints init scaffolds sample books, quints check validates them, and quints mwst prints the Form-310 VAT return](https://raw.githubusercontent.com/sealambda/quints/main/docs/assets/quickstart.gif)
+
+Everything a Swiss micro-company (GmbH, AG, or Einzelfirma) needs on top of beancount + Fava:
 
 - **MWST**: quarterly VAT report mapped to the ESTV form Ziffern, settlement
   transactions, VAT status, and Bezugsteuer (reverse-charge, Art. 45 ff. MWSTG)

quints-0.4.0/examples/.gitignore

@@ -0,0 +1,8 @@
+# quints working directories. documents/ (filed sources and rendered
+# invoices) is deliberately NOT ignored — the ledger links to it.
+/staging/
+.env
+__pycache__/
+.venv/
+.DS_Store
+.wise/

quints-0.4.0/examples/AGENTS.md

@@ -0,0 +1,120 @@
+# Working on Example GmbH's books with an AI agent
+
+These are plain-text ([beancount](https://beancount.github.io)) books managed
+with [`quints`](https://github.com/sealambda/quints). **`quints` is a
+deterministic tool — you drive it, it never calls a model.** Your job is to
+extend and maintain the ledger; `quints` validates and reports on it.
+
+## Setup
+
+`uv sync` once — it installs quints, which brings beancount and fava along.
+Then `uv run quints check` (or activate the venv and call `quints` and the
+standard beancount tools directly).
+
+This project is a git repository; `quints init` committed the pristine
+scaffold. Work in reviewable steps: `git diff` before moving drafts into
+`books/`, commit once `quints check` passes — the history is the audit trail.
+
+## Layout
+
+- `main.bean` — options, plugins, includes; the entry point every tool loads.
+  `plugin "quints.plugins.kmu"` is enabled: every `*:CH:GmbH:*` account
+  **must** be opened with a four-digit `kmu:` code (Swiss KMU Kontenrahmen).
+- `accounts.bean` — the chart of accounts (all `open` directives).
+- `books/2026.bean` — transactions, one file per fiscal year. `main.bean`
+  includes `books/*.bean`, so a new year just needs a new file.
+- `commodities.bean` — currencies; `prices.bean` — FX rates, refresh with
+  `quints prices sync`.
+- `quints.toml` — entity config (name, legal form, VAT, importer rules). VAT
+  *rates* are law and live in code, not here.
+- `staging/` — importer drafts land here (git-ignored, transient).
+- `inbox/` — incoming source documents, not yet filed.
+- `documents/` — filed documents, mirroring the account tree as
+  `documents/<Account/Tree>/YYYY-MM-DD.payee.description.pdf`. Committed:
+  the ledger links to these files (`fava.plugins.link_documents`).
+- `invoicing/` — issuer identity (`issuer.yaml`), customer registry
+  (`customers.yaml`), one YAML per issued invoice.
+
+## Extending the chart of accounts (the part that needs judgement)
+
+Add income/expense sub-trees for this business as `open` directives in
+`accounts.bean`, each with the KMU code it rolls up to, e.g.:
+
+```beancount
+2026-01-01 open Expenses:CH:GmbH:Marketing:Ads CHF
+  kmu: "6600"  ; Advertising
+```
+
+See the codes already in use:
+
+```bash
+quints report konten --year 2026
+```
+
+Pick codes from the KMU Kontenrahmen; `quints check` fails on a `:CH:GmbH:`
+account with no valid `kmu:` code.
+
+## The loop — money out (statements → books)
+
+1. Draft bank/PSP activity into `staging/`. Configured importers:
+   - `quints import ubs <statement.mt940>` — the MT940 export from UBS e-banking; no credentials.
+   - `quints import wise --fetch --from <date> --to <date>` — needs `QUINTS_WISE_API_TOKEN` in `.env` (plus `QUINTS_WISE_PRIVATE_KEY` for SCA-protected profiles; the key pair lives in `.wise/`, git-ignored).
+   - `quints import stripe --fetch --from <date> --to <date>` — needs `QUINTS_STRIPE_API_KEY` in `.env` (a restricted read-only key for the `[import.stripe]` account).
+2. Review each draft in `staging/`. A draft is a flagged (`!`) transaction
+   with only the cash leg known:
+
+```beancount
+2026-07-20 ! "ACME AG" "Payment order"
+  Assets:CH:GmbH:Current:UBS:CHF  -250.00 CHF
+```
+
+   Complete the counter leg, decide the VAT treatment (InputVAT /
+   Bezugsteuer / none), link the source document, flip `!` to `*`, and move
+   it into `books/2026.bean`. `quints match` scores staging drafts and
+   inbox documents against invoices and bookings.
+3. **Always** `quints check` before you consider the books consistent.
+
+## The loop — money in (invoice → receivable → payment)
+
+1. Describe the invoice as a YAML file in `invoicing/` (each file carries a
+   `$schema` modeline, so schema-aware editors validate it as you type).
+2. `quints invoice invoicing/<file>.yaml` renders the PDF into `documents/`
+   under the income account and cross-checks the total against the ledger.
+   Not booked yet? It prints the receivable draft to paste into
+   `books/2026.bean`.
+3. The payment arrives with the next bank import; the draft is matched to
+   the open invoice by its QR/SCOR reference. `quints receivables` shows
+   what is still open.
+
+## Machine-readable surfaces (prefer these over scraping text)
+
+Every reporting command takes `--json` — stable keys, ISO dates, decimal
+strings:
+
+```bash
+quints check --json
+quints mwst -q 2026-Q3 --json
+quints status --json
+quints report bilanz --at 2026-12-31 --json
+quints receivables --json
+```
+
+JSON Schemas for the invoicing files are hosted at
+https://sealambda.github.io/quints/schema/ (`quints schema` writes them
+locally to `invoicing/schema/`).
+
+Never invent VAT numbers or rates — compute them with `quints mwst`.
+
+## Sample data — replace before the books are real
+
+The scaffold seeded a demo quarter so every command has data. Before
+booking real activity:
+
+- [ ] `invoicing/issuer.yaml` — the VAT ID (CHE-267.359.056 MWST) and both
+      IBANs are checksum-valid fakes; put the real ones in.
+- [ ] `invoicing/customers.yaml` — replace the demo customers (acme, globex).
+- [ ] `invoicing/acme-2026-07.yaml` and `invoicing/globex-2026-08.yaml`
+      — delete the demo invoices.
+- [ ] `books/2026.bean` — delete the block marked *sample activity*.
+- [ ] `prices.bean` — drop the demo EUR rates, then `quints prices sync`.
+- [ ] `quints.toml` — the placeholder IBAN under `[import.ubs]`.

quints-0.4.0/examples/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

quints-0.4.0/examples/invoicing/acme-2026-07.yaml

@@ -0,0 +1,16 @@
+# yaml-language-server: $schema=https://sealambda.github.io/quints/schema/invoice.schema.json
+# Sample domestic invoice — a Swiss QR-bill. It ties to the ^INV2026014
+# booking in books/2026.bean (net 1'000.00 + 8.1% VAT = 1'081.00), so
+# `quints invoice` cross-checks it clean against the ledger.
+number: INV2026014
+kind: domestic
+currency: CHF
+issue_date: 2026-07-02
+supply: Juli 2026
+customer: acme
+items:
+  - description: Consulting — July
+    quantity: 1
+    unit_price: 1000.00
+    unit: Pauschal
+locale: de_CH

quints-0.4.0/examples/invoicing/customers.yaml

@@ -0,0 +1,16 @@
+# yaml-language-server: $schema=https://sealambda.github.io/quints/schema/customers.schema.json
+# Customer registry — invoices reference these entries by key. A customer
+# is a flat entry, or a dated `versions` history for address changes.
+acme:
+  name: Acme AG
+  address:
+    - Bahnhofstrasse 1
+    - 8001 Zürich
+globex:
+  name: Globex Ltd
+  country: IE
+  # Reverse-charge exports must carry the customer's VAT number.
+  vat_id: IE1234567T
+  address:
+    - 1 Liffey Street
+    - Dublin 1

quints-0.4.0/examples/invoicing/globex-2026-08.yaml

@@ -0,0 +1,14 @@
+# yaml-language-server: $schema=https://sealambda.github.io/quints/schema/invoice.schema.json
+# Sample export invoice — foreign currency, reverse charge, no QR part.
+# Ties to the ^INV2026015 booking in books/2026.bean (500.00 EUR).
+number: INV2026015
+kind: export
+currency: EUR
+issue_date: 2026-08-05
+supply: August 2026
+customer: globex
+items:
+  - description: Export consulting
+    quantity: 1
+    unit_price: 500.00
+locale: en

quints-0.4.0/examples/invoicing/issuer.yaml

@@ -0,0 +1,17 @@
+# yaml-language-server: $schema=https://sealambda.github.io/quints/schema/issuer.schema.json
+# Issuer identity for `quints invoice` — name, address, VAT ID, and one
+# bank account per invoicing currency. Sample data: replace the VAT ID
+# and IBANs with your own before issuing a real invoice.
+name: Example GmbH
+address:
+  - Beispielstrasse 1
+  - 8000 Zürich
+vat_id: CHE-267.359.056 MWST
+email: billing@example.ch
+bank:
+  CHF:
+    # QR-IBAN (QR-IID variant) — a Swiss QR-bill with a QRR reference.
+    qr_iban: CH44 3199 9123 0008 8901 2
+  EUR:
+    # Regular IBAN — foreign transfers can't use the QR-bill scheme.
+    iban: CH93 0076 2011 6238 5295 7

{quints-0.2.0 → quints-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quints"
-version = "0.2.0"
+version = "0.4.0"
 description = "Swiss VAT & accounting toolkit for plain-text (beancount) books: MWST reports and quarterly settlement, Bezugsteuer helpers, BAZG daily FX rates, QR-bill invoicing, KMU statutory statements, and statement importers (UBS MT940, Wise, Stripe) that draft into a staging area"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -15,7 +15,7 @@ dependencies = [
     "beangulp-mt940>=0.1.0",
     "beangulp-stripe>=0.1.0",
     "beangulp-wise[sca]>=0.1.0",
-    "beanprice-bazg>=0.1.0",
+    "beanprice-bazg>=0.2.0",
     "fava>=1.30",
     "pydantic>=2.7",
     "python-stdnum>=1.20",

quints-0.4.0/src/quints/__init__.py

@@ -0,0 +1,7 @@
+"""quints — Swiss VAT & accounting for plain-text (beancount) books."""
+
+from importlib.metadata import version
+
+# Derived from the installed distribution (pyproject.toml is the single
+# source) — a hardcoded string here drifted from the released version once.
+__version__ = version("quints")

{quints-0.2.0 → quints-0.4.0}/src/quints/cli.py

@@ -57,11 +57,26 @@ app = typer.Typer(
 )
 
 
+def _print_version(value: bool) -> None:
+    if value:
+        from . import __version__
+
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
 @app.callback()
 def _main(
     config: Path | None = typer.Option(
         None, "--config", help="quints.toml path (default: ./quints.toml, else built-in defaults)."
     ),
+    version: bool = typer.Option(
+        False,
+        "--version",
+        help="Print the quints version and exit.",
+        callback=_print_version,
+        is_eager=True,
+    ),
 ):
     config_mod.set_path(config)
 
@@ -330,8 +345,37 @@ def prices_sync(
     Without --from: extend each currency forward to today (fast, daily use).
     With --from DATE: re-scan the whole range and fill any missing days.
     """
+    from rich.progress import (
+        BarColumn,
+        MofNCompleteColumn,
+        Progress,
+        TaskID,
+        TextColumn,
+        TimeRemainingColumn,
+    )
+
     repair = _parse_date(from_) if from_ else None
-    result = prices_mod.sync(out, repair_from=repair)
+    # BAZG has no bulk endpoint — the fetch is one request per calendar day per
+    # currency, so a backfill takes a while: show a live per-currency bar
+    # (stderr, transient) unless the caller asked for machine-readable output.
+    with Progress(
+        TextColumn("[progress.description]{task.description}"),
+        BarColumn(),
+        MofNCompleteColumn(),
+        TextColumn("days"),
+        TimeRemainingColumn(),
+        console=ui.err_console,
+        transient=True,
+        disable=as_json,
+    ) as bars:
+        tasks: dict[str, TaskID] = {}
+
+        def on_progress(ccy: str, done: int, total: int) -> None:
+            if ccy not in tasks:
+                tasks[ccy] = bars.add_task(ccy, total=total)
+            bars.update(tasks[ccy], completed=done)
+
+        result = prices_mod.sync(out, repair_from=repair, progress=on_progress)
     if as_json:
         _json_out(
             {
@@ -673,7 +717,10 @@ def check(
 def invoice(
     data: Path = typer.Argument(..., help="Invoice file (.yaml/.toml/.json)."),
     out: Path | None = typer.Option(
-        None, "--out", "-o", help="Output PDF (default: <number>.pdf)."
+        None,
+        "--out",
+        "-o",
+        help="Output PDF (default: filed under documents/<income account>/).",
     ),
     issuer: Path = typer.Option(
         Path("invoicing/issuer.yaml"), "--issuer", help="Issuer config (.yaml/.toml/.json)."
@@ -705,7 +752,12 @@ def invoice(
     registry = m.load_customers(customers) if customers.exists() else None
     inv = m.load_invoice(data, registry)
     iss = m.load_issuer(issuer)
-    out = out or Path(f"{inv.number}.pdf")
+    if out is None:
+        # File the PDF the way beancount documents are filed: under the income
+        # account's folder, date-prefixed, next to the ledger's other evidence.
+        cfg = config_mod.get()
+        account = cfg.income_export if inv.kind == "export" else cfg.income_domestic
+        out = m.document_path(inv, account)
     path, totals, payload = r.render(inv, iss, out)
 
     qr_ok = None
@@ -779,7 +831,9 @@ def schema(
     """Write JSON Schemas for the invoice, issuer, and customers files.
 
     Point an editor at them (yaml-language-server modeline) for completion
-    and validation; any future UI can consume the same contract."""
+    and validation; any future UI can consume the same contract. The same
+    schemas are published on the docs site, so scaffolded YAMLs reference
+    them without running this command."""
     import json as _json
 
     from .invoice import model as m
@@ -793,6 +847,7 @@ def schema(
         path = out / f"{name}.schema.json"
         path.write_text(_json.dumps(mdl.model_json_schema(), indent=2) + "\n")
         ui.console.print(f"[ok]Wrote[/] {path}")
+    ui.console.print(f"[muted]Also hosted at {config_mod.DOCS_URL}/schema/[/]")
 
 
 @app.command()
@@ -816,6 +871,11 @@ def init(
     answers_file: Path | None = typer.Option(
         None, "--answers", help="TOML answer-file for non-interactive scaffolding."
     ),
+    use_git: bool = typer.Option(
+        True,
+        "--git/--no-git",
+        help="git init + commit the pristine scaffold (skipped inside an existing repo).",
+    ),
     force: bool = typer.Option(False, "--force", help="Overwrite existing files."),
     yes: bool = typer.Option(False, "--yes", "-y", help="Skip prompts; accept defaults."),
     as_json: bool = typer.Option(False, "--json", help="Machine-readable output."),
@@ -879,14 +939,18 @@ def init(
         typer.secho(f"ERROR: {e}", fg="red", err=True)
         raise typer.Exit(1) from None
     result = init_mod.write(directory, files, force=force)
+    git_result = init_mod.init_git(directory) if use_git and result.written else None
 
     if as_json:
+        import dataclasses
+
         _json_out(
             {
                 "directory": str(directory),
                 "entity": answers.entity_name,
                 "written": [str(p) for p in result.written],
                 "skipped": [str(p) for p in result.skipped],
+                "git": dataclasses.asdict(git_result) if git_result else None,
             }
         )
         return
@@ -894,6 +958,11 @@ def init(
         ui.console.print(f"[ok]created[/] {path}")
     for path in result.skipped:
         ui.console.print(f"[warn]exists, skipped[/] {path} (use --force to overwrite)")
+    if git_result:
+        if git_result.committed:
+            ui.console.print("[ok]git[/] initialised repository, committed the scaffold")
+        else:
+            ui.console.print(f"[warn]git[/] {git_result.detail}")
     if result.written and not result.skipped:
         ui.console.print(
             f"\nScaffolded [b]{answers.entity_name}[/] in {directory}. "

{quints-0.2.0 → quints-0.4.0}/src/quints/config.py

@@ -28,6 +28,11 @@ else:  # pragma: no cover
 
 DEFAULT_PATH = Path("quints.toml")
 
+# The published documentation site. The invoice/issuer/customers JSON Schemas
+# are hosted under <DOCS_URL>/schema/ (regenerated by `make docs`, sync-tested
+# in CI); `quints init` writes yaml-language-server modelines pointing there.
+DOCS_URL = "https://sealambda.github.io/quints"
+
 # Legal form → account-name component (Assets:CH:<component>:…). The keys are
 # the entity families the official KMU Kontenrahmen (veb.ch) prints Klasse-28
 # variants for: juristische Personen (gmbh, ag) and Einzelunternehmen;