akt-cli 0.5.0__tar.gz → 0.7.0__tar.gz

{akt_cli-0.5.0 → akt_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: akt-cli
-Version: 0.5.0
+Version: 0.7.0
 Summary: akt — a CLI toolbox to fully drive an Akaunting accounting instance
 Keywords: akaunting,accounting,cli,invoices,bills,api
 Author: AsyncAlchemist
@@ -255,10 +255,23 @@ akt coa sync --prune         # also DISABLE accounts/categories absent from the
 
 # code a transaction by GL account — akt auto-fills the mirror category:
 akt payment create --type expense --bank 1 --amount 120 --account 628
+# ...or by category name — akt reverse-fills the matching GL account:
+akt payment create --type expense --bank 1 --amount 120 --category "Cloud Hosting"
 ```
 
-`--account` takes a GL code or name (the double-entry account; see `--bank` for
-the bank/cash account). An explicit `--set de_account_id=` still wins.
+`--account`/`--category` are two ends of the same coin: give either and akt fills
+the other from the COA config, so the category report and the COA report always
+agree. `--account` takes a GL code or name; `--category` a mirror-category name
+(see `--bank` for the bank/cash account). An explicit `--set de_account_id=` still
+wins.
+
+**Enforcement (when a `--coa` config is loaded):** akt refuses to create a
+*standalone* income/expense transaction that has no GL account — you must pass
+`--account`, `--category`, or an explicit `--set de_account_id=`. This makes the
+"category set but GL account left to the module's 628/400 default" mistake
+impossible. Bill/invoice payments (which post to A/P–A/R) are exempt, and with no
+`--coa` config the old behaviour is unchanged. Use `akt verify` to catch any
+transactions (e.g. web-UI entries) that slipped past.
 
 # Anything else: raw API access
 akt raw GET reports
@@ -267,6 +280,50 @@ akt company
 akt settings --search 'key:default.account'
 ```
 
+## Financial reports (needs the akt-api module)
+
+Akaunting's trial balance, P&L, and balance sheet aren't in its JSON API. With
+the companion module installed, akt computes them from the ledger:
+
+```bash
+akt trial-balance --to 2025-12-31                 # every account, debits = credits
+akt report profit-loss --from 2025-01-01 --to 2025-12-31
+akt report balance-sheet --to 2025-12-31
+akt balance --account 105 --to 2025-12-31         # one account's balance
+akt balance --account 200 --to 2025-12-31 --expected 0   # reconcile: exit 1 on mismatch
+```
+
+`--expected` turns `akt balance` into a reconciliation primitive (compare an
+account to an external figure, non-zero exit on a mismatch). Balances aggregate
+through Akaunting's ledger relation, so soft-deleted transactions are excluded
+just as its own reports do.
+
+## Reading the ledger: the `akt-api` companion module
+
+Akaunting's Double-Entry app exposes only `journal-entry` and `chart-of-accounts`
+over the API — the ledger itself (where every transaction's postings land) has no
+endpoint. The optional **`akt-api`** companion module (in `akt-api/`, install it
+into your Akaunting `modules/` directory — see `akt-api/README.md`) adds a
+read-only `GET /api/akt/ledgers`. When it's present, extra commands light up; when
+it's not, they print an install hint and everything else works unchanged.
+
+```bash
+# Show what actually posted to a GL account (by code or name):
+akt ledger --account 628 --from 2025-01-01 --to 2025-12-31
+
+# Audit: every standalone income/expense transaction whose ACTUAL posted GL
+# account differs from the account that mirrors its category. Needs a --coa
+# config (to know the mapping) and the companion module (to read the ledger).
+# Exits non-zero when it finds mis-postings — handy in CI / a pre-close gate.
+akt --coa coa.toml verify --from 2025-01-01 --to 2025-12-31
+```
+
+Because the Double-Entry module posts to the ledger by `de_account_id`, not by
+category, a transaction can carry a tidy category yet post to the wrong GL
+account (e.g. the module's default "Other / Uncategorized"). `akt verify` is how
+you catch that — the category report and the COA report only agree when it comes
+back clean.
+
 ## Akaunting gotchas `akt` handles for you
 
 Driving Akaunting's API directly has sharp edges; `akt` papers over these:

{akt_cli-0.5.0 → akt_cli-0.7.0}/README.md

@@ -234,10 +234,23 @@ akt coa sync --prune         # also DISABLE accounts/categories absent from the
 
 # code a transaction by GL account — akt auto-fills the mirror category:
 akt payment create --type expense --bank 1 --amount 120 --account 628
+# ...or by category name — akt reverse-fills the matching GL account:
+akt payment create --type expense --bank 1 --amount 120 --category "Cloud Hosting"
 ```
 
-`--account` takes a GL code or name (the double-entry account; see `--bank` for
-the bank/cash account). An explicit `--set de_account_id=` still wins.
+`--account`/`--category` are two ends of the same coin: give either and akt fills
+the other from the COA config, so the category report and the COA report always
+agree. `--account` takes a GL code or name; `--category` a mirror-category name
+(see `--bank` for the bank/cash account). An explicit `--set de_account_id=` still
+wins.
+
+**Enforcement (when a `--coa` config is loaded):** akt refuses to create a
+*standalone* income/expense transaction that has no GL account — you must pass
+`--account`, `--category`, or an explicit `--set de_account_id=`. This makes the
+"category set but GL account left to the module's 628/400 default" mistake
+impossible. Bill/invoice payments (which post to A/P–A/R) are exempt, and with no
+`--coa` config the old behaviour is unchanged. Use `akt verify` to catch any
+transactions (e.g. web-UI entries) that slipped past.
 
 # Anything else: raw API access
 akt raw GET reports
@@ -246,6 +259,50 @@ akt company
 akt settings --search 'key:default.account'
 ```
 
+## Financial reports (needs the akt-api module)
+
+Akaunting's trial balance, P&L, and balance sheet aren't in its JSON API. With
+the companion module installed, akt computes them from the ledger:
+
+```bash
+akt trial-balance --to 2025-12-31                 # every account, debits = credits
+akt report profit-loss --from 2025-01-01 --to 2025-12-31
+akt report balance-sheet --to 2025-12-31
+akt balance --account 105 --to 2025-12-31         # one account's balance
+akt balance --account 200 --to 2025-12-31 --expected 0   # reconcile: exit 1 on mismatch
+```
+
+`--expected` turns `akt balance` into a reconciliation primitive (compare an
+account to an external figure, non-zero exit on a mismatch). Balances aggregate
+through Akaunting's ledger relation, so soft-deleted transactions are excluded
+just as its own reports do.
+
+## Reading the ledger: the `akt-api` companion module
+
+Akaunting's Double-Entry app exposes only `journal-entry` and `chart-of-accounts`
+over the API — the ledger itself (where every transaction's postings land) has no
+endpoint. The optional **`akt-api`** companion module (in `akt-api/`, install it
+into your Akaunting `modules/` directory — see `akt-api/README.md`) adds a
+read-only `GET /api/akt/ledgers`. When it's present, extra commands light up; when
+it's not, they print an install hint and everything else works unchanged.
+
+```bash
+# Show what actually posted to a GL account (by code or name):
+akt ledger --account 628 --from 2025-01-01 --to 2025-12-31
+
+# Audit: every standalone income/expense transaction whose ACTUAL posted GL
+# account differs from the account that mirrors its category. Needs a --coa
+# config (to know the mapping) and the companion module (to read the ledger).
+# Exits non-zero when it finds mis-postings — handy in CI / a pre-close gate.
+akt --coa coa.toml verify --from 2025-01-01 --to 2025-12-31
+```
+
+Because the Double-Entry module posts to the ledger by `de_account_id`, not by
+category, a transaction can carry a tidy category yet post to the wrong GL
+account (e.g. the module's default "Other / Uncategorized"). `akt verify` is how
+you catch that — the category report and the COA report only agree when it comes
+back clean.
+
 ## Akaunting gotchas `akt` handles for you
 
 Driving Akaunting's API directly has sharp edges; `akt` papers over these:

{akt_cli-0.5.0 → akt_cli-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "akt-cli"
-version = "0.5.0"
+version = "0.7.0"
 description = "akt — a CLI toolbox to fully drive an Akaunting accounting instance"
 readme = "README.md"
 license = "MIT"

{akt_cli-0.5.0 → akt_cli-0.7.0}/src/akt/cli.py

@@ -22,6 +22,9 @@ from .output import emit
 from .registry import RESOURCES, BY_NOUN
 from .resources import Resource, load_data_arg
 from .coa import load_coa, plan_sync, render_plan, apply_plan
+from .ledger import resolve_account_id
+from .verify import find_miscodings, build_recode_plan
+from . import reports
 
 
 def _add_field_args(p: argparse.ArgumentParser, res: Resource, *, for_update: bool) -> None:
@@ -176,9 +179,75 @@ def _build_parser() -> argparse.ArgumentParser:
                      help="disable accounts/categories absent from the config (never deletes)")
     csp.set_defaults(_special="coa_sync")
 
+    lp = sub.add_parser("ledger", parents=[common],
+                        help="Show general-ledger postings (needs the akt-api module)")
+    lp.add_argument("--account", required=True, metavar="CODE|NAME",
+                    help="Chart-of-accounts code or name to show postings for")
+    lp.add_argument("--from", dest="date_from", metavar="YYYY-MM-DD", help="Earliest issued_at")
+    lp.add_argument("--to", dest="date_to", metavar="YYYY-MM-DD", help="Latest issued_at")
+    lp.set_defaults(_special="ledger")
+
+    vp = sub.add_parser("verify", parents=[common],
+                        help="Audit standalone income/expense postings vs their category "
+                             "(needs akt-api + --coa)")
+    vp.add_argument("--from", dest="date_from", metavar="YYYY-MM-DD", help="Earliest paid_at")
+    vp.add_argument("--to", dest="date_to", metavar="YYYY-MM-DD", help="Latest paid_at")
+    vp.set_defaults(_special="verify")
+
+    rcp = sub.add_parser("recode", parents=[common],
+                         help="Repost mis-coded standalone income/expense txns to their "
+                              "category's GL account (needs akt-api + --coa)")
+    rcp.add_argument("--from", dest="date_from", metavar="YYYY-MM-DD", help="Earliest paid_at")
+    rcp.add_argument("--to", dest="date_to", metavar="YYYY-MM-DD", help="Latest paid_at")
+    rcp.add_argument("--dry-run", dest="dry_run", action="store_true",
+                     help="show the plan without writing anything")
+    rcp.set_defaults(_special="recode")
+
+    bp = sub.add_parser("balance", parents=[common],
+                        help="Show one account's balance (needs the akt-api module)")
+    bp.add_argument("--account", required=True, metavar="CODE|NAME")
+    bp.add_argument("--from", dest="date_from", metavar="YYYY-MM-DD")
+    bp.add_argument("--to", dest="date_to", metavar="YYYY-MM-DD")
+    bp.add_argument("--expected", type=float, metavar="AMOUNT",
+                    help="reconcile: compare to this figure, exit 1 on mismatch")
+    bp.set_defaults(_special="balance")
+
+    tp = sub.add_parser("trial-balance", parents=[common],
+                        help="Trial balance (needs the akt-api module)")
+    tp.add_argument("--from", dest="date_from", metavar="YYYY-MM-DD")
+    tp.add_argument("--to", dest="date_to", metavar="YYYY-MM-DD")
+    tp.set_defaults(_special="trial_balance")
+
+    rpp = sub.add_parser("report", parents=[common], help="Financial reports (needs the akt-api module)")
+    rpv = rpp.add_subparsers(dest="report_verb", metavar="<report>")
+    for verb, sp in (("profit-loss", "report_pnl"), ("balance-sheet", "report_bs")):
+        p = rpv.add_parser(verb, parents=[common])
+        p.add_argument("--from", dest="date_from", metavar="YYYY-MM-DD")
+        p.add_argument("--to", dest="date_to", metavar="YYYY-MM-DD")
+        p.set_defaults(_special=sp)
+
     return parser
 
 
+def _need_akt_api(client: Client, cmd: str) -> None:
+    if not client.has_ledger_api():
+        raise ValueError(f"`akt {cmd}` needs the akt-api companion module — "
+                         "install it into your Akaunting modules/ directory (see akt-api/README.md)")
+
+
+def _fetch_balances(client: Client, ns: Any):
+    accounts = client.list("chart-of-accounts", all_pages=True)
+    accts_by_id = {a["id"]: {"code": a.get("code"), "name": a.get("name"),
+                             "type_id": a.get("type_id")} for a in accounts}
+    params: dict[str, Any] = {}
+    if getattr(ns, "date_from", None):
+        params["date_from"] = ns.date_from
+    if getattr(ns, "date_to", None):
+        params["date_to"] = ns.date_to
+    rows = client.list("akt-api/balances", all_pages=True, params=params or None)
+    return reports.balances_by_id(rows), accts_by_id, accounts
+
+
 def _run_special(name: str, client: Client, ns: Any) -> int:
     if name == "ping":
         emit(client.get("ping"), as_json=True)
@@ -226,6 +295,155 @@ def _run_special(name: str, client: Client, ns: Any) -> int:
         summary = apply_plan(client, plan, prune=ns.prune)
         print("applied: " + ", ".join(f"{k}={v}" for k, v in summary.items() if v))
         return 0
+    if name == "ledger":
+        if not client.has_ledger_api():
+            raise ValueError("`akt ledger` needs the akt-api companion module — "
+                             "install it into your Akaunting modules/ directory (see akt-api/README.md)")
+        accounts = client.list("chart-of-accounts", all_pages=True)
+        account_id = resolve_account_id(accounts, ns.account)
+        params: dict = {"account_id": account_id}
+        if ns.date_from:
+            params["issued_from"] = ns.date_from
+        if ns.date_to:
+            params["issued_to"] = ns.date_to
+        rows = client.list("akt-api/ledgers", params=params, all_pages=True)
+        cols = ["issued_at", "entry_type", "debit", "credit", "ledgerable_type", "ledgerable_id"]
+        emit(rows, as_json=ns.json, columns=None if ns.json else cols,
+             headers=["Date", "Type", "Debit", "Credit", "Source", "Source ID"])
+        return 0
+    if name == "verify":
+        coa = ns._coa
+        if coa is None:
+            raise ValueError("`akt verify` needs a COA config (use --coa FILE or set AKT_COA_FILE)")
+        if not client.has_ledger_api():
+            raise ValueError("`akt verify` needs the akt-api companion module — "
+                             "install it into your Akaunting modules/ directory (see akt-api/README.md)")
+
+        txns = [t for t in client.list("transactions", all_pages=True)
+                if t.get("type") in ("income", "expense") and not t.get("document_id")]
+        if ns.date_from:
+            txns = [t for t in txns if str(t.get("paid_at", ""))[:10] >= ns.date_from]
+        if ns.date_to:
+            txns = [t for t in txns if str(t.get("paid_at", ""))[:10] <= ns.date_to]
+
+        categories_by_id = {c["id"]: {"name": c.get("name"), "type": c.get("type")}
+                            for c in client.list("categories", all_pages=True)}
+        accounts = client.list("chart-of-accounts", all_pages=True)
+        accounts_by_id = {a["id"]: {"code": a.get("code"), "name": a.get("name")} for a in accounts}
+        accounts_by_code = {int(a["code"]): a["id"] for a in accounts if a.get("code") is not None}
+
+        item_ledgers = client.list("akt-api/ledgers", all_pages=True, params={
+            "ledgerable_type": "App\\Models\\Banking\\Transaction", "entry_type": "item"})
+        item_account_by_txn = {int(l["ledgerable_id"]): int(l["account_id"]) for l in item_ledgers}
+
+        findings = find_miscodings(txns, categories_by_id, accounts_by_id,
+                                   accounts_by_code, item_account_by_txn, coa)
+        cols = ["transaction_id", "paid_at", "amount", "category",
+                "expected_code", "actual_code", "reason"]
+        emit(findings, as_json=ns.json, columns=None if ns.json else cols,
+             headers=["Txn", "Date", "Amount", "Category", "Expected", "Actual", "Reason"])
+        return 0 if not findings else 1
+    if name == "recode":
+        coa = ns._coa
+        if coa is None:
+            raise ValueError("`akt recode` needs a COA config (use --coa FILE or set AKT_COA_FILE)")
+        if not client.has_ledger_api():
+            raise ValueError("`akt recode` needs the akt-api companion module — "
+                             "install it into your Akaunting modules/ directory (see akt-api/README.md)")
+
+        txns = [t for t in client.list("transactions", all_pages=True)
+                if t.get("type") in ("income", "expense") and not t.get("document_id")]
+        if ns.date_from:
+            txns = [t for t in txns if str(t.get("paid_at", ""))[:10] >= ns.date_from]
+        if ns.date_to:
+            txns = [t for t in txns if str(t.get("paid_at", ""))[:10] <= ns.date_to]
+        category_by_txn = {int(t["id"]): t.get("category_id") for t in txns}
+
+        categories_by_id = {c["id"]: {"name": c.get("name"), "type": c.get("type")}
+                            for c in client.list("categories", all_pages=True)}
+        accounts = client.list("chart-of-accounts", all_pages=True)
+        accounts_by_id = {a["id"]: {"code": a.get("code"), "name": a.get("name")} for a in accounts}
+        accounts_by_code = {int(a["code"]): a["id"] for a in accounts if a.get("code") is not None}
+        item_ledgers = [{"id": l["id"], "ledgerable_id": int(l["ledgerable_id"]),
+                         "account_id": int(l["account_id"])}
+                        for l in client.list("akt-api/ledgers", all_pages=True, params={
+                            "ledgerable_type": "App\\Models\\Banking\\Transaction",
+                            "entry_type": "item"})]
+
+        plan = build_recode_plan(item_ledgers, category_by_txn, categories_by_id,
+                                 accounts_by_id, accounts_by_code, coa)
+        cols = ["transaction_id", "category", "from_code", "to_code", "ledger_id"]
+        if ns.dry_run or not plan:
+            emit(plan, as_json=ns.json, columns=None if ns.json else cols,
+                 headers=["Txn", "Category", "From", "To", "LedgerRow"])
+            if not ns.json:
+                print(f"\n{len(plan)} transaction(s) would be recoded (dry-run)."
+                      if plan else "nothing to recode — all coded correctly.")
+            return 0
+        done = 0
+        for p in plan:
+            client.request("PATCH", f"akt-api/ledgers/{p['ledger_id']}",
+                           json_body={"account_id": p["to_account_id"]})
+            done += 1
+        print(f"recoded {done} transaction(s).")
+        return 0
+    if name == "balance":
+        _need_akt_api(client, "balance")
+        balances, accts_by_id, accounts = _fetch_balances(client, ns)
+        account_id = resolve_account_id(accounts, ns.account)
+        bal = balances.get(account_id, 0.0)
+        if ns.expected is not None:
+            r = reports.reconcile(bal, ns.expected)
+            emit(r, as_json=ns.json,
+                 columns=None if ns.json else ["actual", "expected", "diff", "ok"],
+                 headers=["Balance", "Expected", "Diff", "OK"])
+            return 0 if r["ok"] else 1
+        emit({"account_id": account_id, "balance": round(bal, 2)}, as_json=ns.json,
+             columns=None if ns.json else ["account_id", "balance"],
+             headers=["Account", "Balance"])
+        return 0
+    if name == "trial_balance":
+        _need_akt_api(client, "trial-balance")
+        balances, accts_by_id, _ = _fetch_balances(client, ns)
+        tb = reports.build_trial_balance(balances, accts_by_id)
+        if ns.json:
+            emit(tb, as_json=True)
+        else:
+            emit(tb["rows"], as_json=False, columns=["code", "name", "debit", "credit"],
+                 headers=["Code", "Account", "Debit", "Credit"])
+            print(f"  {'TOTAL':>34}  {tb['total_debit']:>12,.2f}  {tb['total_credit']:>12,.2f}")
+            print("  BALANCED" if tb["balanced"] else "  *** OUT OF BALANCE")
+        return 0 if tb["balanced"] else 1
+    if name == "report_pnl":
+        _need_akt_api(client, "report profit-loss")
+        balances, accts_by_id, _ = _fetch_balances(client, ns)
+        pl = reports.build_profit_loss(balances, accts_by_id)
+        if ns.json:
+            emit(pl, as_json=True)
+        else:
+            print("INCOME")
+            emit(pl["income"], as_json=False, columns=["code", "name", "amount"], headers=["Code", "Account", "Amount"])
+            print(f"  {'Total income':>40}  {pl['total_income']:>12,.2f}\n\nEXPENSES")
+            emit(pl["expense"], as_json=False, columns=["code", "name", "amount"], headers=["Code", "Account", "Amount"])
+            print(f"  {'Total expenses':>40}  {pl['total_expense']:>12,.2f}")
+            print(f"  {'NET PROFIT':>40}  {pl['net_profit']:>12,.2f}")
+        return 0
+    if name == "report_bs":
+        _need_akt_api(client, "report balance-sheet")
+        balances, accts_by_id, _ = _fetch_balances(client, ns)
+        bs = reports.build_balance_sheet(balances, accts_by_id)
+        if ns.json:
+            emit(bs, as_json=True)
+        else:
+            for title, key, tot in (("ASSETS", "assets", "total_assets"),
+                                    ("LIABILITIES", "liabilities", "total_liabilities"),
+                                    ("EQUITY", "equity", "total_equity")):
+                print(title)
+                emit(bs[key], as_json=False, columns=["code", "name", "amount"], headers=["Code", "Account", "Amount"])
+                print(f"  {'Total ' + title.lower():>40}  {bs[tot]:>12,.2f}\n")
+            print(f"  {'Net income to date':>40}  {bs['net_income']:>12,.2f}")
+            print("  BALANCED" if bs["balanced"] else "  *** DOES NOT BALANCE")
+        return 0 if bs["balanced"] else 1
     raise ValueError(name)
 
 

{akt_cli-0.5.0 → akt_cli-0.7.0}/src/akt/client.py

@@ -69,6 +69,7 @@ class Client:
         self._last_request = 0.0
         self._settings_cache: dict[str, Any] = {}
         self._settings_loaded = False
+        self._capabilities: dict[str, bool] = {}  # optional-module probes (e.g. akt-api)
         self._web_authed = False  # whether a web (session-cookie) login has run
         self._session = requests.Session()
         self._session.auth = (config.email, config.password)
@@ -191,6 +192,20 @@ class Client:
     def get(self, path: str, **kw) -> Any:
         return self.request("GET", path, **kw)
 
+    def has_ledger_api(self) -> bool:
+        """True if the akt-api companion module is installed (GET /api/akt-api/ledgers
+        is reachable). A 404 means the module is absent. Cached per client."""
+        if "ledger_api" not in self._capabilities:
+            try:
+                self.get("akt-api/ledgers", params={"limit": 1})
+                self._capabilities["ledger_api"] = True
+            except ApiError as e:
+                if e.status == 404:
+                    self._capabilities["ledger_api"] = False
+                else:
+                    raise
+        return self._capabilities["ledger_api"]
+
     def post(self, path: str, json_body: Any, **kw) -> Any:
         return self.request("POST", path, json_body=json_body, **kw)
 

{akt_cli-0.5.0 → akt_cli-0.7.0}/src/akt/coa.py

@@ -53,6 +53,16 @@ class CoaConfig:
                 return a
         return None
 
+    def by_category(self, category: str, category_type: str | None = None) -> CoaAccount | None:
+        """Reverse of by_name: the mirrored account whose mirror category matches
+        (name, and type when given). Non-mirrored accounts have no category."""
+        for a in self.accounts:
+            if a.mirror and a.category == category and (
+                category_type is None or a.category_type == category_type
+            ):
+                return a
+        return None
+
     @property
     def mirrored(self) -> list[CoaAccount]:
         return [a for a in self.accounts if a.mirror]
@@ -265,12 +275,21 @@ def _find_account(config: CoaConfig, ref: str) -> CoaAccount:
     return acct
 
 
-def resolve_coding(config: CoaConfig, client, *, account_ref: str) -> tuple[int, int]:
-    """Resolve --account to live (de_account_id, category_id).
+def resolve_coding(config: CoaConfig, client, *, account_ref: str | None = None,
+                   category_ref: str | None = None) -> tuple[int, int]:
+    """Resolve --account OR --category to live (de_account_id, category_id).
+
+    Pass exactly one ref. Both directions require the account to be mirrored and
+    both the account and its mirror category to already exist (run `coa sync`)."""
+    if (account_ref is None) == (category_ref is None):
+        raise ValueError("resolve_coding needs exactly one of account_ref / category_ref")
 
-    The account must already exist in Akaunting (run `coa sync`); category_id
-    is auto-derived from its mirror category, which must also already exist."""
-    acct = _find_account(config, account_ref)
+    if account_ref is not None:
+        acct = _find_account(config, account_ref)
+    else:
+        acct = next((a for a in config.accounts if a.mirror and a.category == category_ref), None)
+        if acct is None:
+            raise ValueError(f"category {category_ref!r} has no mirrored account in the COA config")
 
     if not acct.mirror:
         raise ValueError(

akt_cli-0.7.0/src/akt/ledger.py

@@ -0,0 +1,13 @@
+"""Helpers for the `akt ledger` command."""
+from __future__ import annotations
+
+
+def resolve_account_id(live_accounts: list[dict], ref: str) -> int:
+    """Map a chart-of-accounts ref (numeric code or exact name) to its live id."""
+    if str(ref).lstrip("-").isdigit():
+        hit = next((a for a in live_accounts if int(a.get("code", -1)) == int(ref)), None)
+    else:
+        hit = next((a for a in live_accounts if a.get("name") == ref), None)
+    if hit is None:
+        raise ValueError(f"account {ref!r} not found in the chart of accounts")
+    return int(hit["id"])

{akt_cli-0.5.0 → akt_cli-0.7.0}/src/akt/registry.py

@@ -229,6 +229,9 @@ PAYMENT = Resource(
         f("account", "GL/chart-of-accounts code or name to post to (the double-entry "
                      "account). Requires a --coa config; auto-fills the mirrored "
                      "category. See --bank for the bank/cash account."),
+        f("category", "Mirror category NAME to post under (requires a --coa config; "
+                      "reverse-fills the matching GL account). Mutually exclusive "
+                      "with --account."),
         f("document-id", "Linked document id (advanced)"),
         f("contact-id", "Contact id"),
         f("amount", "Payment amount"),

akt_cli-0.7.0/src/akt/reports.py

@@ -0,0 +1,99 @@
+"""Financial report builders — pure functions over per-account balances.
+
+A `balances` map is {account_id: debit - credit}. `accounts_by_id` is
+{id: {"code":..., "name":..., "type_id":...}} from the chart of accounts.
+"""
+from __future__ import annotations
+
+import sys
+
+# DoubleEntry standard seeds (Database/Seeds/Types.php): type_id -> class_id.
+CLASS_NAMES = {1: "Assets", 2: "Liabilities", 3: "Expenses", 4: "Income", 5: "Equity"}
+TYPE_ID_CLASS = {1: 1, 2: 1, 3: 1, 4: 1, 5: 1, 6: 1, 10: 1,   # assets (incl. depreciation)
+                 7: 2, 8: 2, 9: 2, 17: 2,                      # liabilities (incl. tax)
+                 11: 3, 12: 3,                                 # expenses (incl. direct costs)
+                 13: 4, 14: 4, 15: 4,                          # income
+                 16: 5}                                        # equity
+
+
+def account_class(type_id) -> "int | None":
+    c = TYPE_ID_CLASS.get(type_id)
+    if c is None:
+        print(f"warning: unknown account type_id {type_id}; excluded from "
+              f"class-grouped reports", file=sys.stderr)
+    return c
+
+
+def balances_by_id(rows: list[dict]) -> dict[int, float]:
+    return {int(r["account_id"]): round(float(r.get("debit") or 0)
+                                        - float(r.get("credit") or 0), 2)
+            for r in rows}
+
+
+def _line(a: dict, amount: float) -> dict:
+    return {"code": a.get("code"), "name": a.get("name"), "amount": round(amount, 2)}
+
+
+def build_trial_balance(balances: dict[int, float], accounts_by_id: dict[int, dict]) -> dict:
+    rows = []
+    for aid, bal in balances.items():
+        if abs(bal) < 0.005:
+            continue
+        a = accounts_by_id.get(aid, {})
+        rows.append({"code": a.get("code"), "name": a.get("name"),
+                     "debit": round(bal, 2) if bal > 0 else 0.0,
+                     "credit": round(-bal, 2) if bal < 0 else 0.0})
+    rows.sort(key=lambda r: (r["code"] is None, str(r["code"])))
+    total_debit = round(sum(r["debit"] for r in rows), 2)
+    total_credit = round(sum(r["credit"] for r in rows), 2)
+    return {"rows": rows, "total_debit": total_debit, "total_credit": total_credit,
+            "balanced": abs(total_debit - total_credit) < 0.02}
+
+
+def build_profit_loss(balances: dict[int, float], accounts_by_id: dict[int, dict]) -> dict:
+    income, expense = [], []
+    for aid, bal in balances.items():
+        a = accounts_by_id.get(aid, {})
+        cls = account_class(a.get("type_id"))
+        if cls == 4 and abs(bal) >= 0.005:
+            income.append(_line(a, -bal))          # income is credit-positive
+        elif cls == 3 and abs(bal) >= 0.005:
+            expense.append(_line(a, bal))          # expense is debit-positive
+    income.sort(key=lambda r: str(r["code"]))
+    expense.sort(key=lambda r: str(r["code"]))
+    total_income = round(sum(i["amount"] for i in income), 2)
+    total_expense = round(sum(e["amount"] for e in expense), 2)
+    return {"income": income, "expense": expense, "total_income": total_income,
+            "total_expense": total_expense, "net_profit": round(total_income - total_expense, 2)}
+
+
+def build_balance_sheet(balances: dict[int, float], accounts_by_id: dict[int, dict]) -> dict:
+    assets, liabilities, equity = [], [], []
+    net_income = 0.0
+    for aid, bal in balances.items():
+        a = accounts_by_id.get(aid, {})
+        cls = account_class(a.get("type_id"))
+        if cls == 1 and abs(bal) >= 0.005:
+            assets.append(_line(a, bal))           # asset debit-positive
+        elif cls == 2 and abs(bal) >= 0.005:
+            liabilities.append(_line(a, -bal))     # liability credit-positive
+        elif cls == 5 and abs(bal) >= 0.005:
+            equity.append(_line(a, -bal))          # equity credit-positive
+        elif cls in (3, 4):
+            net_income += -bal                     # income(+) and expense(-) both -bal
+    for s in (assets, liabilities, equity):
+        s.sort(key=lambda r: str(r["code"]))
+    total_assets = round(sum(x["amount"] for x in assets), 2)
+    total_liabilities = round(sum(x["amount"] for x in liabilities), 2)
+    total_equity = round(sum(x["amount"] for x in equity), 2)
+    net_income = round(net_income, 2)
+    return {"assets": assets, "liabilities": liabilities, "equity": equity,
+            "net_income": net_income, "total_assets": total_assets,
+            "total_liabilities": total_liabilities, "total_equity": total_equity,
+            "balanced": abs(total_assets - (total_liabilities + total_equity + net_income)) < 0.02}
+
+
+def reconcile(actual: float, expected: float, tol: float = 0.005) -> dict:
+    diff = round(actual - expected, 2)
+    return {"actual": round(actual, 2), "expected": round(expected, 2),
+            "diff": diff, "ok": abs(actual - expected) < tol}

{akt_cli-0.5.0 → akt_cli-0.7.0}/src/akt/resources.py

@@ -447,13 +447,18 @@ def build_payment_create(res: Resource, client: Client, ns: Any) -> dict:
 
     coa = getattr(ns, "_coa", None)
     account_ref = getattr(ns, "account", None)
+    category_ref = getattr(ns, "category", None)
     de_account_id = None
-    if account_ref:
+    if account_ref and category_ref:
+        raise ValueError("pass only one of --account / --category")
+    if account_ref or category_ref:
         if coa is None:
             raise ValueError(
-                "--account requires a COA config (pass --coa FILE or set AKT_COA_FILE)")
-        coa_de_account_id, coa_category_id = resolve_coding(coa, client, account_ref=account_ref)
-        de_account_id = coa_de_account_id
+                "--account/--category requires a COA config (pass --coa FILE or set AKT_COA_FILE)")
+        if account_ref:
+            de_account_id, coa_category_id = resolve_coding(coa, client, account_ref=account_ref)
+        else:                               # --category NAME -> reverse-resolve the GL account
+            de_account_id, coa_category_id = resolve_coding(coa, client, category_ref=category_ref)
         if category_id is None:            # explicit --category-id wins
             category_id = coa_category_id
 
@@ -471,6 +476,20 @@ def build_payment_create(res: Resource, client: Client, ns: Any) -> dict:
         contact_id = contact_id or document.get("contact_id")
         category_id = category_id or document.get("category_id")
 
+    # Config-gated enforcement (revises the COA spec's Decision #3): with a COA
+    # config loaded, a STANDALONE income/expense payment must resolve a GL account
+    # — via --account, --category, or an explicit --set/--data de_account_id.
+    # Bill/invoice payments (document_id set) post to A/P–A/R and are exempt.
+    # With no COA config, behaviour is unchanged (legacy).
+    overrides = {**parse_set(getattr(ns, "set_", None)),
+                 **load_data_arg(getattr(ns, "data", None))}
+    if (coa is not None and document_id is None and de_account_id is None
+            and "de_account_id" not in overrides):
+        raise ValueError(
+            "standalone income/expense payment needs a GL account — pass --account "
+            "CODE|NAME or --category NAME (with a COA config loaded, akt won't create "
+            "an un-GL-coded transaction). Use --set de_account_id=<id> to override.")
+
     if category_id is None:
         key = "default.income_category" if ptype == "income" else "default.expense_category"
         val = client.setting(key)
@@ -515,8 +534,7 @@ def build_payment_create(res: Resource, client: Client, ns: Any) -> dict:
         body["description"] = ns.description
     if de_account_id is not None:
         body["de_account_id"] = de_account_id
-    body.update(parse_set(getattr(ns, "set_", None)))
-    body.update(load_data_arg(getattr(ns, "data", None)))
+    body.update(overrides)   # --set / --data win (computed once, above)
 
     # A payment tied to a document must be posted to the nested route
     # POST /documents/{id}/transactions (the flat /transactions endpoint rejects

akt_cli-0.7.0/src/akt/verify.py

@@ -0,0 +1,73 @@
+"""Read-and-compare audit: each standalone income/expense transaction's actual
+posted GL account vs the COA mirror of its category."""
+from __future__ import annotations
+
+from .coa import CoaConfig
+
+
+def find_miscodings(transactions: list[dict], categories_by_id: dict[int, dict],
+                    accounts_by_id: dict[int, dict], accounts_by_code: dict[int, int],
+                    item_account_by_txn: dict[int, int], coa: CoaConfig) -> list[dict]:
+    """Return one finding per transaction whose actual posted item-leg GL account
+    differs from the account that mirrors its category. Pure — all lookups are
+    passed in pre-fetched."""
+    findings: list[dict] = []
+    for t in transactions:
+        cat = categories_by_id.get(t.get("category_id"))
+        cat_name = cat["name"] if cat else None
+        expected = coa.by_category(cat_name, cat["type"]) if cat else None
+        actual_id = item_account_by_txn.get(t["id"])
+        actual = accounts_by_id.get(actual_id) if actual_id is not None else None
+
+        if expected is None:
+            reason = "category has no mirror account in COA"
+        else:
+            expected_id = accounts_by_code.get(expected.code)
+            if actual_id == expected_id:
+                continue                                   # correctly coded
+            reason = "posted to the wrong GL account" if actual_id is not None \
+                else "not posted to the ledger"
+
+        findings.append({
+            "transaction_id": t["id"],
+            "paid_at": str(t.get("paid_at", ""))[:10],
+            "amount": t.get("amount"),
+            "category": cat_name,
+            "expected_code": expected.code if expected else None,
+            "expected_name": expected.name if expected else None,
+            "actual_code": actual["code"] if actual else None,
+            "actual_name": actual["name"] if actual else None,
+            "reason": reason,
+        })
+    return findings
+
+
+def build_recode_plan(item_ledgers: list[dict], category_by_txn: dict[int, int],
+                      categories_by_id: dict[int, dict], accounts_by_id: dict[int, dict],
+                      accounts_by_code: dict[int, int], coa: CoaConfig) -> list[dict]:
+    """Per mis-coded item-leg, the ledger row + target account to repoint it to.
+
+    Only rows whose transaction is in ``category_by_txn`` (the standalone
+    income/expense set) and whose category maps to a mirror account that differs
+    from where it currently sits are included."""
+    plan: list[dict] = []
+    for row in item_ledgers:
+        txn = row["ledgerable_id"]
+        cat = categories_by_id.get(category_by_txn.get(txn))
+        expected = coa.by_category(cat["name"], cat["type"]) if cat else None
+        if expected is None:
+            continue
+        to_id = accounts_by_code.get(expected.code)
+        if to_id is None or row["account_id"] == to_id:
+            continue                                   # unmapped, or already correct
+        frm = accounts_by_id.get(row["account_id"]) or {}
+        plan.append({
+            "ledger_id": row["id"],
+            "transaction_id": txn,
+            "from_account_id": row["account_id"],
+            "from_code": frm.get("code"),
+            "to_account_id": to_id,
+            "to_code": expected.code,
+            "category": cat["name"],
+        })
+    return plan