@maschinenlesbar.org/marktstammdatenregister-cli 0.0.8 → 0.2.0

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

@@ -1,3 +1,4 @@
+import type { FilterColumn } from "./types.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
@@ -14,7 +15,8 @@ export type FilterOperator = (typeof FILTER_OPERATORS)[number];
  *
  * - 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);
+ *   returns the unfiltered register); for the other operators the value is not blank,
+ *   quoted (`''`, `' '`) or not;
  * - a value that starts with a single quote ends with one;
  * - conditions are joined by `and` only, and nothing dangles at the end.
  *
@@ -27,6 +29,26 @@ export type FilterOperator = (typeof FILTER_OPERATORS)[number];
  * the unfiltered set); compare with `filterColumns()`.
  */
 export declare function filterProblem(spec: string): string | undefined;
+/**
+ * A FilterName as the register spells it, as far as that can be told without its column
+ * list: Unicode NFC, no surrounding whitespace, inner whitespace runs as one space. The
+ * register matches FilterNames exactly and silently ignores one it doesn't know, so
+ * `Energieträger` typed with a decomposed "ä" (macOS input: `a` + U+0308) or with a space
+ * after `~and~` returned the unfiltered set (live 2026-10-05: 9 562 366 instead of 6 545 851).
+ * The register's own names are NFC, never padded and never hold two spaces in a row, so this
+ * can't turn a valid name into another one.
+ */
+export declare function normalizeFilterName(name: string): string;
+/**
+ * The spec with whitespace next to a `~` dropped where it means nothing: every FilterName
+ * normalised ({@link normalizeFilterName}), the operators and `and`s trimmed, and the
+ * whitespace outside a quoted value dropped (`'Münster' ~and~…`); the inside of a quoted
+ * value is left as it is. The spec is split the way the register splits it, on every `~`:
+ * names are parts 0, 4, 8, …, operators 1, 5, …, values 2, 6, …, `and`s 3, 7, … A malformed
+ * spec comes back normalised too; {@link filterProblem} then reports it. A non-string is
+ * returned as is.
+ */
+export declare function normalizeFilter(spec: string): string;
 /** One condition for {@link buildFilter}. */
 export interface FilterCondition {
     /** The FilterName, e.g. `"Ort"` or `"Energieträger"` (see `filterColumns()`). */
@@ -52,6 +74,28 @@ export interface FilterCondition {
  *   // → "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. */
+/**
+ * Throw a {@link MastrValidationError} if {@link filterProblem} finds a problem. It checks
+ * the spec as given; the client checks (and sends) the {@link normalizeFilter}ed spec.
+ */
 export declare function validateFilter(spec: string): void;
-//# sourceMappingURL=filter.d.ts.map
+/**
+ * Check a filter spec against the category's filter columns (`filterColumns()`) and return
+ * it with every FilterName in the register's spelling, or throw a {@link MastrValidationError}.
+ * The register silently ignores what it doesn't know, so these would otherwise give a wrong
+ * count with exit 0:
+ *
+ * - a FilterName that is not a column of the category: the unfiltered set (live 2026-10-05:
+ *   `energieträger~eq~'2495'` gave all 9 562 366 units, `Energieträger` on `gasverbrauch`
+ *   all 937). A name that differs from a column only in case is written the register's way
+ *   (the register's names don't collide in case); any other unknown name — `__proto__`
+ *   included — is rejected with up to three close names;
+ * - for `eq`/`neq` on a dropdown column, a value that is not one of its codes: an unknown
+ *   code gives 0 rows, a label (`'Wind'`) or junk in a comma list `{"Error":true}`. A label
+ *   is named with its code;
+ * - `null`/`nn` on a number, dropdown or boolean column, which the register answers with
+ *   `{"Error":true}` (they work on text columns).
+ *
+ * `spec` must already pass {@link filterProblem} (the client normalises and checks it first).
+ */
+export declare function resolveFilter(spec: string, columns: readonly FilterColumn[], category: string): string;

package/dist/src/client/filter.js

@@ -13,6 +13,12 @@ export const FILTER_OPERATORS = ["eq", "neq", "sw", "ct", "nct", "ew", "null", "
 /** 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);
+/**
+ * Column types on which the register refuses `null`/`nn` with `{"Error":true}` (live
+ * 2026-10-05: `Bruttoleistung der Einheit`, `Energieträger`, `Bürgerenergie`). They work on
+ * text columns; date and MaStR-number columns are untested and left to the register.
+ */
+const NO_NULL_TEST_TYPES = new Set(["number", "multidropdown", "boolean"]);
 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
@@ -22,7 +28,8 @@ const SHAPE = "Expected FilterName~op~'value' (e.g. Energieträger~eq~'2495'), s
  *
  * - 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);
+ *   returns the unfiltered register); for the other operators the value is not blank,
+ *   quoted (`''`, `' '`) or not;
  * - a value that starts with a single quote ends with one;
  * - conditions are joined by `and` only, and nothing dangles at the end.
  *
@@ -35,6 +42,9 @@ const SHAPE = "Expected FilterName~op~'value' (e.g. Energieträger~eq~'2495'), s
  * the unfiltered set); compare with `filterColumns()`.
  */
 export function filterProblem(spec) {
+    if (typeof spec !== "string") {
+        return `Expected the filter as a string (FilterName~op~'value'), got ${spec === null ? "null" : Array.isArray(spec) ? "an array" : typeof spec}.`;
+    }
     const parts = spec.split("~");
     let i = 0;
     for (let n = 1;; n++) {
@@ -57,6 +67,12 @@ export function filterProblem(spec) {
         if (!UNARY_OPERATORS.has(op) && value.trim() === "") {
             return `Condition ${n} ("${name}~${op}") has no value. ${SHAPE}`;
         }
+        // A quoted blank value ('' or ' ') is no value either: on a text column it matches
+        // nothing, and on a dropdown the live register did not answer within 30 s
+        // (2026-10-05). Only null/nn take ''.
+        if (!UNARY_OPERATORS.has(op) && /^'\s*'$/.test(value.trim())) {
+            return `Condition ${n} ("${name}~${op}~${value.trim()}") has no value: '' is only for null/nn. ${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("'"));
@@ -86,6 +102,53 @@ export function filterProblem(spec) {
         }
     }
 }
+/**
+ * A FilterName as the register spells it, as far as that can be told without its column
+ * list: Unicode NFC, no surrounding whitespace, inner whitespace runs as one space. The
+ * register matches FilterNames exactly and silently ignores one it doesn't know, so
+ * `Energieträger` typed with a decomposed "ä" (macOS input: `a` + U+0308) or with a space
+ * after `~and~` returned the unfiltered set (live 2026-10-05: 9 562 366 instead of 6 545 851).
+ * The register's own names are NFC, never padded and never hold two spaces in a row, so this
+ * can't turn a valid name into another one.
+ */
+export function normalizeFilterName(name) {
+    return name.normalize("NFC").trim().replace(/\s+/g, " ");
+}
+/**
+ * A value with the whitespace outside its quotes dropped: `'Münster' ` (a space before
+ * `~and~`) → `'Münster'`. The register would read the space as part of the value, and the
+ * shape check took the unclosed-looking value for one that holds a `~`. Inside the quotes
+ * nothing changes; a value that isn't quoted is trimmed.
+ */
+function normalizeFilterValue(value) {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith("'"))
+        return trimmed;
+    return trimmed.length >= 2 && trimmed.endsWith("'") ? trimmed : value;
+}
+/**
+ * The spec with whitespace next to a `~` dropped where it means nothing: every FilterName
+ * normalised ({@link normalizeFilterName}), the operators and `and`s trimmed, and the
+ * whitespace outside a quoted value dropped (`'Münster' ~and~…`); the inside of a quoted
+ * value is left as it is. The spec is split the way the register splits it, on every `~`:
+ * names are parts 0, 4, 8, …, operators 1, 5, …, values 2, 6, …, `and`s 3, 7, … A malformed
+ * spec comes back normalised too; {@link filterProblem} then reports it. A non-string is
+ * returned as is.
+ */
+export function normalizeFilter(spec) {
+    if (typeof spec !== "string")
+        return spec;
+    return spec
+        .split("~")
+        .map((part, i) => {
+        if (i % 4 === 0)
+            return normalizeFilterName(part);
+        if (i % 4 === 2)
+            return normalizeFilterValue(part);
+        return part.trim();
+    })
+        .join("~");
+}
 /**
  * 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
@@ -119,7 +182,10 @@ export function buildFilter(conditions) {
             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 (typeof item === "number" && !Number.isFinite(item)) {
+                throw new MastrValidationError(`Invalid filter: condition ${n} ("${c.name}") needs a finite number, got ${String(item)}.`);
+            }
+            const text = typeof item === "number" ? plainNumber(item) : 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).");
@@ -132,14 +198,127 @@ export function buildFilter(conditions) {
         });
         return `${c.name}~${c.op}~'${texts.join(",")}'`;
     });
-    const spec = parts.join("~and~");
+    const spec = normalizeFilter(parts.join("~and~"));
     validateFilter(spec);
     return spec;
 }
-/** Throw a {@link MastrValidationError} if {@link filterProblem} finds a problem. */
+/**
+ * A number as the register reads it: decimal point, no exponent, no grouping. `String()`
+ * writes `1e-7` and `1e+21`, which the register answers with `{"Error":true}`.
+ */
+function plainNumber(n) {
+    const text = String(n);
+    return /e/i.test(text) ? n.toLocaleString("en-US", { useGrouping: false, maximumFractionDigits: 20 }) : text;
+}
+/**
+ * Throw a {@link MastrValidationError} if {@link filterProblem} finds a problem. It checks
+ * the spec as given; the client checks (and sends) the {@link normalizeFilter}ed spec.
+ */
 export function validateFilter(spec) {
     const problem = filterProblem(spec);
     if (problem !== undefined)
         throw new MastrValidationError(`Invalid filter: ${problem}`);
 }
-//# sourceMappingURL=filter.js.map
+/** Edit distance between two strings (Levenshtein), for "did you mean". */
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+/** Up to three column names close to `name`, closest first. */
+function closeNames(name, names) {
+    const lower = name.toLowerCase();
+    const limit = Math.max(2, Math.floor(name.length / 4));
+    return names
+        .map((candidate) => {
+        const other = candidate.toLowerCase();
+        const distance = other.includes(lower) || lower.includes(other) ? 0 : editDistance(lower, other);
+        return { candidate, distance };
+    })
+        .filter(({ distance }) => distance <= limit)
+        .sort((x, y) => x.distance - y.distance)
+        .slice(0, 3)
+        .map(({ candidate }) => candidate);
+}
+/** A value without its surrounding single quotes, when it has them. */
+function unquote(value) {
+    return value.length >= 2 && value.startsWith("'") && value.endsWith("'") ? value.slice(1, -1) : value;
+}
+/**
+ * Check a filter spec against the category's filter columns (`filterColumns()`) and return
+ * it with every FilterName in the register's spelling, or throw a {@link MastrValidationError}.
+ * The register silently ignores what it doesn't know, so these would otherwise give a wrong
+ * count with exit 0:
+ *
+ * - a FilterName that is not a column of the category: the unfiltered set (live 2026-10-05:
+ *   `energieträger~eq~'2495'` gave all 9 562 366 units, `Energieträger` on `gasverbrauch`
+ *   all 937). A name that differs from a column only in case is written the register's way
+ *   (the register's names don't collide in case); any other unknown name — `__proto__`
+ *   included — is rejected with up to three close names;
+ * - for `eq`/`neq` on a dropdown column, a value that is not one of its codes: an unknown
+ *   code gives 0 rows, a label (`'Wind'`) or junk in a comma list `{"Error":true}`. A label
+ *   is named with its code;
+ * - `null`/`nn` on a number, dropdown or boolean column, which the register answers with
+ *   `{"Error":true}` (they work on text columns).
+ *
+ * `spec` must already pass {@link filterProblem} (the client normalises and checks it first).
+ */
+export function resolveFilter(spec, columns, category) {
+    const byName = new Map();
+    const byLowerName = new Map();
+    for (const column of columns) {
+        if (typeof column.FilterName !== "string")
+            continue;
+        byName.set(column.FilterName, column);
+        const lower = column.FilterName.toLowerCase();
+        byLowerName.set(lower, [...(byLowerName.get(lower) ?? []), column]);
+    }
+    const parts = spec.split("~");
+    for (let i = 0, n = 1; i < parts.length; i += 4, n++) {
+        const name = parts[i];
+        let column = byName.get(name);
+        if (column === undefined) {
+            const sameCase = byLowerName.get(name.toLowerCase()) ?? [];
+            if (sameCase.length === 1)
+                column = sameCase[0];
+        }
+        if (column === undefined) {
+            const near = closeNames(name, [...byName.keys()]);
+            throw new MastrValidationError(`Invalid filter: unknown FilterName ${JSON.stringify(name)} in condition ${n}: ${category} has no such ` +
+                "column, and the register would ignore it and return the unfiltered set." +
+                (near.length > 0 ? ` Did you mean ${near.map((x) => JSON.stringify(x)).join(", ")}?` : "") +
+                ` List the names with \`mastr filters ${category}\` (filterColumns() in the library).`);
+        }
+        parts[i] = column.FilterName;
+        const op = parts[i + 1];
+        if (UNARY_OPERATORS.has(op) && NO_NULL_TEST_TYPES.has(String(column.Type))) {
+            throw new MastrValidationError(`Invalid filter: ${op} (condition ${n}) doesn't work on the ${String(column.Type)} column ` +
+                `${JSON.stringify(column.FilterName)}: the register answers null/nn on number, dropdown and ` +
+                "boolean columns with an error (they work on text columns). There is no way to ask for " +
+                "the units without a value in such a column.");
+        }
+        const value = unquote(parts[i + 2].trim());
+        const codes = (column.ListObject ?? []).filter((o) => typeof o?.Value === "string");
+        if (column.Type === "multidropdown" && codes.length > 0 && (op === "eq" || op === "neq")) {
+            for (const item of value.split(",").map((x) => x.trim())) {
+                if (codes.some((o) => o.Value === item))
+                    continue;
+                const label = codes.find((o) => typeof o.Name === "string" && o.Name.toLowerCase() === item.toLowerCase());
+                const shown = codes.slice(0, 8).map((o) => `${o.Value} (${o.Name ?? ""})`).join(", ");
+                throw new MastrValidationError(`Invalid filter: ${JSON.stringify(item)} is not a code of the dropdown column ` +
+                    `${JSON.stringify(column.FilterName)} (condition ${n}). ` +
+                    (label !== undefined
+                        ? `It is the label of code ${label.Value}: a dropdown takes its code (${column.FilterName}~${op}~'${label.Value}').`
+                        : `The register would answer 0 rows or an error. Codes: ${shown}${codes.length > 8 ? ", …" : ""}; ` +
+                            `all of them with \`mastr filters ${category}\`.`));
+            }
+        }
+    }
+    return parts.join("~");
+}

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

