@teryt24/api 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# @teryt24/api
 
-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.
+The official TypeScript client for the [teryt24.pl API](https://teryt24.pl/docs) —
+Polish registry & geo data: localities and cities (GUS TERYT SIMC), streets
+(ULIC), postal codes (PNA), address validation and geocoding (GUGiK PRG
+address points).
+
+- Types are **generated from the served OpenAPI document** — a server-side
+  field rename breaks the build, not your code at runtime.
+- Errors wrap the published `{error, message, code, details}` envelope
+  ([the error contract](https://teryt24.pl/docs)): `Teryt24ApiError.code`
+  is the branch, `details` the field-level array.
+- The documented **503s are retried once** ("warming up / dataset not
+  ingested"), so a first-deploy integration does not crash on them.
+
+## Install
+
+```bash
+npm install @teryt24/api
+```
+
+## Use
+
+```js
+import { Teryt24Api } from "@teryt24/api";
+
+const teryt = new Teryt24Api({
+  apiKey: process.env.TERYT24_API_KEY, // optional — keyless calls share a 60 req/min/IP bucket
+});
+
+// Locality autocomplete (GUS SIMC, ≈54k entries)
+const { localities } = await teryt.searchLocalities({ q: "wroc", limit: 5 });
+
+// One locality's full record (postal codes, street count, census)
+const detail = await teryt.locality("0986745");
+
+// Street search — within one locality, or country-wide
+const { streets } = await teryt.searchStreets({ city: "0986745", q: "legnicka" });
+
+// Postal codes — prefix, per-locality, or nearest (PRG centroids)
+const { postalCodes } = await teryt.searchPostalCodes({ q: "59-7", limit: 10 });
+
+// Address validation — the verdict, per-field match kinds, issues
+const verdict = await teryt.validate({
+  address: "Wrocław, ul. Eugeniusza Horbaczewskiego 35",
+});
+
+// Geocoding to the house number (GUGiK PRG points)
+const point = await teryt.geocode({ sym: "0986745", streetName: "horbaczewskiego", number: "35" });
+```
+
+Every method is typed from the API's own OpenAPI document — editor
+completion shows the real query parameters and response fields.
+
+## Paging
+
+The paged endpoints (`localities`, `postalCodes`, `changes`) carry
+`meta: { total, offset, limit }`. The `pages()` async iterator walks them:
+
+```js
+for await (const page of teryt.pages("localities", { province: "02" })) {
+  for (const locality of page.localities) console.log(locality.name);
+}
+```
+
+**Where it breaks:** the API's documented maximum `offset` is 10 000. When
+the next page would sit beyond it, the iterator ends after the page it
+just yielded — narrow the query instead (filters, a longer prefix, a date
+window).
+
+## Errors
+
+```js
+import { Teryt24ApiError } from "@teryt24/api";
+
+try {
+  await teryt.locality("0000000");
+} catch (error) {
+  if (error instanceof Teryt24ApiError) {
+    error.status;  // 404
+    error.code;    // "locality_not_found" — branch on this, never on message
+    error.details; // field-level array on 400s
+    error.message; // a human sentence (wording may change without notice)
+  }
+}
+```
+
+The full table of codes lives in [the compatibility policy](https://teryt24.pl/docs)
+(`docs/API-COMPATIBILITY.md` §5 in the service's repository). `5xx` mean
+"retry later" (503s are retried once for you); `429` carries `Retry-After`.
+
+## Keys and browsers
+
+The API key travels in the `X-API-Key` header. This client is typed for
+**server use** — a browser would expose the key to every visitor. For
+browser forms use the keyless API directly, or proxy through your own
+backend: see [the address widget's API-key proxy guidance](https://teryt24.pl/docs/widget).
+
+## Attribution
+
+When you display results in an application, website, map or report,
+attribute the data — `Data: GUS TERYT, PRG address points (GUGiK),
+GeoNames postal codes — via teryt24.pl` — per the
+[usage policy](https://teryt24.pl/usage-policy). Server-side-only use is
+exempt.
+
+## The MCP server
+
+An agent that should call this API through tool calls can use
+[`@teryt24/mcp`](https://www.npmjs.com/package/@teryt24/mcp) — a stdio MCP
+server built on this package (12 tools, responses verbatim).

package/dist/client.d.ts

@@ -0,0 +1,289 @@
+/**
+ * The hand-written thin client for the teryt24.pl API (`@teryt24/api`).
+ *
+ * Three rules shape it:
+ *
+ * 1. **Types come from the generated document.** Every method's params
+ *    and response are indexed out of `openapi.gen.d.ts`, which
+ *    scripts/build-sdk-types.ts generates from `GET /openapi.json` — the
+ *    doc the routes' own zod schemas produce. A server-side field rename
+ *    therefore becomes a typecheck failure in the SDK build (and in the
+ *    consumer fixture), never a silent `undefined` in a customer's code.
+ * 2. **Errors are the published envelope.** Every /v1 error body carries
+ *    `{error, message, code, details}` (docs/API-COMPATIBILITY.md §5);
+ *    the client wraps it in a typed `Teryt24ApiError` whose `code` is the
+ *    branch and whose `details` is the field-level array. Nothing here
+ *    string-matches `error` or `message` — `code` is the contract.
+ * 3. **The documented 503s are retried once.** Warming up and the
+ *    not-yet-ingested datasets answer 503 "try again shortly" on a
+ *    freshly deployed instance; a first-deploy integration should survive
+ *    that without an explicit retry loop, so the client retries a 503
+ *    exactly once (configurable, and off when `retry503Once: false`).
+ *
+ * The client is typed for SERVER use: the API key travels in the
+ * `X-API-Key` header, and a browser would expose it to every visitor. The
+ * widget's documentation (https://teryt24.pl/docs/widget) describes the
+ * proxy pattern for browsers; this package does not pretend a key is safe
+ * client-side.
+ */
+import type { paths } from "./openapi.gen.js";
+export { SDK_VERSION } from "./version.js";
+/** One field-level validation detail, as the error envelope carries it. */
+export interface ErrorDetail {
+    path: string;
+    message: string;
+}
+/** The body keys a /v1 error answer carries (docs/API-COMPATIBILITY.md §5). */
+export interface ErrorBody {
+    error?: string;
+    message?: string;
+    code?: string;
+    details?: ErrorDetail[];
+    [key: string]: unknown;
+}
+/**
+ * A non-2xx answer from the API. `code` is the machine-readable branch
+ * (the table lives in docs/API-COMPATIBILITY.md §5), `details` the
+ * field-level array a 400 carries, and `body` the parsed body in full —
+ * new fields arrive without notice and stay reachable through it.
+ */
+export declare class Teryt24ApiError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    readonly details: readonly ErrorDetail[];
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}
+export interface Teryt24ClientOptions {
+    /**
+     * The API key sent as `X-API-Key` (raises the rate limit and is what
+     * the metering applies to). Optional: the API serves keyless callers
+     * from a shared 60 req/min/IP bucket.
+     */
+    apiKey?: string;
+    /** The service base URL. Default: `https://teryt24.pl`. */
+    baseUrl?: string;
+    /** The fetch implementation. Default: the global one (Node ≥ 18). */
+    fetch?: typeof fetch;
+    /** Per-attempt timeout in milliseconds. Default: 10 000. */
+    timeoutMs?: number;
+    /**
+     * Retry a 503 exactly once (the documented "warming up / dataset not
+     * ingested" contract). Default: true.
+     */
+    retry503Once?: boolean;
+    /** The wait before that one retry, in milliseconds. Default: 1 000. */
+    retryDelayMs?: number;
+    /** Extra headers (a meaningful `User-Agent` naming your application is encouraged by the usage policy). */
+    headers?: Record<string, string>;
+}
+/**
+ * The parameters object of one GET endpoint, as the generated document
+ * declares it: `{ query?, path?, header?, cookie? }` with `never` for the
+ * kinds the endpoint does not take. A method passes the members it needs
+ * (`{ query }` or `{ path: { sym } }`); the private transport splits them.
+ */
+type GetParametersOf<Path extends keyof paths & string> = paths[Path] extends {
+    get: {
+        parameters: infer P;
+    };
+} ? P : never;
+/** The 200 JSON body of one GET endpoint, from the generated document. */
+type BodyOf<Path extends keyof paths & string> = paths[Path] extends {
+    get: {
+        responses: {
+            200: {
+                content: {
+                    "application/json": infer B;
+                };
+            };
+        };
+    };
+} ? B : never;
+/** The 200 JSON body of one POST endpoint (the batch/bulk endpoints). */
+type PostBodyOf<Path extends keyof paths & string> = paths[Path] extends {
+    post: {
+        responses: {
+            200: {
+                content: {
+                    "application/json": infer B;
+                };
+            };
+        };
+    };
+} ? B : never;
+/** The JSON request body of one POST endpoint, from the document. */
+type PostRequestOf<Path extends keyof paths & string> = paths[Path] extends {
+    post: {
+        requestBody: {
+            content: {
+                "application/json": infer B;
+            };
+        };
+    };
+} ? B : never;
+/** The query type of one GET endpoint (the method signatures' ergonomics). */
+type QueryOf<Path extends keyof paths & string> = GetParametersOf<Path> extends {
+    query?: infer Q;
+} ? NonNullable<Q> : never;
+export type LocalitiesQuery = QueryOf<"/v1/localities">;
+export type LocalitiesResponse = BodyOf<"/v1/localities">;
+export type LocalityDetail = BodyOf<"/v1/localities/{sym}">;
+export type StreetsQuery = QueryOf<"/v1/streets">;
+export type StreetsResponse = BodyOf<"/v1/streets">;
+export type StreetDetail = BodyOf<"/v1/streets/{symUl}">;
+export type PostalCodesQuery = QueryOf<"/v1/postal-codes">;
+export type PostalCodesResponse = BodyOf<"/v1/postal-codes">;
+export type PostalCodeDetail = BodyOf<"/v1/postal-codes/{code}">;
+/** One row of either postal-codes list mode (the document's response union). */
+export type PostalCodeRow = PostalCodesResponse extends {
+    postalCodes: (infer R)[];
+} ? R : never;
+/** The nearest-mode row, narrowed by its `distanceKm` field. */
+export type PostalCodesNearestRow = Extract<PostalCodeRow, {
+    distanceKm: number;
+}>;
+export type RegionsResponse = BodyOf<"/v1/regions">;
+export type RegionCountiesResponse = BodyOf<"/v1/regions/{code}/counties">;
+export type RegionMunicipalitiesResponse = BodyOf<"/v1/regions/{code}/municipalities">;
+export type RegionDemography = BodyOf<"/v1/regions/{code}/demography">;
+export type RegionCensus = BodyOf<"/v1/regions/{code}/census">;
+export type AreaCodeResponse = BodyOf<"/v1/area-codes/{terc}">;
+export type BoundaryFeatureCollection = paths["/v1/boundaries/regions"] extends {
+    get: {
+        responses: {
+            200: {
+                content: {
+                    "application/geo+json": infer B;
+                };
+            };
+        };
+    };
+} ? B : never;
+export type GeocodeQuery = QueryOf<"/v1/geocode">;
+export type GeocodeResponse = BodyOf<"/v1/geocode">;
+export type GeocodeBatchRequest = PostRequestOf<"/v1/geocode/batch">;
+export type GeocodeBatchResponse = PostBodyOf<"/v1/geocode/batch">;
+export type ValidateQuery = QueryOf<"/v1/validate">;
+export type ValidateResponse = BodyOf<"/v1/validate">;
+export type ReverseGeocodeQuery = QueryOf<"/v1/reverse-geocode">;
+export type ReverseGeocodeResponse = BodyOf<"/v1/reverse-geocode">;
+export type AutosuggestQuery = QueryOf<"/v1/autosuggest">;
+export type AutosuggestResponse = BodyOf<"/v1/autosuggest">;
+export type ChangesQuery = QueryOf<"/v1/changes">;
+export type ChangesResponse = BodyOf<"/v1/changes">;
+export type DatasetsResponse = BodyOf<"/v1/datasets">;
+export type WhoamiResponse = BodyOf<"/v1/whoami">;
+export type UsageQuery = QueryOf<"/v1/usage">;
+export type UsageResponse = BodyOf<"/v1/usage">;
+export type PostalBulkRequest = PostRequestOf<"/v1/postal-codes/bulk">;
+export type PostalBulkResponse = PostBodyOf<"/v1/postal-codes/bulk">;
+/**
+ * The deep `/health` view. The document types it as an open object (the
+ * advisory shape moves with the datasets an instance serves); the stable
+ * fields it carries are documented in the service's README and at
+ * https://teryt24.pl/docs.
+ */
+export type HealthResponse = BodyOf<"/health">;
+/** The paged endpoints the `pages()` iterator walks. */
+export type PagedEndpoint = "localities" | "postalCodes" | "changes";
+/**
+ * The thin client. Create one per process (or per credential) and reuse
+ * it: it holds no connection pool of its own, only configuration.
+ *
+ * ```ts
+ * import { Teryt24Api } from "@teryt24/api";
+ *
+ * const teryt = new Teryt24Api({ apiKey: process.env.TERYT24_API_KEY });
+ * const { localities, meta } = await teryt.searchLocalities({ q: "wroc" });
+ * for await (const page of teryt.pages("localities", { q: "wroc" })) {
+ *   // page.localities …
+ * }
+ * ```
+ */
+export declare class Teryt24Api {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly retry503Once;
+    private readonly retryDelayMs;
+    private readonly extraHeaders;
+    constructor(options?: Teryt24ClientOptions);
+    searchLocalities(params: LocalitiesQuery): Promise<LocalitiesResponse>;
+    locality(sym: string): Promise<LocalityDetail>;
+    searchStreets(params: StreetsQuery): Promise<StreetsResponse>;
+    street(symUl: string): Promise<StreetDetail>;
+    searchPostalCodes(params: PostalCodesQuery): Promise<PostalCodesResponse>;
+    postalCode(code: string): Promise<PostalCodeDetail>;
+    /**
+     * POST /v1/postal-codes/bulk — many codes, one request, one rate-limit
+     * slot. The response rows are the detail endpoint's rows, keyed by the
+     * caller's own `id` echo.
+     */
+    postalCodesBulk(body: PostalBulkRequest): Promise<PostalBulkResponse>;
+    regions(): Promise<RegionsResponse>;
+    regionCounties(code: string): Promise<RegionCountiesResponse>;
+    regionMunicipalities(code: string, query?: {
+        county?: string;
+    }): Promise<RegionMunicipalitiesResponse>;
+    regionDemography(code: string): Promise<RegionDemography>;
+    regionCensus(code: string): Promise<RegionCensus>;
+    areaCode(terc: string): Promise<AreaCodeResponse>;
+    boundaries(kind: "regions" | "counties", query?: {
+        province?: string;
+    }): Promise<BoundaryFeatureCollection>;
+    geocode(params: GeocodeQuery): Promise<GeocodeResponse>;
+    /**
+     * POST /v1/geocode/batch — many addresses through the same pipeline
+     * GET /v1/geocode runs, one request. A malformed item answers as a
+     * `status: "error"` row; the HTTP status is 200 whenever the envelope
+     * itself parsed.
+     */
+    geocodeBatch(body: GeocodeBatchRequest): Promise<GeocodeBatchResponse>;
+    validate(params: ValidateQuery): Promise<ValidateResponse>;
+    reverseGeocode(params: ReverseGeocodeQuery): Promise<ReverseGeocodeResponse>;
+    autosuggest(params: AutosuggestQuery): Promise<AutosuggestResponse>;
+    changes(params?: ChangesQuery): Promise<ChangesResponse>;
+    datasets(): Promise<DatasetsResponse>;
+    health(): Promise<HealthResponse>;
+    whoami(): Promise<WhoamiResponse>;
+    usage(params?: UsageQuery): Promise<UsageResponse>;
+    /**
+     * Walks a paged endpoint page by page, following `meta.total` /
+     * `meta.offset` / `meta.limit` until the selection is exhausted.
+     *
+     * **Where it breaks:** the API's documented maximum `offset` is 10 000
+     * (a deliberate depth bound — see /docs). When the NEXT page would sit
+     * beyond it, the iterator ENDS after the page it just yielded — it does
+     * not throw, and it does not silently continue from the other side. A
+     * selection deeper than 10 000 rows must be narrowed (province /
+     * county / municipality / population filters on localities; a longer
+     * prefix on postal codes; a date window on changes) — the requests this
+     * iterator would otherwise take are 400s, not data.
+     *
+     * Yields the same body the endpoint's own method returns (`rows` key +
+     * `meta`), so a consumer can switch between paging styles freely.
+     */
+    pages(endpoint: "localities", params: LocalitiesQuery): AsyncGenerator<LocalitiesResponse, void, undefined>;
+    pages(endpoint: "postalCodes", params: PostalCodesQuery): AsyncGenerator<PostalCodesResponse, void, undefined>;
+    pages(endpoint: "changes", params: ChangesQuery): AsyncGenerator<ChangesResponse, void, undefined>;
+    private getPage;
+    private headers;
+    private url;
+    private request;
+    private parse;
+    /**
+     * The GET transport. The document's parameters object is split here:
+     * `path` fills the `{sym}`-shaped holes in the template, `query` rides
+     * the search string.
+     */
+    private get;
+    /** The boundaries endpoints answer `application/geo+json` (RFC 7946). */
+    private getGeo;
+    private post;
+}
+/** A factory for the functional style; the class is the same thing. */
+export declare function createTeryt24Api(options?: Teryt24ClientOptions): Teryt24Api;
+/** Exposed for typed consumers that branch on a path's parameters object. */
+export type { GetParametersOf, QueryOf, BodyOf, PostBodyOf, PostRequestOf };