@maschinenlesbar.org/marktstammdatenregister-cli 0.0.7 → 0.1.0

package/README.md

@@ -42,11 +42,15 @@ mastr filters stromerzeugung                        # the filterable columns + d
 
 Categories: `stromerzeugung`, `stromverbrauch`, `gaserzeugung`, `gasverbrauch`.
 
-**Filtering** uses the register's own syntax — `FilterName~op~'value'~[and|or]~…`
+**Filtering** uses the register's own syntax — `FilterName~op~'value'~and~…`
 (ops `eq|neq|sw|ct|nct|ew|null|nn`, plus the strict `gt`/`lt` for numbers and dates);
-discover the German field names and dropdown codes with `mastr filters <category>`. A
-**wrong `FilterName` is silently ignored** (you get the unfiltered set), while a **wrong
-operator** (e.g. `gte`) or a **wrong `--sort` key returns 0 rows**. Verify filter names
+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
 (`Bruttoleistung`), not FilterNames — list them with
 `mastr stromerzeugung --page-size 1 --compact | jq '.data[0] | keys'`. **Dates** come as Microsoft
@@ -63,9 +67,25 @@ 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
 ```
 
+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
+condition. `buildFilter` quotes each value and throws `MastrValidationError` for a `~`:
+
+```ts
+import { buildFilter } from "@maschinenlesbar.org/marktstammdatenregister-cli";
+
+const filter = buildFilter([
+  { name: "Ort", op: "eq", value: town },                        // quoted, ~ refused
+  { name: "Energieträger", op: "eq", value: ["2497", "2498"] },  // comma list = any of
+]);
+await mastr.stromerzeugung({ filter, pageSize: 1 });
+```
+
 ## Documentation
 
 - [Usage.md](Usage.md) — commands, filter syntax, exit codes

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

@@ -2,12 +2,16 @@
 // gas × generation / consumption), each a paged, optionally-filtered search, plus a
 // `filters` command to discover the filterable columns and their dropdown codes.
 import { Argument } from "commander";
-import { action, parseBoundedInt, parseNonEmpty, renderJson } from "../shared.js";
+import { MAX_PAGE, MAX_PAGE_SIZE } from "../../client/client.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.
 const CATEGORIES = [
-    { name: "stromerzeugung", desc: "Electricity-generation units (Stromerzeugung)" },
-    { name: "stromverbrauch", desc: "Electricity-consumption units (Stromverbrauch)" },
-    { name: "gaserzeugung", desc: "Gas-generation units (Gaserzeugung)" },
-    { name: "gasverbrauch", desc: "Gas-consumption units (Gasverbrauch)" },
+    { name: "stromerzeugung", desc: "Electricity-generation units (Stromerzeugung)", sortKey: "Bruttoleistung" },
+    { name: "stromverbrauch", desc: "Electricity-consumption units (Stromverbrauch)", sortKey: "InbetriebnahmeDatum" },
+    { name: "gaserzeugung", desc: "Gas-generation units (Gaserzeugung)", sortKey: "Erzeugungsleistung" },
+    { name: "gasverbrauch", desc: "Gas-consumption units (Gasverbrauch)", sortKey: "MaximaleGasbezugsLeistung" },
 ];
 const RUN = {
     stromerzeugung: (c, q) => c.stromerzeugung(q),
@@ -15,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) {
@@ -37,31 +42,38 @@ export function registerCommands(program, deps) {
         program
             .command(cat.name)
             .description(cat.desc)
-            .option("--page <n>", "1-based page number", parseBoundedInt(1, 1_000_000), 1)
-            .option("--page-size <n>", "rows per page (1..5000)", parseBoundedInt(1, 5000), 25)
+            .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. Bruttoleistung-desc)", parseNonEmpty)
-            .option("--filter <spec>", "filter: FilterName~op~'value'~[and|or]~… (see `filters`; ops eq|neq|sw|ct|nct|ew|null|nn|gt|lt, " +
-            "gt/lt strict; an unknown op returns 0 rows)", parseNonEmpty)
-            .option("--total", "print only the total match count, not the rows")
+            `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 (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`);
             // the FilterNames from `mastr filters` ("Bruttoleistung der Einheit") don't sort.
             if (page.total === 0 && typeof opts["sort"] === "string") {
                 deps.io.err("Note: 0 results with --sort set. If you expected matches, an unknown sort " +
-                    "key returns 0 rows. Sort keys are record field names (e.g. Bruttoleistung), " +
+                    `key returns 0 rows. Sort keys are record field names (e.g. ${cat.sortKey}), ` +
                     "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.
             if (page.total === 0 && typeof opts["filter"] === "string") {
-                deps.io.err("Note: 0 results with --filter set. If you expected matches, check the operators: " +
-                    "the known ones are eq, neq, sw, ct, nct, ew, null, nn, gt and lt; an unknown " +
-                    "operator (e.g. gte) returns 0 rows.");
+                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.");
             }
-            renderJson(deps, global, opts["total"] === true ? page.total : page);
+            renderJson(deps, global, total ?? page);
         }));
     }
     program
@@ -72,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)", 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,27 +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;
 /**
- * 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.
+ * 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`: 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;
@@ -41,9 +51,10 @@ export interface GlobalOptions {
 /** Translate resolved global CLI options into client options. */
 export declare function toEngineOptions(global: GlobalOptions): MastrClientOptions;
 /**
- * Escape the control characters JSON.stringify leaves raw. It escapes C0 (including
- * ESC) but not DEL or the C1 range U+0080–U+009F, and terminals may act on those —
- * U+009B is the 8-bit form of CSI. The output is server data, so escape them; the
+ * Escape the characters JSON.stringify leaves raw although a terminal acts on them.
+ * It escapes C0 (including ESC) but not DEL, the C1 range U+0080–U+009F (U+009B is
+ * the 8-bit form of CSI) or the bidi formatting characters (isBidiControl), which
+ * reorder the text that follows. The output is server data, so escape them; the
  * result is equivalent, valid JSON (these characters only occur inside strings).
  * Checked by char code so the source stays free of control bytes.
  */
@@ -68,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

@@ -3,6 +3,9 @@
 import { InvalidArgumentError } from "commander";
 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.
  *
@@ -20,39 +23,40 @@ 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 `--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 `--filter`: non-blank, and not a spec the register would
+ * misread (see `filterProblem`), so it becomes a usage error before any request.
  */
-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.");
-    }
+export function parseFilter(value) {
+    parseNonEmpty(value);
+    const problem = filterProblem(value);
+    if (problem !== undefined)
+        throw new InvalidArgumentError(problem);
     return value;
 }
+/**
+ * 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 const parseBaseUrl = parseWith(baseUrlProblem);
 /** Build a commander value-parser for an integer constrained to [min, max]. */
 export function parseBoundedInt(min, max) {
     return (value) => {
@@ -65,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 = {};
@@ -95,9 +91,10 @@ export function toEngineOptions(global) {
     return options;
 }
 /**
- * Escape the control characters JSON.stringify leaves raw. It escapes C0 (including
- * ESC) but not DEL or the C1 range U+0080–U+009F, and terminals may act on those —
- * U+009B is the 8-bit form of CSI. The output is server data, so escape them; the
+ * Escape the characters JSON.stringify leaves raw although a terminal acts on them.
+ * It escapes C0 (including ESC) but not DEL, the C1 range U+0080–U+009F (U+009B is
+ * the 8-bit form of CSI) or the bidi formatting characters (isBidiControl), which
+ * reorder the text that follows. The output is server data, so escape them; the
  * result is equivalent, valid JSON (these characters only occur inside strings).
  * Checked by char code so the source stays free of control bytes.
  */
@@ -106,7 +103,7 @@ export function escapeControlChars(json) {
     let from = 0;
     for (let i = 0; i < json.length; i++) {
         const c = json.charCodeAt(i);
-        if (c >= 0x7f && c <= 0x9f) {
+        if ((c >= 0x7f && c <= 0x9f) || isBidiControl(c)) {
             result += json.slice(from, i) + "\\u" + c.toString(16).padStart(4, "0");
             from = i + 1;
         }
@@ -152,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,10 +1,16 @@
 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. */
+export declare const MAX_PAGE_SIZE = 5000;
 /** Options for the MaStR client (engine options only — the API needs no auth). */
 export type MastrClientOptions = EngineOptions;
 /**
  * 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 declare function parseMsDate(value: string): Date | null;
 /**
@@ -19,8 +25,21 @@ export declare 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.
      */
     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`). */
@@ -29,7 +48,10 @@ export declare class MastrClient {
     gaserzeugung(query?: UnitQuery): Promise<UnitPage>;
     /** Gas-consumption units (`Gasverbrauch`). */
     gasverbrauch(query?: UnitQuery): Promise<UnitPage>;
-    /** 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".
+     */
     filterColumns(category: UnitCategory): Promise<FilterColumn[]>;
 }
-//# sourceMappingURL=client.d.ts.map