@teryt24/api 0.0.0-stage → 0.1.0

package/dist/client.js

@@ -0,0 +1,314 @@
+/**
+ * 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 { SDK_VERSION } from "./version.js";
+export { SDK_VERSION } from "./version.js";
+/**
+ * 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 class Teryt24ApiError extends Error {
+    status;
+    code;
+    details;
+    body;
+    constructor(status, body) {
+        const envelope = (typeof body === "object" && body !== null ? body : {});
+        const message = typeof envelope.message === "string" && envelope.message.length > 0
+            ? envelope.message
+            : `teryt24 API answered ${status}`;
+        super(message);
+        this.name = "Teryt24ApiError";
+        this.status = status;
+        this.code = typeof envelope.code === "string" ? envelope.code : null;
+        this.details = Array.isArray(envelope.details)
+            ? envelope.details.filter((d) => typeof d === "object" &&
+                d !== null &&
+                typeof d.message === "string")
+            : [];
+        this.body = body;
+    }
+}
+/**
+ * The server's maximum `offset` (the paged endpoints' documented bound).
+ * `pages()` stops at it — see its JSDoc.
+ */
+const MAX_OFFSET = 10_000;
+/**
+ * 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 class Teryt24Api {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    timeoutMs;
+    retry503Once;
+    retryDelayMs;
+    extraHeaders;
+    constructor(options = {}) {
+        this.baseUrl = (options.baseUrl ?? "https://teryt24.pl").replace(/\/+$/, "");
+        this.apiKey = options.apiKey;
+        this.fetchImpl = options.fetch ?? fetch;
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+        this.retry503Once = options.retry503Once ?? true;
+        this.retryDelayMs = options.retryDelayMs ?? 1_000;
+        this.extraHeaders = options.headers ?? {};
+    }
+    // --- /v1/localities --------------------------------------------------------
+    async searchLocalities(params) {
+        return this.get("/v1/localities", { query: params });
+    }
+    async locality(sym) {
+        return this.get("/v1/localities/{sym}", { path: { sym } });
+    }
+    // --- /v1/streets -------------------------------------------------------------
+    async searchStreets(params) {
+        return this.get("/v1/streets", { query: params });
+    }
+    async street(symUl) {
+        return this.get("/v1/streets/{symUl}", { path: { symUl } });
+    }
+    // --- /v1/postal-codes ----------------------------------------------------------
+    async searchPostalCodes(params) {
+        return this.get("/v1/postal-codes", { query: params });
+    }
+    async postalCode(code) {
+        return this.get("/v1/postal-codes/{code}", { path: { code } });
+    }
+    /**
+     * 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.
+     */
+    async postalCodesBulk(body) {
+        return this.post("/v1/postal-codes/bulk", body);
+    }
+    // --- /v1/regions -------------------------------------------------------------------
+    async regions() {
+        return this.get("/v1/regions", {});
+    }
+    async regionCounties(code) {
+        return this.get("/v1/regions/{code}/counties", { path: { code } });
+    }
+    async regionMunicipalities(code, query = {}) {
+        return this.get("/v1/regions/{code}/municipalities", {
+            path: { code },
+            query,
+        });
+    }
+    async regionDemography(code) {
+        return this.get("/v1/regions/{code}/demography", { path: { code } });
+    }
+    async regionCensus(code) {
+        return this.get("/v1/regions/{code}/census", { path: { code } });
+    }
+    async areaCode(terc) {
+        return this.get("/v1/area-codes/{terc}", { path: { terc } });
+    }
+    // --- boundaries -----------------------------------------------------------------------
+    async boundaries(kind, query = {}) {
+        const path = kind === "regions" ? "/v1/boundaries/regions" : "/v1/boundaries/counties";
+        return this.getGeo(path, query);
+    }
+    // --- geocoding ---------------------------------------------------------------------------
+    async geocode(params) {
+        return this.get("/v1/geocode", { query: params });
+    }
+    /**
+     * 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.
+     */
+    async geocodeBatch(body) {
+        return this.post("/v1/geocode/batch", body);
+    }
+    async validate(params) {
+        return this.get("/v1/validate", { query: params });
+    }
+    async reverseGeocode(params) {
+        return this.get("/v1/reverse-geocode", { query: params });
+    }
+    async autosuggest(params) {
+        return this.get("/v1/autosuggest", { query: params });
+    }
+    // --- the feed and the meta surfaces ---------------------------------------------------------
+    async changes(params = {}) {
+        return this.get("/v1/changes", { query: params });
+    }
+    async datasets() {
+        return this.get("/v1/datasets", {});
+    }
+    async health() {
+        return this.get("/health", {});
+    }
+    async whoami() {
+        return this.get("/v1/whoami", {});
+    }
+    async usage(params = {}) {
+        return this.get("/v1/usage", { query: params });
+    }
+    async *pages(endpoint, params) {
+        let offset = typeof params.offset === "number" ? params.offset : 0;
+        for (;;) {
+            const page = (await this.getPage(endpoint, params));
+            yield page;
+            const meta = page.meta;
+            if (!meta)
+                return;
+            const next = meta.offset + meta.limit;
+            if (next >= meta.total)
+                return;
+            if (next > MAX_OFFSET)
+                return; // documented bound — see the JSDoc
+            params = { ...params, offset: next };
+        }
+    }
+    getPage(endpoint, params) {
+        if (endpoint === "localities") {
+            return this.get("/v1/localities", { query: params });
+        }
+        if (endpoint === "postalCodes") {
+            return this.get("/v1/postal-codes", { query: params });
+        }
+        return this.get("/v1/changes", { query: params });
+    }
+    // --- the transport ---------------------------------------------------------------------------------
+    headers(extra) {
+        const headers = {
+            accept: "application/json",
+            "user-agent": `@teryt24/api/${SDK_VERSION}`,
+            ...this.extraHeaders,
+            ...extra,
+        };
+        if (this.apiKey !== undefined)
+            headers["x-api-key"] = this.apiKey;
+        return headers;
+    }
+    url(path, params) {
+        const search = new URLSearchParams();
+        for (const [key, value] of Object.entries(params ?? {})) {
+            if (value === undefined || value === null || value === "")
+                continue;
+            search.set(key, String(value));
+        }
+        const qs = search.toString();
+        return `${this.baseUrl}${path}${qs ? `?${qs}` : ""}`;
+    }
+    async request(url, init) {
+        const response = await this.fetchImpl(url, {
+            ...init,
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        if (response.status === 503 && this.retry503Once) {
+            // The documented 503s (warming up, dataset not ingested, the
+            // handler budget) all mean "come back shortly". One retry is the
+            // client's own patience; a second failure is thrown as-is.
+            await new Promise((resolve) => setTimeout(resolve, this.retryDelayMs));
+            return this.fetchImpl(url, {
+                ...init,
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        return response;
+    }
+    async parse(response) {
+        if (response.ok) {
+            return (await response.json());
+        }
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            // A non-JSON error answer (an edge page, a proxy failure) still
+            // throws with the status; the envelope fields stay null.
+        }
+        throw new Teryt24ApiError(response.status, body);
+    }
+    /**
+     * 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.
+     */
+    async get(template, params) {
+        const split = params;
+        const named = split.path ?? {};
+        let concrete = template;
+        for (const [name, value] of Object.entries(named)) {
+            if (value === undefined || value === null) {
+                throw new TypeError(`@teryt24/api: missing path parameter "${name}" for ${template}`);
+            }
+            concrete = concrete.replace(`{${name}}`, encodeURIComponent(String(value)));
+        }
+        const url = this.url(concrete, split.query);
+        const response = await this.request(url, { method: "GET", headers: this.headers() });
+        return this.parse(response);
+    }
+    /** The boundaries endpoints answer `application/geo+json` (RFC 7946). */
+    async getGeo(path, params) {
+        const url = this.url(path, params);
+        const response = await this.request(url, { method: "GET", headers: this.headers() });
+        if (response.ok)
+            return (await response.json());
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            // as in parse()
+        }
+        throw new Teryt24ApiError(response.status, body);
+    }
+    async post(template, body) {
+        const url = this.url(template);
+        const response = await this.request(url, {
+            method: "POST",
+            headers: this.headers({ "content-type": "application/json" }),
+            body: JSON.stringify(body),
+        });
+        return this.parse(response);
+    }
+}
+/** A factory for the functional style; the class is the same thing. */
+export function createTeryt24Api(options) {
+    return new Teryt24Api(options);
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@teryt24/api` — the official TypeScript client for the teryt24.pl API
+ * (Polish registry & geo data: GUS TERYT, GUGiK PRG, GeoNames postal).
+ *
+ * Types are generated from the served OpenAPI document; errors wrap the
+ * published `{error, message, code, details}` envelope; the documented
+ * 503s are retried once. Server use only — see the class docblock.
+ */
+export { SDK_VERSION } from "./version.js";
+export { Teryt24Api, createTeryt24Api, Teryt24ApiError, } from "./client.js";
+export type { Teryt24ClientOptions, ErrorDetail, ErrorBody, LocalitiesQuery, LocalitiesResponse, LocalityDetail, StreetsQuery, StreetsResponse, StreetDetail, PostalCodesQuery, PostalCodesResponse, PostalCodeDetail, PostalCodeRow, PostalCodesNearestRow, RegionsResponse, RegionCountiesResponse, RegionMunicipalitiesResponse, RegionDemography, RegionCensus, AreaCodeResponse, BoundaryFeatureCollection, GeocodeQuery, GeocodeResponse, GeocodeBatchRequest, GeocodeBatchResponse, ValidateQuery, ValidateResponse, ReverseGeocodeQuery, ReverseGeocodeResponse, AutosuggestQuery, AutosuggestResponse, ChangesQuery, ChangesResponse, DatasetsResponse, WhoamiResponse, UsageQuery, UsageResponse, HealthResponse, PostalBulkRequest, PostalBulkResponse, PagedEndpoint, } from "./client.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@teryt24/api` — the official TypeScript client for the teryt24.pl API
+ * (Polish registry & geo data: GUS TERYT, GUGiK PRG, GeoNames postal).
+ *
+ * Types are generated from the served OpenAPI document; errors wrap the
+ * published `{error, message, code, details}` envelope; the documented
+ * 503s are retried once. Server use only — see the class docblock.
+ */
+export { SDK_VERSION } from "./version.js";
+export { Teryt24Api, createTeryt24Api, Teryt24ApiError, } from "./client.js";