@maschinenlesbar.org/marktstammdatenregister-cli 0.1.0 → 0.2.0

package/README.md

@@ -27,14 +27,16 @@ npm install -g @maschinenlesbar.org/marktstammdatenregister-cli   # the `mastr`
 npm install @maschinenlesbar.org/marktstammdatenregister-cli
 ```
 
+Requires **Node.js 22.12+**.
+
 ## CLI
 
 Four datasets, each paged and filterable. Prints `{ total, data }` (or just the
 count with `--total`).
 
 ```bash
-mastr stromerzeugung --total                       # how many electricity-generation units? → 9063887
-mastr stromerzeugung --filter "Energieträger~eq~'2495'" --total   # …how many are solar? → 6267133
+mastr stromerzeugung --total                       # how many electricity-generation units? → 9562366 (2026-10-05; it grows)
+mastr stromerzeugung --filter "Energieträger~eq~'2495'" --total   # …how many are solar? → 6545851
 mastr stromerzeugung --sort "Bruttoleistung-desc" --page-size 20 --iso-dates
 mastr gaserzeugung --page 1 --page-size 50
 mastr filters stromerzeugung                        # the filterable columns + dropdown codes
@@ -46,12 +48,15 @@ Categories: `stromerzeugung`, `stromverbrauch`, `gaserzeugung`, `gasverbrauch`.
 (ops `eq|neq|sw|ct|nct|ew|null|nn`, plus the strict `gt`/`lt` for numbers and dates);
 there is **no working `~or~`** (the register drops everything after it, so the CLI
 rejects it) — for several codes of one dropdown, list them in one value:
-`Energieträger~eq~'2497,2498'`. Discover the German field names and dropdown codes with `mastr filters <category>`. A
-**wrong `FilterName` is silently ignored** (you get the unfiltered set), and a **wrong
-`--sort` key returns 0 rows**; a malformed spec or an unknown operator (e.g. `gte`) is
-rejected before any request (exit 2), because the register would answer it with a wrong
-count. Verify filter names
-with `mastr filters` and sanity-check with `--total`; sort keys are record field names
+`Energieträger~eq~'2497,2498'`. Discover the German field names and dropdown codes with `mastr filters <category>`.
+The register silently ignores a FilterName it doesn't know (you'd get the unfiltered set)
+and answers an unknown dropdown code with 0 rows, so the CLI checks every FilterName and
+every `eq`/`neq` dropdown code against the category's columns (one extra request) and
+rejects an unknown one (exit 2, with "did you mean"); a name typed with a decomposed umlaut,
+padding or in another case is sent the register's way. A malformed spec or an unknown
+operator (e.g. `gte`) is rejected too. Several `--filter` flags are joined with `~and~`;
+any other option given twice is a usage error. A **wrong `--sort` key returns 0 rows**:
+sanity-check with `--total`; sort keys are record field names
 (`Bruttoleistung`), not FilterNames — list them with
 `mastr stromerzeugung --page-size 1 --compact | jq '.data[0] | keys'`. **Dates** come as Microsoft
 `/Date(ms)/` strings — add `--iso-dates` to convert them to ISO-8601.
