@seta-labs/geo 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @seta-labs/geo
 
+## 0.3.0
+
+- `geocode`, `geocodeBatch`, `reverseGeocode` and `cadastreParcel` take
+  `cache: { refresh, noStore, maxAge, onlyIfCached }`, sent as
+  `Cache-Control` (`no-cache`, `no-store`, `max-age`, `only-if-cached`).
+  Without it nothing changes. New types `LookupCache` and `LookupOptions`.
+- A lookup refused by `onlyIfCached` rejects with `ApiError` 504
+  (`code: 'NOT_CACHED'`); a batch item has `status: 'NOT_CACHED'`.
+
+## 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.

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,14 +58,24 @@ 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.
 
+The four lookups (`geocode`, `geocodeBatch`, `reverseGeocode`,
+`cadastreParcel`) take `cache` in their options, sent as `Cache-Control`:
+`{ refresh: true }` asks the provider again and stores the new answer,
+`{ refresh: true, noStore: true }` bypasses the store entirely, `{ maxAge }`
+asks again past that many seconds, `{ onlyIfCached: true }` never asks the
+provider (504 `NOT_CACHED`, or `status: 'NOT_CACHED'` for a batch item).
+
 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.

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;
@@ -339,8 +355,11 @@ interface components {
             include?: 'best' | 'full';
         };
         GeocodeResultDto: {
-            /** @enum {string} */
-            status: 'OK' | 'NO_RESULT' | 'INVALID_QUERY';
+            /**
+             * @description NOT_CACHED: a batch item refused by Cache-Control only-if-cached.
+             * @enum {string}
+             */
+            status: 'OK' | 'NO_RESULT' | 'INVALID_QUERY' | 'NOT_CACHED';
             /** @description The normalized query actually used as cache key and provider input. */
             query: string | null;
             lat: number | null;
@@ -390,6 +409,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;
@@ -606,7 +655,10 @@ interface operations {
     GeocodeController_geocode: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description no-cache: ask the provider and store its answer; no-store: never write the store; max-age=N: a stored answer older than N seconds is asked again; only-if-cached: never ask the provider. The response says what happened in Cache-Status (hit, fwd=miss|request|stale, stored) and, on a hit, Age. */
+                'Cache-Control'?: string;
+            };
             path?: never;
             cookie?: never;
         };
@@ -638,12 +690,22 @@ interface operations {
                 };
                 content?: never;
             };
+            /** @description NOT_CACHED: only-if-cached and no usable stored answer. */
+            504: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     GeocodeController_geocodeBatch: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description Applies to every item: no-cache, no-store, max-age=N, only-if-cached. An item only-if-cached refuses has status NOT_CACHED; the batch still answers 200. */
+                'Cache-Control'?: string;
+            };
             path?: never;
             cookie?: never;
         };
