ynab-amazon-categorizer 2.2.4__tar.gz → 2.3.0__tar.gz

ynab_amazon_categorizer-2.3.0/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # Fetch full history and tags for setuptools-scm
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Run tests
+        run: uv run python -X utf8 -m pytest tests/ -v
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Ruff format check
+        run: uv run --extra dev ruff format --check src tests
+      - name: Ruff lint
+        run: uv run --extra dev ruff check src tests
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # Fetch full history and tags for setuptools-scm
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Run type checker
+        run: uv run --extra dev ty check src tests

{ynab_amazon_categorizer-2.2.4 → ynab_amazon_categorizer-2.3.0}/.gitignore

@@ -29,6 +29,15 @@ wheels/
 venv/
 env/
 ENV/
+.venv/
+
+# Test / coverage artifacts
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.uv-cache/
 
 # IDE
 .vscode/

{ynab_amazon_categorizer-2.2.4 → ynab_amazon_categorizer-2.3.0}/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-06-19
+
+### Added
+
+- `--dry-run` flag: preview every update without sending changes to YNAB
+- `--batch` flag: non-interactively auto-set memos (items + order link) for confidently matched transactions, leaving categories unchanged; combine with `--dry-run` to preview
+- CI workflow running tests (Ubuntu + Windows, Python 3.12 & 3.13), lint, and type checks on every push and pull request
+
+### Changed
+
+- All interactive prompts now go through `prompt_toolkit` for consistent input handling (replaces the builtin `input()`)
+
+### Fixed
+
+- A matched Amazon order is no longer reused for multiple same-amount transactions in a single run
+- "Subscribe & Save" / delivery-management lines and refund-status lines are no longer extracted as order items
+
 ## [2.2.4] - 2026-05-13
 
 ### Fixed

