anaf-sync 0.1.0__py3-none-any.whl

anaf_sync/__init__.py

@@ -0,0 +1,13 @@
+"""anaf-sync — scheduled local archiver for RO e-Factura invoices.
+
+Lists every e-Factura message in the retention window, downloads the ones not
+seen before, and files each artifact under a path rendered from a user-defined
+template of invoice context variables. Built on :mod:`anafpy`; reuses the
+credentials and token store written by ``anafpy auth login``.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

anaf_sync/cli.py

@@ -0,0 +1,215 @@
+"""The ``anaf-sync`` command-line interface."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from pathlib import Path
+from typing import Annotated
+
+import structlog
+import typer
+from anafpy.exceptions import AnafError
+
+from . import __version__
+from .config import (
+    AuthSettings,
+    default_config_path,
+    default_state_path,
+    load_config,
+    write_default_config,
+)
+from .engine import run_sync
+from .scheduling import ScheduleError
+from .scheduling import install as schedule_install
+from .scheduling import status as schedule_status
+from .scheduling import uninstall as schedule_uninstall
+from .state import SyncState
+
+app = typer.Typer(
+    name="anaf-sync",
+    help="Archive RO e-Factura invoices locally, on a schedule.",
+    no_args_is_help=True,
+)
+schedule_app = typer.Typer(help="Manage the OS-level schedule for `anaf-sync sync`.")
+app.add_typer(schedule_app, name="schedule")
+
+_CONFIG_ENV = "ANAF_SYNC_CONFIG"
+
+ConfigOption = Annotated[
+    Path | None,
+    typer.Option(
+        "--config",
+        "-c",
+        help=f"Config file (default: ${_CONFIG_ENV} or the platform config dir).",
+    ),
+]
+
+
+def _configure_logging(verbose: bool) -> None:
+    level = logging.DEBUG if verbose else logging.INFO
+    structlog.configure(
+        wrapper_class=structlog.make_filtering_bound_logger(level),
+        processors=[
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="%H:%M:%S"),
+            structlog.dev.ConsoleRenderer(),
+        ],
+    )
+
+
+def _resolve_config_path(option: Path | None) -> Path:
+    if option is not None:
+        return option.expanduser()
+    if env := os.environ.get(_CONFIG_ENV):
+        return Path(env).expanduser()
+    return default_config_path()
+
+
+@app.callback()
+def _main(
+    verbose: Annotated[
+        bool, typer.Option("--verbose", "-v", help="Debug logging.")
+    ] = False,
+) -> None:
+    _configure_logging(verbose)
+
+
+@app.command()
+def version() -> None:
+    """Print the anaf-sync version."""
+    typer.echo(f"anaf-sync {__version__}")
+
+
+@app.command()
+def init(
+    config: ConfigOption = None,
+    force: Annotated[
+        bool, typer.Option("--force", help="Overwrite an existing config.")
+    ] = False,
+) -> None:
+    """Write a commented default configuration file."""
+    path = _resolve_config_path(config)
+    try:
+        write_default_config(path, force=force)
+    except FileExistsError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(f"wrote {path}")
+    typer.echo("Edit it (CIF, output folder, template), then run: anaf-sync sync")
+
+
+@app.command()
+def sync(
+    config: ConfigOption = None,
+    days: Annotated[
+        int | None,
+        typer.Option(min=1, max=60, help="Override the lookback window."),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="List what would be downloaded; write nothing."),
+    ] = False,
+    redownload: Annotated[
+        bool,
+        typer.Option(
+            "--redownload", help="Ignore the state file and fetch everything."
+        ),
+    ] = False,
+) -> None:
+    """Download all new e-Factura invoices into the archive."""
+    config_path = _resolve_config_path(config)
+    try:
+        cfg = load_config(config_path)
+        provider = AuthSettings.from_env().build_provider()
+        state = SyncState.load(default_state_path())
+        report = asyncio.run(
+            run_sync(
+                cfg,
+                provider,
+                state,
+                days=days,
+                dry_run=dry_run,
+                redownload=redownload,
+            )
+        )
+    except (AnafError, FileNotFoundError, ValueError) as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+    typer.echo(
+        f"listed {report.listed} | new {report.downloaded} | "
+        f"already archived {report.already_archived} | "
+        f"non-invoice {report.skipped_non_invoice}"
+        + (f" | would download {report.would_download}" if dry_run else "")
+    )
+    if report.failures:
+        for message_id, error in report.failures:
+            typer.echo(f"failed {message_id}: {error}", err=True)
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def status(config: ConfigOption = None) -> None:
+    """Show configuration, archive state, and schedule status."""
+    config_path = _resolve_config_path(config)
+    typer.echo(
+        f"config:   {config_path} ({'ok' if config_path.exists() else 'MISSING'})"
+    )
+    state = SyncState.load(default_state_path())
+    typer.echo(f"state:    {state.path} ({state.count} messages archived)")
+    for message_id, failure in state.failures.items():
+        typer.echo(
+            f"failing:  {message_id} — {failure.attempts} run(s) since "
+            f"{failure.first_failed_at:%Y-%m-%d}: {failure.error}"
+        )
+    if config_path.exists():
+        cfg = load_config(config_path)
+        typer.echo(f"cifs:     {', '.join(cfg.cifs)}  [{cfg.direction.value}]")
+        typer.echo(f"output:   {cfg.output.resolved_directory}")
+        typer.echo(f"template: {cfg.output.template}")
+    typer.echo(f"schedule: {schedule_status()}")
+
+
+@schedule_app.command("install")
+def schedule_install_cmd(
+    every: Annotated[
+        str | None,
+        typer.Option("--every", help="Run interval, e.g. 30m, 6h, 1d."),
+    ] = None,
+    daily_at: Annotated[
+        str | None,
+        typer.Option("--daily-at", help="Run once a day at HH:MM (24h)."),
+    ] = None,
+) -> None:
+    """Register `anaf-sync sync` with the OS scheduler.
+
+    Uses Task Scheduler on Windows, a systemd user timer on Linux, and
+    launchd on macOS.
+    """
+    try:
+        typer.echo(schedule_install(every=every, daily_at=daily_at))
+    except ScheduleError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@schedule_app.command("remove")
+def schedule_remove_cmd() -> None:
+    """Remove the scheduled job."""
+    try:
+        typer.echo(schedule_uninstall())
+    except ScheduleError as exc:
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+
+@schedule_app.command("status")
+def schedule_status_cmd() -> None:
+    """Show whether the scheduled job is installed."""
+    typer.echo(schedule_status())
+
+
+if __name__ == "__main__":
+    app()

