@maschinenlesbar.org/marktstammdatenregister-cli 0.0.1

package/LICENSING.md

@@ -0,0 +1,47 @@
+# Licensing
+
+`marktstammdatenregister-cli` is **dual-licensed**. You may use it under **either** of the
+following, at your choice:
+
+## 1. Open source — AGPL-3.0-or-later (default)
+
+Free to use, modify, and distribute under the
+[GNU Affero General Public License v3.0 or later](LICENSE).
+
+The key obligation is the AGPL's **§13 network clause**: if you run a modified
+version of this software to provide a service to others over a network, you must
+make the complete corresponding source code of your modified version available
+to the users of that service. The usual copyleft terms also apply when you
+distribute the software or works based on it.
+
+This is the right option for open-source projects, internal and personal use,
+evaluation, and anyone able to comply with the AGPL.
+
+## 2. Commercial license
+
+If the AGPL's obligations do not fit your situation — for example, you want to:
+
+- embed `marktstammdatenregister-cli` in a **closed-source / proprietary product**, or
+- run a **modified version as a proprietary network service (SaaS)** without
+  disclosing your source, or
+- keep your modifications private,
+
+then a separate **commercial license** is available. It grants use of the same
+code without the AGPL's copyleft and network-disclosure obligations, under
+negotiated terms.
+
+**To obtain a commercial license, contact:** sebs@2xs.org
+
+## Why this is possible
+
+The copyright holder owns 100% of the source code in this repository and can
+therefore offer it under more than one license simultaneously. This project does
+**not** accept external code contributions (see [CONTRIBUTING.md](CONTRIBUTING.md)),
+which keeps copyright ownership single and unambiguous — a prerequisite for
+offering the commercial option. The only third-party dependency that ships with
+the package, [`commander`](https://github.com/tj/commander.js), is MIT-licensed
+and compatible with both licensing options.
+
+---
+
+Copyright © 2026 Sebastian Schürmann. All rights reserved.

package/README.md

@@ -0,0 +1,72 @@
+# marktstammdatenregister-cli
+
+A dependency-light **TypeScript client + CLI** for the **Marktstammdatenregister
+(MaStR)** — the Bundesnetzagentur's register of the German electricity & gas market:
+~9 million generation and consumption units (solar, wind, storage, CHP, …). Wraps
+the public "erweiterte öffentliche Einheitensuche". A [bund.dev](https://bund.dev) API.
+
+- **No API key.** The public search is open.
+- **Zero runtime HTTP dependencies.** Built on `node:http`/`https`; the CLI's only
+  runtime dependency is `commander`.
+- **Library + CLI.** Use the typed `MastrClient`, or the `mastr` command.
+
+> **We provide the tool, not the data.** MaStR data is © the Bundesnetzagentur under
+> **DL-DE-BY-2.0** — free to use with attribution. See [DATA_LICENSE.md](DATA_LICENSE.md).
+
+## Install
+
+```bash
+npm install -g @maschinenlesbar.org/marktstammdatenregister-cli   # the `mastr` command
+# or as a library:
+npm install @maschinenlesbar.org/marktstammdatenregister-cli
+```
+
+## 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 --sort "Bruttoleistung-desc" --page-size 20 --iso-dates
+mastr gaserzeugung --page 1 --page-size 50
+mastr filters stromerzeugung                        # the filterable columns + dropdown codes
+```
+
+Categories: `stromerzeugung`, `stromverbrauch`, `gaserzeugung`, `gasverbrauch`.
+
+**Filtering** uses the register's own syntax — `FilterName~op~'value'~[and|or]~…`
+(ops `eq|neq|sw|ct|nct|ew|null|nn`); 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` field returns 0 rows** — verify
+with `mastr filters` and sanity-check with `--total`. **Dates** come as Microsoft
+`/Date(ms)/` strings — add `--iso-dates` to convert them to ISO-8601.
+
+Global flags: `--base-url`, `--timeout`, `--user-agent`, `--max-retries`,
+`--max-response-bytes`, `--compact`, `--iso-dates`. See [Usage.md](Usage.md).
+
+## Library
+
+```ts
+import { MastrClient, parseMsDate } from "@maschinenlesbar.org/marktstammdatenregister-cli";
+
+const mastr = new MastrClient();
+const solar = await mastr.stromerzeugung({ filter: "Energieträger~eq~'2495'", pageSize: 10 });
+solar.total; // total matching units
+parseMsDate(String(solar.data[0]?.EinheitRegistrierungsdatum)); // Date | null
+```
+
+## Documentation
+
+- [Usage.md](Usage.md) — commands, filter syntax, exit codes
+- [DEVELOPING.md](DEVELOPING.md) — architecture, testing, the live-API quirks
+- [GLOSSARY.md](GLOSSARY.md) — MaStR domain terms
+- [DATA_LICENSE.md](DATA_LICENSE.md) — the DL-DE-BY-2.0 data terms
+- [SKILLS.md](SKILLS.md) — the Claude Code skills this repo ships
+
+## Licence
+
+Code is dual-licensed **AGPL-3.0-or-later OR commercial** — see
+[LICENSING.md](LICENSING.md). No external code contributions are accepted (see
+[CONTRIBUTING.md](CONTRIBUTING.md)); bug reports and AGPL forks are welcome.

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

@@ -0,0 +1,4 @@
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/units.ts"],"names":[],"mappings":"AAIA,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAgCxC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAyCtE"}

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

@@ -0,0 +1,64 @@
+// Command group for the MaStR CLI: one command per unit category (electricity /
+// 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";
+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)" },
+];
+const RUN = {
+    stromerzeugung: (c, q) => c.stromerzeugung(q),
+    stromverbrauch: (c, q) => c.stromverbrauch(q),
+    gaserzeugung: (c, q) => c.gaserzeugung(q),
+    gasverbrauch: (c, q) => c.gasverbrauch(q),
+};
+/** Build a UnitQuery from this command's parsed options. */
+function buildQuery(opts) {
+    const q = {};
+    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) {
+    for (const cat of CATEGORIES) {
+        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("--sort <spec>", "sort: FieldKey-asc | FieldKey-desc (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)", parseNonEmpty)
+            .option("--total", "print only the total match count, not the rows")
+            .action(action(deps, async ({ client, global, opts }) => {
+            const page = await RUN[cat.name](client, buildQuery(opts));
+            // An unknown --sort field makes the server return 0 rows (not an error),
+            // which reads like "no matches". Nudge the user toward the likely cause.
+            if (page.total === 0 && typeof opts["sort"] === "string") {
+                deps.io.err("Note: 0 results with --sort set. If you expected matches, an unknown sort " +
+                    "field returns 0 rows — verify the sort column key (see `mastr filters`).");
+            }
+            renderJson(deps, global, opts["total"] === true ? page.total : page);
+        }));
+    }
+    program
+        .command("filters")
+        .description("List the filterable columns (names, types, dropdown codes) for a category")
+        .addArgument(new Argument("<category>", "unit category").choices(CATEGORIES.map((c) => c.name)))
+        .action(action(deps, async ({ client, global }, [category]) => {
+        renderJson(deps, global, await client.filterColumns(category));
+    }));
+}
+//# sourceMappingURL=units.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"units.js","sourceRoot":"","sources":["../../../../src/cli/commands/units.ts"],"names":[],"mappings":"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"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":""}

