freeagent-cli 0.2.1__tar.gz → 0.6.0__tar.gz

freeagent_cli-0.6.0/.github/workflows/ci.yml

@@ -0,0 +1,77 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  # Deliberately unfiltered: PRs are sometimes stacked on another feature
+  # branch rather than main, and those need checking too.
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      # Rules and version both come from pyproject.toml, so a ruff release
+      # can't change what CI enforces without a deliberate bump.
+      - name: Ruff
+        run: uv run --no-sync ruff check --output-format=github .
+
+  test:
+    name: tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Matches requires-python and the classifiers in pyproject.toml.
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+
+      # --locked fails if uv.lock has drifted from pyproject.toml, so a
+      # dependency change that wasn't re-locked is caught here rather than
+      # by whoever installs the tool next.
+      - name: Install dependencies
+        run: uv sync --locked --python ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run --no-sync pytest -q
+
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      # The console script is the whole product, so check it actually runs
+      # from the built wheel. Catches packaging mistakes tests can't see.
+      - name: Smoke-test the built wheel
+        run: uv run --no-project --with dist/*.whl freeagent-cli --help

freeagent_cli-0.6.0/.github/workflows/workflow.yml

@@ -0,0 +1,74 @@
+name: Release
+
+# Filename matters: PyPI trusted publishing matches the workflow file by name,
+# so this must stay `workflow.yml` to match the publisher configured on PyPI.
+# Renaming it breaks publishing until the PyPI side is updated to match.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: build and verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      # A tag that disagrees with pyproject.toml would publish a version nobody
+      # asked for, and PyPI version numbers cannot be reused. Fail loudly first.
+      - name: Check the tag matches the packaged version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          packaged=$(uv run --no-sync python -c \
+            "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "tag=$tag packaged=$packaged"
+          if [ "$tag" != "$packaged" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME implies $tag but pyproject.toml says $packaged"
+            exit 1
+          fi
+
+      - name: Ruff
+        run: uv run --no-sync ruff check --output-format=github .
+
+      - name: Run tests
+        run: uv run --no-sync pytest -q
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Smoke-test the built wheel
+        run: uv run --no-project --with dist/*.whl freeagent-cli --help
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # OIDC: the short-lived credential is minted here, so no PyPI token is
+    # stored anywhere. Nothing else in this job may need write access.
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@v1.14.1

freeagent_cli-0.6.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: freeagent-cli
+Version: 0.6.0
+Summary: CLI for submitting FreeAgent timeslips
+Project-URL: Homepage, https://github.com/tomdyson/freeagent-cli
+Project-URL: Repository, https://github.com/tomdyson/freeagent-cli
+Project-URL: Issues, https://github.com/tomdyson/freeagent-cli/issues
+Author-email: Tom Dyson <tom@naive.co.uk>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,freeagent,timeslip,timetracking
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.0
+Description-Content-Type: text/markdown
+
+# freeagent-cli
+
+[![CI](https://github.com/tomdyson/freeagent-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/tomdyson/freeagent-cli/actions/workflows/ci.yml)
+
+A small CLI for submitting FreeAgent timeslips without clicking through the web UI.
+
+```
+freeagent-cli log acme 1h30m "fixed the thing"
+```
+
+## Install
+
+```
+uv tool install freeagent-cli
+```
+
+## One-time setup
+
+You'll need to register your own OAuth app with FreeAgent. It takes about two minutes and keeps your data and rate limits separate from everyone else's.
+
+1. Go to <https://dev.freeagent.com/apps> and create a new app.
+2. Set the redirect URI to: `http://localhost:7878/callback`
+3. Note the **OAuth identifier** and **OAuth secret**.
+4. Save them locally:
+
+   ```
+   freeagent-cli auth init --client-id <id> --client-secret <secret>
+   ```
+
+   Add `--sandbox` if you want to test against the FreeAgent sandbox first.
+5. Authorise the app in your browser:
+
+   ```
+   freeagent-cli auth login
+   ```
+
+   A browser tab opens, you approve, and the CLI captures the refresh token. The refresh token lasts ~20 years; access tokens auto-refresh on every command.
+
+Credentials are stored at `~/Library/Application Support/freeagent-cli/config.json` (macOS) or the equivalent platform config directory, with file mode `0600`.
+
+## Usage
+
+```
+freeagent-cli --help                                       # canonical flow
+freeagent-cli recent                                       # what you've already logged (run this first to avoid duplicates)
+freeagent-cli log <project> <duration> [comment...]        # submit a timeslip
+freeagent-cli projects                                     # first-time / discovery: projects + tasks in one call
+freeagent-cli accounts                                     # bank accounts + balances
+freeagent-cli unexplained                                  # bank transactions still needing an explanation
+```
+
+Examples:
+
+```
+freeagent-cli log Acme 1h30m "fixed the thing"
+freeagent-cli log Acme 90m fixed the thing                 # comment without quotes
+freeagent-cli log "Big Co" 1.5 --task Coding --date 2026-05-01
+freeagent-cli log Acme 1.5 --dry-run                       # preview, don't submit
+```
+
+- **Duration** accepts `1.5`, `90m`, `1h30m`, or `1:30`.
+- **Project / task** match by case-insensitive name substring, numeric id, or full URL.
+- **`--task`** is optional when the project has a single task; otherwise the error lists the choices.
+- **`--date`** defaults to today (ISO `YYYY-MM-DD` to override).
+- **`--dry-run`** resolves the project/task/date and prints the would-be submission without sending it.
+- **`projects --flat`** emits one project/task pair per line (tab-separated) for grep/awk.
+
+## Banking
+
+```
+freeagent-cli accounts                                     # id, name, currency, balance
+freeagent-cli unexplained                                  # what still needs explaining
+freeagent-cli unexplained --account Current --days 365
+freeagent-cli unexplained -n 0 | grep -i stripe            # the whole backlog, filtered
+```
+
+`unexplained` prints one tab-separated transaction per line — date, unexplained amount, description, count of similar transactions, marker, URL — most recent first. The marker reads `partial` when only part of a transaction has been explained.
+
+- **`--account`** is optional if you have a single active bank account; otherwise the error lists the choices. Matches by name substring, id, or URL, like `--project`.
+- **`--days`** defaults to 90. Pass `0` for no date limit.
+- **`-n`** defaults to 25. Pass `0` for all.
+- A summary (count and total) goes to **stderr**, so piping stdout into `grep`/`awk` stays clean.
+
+Hidden accounts are left out of `accounts` unless you pass `--all`, and are never picked as the implicit default for `unexplained`. Naming one explicitly with `--account` still works.
+
+### Explaining transactions
+
+```
+freeagent-cli categories --search travel                   # find a category
+freeagent-cli explain 12345 285 --dry-run                  # preview
+freeagent-cli explain 12345 285 --description "train fare" # submit
+freeagent-cli explain 12345 285 --amount 20                # explain part of it
+```
+
+`categories` lists nominal code, group and description, one per line. Filter with `--search` or `--group` (`admin_expenses`, `cost_of_sales`, `income`, `general`).
+
+- **CATEGORY** matches by nominal code (`285`), full URL, or case-insensitive description substring. An ambiguous match lists the candidates with their codes.
+- **`--like <transaction>`** reuses the category from a transaction you've already explained, instead of naming one. See below.
+- **`--amount`** explains part of a transaction; it defaults to the whole unexplained amount and can't exceed it. Currency symbols and commas are ignored.
+- **The sign always comes from the transaction**, so `--amount 20` on a payment of `-42.50` explains `-20.00`. You can't accidentally book a spend as income.
+- **`--date`** defaults to the transaction's own date.
+- **`--dry-run`** previews; otherwise you're asked to confirm. `-y` skips the prompt.
+
+**VAT:** `explain` doesn't set sales-tax fields, so FreeAgent applies the category's automatic rate. If a transaction needs a non-standard rate, EC status, or a manual VAT amount, do that one in the web UI.
+
+### Recurring payees
+
+Most of a backlog is the same handful of payees every month. `--like` copies the category from a transaction you've already explained, so you don't have to remember which one it was:
+
+```
+freeagent-cli explain 12345 --like 9999
+```
+
+The `similar` column in `unexplained` (from `matching_transactions_count`) tells you when a transaction has precedent worth copying.
+
+`--like` reads the category and nothing else — the amount, date and description still come from the transaction being explained, or from your flags. It refuses rather than guesses when there's no single answer:
+
+- The source has no category — invoice payments, bill payments and transfers aren't categorised.
+- The source is split across several categories, in which case the error lists them so you can pick one.
+
+A typical backlog session:
+
+```
+freeagent-cli unexplained
+freeagent-cli explain 12345 285 --description "client dinner"
+freeagent-cli explain 12346 --like 12345
+```
+
+## License
+
+MIT

freeagent_cli-0.6.0/README.md

@@ -0,0 +1,131 @@
+# freeagent-cli
+
+[![CI](https://github.com/tomdyson/freeagent-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/tomdyson/freeagent-cli/actions/workflows/ci.yml)
+
+A small CLI for submitting FreeAgent timeslips without clicking through the web UI.
+
+```
+freeagent-cli log acme 1h30m "fixed the thing"
+```
+
+## Install
+
+```
+uv tool install freeagent-cli
+```
+
+## One-time setup
+
+You'll need to register your own OAuth app with FreeAgent. It takes about two minutes and keeps your data and rate limits separate from everyone else's.
+
+1. Go to <https://dev.freeagent.com/apps> and create a new app.
+2. Set the redirect URI to: `http://localhost:7878/callback`
+3. Note the **OAuth identifier** and **OAuth secret**.
+4. Save them locally:
+
+   ```
+   freeagent-cli auth init --client-id <id> --client-secret <secret>
+   ```
+
+   Add `--sandbox` if you want to test against the FreeAgent sandbox first.
+5. Authorise the app in your browser:
+
+   ```
+   freeagent-cli auth login
+   ```
+
+   A browser tab opens, you approve, and the CLI captures the refresh token. The refresh token lasts ~20 years; access tokens auto-refresh on every command.
+
+Credentials are stored at `~/Library/Application Support/freeagent-cli/config.json` (macOS) or the equivalent platform config directory, with file mode `0600`.
+
+## Usage
+
+```
+freeagent-cli --help                                       # canonical flow
+freeagent-cli recent                                       # what you've already logged (run this first to avoid duplicates)
+freeagent-cli log <project> <duration> [comment...]        # submit a timeslip
+freeagent-cli projects                                     # first-time / discovery: projects + tasks in one call
+freeagent-cli accounts                                     # bank accounts + balances
+freeagent-cli unexplained                                  # bank transactions still needing an explanation
+```
+
+Examples:
+
+```
+freeagent-cli log Acme 1h30m "fixed the thing"
+freeagent-cli log Acme 90m fixed the thing                 # comment without quotes
+freeagent-cli log "Big Co" 1.5 --task Coding --date 2026-05-01
+freeagent-cli log Acme 1.5 --dry-run                       # preview, don't submit
+```
+
+- **Duration** accepts `1.5`, `90m`, `1h30m`, or `1:30`.
+- **Project / task** match by case-insensitive name substring, numeric id, or full URL.
+- **`--task`** is optional when the project has a single task; otherwise the error lists the choices.
+- **`--date`** defaults to today (ISO `YYYY-MM-DD` to override).
+- **`--dry-run`** resolves the project/task/date and prints the would-be submission without sending it.
+- **`projects --flat`** emits one project/task pair per line (tab-separated) for grep/awk.
+
+## Banking
+
+```
+freeagent-cli accounts                                     # id, name, currency, balance
+freeagent-cli unexplained                                  # what still needs explaining
+freeagent-cli unexplained --account Current --days 365
+freeagent-cli unexplained -n 0 | grep -i stripe            # the whole backlog, filtered
+```
+
+`unexplained` prints one tab-separated transaction per line — date, unexplained amount, description, count of similar transactions, marker, URL — most recent first. The marker reads `partial` when only part of a transaction has been explained.
+
+- **`--account`** is optional if you have a single active bank account; otherwise the error lists the choices. Matches by name substring, id, or URL, like `--project`.
+- **`--days`** defaults to 90. Pass `0` for no date limit.
+- **`-n`** defaults to 25. Pass `0` for all.
+- A summary (count and total) goes to **stderr**, so piping stdout into `grep`/`awk` stays clean.
+
+Hidden accounts are left out of `accounts` unless you pass `--all`, and are never picked as the implicit default for `unexplained`. Naming one explicitly with `--account` still works.
+
+### Explaining transactions
+
+```
+freeagent-cli categories --search travel                   # find a category
+freeagent-cli explain 12345 285 --dry-run                  # preview
+freeagent-cli explain 12345 285 --description "train fare" # submit
+freeagent-cli explain 12345 285 --amount 20                # explain part of it
+```
+
+`categories` lists nominal code, group and description, one per line. Filter with `--search` or `--group` (`admin_expenses`, `cost_of_sales`, `income`, `general`).
+
+- **CATEGORY** matches by nominal code (`285`), full URL, or case-insensitive description substring. An ambiguous match lists the candidates with their codes.
+- **`--like <transaction>`** reuses the category from a transaction you've already explained, instead of naming one. See below.
+- **`--amount`** explains part of a transaction; it defaults to the whole unexplained amount and can't exceed it. Currency symbols and commas are ignored.
+- **The sign always comes from the transaction**, so `--amount 20` on a payment of `-42.50` explains `-20.00`. You can't accidentally book a spend as income.
+- **`--date`** defaults to the transaction's own date.
+- **`--dry-run`** previews; otherwise you're asked to confirm. `-y` skips the prompt.
+
+**VAT:** `explain` doesn't set sales-tax fields, so FreeAgent applies the category's automatic rate. If a transaction needs a non-standard rate, EC status, or a manual VAT amount, do that one in the web UI.
+
+### Recurring payees
+
+Most of a backlog is the same handful of payees every month. `--like` copies the category from a transaction you've already explained, so you don't have to remember which one it was:
+
+```
+freeagent-cli explain 12345 --like 9999
+```
+
+The `similar` column in `unexplained` (from `matching_transactions_count`) tells you when a transaction has precedent worth copying.
+
+`--like` reads the category and nothing else — the amount, date and description still come from the transaction being explained, or from your flags. It refuses rather than guesses when there's no single answer:
+
+- The source has no category — invoice payments, bill payments and transfers aren't categorised.
+- The source is split across several categories, in which case the error lists them so you can pick one.
+
+A typical backlog session:
+
+```
+freeagent-cli unexplained
+freeagent-cli explain 12345 285 --description "client dinner"
+freeagent-cli explain 12346 --like 12345
+```
+
+## License
+
+MIT

{freeagent_cli-0.2.1 → freeagent_cli-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "freeagent-cli"
-version = "0.2.1"
+version = "0.6.0"
 description = "CLI for submitting FreeAgent timeslips"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -40,3 +40,29 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/freeagent_cli"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "ruff>=0.14",
+]
+
+[tool.ruff]
+# Wide enough for the existing tab-separated click.echo lines and help epilogs,
+# which read worse wrapped than long.
+line-length = 110
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "N", "RUF"]
+ignore = [
+    # `date.today()` is correct here. Timeslips and bank transactions are dated
+    # in the user's local day; a tz-aware UTC date would file work on the wrong
+    # day either side of midnight. Kept out of `select` rather than noqa'd at
+    # each of the three call sites.
+    "DTZ011",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests lean on long inline fixtures where wrapping hurts more than it helps.
+"tests/*" = ["E501"]

freeagent_cli-0.6.0/src/freeagent_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.6.0"

freeagent_cli-0.6.0/src/freeagent_cli/api.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import httpx
+
+from . import __version__, auth
+from . import config as cfg
+
+#: FreeAgent caps per_page at 100; asking for the maximum keeps round trips down.
+PER_PAGE = 100
+
+#: Safety valve so a runaway Link chain can't loop forever. 100 pages = 10,000 records.
+MAX_PAGES = 100
+
+
+class FreeAgent:
+    def __init__(self, c: cfg.Config):
+        self.cfg = c
+
+    def _client(self) -> httpx.Client:
+        return httpx.Client(
+            base_url=self.cfg.api_base,
+            headers={
+                "Authorization": f"Bearer {auth.access_token(self.cfg)}",
+                "Accept": "application/json",
+                "User-Agent": f"freeagent-cli/{__version__}",
+            },
+            timeout=30,
+        )
+
+    def get(self, path: str, **params) -> dict:
+        with self._client() as c:
+            r = c.get(path, params=params)
+            r.raise_for_status()
+            return r.json()
+
+    def get_all(self, path: str, key: str, **params) -> list[dict]:
+        """GET a list endpoint, following `Link: rel="next"` until exhausted.
+
+        FreeAgent returns 25 records per page by default, so anything that reads a
+        single response silently truncates. Params with a value of None are dropped.
+        """
+        query = {k: v for k, v in params.items() if v is not None}
+        query.setdefault("per_page", PER_PAGE)
+        items: list[dict] = []
+        with self._client() as c:
+            url = path
+            # Only the first request needs params; each `next` URL carries its own.
+            request_params: dict | None = query
+            for _ in range(MAX_PAGES):
+                r = c.get(url, params=request_params)
+                r.raise_for_status()
+                items.extend(r.json().get(key, []))
+                next_link = r.links.get("next")
+                if not next_link:
+                    return items
+                url = next_link["url"]
+                request_params = None
+        raise RuntimeError(
+            f"Stopped after {MAX_PAGES} pages of {path}; narrow the date range."
+        )
+
+    def post(self, path: str, json_body: dict) -> dict:
+        with self._client() as c:
+            r = c.post(path, json=json_body)
+            if r.status_code >= 400:
+                raise httpx.HTTPStatusError(
+                    f"{r.status_code} {r.reason_phrase}: {r.text}",
+                    request=r.request, response=r,
+                )
+            return r.json()
+
+    def me(self) -> dict:
+        return self.get("/v2/users/me")["user"]
+
+    def projects(self, view: str = "active") -> list[dict]:
+        return self.get_all("/v2/projects", "projects", view=view)
+
+    def tasks(self, project_url: str) -> list[dict]:
+        return self.get_all("/v2/tasks", "tasks", project=project_url)
+
+    def list_timeslips(self, *, from_date: str, to_date: str | None = None,
+                       user: str | None = None, nested: bool = False) -> list[dict]:
+        return self.get_all(
+            "/v2/timeslips", "timeslips",
+            from_date=from_date, to_date=to_date, user=user,
+            nested="true" if nested else None,
+        )
+
+    def create_timeslip(self, *, user: str, project: str, task: str,
+                        dated_on: str, hours: float, comment: str | None = None) -> dict:
+        body: dict = {
+            "timeslip": {
+                "user": user,
+                "project": project,
+                "task": task,
+                "dated_on": dated_on,
+                "hours": str(hours),
+            }
+        }
+        if comment:
+            body["timeslip"]["comment"] = comment
+        return self.post("/v2/timeslips", body)
+
+    # -- banking ---------------------------------------------------------
+
+    def bank_accounts(self, view: str | None = None) -> list[dict]:
+        return self.get_all("/v2/bank_accounts", "bank_accounts", view=view)
+
+    def bank_transactions(self, *, bank_account: str, view: str = "all",
+                          from_date: str | None = None,
+                          to_date: str | None = None) -> list[dict]:
+        """List transactions for one account. `bank_account` is required by the API."""
+        return self.get_all(
+            "/v2/bank_transactions", "bank_transactions",
+            bank_account=bank_account, view=view,
+            from_date=from_date, to_date=to_date,
+        )
+
+    def bank_transaction(self, txn_id: str) -> dict:
+        return self.get(f"/v2/bank_transactions/{txn_id}")["bank_transaction"]
+
+    def categories(self) -> list[dict]:
+        """Flatten the four parallel category arrays into one list.
+
+        The API groups categories into `admin_expenses_categories`,
+        `cost_of_sales_categories`, `income_categories` and `general_categories`.
+        Each entry is tagged with the group it came from. Note that categories
+        name themselves with `description`, not `name`, and are keyed by nominal
+        code — which can carry a leading zero, e.g. "001".
+        """
+        data = self.get("/v2/categories", per_page=PER_PAGE)
+        out: list[dict] = []
+        for group, items in data.items():
+            if not group.endswith("_categories") or not isinstance(items, list):
+                continue
+            label = group[: -len("_categories")]
+            out.extend({**c, "group": label} for c in items)
+        return out
+
+    def explanation(self, exp_id: str) -> dict:
+        return self.get(
+            f"/v2/bank_transaction_explanations/{exp_id}"
+        )["bank_transaction_explanation"]
+
+    def create_explanation(self, *, bank_transaction: str, dated_on: str,
+                           gross_value: str, category: str,
+                           description: str | None = None) -> dict:
+        """Explain (part of) a bank transaction against a category.
+
+        Sales-tax fields are deliberately omitted so FreeAgent applies the
+        category's automatic rate rather than this CLI guessing at VAT.
+        """
+        body: dict = {
+            "bank_transaction_explanation": {
+                "bank_transaction": bank_transaction,
+                "dated_on": dated_on,
+                "gross_value": gross_value,
+                "category": category,
+            }
+        }
+        if description:
+            body["bank_transaction_explanation"]["description"] = description
+        return self.post("/v2/bank_transaction_explanations", body)
+
+    def delete(self, path: str) -> dict:
+        with self._client() as c:
+            r = c.delete(path)
+            r.raise_for_status()
+            return r.json()
+
+    def delete_timeslip(self, timeslip_id: str) -> dict:
+        try:
+            return self.delete(f"/v2/timeslips/{timeslip_id}")
+        except httpx.HTTPStatusError as e:
+            if e.response.status_code == 404:
+                return {"deleted": True, "id": timeslip_id, "already_deleted": True}
+            raise
+
+    def get_timeslip(self, timeslip_id: str) -> dict:
+        return self.get(f"/v2/timeslips/{timeslip_id}", nested="true")["timeslip"]

{freeagent_cli-0.2.1 → freeagent_cli-0.6.0}/src/freeagent_cli/auth.py

@@ -4,6 +4,7 @@ import secrets
 import time
 import webbrowser
 from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import ClassVar
 from urllib.parse import parse_qs, urlencode, urlparse
 
 import httpx
@@ -20,9 +21,11 @@ def _authorize_url(c: cfg.Config) -> str:
 
 
 class _Handler(BaseHTTPRequestHandler):
-    received: dict[str, str] = {}
+    # Shared on the class on purpose: HTTPServer instantiates a new handler per
+    # request, so this is how the callback hands the result back to login().
+    received: ClassVar[dict[str, str]] = {}
 
-    def do_GET(self):  # noqa: N802
+    def do_GET(self):
         parsed = urlparse(self.path)
         if parsed.path != "/callback":
             self.send_response(404)