akt-cli 0.4.1__tar.gz → 0.6.0__tar.gz

{akt_cli-0.4.1 → akt_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: akt-cli
-Version: 0.4.1
+Version: 0.6.0
 Summary: akt — a CLI toolbox to fully drive an Akaunting accounting instance
 Keywords: akaunting,accounting,cli,invoices,bills,api
 Author: AsyncAlchemist
@@ -171,6 +171,15 @@ akt tax create --name "Sales Tax" --rate 8.25
 akt bank create --name "Business Checking" --number 1001 --currency-code USD
 akt bank list
 
+# Open a book with a prior-period opening balance. The Double-Entry module
+# auto-posts an opening-balance journal entry dated to the account's creation
+# date; --opening-balance-date re-dates it to the period boundary so it lands in
+# the right financial year. Needs a positive --opening-balance.
+akt bank create --name "Business Checking" --number 1001 --currency-code USD \
+    --opening-balance 5000 --opening-balance-date 2024-12-31
+# Re-date the opening entry of an existing account:
+akt bank update 3 --opening-balance-date 2024-12-31
+
 # Invoice with line items (totals computed server-side; number auto-generated)
 akt invoice create --contact 12 \
     --item 'name=Consulting,price=150,quantity=10,item_id=2' \
@@ -246,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 "Market Data Feeds"
 ```
 
-`--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
@@ -258,6 +280,32 @@ akt company
 akt settings --search 'key:default.account'
 ```
 
+## 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.4.1 → akt_cli-0.6.0}/README.md

@@ -150,6 +150,15 @@ akt tax create --name "Sales Tax" --rate 8.25
 akt bank create --name "Business Checking" --number 1001 --currency-code USD
 akt bank list
 
+# Open a book with a prior-period opening balance. The Double-Entry module
+# auto-posts an opening-balance journal entry dated to the account's creation
+# date; --opening-balance-date re-dates it to the period boundary so it lands in
+# the right financial year. Needs a positive --opening-balance.
+akt bank create --name "Business Checking" --number 1001 --currency-code USD \
+    --opening-balance 5000 --opening-balance-date 2024-12-31
+# Re-date the opening entry of an existing account:
+akt bank update 3 --opening-balance-date 2024-12-31
+
 # Invoice with line items (totals computed server-side; number auto-generated)
 akt invoice create --contact 12 \
     --item 'name=Consulting,price=150,quantity=10,item_id=2' \
@@ -225,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 "Market Data Feeds"
 ```
 
-`--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
@@ -237,6 +259,32 @@ akt company
 akt settings --search 'key:default.account'
 ```
 
+## 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.4.1 → akt_cli-0.6.0}/pyproject.toml

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

{akt_cli-0.4.1 → akt_cli-0.6.0}/src/akt/cli.py

@@ -22,6 +22,8 @@ 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
 
 
 def _add_field_args(p: argparse.ArgumentParser, res: Resource, *, for_update: bool) -> None:
@@ -176,6 +178,30 @@ 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")
+
     return parser
 
 
@@ -226,6 +252,98 @@ 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
     raise ValueError(name)
 
 

{akt_cli-0.4.1 → akt_cli-0.6.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.4.1 → akt_cli-0.6.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.4.1 → akt_cli-0.6.0}/src/akt/commands.py

@@ -56,6 +56,8 @@ def cmd_create(res: Resource, client: Client, ns: Any) -> int:
     else:
         payload = client.post(endpoint, body, type_scope=type_scope)
     data = payload.get("data", payload) if isinstance(payload, dict) else payload
+    if res.post_write:
+        res.post_write(res, client, data, ns)
     emit(data, as_json=True)
     return 0
 
@@ -104,6 +106,8 @@ def cmd_update(res: Resource, client: Client, ns: Any) -> int:
             body["remove_attachment"] = 1
         payload = client.put(path, body, type_scope=type_scope)
     data = payload.get("data", payload) if isinstance(payload, dict) else payload
+    if res.post_write:
+        res.post_write(res, client, data, ns)
     emit(data, as_json=True)
     return 0
 

akt_cli-0.6.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.4.1 → akt_cli-0.6.0}/src/akt/registry.py

@@ -13,6 +13,7 @@ from .resources import (
     build_journal_update,
     build_payment_create,
     build_transfer_create,
+    redate_opening_balance,
     resolve_payment_delete,
     resolve_payment_update,
 )
@@ -101,6 +102,10 @@ BANK = Resource(
         f("type", "Account type", default="bank"),
         f("currency-code", "Currency code", default="USD"),
         f("opening-balance", "Opening balance", default=0),
+        f("opening-balance-date",
+          "Date for the opening-balance journal entry (YYYY-MM-DD). Re-dates the "
+          "entry the Double-Entry module auto-posts; needs a positive opening balance.",
+          dest="opening_balance_date", local=True),
         f("bank-name", "Bank name"),
         f("bank-phone", "Bank phone"),
         f("bank-address", "Bank address"),
@@ -112,6 +117,7 @@ BANK = Resource(
         ("Enabled", "enabled"),
     ],
     help="Bank / cash accounts",
+    post_write=redate_opening_balance,
 )
 
 CATEGORY = Resource(
@@ -223,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.4.1 → akt_cli-0.6.0}/src/akt/resources.py

