@seta-labs/geo 0.0.0-stage → 0.1.0-next.0

package/README.md

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# @seta-labs/geo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed ESM client for Seta Geo's HTTP API. Requires Node.js 22+ or a browser with
+standard Fetch, Request, Response and AbortController support. The server's
+Node.js 26 development requirement does not apply to SDK consumers.
+
+```ts
+import { ApiError, createGeoClient } from '@seta-labs/geo';
+
+const geo = createGeoClient({
+    baseUrl: 'https://geo.example.com/api',
+    apiKey: serverConfig.geoApiKey,
+});
+
+try {
+    const result = await geo.geocode(
+        { query: 'Via Roma 1, Torino', include: 'full' },
+        { signal: AbortSignal.timeout(20_000) },
+    );
+    // result is GeocodeResult, inferred from the generated HTTP contract.
+} catch (error) {
+    if (error instanceof ApiError) {
+        // error.status, error.body (unknown), error.headers and error.requestId.
+        // Retry-After and any retryAfterMs in the body remain available.
+    }
+    throw error;
+}
+```
+
+`baseUrl` is the complete API root, including `/api` when the deployment uses
+that prefix. The SDK never appends `/api`. Browser-relative roots such as `/api`
+resolve against the current page. SSR requires an absolute API root and a new
+client for each request when credentials are request-scoped.
+
+Use API keys only on a trusted backend. A browser may omit `apiKey` when calling
+its own backend, which supplies the key to Geo. The bundled Geo panel follows
+this arrangement through its existing Nitro pass-through. It adapts Nitro's
+request-scoped Fetch to real `Response` objects and preserves cookies locally.
+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.
+
+| Method                                   | Input                                  |
+| ---------------------------------------- | -------------------------------------- |
+| `geocode`                                | `GeocodeRequest`                       |
+| `geocodeBatch`                           | `GeocodeBatchRequest`                  |
+| `reverseGeocode`                         | `ReverseGeocodeRequest`                |
+| `territory.status`, `territory.datasets` | options only                           |
+| `territory.comuni`                       | optional `TerritoryComuniQuery`        |
+| `territory.quotazioni`                   | optional `TerritoryQuotazioniQuery`    |
+| `territory.compravendite`                | optional `TerritoryCompravenditeQuery` |
+| `territory.comune`                       | municipality code                      |
+| `territory.resolve`                      | `TerritoryResolveRequest`              |
+
+The package exports `createGeoClient`, `ApiError`, client/options interfaces,
+query types and the generated geocode/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
+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
+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.

package/dist/index.d.ts

