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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: akt-cli
-Version: 0.2.0
+Version: 0.4.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, banks, 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,7 +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    |
-| `item`, `account`, `category`, `tax`, `currency`, `transfer` | as named | |
+| `journal-entry` | `journal-entry` | double-entry general-ledger entry (module)     |
+| `account`  | `chart-of-accounts` | GL accounts (general ledger) — read via API, CRUD via web |
+| `bank`     | `accounts`     | bank / cash accounts (the money, not the GL)      |
+| `item`, `category`, `tax`, `currency`, `transfer` | as named | |
+
+> `journal-entry` and `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 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
@@ -156,6 +167,10 @@ akt item create --name "Consulting Hour" --sale-price 150 --purchase-price 0
 akt category create --name "Services" --type income
 akt tax create --name "Sales Tax" --rate 8.25
 
+# Bank / cash accounts (the money side — see the COA section below for GL accounts)
+akt bank create --name "Business Checking" --number 1001 --currency-code USD
+akt bank list
+
 # 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' \
@@ -181,6 +196,61 @@ 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 account list                                       # read the chart of accounts
+akt 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 account create --name "Cash on Hand" --code 1010 --type-id 6
+akt account create --name "Petty Cash" --code 1011 --type-id 6 --parent-id 12
+akt account update 12 --code 1000 --description "Operating cash"
+akt 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
+
+## COA config: link categories and accounts (Xero-style)
+
+Akaunting keeps *categories* (required on every transaction) separate from the
+double-entry *chart of accounts*. Point akt at a COA config and it keeps them in
+lockstep: one list to maintain (accounts), a 1:1 mirror of categories generated
+from it, and `payment create` coded by `--account` — with the mirror category
+filled in automatically.
+
+akt finds the config at `--coa FILE` → `AKT_COA_FILE` → `./coa.toml` →
+`~/.config/akt/coa.toml`. Minimal schema (extra keys are ignored):
+
+```toml
+[[account]]
+code    = 400
+name    = "API Subscription Revenue"
+type_id = 13            # DoubleEntry account type; income/expense class -> category type
+# optional: category = "Revenue"   (override the mirror name)
+# optional: mirror   = false        (skip mirroring, e.g. bank/AR/AP accounts)
+```
+
+```bash
+akt coa diff                 # preview: accounts/categories to create or rename
+akt coa sync                 # apply (create + rename; idempotent)
+akt coa sync --prune         # also DISABLE accounts/categories absent from the config
+
+# code a transaction by GL account — akt auto-fills the mirror category:
+akt payment create --type expense --bank 1 --amount 120 --account 628
+```
+
+`--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.
+
 # Anything else: raw API access
 akt raw GET reports
 akt raw POST items --data '{"name":"Ad-hoc","type":"service","sale_price":99}'
@@ -216,6 +286,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 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
 
@@ -236,75 +323,10 @@ timing out. `akt` retries throttle/WAF responses with backoff, and
 use `--throttle 1` for bulk work. A durable fix is to whitelist your IP in the
 host firewall.
 
