@maschinenlesbar.org/regionalatlas-cli 0.0.1

package/dist/src/client/engine.d.ts

@@ -0,0 +1,77 @@
+import { type Transport } from "./http.js";
+import { type QueryParams } from "./query.js";
+/** The ArcGIS MapServer host that answers the dynamicLayer data queries. */
+export declare const DEFAULT_BASE_URL = "https://www.gis-idmz.nrw.de";
+export interface RawResponse {
+    data: Buffer;
+    contentType: string;
+    status: number;
+}
+export interface EngineOptions {
+    /** Base URL of the ArcGIS data host. Defaults to the gis-idmz.nrw.de MapServer host. */
+    baseUrl?: string;
+    /** Swappable transport. Defaults to the built-in node http/https transport. */
+    transport?: Transport;
+    /** Value of the User-Agent header. */
+    userAgent?: string;
+    /** Extra headers sent on every request. */
+    defaultHeaders?: Record<string, string>;
+    /** Per-request timeout in milliseconds (0 disables). */
+    timeoutMs?: number;
+    /** Number of automatic retries for transient (429/503) responses. */
+    maxRetries?: number;
+    /** Base backoff between retries in milliseconds (grows linearly). */
+    retryDelayMs?: number;
+    /**
+     * Hard cap on response body size in bytes (defends against memory exhaustion
+     * from a hostile/buggy endpoint). Defaults to 100 MiB; set to 0 for no limit.
+     */
+    maxResponseBytes?: number;
+    /** Injectable sleep, primarily for deterministic tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Strip control characters out of a string that originates in an
+ * attacker-controlled response — the ArcGIS `error` detail and the non-JSON body
+ * snippet — before it flows into a `RegionalatlasApiError.message` that run.ts
+ * prints raw to stderr. `JSON.parse` decodes an escaped ESC (a backslash-u-001b
+ * sequence) in an error body into a real ESC byte, so without this a hostile or
+ * MITM'd endpoint could inject
+ * ANSI/OSC terminal escape sequences (screen clears, title changes, output
+ * spoofing) when the message reaches the user's terminal. The success path is
+ * already safe (`JSON.stringify` escapes these). Removes all C0 controls (except
+ * tab/newline), DEL, and the C1 range; implemented via char codes so this source
+ * file never contains a raw control byte.
+ */
+export declare function sanitizeServerText(text: string): string;
+export declare class RequestEngine {
+    private readonly baseUrl;
+    private readonly transport;
+    private readonly userAgent;
+    private readonly defaultHeaders;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private readonly maxResponseBytes;
+    private readonly sleep;
+    constructor(options?: EngineOptions);
+    /** Build a fully-qualified URL from a path (on the data host) and optional query. */
+    buildUrl(path: string, query?: QueryParams): string;
+    /** Build a fully-qualified URL from an absolute base URL and optional query. */
+    buildAbsoluteUrl(absoluteUrl: string, query?: QueryParams): string;
+    /**
+     * Perform a GET with Accept negotiation and transient-error retries. Redirects
+     * are NOT followed — the canonical host answers directly, so a 3xx surfaces as
+     * an error.
+     */
+    private requestUrl;
+    /** GET a path on the data host with query params. */
+    request(path: string, query?: QueryParams, accept?: string): Promise<RawResponse>;
+    /** GET a path on the data host and parse the JSON reply into `T`. */
+    getJson<T>(path: string, query?: QueryParams): Promise<T>;
+    /** GET a fully-qualified absolute URL (e.g. the catalogue host) and parse JSON into `T`. */
+    getJsonAbsolute<T>(absoluteUrl: string, query?: QueryParams): Promise<T>;
+    private decodeJson;
+    private toApiError;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/src/client/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/client/engine.ts"],"names":[],"mappings":"AAWA,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAGhE,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,gCAAgC,CAAC;AAG9D,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYvD;AAKD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyB;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;gBAE1C,OAAO,GAAE,aAAkB;IAYvC,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,MAAM;IAMnD,gFAAgF;IAChF,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,MAAM;IAMlE;;;;OAIG;YACW,UAAU;IAkCxB,qDAAqD;IAC/C,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,EAAE,MAAM,SAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;IAInG,qEAAqE;IAC/D,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IAI/D,4FAA4F;IACtF,eAAe,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IAK9E,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,UAAU;CA0BnB"}

package/dist/src/client/engine.js

@@ -0,0 +1,167 @@
+// The request engine: turns logical (path, query) calls into HTTP GET requests via
+// a Transport, applies retry/backoff for transient statuses (429, 503), and decodes
+// JSON responses. The Regionalatlas is backed by an ArcGIS MapServer — an
+// unauthenticated GET API whose parameters travel in the query string.
+//
+// Two-host note: the *data* queries hit the ArcGIS MapServer (`baseUrl`, default
+// the gis-idmz.nrw.de host), while the *indicator catalogue* is a static JSON file
+// on the statistikportal.de host. The engine therefore also supports GETting a
+// fully-qualified absolute URL (`requestAbsolute`) so the catalogue can be fetched
+// without changing the data `baseUrl`.
+import { nodeHttpTransport } from "./http.js";
+import { buildQueryString } from "./query.js";
+import { RegionalatlasApiError, RegionalatlasParseError } from "./errors.js";
+/** The ArcGIS MapServer host that answers the dynamicLayer data queries. */
+export const DEFAULT_BASE_URL = "https://www.gis-idmz.nrw.de";
+const DEFAULT_USER_AGENT = "regionalatlas-cli";
+const DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024 * 1024;
+/**
+ * Strip control characters out of a string that originates in an
+ * attacker-controlled response — the ArcGIS `error` detail and the non-JSON body
+ * snippet — before it flows into a `RegionalatlasApiError.message` that run.ts
+ * prints raw to stderr. `JSON.parse` decodes an escaped ESC (a backslash-u-001b
+ * sequence) in an error body into a real ESC byte, so without this a hostile or
+ * MITM'd endpoint could inject
+ * ANSI/OSC terminal escape sequences (screen clears, title changes, output
+ * spoofing) when the message reaches the user's terminal. The success path is
+ * already safe (`JSON.stringify` escapes these). Removes all C0 controls (except
+ * tab/newline), DEL, and the C1 range; implemented via char codes so this source
+ * file never contains a raw control byte.
+ */
+export function sanitizeServerText(text) {
+    let out = "";
+    for (const ch of text) {
+        const n = ch.codePointAt(0) ?? 0;
+        if (n === 0x09 || n === 0x0a) {
+            out += ch;
+            continue;
+        }
+        if (n <= 8 || (n >= 0x0b && n <= 0x1f) || (n >= 0x7f && n <= 0x9f))
+            continue;
+        out += ch;
+    }
+    return out;
+}
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class RequestEngine {
+    baseUrl;
+    transport;
+    userAgent;
+    defaultHeaders;
+    timeoutMs;
+    maxRetries;
+    retryDelayMs;
+    maxResponseBytes;
+    sleep;
+    constructor(options = {}) {
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.transport = options.transport ?? nodeHttpTransport;
+        this.userAgent = options.userAgent ?? DEFAULT_USER_AGENT;
+        this.defaultHeaders = options.defaultHeaders ?? {};
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.retryDelayMs = options.retryDelayMs ?? 200;
+        this.maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+        this.sleep = options.sleep ?? realSleep;
+    }
+    /** Build a fully-qualified URL from a path (on the data host) and optional query. */
+    buildUrl(path, query) {
+        const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+        const qs = query ? buildQueryString(query) : "";
+        return `${this.baseUrl}${normalizedPath}${qs ? `?${qs}` : ""}`;
+    }
+    /** Build a fully-qualified URL from an absolute base URL and optional query. */
+    buildAbsoluteUrl(absoluteUrl, query) {
+        const qs = query ? buildQueryString(query) : "";
+        if (!qs)
+            return absoluteUrl;
+        return absoluteUrl.includes("?") ? `${absoluteUrl}&${qs}` : `${absoluteUrl}?${qs}`;
+    }
+    /**
+     * Perform a GET with Accept negotiation and transient-error retries. Redirects
+     * are NOT followed — the canonical host answers directly, so a 3xx surfaces as
+     * an error.
+     */
+    async requestUrl(url, accept) {
+        const headers = {
+            ...this.defaultHeaders,
+            Accept: accept,
+            "User-Agent": this.userAgent,
+        };
+        let attempt = 0;
+        for (;;) {
+            const response = await this.transport({
+                method: "GET",
+                url,
+                headers,
+                timeoutMs: this.timeoutMs,
+                ...(this.maxResponseBytes > 0 ? { maxResponseBytes: this.maxResponseBytes } : {}),
+            });
+            const status = response.status;
+            const retryable = status === 429 || status === 503;
+            if (retryable && attempt < this.maxRetries) {
+                attempt += 1;
+                await this.sleep(this.retryDelayMs * attempt);
+                continue;
+            }
+            const contentType = String(response.headers["content-type"] ?? "");
+            if (status < 200 || status >= 300) {
+                throw this.toApiError(url, status, response.body);
+            }
+            return { data: response.body, contentType, status };
+        }
+    }
+    /** GET a path on the data host with query params. */
+    async request(path, query, accept = "application/json") {
+        return this.requestUrl(this.buildUrl(path, query), accept);
+    }
+    /** GET a path on the data host and parse the JSON reply into `T`. */
+    async getJson(path, query) {
+        return this.decodeJson(await this.request(path, query), path);
+    }
+    /** GET a fully-qualified absolute URL (e.g. the catalogue host) and parse JSON into `T`. */
+    async getJsonAbsolute(absoluteUrl, query) {
+        const url = this.buildAbsoluteUrl(absoluteUrl, query);
+        return this.decodeJson(await this.requestUrl(url, "application/json"), url);
+    }
+    decodeJson(res, source) {
+        const text = res.data.toString("utf8");
+        if (res.status === 204 || text.trim().length === 0) {
+            return null;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch (cause) {
+            throw new RegionalatlasParseError(`Failed to parse JSON response from ${source}`, { cause });
+        }
+    }
+    toApiError(url, status, body) {
+        const text = body.toString("utf8");
+        let detail;
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed?.error && typeof parsed.error.message === "string")
+                detail = parsed.error.message;
+            else if (typeof parsed?.message === "string")
+                detail = parsed.message;
+            else if (typeof parsed?.detail === "string")
+                detail = parsed.detail;
+        }
+        catch {
+            // Not JSON (e.g. an HTML error page). Surface a short, whitespace-collapsed
+            // snippet of a textual body; skip HTML pages (start with "<").
+            const snippet = text.trim().replace(/\s+/g, " ");
+            if (snippet.length > 0 && !snippet.startsWith("<")) {
+                detail = snippet.length > 200 ? `${snippet.slice(0, 200)}…` : snippet;
+            }
+        }
+        // `detail` came from the attacker-controlled response body; strip control
+        // characters so a hostile endpoint cannot drive terminal escape sequences
+        // into stderr via the error message.
+        if (detail !== undefined)
+            detail = sanitizeServerText(detail);
+        return new RegionalatlasApiError({ status, url, method: "GET", body: text, detail });
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/src/client/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/client/engine.ts"],"names":[],"mappings":"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"}

package/dist/src/client/errors.d.ts

@@ -0,0 +1,51 @@
+/** Base class for every error originating from this client. */
+export declare class RegionalatlasError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The API signalled a failure. The Regionalatlas ArcGIS MapServer is unusual: it
+ * answers HTTP 200 even for logical errors, carrying the message in an `error`
+ * object (`{code, message, details}`) — e.g. a malformed query or an invalid
+ * parameter. This error models both worlds:
+ *  - `status` is set for a genuine transport/HTTP failure (non-2xx);
+ *  - `arcgisCode` is set for a logical ArcGIS error (from `error.code`).
+ * `detail` holds the human-readable message in either case.
+ */
+export declare class RegionalatlasApiError extends RegionalatlasError {
+    readonly status: number | undefined;
+    readonly arcgisCode: number | undefined;
+    readonly detail: string | undefined;
+    readonly url: string;
+    readonly method: string;
+    readonly body: string;
+    constructor(args: {
+        url: string;
+        method: string;
+        body: string;
+        status?: number;
+        arcgisCode?: number;
+        detail?: string;
+    });
+    /** True for HTTP statuses the API treats as transient and retry-able. */
+    get isRetryable(): boolean;
+    /** True for a transport-level HTTP 404. */
+    get isNotFound(): boolean;
+}
+/** A transport-level failure (DNS, connection reset, timeout, ...). */
+export declare class RegionalatlasNetworkError extends RegionalatlasError {
+}
+/**
+ * A client-side validation / not-found error made before any request — e.g. an
+ * unknown indicator code, an unknown geo level, or a year outside an indicator's
+ * available range. Crucially, the indicator/level/year values that enter the raw
+ * SQL query are all validated against the catalogue here, so a rejected value
+ * never reaches the transport.
+ */
+export declare class RegionalatlasValidationError extends RegionalatlasError {
+}
+/** The response body could not be parsed as the expected JSON shape. */
+export declare class RegionalatlasParseError extends RegionalatlasError {
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/client/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/client/errors.ts"],"names":[],"mappings":"AAGA,+DAA+D;AAC/D,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,SAAQ,kBAAkB;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE;QAChB,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IAeD,yEAAyE;IACzE,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,2CAA2C;IAC3C,IAAI,UAAU,IAAI,OAAO,CAExB;CACF;AAED,uEAAuE;AACvE,qBAAa,yBAA0B,SAAQ,kBAAkB;CAAG;AAEpE;;;;;;GAMG;AACH,qBAAa,4BAA6B,SAAQ,kBAAkB;CAAG;AAEvE,wEAAwE;AACxE,qBAAa,uBAAwB,SAAQ,kBAAkB;CAAG"}

package/dist/src/client/errors.js

@@ -0,0 +1,63 @@
+// Error types raised by the client. Kept free of any I/O so they are trivial to
+// construct in tests and to `instanceof`-check by consumers.
+/** Base class for every error originating from this client. */
+export class RegionalatlasError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/**
+ * The API signalled a failure. The Regionalatlas ArcGIS MapServer is unusual: it
+ * answers HTTP 200 even for logical errors, carrying the message in an `error`
+ * object (`{code, message, details}`) — e.g. a malformed query or an invalid
+ * parameter. This error models both worlds:
+ *  - `status` is set for a genuine transport/HTTP failure (non-2xx);
+ *  - `arcgisCode` is set for a logical ArcGIS error (from `error.code`).
+ * `detail` holds the human-readable message in either case.
+ */
+export class RegionalatlasApiError extends RegionalatlasError {
+    status;
+    arcgisCode;
+    detail;
+    url;
+    method;
+    body;
+    constructor(args) {
+        const detailPart = args.detail ? `: ${args.detail}` : "";
+        const head = args.status !== undefined
+            ? `HTTP ${args.status}`
+            : `ArcGIS error${args.arcgisCode !== undefined ? ` ${args.arcgisCode}` : ""}`;
+        super(`${head} for ${args.method} ${args.url}${detailPart}`);
+        this.status = args.status;
+        this.arcgisCode = args.arcgisCode;
+        this.url = args.url;
+        this.method = args.method;
+        this.body = args.body;
+        this.detail = args.detail;
+    }
+    /** True for HTTP statuses the API treats as transient and retry-able. */
+    get isRetryable() {
+        return this.status === 429 || this.status === 503;
+    }
+    /** True for a transport-level HTTP 404. */
+    get isNotFound() {
+        return this.status === 404;
+    }
+}
+/** A transport-level failure (DNS, connection reset, timeout, ...). */
+export class RegionalatlasNetworkError extends RegionalatlasError {
+}
+/**
+ * A client-side validation / not-found error made before any request — e.g. an
+ * unknown indicator code, an unknown geo level, or a year outside an indicator's
+ * available range. Crucially, the indicator/level/year values that enter the raw
+ * SQL query are all validated against the catalogue here, so a rejected value
+ * never reaches the transport.
+ */
+export class RegionalatlasValidationError extends RegionalatlasError {
+}
+/** The response body could not be parsed as the expected JSON shape. */
+export class RegionalatlasParseError extends RegionalatlasError {
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/client/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/client/errors.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,6DAA6D;AAE7D,+DAA+D;AAC/D,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,qBAAsB,SAAQ,kBAAkB;IAClD,MAAM,CAAqB;IAC3B,UAAU,CAAqB;IAC/B,MAAM,CAAqB;IAC3B,GAAG,CAAS;IACZ,MAAM,CAAS;IACf,IAAI,CAAS;IAEtB,YAAY,IAOX;QACC,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,GACR,IAAI,CAAC,MAAM,KAAK,SAAS;YACvB,CAAC,CAAC,QAAQ,IAAI,CAAC,MAAM,EAAE;YACvB,CAAC,CAAC,eAAe,IAAI,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QAClF,KAAK,CAAC,GAAG,IAAI,QAAQ,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,GAAG,UAAU,EAAE,CAAC,CAAC;QAC7D,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QAClC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACpB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,yEAAyE;IACzE,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC;IACpD,CAAC;IAED,2CAA2C;IAC3C,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC;IAC7B,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,OAAO,yBAA0B,SAAQ,kBAAkB;CAAG;AAEpE;;;;;;GAMG;AACH,MAAM,OAAO,4BAA6B,SAAQ,kBAAkB;CAAG;AAEvE,wEAAwE;AACxE,MAAM,OAAO,uBAAwB,SAAQ,kBAAkB;CAAG"}

package/dist/src/client/http.d.ts

@@ -0,0 +1,26 @@
+import http from "node:http";
+export interface HttpRequest {
+    method: string;
+    /** Fully-qualified absolute URL. */
+    url: string;
+    headers?: Record<string, string>;
+    /** Optional request body (already serialised). */
+    body?: string | Buffer;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Hard cap on the response body size in bytes; the request aborts if exceeded. */
+    maxResponseBytes?: number;
+}
+export interface HttpResponse {
+    status: number;
+    headers: http.IncomingHttpHeaders;
+    body: Buffer;
+}
+export type Transport = (request: HttpRequest) => Promise<HttpResponse>;
+/**
+ * Default transport. Resolves with the raw response (including non-2xx) — status
+ * interpretation is the client's job. Rejects only on transport-level failures
+ * (connection errors, timeouts, malformed URLs).
+ */
+export declare const nodeHttpTransport: Transport;
+//# sourceMappingURL=http.d.ts.map

package/dist/src/client/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/client/http.ts"],"names":[],"mappings":"AAQA,OAAO,IAAI,MAAM,WAAW,CAAC;AAI7B,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,IAAI,CAAC,mBAAmB,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAwE5B,CAAC"}

package/dist/src/client/http.js

@@ -0,0 +1,80 @@
+// HTTP transport built on Node's built-in `http`/`https` modules — no axios,
+// no fetch polyfill, no third-party HTTP client.
+//
+// The transport is a plain function so it can be trivially swapped out in tests
+// (inject a `mock.fn()` returning a canned HttpResponse) without touching the
+// network. The default implementation below is exercised against a real local
+// `http.createServer` in the test-suite.
+import http from "node:http";
+import https from "node:https";
+import { RegionalatlasNetworkError } from "./errors.js";
+/**
+ * Default transport. Resolves with the raw response (including non-2xx) — status
+ * interpretation is the client's job. Rejects only on transport-level failures
+ * (connection errors, timeouts, malformed URLs).
+ */
+export const nodeHttpTransport = (request) => new Promise((resolve, reject) => {
+    let url;
+    try {
+        url = new URL(request.url);
+    }
+    catch {
+        reject(new RegionalatlasNetworkError(`Invalid URL: ${request.url}`));
+        return;
+    }
+    // Only http/https are supported. Reject anything else up front with a clear,
+    // typed error instead of letting Node throw an opaque ERR_INVALID_PROTOCOL.
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        reject(new RegionalatlasNetworkError(`Unsupported protocol "${url.protocol}" in URL: ${request.url}`));
+        return;
+    }
+    const isHttps = url.protocol === "https:";
+    const driver = isHttps ? https : http;
+    const maxBytes = request.maxResponseBytes;
+    const req = driver.request(url, {
+        method: request.method,
+        headers: request.headers,
+    }, (res) => {
+        const chunks = [];
+        let received = 0;
+        let aborted = false;
+        res.on("data", (chunk) => {
+            if (aborted)
+                return;
+            received += chunk.length;
+            if (maxBytes !== undefined && received > maxBytes) {
+                aborted = true;
+                res.destroy();
+                reject(new RegionalatlasNetworkError(`Response exceeded maxResponseBytes (${maxBytes})`));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        res.on("end", () => {
+            if (aborted)
+                return;
+            resolve({
+                status: res.statusCode ?? 0,
+                headers: res.headers,
+                body: Buffer.concat(chunks),
+            });
+        });
+        res.on("error", (err) => {
+            if (aborted)
+                return; // we already rejected with the size-cap error
+            reject(new RegionalatlasNetworkError(`Response stream error: ${err.message}`, { cause: err }));
+        });
+    });
+    if (request.timeoutMs && request.timeoutMs > 0) {
+        req.setTimeout(request.timeoutMs, () => {
+            req.destroy(new RegionalatlasNetworkError(`Request timed out after ${request.timeoutMs}ms`));
+        });
+    }
+    req.on("error", (err) => {
+        reject(err instanceof RegionalatlasNetworkError ? err : new RegionalatlasNetworkError(err.message, { cause: err }));
+    });
+    if (request.body !== undefined)
+        req.write(request.body);
+    req.end();
+});
+//# sourceMappingURL=http.js.map

package/dist/src/client/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/client/http.ts"],"names":[],"mappings":"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"}

package/dist/src/client/index.d.ts

@@ -0,0 +1,15 @@
+export { RegionalatlasClient, DEFAULT_CATALOG_URL, parseRow, filterByRegion, projectFields, } from "./client.js";
+export type { RegionalatlasClientOptions } from "./client.js";
+export { RequestEngine, DEFAULT_BASE_URL, sanitizeServerText } from "./engine.js";
+export type { EngineOptions, RawResponse } from "./engine.js";
+export { nodeHttpTransport } from "./http.js";
+export type { Transport, HttpRequest, HttpResponse } from "./http.js";
+export { buildQueryString } from "./query.js";
+export type { QueryParams, QueryValue } from "./query.js";
+export { parseThemes, parseIndicators, filterIndicators, resolveIndicator, resolveYear, tableForCode, } from "./catalog.js";
+export type { IndicatorFilter } from "./catalog.js";
+export { GEO_LEVELS, LEVEL_ALIASES, findLevel, resolveLevel, levelForTyp } from "./levels.js";
+export { buildSql, buildLayerParam } from "./sql.js";
+export { RegionalatlasError, RegionalatlasApiError, RegionalatlasNetworkError, RegionalatlasValidationError, RegionalatlasParseError, } from "./errors.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,QAAQ,EACR,cAAc,EACd,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAClF,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EACL,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,YAAY,GACb,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9F,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,yBAAyB,EACzB,4BAA4B,EAC5B,uBAAuB,GACxB,MAAM,aAAa,CAAC;AAErB,cAAc,YAAY,CAAC"}

package/dist/src/client/index.js

@@ -0,0 +1,11 @@
+// Public entry point for the API client library.
+export { RegionalatlasClient, DEFAULT_CATALOG_URL, parseRow, filterByRegion, projectFields, } from "./client.js";
+export { RequestEngine, DEFAULT_BASE_URL, sanitizeServerText } from "./engine.js";
+export { nodeHttpTransport } from "./http.js";
+export { buildQueryString } from "./query.js";
+export { parseThemes, parseIndicators, filterIndicators, resolveIndicator, resolveYear, tableForCode, } from "./catalog.js";
+export { GEO_LEVELS, LEVEL_ALIASES, findLevel, resolveLevel, levelForTyp } from "./levels.js";
+export { buildSql, buildLayerParam } from "./sql.js";
+export { RegionalatlasError, RegionalatlasApiError, RegionalatlasNetworkError, RegionalatlasValidationError, RegionalatlasParseError, } from "./errors.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/src/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA,iDAAiD;AAEjD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,QAAQ,EACR,cAAc,EACd,aAAa,GACd,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAElF,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EACL,WAAW,EACX,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,YAAY,GACb,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9F,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AACrD,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,yBAAyB,EACzB,4BAA4B,EAC5B,uBAAuB,GACxB,MAAM,aAAa,CAAC;AAErB,cAAc,YAAY,CAAC"}

package/dist/src/client/levels.d.ts

@@ -0,0 +1,16 @@
+import type { GeoLevelInfo } from "./types.js";
+/** The canonical level definitions (order defines display order). */
+export declare const GEO_LEVELS: readonly GeoLevelInfo[];
+/** Every alias a user may type for a level (for CLI help / completion). */
+export declare const LEVEL_ALIASES: readonly string[];
+/** Look up a canonical level by friendly name/alias, or return undefined. */
+export declare function findLevel(input: string): GeoLevelInfo | undefined;
+/**
+ * Resolve a friendly level name to its info, throwing a typed validation error for
+ * an unknown level. The returned `typ` is one of the fixed integers 1/2/3/5 — the
+ * only value that ends up in SQL.
+ */
+export declare function resolveLevel(input: string): GeoLevelInfo;
+/** Get the info for a raw `typ` integer, or undefined if not a known level. */
+export declare function levelForTyp(typ: number): GeoLevelInfo | undefined;
+//# sourceMappingURL=levels.d.ts.map

package/dist/src/client/levels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"levels.d.ts","sourceRoot":"","sources":["../../../src/client/levels.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAY,YAAY,EAAE,MAAM,YAAY,CAAC;AAGzD,qEAAqE;AACrE,eAAO,MAAM,UAAU,EAAE,SAAS,YAAY,EAK7C,CAAC;AA2BF,2EAA2E;AAC3E,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAAyB,CAAC;AAErE,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAIjE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CASxD;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAEjE"}

package/dist/src/client/levels.js

@@ -0,0 +1,59 @@
+// The geographic-level (Gebietstyp / `typ`) allowlist. Friendly names map onto a
+// fixed set of integers; ONLY the resolved integer `typ` is ever interpolated into
+// the SQL query. An unknown level is rejected before any SQL is built.
+import { RegionalatlasValidationError } from "./errors.js";
+/** The canonical level definitions (order defines display order). */
+export const GEO_LEVELS = [
+    { name: "land", typ: 1, label: "Bundesländer" },
+    { name: "regierungsbezirk", typ: 2, label: "Regierungsbezirke" },
+    { name: "kreis", typ: 3, label: "Kreise / kreisfreie Städte" },
+    { name: "gemeinde", typ: 5, label: "Gemeinden" },
+];
+/**
+ * All accepted aliases → the canonical name. Kept small and explicit so the mapping
+ * is auditable; the CLI value-parser also uses these keys for its choices.
+ */
+const ALIASES = {
+    land: "land",
+    laender: "land",
+    "länder": "land",
+    bundesland: "land",
+    bundeslaender: "land",
+    "bundesländer": "land",
+    regierungsbezirk: "regierungsbezirk",
+    regierungsbezirke: "regierungsbezirk",
+    rb: "regierungsbezirk",
+    kreis: "kreis",
+    kreise: "kreis",
+    landkreis: "kreis",
+    landkreise: "kreis",
+    gemeinde: "gemeinde",
+    gemeinden: "gemeinde",
+};
+/** Every alias a user may type for a level (for CLI help / completion). */
+export const LEVEL_ALIASES = Object.keys(ALIASES);
+/** Look up a canonical level by friendly name/alias, or return undefined. */
+export function findLevel(input) {
+    const canonical = ALIASES[input.trim().toLowerCase()];
+    if (canonical === undefined)
+        return undefined;
+    return GEO_LEVELS.find((l) => l.name === canonical);
+}
+/**
+ * Resolve a friendly level name to its info, throwing a typed validation error for
+ * an unknown level. The returned `typ` is one of the fixed integers 1/2/3/5 — the
+ * only value that ends up in SQL.
+ */
+export function resolveLevel(input) {
+    const level = findLevel(input);
+    if (level === undefined) {
+        const names = GEO_LEVELS.map((l) => l.name).join(", ");
+        throw new RegionalatlasValidationError(`Unknown geo level "${input}". Use one of: ${names} (aliases: ${LEVEL_ALIASES.join(", ")}).`);
+    }
+    return level;
+}
+/** Get the info for a raw `typ` integer, or undefined if not a known level. */
+export function levelForTyp(typ) {
+    return GEO_LEVELS.find((l) => l.typ === typ);
+}
+//# sourceMappingURL=levels.js.map

package/dist/src/client/levels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"levels.js","sourceRoot":"","sources":["../../../src/client/levels.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,mFAAmF;AACnF,uEAAuE;AAGvE,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAE3D,qEAAqE;AACrE,MAAM,CAAC,MAAM,UAAU,GAA4B;IACjD,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE;IAC/C,EAAE,IAAI,EAAE,kBAAkB,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,mBAAmB,EAAE;IAChE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,4BAA4B,EAAE;IAC9D,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE;CACjD,CAAC;AAEF;;;GAGG;AACH,MAAM,OAAO,GAAqC;IAChD,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,MAAM;IACf,QAAQ,EAAE,MAAM;IAChB,UAAU,EAAE,MAAM;IAClB,aAAa,EAAE,MAAM;IACrB,cAAc,EAAE,MAAM;IAEtB,gBAAgB,EAAE,kBAAkB;IACpC,iBAAiB,EAAE,kBAAkB;IACrC,EAAE,EAAE,kBAAkB;IAEtB,KAAK,EAAE,OAAO;IACd,MAAM,EAAE,OAAO;IACf,SAAS,EAAE,OAAO;IAClB,UAAU,EAAE,OAAO;IAEnB,QAAQ,EAAE,UAAU;IACpB,SAAS,EAAE,UAAU;CACtB,CAAC;AAEF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,aAAa,GAAsB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAErE,6EAA6E;AAC7E,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IACtD,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC9C,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa;IACxC,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvD,MAAM,IAAI,4BAA4B,CACpC,sBAAsB,KAAK,kBAAkB,KAAK,cAAc,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAC7F,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAM,GAAgB,CAAC,CAAC;AAC7D,CAAC"}

package/dist/src/client/query.d.ts

@@ -0,0 +1,9 @@
+export type QueryPrimitive = string | number | boolean | Date | null | undefined;
+export type QueryValue = QueryPrimitive | QueryPrimitive[];
+export type QueryParams = Record<string, QueryValue>;
+/**
+ * Build a query string (without a leading `?`) from a params object.
+ * Returns an empty string when no parameters survive filtering.
+ */
+export declare function buildQueryString(params: QueryParams): string;
+//# sourceMappingURL=query.d.ts.map