@maschinenlesbar.org/regionalatlas-cli 0.0.1

package/dist/src/cli/shared.js

@@ -0,0 +1,154 @@
+// Shared helpers used across CLI command groups: option parsers, the global
+// option resolver, and JSON rendering.
+import { InvalidArgumentError } from "commander";
+import { findLevel, GEO_LEVELS, LEVEL_ALIASES } from "../client/levels.js";
+/**
+ * commander value-parser: a plain base-10 non-negative integer.
+ *
+ * Uses a strict regex rather than `Number()` coercion, which would otherwise
+ * accept empty/whitespace strings (`Number("") === 0`), hex/binary/scientific
+ * literals, signs, padding and decimals.
+ */
+export function parseIntArg(value) {
+    if (!/^[0-9]+$/.test(value)) {
+        throw new InvalidArgumentError("Expected a non-negative integer.");
+    }
+    const n = Number(value);
+    if (!Number.isSafeInteger(n)) {
+        throw new InvalidArgumentError("Expected a non-negative integer.");
+    }
+    return n;
+}
+/** commander value-parser: a 4-digit year (integer 1000..9999). */
+export function parseYear(value) {
+    if (!/^[0-9]{4}$/.test(value)) {
+        throw new InvalidArgumentError("Expected a 4-digit year (e.g. 2020).");
+    }
+    return Number(value);
+}
+/** commander value-parser: a non-empty (after trimming) string. */
+export function parseNonEmpty(value) {
+    if (value.trim() === "") {
+        throw new InvalidArgumentError("Expected a non-empty value.");
+    }
+    return value;
+}
+/**
+ * commander value-parser for `--level`: resolves a friendly name/alias to the
+ * canonical level name, rejecting an unknown level at parse time (exit 2) with a
+ * clear message. The client re-resolves it (defence in depth) and only the fixed
+ * integer `typ` ever enters SQL.
+ */
+export function parseLevel(value) {
+    const level = findLevel(value);
+    if (level === undefined) {
+        const names = GEO_LEVELS.map((l) => l.name).join(", ");
+        throw new InvalidArgumentError(`Unknown geo level. Use one of: ${names} (aliases: ${LEVEL_ALIASES.join(", ")}).`);
+    }
+    return level.name;
+}
+/**
+ * commander value-parser for a comma-separated field list. Splits on commas,
+ * trims, and drops empty entries. Field names are validated/projected client-side
+ * later, so this only produces a clean array.
+ */
+export function parseFieldList(value) {
+    const fields = value
+        .split(",")
+        .map((f) => f.trim())
+        .filter((f) => f !== "");
+    if (fields.length === 0) {
+        throw new InvalidArgumentError("Expected a comma-separated list of field names.");
+    }
+    return fields;
+}
+/**
+ * commander value-parser for `--base-url` / `--catalog-url`: a non-empty,
+ * well-formed URL whose scheme is `http:` or `https:`. Validating here (parse time)
+ * rejects a bad scheme (`file:`, `ftp:`, ...) as a usage error (exit 2) with a clear
+ * message, rather than letting it reach the transport and surface as a network error
+ * (exit 6). The transport re-checks the scheme as defence in depth.
+ */
+export function parseHttpUrl(value) {
+    const trimmed = value.trim();
+    if (trimmed === "") {
+        throw new InvalidArgumentError("Expected a non-empty value.");
+    }
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        throw new InvalidArgumentError("Expected a valid URL (e.g. https://host/path).");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new InvalidArgumentError("Only http: and https: URLs are supported.");
+    }
+    return value;
+}
+/** Build a commander value-parser for an integer constrained to [min, max]. */
+export function parseBoundedInt(min, max) {
+    return (value) => {
+        const n = parseIntArg(value);
+        if (n < min)
+            throw new InvalidArgumentError(`Must be >= ${min}.`);
+        if (n > max)
+            throw new InvalidArgumentError(`Must be <= ${max}.`);
+        return n;
+    };
+}
+/**
+ * commander value-parser for a value that ends up in an HTTP header (User-Agent).
+ * Rejects control characters — a CR/LF (or other C0/DEL byte) would otherwise reach
+ * Node's HTTP layer and throw an opaque `ERR_INVALID_CHAR`. Tab (0x09) is allowed;
+ * checked by char code so the source stays free of control bytes.
+ */
+export function parseHeaderValue(value) {
+    for (let i = 0; i < value.length; i++) {
+        const c = value.charCodeAt(i);
+        if ((c < 0x20 && c !== 0x09) || c === 0x7f) {
+            throw new InvalidArgumentError("Value contains control characters.");
+        }
+    }
+    return value;
+}
+/** Translate resolved global CLI options into client options. */
+export function toEngineOptions(global) {
+    const options = {};
+    if (global.baseUrl !== undefined)
+        options.baseUrl = global.baseUrl;
+    if (global.catalogUrl !== undefined)
+        options.catalogUrl = global.catalogUrl;
+    if (global.timeout !== undefined)
+        options.timeoutMs = global.timeout;
+    if (global.userAgent !== undefined)
+        options.userAgent = global.userAgent;
+    if (global.maxRetries !== undefined)
+        options.maxRetries = global.maxRetries;
+    if (global.maxResponseBytes !== undefined)
+        options.maxResponseBytes = global.maxResponseBytes;
+    return options;
+}
+/** Render a JSON value to stdout, pretty by default, compact with --compact. */
+export function renderJson(deps, global, value) {
+    const text = global.compact ? JSON.stringify(value) : JSON.stringify(value, null, 2);
+    deps.io.out(text);
+}
+/**
+ * Wrap an async command action with consistent global-option resolution and
+ * client construction. The callback receives a context (client + resolved global
+ * options + this command's options) and the command's positional arguments.
+ *
+ * Commander invokes actions as (arg1, ..., argN, options, command); we slice off
+ * the trailing options object and command instance to recover the positionals.
+ */
+export function action(deps, fn) {
+    return async (...args) => {
+        const command = args[args.length - 1];
+        const positionals = args.slice(0, Math.max(0, args.length - 2));
+        const global = command.optsWithGlobals();
+        const client = deps.createClient(toEngineOptions(global));
+        await fn({ client, global, opts: command.opts() }, positionals);
+    };
+}
+//# sourceMappingURL=shared.js.map

