@maschinenlesbar.org/pegel-online-cli 0.2.0 → 0.3.0

package/README.md

@@ -27,7 +27,7 @@ you can pipe straight into [`jq`](https://jqlang.github.io/jq/).
 npm i -g @maschinenlesbar.org/pegel-online-cli
 ```
 
-This installs the **`pegel`** command. Requires **Node.js 20+**.
+This installs the **`pegel`** command. Requires **Node.js 22.12+**.
 
 Check it works:
 
@@ -74,7 +74,10 @@ waters                                    list all bodies of water (Gewässer)
 ```
 
 A `<station>` may be a **uuid**, **number**, **shortname** or **longname** — e.g.
-`BONN`, `6302010`, or a full UUID. A `[timeseries]` defaults to **`W`** (water
+`BONN`, `6302010`, or a full UUID. Names are not unique (`NEUSTADT` is a gauge on the
+Leine and one on the Baltic coast), and a lookup by such a name returns one of them
+without a warning; `pegel stations list --ids NEUSTADT` lists both and says so on
+stderr — then use the number or uuid. A `[timeseries]` defaults to **`W`** (water
 level); other codes include `Q` (flow/discharge), `WT` (water temperature), and
 `LT` (air temperature) depending on the station.
 
@@ -101,6 +104,11 @@ The API nests the current measurement and the gauge marks *inside* each
 timeseries and drops them without the timeseries list, so `--include-current` and
 `--include-characteristic` turn on `--include-timeseries` themselves.
 
+The API answers an unknown `--ids` entry by leaving it out, and an unknown `--waters` or
+`--fuzzy-id` with `[]`. The CLI says so on stderr (`Note: --ids "KOELN" matched no
+station; …`) and still exits `0`. Every option but `--ids` takes one value; giving one
+twice is a usage error (exit `2`).
+
 ### `measurements` options
 
 | Flag | Meaning |
@@ -149,6 +157,12 @@ pegel stations list --ids BONN --ids KÖLN --ids EMMERICH --include-current
 Every command prints **pretty JSON to stdout**. Errors and diagnostics go to
 stderr, so piping stdout into `jq` stays clean.
 
+A reading's `value` is in the unit of its timeseries (see `pegel timeseries <station>`) —
+`cm` for most water levels, but `m+NN` or `m+PNP` (metres) on canal and reservoir gauges —
+and it is `null` when the gauge sent no value: some gauges report the placeholder `99999`
+instead, which `pegel` turns into `null` so it never reads as a 1 km water level. Drop
+`null` points before a minimum, maximum or trend (`jq 'map(select(.value != null))'`).
+
 ```bash
 # Water shortnames, one per line
 pegel waters | jq -r '.[].shortname'
@@ -157,7 +171,7 @@ pegel waters | jq -r '.[].shortname'
 pegel current BONN | jq '{value, timestamp}'
 
 # CSV-ish series for a spreadsheet
-pegel measurements BONN W --start P3D | jq -r '.[] | [.timestamp, .value] | @csv'
+pegel measurements BONN W --start P3D | jq -r '.[] | select(.value != null) | [.timestamp, .value] | @csv'
 
 # Station names and coordinates on the Rhine (tab-separated)
 pegel stations list --waters RHEIN | jq -r '.[] | [.shortname, .longitude, .latitude] | @tsv'
@@ -185,10 +199,15 @@ both `pegel --compact waters` and `pegel waters --compact` do the same thing.
 | `4` | station or resource not found (`404`) |
 | `1` | any other error (network, timeout, unexpected response) |
 
+A reader that stops early (`| head`, `| jq` exiting on a match) is ordinary use: the CLI
+stops quietly with exit `0`. A failed run keeps its exit code even when nothing reads
+stderr any more (`2>&1 | head -1`).
+
 ## Troubleshooting
 
 - **`command not found: pegel`** — the global npm bin directory isn't on your
-  `PATH`. Run `npm bin -g` to find it and add it, or run via
+  `PATH`. Run `npm prefix -g` to find it (the commands are in its `bin`
+  subdirectory) and add that to your `PATH`, or run via
   `npx @maschinenlesbar.org/pegel-online-cli …`.
 - **Exit `2` / "invalid argument"** — check the command syntax: a `<station>`
   argument is required, and no argument or option value may be blank (or `.` /
@@ -206,8 +225,10 @@ both `pegel --compact waters` and `pegel waters --compact` do the same thing.
   `P7D`, not `7d`.
 - **Empty `[]` from `measurements`** — the window lies outside the data the API
   keeps (about the last month), e.g. a date from earlier in the year.
-- **Exit `1` / network error** — connectivity, DNS, or a timeout. Try again, or
-  raise the limit with `--timeout 60000`.
+- **Exit `1` / network error** — connectivity, DNS, or a timeout; the message names
+  the request that failed (`GET https://… failed: socket hang up`). Try again, or
+  raise the limit with `--timeout 60000`. A body larger than `--max-response-bytes`
+  fails the same way and says so.
 
 ## Global options
 
@@ -218,10 +239,10 @@ These apply to every command and may be given before *or* after it:
 | `-V, --version` | Print the version number |
 | `-h, --help` | Show help for the program or a command |
 | `--compact` | Print JSON on a single line instead of pretty-printed |
-| `--base-url <url>` | API base URL (default `https://www.pegelonline.wsv.de`); http(s) only, a path prefix is fine, no query (`?`), fragment (`#`), whitespace or control characters; userinfo is sent as Basic auth but shown as `***` in messages |
+| `--base-url <url>` | API base URL (default `https://www.pegelonline.wsv.de`); http(s) only, a path prefix is fine, no query (`?`), fragment (`#`), whitespace or control characters; userinfo is sent as Basic auth but shown as `***` in messages (write a literal `%` in it as `%25`) |
 | `--timeout <ms>` | Time limit per request in milliseconds, reading the whole response included (default `30000`; at most `2147483647`) |
 | `--user-agent <ua>` | `User-Agent` header value (not blank; Latin-1, no control characters) |
-| `--max-retries <n>` | Retries for transient `429`/`503` responses, `0`–`10` (default `2`); each waits the server's `Retry-After` (up to 30 s; a longer one is not retried), else 200 ms × attempt |
+| `--max-retries <n>` | Retries for transient `429`/`503` responses and reset connections, `0`–`10` (default `2`); each waits 200 ms × attempt, or longer if the server's `Retry-After` asks (up to 30 s; a longer one is not retried, and the error names the wait). A timeout is not retried |
 | `--max-response-bytes <n>` | Cap response body size in bytes (`0` = unlimited; default 100 MiB) |
 
 ## Learn more

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

@@ -1,5 +1,25 @@
 import { Option } from "commander";
-import { STATION_HELP, action, parseNonEmpty, parsePathArg, renderJson } from "../shared.js";
+import { STATION_HELP, action, once, parseNonEmpty, parsePathArg, renderJson } from "../shared.js";
+import { stationListNotes } from "../../client/client.js";
+/** A library note about the listing, worded with the CLI's flag names. */
+function noteText(note) {
+    if (note.kind === "ambiguous") {
+        const which = note.stations
+            .map((s) => `${s.shortname}${s.water !== undefined ? ` on ${s.water}` : ""} (number ${s.number}, uuid ${s.uuid})`)
+            .join(" and ");
+        return (`Note: ${JSON.stringify(note.name)} names ${note.stations.length} stations: ${which}. ` +
+            "A lookup by that name (stations get, timeseries, current, measurements) returns only one of them; use the number or uuid.");
+    }
+    const value = JSON.stringify(note.value);
+    switch (note.filter) {
+        case "ids":
+            return `Note: --ids ${value} matched no station; the list has only the others. Find the name with --fuzzy-id.`;
+        case "waters":
+            return `Note: --waters ${value} matched no station; it takes a water shortname as \`pegel waters\` lists it (e.g. RHEIN).`;
+        case "fuzzyId":
+            return `Note: --fuzzy-id ${value} matched no station; it is matched literally, umlauts included (köln, not koeln).`;
+    }
+}
 /** commander accumulator for a repeatable string option. */
 function collect(value, previous = []) {
     return previous.concat([parseNonEmpty(value)]);
@@ -24,8 +44,8 @@ export function registerStationCommands(program, deps) {
         .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`)", parseNonEmpty)
-        .option("--fuzzy-id <id>", "fuzzy id match", parseNonEmpty);
+        .option("--waters <shortname>", "filter by water shortname (see `waters`)", once("--waters", parseNonEmpty))
+        .option("--fuzzy-id <id>", "fuzzy id match", once("--fuzzy-id", parseNonEmpty));
     addIncludeOptions(list).action(action(deps, async ({ client, global, opts }) => {
         const params = {
             ids: opts["ids"],
@@ -33,7 +53,12 @@ export function registerStationCommands(program, deps) {
             fuzzyId: opts["fuzzyId"],
             ...includesFrom(opts),
         };
-        renderJson(deps, global, await client.stations.list(params));
+        const stations = await client.stations.list(params);
+        renderJson(deps, global, stations);
+        // Filter values the API matched nothing for: still exit 0 (the answer is valid),
+        // but say so on stderr rather than silently printing fewer stations or [].
+        for (const note of stationListNotes(params, stations))
+            deps.io.err(noteText(note));
     }));
     const get = stations
         .command("get")

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

@@ -1,4 +1,4 @@
-import { STATION_HELP, action, parseNonEmpty, parsePathArg, renderJson, timeseriesOr } from "../shared.js";
+import { STATION_HELP, action, once, parseNonEmpty, parsePathArg, renderJson, timeseriesOr } from "../shared.js";
 const TIMESERIES_HELP = "timeseries shortname, e.g. W (water level) or Q (flow)";
 export function registerTimeseriesCommands(program, deps) {
     program
@@ -22,8 +22,8 @@ export function registerTimeseriesCommands(program, deps) {
         .argument("<station>", STATION_HELP, parsePathArg)
         .argument("[timeseries]", TIMESERIES_HELP, parsePathArg)
         .description("A window of measurements (timeseries defaults to 'W')")
-        .option("--start <iso>", "window start: ISO-8601 instant, or a period like P7D", parseNonEmpty)
-        .option("--end <iso>", "window end: ISO-8601 instant", parseNonEmpty)
+        .option("--start <iso>", "window start: ISO-8601 instant, or a period like P7D", once("--start", parseNonEmpty))
+        .option("--end <iso>", "window end: ISO-8601 instant", once("--end", parseNonEmpty))
         .action(action(deps, async ({ client, global, opts }, [station, ts]) => {
         renderJson(deps, global, await client.timeseries.measurements(station, timeseriesOr(ts), {
             start: opts["start"],

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

@@ -22,7 +22,8 @@ export interface OutputStreams {
  * pager — closes the pipe while the CLI is still writing, and the next write fails
  * with EPIPE. That is ordinary use, so the process exits 0 at once, quietly. Any
  * other stdout error prints one `Output error: <message>` line to stderr and exits
- * 1; any other stderr error exits 1 silently (there is nowhere left to report it).
+ * 1. On stderr an EPIPE is ignored, so a failed run keeps its exit code; any other
+ * stderr error exits 1 silently (there is nowhere left to report it).
  * The bin shim installs this once, before `run()`.
  */
 export declare function handleOutputErrors(streams?: OutputStreams, exit?: (code: number) => void): void;

package/dist/src/cli/io.js

@@ -8,7 +8,8 @@
  * pager — closes the pipe while the CLI is still writing, and the next write fails
  * with EPIPE. That is ordinary use, so the process exits 0 at once, quietly. Any
  * other stdout error prints one `Output error: <message>` line to stderr and exits
- * 1; any other stderr error exits 1 silently (there is nowhere left to report it).
+ * 1. On stderr an EPIPE is ignored, so a failed run keeps its exit code; any other
+ * stderr error exits 1 silently (there is nowhere left to report it).
  * The bin shim installs this once, before `run()`.
  */
 export function handleOutputErrors(streams = process, exit = (code) => process.exit(code)) {
@@ -18,8 +19,12 @@ export function handleOutputErrors(streams = process, exit = (code) => process.e
         process.stderr.write(`Output error: ${err.message}\n`);
         exit(1);
     });
+    // stderr's reader going away doesn't make a failed run a success: ignore EPIPE there
+    // and let the run's own exit code stand (`2>&1 | head -1` used to turn a usage error
+    // into 0).
     streams.stderr.on("error", (err) => {
-        exit(err.code === "EPIPE" ? 0 : 1);
+        if (err.code !== "EPIPE")
+            exit(1);
     });
 }
 export const defaultIO = {

package/dist/src/cli/program.js

@@ -8,7 +8,7 @@ import { defaultIO } from "./io.js";
 import { PegelOnlineClient } from "../client/client.js";
 import { MAX_TIMEOUT_MS } from "../client/http.js";
 import { MAX_RETRIES } from "../client/engine.js";
-import { parseBoundedInt, parseIntArg, parseBaseUrl, parseHeaderValue } from "./shared.js";
+import { once, parseBoundedInt, parseIntArg, parseBaseUrl, parseHeaderValue } from "./shared.js";
 import { registerStationCommands } from "./commands/stations.js";
 import { registerTimeseriesCommands } from "./commands/timeseries.js";
 /**
@@ -40,11 +40,11 @@ export function buildProgram(deps = defaultDeps) {
         .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", parseBaseUrl, "https://www.pegelonline.wsv.de")
-        .option("--timeout <ms>", "time limit per request in milliseconds, whole response included", 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; each waits the server's Retry-After, up to 30 s)", parseBoundedInt(0, MAX_RETRIES))
-        .option("--max-response-bytes <n>", "cap response body size in bytes (0 = unlimited; default 100 MiB)", parseIntArg)
+        .option("--base-url <url>", "API base URL", once("--base-url", parseBaseUrl), "https://www.pegelonline.wsv.de")
+        .option("--timeout <ms>", "time limit per request in milliseconds, whole response included", once("--timeout", parseBoundedInt(0, MAX_TIMEOUT_MS)))
+        .option("--user-agent <ua>", "User-Agent header value", once("--user-agent", parseHeaderValue))
+        .option("--max-retries <n>", "retries for transient 429/503 responses and reset connections (0..10; each waits the server's Retry-After, up to 30 s)", once("--max-retries", parseBoundedInt(0, MAX_RETRIES)))
+        .option("--max-response-bytes <n>", "cap response body size in bytes (0 = unlimited; default 100 MiB)", once("--max-response-bytes", parseIntArg))
         .option("--compact", "print JSON on a single line instead of pretty-printed")
         .showHelpAfterError();
     registerStationCommands(program, deps);

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

@@ -1,2 +1,14 @@
 import type { CliDeps } from "./io.js";
+/**
+ * `deps` with an `io` that redacts the credentials of every argument from everything it
+ * prints. Commander echoes rejected values in its errors (`argument '<value>' is
+ * invalid`), names unknown commands and options, and a URL typed where a station id
+ * belongs ends up in an error message: whatever path a credential takes to stdout or
+ * stderr, its exact userinfo (as `credentialsIn` finds it, plus its JSON-quoted form) is
+ * replaced by `***`. A pattern alone can't delimit a password with spaces, quotes, `#`,
+ * `?` or `/`; the exact strings can. Without credentials the output passes through
+ * unchanged. (This CLI reads no environment variable, so the arguments are the only
+ * source.)
+ */
+export declare function withRedactedOutput(deps: CliDeps, argv: readonly string[]): CliDeps;
 export declare function run(argv: string[], deps?: CliDeps): Promise<number>;

package/dist/src/cli/run.js

@@ -3,7 +3,7 @@
 // captured output and exit code without spawning a subprocess.
 import { CommanderError } from "commander";
 import { buildProgram, defaultDeps } from "./program.js";
-import { PegelApiError, PegelError, PegelValidationError } from "../client/errors.js";
+import { PegelApiError, PegelError, PegelValidationError, credentialsIn, redactCredentials, } 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
@@ -21,7 +21,35 @@ function configureTree(command, 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;
+/**
+ * `deps` with an `io` that redacts the credentials of every argument from everything it
+ * prints. Commander echoes rejected values in its errors (`argument '<value>' is
+ * invalid`), names unknown commands and options, and a URL typed where a station id
+ * belongs ends up in an error message: whatever path a credential takes to stdout or
+ * stderr, its exact userinfo (as `credentialsIn` finds it, plus its JSON-quoted form) is
+ * replaced by `***`. A pattern alone can't delimit a password with spaces, quotes, `#`,
+ * `?` or `/`; the exact strings can. Without credentials the output passes through
+ * unchanged. (This CLI reads no environment variable, so the arguments are the only
+ * source.)
+ */
+export function withRedactedOutput(deps, argv) {
+    // An `--option=value` token is echoed as its value alone.
+    const values = argv.map((token) => token.startsWith("-") && token.includes("=") ? token.slice(token.indexOf("=") + 1) : token);
+    const secrets = new Set();
+    for (const source of [...argv, ...values]) {
+        for (const secret of credentialsIn(source)) {
+            secrets.add(secret);
+            secrets.add(JSON.stringify(secret).slice(1, -1));
+        }
+    }
+    if (secrets.size === 0)
+        return deps;
+    const list = [...secrets];
+    const redact = (text) => redactCredentials(text, list);
+    return { ...deps, io: { out: (text) => deps.io.out(redact(text)), err: (text) => deps.io.err(redact(text)) } };
+}
 export async function run(argv, deps = defaultDeps) {
+    deps = withRedactedOutput(deps, argv);
     const program = buildProgram(deps);
     configureTree(program, deps);
     // A bare invocation with no command should show help on stdout and exit 0,

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

@@ -6,6 +6,14 @@ export declare const STATION_HELP = "station uuid, number, shortname or longname
 export declare function parseIntArg(value: string): number;
 /** Build a commander value-parser for an integer constrained to [min, max]. */
 export declare function parseBoundedInt(min: number, max: number): (value: string) => number;
+/**
+ * Wrap a commander value-parser so its option may be given only once. Commander keeps
+ * the last of a repeated single-value option silently: `--waters ELBE --waters RHEIN`
+ * listed the Rhine only, `--start P7D --start P1D` fetched one day. A repetition is a
+ * usage error instead. The program is built anew for every run, so the flag starts
+ * fresh each time.
+ */
+export declare function once<T>(flag: string, parser: (value: string) => T): (value: string) => T;
 /**
  * commander value-parser: a value that is not blank. The rule is the library's
  * nonEmptyProblem, which the client enforces on every filter value too (the API

package/dist/src/cli/shared.js

@@ -30,6 +30,22 @@ export function parseBoundedInt(min, max) {
         return n;
     };
 }
+/**
+ * Wrap a commander value-parser so its option may be given only once. Commander keeps
+ * the last of a repeated single-value option silently: `--waters ELBE --waters RHEIN`
+ * listed the Rhine only, `--start P7D --start P1D` fetched one day. A repetition is a
+ * usage error instead. The program is built anew for every run, so the flag starts
+ * fresh each time.
+ */
+export function once(flag, parser) {
+    let seen = false;
+    return (value) => {
+        if (seen)
+            throw new InvalidArgumentError(`${flag} may be given only once.`);
+        seen = true;
+        return parser(value);
+    };
+}
 /**
  * commander value-parser: a value that is not blank. The rule is the library's
  * nonEmptyProblem, which the client enforces on every filter value too (the API

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

@@ -1,5 +1,12 @@
 import { RequestEngine, type EngineOptions } from "./engine.js";
 import type { Station, Water, TimeseriesInfo, CurrentMeasurement, Measurement, StationListParams, IncludeParams, MeasurementsParams } from "./types.js";
+/**
+ * The value PEGELONLINE relays for "no reading" on some gauges (seen on the
+ * Rijkswaterstaat gauge PANNERDENSE KOP: `99999` cm, interleaved with real readings of
+ * 576–597 cm in a measurement window). As a number it read as a 1 km water level and
+ * broke every minimum, maximum, trend and map built on it.
+ */
+export declare const NO_VALUE_SENTINEL = 99999;
 /** Stations: list with filters, or fetch one by uuid/number/shortname/longname. */
 declare class StationsResource {
     private readonly e;
@@ -22,6 +29,39 @@ declare class TimeseriesResource {
     /** Rejects (PegelValidationError, no request) a blank `start` or `end`. */
     measurements(station: string, timeseries?: string, params?: MeasurementsParams): Promise<Measurement[]>;
 }
+/**
+ * What {@link stationListNotes} reports about a `stations.list` result: a filter value
+ * that matched no station, or a name that more than one returned station carries.
+ */
+export type StationListNote = {
+    kind: "unmatched";
+    filter: "ids" | "waters" | "fuzzyId";
+    value: string;
+} | {
+    kind: "ambiguous";
+    /** The shortname two or more returned stations share (e.g. "NEUSTADT"). */
+    name: string;
+    /** Those stations, to pick one by its unambiguous uuid or number. */
+    stations: Array<Pick<Station, "uuid" | "number" | "shortname" | "longname"> & {
+        water?: string;
+    }>;
+};
+/**
+ * The filter values of a `stations.list` call that matched nothing in its result. The
+ * API drops an `ids` entry it doesn't know and answers an unknown `waters` or `fuzzyId`
+ * with `[]`, both with HTTP 200, so `ids: ["BONN", "KOELN", "EMMERICH"]` silently gave two
+ * stations and `waters: "Rhine"` an empty river. This reports each `ids` entry that names
+ * none of the returned stations (by uuid, number, shortname or longname, ignoring case),
+ * and a `waters` or `fuzzyId` filter whose result is empty. An empty array means every
+ * filter matched.
+ *
+ * When the call looked stations up by name (`ids` or `fuzzyId`), it also reports every
+ * shortname that two or more returned stations share: NEUSTADT names a gauge on the
+ * LEINE and one on the OSTSEE, and a lookup by that name (`stations.get("NEUSTADT")`,
+ * `timeseries.currentMeasurement("NEUSTADT")`) silently returns one of them — the uuid
+ * or number picks the right one. The CLI prints all notes on stderr.
+ */
+export declare function stationListNotes(params: StationListParams, stations: readonly Station[]): StationListNote[];
 export declare class PegelOnlineClient {
     private readonly engine;
     readonly stations: StationsResource;

package/dist/src/client/client.js

@@ -6,18 +6,9 @@
 //   client.timeseries.currentMeasurement("BONN", "W")
 //   client.timeseries.measurements("BONN", "W", { start: "P3D" })
 import { RequestEngine } from "./engine.js";
-import { PegelError } from "./errors.js";
-import { assertValid, idListProblem, nonEmptyProblem } from "./validate.js";
+import { PegelParseError, PegelValidationError } from "./errors.js";
+import { assertValid, idListProblem, knownKeysProblem, nonEmptyProblem, normalizeInput, optionalBooleanProblem, } from "./validate.js";
 const API = "/webservices/rest-api/v2";
-/**
- * Station names, waters and ids are matched exactly by the API, which stores them
- * composed (NFC): a decomposed umlaut ("KO" + U+0308 + "LN", as pasted from macOS
- * file names or some PDFs) is a 404 / an empty list. Compose every such input.
- * NFC, not NFKC: an id lookup must not rewrite compatibility characters.
- */
-function nfc(value) {
-    return value.normalize("NFC");
-}
 /**
  * One URL path segment from a caller-supplied station or timeseries id. A blank
  * value would build a different path (`stations/.json`, `stations//W.json`), and
@@ -26,24 +17,71 @@ function nfc(value) {
  */
 function enc(name, value) {
     if (typeof value !== "string" || value.trim() === "") {
-        throw new PegelError(`Invalid ${name}: expected a non-empty string, got ${JSON.stringify(value)}.`);
+        throw new PegelValidationError(`Invalid ${name}: expected a non-empty string, got ${typeof value === "string" ? JSON.stringify(value) : typeof value}.`);
     }
-    if (value === "." || value === "..") {
-        throw new PegelError(`Invalid ${name} "${value}": "." and ".." cannot be used as an id.`);
+    const id = normalizeInput(value);
+    if (id === "." || id === "..") {
+        throw new PegelValidationError(`Invalid ${name} "${id}": "." and ".." cannot be used as an id.`);
     }
-    return encodeURIComponent(nfc(value));
+    return encodeURIComponent(id);
 }
 /**
  * An optional query value: `undefined` means omitted; anything else must be a
  * non-blank string (nonEmptyProblem), or PegelValidationError is thrown.
  */
 function optionalValue(name, value) {
-    return value === undefined ? undefined : assertValid(name, value, nonEmptyProblem);
+    return value === undefined ? undefined : normalizeInput(assertValid(name, value, nonEmptyProblem));
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const hasStrings = (...keys) => (v) => isObject(v) && keys.every((k) => typeof v[k] === "string");
+const arrayOf = (item) => (v) => Array.isArray(v) && v.every(item);
+const isWater = hasStrings("shortname", "longname");
+const isStation = hasStrings("uuid", "shortname");
+const isTimeseries = hasStrings("shortname", "unit");
+const isMeasurement = (v) => hasStrings("timestamp")(v) && (typeof v.value === "number" || v.value === null);
+/** `value` when `shape(value)` holds; otherwise a PegelParseError naming the expectation. */
+function expectShape(path, value, shape, what) {
+    if (!shape(value))
+        throw new PegelParseError(`Unexpected response from ${path}: expected ${what}.`);
+    return value;
+}
+const INCLUDE_KEYS = ["includeTimeseries", "includeCurrentMeasurement", "includeCharacteristicValues"];
+const LIST_KEYS = ["ids", "waters", "fuzzyId", ...INCLUDE_KEYS];
+const MEASUREMENT_KEYS = ["start", "end"];
+/**
+ * A method's parameter object, checked before any request: `undefined` (or `null` from
+ * JavaScript) means none; otherwise only the documented keys (knownKeysProblem), and the
+ * include flags only as booleans. Throws PegelValidationError.
+ */
+function checkParams(name, params, allowed) {
+    if (params === undefined || params === null)
+        return {};
+    assertValid(name, params, knownKeysProblem(allowed));
+    for (const key of INCLUDE_KEYS) {
+        if (allowed.includes(key))
+            assertValid(key, params[key], optionalBooleanProblem);
+    }
+    return params;
 }
-/** An optional filter value (optionalValue), composed to NFC like every name the API matches. */
-function optionalFilter(name, value) {
-    const checked = optionalValue(name, value);
-    return checked === undefined ? undefined : nfc(checked);
+/**
+ * The value PEGELONLINE relays for "no reading" on some gauges (seen on the
+ * Rijkswaterstaat gauge PANNERDENSE KOP: `99999` cm, interleaved with real readings of
+ * 576–597 cm in a measurement window). As a number it read as a 1 km water level and
+ * broke every minimum, maximum, trend and map built on it.
+ */
+export const NO_VALUE_SENTINEL = 99999;
+/** `m` with a sentinel `value` replaced by `null` (no reading at that time). */
+function readingOf(m) {
+    return m.value === NO_VALUE_SENTINEL ? { ...m, value: null } : m;
+}
+/** A timeseries with the sentinel mapped in its embedded current measurement. */
+function timeseriesOf(t) {
+    const current = t.currentMeasurement;
+    return current !== undefined && isMeasurement(current) ? { ...t, currentMeasurement: readingOf(current) } : t;
+}
+/** A station with the sentinel mapped in every embedded current measurement. */
+function stationOf(s) {
+    return Array.isArray(s.timeseries) ? { ...s, timeseries: s.timeseries.map((t) => (isObject(t) ? timeseriesOf(t) : t)) } : s;
 }
 /** Drop undefined values so only the parameters the caller set are sent. */
 function prune(params) {
@@ -87,16 +125,20 @@ class StationsResource {
      * no filter and would answer with every station.
      */
     async list(params = {}) {
+        params = checkParams("stations.list parameters", params, LIST_KEYS);
         const query = prune({
-            ids: params.ids === undefined ? undefined : assertValid("ids", params.ids, idListProblem).map(nfc).join(","),
-            waters: optionalFilter("waters", params.waters),
-            fuzzyId: optionalFilter("fuzzyId", params.fuzzyId),
+            ids: params.ids === undefined ? undefined : assertValid("ids", params.ids, idListProblem).map(normalizeInput).join(","),
+            waters: optionalValue("waters", params.waters),
+            fuzzyId: optionalValue("fuzzyId", params.fuzzyId),
             ...stationIncludes(params),
         });
-        return this.e.getJson(`${API}/stations.json`, query);
+        const path = `${API}/stations.json`;
+        return expectShape(path, await this.e.getJson(path, query), arrayOf(isStation), "an array of stations").map(stationOf);
     }
     async get(station, params = {}) {
-        return this.e.getJson(`${API}/stations/${enc("station", station)}.json`, stationIncludes(params));
+        params = checkParams("stations.get parameters", params, INCLUDE_KEYS);
+        const path = `${API}/stations/${enc("station", station)}.json`;
+        return stationOf(expectShape(path, await this.e.getJson(path, stationIncludes(params)), isStation, "a station object"));
     }
 }
 /** Timeseries: metadata, the current measurement, a window of measurements, gauge marks. */
@@ -107,27 +149,92 @@ class TimeseriesResource {
     }
     /** Timeseries metadata (e.g. "W" = water level, "Q" = flow). */
     async get(station, timeseries = "W", params = {}) {
-        return this.e.getJson(`${API}/stations/${enc("station", station)}/${enc("timeseries", timeseries)}.json`, includeQuery(params));
+        params = checkParams("timeseries.get parameters", params, INCLUDE_KEYS);
+        const path = `${API}/stations/${enc("station", station)}/${enc("timeseries", timeseries)}.json`;
+        return timeseriesOf(expectShape(path, await this.e.getJson(path, includeQuery(params)), isTimeseries, "a timeseries object"));
     }
     async currentMeasurement(station, timeseries = "W") {
-        return this.e.getJson(`${API}/stations/${enc("station", station)}/${enc("timeseries", timeseries)}/currentmeasurement.json`);
+        const path = `${API}/stations/${enc("station", station)}/${enc("timeseries", timeseries)}/currentmeasurement.json`;
+        return readingOf(expectShape(path, await this.e.getJson(path), isMeasurement, "a measurement object"));
     }
     /** Rejects (PegelValidationError, no request) a blank `start` or `end`. */
     async measurements(station, timeseries = "W", params = {}) {
-        return this.e.getJson(`${API}/stations/${enc("station", station)}/${enc("timeseries", timeseries)}/measurements.json`, prune({ start: optionalValue("start", params.start), end: optionalValue("end", params.end) }));
+        params = checkParams("timeseries.measurements parameters", params, MEASUREMENT_KEYS);
+        const path = `${API}/stations/${enc("station", station)}/${enc("timeseries", timeseries)}/measurements.json`;
+        const query = prune({ start: optionalValue("start", params.start), end: optionalValue("end", params.end) });
+        return expectShape(path, await this.e.getJson(path, query), arrayOf(isMeasurement), "an array of measurements").map(readingOf);
+    }
+}
+/** Case-insensitive equality the way the API's id lookup behaves (`roßdorf` finds `ROSSDORF`). */
+function sameId(a, b) {
+    return a.toLowerCase() === b.toLowerCase() || a.toUpperCase() === b.toUpperCase();
+}
+/**
+ * The filter values of a `stations.list` call that matched nothing in its result. The
+ * API drops an `ids` entry it doesn't know and answers an unknown `waters` or `fuzzyId`
+ * with `[]`, both with HTTP 200, so `ids: ["BONN", "KOELN", "EMMERICH"]` silently gave two
+ * stations and `waters: "Rhine"` an empty river. This reports each `ids` entry that names
+ * none of the returned stations (by uuid, number, shortname or longname, ignoring case),
+ * and a `waters` or `fuzzyId` filter whose result is empty. An empty array means every
+ * filter matched.
+ *
+ * When the call looked stations up by name (`ids` or `fuzzyId`), it also reports every
+ * shortname that two or more returned stations share: NEUSTADT names a gauge on the
+ * LEINE and one on the OSTSEE, and a lookup by that name (`stations.get("NEUSTADT")`,
+ * `timeseries.currentMeasurement("NEUSTADT")`) silently returns one of them — the uuid
+ * or number picks the right one. The CLI prints all notes on stderr.
+ */
+export function stationListNotes(params, stations) {
+    const notes = [];
+    for (const raw of params.ids ?? []) {
+        const id = normalizeInput(raw);
+        const found = stations.some((s) => [s.uuid, s.number, s.shortname, s.longname].some((f) => typeof f === "string" && sameId(f, id)));
+        if (!found)
+            notes.push({ kind: "unmatched", filter: "ids", value: raw });
+    }
+    if (stations.length === 0) {
+        if (params.waters !== undefined)
+            notes.push({ kind: "unmatched", filter: "waters", value: params.waters });
+        if (params.fuzzyId !== undefined)
+            notes.push({ kind: "unmatched", filter: "fuzzyId", value: params.fuzzyId });
+    }
+    if (params.ids !== undefined || params.fuzzyId !== undefined) {
+        const byName = new Map();
+        for (const s of stations) {
+            const key = s.shortname.toUpperCase();
+            byName.set(key, [...(byName.get(key) ?? []), s]);
+        }
+        for (const same of byName.values()) {
+            if (same.length < 2)
+                continue;
+            notes.push({
+                kind: "ambiguous",
+                name: same[0].shortname,
+                stations: same.map((s) => ({
+                    uuid: s.uuid,
+                    number: s.number,
+                    shortname: s.shortname,
+                    longname: s.longname,
+                    ...(s.water?.shortname !== undefined ? { water: s.water.shortname } : {}),
+                })),
+            });
+        }
     }
+    return notes;
 }
 export class PegelOnlineClient {
     engine;
     stations;
     timeseries;
     constructor(options = {}) {
-        this.engine = new RequestEngine(options);
+        // A JavaScript caller may pass null for "no options"; treat it like undefined.
+        this.engine = new RequestEngine(options ?? {});
         this.stations = new StationsResource(this.engine);
         this.timeseries = new TimeseriesResource(this.engine);
     }
     /** List all bodies of water (Gewässer) covered by the service. */
-    waters() {
-        return this.engine.getJson(`${API}/waters.json`);
+    async waters() {
+        const path = `${API}/waters.json`;
+        return expectShape(path, await this.engine.getJson(path), arrayOf(isWater), "an array of waters");
     }
 }