package/dist/src/cli/index.js

@@ -0,0 +1,11 @@
+#!/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 { run } from "./run.js";
+run(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map

package/dist/src/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AACA,6EAA6E;AAC7E,kEAAkE;AAElE,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC7B,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,CAAC,GAAY,EAAE,EAAE;IACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChG,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC"}

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

@@ -0,0 +1,12 @@
+import type { MastrClient, MastrClientOptions } from "../client/client.js";
+export interface CliIO {
+    out(text: string): void;
+    err(text: string): void;
+}
+export interface CliDeps {
+    io: CliIO;
+    /** Build a client from the resolved global options (injectable for tests). */
+    createClient(options: MastrClientOptions): MastrClient;
+}
+export declare const defaultIO: CliIO;
+//# sourceMappingURL=io.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../../src/cli/io.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE3E,MAAM,WAAW,KAAK;IACpB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,KAAK,CAAC;IACV,8EAA8E;IAC9E,YAAY,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAAC;CACxD;AAED,eAAO,MAAM,SAAS,EAAE,KAGvB,CAAC"}

package/dist/src/cli/io.js

@@ -0,0 +1,7 @@
+// 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.
+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/io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.js","sourceRoot":"","sources":["../../../src/cli/io.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,sEAAsE;AAetE,MAAM,CAAC,MAAM,SAAS,GAAU;IAC9B,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;IAChD,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;CACjD,CAAC"}

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

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+import type { CliDeps } from "./io.js";
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../../../src/cli/program.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAsBvC,eAAO,MAAM,OAAO,QAAgB,CAAC;AAErC,8DAA8D;AAC9D,eAAO,MAAM,WAAW,EAAE,OAGzB,CAAC;AAEF,wBAAgB,YAAY,CAAC,IAAI,GAAE,OAAqB,GAAG,OAAO,CAkCjE"}

package/dist/src/cli/program.js

@@ -0,0 +1,54 @@
+// Assemble the full commander program. The program is built around an injectable
+// CliDeps so the entire CLI can be driven in tests with a mocked client and
+// captured output.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { defaultIO } from "./io.js";
+import { MastrClient } from "../client/client.js";
+import { parseIntArg, parseBoundedInt, parseHeaderValue, parseNonEmpty } from "./shared.js";
+import { registerCommands } from "./commands/units.js";
+/**
+ * Single source of truth for the version: read from package.json at runtime
+ * rather than duplicating a literal that can silently drift after a release bump.
+ * From the compiled location (dist/src/cli/program.js) package.json is three
+ * directories up; the same offset holds for the source under src/cli.
+ */
+function readVersion() {
+    try {
+        const pkgUrl = new URL("../../../package.json", import.meta.url);
+        const pkg = JSON.parse(readFileSync(fileURLToPath(pkgUrl), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export const VERSION = readVersion();
+/** Default dependencies: real client + real stdout/stderr. */
+export const defaultDeps = {
+    io: defaultIO,
+    createClient: (options) => new MastrClient(options),
+};
+export function buildProgram(deps = defaultDeps) {
+    const program = new Command();
+    program
+        .name("mastr")
+        .description("CLI for the Marktstammdatenregister (MaStR) — the Bundesnetzagentur's register " +
+        "of the German electricity & gas market (~9M generation/consumption units). No " +
+        "API key needed. Each command searches one dataset, paged with --page/--page-size " +
+        "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", parseNonEmpty, "https://www.marktstammdatenregister.de/MaStR")
+        .option("--timeout <ms>", "per-request timeout in ms (0 = no timeout)", parseIntArg)
+        .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-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")
+        .showHelpAfterError();
+    registerCommands(program, deps);
+    return program;
+}
+//# sourceMappingURL=program.js.map

package/dist/src/cli/program.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.js","sourceRoot":"","sources":["../../../src/cli/program.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,4EAA4E;AAC5E,mBAAmB;AAEnB,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;GAKG;AACH,SAAS,WAAW;IAClB,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,uBAAuB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAyB,CAAC;QAC5F,OAAO,GAAG,CAAC,OAAO,IAAI,OAAO,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,OAAO,CAAC;IACjB,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC;AAErC,8DAA8D;AAC9D,MAAM,CAAC,MAAM,WAAW,GAAY;IAClC,EAAE,EAAE,SAAS;IACb,YAAY,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,WAAW,CAAC,OAAO,CAAC;CACpD,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,OAAgB,WAAW;IACtD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,OAAO,CAAC;SACb,WAAW,CACV,iFAAiF;QAC/E,gFAAgF;QAChF,mFAAmF;QACnF,gFAAgF;QAChF,oFAAoF,CACvF;SACA,OAAO,CAAC,OAAO,CAAC;SAChB,MAAM,CACL,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,8CAA8C,CAC/C;SACA,MAAM,CAAC,gBAAgB,EAAE,4CAA4C,EAAE,WAAW,CAAC;SACnF,MAAM,CAAC,mBAAmB,EAAE,yBAAyB,EAAE,gBAAgB,CAAC;SACxE,MAAM,CAAC,mBAAmB,EAAE,iDAAiD,EAAE,eAAe,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;SACtG,MAAM,CACL,0BAA0B,EAC1B,kEAAkE,EAClE,WAAW,CACZ;SACA,MAAM,CAAC,WAAW,EAAE,uDAAuD,CAAC;SAC5E,MAAM,CAAC,aAAa,EAAE,iDAAiD,CAAC;SACxE,kBAAkB,EAAE,CAAC;IAExB,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAEhC,OAAO,OAAO,CAAC;AACjB,CAAC"}

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

@@ -0,0 +1,3 @@
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/cli/run.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAqCvC,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,OAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAkDtF"}

package/dist/src/cli/run.js

@@ -0,0 +1,85 @@
+// Run the CLI and resolve to a process exit code. Kept separate from the bin
+// shim so tests can call run() directly with injected deps and assert on the
+// 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";
+/**
+ * Process exit codes. Distinct codes let scripts tell apart a usage error, a
+ * missing resource, a transport failure, and a catch-all.
+ */
+const EXIT = {
+    /** Usage / parse / client-side validation error. */
+    USAGE: 2,
+    /** HTTP 404 — resource not found. */
+    NOT_FOUND: 4,
+    /** Network / transport failure (DNS, connection, timeout, size-cap). */
+    NETWORK: 6,
+    /** Any other error. */
+    OTHER: 1,
+};
+/**
+ * Apply exitOverride + output redirection to every command in the tree.
+ * commander does not propagate these to subcommands, so a parse error on a
+ * subcommand would otherwise call process.exit() and bypass our error handling.
+ */
+function configureTree(command, deps) {
+    command.exitOverride();
+    command.configureOutput({
+        writeOut: (str) => deps.io.out(str.replace(/\n$/, "")),
+        writeErr: (str) => deps.io.err(str.replace(/\n$/, "")),
+    });
+    for (const child of command.commands)
+        configureTree(child, deps);
+}
+export async function run(argv, deps = defaultDeps) {
+    const program = buildProgram(deps);
+    configureTree(program, deps);
+    // A bare invocation (no command) is a help request, not an error: print help
+    // to stdout and exit 0, matching `--help`.
+    if (argv.length === 0) {
+        deps.io.out(program.helpInformation().replace(/\n$/, ""));
+        return 0;
+    }
+    try {
+        await program.parseAsync(argv, { from: "user" });
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            // Help/version requests exit 0; every genuine usage/parse error maps to a
+            // single USAGE code (commander's own exitCode is 1, indistinguishable from
+            // the catch-all).
+            return err.exitCode === 0 ? 0 : EXIT.USAGE;
+        }
+        if (err instanceof MastrValidationError) {
+            deps.io.err(`Error: ${err.message}`);
+            return EXIT.USAGE;
+        }
+        if (err instanceof MastrApiError) {
+            deps.io.err(`Error: ${err.message}`);
+            if (err.status === 404)
+                return EXIT.NOT_FOUND;
+            // A 3xx means the base URL redirected (the canonical host answers directly),
+            // so it is a base-URL misconfiguration — a usage error.
+            if (err.status !== undefined && err.status >= 300 && err.status < 400)
+                return EXIT.USAGE;
+            return EXIT.OTHER;
+        }
+        if (err instanceof MastrNetworkError) {
+            deps.io.err(`Error: ${err.message}`);
+            if (/maxResponseBytes/.test(err.message)) {
+                deps.io.err("Hint: the response exceeded the size cap. Lower --page-size or raise " +
+                    "--max-response-bytes <n> (0 = unlimited).");
+            }
+            return EXIT.NETWORK;
+        }
+        if (err instanceof MastrError) {
+            deps.io.err(`Error: ${err.message}`);
+            return EXIT.OTHER;
+        }
+        deps.io.err(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+        return EXIT.OTHER;
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/src/cli/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/cli/run.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,53 @@
+import type { CliDeps } from "./io.js";
+import type { MastrClientOptions } from "../client/client.js";
+/**
+ * commander value-parser: a plain base-10 non-negative integer.
+ *
+ * Uses a strict regex rather than `Number()` coercion, which would otherwise
+ * accept empty/whitespace strings (`Number("") === 0`), hex/binary/scientific
+ * literals (`0x10`, `0b10`, `1e3`), signs, padding and decimals.
+ */
+export declare function parseIntArg(value: string): number;
+/** commander value-parser: a non-empty (after trimming) string. */
+export declare function parseNonEmpty(value: string): string;
+/** Build a commander value-parser 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.
+ */
+export declare function parseHeaderValue(value: string): string;
+export interface GlobalOptions {
+    baseUrl?: string;
+    timeout?: number;
+    userAgent?: string;
+    maxRetries?: number;
+    maxResponseBytes?: number;
+    compact?: boolean;
+    isoDates?: boolean;
+}
+/** Translate resolved global CLI options into client options. */
+export declare function toEngineOptions(global: GlobalOptions): MastrClientOptions;
+/**
+ * Render a JSON value to stdout, pretty by default and compact with --compact.
+ * With --iso-dates, every MaStR `"/Date(ms)/"` string is rewritten to ISO-8601 first.
+ */
+export declare function renderJson(deps: CliDeps, global: GlobalOptions, value: unknown): void;
+export interface ActionContext {
+    client: ReturnType<CliDeps["createClient"]>;
+    global: GlobalOptions;
+    /** This command's own parsed options. */
+    opts: Record<string, unknown>;
+}
+/**
+ * Wrap an async command action with consistent global-option resolution and
+ * client construction. The callback receives a context (client + resolved global
+ * options + this command's options) and the command's positional arguments.
+ *
+ * Commander invokes actions as (arg1, ..., argN, options, command); we slice off
+ * 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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/cli/shared.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAG9D;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASjD;AAED,mEAAmE;AACnE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAOnF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQtD;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,kBAAkB,CAQzE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAIrF;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;IAC5C,MAAM,EAAE,aAAa,CAAC;IACtB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CACpB,IAAI,EAAE,OAAO,EACb,EAAE,EAAE,CAAC,GAAG,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAC/D,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAQvC"}

package/dist/src/cli/shared.js

@@ -0,0 +1,96 @@
+// Shared helpers used across CLI command groups: option parsers, the global
+// option resolver, and JSON rendering (with the --iso-dates transform).
+import { InvalidArgumentError } from "commander";
+import { isoifyDates } from "../client/client.js";
+/**
+ * commander value-parser: a plain base-10 non-negative integer.
+ *
+ * Uses a strict regex rather than `Number()` coercion, which would otherwise
+ * accept empty/whitespace strings (`Number("") === 0`), hex/binary/scientific
+ * literals (`0x10`, `0b10`, `1e3`), signs, padding and decimals.
+ */
+export function parseIntArg(value) {
+    if (!/^[0-9]+$/.test(value)) {
+        throw new InvalidArgumentError("Expected a non-negative integer.");
+    }
+    const n = Number(value);
+    if (!Number.isSafeInteger(n)) {
+        throw new InvalidArgumentError("Expected a non-negative integer.");
+    }
+    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 for an integer constrained to [min, max]. */
+export function parseBoundedInt(min, max) {
+    return (value) => {
+        const n = parseIntArg(value);
+        if (n < min)
+            throw new InvalidArgumentError(`Must be >= ${min}.`);
+        if (n > max)
+            throw new InvalidArgumentError(`Must be <= ${max}.`);
+        return n;
+    };
+}
+/**
+ * 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.
+ */
+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;
+}
+/** Translate resolved global CLI options into client options. */
+export function toEngineOptions(global) {
+    const options = {};
+    if (global.baseUrl !== undefined)
+        options.baseUrl = global.baseUrl;
+    if (global.timeout !== undefined)
+        options.timeoutMs = global.timeout;
+    if (global.userAgent !== undefined)
+        options.userAgent = global.userAgent;
+    if (global.maxRetries !== undefined)
+        options.maxRetries = global.maxRetries;
+    if (global.maxResponseBytes !== undefined)
+        options.maxResponseBytes = global.maxResponseBytes;
+    return options;
+}
+/**
+ * Render a JSON value to stdout, pretty by default and compact with --compact.
+ * With --iso-dates, every MaStR `"/Date(ms)/"` string is rewritten to ISO-8601 first.
+ */
+export function renderJson(deps, global, value) {
+    const shaped = global.isoDates ? isoifyDates(value) : value;
+    const text = global.compact ? JSON.stringify(shaped) : JSON.stringify(shaped, null, 2);
+    deps.io.out(text);
+}
+/**
+ * Wrap an async command action with consistent global-option resolution and
+ * client construction. The callback receives a context (client + resolved global
+ * options + this command's options) and the command's positional arguments.
+ *
+ * Commander invokes actions as (arg1, ..., argN, options, command); we slice off
+ * the trailing options object and command instance to recover the positionals.
+ */
+export function action(deps, fn) {
+    return async (...args) => {
+        const command = args[args.length - 1];
+        const positionals = args.slice(0, Math.max(0, args.length - 2));
+        const global = command.optsWithGlobals();
+        const client = deps.createClient(toEngineOptions(global));
+        await fn({ client, global, opts: command.opts() }, positionals);
+    };
+}
+//# sourceMappingURL=shared.js.map

package/dist/src/cli/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/cli/shared.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,35 @@
+import { type EngineOptions } from "./engine.js";
+import type { FilterColumn, UnitCategory, UnitPage, UnitQuery } from "./types.js";
+/** 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.
+ */
+export declare function parseMsDate(value: string): Date | null;
+/**
+ * Recursively rewrite every `"/Date(ms)/"` string in a value to an ISO-8601 string,
+ * returning a new value. Used by the CLI's `--iso-dates`.
+ */
+export declare function isoifyDates<T>(value: T): T;
+export declare class MastrClient {
+    private readonly engine;
+    constructor(options?: MastrClientOptions);
+    /**
+     * 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.").
+     */
+    units(category: UnitCategory, query?: UnitQuery): Promise<UnitPage>;
+    /** Electricity-generation units (`Stromerzeugung`). */
+    stromerzeugung(query?: UnitQuery): Promise<UnitPage>;
+    /** Electricity-consumption units (`Stromverbrauch`). */
+    stromverbrauch(query?: UnitQuery): Promise<UnitPage>;
+    /** Gas-generation units (`Gaserzeugung`). */
+    gaserzeugung(query?: UnitQuery): Promise<UnitPage>;
+    /** Gas-consumption units (`Gasverbrauch`). */
+    gasverbrauch(query?: UnitQuery): Promise<UnitPage>;
+    /** The filterable columns (names, types, dropdown codes) for a category. */
+    filterColumns(category: UnitCategory): Promise<FilterColumn[]>;
+}
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/client/client.ts"],"names":[],"mappings":"AAYA,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAGhE,OAAO,KAAK,EAAE,YAAY,EAAa,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAgB,MAAM,YAAY,CAAC;AAe3G,kFAAkF;AAClF,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAItD;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAgB1C;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAE3B,OAAO,GAAE,kBAAuB;IAI5C;;;;OAIG;IACG,KAAK,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,GAAE,SAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IAqB7E,uDAAuD;IACvD,cAAc,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;IAGpD,wDAAwD;IACxD,cAAc,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;IAGpD,6CAA6C;IAC7C,YAAY,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;IAGlD,8CAA8C;IAC9C,YAAY,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;IAIlD,4EAA4E;IACtE,aAAa,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CAKrE"}