diff options
| -rw-r--r-- | SKILL.md | 18 | ||||
| -rw-r--r-- | completions/firefly.bash | 4 | ||||
| -rw-r--r-- | firefly_cli/__init__.py | 2 | ||||
| -rw-r--r-- | firefly_cli/commands/account.py | 13 | ||||
| -rw-r--r-- | firefly_cli/commands/transaction.py | 13 | ||||
| -rw-r--r-- | firefly_cli/output.py | 21 | ||||
| -rw-r--r-- | pyproject.toml | 2 | ||||
| -rw-r--r-- | tests/unit/test_commands_account.py | 36 | ||||
| -rw-r--r-- | tests/unit/test_commands_transaction.py | 45 | ||||
| -rw-r--r-- | tests/unit/test_output.py | 25 |
10 files changed, 166 insertions, 13 deletions
@@ -105,7 +105,10 @@ firefly account create Rent --type expense ``` Supports asset, expense, revenue. asset accounts get the default role automatically. Unlike categories/tags, accounts are NOT auto-created by -`tx add`, create them explicitly here first. +`tx add`, create them explicitly here first. For idempotent import scripts add +`--if-not-exists`: if an account with that name already exists it returns that +account's JSON with `"existed": true` (exit 0) instead of erroring on the name +clash, so a re-run is safe. **Validate a batch before writing any of it:** when importing many rows in a loop, a mid-batch failure (a `--to` account that doesn't exist yet) leaves the @@ -136,6 +139,19 @@ firefly account balance test01 --at 2026-05-31 # historical: balance as of that ```bash firefly tx list --account test01 --since 2026-06-01 --until 2026-06-30 ``` +`--since`/`--until` filter on the transaction date (the date set on the tx), +inclusive on both ends. Firefly journals have a single date field, so this is +the value date used for reconciliation; there is no separate book/entry date. + +**Flatten output for scripting.** `tx list` nests each journal's splits under +`transactions[]` even for the single-split common case. Add `--flat` to get one +top-level object per split (the journal `id` repeated), with the split fields +(`amount`, `source_name`, `destination_name`, `category_name`, ...) at the top +level and no `transactions[]` key: +```bash +firefly tx list --account test01 --flat +``` +`--flat` affects JSON only; `--human` already renders one row per split. **Look up a transaction by id** (ids come from `tx add`/`tx list` output): ```bash diff --git a/completions/firefly.bash b/completions/firefly.bash index 648fbe0..6901d14 100644 --- a/completions/firefly.bash +++ b/completions/firefly.bash @@ -38,12 +38,12 @@ _firefly() { case "$group $leaf" in "auth set") leaf_opts="--token --url";; "account balance") leaf_opts="--at";; - "account create") leaf_opts="--currency --opening-balance --type";; + "account create") leaf_opts="--currency --if-not-exists --opening-balance --type";; "account list") leaf_opts="--type";; "tx add") leaf_opts="--category --date --desc --dry-run --from --skip-dupes --tags --to --type";; "tx delete") leaf_opts="--yes";; "tx edit") leaf_opts="--amount --category --date --desc --from --tags --to --type";; - "tx list") leaf_opts="--account --all --limit --since --until";; + "tx list") leaf_opts="--account --all --flat --limit --since --until";; esac # Leaves per group. diff --git a/firefly_cli/__init__.py b/firefly_cli/__init__.py index 4b170ef..27e214f 100644 --- a/firefly_cli/__init__.py +++ b/firefly_cli/__init__.py @@ -2,4 +2,4 @@ # Copyright (C) 2026 Danilo M. <danix@danix.xyz> # Licensed under the GNU General Public License v2.0 only. -__version__ = "0.3.5" +__version__ = "0.3.6" diff --git a/firefly_cli/commands/account.py b/firefly_cli/commands/account.py index d78f8fc..81c2e1d 100644 --- a/firefly_cli/commands/account.py +++ b/firefly_cli/commands/account.py @@ -23,6 +23,8 @@ def _create_args(p): p.add_argument("--opening-balance", dest="opening_balance", default=None, help="initial balance (asset accounts); dated today") p.add_argument("--currency", default=None, help="currency code, e.g. EUR") + p.add_argument("--if-not-exists", dest="if_not_exists", action="store_true", + help="if an account with this name exists, return it (existed:true) instead of erroring") @registry.command("account create", help="create an asset, expense, or revenue account", args=_create_args) def cmd_create(args, ctx): @@ -30,6 +32,17 @@ def cmd_create(args, ctx): raise FireflyError( f'Unsupported account type "{args.type}". ' f'Use one of: {", ".join(_CREATE_TYPES)}.') + if getattr(args, "if_not_exists", False): + # Resolve by name to detect existence; avoids parsing Firefly's 422 + # "name already in use" error string. Missing = ResolutionError -> create. + from firefly_cli.errors import ResolutionError + try: + existing = ctx.resolver.account(args.name) + except ResolutionError: + existing = None + if existing is not None: + output.emit({**existing, "existed": True}, human=ctx.human) + return 0 body = {"name": args.name, "type": args.type} if args.type == "asset": body["account_role"] = "defaultAsset" diff --git a/firefly_cli/commands/transaction.py b/firefly_cli/commands/transaction.py index df1ffc4..714d2d4 100644 --- a/firefly_cli/commands/transaction.py +++ b/firefly_cli/commands/transaction.py @@ -139,6 +139,8 @@ def _list_args(p): p.add_argument("--limit", type=int, default=20) p.add_argument("--all", action="store_true", help="fetch every page (ignores --limit truncation)") + p.add_argument("--flat", action="store_true", + help="one flat object per split; drop the transactions[] nesting (JSON only)") @registry.command("tx list", help="list recent transactions (newest first)", args=_list_args) def cmd_list(args, ctx): @@ -162,7 +164,7 @@ def cmd_list(args, ctx): if page >= (pg.get("total_pages") or 1): break page += 1 - output.emit(rows, human=ctx.human) + output.emit(_maybe_flat(rows, args, ctx), human=ctx.human) return 0 resp = ctx.client.request("GET", path, params=params) @@ -171,9 +173,16 @@ def cmd_list(args, ctx): if total is not None and count is not None and count < total: import sys print(f"showing {count} of {total} (use --all for all)", file=sys.stderr) - output.emit(output.unwrap(resp), human=ctx.human) + output.emit(_maybe_flat(output.unwrap(resp), args, ctx), human=ctx.human) return 0 +# --flat is a JSON-only convenience; --human already explodes splits into a +# table, so leave its nested rows alone. +def _maybe_flat(rows, args, ctx): + if getattr(args, "flat", False) and not ctx.human: + return output.flatten_tx(rows) + return rows + def _id_arg(p): p.add_argument("id") diff --git a/firefly_cli/output.py b/firefly_cli/output.py index 166e1bf..6c6a61c 100644 --- a/firefly_cli/output.py +++ b/firefly_cli/output.py @@ -62,6 +62,27 @@ def _tx_rows(rows): def _is_tx(rows): return bool(rows) and isinstance(rows[0], dict) and "transactions" in rows[0] +def flatten_tx(rows): + """Explode unwrapped tx journals into one flat object per split. + + Each journal is {id, transactions: [split, ...], ...}. We emit one object + per split: the split's raw Firefly fields (source_name, amount, etc.) with + the journal id merged in and the `transactions` list dropped. Single-split + journals (the common case) become one clean object. Rows without a + `transactions` list pass through unchanged. + """ + out = [] + for r in rows: + splits = r.get("transactions") + if not isinstance(splits, list): + out.append(r) + continue + for s in splits: + flat = dict(s) + flat["id"] = r.get("id") + out.append(flat) + return out + # Per-resource column whitelists for --human. Firefly returns ~50 fields per # row; only a handful are worth a table. A row is matched by a signature key. # (signature, columns) -- first match wins; unmatched rows use a generic table. diff --git a/pyproject.toml b/pyproject.toml index 7e1dbcd..86e8e62 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "firefly-iii-agent" -version = "0.3.5" +version = "0.3.6" description = "CLI tool for agent interaction with Firefly III" readme = "README.md" requires-python = ">=3.11" diff --git a/tests/unit/test_commands_account.py b/tests/unit/test_commands_account.py index 4a01292..c328890 100644 --- a/tests/unit/test_commands_account.py +++ b/tests/unit/test_commands_account.py @@ -43,7 +43,8 @@ class TestAccountCmd(unittest.TestCase): class TestAccountCreate(unittest.TestCase): def _args(self, **kw): - base = dict(name=None, type=None, opening_balance=None, currency=None) + base = dict(name=None, type=None, opening_balance=None, currency=None, + if_not_exists=False) base.update(kw) m = MagicMock() m.configure_mock(**base) # 'name' is reserved in MagicMock ctor, not configure_mock @@ -89,3 +90,36 @@ class TestAccountCreate(unittest.TestCase): with self.assertRaises(FireflyError): acct.cmd_create(self._args(name="X", type="bogus"), ctx) client.request.assert_not_called() + + def test_if_not_exists_returns_existing_no_post(self): + ctx, client, resolver = make_ctx() + resolver.account.return_value = {"id": "5", "name": "Savings", + "type": "asset"} + rc = acct.cmd_create( + self._args(name="Savings", type="asset", if_not_exists=True), ctx) + self.assertEqual(rc, 0) + resolver.account.assert_called_once_with("Savings") + client.request.assert_not_called() # existed -> no create + + def test_if_not_exists_creates_when_missing(self): + from firefly_cli.errors import ResolutionError + ctx, client, resolver = make_ctx() + resolver.account.side_effect = ResolutionError('No account named "Savings"') + client.request.return_value = {"data": {"id": "9", "attributes": {}}} + rc = acct.cmd_create( + self._args(name="Savings", type="asset", if_not_exists=True), ctx) + self.assertEqual(rc, 0) + method, path = client.request.call_args[0][:2] + self.assertEqual((method, path), ("POST", "/api/v1/accounts")) + + def test_if_not_exists_emits_existed_flag(self): + import io, json + from contextlib import redirect_stdout + ctx, client, resolver = make_ctx() + resolver.account.return_value = {"id": "5", "name": "Savings"} + buf = io.StringIO() + with redirect_stdout(buf): + acct.cmd_create( + self._args(name="Savings", type="asset", if_not_exists=True), ctx) + self.assertEqual(json.loads(buf.getvalue()), + {"id": "5", "name": "Savings", "existed": True}) diff --git a/tests/unit/test_commands_transaction.py b/tests/unit/test_commands_transaction.py index 0fa02ac..28882d3 100644 --- a/tests/unit/test_commands_transaction.py +++ b/tests/unit/test_commands_transaction.py @@ -264,7 +264,7 @@ class TestTxList(unittest.TestCase): ctx, client, _ = make_ctx() client.request.return_value = {"data": []} args = MagicMock(since="2026-06-01", until="2026-06-30", - account=None, limit=10, all=False) + account=None, limit=10, all=False, flat=False) tx.cmd_list(args, ctx) params = client.request.call_args[1]["params"] self.assertEqual(params["start"], "2026-06-01") @@ -280,7 +280,7 @@ class TestTxList(unittest.TestCase): "meta": {"pagination": {"total": 90, "count": 20, "current_page": 1, "total_pages": 5}}, } - args = MagicMock(since=None, until=None, account=None, limit=20, all=False) + args = MagicMock(since=None, until=None, account=None, limit=20, all=False, flat=False) buf = io.StringIO() with redirect_stderr(buf): tx.cmd_list(args, ctx) @@ -296,12 +296,49 @@ class TestTxList(unittest.TestCase): "meta": {"pagination": {"total": 1, "count": 1, "current_page": 1, "total_pages": 1}}, } - args = MagicMock(since=None, until=None, account=None, limit=20, all=False) + args = MagicMock(since=None, until=None, account=None, limit=20, all=False, flat=False) buf = io.StringIO() with redirect_stderr(buf): tx.cmd_list(args, ctx) self.assertEqual(buf.getvalue(), "") + def test_list_flat_explodes_splits_json(self): + import io, json + from contextlib import redirect_stdout + ctx, client, _ = make_ctx() + client.request.return_value = { + "data": [{"id": "7", "type": "transactions", "attributes": { + "transactions": [{"amount": "5", "source_name": "A"}]}}], + "meta": {"pagination": {"total": 1, "count": 1, "total_pages": 1}}, + } + args = MagicMock(since=None, until=None, account=None, limit=20, + all=False, flat=True) + buf = io.StringIO() + with redirect_stdout(buf): + tx.cmd_list(args, ctx) + out = json.loads(buf.getvalue()) + self.assertEqual(out, [{"amount": "5", "source_name": "A", "id": "7"}]) + + def test_list_flat_skipped_for_human(self): + # --human path must keep nested rows so the table renderer explodes them. + import io + from contextlib import redirect_stdout + ctx, client, _ = make_ctx() + ctx = Context(client=client, resolver=ctx.resolver, human=True) + client.request.return_value = { + "data": [{"id": "7", "attributes": { + "transactions": [{"amount": "5", "source_name": "A", + "destination_name": "B", "type": "withdrawal"}]}}], + "meta": {"pagination": {"total": 1, "count": 1, "total_pages": 1}}, + } + args = MagicMock(since=None, until=None, account=None, limit=20, + all=False, flat=True) + buf = io.StringIO() + with redirect_stdout(buf): + tx.cmd_list(args, ctx) + # human table shows the exploded split value; not raw JSON + self.assertIn("5", buf.getvalue()) + def test_list_all_paginates(self): ctx, client, _ = make_ctx() def page(method, path, params=None, body=None): @@ -312,7 +349,7 @@ class TestTxList(unittest.TestCase): "current_page": p, "total_pages": 2}}, } client.request.side_effect = page - args = MagicMock(since=None, until=None, account=None, limit=2, all=True) + args = MagicMock(since=None, until=None, account=None, limit=2, all=True, flat=False) rc = tx.cmd_list(args, ctx) self.assertEqual(rc, 0) self.assertEqual(client.request.call_count, 2) diff --git a/tests/unit/test_output.py b/tests/unit/test_output.py index 2e3e5ea..069a21d 100644 --- a/tests/unit/test_output.py +++ b/tests/unit/test_output.py @@ -1,6 +1,6 @@ import io, json, unittest from contextlib import redirect_stdout -from firefly_cli.output import unwrap, emit +from firefly_cli.output import unwrap, emit, flatten_tx class TestOutput(unittest.TestCase): def test_unwrap_list_returns_clean_objects(self): @@ -22,6 +22,29 @@ class TestOutput(unittest.TestCase): emit([{"id": "1", "name": "x"}], human=False) self.assertEqual(json.loads(buf.getvalue()), [{"id": "1", "name": "x"}]) + def test_flatten_single_split(self): + rows = [{"id": "10", "group_title": None, "transactions": [ + {"amount": "5.00", "source_name": "A", "destination_name": "B", + "type": "withdrawal"}]}] + flat = flatten_tx(rows) + self.assertEqual(len(flat), 1) + self.assertNotIn("transactions", flat[0]) + self.assertEqual(flat[0]["id"], "10") + self.assertEqual(flat[0]["amount"], "5.00") + self.assertEqual(flat[0]["source_name"], "A") + + def test_flatten_multi_split_repeats_id(self): + rows = [{"id": "20", "transactions": [ + {"amount": "1", "type": "withdrawal"}, + {"amount": "2", "type": "withdrawal"}]}] + flat = flatten_tx(rows) + self.assertEqual([f["id"] for f in flat], ["20", "20"]) + self.assertEqual([f["amount"] for f in flat], ["1", "2"]) + + def test_flatten_passes_through_non_tx_rows(self): + rows = [{"id": "1", "name": "Checking"}] + self.assertEqual(flatten_tx(rows), rows) + def test_emit_human_table_contains_values(self): buf = io.StringIO() with redirect_stdout(buf): |