@seta-labs/geo 0.1.0-next.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @seta-labs/geo
 
+## 0.2.0
+
+- New `cadastreParcel({ lat, lng })` on `POST /cadastre/parcel`: what the AdE
+  cadastral map finds under a point (`tipologia`, the cadastral fields with
+  blanks cleared, the `raw` answer), served from the shared store when known.
+  A `503` with `code: 'CADASTRE_BLOCKED'` carries `Retry-After`.
+- New type aliases `CadastreParcelRequest` and `CadastreParcelResult`.
+
+## 0.1.0
+
+- Promote the SDK from `0.1.0-next.1` to the ordinary `latest` npm channel.
+  The Geo 0.4.10 HTTP contract, public SDK interfaces and runtime behavior are unchanged.
+- SDK releases publish only to npm. Consumers update their exact dependency
+  version and lockfile explicitly, then verify and release independently.
+
 ## 0.1.0-next.1
 
 ### Patch Changes

package/README.md

@@ -49,6 +49,7 @@ retain their own concurrency and retry policy.
 | `geocode`                                | `GeocodeRequest`                       |
 | `geocodeBatch`                           | `GeocodeBatchRequest`                  |
 | `reverseGeocode`                         | `ReverseGeocodeRequest`                |
+| `cadastreParcel`                         | `CadastreParcelRequest`                |
 | `territory.status`, `territory.datasets` | options only                           |
 | `territory.comuni`                       | optional `TerritoryComuniQuery`        |
 | `territory.quotazioni`                   | optional `TerritoryQuotazioniQuery`    |
@@ -57,23 +58,36 @@ retain their own concurrency and retry policy.
 | `territory.resolve`                      | `TerritoryResolveRequest`              |
 
 The package exports `createGeoClient`, `ApiError`, client/options interfaces,
-query types and the generated geocode/territory request and response aliases.
+query types and the generated geocode/cadastre/territory request and response aliases.
 The three service health routes are intentionally outside this SDK surface.
 OpenAPI remains authoritative: TypeScript provides static types, not runtime
 validation of received data. `include` may be omitted and defaults to `best`
 on the service.
 
 HTTP errors are `ApiError`; their body is JSON when parseable, otherwise text,
-or `undefined` for an empty response. Network failures, aborts and JSON parsing
+or `undefined` for an empty response. A `503` from `cadastreParcel` with
+`code: 'CADASTRE_BLOCKED'` means the cadastral map is refusing calls: its
+`Retry-After` header (and `retryAfterSeconds` in the body) says when to ask
+again. Network failures, aborts and JSON parsing
 errors retain their native types. Every Geo success operation requires a JSON
 result: an unexpected empty/204 success raises `SyntaxError`. The SDK logs no
 body, URL or credential automatically.
 
-Versioning is independent from the service. The initial `0.1.0-next.0` candidate
+Versioning is independent from the service. SDK `0.1.0`
 uses the HTTP contract of Geo service `0.4.10`. Declarations are bundled from the
 repository's generated types; installing the SDK needs no private workspace
 package. Distribution is public npm; the retained license is `UNLICENSED`.
 
 The SDK remains on `0.x` until an explicit decision to graduate to `1.0`.
-Prerelease candidates use the `next` channel; completing prerelease testing
-does not itself authorize a `1.0` version.
+Ordinary releases use the `latest` npm channel, without a prerelease suffix.
+Publishing the SDK does not deploy Geo or update, merge or release any consumer.
+
+Update explicitly from the consumer package directory:
+
+```sh
+pnpm add @seta-labs/geo@latest --save-exact
+```
+
+`latest` selects the version at update time; the manifest records that exact
+numeric version. Commit it together with the lockfile after the consumer's
+checks pass, and release the consumer independently.

package/dist/index.d.ts

@@ -111,6 +111,22 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    '/cadastre/parcel': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations['CadastreController_parcel'];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     '/territory/status': {
         parameters: {
             query?: never;
@@ -390,6 +406,36 @@ interface components {
                 [key: string]: unknown;
             }[] | null;
         };
+        CadastreParcelRequestDto: {
+            lat: number;
+            lng: number;
+        };
+        CadastreParcelResultDto: {
+            /** @description Canonical cache key: "lat,lng" rounded to 5 decimals (~1 m). */
+            query: string;
+            /**
+             * @description What lies under the point, verbatim from the map: PARTICELLA, STRADA, …
+             * @example PARTICELLA
+             */
+            tipologia: string;
+            /** @example B885 */
+            codComune: string | null;
+            /** @description Null when the map gives none: blanks and "null" strings are cleared. */
+            sezione: string | null;
+            /** @example 36 */
+            foglio: string | null;
+            /** @example G */
+            allegato: string | null;
+            sviluppo: string | null;
+            /** @example 5101 */
+            particella: string | null;
+            /** @description The map answer exactly as returned (blank SEZIONE and "null" strings included). */
+            raw: {
+                [key: string]: unknown;
+            };
+            /** @description True when the answer came from the cache, no map call. */
+            cached: boolean;
+        };
         TerritoryStatusDto: {
             /** @description Latest OMI publication loaded (`YYYY-S`), null while no supply is loaded. */
             semestre: string | null;
@@ -714,6 +760,51 @@ interface operations {
             };
         };
     };
