ynab-unlinked 0.0.2__tar.gz

ynab_unlinked-0.0.2/.github/workflows/pypi-release.yml

@@ -0,0 +1,38 @@
+name: Python Package CI
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build-and-publish:
+    if: startsWith(github.event.release.tag_name, 'yul-')
+    name: Build and publish Python distributions to PyPI
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write # Needed for OIDC
+      contents: read # Needed to checkout the repository
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12" # Or specify your desired Python version
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch
+
+      - name: Build package
+        run: hatch build
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # skip_existing: true # Uncomment if you want to skip publishing if the version already exists
+          print_hash: true

ynab_unlinked-0.0.2/.gitignore

@@ -0,0 +1,2 @@
+__pycache__
+*.ipynb

ynab_unlinked-0.0.2/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025-present Juanpe Araque <juanpe@committhatline.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

ynab_unlinked-0.0.2/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: ynab-unlinked
+Version: 0.0.2
+Project-URL: Documentation, https://github.com/Juanpe Araque/ynab-unlinked#readme
+Project-URL: Issues, https://github.com/Juanpe Araque/ynab-unlinked/issues
+Project-URL: Source, https://github.com/Juanpe Araque/ynab-unlinked
+Author-email: Juanpe Araque <juanpe@committhatline.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.12
+Requires-Dist: html-text
+Requires-Dist: pdfplumber
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: rapidfuzz
+Requires-Dist: typer
+Requires-Dist: unidecode
+Requires-Dist: ynab
+Description-Content-Type: text/markdown
+
+# YNAB Unlinked
+
+YNAB Unlinked is a CLI tools that allows creating transactions in your YNAB account from any input file.
+
+Want to know more? Check out our [wiki](https://github.com/AAraKKe/ynab-unlinked/wiki) where you'll find all the details on how to get started, add new entities, and make the most of this tool. It's pretty straightforward once you get the hang of it!
+
+> [!IMPORTANT]
+> This project just started and is open to contributions!
+
+## License
+
+`ynab-unlinked` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

ynab_unlinked-0.0.2/README.md

@@ -0,0 +1,12 @@
+# YNAB Unlinked
+
+YNAB Unlinked is a CLI tools that allows creating transactions in your YNAB account from any input file.
+
+Want to know more? Check out our [wiki](https://github.com/AAraKKe/ynab-unlinked/wiki) where you'll find all the details on how to get started, add new entities, and make the most of this tool. It's pretty straightforward once you get the hang of it!
+
+> [!IMPORTANT]
+> This project just started and is open to contributions!
+
+## License
+
+`ynab-unlinked` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

ynab_unlinked-0.0.2/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ynab-unlinked"
+dynamic = ["version"]
+description = ''
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+keywords = []
+authors = [{ name = "Juanpe Araque", email = "juanpe@committhatline.com" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Programming Language :: Python :: Implementation :: PyPy",
+]
+dependencies = [
+  "ynab",
+  "typer",
+  "rapidfuzz",
+  "unidecode",
+  "html-text",
+  "pdfplumber",
+  "pydantic >= 2.0.0",
+]
+
+[project.scripts]
+yul = "ynab_unlinked.__main__:main"
+
+[project.urls]
+Documentation = "https://github.com/Juanpe Araque/ynab-unlinked#readme"
+Issues = "https://github.com/Juanpe Araque/ynab-unlinked/issues"
+Source = "https://github.com/Juanpe Araque/ynab-unlinked"
+
+[tool.hatch.version]
+path = "src/ynab_unlinked/__about__.py"
+
+[tool.hatch.envs.types]
+extra-dependencies = ["mypy>=1.0.0"]
+[tool.hatch.envs.types.scripts]
+check = "mypy --install-types --non-interactive {args:src/ynab_unlinked tests}"
+
+[tool.hatch.envs.default.scripts]
+yul = "python src/ynab_unlinked {args}"
+
+[tool.coverage.run]
+source_pkgs = ["ynab_unlinked", "tests"]
+branch = true
+parallel = true
+omit = ["src/ynab_unlinked/__about__.py"]
+
+[tool.coverage.paths]
+ynab_unlinked = ["src/ynab_unlinked", "*/ynab-unlinked/src/ynab_unlinked"]
+tests = ["tests", "*/ynab-unlinked/tests"]
+
+[tool.coverage.report]
+exclude_lines = ["no cov", "if __name__ == .__main__.:", "if TYPE_CHECKING:"]

ynab_unlinked-0.0.2/src/ynab_unlinked/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2025-present Juanpe Araque <juanpe@committhatline.com>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.0.2"

ynab_unlinked-0.0.2/src/ynab_unlinked/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2025-present Juanpe Araque <juanpe@committhatline.com>
+#
+# SPDX-License-Identifier: MIT
+
+import typer
+
+app = typer.Typer(name="ynab-unlinked", no_args_is_help=True)

ynab_unlinked-0.0.2/src/ynab_unlinked/__main__.py

@@ -0,0 +1,56 @@
+import typer
+
+from ynab_unlinked.config import Config, ensure_config
+from ynab_unlinked.context_object import YnabUnlinkedContext
+from ynab_unlinked.commands import load, config
+from ynab_unlinked.display import prompt_for_api_key, prompt_for_budget
+
+from rich import print
+
+app = typer.Typer()
+
+app.add_typer(load, name="load")
+app.add_typer(config, name="config")
+
+
+@app.command(name="setup")
+def setup_command():
+    """Setup YNAB Unlinked"""
+    print("[bold]Welcome to ynab-unlinked! Lets setup your connection")
+    api_key = prompt_for_api_key()
+    config = Config(api_key=api_key, budget_id="")
+    config.save()
+
+    budget_id = prompt_for_budget()
+    config.budget_id = budget_id
+    config.save()
+
+    print("[bold green]All done!")
+
+
+@app.callback(no_args_is_help=True)
+def cli(context: typer.Context):
+    """
+    Create transations in your YNAB account from a bank export of your extract.
+    \n
+
+    The first time the command is run you will be asked some questions to setup your YNAB connection. After that,
+    transaction processing won't require any input unless there are some actions to take for specific transactions.
+    """
+
+    if context.invoked_subcommand == "setup":
+        # If we are running setup there is nothing to do here
+        return
+
+    if not ensure_config():
+        setup_command()
+    config = Config.load()
+    context.obj = YnabUnlinkedContext(config=config, extras=None)
+
+
+def main():
+    app(prog_name="yul")
+
+
+if __name__ == "__main__":
+    main()

ynab_unlinked-0.0.2/src/ynab_unlinked/commands/__init__.py

@@ -0,0 +1,4 @@
+from .load import load
+from .config import config
+
+__all__ = ["config", "load"]

ynab_unlinked-0.0.2/src/ynab_unlinked/commands/config.py

@@ -0,0 +1,56 @@
+from typing_extensions import Annotated
+from typing import assert_never
+from enum import StrEnum
+
+import typer
+from rich import print
+
+from ynab_unlinked.config import Config, ensure_config
+from ynab_unlinked.display import prompt_for_api_key, prompt_for_budget
+
+
+class ValidKeys(StrEnum):
+    BUDGET = "budget"
+    API_KEY = "api_key"
+
+
+config = typer.Typer(help="Manage YNAB Unlinked configuration")
+
+
+@config.command(name="set")
+def set_command(
+    key: Annotated[
+        ValidKeys, typer.Argument(help="The config key to set", show_default=False)
+    ],
+):
+    """Set configuration options"""
+
+    match key:
+        case ValidKeys.API_KEY:
+            api_key = prompt_for_api_key()
+            # If the config exist, just update it
+            if ensure_config():
+                config = Config.load()
+                config.api_key = api_key
+            else:
+                config = Config(api_key=api_key, budget_id="")
+
+            config.save()
+            print("[bold green]🎉 The API key has been updated[/]")
+        case ValidKeys.BUDGET:
+            budget_id = prompt_for_budget()
+            config = Config.load()
+            config.budget_id = budget_id
+            config.save()
+            print("[bold green]🎉 The budget has been updated[/]")
+        case never:
+            assert_never(never)
+
+
+@config.command(name="show")
+def show():
+    if not ensure_config():
+        raise typer.Abort("YNAB Unlinked config not found. Run 'yul setup' to configure it.")
+
+    config = Config.load()
+    print(config.model_dump_json(indent=2))

ynab_unlinked-0.0.2/src/ynab_unlinked/commands/load.py

@@ -0,0 +1,48 @@
+import pkgutil
+import importlib
+from typing_extensions import Annotated
+
+import typer
+
+from ynab_unlinked import entities
+from ynab_unlinked.context_object import YnabUnlinkedContext
+
+load = typer.Typer(
+    help="Load transactions from a bank statement into your YNAB account.",
+)
+
+
+@load.callback()
+def load_callback(
+    context: typer.Context,
+    show: Annotated[
+        bool,
+        typer.Option(
+            "-s",
+            "--show",
+            help="Just show the transactions available in the input file.",
+        ),
+    ] = False,
+    reconcile: Annotated[
+        bool, typer.Option("-r", "--reconcile", help="Reconcile cleared transactions")
+    ] = False,
+):
+    obj: YnabUnlinkedContext = context.obj
+
+    obj.show = show
+    obj.reconcile = reconcile
+
+
+# Dynamically load all entities commands when present
+for finder, name, ispkg in pkgutil.iter_modules(entities.__path__):
+    if not ispkg:
+        continue
+
+    module = importlib.import_module(f"{entities.__name__}.{name}")
+    if not hasattr(module, "command"):
+        continue
+
+    command = getattr(module, "command")
+
+    if callable(command):
+        load.command(name=name, no_args_is_help=True)(command)

ynab_unlinked-0.0.2/src/ynab_unlinked/config.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import datetime as dt
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from ynab_unlinked.models import Transaction, TransactionWithYnabData
+
+CONFIG_PATH = Path.home() / ".config/ynab_unlinked/config.json"
+TRANSACTION_GRACE_PERIOD_DAYS = 2
+
+
+class Checkpoint(BaseModel):
+    latest_date_processed: dt.date
+    latest_transaction_hash: int
+
+
+class EntityConfig(BaseModel):
+    account_id: str
+    checkpoint: Checkpoint | None = None
+
+
+class Config(BaseModel):
+    api_key: str
+    budget_id: str
+    entities: dict[str, EntityConfig] = Field(default_factory=dict)
+    payee_rules: dict[str, set[str]] = Field(default_factory=dict)
+
+    def save(self):
+        CONFIG_PATH.write_text(self.model_dump_json(indent=4))
+
+    def update_and_save(self, last_transaction: Transaction, entity_name: str):
+        checkpoint = Checkpoint(
+            latest_date_processed=(
+                last_transaction.date - dt.timedelta(days=TRANSACTION_GRACE_PERIOD_DAYS)
+            ),
+            latest_transaction_hash=hash(last_transaction),
+        )
+
+        self.entities[entity_name].checkpoint = checkpoint
+
+        self.save()
+
+    @staticmethod
+    def load() -> Config:
+        return Config.model_validate_json(CONFIG_PATH.read_text())
+
+    def add_payee_rules(self, transactions: list[TransactionWithYnabData]):
+        # For each transaction, add a rule that matches both payees
+        for transaction in transactions:
+            if transaction.partial_match is None:
+                continue
+
+            if transaction.ynab_payee is None:
+                continue
+
+            imported_payee = transaction.payee
+            ynab_payee = transaction.ynab_payee
+
+            if imported_payee == ynab_payee:
+                continue
+
+            self.payee_rules.setdefault(ynab_payee, set()).add(imported_payee)
+            self.save()
+
+    def payee_from_fules(self, payee: str) -> str | None:
+        return next(
+            (
+                ynab_payee
+                for ynab_payee, valid_names in self.payee_rules.items()
+                if payee in valid_names
+            ),
+            None,
+        )
+
+
+def ensure_config():
+    if not CONFIG_PATH.is_file():
+        CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        return False
+    return True

ynab_unlinked-0.0.2/src/ynab_unlinked/context_object.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass
+
+from ynab_unlinked.config import Config
+
+
+@dataclass
+class YnabUnlinkedContext[T]:
+    config: Config
+    extras: T
+    show: bool = False
+    reconcile: bool = False

ynab_unlinked-0.0.2/src/ynab_unlinked/display.py

@@ -0,0 +1,216 @@
+from rich import box, print
+from rich.rule import Rule
+from rich.style import Style
+from rich.table import Column, Table
+from rich.prompt import Prompt
+from rich.status import Status
+
+from ynab_unlinked.config import Config, ensure_config
+from ynab_unlinked.models import MatchStatus, Transaction, TransactionWithYnabData
+from ynab_unlinked.ynab_api.client import Client
+
+MAX_PAST_TRANSACTIONS_SHOWN = 3
+
+
+def prompt_for_api_key() -> str:
+    return Prompt.ask("What is the API Key to connect to YNAB?", password=True)
+
+
+def prompt_for_budget() -> str:
+    if ensure_config():
+        client = Client(Config.load())
+    else:
+        api_key = prompt_for_api_key()
+        config = Config(api_key=api_key, budget_id="")
+        config.save()
+        client = Client(config)
+
+    with Status("Getting budgets..."):
+        budgets = client.budgets()
+
+    print("Available budgets:")
+    for idx, budget in enumerate(budgets):
+        print(f" - {idx + 1}. {budget.name}")
+
+    budget_num = Prompt.ask(
+        "What budget do you want to use? (By number)",
+        choices=[str(i) for i in range(1, len(budgets) + 1)],
+        show_choices=False,
+    )
+    budget = budgets[int(budget_num) - 1]
+
+    print(f"[bold]Selected budget: {budget.name}")
+    return budget.id
+
+
+def transaction_table(transactions: list[Transaction]):
+    columns = [
+        Column(header="Date", justify="left", max_width=10),
+        Column(header="Payee", justify="left", width=50),
+        Column(header="Inflow", justify="right", max_width=15),
+        Column(header="Outflow", justify="right", max_width=15),
+    ]
+    table = Table(
+        *columns,
+        title="Transactions to process",
+        caption=f"Only {MAX_PAST_TRANSACTIONS_SHOWN} processed transactions are shown.",
+        box=box.SIMPLE,
+    )
+
+    past_counter = 0
+    for transaction in transactions:
+        style = Style(color="gray37" if transaction.past else "default")
+
+        past_counter += int(transaction.past)
+        if past_counter == MAX_PAST_TRANSACTIONS_SHOWN:
+            # Stop adding transactions that are past after 5 for clarification
+            table.add_row("...", "...", "...", "...")
+            break
+
+        outflow = transaction.pretty_amount if transaction.amount < 0 else None
+        inflow = transaction.pretty_amount if transaction.amount > 0 else None
+
+        table.add_row(
+            transaction.date.strftime("%m/%d/%Y"),
+            transaction.payee,
+            inflow,
+            outflow,
+            style=style,
+        )
+
+    print(table)
+
+
+def payee_line(transaction: TransactionWithYnabData) -> str:
+    if (
+        transaction.ynab_payee is not None
+        and transaction.payee == transaction.ynab_payee
+    ):
+        return transaction.ynab_payee
+
+    return f"{transaction.ynab_payee} [gray37] [Original payee: {transaction.payee}][/gray37]"
+
+
+def updload_help_message(with_partial_matches=False) -> str:
+    main_message = (
+        "The table below shows the transactaions to be imported to YNAB. The transactions in the input file have been matched with existing transactions in YNAB.\n"
+        " - The [green]green[/] rows are new transactions to be imported.\n"
+    )
+    if with_partial_matches:
+        main_message += (
+            " - The [yellow]yellow[/] rows are transaction to be imported that match in date and amount with\n"
+            "   transations that exist in YNAB but for which teh payee name could not be matched.\n"
+            "   This is usually because the name from the import file is substantially different any payee present in YNAB.\n"
+            "   If you accept these transactions are valid, we will keep track of this naming for future imports."
+        )
+
+    main_message += (
+        "The cleared status column shows how the transaction will be loaded to YNAB, not the current "
+        "status if the transaction was already in YNAB."
+    )
+
+    return main_message
+
+
+def transactions_to_upload(transactions: list[TransactionWithYnabData]):
+    columns = [
+        Column(header="Match", justify="center", width=5),
+        Column(header="Date", justify="left", max_width=10),
+        Column(header="Payee", justify="left", width=70),
+        Column(header="Inflow", justify="right", max_width=15),
+        Column(header="Outflow", justify="right", max_width=15),
+        Column(header="Cleared Status", justify="left", width=15),
+    ]
+    table = Table(
+        *columns,
+        title="Recent Transactions",
+        caption="Transactions to [cyan bold]update[/] and [bold green]create[/].",
+        box=box.SIMPLE,
+    )
+
+    partial_matches = False
+    for transaction in transactions:
+        outflow = transaction.pretty_amount if transaction.amount < 0 else None
+        inflow = transaction.pretty_amount if transaction.amount > 0 else None
+
+        if transaction.needs_creation:
+            if transaction.match_status == MatchStatus.PARTIAL_MATCH:
+                style = "yellow"
+                partial_matches = True
+            else:
+                style = "green"
+        else:
+            style = "default"
+
+        table.add_row(
+            transaction.match_emoji,
+            transaction.date.strftime("%m/%d/%Y"),
+            payee_line(transaction),
+            inflow,
+            outflow,
+            transaction.cleared_status,
+            style=style,
+        )
+
+    print(Rule("Transactions to be imported"))
+    print(updload_help_message(partial_matches))
+    print(table)
+
+
+def partial_matches(transactions: list[TransactionWithYnabData]):
+    columns = [
+        Column(header="Date", justify="left", max_width=10),
+        Column(header="Payee", justify="left", width=50),
+        Column(header="Inflow", justify="right", max_width=15),
+        Column(header="Outflow", justify="right", max_width=15),
+        Column(header="Cleared Status", justify="left", width=15),
+    ]
+    table = Table(
+        *columns,
+        title="Partial Matches",
+        caption="Each pair of transactions shows the imported transaction (top) and the \npartial match in YNAB (bottom).",
+        box=box.SIMPLE,
+        row_styles=["", "gray70"],
+    )
+
+    for transaction in transactions:
+        # If we do not need to import it, skip it
+        if not transaction.needs_creation:
+            continue
+
+        # Skip if no partial match
+        if (
+            transaction.match_status != MatchStatus.PARTIAL_MATCH
+            or transaction.partial_match is None
+        ):
+            continue
+
+        # Original transaction row
+        orig_outflow = transaction.pretty_amount if transaction.amount < 0 else None
+        orig_inflow = transaction.pretty_amount if transaction.amount > 0 else None
+
+        # YNAB transaction row (from partial_match)
+        ynab_amount = transaction.partial_match.amount / 1000
+        ynab_pretty_amount = f"{ynab_amount:.2f}€"
+        ynab_outflow = ynab_pretty_amount if ynab_amount < 0 else None
+        ynab_inflow = ynab_pretty_amount if ynab_amount > 0 else None
+
+        # Add the pair of rows
+        table.add_row(
+            transaction.date.strftime("%m/%d/%Y"),
+            transaction.payee,
+            orig_inflow,
+            orig_outflow,
+            "",
+        )
+
+        table.add_row(
+            transaction.partial_match.var_date.strftime("%m/%d/%Y"),
+            transaction.partial_match.payee_name or "",
+            ynab_inflow,
+            ynab_outflow,
+            transaction.partial_match.cleared.name.capitalize(),
+            end_section=True,
+        )
+
+    print(table)

ynab_unlinked-0.0.2/src/ynab_unlinked/entities/__init__.py

@@ -0,0 +1,12 @@
+from enum import StrEnum
+
+from ._protocol import Entity
+
+
+class InputType(StrEnum):
+    TXT = "txt"
+    CSV = "csv"
+    HTML = "html"
+
+
+__all__ = ["Entity", "InputType"]