anaf-sync 0.1.0__tar.gz

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

@@ -0,0 +1,53 @@
+# Credential-free gates on every push/PR: the fake-client test suite, ruff,
+# black, and mypy --strict, across the supported Python versions. The tests
+# additionally run on macOS and Windows — path handling and the scheduler
+# layer (schtasks / systemd user / launchd) are platform-dispatched and their
+# shared code must stay green everywhere.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Nothing here writes back to the repo — checkout is the only token consumer.
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Sync dependencies
+        run: uv sync
+      - name: Tests
+        run: uv run pytest -q --cov --cov-report=xml
+      # Every leg uploads; Codecov merges them per commit — the macOS/Windows
+      # legs execute scheduler branches the ubuntu leg never does. A Codecov
+      # outage must not break the gates, hence fail_ci_if_error stays off.
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v7
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          flags: ${{ matrix.os }}-py${{ matrix.python-version }}
+          fail_ci_if_error: false
+      # The static gates are platform-independent; run them once per Python.
+      - name: Ruff lint
+        if: runner.os == 'Linux'
+        run: uv run ruff check src tests
+      - name: Black format
+        if: runner.os == 'Linux'
+        run: uv run black --check src tests
+      - name: Mypy (strict)
+        if: runner.os == 'Linux'
+        run: uv run mypy src

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

@@ -0,0 +1,74 @@
+# Publish to PyPI on a version tag (v*) via trusted publishing (OIDC) — no
+# API token is stored in the repo. PyPI side: the project's trusted publisher
+# must name this repo, this filename (release.yml), and the `pypi` environment.
+# The full CI gates re-run here so a tag can never ship an artifact that a
+# broken branch produced.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+# Least privilege by default; the publish job re-declares what it actually needs
+# (a job-level block replaces this one rather than adding to it).
+permissions:
+  contents: read
+
+jobs:
+  gates:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: Sync dependencies
+        run: uv sync
+      - name: Tests
+        run: uv run pytest -q
+      - name: Ruff lint
+        run: uv run ruff check src tests
+      - name: Black format
+        run: uv run black --check src tests
+      - name: Mypy (strict)
+        run: uv run mypy src
+
+  build:
+    needs: gates
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.0
+      - name: Tag matches the package version
+        run: |
+          version="$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+          if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "pyproject version ${version} does not match tag ${GITHUB_REF_NAME}" >&2
+            exit 1
+          fi
+      - name: Build sdist + wheel
+        run: uv build
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/anaf-sync
+    permissions:
+      id-token: write  # OIDC for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

anaf_sync-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Coverage
+.coverage
+coverage.xml

anaf_sync-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

anaf_sync-0.1.0/CLAUDE.md