package/dist/src/cli/shared.js.map

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

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

@@ -0,0 +1,32 @@
+import type { Indicator, Theme } from "./types.js";
+/** Derive the SQL table name from a catalogue code: lowercase, `-` → `_`. */
+export declare function tableForCode(code: string): string;
+/** Parse the raw services.json array into a flat list of indicators. */
+export declare function parseIndicators(raw: unknown): Indicator[];
+/** Parse the raw services.json into a list of themes with their indicator counts. */
+export declare function parseThemes(raw: unknown): Theme[];
+/** Filters for listing indicators. */
+export interface IndicatorFilter {
+    /** Case-insensitive substring on the theme title. */
+    theme?: string;
+    /** Membership: the indicator must offer this year. */
+    year?: string | number;
+    /** Case-insensitive substring over code + short + long titles. */
+    search?: string;
+}
+/** Apply the (optional) filters to a flat indicator list. */
+export declare function filterIndicators(indicators: Indicator[], filter?: IndicatorFilter): Indicator[];
+/**
+ * Resolve a user-supplied indicator string against the catalogue allowlist. Accepts
+ * either the code form (`AI002-1-5`, case-insensitive) or the table form
+ * (`ai002_1_5`). Throws a typed validation error if not found — BEFORE any SQL is
+ * built. The returned indicator's `table` is the only value interpolated into SQL.
+ */
+export declare function resolveIndicator(indicators: Indicator[], input: string): Indicator;
+/**
+ * Validate and resolve the year for an indicator. When `year` is undefined, the
+ * latest available year is used. A provided year must be an integer AND present in
+ * the indicator's catalogue years. Only the validated integer enters SQL.
+ */
+export declare function resolveYear(indicator: Indicator, year?: number): number;
+//# sourceMappingURL=catalog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/client/catalog.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,SAAS,EAIT,KAAK,EACN,MAAM,YAAY,CAAC;AAGpB,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAWD,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,EAAE,CA+BzD;AAED,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,EAAE,CAajD;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,MAAM,GAAE,eAAoB,GAAG,SAAS,EAAE,CAcnG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CAgBlF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAoBvE"}