@@ -71,6 +76,11 @@ await mastr.count("stromerzeugung", { filter: "Energieträger~eq~'2495'" }); //
 parseMsDate(String(solar.data[0]?.EinheitRegistrierungsdatum)); // Date | null
 ```
 
+The client checks a filter's FilterNames and dropdown codes against the category's columns
+(`filterColumns()`, fetched once per client and category) and throws `MastrValidationError`
+for one the register would ignore; `new MastrClient({ allowUnknownFilters: true })` skips that
+check and its request. A query key it doesn't know (`filtr`) is refused the same way.
+
 Build filters from user input with `buildFilter`, not string interpolation: a filter
 value cannot contain `~` (the register splits on it and has no escape), so
 `` `Ort~eq~'${input}'` `` lets an input like `Münster'~and~Energieträger~eq~'2497` add a

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, parseSort, renderJson } from "../shared.js";
+import { action, once, 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.
@@ -42,13 +42,15 @@ export function registerCommands(program, deps) {
         program
             .command(cat.name)
             .description(cat.desc)
-            .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("--page <n>", "1-based page number", once("--page", parseBoundedInt(1, MAX_PAGE)), 1)
+            .option("--page-size <n>", `rows per page (1..${MAX_PAGE_SIZE})`, once("--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)`, parseSort)
+            `FilterName (e.g. ${cat.sortKey}-desc)`, once("--sort", 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)
+            "gt/lt strict; null/nn take ''). A malformed spec, an unknown op, a FilterName the " +
+            "category doesn't have or a dropdown code it doesn't list is rejected. Repeatable: " +
+            "several --filter are joined with ~and~. 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 (a one-row request; --page and --page-size are ignored)")
             .action(action(deps, async ({ client, global, opts }) => {
             // `--total` is the library's count(): a one-row request for the match count.
@@ -66,12 +68,12 @@ export function registerCommands(program, deps) {
                     "not the FilterNames from `mastr filters`; list them with " +
                     `\`mastr ${cat.name} --page-size 1 --compact | jq '.data[0] | keys'\`.`);
             }
-            // An unknown operator is already a usage error (filterProblem); what is left
-            // that silently gives 0 rows is a value the register can't match.
+            // An unknown operator, FilterName or dropdown code is already a usage error; what
+            // is left that silently gives 0 rows is a value the register can't match.
             if (page.total === 0 && typeof opts["filter"] === "string") {
-                deps.io.err("Note: 0 results with --filter set. If you expected matches, check the values: a " +
-                    "dropdown takes its code (the Value from `mastr filters`), not its label, decimals " +
-                    "take a point ('4999.999'), and gt/lt are strict.");
+                deps.io.err("Note: 0 results with --filter set. If you expected matches, check the values: eq " +
+                    "on a text column matches the whole text (ct matches a part), decimals take a " +
+                    "point ('4999.999'), and gt/lt are strict.");
             }
             renderJson(deps, global, total ?? page);
         }));

package/dist/src/cli/index.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 // Bin shim: parse argv, run the CLI, and set the process exit code. All real
 // logic lives in run.ts (testable without spawning a subprocess).
+import { handleOutputErrors } from "./io.js";
 import { run } from "./run.js";