-## Testing
-
-Tests are split in two:
-
-* **`tests/unit/`** — offline tests for the body builders and arg parsing. No
-  network. This is what CI runs by default and what gates pull requests.
-* **`tests/integration/`** — drive the real `akt` CLI against a live Akaunting
-  instance, exercising the full surface (contacts, items, bill → payment →
-  paid, transfers, …). Every record they create is deleted on teardown — even
-  on failure — so no invoices, bills or payments are left behind.
-
-```bash
-uv run pytest tests/unit                 # fast, offline (default)
-uv run pytest                            # integration tests auto-skip without creds
-
-# Run integration tests against a deployment:
-AKT_BASE_URL=https://accounting.example.com \
-AKT_EMAIL=admin@example.com \
-AKT_PASSWORD=… \
-uv run pytest tests/integration -v
-```
-
-> Invoice creation is `xfail`-ed when the host's plan-limit gate is active (see
-> above); the rest of the suite must pass.
-
-### CI / CD
-
-* **CI** (`.github/workflows/ci.yml`) runs on every push and PR: unit tests +
-  coverage, uploaded to [Codecov](https://codecov.io/gh/AsyncAlchemist/akt-cli).
-* **Release** (`.github/workflows/release.yml`) runs the live integration suite
-  on published releases (and via *Run workflow*). Connection details come from
-  GitHub Actions **secrets** (`AKT_BASE_URL`, `AKT_EMAIL`, `AKT_PASSWORD`) — they
-  are never committed and are masked in logs.
-* **Publish** (`.github/workflows/publish.yml`) builds the sdist + wheel and
-  uploads them via **Trusted Publishing (OIDC)** — no API token is stored.
-  *Run workflow* publishes to **TestPyPI**; a published release publishes to
-  **PyPI**.
-
-### Releasing to PyPI
-
-One-time setup — add a *pending publisher* on each index
-(Account → Publishing → *Add a pending publisher*) with:
-
-| Field | TestPyPI | PyPI |
-|-------|----------|------|
-| Project Name | `akt-cli` | `akt-cli` |
-| Owner | `AsyncAlchemist` | `AsyncAlchemist` |
-| Repository name | `akt-cli` | `akt-cli` |
-| Workflow name | `publish.yml` | `publish.yml` |
-| Environment name | `testpypi` | `pypi` |
-
-Then:
+## Contributing
 
-* **Verify** — *Actions → Publish (PyPI) → Run workflow* uploads the current
-  version to TestPyPI.
-* **Release** — bump `version` in `pyproject.toml`, push, and publish a GitHub
-  Release. That runs the live integration suite and publishes to PyPI.
-
-The code is small and declarative:
-
-| file            | purpose                                                  |
-|-----------------|----------------------------------------------------------|
-| `config.py`     | credential resolution (flags / env / dotenv)             |
-| `client.py`     | HTTP, auth, company scoping, pagination, retries         |
-| `resources.py`  | field specs + body builders (documents, payments)        |
-| `registry.py`   | the concrete list of resources and their columns         |
-| `commands.py`   | generic list/get/create/update/delete/toggle handlers    |
-| `cli.py`        | argparse wiring and entrypoint                            |
-| `output.py`     | JSON / table rendering                                    |
+Developing, testing, or releasing `akt`? See [CONTRIBUTING.md](CONTRIBUTING.md)
+for the test suite, CI/CD, release process, and a map of the source files.
 
 ## License
 

{akt_cli-0.2.0 → akt_cli-0.4.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, banks, 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,7 +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    |
-| `item`, `account`, `category`, `tax`, `currency`, `transfer` | as named | |
+| `journal-entry` | `journal-entry` | double-entry general-ledger entry (module)     |
+| `account`  | `chart-of-accounts` | GL accounts (general ledger) — read via API, CRUD via web |
+| `bank`     | `accounts`     | bank / cash accounts (the money, not the GL)      |
+| `item`, `category`, `tax`, `currency`, `transfer` | as named | |
+
+> `journal-entry` and `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 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
@@ -135,6 +146,10 @@ akt item create --name "Consulting Hour" --sale-price 150 --purchase-price 0
 akt category create --name "Services" --type income
 akt tax create --name "Sales Tax" --rate 8.25
 
+# Bank / cash accounts (the money side — see the COA section below for GL accounts)
+akt bank create --name "Business Checking" --number 1001 --currency-code USD
+akt bank list
+
 # 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' \
@@ -160,6 +175,61 @@ 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 account list                                       # read the chart of accounts
+akt 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 account create --name "Cash on Hand" --code 1010 --type-id 6
+akt account create --name "Petty Cash" --code 1011 --type-id 6 --parent-id 12
+akt account update 12 --code 1000 --description "Operating cash"
+akt 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
+
+## COA config: link categories and accounts (Xero-style)
+
+Akaunting keeps *categories* (required on every transaction) separate from the
+double-entry *chart of accounts*. Point akt at a COA config and it keeps them in
+lockstep: one list to maintain (accounts), a 1:1 mirror of categories generated
+from it, and `payment create` coded by `--account` — with the mirror category
+filled in automatically.
+
+akt finds the config at `--coa FILE` → `AKT_COA_FILE` → `./coa.toml` →
+`~/.config/akt/coa.toml`. Minimal schema (extra keys are ignored):
+
+```toml
+[[account]]
+code    = 400
+name    = "API Subscription Revenue"
+type_id = 13            # DoubleEntry account type; income/expense class -> category type
+# optional: category = "Revenue"   (override the mirror name)
+# optional: mirror   = false        (skip mirroring, e.g. bank/AR/AP accounts)
+```
+
+```bash
+akt coa diff                 # preview: accounts/categories to create or rename
+akt coa sync                 # apply (create + rename; idempotent)
+akt coa sync --prune         # also DISABLE accounts/categories absent from the config
+
+# code a transaction by GL account — akt auto-fills the mirror category:
+akt payment create --type expense --bank 1 --amount 120 --account 628
+```
+
+`--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.
+
 # Anything else: raw API access
 akt raw GET reports
 akt raw POST items --data '{"name":"Ad-hoc","type":"service","sale_price":99}'
@@ -195,6 +265,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 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
 
@@ -215,75 +302,10 @@ timing out. `akt` retries throttle/WAF responses with backoff, and
 use `--throttle 1` for bulk work. A durable fix is to whitelist your IP in the
 host firewall.
 
-## Testing
-
-Tests are split in two:
-
-* **`tests/unit/`** — offline tests for the body builders and arg parsing. No
-  network. This is what CI runs by default and what gates pull requests.
-* **`tests/integration/`** — drive the real `akt` CLI against a live Akaunting
-  instance, exercising the full surface (contacts, items, bill → payment →
-  paid, transfers, …). Every record they create is deleted on teardown — even
-  on failure — so no invoices, bills or payments are left behind.
-
-```bash
-uv run pytest tests/unit                 # fast, offline (default)
-uv run pytest                            # integration tests auto-skip without creds
-
-# Run integration tests against a deployment:
-AKT_BASE_URL=https://accounting.example.com \
-AKT_EMAIL=admin@example.com \
-AKT_PASSWORD=… \
-uv run pytest tests/integration -v
-```
-
-> Invoice creation is `xfail`-ed when the host's plan-limit gate is active (see
-> above); the rest of the suite must pass.
-
-### CI / CD
-
-* **CI** (`.github/workflows/ci.yml`) runs on every push and PR: unit tests +
-  coverage, uploaded to [Codecov](https://codecov.io/gh/AsyncAlchemist/akt-cli).
-* **Release** (`.github/workflows/release.yml`) runs the live integration suite
-  on published releases (and via *Run workflow*). Connection details come from
-  GitHub Actions **secrets** (`AKT_BASE_URL`, `AKT_EMAIL`, `AKT_PASSWORD`) — they
-  are never committed and are masked in logs.
-* **Publish** (`.github/workflows/publish.yml`) builds the sdist + wheel and
-  uploads them via **Trusted Publishing (OIDC)** — no API token is stored.
-  *Run workflow* publishes to **TestPyPI**; a published release publishes to
-  **PyPI**.
-
-### Releasing to PyPI
-
-One-time setup — add a *pending publisher* on each index
-(Account → Publishing → *Add a pending publisher*) with:
-
-| Field | TestPyPI | PyPI |
-|-------|----------|------|
-| Project Name | `akt-cli` | `akt-cli` |
-| Owner | `AsyncAlchemist` | `AsyncAlchemist` |
-| Repository name | `akt-cli` | `akt-cli` |
-| Workflow name | `publish.yml` | `publish.yml` |
-| Environment name | `testpypi` | `pypi` |
-
-Then:
+## Contributing
 
-* **Verify** — *Actions → Publish (PyPI) → Run workflow* uploads the current
-  version to TestPyPI.
-* **Release** — bump `version` in `pyproject.toml`, push, and publish a GitHub
-  Release. That runs the live integration suite and publishes to PyPI.
-
-The code is small and declarative:
-
-| file            | purpose                                                  |
-|-----------------|----------------------------------------------------------|
-| `config.py`     | credential resolution (flags / env / dotenv)             |
-| `client.py`     | HTTP, auth, company scoping, pagination, retries         |
-| `resources.py`  | field specs + body builders (documents, payments)        |
-| `registry.py`   | the concrete list of resources and their columns         |
-| `commands.py`   | generic list/get/create/update/delete/toggle handlers    |
-| `cli.py`        | argparse wiring and entrypoint                            |
-| `output.py`     | JSON / table rendering                                    |
+Developing, testing, or releasing `akt`? See [CONTRIBUTING.md](CONTRIBUTING.md)
+for the test suite, CI/CD, release process, and a map of the source files.
 
 ## License
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "akt-cli"
-version = "0.2.0"
+version = "0.4.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.4.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.4.0}/src/akt/cli.py

@@ -21,6 +21,7 @@ from .commands import (
 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
 
 
 def _add_field_args(p: argparse.ArgumentParser, res: Resource, *, for_update: bool) -> None:
@@ -40,6 +41,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 "
@@ -80,6 +85,9 @@ def _build_parser() -> argparse.ArgumentParser:
                         metavar="SECONDS",
                         help="Min seconds between API calls (or AKT_THROTTLE). "
                              "Use a value like 1.0 to avoid tripping host bot-protection.")
+    parser.add_argument("--coa", dest="coa_file", default=None, metavar="FILE",
+                        help="COA config for category<->account linking "
+                             "(or AKT_COA_FILE / ./coa.toml / ~/.config/akt/coa.toml)")
 
     sub = parser.add_subparsers(dest="resource", metavar="<resource>")
 
@@ -97,18 +105,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))
+        # 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))
+            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))
+            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],
@@ -152,6 +163,19 @@ def _build_parser() -> argparse.ArgumentParser:
     rp.add_argument("--type-scope", help="search=type:X scope for contacts/documents")
     rp.set_defaults(_special="raw")
 
