quints 0.1.0__py3-none-any.whl

quints/config.py

@@ -0,0 +1,214 @@
+"""quints configuration — the entity lives in ``quints.toml``, not in code.
+
+Defaults are a neutral Swiss GmbH chart of accounts, so any repo following
+the ``CH:GmbH`` namespacing works out of the box; everything entity-specific
+(name, VAT registration, importer credentials/rules) comes from
+``quints.toml`` — a stranger with their own beancount file and a
+``quints.toml`` gets correct reports without touching this package.
+
+Precedence: an explicit ``--config`` path > ``./quints.toml`` > built-in
+defaults. VAT *rates* are deliberately not configurable — they are law and
+live in :data:`quints.ledger.VAT_RATES`.
+
+Modules take a ``cfg`` parameter (tests construct :class:`Config` inline) and
+fall back to :func:`get`, the process-wide config the CLI resolves once.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, replace
+from datetime import date as Date
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover
+    import tomli as tomllib
+
+DEFAULT_PATH = Path("quints.toml")
+
+
+@dataclass(frozen=True)
+class UbsImport:
+    """[import.ubs] — MT940 statements for one CHF bank account."""
+
+    account: str = "Assets:CH:GmbH:Current:UBS:CHF"
+    iban: str | None = None  # required to identify statements
+    currency: str = "CHF"
+    rules: tuple[tuple[str, str, str], ...] = ()  # (payee regex, account, flag)
+
+
+@dataclass(frozen=True)
+class WiseImport:
+    """[import.wise] — Wise balance statements, one account per currency."""
+
+    accounts: tuple[tuple[str, str], ...] = (  # (currency, account)
+        ("CHF", "Assets:CH:GmbH:Current:Wise:CHF"),
+        ("EUR", "Assets:CH:GmbH:Current:Wise:EUR"),
+        ("USD", "Assets:CH:GmbH:Current:Wise:USD"),
+    )
+    fees_account: str = "Expenses:CH:GmbH:BankFees:Wise"
+    holder: str | None = None  # businessName filter (multi-profile tokens)
+    rules: tuple[tuple[str, str, str], ...] = ()
+
+    @property
+    def account_map(self) -> dict[str, str]:
+        return dict(self.accounts)
+
+
+@dataclass(frozen=True)
+class StripeImport:
+    """[import.stripe] — Stripe balance transactions for one account."""
+
+    accounts: tuple[tuple[str, str], ...] = (("EUR", "Assets:CH:GmbH:Current:Stripe:EUR"),)
+    fees_account: str = "Expenses:CH:GmbH:BankFees:Stripe"
+    tax_account: str = "Assets:CH:GmbH:Tax:InputVAT"  # VAT within Stripe's own fees
+    account_id: str | None = None  # required: acct_… this key must belong to
+    rules: tuple[tuple[str, str, str], ...] = ()
+
+    @property
+    def account_map(self) -> dict[str, str]:
+        return dict(self.accounts)
+
+
+@dataclass(frozen=True)
+class Config:
+    # [entity]
+    entity_name: str = "Example GmbH"
+    vat_method: str = "effective"  # "saldo" would need a different Form-310 mapping
+    vat_registered_since: Date | None = None
+    operating_currency: str = "CHF"
+    # [ledger]
+    ledger_main: Path = Path("main.bean")
+    ledger_prices: Path = Path("prices.bean")
+    # [accounts]
+    input_vat: str = "Assets:CH:GmbH:Tax:InputVAT"
+    output_vat: str = "Liabilities:CH:GmbH:Tax:OutputVAT"
+    bezugsteuer: str = "Liabilities:CH:GmbH:Tax:Bezugsteuer"
+    payable_vat: str = "Liabilities:CH:GmbH:Tax:PayableVAT"
+    income_prefix: str = "Income:CH:GmbH"
+    export_marker: str = ":Export"
+    entity_marker: str = ":CH:GmbH:"
+    fx_gain: str = "Income:CH:GmbH:FX:CurrencyGain"
+    fx_loss: str = "Expenses:CH:GmbH:FX:CurrencyLoss"
+    receivable: str = "Assets:CH:GmbH:Receivable:Trade"
+    rounding_income: str = "Income:CH:GmbH:Rounding"
+    income_domestic: str = "Income:CH:GmbH:Consulting:External:Domestic"
+    income_export: str = "Income:CH:GmbH:Consulting:External:Export"
+    # [report]
+    report_language: str = "en"
+    # [import.*] — statement importers (plan 2); None = not configured
+    import_ubs: UbsImport | None = None
+    import_wise: WiseImport | None = None
+    import_stripe: StripeImport | None = None
+
+
+def _rules(section: dict) -> tuple[tuple[str, str, str], ...]:
+    return tuple((r[0], r[1], r[2]) for r in section.get("rules", ()))
+
+
+def _accounts_map(section: dict, default) -> tuple[tuple[str, str], ...]:
+    if "accounts" not in section:
+        return default
+    return tuple(sorted(section["accounts"].items()))
+
+
+def _import_sections(raw: dict) -> dict:
+    imports = raw.get("import") or {}
+    updates: dict = {}
+    if "ubs" in imports:
+        s = imports["ubs"]
+        updates["import_ubs"] = UbsImport(
+            account=s.get("account", UbsImport.account),
+            iban=s.get("iban"),
+            currency=s.get("currency", UbsImport.currency),
+            rules=_rules(s),
+        )
+    if "wise" in imports:
+        s = imports["wise"]
+        updates["import_wise"] = WiseImport(
+            accounts=_accounts_map(s, WiseImport.accounts),
+            fees_account=s.get("fees_account", WiseImport.fees_account),
+            holder=s.get("holder"),
+            rules=_rules(s),
+        )
+    if "stripe" in imports:
+        s = imports["stripe"]
+        updates["import_stripe"] = StripeImport(
+            accounts=_accounts_map(s, StripeImport.accounts),
+            fees_account=s.get("fees_account", StripeImport.fees_account),
+            tax_account=s.get("tax_account", StripeImport.tax_account),
+            account_id=s.get("account_id"),
+            rules=_rules(s),
+        )
+    return updates
+
+
+def _from_mapping(raw: dict) -> Config:
+    entity = raw.get("entity") or {}
+    ledger_ = raw.get("ledger") or {}
+    accounts = raw.get("accounts") or {}
+    report = raw.get("report") or {}
+    cfg = Config()
+    updates: dict = {}
+
+    def take(section: dict, key: str, field: str, cast=None):
+        if key in section:
+            value = section[key]
+            updates[field] = cast(value) if cast else value
+
+    take(entity, "name", "entity_name")
+    take(entity, "vat_method", "vat_method")
+    take(entity, "vat_registered_since", "vat_registered_since")
+    take(entity, "operating_currency", "operating_currency")
+    take(ledger_, "main", "ledger_main", Path)
+    take(ledger_, "prices", "ledger_prices", Path)
+    for key in (
+        "input_vat",
+        "output_vat",
+        "bezugsteuer",
+        "payable_vat",
+        "income_prefix",
+        "export_marker",
+        "entity_marker",
+        "fx_gain",
+        "fx_loss",
+        "receivable",
+        "rounding_income",
+        "income_domestic",
+        "income_export",
+    ):
+        take(accounts, key, key)
+    take(report, "language", "report_language")
+    updates.update(_import_sections(raw))
+    return replace(cfg, **updates)
+
+
+def load(path: Path | None = None) -> Config:
+    """Load ``path``, or ``./quints.toml`` if present, else defaults."""
+    if path is None:
+        path = DEFAULT_PATH if DEFAULT_PATH.exists() else None
+    if path is None:
+        return Config()
+    with open(path, "rb") as f:
+        return _from_mapping(tomllib.load(f))
+
+
+_current: Config | None = None
+_path: Path | None = None
+
+
+def set_path(path: Path | None) -> None:
+    """CLI hook: remember --config and invalidate the cached config."""
+    global _path, _current
+    _path = path
+    _current = None
+
+
+def get() -> Config:
+    """The process-wide config (cached; honors a previous :func:`set_path`)."""
+    global _current
+    if _current is None:
+        _current = load(_path)
+    return _current

quints/fava/__init__.py

@@ -0,0 +1,65 @@
+"""Fava extension: the quints review panel (docs/plans/06, plan 5.4.1).
+
+The read-only half of the approval-queue surface: VAT status, open
+receivables, staging drafts, and inbox backlog — the same compute layer
+the CLI's ``--json`` exposes, rendered inside the UI users already run.
+
+Enable in the beancount file:
+
+    2024-01-01 custom "fava-extension" "quints.fava"
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+from fava.ext import FavaExtensionBase
+
+from .. import config, receivables, settlement
+from .. import inbox as inbox_mod
+
+_DRAFT_LINE = re.compile(r"^\d{4}-\d{2}-\d{2} +([*!]) ", re.M)
+
+
+class QuintDashboard(FavaExtensionBase):
+    """VAT, receivables, and review-queue panel."""
+
+    report_title = "Quint"
+
+    @property
+    def _root(self) -> Path:
+        return Path(self.ledger.beancount_file_path).parent
+
+    @property
+    def _cfg(self) -> config.Config:
+        return config.load(
+            self._root / "quints.toml" if (self._root / "quints.toml").exists() else None
+        )
+
+    def today(self):
+        return datetime.now(timezone.utc).date()
+
+    def vat_status(self):
+        """(liabilities, unlinked_owed, total_owed, today) — see settlement."""
+        return settlement.outstanding(
+            Path(self.ledger.beancount_file_path),
+            cfg=self._cfg,
+            entries=self.ledger.all_entries,
+        )
+
+    def open_receivables(self):
+        return receivables.compute_from_entries(self.ledger.all_entries, self.today(), self._cfg)
+
+    def staging(self):
+        """Pending staging drafts: (file name, total drafts, flagged drafts)."""
+        out = []
+        for f in sorted((self._root / "staging").glob("*.bean")):
+            flags = _DRAFT_LINE.findall(f.read_text(encoding="utf-8"))
+            out.append((f.name, len(flags), flags.count("!")))
+        return out
+
+    def inbox(self):
+        """Inbox inventory (hints + duplicate/linked status) — see quints.inbox."""
+        return inbox_mod.scan(self._root, self.ledger.all_entries)