{ynab_amazon_categorizer-2.2.4 → ynab_amazon_categorizer-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ynab-amazon-categorizer
-Version: 2.2.4
+Version: 2.3.0
 Summary: Automatically categorize Amazon transactions in YNAB with rich item information
 Author: dizzlkheinz
 License: GPL-3.0
@@ -138,6 +138,37 @@ ynab-amazon-categorizer
 python -m ynab_amazon_categorizer
 ```
 
+### Dry run
+
+Use `--dry-run` to walk through the full interactive flow and preview every
+update without sending any changes to YNAB:
+
+```bash
+ynab-amazon-categorizer --dry-run
+```
+
+The tool still shows the JSON preview for each transaction but skips the API
+call, so it is safe for trying the tool out or verifying matches.
+
+### Batch mode
+
+Use `--batch` to run non-interactively: for every transaction with a single
+high-confidence order match (unique exact-amount match within ~7 days), the
+tool sets the memo (items + order link) automatically and **leaves the category
+unchanged**, so you can still review/categorize later. Transactions with no
+match or an ambiguous match are skipped.
+
+```bash
+# Preview what batch mode would enrich
+ynab-amazon-categorizer --batch --dry-run
+
+# Apply memo enrichment
+ynab-amazon-categorizer --batch
+```
+
+You still paste the Amazon orders page once when prompted; `--batch` only
+removes the per-transaction prompting.
+
 ### Workflow
 1. **Provide Amazon Orders Data** (optional but recommended):
    - Copy your Amazon orders page content

{ynab_amazon_categorizer-2.2.4 → ynab_amazon_categorizer-2.3.0}/README.md

@@ -104,6 +104,37 @@ ynab-amazon-categorizer
 python -m ynab_amazon_categorizer
 ```
 
+### Dry run
+
+Use `--dry-run` to walk through the full interactive flow and preview every
+update without sending any changes to YNAB:
+
+```bash
+ynab-amazon-categorizer --dry-run
+```
+
+The tool still shows the JSON preview for each transaction but skips the API
+call, so it is safe for trying the tool out or verifying matches.
+
+### Batch mode
+
+Use `--batch` to run non-interactively: for every transaction with a single
+high-confidence order match (unique exact-amount match within ~7 days), the
+tool sets the memo (items + order link) automatically and **leaves the category
+unchanged**, so you can still review/categorize later. Transactions with no
+match or an ambiguous match are skipped.
+
+```bash
+# Preview what batch mode would enrich
+ynab-amazon-categorizer --batch --dry-run
+
+# Apply memo enrichment
+ynab-amazon-categorizer --batch
+```
+
+You still paste the Amazon orders page once when prompted; `--batch` only
+removes the per-transaction prompting.
+
 ### Workflow
 1. **Provide Amazon Orders Data** (optional but recommended):
    - Copy your Amazon orders page content

{ynab_amazon_categorizer-2.2.4 → ynab_amazon_categorizer-2.3.0}/src/ynab_amazon_categorizer/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.2.4'
-__version_tuple__ = version_tuple = (2, 2, 4)
+__version__ = version = '2.3.0'
+__version_tuple__ = version_tuple = (2, 3, 0)
 
-__commit_id__ = commit_id = 'g034b5e27c'
+__commit_id__ = commit_id = 'gfc90aac23'

{ynab_amazon_categorizer-2.2.4 → ynab_amazon_categorizer-2.3.0}/src/ynab_amazon_categorizer/amazon_parser.py

@@ -112,7 +112,9 @@ class AmazonParser:
             skip_patterns = [
                 r"^(Buy it again|Track package|View|Return|Write|Get|Share|Leave|Ask)",
                 r"^(Delivered|Arriving|Now arriving|Auto-delivered|Package was)",
-                r"^(Return items:|Return or replace)",
+                r"^(Return items:|Return or replace|Refund issued|Refund:|Returned)",
+                r"^(Subscribe & Save|Subscribe now|Skip this delivery|Deliver every"
+                r"|Change delivery|Manage subscription|Edit delivery|Set up now)",
                 r"^\d+\.?\d* out of \d+ stars",
                 r"^FREE|^Today by|^Get it|^List:|^Was:|^Limited-time deal",
                 r"^\$\d+\.\d+|\(\$\d+\.\d+",

{ynab_amazon_categorizer-2.2.4 → ynab_amazon_categorizer-2.3.0}/src/ynab_amazon_categorizer/cli.py

@@ -1,3 +1,4 @@
+import argparse
 import copy
 import json
 import logging
@@ -90,6 +91,18 @@ def get_multiline_input_with_custom_submit(
         return None
 
 
+def _prompt_line(message: str) -> str:
+    """Read one line of input via prompt_toolkit for consistent UX.
+
+    Used in place of the builtin input function so every prompt in the tool goes
+    through prompt_toolkit (uniform rendering and key handling). Mirrors builtin
+    input semantics: returns the entered text and lets ``EOFError`` /
+    ``KeyboardInterrupt`` propagate to the caller, so existing ``.strip()`` /
+    ``.lower()`` chains on the result keep working.
+    """
+    return prompt(message)
+
+
 def generate_split_summary_memo(matching_order: Order) -> str:
     """Generate a summary memo for split transactions showing all items"""
     if (
@@ -118,13 +131,15 @@ def prompt_for_item_details() -> dict[str, str | int | float | list[str] | None]
     item_details: dict[str, str | int | float | list[str] | None] = {}
 
     # Get item title/description
-    title = input("Enter item title/description (optional): ").strip()
+    title = _prompt_line("Enter item title/description (optional): ").strip()
     if title:
         item_details["title"] = title
 
     # Get quantity
     while True:
-        qty_input = input("Enter quantity (optional, press Enter to skip): ").strip()
+        qty_input = _prompt_line(
+            "Enter quantity (optional, press Enter to skip): "
+        ).strip()
         if not qty_input:
             break
         try:
@@ -139,7 +154,7 @@ def prompt_for_item_details() -> dict[str, str | int | float | list[str] | None]
 
     # Get price per item
     while True:
-        price_input = input(
+        price_input = _prompt_line(
             "Enter item price (optional, press Enter to skip): "
         ).strip()
         if not price_input:
@@ -248,6 +263,37 @@ def build_single_payload(
     }
 
 
+def build_memo_only_payload(transaction: dict[str, Any], memo: str) -> dict[str, Any]:
+    """Build an update payload that changes only the memo.
+
+    Used by batch mode: the category and approved status are preserved exactly
+    as YNAB returned them, so the transaction stays uncategorized for later
+    review while gaining the enriched Amazon memo.
+    """
+    return {
+        "id": transaction["id"],
+        "account_id": transaction["account_id"],
+        "date": transaction["date"],
+        "amount": transaction["amount"],
+        "payee_id": transaction.get("payee_id"),
+        "payee_name": transaction.get("payee_name", "N/A"),
+        "category_id": transaction.get("category_id"),
+        "memo": sanitize_memo(memo),
+        "cleared": transaction.get("cleared"),
+        "approved": transaction.get("approved", False),
+        "flag_color": transaction.get("flag_color"),
+        "import_id": transaction.get("import_id"),
+    }
+
+
+def build_batch_memo(order: Order, memo_generator: MemoGenerator) -> str:
+    """Build the auto-enrich memo (item summary + order link) for batch mode."""
+    items_text = generate_split_summary_memo(order) or "Amazon Purchase"
+    order_link = memo_generator.generate_amazon_order_link(order.order_id)
+    raw = f"{items_text}\n {order_link}" if order_link else items_text
+    return sanitize_memo(raw)
+
+
 def build_split_payload(
     transaction: dict[str, Any],
     subtransactions: list[dict[str, int | str | None]],
@@ -416,7 +462,7 @@ def resolve_memo(
         }
     else:
         # Ask if user wants to enter item details manually
-        manual_entry = input(
+        manual_entry = _prompt_line(
             "No order match found. Enter item details manually? (y/n, default n): "
         ).lower()
         if manual_entry == "y":
@@ -447,7 +493,7 @@ def resolve_memo(
     if enhanced_memo and enhanced_memo != original_memo:
         print("\nSuggested memo:")
         print(f"'{enhanced_memo}'")
-        use_suggested = input("Use suggested memo? (y/n, default y): ").lower()
+        use_suggested = _prompt_line("Use suggested memo? (y/n, default y): ").lower()
         if use_suggested != "n":
             return sanitize_memo(enhanced_memo)
         else:
@@ -503,7 +549,7 @@ def handle_split(
         while True:
             try:
                 max_amount = abs(remaining_milliunits / 1000.0)
-                amount_str = input(
+                amount_str = _prompt_line(
                     f"Enter amount for '{category_name}' (positive, max {max_amount:.2f}, default {max_amount:.2f}): "
                 )
                 if not amount_str:
@@ -575,7 +621,7 @@ def _resolve_split_memo(
         else:
             suggested_split_memo = "Additional item"
     else:
-        manual_entry = input(
+        manual_entry = _prompt_line(
             "Enter item details for this split? (y/n, default n): "
         ).lower()
         if manual_entry == "y":
@@ -588,7 +634,7 @@ def _resolve_split_memo(
     if suggested_split_memo:
         print(f"Suggested memo for '{category_name}' split:")
         print(f"'{suggested_split_memo}'")
-        use_suggested = input("Use suggested memo? (y/n, default y): ").lower()
+        use_suggested = _prompt_line("Use suggested memo? (y/n, default y): ").lower()
         if use_suggested != "n":
             return suggested_split_memo
         else:
@@ -611,10 +657,17 @@ def process_transaction(
     category_completer: CategoryCompleter,
     category_name_map: dict[str, str],
     category_id_map: dict[str, str],
+    used_order_ids: set[str] | None = None,
+    dry_run: bool = False,
 ) -> bool:
     """Process a single transaction through the interactive flow.
 
     Returns True if processed/skipped, False if user quit.
+
+    ``used_order_ids`` accumulates the order IDs already applied to a
+    transaction so the matcher does not reuse one order for several
+    same-amount transactions. When ``dry_run`` is True no changes are sent
+    to YNAB and matched orders are not marked as used.
     """
     transaction_id = transaction["id"]
     date = transaction["date"]
@@ -625,7 +678,7 @@ def process_transaction(
 
     if amount_milliunits > 0:
         print(f"Found inflow transaction: {payee} ${amount_float:.2f}")
-        process_inflow = input(
+        process_inflow = _prompt_line(
             "Process this inflow (refund/credit)? (y/n, default n): "
         ).lower()
         if process_inflow != "y":
@@ -645,7 +698,7 @@ def process_transaction(
     if parsed_orders:
         transaction_matcher = TransactionMatcher()
         matching_order = transaction_matcher.find_matching_order(
-            amount_float, date, parsed_orders
+            amount_float, date, parsed_orders, used_order_ids
         )
         if matching_order:
             display_matched_order(matching_order, memo_generator)
@@ -653,7 +706,7 @@ def process_transaction(
             print("  ⚠ No matching order found in parsed Amazon data")
 
     while True:  # Action loop (c, s, q)
-        action = input(
+        action = _prompt_line(
             "Action? (c = categorize/split, s = skip, q = quit, default c): "
         ).lower()
         if not action:
@@ -674,8 +727,19 @@ def process_transaction(
                 category_completer,
                 category_name_map,
                 category_id_map,
+                dry_run,
             )
             if result == "done":
+                # Mark the matched order as consumed so it is not reused for a
+                # later transaction of the same amount. Skip in dry-run because
+                # nothing was actually applied.
+                if (
+                    not dry_run
+                    and used_order_ids is not None
+                    and matching_order is not None
+                    and matching_order.order_id is not None
+                ):
+                    used_order_ids.add(matching_order.order_id)
                 return True
             # result == "continue" means back to action prompt
             continue
@@ -692,11 +756,14 @@ def _handle_categorize(
     category_completer: CategoryCompleter,
     category_name_map: dict[str, str],
     category_id_map: dict[str, str],
+    dry_run: bool = False,
 ) -> str:
     """Handle the categorize action for a transaction.
 
     Returns "done" if the transaction was successfully updated (or split completed),
     or "continue" to go back to the action prompt.
+
+    When ``dry_run`` is True the preview is shown but no update is sent to YNAB.
     """
     transaction_id = transaction["id"]
     updated_payload_dict: dict[str, Any] | None = None
@@ -709,7 +776,7 @@ def _handle_categorize(
     if should_offer_split:
         print("There is more than one item in this transaction.")
 
-    split_decision = input("Split this transaction? (y/n, default n): ").lower()
+    split_decision = _prompt_line("Split this transaction? (y/n, default n): ").lower()
 
     if split_decision != "y":
         # --- SINGLE CATEGORY ---
@@ -748,7 +815,10 @@ def _handle_categorize(
         print("\n--- Preview Update ---")
         preview_dict = build_preview(updated_payload_dict, category_id_map)
         print(json.dumps(preview_dict, indent=2, ensure_ascii=False))
-        confirm = input("Confirm update? (y/n, default y): ").lower()
+        if dry_run:
+            print("[dry-run] No changes were sent to YNAB.")
+            return "done"
+        confirm = _prompt_line("Confirm update? (y/n, default y): ").lower()
         if not confirm:
             confirm = "y"
         if confirm == "y":
@@ -767,13 +837,102 @@ def _handle_categorize(
     return "continue"
 
 
+# --- Batch Mode ---
+
+
+def process_batch(
+    transactions: list[dict[str, Any]],
+    parsed_orders: list[Order] | None,
+    memo_generator: MemoGenerator,
+    ynab_client: YNABClient,
+    dry_run: bool = False,
+) -> tuple[int, int, int]:
+    """Auto-enrich memos for confidently-matched transactions without prompting.
+
+    Only the memo is set (items + order link); the category is left untouched so
+    the transaction stays uncategorized for later review. Transactions with no
+    match or an ambiguous match are skipped.
+
+    Returns a ``(enriched, skipped, failed)`` tuple.
+    """
+    matcher = TransactionMatcher()
+    used_order_ids: set[str] = set()
+    enriched = skipped = failed = 0
+
+    for t in transactions:
+        amount_float = t["amount"] / 1000.0
+        order = matcher.find_confident_match(
+            amount_float, t["date"], parsed_orders or [], used_order_ids
+        )
+        if order is None:
+            skipped += 1
+            continue
+
+        memo = build_batch_memo(order, memo_generator)
+        payload = build_memo_only_payload(t, memo)
+        payee = t.get("payee_name", "N/A")
+        summary = memo.splitlines()[0] if memo else ""
+
+        if dry_run:
+            print(f"  [dry-run] would enrich {payee} ${amount_float:.2f}: {summary}")
+            if order.order_id:
+                used_order_ids.add(order.order_id)
+            enriched += 1
+            continue
+
+        try:
+            ynab_client.update_transaction(t["id"], payload)
+            print(f"  ✓ Enriched {payee} ${amount_float:.2f}: {summary}")
+            if order.order_id:
+                used_order_ids.add(order.order_id)
+            enriched += 1
+        except (YNABAPIError, requests.exceptions.RequestException) as exc:
+            logger.error("Failed to enrich transaction %s: %s", t["id"], exc)
+            print(f"  ✗ Failed to enrich {payee} ${amount_float:.2f}: {exc}")
+            failed += 1
+
+    return enriched, skipped, failed
+
+
 # --- Main Script Logic ---
 
 
-def main() -> None:
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    """Parse command-line arguments."""
+    parser = argparse.ArgumentParser(
+        prog="ynab-amazon-categorizer",
+        description=(
+            "Auto-categorize Amazon transactions in YNAB with item-level "
+            "memos and category suggestions."
+        ),
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview updates without sending any changes to YNAB.",
+    )
+    parser.add_argument(
+        "--batch",
+        action="store_true",
+        help=(
+            "Non-interactive: auto-set memos (items + order link) for "
+            "confidently matched transactions and leave categories unchanged. "
+            "Combine with --dry-run to preview."
+        ),
+    )
+    return parser.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> None:
     """Main CLI function."""
+    args = _parse_args(argv)
+    dry_run = args.dry_run
+
     logging.basicConfig(level=logging.INFO)
 
+    if dry_run:
+        print("*** DRY RUN: no changes will be sent to YNAB. ***")
+
     # Load configuration using extracted Config class
     try:
         config = Config.from_env()
@@ -810,7 +969,7 @@ def main() -> None:
     print(
         "You can paste Amazon orders page content to automatically match transactions with order details."
     )
-    provide_orders = input(
+    provide_orders = _prompt_line(
         "Would you like to provide Amazon orders data? (y/n, default y): "
     ).lower()
     if not provide_orders:
@@ -842,7 +1001,24 @@ def main() -> None:
         f"\nFound {len(transactions_to_process)} uncategorized Amazon transaction(s) needing attention."
     )
 
+    # --- Batch Mode (non-interactive memo enrichment) ---
+    if args.batch:
+        print("\n--- Batch: auto-enriching memos for confident matches ---")
+        enriched, skipped, failed = process_batch(
+            transactions_to_process,
+            parsed_orders,
+            memo_generator,
+            ynab_client,
+            dry_run,
+        )
+        print(
+            f"\nBatch complete: {enriched} enriched, {skipped} skipped "
+            f"(no/ambiguous match), {failed} failed."
+        )
+        return
+
     # --- Process Transactions (Main Loop) ---
+    used_order_ids: set[str] = set()
     for i, t in enumerate(transactions_to_process):
         should_continue = process_transaction(
             t,
@@ -854,6 +1030,8 @@ def main() -> None:
             category_completer_instance,
             category_name_map,
             category_id_map,
+            used_order_ids,
+            dry_run,
         )
         if not should_continue:
             sys.exit(0)

{ynab_amazon_categorizer-2.2.4 → ynab_amazon_categorizer-2.3.0}/src/ynab_amazon_categorizer/transaction_matcher.py

@@ -20,11 +20,15 @@ class TransactionMatcher:
         transaction_amount: float,
         transaction_date: str,
         parsed_orders: Sequence[Order],
+        used_order_ids: set[str] | None = None,
     ) -> Order | None:
         """Find the best matching order for a transaction.
 
         Matching requires an exact amount match (within 1 cent).
         Ties are broken by date proximity, then by order ID for determinism.
+
+        Orders whose ``order_id`` appears in ``used_order_ids`` are skipped so a
+        single order is not matched to multiple transactions of the same amount.
         """
         if not parsed_orders:
             return None
@@ -46,6 +50,13 @@ class TransactionMatcher:
             if order.total is None:
                 continue
 
+            if (
+                used_order_ids
+                and order.order_id is not None
+                and order.order_id in used_order_ids
+            ):
+                continue
+
             amount_diff = abs(order.total - transaction_amount_abs)
             if amount_diff >= 0.01:
                 continue
@@ -91,3 +102,55 @@ class TransactionMatcher:
                 best_order_id = order_id
 
         return best_match
+
+    def find_confident_match(
+        self,
+        transaction_amount: float,
+        transaction_date: str,
+        parsed_orders: Sequence[Order],
+        used_order_ids: set[str] | None = None,
+        max_date_diff_days: int = 7,
+    ) -> Order | None:
+        """Return an order only when the match is unambiguous (for batch use).
+
+        Unlike ``find_matching_order``, this requires *exactly one* unused order
+        matching the amount (within 1 cent). If that order has a parseable date
+        it must be within ``max_date_diff_days`` of the transaction. Any
+        ambiguity (zero or multiple amount matches, or a far-off date) returns
+        ``None`` so batch mode never auto-applies a guess.
+        """
+        amount_abs = abs(transaction_amount)
+
+        try:
+            trans_date: datetime | None = datetime.strptime(
+                transaction_date, "%Y-%m-%d"
+            )
+        except (ValueError, TypeError):
+            trans_date = None
+
+        candidates: list[Order] = []
+        for order in parsed_orders:
+            if order.total is None:
+                continue
+            if (
+                used_order_ids
+                and order.order_id is not None
+                and order.order_id in used_order_ids
+            ):
+                continue
+            if abs(order.total - amount_abs) >= 0.01:
+                continue
+            candidates.append(order)
+
+        if len(candidates) != 1:
+            return None
+
+        order = candidates[0]
+        if trans_date and isinstance(order.date_str, str) and order.date_str:
+            try:
+                order_date = datetime.strptime(order.date_str, "%B %d, %Y")
+                if abs((trans_date - order_date).days) > max_date_diff_days:
+                    return None
+            except (ValueError, TypeError):
+                pass
+        return order