+    coap = sub.add_parser("coa", parents=[common],
+                          help="Sync chart-of-accounts <-> categories from a COA config")
+    coav = coap.add_subparsers(dest="coa_verb", metavar="<verb>")
+    cdp = coav.add_parser("diff", parents=[common], help="Preview the sync plan (read-only)")
+    cdp.add_argument("--prune", action="store_true",
+                     help="also show accounts/categories that --prune would disable")
+    cdp.set_defaults(_special="coa_diff")
+    csp = coav.add_parser("sync", parents=[common],
+                          help="Apply: create/rename accounts + mirror categories")
+    csp.add_argument("--prune", action="store_true",
+                     help="disable accounts/categories absent from the config (never deletes)")
+    csp.set_defaults(_special="coa_sync")
+
     return parser
 
 
@@ -178,6 +202,30 @@ def _run_special(name: str, client: Client, ns: Any) -> int:
                                 json_body=body, type_scope=ns.type_scope)
         emit(result, as_json=True)
         return 0
+    if name == "coa_diff":
+        coa = ns._coa
+        if coa is None:
+            raise ValueError("no COA config found (use --coa FILE or set AKT_COA_FILE)")
+        live_accounts = client.list("chart-of-accounts", all_pages=True)
+        live_categories = client.list("categories", all_pages=True)
+        plan = plan_sync(coa, live_accounts, live_categories, prune=ns.prune)
+        for line in render_plan(plan):
+            print(line)
+        return 0
+    if name == "coa_sync":
+        coa = ns._coa
+        if coa is None:
+            raise ValueError("no COA config found (use --coa FILE or set AKT_COA_FILE)")
+        live_accounts = client.list("chart-of-accounts", all_pages=True)
+        live_categories = client.list("categories", all_pages=True)
+        plan = plan_sync(coa, live_accounts, live_categories, prune=ns.prune)
+        for line in render_plan(plan):
+            print(line)
+        if plan.is_empty:
+            return 0
+        summary = apply_plan(client, plan, prune=ns.prune)
+        print("applied: " + ", ".join(f"{k}={v}" for k, v in summary.items() if v))
+        return 0
     raise ValueError(name)
 
 
