@maschinenlesbar.org/marktstammdatenregister-cli 0.1.0 → 0.2.0

package/dist/src/client/errors.js

@@ -11,14 +11,63 @@ export function redactUrl(url) {
         parsed = new URL(url);
     }
     catch {
-        return url;
+        // A value that doesn't parse (a port typo, an unencoded "#" in the password) can still
+        // carry credentials: cut them out by text.
+        return redactCredentials(url, credentialsIn(url));
     }
+    // `user:pw@host` without a scheme parses as a URL with the scheme "user:": no userinfo.
     if (parsed.username === "" && parsed.password === "")
-        return url;
+        return redactCredentials(url, credentialsIn(url));
     parsed.username = "***";
     parsed.password = "";
     return parsed.href;
 }
+/**
+ * The userinfo a URL-like value carries, exactly as written — `["alice:pa#ss"]` for
+ * `https://alice:pa#ss@host` — or `[]` when it carries none. It works on values that don't
+ * parse as a URL too, and on values with a prefix (`--base-url=https://u:p@h`): the userinfo
+ * is everything between `://` and the last `@` before the host. A value without a scheme
+ * counts when it reads `user:password@host`. Used to redact those exact strings from text
+ * that echoes the value (usage errors, help), whatever characters the password contains.
+ */
+export function credentialsIn(value) {
+    if (typeof value !== "string")
+        return [];
+    const schemeAt = value.indexOf("://");
+    const rest = schemeAt >= 0 ? value.slice(schemeAt + 3) : value;
+    // Without a scheme only the unmistakable `user:password@host` form counts.
+    if (schemeAt < 0 && !/^[^\s/@:]+:[^@]*@[^@\s/]/.test(rest))
+        return [];
+    // The URL itself starts at its scheme (`--base-url=https://…` has a prefix).
+    const scheme = schemeAt >= 0 ? /[a-z][a-z0-9+.-]*$/i.exec(value.slice(0, schemeAt)) : null;
+    let parses = false;
+    try {
+        new URL(schemeAt >= 0 ? value.slice(scheme?.index ?? schemeAt) : `http://${rest}`);
+        parses = true;
+    }
+    catch {
+        // Doesn't parse: the password may hold "/", "?", "#" or spaces.
+    }
+    // In a URL that parses, the userinfo ends at the last "@" of the authority (before the
+    // first "/", "?" or "#"); in one that doesn't, at the last "@" of the value.
+    const authority = parses ? rest.slice(0, rest.search(/[/?#]|$/)) : rest;
+    const end = authority.lastIndexOf("@");
+    return end > 0 ? [rest.slice(0, end)] : [];
+}
+/**
+ * `text` with every occurrence of each credential (as `credentialsIn` returns them) that is
+ * followed by `@` replaced by `***`. Matching the exact strings, not a pattern, covers
+ * passwords with spaces, quotes, `#`, `?` or `/` that no URL pattern can delimit.
+ */
+export function redactCredentials(text, credentials) {
+    let out = text;
+    for (const secret of credentials) {
+        if (secret === "")
+            continue;
+        out = out.split(`${secret}@`).join("***@");
+    }
+    return out;
+}
 /** Base class for every error originating from this client. */
 export class MastrError extends Error {
     constructor(message, options) {

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,5 +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;
+/**
+ * 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,13 +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}`);
 }
+/** 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.

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.
@@ -64,7 +68,7 @@ export const nodeHttpTransport = (request) => new Promise((resolve, reject) => {
                 if (maxBytes !== undefined && received > maxBytes) {
                     aborted = true;
                     res.destroy();
-                    fail(new MastrNetworkError(`Response exceeded maxResponseBytes (${maxBytes})`));
+                    fail(new MastrNetworkError(sizeLimitMessage(maxBytes)));
                     return;
                 }
                 chunks.push(chunk);
@@ -99,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 }));
     });

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

@@ -1,14 +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, assertHeaderValue, validateBaseUrl, DEFAULT_BASE_URL, MAX_RETRIES, 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";

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, 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 { 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 { 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 { MastrError, MastrApiError, MastrNetworkError, MastrValidationError, MastrParseError, redactUrl, credentialsIn, redactCredentials, } from "./errors.js";
 export * from "./types.js";

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

@@ -98,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;
 }

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

@@ -43,8 +43,10 @@ export declare const baseUrlWhitespaceProblem: Problem<string>;
  * 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.
+ * 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>;
 /**

package/dist/src/client/validate.js

@@ -87,8 +87,10 @@ export const baseUrlWhitespaceProblem = (value) => {
  * 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.
+ * 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 const baseUrlProblem = (value) => {
     const blank = nonBlankProblem(value);
@@ -108,6 +110,16 @@ export const baseUrlProblem = (value) => {
         return "Only http and https URLs are supported.";
     if (/[?#]/.test(value))
         return "A base URL cannot have a query (?) or fragment (#).";
+    // Node decodes the userinfo into the Authorization header and throws "URI malformed" for a
+    // "%" that isn't an escape — at request time, as a network error. Reject it here.
+    for (const part of [url.username, url.password]) {
+        try {
+            decodeURIComponent(part);
+        }
+        catch {
+            return 'The user name or password has a "%" that is not followed by two hex digits; write a literal "%" as %25.';
+        }
+    }
     return undefined;
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maschinenlesbar.org/marktstammdatenregister-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript API client and CLI for the Marktstammdatenregister (MaStR) — the Bundesnetzagentur's register of German electricity & gas market units",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
     "CONTRIBUTING.md"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.12"
   },
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
@@ -68,7 +68,7 @@
     "commander": "15.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.5.1",
+    "@types/node": "^22.20.5",
     "typescript": "7.0.2"
   }
 }