@@ -0,0 +1,1002 @@
+/** HTTP failures only. Network, abort and JSON parsing errors keep their native types. */
+declare class ApiError extends Error {
+    readonly body: unknown;
+    readonly status: number;
+    readonly headers: Headers;
+    readonly requestId: string | undefined;
+    constructor(response: Response, body: unknown);
+}
+
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+interface paths {
+    '/health': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Liveness: the process answers; no dependency is checked */
+        get: operations['HealthController_live'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/health/ready': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Readiness: memory pressure and critical dependencies */
+        get: operations['HealthController_ready'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/health/status': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Diagnostics: memory, event loop delay, every check with its error */
+        get: operations['HealthController_status'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/geocode': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations['GeocodeController_geocode'];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/geocode/batch': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations['GeocodeController_geocodeBatch'];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/geocode/reverse': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations['GeocodeController_reverseGeocode'];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/territory/status': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations['TerritoryController_status'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/territory/datasets': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations['TerritoryController_datasets'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/territory/comuni': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations['TerritoryController_listComuni'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/territory/quotazioni': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations['TerritoryController_listQuotazioni'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/territory/compravendite': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations['TerritoryController_listCompravendite'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/territory/comuni/{codComune}': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations['TerritoryController_comune'];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/territory/resolve': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations['TerritoryController_resolve'];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+interface components {
+    schemas: {
+        /** @enum {string} */
+        HealthStatus: 'ok' | 'degraded' | 'down';
+        HealthCheckResultDto: {
+            /** @example database */
+            name: string;
+            /**
+             * @description A check is `ok` or `down`.
+             * @example ok
+             */
+            status: components['schemas']['HealthStatus'];
+            /** @description A failing critical check fails readiness. */
+            critical: boolean;
+            /** @example 3.2 */
+            durationMs: number;
+            /**
+             * @description Failure reason, only in `/health/status`: probes are public.
+             * @example timed out after 750 ms
+             */
+            error?: string;
+        };
+        HealthCheckResponseDto: {
+            /** @example ok */
+            status: components['schemas']['HealthStatus'];
+            /** @example api */
+            service: string;
+            /**
+             * Format: date-time
+             * @example 2026-07-03T10:00:00.000Z
+             */
+            timestamp: string;
+            /** @description Readiness checks; absent on liveness. */
+            checks?: components['schemas']['HealthCheckResultDto'][];
+        };
+        MemoryUsageDto: {
+            /** @example 182.4 */
+            rssMiB: number;
+            /** @example 96.1 */
+            heapUsedMiB: number;
+            /** @example 120.5 */
+            heapTotalMiB: number;
+            /** @example 4.2 */
+            externalMiB: number;
+            /** @example 1.3 */
+            arrayBuffersMiB: number;
+            /**
+             * @description V8 `heap_size_limit`.
+             * @example 259
+             */
+            heapLimitMiB: number;
+            /**
+             * @description cgroup memory limit, `null` when unconstrained.
+             * @example 512
+             */
+            containerLimitMiB: number | null;
+            /**
+             * @description `heapUsed / heapLimit`.
+             * @example 0.371
+             */
+            heapRatio: number;
+            /**
+             * @description `rss / containerLimit`, `null` when unconstrained.
+             * @example 0.356
+             */
+            rssRatio: number | null;
+        };
+        EventLoopDelayDto: {
+            /** @example 10.1 */
+            p50Ms: number;
+            /** @example 21.4 */
+            p99Ms: number;
+            /** @example 48.7 */
+            maxMs: number;
+            /**
+             * @description Seconds covered: since the previous status report, or since startup.
+             * @example 60
+             */
+            windowSec: number;
+        };
+        HealthReportResponseDto: {
+            /** @example ok */
+            status: components['schemas']['HealthStatus'];
+            /** @example api */
+            service: string;
+            /** @example v0.4.2 */
+            version?: string;
+            /** @example v22.23.2 */
+            node: string;
+            /** @example 3600 */
+            uptimeSec: number;
+            /**
+             * Format: date-time
+             * @example 2026-07-03T10:00:00.000Z
+             */
+            timestamp: string;
+            memory: components['schemas']['MemoryUsageDto'];
+            eventLoop: components['schemas']['EventLoopDelayDto'];
+            checks: components['schemas']['HealthCheckResultDto'][];
+        };
+        GeocodeRequestDto: {
+            /** @description Free-text query, used verbatim when present. */
+            query?: string;
+            indirizzo?: string;
+            cap?: string;
+            citta?: string;
+            provincia?: string;
+            /**
+             * @description 'full' adds `results`: the provider's untouched result list, for callers that pick themselves.
+             * @default best
+             * @enum {string}
+             */
+            include?: 'best' | 'full';
+        };
+        GeocodeResultDto: {
+            /** @enum {string} */
+            status: 'OK' | 'NO_RESULT' | 'INVALID_QUERY';
+            /** @description The normalized query actually used as cache key and provider input. */
+            query: string | null;
+            lat: number | null;
+            lng: number | null;
+            /** @description True when the answer came from the cache, no provider call. */
+            cached: boolean;
+            /** @description True when the coordinates fall inside the loose Italy bounding box. */
+            withinItaly: 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;
+        };
+        GeocodeBatchRequestDto: {
+            items: components['schemas']['GeocodeRequestDto'][];
+            /**
+             * @description Applied to every item; a per-item include overrides it.
+             * @default best
+             * @enum {string}
+             */
+            include?: 'best' | 'full';
+        };
+        GeocodeBatchResponseDto: {
+            /** @description Same order as the request items. */
+            items: components['schemas']['GeocodeResultDto'][];
+        };
+        ReverseGeocodeRequestDto: {
+            lat: number;
+            lng: number;
+            /**
+             * @default best
+             * @enum {string}
+             */
+            include?: 'best' | 'full';
+        };
+        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;
+        };
+        TerritoryStatusDto: {
+            /** @description Latest OMI publication loaded (`YYYY-S`), null while no supply is loaded. */
+            semestre: string | null;
+        };
+        TerritoryDatasetsDto: {
+            comuni: number;
+            zone: number;
+            quotazioni: number;
+            compravendite: number;
+            /** @description Newest first. */
+            semestri: string[];
+            tipologie: string[];
+            stati: string[];
+            /** @description Newest first. */
+            anni: number[];
+            province: string[];
+            regioni: string[];
+        };
+        TerritoryComuneRigaDto: {
+            codComune: string;
+            codIstat: string;
+            denominazione: string;
+            provincia: string;
+            regione: string;
+            popolazione: number | null;
+            redditoMedio: number | null;
+        };
+        TerritoryComuniPageDto: {
+            page: number;
+            pageSize: number;
+            total: number;
+            items: components['schemas']['TerritoryComuneRigaDto'][];
+        };
+        TerritoryQuotazioneDto: {
+            semestre: string;
+            codComune: string;
+            comune: string | null;
+            provincia: string | null;
+            codZona: string;
+            zona: string | null;
+            tipologia: string;
+            stato: string;
+            comprMin: number | null;
+            comprMax: number | null;
+            locMin: number | null;
+            locMax: number | null;
+        };
+        TerritoryQuotazioniPageDto: {
+            page: number;
+            pageSize: number;
+            total: number;
+            /** @description Publication listed, null while none is loaded. */
+            semestre: string | null;
+            items: components['schemas']['TerritoryQuotazioneDto'][];
+        };
+        TerritoryCompravenditaDto: {
+            codComune: string;
+            comune: string | null;
+            provincia: string | null;
+            anno: number;
+            segmento: string;
+            ntn: number;
+        };
+        TerritoryCompravenditePageDto: {
+            page: number;
+            pageSize: number;
+            total: number;
+            items: components['schemas']['TerritoryCompravenditaDto'][];
+        };
+        TerritoryComuneDto: {
+            codComune: string;
+            codIstat: string;
+            denominazione: string;
+            provincia: string;
+            regione: string;
+        };
+        TerritoryIstatDto: {
+            denominazione: string;
+            provincia: string;
+            popolazione: number | null;
+            popolazioneAnno: number | null;
+            redditoMedio: number | null;
+            redditoAnno: number | null;
+        };
+        TerritoryOmiDto: {
+            semestre: string;
+            tipologia: string;
+            stato: string;
+            comprMin: number | null;
+            comprMax: number | null;
+            locMin: number | null;
+            locMax: number | null;
+        };
+        TerritoryZonaQuotazioneDto: {
+            codZona: string;
+            nome: string | null;
+            omi: components['schemas']['TerritoryOmiDto'] | null;
+        };
+        TerritoryCompravenditaAnnoDto: {
+            anno: number;
+            segmento: string;
+            ntn: number;
+        };
+        TerritoryComuneDetailDto: {
+            comune: components['schemas']['TerritoryComuneDto'];
+            istat: components['schemas']['TerritoryIstatDto'];
+            /** @description Publication the zone quotations come from, null while none is loaded. */
+            semestre: string | null;
+            zone: components['schemas']['TerritoryZonaQuotazioneDto'][];
+            compravendite: components['schemas']['TerritoryCompravenditaAnnoDto'][];
+        };
+        TerritoryPointDto: {
+            id: string;
+            lat: number;
+            lng: number;
+        };
+        TerritoryResolveRequestDto: {
+            /** @description OMI publication to quote from (`YYYY-S`). Callers pin it once per run — from `GET /territory/status` — so a publication switch mid-run cannot shear the batch. */
+            semestre: string;
+            points: components['schemas']['TerritoryPointDto'][];
+        };
+        TerritoryZonaDto: {
+            codComune: string;
+            codZona: string;
+            nome: string | null;
+        };
+        TerritoryCompravenditeDto: {
+            anno: number;
+            ntn: number;
+        };
+        TerritoryPointResultDto: {
+            id: string;
+            zona: components['schemas']['TerritoryZonaDto'] | null;
+            omi: components['schemas']['TerritoryOmiDto'] | null;
+            istat: components['schemas']['TerritoryIstatDto'] | null;
+            compravendite: components['schemas']['TerritoryCompravenditeDto'] | null;
+        };
+        TerritoryResolveResponseDto: {
+            items: components['schemas']['TerritoryPointResultDto'][];
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+interface operations {
+    HealthController_live: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['HealthCheckResponseDto'];
+                };
+            };
+        };
+    };
+    HealthController_ready: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['HealthCheckResponseDto'];
+                };
+            };
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['HealthCheckResponseDto'];
+                };
+            };
+        };
+    };
+    HealthController_status: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['HealthReportResponseDto'];
+                };
+            };
+        };
+    };
+    GeocodeController_geocode: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                'application/json': components['schemas']['GeocodeRequestDto'];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['GeocodeResultDto'];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Provider not configured, cache miss unservable. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    GeocodeController_geocodeBatch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                'application/json': components['schemas']['GeocodeBatchRequestDto'];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['GeocodeBatchResponseDto'];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Provider not configured, cache miss unservable. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    GeocodeController_reverseGeocode: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                'application/json': components['schemas']['ReverseGeocodeRequestDto'];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['ReverseGeocodeResultDto'];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Provider not configured, cache miss unservable. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    TerritoryController_status: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['TerritoryStatusDto'];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    TerritoryController_datasets: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['TerritoryDatasetsDto'];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    TerritoryController_listComuni: {
+        parameters: {
+            query?: {
+                page?: number;
+                pageSize?: number;
+                /** @description Part of the municipality name, case-insensitive. */
+                q?: string;
+                /** @description Province code, e.g. `GE`. */
+                provincia?: string;
+                regione?: string;
+                ordina?: 'denominazione' | 'popolazione';
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['TerritoryComuniPageDto'];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    TerritoryController_listQuotazioni: {
+        parameters: {
+            query?: {
+                page?: number;
+                pageSize?: number;
+                /** @description Publication `YYYY-S`; defaults to the latest loaded. */
+                semestre?: string;
+                /** @description Belfiore code of the municipality. */
+                codComune?: string;
+                /** @description Province code, e.g. `GE`. */
+                provincia?: string;
+                /** @description Property type as published, e.g. `Abitazioni civili`. */
+                tipologia?: string;
+                /** @description Condition as published, e.g. `NORMALE`. */
+                stato?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['TerritoryQuotazioniPageDto'];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    TerritoryController_listCompravendite: {
+        parameters: {
+            query?: {
+                page?: number;
+                pageSize?: number;
+                anno?: number;
+                /** @description Belfiore code of the municipality. */
+                codComune?: string;
+                /** @description Province code, e.g. `GE`. */
+                provincia?: string;
+                segmento?: 'RESIDENZIALE' | 'RESIDENZIALE_FINO_50MQ' | 'RESIDENZIALE_50_85MQ' | 'RESIDENZIALE_85_115MQ' | 'RESIDENZIALE_115_145MQ' | 'RESIDENZIALE_OLTRE_145MQ';
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['TerritoryCompravenditePageDto'];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    TerritoryController_comune: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Belfiore code of the municipality (e.g. `D969`). */
+                codComune: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['TerritoryComuneDetailDto'];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description The municipality is not in the registry. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+    TerritoryController_resolve: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                'application/json': components['schemas']['TerritoryResolveRequestDto'];
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    'application/json': components['schemas']['TerritoryResolveResponseDto'];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
+}
+
+type ApiPaths = paths;
+type ApiSchemas = components['schemas'];
+type GeocodeRequest = ApiSchemas['GeocodeRequestDto'];
+type GeocodeBatchRequest = ApiSchemas['GeocodeBatchRequestDto'];
+type GeocodeResult = ApiSchemas['GeocodeResultDto'];
+type GeocodeBatchResponse = ApiSchemas['GeocodeBatchResponseDto'];
+type ReverseGeocodeRequest = ApiSchemas['ReverseGeocodeRequestDto'];
+type ReverseGeocodeResult = ApiSchemas['ReverseGeocodeResultDto'];
+type TerritoryStatus = ApiSchemas['TerritoryStatusDto'];
+type TerritoryResolveRequest = ApiSchemas['TerritoryResolveRequestDto'];
+type TerritoryResolveResponse = ApiSchemas['TerritoryResolveResponseDto'];
+type TerritoryPointResult = ApiSchemas['TerritoryPointResultDto'];
+type TerritoryOmi = ApiSchemas['TerritoryOmiDto'];
+type TerritoryComune = ApiSchemas['TerritoryComuneDto'];
+type TerritoryComuneDetail = ApiSchemas['TerritoryComuneDetailDto'];
+type TerritoryDatasets = ApiSchemas['TerritoryDatasetsDto'];
+type TerritoryComuniPage = ApiSchemas['TerritoryComuniPageDto'];
+type TerritoryComuneRiga = ApiSchemas['TerritoryComuneRigaDto'];
+type TerritoryQuotazioniPage = ApiSchemas['TerritoryQuotazioniPageDto'];
+type TerritoryQuotazione = ApiSchemas['TerritoryQuotazioneDto'];
+type TerritoryCompravenditePage = ApiSchemas['TerritoryCompravenditePageDto'];
+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']>;
+interface RequestOptions {
+    signal?: AbortSignal;
+}
+interface GeoClientOptions {
+    /** Complete API root, including /api. Relative roots are supported in browsers. */
+    baseUrl: string;
+    /** Omit only when a trusted same-origin backend supplies the API key. */
+    apiKey?: string;
+    /** A real Fetch implementation returning a Response, not a parsed-body $fetch. */
+    fetch?: (request: Request) => Promise<Response>;
+}
+interface TerritoryClient {
+    status(options?: RequestOptions): Promise<TerritoryStatus>;
+    datasets(options?: RequestOptions): Promise<TerritoryDatasets>;
+    comuni(query?: TerritoryComuniQuery, options?: RequestOptions): Promise<TerritoryComuniPage>;
+    quotazioni(query?: TerritoryQuotazioniQuery, options?: RequestOptions): Promise<TerritoryQuotazioniPage>;
+    compravendite(query?: TerritoryCompravenditeQuery, options?: RequestOptions): Promise<TerritoryCompravenditePage>;
+    comune(codComune: string, options?: RequestOptions): Promise<TerritoryComuneDetail>;
+    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>;
+    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 };

package/dist/index.js

@@ -0,0 +1,79 @@
+// src/api-error.ts
+var ApiError = class extends Error {
+  constructor(response, body) {
+    super(`Geo API request failed with status ${response.status}`);
+    this.body = body;
+    this.name = "ApiError";
+    this.status = response.status;
+    this.headers = new Headers(response.headers);
+    this.requestId = response.headers.get("x-request-id") ?? void 0;
+  }
+  body;
+  status;
+  headers;
+  requestId;
+};
+async function readErrorBody(response) {
+  const text = await response.text();
+  if (!text) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+// src/client.ts
+import createClient from "openapi-fetch";
+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) {
+    throw new TypeError(
+      "baseUrl must be an HTTP(S) API root without credentials, query or fragment"
+    );
+  }
+  return url.href.replace(/\/+$/, "");
+}
+async function data(request) {
+  const result = await request;
+  if (result.data === void 0) throw new SyntaxError("Geo API returned an empty JSON response");
+  return result.data;
+}
+function territory(client) {
+  return {
+    status: (options) => data(client.GET("/territory/status", { ...options })),
+    datasets: (options) => data(client.GET("/territory/datasets", { ...options })),
+    comuni: (query, options) => data(client.GET("/territory/comuni", { ...options, params: { query } })),
+    quotazioni: (query, options) => data(client.GET("/territory/quotazioni", { ...options, params: { query } })),
+    compravendite: (query, options) => data(client.GET("/territory/compravendite", { ...options, params: { query } })),
+    comune: (codComune, options) => data(
+      client.GET("/territory/comuni/{codComune}", {
+        ...options,
+        params: { path: { codComune } }
+      })
+    ),
+    resolve: (input, options) => data(client.POST("/territory/resolve", { ...options, body: input }))
+  };
+}
+function createGeoClient(options) {
+  const client = createClient({
+    baseUrl: apiBaseUrl(options.baseUrl),
+    fetch: options.fetch,
+    headers: options.apiKey ? { "x-api-key": options.apiKey } : void 0
+  });
+  client.use({
+    async onResponse({ response }) {
+      if (!response.ok) throw new ApiError(response, await readErrorBody(response));
+    }
+  });
+  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 })),
+    territory: territory(client)
+  };
+}
+export {
+  ApiError,
+  createGeoClient
+};

package/package.json

@@ -1,6 +1,50 @@
 {
-  "name": "@seta-labs/geo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@seta-labs/geo",
+    "version": "0.1.0-next.0",
+    "description": "Typed Fetch client for the Seta Geo HTTP API",
+    "license": "UNLICENSED",
+    "type": "module",
+    "sideEffects": false,
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "engines": {
+        "node": ">=22"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Seta-Labs/seta-geo.git",
+        "directory": "packages/sdk"
+    },
+    "publishConfig": {
+        "access": "public",
+        "tag": "next",
+        "provenance": false
+    },
+    "scripts": {
+        "build": "tsup",
+        "lint": "eslint src tsup.config.ts",
+        "lint:fix": "eslint --fix src tsup.config.ts",
+        "typecheck": "tsc --noEmit",
+        "test:unit": "vitest run src"
+    },
+    "dependencies": {
+        "openapi-fetch": "^0.17.0"
+    },
+    "devDependencies": {
+        "@seta-geo/types": "workspace:*",
+        "@seta-labs/config": "^0.16.1",
+        "tsup": "^9.0.0",
+        "typescript": "^6.0.3",
+        "vitest": "^5.0.3"
+    }
+}