nexterp-declarations 0.2.0__py3-none-any.whl

nexterp_declarations/XSD_BUNDLING.md

@@ -0,0 +1,71 @@
+# XSD bundling per declaration version
+
+Each version subdir (`<decl>/<vN>/`) can carry a `schema.xsd` next to its
+`generator.py`. When present, `gen.validate_xsd(xml_bytes)` validates the
+emitted XML against it; when missing, `validate_xsd` returns a single
+``warning`` issue telling the caller exactly where to drop the file.
+
+## Currently bundled (from `l10n-romania-enterprise`)
+
+| Declaration | Version | XSD file | Source |
+|---|---|---|---|
+| D101 | v10 | `d101/v10/schema.xsd` | `l10n_ro_declaration_D101/data/xsd/d101_20250214.xsd` |
+| D120 | v40 | `d120/v40/schema.xsd` | `l10n_ro_declaration_D120/static/xsd/d120_v3_24032020.xsd` |
+| D120 | v50 | `d120/v50/schema.xsd` | `l10n_ro_declaration_D120/static/xsd/d120_13052025.xsd` |
+| D390 | v3  | `d390/v3/schema.xsd`  | `l10n_ro_declaration_D390/static/xsd/d390_20200323.xsd` |
+| D390 | v41 | `d390/v41/schema.xsd` | `l10n_ro_declaration_D390/static/xsd/d390_12022021.xsd` |
+
+## Pending (URL-only references — ANAF serves them off `static.anaf.ro`)
+
+For each, drop the downloaded `.xsd` into the matching directory below
+and `validate_xsd` will pick it up automatically (resolved via
+`importlib.resources` in the XSD mixin).
+
+| Declaration | Version | Path inside the package | Source URL |
+|---|---|---|---|
+| D100 | v2  | `d100/v2/schema.xsd`  | <https://static.anaf.ro/static/10/Anaf/Declaratii_R/AplicatiiDec/d100_24022022.xsd> |
+| D710 | v1  | `d100/v2/d710.xsd` †  | <https://static.anaf.ro/static/10/Anaf/Declaratii_R/AplicatiiDec/d710_20012025.xsd> |
+| D300 | v6  | `d300/v6/schema.xsd`  | <https://static.anaf.ro/static/10/Anaf/Declaratii_R/AplicatiiDec/d300_06092019.xsd> |
+| D300 | v7  | `d300/v7/schema.xsd`  | (ANAF release — confirm URL on publication notice) |
+| D300 | v9  | `d300/v9/schema.xsd`  | (ANAF release — confirm URL) |
+| D300 | v10 | `d300/v10/schema.xsd` | (ANAF release — confirm URL) |
+| D300 | v11 | `d300/v11/schema.xsd` | (ANAF release — confirm URL) |
+| D300 | v12 | `d300/v12/schema.xsd` | (ANAF release — confirm URL) |
+| D394 | v3  | `d394/v3/schema.xsd`  | <https://static.anaf.ro/static/10/Anaf/Declaratii_R/AplicatiiDec/d394_20200925.xsd> |
+| D394 | v4  | `d394/v4/schema.xsd`  | <https://static.anaf.ro/static/10/Anaf/Declaratii_R/AplicatiiDec/d394_20220510.xsd> |
+| D394 | v5  | `d394/v5/schema.xsd`  | (ANAF release — confirm URL) |
+| D406 | v1  | `d406/v1/Romanian_SAF-T_Financial_Schema_v_2.4.9.xsd` ‡ | <https://static.anaf.ro/static/10/Anaf/Declaratii_R/AplicatiiDec/Romanian_SAF-T_Financial_Schema_v_2.4.9.xsd> |
+| Intrastat | v1 | `intrastat/v1/schema.xsd` | INS — see Intrastat handbook |
+
+† D710 shares the wizard with D100 but has a distinct XSD. The current
+`D100GeneratorV2._envelope()` swaps the `xsi:schemaLocation` filename via
+`_DECL_FORMAT`; bundle D710's XSD under a non-default filename and override
+`_xsd_resource` on the rectifying branch (Wave 2).
+
+‡ D406 carries the SAF-T XSD filename verbatim in its `xsi:schemaLocation`
+attribute, so the file under `d406/v1/` must keep that exact name. The
+`XSDValidatableMixin` reads its `_xsd_resource` class attribute as the
+filename — D406 already overrides it to the SAF-T filename.
+
+## How to refresh after ANAF publishes a new version
+
+The duk_validation watcher in [`validator/app/watcher/`](../../validator/app/watcher/)
+detects the URL change and writes a diff JSON (see
+[`validator/app/watcher/diff_publisher.py`](../../validator/app/watcher/diff_publisher.py)).
+The CI bot at
+[`.github/workflows/auto-version-skeleton.yml`](../../.github/workflows/auto-version-skeleton.yml)
+runs `tools/gen_version_skeleton.py` against the diff and opens a PR with
+the skeleton class. **The PR does NOT bundle the new XSD** — that's a
+manual step on every release.
+
+Workflow when reviewing such a PR:
+
+1. Download the XSD from the URL in the diff JSON's `source_url`.
+2. Drop it as `<decl>/<vN>/schema.xsd` (or whatever the dispatcher's
+   `_xsd_resource` resolves to).
+3. Run `pytest tests/` — the smoke test for the new version will start
+   failing if your renderer produces output the bundled XSD rejects.
+4. Iterate on the generator until the XSD validates.
+
+The XSD is part of the wheel via `MANIFEST.in` (`recursive-include src *.xsd`),
+so once committed it ships in the next pip release.