@@ -209,11 +257,24 @@ def main(argv: list[str] | None = None) -> int:
         throttle = float(os.environ.get("AKT_THROTTLE", "0") or 0)
     client = Client(config, throttle=throttle)
 
+    try:
+        ns._coa = load_coa(getattr(ns, "coa_file", None))
+    except (ValueError, OSError) as e:
+        print(f"coa config error: {e}", file=sys.stderr)
+        return 2
+
     try:
         special = getattr(ns, "_special", None)
         if special:
             return _run_special(special, client, ns)
 
+        if ns.resource not in BY_NOUN:
+            # command group (e.g. "coa") invoked without a verb
+            sub = next(a for a in parser._subparsers._actions  # type: ignore[attr-defined]
+                       if a.dest == "resource")
+            sub.choices[ns.resource].print_help()  # type: ignore[union-attr]
+            return 1
+
         res = BY_NOUN[ns.resource]
         handler = getattr(ns, "_handler", None)
         if handler is None:

{akt_cli-0.2.0 → akt_cli-0.4.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.4.0/src/akt/coa.py

@@ -0,0 +1,289 @@
+"""Config-driven chart-of-accounts <-> category linking.
+
+akt defines a small COA config schema. When present, it lets `coa sync`
+reconcile the double-entry chart of accounts and a 1:1 mirror of Akaunting
+categories, and lets `payment create` code by --account with the mirror
+category filled in automatically. The feature is inert when no config is found.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+# DoubleEntry standard seeds: account type_id -> Akaunting category type.
+# Income classes -> "income", Expense classes -> "expense", everything else
+# (assets/liabilities/equity) -> "other".
+TYPE_ID_CATEGORY_TYPE: dict[int, str] = {
+    13: "income", 14: "income", 15: "income",          # revenue, sales, other_income
+    11: "expense", 12: "expense",                       # direct_costs, expense
+    1: "other", 2: "other", 3: "other", 4: "other",     # asset types
+    5: "other", 6: "other", 10: "other",                # prepayment, bank_cash, depreciation
+    7: "other", 8: "other", 9: "other", 17: "other",    # liability types + tax
+    16: "other",                                        # equity
+}
+
+
+@dataclass(frozen=True)
+class CoaAccount:
+    code: int
+    name: str
+    type_id: int
+    category: str        # mirror category name (== name unless overridden)
+    category_type: str   # "income" | "expense" | "other"
+    mirror: bool         # whether to create/keep a mirror category
+
+
+@dataclass
+class CoaConfig:
+    accounts: list[CoaAccount] = field(default_factory=list)
+
+    def by_code(self, code: int) -> CoaAccount | None:
+        for a in self.accounts:
+            if a.code == int(code):
+                return a
+        return None
+
+    def by_name(self, name: str) -> CoaAccount | None:
+        for a in self.accounts:
+            if a.name == name:
+                return a
+        return None
+
+    @property
+    def mirrored(self) -> list[CoaAccount]:
+        return [a for a in self.accounts if a.mirror]
+
+
+def parse_coa(text: str) -> CoaConfig:
+    doc = tomllib.loads(text)
+    raw_accounts = doc.get("account", [])
+    accounts: list[CoaAccount] = []
+    seen_codes: set[int] = set()
+    seen_categories: set[str] = set()
+    for i, row in enumerate(raw_accounts):
+        if "code" not in row:
+            raise ValueError(f"account #{i + 1}: missing required 'code'")
+        if "name" not in row:
+            raise ValueError(f"account #{i + 1} (code {row['code']}): missing required 'name'")
+        if "type_id" not in row:
+            raise ValueError(f"account '{row['name']}': missing required 'type_id'")
+        code = int(row["code"])
+        name = str(row["name"])
+        type_id = int(row["type_id"])
+        mirror = bool(row.get("mirror", True))
+        category = str(row.get("category", name))
+        if code in seen_codes:
+            raise ValueError(f"duplicate code {code}")
+        seen_codes.add(code)
+        if type_id not in TYPE_ID_CATEGORY_TYPE:
+            print(f"warning: unknown type_id {type_id} for account '{name}'; "
+                  f"mirror category type defaulted to 'other'", file=sys.stderr)
+        category_type = TYPE_ID_CATEGORY_TYPE.get(type_id, "other")
+        if mirror:
+            if category in seen_categories:
+                raise ValueError(f"duplicate category name {category!r} "
+                                 f"(mirror category names must be unique)")
+            seen_categories.add(category)
+        accounts.append(CoaAccount(code=code, name=name, type_id=type_id,
+                                   category=category, category_type=category_type,
+                                   mirror=mirror))
+    return CoaConfig(accounts=accounts)
+
+
+def _coa_candidate_files(explicit: str | None) -> list[Path]:
+    if explicit:
+        return [Path(explicit).expanduser()]
+    files: list[Path] = []
+    if os.environ.get("AKT_COA_FILE"):
+        files.append(Path(os.environ["AKT_COA_FILE"]).expanduser())
+    files.append(Path.cwd() / "coa.toml")
+    files.append(Path.home() / ".config" / "akt" / "coa.toml")
+    return files
+
+
+def load_coa(path: str | None = None) -> CoaConfig | None:
+    """Find and parse the COA config; return None if none is present.
+
+    An explicitly-passed ``path`` that does not exist is an error (the user
+    asked for a specific file); discovered defaults simply fall through."""
+    if path and not Path(path).expanduser().is_file():
+        raise ValueError(f"COA config not found: {path}")
+    for f in _coa_candidate_files(path):
+        if f.is_file():
+            return parse_coa(f.read_text())
+    return None
+
+
+@dataclass
+class CoaPlan:
+    accounts_create: list[CoaAccount] = field(default_factory=list)
+    accounts_rename: list[tuple[CoaAccount, dict]] = field(default_factory=list)
+    categories_create: list[CoaAccount] = field(default_factory=list)
+    categories_rename: list[tuple[CoaAccount, dict]] = field(default_factory=list)
+    accounts_disable: list[dict] = field(default_factory=list)
+
+    @property
+    def is_empty(self) -> bool:
+        return not any([self.accounts_create, self.accounts_rename,
+                        self.categories_create, self.categories_rename,
+                        self.accounts_disable])
+
+
+def plan_sync(config: CoaConfig, live_accounts: list[dict],
+              live_categories: list[dict], *, prune: bool) -> CoaPlan:
+    """Diff the config against live Akaunting data. Pure: no I/O."""
+    plan = CoaPlan()
+    live_by_code = {int(a["code"]): a for a in live_accounts if a.get("code") is not None}
+    # (name, type) -> live category, so a same-named category of another type
+    # never gets clobbered.
+    live_cat = {(c.get("name"), c.get("type")): c for c in live_categories}
+
+    for acct in config.accounts:
+        live = live_by_code.get(acct.code)
+        if live is None:
+            plan.accounts_create.append(acct)
+        elif str(live.get("name")) != acct.name:
+            plan.accounts_rename.append((acct, live))
+
+    # A renamed mirrored account's mirror category currently lives under the account's
+    # OLD name; rename it instead of creating a fresh one (which would orphan the old).
+    rename_targets = {}   # (new category, type) -> (acct, live_old_category)
+    for acct, live in plan.accounts_rename:
+        if not acct.mirror:
+            continue
+        old = live_cat.get((str(live.get("name")), acct.category_type))
+        if old is not None and old.get("name") != acct.category:
+            rename_targets[(acct.category, acct.category_type)] = (acct, old)
+
+    # Mirror-category names are unique by construction (parse_coa rejects
+    # duplicate category names among mirrored accounts), so these loops can
+    # never enqueue the same categories_create/categories_rename entry twice.
+    for acct in config.mirrored:
+        key = (acct.category, acct.category_type)
+        if live_cat.get(key) is not None:
+            continue                      # already correct
+        if key in rename_targets:
+            a, old = rename_targets[key]
+            plan.categories_rename.append((a, old))   # rename old -> a.category
+        else:
+            plan.categories_create.append(acct)
+
+    if prune:
+        config_codes = {a.code for a in config.accounts}
+        for live in live_accounts:
+            code = live.get("code")
+            if code is None:
+                continue
+            if int(code) not in config_codes and int(live.get("enabled", 1)) == 1:
+                plan.accounts_disable.append(live)
+    return plan
+
+
+def render_plan(plan: CoaPlan) -> list[str]:
+    lines: list[str] = []
+    for a in plan.accounts_create:
+        lines.append(f"create account {a.code} {a.name} (type_id {a.type_id})")
+    for a, live in plan.accounts_rename:
+        lines.append(f"rename account {a.code}: {live.get('name')!r} -> {a.name!r}")
+    for a in plan.categories_create:
+        lines.append(f"create category {a.category!r} [{a.category_type}]")
+    for a, live in plan.categories_rename:
+        lines.append(f"rename category {live.get('name')!r} -> {a.category!r}")
+    for live in plan.accounts_disable:
+        lines.append(f"disable account {live.get('code')} {live.get('name')!r}")
+    if not lines:
+        lines.append("in sync — nothing to do")
+    return lines
+
+
+def _account_form(acct: CoaAccount) -> list[tuple[str, str]]:
+    """The web-CRUD form body for a chart-of-accounts create/update."""
+    from .resources import flatten_form  # local import: avoids resources<->coa cycle
+    return flatten_form({
+        "code": acct.code,
+        "name": acct.name,
+        "type_id": acct.type_id,
+        "enabled": 1,
+        "is_sub_account": "false",
+    })
+
+
+def apply_plan(client, plan: "CoaPlan", *, prune: bool) -> dict:
+    """Execute the plan against Akaunting. Accounts use the web CRUD route
+    (chart-of-accounts is read-only on /api); categories use /api."""
+    summary = {"accounts_created": 0, "accounts_renamed": 0,
+               "categories_created": 0, "categories_renamed": 0,
+               "accounts_disabled": 0}
+
+    for acct in plan.accounts_create:
+        client.web_json("POST", "double-entry/chart-of-accounts", _account_form(acct))
+        summary["accounts_created"] += 1
+
+    for acct, live in plan.accounts_rename:
+        client.web_json("PATCH", f"double-entry/chart-of-accounts/{live['id']}",
+                        _account_form(acct))
+        summary["accounts_renamed"] += 1
+
+    for acct in plan.categories_create:
+        client.post("categories", {
+            "name": acct.category,
+            "type": acct.category_type,
+            "color": "#00bcd4",
+            "enabled": 1,
+        })
+        summary["categories_created"] += 1
+
+    for acct, live in plan.categories_rename:
+        client.put(f"categories/{live['id']}", {
+            "name": acct.category,
+            "type": acct.category_type,
+            "color": live.get("color") or "#00bcd4",
+            "enabled": 1,
+        })
+        summary["categories_renamed"] += 1
+
+    if prune:
+        for live in plan.accounts_disable:
+            client.web_json("GET", f"double-entry/chart-of-accounts/{live['id']}/disable")
+            summary["accounts_disabled"] += 1
+
+    return summary
+
+
+def _find_account(config: CoaConfig, ref: str) -> CoaAccount:
+    acct = config.by_code(int(ref)) if str(ref).lstrip("-").isdigit() else config.by_name(ref)
+    if acct is None:
+        raise ValueError(f"account {ref!r} is not in the COA config")
+    return acct
+
+
+def resolve_coding(config: CoaConfig, client, *, account_ref: str) -> tuple[int, int]:
+    """Resolve --account to live (de_account_id, category_id).
+
+    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 not acct.mirror:
+        raise ValueError(
+            f"account {acct.code} ({acct.name}) has mirror=false — it has no mirror "
+            f"category, so it can't be coded onto a payment via --account "
+            f"(only mirrored income/expense accounts can be)")
+
+    live_accounts = client.list("chart-of-accounts", all_pages=True)
+    de_id = next((a["id"] for a in live_accounts if int(a.get("code", -1)) == acct.code), None)
+    if de_id is None:
+        raise ValueError(f"account {acct.code} ({acct.name}) is not in Akaunting yet — "
+                         f"run `akt coa sync` first")
+    live_categories = client.list("categories", all_pages=True)
+    cat_id = next((c["id"] for c in live_categories
+                   if c.get("name") == acct.category and c.get("type") == acct.category_type),
+                  None)
+    if cat_id is None:
+        raise ValueError(f"mirror category {acct.category!r} [{acct.category_type}] is not in "
+                         f"Akaunting yet — run `akt coa sync` first")
+    return int(de_id), int(cat_id)

{akt_cli-0.2.0 → akt_cli-0.4.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.4.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,
@@ -88,8 +92,8 @@ ITEM = Resource(
     help="Products and services",
 )
 
-ACCOUNT = Resource(
-    noun="account",
+BANK = Resource(
+    noun="bank",
     endpoint="accounts",
     fields=[
         f("name", "Account name", required=True),
@@ -216,10 +220,13 @@ PAYMENT = Resource(
         f("type", "income | expense", choices=["income", "expense"]),
         f("invoice", "Invoice id to apply an income payment to"),
         f("bill", "Bill id to apply an expense payment to"),
+        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("document-id", "Linked document id (advanced)"),
         f("contact-id", "Contact id"),
         f("amount", "Payment amount"),
-        f("account-id", "Bank/cash account id"),
+        f("bank", "Bank/cash account id", dest="account_id"),
         f("category-id", "Category id"),
         f("paid-at", "Payment date/time (YYYY-MM-DD)"),
         f("currency-code", "Currency code"),
@@ -242,8 +249,8 @@ TRANSFER = Resource(
     noun="transfer",
     endpoint="transfers",
     fields=[
-        f("from-account-id", "Source account id", required=True),
-        f("to-account-id", "Destination account id", required=True),
+        f("from-bank", "Source bank/cash account id", dest="from_account_id", required=True),
+        f("to-bank", "Destination bank/cash account id", dest="to_account_id", required=True),
         f("amount", "Amount", required=True),
         f("transferred-at", "Transfer date/time (YYYY-MM-DD)"),
         f("payment-method", "Payment method code", default="offline-payments.cash.1"),
@@ -260,9 +267,66 @@ 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.
+
+ACCOUNT = Resource(
+    noun="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("parent-id", "Parent account id (makes this a sub-account)", dest="account_id"),
+        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 (general ledger; 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,
+    CUSTOMER, VENDOR, ITEM, BANK, CATEGORY, TAX, CURRENCY,
     INVOICE, BILL, PAYMENT, TRANSFER,
+    ACCOUNT, JOURNAL_ENTRY,
 ]
 
 BY_NOUN = {r.noun: r for r in RESOURCES}

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

@@ -16,6 +16,7 @@ from dataclasses import dataclass, field
 from typing import Any, Callable
 
 from .client import Client
+from .coa import resolve_coding
 
 
 # --------------------------------------------------------------------------
@@ -53,6 +54,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)
@@ -431,6 +437,18 @@ def build_payment_create(res: Resource, client: Client, ns: Any) -> dict:
     contact_id = getattr(ns, "contact_id", None)
     category_id = getattr(ns, "category_id", None)
 
+    coa = getattr(ns, "_coa", None)
+    account_ref = getattr(ns, "account", None)
+    de_account_id = None
+    if account_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
+        if category_id is None:            # explicit --category-id wins
+            category_id = coa_category_id
+
     if invoice_id:
         document = client.show("documents", invoice_id, type_scope="invoice")
         ptype = ptype or "income"
@@ -487,6 +505,8 @@ def build_payment_create(res: Resource, client: Client, ns: Any) -> dict:
         body["reference"] = ns.reference
     if getattr(ns, "description", None):
         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)))
 
@@ -551,3 +571,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 an 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