@maschinenlesbar.org/marktstammdatenregister-cli 0.0.8 → 0.1.0

package/README.md

@@ -67,6 +67,7 @@ import { MastrClient, parseMsDate } from "@maschinenlesbar.org/marktstammdatenre
 const mastr = new MastrClient();
 const solar = await mastr.stromerzeugung({ filter: "Energieträger~eq~'2495'", pageSize: 10 });
 solar.total; // total matching units
+await mastr.count("stromerzeugung", { filter: "Energieträger~eq~'2495'" }); // just the count, one-row request
 parseMsDate(String(solar.data[0]?.EinheitRegistrierungsdatum)); // Date | null
 ```
 

package/dist/src/cli/commands/units.d.ts

@@ -1,4 +1,3 @@
 import { type Command } from "commander";
 import type { CliDeps } from "../io.js";
 export declare function registerCommands(program: Command, deps: CliDeps): void;
-//# sourceMappingURL=units.d.ts.map

package/dist/src/cli/commands/units.js

@@ -3,7 +3,7 @@
 // `filters` command to discover the filterable columns and their dropdown codes.
 import { Argument } from "commander";
 import { MAX_PAGE, MAX_PAGE_SIZE } from "../../client/client.js";
-import { action, parseBoundedInt, parseFilter, parseNonEmpty, renderJson } from "../shared.js";
+import { action, parseBoundedInt, parseFilter, parseSort, renderJson } from "../shared.js";
 // `sortKey` is a record field that exists in that category's rows (live 2026-09-26):
 // only stromerzeugung rows carry Bruttoleistung/Nettonennleistung, so the stderr hint
 // must not suggest it for the other three.
@@ -19,21 +19,22 @@ const RUN = {
     gaserzeugung: (c, q) => c.gaserzeugung(q),
     gasverbrauch: (c, q) => c.gasverbrauch(q),
 };
+/** Build a CountQuery (filter and sort) from this command's parsed options. */
+function buildCountQuery(opts) {
+    const q = {};
+    if (typeof opts["sort"] === "string")
+        q.sort = opts["sort"];
+    if (typeof opts["filter"] === "string")
+        q.filter = opts["filter"];
+    return q;
+}
 /** Build a UnitQuery from this command's parsed options. */
 function buildQuery(opts) {
-    const q = {};
+    const q = buildCountQuery(opts);
     if (typeof opts["page"] === "number")
         q.page = opts["page"];
     if (typeof opts["pageSize"] === "number")
         q.pageSize = opts["pageSize"];
-    if (typeof opts["sort"] === "string")
-        q.sort = opts["sort"];
-    if (typeof opts["filter"] === "string")
-        q.filter = opts["filter"];
-    // `--total` needs only the match count (returned regardless of page size), so
-    // request a single row instead of fetching and discarding a full page.
-    if (opts["total"] === true)
-        q.pageSize = 1;
     return q;
 }
 export function registerCommands(program, deps) {
@@ -44,13 +45,17 @@ export function registerCommands(program, deps) {
             .option("--page <n>", "1-based page number", parseBoundedInt(1, MAX_PAGE), 1)
             .option("--page-size <n>", `rows per page (1..${MAX_PAGE_SIZE})`, parseBoundedInt(1, MAX_PAGE_SIZE), 25)
             .option("--sort <spec>", "sort: FieldKey-asc | FieldKey-desc, where FieldKey is a record field name, not a " +
-            `FilterName (e.g. ${cat.sortKey}-desc)`, parseNonEmpty)
+            `FilterName (e.g. ${cat.sortKey}-desc)`, parseSort)
             .option("--filter <spec>", "filter: FilterName~op~'value'~and~… (see `filters`; ops eq|neq|sw|ct|nct|ew|null|nn|gt|lt, " +
             "gt/lt strict; null/nn take ''). A malformed spec or unknown op is rejected. No ~or~: " +
             "for several dropdown codes use one comma list, e.g. Energieträger~eq~'2497,2498'", parseFilter)
-            .option("--total", "print only the total match count, not the rows")
+            .option("--total", "print only the total match count, not the rows (a one-row request; --page and --page-size are ignored)")
             .action(action(deps, async ({ client, global, opts }) => {
-            const page = await RUN[cat.name](client, buildQuery(opts));
+            // `--total` is the library's count(): a one-row request for the match count.
+            const total = opts["total"] === true
+                ? await client.count(cat.name, buildCountQuery(opts))
+                : undefined;
+            const page = total === undefined ? await RUN[cat.name](client, buildQuery(opts)) : { total };
             // An unknown --sort key or --filter operator makes the server return 0 rows
             // (not an error), which reads like "no matches". Nudge the user toward the
             // likely cause. Sort keys are the record's field names (`Bruttoleistung`);
@@ -68,7 +73,7 @@ export function registerCommands(program, deps) {
                     "dropdown takes its code (the Value from `mastr filters`), not its label, decimals " +
                     "take a point ('4999.999'), and gt/lt are strict.");
             }
-            renderJson(deps, global, opts["total"] === true ? page.total : page);
+            renderJson(deps, global, total ?? page);
         }));
     }
     program
@@ -79,4 +84,3 @@ export function registerCommands(program, deps) {
         renderJson(deps, global, await client.filterColumns(category));
     }));
 }
-//# sourceMappingURL=units.js.map

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

@@ -1,3 +1,2 @@
 #!/usr/bin/env node
 export {};
-//# sourceMappingURL=index.d.ts.map

package/dist/src/cli/index.js

@@ -8,4 +8,3 @@ run(process.argv.slice(2)).then((code) => {
     process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}\n`);
     process.exitCode = 1;
 });