anaf_sync/config.py

@@ -0,0 +1,248 @@
+"""Configuration: a TOML file for sync behaviour, environment variables for auth.
+
+Credentials deliberately reuse anafpy's own conventions (``ANAFPY_CLIENT_ID``,
+``ANAFPY_CLIENT_SECRET``, ``ANAFPY_TOKEN_STORE``, ``ANAFPY_TOKEN_STORE_BACKEND``)
+so the login performed with ``anafpy auth login`` — CLI or MCP server — is shared
+as-is. Everything behavioural (CIFs, window, output template, artifacts) lives in
+a TOML file the user owns.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from enum import StrEnum
+from pathlib import Path
+from typing import Literal, Self
+
+import platformdirs
+from anafpy.auth import FileTokenStore, KeyringTokenStore, TokenProvider, TokenStore
+from anafpy.exceptions import AnafConfigError
+from pydantic import BaseModel, Field, field_validator, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+__all__ = [
+    "APP_NAME",
+    "Artifact",
+    "AuthSettings",
+    "Direction",
+    "OutputConfig",
+    "SyncConfig",
+    "default_config_path",
+    "default_state_path",
+    "load_config",
+    "write_default_config",
+]
+
+APP_NAME = "anaf-sync"
+
+_DEFAULT_TEMPLATE = (
+    "{cif}/{direction}/{issue_date:%Y}/{issue_date:%m}/"
+    "{issue_date:%Y-%m-%d}_{number}_{partner_name}"
+)
+
+
+class Direction(StrEnum):
+    """Which side of the exchange to archive."""
+
+    RECEIVED = "received"
+    SENT = "sent"
+    BOTH = "both"
+
+
+class Artifact(StrEnum):
+    """What to write to disk for each downloaded message."""
+
+    ZIP = "zip"  # the raw descarcare ZIP — the legally meaningful archive
+    XML = "xml"  # the invoice UBL XML extracted from the ZIP
+    SIGNATURE = "signature"  # the detached MF signature XML
+    PDF = "pdf"  # ANAF's own PDF rendering (public transformare service)
+    METADATA = "metadata"  # a small JSON sidecar with the message + summary
+
+
+class OutputConfig(BaseModel):
+    """Where and how downloaded invoices are written."""
+
+    directory: Path = Path("~/Facturi")
+    template: str = _DEFAULT_TEMPLATE
+    artifacts: list[Artifact] = [Artifact.ZIP, Artifact.PDF]
+
+    @field_validator("artifacts")
+    @classmethod
+    def _non_empty(cls, value: list[Artifact]) -> list[Artifact]:
+        if not value:
+            raise ValueError("output.artifacts cannot be empty")
+        return value
+
+    @property
+    def resolved_directory(self) -> Path:
+        return self.directory.expanduser()
+
+
+class SyncConfig(BaseModel):
+    """The TOML configuration file, validated."""
+
+    cifs: list[str] = Field(min_length=1)
+    direction: Direction = Direction.RECEIVED
+    lookback_days: int = Field(default=60, ge=1, le=60)
+    # Floor of 60: pruning records ANAF can still list would re-download them.
+    state_retention_days: int = Field(default=90, ge=60)
+    output: OutputConfig = OutputConfig()
+
+    @model_validator(mode="before")
+    @classmethod
+    def _accept_single_cif(cls, data: object) -> object:
+        # `cif = "123"` is friendlier than a one-element list; accept both.
+        if isinstance(data, dict) and "cif" in data and "cifs" not in data:
+            data = dict(data)
+            data["cifs"] = [data.pop("cif")]
+        return data
+
+    @field_validator("cifs")
+    @classmethod
+    def _digits_only(cls, value: list[str]) -> list[str]:
+        cleaned = [str(cif).strip().upper().removeprefix("RO") for cif in value]
+        for cif in cleaned:
+            if not cif.isdigit():
+                raise ValueError(f"CIF {cif!r} is not numeric (drop any RO prefix)")
+        return cleaned
+
+
+class AuthSettings(BaseSettings):
+    """ANAF OAuth credentials and token-store location, from ``ANAFPY_*`` env vars.
+
+    Mirrors anafpy's own MCP-server config so one login serves every consumer.
+    """
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    client_id: str | None = Field(default=None, validation_alias="ANAFPY_CLIENT_ID")
+    client_secret: str | None = Field(
+        default=None, validation_alias="ANAFPY_CLIENT_SECRET"
+    )
+    token_store_path: Path = Field(
+        default=Path("~/.anafpy/tokens.json"), validation_alias="ANAFPY_TOKEN_STORE"
+    )
+    token_store_backend: Literal["keyring", "file"] = Field(
+        default="keyring", validation_alias="ANAFPY_TOKEN_STORE_BACKEND"
+    )
+
+    def build_store(self) -> TokenStore:
+        if self.token_store_backend == "file":
+            return FileTokenStore(self.token_store_path)
+        return KeyringTokenStore()
+
+    def build_provider(self) -> TokenProvider:
+        """A refreshing token provider over the shared store.
+
+        Raises:
+            AnafConfigError: the OAuth client credentials are missing — without
+                them expired access tokens cannot be refreshed, which a scheduled
+                job depends on.
+        """
+        if not self.client_id or not self.client_secret:
+            raise AnafConfigError(
+                "ANAFPY_CLIENT_ID / ANAFPY_CLIENT_SECRET are not set — anaf-sync "
+                "needs them to refresh tokens between scheduled runs"
+            )
+        return TokenProvider(
+            client_id=self.client_id,
+            client_secret=self.client_secret,
+            store=self.build_store(),
+        )
+
+    @classmethod
+    def from_env(cls) -> Self:
+        return cls()
+
+
+def default_config_path() -> Path:
+    """``config.toml`` in the platform config dir (roaming on Windows)."""
+    return platformdirs.user_config_path(APP_NAME, appauthor=False) / "config.toml"
+
+
+def default_state_path() -> Path:
+    """``state.json`` in the platform state dir (survives config wipes)."""
+    return platformdirs.user_state_path(APP_NAME, appauthor=False) / "state.json"
+
+
+def load_config(path: Path) -> SyncConfig:
+    """Load and validate the TOML configuration.
+
+    Raises:
+        FileNotFoundError: no config file at ``path`` — run ``anaf-sync init``.
+    """
+    if not path.exists():
+        raise FileNotFoundError(
+            f"no configuration at {path} — run `anaf-sync init` to create one"
+        )
+    with path.open("rb") as fh:
+        data = tomllib.load(fh)
+    return SyncConfig.model_validate(data)
+
+
+_DEFAULT_CONFIG_TOML = f"""\
+# anaf-sync configuration.
+#
+# Credentials are NOT stored here: anaf-sync reuses the anafpy login
+# (`anafpy auth login`) plus the ANAFPY_CLIENT_ID / ANAFPY_CLIENT_SECRET
+# environment variables, exactly like the anafpy MCP server.
+
+# The company CIF(s) to archive invoices for (numeric, no RO prefix).
+cif = "12345678"
+# ...or several:  cifs = ["12345678", "87654321"]
+
+# Which invoices to download: "received", "sent", or "both".
+direction = "received"
+
+# How far back each run looks (1-60; ANAF purges messages after 60 days).
+lookback_days = 60
+
+# How long to keep state-file records of already-archived messages, in days
+# (minimum 60). Past ANAF's 60-day window a message can never be listed again,
+# so older records are pruned at the start of each run to keep state.json small.
+state_retention_days = 90
+
+[output]
+# Root folder for the archive (created if missing; ~ is expanded).
+directory = "~/Facturi"
+
+# Where each invoice lands, relative to `directory`, as a template over the
+# invoice's context variables. Python format-spec syntax applies, so dates
+# support strftime specs like {{issue_date:%Y}}. Available variables:
+#
+#   number          invoice number (BT-1)
+#   issue_date      issue date (a real date - format with strftime specs)
+#   due_date        due date, when present
+#   currency        invoice currency code
+#   total           payable amount
+#   kind            "invoice" or "credit_note"
+#   direction       "received" or "sent"
+#   cif             the CIF this sync run queried
+#   seller_name     seller legal name        seller_cif    seller CIF (digits)
+#   buyer_name      buyer legal name         buyer_cif     buyer CIF (digits)
+#   partner_name    the other party's name   partner_cif   the other party's CIF
+#   message_id      ANAF download id         request_id    ANAF upload id
+#   message_type    ANAF message type        created       message creation time
+#
+# Values are sanitised for the filesystem; "/" in the template creates folders.
+# Do not add an extension - each artifact appends its own (.zip, .xml, ...).
+template = "{_DEFAULT_TEMPLATE}"
+
+# What to save per invoice: "zip" (raw signed archive), "xml" (invoice UBL),
+# "signature" (detached MF signature), "pdf" (ANAF's rendering), "metadata"
+# (JSON sidecar with the message details).
+artifacts = ["zip", "pdf"]
+"""
+
+
+def write_default_config(path: Path, *, force: bool = False) -> Path:
+    """Write the commented default config to ``path``.
+
+    Raises:
+        FileExistsError: the file exists and ``force`` is not set.
+    """
+    if path.exists() and not force:
+        raise FileExistsError(f"{path} already exists (use --force to overwrite)")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(_DEFAULT_CONFIG_TOML, encoding="utf-8")
+    return path

anaf_sync/context.py

@@ -0,0 +1,129 @@
+"""Build the template context for one downloaded e-Factura message.
+
+Every variable the path template may reference is assembled here, from two
+sources: the message-list entry (always present) and the parsed invoice view
+(present when the downloaded content is a readable UBL invoice/credit note).
+Missing values stay ``None`` — the template renders them as ``unknown``.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from decimal import Decimal
+from typing import Any
+
+from anafpy.efactura import MessageListItem
+from anafpy.efactura.authoring import InvoiceDocument
+
+__all__ = ["Direction", "build_context", "direction_of"]
+
+Direction = str  # "received" | "sent" | None — narrow alias for readability
+
+
+def direction_of(item: MessageListItem) -> Direction | None:
+    """Classify a message as received/sent from ANAF's ``tip`` field."""
+    kind = (item.message_type or "").casefold()
+    if "primita" in kind:
+        return "received"
+    if "trimisa" in kind:
+        return "sent"
+    return None
+
+
+def _parse_created(raw: str | None) -> dt.datetime | None:
+    """ANAF's ``data_creare`` is ``yyyymmddhhmm``; be lenient about it."""
+    if not raw:
+        return None
+    try:
+        return dt.datetime.strptime(raw.strip(), "%Y%m%d%H%M")
+    except ValueError:
+        return None
+
+
+def _digits(value: str | None) -> str | None:
+    """A CIF as plain digits, from either ``123`` or ``RO123`` shapes."""
+    if not value:
+        return None
+    cleaned = value.strip().upper().removeprefix("RO")
+    return cleaned if cleaned.isdigit() else None
+
+
+def _party_cif(vat_id: str | None, *fallbacks: str | None) -> str | None:
+    for candidate in (vat_id, *fallbacks):
+        if digits := _digits(candidate):
+            return digits
+    return None
+
+
+def build_context(
+    item: MessageListItem,
+    view: InvoiceDocument | None,
+    *,
+    cif: str,
+) -> dict[str, Any]:
+    """The full variable set available to the path template.
+
+    Args:
+        item: the message-list entry the download originated from.
+        view: the parsed flat invoice, when the content was readable UBL.
+        cif: the CIF this sync run queried (the "own" company).
+    """
+    direction = direction_of(item)
+
+    number: str | None = None
+    issue_date: dt.date | None = None
+    due_date: dt.date | None = None
+    currency: str | None = None
+    total: Decimal | None = None
+    kind: str | None = None
+    seller_name: str | None = None
+    seller_cif: str | None = None
+    buyer_name: str | None = None
+    buyer_cif: str | None = None
+
+    if view is not None:
+        number = view.number
+        issue_date = view.issue_date
+        due_date = view.due_date
+        currency = str(view.currency)
+        kind = view.kind.value
+        seller_name = view.seller.name
+        seller_cif = _party_cif(
+            view.seller.vat_id, view.seller.tax_registration_id, item.sender_cif
+        )
+        buyer_name = view.buyer.name
+        buyer_cif = _party_cif(view.buyer.vat_id, item.receiver_cif)
+        try:
+            total = view.effective_totals().payable
+        except Exception:  # totals are auxiliary context — never fail the archive
+            total = None
+    else:
+        seller_cif = _digits(item.sender_cif)
+        buyer_cif = _digits(item.receiver_cif)
+
+    if direction == "sent":
+        partner_name, partner_cif = buyer_name, buyer_cif
+    else:
+        # Received — and the safe default when the type is unrecognised.
+        partner_name, partner_cif = seller_name, seller_cif
+
+    return {
+        "message_id": item.id,
+        "request_id": item.request_id,
+        "message_type": item.message_type,
+        "created": _parse_created(item.created_at),
+        "cif": _digits(cif) or cif,
+        "direction": direction,
+        "number": number,
+        "issue_date": issue_date,
+        "due_date": due_date,
+        "currency": currency,
+        "total": total,
+        "kind": kind,
+        "seller_name": seller_name,
+        "seller_cif": seller_cif,
+        "buyer_name": buyer_name,
+        "buyer_cif": buyer_cif,
+        "partner_name": partner_name,
+        "partner_cif": partner_cif,
+    }