quints/fava/templates/QuintDashboard.html

@@ -0,0 +1,85 @@
+{% set liabilities, unlinked, vat_total, today = extension.vat_status() %}
+{% set open_invoices = extension.open_receivables() %}
+{% set staging = extension.staging() %}
+{% set inbox = extension.inbox() %}
+
+<div class="left">
+
+  <h3>VAT outstanding · {{ today }}</h3>
+  {% if not liabilities and not unlinked %}
+    <p>Nothing outstanding — all filed VAT is paid. ✓</p>
+  {% else %}
+    <table is="sortable-table">
+      <thead>
+        <tr><th data-sort="string">Period</th><th data-sort="num">Owed CHF</th>
+            <th data-sort="string">Due</th><th data-sort="num">Days left</th></tr>
+      </thead>
+      <tbody>
+        {% for l in liabilities %}
+        <tr>
+          <td>{{ l.period }}</td>
+          <td class="num">{{ l.owed }}</td>
+          <td>{{ l.due or "—" }}</td>
+          <td class="num">{{ l.days_left if l.days_left is not none else "—" }}</td>
+        </tr>
+        {% endfor %}
+        {% if unlinked %}
+        <tr><td>(unlinked)</td><td class="num">{{ unlinked }}</td><td>—</td><td></td></tr>
+        {% endif %}
+      </tbody>
+      <tfoot><tr><td>Total</td><td class="num">{{ vat_total }}</td><td></td><td></td></tr></tfoot>
+    </table>
+  {% endif %}
+
+  <h3>Open receivables</h3>
+  {% if not open_invoices %}
+    <p>Nothing open — every invoice is settled. ✓</p>
+  {% else %}
+    <table is="sortable-table">
+      <thead>
+        <tr><th data-sort="string">Invoice</th><th data-sort="string">Payee</th>
+            <th data-sort="string">Date</th><th data-sort="num">Age (d)</th>
+            <th data-sort="num">Open</th></tr>
+      </thead>
+      <tbody>
+        {% for o in open_invoices %}
+        <tr>
+          <td>{{ o.number }}</td>
+          <td>{{ o.payee }}</td>
+          <td>{{ o.invoice_date }}</td>
+          <td class="num"{% if o.age_days > 30 %} style="color: var(--budget-negative)"{% endif %}>{{ o.age_days }}</td>
+          <td class="num">{{ o.open_amount }} {{ o.currency }}</td>
+        </tr>
+        {% endfor %}
+      </tbody>
+    </table>
+  {% endif %}
+
+  <h3>Review queue</h3>
+  {% if not staging and not inbox %}
+    <p>Inbox and staging are empty. ✓</p>
+  {% else %}
+    {% if staging %}
+      <table>
+        <thead><tr><th>Staging file</th><th>Drafts</th><th>Needs decision (!)</th></tr></thead>
+        <tbody>
+          {% for name, total, flagged in staging %}
+          <tr><td>{{ name }}</td><td class="num">{{ total }}</td><td class="num">{{ flagged }}</td></tr>
+          {% endfor %}
+        </tbody>
+      </table>
+    {% endif %}
+    {% if inbox %}
+      <p>Inbox — {{ inbox | length }} document(s):</p>
+      <ul>
+        {% for d in inbox %}
+        <li>{{ d.name }}
+          {%- if d.duplicate_of %} — duplicate of {{ d.duplicate_of }}
+          {%- elif d.linked %} — already linked in ledger
+          {%- endif %}</li>
+        {% endfor %}
+      </ul>
+    {% endif %}
+  {% endif %}
+
+</div>