package/dist/src/client/catalog.js

@@ -0,0 +1,127 @@
+// The indicator catalogue: parse the raw services.json into flat `Theme`/
+// `Indicator` lists, filter them, and — crucially — resolve a user-supplied
+// indicator string against the catalogue allowlist.
+//
+// The catalogue is the security boundary for the raw SQL query: the only table
+// name ever interpolated into SQL is the `table` of a *matched* catalogue entry,
+// never raw user text.
+import { RegionalatlasParseError, RegionalatlasValidationError } from "./errors.js";
+/** Derive the SQL table name from a catalogue code: lowercase, `-` → `_`. */
+export function tableForCode(code) {
+    return code.toLowerCase().replace(/-/g, "_");
+}
+/** Normalise a user indicator string to compare against a code or a table form. */
+function normalizeIndicatorKey(input) {
+    return input.trim().toLowerCase().replace(/-/g, "_");
+}
+function asString(value) {
+    return typeof value === "string" ? value : "";
+}
+/** Parse the raw services.json array into a flat list of indicators. */
+export function parseIndicators(raw) {
+    if (!Array.isArray(raw)) {
+        throw new RegionalatlasParseError("Unexpected catalogue shape: expected a JSON array of themes from services.json.");
+    }
+    const catalog = raw;
+    const out = [];
+    for (const theme of catalog) {
+        if (theme === null || typeof theme !== "object")
+            continue;
+        const t = theme;
+        const themeTitle = asString(t.title);
+        const children = Array.isArray(t.children) ? t.children : [];
+        for (const child of children) {
+            if (child === null || typeof child !== "object")
+                continue;
+            const c = child;
+            const code = asString(c.code);
+            if (code === "")
+                continue;
+            const years = c.years && typeof c.years === "object" ? Object.keys(c.years).sort() : [];
+            out.push({
+                code,
+                table: tableForCode(code),
+                theme: themeTitle,
+                titleShort: asString(c.title_short),
+                titleLong: asString(c.title_long),
+                years,
+            });
+        }
+    }
+    return out;
+}
+/** Parse the raw services.json into a list of themes with their indicator counts. */
+export function parseThemes(raw) {
+    if (!Array.isArray(raw)) {
+        throw new RegionalatlasParseError("Unexpected catalogue shape: expected a JSON array of themes from services.json.");
+    }
+    const catalog = raw;
+    return catalog
+        .filter((t) => t !== null && typeof t === "object")
+        .map((t) => ({
+        title: asString(t.title),
+        indicatorCount: Array.isArray(t.children) ? t.children.length : 0,
+    }));
+}
+/** Apply the (optional) filters to a flat indicator list. */
+export function filterIndicators(indicators, filter = {}) {
+    const theme = filter.theme?.trim().toLowerCase();
+    const search = filter.search?.trim().toLowerCase();
+    const year = filter.year !== undefined ? String(filter.year) : undefined;
+    return indicators.filter((ind) => {
+        if (theme && !ind.theme.toLowerCase().includes(theme))
+            return false;
+        if (year && !ind.years.includes(year))
+            return false;
+        if (search) {
+            const hay = `${ind.code} ${ind.titleShort} ${ind.titleLong}`.toLowerCase();
+            if (!hay.includes(search))
+                return false;
+        }
+        return true;
+    });
+}
+/**
+ * Resolve a user-supplied indicator string against the catalogue allowlist. Accepts
+ * either the code form (`AI002-1-5`, case-insensitive) or the table form
+ * (`ai002_1_5`). Throws a typed validation error if not found — BEFORE any SQL is
+ * built. The returned indicator's `table` is the only value interpolated into SQL.
+ */
+export function resolveIndicator(indicators, input) {
+    const trimmed = input.trim();
+    if (trimmed === "") {
+        throw new RegionalatlasValidationError("An indicator code is required (e.g. AI002-1-5).");
+    }
+    const key = normalizeIndicatorKey(trimmed);
+    // A code's normalized form equals its table form, so one key matches both the
+    // code (case-insensitive, hyphen or underscore) and the table name.
+    const match = indicators.find((ind) => ind.table === key);
+    if (match === undefined) {
+        throw new RegionalatlasValidationError(`Unknown indicator "${input}". It is not in the catalogue — list indicators with ` +
+            `\`regionalatlas indicators\` (accepts the code form AI002-1-5 or the table form ai002_1_5).`);
+    }
+    return match;
+}
+/**
+ * Validate and resolve the year for an indicator. When `year` is undefined, the
+ * latest available year is used. A provided year must be an integer AND present in
+ * the indicator's catalogue years. Only the validated integer enters SQL.
+ */
+export function resolveYear(indicator, year) {
+    if (indicator.years.length === 0) {
+        throw new RegionalatlasValidationError(`Indicator "${indicator.code}" has no years listed in the catalogue.`);
+    }
+    if (year === undefined) {
+        // Latest available year (years are 4-digit strings; compare numerically).
+        return Math.max(...indicator.years.map((y) => Number(y)));
+    }
+    if (!Number.isInteger(year)) {
+        throw new RegionalatlasValidationError(`Year must be an integer, got "${year}".`);
+    }
+    if (!indicator.years.includes(String(year))) {
+        throw new RegionalatlasValidationError(`Year ${year} is not available for indicator "${indicator.code}". ` +
+            `Available: ${indicator.years.join(", ")}.`);
+    }
+    return year;
+}
+//# sourceMappingURL=catalog.js.map

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

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

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

