anncsu-sdk 0.0.10.dev2__tar.gz → 0.0.10.dev4__tar.gz

{anncsu_sdk-0.0.10.dev2 → anncsu_sdk-0.0.10.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anncsu-sdk
-Version: 0.0.10.dev2
+Version: 0.0.10.dev4
 Summary: ANNCSU Software Development Kit for API consumption
 Author-email: Francesco Bartoli <francesco.bartoli@geobeyond.it>
 License-File: LICENSE

{anncsu_sdk-0.0.10.dev2 → anncsu_sdk-0.0.10.dev4}/docs/CLI.md

@@ -1789,15 +1789,18 @@ anncsu pa accesso --prognazacc 28586543 --raw
 
 #### `anncsu pa accessi`
 
-List access points (civici) for a street. First searches for the street by municipality code and partial name, then lists all access points.
+List access points (civici) for a street. Resolve the street either by `--denom` (municipality code + base64 partial name) **or** directly by `--prognaz`, then list its access points.
 
 ```bash
-# List all access points for a street
+# List access points by street name (base64)
 anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE="
 
 # Filter by partial civic number
 anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --accparz "1"
 
+# Target a specific odonimo directly by its national progressive
+anncsu pa accessi --codcom H501 --prognaz 920585 --accparz 95
+
 # Production with JSON output
 anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --production --json
 ```
@@ -1807,7 +1810,8 @@ anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --production --json
 | Option | Required | Description |
 |--------|----------|-------------|
 | `--codcom`, `-c` | Yes | Codice Belfiore del comune |
-| `--denom`, `-d` | Yes | Denominazione parziale dell'odonimo - base64 encoded |
+| `--denom`, `-d` | One of denom/prognaz | Denominazione parziale dell'odonimo - base64 encoded |
+| `--prognaz`, `-p` | One of denom/prognaz | Progressivo nazionale dell'odonimo (targets it directly) |
 | `--accparz`, `-a` | No | Valore parziale del civico (default: "1") |
 | `--validation/--production` | No | Environment (default: validation) |
 | `--token-endpoint`, `-e` | No | PDND token endpoint URL |
@@ -1816,6 +1820,10 @@ anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --production --json
 | `--json` | No | Output as JSON |
 | `--raw` | No | Print raw API responses to stderr (odonimo + accessi) |
 
+> **`--denom` is a substring search and can be ambiguous.** E.g. `--denom` for "taranto" matches both `VIA NINO TARANTO` and `VIA TARANTO`. When more than one odonimo matches, the command does **not** silently pick the first: it lists every candidate with its `--prognaz` and exits, so you can re-run targeting the exact one. `--denom` and `--prognaz` are mutually exclusive; provide exactly one.
+
+> **`--accparz` is a substring match on the civico** (not a prefix): `--accparz 9` returns 9, 19, 29, … 91, 97. To list *all* accessi you currently have to union several `accparz` values (e.g. `0`–`9`) and de-duplicate by `prognazacc` — the API has no "list all" wildcard. The esponente comes back in the `Esp.` column: civico 95 may yield three rows (95, 95/A, 95/D), each a distinct `prognazacc`.
+
 **Output columns:** Prog. Naz. Acc., Civico, Esp., Specif., Metrico, Coord X, Coord Y, Quota, Metodo
 
 **JSON output example:**
@@ -2184,17 +2192,17 @@ anncsu odonimo insert --codcom A062 --dug VIA \
 Options:
 
 - `--codcom, -c` - Codice comune (Belfiore code, e.g. `A062`) **[required]**
-- `--dug` - DUG (e.g. `VIA`, `PIAZZA`, `STRADA`) **[required for I/R]**
-- `--denom-delibera` - Denominazione delibera (uppercase applied server-side)
-- `--denom-in-lingua-1` / `--denom-in-lingua-2` - Odonimo in lingua (per comuni bi/tri-lingua)
-- `--denom-localita` - Denominazione località (uppercase applied)
-- `--codice-comunale` - Codifica comunale dell'odonimo (no uppercase)
-- `--provv-data` - Data del provvedimento (formato `dd/MM/yyyy`)
+- `--dug` - DUG (e.g. `VIA`, `PIAZZA`, `STRADA`; max 30 char) **[required for I/R]**
+- `--denom-delibera` - Denominazione ufficiale da delibera, **senza DUG** (e.g. `DELLE ORCHIDEE` for "VIA DELLE ORCHIDEE"; max 120 char, uppercase applied server-side)
+- `--denom-in-lingua-1` / `--denom-in-lingua-2` - Odonimo in lingua, **DUG inclusa** (per comuni bi/tri-lingua; max 150 char, uppercase applied)
+- `--denom-localita` - Denominazione località (max 151 char — OAS quirk; uppercase applied)
+- `--codice-comunale` - Codifica comunale dell'odonimo (max 30 char, no uppercase)
+- `--provv-data` - Data del provvedimento (valid calendar date, formato `dd/MM/yyyy`)
 - `--provv-protocollo` - Protocollo del provvedimento (max 70 char, no uppercase)
-- `--provv-flag-delibera` - Flag delibera (`0`-`4`); `0` and `1` make `--provv-data` + `--provv-protocollo` required
-- `--prefettura-data` - Data prefettura (required if `--prefettura-protocollo`)
-- `--prefettura-protocollo` - Protocollo prefettura (required if `--prefettura-data`)
-- `--data-valid-amm` - Data validità amministrativa (formato `dd/MM/yyyy`)
+- `--provv-flag-delibera` - Flag delibera, **only `0`-`4` accepted**; `0` and `1` make `--provv-data` + `--provv-protocollo` required
+- `--prefettura-data` - Data prefettura (`dd/MM/yyyy`; required if `--prefettura-protocollo`)
+- `--prefettura-protocollo` - Protocollo prefettura (max 70 char; required if `--prefettura-data`)
+- `--data-valid-amm` - Data validità amministrativa (`dd/MM/yyyy`). Must be **≤ today** for every operation (checked client-side); for R it must additionally be ≥ the previous validity date (checked server-side)
 - `--token-endpoint, -e` - PDND token endpoint URL
 - `--server-url, -s` - API server URL (auto-discovered from voucher if omitted)
 - `--validation/--production` - Use validation (UAT) or production environment
@@ -2203,6 +2211,8 @@ Options:
 - `--raw` - Print raw API response to stderr
 - `--dry-run` - I + S rollback (see `--dry-run` section below)
 
+All constraints above (maxLength, flag range, date format, future dates) are validated **client-side before any API call** via `ValidatedOdonimo` — invalid input exits with code 1 and a `Validation error:` message, without consuming PDND tokens. See [sdk-odonimi.md](sdk-odonimi.md#business-rules) for the full rule list.
+
 JSON output:
 
 ```json
@@ -2233,10 +2243,22 @@ anncsu odonimo update --codcom A062 \
 
 Options:
 
-- All `insert` options (except `--prognaz` is required, not assigned)
-- `--prognaz, -p` - Progressivo nazionale dell'odonimo (required unless `--auto-resolve`)
+- All `insert` options (same fields, constraints and client-side validation — see the `insert` option list above)
+- `--prognaz, -p` - Progressivo nazionale dell'odonimo (max 10 char; required unless `--auto-resolve`)
 - `--auto-resolve` - Resolve `--prognaz` via PA from `--codcom` + `--denom` (see `--auto-resolve` section)
-- `--denom` - Base64-encoded denomination used with `--auto-resolve`
+- `--denom` - Base64-encoded denomination used with `--auto-resolve` (lookup only — the **new** denomination goes in `--denom-delibera`)
+
+Note: `R` is a **replace**, not a partial patch — read the current state first (`anncsu pa odonimo`) and re-pass the values you want to keep.
+
+Server-side errors (HTTP 400/404/500) are rendered with the structured ANNCSU fields:
+
+```
+Errore ANNCSU (codice 23): Errore di validazione: ...
+```
+
+When an `R` with `--data-valid-amm` fails server-side, the CLI also prints a hint about the rule it cannot check client-side: *per l'aggiornamento (R), `data_valid_amm` deve essere ≥ della precedente data di validità dell'odonimo*. Non-ANNCSU error bodies (e.g. RFC 7807 from the GovWay gateway) are shown raw.
+
+> **Known limitation — clearing `codice_comunale`**: `codice_comunale` is the only *nullable* field of the request schema (three states: omitted / value / explicit `null`). The CLI can omit it or set a value, but cannot send an explicit `"codice_comunale": null` — i.e. there is no way to **clear** an existing codifica comunale via `update`. If this becomes a real use case, a dedicated flag (e.g. `--clear-codice-comunale`) is the planned solution. The SDK supports it already: `Richiesta(codice_comunale=None, ...)` with the field explicitly set serializes to `null`.
 
 #### `anncsu odonimo delete`
 
@@ -2301,6 +2323,12 @@ Unlike `accesso --dry-run` (which operates on an existing accesso via test+resto
 
 **For `update --dry-run`**: `--prognaz` and `--auto-resolve` are ignored (a warning is printed) because the R is always applied to the fake odonimo generated by the preceding I.
 
+**Client-side validation in dry-run**: user data is validated via `ValidatedOdonimo` (same rules as the real commands — maxLength, flag range, date format, future dates) before being sent. For `update --dry-run` the user R payload is validated **after** the fake I has been created: on validation error the CLI prints `Validation error (user R):`, attempts an emergency S cleanup of the fake odonimo, and exits 1.
+
+**Server error rendering in dry-run**: unlike the real commands (which render `Errore ANNCSU (codice N): messaggio` plus the `data_valid_amm` hint), a server rejection inside a dry-run step is captured into that step's result — e.g. `update_op.messaggio = "Update exception: <raw body>"` — so the cycle can continue with the S cleanup. Check `test_op` / `update_op` / `rollback` in the JSON output for the per-step outcome.
+
+> **Tip — reproducing the `data_valid_amm` server rule safely**: the fake odonimo is created *today*, so its current validity date is the creation date. Running `update --dry-run --data-valid-amm <past date>` makes the R violate the server rule *data_valid_amm ≥ precedente* on the fictitious odonimo — a safe way to capture the real ANNCSU error code and message without touching real data.
+
 Examples:
 
 ```bash

{anncsu_sdk-0.0.10.dev2 → anncsu_sdk-0.0.10.dev4}/docs/VALIDATION.md

@@ -2,6 +2,8 @@
 
 The ANNCSU SDK implements a hybrid validation approach to ensure data quality for both API requests and responses.
 
+> **Write operations (odonimi/accessi)**: the business-rule validation for the *aggiornamento* APIs lives in dedicated models — `ValidatedOdonimo` (rules I/R/S, maxLength, flag delibera 0-4, date `dd/MM/yyyy`, `data_valid_amm` non-future) and `ValidatedAccesso`. See [sdk-odonimi.md § Validazione Odonimo](sdk-odonimi.md#validazione-odonimo) for the full rule list and error classes. This document covers the *consultazione* (PA) input/response validation.
+
 ## Overview
 
 ### Phase 1: Input Validation (Always Enabled)

{anncsu_sdk-0.0.10.dev2 → anncsu_sdk-0.0.10.dev4}/docs/sdk-odonimi.md

@@ -257,6 +257,28 @@ def is_success(response, tipo_operazione: str) -> bool:
 
 Una check ingenua `esito == "0"` produce un **false-negative** sulle S che vanno a buon fine — è una causa nota di errori in codice cliente.
 
+## Errori HTTP (`RispostaErrore`)
+
+I rifiuti del server (HTTP **400** richiesta non valida, **404** odonimo non trovato, **500** errore interno) arrivano come `application/problem+json`, ma **non è RFC 7807**: il contratto ANNCSU definisce uno schema custom con tre campi (`id`, `codice`, `messaggio`). L'SDK li trasforma nell'eccezione `RispostaErrore`:
+
+```python
+from anncsu.odonimi.errors import RispostaErrore
+
+try:
+    response = sdk.anncsu.gestione_anncsu_odonimi_pdnd(richiesta=richiesta)
+except RispostaErrore as e:
+    print(e.data.codice)     # es. "23" — codice dal catalogo errori ANNCSU
+    print(e.data.messaggio)  # es. "Errore di validazione: ..."
+    # str(e) è il body JSON grezzo della risposta
+```
+
+Attenzione a due cose:
+
+- `str(e)` (e quindi un log naive `f"errore: {e}"`) mostra il **body grezzo**, non i campi strutturati — usare sempre `e.data.codice` / `e.data.messaggio`.
+- Se il body non è conforme allo schema ANNCSU (es. un RFC 7807 vero emesso dal gateway GovWay, con `type`/`title`/`detail`), `e.data.codice` e `e.data.messaggio` sono `None`: in quel caso l'unica informazione utile è `str(e)`.
+
+Caso tipico di 400 su `R`: `data_valid_amm` inferiore alla precedente data di validità dell'odonimo — regola che il client **non può** verificare (richiede il valore storico). La CLI in questo caso mostra `Errore ANNCSU (codice N): messaggio` più una nota che spiega la regola.
+
 ## Validazione Odonimo
 
 L'SDK fornisce un modello `ValidatedOdonimo` con validazione delle business rules ANNCSU. Va sempre usato prima della chiamata API per intercettare errori a livello locale.
@@ -273,8 +295,11 @@ Le regole sono applicate in ordine in un singolo `@model_validator(mode="after")
 6. **Per `S`**: `dug` **vietato** — altrimenti `DugNotAllowedForDeleteError`
 7. Se `provvedimento.flag_delibera ∈ {"0","1"}`: `data` + `protocollo` obbligatori — altrimenti `FlagDeliberaMissingFieldsError`
 8. `aut_prefettura.data_pref` ↔ `protocollo_pref` mutex (entrambi o nessuno) — altrimenti `PrefetturaMutexError`
+9. `provvedimento.flag_delibera`, se valorizzato, deve essere `"0"`..`"4"` (OAS: "valori numerici da 0 a 4") — altrimenti `FlagDeliberaInvalidValueError`
+10. I campi data (`provvedimento.data`, `aut_prefettura.data_pref`, `data_valid_amm`), se valorizzati, devono essere date di calendario valide in formato **`dd/MM/yyyy`** (es. `"10/10/2023"`; rifiutati `"2023-10-10"`, `"31/02/2024"`) — altrimenti `InvalidDateFormatError`
+11. `data_valid_amm` non può essere nel futuro, per **tutte** le operazioni — altrimenti `DataValidAmmInFutureError`. L'OAS dice "minore o uguale della data corrente per inserimento e soppressione. Per aggiornamento **anche** >= della precedente": l'"anche" è additivo, quindi il vincolo ≤ data corrente vale pure per `R`
 
-Le regole su `data_valid_amm` (`≤` data corrente per `I/S`, `≥` precedente per `R`) sono **delegate al server** (richiedono date arithmetic e lookup storici non disponibili lato client).
+La metà R-only della regola su `data_valid_amm` (`≥` della precedente) resta **delegata al server**: richiede il valore storico precedente, non disponibile lato client.
 
 ### Uso del Modello Validato
 
@@ -338,6 +363,9 @@ from anncsu.odonimi.errors.odonimo_validation import (
     OdonimoMaxLengthError,          # campo eccede maxLength OAS
     FlagDeliberaMissingFieldsError, # flag_delibera 0/1 senza data+protocollo
     PrefetturaMutexError,           # data_pref ↔ protocollo_pref mutex
+    FlagDeliberaInvalidValueError,  # flag_delibera fuori range 0-4
+    InvalidDateFormatError,         # data non valida o non dd/MM/yyyy
+    DataValidAmmInFutureError,      # data_valid_amm nel futuro per I/S
 )
 
 # Catch specifico

{anncsu_sdk-0.0.10.dev2 → anncsu_sdk-0.0.10.dev4}/docs/sdk-pa.md

@@ -178,16 +178,36 @@ if result.res == "OK":
 else:
     print(f"Odonimo non trovato")
 
-# 5. Elenco accessi per l'odonimo
+# 5. Elenco accessi per l'odonimo.
+# NB: ``accparz`` è OBBLIGATORIO (match per sottostringa sul civico) — non
+# esiste un valore "tutti". Vedi la nota sotto.
 accessi = sdk.queryparam.elenco_accessi_get_query_param(
     codcom=codcom,
     denom=denom,
+    accparz="1",  # es. tutti i civici che contengono "1"
 )
 
 for accesso in accessi.data:
-    print(f"Civico: {accesso.civico}, Coordinate: ({accesso.coord_x}, {accesso.coord_y})")
+    # L'esponente torna nel campo dedicato ``esp`` (civico e esponente sono
+    # separati): es. civico="95", esp="A" → 95/A.
+    print(
+        f"Civico: {accesso.civico}{('/' + accesso.esp) if accesso.esp else ''}, "
+        f"Coordinate: ({accesso.coord_x}, {accesso.coord_y})"
+    )
 ```
 
+> **`accparz` è obbligatorio ed è un match per sottostringa** (non prefisso): `accparz="9"`
+> ritorna `9, 19, 29, …, 91, 97` (tutti i civici che *contengono* "9"). **Non esiste un
+> wildcard "elenca tutti"**: per ottenere l'elenco completo bisogna unire più valori di
+> `accparz` (es. `"0"`–`"9"`) e deduplicare per `prognazacc`. Lo stesso vale per
+> `elenco_accessi_prog` (per `prognaz`).
+>
+> **Esponente / specificità**: un accesso è identificato da `civico` (numero) + `esp`
+> (esponente) + `specif`. Più accessi possono condividere lo stesso `civico` con `esp`
+> diversi → `prognazacc` distinti, **tutti** restituiti dalla stessa `accparz`. Es. su
+> VIA TARANTO (H501, prognaz `920585`) il civico `95` ritorna tre accessi: `95`, `95/A`,
+> `95/D`.
+
 ## Gestione Errori
 
 ```python

{anncsu_sdk-0.0.10.dev2 → anncsu_sdk-0.0.10.dev4}/src/anncsu/cli/commands/odonimo.py

@@ -48,6 +48,7 @@ from anncsu.common.modi import AuditContext, ModIConfig
 from anncsu.common.security import Security as PASecurity
 from anncsu.common.session import get_config_dir
 from anncsu.odonimi import AnncsuOdonimi
+from anncsu.odonimi.errors import RispostaErrore as OdonimiRispostaErrore
 from anncsu.odonimi.models import Security
 from anncsu.odonimi.models.richiestaoperazione import (
     AutPrefettura,
@@ -1364,6 +1365,36 @@ def _build_richiesta(
     )
 
 
+def _render_server_error(
+    e: OdonimiRispostaErrore,
+    *,
+    tipo_operazione: str,
+    richiesta: Richiesta,
+) -> None:
+    """Render an ANNCSU ``RispostaErrore`` (HTTP 400/404/500) readably.
+
+    The contract's problem+json carries structured ``codice`` +
+    ``messaggio``; bodies without them (e.g. RFC 7807 from the gateway)
+    fall back to the raw body. For R with ``data_valid_amm`` set, the
+    server-side rule that the client cannot check is surfaced as a hint.
+    """
+    codice = getattr(e.data, "codice", None)
+    messaggio = getattr(e.data, "messaggio", None)
+    if codice or messaggio:
+        error_console.print(
+            f"[red]Errore ANNCSU[/red] (codice {codice or '—'}): {messaggio or '—'}"
+        )
+    else:
+        error_console.print(f"[red]Error:[/red] {e}")
+
+    if tipo_operazione == "R" and richiesta.data_valid_amm:
+        error_console.print(
+            "[yellow]Nota:[/yellow] per l'aggiornamento (R), 'data_valid_amm' "
+            "deve essere maggiore o uguale alla precedente data di validità "
+            "dell'odonimo (regola verificata dal server ANNCSU)."
+        )
+
+
 def _execute_operation(
     *,
     tipo_operazione: str,
@@ -1395,6 +1426,9 @@ def _execute_operation(
 
     try:
         response = sdk.anncsu.gestione_anncsu_odonimi_pdnd(richiesta=richiesta)
+    except OdonimiRispostaErrore as e:
+        _render_server_error(e, tipo_operazione=tipo_operazione, richiesta=richiesta)
+        raise typer.Exit(1) from None
     except Exception as e:
         error_console.print(f"[red]Error:[/red] API call failed: {e}")
         raise typer.Exit(1) from None
@@ -1532,7 +1566,10 @@ def insert(
         str | None,
         typer.Option(
             "--data-valid-amm",
-            help="Data di validità amministrativa (dd/MM/yyyy).",
+            help=(
+                "Data di validità amministrativa (dd/MM/yyyy). Non può "
+                "essere nel futuro (regola ANNCSU per I)."
+            ),
         ),
     ] = None,
     token_endpoint: Annotated[
@@ -1743,7 +1780,12 @@ def update(
         str | None,
         typer.Option(
             "--data-valid-amm",
-            help="Data di validità amministrativa (dd/MM/yyyy).",
+            help=(
+                "Data di validità amministrativa (dd/MM/yyyy). Non può "
+                "essere nel futuro; inoltre per l'odonimo esistente deve "
+                "essere >= della precedente data di validità (quest'ultima "
+                "regola è verificata dal server ANNCSU)."
+            ),
         ),
     ] = None,
     token_endpoint: Annotated[
@@ -1916,7 +1958,10 @@ def delete(
         str | None,
         typer.Option(
             "--data-valid-amm",
-            help="Data di fine validità (dd/MM/yyyy). Default: data corrente.",
+            help=(
+                "Data di fine validità (dd/MM/yyyy). Default: data "
+                "corrente. Non può essere nel futuro (regola ANNCSU per S)."
+            ),
         ),
     ] = None,
     token_endpoint: Annotated[

{anncsu_sdk-0.0.10.dev2 → anncsu_sdk-0.0.10.dev4}/src/anncsu/cli/commands/pa.py

@@ -360,13 +360,28 @@ def accessi(
         ),
     ],
     denom: Annotated[
-        str,
+        str | None,
         typer.Option(
             "--denom",
             "-d",
-            help="Denominazione anche parziale dell'odonimo - base64 encoded.",
+            help=(
+                "Denominazione anche parziale dell'odonimo - base64 encoded. "
+                "Mutually exclusive with --prognaz."
+            ),
         ),
-    ],
+    ] = None,
+    prognaz: Annotated[
+        str | None,
+        typer.Option(
+            "--prognaz",
+            "-p",
+            help=(
+                "Progressivo nazionale dell'odonimo. Use it to target a "
+                "specific odonimo directly (skips the --denom search and its "
+                "ambiguity). Mutually exclusive with --denom."
+            ),
+        ),
+    ] = None,
     accparz: Annotated[
         str | None,
         typer.Option(
@@ -419,12 +434,16 @@ def accessi(
 ) -> None:
     """List access points for a street.
 
-    First searches for the street (odonimo) by municipality code and name,
-    then lists all access points (civici) for that street.
+    Resolve the street (odonimo) either by ``--denom`` (municipality code +
+    base64 name) or directly by ``--prognaz``, then list its access points
+    (civici). ``--denom`` is a substring search: when it matches more than one
+    odonimo the command stops and lists the candidates so you can re-run with
+    ``--prognaz`` (it never silently picks the first match).
 
     Example:
         anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE="
         anncsu pa accessi --codcom I501 --denom "VklBIFJPTUE=" --accparz "1"
+        anncsu pa accessi --codcom H501 --prognaz 920585 --accparz 95
     """
     if server_url is None:
         server_url = (
@@ -440,43 +459,92 @@ def accessi(
         verify_ssl=not no_verify_ssl,
     )
 
-    # Step 1: Find odonimo prognaz
-    try:
-        odonimo_response = sdk.queryparam.elencoodonimiprog_get_query_param(
-            codcom=codcom,
-            denomparz=denom,
+    # Step 1: Resolve the odonimo — either directly via --prognaz or by
+    # searching --denom. The denom search can match multiple odonimi (it is a
+    # substring match), so we never silently pick the first: we error and ask
+    # the user to disambiguate with --prognaz.
+    if prognaz and denom:
+        error_console.print(
+            "[red]Error:[/red] --denom and --prognaz are mutually exclusive."
         )
-    except Exception as e:
-        error_console.print(f"[red]Error:[/red] Odonimo search failed: {e}")
-        raise typer.Exit(1) from None
+        raise typer.Exit(1)
 
-    if raw_output:
-        _print_raw(odonimo_response, "Raw odonimo response")
+    if prognaz:
+        try:
+            odonimo_response = sdk.queryparam.prognazarea_get_query_param(
+                prognaz=prognaz,
+            )
+        except Exception as e:
+            error_console.print(f"[red]Error:[/red] Odonimo lookup failed: {e}")
+            raise typer.Exit(1) from None
+
+        if raw_output:
+            _print_raw(odonimo_response, "Raw odonimo response")
+
+        if not odonimo_response.data:
+            error_console.print(
+                f"[red]No results:[/red] No odonimo found for prognaz={prognaz}"
+            )
+            raise typer.Exit(1) from None
 
-    if not odonimo_response.data:
+        odonimo_data = odonimo_response.data[0]
+        resolved_prognaz = prognaz
+    elif denom:
+        try:
+            odonimo_response = sdk.queryparam.elencoodonimiprog_get_query_param(
+                codcom=codcom,
+                denomparz=denom,
+            )
+        except Exception as e:
+            error_console.print(f"[red]Error:[/red] Odonimo search failed: {e}")
+            raise typer.Exit(1) from None
+
+        if raw_output:
+            _print_raw(odonimo_response, "Raw odonimo response")
+
+        if not odonimo_response.data:
+            error_console.print(
+                f"[red]No results:[/red] No odonimo found for codcom={codcom}, "
+                f"denom={denom}"
+            )
+            raise typer.Exit(1) from None
+
+        matches = list(odonimo_response.data)
+        if len(matches) > 1:
+            error_console.print(
+                f"[red]Ambiguous:[/red] {len(matches)} odonimi match codcom="
+                f"{codcom}, denom={denom}. Re-run with --prognaz to pick one:"
+            )
+            for m in matches:
+                error_console.print(
+                    f"  --prognaz {m.prognaz}  →  {m.dug or ''} {m.denomuff or ''}"
+                )
+            raise typer.Exit(1)
+
+        odonimo_data = matches[0]
+        resolved_prognaz = odonimo_data.prognaz
+    else:
         error_console.print(
-            f"[red]No results:[/red] No odonimo found for codcom={codcom}, denom={denom}"
+            "[red]Error:[/red] Provide --denom (street name, base64) or "
+            "--prognaz (national progressive of the odonimo)."
         )
-        raise typer.Exit(1) from None
-
-    odonimo_data = odonimo_response.data[0]
-    prognaz = odonimo_data.prognaz
+        raise typer.Exit(1)
 
-    if not prognaz:
+    if not resolved_prognaz:
         error_console.print("[red]Error:[/red] Odonimo found but no prognaz available")
         raise typer.Exit(1) from None
 
     if not json_output:
         console.print(
             f"[bold]Street:[/bold] {odonimo_data.dug} {odonimo_data.denomuff} "
-            f"(prognaz={prognaz})\n"
+            f"(prognaz={resolved_prognaz})\n"
         )
 
     # Step 2: List accessi for this odonimo
     search_accparz = accparz if accparz else "1"
     try:
         accessi_response = sdk.queryparam.elencoaccessiprog_get_query_param(
-            prognaz=prognaz,
+            prognaz=resolved_prognaz,
             accparz=search_accparz,
         )
     except Exception as e:
@@ -488,7 +556,8 @@ def accessi(
 
     if not accessi_response.data:
         error_console.print(
-            f"[red]No results:[/red] No access points found for prognaz={prognaz}"
+            f"[red]No results:[/red] No access points found for "
+            f"prognaz={resolved_prognaz}"
         )
         raise typer.Exit(1) from None
 

{anncsu_sdk-0.0.10.dev2 → anncsu_sdk-0.0.10.dev4}/src/anncsu/odonimi/__init__.py

@@ -9,9 +9,12 @@ from ._version import (
 )
 from .errors.odonimo_validation import (
     CodcomRequiredError,
+    DataValidAmmInFutureError,
     DugNotAllowedForDeleteError,
     DugRequiredError,
+    FlagDeliberaInvalidValueError,
     FlagDeliberaMissingFieldsError,
+    InvalidDateFormatError,
     OdonimoMaxLengthError,
     OdonimoValidationError,
     PrefetturaMutexError,
@@ -35,9 +38,12 @@ __all__ = [
     "__user_agent__",
     "AnncsuOdonimi",
     "CodcomRequiredError",
+    "DataValidAmmInFutureError",
     "DugNotAllowedForDeleteError",
     "DugRequiredError",
+    "FlagDeliberaInvalidValueError",
     "FlagDeliberaMissingFieldsError",
+    "InvalidDateFormatError",
     "OdonimoMaxLengthError",
     "OdonimoValidationError",
     "PrefetturaMutexError",

{anncsu_sdk-0.0.10.dev2 → anncsu_sdk-0.0.10.dev4}/src/anncsu/odonimi/errors/odonimo_validation.py

@@ -175,6 +175,63 @@ class PrefetturaMutexError(OdonimoValidationError):
         )
 
 
+@dataclass
+class FlagDeliberaInvalidValueError(OdonimoValidationError):
+    """Raised when provvedimento.flag_delibera is not one of '0'..'4'.
+
+    Per OAS spec: "Flag della delibera (valori numerici da 0 a 4)".
+    """
+
+    value: str
+
+    def __str__(self) -> str:
+        return (
+            f"Il campo 'provvedimento.flag_delibera' deve essere un valore "
+            f"numerico da '0' a '4'. Valore fornito: {self.value!r}"
+        )
+
+
+@dataclass
+class InvalidDateFormatError(OdonimoValidationError):
+    """Raised when a date field is not a valid dd/MM/yyyy calendar date.
+
+    Applies to provvedimento.data, aut_prefettura.data_pref and
+    data_valid_amm (OAS examples: "10/10/2023", "08/10/2024").
+    """
+
+    field_name: str
+    value: str
+
+    def __str__(self) -> str:
+        return (
+            f"Il campo '{self.field_name}' deve essere una data valida nel "
+            f"formato dd/MM/yyyy (es. '10/10/2023'). "
+            f"Valore fornito: {self.value!r}"
+        )
+
+
+@dataclass
+class DataValidAmmInFutureError(OdonimoValidationError):
+    """Raised when data_valid_amm is in the future (any operation).
+
+    Per OAS spec: "minore o uguale della data corrente per inserimento e
+    soppressione. Per aggiornamento anche >= della precedente" — the
+    'anche' is additive, so the <= today bound applies to R as well.
+    The R-only half (">= della precedente") requires the server-side
+    historical value and is NOT checked client-side.
+    """
+
+    operazione: str
+    value: str
+
+    def __str__(self) -> str:
+        return (
+            f"Il campo 'data_valid_amm' non puo' essere nel futuro per "
+            f"tipo_operazione='{self.operazione}' (deve essere minore o "
+            f"uguale alla data corrente). Valore fornito: {self.value!r}"
+        )
+
+
 __all__ = [
     "OdonimoValidationError",
     "TipoOperazioneError",
@@ -185,4 +242,7 @@ __all__ = [
     "OdonimoMaxLengthError",
     "FlagDeliberaMissingFieldsError",
     "PrefetturaMutexError",
+    "FlagDeliberaInvalidValueError",
+    "InvalidDateFormatError",
+    "DataValidAmmInFutureError",
 ]