quints/fx.py

@@ -0,0 +1,164 @@
+"""Year-end FX revaluation of non-CHF GmbH balances (OR Art. 960 ff.).
+
+Beancount accounts hold plain units, so a currency account's **book value in
+CHF** is implicit: the sum of each posting's CHF weight (its booked ``@``/
+``@@`` rate, or the BAZG rate of the transaction date) — the same valuation
+the Erfolgsrechnung uses. The revaluation books, per currency, the difference
+between that book value and the balance valued at the report-date BAZG rate:
+
+    2026-12-31 * "Wise" "Year-end FX revaluation EUR (Art. 960 OR)"
+        Assets:…:Wise:EUR   -6395.74 EUR @@ 5952.86 CHF   ; out at book value
+        Assets:…:Wise:EUR    6395.74 EUR @@ 5900.11 CHF   ; back at year-end rate
+        Expenses:CH:GmbH:FX:CurrencyLoss  52.75 CHF
+
+Units net to zero; the CHF delta lands in CurrencyGain/CurrencyLoss. After
+booking, the account's implicit book value equals the year-end market value,
+so the KMU Bilanz's balancing result and the Erfolgsrechnung agree — the
+unrealized FX becomes explicit instead of a reconciling difference.
+
+Like the settlement, this prints ledger text to review and paste — it never
+writes the books.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date as Date
+from decimal import Decimal
+from pathlib import Path
+
+from beancount.core import convert as bc_convert
+from beancount.core import data
+from beancount.core import prices as bc_prices
+from beancount.core.inventory import Inventory
+from rich.console import Console
+
+from . import config, ledger, ui
+
+
+@dataclass
+class Revaluation:
+    currency: str
+    account: str
+    units: Decimal
+    book_chf: Decimal  # implicit book value (booked rates / txn-date BAZG)
+    market_chf: Decimal  # units at the report-date BAZG rate
+    rate: Decimal  # report-date rate used
+    rate_date: Date  # BAZG date of that rate
+
+    @property
+    def delta(self) -> Decimal:
+        """Positive = unrealized gain, negative = loss."""
+        return self.market_chf - self.book_chf
+
+
+class RateUnavailable(RuntimeError):
+    def __init__(self, ccy: str, on: Date):
+        super().__init__(f"no {ccy}→CHF rate on or before {on}")
+        self.ccy, self.on = ccy, on
+
+
+def compute(ledger_path: Path, at: str, cfg: config.Config | None = None) -> list[Revaluation]:
+    cfg = cfg or config.get()
+    on = Date.fromisoformat(at)
+    entries, _ = ledger.load_entries(ledger_path)
+    price_map = bc_prices.build_price_map(entries)
+
+    inventories: dict[str, Inventory] = {}
+    book: dict[tuple[str, str], Decimal] = {}  # (account, ccy) → CHF book value
+    for e in entries:
+        if not isinstance(e, data.Transaction) or e.date > on:
+            continue
+        for p in e.postings:
+            root = p.account.split(":", 1)[0]
+            if cfg.entity_marker not in p.account or root not in ("Assets", "Liabilities"):
+                continue
+            if p.units.currency == "CHF":
+                continue
+            inventories.setdefault(p.account, Inventory()).add_position(p)
+            weight = bc_convert.get_weight(p)
+            if weight.currency == "CHF":
+                chf = weight.number
+            else:
+                conv = bc_convert.convert_amount(weight, "CHF", price_map, date=e.date)
+                chf = conv.number if conv.currency == "CHF" else None
+            if chf is None:
+                raise RateUnavailable(p.units.currency, e.date)
+            key = (p.account, p.units.currency)
+            book[key] = book.get(key, Decimal("0")) + chf
+
+    revaluations: list[Revaluation] = []
+    for account, inv in sorted(inventories.items()):
+        for pos in inv:
+            units = pos.units.number.quantize(Decimal("0.01"))
+            if not units:
+                continue
+            rate_date, rate = ledger.rate(price_map, pos.units.currency, on)
+            if rate is None:
+                raise RateUnavailable(pos.units.currency, on)
+            market = ledger.rappen(units * Decimal(rate))
+            book_value = ledger.rappen(book.get((account, pos.units.currency), Decimal("0")))
+            revaluations.append(
+                Revaluation(
+                    currency=pos.units.currency,
+                    account=account,
+                    units=units,
+                    book_chf=book_value,
+                    market_chf=market,
+                    rate=Decimal(rate),
+                    rate_date=rate_date,
+                )
+            )
+    return revaluations
+
+
+def revaluation_text(
+    revaluations: list[Revaluation], at: str, cfg: config.Config | None = None
+) -> str:
+    """Paste-ready ledger text, one transaction per currency."""
+    cfg = cfg or config.get()
+    by_ccy: dict[str, list[Revaluation]] = {}
+    for r in revaluations:
+        if r.delta:
+            by_ccy.setdefault(r.currency, []).append(r)
+
+    chunks: list[str] = []
+    for ccy, items in sorted(by_ccy.items()):
+        lines = [
+            f'{at} * "Wise" "Year-end FX revaluation {ccy} (Art. 960 OR)"',
+        ]
+        total_delta = Decimal("0")
+        for r in items:
+            lines.append(
+                f"    ; {r.units} {ccy} @ {r.rate:.5f} CHF/{ccy} (BAZG {r.rate_date}) "
+                f"= {r.market_chf} CHF vs {r.book_chf} CHF book"
+            )
+            lines.append(f"    {r.account:<48} {-r.units:>12} {ccy} @@ {r.book_chf} CHF")
+            lines.append(f"    {r.account:<48} {r.units:>12} {ccy} @@ {r.market_chf} CHF")
+            total_delta += r.delta
+        if total_delta > 0:
+            lines.append(f"    {cfg.fx_gain:<48} {-total_delta:>12} CHF")
+        else:
+            lines.append(f"    {cfg.fx_loss:<48} {-total_delta:>12} CHF")
+        chunks.append("\n".join(lines))
+    return "\n\n".join(chunks)
+
+
+def render(revaluations: list[Revaluation], at: str, console: Console | None = None) -> None:
+    console = console or ui.console
+    if not any(r.delta for r in revaluations):
+        console.print(f"No unrealized FX at {at} — nothing to revalue.", style="ok")
+        return
+    console.print()
+    console.rule(f"[bold]FX revaluation[/]   per {at}")
+    for r in revaluations:
+        style = "refund" if r.delta > 0 else "owe" if r.delta < 0 else "muted"
+        console.print(
+            f"  {r.account}  {r.units} {r.currency}: book {ui.money(r.book_chf)} → "
+            f"market {ui.money(r.market_chf)} CHF  [{style}]{ui.money(r.delta)}[/]"
+        )
+    console.print()
+    console.print("Paste into books/<year>.bean (review first):", style="muted")
+    console.print()
+    console.print(revaluation_text(revaluations, at), highlight=False)
+    console.print()