@maschinenlesbar.org/mudab-cli 0.0.1

package/dist/src/cli/shared.js

@@ -0,0 +1,121 @@
+// Shared helpers used across CLI command groups: option parsers, the global
+// option resolver, the FilterRequest builder, and JSON rendering.
+import { InvalidArgumentError } from "commander";
+import { MudabValidationError } from "../client/errors.js";
+/** Default `range.count` — MUDAB returns the WHOLE table when no range is sent. */
+export const DEFAULT_COUNT = 100;
+/**
+ * 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 (`0x10`, `0b10`, `1e3`), 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 non-empty (after trimming) string. */
+export function parseNonEmpty(value) {
+    if (value.trim() === "") {
+        throw new InvalidArgumentError("Expected a non-empty value.");
+    }
+    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`, which escapes
+ * typed-error handling and surfaces as an ugly "Unexpected error". 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.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;
+}
+/**
+ * Add the shared list options (range / filter / orderby) to a command.
+ * Kept in one place so every list command exposes an identical surface.
+ */
+export function addListOptions(cmd) {
+    return cmd
+        .option("--from <n>", "skip this many rows (range.from)", parseIntArg)
+        .option("--count <n>", `max rows to return (default ${DEFAULT_COUNT})`, parseIntArg)
+        .option("--all", "return the whole table (omit the range — can be very large; not combinable with --from/--count)");
+}
+/**
+ * Build the request body from parsed list options — a `range` (paging) only.
+ *
+ * `range` is omitted entirely with `--all`; otherwise `count` defaults to
+ * {@link DEFAULT_COUNT} so a bare command never dumps a whole table, and `from`
+ * defaults to 0 (the server answers a count-only range with an HTTP 500).
+ */
+export function buildFilterRequest(opts) {
+    if (opts.all) {
+        if (opts.from !== undefined || opts.count !== undefined) {
+            throw new MudabValidationError("--all cannot be combined with --from/--count.");
+        }
+        return {};
+    }
+    return { range: { from: opts.from ?? 0, count: opts.count ?? DEFAULT_COUNT } };
+}
+/** 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/client.d.ts

@@ -0,0 +1,37 @@
+import { type EngineOptions } from "./engine.js";
+import type { FilterRequest, HelcomPLCStation, Messstation, MesswertPLC, Parameter, ParameterPLC, ParameterValue, ProjectStation } from "./types.js";
+/** Options for the MUDAB client (engine options only — the API needs no auth). */
+export type MudabClientOptions = EngineOptions;
+/** The four compartment-specific parameter endpoints. */
+export type ParameterCompartment = "biologie" | "biota" | "wasser" | "sediment";
+/**
+ * Extract the row array from a MUDAB response. The API always returns a single-key
+ * object wrapping the array, but the key is not reliably the path name (e.g.
+ * `/STATION_SMALL` -> key `V_STATION_SMALL`), so we take the first array-valued
+ * property rather than trusting a fixed key. Returns `[]` for a null/empty reply.
+ */
+export declare function extractRows<T>(res: unknown): T[];
+export declare class MudabClient {
+    private readonly engine;
+    constructor(options?: MudabClientOptions);
+    /** POST a FilterRequest to `resource` and return the extracted row array. */
+    private filterList;
+    /** Measurement stations (`STATION_SMALL`). */
+    stations(req?: FilterRequest): Promise<Messstation[]>;
+    /** Project stations (`PROJECTSTATION_SMALL`). */
+    projectStations(req?: FilterRequest): Promise<ProjectStation[]>;
+    /**
+     * Measured parameters (`MV_PARAMETER`). Pass a compartment to hit the
+     * compartment-specific endpoint (`MV_PARAMETER_{BIOLOGIE,BIOTA,WASSER,SEDIMENT}`).
+     */
+    parameters(req?: FilterRequest, compartment?: ParameterCompartment): Promise<Parameter[]>;
+    /** Individual station measurements (`MV_STATION_MSMNT`) — a very large table. */
+    measurements(req?: FilterRequest): Promise<ParameterValue[]>;
+    /** HELCOM PLC stations (`V_PLC_STATION`). */
+    plcStations(req?: FilterRequest): Promise<HelcomPLCStation[]>;
+    /** Parameters measured at PLC stations (`V_GEMESSENE_PARA_PLC`). */
+    plcParameters(req?: FilterRequest): Promise<ParameterPLC[]>;
+    /** Measured values at PLC stations (`V_MESSWERTE_PLC`). */
+    plcMeasurements(req?: FilterRequest): Promise<MesswertPLC[]>;
+}
+//# 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":"AAWA,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,SAAS,EACT,YAAY,EACZ,cAAc,EACd,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,kFAAkF;AAClF,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAE/C,yDAAyD;AACzD,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;AAShF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,GAAG,CAAC,EAAE,CAQhD;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAE3B,OAAO,GAAE,kBAAuB;IAI5C,6EAA6E;YAC/D,UAAU;IAKxB,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIrD,iDAAiD;IACjD,eAAe,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAI/D;;;OAGG;IACH,UAAU,CAAC,GAAG,CAAC,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAKzF,iFAAiF;IACjF,YAAY,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAI5D,6CAA6C;IAC7C,WAAW,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAI7D,oEAAoE;IACpE,aAAa,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAI3D,2DAA2D;IAC3D,eAAe,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;CAG7D"}

package/dist/src/client/client.js

@@ -0,0 +1,78 @@
+// MudabClient — a typed client over the MUDAB (Meeresumweltdatenbank) REST API
+// (geoportal.bafg.de/mudab/rest/BaseController/FilterElements): marine-monitoring
+// data from the German coastal Bundesländer and research institutions.
+//
+// Every endpoint is a POST that takes a FilterRequest (filter / range / orderby)
+// and returns a single-key object wrapping the row array. There is NO auth.
+//
+//   const c = new MudabClient();
+//   await c.stations({ range: { count: 10 } });
+//   await c.parameters({ filter: { and: { col: "COMPT_DS", op: "=", value: "CW" } } });
+import { RequestEngine } from "./engine.js";
+const COMPARTMENT_ENDPOINT = {
+    biologie: "/MV_PARAMETER_BIOLOGIE",
+    biota: "/MV_PARAMETER_BIOTA",
+    wasser: "/MV_PARAMETER_WASSER",
+    sediment: "/MV_PARAMETER_SEDIMENT",
+};
+/**
+ * Extract the row array from a MUDAB response. The API always returns a single-key
+ * object wrapping the array, but the key is not reliably the path name (e.g.
+ * `/STATION_SMALL` -> key `V_STATION_SMALL`), so we take the first array-valued
+ * property rather than trusting a fixed key. Returns `[]` for a null/empty reply.
+ */
+export function extractRows(res) {
+    if (Array.isArray(res))
+        return res;
+    if (res && typeof res === "object") {
+        for (const value of Object.values(res)) {
+            if (Array.isArray(value))
+                return value;
+        }
+    }
+    return [];
+}
+export class MudabClient {
+    engine;
+    constructor(options = {}) {
+        this.engine = new RequestEngine(options);
+    }
+    /** POST a FilterRequest to `resource` and return the extracted row array. */
+    async filterList(resource, req = {}) {
+        const res = await this.engine.postJson(resource, req);
+        return extractRows(res);
+    }
+    /** Measurement stations (`STATION_SMALL`). */
+    stations(req) {
+        return this.filterList("/STATION_SMALL", req);
+    }
+    /** Project stations (`PROJECTSTATION_SMALL`). */
+    projectStations(req) {
+        return this.filterList("/PROJECTSTATION_SMALL", req);
+    }
+    /**
+     * Measured parameters (`MV_PARAMETER`). Pass a compartment to hit the
+     * compartment-specific endpoint (`MV_PARAMETER_{BIOLOGIE,BIOTA,WASSER,SEDIMENT}`).
+     */
+    parameters(req, compartment) {
+        const resource = compartment ? COMPARTMENT_ENDPOINT[compartment] : "/MV_PARAMETER";
+        return this.filterList(resource, req);
+    }
+    /** Individual station measurements (`MV_STATION_MSMNT`) — a very large table. */
+    measurements(req) {
+        return this.filterList("/MV_STATION_MSMNT", req);
+    }
+    /** HELCOM PLC stations (`V_PLC_STATION`). */
+    plcStations(req) {
+        return this.filterList("/V_PLC_STATION", req);
+    }
+    /** Parameters measured at PLC stations (`V_GEMESSENE_PARA_PLC`). */
+    plcParameters(req) {
+        return this.filterList("/V_GEMESSENE_PARA_PLC", req);
+    }
+    /** Measured values at PLC stations (`V_MESSWERTE_PLC`). */
+    plcMeasurements(req) {
+        return this.filterList("/V_MESSWERTE_PLC", req);
+    }
+}
+//# 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":"AAAA,+EAA+E;AAC/E,kFAAkF;AAClF,uEAAuE;AACvE,EAAE;AACF,iFAAiF;AACjF,4EAA4E;AAC5E,EAAE;AACF,iCAAiC;AACjC,gDAAgD;AAChD,wFAAwF;AAExF,OAAO,EAAE,aAAa,EAAsB,MAAM,aAAa,CAAC;AAkBhE,MAAM,oBAAoB,GAAyC;IACjE,QAAQ,EAAE,wBAAwB;IAClC,KAAK,EAAE,qBAAqB;IAC5B,MAAM,EAAE,sBAAsB;IAC9B,QAAQ,EAAE,wBAAwB;CACnC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAI,GAAY;IACzC,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,GAAU,CAAC;IAC1C,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QACnC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,GAA8B,CAAC,EAAE,CAAC;YAClE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBAAE,OAAO,KAAY,CAAC;QAChD,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,OAAO,WAAW;IACL,MAAM,CAAgB;IAEvC,YAAY,UAA8B,EAAE;QAC1C,IAAI,CAAC,MAAM,GAAG,IAAI,aAAa,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;IAED,6EAA6E;IACrE,KAAK,CAAC,UAAU,CAAI,QAAgB,EAAE,MAAqB,EAAE;QACnE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAU,QAAQ,EAAE,GAAG,CAAC,CAAC;QAC/D,OAAO,WAAW,CAAI,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED,8CAA8C;IAC9C,QAAQ,CAAC,GAAmB;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;IAChD,CAAC;IAED,iDAAiD;IACjD,eAAe,CAAC,GAAmB;QACjC,OAAO,IAAI,CAAC,UAAU,CAAC,uBAAuB,EAAE,GAAG,CAAC,CAAC;IACvD,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,GAAmB,EAAE,WAAkC;QAChE,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAC,oBAAoB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC;QACnF,OAAO,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IACxC,CAAC;IAED,iFAAiF;IACjF,YAAY,CAAC,GAAmB;QAC9B,OAAO,IAAI,CAAC,UAAU,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;IACnD,CAAC;IAED,6CAA6C;IAC7C,WAAW,CAAC,GAAmB;QAC7B,OAAO,IAAI,CAAC,UAAU,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC;IAChD,CAAC;IAED,oEAAoE;IACpE,aAAa,CAAC,GAAmB;QAC/B,OAAO,IAAI,CAAC,UAAU,CAAC,uBAAuB,EAAE,GAAG,CAAC,CAAC;IACvD,CAAC;IAED,2DAA2D;IAC3D,eAAe,CAAC,GAAmB;QACjC,OAAO,IAAI,CAAC,UAAU,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IAClD,CAAC;CACF"}

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

@@ -0,0 +1,59 @@
+import { type Transport } from "./http.js";
+export declare const DEFAULT_BASE_URL = "https://geoportal.bafg.de/mudab/rest/BaseController/FilterElements";
+export interface RawResponse {
+    data: Buffer;
+    contentType: string;
+    status: number;
+}
+export interface EngineOptions {
+    /** Base URL of the API. Defaults to the canonical geoportal.bafg.de MUDAB base. */
+    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>;
+}
+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 (all parameters travel in the body). */
+    buildUrl(path: string): string;
+    /**
+     * Perform a request with Accept negotiation and transient-error retries.
+     *
+     * Redirects are deliberately NOT followed: the canonical host answers directly,
+     * and following a cross-origin 3xx blindly is a footgun. A 3xx therefore
+     * surfaces as an error, with a hint to use the canonical base URL.
+     */
+    request(method: string, path: string, options?: {
+        accept: string;
+        body?: Buffer;
+    }): Promise<RawResponse>;
+    /** POST a JSON payload and parse the JSON reply into `T`. */
+    postJson<T>(path: string, payload: unknown): Promise<T>;
+    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":"AAOA,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAG9D,eAAO,MAAM,gBAAgB,uEAAuE,CAAC;AAGrG,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,mFAAmF;IACnF,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;AAOD,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,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAK9B;;;;;;OAMG;IACG,OAAO,CACX,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAmC,GAC1E,OAAO,CAAC,WAAW,CAAC;IAwCvB,6DAA6D;IACvD,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAe7D,OAAO,CAAC,UAAU;CAsBnB"}

package/dist/src/client/engine.js

@@ -0,0 +1,125 @@
+// The request engine: turns logical (method, path, body) calls into HTTP requests
+// via a Transport, applies retry/backoff for transient statuses (429, 503), and
+// decodes JSON responses.
+//
+// MUDAB is POST-only with a JSON body (the FilterRequest); every parameter travels
+// in the body, so there is no query-string builder. There is no authentication.
+import { nodeHttpTransport } from "./http.js";
+import { MudabApiError, MudabParseError } from "./errors.js";
+export const DEFAULT_BASE_URL = "https://geoportal.bafg.de/mudab/rest/BaseController/FilterElements";
+const DEFAULT_USER_AGENT = "mudab-cli";
+const DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024 * 1024;
+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 (all parameters travel in the body). */
+    buildUrl(path) {
+        const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+        return `${this.baseUrl}${normalizedPath}`;
+    }
+    /**
+     * Perform a request with Accept negotiation and transient-error retries.
+     *
+     * Redirects are deliberately NOT followed: the canonical host answers directly,
+     * and following a cross-origin 3xx blindly is a footgun. A 3xx therefore
+     * surfaces as an error, with a hint to use the canonical base URL.
+     */
+    async request(method, path, options = { accept: "application/json" }) {
+        const url = this.buildUrl(path);
+        const headers = {
+            ...this.defaultHeaders,
+            Accept: options.accept,
+            "User-Agent": this.userAgent,
+        };
+        if (options.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            headers["Content-Length"] = String(options.body.length);
+        }
+        let attempt = 0;
+        for (;;) {
+            const response = await this.transport({
+                method,
+                url,
+                headers,
+                ...(options.body !== undefined ? { body: options.body } : {}),
+                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(method, url, status, response.body);
+            }
+            return { data: response.body, contentType, status };
+        }
+    }
+    /** POST a JSON payload and parse the JSON reply into `T`. */
+    async postJson(path, payload) {
+        const body = Buffer.from(JSON.stringify(payload ?? {}), "utf8");
+        const res = await this.request("POST", path, { accept: "application/json", body });
+        const text = res.data.toString("utf8");
+        // A 204 or empty body is not a parse failure — surface it as null.
+        if (res.status === 204 || text.trim().length === 0) {
+            return null;
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch (cause) {
+            throw new MudabParseError(`Failed to parse JSON response from ${path}`, { cause });
+        }
+    }
+    toApiError(method, url, status, body) {
+        const text = body.toString("utf8");
+        let detail;
+        if (status >= 300 && status < 400) {
+            detail = "unexpected redirect — use the canonical base URL (default " + DEFAULT_BASE_URL + ")";
+        }
+        else {
+            try {
+                const parsed = JSON.parse(text);
+                if (typeof parsed?.detail === "string")
+                    detail = parsed.detail;
+                else if (typeof parsed?.message === "string")
+                    detail = parsed.message;
+                else if (typeof parsed?.error === "string")
+                    detail = parsed.error;
+            }
+            catch {
+                // Not JSON. Surface a short, whitespace-collapsed snippet of a textual
+                // body so the failure isn't context-free; 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;
+                }
+            }
+        }
+        return new MudabApiError({ status, url, method, 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,36 @@
+/** Base class for every error originating from this client. */
+export declare class MudabError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The API responded with a non-2xx status code. `detail` holds a human-readable
+ * message extracted from the response body when one is present.
+ */
+export declare class MudabApiError extends MudabError {
+    readonly status: number;
+    readonly detail: string | undefined;
+    readonly url: string;
+    readonly method: string;
+    readonly body: string;
+    constructor(args: {
+        status: number;
+        url: string;
+        method: string;
+        body: string;
+        detail?: string;
+    });
+    /** True for statuses the API documents as transient and retry-able. */
+    get isRetryable(): boolean;
+}
+/** A transport-level failure (DNS, connection reset, timeout, ...). */
+export declare class MudabNetworkError extends MudabError {
+}
+/** A client-side validation error (e.g. a bad --compartment) — no request made. */
+export declare class MudabValidationError extends MudabError {
+}
+/** The response body could not be parsed as the expected JSON shape. */
+export declare class MudabParseError extends MudabError {
+}
+//# 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,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED;;;GAGG;AACH,qBAAa,aAAc,SAAQ,UAAU;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,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,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IAUD,uEAAuE;IACvE,IAAI,WAAW,IAAI,OAAO,CAEzB;CACF;AAED,uEAAuE;AACvE,qBAAa,iBAAkB,SAAQ,UAAU;CAAG;AAEpD,mFAAmF;AACnF,qBAAa,oBAAqB,SAAQ,UAAU;CAAG;AAEvD,wEAAwE;AACxE,qBAAa,eAAgB,SAAQ,UAAU;CAAG"}

package/dist/src/client/errors.js

@@ -0,0 +1,43 @@
+// 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 MudabError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/**
+ * The API responded with a non-2xx status code. `detail` holds a human-readable
+ * message extracted from the response body when one is present.
+ */
+export class MudabApiError extends MudabError {
+    status;
+    detail;
+    url;
+    method;
+    body;
+    constructor(args) {
+        const detailPart = args.detail ? `: ${args.detail}` : "";
+        super(`HTTP ${args.status} for ${args.method} ${args.url}${detailPart}`);
+        this.status = args.status;
+        this.url = args.url;
+        this.method = args.method;
+        this.body = args.body;
+        this.detail = args.detail;
+    }
+    /** True for statuses the API documents as transient and retry-able. */
+    get isRetryable() {
+        return this.status === 429 || this.status === 503;
+    }
+}
+/** A transport-level failure (DNS, connection reset, timeout, ...). */
+export class MudabNetworkError extends MudabError {
+}
+/** A client-side validation error (e.g. a bad --compartment) — no request made. */
+export class MudabValidationError extends MudabError {
+}
+/** The response body could not be parsed as the expected JSON shape. */
+export class MudabParseError extends MudabError {
+}
+//# 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,UAAW,SAAQ,KAAK;IACnC,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;;;GAGG;AACH,MAAM,OAAO,aAAc,SAAQ,UAAU;IAClC,MAAM,CAAS;IACf,MAAM,CAAqB;IAC3B,GAAG,CAAS;IACZ,MAAM,CAAS;IACf,IAAI,CAAS;IAEtB,YAAY,IAMX;QACC,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,KAAK,CAAC,QAAQ,IAAI,CAAC,MAAM,QAAQ,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,GAAG,UAAU,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,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,uEAAuE;IACvE,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC;IACpD,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,OAAO,iBAAkB,SAAQ,UAAU;CAAG;AAEpD,mFAAmF;AACnF,MAAM,OAAO,oBAAqB,SAAQ,UAAU;CAAG;AAEvD,wEAAwE;AACxE,MAAM,OAAO,eAAgB,SAAQ,UAAU;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"}