@maschinenlesbar.org/pegel-online-cli 0.0.1

package/LICENSING.md

@@ -0,0 +1,47 @@
+# Licensing
+
+`pegel-online-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 `pegel-online-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,203 @@
+# pegel-online-cli
+
+A TypeScript **API client** and **command-line interface** for the open
+[PEGELONLINE REST API v2](https://www.pegelonline.wsv.de/webservice/dokuRestapi)
+(`pegelonline.wsv.de`) operated by the **WSV** (Wasserstraßen- und
+Schifffahrtsverwaltung des Bundes) — live **water levels** and related timeseries
+across the German federal waterway network.
+
+- **Zero runtime HTTP dependencies** — built on Node's built-in `http`/`https` (no axios, no fetch polyfill).
+- **One small dependency** for the CLI: [`commander`](https://github.com/tj/commander.js).
+- **Strongly typed** — typed stations, timeseries and measurement shapes.
+- **Well tested** — unit tests on Node's built-in test runner (`node --test`), every HTTP response mocked.
+- **Read-only, no auth** — the PEGELONLINE API needs no key; this client only reads.
+
+New to PEGELONLINE, or terms like *Gewässer*, *timeseries* (`W`/`Q`), MNW/MHW or
+NSW/HSW? See **[GLOSSARY.md](GLOSSARY.md)** for the domain concepts and the
+project's own vocabulary.
+
+## Requirements
+
+- Node.js **>= 20** (uses the stable built-in test runner, ESM and top-level `await`).
+
+## Install
+
+```bash
+npm install
+npm run build        # compiles TypeScript to dist/
+```
+
+Run the CLI without a global install:
+
+```bash
+node dist/src/cli/index.js --help
+# or, after `npm link` / global install:
+pegel --help
+```
+
+---
+
+## CLI usage
+
+Every command prints pretty JSON to stdout (`--compact` for a single line). A
+`<station>` may be a **uuid**, **number**, **shortname** or **longname**. A
+`[timeseries]` defaults to **`W`** (water level); others include `Q` (flow),
+`WT` (water temperature), `LT` (air temperature), depending on the station.
+
+### Global options
+
+| Option | Description |
+| --- | --- |
+| `--base-url <url>` | API base URL (default `https://www.pegelonline.wsv.de`) |
+| `--timeout <ms>` | Per-request timeout (default `30000`) |
+| `--user-agent <ua>` | `User-Agent` header value |
+| `--max-retries <n>` | Retries for transient `429`/`503` responses (default `2`) |
+| `--max-response-bytes <n>` | Cap response body size in bytes (`0` = unlimited; default 100 MiB) |
+| `--compact` | Print JSON on a single line |
+
+Global options are accepted **before or after** the command, e.g. both
+`pegel --compact waters` and `pegel waters --compact` work; placing them before
+the command is recommended for clarity.
+
+### Commands
+
+```text
+stations list [--ids <id> ...] [--waters <shortname>] [--fuzzy-id <id>]
+              [--include-timeseries] [--include-current] [--include-characteristic]
+stations get <station> [--include-...]
+timeseries     <station> [timeseries]    metadata for a timeseries
+current        <station> [timeseries]    the current measurement
+measurements   <station> [timeseries] [--start <iso|P7D>] [--end <iso>]
+waters                                   list all bodies of water (Gewässer)
+```
+
+### Examples
+
+```bash
+# All stations on the Rhine, with their current water level
+pegel stations list --waters RHEIN --include-current
+
+# One station
+pegel stations get BONN --include-timeseries --include-current
+
+# Current water level at Bonn
+pegel current BONN
+
+# Last 3 days of measurements
+pegel measurements BONN W --start P3D
+
+# Characteristic (gauge-mark) values, embedded in the timeseries
+pegel stations get BONN --include-timeseries --include-characteristic
+
+# Bodies of water
+pegel waters
+```
+
+Exit codes: `0` success, `2` for usage/parse errors (unknown command/option, missing argument, invalid flag value), `4` on a `404` from the API, `1` for any other (runtime/network) error.
+
+---
+
+## Library usage
+
+```ts
+import { PegelOnlineClient, PegelApiError } from "@maschinenlesbar.org/pegel-online-cli";
+
+const client = new PegelOnlineClient(); // defaults to https://www.pegelonline.wsv.de
+
+const rhine = await client.stations.list({ waters: "RHEIN", includeCurrentMeasurement: true });
+const bonn = await client.stations.get("BONN", { includeTimeseries: true });
+const now = await client.timeseries.currentMeasurement("BONN", "W");
+const series = await client.timeseries.measurements("BONN", "W", { start: "P3D" });
+
+try {
+  await client.stations.get("DOES-NOT-EXIST");
+} catch (err) {
+  if (err instanceof PegelApiError) console.error(err.status, err.detail);
+}
+```
+
+### Client options
+
+```ts
+new PegelOnlineClient({
+  baseUrl: "https://www.pegelonline.wsv.de",
+  timeoutMs: 15_000,
+  maxRetries: 3,              // 429 / 503 are retried with linear backoff
+  maxResponseBytes: 50 << 20, // abort responses larger than 50 MiB (0 = unlimited)
+  userAgent: "my-app/1.0",
+  transport: customTransport, // inject your own HTTP transport
+});
+```
+
+### Resource groups
+
+`client.stations` (`.list` / `.get`), `client.timeseries` (`.get` / `.currentMeasurement` /
+`.measurements`), and `client.waters()`. Characteristic (gauge-mark) values are
+available via the `includeCharacteristicValues` embed on `.get` / `.list`.
+
+---
+
+## Architecture
+
+```
+src/
+  client/
+    types.ts     # Station / TimeseriesInfo / CurrentMeasurement / Measurement + param objects
+    query.ts     # dependency-free query-string builder
+    http.ts      # the Transport interface + default node:http/https transport
+    engine.ts    # URL building, retry/backoff, redirects, JSON decoding, error mapping
+    errors.ts    # PegelError / PegelApiError / PegelNetworkError / PegelParseError
+    client.ts    # PegelOnlineClient — stations + timeseries resources over the engine
+  cli/
+    io.ts        # injectable I/O seam (stdout/stderr)
+    shared.ts    # option parsers, global-option resolver, JSON renderer
+    commands/    # stations + timeseries/measurements/waters
+    program.ts   # assembles the commander program from injectable deps
+    run.ts       # parses argv -> exit code (no process.exit; testable)
+    index.ts     # #! bin shim
+```
+
+**Design notes**
+
+- The HTTP layer is a single `Transport` function (`(req) => Promise<HttpResponse>`). The default
+  uses `node:http`/`node:https`; tests inject a mock. This keeps the client free of any HTTP framework.
+- The CLI is built around injectable `CliDeps` (client factory + I/O), so the whole program can be
+  driven in-process by tests with a mocked client and captured output — no subprocesses.
+- The engine follows HTTP redirects, so trailing-slash and host normalisations are handled transparently.
+
+---
+
+## Testing
+
+```bash
+npm test          # builds, then runs `node --test` over dist/test
+```
+
+- **`query.test.ts`** — query-string serialisation.
+- **`http.test.ts`** — the default transport against a real loopback `http.createServer`.
+- **`engine.test.ts`** — URL building, JSON decoding, error mapping, 429/503 retry — mocked transport.
+- **`client.test.ts`** — every endpoint's method/URL/query mapping — mocked transport.
+- **`cli.test.ts`** — end-to-end command parsing, validation and exit codes — mocked client.
+
+## Continuous integration
+
+GitHub Actions workflows under `.github/workflows/`:
+
+- **ci.yml** — type-check, build and test on Node 20/22/24 for every push and PR.
+- **release.yml** — on a `v*` tag: verify the tag matches `package.json`, test, `npm pack`, and create a GitHub Release with the tarball.
+- **publish.yml** — manual dispatch: publish to npm via OIDC **Trusted Publishing** (no stored `NPM_TOKEN`) with provenance.
+- **docs.yml** — build TypeDoc API docs and deploy to GitHub Pages on each `v*` tag.
+
+## License
+
+**Dual-licensed** — use it under **either**:
+
+- **[AGPL-3.0-or-later](LICENSE)** (default, free). Note the AGPL's §13 network
+  clause: if you run a modified version as a network service, you must offer that
+  modified source to the service's users.
+- **Commercial license** (paid), for closed-source / proprietary or SaaS use
+  without the AGPL's obligations.
+
+See **[LICENSING.md](LICENSING.md)** for details, and **[CONTRIBUTING.md](CONTRIBUTING.md)**
+for the contribution policy (this project does not accept external code
+contributions). Commercial enquiries: **sebs@2xs.org**.

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

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

package/dist/src/cli/commands/stations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stations.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/stations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAyBxC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAiC7E"}

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

@@ -0,0 +1,45 @@
+import { Option } from "commander";
+import { action, renderJson, requireArg } from "../shared.js";
+/** commander accumulator for a repeatable string option. */
+function collect(value, previous = []) {
+    return previous.concat([value]);
+}
+/** Read the three include flags off a parsed-options object. */
+function includesFrom(opts) {
+    return {
+        includeTimeseries: opts["includeTimeseries"],
+        includeCurrentMeasurement: opts["includeCurrent"],
+        includeCharacteristicValues: opts["includeCharacteristic"],
+    };
+}
+function addIncludeOptions(cmd) {
+    return cmd
+        .addOption(new Option("--include-timeseries", "embed each station's timeseries list"))
+        .addOption(new Option("--include-current", "embed the current measurement"))
+        .addOption(new Option("--include-characteristic", "embed characteristic (gauge-mark) values"));
+}
+export function registerStationCommands(program, deps) {
+    const stations = program.command("stations").description("Measuring stations");
+    const list = stations
+        .command("list")
+        .description("List/filter stations")
+        .option("--ids <id>", "station id (uuid/number/shortname/longname); repeatable", collect)
+        .option("--waters <shortname>", "filter by water shortname (see `waters`)")
+        .option("--fuzzy-id <id>", "fuzzy id match");
+    addIncludeOptions(list).action(action(deps, async ({ client, global, opts }) => {
+        const params = {
+            ids: opts["ids"],
+            waters: opts["waters"],
+            fuzzyId: opts["fuzzyId"],
+            ...includesFrom(opts),
+        };
+        renderJson(deps, global, await client.stations.list(params));
+    }));
+    const get = stations
+        .command("get <station>")
+        .description("Get one station by uuid/number/shortname/longname");
+    addIncludeOptions(get).action(action(deps, async ({ client, global, opts }, [station]) => {
+        renderJson(deps, global, await client.stations.get(requireArg("station", station), includesFrom(opts)));
+    }));
+}
+//# sourceMappingURL=stations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stations.js","sourceRoot":"","sources":["../../../../src/cli/commands/stations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG9D,4DAA4D;AAC5D,SAAS,OAAO,CAAC,KAAa,EAAE,WAAqB,EAAE;IACrD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AAClC,CAAC;AAED,gEAAgE;AAChE,SAAS,YAAY,CAAC,IAA6B;IACjD,OAAO;QACL,iBAAiB,EAAE,IAAI,CAAC,mBAAmB,CAAwB;QACnE,yBAAyB,EAAE,IAAI,CAAC,gBAAgB,CAAwB;QACxE,2BAA2B,EAAE,IAAI,CAAC,uBAAuB,CAAwB;KAClF,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAY;IACrC,OAAO,GAAG;SACP,SAAS,CAAC,IAAI,MAAM,CAAC,sBAAsB,EAAE,sCAAsC,CAAC,CAAC;SACrF,SAAS,CAAC,IAAI,MAAM,CAAC,mBAAmB,EAAE,+BAA+B,CAAC,CAAC;SAC3E,SAAS,CAAC,IAAI,MAAM,CAAC,0BAA0B,EAAE,0CAA0C,CAAC,CAAC,CAAC;AACnG,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,OAAgB,EAAE,IAAa;IACrE,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,WAAW,CAAC,oBAAoB,CAAC,CAAC;IAE/E,MAAM,IAAI,GAAG,QAAQ;SAClB,OAAO,CAAC,MAAM,CAAC;SACf,WAAW,CAAC,sBAAsB,CAAC;SACnC,MAAM,CAAC,YAAY,EAAE,yDAAyD,EAAE,OAAO,CAAC;SACxF,MAAM,CAAC,sBAAsB,EAAE,0CAA0C,CAAC;SAC1E,MAAM,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,CAAC;IAC/C,iBAAiB,CAAC,IAAI,CAAC,CAAC,MAAM,CAC5B,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE;QAC9C,MAAM,MAAM,GAAsB;YAChC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAyB;YACxC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAuB;YAC5C,OAAO,EAAE,IAAI,CAAC,SAAS,CAAuB;YAC9C,GAAG,YAAY,CAAC,IAAI,CAAC;SACtB,CAAC;QACF,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/D,CAAC,CAAC,CACH,CAAC;IAEF,MAAM,GAAG,GAAG,QAAQ;SACjB,OAAO,CAAC,eAAe,CAAC;SACxB,WAAW,CAAC,mDAAmD,CAAC,CAAC;IACpE,iBAAiB,CAAC,GAAG,CAAC,CAAC,MAAM,CAC3B,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE;QACzD,UAAU,CACR,IAAI,EACJ,MAAM,EACN,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAC9E,CAAC;IACJ,CAAC,CAAC,CACH,CAAC;AACJ,CAAC"}

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

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

package/dist/src/cli/commands/timeseries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeseries.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/timeseries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AASxC,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAqDhF"}

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

@@ -0,0 +1,38 @@
+import { action, renderJson, requireArg, timeseriesOr } from "../shared.js";
+/** An empty option value (e.g. `--start ""`) should be omitted, not sent blank. */
+function optStr(value) {
+    const s = value;
+    return s !== undefined && s !== "" ? s : undefined;
+}
+export function registerTimeseriesCommands(program, deps) {
+    program
+        .command("timeseries <station> [timeseries]")
+        .description("Timeseries metadata (timeseries defaults to 'W' = water level)")
+        .action(action(deps, async ({ client, global }, [station, ts]) => {
+        renderJson(deps, global, await client.timeseries.get(requireArg("station", station), timeseriesOr(ts)));
+    }));
+    program
+        .command("current <station> [timeseries]")
+        .description("The current measurement (timeseries defaults to 'W')")
+        .action(action(deps, async ({ client, global }, [station, ts]) => {
+        renderJson(deps, global, await client.timeseries.currentMeasurement(requireArg("station", station), timeseriesOr(ts)));
+    }));
+    program
+        .command("measurements <station> [timeseries]")
+        .description("A window of measurements (timeseries defaults to 'W')")
+        .option("--start <iso>", "window start: ISO-8601 instant, or a period like P7D")
+        .option("--end <iso>", "window end: ISO-8601 instant")
+        .action(action(deps, async ({ client, global, opts }, [station, ts]) => {
+        renderJson(deps, global, await client.timeseries.measurements(requireArg("station", station), timeseriesOr(ts), {
+            start: optStr(opts["start"]),
+            end: optStr(opts["end"]),
+        }));
+    }));
+    program
+        .command("waters")
+        .description("List all bodies of water (Gewässer)")
+        .action(action(deps, async ({ client, global }) => {
+        renderJson(deps, global, await client.waters());
+    }));
+}
+//# sourceMappingURL=timeseries.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timeseries.js","sourceRoot":"","sources":["../../../../src/cli/commands/timeseries.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5E,mFAAmF;AACnF,SAAS,MAAM,CAAC,KAAc;IAC5B,MAAM,CAAC,GAAG,KAA2B,CAAC;IACtC,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,OAAgB,EAAE,IAAa;IACxE,OAAO;SACJ,OAAO,CAAC,mCAAmC,CAAC;SAC5C,WAAW,CAAC,gEAAgE,CAAC;SAC7E,MAAM,CACL,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE;QACvD,UAAU,CACR,IAAI,EACJ,MAAM,EACN,MAAM,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC,CAC9E,CAAC;IACJ,CAAC,CAAC,CACH,CAAC;IAEJ,OAAO;SACJ,OAAO,CAAC,gCAAgC,CAAC;SACzC,WAAW,CAAC,sDAAsD,CAAC;SACnE,MAAM,CACL,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE;QACvD,UAAU,CACR,IAAI,EACJ,MAAM,EACN,MAAM,MAAM,CAAC,UAAU,CAAC,kBAAkB,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC,CAC7F,CAAC;IACJ,CAAC,CAAC,CACH,CAAC;IAEJ,OAAO;SACJ,OAAO,CAAC,qCAAqC,CAAC;SAC9C,WAAW,CAAC,uDAAuD,CAAC;SACpE,MAAM,CAAC,eAAe,EAAE,sDAAsD,CAAC;SAC/E,MAAM,CAAC,aAAa,EAAE,8BAA8B,CAAC;SACrD,MAAM,CACL,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE;QAC7D,UAAU,CACR,IAAI,EACJ,MAAM,EACN,MAAM,MAAM,CAAC,UAAU,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,EAAE,CAAC,EAAE;YACrF,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC5B,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;SACzB,CAAC,CACH,CAAC;IACJ,CAAC,CAAC,CACH,CAAC;IAEJ,OAAO;SACJ,OAAO,CAAC,QAAQ,CAAC;SACjB,WAAW,CAAC,qCAAqC,CAAC;SAClD,MAAM,CACL,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE;QACxC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAClD,CAAC,CAAC,CACH,CAAC;AACN,CAAC"}

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,6 @@
+#!/usr/bin/env node
+// Binary entry point. Thin shim around run(); all logic lives in run.ts/program.ts.
+import { run } from "./run.js";
+const exitCode = await run(process.argv.slice(2));
+process.exitCode = exitCode;
+//# 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,oFAAoF;AAEpF,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAClD,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC"}

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

@@ -0,0 +1,13 @@
+import type { PegelOnlineClient } from "../client/client.js";
+import type { EngineOptions } from "../client/engine.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: EngineOptions): PegelOnlineClient;
+}
+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,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,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,aAAa,GAAG,iBAAiB,CAAC;CACzD;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;AAgBtE,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/filesystem. */
+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;AAuBvC,eAAO,MAAM,OAAO,QAAgB,CAAC;AAErC,yEAAyE;AACzE,eAAO,MAAM,WAAW,EAAE,OAGzB,CAAC;AAEF,wBAAgB,YAAY,CAAC,IAAI,GAAE,OAAqB,GAAG,OAAO,CA0BjE"}

package/dist/src/cli/program.js

@@ -0,0 +1,52 @@
+// 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 { PegelOnlineClient } from "../client/client.js";
+import { parseIntArg } from "./shared.js";
+import { registerStationCommands } from "./commands/stations.js";
+import { registerTimeseriesCommands } from "./commands/timeseries.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/filesystem. */
+export const defaultDeps = {
+    io: defaultIO,
+    createClient: (options) => new PegelOnlineClient(options),
+};
+export function buildProgram(deps = defaultDeps) {
+    const program = new Command();
+    program
+        .name("pegel")
+        .description("CLI for the open PEGELONLINE water-level REST API " +
+        "(https://www.pegelonline.wsv.de/webservices/rest-api/v2)")
+        .version(VERSION)
+        .option("--base-url <url>", "API base URL", "https://www.pegelonline.wsv.de")
+        .option("--timeout <ms>", "per-request timeout in milliseconds", parseIntArg)
+        .option("--user-agent <ua>", "User-Agent header value")
+        .option("--max-retries <n>", "retries for transient 429/503 responses", parseIntArg)
+        .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")
+        .showHelpAfterError();
+    registerStationCommands(program, deps);
+    registerTimeseriesCommands(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,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAEtE;;;;;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,yEAAyE;AACzE,MAAM,CAAC,MAAM,WAAW,GAAY;IAClC,EAAE,EAAE,SAAS;IACb,YAAY,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,iBAAiB,CAAC,OAAO,CAAC;CAC1D,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,oDAAoD;QAClD,0DAA0D,CAC7D;SACA,OAAO,CAAC,OAAO,CAAC;SAChB,MAAM,CAAC,kBAAkB,EAAE,cAAc,EAAE,gCAAgC,CAAC;SAC5E,MAAM,CAAC,gBAAgB,EAAE,qCAAqC,EAAE,WAAW,CAAC;SAC5E,MAAM,CAAC,mBAAmB,EAAE,yBAAyB,CAAC;SACtD,MAAM,CAAC,mBAAmB,EAAE,yCAAyC,EAAE,WAAW,CAAC;SACnF,MAAM,CACL,0BAA0B,EAC1B,kEAAkE,EAClE,WAAW,CACZ;SACA,MAAM,CAAC,WAAW,EAAE,uDAAuD,CAAC;SAC5E,kBAAkB,EAAE,CAAC;IAExB,uBAAuB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACvC,0BAA0B,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAE1C,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;AAqBvC,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,GAAE,OAAqB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmCtF"}

package/dist/src/cli/run.js

@@ -0,0 +1,62 @@
+// 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 { PegelApiError, PegelError } from "../client/errors.js";
+/**
+ * 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);
+}
+/** Distinct exit code for usage/parse errors, so scripts can tell a user mistake
+ *  apart from a runtime/network failure (which exit 1). */
+const USAGE_EXIT = 2;
+export async function run(argv, deps = defaultDeps) {
+    const program = buildProgram(deps);
+    configureTree(program, deps);
+    // A bare invocation with no command should show help on stdout and exit 0,
+    // matching `--help`, rather than erroring out with help on stderr.
+    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 are not errors -> exit 0.
+            if (err.code === "commander.help" || err.code === "commander.helpDisplayed")
+                return 0;
+            if (err.code === "commander.version")
+                return 0;
+            // Every other CommanderError is a usage/parse error -> distinct exit code.
+            return USAGE_EXIT;
+        }
+        if (err instanceof PegelApiError) {
+            deps.io.err(`Error: ${err.message}`);
+            // Map a few notable statuses to distinct exit codes for scripting.
+            if (err.status === 404)
+                return 4;
+            return 1;
+        }
+        if (err instanceof PegelError) {
+            deps.io.err(`Error: ${err.message}`);
+            return 1;
+        }
+        deps.io.err(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+//# 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":"AAAA,6EAA6E;AAC7E,6EAA6E;AAC7E,+DAA+D;AAE/D,OAAO,EAAE,cAAc,EAAgB,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEhE;;;;GAIG;AACH,SAAS,aAAa,CAAC,OAAgB,EAAE,IAAa;IACpD,OAAO,CAAC,YAAY,EAAE,CAAC;IACvB,OAAO,CAAC,eAAe,CAAC;QACtB,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACtD,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;KACvD,CAAC,CAAC;IACH,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,QAAQ;QAAE,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACnE,CAAC;AAED;2DAC2D;AAC3D,MAAM,UAAU,GAAG,CAAC,CAAC;AAErB,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,IAAc,EAAE,OAAgB,WAAW;IACnE,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACnC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAE7B,2EAA2E;IAC3E,mEAAmE;IACnE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;QAC1D,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACjD,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;YAClC,kDAAkD;YAClD,IAAI,GAAG,CAAC,IAAI,KAAK,gBAAgB,IAAI,GAAG,CAAC,IAAI,KAAK,yBAAyB;gBAAE,OAAO,CAAC,CAAC;YACtF,IAAI,GAAG,CAAC,IAAI,KAAK,mBAAmB;gBAAE,OAAO,CAAC,CAAC;YAC/C,2EAA2E;YAC3E,OAAO,UAAU,CAAC;QACpB,CAAC;QACD,IAAI,GAAG,YAAY,aAAa,EAAE,CAAC;YACjC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACrC,mEAAmE;YACnE,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;gBAAE,OAAO,CAAC,CAAC;YACjC,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,GAAG,YAAY,UAAU,EAAE,CAAC;YAC9B,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACrC,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,qBAAqB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrF,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,44 @@
+import type { CliDeps } from "./io.js";
+import type { EngineOptions } from "../client/engine.js";
+/** commander value-parser: a non-negative integer. */
+export declare function parseIntArg(value: string): number;
+/**
+ * Validate a required positional argument: reject an empty/blank value rather
+ * than forwarding it into the URL path (which would produce a malformed request
+ * like `/stations//W/...`). Returns the trimmed value.
+ */
+export declare function requireArg(name: string, value: string | undefined): string;
+/**
+ * Normalise an optional `[timeseries]` positional: an empty/blank value behaves
+ * like omitting it and defaults to "W" (water level), matching the documented
+ * default. (`??` alone would forward an empty string into the path.)
+ */
+export declare function timeseriesOr(value: string | undefined, fallback?: string): string;
+export interface GlobalOptions {
+    baseUrl?: string;
+    timeout?: number;
+    userAgent?: string;
+    maxRetries?: number;
+    maxResponseBytes?: number;
+    compact?: boolean;
+}
+/** Translate resolved global CLI options into client EngineOptions. */
+export declare function toEngineOptions(global: GlobalOptions): EngineOptions;
+/** Render a JSON value to stdout, pretty by default, compact with --compact. */
+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,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGzD,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAajD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAU1E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,SAAM,GAAG,MAAM,CAE9E;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;CACnB;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAQpE;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAGrF;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"}