+    CadastreController_parcel: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                'application/json': components['schemas']['CadastreParcelRequestDto'];
+            };
+        };
+        responses: {
+            /** @description What the AdE cadastral map finds under the point: a parcel, a street, … */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['CadastreParcelResultDto'];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description CADASTRE_UNAVAILABLE or CADASTRE_INVALID_REPLY: the map gave no answer. */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description CADASTRE_BLOCKED: the map is refusing calls; Retry-After says when to try again. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     TerritoryController_status: {
         parameters: {
             query?: never;
@@ -951,6 +1042,8 @@ type GeocodeResult = ApiSchemas['GeocodeResultDto'];
 type GeocodeBatchResponse = ApiSchemas['GeocodeBatchResponseDto'];
 type ReverseGeocodeRequest = ApiSchemas['ReverseGeocodeRequestDto'];
 type ReverseGeocodeResult = ApiSchemas['ReverseGeocodeResultDto'];
+type CadastreParcelRequest = ApiSchemas['CadastreParcelRequestDto'];
+type CadastreParcelResult = ApiSchemas['CadastreParcelResultDto'];
 type TerritoryStatus = ApiSchemas['TerritoryStatusDto'];
 type TerritoryResolveRequest = ApiSchemas['TerritoryResolveRequestDto'];
 type TerritoryResolveResponse = ApiSchemas['TerritoryResolveResponseDto'];
@@ -993,10 +1086,12 @@ interface GeoClient {
     geocode(input: GeocodeRequest, options?: RequestOptions): Promise<GeocodeResult>;
     geocodeBatch(input: GeocodeBatchRequest, options?: RequestOptions): Promise<GeocodeBatchResponse>;
     reverseGeocode(input: ReverseGeocodeRequest, options?: RequestOptions): Promise<ReverseGeocodeResult>;
+    /** What the AdE cadastral map finds under a point; 503 `CADASTRE_BLOCKED` carries Retry-After. */
+    cadastreParcel(input: CadastreParcelRequest, options?: RequestOptions): Promise<CadastreParcelResult>;
     territory: TerritoryClient;
 }
 
 declare function createGeoClient(options: GeoClientOptions): GeoClient;
 
 export { ApiError, createGeoClient };
-export type { GeoClient, GeoClientOptions, GeocodeBatchRequest, GeocodeBatchResponse, GeocodeRequest, GeocodeResult, RequestOptions, ReverseGeocodeRequest, ReverseGeocodeResult, TerritoryClient, TerritoryCompravendita, TerritoryCompravenditePage, TerritoryCompravenditeQuery, TerritoryComune, TerritoryComuneDetail, TerritoryComuneRiga, TerritoryComuniPage, TerritoryComuniQuery, TerritoryDatasets, TerritoryOmi, TerritoryPointResult, TerritoryQuotazione, TerritoryQuotazioniPage, TerritoryQuotazioniQuery, TerritoryResolveRequest, TerritoryResolveResponse, TerritoryStatus };
+export type { CadastreParcelRequest, CadastreParcelResult, GeoClient, GeoClientOptions, GeocodeBatchRequest, GeocodeBatchResponse, GeocodeRequest, GeocodeResult, RequestOptions, ReverseGeocodeRequest, ReverseGeocodeResult, TerritoryClient, TerritoryCompravendita, TerritoryCompravenditePage, TerritoryCompravenditeQuery, TerritoryComune, TerritoryComuneDetail, TerritoryComuneRiga, TerritoryComuniPage, TerritoryComuniQuery, TerritoryDatasets, TerritoryOmi, TerritoryPointResult, TerritoryQuotazione, TerritoryQuotazioniPage, TerritoryQuotazioniQuery, TerritoryResolveRequest, TerritoryResolveResponse, TerritoryStatus };

package/dist/index.js

@@ -70,6 +70,7 @@ function createGeoClient(options) {
     geocode: (input, request) => data(client.POST("/geocode", { ...request, body: input })),
     geocodeBatch: (input, request) => data(client.POST("/geocode/batch", { ...request, body: input })),
     reverseGeocode: (input, request) => data(client.POST("/geocode/reverse", { ...request, body: input })),
+    cadastreParcel: (input, request) => data(client.POST("/cadastre/parcel", { ...request, body: input })),
     territory: territory(client)
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@seta-labs/geo",
-    "version": "0.1.0-next.1",
+    "version": "0.2.0",
     "description": "Typed Fetch client for the Seta Geo HTTP API",
     "license": "UNLICENSED",
     "type": "module",
@@ -28,7 +28,7 @@
     },
     "publishConfig": {
         "access": "public",
-        "tag": "next",
+        "tag": "latest",
         "provenance": false
     },
     "scripts": {