akt-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{akt_cli-0.2.0 → akt_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: akt-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: akt — a CLI toolbox to fully drive an Akaunting accounting instance
 Keywords: akaunting,accounting,cli,invoices,bills,api
 Author: AsyncAlchemist
@@ -24,7 +24,7 @@ Description-Content-Type: text/markdown
 # akt — Akaunting CLI toolbox
 ### Drive your Akaunting accounting instance entirely from the command line
 
->`akt` gives you full create / read / update / delete for customers, vendors, items, invoices, bills, payments, accounts, categories, taxes, currencies and transfers — plus a `raw` escape hatch for any other endpoint. Built and tested against [Akaunting](https://akaunting.com) **3.1.x**; works with any 3.x deployment that exposes the REST API.
+>`akt` gives you full create / read / update / delete for customers, vendors, items, invoices, bills, payments, accounts, categories, taxes, currencies and transfers — plus double-entry journal entries and the chart of accounts, and a `raw` escape hatch for any other endpoint. Built and tested against [Akaunting](https://akaunting.com) **3.1.x**; works with any 3.x deployment that exposes the REST API.
 
 [![PyPI Version](https://img.shields.io/pypi/v/akt-cli.svg?style=flat-square)](https://pypi.org/project/akt-cli/)
 [![Tests](https://img.shields.io/github/actions/workflow/status/AsyncAlchemist/akt-cli/ci.yml?branch=main&label=tests&style=flat-square)](https://github.com/AsyncAlchemist/akt-cli/actions/workflows/ci.yml)
@@ -101,8 +101,18 @@ Akaunting folds several nouns onto shared endpoints; `akt` hides that:
 | `invoice`  | `documents`    | document of type `invoice`                         |
 | `bill`     | `documents`    | document of type `bill`                            |
 | `payment`  | `transactions` | income (invoice) or expense (bill) transaction    |
+| `journal-entry` | `journal-entry` | double-entry general-ledger entry (module)     |
+| `chart-of-account` | `chart-of-accounts` | GL accounts — read via API, CRUD via web    |
 | `item`, `account`, `category`, `tax`, `currency`, `transfer` | as named | |
 
+> `journal-entry` and `chart-of-account` require the **Double-Entry** module
+> installed on the instance. The module publishes chart-of-accounts read-only on
+> the `/api` surface (index/show); its create/update/delete live only on the
+> session/CSRF **web** route. `akt chart-of-account` gives you the full verb set
+> anyway — `list`/`get` hit `/api`, while `create`/`update`/`delete` transparently
+> drive the web CRUD with your admin session (the same mechanism
+> `download-attachment` already uses).
+
 > The `contacts` and `documents` endpoints derive their permission from a
 > `search=type:<x>` query param. `akt` injects this automatically — calling them
 > raw without it returns `403 necessary access rights`.
@@ -181,6 +191,29 @@ akt bill attachments 41                             # list attached files
 akt bill download-attachment 41 --out ./downloads   # save to disk
 akt payment update 57 --remove-attachment           # clear attachments
 
+# Double-entry general ledger (requires the Double-Entry module)
+akt chart-of-account list                              # read the chart of accounts
+akt chart-of-account get 12
+
+# Build the chart of accounts as code (create/update/delete run via the web
+# session; type-id is the double-entry account-type id — copy it from an
+# existing account's `type_id`)
+akt chart-of-account create --name "Cash on Hand" --code 1010 --type-id 6
+akt chart-of-account create --name "Petty Cash" --code 1011 --type-id 6 --account-id 12
+akt chart-of-account update 12 --code 1000 --description "Operating cash"
+akt chart-of-account delete 12
+
+# Post a balanced journal entry (>= 2 lines; debits must equal credits;
+# journal number auto-generated, basis defaults to accrual)
+akt journal-entry create --description "Owner capital contribution" \
+    --item 'account_id=10,debit=5000' \
+    --item 'account_id=30,credit=5000'
+akt journal-entry list
+akt journal-entry update 4 --description "Corrected memo"
+akt journal-entry create --description "Vendor bill accrual" --basis accrual \
+    --item 'account_id=60,debit=250' --item 'account_id=21,credit=250' \
+    --attachment ./invoice.pdf
+
 # Anything else: raw API access
 akt raw GET reports
 akt raw POST items --data '{"name":"Ad-hoc","type":"service","sale_price":99}'
@@ -216,6 +249,23 @@ Driving Akaunting's API directly has sharp edges; `akt` papers over these:
   size) comes from the `/api` record itself.
 * **Full-replace updates** — Akaunting PUT re-validates required fields, so
   `akt` merges your changes onto the current record.
+* **Journal entries must balance** — a `journal-entry` needs >= 2 lines whose
+  debits equal its credits; `akt` validates this client-side (clear error)
+  before hitting the API. Each line carries both a `debit` and a `credit` key
+  (the unused side sent as `0`) because Akaunting validates both as required.
+* **Journal updates re-derive ledgers** — like documents, a journal update
+  deletes any ledger line absent from the request. `akt` resends the existing
+  lines (with their ledger ids) so an update that only changes a field doesn't
+  wipe the entry, and auto-generates the `journal_number` from the module's
+  `double-entry.journal.number_*` settings when you don't pass one.
+* **Chart-of-accounts CRUD is web-only** — the Double-Entry module exposes
+  accounts read-only on `/api`; create/update/delete exist solely on the
+  session/CSRF web route. `akt chart-of-account create|update|delete` logs in a
+  web session (reusing your admin credentials, cached for the process), attaches
+  the CSRF token, and unwraps Akaunting's `{success, error, data, message}` AJAX
+  envelope — so a server-side block (e.g. *deleting an account that has ledgers*)
+  surfaces as a normal error. Updates resend `name` (required by Akaunting on
+  update) from the current record when you don't pass one.
 
 ### Invoice creation may be gated by a plan check
 

{akt_cli-0.2.0 → akt_cli-0.3.0}/README.md

@@ -3,7 +3,7 @@
 # akt — Akaunting CLI toolbox
 ### Drive your Akaunting accounting instance entirely from the command line
 
->`akt` gives you full create / read / update / delete for customers, vendors, items, invoices, bills, payments, accounts, categories, taxes, currencies and transfers — plus a `raw` escape hatch for any other endpoint. Built and tested against [Akaunting](https://akaunting.com) **3.1.x**; works with any 3.x deployment that exposes the REST API.
+>`akt` gives you full create / read / update / delete for customers, vendors, items, invoices, bills, payments, accounts, categories, taxes, currencies and transfers — plus double-entry journal entries and the chart of accounts, and a `raw` escape hatch for any other endpoint. Built and tested against [Akaunting](https://akaunting.com) **3.1.x**; works with any 3.x deployment that exposes the REST API.
 
 [![PyPI Version](https://img.shields.io/pypi/v/akt-cli.svg?style=flat-square)](https://pypi.org/project/akt-cli/)
 [![Tests](https://img.shields.io/github/actions/workflow/status/AsyncAlchemist/akt-cli/ci.yml?branch=main&label=tests&style=flat-square)](https://github.com/AsyncAlchemist/akt-cli/actions/workflows/ci.yml)
@@ -80,8 +80,18 @@ Akaunting folds several nouns onto shared endpoints; `akt` hides that:
 | `invoice`  | `documents`    | document of type `invoice`                         |
 | `bill`     | `documents`    | document of type `bill`                            |
 | `payment`  | `transactions` | income (invoice) or expense (bill) transaction    |
+| `journal-entry` | `journal-entry` | double-entry general-ledger entry (module)     |
+| `chart-of-account` | `chart-of-accounts` | GL accounts — read via API, CRUD via web    |
 | `item`, `account`, `category`, `tax`, `currency`, `transfer` | as named | |
 
+> `journal-entry` and `chart-of-account` require the **Double-Entry** module
+> installed on the instance. The module publishes chart-of-accounts read-only on
+> the `/api` surface (index/show); its create/update/delete live only on the
+> session/CSRF **web** route. `akt chart-of-account` gives you the full verb set
+> anyway — `list`/`get` hit `/api`, while `create`/`update`/`delete` transparently
+> drive the web CRUD with your admin session (the same mechanism
+> `download-attachment` already uses).
+
 > The `contacts` and `documents` endpoints derive their permission from a
 > `search=type:<x>` query param. `akt` injects this automatically — calling them
 > raw without it returns `403 necessary access rights`.
@@ -160,6 +170,29 @@ akt bill attachments 41                             # list attached files
 akt bill download-attachment 41 --out ./downloads   # save to disk
 akt payment update 57 --remove-attachment           # clear attachments
 
+# Double-entry general ledger (requires the Double-Entry module)
+akt chart-of-account list                              # read the chart of accounts
+akt chart-of-account get 12
+
+# Build the chart of accounts as code (create/update/delete run via the web
+# session; type-id is the double-entry account-type id — copy it from an
+# existing account's `type_id`)
+akt chart-of-account create --name "Cash on Hand" --code 1010 --type-id 6
+akt chart-of-account create --name "Petty Cash" --code 1011 --type-id 6 --account-id 12
+akt chart-of-account update 12 --code 1000 --description "Operating cash"
+akt chart-of-account delete 12
+
+# Post a balanced journal entry (>= 2 lines; debits must equal credits;
+# journal number auto-generated, basis defaults to accrual)
+akt journal-entry create --description "Owner capital contribution" \
+    --item 'account_id=10,debit=5000' \
+    --item 'account_id=30,credit=5000'
+akt journal-entry list
+akt journal-entry update 4 --description "Corrected memo"
+akt journal-entry create --description "Vendor bill accrual" --basis accrual \
+    --item 'account_id=60,debit=250' --item 'account_id=21,credit=250' \
+    --attachment ./invoice.pdf
+
 # Anything else: raw API access
 akt raw GET reports
 akt raw POST items --data '{"name":"Ad-hoc","type":"service","sale_price":99}'
@@ -195,6 +228,23 @@ Driving Akaunting's API directly has sharp edges; `akt` papers over these:
   size) comes from the `/api` record itself.
 * **Full-replace updates** — Akaunting PUT re-validates required fields, so
   `akt` merges your changes onto the current record.
+* **Journal entries must balance** — a `journal-entry` needs >= 2 lines whose
+  debits equal its credits; `akt` validates this client-side (clear error)
+  before hitting the API. Each line carries both a `debit` and a `credit` key
+  (the unused side sent as `0`) because Akaunting validates both as required.
+* **Journal updates re-derive ledgers** — like documents, a journal update
+  deletes any ledger line absent from the request. `akt` resends the existing
+  lines (with their ledger ids) so an update that only changes a field doesn't
+  wipe the entry, and auto-generates the `journal_number` from the module's
+  `double-entry.journal.number_*` settings when you don't pass one.
+* **Chart-of-accounts CRUD is web-only** — the Double-Entry module exposes
+  accounts read-only on `/api`; create/update/delete exist solely on the
+  session/CSRF web route. `akt chart-of-account create|update|delete` logs in a
+  web session (reusing your admin credentials, cached for the process), attaches
+  the CSRF token, and unwraps Akaunting's `{success, error, data, message}` AJAX
+  envelope — so a server-side block (e.g. *deleting an account that has ledgers*)
+  surfaces as a normal error. Updates resend `name` (required by Akaunting on
+  update) from the current record when you don't pass one.
 
 ### Invoice creation may be gated by a plan check
 

{akt_cli-0.2.0 → akt_cli-0.3.0}/pyproject.toml

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

{akt_cli-0.2.0 → akt_cli-0.3.0}/src/akt/__init__.py

@@ -3,4 +3,4 @@
 from .cli import main
 
 __all__ = ["main"]
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{akt_cli-0.2.0 → akt_cli-0.3.0}/src/akt/cli.py

@@ -40,6 +40,10 @@ def _add_field_args(p: argparse.ArgumentParser, res: Resource, *, for_update: bo
     if res.endpoint == "documents":
         p.add_argument("--item", action="append", metavar="K=V,...",
                        help="line item, e.g. 'name=Widget,price=10,quantity=2,tax_id=1' (repeatable)")
+    elif res.endpoint == "journal-entry":
+        p.add_argument("--item", action="append", metavar="K=V,...",
+                       help="ledger line (>= 2, must balance), e.g. "
+                            "'account_id=10,debit=100' or 'account_id=20,credit=100' (repeatable)")
     if res.supports_attachments:
         p.add_argument("--attachment", action="append", metavar="PATH",
                        help="attach a file (pdf/jpg/png, repeatable); switches the "
@@ -97,18 +101,21 @@ def _build_parser() -> argparse.ArgumentParser:
         gp.add_argument("id")
         gp.set_defaults(_handler=lambda res, c, ns: cmd_get(res, c, ns))
 
-        cp = verbs.add_parser("create", parents=[common], help=f"Create a {res.noun}")
-        _add_field_args(cp, res, for_update=False)
-        cp.set_defaults(_handler=lambda res, c, ns: cmd_create(res, c, ns))
-
-        up = verbs.add_parser("update", parents=[common], help=f"Update a {res.noun}")
-        up.add_argument("id")
-        _add_field_args(up, res, for_update=True)
-        up.set_defaults(_handler=lambda res, c, ns: cmd_update(res, c, ns))
-
-        dp = verbs.add_parser("delete", parents=[common], help=f"Delete a {res.noun}")
-        dp.add_argument("id")
-        dp.set_defaults(_handler=lambda res, c, ns: cmd_delete(res, c, ns))
+        # Read-only resources (e.g. chart-of-accounts) expose only list/get; the
+        # API has no create/update/delete route for them.
+        if not res.read_only:
+            cp = verbs.add_parser("create", parents=[common], help=f"Create a {res.noun}")
+            _add_field_args(cp, res, for_update=False)
+            cp.set_defaults(_handler=lambda res, c, ns: cmd_create(res, c, ns))
+
+            up = verbs.add_parser("update", parents=[common], help=f"Update a {res.noun}")
+            up.add_argument("id")
+            _add_field_args(up, res, for_update=True)
+            up.set_defaults(_handler=lambda res, c, ns: cmd_update(res, c, ns))
+
+            dp = verbs.add_parser("delete", parents=[common], help=f"Delete a {res.noun}")
+            dp.add_argument("id")
+            dp.set_defaults(_handler=lambda res, c, ns: cmd_delete(res, c, ns))
 
         if res.supports_attachments:
             ap = verbs.add_parser("attachments", parents=[common],

{akt_cli-0.2.0 → akt_cli-0.3.0}/src/akt/client.py

@@ -76,7 +76,7 @@ class Client:
             {
                 "Accept": "application/json",
                 "Content-Type": "application/json",
-                "User-Agent": "akt/0.2 (+akaunting-cli)",
+                "User-Agent": "akt/0.3 (+akaunting-cli)",
             }
         )
 
@@ -277,6 +277,62 @@ class Client:
         filename = self._disposition_filename(resp.headers.get("Content-Disposition", ""))
         return filename or f"attachment-{media_id}", resp.content
 
+    def _xsrf_header(self) -> dict:
+        """CSRF header for a session web request.
+
+        Laravel accepts the *encrypted* ``XSRF-TOKEN`` cookie value echoed back in
+        the ``X-XSRF-TOKEN`` header (it decrypts that to the session token) — this
+        is exactly what Akaunting's axios frontend does, and is far more robust
+        than scraping a per-page ``_token`` (Akaunting emits no ``csrf-token``
+        meta tag). ``requests`` already stores the cookie; we just surface it as a
+        header."""
+        cookie = self._session.cookies.get("XSRF-TOKEN")
+        return {"X-XSRF-TOKEN": unquote(cookie)} if cookie else {}
+
+    def web_json(self, method: str, path: str,
+                 form: "list[tuple[str, str]] | None" = None) -> Any:
+        """Call a session-authenticated web (non-``/api``) route that answers JSON.
+
+        Some module features are exposed only on the CSRF-protected web surface,
+        not the Basic-auth ``/api`` one — notably the Double-Entry
+        chart-of-accounts CRUD (``apiResource`` publishes it read-only). This logs
+        in a web session (cached for the process), attaches the CSRF token plus the
+        ``X-Requested-With``/``Accept`` headers Laravel needs to reply with JSON
+        instead of an HTML redirect, and unwraps Akaunting's
+        ``{success, error, data, message}`` AJAX envelope. ``path`` is relative to
+        ``{web_root}/{company_id}/``; use a real ``PATCH``/``DELETE`` method (the
+        resource controller and its FormRequest honor it directly)."""
+        self._web_login()
+        url = f"{self.config.web_root}/{self.config.company_id}/{path.lstrip('/')}"
+        headers = {
+            # Drop the JSON content-type so requests url-encodes the form itself.
+            "Content-Type": None,
+            "Accept": "application/json",
+            "X-Requested-With": "XMLHttpRequest",
+            **self._xsrf_header(),
+        }
+        resp = self._session.request(
+            method.upper(), url, data=list(form or []), headers=headers,
+            allow_redirects=False, timeout=self.timeout,
+        )
+        if self._waf_blocked(resp):
+            raise ApiError(resp.status_code, "Blocked by bot-protection on web route.")
+        if resp.status_code in (301, 302, 303, 307, 308):
+            raise ApiError(
+                resp.status_code,
+                "Web route redirected instead of returning JSON — the session "
+                "isn't authenticated or the CSRF token was rejected. Check the "
+                "admin credentials.",
+            )
+        payload = self._handle(resp)  # raises ApiError (with validation errors) on non-2xx
+        # Akaunting's AJAX envelope: a 200 can still carry a business-rule failure
+        # (e.g. deleting an account that has ledgers) as {success:false, error:true}.
+        if isinstance(payload, dict) and payload.get("error"):
+            raise ApiError(400, payload.get("message") or "Request failed")
+        if isinstance(payload, dict) and "data" in payload and "success" in payload:
+            return payload["data"]
+        return payload
+
     @staticmethod
     def _disposition_filename(disposition: str) -> str | None:
         name = None

{akt_cli-0.2.0 → akt_cli-0.3.0}/src/akt/commands.py

@@ -43,6 +43,12 @@ def cmd_create(res: Resource, client: Client, ns: Any) -> int:
     # document goes to documents/{id}/transactions).
     endpoint = body.pop("__endpoint__", res.endpoint)
     type_scope = body.pop("__type_scope__", res.type_scope)
+    # Resources whose CRUD lives only on the session/CSRF web surface (e.g.
+    # chart-of-accounts) POST through client.web_json instead of /api.
+    if res.web_endpoint:
+        data = client.web_json("POST", res.web_endpoint, flatten_form(body))
+        emit(data, as_json=True)
+        return 0
     files = load_attachments(getattr(ns, "attachment", None))
     if files:
         payload = client.post_multipart(endpoint, flatten_form(body), files,
@@ -63,6 +69,12 @@ def cmd_update(res: Resource, client: Client, ns: Any) -> int:
         # record to satisfy required-field validation.
         body = body_from_fields(res, ns, for_update=True, current=current)
 
+    # Web-surface CRUD resources (chart-of-accounts) update via the session route.
+    if res.web_endpoint:
+        data = client.web_json("PATCH", f"{res.web_endpoint}/{ns.id}", flatten_form(body))
+        emit(data, as_json=True)
+        return 0
+
     # A resolver may redirect to a nested route (a document-linked payment must
     # update via documents/{doc}/transactions/{id}; the flat route 400s on it).
     if res.update_resolver:
@@ -97,6 +109,10 @@ def cmd_update(res: Resource, client: Client, ns: Any) -> int:
 
 
 def cmd_delete(res: Resource, client: Client, ns: Any) -> int:
+    if res.web_endpoint:
+        client.web_json("DELETE", f"{res.web_endpoint}/{ns.id}")
+        print(f"deleted {res.noun} {ns.id}")
+        return 0
     if res.delete_resolver:
         path, type_scope = res.delete_resolver(res, client, str(ns.id))
     else:

{akt_cli-0.2.0 → akt_cli-0.3.0}/src/akt/registry.py

@@ -5,8 +5,12 @@ from __future__ import annotations
 from .resources import (
     Resource,
     f,
+    build_account_create,
+    build_account_update,
     build_document_create,
     build_document_update,
+    build_journal_create,
+    build_journal_update,
     build_payment_create,
     build_transfer_create,
     resolve_payment_delete,
@@ -260,9 +264,65 @@ TRANSFER = Resource(
 )
 
 
+# Double-entry (general ledger) -------------------------------------------
+
+# The DoubleEntry module publishes chart-of-accounts READ-ONLY over the API
+# (index/show only). Create/update/delete exist only on the session/CSRF web
+# CRUD route, so those verbs are driven through client.web_json (web_endpoint)
+# while list/get keep using the /api surface (endpoint). journal-entry is full
+# API CRUD.
+
+CHART_OF_ACCOUNT = Resource(
+    noun="chart-of-account",
+    endpoint="chart-of-accounts",
+    web_endpoint="double-entry/chart-of-accounts",
+    fields=[
+        f("name", "Account name", required=True),
+        f("code", "Account code (unique integer per company)"),
+        f("type-id", "Double-entry account type id (see an existing account's type_id)"),
+        f("account-id", "Parent account id (makes this a sub-account)"),
+        f("description", "Description"),
+        f("enabled", "Enable the record", is_flag=True, default=1),
+    ],
+    columns=[
+        ("ID", "id"), ("Code", "code"), ("Name", "name"), ("Type", "type_id"),
+        ("Parent", "account_id"), ("Enabled", "enabled"),
+    ],
+    supports_toggle=False,
+    build_create=build_account_create,
+    build_update=build_account_update,
+    help="Chart of accounts (read via API; create/update/delete via web, double-entry module)",
+)
+
+JOURNAL_ENTRY = Resource(
+    noun="journal-entry",
+    endpoint="journal-entry",
+    fields=[
+        f("journal-number", "Journal number (auto-generated if omitted)"),
+        f("paid-at", "Entry date (YYYY-MM-DD; defaults to today)"),
+        f("description", "Description", required=True),
+        f("basis", "cash | accrual", default="accrual", choices=["cash", "accrual"]),
+        f("reference", "Reference"),
+        f("currency-code", "Currency code", default="USD"),
+        f("currency-rate", "Currency rate", default=1),
+    ],
+    columns=[
+        ("ID", "id"), ("Number", "journal_number"), ("Date", "paid_at"),
+        ("Amount", "amount_formatted"), ("Basis", "basis"),
+        ("Description", "description"),
+    ],
+    supports_toggle=False,
+    supports_attachments=True,
+    build_create=build_journal_create,
+    build_update=build_journal_update,
+    help="Journal entries (double-entry general ledger)",
+)
+
+
 RESOURCES: list[Resource] = [
     CUSTOMER, VENDOR, ITEM, ACCOUNT, CATEGORY, TAX, CURRENCY,
     INVOICE, BILL, PAYMENT, TRANSFER,
+    CHART_OF_ACCOUNT, JOURNAL_ENTRY,
 ]
 
 BY_NOUN = {r.noun: r for r in RESOURCES}

{akt_cli-0.2.0 → akt_cli-0.3.0}/src/akt/resources.py

@@ -53,6 +53,11 @@ class Resource:
     search_default: str | None = None      # always-applied search filter
     supports_toggle: bool = True           # enable/disable verbs
     supports_attachments: bool = False     # --attachment upload + attachments/download verbs
+    read_only: bool = False                # expose only list/get (no create/update/delete)
+    # When set, create/update/delete are driven through the session-authenticated
+    # web route (client.web_json) at this path instead of the /api surface — for
+    # resources whose CRUD Akaunting exposes only on the web (e.g. chart-of-accounts).
+    web_endpoint: str | None = None
     help: str = ""
 
     # hooks (override for documents/payments)
@@ -551,3 +556,190 @@ def _next_transaction_number(client: Client) -> str:
         if tail:
             maxn = max(maxn, int(tail))
     return f"{pre}{maxn + 1:05d}"
+
+
+# --------------------------------------------------------------------------
+# journal entry (double-entry) body builder
+# --------------------------------------------------------------------------
+
+def parse_journal_item(spec: str) -> dict:
+    """Parse one journal line: ``account_id=10,debit=100`` or
+    ``account_id=20,credit=100`` (optional ``id=`` on update to target an
+    existing ledger, optional ``notes=``). A line carries a debit *or* a
+    credit; the omitted side defaults to 0."""
+    item: dict[str, Any] = {}
+    for part in spec.split(","):
+        if not part.strip():
+            continue
+        if "=" not in part:
+            raise ValueError(f"--item field must be key=value, got {part!r}")
+        k, _, v = part.partition("=")
+        item[k.strip()] = _coerce(v.strip())
+    if "account_id" not in item:
+        raise ValueError(f"--item requires an account_id=… field: {spec!r}")
+    if "debit" not in item and "credit" not in item:
+        raise ValueError(f"--item requires a debit=… or credit=… field: {spec!r}")
+    return item
+
+
+def _normalize_journal_items(items: list[dict]) -> list[dict]:
+    """Coerce account_id/id to int and ensure both debit & credit keys exist
+    (Akaunting validates ``items.*.debit`` and ``items.*.credit`` as required)."""
+    for it in items:
+        if it.get("account_id") is not None:
+            it["account_id"] = int(it["account_id"])
+        if it.get("id") is not None:
+            it["id"] = int(it["id"])
+        it.setdefault("debit", 0)
+        it.setdefault("credit", 0)
+    return items
+
+
+def _require_balanced(items: list[dict]) -> None:
+    """A journal entry needs >= 2 lines whose debits equal its credits."""
+    if len(items) < 2:
+        raise ValueError("a journal entry needs at least 2 line items")
+    debit = sum(float(it.get("debit") or 0) for it in items)
+    credit = sum(float(it.get("credit") or 0) for it in items)
+    if abs(debit - credit) > 1e-4:
+        raise ValueError(
+            f"journal entry does not balance: debits {debit:.2f} != credits {credit:.2f}"
+        )
+
+
+def _next_journal_number(client: Client) -> str:
+    pre = client.setting("double-entry.journal.number_prefix") or "MJE-"
+    digit = client.setting("double-entry.journal.number_digit")
+    try:
+        width = int(digit)
+    except (TypeError, ValueError):
+        width = 5
+    existing = client.list("journal-entry", all_pages=True)
+    maxn = 0
+    for row in existing:
+        tail = "".join(ch for ch in str(row.get("journal_number", "")) if ch.isdigit())
+        if tail:
+            maxn = max(maxn, int(tail))
+    return f"{pre}{maxn + 1:0{width}d}"
+
+
+def build_journal_create(res: Resource, client: Client, ns: Any) -> dict:
+    extra = load_data_arg(getattr(ns, "data", None))
+    items = [parse_journal_item(s) for s in (getattr(ns, "item", None) or [])]
+    if not items and "items" not in extra:
+        raise ValueError(
+            "at least two --item 'account_id=…,debit=…|credit=…' lines are "
+            "required (or supply --data with items)"
+        )
+
+    description = getattr(ns, "description", None)
+    if not description:
+        raise ValueError("--description is required to create a journal-entry")
+
+    body: dict[str, Any] = {
+        "paid_at": _normalize_date(getattr(ns, "paid_at", None) or today_dt()),
+        "journal_number": getattr(ns, "journal_number", None),
+        "description": description,
+        "basis": getattr(ns, "basis", None) or "accrual",
+        "currency_code": getattr(ns, "currency_code", None) or "USD",
+        "currency_rate": getattr(ns, "currency_rate", None) or 1,
+        # Akaunting recomputes the entry amount from the ledger debits; send 0.
+        "amount": 0,
+        "items": items,
+    }
+    if getattr(ns, "reference", None):
+        body["reference"] = ns.reference
+    body.update(parse_set(getattr(ns, "set_", None)))
+    body.update(extra)
+    if isinstance(body.get("items"), list):
+        _normalize_journal_items(body["items"])
+        _require_balanced(body["items"])
+    # Assign the journal number last — after client-side validation — so an
+    # invalid entry never burns a lookup (and the imbalance error surfaces
+    # without a network round-trip).
+    if not body.get("journal_number"):
+        body["journal_number"] = _next_journal_number(client)
+    return body
+
+
+def _journal_items_from_current(current: dict) -> list[dict]:
+    """Rebuild request items from a fetched entry's ledgers so an update that
+    doesn't touch lines doesn't delete them (UpdateJournalEntry deletes any
+    ledger whose id is absent from the request). Each line carries its ledger
+    ``id`` so the existing row is updated in place rather than recreated."""
+    out: list[dict] = []
+    for led in current.get("ledgers", {}).get("data", []):
+        row = {
+            "account_id": led.get("account_id"),
+            "debit": float(led.get("debit") or 0),
+            "credit": float(led.get("credit") or 0),
+        }
+        if led.get("id"):
+            row["id"] = int(led["id"])
+        out.append(row)
+    return out
+
+
+def build_journal_update(res: Resource, client: Client, ns: Any, current: dict) -> dict:
+    """Full update: Akaunting re-derives ledgers & amount from the request, so
+    resend the whole entry, overlaying any provided fields."""
+    body: dict[str, Any] = {
+        "paid_at": _normalize_dt_field(current.get("paid_at") or today_dt()),
+        "journal_number": current.get("journal_number"),
+        "description": current.get("description"),
+        "basis": current.get("basis") or "accrual",
+        "currency_code": current.get("currency_code"),
+        "currency_rate": current.get("currency_rate", 1),
+        "amount": 0,
+        "items": _journal_items_from_current(current),
+    }
+    if current.get("reference"):
+        body["reference"] = current["reference"]
+
+    for attr, key in [
+        ("paid_at", "paid_at"), ("journal_number", "journal_number"),
+        ("description", "description"), ("basis", "basis"),
+        ("currency_code", "currency_code"), ("currency_rate", "currency_rate"),
+        ("reference", "reference"),
+    ]:
+        v = getattr(ns, attr, None)
+        if v is not None:
+            body[key] = _normalize_date(v) if key == "paid_at" else v
+
+    items_specs = getattr(ns, "item", None) or []
+    if items_specs:
+        body["items"] = [parse_journal_item(s) for s in items_specs]
+
+    body.update(parse_set(getattr(ns, "set_", None)))
+    body.update(load_data_arg(getattr(ns, "data", None)))
+    if isinstance(body.get("items"), list):
+        _normalize_journal_items(body["items"])
+        _require_balanced(body["items"])
+    return body
+
+
+# --------------------------------------------------------------------------
+# chart-of-accounts (double-entry) — web-surface CRUD body builder
+# --------------------------------------------------------------------------
+
+def _apply_sub_account(body: dict) -> None:
+    """The web CRUD form carries an ``is_sub_account`` toggle; a parent
+    ``account_id`` is only honored when it's ``"true"`` and is cleared when
+    ``"false"``. Derive it from whether a parent was supplied."""
+    body["is_sub_account"] = "true" if body.get("account_id") else "false"
+
+
+def build_account_create(res: Resource, client: Client, ns: Any) -> dict:
+    body = body_from_fields(res, ns, for_update=False)
+    if not body.get("name"):
+        raise ValueError("--name is required to create a chart-of-account")
+    _apply_sub_account(body)
+    return body
+
+
+def build_account_update(res: Resource, client: Client, ns: Any, current: dict) -> dict:
+    # A full replace: Akaunting's Account request re-validates `name` on update,
+    # so backfill unspecified fields from the current record.
+    body = body_from_fields(res, ns, for_update=True, current=current)
+    _apply_sub_account(body)
+    return body