@maschinenlesbar.org/pegel-online-cli 0.1.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 (`#`) or surrounding whitespace; 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.d.ts

@@ -1,4 +1,3 @@
 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.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")
@@ -43,4 +68,3 @@ export function registerStationCommands(program, deps) {
         renderJson(deps, global, await client.stations.get(station, includesFrom(opts)));
     }));
 }
-//# sourceMappingURL=stations.js.map

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

@@ -1,4 +1,3 @@
 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.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"],
@@ -37,4 +37,3 @@ export function registerTimeseriesCommands(program, deps) {
         renderJson(deps, global, await client.waters());
     }));
 }
-//# sourceMappingURL=timeseries.js.map

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

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

package/dist/src/cli/index.js

@@ -5,4 +5,3 @@ import { run } from "./run.js";
 handleOutputErrors();
 const exitCode = await run(process.argv.slice(2));
 process.exitCode = exitCode;
-//# sourceMappingURL=index.js.map

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

@@ -22,9 +22,9 @@ 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;
 export declare const defaultIO: CliIO;
-//# sourceMappingURL=io.d.ts.map

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,12 +19,15 @@ 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 = {
     out: (text) => process.stdout.write(text + "\n"),
     err: (text) => process.stderr.write(text + "\n"),
 };
-//# sourceMappingURL=io.js.map

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

@@ -4,4 +4,3 @@ export declare const VERSION: string;
 /** Default dependencies: real client + real stdout/stderr/filesystem. */
 export declare const defaultDeps: CliDeps;
 export declare function buildProgram(deps?: CliDeps): Command;
-//# sourceMappingURL=program.d.ts.map

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,15 +40,14 @@ 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);
     registerTimeseriesCommands(program, deps);
     return program;
 }
-//# sourceMappingURL=program.js.map

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

@@ -1,3 +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>;
-//# sourceMappingURL=run.d.ts.map

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 } 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,
@@ -51,6 +79,12 @@ export async function run(argv, deps = defaultDeps) {
                 return 4;
             return 1;
         }
+        if (err instanceof PegelValidationError) {
+            // An input the library rejected before any request: a usage error, the same
+            // exit code as commander's own parse errors.
+            deps.io.err(`Error: ${err.message}`);
+            return USAGE_EXIT;
+        }
         if (err instanceof PegelError) {
             deps.io.err(`Error: ${err.message}`);
             return 1;
@@ -59,4 +93,3 @@ export async function run(argv, deps = defaultDeps) {
         return 1;
     }
 }
-//# sourceMappingURL=run.js.map

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

@@ -7,17 +7,25 @@ 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;
 /**
- * commander value-parser: a value that is not blank. A blank filter would
- * otherwise be dropped and the command would silently run unfiltered.
+ * 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
+ * reads an empty parameter as no filter); here it only turns a blank value into an
+ * early usage error.
  */
 export declare function parseNonEmpty(value: string): string;
 /**
- * commander value-parser for a value that ends up in an HTTP header (`--user-agent`).
- * Node's HTTP layer throws an opaque "Invalid character in header content" at request
- * time for a CR/LF (or any other C0 control or DEL) and for any character above
- * U+00FF, which surfaced as "Unexpected error". Reject those here as a usage error,
- * along with a blank value. Tab is allowed, as in HTTP. Checked by char code so the
- * source stays free of control bytes.
+ * commander value-parser for a value that ends up in an HTTP header (`--user-agent`):
+ * the library's headerValueProblem rule (not blank, no control character except tab,
+ * nothing above U+00FF), which the engine enforces when the client is built; here it
+ * only turns a bad value into an early usage error.
  */
 export declare function parseHeaderValue(value: string): string;
 /**
@@ -29,12 +37,11 @@ export declare function parseHeaderValue(value: string): string;
  */
 export declare function parsePathArg(value: string): string;
 /**
- * commander value-parser for `--base-url`: reject anything that is not a parseable
- * absolute `http:`/`https:` URL at *parse* time, so a bad scheme (`file:`, `ftp:`)
- * or malformed URL exits 2 (usage) — consistent with the blueprint — instead of
- * surfacing later as a runtime PegelNetworkError (exit 1). The transport still
- * enforces the same allowlist as the authoritative egress control; this only moves
- * the user-facing rejection earlier and to the correct exit code.
+ * commander value-parser for `--base-url`: the library's baseUrlProblem rule (no
+ * whitespace or control characters, an absolute http(s) URL, no query or
+ * fragment), reported at *parse* time as a usage error (exit 2). The engine
+ * enforces the same rule when the client is built, and the transport still gates
+ * the scheme on every hop as the authoritative egress control.
  */
 export declare function parseBaseUrl(value: string): string;
 /**
@@ -78,4 +85,3 @@ export interface ActionContext {
  * the trailing options object and command instance to recover the positionals.
  */
 export declare function action(deps: CliDeps, fn: (ctx: ActionContext, positionals: string[]) => Promise<void>): (...args: unknown[]) => Promise<void>;
-//# sourceMappingURL=shared.d.ts.map

package/dist/src/cli/shared.js

@@ -2,6 +2,7 @@
 // option resolver, and the JSON result renderer.
 import { InvalidArgumentError } from "commander";
 import { PegelError } from "../client/errors.js";
