@maschinenlesbar.org/marktstammdatenregister-cli 0.0.7 → 0.1.0

package/dist/src/client/errors.js

@@ -1,5 +1,24 @@
 // 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.
+/**
+ * Replace the userinfo of a URL (`https://user:secret@host/...`) with `***`, so a
+ * credential in a base URL never reaches an error message, a log or CI output.
+ * A URL without userinfo, or one that does not parse, is returned unchanged.
+ */
+export function redactUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return url;
+    }
+    if (parsed.username === "" && parsed.password === "")
+        return url;
+    parsed.username = "***";
+    parsed.password = "";
+    return parsed.href;
+}
 /** Base class for every error originating from this client. */
 export class MastrError extends Error {
     constructor(message, options) {
@@ -22,11 +41,13 @@ export class MastrApiError extends MastrError {
     method;
     body;
     constructor(args) {
+        // The URL is shown without userinfo: a credential in --base-url must not leak.
+        const url = redactUrl(args.url);
         const detailPart = args.detail ? `: ${args.detail}` : "";
         const head = args.status !== undefined ? `HTTP ${args.status}` : "MaStR error";
-        super(`${head} for ${args.method} ${args.url}${detailPart}`);
+        super(`${head} for ${args.method} ${url}${detailPart}`);
         this.status = args.status;
-        this.url = args.url;
+        this.url = url;
         this.method = args.method;
         this.body = args.body;
         this.detail = args.detail;
@@ -43,10 +64,14 @@ export class MastrApiError extends MastrError {
 /** A transport-level failure (DNS, connection reset, timeout, ...). */
 export class MastrNetworkError extends MastrError {
 }
-/** A client-side validation error (e.g. a bad category) — no request made. */
+/**
+ * A client-side validation error — an unknown category, a page or pageSize out of
+ * range, a filter the register would misread — thrown before any request, with the
+ * message `Invalid <name>: <reason>` (see `assertValid`). The CLI maps it to the
+ * usage exit code 2.
+ */
 export class MastrValidationError extends MastrError {
 }
 /** The response body could not be parsed as the expected JSON shape. */
 export class MastrParseError extends MastrError {
 }
-//# sourceMappingURL=errors.js.map

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

@@ -0,0 +1,56 @@
+/**
+ * The operators the register's search understands (from its web form, all checked
+ * live). `gt`/`lt` are strict and only for `number`/`date` columns; there is no
+ * `gte`/`lte`. Any other operator makes the register return 0 rows.
+ */
+export declare const FILTER_OPERATORS: readonly ["eq", "neq", "sw", "ct", "nct", "ew", "null", "nn", "gt", "lt"];
+/** A filter operator. */
+export type FilterOperator = (typeof FILTER_OPERATORS)[number];
+/**
+ * Describe why the register would misread a filter spec, or return `undefined` when
+ * the spec is fine. The spec is read the way the register reads it — split on every
+ * `~` into `FilterName`, operator and value, conditions joined by `and` — and must
+ * have that shape:
+ *
+ * - every condition has a non-blank FilterName, a known lower-case operator and a
+ *   value (`''` for `null`/`nn`: `Ort~null` without a value is ignored upstream and
+ *   returns the unfiltered register; a blank value for the other operators);
+ * - a value that starts with a single quote ends with one;
+ * - conditions are joined by `and` only, and nothing dangles at the end.
+ *
+ * `~or~` is refused: the live search keeps only the part before the first `~or~` and
+ * drops every later condition without an error (checked 2026-09-26: wind `2497` alone
+ * 43633, `2497~or~…2498` also 43633). An OR between codes of one dropdown column works
+ * as a comma list inside one value: `Energieträger~eq~'2497,2498'` (52448 = 43633 + 8815).
+ *
+ * An unknown FilterName cannot be checked here (the register ignores it and returns
+ * the unfiltered set); compare with `filterColumns()`.
+ */
+export declare function filterProblem(spec: string): string | undefined;
+/** One condition for {@link buildFilter}. */
+export interface FilterCondition {
+    /** The FilterName, e.g. `"Ort"` or `"Energieträger"` (see `filterColumns()`). */
+    name: string;
+    /** The operator. */
+    op: FilterOperator;
+    /**
+     * The value, quoted by `buildFilter`. For a dropdown column pass its code; an array
+     * becomes the comma list the register reads as "any of these codes". Ignored for
+     * `null`/`nn` (sent as `''`). Must not contain `~` (nor `,` in an array item).
+     */
+    value?: string | number | readonly (string | number)[];
+}
+/**
+ * Build a filter spec from conditions joined by `~and~`, quoting each value. Unlike
+ * string interpolation (`Ort~eq~'${input}'`), a value can't add conditions: one with a
+ * `~` (the register's separator, which has no escape) throws `MastrValidationError`, so
+ * `Münster'~and~Energieträger~eq~'2497` is refused instead of becoming a second
+ * condition.
+ *
+ *   buildFilter([{ name: "Ort", op: "eq", value: "Münster" },
+ *                { name: "Energieträger", op: "eq", value: ["2497", "2498"] }])
+ *   // → "Ort~eq~'Münster'~and~Energieträger~eq~'2497,2498'"
+ */
+export declare function buildFilter(conditions: readonly FilterCondition[]): string;
+/** Throw a {@link MastrValidationError} if {@link filterProblem} finds a problem. */
+export declare function validateFilter(spec: string): void;

package/dist/src/client/filter.js

@@ -0,0 +1,144 @@
+// Checks for MaStR filter specs (`FilterName~op~'value'~and~…`), shared by the
+// client (library callers) and the CLI's `--filter` parser. The register never
+// reports a filter it misreads: it answers with a plausible but wrong count (an
+// unfiltered total, a truncated condition list, or 0 rows), so specs it would
+// misread are refused before any request.
+import { MastrValidationError } from "./errors.js";
+/**
+ * The operators the register's search understands (from its web form, all checked
+ * live). `gt`/`lt` are strict and only for `number`/`date` columns; there is no
+ * `gte`/`lte`. Any other operator makes the register return 0 rows.
+ */
+export const FILTER_OPERATORS = ["eq", "neq", "sw", "ct", "nct", "ew", "null", "nn", "gt", "lt"];
+/** Operators that test for an empty / non-empty column and ignore their value (send `''`). */
+const UNARY_OPERATORS = new Set(["null", "nn"]);
+const OPERATORS = new Set(FILTER_OPERATORS);
+const SHAPE = "Expected FilterName~op~'value' (e.g. Energieträger~eq~'2495'), several joined by ~and~.";
+/**
+ * Describe why the register would misread a filter spec, or return `undefined` when
+ * the spec is fine. The spec is read the way the register reads it — split on every
+ * `~` into `FilterName`, operator and value, conditions joined by `and` — and must
+ * have that shape:
+ *
+ * - every condition has a non-blank FilterName, a known lower-case operator and a
+ *   value (`''` for `null`/`nn`: `Ort~null` without a value is ignored upstream and
+ *   returns the unfiltered register; a blank value for the other operators);
+ * - a value that starts with a single quote ends with one;
+ * - conditions are joined by `and` only, and nothing dangles at the end.
+ *
+ * `~or~` is refused: the live search keeps only the part before the first `~or~` and
+ * drops every later condition without an error (checked 2026-09-26: wind `2497` alone
+ * 43633, `2497~or~…2498` also 43633). An OR between codes of one dropdown column works
+ * as a comma list inside one value: `Energieträger~eq~'2497,2498'` (52448 = 43633 + 8815).
+ *
+ * An unknown FilterName cannot be checked here (the register ignores it and returns
+ * the unfiltered set); compare with `filterColumns()`.
+ */
+export function filterProblem(spec) {
+    const parts = spec.split("~");
+    let i = 0;
+    for (let n = 1;; n++) {
+        const name = parts[i];
+        const op = parts[i + 1];
+        const value = parts[i + 2];
+        if (name === undefined || name.trim() === "") {
+            return `Condition ${n} has no FilterName. ${SHAPE}`;
+        }
+        if (op === undefined || value === undefined) {
+            return `Condition ${n} ("${parts.slice(i).join("~")}") is incomplete. ${SHAPE}`;
+        }
+        if (!OPERATORS.has(op)) {
+            const lower = op.trim().toLowerCase();
+            const hint = OPERATORS.has(lower) ? ` Operators are lower case: use "${lower}".` : "";
+            return (`Unknown operator "${op}" in condition ${n}. The operators are ` +
+                `${FILTER_OPERATORS.join(", ")} (gt/lt are strict; there is no gte/lte); the register ` +
+                `returns 0 rows for any other.${hint}`);
+        }
+        if (!UNARY_OPERATORS.has(op) && value.trim() === "") {
+            return `Condition ${n} ("${name}~${op}") has no value. ${SHAPE}`;
+        }
+        if (value.startsWith("'") && (value.length < 2 || !value.endsWith("'"))) {
+            // A later part that closes the quote means the value itself held a "~".
+            const close = parts.findIndex((part, j) => j > i + 2 && part.endsWith("'"));
+            if (close !== -1) {
+                const meant = parts.slice(i + 2, close + 1).join("~");
+                return (`The value ${meant} in condition ${n} contains "~". A filter value cannot contain "~": ` +
+                    `the register splits the filter on every "~" and has no escape, so it would read ${value}' ` +
+                    "and treat the rest as further conditions. Leave the ~ out (e.g. match a part with ct).");
+            }
+            return `The value of condition ${n} (${value}) has no closing single quote. ${SHAPE}`;
+        }
+        i += 3;
+        if (i >= parts.length)
+            return undefined;
+        const conjunction = parts[i] ?? "";
+        if (conjunction.toLowerCase() === "or") {
+            return ('"~or~" is not supported: the register ignores everything after the first ~or~ and ' +
+                "returns a wrong count. For several codes of one dropdown column, list them in one " +
+                "value: Energieträger~eq~'2497,2498'.");
+        }
+        if (conjunction !== "and") {
+            return `Expected ~and~ after condition ${n}, got "~${conjunction}~". Conditions are joined by ~and~ only.`;
+        }
+        i += 1;
+        if (parts.slice(i).join("~").trim() === "") {
+            return 'The filter ends with "~and~": a condition must follow it.';
+        }
+    }
+}
+/**
+ * Build a filter spec from conditions joined by `~and~`, quoting each value. Unlike
+ * string interpolation (`Ort~eq~'${input}'`), a value can't add conditions: one with a
+ * `~` (the register's separator, which has no escape) throws `MastrValidationError`, so
+ * `Münster'~and~Energieträger~eq~'2497` is refused instead of becoming a second
+ * condition.
+ *
+ *   buildFilter([{ name: "Ort", op: "eq", value: "Münster" },
+ *                { name: "Energieträger", op: "eq", value: ["2497", "2498"] }])
+ *   // → "Ort~eq~'Münster'~and~Energieträger~eq~'2497,2498'"
+ */
+export function buildFilter(conditions) {
+    if (!Array.isArray(conditions) || conditions.length === 0) {
+        throw new MastrValidationError("Invalid filter: expected at least one condition.");
+    }
+    const parts = conditions.map((c, index) => {
+        const n = index + 1;
+        if (typeof c?.name !== "string" || c.name.trim() === "" || c.name.includes("~")) {
+            throw new MastrValidationError(`Invalid filter: condition ${n} needs a non-blank FilterName without "~", got ${JSON.stringify(c?.name)}.`);
+        }
+        if (!OPERATORS.has(c.op)) {
+            throw new MastrValidationError(`Invalid filter: unknown operator ${JSON.stringify(c.op)} in condition ${n}; expected one of ${FILTER_OPERATORS.join(", ")}.`);
+        }
+        if (UNARY_OPERATORS.has(c.op))
+            return `${c.name}~${c.op}~''`;
+        const items = Array.isArray(c.value) ? c.value : [c.value];
+        if (items.length === 0) {
+            throw new MastrValidationError(`Invalid filter: condition ${n} ("${c.name}") has an empty value list.`);
+        }
+        const texts = items.map((item) => {
+            if ((typeof item !== "string" && typeof item !== "number") || String(item).trim() === "") {
+                throw new MastrValidationError(`Invalid filter: condition ${n} ("${c.name}") needs a non-blank value, got ${JSON.stringify(item)}.`);
+            }
+            const text = String(item);
+            if (text.includes("~")) {
+                throw new MastrValidationError(`Invalid filter: the value ${JSON.stringify(text)} in condition ${n} contains "~", which the ` +
+                    "register reads as a separator (there is no escape).");
+            }
+            if (items.length > 1 && text.includes(",")) {
+                throw new MastrValidationError(`Invalid filter: the list item ${JSON.stringify(text)} in condition ${n} contains ",", which ` +
+                    "separates the codes of a list.");
+            }
+            return text;
+        });
+        return `${c.name}~${c.op}~'${texts.join(",")}'`;
+    });
+    const spec = parts.join("~and~");
+    validateFilter(spec);
+    return spec;
+}
+/** Throw a {@link MastrValidationError} if {@link filterProblem} finds a problem. */
+export function validateFilter(spec) {
+    const problem = filterProblem(spec);
+    if (problem !== undefined)
+        throw new MastrValidationError(`Invalid filter: ${problem}`);
+}

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

@@ -28,4 +28,3 @@ export declare const MAX_TIMEOUT_MS = 2147483647;
  * (connection errors, timeouts, malformed URLs).
  */
 export declare const nodeHttpTransport: Transport;
-//# sourceMappingURL=http.d.ts.map

package/dist/src/client/http.js

@@ -7,7 +7,7 @@
 // `http.createServer` in the test-suite.
 import http from "node:http";
 import https from "node:https";
-import { MastrNetworkError } from "./errors.js";
+import { MastrNetworkError, redactUrl } from "./errors.js";
 /**
  * The longest delay Node's timers support (2^31 - 1 ms, about 24.8 days). A longer one
  * prints a TimeoutOverflowWarning and fires after 1 ms, so timeouts are capped here.
@@ -30,7 +30,7 @@ export const nodeHttpTransport = (request) => new Promise((resolve, reject) => {
     // 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 MastrNetworkError(`Unsupported protocol "${url.protocol}" in URL: ${request.url}`));
+        reject(new MastrNetworkError(`Unsupported protocol "${url.protocol}" in URL: ${redactUrl(request.url)}`));
         return;
     }
     const isHttps = url.protocol === "https:";
@@ -46,40 +46,51 @@ export const nodeHttpTransport = (request) => new Promise((resolve, reject) => {
     };
     const done = settle(resolve);
     const fail = settle(reject);
-    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();
-                fail(new MastrNetworkError(`Response exceeded maxResponseBytes (${maxBytes})`));
-                return;
-            }
-            chunks.push(chunk);
-        });
-        res.on("end", () => {
-            if (aborted)
-                return;
-            done({
-                status: res.statusCode ?? 0,
-                headers: res.headers,
-                body: Buffer.concat(chunks),
+    // driver.request() validates the headers synchronously and throws a raw
+    // TypeError (ERR_INVALID_CHAR) for a bad one; reject with the typed error instead.
+    let req;
+    try {
+        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();
+                    fail(new MastrNetworkError(`Response exceeded maxResponseBytes (${maxBytes})`));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            res.on("end", () => {
+                if (aborted)
+                    return;
+                done({
+                    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
+                fail(new MastrNetworkError(`Response stream error: ${err.message}`, { cause: err }));
             });
         });
-        res.on("error", (err) => {
-            if (aborted)
-                return; // we already rejected with the size-cap error
-            fail(new MastrNetworkError(`Response stream error: ${err.message}`, { cause: err }));
-        });
-    });
+    }
+    catch (err) {
+        reject(new MastrNetworkError(`Invalid request: ${err instanceof Error ? err.message : String(err)}`, {
+            cause: err,
+        }));
+        return;
+    }
     if (request.timeoutMs && request.timeoutMs > 0) {
         const timeoutMs = request.timeoutMs;
         timer = setTimeout(() => {
@@ -95,4 +106,3 @@ export const nodeHttpTransport = (request) => new Promise((resolve, reject) => {
         req.write(request.body);
     req.end();
 });
-//# sourceMappingURL=http.js.map

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

@@ -1,11 +1,14 @@
-export { MastrClient, parseMsDate, isoifyDates } from "./client.js";
+export { MastrClient, parseMsDate, isoifyDates, MAX_PAGE, MAX_PAGE_SIZE } from "./client.js";
 export type { MastrClientOptions } from "./client.js";
-export { RequestEngine, DEFAULT_BASE_URL } from "./engine.js";
+export { FILTER_OPERATORS, buildFilter, filterProblem, validateFilter } from "./filter.js";
+export type { FilterCondition, FilterOperator } from "./filter.js";
+export { RequestEngine, assertHeaderValue, validateBaseUrl, DEFAULT_BASE_URL, MAX_RETRIES, MAX_RETRY_AFTER_MS, parseRetryAfter, describeMastrErrors, sanitizeServerText, isBidiControl, } from "./engine.js";
 export type { EngineOptions, RawResponse } from "./engine.js";
 export { MAX_TIMEOUT_MS, nodeHttpTransport } from "./http.js";
 export type { Transport, HttpRequest, HttpResponse } from "./http.js";
 export { buildQueryString } from "./query.js";
+export { assertValid, baseUrlProblem, baseUrlWhitespaceProblem, COUNT_IGNORED_KEYS, countQueryProblem, headerNameProblem, headerValueProblem, intRangeProblem, nonBlankProblem, sortProblem, } from "./validate.js";
+export type { Problem } from "./validate.js";
 export type { QueryParams, QueryValue } from "./query.js";
-export { MastrError, MastrApiError, MastrNetworkError, MastrValidationError, MastrParseError, } from "./errors.js";
+export { MastrError, MastrApiError, MastrNetworkError, MastrValidationError, MastrParseError, redactUrl, } from "./errors.js";
 export * from "./types.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/src/client/index.js

@@ -1,8 +1,9 @@
 // Public entry point for the API client library.
-export { MastrClient, parseMsDate, isoifyDates } from "./client.js";
-export { RequestEngine, DEFAULT_BASE_URL } from "./engine.js";
+export { MastrClient, parseMsDate, isoifyDates, MAX_PAGE, MAX_PAGE_SIZE } from "./client.js";
+export { FILTER_OPERATORS, buildFilter, filterProblem, validateFilter } from "./filter.js";
+export { RequestEngine, assertHeaderValue, validateBaseUrl, DEFAULT_BASE_URL, MAX_RETRIES, MAX_RETRY_AFTER_MS, parseRetryAfter, describeMastrErrors, sanitizeServerText, isBidiControl, } from "./engine.js";
 export { MAX_TIMEOUT_MS, nodeHttpTransport } from "./http.js";
 export { buildQueryString } from "./query.js";
-export { MastrError, MastrApiError, MastrNetworkError, MastrValidationError, MastrParseError, } from "./errors.js";
+export { assertValid, baseUrlProblem, baseUrlWhitespaceProblem, COUNT_IGNORED_KEYS, countQueryProblem, headerNameProblem, headerValueProblem, intRangeProblem, nonBlankProblem, sortProblem, } from "./validate.js";
+export { MastrError, MastrApiError, MastrNetworkError, MastrValidationError, MastrParseError, redactUrl, } from "./errors.js";
 export * from "./types.js";
-//# sourceMappingURL=index.js.map

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

@@ -6,4 +6,3 @@ export type QueryParams = Record<string, QueryValue>;
  * Returns an empty string when no parameters survive filtering.
  */
 export declare function buildQueryString(params: QueryParams): string;
-//# sourceMappingURL=query.d.ts.map

package/dist/src/client/query.js

@@ -30,4 +30,3 @@ export function buildQueryString(params) {
     // URLSearchParams encodes spaces as "+"; "%20" is more broadly interoperable.
     return search.toString().replace(/\+/g, "%20");
 }
-//# sourceMappingURL=query.js.map

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

@@ -8,9 +8,9 @@ export type MastrDate = string;
 export type UnitCategory = "stromerzeugung" | "stromverbrauch" | "gaserzeugung" | "gasverbrauch";
 /**
  * A unit ("Einheit") record. The API returns a very wide row (~90 fields) whose
- * populated columns vary by category (a solar unit carries module fields a gas
- * consumer does not), so only the broadly-useful, category-independent fields are
- * typed; the index signature carries the rest. Natural-person and confidential data
+ * columns vary by category (a solar unit carries module fields a gas consumer does
+ * not), so only broadly useful fields are typed — each says where it occurs when not
+ * in every category; the index signature carries the rest. Natural-person and confidential data
  * are withheld upstream, so operator names may be anonymised (e.g.
  * `"natürliche Person (ABR…)"`).
  */
@@ -23,13 +23,23 @@ export interface MastrUnit {
     /** Operating status name, e.g. `"In Betrieb"`. */
     BetriebsStatusName?: string;
     BetriebsStatusId?: number;
-    /** Energy carrier name, e.g. `"Solare Strahlungsenergie"`. */
+    /** Energy carrier name, e.g. `"Solare Strahlungsenergie"` (`stromerzeugung`). */
     EnergietraegerName?: string;
     EnergietraegerId?: number;
-    /** Gross capacity in kW. */
+    /** Gross capacity in kW. Only in `stromerzeugung` rows. */
     Bruttoleistung?: number;
-    /** Net rated capacity in kW. */
+    /** Net rated capacity in kW. Only in `stromerzeugung` rows. */
     Nettonennleistung?: number;
+    /** Gas generation capacity (`gaserzeugung`; the rows state no unit). */
+    Erzeugungsleistung?: number | null;
+    /** Gas storage injection capacity in kWh/h (`gaserzeugung`). */
+    MaxEinspeicherleistung?: number | null;
+    /** Gas storage withdrawal capacity in kWh/h (`gaserzeugung`). */
+    MaxAusspeicherleistung?: number | null;
+    /** Gas storage working gas volume in kWh (`gaserzeugung`). */
+    MaxArbeitsvolumen?: number | null;
+    /** Maximum gas intake (`gasverbrauch`; the rows state no unit). */
+    MaximaleGasbezugsLeistung?: number | null;
     Bundesland?: string;
     Landkreis?: string;
     Gemeinde?: string;
@@ -59,8 +69,11 @@ export interface UnitResponse {
     /** Total number of matching units (across all pages). */
     Total: number;
     AggregateResults?: unknown;
-    /** A logical error message (e.g. `"Die Anfrage ist Null."`); null on success. */
-    Errors?: string | null;
+    /**
+     * A logical error: a message (e.g. `"Die Anfrage ist Null."`) or a Kendo ModelState
+     * object; null on success. The client throws `MastrApiError` for any other value.
+     */
+    Errors?: string | Record<string, unknown> | null;
 }
 /** A page of units plus the total match count — what the client returns. */
 export interface UnitPage {
@@ -70,6 +83,8 @@ export interface UnitPage {
     data: MastrUnit[];
 }
 /** Query parameters for a unit search. `group` is always sent empty by the client. */
+/** The query `count()` takes: the filter and sort of a `UnitQuery`, no paging. */
+export type CountQuery = Pick<UnitQuery, "filter" | "sort">;
 export interface UnitQuery {
     /** 1-based page number (default 1). */
     page?: number;
@@ -78,9 +93,12 @@ export interface UnitQuery {
     /** Sort spec: `FieldKey-asc` or `FieldKey-desc`, e.g. `"Bruttoleistung-desc"`. */
     sort?: string;
     /**
-     * Filter spec: `FilterName~op~'value'~[and|or]~…` with ops
-     * `eq|neq|sw|ct|nct|ew|null|nn`, e.g. `"Energieträger~eq~'2495'"`. Discover the
-     * `FilterName`s and dropdown codes via {@link MastrClient.filterColumns}.
+     * Filter spec: `FilterName~op~'value'~and~…` with ops
+     * `eq|neq|sw|ct|nct|ew|null|nn|gt|lt`, e.g. `"Energieträger~eq~'2495'"`. There is
+     * no working `~or~` (the register drops everything after it, so the client rejects
+     * it); for several codes of one dropdown column list them in one value:
+     * `"Energieträger~eq~'2497,2498'"`. Discover the `FilterName`s and dropdown codes
+     * via {@link MastrClient.filterColumns}.
      */
     filter?: string;
 }
@@ -100,4 +118,3 @@ export interface FilterColumn {
     Position?: number | null;
     OptionalFilterEntity?: unknown;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/src/client/types.js

@@ -1,4 +1,3 @@
 // Domain types for the Marktstammdatenregister (MaStR) public unit-search API
 // (www.marktstammdatenregister.de/MaStR).
 export {};
-//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,63 @@
+import type { UnitQuery } from "./types.js";
+/** A rule: the reason `value` is invalid, or `undefined` when it is valid. */
+export type Problem<T = unknown> = (value: T) => string | undefined;
+/**
+ * Throw a {@link MastrValidationError} with the message `Invalid <name>: <reason>`
+ * when `problem(value)` finds a reason; otherwise return `value` unchanged. Call it
+ * before any request, so a rejected input sends nothing. Async methods call it
+ * inside their body, so the rejection arrives as a rejected promise rather than a
+ * synchronous throw; constructors throw.
+ */
+export declare function assertValid<T>(name: string, value: T, problem: Problem<T>): T;
+/**
+ * A rule for an integer option: a safe integer from `min` to `max`. Anything else
+ * (a negative, NaN, Infinity, a fraction, a non-number) gets the reason
+ * `expected an integer from <min> to <max>, got <value>.`
+ */
+export declare function intRangeProblem(min: number, max: number): Problem<number>;
+/**
+ * A string that is not blank: `""` or whitespace only is refused, because the
+ * register reads an empty parameter as "not set" rather than as an error.
+ */
+export declare const nonBlankProblem: Problem<string>;
+/**
+ * A rule for a value that goes into an HTTP header (User-Agent, `defaultHeaders`):
+ * not blank, no control characters (a CR/LF or other C0 byte, DEL; tab is fine)
+ * and no code units above U+00FF. That is what Node's HTTP layer accepts; anything
+ * else it refuses with an opaque `ERR_INVALID_CHAR`, and a CR/LF handed to a custom
+ * transport could inject a header. Checked by char code so the source stays free
+ * of control bytes.
+ */
+export declare const headerValueProblem: Problem<string>;
+/** A rule for an HTTP header name: an RFC 9110 token (`X-Trace-Id`). */
+export declare const headerNameProblem: Problem<string>;
+/**
+ * A base URL must not carry whitespace or control characters. `new URL()` trims
+ * surrounding whitespace and drops tab/CR/LF silently, but the engine joins the raw
+ * string to each request path, so "https://h/MaStR " would request `/MaStR%20/...`
+ * and a custom transport would see the raw value. Reject rather than guess.
+ */
+export declare const baseUrlWhitespaceProblem: Problem<string>;
+/**
+ * Every rule for a base URL, in order: a non-blank string, no whitespace or control
+ * characters ({@link baseUrlWhitespaceProblem}), an absolute URL, the `http:` or
+ * `https:` scheme, and no query or fragment — request paths are appended to the
+ * base URL as a string, so a `?` or `#` would swallow every path (`http://h/?x=1`
+ * requests `/?x=1/Einheit/...`, `http://h/#f` requests `/`). Userinfo is allowed
+ * (error messages redact it). The reasons never echo the URL.
+ */
+export declare const baseUrlProblem: Problem<string>;
+/**
+ * A `sort` spec (`FieldKey-asc` / `FieldKey-desc`): not blank. A blank one would go
+ * out as `sort=` (the same as no sort) or `sort=%20%20`, and an explicitly blank
+ * sort is a mistake rather than a request for the default order. The shape itself is
+ * left to the register: an unknown sort key there answers 0 rows.
+ */
+export declare const sortProblem: Problem<string>;
+/**
+ * The `UnitQuery` keys that page the rows. The match count is the same on every
+ * page, so `count()` refuses them rather than silently ignore them.
+ */
+export declare const COUNT_IGNORED_KEYS: readonly ["page", "pageSize"];
+/** Why `query` cannot be counted: it sets a paging option. */
+export declare const countQueryProblem: Problem<UnitQuery>;