@@ -10,13 +10,26 @@ export interface HttpRequest {
     timeoutMs?: number;
     /** Hard cap on the response body size in bytes; the request aborts if exceeded. */
     maxResponseBytes?: number;
+    /**
+     * Aborted when the engine's overall deadline (`timeoutMs`) passes. A transport should stop
+     * the request then (`fetch(url, { signal })`); the engine rejects at the deadline either way,
+     * and enforces `maxResponseBytes` on the body it gets back, so neither limit depends on it.
+     */
+    signal?: AbortSignal;
 }
+/**
+ * What a transport resolves with. The engine also accepts what a `fetch`-based transport
+ * naturally returns: `headers` as a `Headers` object, a `Map` or a record in any case, and
+ * `body` as any `ArrayBuffer` view (a `Uint8Array`, from any realm) or an `ArrayBuffer`.
+ */
 export interface HttpResponse {
     status: number;
     headers: http.IncomingHttpHeaders;
     body: Buffer;
 }
 export type Transport = (request: HttpRequest) => Promise<HttpResponse>;
+/** The message for a body over the size cap, naming the option on both sides. */
+export declare function sizeLimitMessage(maxBytes: number): string;
 /**
  * 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.
@@ -28,4 +41,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

@@ -8,6 +8,10 @@
 import http from "node:http";
 import https from "node:https";
 import { MastrNetworkError, redactUrl } from "./errors.js";
+/** The message for a body over the size cap, naming the option on both sides. */
+export function sizeLimitMessage(maxBytes) {
+    return `Response exceeded the size limit of ${maxBytes} bytes (maxResponseBytes; --max-response-bytes on the CLI)`;
+}
 /**
  * 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.
@@ -46,40 +50,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(sizeLimitMessage(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(() => {
@@ -88,6 +103,17 @@ export const nodeHttpTransport = (request) => new Promise((resolve, reject) => {
             req.destroy(err);
         }, Math.min(timeoutMs, MAX_TIMEOUT_MS));
     }
+    if (request.signal !== undefined) {
+        const abort = () => {
+            const err = new MastrNetworkError(`Request timed out after ${request.timeoutMs ?? 0}ms`);
+            fail(err);
+            req.destroy(err);
+        };
+        if (request.signal.aborted)
+            abort();
+        else
+            request.signal.addEventListener("abort", abort, { once: true });
+    }
     req.on("error", (err) => {
         fail(err instanceof MastrNetworkError ? err : new MastrNetworkError(err.message, { cause: err }));
     });
@@ -95,4 +121,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,13 +1,14 @@
 export { MastrClient, parseMsDate, isoifyDates, MAX_PAGE, MAX_PAGE_SIZE } from "./client.js";
 export type { MastrClientOptions } from "./client.js";
-export { FILTER_OPERATORS, buildFilter, filterProblem, validateFilter } from "./filter.js";
+export { FILTER_OPERATORS, buildFilter, filterProblem, normalizeFilter, normalizeFilterName, resolveFilter, validateFilter, } from "./filter.js";
 export type { FilterCondition, FilterOperator } from "./filter.js";
-export { RequestEngine, DEFAULT_BASE_URL, MAX_RETRY_AFTER_MS, parseRetryAfter, describeMastrErrors, sanitizeServerText, isBidiControl, } from "./engine.js";
+export { RequestEngine, assertHeaderValue, validateBaseUrl, DEFAULT_BASE_URL, MAX_RETRIES, MAX_RETRY_AFTER_MS, parseRetryAfter, isTransientNetworkError, MAX_DETAIL_LENGTH, describeMastrErrors, sanitizeServerText, isBidiControl, } from "./engine.js";
 export type { EngineOptions, RawResponse } from "./engine.js";
-export { MAX_TIMEOUT_MS, nodeHttpTransport } from "./http.js";
+export { MAX_TIMEOUT_MS, nodeHttpTransport, sizeLimitMessage } 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, redactUrl, } from "./errors.js";
+export { MastrError, MastrApiError, MastrNetworkError, MastrValidationError, MastrParseError, redactUrl, credentialsIn, redactCredentials, } from "./errors.js";
 export * from "./types.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/src/client/index.js

@@ -1,9 +1,9 @@
 // Public entry point for the API client library.
 export { MastrClient, parseMsDate, isoifyDates, MAX_PAGE, MAX_PAGE_SIZE } from "./client.js";
-export { FILTER_OPERATORS, buildFilter, filterProblem, validateFilter } from "./filter.js";
-export { RequestEngine, DEFAULT_BASE_URL, MAX_RETRY_AFTER_MS, parseRetryAfter, describeMastrErrors, sanitizeServerText, isBidiControl, } from "./engine.js";
-export { MAX_TIMEOUT_MS, nodeHttpTransport } from "./http.js";
+export { FILTER_OPERATORS, buildFilter, filterProblem, normalizeFilter, normalizeFilterName, resolveFilter, validateFilter, } from "./filter.js";
+export { RequestEngine, assertHeaderValue, validateBaseUrl, DEFAULT_BASE_URL, MAX_RETRIES, MAX_RETRY_AFTER_MS, parseRetryAfter, isTransientNetworkError, MAX_DETAIL_LENGTH, describeMastrErrors, sanitizeServerText, isBidiControl, } from "./engine.js";
+export { MAX_TIMEOUT_MS, nodeHttpTransport, sizeLimitMessage } from "./http.js";
 export { buildQueryString } from "./query.js";
-export { MastrError, MastrApiError, MastrNetworkError, MastrValidationError, MastrParseError, redactUrl, } 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, credentialsIn, redactCredentials, } 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

@@ -83,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;
@@ -96,7 +98,8 @@ export interface UnitQuery {
      * 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}.
+     * via {@link MastrClient.filterColumns}; the client checks them against that list
+     * (unless `allowUnknownFilters`), because the register ignores an unknown name.
      */
     filter?: string;
 }
@@ -116,4 +119,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,65 @@
+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 `/`), and a `%` in the user name or
+ * password that doesn't start a valid escape (Node fails to decode it for the Authorization
+ * header at request time; a literal one is `%25`). 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>;