@maschinenlesbar.org/pegel-online-cli 0.0.7 → 0.1.0

package/README.md

@@ -86,16 +86,20 @@ level); other codes include `Q` (flow/discharge), `WT` (water temperature), and
 | `--waters <shortname>` | filter by water shortname (see `waters`) |
 | `--fuzzy-id <id>` | fuzzy match against short/long name |
 | `--include-timeseries` | embed each station's timeseries list |
-| `--include-current` | embed the current measurement |
-| `--include-characteristic` | embed characteristic (gauge-mark) values |
+| `--include-current` | embed the current measurement in each timeseries (implies `--include-timeseries`) |
+| `--include-characteristic` | embed characteristic (gauge-mark) values in each timeseries (implies `--include-timeseries`) |
 
 ### `stations get` options
 
 | Flag | Meaning |
 | --- | --- |
 | `--include-timeseries` | embed the station's timeseries list |
-| `--include-current` | embed the current measurement |
-| `--include-characteristic` | embed characteristic (gauge-mark) values |
+| `--include-current` | embed the current measurement in each timeseries (implies `--include-timeseries`) |
+| `--include-characteristic` | embed characteristic (gauge-mark) values in each timeseries (implies `--include-timeseries`) |
+
+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.
 
 ### `measurements` options
 
@@ -187,15 +191,23 @@ both `pegel --compact waters` and `pegel waters --compact` do the same thing.
   `PATH`. Run `npm bin -g` to find it and add it, or run via
   `npx @maschinenlesbar.org/pegel-online-cli …`.
 - **Exit `2` / "invalid argument"** — check the command syntax: a `<station>`
-  argument is required, and `--start` / `--end` must be valid ISO-8601 instants or
-  periods (e.g. `P7D`). Run `pegel <command> --help` for the exact signature.
-- **Exit `4` / "not found"** — the station shortname or id doesn't exist. Run
-  `pegel stations list --fuzzy-id <name>` or `pegel waters` to find the right
-  shortname.
+  argument is required, and no argument or option value may be blank (or `.` /
+  `..` for an id). Run `pegel <command> --help` for the exact signature.
+- **Exit `4` / "not found"** — the station shortname or id doesn't exist, or the
+  station doesn't publish the requested series (`Timeseries does not exist.` /
+  `Current measurement does not exist.`). Run `pegel stations list --fuzzy-id <name>`
+  or `pegel waters` to find the right shortname, and
+  `pegel stations get <station> --include-timeseries | jq -r '.timeseries[].shortname'`
+  to see which series codes it exposes.
+- **Exit `1` / `HTTP 400` on `measurements`** — `--start` / `--end` are not checked
+  locally; the API rejects a value that is not an ISO-8601 instant or period
+  (`Given start parameter is neither a valid ISO date time, nor an ISO period.`) and
+  a window whose start is not before its end (e.g. a start in the future). Use
+  `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`.
-- **Empty `timeseries` array** — the station doesn't publish the requested series.
-  Run `pegel timeseries <station>` to see which codes it actually exposes.
 
 ## Global options
 