-//# sourceMappingURL=index.js.map

package/dist/src/cli/io.d.ts

@@ -9,4 +9,3 @@ export interface CliDeps {
     createClient(options: MastrClientOptions): MastrClient;
 }
 export declare const defaultIO: CliIO;
-//# sourceMappingURL=io.d.ts.map

package/dist/src/cli/io.js

@@ -4,4 +4,3 @@ export const defaultIO = {
     out: (text) => process.stdout.write(text + "\n"),
     err: (text) => process.stderr.write(text + "\n"),
 };
-//# sourceMappingURL=io.js.map

package/dist/src/cli/program.d.ts

@@ -4,4 +4,3 @@ export declare const VERSION: string;
 /** Default dependencies: real client + real stdout/stderr. */
 export declare const defaultDeps: CliDeps;
 export declare function buildProgram(deps?: CliDeps): Command;
-//# sourceMappingURL=program.d.ts.map

package/dist/src/cli/program.js

@@ -7,6 +7,7 @@ import { Command } from "commander";
 import { defaultIO } from "./io.js";
 import { MastrClient } from "../client/client.js";
 import { MAX_TIMEOUT_MS } from "../client/http.js";
+import { MAX_RETRIES } from "../client/engine.js";
 import { parseIntArg, parseBoundedInt, parseHeaderValue, parseBaseUrl } from "./shared.js";
 import { registerCommands } from "./commands/units.js";
 /**
@@ -44,7 +45,7 @@ export function buildProgram(deps = defaultDeps) {
         .option("--base-url <url>", "API base URL (http/https only)", parseBaseUrl, "https://www.marktstammdatenregister.de/MaStR")
         .option("--timeout <ms>", "time limit per request in ms, whole response included (0 = no timeout)", parseBoundedInt(0, MAX_TIMEOUT_MS))
         .option("--user-agent <ua>", "User-Agent header value", parseHeaderValue)
-        .option("--max-retries <n>", "retries for transient 429/503 responses (0..10; each waits the server's Retry-After, up to 30 s)", parseBoundedInt(0, 10))
+        .option("--max-retries <n>", `retries for transient 429/503 responses (0..${MAX_RETRIES}; each waits the server's Retry-After, up to 30 s)`, parseBoundedInt(0, MAX_RETRIES))
         .option("--max-response-bytes <n>", "cap response body size in bytes (0 = unlimited; default 100 MiB)", parseIntArg)
         .option("--compact", "print JSON on a single line instead of pretty-printed")
         .option("--iso-dates", "rewrite MaStR /Date(ms)/ timestamps to ISO-8601")
@@ -52,4 +53,3 @@ export function buildProgram(deps = defaultDeps) {
     registerCommands(program, deps);
     return program;
 }
-//# sourceMappingURL=program.js.map

package/dist/src/cli/run.d.ts

@@ -1,3 +1,2 @@
 import type { CliDeps } from "./io.js";
 export declare function run(argv: string[], deps?: CliDeps): Promise<number>;
-//# sourceMappingURL=run.d.ts.map

package/dist/src/cli/run.js

@@ -82,4 +82,3 @@ export async function run(argv, deps = defaultDeps) {
         return EXIT.OTHER;
     }
 }
-//# sourceMappingURL=run.js.map

package/dist/src/cli/shared.d.ts

@@ -1,5 +1,6 @@
 import type { CliDeps } from "./io.js";
 import type { MastrClientOptions } from "../client/client.js";
+import { type Problem } from "../client/validate.js";
 /**
  * commander value-parser: a plain base-10 non-negative integer.
  *
@@ -8,32 +9,36 @@ import type { MastrClientOptions } from "../client/client.js";
  * literals (`0x10`, `0b10`, `1e3`), signs, padding and decimals.
  */
 export declare function parseIntArg(value: string): number;
