@maschinenlesbar.org/marktstammdatenregister-cli 0.0.7 → 0.1.0

package/dist/src/client/client.js

@@ -9,8 +9,10 @@
 //   const c = new MastrClient();
 //   const page = await c.stromerzeugung({ pageSize: 10, filter: "Energieträger~eq~'2495'" });
 //   page.total; // total solar units
-import { RequestEngine, sanitizeServerText } from "./engine.js";
-import { MastrApiError } from "./errors.js";
+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 = {
@@ -21,15 +23,37 @@ const CATEGORY_SUFFIX = {
 };
 const DEFAULT_PAGE = 1;
 const DEFAULT_PAGE_SIZE = 25;
+/** Largest `page` the client (and the CLI's `--page`) accepts. */
+export const MAX_PAGE = 1_000_000;
+/** Largest `pageSize` the client (and the CLI's `--page-size`) accepts. */
+export const MAX_PAGE_SIZE = 5000;
+/** The category's endpoint suffix; an unknown category (from plain JS) throws. */
+function categorySuffix(category) {
+    if (typeof category !== "string" || !Object.hasOwn(CATEGORY_SUFFIX, category)) {
+        throw new MastrValidationError(`Invalid category: expected one of ${Object.keys(CATEGORY_SUFFIX).join(", ")}, got ${JSON.stringify(category)}.`);
+    }
+    return CATEGORY_SUFFIX[category];
+}
+/** Check an optional integer paging option against 1..max. */
+function checkPaging(name, value, max) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > max) {
+        throw new MastrValidationError(`Invalid ${name}: expected an integer from 1 to ${max}, got ${typeof value === "string" ? JSON.stringify(value) : String(value)}.`);
+    }
+}
 /**
  * Parse a MaStR Microsoft-AJAX date string (`"/Date(1548979200000)/"`) into a Date.
- * Returns null if the string is not in that format.
+ * The offset form `"/Date(1548979200000+0100)/"` is accepted too; its milliseconds
+ * are UTC already, the offset only names the sender's zone. Returns null if the
+ * string is not in that format or the value is outside the Date range.
  */
 export function parseMsDate(value) {
-    const m = /^\/Date\((-?\d+)\)\/$/.exec(value);
+    const m = /^\/Date\((-?\d+)(?:[+-]\d{4})?\)\/$/.exec(value);
     if (!m)
         return null;
-    return new Date(Number(m[1]));
+    const date = new Date(Number(m[1]));
+    return Number.isNaN(date.getTime()) ? null : date;
 }
 /**
  * Recursively rewrite every `"/Date(ms)/"` string in a value to an ISO-8601 string,
@@ -37,10 +61,10 @@ export function parseMsDate(value) {
  */
 export function isoifyDates(value) {
     if (typeof value === "string") {
+        // parseMsDate returns null for an out-of-range value, so `.toISOString()` never
+        // throws; such a string is left as-is.
         const d = parseMsDate(value);
-        // An out-of-range milliseconds value yields an Invalid Date (a truthy object);
-        // guard against it so `.toISOString()` never throws — leave the string as-is.
-        return (d && !Number.isNaN(d.getTime()) ? d.toISOString() : value);
+        return (d ? d.toISOString() : value);
     }
     if (Array.isArray(value)) {
         return value.map((v) => isoifyDates(v));
@@ -58,6 +82,13 @@ export function isoifyDates(value) {
     }
     return value;
 }
+/** True for a JSON object (not null, not an array). */
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function shapeError(path, expected) {
+    return new MastrParseError(`Unexpected response shape from ${path}: expected ${expected}.`);
+}
 export class MastrClient {
     engine;
     constructor(options = {}) {
@@ -67,8 +98,19 @@ export class MastrClient {
      * Fetch one page of units for a category. Sends the full Kendo param set —
      * `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`, 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 = {
             sort: query.sort ?? "",
             page: query.page ?? DEFAULT_PAGE,
@@ -76,20 +118,50 @@ export class MastrClient {
             group: "",
             filter: query.filter ?? "",
         };
-        const path = `${SERVICE}/GetErweiterteOeffentlicheEinheit${CATEGORY_SUFFIX[category]}`;
+        const path = `${SERVICE}/GetErweiterteOeffentlicheEinheit${suffix}`;
         const res = await this.engine.getJson(path, params);
-        if (res && typeof res.Errors === "string" && res.Errors.length > 0) {
+        if (!isObject(res))
+            throw shapeError(path, "a JSON object with Data and Total");
+        // MaStR answers HTTP 200 with a logical error in `Errors`: a string such as "Die
+        // Anfrage ist Null.", or a Kendo ModelState object. Anything but null is an error
+        // (a broken reply must not read as "no matches"). The text is server-controlled
+        // and reaches stderr, so describeMastrErrors sanitises it.
+        if (res["Errors"] !== undefined && res["Errors"] !== null) {
             throw new MastrApiError({
                 url: this.engine.buildUrl(path, params),
                 method: "GET",
                 body: JSON.stringify(res),
-                // MaStR answers HTTP 200 with a logical error string; it is server-
-                // controlled and reaches stderr, so strip control characters to prevent
-                // terminal escape-sequence injection.
-                detail: sanitizeServerText(res.Errors),
+                detail: describeMastrErrors(res["Errors"]),
             });
         }
-        return { total: res?.Total ?? 0, data: (res?.Data ?? []) };
+        const total = res["Total"];
+        if (typeof total !== "number" || !Number.isSafeInteger(total) || total < 0) {
+            throw shapeError(path, "a numeric Total");
+        }
+        const data = res["Data"];
+        // A reply with no matches may carry `Data: null`; with a positive Total it must be an array.
+        if (data === null && total === 0)
+            return { total, data: [] };
+        if (!Array.isArray(data))
+            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) {
@@ -107,11 +179,25 @@ export class MastrClient {
     gasverbrauch(query) {
         return this.units("gasverbrauch", query);
     }
-    /** The filterable columns (names, types, dropdown codes) for a category. */
+    /**
+     * The filterable columns (names, types, dropdown codes) for a category. An `Errors`
+     * envelope throws `MastrApiError`, any other non-array reply `MastrParseError` —
+     * never an empty list, which would read as "this category has no filters".
+     */
     async filterColumns(category) {
-        const path = `${SERVICE}/GetFilterColumnsErweiterteOeffentlicheEinheit${CATEGORY_SUFFIX[category]}`;
+        const path = `${SERVICE}/GetFilterColumnsErweiterteOeffentlicheEinheit${categorySuffix(category)}`;
         const res = await this.engine.getJson(path);
-        return Array.isArray(res) ? res : [];
+        if (isObject(res) && res["Errors"] !== undefined && res["Errors"] !== null) {
+            throw new MastrApiError({
+                url: this.engine.buildUrl(path),
+                method: "GET",
+                body: JSON.stringify(res),
+                detail: describeMastrErrors(res["Errors"]),
+            });
+        }
+        if (!Array.isArray(res) || !res.every(isObject)) {
+            throw shapeError(path, "a JSON array of filter columns");
+        }
+        return res;
     }
 }
-//# sourceMappingURL=client.js.map

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

@@ -7,43 +7,118 @@ 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. */
+    /**
+     * 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). */
+    /**
+     * 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
+ * once: retrying early would only land inside the window the server asked us to wait
+ * out, and a hostile value must not stall the CLI.
+ */
+export declare const MAX_RETRY_AFTER_MS = 30000;
+/**
+ * Parse a `Retry-After` header into a delay in milliseconds (RFC 9110 §10.2.3):
+ * either delay-seconds (`"120"`) or an HTTP-date (`"Wed, 21 Oct 2026 07:28:00 GMT"`,
+ * turned into the time left from `now`; a date in the past gives 0).
+ *
+ * Returns `undefined` when the header is absent or malformed — negative (`"-1"`),
+ * fractional (`"1.5"`), padded inside, any other date format — so the caller falls
+ * back to its own backoff. The strict patterns matter: `Date.parse` alone would
+ * read `"1.5"` as a date in 2001 and retry at once.
+ */
+export declare function parseRetryAfter(header: string | string[] | undefined, now?: number): number | undefined;
+/**
+ * True for the Unicode bidirectional formatting characters: ALM (U+061C), LRM/RLM
+ * (U+200E/U+200F), the embeddings and overrides U+202A–U+202E and the isolates
+ * U+2066–U+2069. A terminal applies them to the text that follows, so an override
+ * in server text can reorder what the user sees ("Trojan Source" spoofing).
+ */
+export declare function isBidiControl(code: number): boolean;
 /**
- * Strip control characters (C0 except tab/newline, DEL, and C1) out of a string
- * that originates in an attacker-controlled response — the error `detail` and the
- * echoed Content-Type. `JSON.parse` decodes an escaped ESC in an error body into a
- * real ESC byte, so without this a hostile/MITM'd endpoint could drive ANSI/OSC
- * escape sequences into the user's terminal when the message is printed to stderr.
- * This only needs to cover text that flows into an error message: the CLI's JSON
- * output is escaped separately (`escapeControlChars` in cli/shared.ts), as
- * `JSON.stringify` alone leaves DEL and the C1 range raw. Implemented as a code-point
- * filter so no raw control byte ever appears in this source file.
+ * Make a string that originates in an attacker-controlled response — the error
+ * `detail` (a JSON field, an `Errors` value or a text snippet) and the echoed
+ * Content-Type — safe to print into an error message on stderr:
+ *
+ * - C0 and C1 controls and DEL are dropped. `JSON.parse` decodes an escaped ESC into
+ *   a real ESC byte; printed raw, a hostile or MITM'd endpoint could drive ANSI/OSC
+ *   sequences into the terminal.
+ * - Bidi formatting characters (isBidiControl) are dropped, so server text cannot
+ *   reorder the visible message.
+ * - Every run of whitespace — newlines, tabs, U+2028/U+2029 included — becomes one
+ *   space and the ends are trimmed, so the text stays on one line and a server
+ *   cannot forge an `Error:` line of its own.
+ *
+ * The CLI's JSON output is escaped separately (`escapeControlChars` in
+ * cli/shared.ts): `JSON.stringify` alone leaves DEL, C1 and bidi characters raw.
+ * Written as a code-point filter so no raw control byte appears in this source.
  */
 export declare function sanitizeServerText(text: string): string;
+/**
+ * Describe a Kendo `Errors` value for an error message: a string as is; otherwise
+ * (a ModelState object such as `{"": {"errors": ["Invalid filter"]}}`, or an array)
+ * every string found in it, sanitised, blanks and repeats dropped, joined "; ".
+ * 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;
@@ -63,8 +138,11 @@ export declare class RequestEngine {
      * base URL bouncing to a portal page) surfaces as an error.
      */
     request(path: string, query?: QueryParams, accept?: string): Promise<RawResponse>;
-    /** GET a path with query params and parse the JSON reply into `T`. */
+    /**
+     * GET a path with query params and parse the JSON reply into `T`. Every MaStR
+     * endpoint answers with a JSON document, so an empty body or a 204 is a
+     * `MastrParseError`, never a silent `null`.
+     */
     getJson<T>(path: string, query?: QueryParams): Promise<T>;
     private toApiError;
 }
-//# sourceMappingURL=engine.d.ts.map

package/dist/src/client/engine.js

@@ -2,50 +2,144 @@
 // 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 } 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;
 /**
- * Strip control characters (C0 except tab/newline, DEL, and C1) out of a string
- * that originates in an attacker-controlled response — the error `detail` and the
- * echoed Content-Type. `JSON.parse` decodes an escaped ESC in an error body into a
- * real ESC byte, so without this a hostile/MITM'd endpoint could drive ANSI/OSC
- * escape sequences into the user's terminal when the message is printed to stderr.
- * This only needs to cover text that flows into an error message: the CLI's JSON
- * output is escaped separately (`escapeControlChars` in cli/shared.ts), as
- * `JSON.stringify` alone leaves DEL and the C1 range raw. Implemented as a code-point
- * filter so no raw control byte ever appears in this source file.
+ * 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
+ * once: retrying early would only land inside the window the server asked us to wait
+ * out, and a hostile value must not stall the CLI.
+ */
+export const MAX_RETRY_AFTER_MS = 30_000;
+/** An IMF-fixdate (RFC 9110 §5.6.7), the one HTTP-date form senders must generate. */
+const IMF_FIXDATE = /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+/**
+ * Parse a `Retry-After` header into a delay in milliseconds (RFC 9110 §10.2.3):
+ * either delay-seconds (`"120"`) or an HTTP-date (`"Wed, 21 Oct 2026 07:28:00 GMT"`,
+ * turned into the time left from `now`; a date in the past gives 0).
+ *
+ * Returns `undefined` when the header is absent or malformed — negative (`"-1"`),
+ * fractional (`"1.5"`), padded inside, any other date format — so the caller falls
+ * back to its own backoff. The strict patterns matter: `Date.parse` alone would
+ * read `"1.5"` as a date in 2001 and retry at once.
+ */
+export function parseRetryAfter(header, now = Date.now()) {
+    const value = (Array.isArray(header) ? header[0] : header)?.trim();
+    if (value === undefined || value === "")
+        return undefined;
+    if (/^\d+$/.test(value))
+        return Number(value) * 1000;
+    if (!IMF_FIXDATE.test(value))
+        return undefined;
+    const when = Date.parse(value);
+    return Number.isNaN(when) ? undefined : Math.max(0, when - now);
+}
+/**
+ * True for the Unicode bidirectional formatting characters: ALM (U+061C), LRM/RLM
+ * (U+200E/U+200F), the embeddings and overrides U+202A–U+202E and the isolates
+ * U+2066–U+2069. A terminal applies them to the text that follows, so an override
+ * in server text can reorder what the user sees ("Trojan Source" spoofing).
+ */
+export function isBidiControl(code) {
+    return (code === 0x061c ||
+        code === 0x200e ||
+        code === 0x200f ||
+        (code >= 0x202a && code <= 0x202e) ||
+        (code >= 0x2066 && code <= 0x2069));
+}
+/**
+ * Make a string that originates in an attacker-controlled response — the error
+ * `detail` (a JSON field, an `Errors` value or a text snippet) and the echoed
+ * Content-Type — safe to print into an error message on stderr:
+ *
+ * - C0 and C1 controls and DEL are dropped. `JSON.parse` decodes an escaped ESC into
+ *   a real ESC byte; printed raw, a hostile or MITM'd endpoint could drive ANSI/OSC
+ *   sequences into the terminal.
+ * - Bidi formatting characters (isBidiControl) are dropped, so server text cannot
+ *   reorder the visible message.
+ * - Every run of whitespace — newlines, tabs, U+2028/U+2029 included — becomes one
+ *   space and the ends are trimmed, so the text stays on one line and a server
+ *   cannot forge an `Error:` line of its own.
+ *
+ * The CLI's JSON output is escaped separately (`escapeControlChars` in
+ * cli/shared.ts): `JSON.stringify` alone leaves DEL, C1 and bidi characters raw.
+ * Written as a code-point filter so no raw control byte appears in this source.
  */
 export function sanitizeServerText(text) {
     let out = "";
     for (const ch of text) {
         const n = ch.codePointAt(0) ?? 0;
-        if (n <= 8 || (n >= 0x0b && n <= 0x1f) || (n >= 0x7f && n <= 0x9f))
+        const whitespaceControl = n >= 0x09 && n <= 0x0d;
+        if (!whitespaceControl && (n <= 0x1f || (n >= 0x7f && n <= 0x9f) || isBidiControl(n)))
             continue;
         out += ch;
     }
-    return out;
+    return out.replace(/\s+/g, " ").trim();
 }
 /**
- * Reject a base URL whose scheme is not http(s). The default transport already
- * gates this 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).
+ * Describe a Kendo `Errors` value for an error message: a string as is; otherwise
+ * (a ModelState object such as `{"": {"errors": ["Invalid filter"]}}`, or an array)
+ * every string found in it, sanitised, blanks and repeats dropped, joined "; ".
+ * Returns `undefined` when nothing readable is left.
  */
-function assertHttpScheme(baseUrl) {
-    let url;
-    try {
-        url = new URL(baseUrl);
-    }
-    catch {
-        throw new MastrNetworkError(`Invalid base URL: ${baseUrl}`);
-    }
-    if (url.protocol !== "http:" && url.protocol !== "https:") {
-        throw new MastrNetworkError(`Unsupported protocol "${url.protocol}" in base URL: ${baseUrl}`);
+export function describeMastrErrors(errors) {
+    const found = [];
+    const walk = (value, depth) => {
+        if (typeof value === "string") {
+            const text = sanitizeServerText(value);
+            if (text !== "" && !found.includes(text))
+                found.push(text);
+        }
+        else if (value !== null && typeof value === "object" && depth < 5) {
+            for (const v of Object.values(value))
+                walk(v, depth + 1);
+        }
+    };
+    walk(errors, 0);
+    return found.length > 0 ? found.join("; ") : 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 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 {
@@ -59,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. */
@@ -103,9 +206,14 @@ export class RequestEngine {
             const status = response.status;
             const retryable = status === 429 || status === 503;
             if (retryable && attempt < this.maxRetries) {
-                attempt += 1;
-                await this.sleep(this.retryDelayMs * attempt);
-                continue;
+                // Honour Retry-After; without a usable one, back off linearly. A Retry-After
+                // beyond MAX_RETRY_AFTER_MS is not retried: the error below surfaces at once.
+                const retryAfter = parseRetryAfter(response.headers["retry-after"]);
+                if (retryAfter === undefined || retryAfter <= MAX_RETRY_AFTER_MS) {
+                    attempt += 1;
+                    await this.sleep(retryAfter ?? this.retryDelayMs * attempt);
+                    continue;
+                }
             }
             const contentType = String(response.headers["content-type"] ?? "");
             if (status < 200 || status >= 300) {
@@ -114,12 +222,16 @@ export class RequestEngine {
             return { data: response.body, contentType, status };
         }
     }
-    /** GET a path with query params and parse the JSON reply into `T`. */
+    /**
+     * GET a path with query params and parse the JSON reply into `T`. Every MaStR
+     * endpoint answers with a JSON document, so an empty body or a 204 is a
+     * `MastrParseError`, never a silent `null`.
+     */
     async getJson(path, query) {
         const res = await this.request(path, query);
         const text = res.data.toString("utf8");
         if (res.status === 204 || text.trim().length === 0) {
-            return null;
+            throw new MastrParseError(`Empty response body from ${path}`);
         }
         try {
             return JSON.parse(text);
@@ -133,8 +245,8 @@ export class RequestEngine {
         let detail;
         try {
             const parsed = JSON.parse(text);
-            if (typeof parsed?.Errors === "string")
-                detail = parsed.Errors;
+            if (parsed?.Errors !== undefined && parsed.Errors !== null)
+                detail = describeMastrErrors(parsed.Errors);
             else if (typeof parsed?.message === "string")
                 detail = parsed.message;
             else if (typeof parsed?.detail === "string")
@@ -156,4 +268,3 @@ export class RequestEngine {
         return new MastrApiError({ status, url, method: "GET", body: text, detail });
     }
 }
-//# sourceMappingURL=engine.js.map

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

@@ -1,3 +1,9 @@
+/**
+ * Replace the userinfo of a URL (`https://user:secret@host/...`) with `***`, so a
+ * credential in a base URL never reaches an error message, a log or CI output.
+ * A URL without userinfo, or one that does not parse, is returned unchanged.
+ */
+export declare function redactUrl(url: string): string;
 /** Base class for every error originating from this client. */
 export declare class MastrError extends Error {
     constructor(message: string, options?: {
@@ -33,10 +39,14 @@ export declare class MastrApiError extends MastrError {
 /** A transport-level failure (DNS, connection reset, timeout, ...). */
 export declare class MastrNetworkError extends MastrError {
 }
-/** A client-side validation error (e.g. a bad category) — no request made. */
+/**
+ * A client-side validation error — an unknown category, a page or pageSize out of
+ * range, a filter the register would misread — thrown before any request, with the
+ * message `Invalid <name>: <reason>` (see `assertValid`). The CLI maps it to the
+ * usage exit code 2.
+ */
 export declare class MastrValidationError extends MastrError {
 }
 /** The response body could not be parsed as the expected JSON shape. */
 export declare class MastrParseError extends MastrError {
 }
-//# sourceMappingURL=errors.d.ts.map