@@ -206,10 +218,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`) |
+| `--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 |
 | `--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 |
-| `--max-retries <n>` | Retries for transient `429`/`503` responses (default `2`) |
+| `--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-response-bytes <n>` | Cap response body size in bytes (`0` = unlimited; default 100 MiB) |
 
 ## Learn more

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

@@ -1 +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"}
+{"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;AAmCxC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAkC7E"}

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

@@ -1,5 +1,5 @@
 import { Option } from "commander";
-import { action, parseNonEmpty, renderJson, requireArg } from "../shared.js";
+import { STATION_HELP, action, parseNonEmpty, parsePathArg, renderJson } from "../shared.js";
 /** commander accumulator for a repeatable string option. */
 function collect(value, previous = []) {
     return previous.concat([parseNonEmpty(value)]);
@@ -15,8 +15,8 @@ function includesFrom(opts) {
 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"));
+        .addOption(new Option("--include-current", "embed the current measurement in each timeseries (implies --include-timeseries)"))
+        .addOption(new Option("--include-characteristic", "embed characteristic (gauge-mark) values in each timeseries (implies --include-timeseries)"));
 }
 export function registerStationCommands(program, deps) {
     const stations = program.command("stations").description("Measuring stations");
@@ -36,10 +36,11 @@ export function registerStationCommands(program, deps) {
         renderJson(deps, global, await client.stations.list(params));
     }));
     const get = stations
-        .command("get <station>")
+        .command("get")
+        .argument("<station>", STATION_HELP, parsePathArg)
         .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)));
+        renderJson(deps, global, await client.stations.get(station, includesFrom(opts)));
     }));
 }
 //# sourceMappingURL=stations.js.map

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

@@ -1 +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,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG7E,4DAA4D;AAC5D,SAAS,OAAO,CAAC,KAAa,EAAE,QAAQ,GAAa,EAAE;IACrD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACjD,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,EAAE,aAAa,CAAC;SACzF,MAAM,CAAC,iBAAiB,EAAE,gBAAgB,EAAE,aAAa,CAAC,CAAC;IAC9D,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"}
+{"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,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG7F,4DAA4D;AAC5D,SAAS,OAAO,CAAC,KAAa,EAAE,QAAQ,GAAa,EAAE;IACrD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACjD,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,CACR,IAAI,MAAM,CACR,mBAAmB,EACnB,iFAAiF,CAClF,CACF;SACA,SAAS,CACR,IAAI,MAAM,CACR,0BAA0B,EAC1B,4FAA4F,CAC7F,CACF,CAAC;AACN,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,EAAE,aAAa,CAAC;SACzF,MAAM,CAAC,iBAAiB,EAAE,gBAAgB,EAAE,aAAa,CAAC,CAAC;IAC9D,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,KAAK,CAAC;SACd,QAAQ,CAAC,WAAW,EAAE,YAAY,EAAE,YAAY,CAAC;SACjD,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,OAAQ,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CACxD,CAAC;IACJ,CAAC,CAAC,CACH,CAAC;AACJ,CAAC"}

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

@@ -1 +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;AAMxC,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CA2DhF"}
+{"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;AAKxC,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CA2DhF"}

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

@@ -1,32 +1,31 @@
-import { action, parseNonEmpty, renderJson, requireArg, timeseriesOr } from "../shared.js";
-const STATION_HELP = "station uuid, number, shortname or longname";
+import { STATION_HELP, action, 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
         .command("timeseries")
-        .argument("<station>", STATION_HELP)
-        .argument("[timeseries]", TIMESERIES_HELP, parseNonEmpty)
+        .argument("<station>", STATION_HELP, parsePathArg)
+        .argument("[timeseries]", TIMESERIES_HELP, parsePathArg)
         .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)));
+        renderJson(deps, global, await client.timeseries.get(station, timeseriesOr(ts)));
     }));
     program
         .command("current")
-        .argument("<station>", STATION_HELP)
-        .argument("[timeseries]", TIMESERIES_HELP, parseNonEmpty)
+        .argument("<station>", STATION_HELP, parsePathArg)
+        .argument("[timeseries]", TIMESERIES_HELP, parsePathArg)
         .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)));
+        renderJson(deps, global, await client.timeseries.currentMeasurement(station, timeseriesOr(ts)));
     }));
     program
         .command("measurements")
-        .argument("<station>", STATION_HELP)
-        .argument("[timeseries]", TIMESERIES_HELP, parseNonEmpty)
+        .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)
         .action(action(deps, async ({ client, global, opts }, [station, ts]) => {
-        renderJson(deps, global, await client.timeseries.measurements(requireArg("station", station), timeseriesOr(ts), {
+        renderJson(deps, global, await client.timeseries.measurements(station, timeseriesOr(ts), {
             start: opts["start"],
             end: opts["end"],
         }));

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

@@ -1 +1 @@
-{"version":3,"file":"timeseries.js","sourceRoot":"","sources":["../../../../src/cli/commands/timeseries.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE3F,MAAM,YAAY,GAAG,6CAA6C,CAAC;AACnE,MAAM,eAAe,GAAG,wDAAwD,CAAC;AAEjF,MAAM,UAAU,0BAA0B,CAAC,OAAgB,EAAE,IAAa;IACxE,OAAO;SACJ,OAAO,CAAC,YAAY,CAAC;SACrB,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;SACnC,QAAQ,CAAC,cAAc,EAAE,eAAe,EAAE,aAAa,CAAC;SACxD,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,SAAS,CAAC;SAClB,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;SACnC,QAAQ,CAAC,cAAc,EAAE,eAAe,EAAE,aAAa,CAAC;SACxD,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,cAAc,CAAC;SACvB,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;SACnC,QAAQ,CAAC,cAAc,EAAE,eAAe,EAAE,aAAa,CAAC;SACxD,WAAW,CAAC,uDAAuD,CAAC;SACpE,MAAM,CAAC,eAAe,EAAE,sDAAsD,EAAE,aAAa,CAAC;SAC9F,MAAM,CAAC,aAAa,EAAE,8BAA8B,EAAE,aAAa,CAAC;SACpE,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,IAAI,CAAC,OAAO,CAAuB;YAC1C,GAAG,EAAE,IAAI,CAAC,KAAK,CAAuB;SACvC,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"}
+{"version":3,"file":"timeseries.js","sourceRoot":"","sources":["../../../../src/cli/commands/timeseries.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE3G,MAAM,eAAe,GAAG,wDAAwD,CAAC;AAEjF,MAAM,UAAU,0BAA0B,CAAC,OAAgB,EAAE,IAAa;IACxE,OAAO;SACJ,OAAO,CAAC,YAAY,CAAC;SACrB,QAAQ,CAAC,WAAW,EAAE,YAAY,EAAE,YAAY,CAAC;SACjD,QAAQ,CAAC,cAAc,EAAE,eAAe,EAAE,YAAY,CAAC;SACvD,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,OAAQ,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC,CACxD,CAAC;IACJ,CAAC,CAAC,CACH,CAAC;IAEJ,OAAO;SACJ,OAAO,CAAC,SAAS,CAAC;SAClB,QAAQ,CAAC,WAAW,EAAE,YAAY,EAAE,YAAY,CAAC;SACjD,QAAQ,CAAC,cAAc,EAAE,eAAe,EAAE,YAAY,CAAC;SACvD,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,OAAQ,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC,CACvE,CAAC;IACJ,CAAC,CAAC,CACH,CAAC;IAEJ,OAAO;SACJ,OAAO,CAAC,cAAc,CAAC;SACvB,QAAQ,CAAC,WAAW,EAAE,YAAY,EAAE,YAAY,CAAC;SACjD,QAAQ,CAAC,cAAc,EAAE,eAAe,EAAE,YAAY,CAAC;SACvD,WAAW,CAAC,uDAAuD,CAAC;SACpE,MAAM,CAAC,eAAe,EAAE,sDAAsD,EAAE,aAAa,CAAC;SAC9F,MAAM,CAAC,aAAa,EAAE,8BAA8B,EAAE,aAAa,CAAC;SACpE,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,OAAQ,EAAE,YAAY,CAAC,EAAE,CAAC,EAAE;YAC/D,KAAK,EAAE,IAAI,CAAC,OAAO,CAAuB;YAC1C,GAAG,EAAE,IAAI,CAAC,KAAK,CAAuB;SACvC,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.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 // Binary entry point. Thin shim around run(); all logic lives in run.ts/program.ts.
+import { handleOutputErrors } from "./io.js";
 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/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AACA,oFAAoF;AAEpF,OAAO,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,kBAAkB,EAAE,CAAC;AACrB,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

@@ -9,5 +9,22 @@ export interface CliDeps {
     /** Build a client from the resolved global options (injectable for tests). */
     createClient(options: EngineOptions): PegelOnlineClient;
 }
+/** The two process streams, as far as `handleOutputErrors` needs them. */
+export interface OutputStreams {
+    stdout: Pick<NodeJS.WriteStream, "on">;
+    stderr: Pick<NodeJS.WriteStream, "on">;
+}
+/**
+ * Handle write errors on stdout/stderr, which Node otherwise reports as an
+ * unhandled 'error' event: a raw stack trace and exit 1.
+ *
+ * A reader that stops early — `| head`, `| jq` exiting on the first match, a closed
+ * 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).
+ * 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.d.ts.map

@@ -1 +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"}
+{"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,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IACvC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;CACxC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,aAAuB,EAChC,IAAI,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAmC,GAC1D,IAAI,CASN;AAED,eAAO,MAAM,SAAS,EAAE,KAGvB,CAAC"}

package/dist/src/cli/io.js

@@ -1,5 +1,27 @@
 // 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.
+/**
+ * Handle write errors on stdout/stderr, which Node otherwise reports as an
+ * unhandled 'error' event: a raw stack trace and exit 1.
+ *
+ * A reader that stops early — `| head`, `| jq` exiting on the first match, a closed
+ * 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).
+ * The bin shim installs this once, before `run()`.
+ */
+export function handleOutputErrors(streams = process, exit = (code) => process.exit(code)) {
+    streams.stdout.on("error", (err) => {
+        if (err.code === "EPIPE")
+            return exit(0);
+        process.stderr.write(`Output error: ${err.message}\n`);
+        exit(1);
+    });
+    streams.stderr.on("error", (err) => {
+        exit(err.code === "EPIPE" ? 0 : 1);
+    });
+}
 export const defaultIO = {
     out: (text) => process.stdout.write(text + "\n"),
     err: (text) => process.stderr.write(text + "\n"),

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

@@ -1 +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"}
+{"version":3,"file":"io.js","sourceRoot":"","sources":["../../../src/cli/io.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,sEAAsE;AAsBtE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAO,GAAkB,OAAO,EAChC,IAAI,GAA2B,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;IAE3D,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAA0B,EAAE,EAAE;QACxD,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;QACzC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;QACvD,IAAI,CAAC,CAAC,CAAC,CAAC;IACV,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAA0B,EAAE,EAAE;QACxD,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,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.map

@@ -1 +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;AAwBvC,eAAO,MAAM,OAAO,QAAgB,CAAC;AAErC,yEAAyE;AACzE,eAAO,MAAM,WAAW,EAAE,OAGzB,CAAC;AAEF,wBAAgB,YAAY,CAAC,IAAI,GAAE,OAAqB,GAAG,OAAO,CA8BjE"}
+{"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;AAyBvC,eAAO,MAAM,OAAO,QAAgB,CAAC;AAErC,yEAAyE;AACzE,eAAO,MAAM,WAAW,EAAE,OAGzB,CAAC;AAEF,wBAAgB,YAAY,CAAC,IAAI,GAAE,OAAqB,GAAG,OAAO,CAkCjE"}

package/dist/src/cli/program.js

@@ -7,7 +7,8 @@ import { Command } from "commander";
 import { defaultIO } from "./io.js";
 import { PegelOnlineClient } from "../client/client.js";
 import { MAX_TIMEOUT_MS } from "../client/http.js";
-import { parseBoundedInt, parseIntArg, parseBaseUrl } from "./shared.js";
+import { MAX_RETRIES } from "../client/engine.js";
+import { parseBoundedInt, parseIntArg, parseBaseUrl, parseHeaderValue } from "./shared.js";
 import { registerStationCommands } from "./commands/stations.js";
 import { registerTimeseriesCommands } from "./commands/timeseries.js";
 /**
@@ -41,8 +42,8 @@ export function buildProgram(deps = defaultDeps) {
         .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")
-        .option("--max-retries <n>", "retries for transient 429/503 responses", parseIntArg)
+        .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("--compact", "print JSON on a single line instead of pretty-printed")
         .showHelpAfterError();

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

@@ -1 +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,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACzE,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,OAAO,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,IAAI,GAAY,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,YAAY,EAAE,gCAAgC,CAAC;SAC1F,MAAM,CACL,gBAAgB,EAChB,iEAAiE,EACjE,eAAe,CAAC,CAAC,EAAE,cAAc,CAAC,CACnC;SACA,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"}
+{"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,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC3F,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,OAAO,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,IAAI,GAAY,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,YAAY,EAAE,gCAAgC,CAAC;SAC1F,MAAM,CACL,gBAAgB,EAChB,iEAAiE,EACjE,eAAe,CAAC,CAAC,EAAE,cAAc,CAAC,CACnC;SACA,MAAM,CAAC,mBAAmB,EAAE,yBAAyB,EAAE,gBAAgB,CAAC;SACxE,MAAM,CACL,mBAAmB,EACnB,kGAAkG,EAClG,eAAe,CAAC,CAAC,EAAE,WAAW,CAAC,CAChC;SACA,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/shared.d.ts

@@ -1,5 +1,7 @@
 import type { CliDeps } from "./io.js";
 import type { EngineOptions } from "../client/engine.js";
+/** Help text of every `<station>` positional. */
+export declare const STATION_HELP = "station uuid, number, shortname or longname";
 /** commander value-parser: a non-negative integer. */
 export declare function parseIntArg(value: string): number;
 /** Build a commander value-parser for an integer constrained to [min, max]. */
@@ -9,6 +11,23 @@ export declare function parseBoundedInt(min: number, max: number): (value: strin
  * otherwise be dropped and the command would silently run unfiltered.
  */
 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.
+ */
+export declare function parseHeaderValue(value: string): string;
+/**
+ * commander value-parser for an id that becomes a URL path segment (the
+ * `<station>` and `[timeseries]` positionals): not blank (which would build
+ * `/stations//W/...`), and not "." / "..", which
+ * encodeURIComponent leaves untouched and URL parsing would resolve, sending the
+ * request to a different resource. A usage error, before any request.
+ */
+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:`)
@@ -18,12 +37,6 @@ export declare function parseNonEmpty(value: string): string;
  * the user-facing rejection earlier and to the correct exit code.
  */
 export declare function parseBaseUrl(value: string): string;
-/**
- * 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;
 /**
  * Default an omitted optional `[timeseries]` positional to "W" (water level),
  * matching the documented default. A blank value never reaches here: the

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

@@ -1 +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,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAQnF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAWlD;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;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWvD;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"}
+{"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,iDAAiD;AACjD,eAAO,MAAM,YAAY,gDAAgD,CAAC;AAE1E,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAajD;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAQnF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYtD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqBlD;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;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWvD;AAyBD,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"}

package/dist/src/cli/shared.js

@@ -2,6 +2,8 @@
 // option resolver, and the JSON result renderer.
 import { InvalidArgumentError } from "commander";
 import { PegelError } from "../client/errors.js";
+/** Help text of every `<station>` positional. */
+export const STATION_HELP = "station uuid, number, shortname or longname";
 /** commander value-parser: a non-negative integer. */
 export function parseIntArg(value) {
     // Require a plain decimal integer. Reject blank/whitespace ("" and " " coerce
@@ -37,6 +39,41 @@ export function parseNonEmpty(value) {
     }
     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.
+ */
+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).");
+        }
+    }
+    return value;
+}
+/**
+ * commander value-parser for an id that becomes a URL path segment (the
+ * `<station>` and `[timeseries]` positionals): not blank (which would build
+ * `/stations//W/...`), and not "." / "..", which
+ * encodeURIComponent leaves untouched and URL parsing would resolve, sending the
+ * request to a different resource. A usage error, before any request.
+ */
+export function parsePathArg(value) {
+    parseNonEmpty(value);
+    if (value === "." || value === "..") {
+        throw new InvalidArgumentError('"." and ".." cannot be used as an id.');
+    }
+    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:`)
@@ -56,21 +93,15 @@ export function parseBaseUrl(value) {
     if (url.protocol !== "http:" && url.protocol !== "https:") {
         throw new InvalidArgumentError("Only http and https URLs are supported.");
     }
-    return value;
-}
-/**
- * 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 function requireArg(name, value) {
-    if (value === undefined || value.trim() === "") {
-        throw new PegelError(`Missing required <${name}> argument.`);
+    // 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 (#).");
     }
-    // Reject "." / ".." which encodeURIComponent leaves untouched and which would
-    // otherwise inject a relative path segment into the request URL.
-    if (value === "." || value === "..") {
-        throw new PegelError(`Invalid <${name}> argument: "${value}".`);
+    // 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.");
     }
     return value;
 }
@@ -116,9 +147,29 @@ export function escapeControlChars(json) {
     }
     return from === 0 ? json : result + json.slice(from);
 }
+/**
+ * JSON.stringify, pretty or compact. A deeply nested value (a hostile or broken
+ * response) overflows the stack — the pretty form far sooner than the compact one,
+ * which is why the message suggests --compact. The RangeError becomes a PegelError so
+ * the CLI prints a clear message instead of "Unexpected error: Maximum call stack
+ * size exceeded".
+ */
+function stringifyJson(value, compact) {
+    try {
+        return compact ? JSON.stringify(value) : JSON.stringify(value, null, 2);
+    }
+    catch (err) {
+        if (err instanceof RangeError) {
+            throw new PegelError(compact
+                ? "The response is nested too deeply to print."
+                : "The response is nested too deeply to pretty-print; try --compact.", { cause: err });
+        }
+        throw err;
+    }
+}
 /** Render a JSON value to stdout, pretty by default, compact with --compact. */
 export function renderJson(deps, global, value) {
-    const text = escapeControlChars(global.compact ? JSON.stringify(value) : JSON.stringify(value, null, 2));
+    const text = escapeControlChars(stringifyJson(value, global.compact === true));
     deps.io.out(text);
 }
 /**

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

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

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

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/client/client.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,KAAK,EACV,OAAO,EACP,KAAK,EACL,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAsBpB,mFAAmF;AACnF,cAAM,gBAAgB;IACR,OAAO,CAAC,QAAQ,CAAC,CAAC;IAA9B,YAA6B,CAAC,EAAE,aAAa,EAAI;IAEjD,IAAI,CAAC,MAAM,GAAE,iBAAsB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAUvD;IAED,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAEjE;CACF;AAED,4FAA4F;AAC5F,cAAM,kBAAkB;IACV,OAAO,CAAC,QAAQ,CAAC,CAAC;IAA9B,YAA6B,CAAC,EAAE,aAAa,EAAI;IAEjD,gEAAgE;IAChE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,SAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAK1F;IAED,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,SAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAIjF;IAED,YAAY,CACV,OAAO,EAAE,MAAM,EACf,UAAU,SAAM,EAChB,MAAM,GAAE,kBAAuB,GAC9B,OAAO,CAAC,WAAW,EAAE,CAAC,CAKxB;CACF;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IAEvC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IAExC,YAAY,OAAO,GAAE,aAAkB,EAItC;IAED,kEAAkE;IAClE,MAAM,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAEzB;CACF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/client/client.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAGhE,OAAO,KAAK,EACV,OAAO,EACP,KAAK,EACL,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAC;AA8DpB,mFAAmF;AACnF,cAAM,gBAAgB;IACR,OAAO,CAAC,QAAQ,CAAC,CAAC;IAA9B,YAA6B,CAAC,EAAE,aAAa,EAAI;IAEjD,IAAI,CAAC,MAAM,GAAE,iBAAsB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAQvD;IAEK,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAEvE;CACF;AAED,4FAA4F;AAC5F,cAAM,kBAAkB;IACV,OAAO,CAAC,QAAQ,CAAC,CAAC;IAA9B,YAA6B,CAAC,EAAE,aAAa,EAAI;IAEjD,gEAAgE;IAC1D,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,SAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAKhG;IAEK,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,SAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAIvF;IAEK,YAAY,CAChB,OAAO,EAAE,MAAM,EACf,UAAU,SAAM,EAChB,MAAM,GAAE,kBAAuB,GAC9B,OAAO,CAAC,WAAW,EAAE,CAAC,CAKxB;CACF;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IAEvC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IAExC,YAAY,OAAO,GAAE,aAAkB,EAItC;IAED,kEAAkE;IAClE,MAAM,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC,CAEzB;CACF"}

package/dist/src/client/client.js

@@ -6,8 +6,32 @@
 //   client.timeseries.currentMeasurement("BONN", "W")
 //   client.timeseries.measurements("BONN", "W", { start: "P3D" })
 import { RequestEngine } from "./engine.js";
+import { PegelError } from "./errors.js";
 const API = "/webservices/rest-api/v2";
-const enc = encodeURIComponent;
+/**
+ * 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
+ * "." / ".." pass encodeURIComponent unchanged and are resolved by URL parsing
+ * (the engine's `buildUrl` refuses them as path segments too), so all are refused.
+ */
+function enc(name, value) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new PegelError(`Invalid ${name}: expected a non-empty string, got ${JSON.stringify(value)}.`);
+    }
+    if (value === "." || value === "..") {
+        throw new PegelError(`Invalid ${name} "${value}": "." and ".." cannot be used as an id.`);
+    }
+    return encodeURIComponent(nfc(value));
+}
 /** Drop undefined values so only the parameters the caller set are sent. */
 function prune(params) {
     const out = {};
@@ -17,6 +41,20 @@ function prune(params) {
     }
     return out;
 }
+/**
+ * The station include parameters. The API nests the current measurement and the
+ * gauge marks *inside* each timeseries, so without `includeTimeseries=true` it
+ * silently drops both. Asking for either therefore implies `includeTimeseries`
+ * unless the caller set it explicitly.
+ */
+function stationIncludes(p) {
+    const nested = p.includeCurrentMeasurement === true || p.includeCharacteristicValues === true;
+    return prune({
+        includeTimeseries: p.includeTimeseries ?? (nested ? true : undefined),
+        includeCurrentMeasurement: p.includeCurrentMeasurement,
+        includeCharacteristicValues: p.includeCharacteristicValues,
+    });
+}
 function includeQuery(p) {
     return prune({
         includeTimeseries: p.includeTimeseries,
@@ -32,17 +70,15 @@ class StationsResource {
     }
     list(params = {}) {
         const query = prune({
-            ids: params.ids && params.ids.length > 0 ? params.ids.join(",") : undefined,
-            waters: params.waters,
-            fuzzyId: params.fuzzyId,
-            includeTimeseries: params.includeTimeseries,
-            includeCurrentMeasurement: params.includeCurrentMeasurement,
-            includeCharacteristicValues: params.includeCharacteristicValues,
+            ids: params.ids && params.ids.length > 0 ? params.ids.map(nfc).join(",") : undefined,
+            waters: params.waters === undefined ? undefined : nfc(params.waters),
+            fuzzyId: params.fuzzyId === undefined ? undefined : nfc(params.fuzzyId),
+            ...stationIncludes(params),
         });
         return this.e.getJson(`${API}/stations.json`, query);
     }
-    get(station, params = {}) {
-        return this.e.getJson(`${API}/stations/${enc(station)}.json`, includeQuery(params));
+    async get(station, params = {}) {
+        return this.e.getJson(`${API}/stations/${enc("station", station)}.json`, stationIncludes(params));
     }
 }
 /** Timeseries: metadata, the current measurement, a window of measurements, gauge marks. */
@@ -52,14 +88,14 @@ class TimeseriesResource {
         this.e = e;
     }
     /** Timeseries metadata (e.g. "W" = water level, "Q" = flow). */
-    get(station, timeseries = "W", params = {}) {
-        return this.e.getJson(`${API}/stations/${enc(station)}/${enc(timeseries)}.json`, includeQuery(params));
+    async get(station, timeseries = "W", params = {}) {
+        return this.e.getJson(`${API}/stations/${enc("station", station)}/${enc("timeseries", timeseries)}.json`, includeQuery(params));
     }
-    currentMeasurement(station, timeseries = "W") {
-        return this.e.getJson(`${API}/stations/${enc(station)}/${enc(timeseries)}/currentmeasurement.json`);
+    async currentMeasurement(station, timeseries = "W") {
+        return this.e.getJson(`${API}/stations/${enc("station", station)}/${enc("timeseries", timeseries)}/currentmeasurement.json`);
     }
-    measurements(station, timeseries = "W", params = {}) {
-        return this.e.getJson(`${API}/stations/${enc(station)}/${enc(timeseries)}/measurements.json`, prune({ start: params.start, end: params.end }));
+    async measurements(station, timeseries = "W", params = {}) {
+        return this.e.getJson(`${API}/stations/${enc("station", station)}/${enc("timeseries", timeseries)}/measurements.json`, prune({ start: params.start, end: params.end }));
     }
 }
 export class PegelOnlineClient {