nexterp_declarations/__init__.py

@@ -0,0 +1,12 @@
+"""nexterp-declarations: Romanian ANAF declarations (schemas + generators)."""
+
+from ._version import __version__
+from .base._client import GenerationError, LicenseError, configure_license, remote_generate
+
+__all__ = [
+    "__version__",
+    "configure_license",
+    "remote_generate",
+    "GenerationError",
+    "LicenseError",
+]

nexterp_declarations/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = None

nexterp_declarations/base/__init__.py

@@ -0,0 +1,78 @@
+"""Shared schemas + utilities used by every declaration.
+
+Split by who needs them:
+
+* **Data models** (CompanyV2, MovesData, the schemas, exceptions) are the
+  public input contract -- imported eagerly; clients need them to build a
+  declaration input. They ship in the distributed wheel.
+* **Generation helpers** (``coa`` classifier, ``xml_render``,
+  ``xsd_validator``) are server-side logic -- imported lazily via
+  ``__getattr__`` so importing :mod:`nexterp_declarations.base` (e.g. to get
+  ``CompanyV2``) never pulls them in. They are excluded from the distributed
+  wheel and live only where generation runs (the duk service, from source).
+"""
+
+# Data models -- always available (the public input contract).
+from .common_moves import Move, MoveLine, MovesData, Partner, VatRegime
+from .envelope_v2 import CompanyV2, PeriodV2
+from .exceptions import DeclarationError, GenerationError, ValidationError
+from .schemas import (
+    Address,
+    Bank,
+    Company,
+    DeclarationKind,
+    MonetaryAmount,
+    Period,
+    Signer,
+    ValidationIssue,
+)
+
+# Generation helpers -- resolved lazily (excluded from the client wheel).
+_LAZY = {
+    "MovementKind": ("coa", "MovementKind"),
+    "classify": ("coa", "classify"),
+    "is_intracom": ("coa", "is_intracom"),
+    "render_document": ("xml_render", "render_document"),
+    "render_section": ("xml_render", "render_section"),
+    "value_to_xml_attr": ("xml_render", "value_to_xml_attr"),
+    "validate_xml": ("xsd_validator", "validate_xml"),
+}
+
+
+def __getattr__(name):
+    target = _LAZY.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    mod = importlib.import_module(f".{target[0]}", __name__)
+    return getattr(mod, target[1])
+
+
+__all__ = [
+    "Address",
+    "Bank",
+    "Company",
+    "CompanyV2",
+    "DeclarationError",
+    "DeclarationKind",
+    "GenerationError",
+    "MonetaryAmount",
+    "Move",
+    "MoveLine",
+    "MovementKind",
+    "MovesData",
+    "Partner",
+    "Period",
+    "PeriodV2",
+    "Signer",
+    "ValidationError",
+    "ValidationIssue",
+    "VatRegime",
+    "classify",
+    "is_intracom",
+    "render_document",
+    "render_section",
+    "validate_xml",
+    "value_to_xml_attr",
+]

nexterp_declarations/base/_client.py