+import { baseUrlProblem, headerValueProblem, nonEmptyProblem } from "../client/validate.js";
 /** Help text of every `<station>` positional. */
 export const STATION_HELP = "station uuid, number, shortname or longname";
 /** commander value-parser: a non-negative integer. */
@@ -30,34 +31,43 @@ export function parseBoundedInt(min, max) {
     };
 }
 /**
- * commander value-parser: a value that is not blank. A blank filter would
- * otherwise be dropped and the command would silently run unfiltered.
+ * 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
+ * reads an empty parameter as no filter); here it only turns a blank value into an
+ * early usage error.
  */
 export function parseNonEmpty(value) {
-    if (value.trim() === "") {
-        throw new InvalidArgumentError("Expected a non-empty value.");
-    }
+    const reason = nonEmptyProblem(value);
+    if (reason !== undefined)
+        throw new InvalidArgumentError(reason);
     return value;
 }
 /**
- * commander value-parser for a value that ends up in an HTTP header (`--user-agent`).
- * Node's HTTP layer throws an opaque "Invalid character in header content" at request
- * time for a CR/LF (or any other C0 control or DEL) and for any character above
- * U+00FF, which surfaced as "Unexpected error". Reject those here as a usage error,
- * along with a blank value. Tab is allowed, as in HTTP. Checked by char code so the
- * source stays free of control bytes.
+ * commander value-parser for a value that ends up in an HTTP header (`--user-agent`):
+ * the library's headerValueProblem rule (not blank, no control character except tab,
+ * nothing above U+00FF), which the engine enforces when the client is built; here it
+ * only turns a bad value into an early usage error.
  */
 export function parseHeaderValue(value) {
-    parseNonEmpty(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.");
-        }
-        if (c > 0xff) {
-            throw new InvalidArgumentError("Value contains characters outside Latin-1 (above U+00FF).");
-        }
-    }
+    const reason = headerValueProblem(value);
+    if (reason !== undefined)
+        throw new InvalidArgumentError(reason);
     return value;
 }
 /**
@@ -75,34 +85,16 @@ export function parsePathArg(value) {
     return value;
 }
 /**
- * commander value-parser for `--base-url`: reject anything that is not a parseable
- * absolute `http:`/`https:` URL at *parse* time, so a bad scheme (`file:`, `ftp:`)
- * or malformed URL exits 2 (usage) — consistent with the blueprint — instead of
- * surfacing later as a runtime PegelNetworkError (exit 1). The transport still
- * enforces the same allowlist as the authoritative egress control; this only moves
- * the user-facing rejection earlier and to the correct exit code.
+ * commander value-parser for `--base-url`: the library's baseUrlProblem rule (no
+ * whitespace or control characters, an absolute http(s) URL, no query or
+ * fragment), reported at *parse* time as a usage error (exit 2). The engine
+ * enforces the same rule when the client is built, and the transport still gates
+ * the scheme on every hop as the authoritative egress control.
  */
 export function parseBaseUrl(value) {
-    let url;
-    try {
-        url = new URL(value);
-    }
-    catch {
-        throw new InvalidArgumentError("Expected an absolute http(s) URL.");
-    }
-    if (url.protocol !== "http:" && url.protocol !== "https:") {
-        throw new InvalidArgumentError("Only http and https URLs are supported.");
-    }
-    // Paths are appended to the base URL as a string, so a query or fragment would
-    // swallow every request path ("http://h/#f" requests "/" for every command).
-    if (/[?#]/.test(value)) {
-        throw new InvalidArgumentError("A base URL cannot have a query (?) or fragment (#).");
-    }
-    // new URL() trims surrounding whitespace silently; the raw value is what the
-    // engine uses, so reject it rather than guess.
-    if (value !== value.trim()) {
-        throw new InvalidArgumentError("A base URL cannot have surrounding whitespace.");
-    }
+    const reason = baseUrlProblem(value);
+    if (reason !== undefined)
+        throw new InvalidArgumentError(reason);
     return value;
 }
 /**
@@ -189,4 +181,3 @@ export function action(deps, fn) {
         await fn({ client, global, opts: command.opts() }, positionals);
     };
 }
-//# sourceMappingURL=shared.js.map

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

@@ -1,9 +1,21 @@
 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;
     constructor(e: RequestEngine);
+    /**
+     * Rejects (PegelValidationError, no request) a blank `waters` or `fuzzyId`, a
+     * blank `ids` entry and an empty `ids` array: the API reads an empty parameter as
+     * no filter and would answer with every station.
+     */
     list(params?: StationListParams): Promise<Station[]>;
     get(station: string, params?: IncludeParams): Promise<Station>;
 }
@@ -14,8 +26,42 @@ declare class TimeseriesResource {
     /** Timeseries metadata (e.g. "W" = water level, "Q" = flow). */
     get(station: string, timeseries?: string, params?: IncludeParams): Promise<TimeseriesInfo>;
     currentMeasurement(station: string, timeseries?: string): Promise<CurrentMeasurement>;
+    /** 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;
@@ -25,4 +71,3 @@ export declare class PegelOnlineClient {
     waters(): Promise<Water[]>;
 }
 export {};
-//# sourceMappingURL=client.d.ts.map