@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working in this repository.
+
+## What this is
+
+`anaf-sync` is a cross-platform (Windows/Linux/macOS) CLI that archives RO
+e-Factura invoices locally on a schedule. It is a thin, deliberate layer over
+[anafpy](https://github.com/robert-malai/anafpy) — Robert's own package, which
+also powers his local anafpy MCP server. Design rationale lives in
+[DESIGN.md](DESIGN.md); read it before changing architecture-level behaviour.
+
+## Commands
+
+```bash
+uv sync                                  # install deps (incl. dev group)
+uv run pytest -q                         # tests
+uv run ruff check src tests             # lint
+uv run black --check src tests          # format check (black writes; ruff checks)
+uv run mypy src                          # strict typing — must stay clean
+uv run anaf-sync --help                  # run the CLI from the venv
+```
+
+All four gates (pytest, ruff, black, mypy --strict) must pass before a change
+is considered done.
+
+## Architecture map
+
+| Module | Responsibility |
+|---|---|
+| `cli.py` | typer commands; the only place exceptions are caught for the user |
+| `config.py` | TOML sync config + `ANAFPY_*` env auth settings; `init` template |
+| `engine.py` | one sync pass: list → dedupe → download (retry) → write artifacts |
+| `context.py` | assembles the template variable dict for one message |
+| `template.py` | `str.format`-based path template, sanitised per substitution |
+| `state.py` | JSON record of archived message ids (idempotence) + failure traces (visibility only, never a retry gate) |
+| `scheduling.py` | registers `anaf-sync sync` with schtasks / systemd user / launchd |
+
+## Invariants — do not break
+
+- **Auth is anafpy's, not ours.** Credentials come from `ANAFPY_CLIENT_ID` /
+  `ANAFPY_CLIENT_SECRET` and the token store written by `anafpy auth login`
+  (`ANAFPY_TOKEN_STORE`, `ANAFPY_TOKEN_STORE_BACKEND`). Never introduce
+  anaf-sync-specific credential storage or config keys.
+- **Idempotence.** `state.json` is saved atomically after *every* archived
+  message. A crash mid-run must never lose or duplicate work.
+- **Path safety.** Every substituted template value is sanitised
+  (`template.py`); rendered paths must stay relative and inside the output
+  root. Windows-illegal characters and trailing dots/spaces are handled there
+  — keep any new path logic behind that choke point.
+- **Error philosophy** (mirrors anafpy): business outcomes are values,
+  exceptions propagate; catch only at boundaries. In the engine, a per-message
+  `AnafError` is recorded in the report and the run continues; everything else
+  crashes the run on purpose. The CLI is the only layer that formats errors
+  for humans and sets exit codes.
+- **Cross-platform.** Anything touching paths, schedulers, or consoles must
+  work on Windows, Linux, and macOS. No POSIX-only assumptions outside the
+  platform-dispatched branches of `scheduling.py`.
+
+## Sharp edges
+
+- ANAF retains messages for **60 days** and rejects older windows; the
+  1–60 bound on `lookback_days`/`--days` is ANAF's rule, not ours.
+- The message listing never carries party CIFs as JSON fields; anafpy extracts
+  them from the `detalii` prose. `context.py` treats them as best-effort.
+- `DownloadedMessage.view` is `None` for non-UBL content (nok error files,
+  buyer messages) *and* for rule-drift — the template must render regardless
+  (missing values become `unknown`).
+- anafpy's API is best learned from the installed source under
+  `.venv/lib/python3.12/site-packages/anafpy/` — its docstrings are the spec.
+
+## Conventions
+
+Robert's standard Python stack applies (see the `python-conventions` skill):
+Python 3.12+, `uv`, src layout, full type hints with `mypy --strict`,
+Pydantic v2 for anything structured, `pydantic-settings` for env config,
+`structlog` key-value logging, `httpx`/`tenacity` (via anafpy), `typer` CLI,
+`pytest` with pragmatic coverage. Google-style docstrings on public surfaces.
+
+Tests use fakes at the `EFacturaClient` seam (`tests/test_engine.py`) and
+`model_construct` to build invoice views without full UBL validation — follow
+those patterns rather than mocking HTTP.

anaf_sync-0.1.0/DESIGN.md

@@ -0,0 +1,219 @@
+# anaf-sync — design
+
+Why this tool is shaped the way it is. Companion to [README.md](README.md)
+(usage) and [CLAUDE.md](CLAUDE.md) (working conventions).
+
+## 1. Problem and goals
+
+ANAF's SPV purges e-Factura messages roughly **60 days** after filing. Any
+business that wants a durable local archive must poll within that window and
+keep its own copy. The goals, in order:
+
+1. **Never lose an invoice.** Anything filed must land on disk before ANAF
+   purges it, even across crashes, reboots, and flaky networks.
+2. **Zero-attention operation.** Install once, schedule, forget. A run that
+   finds nothing new is silent and cheap.
+3. **Human-shaped archive.** The on-disk layout is the user's to define, from
+   invoice data (`2026/07/2026-07-03_FCT-1001_ACME SRL.xml`), not ANAF's
+   opaque message ids.
+4. **Windows and Linux first-class** (macOS comes along for free — it is the
+   development machine).
+
+Non-goals: uploading/filing invoices, a GUI, multi-tenant server operation,
+long-term document management (search, OCR, bookkeeping integration). The
+archive is plain files; downstream tools take it from there.
+
+## 2. Position in the anafpy ecosystem
+
+anaf-sync is a *consumer* of anafpy, not a fork of its concerns. The split:
+
+- **anafpy** owns everything ANAF-shaped: OAuth + token refresh, transport,
+  pagination, response parsing, UBL models, the 60-day window rules.
+- **anaf-sync** owns everything archive-shaped: what to keep, where to put
+  it, what has already been fetched, and when to run.
+
+The most consequential decision follows from this: **anaf-sync has no
+credential system of its own.** It reads the same `ANAFPY_CLIENT_ID` /
+`ANAFPY_CLIENT_SECRET` env vars and the same token store
+(`anafpy auth login`, keyring or file backend, selected by
+`ANAFPY_TOKEN_STORE_BACKEND` / `ANAFPY_TOKEN_STORE`) as the anafpy CLI and
+MCP server. One browser login with the ANAF certificate serves every tool;
+`TokenProvider` re-reads the store on each use, so a refresh performed by any
+process is picked up by the others. The scheduled job depends on refresh
+working headlessly, which is why missing client credentials are a hard,
+early error rather than a warning.
+
+## 3. The sync model: stateless window, stateful archive
+
+Each run lists the **full lookback window** (default the whole 60 days) and
+dedupes against a local state file, rather than tracking a "last synced"
+timestamp.
+
+Rationale: a timestamp cursor is fragile in exactly the ways that lose
+invoices — clock skew, a failed run advancing the cursor, ANAF's listing
+being eventually-consistent at the window edge. Listing is cheap (paginated
+JSON); downloads are the expensive part, and the state file already gates
+those. With overlapping windows every run gets a fresh chance at anything
+previously missed, and a message only leaves the retry pool by being archived.
+
+Mechanics (`engine.py` + `state.py`):
+
+- The listing is materialised first so a pagination error aborts before any
+  download work.
+- `state.json` maps message id → record (when, where, which artifacts). It is
+  written **atomically after every archived message** (temp file + rename,
+  same pattern as anafpy's `FileTokenStore`), so a crash mid-run redoes at
+  most the in-flight message — and that redo is harmless because downloads
+  are idempotent GETs.
+- Failures are per-message: an `AnafError` on one download is recorded in the
+  `SyncReport` and the run continues. The next scheduled run retries it
+  naturally, because it is still absent from the state file. Anything outside
+  the `AnafError` hierarchy is a bug and crashes the run loudly.
+- Persistent failures also leave a trace in the state file (first/last attempt,
+  count, last error) so `anaf-sync status` can surface a message that keeps
+  failing before the 60-day window closes on it. These records are
+  **observability only** — they must never gate a retry; the record is cleared
+  the moment the message finally archives, and pruned once its last attempt
+  ages past `state_retention_days`.
+- Transient transport and rate-limit errors retry in-process with
+  exponential-jitter backoff (tenacity, 4 attempts) before counting as a
+  failure. Only the idempotent download GET retries; mirroring anafpy's
+  "single transparent call" stance, nothing non-idempotent ever does.
+- Records older than `state_retention_days` (default 90) are pruned at the
+  start of each non-dry run: past ANAF's 60-day retention a message id can
+  never be listed again, so its record gates nothing. The configured value is
+  floored at 60 for exactly that reason — pruning younger records would
+  re-download messages still in the window. This keeps `state.json` bounded
+  by the window, not by the archive's lifetime.
+
+`--redownload` bypasses the state gate (re-fetch everything, e.g. after
+changing the template); `--dry-run` reports what would be fetched without
+touching disk or state.
+
+## 4. Path templating
+
+The archive layout is a template over per-invoice variables, e.g.
+
+```
+{cif}/{direction}/{issue_date:%Y}/{issue_date:%m}/{issue_date:%Y-%m-%d}_{number}_{partner_name}
+```
+
+**Language choice: Python's `str.format` mini-language,** not Jinja2.
+Format specs give the two things a path actually needs — variable
+substitution and formatting (crucially `strftime` specs on real dates) — with
+zero dependencies, a syntax users already know, and no logic (loops,
+conditionals, filters) to escape-hatch into. If real conditional layout is
+ever needed, that is a sign the variable set is wrong, not that the template
+needs a `{% if %}`.
+
+Safety properties (`template.py`), enforced at one choke point:
+
+- Every **substituted value** is sanitised: Windows-illegal characters and
+  control chars become `-`, trailing dots/spaces are stripped. Literal `/` in
+  the template creates directories; a `/` inside a value cannot.
+- The rendered path must be relative and contain no `..` — output can never
+  escape the configured root, whatever an invoice number contains.
+- `None` renders as `unknown` rather than failing: an invoice that ANAF
+  accepted must be archivable even when our parser cannot project a field.
+- Unknown variables fail fast with the full list of available names —
+  template typos surface on the first run, not as mis-filed invoices.
+
+The variable set (`context.py`) is assembled from two tiers: the message
+listing (always present) and the parsed UBL view (best-effort). `partner_*`
+is the deliberate star: "the other party" resolved by direction, so one
+template serves both received and sent archives. Party CIFs prefer the
+invoice's own VAT fields and fall back to what anafpy extracts from the
+listing's `detalii` prose (ANAF never sends them as structured fields).
+
+A base path collision with an *existing different* file gets a `_{message_id}`
+suffix rather than clobbering — two invoices may legitimately render the same
+name.
+
+## 5. Artifacts
+
+Per message, the user picks any of:
+
+| artifact | content | why |
+|---|---|---|
+| `zip` | the raw `descarcare` ZIP | the legally meaningful, signed original — tier-1 truth, byte-preserved |
+| `xml` | invoice UBL extracted from the ZIP | convenient for downstream parsing |
+| `signature` | detached MF signature XML | verification without unzipping |
+| `pdf` | ANAF's own rendering | human-readable copy, via the public no-auth `transformare` service (`validate=False` — the document already passed validation at filing) |
+| `metadata` | JSON sidecar: listing entry + resolved context | machine-readable index without re-parsing UBL |
+
+Default is `["zip", "pdf"]`: the archive keeps the authoritative bytes plus
+the copy humans actually ask for. The XML stays available inside the ZIP (and
+as an opt-in artifact) — and since the PDF is rendered *from* that XML by a
+public no-auth service, it can be regenerated later; only the ZIP is
+unrecoverable after ANAF's window. The PDF client is only constructed when the
+artifact is enabled, and a non-PDF response (ANAF answers HTTP 200 with a
+JSON error) is a logged skip, not a failure — the invoice itself is already
+safe on disk.
+
+## 6. Configuration split
+
+Two layers, on purpose:
+
+- **TOML file** (`config.toml`, platformdirs config dir) for behaviour: CIFs,
+  direction, window, output template, artifacts. Human-owned,
+  diffable, commented by `anaf-sync init`, readable with stdlib `tomllib`.
+  There is deliberately no `environment` key: ANAF's TEST inbox only ever
+  holds messages you uploaded there yourself, so an archiver pointed at it
+  syncs nothing real, and every operation we perform is a read — production
+  is always safe. `--dry-run` covers the "preview without writing" need,
+  against the real inbox.
+- **Environment variables** for secrets and machine wiring: the `ANAFPY_*`
+  family (§2), plus `ANAF_SYNC_CONFIG` to relocate the config file. Secrets
+  never live in the TOML.
+
+State (`state.json`) lives in the platformdirs *state* dir, separate from
+config: wiping or versioning configuration must not forget what has been
+archived.
+
+## 7. Scheduling: the OS's job, not ours
+
+`anaf-sync schedule install` registers `anaf-sync sync` with the native
+scheduler; there is no daemon, no long-running process, no internal cron:
+
+- **Windows** — Task Scheduler via `schtasks` (interval → `/SC MINUTE|HOURLY|DAILY /MO n`, `--daily-at` → `/SC DAILY /ST`).
+- **Linux** — systemd **user** units (`anaf-sync.timer` + `.service`,
+  `Persistent=true` so missed runs fire on wake; `loginctl enable-linger`
+  documented for logged-out operation).
+- **macOS** — a launchd agent (`StartInterval` / `StartCalendarInterval`).
+
+Rationale: native schedulers survive reboots, handle wake-from-sleep and
+missed windows, and are inspectable with tools operators already know. The
+CLI resolves its own console-script path at install time so the job works
+without any venv activation. Because runs are idempotent (§3), overlapping
+or missed schedules are harmless — the schedule needs to be *roughly* right,
+never precise.
+
+## 8. Error handling and observability
+
+Mirrors anafpy's hybrid model:
+
+- **Values for business outcomes**: the `SyncReport` (listed / new / already
+  archived / non-invoice / failures) is the result of a run; per-message
+  failures are data in it.
+- **Exceptions for broken preconditions**: missing config, missing
+  credentials, invalid template, unexpected response shapes. These propagate
+  to the CLI boundary, which is the only place they are formatted for humans
+  and turned into exit codes (non-zero when anything failed, so the OS
+  scheduler's failure status is meaningful).
+- `structlog` key-value logging throughout (`archived`,
+  `message_id=…, path=…`), console-rendered; `--verbose` for debug.
+
+## 9. Known trade-offs and future work
+
+- **Sequential downloads.** Deliberate: ANAF enforces daily call quotas and
+  rate limits, and a nightly batch is not latency-sensitive. Concurrency is
+  the first knob to turn if volumes ever demand it.
+- **State is a JSON file.** Right up to tens of thousands of messages; SQLite
+  is the successor if listing volumes or query needs grow.
+- **Purge awareness, not purge alerts.** A message that fails for 60 days
+  straight ages out of ANAF's window and is lost. Failures are visible in
+  every run's report and exit code; an explicit "about to age out" warning
+  would be a cheap, worthwhile addition.
+- **No archive verification command.** `anaf-sync verify` (re-hash artifacts
+  against state, validate MF signatures via `validate_signature`) is a
+  natural extension.

anaf_sync-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: anaf-sync
+Version: 0.1.0
+Summary: Scheduled local archiver for RO e-Factura invoices, built on anafpy.
+Author-email: Robert Malai <rmalai@trocglobal.com>
+Requires-Python: >=3.12
+Requires-Dist: anafpy>=0.4.0
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: structlog>=24.1
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# anaf-sync
+
+<p>
+  <a href="https://github.com/robert-malai/anaf-sync/actions/workflows/ci.yml"><img
+    src="https://img.shields.io/github/actions/workflow/status/robert-malai/anaf-sync/ci.yml?branch=main&label=CI" alt="CI"></a>
+  <a href="https://codecov.io/gh/robert-malai/anaf-sync"><img
+    src="https://img.shields.io/codecov/c/github/robert-malai/anaf-sync?branch=main" alt="Coverage"></a>
+  <a href="https://pypi.org/project/anaf-sync/"><img
+    src="https://img.shields.io/pypi/v/anaf-sync" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/anaf-sync/"><img
+    src="https://img.shields.io/pypi/pyversions/anaf-sync" alt="Python versions"></a>
+</p>
+
+Scheduled local archiver for RO e-Factura invoices, built on
+[anafpy](https://github.com/robert-malai/anafpy). Each run lists every message
+in ANAF's 60-day retention window, downloads the ones it hasn't seen before,
+and files them under paths rendered from a template of invoice variables.
+Runs on Windows, Linux, and macOS.
+
+Design rationale lives in [DESIGN.md](DESIGN.md); conventions for working on
+the codebase in [CLAUDE.md](CLAUDE.md).
+
+## Install
+
+```bash
+uv tool install anaf-sync        # from a published wheel
+# or, from this checkout:
+uv tool install --from . anaf-sync
+```
+
+## Authentication
+
+anaf-sync reuses the anafpy login — the same one the anafpy MCP server uses:
+
+1. `anafpy auth login` (browser OAuth with your ANAF certificate) writes the
+   token set to the OS credential store (or a JSON file).
+2. Set `ANAFPY_CLIENT_ID` and `ANAFPY_CLIENT_SECRET` in the environment (or a
+   `.env` file) so scheduled runs can refresh expired tokens.
+
+Optional, mirroring anafpy: `ANAFPY_TOKEN_STORE_BACKEND=file` and
+`ANAFPY_TOKEN_STORE=~/.anafpy/tokens.json` for headless hosts without a
+credential store.
+
+## Configure
+
+```bash
+anaf-sync init            # writes a commented config.toml
+anaf-sync status          # shows where it lives on your platform
+```
+
+The interesting part is the path template:
+
+```toml
+[output]
+directory = "~/Facturi"
+template  = "{cif}/{direction}/{issue_date:%Y}/{issue_date:%m}/{issue_date:%Y-%m-%d}_{number}_{partner_name}"
+artifacts = ["zip", "pdf"]        # also: xml, signature, metadata
+```
+
+Templates use Python format syntax over the invoice's context: `number`,
+`issue_date` / `due_date` (real dates — strftime specs work), `currency`,
+`total`, `kind`, `direction`, `cif`, `seller_name`/`seller_cif`,
+`buyer_name`/`buyer_cif`, `partner_name`/`partner_cif` (the *other* party),
+`message_id`, `request_id`, `message_type`, `created`. Substituted values are
+sanitised for the filesystem; literal `/` in the template creates folders; each
+artifact appends its own extension.
+
+## Run
+
+```bash
+anaf-sync sync --dry-run   # see what would be downloaded
+anaf-sync sync             # download everything new
+```
+
+Runs are idempotent: a state file records archived message ids, so overlapping
+60-day windows never duplicate work, and anything ANAF is about to purge has
+already been captured.
+
+## Schedule
+
+```bash
+anaf-sync schedule install --every 6h        # or --daily-at 07:30
+anaf-sync schedule status
+anaf-sync schedule remove
+```
+
+This registers the sync with the OS scheduler — Task Scheduler on Windows,
+a systemd user timer on Linux (`loginctl enable-linger $USER` to run while
+logged out), launchd on macOS. No daemon of its own.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src tests && uv run black --check src tests && uv run mypy src
+```

anaf_sync-0.1.0/README.md

@@ -0,0 +1,97 @@
+# anaf-sync
+
+<p>
+  <a href="https://github.com/robert-malai/anaf-sync/actions/workflows/ci.yml"><img
+    src="https://img.shields.io/github/actions/workflow/status/robert-malai/anaf-sync/ci.yml?branch=main&label=CI" alt="CI"></a>
+  <a href="https://codecov.io/gh/robert-malai/anaf-sync"><img
+    src="https://img.shields.io/codecov/c/github/robert-malai/anaf-sync?branch=main" alt="Coverage"></a>
+  <a href="https://pypi.org/project/anaf-sync/"><img
+    src="https://img.shields.io/pypi/v/anaf-sync" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/anaf-sync/"><img
+    src="https://img.shields.io/pypi/pyversions/anaf-sync" alt="Python versions"></a>
+</p>
+
+Scheduled local archiver for RO e-Factura invoices, built on
+[anafpy](https://github.com/robert-malai/anafpy). Each run lists every message
+in ANAF's 60-day retention window, downloads the ones it hasn't seen before,
+and files them under paths rendered from a template of invoice variables.
+Runs on Windows, Linux, and macOS.
+
+Design rationale lives in [DESIGN.md](DESIGN.md); conventions for working on
+the codebase in [CLAUDE.md](CLAUDE.md).
+
+## Install
+
+```bash
+uv tool install anaf-sync        # from a published wheel
+# or, from this checkout:
+uv tool install --from . anaf-sync
+```
+
+## Authentication
+
+anaf-sync reuses the anafpy login — the same one the anafpy MCP server uses:
+
+1. `anafpy auth login` (browser OAuth with your ANAF certificate) writes the
+   token set to the OS credential store (or a JSON file).
+2. Set `ANAFPY_CLIENT_ID` and `ANAFPY_CLIENT_SECRET` in the environment (or a
+   `.env` file) so scheduled runs can refresh expired tokens.
+
+Optional, mirroring anafpy: `ANAFPY_TOKEN_STORE_BACKEND=file` and
+`ANAFPY_TOKEN_STORE=~/.anafpy/tokens.json` for headless hosts without a
+credential store.
+
+## Configure
+
+```bash
+anaf-sync init            # writes a commented config.toml
+anaf-sync status          # shows where it lives on your platform
+```
+
+The interesting part is the path template:
+
+```toml
+[output]
+directory = "~/Facturi"
+template  = "{cif}/{direction}/{issue_date:%Y}/{issue_date:%m}/{issue_date:%Y-%m-%d}_{number}_{partner_name}"
+artifacts = ["zip", "pdf"]        # also: xml, signature, metadata
+```
+
+Templates use Python format syntax over the invoice's context: `number`,
+`issue_date` / `due_date` (real dates — strftime specs work), `currency`,
+`total`, `kind`, `direction`, `cif`, `seller_name`/`seller_cif`,
+`buyer_name`/`buyer_cif`, `partner_name`/`partner_cif` (the *other* party),
+`message_id`, `request_id`, `message_type`, `created`. Substituted values are
+sanitised for the filesystem; literal `/` in the template creates folders; each
+artifact appends its own extension.
+
+## Run
+
+```bash
+anaf-sync sync --dry-run   # see what would be downloaded
+anaf-sync sync             # download everything new
+```
+
+Runs are idempotent: a state file records archived message ids, so overlapping
+60-day windows never duplicate work, and anything ANAF is about to purge has
+already been captured.
+
+## Schedule
+
+```bash
+anaf-sync schedule install --every 6h        # or --daily-at 07:30
+anaf-sync schedule status
+anaf-sync schedule remove
+```
+
+This registers the sync with the OS scheduler — Task Scheduler on Windows,
+a systemd user timer on Linux (`loginctl enable-linger $USER` to run while
+logged out), launchd on macOS. No daemon of its own.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src tests && uv run black --check src tests && uv run mypy src
+```