@@ -680,7 +742,10 @@ interface operations {
     GeocodeController_reverseGeocode: {
         parameters: {
             query?: never;
-            header?: never;
+            header?: {
+                /** @description no-cache: ask the provider and store its answer; no-store: never write the store; max-age=N: a stored answer older than N seconds is asked again; only-if-cached: never ask the provider. The response says what happened in Cache-Status (hit, fwd=miss|request|stale, stored) and, on a hit, Age. */
+                'Cache-Control'?: string;
+            };
             path?: never;
             cookie?: never;
         };
@@ -712,6 +777,68 @@ interface operations {
                 };
                 content?: never;
             };
+            /** @description NOT_CACHED: only-if-cached and no usable stored answer. */
+            504: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    CadastreController_parcel: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description no-cache: ask the provider and store its answer; no-store: never write the store; max-age=N: a stored answer older than N seconds is asked again; only-if-cached: never ask the provider. The response says what happened in Cache-Status (hit, fwd=miss|request|stale, stored) and, on a hit, Age. */
+                'Cache-Control'?: string;
+            };
+            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;
+            };
+            /** @description NOT_CACHED: only-if-cached and no usable stored answer. */
+            504: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     TerritoryController_status: {
@@ -951,6 +1078,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'];
@@ -972,6 +1101,23 @@ type TerritoryCompravenditeQuery = NonNullable<ApiPaths['/territory/compravendit
 interface RequestOptions {
     signal?: AbortSignal;
 }
+/**
+ * How a lookup may use seta-geo's store, sent as `Cache-Control` (RFC 9111).
+ * Without it the store answers when it can and the provider otherwise.
+ */
+interface LookupCache {
+    /** `no-cache`: ask the provider even with a stored answer, and store the new one. */
+    refresh?: boolean;
+    /** `no-store`: never write the provider's answer (with `refresh`: a pure bypass). */
+    noStore?: boolean;
+    /** `max-age`: a stored answer older than this many seconds is asked again. */
+    maxAge?: number;
+    /** `only-if-cached`: never ask the provider; 504 `NOT_CACHED` without a stored answer. */
+    onlyIfCached?: boolean;
+}
+interface LookupOptions extends RequestOptions {
+    cache?: LookupCache;
+}
 interface GeoClientOptions {
     /** Complete API root, including /api. Relative roots are supported in browsers. */
     baseUrl: string;
@@ -990,13 +1136,16 @@ interface TerritoryClient {
     resolve(input: TerritoryResolveRequest, options?: RequestOptions): Promise<TerritoryResolveResponse>;
 }
 interface GeoClient {
-    geocode(input: GeocodeRequest, options?: RequestOptions): Promise<GeocodeResult>;
-    geocodeBatch(input: GeocodeBatchRequest, options?: RequestOptions): Promise<GeocodeBatchResponse>;
-    reverseGeocode(input: ReverseGeocodeRequest, options?: RequestOptions): Promise<ReverseGeocodeResult>;
+    geocode(input: GeocodeRequest, options?: LookupOptions): Promise<GeocodeResult>;
+    /** `cache` applies to every item; an item only-if-cached refuses has status NOT_CACHED. */
+    geocodeBatch(input: GeocodeBatchRequest, options?: LookupOptions): Promise<GeocodeBatchResponse>;
+    reverseGeocode(input: ReverseGeocodeRequest, options?: LookupOptions): Promise<ReverseGeocodeResult>;
+    /** What the AdE cadastral map finds under a point; 503 `CADASTRE_BLOCKED` carries Retry-After. */
+    cadastreParcel(input: CadastreParcelRequest, options?: LookupOptions): 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, LookupCache, LookupOptions, 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

@@ -39,6 +39,21 @@ async function data(request) {
   if (result.data === void 0) throw new SyntaxError("Geo API returned an empty JSON response");
   return result.data;
 }
+function cacheControl(cache) {
+  if (!cache) return void 0;
+  const directives = [
+    cache.refresh ? "no-cache" : void 0,
+    cache.noStore ? "no-store" : void 0,
+    cache.maxAge === void 0 ? void 0 : `max-age=${Math.max(0, Math.floor(cache.maxAge))}`,
+    cache.onlyIfCached ? "only-if-cached" : void 0
+  ].filter((directive) => directive !== void 0);
+  return directives.length > 0 ? directives.join(", ") : void 0;
+}
+function lookupInit(options) {
+  const { cache, ...request } = options ?? {};
+  const header = cacheControl(cache);
+  return header ? { ...request, headers: { "cache-control": header } } : request;
+}
 function territory(client) {
   return {
     status: (options) => data(client.GET("/territory/status", { ...options })),
@@ -67,9 +82,10 @@ function createGeoClient(options) {
     }
   });
   return {
-    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 })),
+    geocode: (input, request) => data(client.POST("/geocode", { ...lookupInit(request), body: input })),
+    geocodeBatch: (input, request) => data(client.POST("/geocode/batch", { ...lookupInit(request), body: input })),
+    reverseGeocode: (input, request) => data(client.POST("/geocode/reverse", { ...lookupInit(request), body: input })),
+    cadastreParcel: (input, request) => data(client.POST("/cadastre/parcel", { ...lookupInit(request), body: input })),
     territory: territory(client)
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@seta-labs/geo",
-    "version": "0.1.0",
+    "version": "0.3.0",
     "description": "Typed Fetch client for the Seta Geo HTTP API",
     "license": "UNLICENSED",
     "type": "module",