@@ -0,0 +1,56 @@
+import { type EngineOptions } from "./engine.js";
+import { type IndicatorFilter } from "./catalog.js";
+import type { Indicator, QueryOptions, RawFeatureAttributes, RegionRow, Theme } from "./types.js";
+/** The default catalogue URL (statistikportal.de services.json). */
+export declare const DEFAULT_CATALOG_URL = "https://regionalatlas.statistikportal.de/taskrunner/services.json";
+/** Options for the client (engine options plus the catalogue URL — no auth). */
+export interface RegionalatlasClientOptions extends EngineOptions {
+    /** Full URL of the indicator catalogue (services.json). Defaults to statistikportal.de. */
+    catalogUrl?: string;
+}
+/**
+ * The catalogue is fetched once per query/list call and cached for the lifetime of
+ * the client instance, so a `query` (which needs the catalogue to resolve the
+ * indicator) does not double-fetch.
+ */
+export declare class RegionalatlasClient {
+    private readonly engine;
+    private readonly catalogUrl;
+    private indicatorsCache;
+    private rawCatalogCache;
+    constructor(options?: RegionalatlasClientOptions);
+    /** Fetch and cache the raw services.json (an array of themes). */
+    private rawCatalog;
+    /** Fetch and cache the flat indicator list. */
+    private allIndicators;
+    /** The 21 subject areas (Themenbereiche), each with its indicator count. */
+    themes(): Promise<Theme[]>;
+    /** The flat indicator list, optionally filtered by theme / year / search. */
+    indicators(filter?: IndicatorFilter): Promise<Indicator[]>;
+    /**
+     * Run a data query. Resolves the indicator against the catalogue allowlist, maps
+     * the level to a `typ`, validates/defaults the year, then builds the SQL from
+     * ONLY those validated pieces. `region` and `fields` are applied client-side and
+     * never enter the request.
+     */
+    query(opts: QueryOptions): Promise<RegionRow[]>;
+    /** GET the dynamicLayer data query, then throw on the ArcGIS `error` envelope. */
+    private getData;
+}
+/**
+ * Parse one raw ArcGIS feature into a `RegionRow`. Trims the leading-space padding
+ * of `gen2`, prefers `gen` for the name, and keeps only the indicator value fields
+ * (dropping the join columns and the `<field>v` precision-flag variants).
+ */
+export declare function parseRow(attrs: RawFeatureAttributes, typ: 1 | 2 | 3 | 5, level: string, year: number): RegionRow;
+/**
+ * Client-side region filter. A numeric input is matched as an exact `ags` (ignoring
+ * leading zeros on both sides); otherwise a case-insensitive substring of the name.
+ */
+export declare function filterByRegion(rows: RegionRow[], region: string): RegionRow[];
+/**
+ * Client-side field projection: keep only the named value fields. Unknown field
+ * names are ignored (never sent upstream). Names are matched case-insensitively.
+ */
+export declare function projectFields(rows: RegionRow[], fields: string[]): RegionRow[];
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/client/client.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAqC,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEpF,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,KAAK,EAEV,SAAS,EACT,YAAY,EACZ,oBAAoB,EACpB,SAAS,EACT,KAAK,EACN,MAAM,YAAY,CAAC;AAEpB,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,sEACqC,CAAC;AAMtE,gFAAgF;AAChF,MAAM,WAAW,0BAA2B,SAAQ,aAAa;IAC/D,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,eAAe,CAA0B;IACjD,OAAO,CAAC,eAAe,CAAU;gBAErB,OAAO,GAAE,0BAA+B;IAKpD,kEAAkE;YACpD,UAAU;IAaxB,+CAA+C;YACjC,aAAa;IAO3B,4EAA4E;IACtE,MAAM,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;IAIhC,6EAA6E;IACvE,UAAU,CAAC,MAAM,GAAE,eAAoB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAIpE;;;;;OAKG;IACG,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IA8BrD,kFAAkF;YACpE,OAAO;CA6BtB;AAkBD;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,oBAAoB,EAC3B,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAClB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,GACX,SAAS,CAkBX;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,CAS7E;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,CAU9E"}