-/** commander value-parser: a non-empty (after trimming) string. */
-export declare function parseNonEmpty(value: string): string;
+/**
+ * Build a commander value-parser from a library rule: the rule's reason becomes the
+ * usage error, a valid value passes unchanged.
+ */
+export declare function parseWith(problem: Problem<string>): (value: string) => string;
+/** commander value-parser: a non-empty (after trimming) string (the library's `nonBlankProblem`). */
+export declare const parseNonEmpty: (value: string) => string;
+/** commander value-parser for `--sort`: the library's `sortProblem` (not blank). */
+export declare const parseSort: (value: string) => string;
 /**
  * commander value-parser for `--filter`: non-blank, and not a spec the register would
  * misread (see `filterProblem`), so it becomes a usage error before any request.
  */
 export declare function parseFilter(value: string): string;
 /**
- * commander value-parser for `--base-url`: non-empty and http/https-only.
- *
- * The transport already rejects any non-http(s) scheme, so this is defence in
- * depth — but doing the check at parse time turns a bad scheme (e.g. `file:` /
- * `data:` / `ftp:`) into a friendly usage error (exit 2) with the value the user
- * actually typed, rather than a network error (exit 6) echoing the fully built
- * request URL. The transport check stays the enforcement point for library callers.
+ * commander value-parser for `--base-url`: the library's `baseUrlProblem` (non-blank,
+ * no whitespace, an absolute http(s) URL without a query or fragment), whose reason
+ * becomes a usage error (exit 2) naming the value the user typed. The CLI keeps no
+ * rules of its own; the client constructor enforces the same rule for library callers.
  */
-export declare function parseBaseUrl(value: string): string;
+export declare const parseBaseUrl: (value: string) => string;
 /** Build a commander value-parser for an integer constrained to [min, max]. */
 export declare function parseBoundedInt(min: number, max: number): (value: string) => number;
 /**
- * commander value-parser for a value that ends up in an HTTP header (User-Agent).
- * Rejects control characters — a CR/LF (or other C0/DEL byte) would otherwise reach
- * Node's HTTP layer and throw an opaque `ERR_INVALID_CHAR`. Tab (0x09) is allowed;
- * checked by char code so the source stays free of control bytes.
+ * commander value-parser for a value that ends up in an HTTP header (User-Agent):
+ * the library's `headerValueProblem` (not blank, Latin-1 without control
+ * characters; tab is fine), whose reason becomes the usage error. The engine runs
+ * the same rule on `userAgent`.
  */