@@ -0,0 +1,112 @@
+"""Thin client -- delegate generation + validation to the duk service.
+
+In the distributed (customer) install the package ships only the input
+*schemas* and this client; the generation logic lives on
+``duk.nexterp.ro``. The host (Odoo) calls :func:`configure_license` once with
+the signed license token it obtained from nexterp.ro and the duk URL, then
+:func:`remote_generate` POSTs the composed input to ``/generate`` and returns
+the XML. The token is what authorises the call (verified offline on duk); the
+SAF-T-sized payloads are generated server-side without the logic ever leaving
+duk.
+
+Nothing here is secret -- it is an HTTP client over the public input schemas.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import urllib.error
+import urllib.request
+
+_TOKEN: str | None = None
+_SERVER_URL: str | None = None
+
+
+class LicenseError(RuntimeError):
+    """The duk service rejected the license token (missing/expired/uncovered)."""
+
+
+class GenerationError(RuntimeError):
+    """The duk service failed to generate or validate the declaration."""
+
+
+def configure_license(token: str | None, server_url: str | None) -> None:
+    """Register the signed license token + duk base URL for :func:`remote_generate`."""
+    global _TOKEN, _SERVER_URL
+    _TOKEN = token
+    _SERVER_URL = server_url.rstrip("/") if server_url else None
+
+
+def _decompose(inp):
+    """Split a ``<Decl>Input`` into the duk request parts.
+
+    ``header``/``company``/``period`` map verbatim; every other Input field
+    (``data``, ``lines``, ``arrivals``/``dispatches``, ``serie_facturi`` ...)
+    goes into ``data`` keyed by its field name -- matching the duk
+    auto-registrar's wire format.
+    """
+    full = inp.model_dump(mode="json")
+    header = full.pop("header", {})
+    company = full.pop("company")
+    period = full.pop("period")
+    return header, company, period, full
+
+
+def remote_generate(
+    declaration: str,
+    inp,
+    *,
+    validate_xsd: bool = True,
+    validate_duk: bool = True,
+    return_pdf: bool = False,
+    user_email: str = "",
+    timeout: int = 300,
+) -> bytes:
+    """POST ``inp`` to duk ``/generate`` and return the XML bytes.
+
+    Raises :class:`LicenseError` on 401/403 (bad/expired/uncovered token) and
+    :class:`GenerationError` on validation/generation failure.
+    """
+    if not _SERVER_URL:
+        raise LicenseError(
+            "nexterp-declarations: call configure_license(token, server_url) first"
+        )
+    header, company, period, data = _decompose(inp)
+    payload = {
+        "declaration": declaration,
+        "company": company,
+        "period": period,
+        "header": header,
+        "data": data,
+        "token": _TOKEN or "",
+        "options": {
+            "validate_xsd": validate_xsd,
+            "validate_duk": validate_duk,
+            "return_xml": True,
+            "return_pdf": return_pdf,
+        },
+        "user_email": user_email,
+    }
+    req = urllib.request.Request(
+        f"{_SERVER_URL}/generate",
+        data=json.dumps(payload).encode(),
+        headers={"Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310 - fixed scheme
+            result = json.loads(resp.read())
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode(errors="replace")
+        if exc.code in (401, 403):
+            raise LicenseError(f"license rejected by duk ({exc.code}): {body}") from exc
+        raise GenerationError(f"duk /generate failed ({exc.code}): {body}") from exc
+    except urllib.error.URLError as exc:
+        raise GenerationError(f"duk /generate unreachable: {exc}") from exc
+
+    if not result.get("ok"):
+        msgs = "; ".join(i.get("message", "") for i in (result.get("issues") or []))
+        raise GenerationError(msgs or "duk reported the declaration invalid")
+    xml_b64 = result.get("xml_base64")
+    if not xml_b64:
+        raise GenerationError("duk returned no XML")
+    return base64.b64decode(xml_b64)

nexterp_declarations/base/common_moves.py

@@ -0,0 +1,158 @@
+"""Shared accounting payload -- used by every D-series declaration.
+
+Each declaration has its own ``data`` shape *wrapper* (D300Data,
+D390Data, D394Data, ...), but the underlying ``Partner``, ``Move``,
+and ``MoveLine`` records are identical: they describe the same raw
+accounting facts.
+
+A line carries the **objective accounting properties** of the
+transaction. The service applies declaration-specific rules (account
+code -> sale/purchase/goods/services, partner country -> intra-EU /
+export, etc.) to figure out which ANAF row the line feeds.
+
+VAT regime nuances that the four core flags (``vat_rate``,
+``vat_on_payment``, ``exempted``, ``deductibility``) can't express
+travel via three additional booleans/enums:
+
+* ``reverse_charge`` -- domestic reverse-charge cases (cereals, scrap,
+  electronics, etc.); the line still has a positive ``vat_rate`` but
+  the *seller* doesn't collect VAT.
+* ``exempt_with_deduction_right`` -- only meaningful when
+  ``exempted=True``; distinguishes exports / intracom from medical /
+  educational exemptions.
+* ``regime`` -- special regimes: standard, margin scheme, second-hand,
+  travel agency, special.
+"""
+from __future__ import annotations
+
+from datetime import date
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+_VALID_VAT_RATES = {0, 5, 9, 11, 19, 21, 24}
+_VALID_DEDUCTIBILITY = {0, 50, 100}
+
+VatRegime = Literal["standard", "margin", "second_hand", "travel", "special"]
+
+
+class Partner(BaseModel):
+    """Counterparty directory entry."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    cui: str = Field(min_length=1, max_length=50, description="Partner VAT number, with country prefix.")
+    country: str = Field(min_length=2, max_length=2, description="ISO-3166-1 alpha-2 country code (uppercase).")
+    name: str = Field(min_length=1, max_length=200)
+
+    @field_validator("country", mode="before")
+    @classmethod
+    def _upper_country(cls, v: str) -> str:
+        if not isinstance(v, str):
+            raise TypeError("country must be a string")
+        return v.strip().upper()
+
+
+class MoveLine(BaseModel):
+    """One accounting line.
+
+    ``deductibility`` is purchase-side only (``null`` on sale lines).
+    ``exempt_with_deduction_right`` is meaningful only when ``exempted=True``.
+    ``reverse_charge`` is for domestic reverse-charge regimes (intracom
+    operations are derived from the partner's country, not this flag).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    account_code: str = Field(min_length=1, max_length=20)
+    tax_base: float = Field(description="Signed base amount (negative for refunds/returns).")
+    vat_amount: float = Field(default=0.0)
+    vat_rate: int = Field(description="VAT rate as integer percentage.")
+    vat_on_payment: bool = Field(default=False)
+    exempted: bool = Field(default=False)
+    deductibility: int | None = Field(default=None)
+    reverse_charge: bool = Field(default=False)
+    exempt_with_deduction_right: bool = Field(default=False)
+    regime: VatRegime = Field(default="standard")
+    correction: bool = Field(
+        default=False,
+        description=(
+            "True when this line is a *regularization* of an earlier-period "
+            "invoice (Odoo's ``l10n_ro_correction`` flag). D300 routes "
+            "corrections to dedicated rows: R2 for intracom sale fixes, "
+            "R11 for domestic sale fixes, R14 for exempt-no-deduction fixes."
+        ),
+    )
+    product_anaf_code: str | None = Field(default=None)
+    # Canonical ANAF operation type from the Odoo localization
+    # (``l10n_ro_operation_type``: L/A/LS/AS/AI/V/C/N). When set it is
+    # authoritative; consumers fall back to a flag-based heuristic only when
+    # it is absent.
+    oper_type: str | None = Field(default=None)
+
+    @field_validator("vat_rate")
+    @classmethod
+    def _validate_rate(cls, v: int) -> int:
+        if v not in _VALID_VAT_RATES:
+            raise ValueError(
+                f"vat_rate must be one of {sorted(_VALID_VAT_RATES)}, got {v!r}"
+            )
+        return v
+
+    @field_validator("deductibility")
+    @classmethod
+    def _validate_ded(cls, v: int | None) -> int | None:
+        if v is None:
+            return v
+        if v not in _VALID_DEDUCTIBILITY:
+            raise ValueError(
+                f"deductibility must be one of {sorted(_VALID_DEDUCTIBILITY)} "
+                f"or null, got {v!r}"
+            )
+        return v
+
+
+class Move(BaseModel):
+    """One accounting move with its lines."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str = Field(min_length=1, max_length=100)
+    date: date
+    partner_cui: str = Field(min_length=1, max_length=50)
+    lines: list[MoveLine] = Field(default_factory=list)
+    # Whether the partner's fiscal code is shown on the document. When False
+    # (e.g. a simplified receipt / bon fiscal without CUI) the operation is
+    # anonymous for D394 -- reported in the aggregate fields, not per-partner.
+    has_vat_number: bool = Field(default=True)
+    # Canonical ANAF tip_partener (1..4) from the Odoo localization
+    # (``l10n_ro_partner_type``). Authoritative when set; consumers fall back
+    # to a cui-based heuristic only when absent.
+    partner_kind: str | None = Field(default=None)
+    # ANAF document type (D394 ``tip_document``/``document_N``) from the Odoo
+    # localization (``l10n_ro_invoice_origin_d394``): 1=facturi, 2=borderouri,
+    # 3=file carnet comercializare, 4=contracte, 5=alte documente. Required for
+    # tip_partener=2 N rows; defaults to "1" (regular invoice).
+    doc_type: str | None = Field(default=None)
+
+
+class MovesData(BaseModel):
+    """Common ``data`` envelope: partners directory + moves list.
+
+    Each declaration extends or wraps this with its own validations.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    partners: list[Partner] = Field(default_factory=list)
+    moves: list[Move] = Field(default_factory=list)
+
+    @field_validator("partners")
+    @classmethod
+    def _unique_partner_cui(cls, v: list[Partner]) -> list[Partner]:
+        seen: set[str] = set()
+        for p in v:
+            if p.cui in seen:
+                raise ValueError(f"duplicate partner CUI: {p.cui}")
+            seen.add(p.cui)
+        return v

nexterp_declarations/base/envelope_v2.py

@@ -0,0 +1,81 @@
+"""Alternate envelope schemas (Company, Period) shaped after the ANAF XSD.
+
+The primary :mod:`base.schemas` exposes a structured ``Company`` (with a
+nested ``Address``) and a ``Period`` whose granularity is selected by
+``month``/``quarter``/``semester``/``annual``. Those are the public
+contract used by D100 and D394.
+
+D-series declarations ported from the ``duk_validation`` service expect
+a *flatter* shape that mirrors the ANAF XSD attribute names verbatim
+(``cui``, ``den``, ``adresa``, ``telefon``, ``regCom``, ``caen``,
+``codTT``) and a date-range ``Period`` (``date_from``/``date_to``).
+Rather than break the existing D100/D394 contracts, this module ships
+those schemas alongside.
+
+Naming policy: any field that maps to an ANAF XSD attribute keeps the
+ANAF name verbatim. Service-level fields use snake_case.
+"""
+from __future__ import annotations
+
+from datetime import date
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class CompanyV2(BaseModel):
+    """Identity attributes of the legal entity, named as in the ANAF XSD.
+
+    Used by D300 (and other D-series declarations ported from the
+    duk_validation service). The service is multi-tenant by payload:
+    every request carries the full company identity, no per-customer
+    state is held server-side.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    cui: str = Field(
+        description="CUI / VAT number, digits only. A leading 'RO' is "
+        "stripped before validation."
+    )
+    den: str = Field(min_length=1, max_length=200, description="Denumire")
+    adresa: str = Field(min_length=1, max_length=500)
+    telefon: str = Field(default="", max_length=50)
+    regCom: str = Field(default="", max_length=50, description="Registru Comertului")
+    caen: str = Field(default="", max_length=10, description="CAEN code, 4 digits")
+    codTT: int = Field(
+        ge=1, le=99, description="ANAF order code of the county (judet). 1..52."
+    )
+
+    @field_validator("cui", mode="before")
+    @classmethod
+    def _strip_ro(cls, v: str) -> str:
+        if not isinstance(v, str):
+            raise TypeError("cui must be a string")
+        v = v.strip().upper()
+        if v.startswith("RO"):
+            v = v[2:]
+        if not v.isdigit():
+            raise ValueError("cui must contain only digits (after stripping 'RO')")
+        return v
+
+
+class PeriodV2(BaseModel):
+    """Date-range period used by D-series declarations.
+
+    The ANAF XSDs use ``luna``/``an`` and a ``tip_decont`` derived from
+    the period length; we derive both from a (``date_from``, ``date_to``)
+    pair so callers don't have to know the encoding.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    date_from: date
+    date_to: date
+
+    @property
+    def year(self) -> int:
+        return self.date_to.year
+
+    @property
+    def month(self) -> int:
+        return self.date_to.month

nexterp_declarations/base/exceptions.py

@@ -0,0 +1,13 @@
+"""Errors raised by the package. Map cleanly to UI errors on the caller side."""
+
+
+class DeclarationError(Exception):
+    """Base for everything raised here."""
+
+
+class ValidationError(DeclarationError):
+    """Input data does not satisfy the declaration's contract."""
+
+
+class GenerationError(DeclarationError):
+    """Generator failed to produce the output (XML build, signing, etc.)."""