@@ -12,6 +12,7 @@ import datetime as _dt
 import json
 import mimetypes
 import os
+import sys
 from dataclasses import dataclass, field
 from typing import Any, Callable
 
@@ -32,6 +33,7 @@ class Field:
     default: Any = None             # default applied on create when omitted
     is_flag: bool = False           # store_true boolean flag
     choices: list[str] | None = None
+    local: bool = False             # CLI flag only; never sent in the request body
 
 
 def f(name: str, help: str = "", **kw) -> Field:
@@ -69,6 +71,10 @@ class Resource:
     # returns (path, type_scope) for update; lets document-linked payments use
     # the nested route (the flat /transactions route 400s on any document_id)
     update_resolver: Callable[["Resource", Client, str, dict], "tuple[str, str | None]"] | None = None
+    # runs after a successful create/update on the /api path, with the returned
+    # record + the argparse namespace; used by bank to re-date the auto-posted
+    # opening-balance journal entry.
+    post_write: Callable[["Resource", Client, dict, Any], None] | None = None
 
     def contact_scope(self) -> str:
         """ACL scope of the contact tied to a document resource."""
@@ -205,6 +211,8 @@ def body_from_fields(res: Resource, ns: Any, *, for_update: bool,
     """
     body: dict[str, Any] = {}
     for fld in res.fields:
+        if fld.local:
+            continue
         val = getattr(ns, fld.dest, None)
         if fld.is_flag:
             # tri-state: only include if explicitly toggled
@@ -439,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
 
@@ -463,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)
@@ -507,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
@@ -733,6 +759,76 @@ def build_journal_update(res: Resource, client: Client, ns: Any, current: dict)
     return body
 
 
+# --------------------------------------------------------------------------
+# opening-balance journal entry re-dating (bank post_write hook)
+# --------------------------------------------------------------------------
+
+def _journal_reput_body(current: dict, *, paid_at: str, journal_number: str) -> dict:
+    """Full journal-entry PUT body that re-dates an existing entry, preserving
+    its ledgers (by id) and amounts. ``journal_number`` is supplied by the caller
+    (the server-created opening-balance entry carries none, but the API requires
+    one)."""
+    body: dict[str, Any] = {
+        "paid_at": paid_at,
+        "journal_number": journal_number,
+        "description": current.get("description"),
+        "basis": current.get("basis") or "accrual",
+        "currency_code": current.get("currency_code") or "USD",
+        "currency_rate": current.get("currency_rate", 1) or 1,
+        "amount": 0,
+        "items": _journal_items_from_current(current),
+    }
+    if current.get("reference"):
+        body["reference"] = current["reference"]
+    return body
+
+
+def _find_opening_balance_je(client: Client, record: dict) -> dict | None:
+    """Locate the opening-balance journal entry the Double-Entry module auto-posts
+    for a bank/cash account. It carries ``reference = "opening-balance:<coa_id>"``
+    and ``description`` ending ``";<account name>"``. The chart-of-accounts API
+    doesn't expose the bank<->coa link, so match on those two fields and, if an
+    account name is duplicated, take the newest by ``created_at``."""
+    name = str(record.get("name") or "")
+    suffix = ";" + name
+    matches = [
+        e for e in client.list("journal-entry", all_pages=True)
+        if str(e.get("reference") or "").startswith("opening-balance:")
+        and str(e.get("description") or "").endswith(suffix)
+    ]
+    if not matches:
+        return None
+    matches.sort(key=lambda e: str(e.get("created_at") or ""), reverse=True)
+    return matches[0]
+
+
+def redate_opening_balance(res: "Resource", client: Client, record: dict, ns: Any) -> None:
+    """post_write hook for bank create/update: re-date the auto-posted
+    opening-balance journal entry to ``--opening-balance-date``.
+
+    The Double-Entry module stamps that entry with the account's created_at and
+    exposes no date field, so we set the balance normally (keeping the Banking
+    register correct) and rewrite the entry's date here. Re-dating via the
+    journal-entry route also rewrites each ledger's issued_at (what reports
+    filter on), and the module's account-update path only touches ledger
+    amounts, so the date sticks across later edits."""
+    date = getattr(ns, "opening_balance_date", None)
+    if not date:
+        return
+    je = _find_opening_balance_je(client, record)
+    if je is None:
+        print(f"note: no opening-balance journal entry found for {res.noun} "
+              f"{record.get('id')}; --opening-balance-date had no effect "
+              f"(opening balance is 0, or the Double-Entry module / owners-"
+              f"contribution account is not configured)", file=sys.stderr)
+        return
+    number = je.get("journal_number") or _next_journal_number(client)
+    body = _journal_reput_body(je, paid_at=_normalize_date(date), journal_number=number)
+    client.put(f"journal-entry/{je['id']}", body)
+    print(f"note: re-dated opening-balance journal entry {je['id']} to {date}",
+          file=sys.stderr)
+
+
 # --------------------------------------------------------------------------
 # chart-of-accounts (double-entry) — web-surface CRUD body builder
 # --------------------------------------------------------------------------

akt_cli-0.6.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