Merge branch 'develop' into dependabot/pip/main/pytest-asyncio-1.4.0

Author: bobokun

VERSION

@@ -1 +1 @@
-0.1.9
+0.1.10

__init__.py

@@ -1,6 +1,6 @@
-actualpy==0.22.1
+actualpy==0.22.2
 fastapi[standard]==0.136.3
 pydantic
 pydantic-settings
 pyyaml
-uvicorn==0.47.0
+uvicorn==0.49.0

requirements.txt

@@ -1,12 +1,18 @@
 import hashlib
 import json
+import typing
 from decimal import Decimal
 from typing import List
 
 from actual import Actual
 from actual.queries import create_transaction
 from actual.queries import get_payees
-from actual.queries import get_ruleset
+from actual.queries import get_rules
+from actual.rules import Action
+from actual.rules import Condition
+from actual.rules import Rule
+from actual.rules import RuleSet
+from pydantic import TypeAdapter
 from sqlalchemy.orm.exc import MultipleResultsFound
 
 from core.config import settings
@@ -18,11 +24,19 @@
 
 
 class ActualService:
+    """Service layer for interacting with the Actual Budget API."""
+
     def __init__(self):
         self.client = None
 
     @staticmethod
     def _build_import_id(account_id: str, amount: Decimal, date, payee: str, notes: str, cleared: bool) -> str:
+        """Build a deterministic SHA-256-based import ID for a transaction.
+
+        The ID is derived from the account ID, amount, date, payee, notes, and
+        cleared flag so that identical transactions always produce the same ID,
+        allowing Actual Budget to detect and skip duplicates on re-import.
+        """
         normalized_amount = format(amount.normalize(), "f")
         normalized_payee = (payee or "").strip().lower()
         normalized_notes = (notes or "").strip().lower()
@@ -44,16 +58,83 @@ def _build_import_id(account_id: str, amount: Decimal, date, payee: str, notes:
 
     @staticmethod
     def _is_duplicate_payee_error(error: Exception) -> bool:
+        """Return True if the exception indicates a duplicate payee lookup result."""
         return isinstance(error, MultipleResultsFound) or "Multiple rows were found when one or none was required" in str(error)
 
     @staticmethod
     def _get_first_matching_payee(session, payee_name: str):
+        """Return the first payee matching the given name, or None if not found."""
         matching_payees = get_payees(session, name=payee_name)
         if not matching_payees:
             return None
         return matching_payees[0]
 
+    @staticmethod
+    def _build_ruleset(session) -> RuleSet:
+        """Build a RuleSet from the database, skipping any rules that fail validation.
+
+        Valid action fields are derived dynamically from the ``Action`` model's
+        type annotation so the check stays in sync with the installed version of
+        ``actualpy``.  Any rule whose actions reference an unrecognised field is
+        logged as a warning and excluded from the returned RuleSet rather than
+        aborting the entire import.
+        """
+        _field_annotation = Action.model_fields["field"].annotation
+        valid_action_fields = {
+            v
+            for arg in typing.get_args(_field_annotation)
+            for v in (typing.get_args(arg) if typing.get_origin(arg) is typing.Literal else ())
+        }
+        condition_adapter = TypeAdapter(list[Condition])
+        action_adapter = TypeAdapter(list[Action])
+        valid_rules = []
+        for raw_rule in get_rules(session):
+            if not raw_rule.conditions or not raw_rule.actions:
+                continue
+            try:
+                conditions = condition_adapter.validate_json(raw_rule.conditions)
+                actions = action_adapter.validate_json(raw_rule.actions)
+                valid_rules.append(
+                    Rule(
+                        conditions=conditions,
+                        operation=raw_rule.conditions_op,
+                        actions=actions,
+                        stage=raw_rule.stage,
+                    )
+                )
+            except Exception as rule_error:
+                try:
+                    raw_actions = json.loads(raw_rule.actions)
+                    bad_fields = [
+                        a.get("field")
+                        for a in raw_actions
+                        if isinstance(a, dict) and a.get("field") not in valid_action_fields and a.get("field") is not None
+                    ]
+                    raw_conditions = json.loads(raw_rule.conditions or "[]")
+                    condition_summary = ", ".join(
+                        f"{c.get('field')} {c.get('op')} '{c.get('value')}'" for c in raw_conditions if isinstance(c, dict)
+                    )
+                except json.JSONDecodeError:
+                    bad_fields = []
+                    condition_summary = "(unreadable)"
+                logger.warning(
+                    f"Skipping rule ID '{raw_rule.id}' (stage={raw_rule.stage!r}, "
+                    f"conditions: [{condition_summary}])"
+                    + (f" — unsupported action field(s): {bad_fields}" if bad_fields else f": {rule_error}")
+                )
+        return RuleSet(rules=valid_rules)
+
     def add_transactions(self, transactions: List[Transaction]):
+        """Add a list of transactions to Actual Budget.
+
+        For each transaction, the account name is resolved to an Actual account
+        ID using the configured mappings.  A deterministic import ID is generated
+        so duplicate submissions are ignored by Actual Budget.  After all
+        transactions are created, the full ruleset is applied (with invalid rules
+        skipped), and the session is committed.
+
+        Returns a list of dicts containing the logged details for each transaction.
+        """
         transaction_info_list = []
         submitted_transactions = []
 
@@ -133,9 +214,8 @@ def add_transactions(self, transactions: List[Transaction]):
                     )
                 submitted_transactions.append(actual_transaction)
 
-            # Run ruleset on submitted transactions
-            rs = get_ruleset(actual.session)
-            rs.run(submitted_transactions)
+            # Run ruleset on submitted transactions, skipping any rules that fail validation
+            self._build_ruleset(actual.session).run(submitted_transactions)
 
             # Log transaction info
             logger.info("\n" + json.dumps(transaction_info_list, indent=2))