costcrunch 0.1.0__tar.gz

costcrunch-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv venv -p ${{ matrix.python }} && uv pip install -e '.[dev]'
+      - run: .venv/bin/ruff check src tests
+      - run: .venv/bin/pytest -q
+      - run: .venv/bin/cost --help >/dev/null

costcrunch-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+# Publishes to PyPI when a version tag is pushed:  git tag v0.1.0 && git push origin v0.1.0
+# Uses PyPI trusted publishing (no token stored anywhere): the pending publisher on pypi.org names
+# this repo, this workflow file and the `pypi` environment.
+name: release
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv venv && uv pip install -e '.[dev]'
+      - run: .venv/bin/ruff check src tests && .venv/bin/pytest -q
+      - name: Tag matches the package version
+        run: |
+          version=$(.venv/bin/python -c 'import costcrunch; print(costcrunch.__version__)')
+          test "v$version" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME != version $version"; exit 1; }
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

costcrunch-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

costcrunch-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CostCrunch
+
+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.

costcrunch-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: costcrunch
+Version: 0.1.0
+Summary: CostCrunch from Python, your terminal, and AI assistants (MCP).
+Project-URL: Homepage, https://costcrunch.ai
+Project-URL: Documentation, https://support.costcrunch.ai
+Author-email: CostCrunch <support@costcrunch.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,construction,costcrunch,invoices,mcp,procurement
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CostCrunch for Python, the terminal and AI assistants
+
+One package, three ways in to your CostCrunch data:
+
+| | |
+|---|---|
+| **CLI** | `cost documents list --status needs_attention` |
+| **Python** | `CostCrunch().materials.history(material_id)` |
+| **MCP** | Ask Claude, Cursor or any MCP client *"what did we pay for 5/8 sheetrock last month, and is that a good price?"* |
+
+All three are generated from the same list of operations, so they always match. Everything is
+read-only and scoped to your company: you see exactly what you see in the CostCrunch app.
+
+## Install
+
+```sh
+uv tool install costcrunch          # or: pipx install costcrunch
+cost auth login
+```
+
+This opens your browser to sign in with Google. For an email + password account, use
+`cost auth login --email you@company.com`. Your session is stored in `~/.config/costcrunch/credentials.json`,
+readable only by you. `cost auth logout` removes it.
+
+Or use an **API key**: create one in CostCrunch under **Settings › Connections › API**, then
+`cost auth login --api-key` (it asks for the key), or set `COSTCRUNCH_API_KEY`. A key belongs to
+one company, can only read, and works until you revoke it on that page.
+
+If you belong to more than one company: `cost account orgs`, then
+`cost account use-org <id>` (or pass `--org <id>` to any command).
+
+## CLI
+
+```sh
+cost search all "tri-state"                        # anything: documents, suppliers, materials...
+cost documents list --type invoice --since 2026-10-01
+cost documents get <document-id>                   # header + line items + price checks
+cost suppliers list
+cost suppliers materials <supplier-id> --search sheetrock
+cost projects get <project-id>                     # spend by supplier, month, cost type
+cost materials find "5/8 sheetrock"                # by meaning, not just words
+cost materials history <material-id> --since 2026-01-01
+cost materials prices <material-id>                # your history vs other suppliers vs online
+cost spend monthly
+```
+
+Add `--json` to any command for machine-readable output, or `--csv` on list commands for a
+spreadsheet: `cost --csv suppliers list > suppliers.csv`. `cost <group> --help`
+lists every command and option.
+
+## Python
+
+```python
+from costcrunch import CostCrunch
+
+cc = CostCrunch()                                   # your `cost auth login`, or COSTCRUNCH_API_KEY
+# cc = CostCrunch(api_key="cc_live_...")            # or pass a key from Settings › API
+for d in cc.documents.list(status="needs_attention")["items"]:
+    print(d["date"], d["supplier"], d["total"], d["url"])
+
+sheetrock = cc.materials.find("5/8 sheetrock")["items"][0]
+history = cc.materials.history(sheetrock["id"], since="2026-01-01")
+print(history["summary"]["avg_price_per_unit"], history["summary"]["unit"])
+```
+
+For scripts and CI, use an API key (`COSTCRUNCH_API_KEY`) instead of signing in.
+Errors raise `costcrunch.ApiError` (with `.status`, `.code`, `.message`), `NotFound`,
+`PermissionDenied` or `AuthError`.
+
+## AI assistants (MCP)
+
+The quickest setup is in CostCrunch under **Settings › Connections › API**: create a key and copy
+the ready-made command for Claude Code, Claude Desktop or Cursor. They run the server with
+[uv](https://docs.astral.sh/uv/), so there's nothing to install first:
+
+```sh
+claude mcp add costcrunch --env COSTCRUNCH_API_KEY=cc_live_... -- uvx --from costcrunch cost mcp
+```
+
+If you've installed the CLI and signed in, it can print the setup for your own sign-in instead:
+
+```sh
+cost mcp setup claude-code                         # prints: claude mcp add costcrunch -- /path/to/cost mcp
+cost mcp setup claude-desktop                      # prints the JSON for claude_desktop_config.json
+cost mcp setup cursor
+```
+
+The server runs on your computer (`cost mcp`, over stdio), as you or as your API key. It exposes 20
+read-only tools such as `search_all`, `documents_list`, `materials_find`, `materials_history`,
+`materials_prices`, `projects_get` and `spend_monthly`, and every result carries a link back
+into the CostCrunch app.
+
+## Security
+
+* You sign in as yourself. The API decides which company's data you can see from your
+  membership; the `--org` option only chooses between companies you already belong to.
+* This package can't change anything: there are no write operations in this version, and the
+  API refuses anything but reads from an API key.
+* Only a hash of each API key is stored by CostCrunch; the key is shown once. Revoking it in
+  Settings › Connections › API stops it within a minute.
+* Tokens are stored with `0600` permissions and refreshed automatically. The public Supabase
+  key embedded in the package is the same one the web app ships with.
+
+## Developing
+
+```sh
+uv venv && uv pip install -e '.[dev]'
+pytest && ruff check src tests
+```
+
+Each operation lives in `src/costcrunch/ops/<group>.py`:
+
+```python
+@op("suppliers", "get")
+def get_supplier(api, supplier_id: Annotated[str, Arg("Supplier id", positional=True)]):
+    """Get one supplier: spend, branches and sales rep."""
+    return pick(api.get(f"/suppliers/{supplier_id}")["supplier"], {...})
+```
+
+That one function becomes `cc.suppliers.get(...)`, `cost suppliers get <id>` and the MCP
+tool `suppliers_get`. The docstring is the help text and tool description. Its first sentence
+is the short summary, so write it for a customer. Results are reshaped with `pick` so internal
+fields (storage paths, bounding boxes, flags) never leak out and the output doesn't change when
+the web app's payloads do. `tests/test_registry.py` enforces the conventions.
+
+Writes are supported by the registry (`@op(..., write=True)`). The CLI asks for confirmation
+(or `--yes`), Python needs `confirm=True`, and the MCP tool requires a verbatim
+`user_confirmation`. None are exposed yet.

costcrunch-0.1.0/README.md

@@ -0,0 +1,128 @@
+# CostCrunch for Python, the terminal and AI assistants
+
+One package, three ways in to your CostCrunch data:
+
+| | |
+|---|---|
+| **CLI** | `cost documents list --status needs_attention` |
+| **Python** | `CostCrunch().materials.history(material_id)` |
+| **MCP** | Ask Claude, Cursor or any MCP client *"what did we pay for 5/8 sheetrock last month, and is that a good price?"* |
+
+All three are generated from the same list of operations, so they always match. Everything is
+read-only and scoped to your company: you see exactly what you see in the CostCrunch app.
+
+## Install
+
+```sh
+uv tool install costcrunch          # or: pipx install costcrunch
+cost auth login
+```
+
+This opens your browser to sign in with Google. For an email + password account, use
+`cost auth login --email you@company.com`. Your session is stored in `~/.config/costcrunch/credentials.json`,
+readable only by you. `cost auth logout` removes it.
+
+Or use an **API key**: create one in CostCrunch under **Settings › Connections › API**, then
+`cost auth login --api-key` (it asks for the key), or set `COSTCRUNCH_API_KEY`. A key belongs to
+one company, can only read, and works until you revoke it on that page.
+
+If you belong to more than one company: `cost account orgs`, then
+`cost account use-org <id>` (or pass `--org <id>` to any command).
+
+## CLI
+
+```sh
+cost search all "tri-state"                        # anything: documents, suppliers, materials...
+cost documents list --type invoice --since 2026-10-01
+cost documents get <document-id>                   # header + line items + price checks
+cost suppliers list
+cost suppliers materials <supplier-id> --search sheetrock
+cost projects get <project-id>                     # spend by supplier, month, cost type
+cost materials find "5/8 sheetrock"                # by meaning, not just words
+cost materials history <material-id> --since 2026-01-01
+cost materials prices <material-id>                # your history vs other suppliers vs online
+cost spend monthly
+```
+
+Add `--json` to any command for machine-readable output, or `--csv` on list commands for a
+spreadsheet: `cost --csv suppliers list > suppliers.csv`. `cost <group> --help`
+lists every command and option.
+
+## Python
+
+```python
+from costcrunch import CostCrunch
+
+cc = CostCrunch()                                   # your `cost auth login`, or COSTCRUNCH_API_KEY
+# cc = CostCrunch(api_key="cc_live_...")            # or pass a key from Settings › API
+for d in cc.documents.list(status="needs_attention")["items"]:
+    print(d["date"], d["supplier"], d["total"], d["url"])
+
+sheetrock = cc.materials.find("5/8 sheetrock")["items"][0]
+history = cc.materials.history(sheetrock["id"], since="2026-01-01")
+print(history["summary"]["avg_price_per_unit"], history["summary"]["unit"])
+```
+
+For scripts and CI, use an API key (`COSTCRUNCH_API_KEY`) instead of signing in.
+Errors raise `costcrunch.ApiError` (with `.status`, `.code`, `.message`), `NotFound`,
+`PermissionDenied` or `AuthError`.
+
+## AI assistants (MCP)
+
+The quickest setup is in CostCrunch under **Settings › Connections › API**: create a key and copy
+the ready-made command for Claude Code, Claude Desktop or Cursor. They run the server with
+[uv](https://docs.astral.sh/uv/), so there's nothing to install first:
+
+```sh
+claude mcp add costcrunch --env COSTCRUNCH_API_KEY=cc_live_... -- uvx --from costcrunch cost mcp
+```
+
+If you've installed the CLI and signed in, it can print the setup for your own sign-in instead:
+
+```sh
+cost mcp setup claude-code                         # prints: claude mcp add costcrunch -- /path/to/cost mcp
+cost mcp setup claude-desktop                      # prints the JSON for claude_desktop_config.json
+cost mcp setup cursor
+```
+
+The server runs on your computer (`cost mcp`, over stdio), as you or as your API key. It exposes 20
+read-only tools such as `search_all`, `documents_list`, `materials_find`, `materials_history`,
+`materials_prices`, `projects_get` and `spend_monthly`, and every result carries a link back
+into the CostCrunch app.
+
+## Security
+
+* You sign in as yourself. The API decides which company's data you can see from your
+  membership; the `--org` option only chooses between companies you already belong to.
+* This package can't change anything: there are no write operations in this version, and the
+  API refuses anything but reads from an API key.
+* Only a hash of each API key is stored by CostCrunch; the key is shown once. Revoking it in
+  Settings › Connections › API stops it within a minute.
+* Tokens are stored with `0600` permissions and refreshed automatically. The public Supabase
+  key embedded in the package is the same one the web app ships with.
+
+## Developing
+
+```sh
+uv venv && uv pip install -e '.[dev]'
+pytest && ruff check src tests
+```
+
+Each operation lives in `src/costcrunch/ops/<group>.py`:
+
+```python
+@op("suppliers", "get")
+def get_supplier(api, supplier_id: Annotated[str, Arg("Supplier id", positional=True)]):
+    """Get one supplier: spend, branches and sales rep."""
+    return pick(api.get(f"/suppliers/{supplier_id}")["supplier"], {...})
+```
+
+That one function becomes `cc.suppliers.get(...)`, `cost suppliers get <id>` and the MCP
+tool `suppliers_get`. The docstring is the help text and tool description. Its first sentence
+is the short summary, so write it for a customer. Results are reshaped with `pick` so internal
+fields (storage paths, bounding boxes, flags) never leak out and the output doesn't change when
+the web app's payloads do. `tests/test_registry.py` enforces the conventions.
+
+Writes are supported by the registry (`@op(..., write=True)`). The CLI asks for confirmation
+(or `--yes`), Python needs `confirm=True`, and the MCP tool requires a verbatim
+`user_confirmation`. None are exposed yet.

costcrunch-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "costcrunch"
+description = "CostCrunch from Python, your terminal, and AI assistants (MCP)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "CostCrunch", email = "support@costcrunch.ai" }]
+dynamic = ["version"]
+keywords = ["costcrunch", "construction", "invoices", "procurement", "mcp", "cli"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "typer>=0.12",
+  "rich>=13",
+  "mcp>=2.3,<3",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[project.scripts]
+cost = "costcrunch.cli:main"
+
+[project.urls]
+Homepage = "https://costcrunch.ai"
+Documentation = "https://support.costcrunch.ai"
+
+[tool.hatch.version]
+path = "src/costcrunch/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/costcrunch"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py310"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "B", "I"]
+ignore = ["B008"]

costcrunch-0.1.0/src/costcrunch/__init__.py

@@ -0,0 +1,7 @@
+"""CostCrunch: your construction purchasing data from Python, the terminal, or an AI assistant."""
+from costcrunch._version import __version__
+from costcrunch.client import CostCrunch
+from costcrunch.errors import ApiError, AuthError, CostCrunchError, NotFound, PermissionDenied, UsageError
+
+__all__ = ["CostCrunch", "ApiError", "AuthError", "CostCrunchError", "NotFound",
+           "PermissionDenied", "UsageError", "__version__"]

costcrunch-0.1.0/src/costcrunch/__main__.py

@@ -0,0 +1,3 @@
+from costcrunch.cli import main
+
+main()

costcrunch-0.1.0/src/costcrunch/_version.py

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

costcrunch-0.1.0/src/costcrunch/auth.py

@@ -0,0 +1,207 @@
+"""Signing in to CostCrunch.
+
+A CostCrunch API call is authenticated by the same Supabase session the web app uses: a
+short-lived access token (Bearer) plus a refresh token. We keep both in the saved profile and
+refresh the access token a few minutes before it expires.
+
+Ways to get a session:
+
+  * password     email + password (accounts created with a password)
+  * browser      opens the CostCrunch sign-in in the browser (Google and other providers), and
+                 catches the redirect on a localhost port (OAuth PKCE)
+  * api key      a cc_live_ key from Settings › Connections › API (COSTCRUNCH_API_KEY, or saved by
+                 `cost auth login --api-key`). Read-only, tied to one company, never expires
+                 until revoked. What the MCP server setup on that page uses.
+  * token        COSTCRUNCH_TOKEN, a raw access token, for CI and one-off scripts (no refresh)
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import http.server
+import json
+import os
+import secrets
+import socketserver
+import threading
+import time
+import urllib.parse
+import webbrowser
+from typing import Callable, Optional
+
+import httpx
+
+from costcrunch import config
+from costcrunch.errors import AuthError
+
+REFRESH_MARGIN_S = 300
+BROWSER_TIMEOUT_S = 300
+# Supabase only redirects to allow-listed URLs (anything else lands on the web app instead), so
+# browser sign-in listens on one fixed port: http://localhost:8976/** is on the allow list.
+BROWSER_PORT = 8976
+
+
+def _anon(profile: config.Profile) -> str:
+    return profile.anon_key or config.DEFAULT_AUTH_ANON_KEY
+
+
+def _token_call(profile: config.Profile, grant_type: str, body: dict) -> dict:
+    try:
+        r = httpx.post(f"{profile.auth_url.rstrip('/')}/auth/v1/token",
+                       params={"grant_type": grant_type},
+                       headers={"apikey": _anon(profile)}, json=body, timeout=30)
+    except httpx.HTTPError as e:
+        raise AuthError(f"could not reach the CostCrunch sign-in service: {e}") from e
+    if r.status_code >= 400:
+        try:
+            j = r.json()
+            msg = j.get("error_description") or j.get("msg") or j.get("message") or r.text
+        except ValueError:
+            msg = r.text
+        raise AuthError(f"sign-in failed: {msg}")
+    return r.json()
+
+
+def _apply_session(profile: config.Profile, s: dict) -> config.Profile:
+    profile.access_token = s["access_token"]
+    profile.refresh_token = s.get("refresh_token") or profile.refresh_token
+    profile.expires_at = time.time() + int(s.get("expires_in", 3600))
+    user = s.get("user") or {}
+    profile.email = user.get("email") or profile.email
+    return profile
+
+
+def login_password(profile: config.Profile, email: str, password: str) -> config.Profile:
+    return _apply_session(profile, _token_call(profile, "password",
+                                               {"email": email, "password": password}))
+
+
+def refresh(profile: config.Profile) -> config.Profile:
+    if not profile.refresh_token:
+        raise AuthError("this sign-in can't be refreshed; run `cost auth login` again")
+    return _apply_session(profile, _token_call(profile, "refresh_token",
+                                               {"refresh_token": profile.refresh_token}))
+
+
+# --- browser sign-in (OAuth PKCE with a localhost redirect) --------------------
+
+_DONE_PAGE = (b"<html><body style='font-family:system-ui;text-align:center;padding-top:4em'>"
+              b"<h2>You're signed in to CostCrunch.</h2><p>You can close this tab and go back "
+              b"to your terminal.</p></body></html>")
+
+
+def login_browser(profile: config.Profile, provider: str = "google", port: int = BROWSER_PORT,
+                  open_browser: Callable[[str], bool] = webbrowser.open,
+                  on_url: Optional[Callable[[str], None]] = None) -> config.Profile:
+    """Open the provider's sign-in page and wait for Supabase to redirect back with a code.
+
+    The redirect URL (http://localhost:<port>/callback) must be on the Supabase project's
+    allowed redirect list."""
+    verifier = secrets.token_urlsafe(64)
+    challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b"=").decode()
+    got: dict[str, str] = {}
+    ready = threading.Event()
+
+    class Handler(http.server.BaseHTTPRequestHandler):
+        def do_GET(self):  # noqa: N802
+            q = urllib.parse.parse_qs(urllib.parse.urlparse(self.path).query)
+            if "code" in q or "error" in q:
+                got.update({k: v[0] for k, v in q.items()})
+                ready.set()
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html")
+            self.end_headers()
+            self.wfile.write(_DONE_PAGE)
+
+        def log_message(self, *a):  # silence the default stderr access log
+            pass
+
+    try:
+        srv = socketserver.TCPServer(("127.0.0.1", port), Handler)
+    except OSError as e:
+        raise AuthError(f"port {port} is busy, so the browser sign-in can't listen for the "
+                        "redirect; sign in with --email instead") from e
+    with srv:
+        redirect = f"http://localhost:{srv.server_address[1]}/callback"
+        url = (f"{profile.auth_url.rstrip('/')}/auth/v1/authorize?" + urllib.parse.urlencode({
+            "provider": provider, "redirect_to": redirect,
+            "code_challenge": challenge, "code_challenge_method": "s256"}))
+        threading.Thread(target=srv.serve_forever, daemon=True).start()
+        if on_url:
+            on_url(url)
+        open_browser(url)
+        finished = ready.wait(BROWSER_TIMEOUT_S)
+        srv.shutdown()
+    if not finished:
+        raise AuthError("timed out waiting for the browser sign-in")
+    if "error" in got:
+        raise AuthError(f"sign-in was not completed: {got.get('error_description') or got['error']}")
+    return _apply_session(profile, _token_call(profile, "pkce", {
+        "auth_code": got["code"], "code_verifier": verifier}))
+
+
+# --- the token the client actually sends ---------------------------------------
+
+def jwt_claims(token: str) -> dict:
+    """Unverified claims of an access token (the API verifies it; we only read sub/email/exp)."""
+    try:
+        payload = token.split(".")[1]
+        return json.loads(base64.urlsafe_b64decode(payload + "=" * (-len(payload) % 4)))
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+API_KEY_PREFIX = "cc_live_"
+
+
+def is_api_key(token: Optional[str]) -> bool:
+    return bool(token) and token.startswith(API_KEY_PREFIX)
+
+
+class TokenSource:
+    """Hands out what goes in `Authorization: Bearer`: an API key, a fixed access token, or the
+    saved sign-in's access token (refreshed as needed).
+
+    Precedence: explicit api_key / token > COSTCRUNCH_API_KEY > COSTCRUNCH_TOKEN > saved profile
+    (its API key, else its session)."""
+
+    def __init__(self, token: Optional[str] = None, profile_name: Optional[str] = None,
+                 api_key: Optional[str] = None):
+        self._lock = threading.Lock()
+        self._fixed = (api_key or token or os.environ.get(config.ENV_API_KEY)
+                       or os.environ.get(config.ENV_TOKEN))
+        self._profile_name = profile_name
+        self._profile: Optional[config.Profile] = None if self._fixed else config.load(profile_name)
+        if self._profile is not None and self._profile.api_key:
+            self._fixed = self._profile.api_key
+
+    @property
+    def profile(self) -> Optional[config.Profile]:
+        return self._profile
+
+    @property
+    def uses_api_key(self) -> bool:
+        return is_api_key(self._fixed)
+
+    def token(self) -> str:
+        if self._fixed:
+            return self._fixed
+        with self._lock:
+            p = self._profile
+            if p is None or not p.access_token:
+                raise AuthError("not signed in: run `cost auth login` "
+                                f"(or set {config.ENV_API_KEY})")
+            if time.time() > p.expires_at - REFRESH_MARGIN_S:
+                refresh(p)
+                config.save(p, self._profile_name)
+            return p.access_token
+
+    def force_refresh(self) -> bool:
+        """After a 401: try once to get a fresh token. False when there is nothing to refresh
+        (an API key or a fixed token)."""
+        if self._fixed or self._profile is None or not self._profile.refresh_token:
+            return False
+        with self._lock:
+            refresh(self._profile)
+            config.save(self._profile, self._profile_name)
+        return True