package/dist/src/client/client.js

@@ -0,0 +1,195 @@
+// RegionalatlasClient — a typed client over the Regionalatlas Deutschland of the
+// Statistische Ämter des Bundes und der Länder.
+//
+// TWO upstream hosts (see DEVELOPING.md):
+//   (A) data   — the ArcGIS MapServer `dynamicLayer/query` on `baseUrl`
+//                (default https://www.gis-idmz.nrw.de), which runs a raw SQL join.
+//   (B) catalogue — the static `services.json` on statistikportal.de, listing the
+//                21 themes / 70 indicators (`catalogUrl`).
+//
+// The ArcGIS server answers HTTP 200 even for logical errors, carrying them in an
+// `error` object — the client checks for it and throws.
+//
+//   const c = new RegionalatlasClient();
+//   await c.themes();                                    // the 21 subject areas
+//   await c.indicators({ search: "bevölkerung" });       // matching indicators
+//   await c.query({ indicator: "AI002-1-5", level: "land", year: 2020 }); // 16 rows
+import { RequestEngine, sanitizeServerText } from "./engine.js";
+import { RegionalatlasApiError, RegionalatlasParseError } from "./errors.js";
+import { filterIndicators, parseIndicators, parseThemes, resolveIndicator, resolveYear, } from "./catalog.js";
+import { resolveLevel } from "./levels.js";
+import { buildLayerParam } from "./sql.js";
+/** The default catalogue URL (statistikportal.de services.json). */
+export const DEFAULT_CATALOG_URL = "https://regionalatlas.statistikportal.de/taskrunner/services.json";
+/** The ArcGIS MapServer path for the dynamicLayer data query (on `baseUrl`). */
+const DATA_PATH = "/arcgis/rest/services/stba/regionalatlas/MapServer/dynamicLayer/query";
+/**
+ * The catalogue is fetched once per query/list call and cached for the lifetime of
+ * the client instance, so a `query` (which needs the catalogue to resolve the
+ * indicator) does not double-fetch.
+ */
+export class RegionalatlasClient {
+    engine;
+    catalogUrl;
+    indicatorsCache;
+    rawCatalogCache;
+    constructor(options = {}) {
+        this.engine = new RequestEngine(options);
+        this.catalogUrl = options.catalogUrl ?? DEFAULT_CATALOG_URL;
+    }
+    /** Fetch and cache the raw services.json (an array of themes). */
+    async rawCatalog() {
+        if (this.rawCatalogCache === undefined) {
+            const raw = await this.engine.getJsonAbsolute(this.catalogUrl);
+            if (raw === null || raw === undefined) {
+                throw new RegionalatlasParseError(`The catalogue at ${this.catalogUrl} returned an empty body.`);
+            }
+            this.rawCatalogCache = raw;
+        }
+        return this.rawCatalogCache;
+    }
+    /** Fetch and cache the flat indicator list. */
+    async allIndicators() {
+        if (this.indicatorsCache === undefined) {
+            this.indicatorsCache = parseIndicators(await this.rawCatalog());
+        }
+        return this.indicatorsCache;
+    }
+    /** The 21 subject areas (Themenbereiche), each with its indicator count. */
+    async themes() {
+        return parseThemes(await this.rawCatalog());
+    }
+    /** The flat indicator list, optionally filtered by theme / year / search. */
+    async indicators(filter = {}) {
+        return filterIndicators(await this.allIndicators(), filter);
+    }
+    /**
+     * Run a data query. Resolves the indicator against the catalogue allowlist, maps
+     * the level to a `typ`, validates/defaults the year, then builds the SQL from
+     * ONLY those validated pieces. `region` and `fields` are applied client-side and
+     * never enter the request.
+     */
+    async query(opts) {
+        // 1. Resolve the indicator against the catalogue allowlist (throws if unknown).
+        const indicators = await this.allIndicators();
+        const indicator = resolveIndicator(indicators, opts.indicator);
+        // 2. Map level → typ (throws if unknown).
+        const level = resolveLevel(opts.level);
+        // 3. Validate/default the year (throws if not an integer in the indicator's years).
+        const year = resolveYear(indicator, opts.year);
+        // 4. Build the SQL from validated pieces only.
+        const layer = buildLayerParam(indicator.table, level.typ, year);
+        const res = await this.getData({
+            layer: JSON.stringify(layer),
+            f: "json",
+            outFields: "*",
+            returnGeometry: false,
+            where: "1=1",
+            spatialRel: "esriSpatialRelIntersects",
+        });
+        const rows = (res.features ?? []).map((f) => parseRow(f.attributes, level.typ, level.name, year));
+        // 5. Client-side region filter + field projection (no user text upstream).
+        const filtered = opts.region ? filterByRegion(rows, opts.region) : rows;
+        return opts.fields && opts.fields.length > 0 ? projectFields(filtered, opts.fields) : filtered;
+    }
+    /** GET the dynamicLayer data query, then throw on the ArcGIS `error` envelope. */
+    async getData(params) {
+        const res = await this.engine.getJson(DATA_PATH, params);
+        // The endpoint answers with a JSON envelope object. A null (empty/204 body) or
+        // non-object reply means the endpoint did not return the expected shape.
+        if (res === null || typeof res !== "object") {
+            throw new RegionalatlasParseError(`Expected a JSON object from the data query but received ${res === null ? "an empty body" : typeof res}.`);
+        }
+        // Logical errors arrive as HTTP 200 with a top-level `error` key — sniff for it.
+        const err = res.error;
+        if (err && typeof err === "object") {
+            // The ArcGIS `error` message/details come from the (attacker-controllable)
+            // response body and flow into an Error.message printed raw to stderr; strip
+            // control characters so a hostile endpoint cannot inject terminal escapes.
+            const detail = [err.message, ...(Array.isArray(err.details) ? err.details : [])]
+                .filter((s) => typeof s === "string" && s.length > 0)
+                .map(sanitizeServerText)
+                .join("; ");
+            throw new RegionalatlasApiError({
+                url: this.engine.buildUrl(DATA_PATH, params),
+                method: "GET",
+                body: JSON.stringify(res),
+                arcgisCode: typeof err.code === "number" ? err.code : undefined,
+                detail: detail || undefined,
+            });
+        }
+        return res;
+    }
+}
+// --------------------------------------------------------------------------
+// Row parsing & client-side filtering (exported for tests)
+// --------------------------------------------------------------------------
+/** The non-value join columns present on every feature (excluded from `values`). */
+const JOIN_FIELDS = new Set([
+    "id",
+    "typ",
+    "ags",
+    "jahr",
+    "gen",
+    "jahr2",
+    "ags2",
+    "gen2",
+]);
+/**
+ * Parse one raw ArcGIS feature into a `RegionRow`. Trims the leading-space padding
+ * of `gen2`, prefers `gen` for the name, and keeps only the indicator value fields
+ * (dropping the join columns and the `<field>v` precision-flag variants).
+ */
+export function parseRow(attrs, typ, level, year) {
+    const ags = String(attrs.ags ?? "").trim();
+    const rawName = typeof attrs.gen === "string" ? attrs.gen : attrs.gen2;
+    const name = typeof rawName === "string" ? rawName.trim() : "";
+    const values = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (JOIN_FIELDS.has(key))
+            continue;
+        // Drop the precision-flag variants: `<field>v` when `<field>` is also present.
+        if (key.endsWith("v")) {
+            const base = key.slice(0, -1);
+            if (Object.prototype.hasOwnProperty.call(attrs, base))
+                continue;
+        }
+        values[key] = typeof value === "number" ? value : value === null ? null : Number(value);
+        if (Number.isNaN(values[key]))
+            values[key] = null;
+    }
+    return { ags, name, typ, level, year, values };
+}
+/**
+ * Client-side region filter. A numeric input is matched as an exact `ags` (ignoring
+ * leading zeros on both sides); otherwise a case-insensitive substring of the name.
+ */
+export function filterByRegion(rows, region) {
+    const trimmed = region.trim();
+    if (trimmed === "")
+        return rows;
+    if (/^\d+$/.test(trimmed)) {
+        const target = String(Number(trimmed)); // strip leading zeros
+        return rows.filter((r) => String(Number(r.ags.replace(/\D/g, "") || "0")) === target);
+    }
+    const needle = trimmed.toLowerCase();
+    return rows.filter((r) => r.name.toLowerCase().includes(needle));
+}
+/**
+ * Client-side field projection: keep only the named value fields. Unknown field
+ * names are ignored (never sent upstream). Names are matched case-insensitively.
+ */
+export function projectFields(rows, fields) {
+    const wanted = new Set(fields.map((f) => f.trim().toLowerCase()).filter((f) => f !== ""));
+    if (wanted.size === 0)
+        return rows;
+    return rows.map((r) => {
+        const values = {};
+        for (const [key, value] of Object.entries(r.values)) {
+            if (wanted.has(key.toLowerCase()))
+                values[key] = value;
+        }
+        return { ...r, values };
+    });
+}
+//# sourceMappingURL=client.js.map

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

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