@seta-labs/geo 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @seta-labs/geo
 
+## 0.8.0
+
+- **Breaking:** `LookupCache` becomes `CachePolicy`, the cache options every
+  Seta service and SDK shares: `refresh` is now `noCache`, like the header
+  directive; `noStore`, `maxAge` and `onlyIfCached` keep their names. The type
+  and its header writer come from `@seta-labs/nestjs-cache-control/policy`,
+  bundled into the SDK: nothing more to install.
+- Each client paces its calls (`pacing`): at most 10 in flight, a `429` or
+  `503` sent again up to 4 times after its `Retry-After` (up to a minute;
+  1-8 s backoff without it), the whole queue waiting meanwhile. `pacing:
+{ concurrency, retries }` tunes it, `pacing: false` turns it off; two queues
+  are two clients.
+- `timeoutMs` (default 30 s) bounds each attempt, not the wait in the queue.
+- `ApiError.code`: Geo's error code (`CADASTRE_BLOCKED`, `NOT_CACHED`, ...)
+  read from the body.
+
+## 0.7.0
+
+- `reverseGeocode(input)` answers from a chain of sources: the ANNCSU register
+  and the OpenStreetMap house numbers loaded in seta-geo first (within 25 m),
+  TrueWay last (an exact street address within 50 m). Failing a number, the
+  named road TrueWay places the point on, as `match.level: 'VIA'` with
+  `streetNumber`, `location` and `distanceM` null. Never an approximate
+  number: with neither, `match` is null and `status` is `NO_RESULT`.
+- The result gains `admin` (new type `GeoAdminArea`: `codComune`, `comune`,
+  `provincia`, `regione`), the municipality of the point from the ISTAT
+  boundaries, present even without a match; and `match` (new type
+  `GeoStreetMatch`): `level`, `provider` (`ANNCSU`, `OSM`, `TRUEWAY`),
+  `precision`, `street`, `streetNumber`, `postalCode`, `locality`,
+  `location`, `distanceM`, `sourceRef`.
+- `address` is now composed from the match: `Via Ponte Schiavo 13, Roma (RM)`,
+  or `Via Ponte Schiavo, Roma (RM)` for a street alone.
+- With `include: 'full'`, `results` is the raw answer of `match.provider`:
+  the TrueWay result list, or the ANNCSU/OSM record as one item.
+- The request takes `maxDistanceM` (1-50), which can only tighten the limits.
+
 ## 0.6.0
 
 - `comune(codComune)` gains the `territorio` block (new type

package/README.md

@@ -40,9 +40,20 @@ Do not use `$fetch` as `fetch`: it returns the parsed body instead of a Response
 
 All calls return `Promise<T>` and accept optional `{ signal }` as the last
 argument. An optional `fetch: (request: Request) => Promise<Response>` allows
-consumer-owned instrumentation or transport adapters. There is no scheduler,
-queue, rate limiter or automatic retry, including for failed writes. Consumers
-retain their own concurrency and retry policy.
+consumer-owned instrumentation or transport adapters.
+
+Each client paces its calls: at most 10 in flight, and a `429` or `503` that
+says when to come back (`Retry-After` up to a minute; 1 s, 2 s, 4 s, 8 s
+without it) is sent again up to 4 times while the client's whole queue waits.
+A refusal asking for a longer wait, every other status and network errors
+reach the caller after one attempt. Each attempt has `timeoutMs` (default
+30 s), not counting the wait in the queue. Two queues are two clients:
+
+```ts
+const geo = createGeoClient({ baseUrl, apiKey }); // lookups, territory
+const cadastre = createGeoClient({ baseUrl, apiKey, pacing: { concurrency: 4 } }); // the map, apart
+const panel = createGeoClient({ baseUrl: '/api', pacing: false }); // every call at once, once
+```
 
 | Method                                   | Input                                  |
 | ---------------------------------------- | -------------------------------------- |
@@ -66,14 +77,24 @@ 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).
+`cadastreParcel`) take `cache` in their options: a `CachePolicy`, the shape
+every Seta service and SDK shares (`@seta-labs/nestjs-cache-control/policy`,
+bundled here), sent as `Cache-Control`. `{ noCache: true }` asks the provider
+again and stores the new answer, `{ noCache: 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). Without `cache` the store answers
+when it can and the provider otherwise. The other calls read Geo's own data
+and take only `signal`.
+
+```ts
+await geo.reverseGeocode({ lat, lng }, { cache: { onlyIfCached: true } });
+await geo.reverseGeocode({ lat, lng }, { cache: jobCachePolicy() }); // the job's, at each call
+```
 
 HTTP errors are `ApiError`; their body is JSON when parseable, otherwise text,
-or `undefined` for an empty response. A `503` from `cadastreParcel` with
+or `undefined` for an empty response, and `code` is Geo's error code when the
+body has one. 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

package/dist/index.d.ts

@@ -4,6 +4,8 @@ declare class ApiError extends Error {
     readonly status: number;
     readonly headers: Headers;
     readonly requestId: string | undefined;
+    /** Geo's error `code` (`CADASTRE_BLOCKED`, `NOT_CACHED`, ...), when the body has one. */
+    readonly code: string | undefined;
     constructor(response: Response, body: unknown);
 }
 
@@ -111,30 +113,30 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    '/cadastre/parcel': {
+    '/territory/status': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        get: operations['TerritoryController_status'];
         put?: never;
-        post: operations['CadastreController_parcel'];
+        post?: never;
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    '/cadastre/parcels': {
+    '/territory/datasets': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations['CadastreController_listParcels'];
+        get: operations['TerritoryController_datasets'];
         put?: never;
         post?: never;
         delete?: never;
@@ -143,14 +145,14 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    '/territory/status': {
+    '/territory/comuni': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations['TerritoryController_status'];
+        get: operations['TerritoryController_listComuni'];
         put?: never;
         post?: never;
         delete?: never;
@@ -159,14 +161,14 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    '/territory/datasets': {
+    '/territory/quotazioni': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations['TerritoryController_datasets'];
+        get: operations['TerritoryController_listQuotazioni'];
         put?: never;
         post?: never;
         delete?: never;
@@ -175,14 +177,14 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    '/territory/comuni': {
+    '/territory/compravendite': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations['TerritoryController_listComuni'];
+        get: operations['TerritoryController_listCompravendite'];
         put?: never;
         post?: never;
         delete?: never;
@@ -191,14 +193,14 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    '/territory/quotazioni': {
+    '/territory/comuni/{codComune}': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations['TerritoryController_listQuotazioni'];
+        get: operations['TerritoryController_comune'];
         put?: never;
         post?: never;
         delete?: never;
@@ -207,48 +209,48 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    '/territory/compravendite': {
+    '/territory/resolve': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations['TerritoryController_listCompravendite'];
+        get?: never;
         put?: never;
-        post?: never;
+        post: operations['TerritoryController_resolve'];
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    '/territory/comuni/{codComune}': {
+    '/cadastre/parcel': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get: operations['TerritoryController_comune'];
+        get?: never;
         put?: never;
-        post?: never;
+        post: operations['CadastreController_parcel'];
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    '/territory/resolve': {
+    '/cadastre/parcels': {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        get?: never;
+        get: operations['CadastreController_listParcels'];
         put?: never;
-        post: operations['TerritoryController_resolve'];
+        post?: never;
         delete?: never;
         options?: never;
         head?: never;
@@ -410,83 +412,68 @@ interface components {
              * @enum {string}
              */
             include?: 'best' | 'full';
+            /** @description Tightens the distance a house number may lie from the point (25 m for ANNCSU and OSM, 50 m for TrueWay); it never widens them. */
+            maxDistanceM?: number;
         };
-        ReverseGeocodeResultDto: {
-            /** @enum {string} */
-            status: 'OK' | 'NO_RESULT';
-            /** @description Canonical cache key: "lat,lng" rounded to 5 decimals (~1 m). */
-            query: string;
-            /** @description Formatted address of the best-tier result. */
-            address: string | null;
-            /** @description True when the answer came from the cache, no provider call. */
-            cached: boolean;
-            /** @description Only with include=full: the provider's result list exactly as returned (all tiers, all fields). Empty array = the provider answered with no results. Null = the raw response is not available for this cached row. */
-            results?: {
-                [key: string]: unknown;
-            }[] | null;
+        GeoAdminAreaDto: {
+            /** @description Belfiore code, `H501`. */
+            codComune: string;
+            comune: string;
+            /** @description Province code, `RM`. */
+            provincia: string;
+            regione: string;
         };
-        CadastreParcelRequestDto: {
+        GeoLocationDto: {
             lat: number;
             lng: number;
         };
-        CadastreParcelResultDto: {
-            /** @description Canonical cache key: "lat,lng" rounded to 5 decimals (~1 m). */
-            query: string;
+        GeoStreetMatchDto: {
             /**
-             * @description What lies under the point, verbatim from the map: PARTICELLA, STRADA, …
-             * @example PARTICELLA
+             * @description How far down the address the match reaches: `CIVICO` a house number close enough, `VIA` only the street, when no source has a number close enough.
+             * @enum {string}
              */
-            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;
-        };
-        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;
+            level: 'CIVICO' | 'VIA';
             /**
-             * Format: date-time
-             * @description When the map last gave this answer.
+             * @description The source that answered: ANNCSU and OSM are loaded locally, TrueWay is paid.
+             * @enum {string}
              */
-            updatedAt: string;
+            provider: 'ANNCSU' | 'OSM' | 'TRUEWAY';
+            /** @description How the source rates the position: `metodo-1`…`metodo-5` (ANNCSU), `nodo` or `edificio` (OSM), `exact` (TrueWay), `centroid` (a TrueWay street). */
+            precision: string;
+            street: string;
+            /** @description `12`, `12/A`, `12 rosso`; null at level `VIA`. */
+            streetNumber: string | null;
+            /** @description Null from ANNCSU, which has none. */
+            postalCode: string | null;
+            /** @description Hamlet or locality as the source names it; the municipality is in `admin`. */
+            locality: string | null;
+            /** @description Where the house number is; null for a street the source places at its centroid. */
+            location: components['schemas']['GeoLocationDto'] | null;
+            /** @description Metres from the requested point to `location`; null without a location. */
+            distanceM: number | null;
+            /** @description Id of the record in its source: ANNCSU access, OSM `n123`/`w456`. */
+            sourceRef: string | null;
         };
-        CadastreParcelsPageDto: {
-            page: number;
-            pageSize: number;
-            total: number;
-            items: components['schemas']['CadastreParcelRowDto'][];
+        ReverseGeocodeResultDto: {
+            /**
+             * @description OK when `match` is present.
+             * @enum {string}
+             */
+            status: 'OK' | 'NO_RESULT';
+            /** @description Canonical cache key: "lat,lng" rounded to 5 decimals (~1 m). */
+            query: string;
+            /** @description The match as one line: `Via Ponte Schiavo 13, Roma (RM)`, or `Via Ponte Schiavo, Roma (RM)` at level `VIA`. */
+            address: string | null;
+            /** @description Municipality of the point from the ISTAT boundaries, whatever the match; null at sea, abroad or while no boundary edition is loaded. */
+            admin: components['schemas']['GeoAdminAreaDto'] | null;
+            /** @description An exact house number close enough, else the street a source names (level `VIA`); null when neither: never an approximate number. */
+            match: components['schemas']['GeoStreetMatchDto'] | null;
+            /** @description True when the answer came from stored rows: no source was asked again. */
+            cached: boolean;
+            /** @description Only with include=full: the raw answer of the source in `match.provider` (the TrueWay result list, or the ANNCSU/OSM record as one item); without a match, the raw answer of the last source asked. */
+            results?: {
+                [key: string]: unknown;
+            }[] | null;
         };
         TerritoryStatusDto: {
             /** @description Latest OMI publication loaded (`YYYY-S`), null while no supply is loaded. */
@@ -651,7 +638,7 @@ interface components {
         TerritoryComuneDetailDto: {
             comune: components['schemas']['TerritoryComuneDto'];
             istat: components['schemas']['TerritoryIstatDto'];
-            /** @description Null for a suppressed municipality: SITUAS describes only the current ones. */
+            /** @description Latest SITUAS edition that describes the municipality; null when none does, as for one suppressed before the first edition loaded. */
             territorio: components['schemas']['TerritoryTerritorioDto'] | null;
             /** @description Publication the zone quotations come from, null while none is loaded. */
             semestre: string | null;
@@ -687,6 +674,69 @@ interface components {
         TerritoryResolveResponseDto: {
             items: components['schemas']['TerritoryPointResultDto'][];
         };
+        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;
+        };
+        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'][];
+        };
     };
     responses: never;
     parameters: never;
@@ -894,97 +944,6 @@ interface operations {
             };
         };
     };
-    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;
-            };
-        };
-    };
-    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: {
         parameters: {
             query?: never;
@@ -1214,6 +1173,97 @@ interface operations {
             };
         };
     };
+    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;
+            };
+        };
+    };
+    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;
+            };
+        };
+    };
 }
 
 type ApiPaths = paths;
@@ -1224,6 +1274,8 @@ type GeocodeResult = ApiSchemas['GeocodeResultDto'];
 type GeocodeBatchResponse = ApiSchemas['GeocodeBatchResponseDto'];
 type ReverseGeocodeRequest = ApiSchemas['ReverseGeocodeRequestDto'];
 type ReverseGeocodeResult = ApiSchemas['ReverseGeocodeResultDto'];
+type GeoStreetMatch = ApiSchemas['GeoStreetMatchDto'];
+type GeoAdminArea = ApiSchemas['GeoAdminAreaDto'];
 type CadastreParcelRequest = ApiSchemas['CadastreParcelRequestDto'];
 type CadastreParcelResult = ApiSchemas['CadastreParcelResultDto'];
 type CadastreParcelsPage = ApiSchemas['CadastreParcelsPageDto'];
@@ -1244,6 +1296,31 @@ type TerritoryQuotazione = ApiSchemas['TerritoryQuotazioneDto'];
 type TerritoryCompravenditePage = ApiSchemas['TerritoryCompravenditePageDto'];
 type TerritoryCompravendita = ApiSchemas['TerritoryCompravenditaDto'];
 
+/**
+ * The request directives of RFC 9111 a lookup honours; any other directive is
+ * ignored. One shape for both sides: the server reads it from the header
+ * (`parseCacheControl`, every flag set), a client writes it
+ * (`formatCacheControl`, an absent flag is false).
+ */
+interface CachePolicy {
+    /** `no-cache`: never answer from the store without asking the provider. */
+    noCache?: boolean;
+    /** `no-store`: never write the provider's answer to the store. */
+    noStore?: boolean;
+    /** `only-if-cached`: never ask the provider; without a usable row, refuse. */
+    onlyIfCached?: boolean;
+    /** `max-age=N`: a stored row older than N seconds is not usable. */
+    maxAge?: number;
+}
+
+/** How a client paces its calls to Geo; each client has its own queue. */
+interface PacingOptions {
+    /** Requests in flight at once; default 10. */
+    concurrency?: number;
+    /** New attempts after a 429 or 503 that says when to come back; default 4 (5 attempts in all). */
+    retries?: number;
+}
+
 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']>;
@@ -1252,21 +1329,12 @@ 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.
+ * The options of a lookup, the four calls Geo answers from its store:
+ * `cache` is sent as `Cache-Control` (RFC 9111). Without it Geo answers
+ * from the store when it can and asks 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;
+    cache?: CachePolicy;
 }
 interface GeoClientOptions {
     /** Complete API root, including /api. Relative roots are supported in browsers. */
@@ -1275,6 +1343,10 @@ interface GeoClientOptions {
     apiKey?: string;
     /** A real Fetch implementation returning a Response, not a parsed-body $fetch. */
     fetch?: (request: Request) => Promise<Response>;
+    /** Each attempt's deadline, not counting the wait in the queue; default 30 s. */
+    timeoutMs?: number;
+    /** The client's queue and its retries on 429/503; `false` sends every call at once, once. */
+    pacing?: false | PacingOptions;
 }
 interface TerritoryClient {
     status(options?: RequestOptions): Promise<TerritoryStatus>;
@@ -1300,4 +1372,4 @@ interface GeoClient {
 declare function createGeoClient(options: GeoClientOptions): GeoClient;
 
 export { ApiError, createGeoClient };
-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, TerritoryTerritorio };
+export type { CachePolicy, CadastreParcelRequest, CadastreParcelResult, CadastreParcelRow, CadastreParcelsPage, CadastreParcelsQuery, GeoAdminArea, GeoClient, GeoClientOptions, GeoStreetMatch, GeocodeBatchRequest, GeocodeBatchResponse, GeocodeRequest, GeocodeResult, LookupOptions, PacingOptions, RequestOptions, ReverseGeocodeRequest, ReverseGeocodeResult, TerritoryClient, TerritoryCompravendita, TerritoryCompravenditePage, TerritoryCompravenditeQuery, TerritoryComune, TerritoryComuneDetail, TerritoryComuneRiga, TerritoryComuniPage, TerritoryComuniQuery, TerritoryDatasets, TerritoryOmi, TerritoryPointResult, TerritoryQuotazione, TerritoryQuotazioniPage, TerritoryQuotazioniQuery, TerritoryResolveRequest, TerritoryResolveResponse, TerritoryStatus, TerritoryTerritorio };

package/dist/index.js

@@ -7,11 +7,14 @@ var ApiError = class extends Error {
     this.status = response.status;
     this.headers = new Headers(response.headers);
     this.requestId = response.headers.get("x-request-id") ?? void 0;
+    this.code = codeOf(body);
   }
   body;
   status;
   headers;
   requestId;
+  /** Geo's error `code` (`CADASTRE_BLOCKED`, `NOT_CACHED`, ...), when the body has one. */
+  code;
 };
 async function readErrorBody(response) {
   const text = await response.text();
@@ -22,9 +25,126 @@ async function readErrorBody(response) {
     return text;
   }
 }
+function codeOf(body) {
+  if (typeof body !== "object" || body === null || !("code" in body)) return void 0;
+  return typeof body.code === "string" ? body.code : void 0;
+}
+
+// ../../node_modules/.pnpm/@seta-labs+nestjs-cache-control@0.2.1_@nestjs+common@12.1.2_class-transformer@0.5.1_cla_d70e55208c987ac6b22f0eff0ce5869e/node_modules/@seta-labs/nestjs-cache-control/dist/cache-policy.util.js
+var MAX_DELTA_SECONDS = 2147483648;
+function formatCacheControl(policy) {
+  if (!policy)
+    return void 0;
+  const maxAge = policy.maxAge;
+  const directives = [
+    policy.noCache ? "no-cache" : void 0,
+    policy.noStore ? "no-store" : void 0,
+    maxAge !== void 0 && Number.isFinite(maxAge) ? `max-age=${Math.min(Math.max(0, Math.floor(maxAge)), MAX_DELTA_SECONDS)}` : void 0,
+    policy.onlyIfCached ? "only-if-cached" : void 0
+  ].filter((directive) => directive !== void 0);
+  return directives.length > 0 ? directives.join(", ") : void 0;
+}
 
 // src/client.ts
 import createClient from "openapi-fetch";
+
+// src/pacing.ts
+var DEFAULT_CONCURRENCY = 10;
+var DEFAULT_RETRIES = 4;
+var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 503]);
+var BACKOFF_MS = 1e3;
+var MAX_WAIT_MS = 6e4;
+function pacedFetch(fetch, options = {}) {
+  const run = limiter(options.concurrency ?? DEFAULT_CONCURRENCY);
+  const retries = options.retries ?? DEFAULT_RETRIES;
+  let pausedUntil = 0;
+  const send = async (request, attempt) => {
+    while (pausedUntil > Date.now()) await sleepUntil(pausedUntil, request.signal);
+    const response = await fetch(request.clone());
+    const waitMs = attempt < retries ? retryDelay(response, attempt) : void 0;
+    if (waitMs !== void 0) pausedUntil = Math.max(pausedUntil, Date.now() + waitMs);
+    return { response, waitMs };
+  };
+  return async (request) => {
+    for (let attempt = 0; ; attempt++) {
+      const { response, waitMs } = await run(request.signal, () => send(request, attempt));
+      if (waitMs === void 0) return response;
+      await response.body?.cancel();
+    }
+  };
+}
+function timedFetch(fetch, timeoutMs) {
+  return (request) => fetch(
+    new Request(request, {
+      signal: AbortSignal.any([request.signal, AbortSignal.timeout(timeoutMs)])
+    })
+  );
+}
+function retryDelay(response, attempt) {
+  if (!RETRY_STATUSES.has(response.status)) return void 0;
+  const header = response.headers.get("retry-after");
+  const waitMs = header === null ? BACKOFF_MS * 2 ** attempt : retryAfterMs(header);
+  return waitMs !== void 0 && waitMs <= MAX_WAIT_MS ? waitMs : void 0;
+}
+function retryAfterMs(header) {
+  const value = header.trim();
+  if (/^\d+$/.test(value)) return Number(value) * 1e3;
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? void 0 : Math.max(0, date - Date.now());
+}
+function limiter(concurrency) {
+  let active = 0;
+  const waiting = [];
+  const acquire = (signal) => {
+    signal.throwIfAborted();
+    if (active < concurrency) {
+      active++;
+      return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      const start = () => {
+        signal.removeEventListener("abort", abort);
+        active++;
+        resolve();
+      };
+      const abort = () => {
+        waiting.splice(waiting.indexOf(start), 1);
+        reject(signal.reason);
+      };
+      waiting.push(start);
+      signal.addEventListener("abort", abort, { once: true });
+    });
+  };
+  return async (signal, task) => {
+    await acquire(signal);
+    try {
+      return await task();
+    } finally {
+      active--;
+      waiting.shift()?.();
+    }
+  };
+}
+function sleepUntil(time, signal) {
+  const delay = time - Date.now();
+  if (delay <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    signal.throwIfAborted();
+    const timer = setTimeout(done, delay);
+    signal.addEventListener("abort", abort, { once: true });
+    function done() {
+      signal.removeEventListener("abort", abort);
+      resolve();
+    }
+    function abort() {
+      clearTimeout(timer);
+      reject(signal.reason);
+    }
+  });
+}
+
+// src/client.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
 function apiBaseUrl(baseUrl) {
   const url = new URL(baseUrl, globalThis.location?.href);
   if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
@@ -39,19 +159,9 @@ 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);
+  const header = formatCacheControl(cache);
   return header ? { ...request, headers: { "cache-control": header } } : request;
 }
 function territory(client) {
@@ -73,7 +183,7 @@ function territory(client) {
 function createGeoClient(options) {
   const client = createClient({
     baseUrl: apiBaseUrl(options.baseUrl),
-    fetch: options.fetch,
+    fetch: transport(options),
     headers: options.apiKey ? { "x-api-key": options.apiKey } : void 0
   });
   client.use({
@@ -90,6 +200,11 @@ function createGeoClient(options) {
     territory: territory(client)
   };
 }
+function transport(options) {
+  const send = options.fetch ?? ((request) => globalThis.fetch(request));
+  const timed = timedFetch(send, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  return options.pacing === false ? timed : pacedFetch(timed, options.pacing);
+}
 export {
   ApiError,
   createGeoClient

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@seta-labs/geo",
-    "version": "0.6.0",
+    "version": "0.8.0",
     "description": "Typed Fetch client for the Seta Geo HTTP API",
     "license": "UNLICENSED",
     "type": "module",
@@ -44,6 +44,7 @@
     "devDependencies": {
         "@seta-geo/types": "workspace:*",
         "@seta-labs/config": "^0.16.1",
+        "@seta-labs/nestjs-cache-control": "0.2.1",
         "tsup": "^9.0.0",
         "typescript": "^6.0.3",
         "vitest": "^5.0.3"