@seta-labs/geo 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @seta-labs/geo
 
+## 0.4.0
+
+- New `cadastreParcels(query?)` on `GET /cadastre/parcels`: the stored
+  cadastral answers, newest first, filtered by `codComune`, `foglio`,
+  `particella` and `tipologia` (exact match), paginated with `page` and
+  `pageSize`. A read of the store: it never asks the cadastral map.
+- New types `CadastreParcelsQuery`, `CadastreParcelsPage` and `CadastreParcelRow`.
+
+## 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

package/README.md

@@ -50,6 +50,7 @@ retain their own concurrency and retry policy.
 | `geocodeBatch`                           | `GeocodeBatchRequest`                  |
 | `reverseGeocode`                         | `ReverseGeocodeRequest`                |
 | `cadastreParcel`                         | `CadastreParcelRequest`                |
+| `cadastreParcels`                        | optional `CadastreParcelsQuery`        |
 | `territory.status`, `territory.datasets` | options only                           |
 | `territory.comuni`                       | optional `TerritoryComuniQuery`        |
 | `territory.quotazioni`                   | optional `TerritoryQuotazioniQuery`    |
@@ -64,6 +65,13 @@ 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. A `503` from `cadastreParcel` with
 `code: 'CADASTRE_BLOCKED'` means the cadastral map is refusing calls: its

package/dist/index.d.ts

@@ -127,6 +127,22 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    '/cadastre/parcels': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations['CadastreController_listParcels'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     '/territory/status': {
         parameters: {
             query?: never;
@@ -355,8 +371,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;
@@ -436,6 +455,39 @@ interface components {
             /** @description True when the answer came from the cache, no map call. */
             cached: boolean;
         };
+        CadastreParcelRowDto: {
+            /** @description Canonical cache key: "lat,lng" rounded to 5 decimals. */
+            query: string;
+            lat: number;
+            lng: number;
+            /** @example PARTICELLA */
+            tipologia: string;
+            /** @example B885 */
+            codComune: string | null;
+            /** @description Municipality name; null when the code is not in the registry. */
+            comune: string | null;
+            /** @example AL */
+            provincia: string | null;
+            sezione: string | null;
+            /** @example 36 */
+            foglio: string | null;
+            /** @example G */
+            allegato: string | null;
+            sviluppo: string | null;
+            /** @example 5101 */
+            particella: string | null;
+            /**
+             * Format: date-time
+             * @description When the map last gave this answer.
+             */
+            updatedAt: string;
+        };
+        CadastreParcelsPageDto: {
+            page: number;
+            pageSize: number;
+            total: number;
+            items: components['schemas']['CadastreParcelRowDto'][];
+        };
         TerritoryStatusDto: {
             /** @description Latest OMI publication loaded (`YYYY-S`), null while no supply is loaded. */
             semestre: string | null;
@@ -652,7 +704,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;
         };
@@ -684,12 +739,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;
         };
@@ -726,7 +791,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;
         };
@@ -758,12 +826,22 @@ 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?: 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;
         };
@@ -803,6 +881,49 @@ interface operations {
                 };
                 content?: never;
             };
+            /** @description NOT_CACHED: only-if-cached and no usable stored answer. */
+            504: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    CadastreController_listParcels: {
+        parameters: {
+            query?: {
+                page?: number;
+                pageSize?: number;
+                /** @description Cadastral municipality code. */
+                codComune?: string;
+                foglio?: string;
+                particella?: string;
+                /** @description What lies under the point. */
+                tipologia?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The stored map answers, newest first; never a map call. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['CadastreParcelsPageDto'];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
         };
     };
     TerritoryController_status: {
@@ -1044,6 +1165,8 @@ type ReverseGeocodeRequest = ApiSchemas['ReverseGeocodeRequestDto'];
 type ReverseGeocodeResult = ApiSchemas['ReverseGeocodeResultDto'];
 type CadastreParcelRequest = ApiSchemas['CadastreParcelRequestDto'];
 type CadastreParcelResult = ApiSchemas['CadastreParcelResultDto'];
+type CadastreParcelsPage = ApiSchemas['CadastreParcelsPageDto'];
+type CadastreParcelRow = ApiSchemas['CadastreParcelRowDto'];
 type TerritoryStatus = ApiSchemas['TerritoryStatusDto'];
 type TerritoryResolveRequest = ApiSchemas['TerritoryResolveRequestDto'];
 type TerritoryResolveResponse = ApiSchemas['TerritoryResolveResponseDto'];
@@ -1062,9 +1185,27 @@ type TerritoryCompravendita = ApiSchemas['TerritoryCompravenditaDto'];
 type TerritoryComuniQuery = NonNullable<ApiPaths['/territory/comuni']['get']['parameters']['query']>;
 type TerritoryQuotazioniQuery = NonNullable<ApiPaths['/territory/quotazioni']['get']['parameters']['query']>;
 type TerritoryCompravenditeQuery = NonNullable<ApiPaths['/territory/compravendite']['get']['parameters']['query']>;
+type CadastreParcelsQuery = NonNullable<ApiPaths['/cadastre/parcels']['get']['parameters']['query']>;
 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;
@@ -1083,15 +1224,18 @@ 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?: RequestOptions): Promise<CadastreParcelResult>;
+    cadastreParcel(input: CadastreParcelRequest, options?: LookupOptions): Promise<CadastreParcelResult>;
+    /** The stored cadastral answers, newest first: a read of the store, never a map call. */
+    cadastreParcels(query?: CadastreParcelsQuery, options?: RequestOptions): Promise<CadastreParcelsPage>;
     territory: TerritoryClient;
 }
 
 declare function createGeoClient(options: GeoClientOptions): GeoClient;
 
 export { ApiError, createGeoClient };
-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 };
+export type { CadastreParcelRequest, CadastreParcelResult, CadastreParcelRow, CadastreParcelsPage, CadastreParcelsQuery, 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,10 +82,11 @@ 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 })),
-    cadastreParcel: (input, request) => data(client.POST("/cadastre/parcel", { ...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 })),
+    cadastreParcels: (query, options2) => data(client.GET("/cadastre/parcels", { ...options2, params: { query } })),
     territory: territory(client)
   };
 }

package/package.json

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