-export declare function parseHeaderValue(value: string): string;
+export declare const parseHeaderValue: (value: string) => string;
 export interface GlobalOptions {
     baseUrl?: string;
     timeout?: number;
@@ -74,4 +79,3 @@ export interface ActionContext {
  * the trailing options object and command instance to recover the positionals.
  */
 export declare function action(deps: CliDeps, fn: (ctx: ActionContext, positionals: string[]) => Promise<void>): (...args: unknown[]) => Promise<void>;
-//# sourceMappingURL=shared.d.ts.map

package/dist/src/cli/shared.js

@@ -5,6 +5,7 @@ import { isoifyDates } from "../client/client.js";
 import { MastrParseError } from "../client/errors.js";
 import { filterProblem } from "../client/filter.js";
 import { isBidiControl } from "../client/engine.js";
+import { baseUrlProblem, headerValueProblem, nonBlankProblem, sortProblem, } from "../client/validate.js";
 /**
  * commander value-parser: a plain base-10 non-negative integer.
  *
@@ -22,13 +23,22 @@ export function parseIntArg(value) {
     }
     return n;
 }
-/** commander value-parser: a non-empty (after trimming) string. */
-export function parseNonEmpty(value) {
-    if (value.trim() === "") {
-        throw new InvalidArgumentError("Expected a non-empty value.");
-    }
-    return value;
+/**
+ * Build a commander value-parser from a library rule: the rule's reason becomes the
+ * usage error, a valid value passes unchanged.
+ */
+export function parseWith(problem) {
+    return (value) => {
+        const reason = problem(value);
+        if (reason !== undefined)
+            throw new InvalidArgumentError(reason);
+        return value;
+    };
 }
+/** commander value-parser: a non-empty (after trimming) string (the library's `nonBlankProblem`). */
+export const parseNonEmpty = parseWith(nonBlankProblem);
+/** commander value-parser for `--sort`: the library's `sortProblem` (not blank). */
+export const parseSort = parseWith(sortProblem);
 /**
  * commander value-parser for `--filter`: non-blank, and not a spec the register would
  * misread (see `filterProblem`), so it becomes a usage error before any request.
@@ -41,41 +51,12 @@ export function parseFilter(value) {
     return value;
 }
 /**
- * commander value-parser for `--base-url`: non-empty and http/https-only.
- *
- * The transport already rejects any non-http(s) scheme, so this is defence in
- * depth — but doing the check at parse time turns a bad scheme (e.g. `file:` /
- * `data:` / `ftp:`) into a friendly usage error (exit 2) with the value the user
- * actually typed, rather than a network error (exit 6) echoing the fully built
- * request URL. The transport check stays the enforcement point for library callers.
+ * commander value-parser for `--base-url`: the library's `baseUrlProblem` (non-blank,
+ * no whitespace, an absolute http(s) URL without a query or fragment), whose reason
+ * becomes a usage error (exit 2) naming the value the user typed. The CLI keeps no
+ * rules of its own; the client constructor enforces the same rule for library callers.
  */
-export function parseBaseUrl(value) {
-    const trimmed = value.trim();
-    if (trimmed === "") {
-        throw new InvalidArgumentError("Expected a non-empty value.");
-    }
-    let parsed;
-    try {
-        parsed = new URL(trimmed);
-    }
-    catch {
-        throw new InvalidArgumentError("Expected an absolute http(s) URL.");
-    }
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-        throw new InvalidArgumentError("Only http and https URLs are supported.");
-    }
-    // Paths are appended to the base URL as a string, so a query or fragment would
-    // swallow every request path ("http://h/#f" requests "/" for every command).
-    if (/[?#]/.test(value)) {
-        throw new InvalidArgumentError("A base URL cannot have a query (?) or fragment (#).");
-    }
-    // new URL() trims surrounding whitespace silently; the raw value is what the
-    // engine uses, so reject it rather than guess.
-    if (value !== value.trim()) {
-        throw new InvalidArgumentError("A base URL cannot have surrounding whitespace.");
-    }
-    return value;
-}
+export const parseBaseUrl = parseWith(baseUrlProblem);
 /** Build a commander value-parser for an integer constrained to [min, max]. */
 export function parseBoundedInt(min, max) {
     return (value) => {
@@ -88,20 +69,12 @@ export function parseBoundedInt(min, max) {
     };
 }
 /**
- * commander value-parser for a value that ends up in an HTTP header (User-Agent).
- * Rejects control characters — a CR/LF (or other C0/DEL byte) would otherwise reach
- * Node's HTTP layer and throw an opaque `ERR_INVALID_CHAR`. Tab (0x09) is allowed;
- * checked by char code so the source stays free of control bytes.
+ * commander value-parser for a value that ends up in an HTTP header (User-Agent):
+ * the library's `headerValueProblem` (not blank, Latin-1 without control
+ * characters; tab is fine), whose reason becomes the usage error. The engine runs
+ * the same rule on `userAgent`.
  */
-export function parseHeaderValue(value) {
-    for (let i = 0; i < value.length; i++) {
-        const c = value.charCodeAt(i);
-        if ((c < 0x20 && c !== 0x09) || c === 0x7f) {
-            throw new InvalidArgumentError("Value contains control characters.");
-        }
-    }
-    return value;
-}
+export const parseHeaderValue = parseWith(headerValueProblem);
 /** Translate resolved global CLI options into client options. */
 export function toEngineOptions(global) {
     const options = {};
@@ -176,4 +149,3 @@ export function action(deps, fn) {
         await fn({ client, global, opts: command.opts() }, positionals);
     };
 }
-//# sourceMappingURL=shared.js.map

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

@@ -1,5 +1,5 @@
 import { type EngineOptions } from "./engine.js";
-import type { FilterColumn, UnitCategory, UnitPage, UnitQuery } from "./types.js";
+import type { CountQuery, FilterColumn, UnitCategory, UnitPage, UnitQuery } from "./types.js";
 /** Largest `page` the client (and the CLI's `--page`) accepts. */
 export declare const MAX_PAGE = 1000000;
 /** Largest `pageSize` the client (and the CLI's `--page-size`) accepts. */
@@ -26,10 +26,20 @@ export declare class MastrClient {
      * `sort`, `page`, `pageSize`, `group`, `filter` — always, because the server
      * rejects a request with `group`/`filter` missing ("Die Anfrage ist Null.").
      * An unknown category, a `page` outside 1..`MAX_PAGE`, a `pageSize` outside
-     * 1..`MAX_PAGE_SIZE` or a filter the register would misread (e.g. `~or~`, see
-     * {@link validateFilter}) is rejected with a `MastrValidationError` before any request.
+     * 1..`MAX_PAGE_SIZE`, a blank `sort` ({@link sortProblem}) or a filter the register
+     * would misread (e.g. `~or~`, see {@link validateFilter}) is rejected with a
+     * `MastrValidationError` before any request.
      */
     units(category: UnitCategory, query?: UnitQuery): Promise<UnitPage>;
+    /**
+     * The number of units in a category that match `filter` (all units without one).
+     * Fetches a single row (`page=1`, `pageSize=1`) and returns the envelope's
+     * `Total`, which counts every match regardless of the page. `sort` is forwarded:
+     * an unknown sort key makes the register answer 0. Paging options are refused
+     * (`countQueryProblem`), as are the inputs `units()` refuses, all with a
+     * `MastrValidationError` before any request.
+     */
+    count(category: UnitCategory, query?: CountQuery): Promise<number>;
     /** Electricity-generation units (`Stromerzeugung`). */
     stromerzeugung(query?: UnitQuery): Promise<UnitPage>;
     /** Electricity-consumption units (`Stromverbrauch`). */
@@ -45,4 +55,3 @@ export declare class MastrClient {
      */
     filterColumns(category: UnitCategory): Promise<FilterColumn[]>;
 }
-//# sourceMappingURL=client.d.ts.map

package/dist/src/client/client.js

@@ -12,6 +12,7 @@
 import { RequestEngine, describeMastrErrors } from "./engine.js";
 import { MastrApiError, MastrParseError, MastrValidationError } from "./errors.js";
 import { validateFilter } from "./filter.js";
+import { assertValid, countQueryProblem, sortProblem } from "./validate.js";
 const SERVICE = "/Einheit/EinheitJson";
 /** Map a category to the PascalCase suffix used in the endpoint names. */
 const CATEGORY_SUFFIX = {
@@ -98,13 +99,16 @@ export class MastrClient {
      * `sort`, `page`, `pageSize`, `group`, `filter` — always, because the server
      * rejects a request with `group`/`filter` missing ("Die Anfrage ist Null.").
      * An unknown category, a `page` outside 1..`MAX_PAGE`, a `pageSize` outside
-     * 1..`MAX_PAGE_SIZE` or a filter the register would misread (e.g. `~or~`, see
-     * {@link validateFilter}) is rejected with a `MastrValidationError` before any request.
+     * 1..`MAX_PAGE_SIZE`, a blank `sort` ({@link sortProblem}) or a filter the register
+     * would misread (e.g. `~or~`, see {@link validateFilter}) is rejected with a
+     * `MastrValidationError` before any request.
      */
     async units(category, query = {}) {
         const suffix = categorySuffix(category);
         checkPaging("page", query.page, MAX_PAGE);
         checkPaging("pageSize", query.pageSize, MAX_PAGE_SIZE);
+        if (query.sort !== undefined)
+            assertValid("sort", query.sort, sortProblem);
         if (query.filter !== undefined)
             validateFilter(query.filter);
         const params = {
@@ -142,6 +146,23 @@ export class MastrClient {
             throw shapeError(path, "a Data array");
         return { total, data: data };
     }
+    /**
+     * The number of units in a category that match `filter` (all units without one).
+     * Fetches a single row (`page=1`, `pageSize=1`) and returns the envelope's
+     * `Total`, which counts every match regardless of the page. `sort` is forwarded:
+     * an unknown sort key makes the register answer 0. Paging options are refused
+     * (`countQueryProblem`), as are the inputs `units()` refuses, all with a
+     * `MastrValidationError` before any request.
+     */
+    async count(category, query = {}) {
+        assertValid("count query", query, countQueryProblem);
+        const q = { page: 1, pageSize: 1 };
+        if (query.sort !== undefined)
+            q.sort = query.sort;
+        if (query.filter !== undefined)
+            q.filter = query.filter;
+        return (await this.units(category, q)).total;
+    }
     /** Electricity-generation units (`Stromerzeugung`). */
     stromerzeugung(query) {
         return this.units("stromerzeugung", query);
@@ -180,4 +201,3 @@ export class MastrClient {
         return res;
     }
 }
-//# sourceMappingURL=client.js.map

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

@@ -7,35 +7,51 @@ export interface RawResponse {
     status: number;
 }
 export interface EngineOptions {
-    /** Base URL of the API. Defaults to the canonical marktstammdatenregister.de base. */
+    /**
+     * Base URL of the API. Defaults to the canonical marktstammdatenregister.de base.
+     * A value that breaks a rule of {@link validateBaseUrl} (blank, whitespace or
+     * control characters, not an absolute http(s) URL, a query or fragment) throws a
+     * MastrValidationError.
+     */
     baseUrl?: string;
     /** Swappable transport. Defaults to the built-in node http/https transport. */
     transport?: Transport;
-    /** Value of the User-Agent header. */
+    /**
+     * Value of the User-Agent header: not blank, Latin-1 without control characters
+     * (tab is fine), else a MastrValidationError.
+     */
     userAgent?: string;
-    /** Extra headers sent on every request. */
+    /** Extra headers sent on every request; names must be tokens, values follow the `userAgent` rule. */
     defaultHeaders?: Record<string, string>;
     /**
      * Time limit per request in milliseconds, covering the whole response body, not
-     * only idle gaps (0 disables; capped at MAX_TIMEOUT_MS, 2^31 - 1 ms).
+     * only idle gaps: an integer 0..`MAX_TIMEOUT_MS` (2^31 - 1 ms); 0 disables.
+     * Defaults to 30000.
      */
     timeoutMs?: number;
     /**
-     * Number of automatic retries for transient (429/503) responses. Each waits the
-     * response's `Retry-After` (up to `MAX_RETRY_AFTER_MS`; a longer one is not
-     * retried), or else `retryDelayMs * attempt`.
+     * Number of automatic retries for transient (429/503) responses, an integer
+     * 0..`MAX_RETRIES` (10); defaults to 2. Each waits the response's `Retry-After`
+     * (up to `MAX_RETRY_AFTER_MS`; a longer one is not retried), or else
+     * `retryDelayMs * attempt`.
      */
     maxRetries?: number;
-    /** Base backoff between retries in milliseconds (grows linearly); used without a Retry-After. */
+    /**
+     * Base backoff between retries in milliseconds (grows linearly), a non-negative
+     * integer; used without a Retry-After. Defaults to 200.
+     */
     retryDelayMs?: number;
     /**
      * Hard cap on response body size in bytes (defends against memory exhaustion
-     * from a hostile/buggy endpoint). Defaults to 100 MiB; set to 0 for no limit.
+     * from a hostile/buggy endpoint), a non-negative integer. Defaults to 100 MiB;
+     * set to 0 for no limit.
      */
     maxResponseBytes?: number;
     /** Injectable sleep, primarily for deterministic tests. */
     sleep?: (ms: number) => Promise<void>;
 }
+/** Most retries `maxRetries` may ask for (each may wait up to `MAX_RETRY_AFTER_MS`). */
+export declare const MAX_RETRIES = 10;
 /**
  * Longest `Retry-After` the engine waits out before retrying a 429/503. When the
  * server asks for longer, the engine does not retry at all and surfaces the error at
@@ -87,6 +103,22 @@ export declare function sanitizeServerText(text: string): string;
  * Returns `undefined` when nothing readable is left.
  */
 export declare function describeMastrErrors(errors: unknown): string | undefined;
+/**
+ * Check a base URL against every rule of {@link baseUrlProblem} — blank, whitespace
+ * or control characters, not an absolute URL, a scheme other than `http:`/`https:`,
+ * a query or fragment — and return it with trailing slashes stripped. A bad value
+ * throws a MastrValidationError (`Invalid baseUrl: <reason>`): it is a configuration
+ * error, not a transport failure. The default transport still gates the scheme per
+ * request, but the engine may be handed a custom transport that does no such check,
+ * so the configured value is checked here, on the raw string.
+ */
+export declare function validateBaseUrl(raw: string): string;
+/**
+ * Check a value bound for an HTTP header (`headerValueProblem`) and return it, or
+ * throw a MastrValidationError (`Invalid <name>: <reason>`). The engine runs it on
+ * `userAgent` and every `defaultHeaders` value before any request.
+ */
+export declare function assertHeaderValue(name: string, value: string): string;
 export declare class RequestEngine {
     private readonly baseUrl;
     private readonly transport;
@@ -114,4 +146,3 @@ export declare class RequestEngine {
     getJson<T>(path: string, query?: QueryParams): Promise<T>;
     private toApiError;
 }
-//# sourceMappingURL=engine.d.ts.map

package/dist/src/client/engine.js

@@ -2,12 +2,22 @@
 // a Transport, applies retry/backoff for transient statuses (429, 503), and decodes
 // JSON responses. MaStR's public search backend is an unauthenticated GET API whose
 // parameters travel in the query string.
-import { nodeHttpTransport } from "./http.js";
+import { MAX_TIMEOUT_MS, nodeHttpTransport } from "./http.js";
 import { buildQueryString } from "./query.js";
-import { MastrApiError, MastrNetworkError, MastrParseError, redactUrl } from "./errors.js";
+import { MastrApiError, MastrParseError } from "./errors.js";
+import { assertValid, baseUrlProblem, headerNameProblem, headerValueProblem, intRangeProblem, } from "./validate.js";
 export const DEFAULT_BASE_URL = "https://www.marktstammdatenregister.de/MaStR";
 const DEFAULT_USER_AGENT = "marktstammdatenregister-cli";
 const DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024 * 1024;
+/** Most retries `maxRetries` may ask for (each may wait up to `MAX_RETRY_AFTER_MS`). */
+export const MAX_RETRIES = 10;
+/**
+ * A numeric engine option: `fallback` when undefined, else an integer in 0..max,
+ * or a MastrValidationError (`Invalid <name>: expected an integer …`).
+ */
+function intOption(name, value, max, fallback) {
+    return value === undefined ? fallback : assertValid(name, value, intRangeProblem(0, max));
+}
 /**
  * Longest `Retry-After` the engine waits out before retrying a 429/503. When the
  * server asks for longer, the engine does not retry at all and surfaces the error at
@@ -103,28 +113,33 @@ export function describeMastrErrors(errors) {
     return found.length > 0 ? found.join("; ") : undefined;
 }
 /**
- * Reject a base URL whose scheme is not http(s), or that has a query or fragment.
- * The default transport already gates the scheme per hop, but the engine is
- * exported as a library and may be handed a custom transport that does no such
- * check, so gate the configured base URL here too (a `file:`/`ftp:` base URL fails
- * fast with a typed error). Request paths are appended to the base URL as a string,
- * so a `?` or `#` in it would swallow every path: `http://h/?x=1` requests
- * `/?x=1/Einheit/...` and `http://h/#f` requests `/`.
+ * Check a base URL against every rule of {@link baseUrlProblem} — blank, whitespace
+ * or control characters, not an absolute URL, a scheme other than `http:`/`https:`,
+ * a query or fragment — and return it with trailing slashes stripped. A bad value
+ * throws a MastrValidationError (`Invalid baseUrl: <reason>`): it is a configuration
+ * error, not a transport failure. The default transport still gates the scheme per
+ * request, but the engine may be handed a custom transport that does no such check,
+ * so the configured value is checked here, on the raw string.
  */
-function assertHttpScheme(baseUrl) {
-    let url;
-    try {
-        url = new URL(baseUrl);
-    }
-    catch {
-        throw new MastrNetworkError(`Invalid base URL: ${redactUrl(baseUrl)}`);
-    }
-    if (url.protocol !== "http:" && url.protocol !== "https:") {
-        throw new MastrNetworkError(`Unsupported protocol "${url.protocol}" in base URL: ${redactUrl(baseUrl)}`);
-    }
-    if (/[?#]/.test(baseUrl)) {
-        throw new MastrNetworkError(`Base URL must not contain a query or fragment: ${redactUrl(baseUrl)}`);
+export function validateBaseUrl(raw) {
+    return assertValid("baseUrl", raw, baseUrlProblem).replace(/\/+$/, "");
+}
+/**
+ * Check a value bound for an HTTP header (`headerValueProblem`) and return it, or
+ * throw a MastrValidationError (`Invalid <name>: <reason>`). The engine runs it on
+ * `userAgent` and every `defaultHeaders` value before any request.
+ */
+export function assertHeaderValue(name, value) {
+    return assertValid(name, value, headerValueProblem);
+}
+/** Check every `defaultHeaders` name (a token) and value; returns a copy. */
+function checkedHeaders(headers) {
+    const out = {};
+    for (const [name, value] of Object.entries(headers)) {
+        assertValid("defaultHeaders name", name, headerNameProblem);
+        out[name] = assertHeaderValue(`defaultHeaders["${name}"]`, value);
     }
+    return out;
 }
 const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export class RequestEngine {
@@ -138,15 +153,24 @@ export class RequestEngine {
     maxResponseBytes;
     sleep;
     constructor(options = {}) {
-        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-        assertHttpScheme(this.baseUrl);
+        // The raw value is checked before the trailing-slash strip, so "https://h/ "
+        // cannot slip past it; only an omitted baseUrl selects the default.
+        this.baseUrl = validateBaseUrl(options.baseUrl === undefined ? DEFAULT_BASE_URL : options.baseUrl);
         this.transport = options.transport ?? nodeHttpTransport;
-        this.userAgent = options.userAgent ?? DEFAULT_USER_AGENT;
-        this.defaultHeaders = options.defaultHeaders ?? {};
-        this.timeoutMs = options.timeoutMs ?? 30_000;
-        this.maxRetries = options.maxRetries ?? 2;
-        this.retryDelayMs = options.retryDelayMs ?? 200;
-        this.maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+        // Header values are checked up front: a blank one would be sent as is, and a
+        // CR/LF or a character above U+00FF would reach a custom transport raw or make
+        // Node's HTTP layer throw an untyped ERR_INVALID_CHAR. Only an omitted
+        // userAgent selects the default.
+        this.userAgent =
+            options.userAgent === undefined ? DEFAULT_USER_AGENT : assertHeaderValue("userAgent", options.userAgent);
+        this.defaultHeaders = checkedHeaders(options.defaultHeaders ?? {});
+        // Range-check the numeric options: a negative, NaN or fractional value would
+        // otherwise silently disable the timeout or the size cap, and an unbounded
+        // maxRetries would keep retrying against the production register.
+        this.timeoutMs = intOption("timeoutMs", options.timeoutMs, MAX_TIMEOUT_MS, 30_000);
+        this.maxRetries = intOption("maxRetries", options.maxRetries, MAX_RETRIES, 2);
+        this.retryDelayMs = intOption("retryDelayMs", options.retryDelayMs, Number.MAX_SAFE_INTEGER, 200);
+        this.maxResponseBytes = intOption("maxResponseBytes", options.maxResponseBytes, Number.MAX_SAFE_INTEGER, DEFAULT_MAX_RESPONSE_BYTES);
         this.sleep = options.sleep ?? realSleep;
     }
     /** Build a fully-qualified URL from a path and optional query parameters. */
@@ -244,4 +268,3 @@ export class RequestEngine {
         return new MastrApiError({ status, url, method: "GET", body: text, detail });
     }
 }
-//# sourceMappingURL=engine.js.map