akt-cli 0.8.1__tar.gz → 0.9.0__tar.gz

{akt_cli-0.8.1 → akt_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: akt-cli
-Version: 0.8.1
+Version: 0.9.0
 Summary: akt — a CLI toolbox to fully drive an Akaunting accounting instance
 Keywords: akaunting,accounting,cli,invoices,bills,api
 Author: AsyncAlchemist
@@ -265,6 +265,27 @@ agree. `--account` takes a GL code or name; `--category` a mirror-category name
 (see `--bank` for the bank/cash account). An explicit `--set de_account_id=` still
 wins.
 
+### Split one transaction across several GL accounts
+
+`--split` posts **one bank transaction to multiple GL accounts at once** — the way
+an invoice's line items each hit their own account. Repeat it per leg as
+`account=<code|name>,debit=<x>` or `account=<code|name>,credit=<x>`; the legs must
+net to `--amount` (income legs credit-heavy, expense legs debit-heavy):
+
+```bash
+# one $13,400 PayPro deposit that books gross revenue, a refund and a fee together
+akt payment create --type income --bank 20 --amount 13400 \
+    --split 'account=400,credit=13686' \
+    --split 'account=545,debit=280' \
+    --split 'account=605,debit=6'
+```
+
+Needs the [`akt-api` companion module](akt-api/) — it writes the extra DoubleEntry
+item legs (a standalone transaction can't natively carry more than one). The
+transaction keeps a **single `category_id`**, a label just like a multi-item
+invoice's, so Akaunting's native category report shows it under one bucket; the
+**DoubleEntry GL (the item legs) is the source of truth**.
+
 **Enforcement (when a `--coa` config is loaded):** akt refuses to create a
 *standalone* income/expense transaction that has no GL account — you must pass
 `--account`, `--category`, or an explicit `--set de_account_id=`. This makes the

{akt_cli-0.8.1 → akt_cli-0.9.0}/README.md

@@ -244,6 +244,27 @@ agree. `--account` takes a GL code or name; `--category` a mirror-category name
 (see `--bank` for the bank/cash account). An explicit `--set de_account_id=` still
 wins.
 
+### Split one transaction across several GL accounts
+
+`--split` posts **one bank transaction to multiple GL accounts at once** — the way
+an invoice's line items each hit their own account. Repeat it per leg as
+`account=<code|name>,debit=<x>` or `account=<code|name>,credit=<x>`; the legs must
+net to `--amount` (income legs credit-heavy, expense legs debit-heavy):
+
+```bash
+# one $13,400 PayPro deposit that books gross revenue, a refund and a fee together
+akt payment create --type income --bank 20 --amount 13400 \
+    --split 'account=400,credit=13686' \
+    --split 'account=545,debit=280' \
+    --split 'account=605,debit=6'
+```
+
+Needs the [`akt-api` companion module](akt-api/) — it writes the extra DoubleEntry
+item legs (a standalone transaction can't natively carry more than one). The
+transaction keeps a **single `category_id`**, a label just like a multi-item
+invoice's, so Akaunting's native category report shows it under one bucket; the
+**DoubleEntry GL (the item legs) is the source of truth**.
+
 **Enforcement (when a `--coa` config is loaded):** akt refuses to create a
 *standalone* income/expense transaction that has no GL account — you must pass
 `--account`, `--category`, or an explicit `--set de_account_id=`. This makes the

{akt_cli-0.8.1 → akt_cli-0.9.0}/pyproject.toml

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

{akt_cli-0.8.1 → akt_cli-0.9.0}/src/akt/cli.py

@@ -48,6 +48,15 @@ def _add_field_args(p: argparse.ArgumentParser, res: Resource, *, for_update: bo
         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)")
+    elif res.endpoint == "transactions" and not for_update:
+        p.add_argument("--split", action="append", metavar="account=CODE,debit|credit=X",
+                       help="split the GL posting across multiple accounts (repeatable): "
+                            "one bank transaction that posts N GL item legs, the way an "
+                            "invoice's line items do. e.g. 'account=400,credit=13686' "
+                            "'account=545,debit=280'. Legs must net to --amount; needs a "
+                            "--coa config and the akt-api companion module. category_id "
+                            "stays a single label — the DoubleEntry GL (item legs) is the "
+                            "source of truth.")
     if res.supports_attachments:
         p.add_argument("--attachment", action="append", metavar="PATH",
                        help="attach a file (pdf/jpg/png, repeatable); switches the "

{akt_cli-0.8.1 → akt_cli-0.9.0}/src/akt/registry.py

@@ -16,6 +16,7 @@ from .resources import (
     redate_opening_balance,
     resolve_payment_delete,
     resolve_payment_update,
+    split_payment_legs,
 )
 
 # Common column sets
@@ -251,6 +252,7 @@ PAYMENT = Resource(
     build_create=build_payment_create,
     delete_resolver=resolve_payment_delete,
     update_resolver=resolve_payment_update,
+    post_write=split_payment_legs,
     help="Payments / transactions (income & expense)",
 )
 

{akt_cli-0.8.1 → akt_cli-0.9.0}/src/akt/resources.py

@@ -436,6 +436,33 @@ def build_document_update(res: Resource, client: Client, ns: Any, current: dict)
 # payment (transaction) body builder
 # --------------------------------------------------------------------------
 
+def parse_split_leg(spec: str) -> dict:
+    """Parse one ``--split`` leg: ``account=<code|name>,debit=<x>`` or
+    ``account=<code|name>,credit=<x>``. Exactly one of debit/credit; ``account`` is a
+    GL code or name resolved against the COA (like ``--account``). Returns
+    ``{'account': str, 'debit'|'credit': float}``."""
+    item: dict[str, Any] = {}
+    for part in spec.split(","):
+        if not part.strip():
+            continue
+        if "=" not in part:
+            raise ValueError(f"--split field must be key=value, got {part!r}")
+        k, _, v = part.partition("=")
+        item[k.strip()] = v.strip()
+    if not item.get("account"):
+        raise ValueError(f"--split leg requires an account=<code|name> field: {spec!r}")
+    has_d = bool(item.get("debit"))
+    has_c = bool(item.get("credit"))
+    if has_d == has_c:
+        raise ValueError(f"--split leg requires exactly one of debit=/credit=: {spec!r}")
+    leg = {"account": item["account"]}
+    if has_d:
+        leg["debit"] = float(item["debit"])
+    else:
+        leg["credit"] = float(item["credit"])
+    return leg
+
+
 def build_payment_create(res: Resource, client: Client, ns: Any) -> dict:
     invoice_id = getattr(ns, "invoice", None)
     bill_id = getattr(ns, "bill", None)
@@ -462,6 +489,33 @@ def build_payment_create(res: Resource, client: Client, ns: Any) -> dict:
         if category_id is None:            # explicit --category-id wins
             category_id = coa_category_id
 
+    # --split: one bank transaction posting N GL item legs (like an invoice's line
+    # items). Resolve each leg's account to a de_account_id; the placeholder item
+    # leg uses the first leg's account, then the split_payment_legs post_write hook
+    # fans it out into the N legs via the akt-api endpoint. category_id stays a
+    # single representative label (mirrors invoice behavior); the GL is the truth.
+    split_specs = getattr(ns, "split", None)
+    split_legs = None
+    if split_specs:
+        if account_ref or category_ref:
+            raise ValueError("pass either --split or --account/--category, not both")
+        if coa is None:
+            raise ValueError("--split requires a COA config (pass --coa FILE or set AKT_COA_FILE)")
+        split_legs = []
+        for spec in split_specs:
+            leg = parse_split_leg(spec)
+            leg_de_account_id, leg_category_id = resolve_coding(coa, client, account_ref=leg["account"])
+            resolved = {"account_id": leg_de_account_id}
+            if "debit" in leg:
+                resolved["debit"] = leg["debit"]
+            else:
+                resolved["credit"] = leg["credit"]
+            split_legs.append(resolved)
+            if category_id is None:        # first leg's category = representative label
+                category_id = leg_category_id
+        de_account_id = split_legs[0]["account_id"]   # placeholder item leg
+        ns._split_resolved = split_legs
+
     if invoice_id:
         document = client.show("documents", invoice_id, type_scope="invoice")
         ptype = ptype or "income"
@@ -503,6 +557,17 @@ def build_payment_create(res: Resource, client: Client, ns: Any) -> dict:
     if amount is None:
         raise ValueError("--amount is required")
 
+    # --split balance: the legs must net to the transaction's single item leg, which
+    # mirrors --amount and the bank leg. Income posts the item leg as a credit of
+    # --amount (net -amount); expense as a debit (net +amount). Fail fast client-side.
+    if split_legs is not None:
+        expected = float(amount) if ptype == "expense" else -float(amount)
+        net = sum(l.get("debit", 0) - l.get("credit", 0) for l in split_legs)
+        if abs(net - expected) > 0.005:
+            raise ValueError(
+                f"--split legs net {net:.2f} but --amount {amount} (type {ptype}) needs "
+                f"{expected:.2f} — income legs must be credit-heavy, expense debit-heavy")
+
     account_id = getattr(ns, "account_id", None)
     if account_id is None:
         val = client.setting("default.account")
@@ -576,6 +641,32 @@ def resolve_payment_update(res: Resource, client: Client, ident: str,
     return f"transactions/{ident}", None
 
 
+def split_payment_legs(res: Resource, client: Client, record: dict, ns: Any) -> None:
+    """post_write hook for ``payment create --split``: after the transaction is
+    created (with a single placeholder item leg), fan that leg out into the N
+    resolved legs via the akt-api ``POST /ledgers/{id}/split`` endpoint. No-op unless
+    ``--split`` was given. Requires the akt-api companion module."""
+    legs = getattr(ns, "_split_resolved", None)
+    if not legs:
+        return
+    if not client.has_ledger_api():
+        raise ValueError(
+            "--split needs the akt-api companion module (GET /api/akt-api/ledgers is "
+            "404). Deploy it (scripts/deploy-akt-api.sh) and retry.")
+    txn_id = record.get("id")
+    payload = client.get("akt-api/ledgers", params={
+        "ledgerable_type": "App\\Models\\Banking\\Transaction",
+        "ledgerable_id": txn_id,
+        "entry_type": "item",
+    })
+    rows = payload.get("data", payload) if isinstance(payload, dict) else payload
+    if len(rows) != 1:
+        raise ValueError(
+            f"expected exactly one item leg on transaction {txn_id} to split, found "
+            f"{len(rows)}")
+    client.post(f"akt-api/ledgers/{rows[0]['id']}/split", {"legs": legs})
+
+
 def build_transfer_create(res: Resource, client: Client, ns: Any) -> dict:
     body = body_from_fields(res, ns, for_update=False)
     # Transfers validate transferred_at as date-only (Y-m-d), unlike transactions.