+// Before run(): a reader that closes the pipe early (`| head`) must not end in a stack trace.
+handleOutputErrors();
 run(process.argv.slice(2)).then((code) => {
     process.exitCode = code;
 }, (err) => {

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

@@ -8,4 +8,22 @@ export interface CliDeps {
     /** Build a client from the resolved global options (injectable for tests). */
     createClient(options: MastrClientOptions): MastrClient;
 }
+/** The two process streams, as far as `handleOutputErrors` needs them. */
+export interface OutputStreams {
+    stdout: Pick<NodeJS.WriteStream, "on">;
+    stderr: Pick<NodeJS.WriteStream, "on">;
+}
+/**
+ * Handle write errors on stdout/stderr, which Node otherwise reports as an
+ * unhandled 'error' event: a raw stack trace and exit 1.
+ *
+ * A reader that stops early — `| head`, `| jq` exiting on the first match, a closed
+ * pager — closes the pipe while the CLI is still writing, and the next write fails
+ * with EPIPE. That is ordinary use, so the process exits 0 at once, quietly. Any
+ * other stdout error prints one `Output error: <message>` line to stderr and exits
+ * 1. On stderr an EPIPE is ignored, so a failed run keeps its exit code; any other stderr
+ * error exits 1 silently (there is nowhere left to report it).
+ * The bin shim installs this once, before `run()`.
+ */
+export declare function handleOutputErrors(streams?: OutputStreams, exit?: (code: number) => void): void;
 export declare const defaultIO: CliIO;

package/dist/src/cli/io.js

@@ -1,5 +1,31 @@
 // I/O seam for the CLI. Everything the CLI writes goes through a CliIO object so
 // tests can capture output instead of hitting the real stdout/stderr.
+/**
+ * Handle write errors on stdout/stderr, which Node otherwise reports as an
+ * unhandled 'error' event: a raw stack trace and exit 1.
+ *
+ * A reader that stops early — `| head`, `| jq` exiting on the first match, a closed
+ * pager — closes the pipe while the CLI is still writing, and the next write fails
+ * with EPIPE. That is ordinary use, so the process exits 0 at once, quietly. Any
+ * other stdout error prints one `Output error: <message>` line to stderr and exits
+ * 1. On stderr an EPIPE is ignored, so a failed run keeps its exit code; any other stderr
+ * error exits 1 silently (there is nowhere left to report it).
+ * The bin shim installs this once, before `run()`.
+ */
+export function handleOutputErrors(streams = process, exit = (code) => process.exit(code)) {
+    streams.stdout.on("error", (err) => {
+        if (err.code === "EPIPE")
+            return exit(0);
+        process.stderr.write(`Output error: ${err.message}\n`);
+        exit(1);
+    });
+    // stderr's reader going away doesn't make a failed run a success: ignore EPIPE there and
+    // let the run's own exit code stand (`2>&1 | true` must not turn a usage error into 0).
+    streams.stderr.on("error", (err) => {
+        if (err.code !== "EPIPE")
+            exit(1);
+    });
+}
 export const defaultIO = {
     out: (text) => process.stdout.write(text + "\n"),
     err: (text) => process.stderr.write(text + "\n"),

package/dist/src/cli/program.js

@@ -8,7 +8,7 @@ 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 { once, parseIntArg, parseBoundedInt, parseHeaderValue, parseBaseUrl } from "./shared.js";
 import { registerCommands } from "./commands/units.js";
 /**
  * Single source of truth for the version: read from package.json at runtime
@@ -42,11 +42,11 @@ export function buildProgram(deps = defaultDeps) {
         "and narrowed with --filter (see `filters` for the field names and codes). Use " +
         "--total for just the match count, and --iso-dates to convert /Date(…)/ timestamps.")
         .version(VERSION)
-        .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..${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("--base-url <url>", "API base URL (http/https only)", once("--base-url", parseBaseUrl), "https://www.marktstammdatenregister.de/MaStR")
+        .option("--timeout <ms>", "time limit per request in ms, whole response included (0 = no timeout)", once("--timeout", parseBoundedInt(0, MAX_TIMEOUT_MS)))
+        .option("--user-agent <ua>", "User-Agent header value", once("--user-agent", parseHeaderValue))
+        .option("--max-retries <n>", `retries for transient 429/503 responses and reset connections (0..${MAX_RETRIES}; each waits the server's Retry-After, up to 30 s)`, once("--max-retries", parseBoundedInt(0, MAX_RETRIES)))
+        .option("--max-response-bytes <n>", "cap response body size in bytes (0 = unlimited; default 100 MiB)", once("--max-response-bytes", parseIntArg))
         .option("--compact", "print JSON on a single line instead of pretty-printed")
         .option("--iso-dates", "rewrite MaStR /Date(ms)/ timestamps to ISO-8601")
         .showHelpAfterError();

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

@@ -1,2 +1,12 @@
 import type { CliDeps } from "./io.js";
+/**
+ * `deps` with an `io` that redacts the credentials of every argument from everything it
+ * prints. Commander echoes rejected values in its errors (`option '--base-url <url>'
+ * argument '…' is invalid`, an unknown command, a surplus argument), so whatever path a
+ * credential takes to stdout or stderr, the exact userinfo (as `credentialsIn` finds it,
+ * plus its JSON-quoted form) is replaced by `***`. A pattern alone can't delimit a password
+ * with spaces, quotes, `#`, `?` or `/`; the exact strings can. Without credentials the
+ * output passes through unchanged.
+ */
+export declare function withRedactedOutput(deps: CliDeps, argv: readonly string[]): CliDeps;
 export declare function run(argv: string[], deps?: CliDeps): Promise<number>;

package/dist/src/cli/run.js

@@ -3,7 +3,7 @@
 // captured output and exit code without spawning a subprocess.
 import { CommanderError } from "commander";
 import { buildProgram, defaultDeps } from "./program.js";
-import { MastrApiError, MastrError, MastrNetworkError, MastrValidationError, } from "../client/errors.js";
+import { MastrApiError, MastrError, MastrNetworkError, MastrValidationError, credentialsIn, redactCredentials, } from "../client/errors.js";
 /**
  * Process exit codes. Distinct codes let scripts tell apart a usage error, a
  * missing resource, a transport failure, and a catch-all.
@@ -32,7 +32,33 @@ function configureTree(command, deps) {
     for (const child of command.commands)
         configureTree(child, deps);
 }
+/**
+ * `deps` with an `io` that redacts the credentials of every argument from everything it
+ * prints. Commander echoes rejected values in its errors (`option '--base-url <url>'
+ * argument '…' is invalid`, an unknown command, a surplus argument), so whatever path a
+ * credential takes to stdout or stderr, the exact userinfo (as `credentialsIn` finds it,
+ * plus its JSON-quoted form) is replaced by `***`. A pattern alone can't delimit a password
+ * with spaces, quotes, `#`, `?` or `/`; the exact strings can. Without credentials the
+ * output passes through unchanged.
+ */
+export function withRedactedOutput(deps, argv) {
+    // An `--option=value` token is echoed as its value alone.
+    const values = argv.map((token) => token.startsWith("-") && token.includes("=") ? token.slice(token.indexOf("=") + 1) : token);
+    const secrets = new Set();
+    for (const source of [...argv, ...values]) {
+        for (const secret of credentialsIn(source)) {
+            secrets.add(secret);
+            secrets.add(JSON.stringify(secret).slice(1, -1));
+        }
+    }
+    if (secrets.size === 0)
+        return deps;
+    const list = [...secrets];
+    const redact = (text) => redactCredentials(text, list);
+    return { ...deps, io: { out: (text) => deps.io.out(redact(text)), err: (text) => deps.io.err(redact(text)) } };
+}
 export async function run(argv, deps = defaultDeps) {
+    deps = withRedactedOutput(deps, argv);
     const program = buildProgram(deps);
     configureTree(program, deps);
     // A bare invocation (no command) is a help request, not an error: print help

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

@@ -20,9 +20,20 @@ export declare const parseNonEmpty: (value: string) => string;
 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.
+ * misread (see `filterProblem`, run on the `normalizeFilter`ed spec as the client sends
+ * it), so it becomes a usage error before any request. The flag can be repeated: a second
+ * `--filter` is joined to the first with `~and~` (it used to replace it silently, and
+ * "solar in Bavaria" became "every unit in Bavaria"). The FilterNames and dropdown codes
+ * are checked by the client against the category's columns.
  */
-export declare function parseFilter(value: string): string;
+export declare function parseFilter(value: string, previous?: string): string;
+/**
+ * Wrap a value-parser so its option may be given only once: commander keeps the last of a
+ * repeated option and drops the others without a word (`--sort A --sort B` sorted by B,
+ * `--page 2 --page 3` fetched page 3). A repeat is a usage error naming the flag. A fresh
+ * program is built per `run()`, so the state lives as long as one parse.
+ */
+export declare function once<T>(flag: string, parse: (value: string) => T): (value: string) => T;
 /**
  * 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

package/dist/src/cli/shared.js

@@ -3,7 +3,7 @@
 import { InvalidArgumentError } from "commander";
 import { isoifyDates } from "../client/client.js";
 import { MastrParseError } from "../client/errors.js";
-import { filterProblem } from "../client/filter.js";
+import { filterProblem, normalizeFilter } from "../client/filter.js";
 import { isBidiControl } from "../client/engine.js";
 import { baseUrlProblem, headerValueProblem, nonBlankProblem, sortProblem, } from "../client/validate.js";
 /**
@@ -41,14 +41,33 @@ export const parseNonEmpty = parseWith(nonBlankProblem);
 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.
+ * misread (see `filterProblem`, run on the `normalizeFilter`ed spec as the client sends
+ * it), so it becomes a usage error before any request. The flag can be repeated: a second
+ * `--filter` is joined to the first with `~and~` (it used to replace it silently, and
+ * "solar in Bavaria" became "every unit in Bavaria"). The FilterNames and dropdown codes
+ * are checked by the client against the category's columns.
  */
-export function parseFilter(value) {
+export function parseFilter(value, previous) {
     parseNonEmpty(value);
-    const problem = filterProblem(value);
+    const problem = filterProblem(normalizeFilter(value));
     if (problem !== undefined)
         throw new InvalidArgumentError(problem);
-    return value;
+    return previous === undefined ? value : `${previous}~and~${value}`;
+}
+/**
+ * Wrap a value-parser so its option may be given only once: commander keeps the last of a
+ * repeated option and drops the others without a word (`--sort A --sort B` sorted by B,
+ * `--page 2 --page 3` fetched page 3). A repeat is a usage error naming the flag. A fresh
+ * program is built per `run()`, so the state lives as long as one parse.
+ */
+export function once(flag, parse) {
+    let seen = false;
+    return (value) => {
+        if (seen)
+            throw new InvalidArgumentError(`${flag} was given more than once; give it once.`);
+        seen = true;
+        return parse(value);
+    };
 }
 /**
  * commander value-parser for `--base-url`: the library's `baseUrlProblem` (non-blank,

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

@@ -4,8 +4,18 @@ import type { CountQuery, FilterColumn, UnitCategory, UnitPage, UnitQuery } from
 export declare const MAX_PAGE = 1000000;
 /** Largest `pageSize` the client (and the CLI's `--page-size`) accepts. */
 export declare const MAX_PAGE_SIZE = 5000;
-/** Options for the MaStR client (engine options only — the API needs no auth). */
-export type MastrClientOptions = EngineOptions;
+/** Options for the MaStR client: the engine options (the API needs no auth) plus one of its own. */
+export interface MastrClientOptions extends EngineOptions {
+    /**
+     * Send filters without checking their FilterNames and dropdown codes against the
+     * category's columns, and so without the one `filterColumns()` request per category that
+     * check costs. Default `false`: a name the category doesn't have, or a code its dropdown
+     * doesn't list, is a `MastrValidationError`, because the register ignores an unknown name
+     * (the unfiltered set) and answers an unknown code with 0 rows. The shape check and the
+     * name normalisation apply either way.
+     */
+    allowUnknownFilters?: boolean;
+}
 /**
  * Parse a MaStR Microsoft-AJAX date string (`"/Date(1548979200000)/"`) into a Date.
  * The offset form `"/Date(1548979200000+0100)/"` is accepted too; its milliseconds
@@ -19,18 +29,38 @@ export declare function parseMsDate(value: string): Date | null;
  */
 export declare function isoifyDates<T>(value: T): T;
 export declare class MastrClient {
+    #private;
     private readonly engine;
     constructor(options?: MastrClientOptions);
+    /** The category's filter columns, fetched on first use and kept; a failed fetch is not kept. */
+    private columnsOf;
+    /**
+     * The filter as it is sent: FilterNames normalised (`normalizeFilter`), the shape checked
+     * (`filterProblem`), then — unless `allowUnknownFilters` — the names and dropdown codes
+     * checked against the category's columns (`resolveFilter`, one cached `filterColumns()`
+     * request), all before the unit request.
+     */
+    private checkedFilter;
     /**
      * 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.
+     * An unknown category or query key, 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. A filter's FilterNames and `eq`/`neq`
+     * dropdown codes are then checked against the category's columns (one cached
+     * `filterColumns()` request, skipped with `allowUnknownFilters`) before the unit request;
+     * the filter is sent normalised (see `normalizeFilter`, `resolveFilter`).
      */
     units(category: UnitCategory, query?: UnitQuery): Promise<UnitPage>;
+    /**
+     * The register's second error envelope, `{"Error":true,"Message":…,"Type":"danger"}`
+     * (HTTP 200), as a MastrApiError: its answer to a filter value it can't read. It used to
+     * surface as "Unexpected response shape … expected a numeric Total", which reads like a
+     * broken server or client and doesn't say what to fix.
+     */
+    private registerRejected;
     /**
      * 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

package/dist/src/client/client.js

@@ -9,10 +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, describeMastrErrors } from "./engine.js";
+import { RequestEngine, describeMastrErrors, optionsObject } from "./engine.js";
 import { MastrApiError, MastrParseError, MastrValidationError } from "./errors.js";
-import { validateFilter } from "./filter.js";
-import { assertValid, countQueryProblem, sortProblem } from "./validate.js";
+import { normalizeFilter, resolveFilter, validateFilter } from "./filter.js";
+import { COUNT_IGNORED_KEYS, 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 = {
@@ -42,6 +42,43 @@ function checkPaging(name, value, max) {
         throw new MastrValidationError(`Invalid ${name}: expected an integer from 1 to ${max}, got ${typeof value === "string" ? JSON.stringify(value) : String(value)}.`);
     }
 }
+/** A query as given (null counts as none), or a MastrValidationError for a non-object. */
+function queryObject(query) {
+    if (query === undefined || query === null)
+        return {};
+    if (typeof query !== "object" || Array.isArray(query)) {
+        throw new MastrValidationError(`Invalid query: expected an object, got ${Array.isArray(query) ? "an array" : `a ${typeof query}`}.`);
+    }
+    return query;
+}
+/** The UnitQuery keys; any other key is refused (a misspelled `filtr` was ignored: the unfiltered set). */
+const UNIT_QUERY_KEYS = ["page", "pageSize", "sort", "filter"];
+/** The CountQuery keys (`page`/`pageSize` get their own message, see countQueryProblem). */
+const COUNT_QUERY_KEYS = ["sort", "filter", ...COUNT_IGNORED_KEYS];
+/**
+ * Throw for a query key that isn't one of `allowed`. A JavaScript caller's typo (`filtr`,
+ * `Filter`) or a key from parsed JSON (`__proto__`) was ignored silently, and the call
+ * answered with the whole unfiltered register.
+ */
+function assertQueryKeys(query, allowed) {
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || allowed.includes(key))
+            continue;
+        const lower = key.toLowerCase();
+        const hint = allowed.find((name) => name.toLowerCase() === lower || editHint(lower, name.toLowerCase()));
+        throw new MastrValidationError(`Invalid query: unknown key ${JSON.stringify(key)}` +
+            (hint === undefined ? `; the keys are ${allowed.join(", ")}.` : ` (did you mean ${hint}?).`));
+    }
+}
+/** True when `a` and `b` differ by one inserted, dropped or changed character. */
+function editHint(a, b) {
+    if (Math.abs(a.length - b.length) > 1)
+        return false;
+    let i = 0;
+    while (i < a.length && a[i] === b[i])
+        i++;
+    return a.slice(i + 1) === b.slice(i + 1) || a.slice(i + 1) === b.slice(i) || a.slice(i) === b.slice(i + 1);
+}
 /**
  * Parse a MaStR Microsoft-AJAX date string (`"/Date(1548979200000)/"`) into a Date.
  * The offset form `"/Date(1548979200000+0100)/"` is accepted too; its milliseconds
@@ -91,32 +128,69 @@ function shapeError(path, expected) {
 }
 export class MastrClient {
     engine;
+    #allowUnknownFilters;
+    /** Each category's filter columns, fetched once per client for the filter check. */
+    #columns = new Map();
     constructor(options = {}) {
-        this.engine = new RequestEngine(options);
+        const { allowUnknownFilters, ...engineOptions } = optionsObject(options);
+        if (allowUnknownFilters !== undefined && typeof allowUnknownFilters !== "boolean") {
+            throw new MastrValidationError(`Invalid allowUnknownFilters: expected a boolean, got ${typeof allowUnknownFilters}.`);
+        }
+        this.engine = new RequestEngine(engineOptions);
+        this.#allowUnknownFilters = allowUnknownFilters === true;
+    }
+    /** The category's filter columns, fetched on first use and kept; a failed fetch is not kept. */
+    columnsOf(category) {
+        let columns = this.#columns.get(category);
+        if (columns === undefined) {
+            columns = this.filterColumns(category);
+            this.#columns.set(category, columns);
+            columns.catch(() => this.#columns.delete(category));
+        }
+        return columns;
+    }
+    /**
+     * The filter as it is sent: FilterNames normalised (`normalizeFilter`), the shape checked
+     * (`filterProblem`), then — unless `allowUnknownFilters` — the names and dropdown codes
+     * checked against the category's columns (`resolveFilter`, one cached `filterColumns()`
+     * request), all before the unit request.
+     */
+    async checkedFilter(category, spec) {
+        const filter = normalizeFilter(spec);
+        validateFilter(filter);
+        if (this.#allowUnknownFilters)
+            return filter;
+        return resolveFilter(filter, await this.columnsOf(category), category);
     }
     /**
      * 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.
+     * An unknown category or query key, 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. A filter's FilterNames and `eq`/`neq`
+     * dropdown codes are then checked against the category's columns (one cached
+     * `filterColumns()` request, skipped with `allowUnknownFilters`) before the unit request;
+     * the filter is sent normalised (see `normalizeFilter`, `resolveFilter`).
      */
     async units(category, query = {}) {
         const suffix = categorySuffix(category);
+        query = queryObject(query);
+        assertQueryKeys(query, UNIT_QUERY_KEYS);
         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);
+        // The register ignores a FilterName it doesn't match exactly and answers with the
+        // unfiltered set, so the filter is normalised and checked first (checkedFilter).
+        const filter = query.filter === undefined ? undefined : await this.checkedFilter(category, query.filter);
         const params = {
             sort: query.sort ?? "",
             page: query.page ?? DEFAULT_PAGE,
             pageSize: query.pageSize ?? DEFAULT_PAGE_SIZE,
             group: "",
-            filter: query.filter ?? "",
+            filter: filter ?? "",
         };
         const path = `${SERVICE}/GetErweiterteOeffentlicheEinheit${suffix}`;
         const res = await this.engine.getJson(path, params);
@@ -130,10 +204,12 @@ export class MastrClient {
             throw new MastrApiError({
                 url: this.engine.buildUrl(path, params),
                 method: "GET",
-                body: JSON.stringify(res),
-                detail: describeMastrErrors(res["Errors"]),
+                body: this.engine.scrub(JSON.stringify(res)),
+                detail: describeMastrErrors(res["Errors"], (text) => this.engine.scrub(text)),
             });
         }
+        if (res["Error"] === true)
+            throw this.registerRejected(path, params, res);
         const total = res["Total"];
         if (typeof total !== "number" || !Number.isSafeInteger(total) || total < 0) {
             throw shapeError(path, "a numeric Total");
@@ -144,8 +220,37 @@ export class MastrClient {
             return { total, data: [] };
         if (!Array.isArray(data))
             throw shapeError(path, "a Data array");
+        // A page can't hold more rows than match, nor more than were asked for: such a reply
+        // would print rows next to `"total": 0` (and the CLI's "0 results" note), or a page
+        // larger than --page-size.
+        if (data.length > total) {
+            throw shapeError(path, `a Total of at least the ${data.length} rows on the page, got ${total}`);
+        }
+        const pageSize = query.pageSize ?? DEFAULT_PAGE_SIZE;
+        if (data.length > pageSize) {
+            throw shapeError(path, `at most ${pageSize} rows (the pageSize), got ${data.length}`);
+        }
         return { total, data: data };
     }
+    /**
+     * The register's second error envelope, `{"Error":true,"Message":…,"Type":"danger"}`
+     * (HTTP 200), as a MastrApiError: its answer to a filter value it can't read. It used to
+     * surface as "Unexpected response shape … expected a numeric Total", which reads like a
+     * broken server or client and doesn't say what to fix.
+     */
+    registerRejected(path, query, res) {
+        const message = typeof res["Message"] === "string" ? describeMastrErrors(res["Message"], (t) => this.engine.scrub(t)) : undefined;
+        return new MastrApiError({
+            url: this.engine.buildUrl(path, query),
+            method: "GET",
+            body: this.engine.scrub(JSON.stringify(res)),
+            detail: `the register rejected the request${message === undefined ? "" : ` (${message})`}. It answers so ` +
+                "to a filter value it can't read: a dropdown label instead of its code (the Value from " +
+                "`mastr filters` / filterColumns()), a decimal comma ('4999,999'; use a point), an exponent " +
+                "or text in a number column, an invalid date, a boolean other than '1'/'0', or null/nn on a " +
+                "column that isn't text",
+        });
+    }
     /**
      * 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
@@ -155,6 +260,8 @@ export class MastrClient {
      * `MastrValidationError` before any request.
      */
     async count(category, query = {}) {
+        query = queryObject(query);
+        assertQueryKeys(query, COUNT_QUERY_KEYS);
         assertValid("count query", query, countQueryProblem);
         const q = { page: 1, pageSize: 1 };
         if (query.sort !== undefined)
@@ -187,12 +294,14 @@ export class MastrClient {
     async filterColumns(category) {
         const path = `${SERVICE}/GetFilterColumnsErweiterteOeffentlicheEinheit${categorySuffix(category)}`;
         const res = await this.engine.getJson(path);
+        if (isObject(res) && res["Error"] === true)
+            throw this.registerRejected(path, undefined, 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"]),
+                body: this.engine.scrub(JSON.stringify(res)),
+                detail: describeMastrErrors(res["Errors"], (text) => this.engine.scrub(text)),
             });
         }
         if (!Array.isArray(res) || !res.every(isObject)) {