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

package/dist/src/client/errors.js

@@ -10,7 +10,9 @@ export class PegelError extends Error {
 /**
  * Replace the userinfo of a URL (`https://user:secret@host/...`) with `***`, so a
  * credential in a base URL never reaches an error message, a log or CI output.
- * A URL without userinfo, or one that does not parse, is returned unchanged.
+ * A value that does not parse as a URL (a port typo, an unencoded "#" in the
+ * password) or has no scheme (`user:pw@host`) is cut by text instead
+ * (`credentialsIn` + `redactCredentials`); one without userinfo is returned unchanged.
  */
 export function redactUrl(url) {
     let parsed;
@@ -18,14 +20,63 @@ export function redactUrl(url) {
         parsed = new URL(url);
     }
     catch {
-        return url;
+        return redactCredentials(url, credentialsIn(url));
     }
+    // `user:pw@host` without a scheme parses as a URL with the scheme "user:": no userinfo.
     if (parsed.username === "" && parsed.password === "")
-        return url;
+        return redactCredentials(url, credentialsIn(url));
     parsed.username = "***";
     parsed.password = "";
     return parsed.href;
 }
+/**
+ * The userinfo a URL-like value carries, exactly as written — `["alice:pa#ss"]` for
+ * `https://alice:pa#ss@host` — or `[]` when it carries none. It works on values that
+ * don't parse as a URL too, and on values with a prefix (`--base-url=https://u:p@h`):
+ * the userinfo is everything between `://` and the last `@` before the host. A value
+ * without a scheme counts when it reads `user:password@host`. Used to redact those
+ * exact strings from text that echoes the value (usage errors, help), whatever
+ * characters the password contains.
+ */
+export function credentialsIn(value) {
+    const schemeAt = value.indexOf("://");
+    const rest = schemeAt >= 0 ? value.slice(schemeAt + 3) : value;
+    // Without a scheme only the unmistakable `user:password@host` form counts.
+    if (schemeAt < 0 && !/^[^\s/@:]+:[^@]*@[^@\s/]/.test(rest))
+        return [];
+    // The URL itself starts at its scheme (`--base-url=https://…` has a prefix).
+    const scheme = schemeAt >= 0 ? /[a-z][a-z0-9+.-]*$/i.exec(value.slice(0, schemeAt)) : null;
+    let parses = false;
+    try {
+        new URL(schemeAt >= 0 ? value.slice(scheme?.index ?? schemeAt) : `http://${rest}`);
+        parses = true;
+    }
+    catch {
+        // Doesn't parse: the password may hold "/", "?", "#" or spaces.
+    }
+    // In a URL that parses, the userinfo ends at the last "@" of the authority (before
+    // the first "/", "?" or "#"); in one that doesn't, at the last "@" of the value.
+    const authority = parses ? rest.slice(0, rest.search(/[/?#]|$/)) : rest;
+    const end = authority.lastIndexOf("@");
+    return end > 0 ? [rest.slice(0, end)] : [];
+}
+/**
+ * `text` with every occurrence of each credential (as `credentialsIn` returns them)
+ * that is followed by `@` replaced by `***`. Matching the exact strings, not a
+ * pattern, covers passwords with spaces, quotes, `#`, `?` or `/` that no URL pattern
+ * can delimit. The percent-encoded form (`alice%3Apw%40`, as a URL typed where a
+ * station id belongs ends up in a request path) is replaced too.
+ */
+export function redactCredentials(text, credentials) {
+    let out = text;
+    for (const secret of credentials) {
+        if (secret === "")
+            continue;
+        out = out.split(`${secret}@`).join("***@");
+        out = out.split(`${encodeURIComponent(secret)}%40`).join("***%40");
+    }
+    return out;
+}
 /**
  * The API responded with a non-2xx status code. `detail` holds a human-readable
  * message extracted from the response body when one is present.
@@ -42,6 +93,12 @@ export class PegelApiError extends PegelError {
      * redacted. The message names it.
      */
     location;
+    /**
+     * For a 429/503 that was not retried because its `Retry-After` asked for longer than
+     * the client waits (`MAX_RETRY_AFTER_MS`, 30 s): the wait the server asked for, in
+     * milliseconds. Retrying before then won't help.
+     */
+    retryAfterMs;
     constructor(args) {
         const parts = [];
         if (args.detail)
@@ -54,6 +111,12 @@ export class PegelApiError extends PegelError {
                 ? `redirect to ${args.location} not followed${limit}`
                 : "redirect not followed (no Location header)");
         }
+        if (args.retryAfterMs !== undefined) {
+            parts.push(`the server asked to wait ${Math.ceil(args.retryAfterMs / 1000)} s (Retry-After), longer than the 30 s ` +
+                "the client waits, so it was not retried; try again after that");
+        }
+        if (args.hint)
+            parts.push(args.hint);
         const detailPart = parts.length > 0 ? `: ${parts.join("; ")}` : "";
         // The URL is shown without userinfo: a credential in --base-url must not leak.
         const url = redactUrl(args.url);
@@ -64,6 +127,7 @@ export class PegelApiError extends PegelError {
         this.body = args.body;
         this.detail = args.detail;
         this.location = args.location;
+        this.retryAfterMs = args.retryAfterMs;
     }
     /** True for statuses the API documents as transient and retry-able. */
     get isRetryable() {

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

@@ -6,17 +6,43 @@ export interface HttpRequest {
     headers?: Record<string, string>;
     /** Optional request body (already serialised). */
     body?: string | Buffer;
+    /**
+     * Always `"manual"`: a transport must not follow redirects itself (fetch does by
+     * default — pass `redirect: request.redirect`). The engine follows them, keeping the
+     * base URL's credentials on the same origin and dropping them, and credential headers,
+     * on another. A response whose `url` (the final URL a fetch transport may report) lies
+     * on another origin than the request is rejected as a PegelNetworkError.
+     */
+    redirect?: "manual";
     /** Timeout for the whole request, response body included, in milliseconds. */
     timeoutMs?: number;
     /** Hard cap on the response body size in bytes; the request aborts if exceeded. */
     maxResponseBytes?: number;
+    /**
+     * Aborted when the engine's overall deadline (`timeoutMs`) passes. A transport should
+     * stop the request then (`fetch(url, { signal })`); the engine rejects at the deadline
+     * either way, and enforces `maxResponseBytes` on the body it gets back, so neither
+     * limit depends on it.
+     */
+    signal?: AbortSignal;
 }
+/**
+ * What a transport resolves with. The engine is lenient about the shapes a custom
+ * transport naturally returns: `headers` may be a plain record in any letter case, a
+ * WHATWG `Headers` object or a `Map`; `body` may be a Buffer, any `ArrayBuffer` view
+ * (fetch's `Uint8Array`, from any realm) or an `ArrayBuffer`. Anything else, or a
+ * `status` outside 100–599, is a PegelNetworkError.
+ */
 export interface HttpResponse {
     status: number;
     headers: http.IncomingHttpHeaders;
     body: Buffer;
+    /** The URL that answered, if the transport knows it (fetch's `Response.url`). */
+    url?: string;
 }
 export type Transport = (request: HttpRequest) => Promise<HttpResponse>;
+/** The message for a body over the size cap, naming the option on both sides. */
+export declare function sizeLimitMessage(maxBytes: number): string;
 /**
  * The longest delay Node's timers support (2^31 - 1 ms, about 24.8 days). A longer one
  * prints a TimeoutOverflowWarning and fires after 1 ms, so timeouts are capped here.

package/dist/src/client/http.js

@@ -8,6 +8,10 @@
 import http from "node:http";
 import https from "node:https";
 import { PegelNetworkError, redactUrl } from "./errors.js";
+/** The message for a body over the size cap, naming the option on both sides. */
+export function sizeLimitMessage(maxBytes) {
+    return `Response exceeded the size limit of ${maxBytes} bytes (maxResponseBytes; --max-response-bytes on the CLI)`;
+}
 /**
  * The longest delay Node's timers support (2^31 - 1 ms, about 24.8 days). A longer one
  * prints a TimeoutOverflowWarning and fires after 1 ms, so timeouts are capped here.
@@ -71,7 +75,7 @@ export const nodeHttpTransport = (request) => new Promise((resolve, reject) => {
             if (maxBytes !== undefined && received > maxBytes) {
                 aborted = true;
                 res.destroy();
-                settleReject(new PegelNetworkError(`Response exceeded maxResponseBytes (${maxBytes})`));
+                settleReject(new PegelNetworkError(sizeLimitMessage(maxBytes)));
                 return;
             }
             chunks.push(chunk);
@@ -101,6 +105,17 @@ export const nodeHttpTransport = (request) => new Promise((resolve, reject) => {
         // Do not let the deadline timer alone keep the process alive.
         deadlineTimer.unref?.();
     }
+    if (request.signal !== undefined) {
+        const abort = () => {
+            const err = new PegelNetworkError(`Request timed out after ${request.timeoutMs ?? 0}ms`);
+            settleReject(err);
+            req.destroy(err);
+        };
+        if (request.signal.aborted)
+            abort();
+        else
+            request.signal.addEventListener("abort", abort, { once: true });
+    }
     req.on("error", (err) => {
         // A timeout destroy already passes an PegelNetworkError; don't double-wrap.
         settleReject(err instanceof PegelNetworkError ? err : new PegelNetworkError(err.message, { cause: err }));

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

@@ -1,11 +1,12 @@
-export { PegelOnlineClient } from "./client.js";
-export { RequestEngine, DEFAULT_BASE_URL, MAX_RETRIES, MAX_RETRY_AFTER_MS, parseRetryAfter, validateBaseUrl, } from "./engine.js";
+export { NO_VALUE_SENTINEL, PegelOnlineClient, stationListNotes } from "./client.js";
+export type { StationListNote } from "./client.js";
+export { RequestEngine, DEFAULT_BASE_URL, MAX_RETRIES, MAX_RETRY_AFTER_MS, isTransientNetworkError, parseRetryAfter, validateBaseUrl, } from "./engine.js";
 export type { EngineOptions, RawResponse } from "./engine.js";
 export { MAX_TIMEOUT_MS, nodeHttpTransport } from "./http.js";
 export type { Transport, HttpRequest, HttpResponse } from "./http.js";
 export { buildQueryString } from "./query.js";
 export type { QueryParams, QueryValue } from "./query.js";
-export { PegelError, PegelApiError, PegelNetworkError, PegelParseError, PegelValidationError, redactUrl, } from "./errors.js";
-export { assertValid, baseUrlProblem, baseUrlWhitespaceProblem, headerValueProblem, idListProblem, isBlank, nonEmptyProblem, } from "./validate.js";
+export { PegelError, PegelApiError, PegelNetworkError, PegelParseError, PegelValidationError, redactUrl, credentialsIn, redactCredentials, } from "./errors.js";
+export { assertValid, baseUrlProblem, baseUrlWhitespaceProblem, headerValueProblem, idListProblem, isBlank, knownKeysProblem, nonEmptyProblem, normalizeInput, optionalBooleanProblem, } from "./validate.js";
 export type { Problem } from "./validate.js";
 export * from "./types.js";

package/dist/src/client/index.js

@@ -1,8 +1,8 @@
 // Public entry point for the API client library.
-export { PegelOnlineClient } from "./client.js";
-export { RequestEngine, DEFAULT_BASE_URL, MAX_RETRIES, MAX_RETRY_AFTER_MS, parseRetryAfter, validateBaseUrl, } from "./engine.js";
+export { NO_VALUE_SENTINEL, PegelOnlineClient, stationListNotes } from "./client.js";
+export { RequestEngine, DEFAULT_BASE_URL, MAX_RETRIES, MAX_RETRY_AFTER_MS, isTransientNetworkError, parseRetryAfter, validateBaseUrl, } from "./engine.js";
 export { MAX_TIMEOUT_MS, nodeHttpTransport } from "./http.js";
 export { buildQueryString } from "./query.js";
-export { PegelError, PegelApiError, PegelNetworkError, PegelParseError, PegelValidationError, redactUrl, } from "./errors.js";
-export { assertValid, baseUrlProblem, baseUrlWhitespaceProblem, headerValueProblem, idListProblem, isBlank, nonEmptyProblem, } from "./validate.js";
+export { PegelError, PegelApiError, PegelNetworkError, PegelParseError, PegelValidationError, redactUrl, credentialsIn, redactCredentials, } from "./errors.js";
+export { assertValid, baseUrlProblem, baseUrlWhitespaceProblem, headerValueProblem, idListProblem, isBlank, knownKeysProblem, nonEmptyProblem, normalizeInput, optionalBooleanProblem, } from "./validate.js";
 export * from "./types.js";

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

@@ -24,14 +24,32 @@ export interface Station {
     water?: Water;
     timeseries?: TimeseriesInfo[];
 }
+/**
+ * The API's classification of a current water level (`stateMnwMhw`, `stateNswHsw`), as
+ * documented upstream:
+ * - `low` — at or below MNW (stateMnwMhw only);
+ * - `normal` — between MNW and MHW, or between 0 and HSW;
+ * - `high` — at or above MHW, or HSW;
+ * - `unknown` — the series has no MNW/MHW (or HSW) mark to compare with;
+ * - `commented` — **gauge malfunction or disruption** ("Fehlfunktion oder Störung"): the
+ *   value may be wrong; the reason is in the series' `comment` (`TimeseriesInfo.comment`);
+ * - `out-dated` — the reading is older than 25 hours.
+ * Typed open (`string & {}`) so a value the API adds later still type-checks.
+ */
+export type MeasurementState = "low" | "normal" | "high" | "unknown" | "commented" | "out-dated" | (string & {});
 /** A measurement value plus the API's state classifications. */
 export interface CurrentMeasurement {
     timestamp: string;
-    value: number;
-    /** Classification vs. the mean low/high water marks. */
-    stateMnwMhw?: string;
-    /** Classification vs. the lowest/highest navigable water marks. */
-    stateNswHsw?: string;
+    /**
+     * The reading, in the unit of its timeseries (`TimeseriesInfo.unit` — not always `cm`
+     * for `W`). `null` when the gauge reported no value: the client maps the sentinel
+     * `99999` (`NO_VALUE_SENTINEL`) the API relays for that to `null`.
+     */
+    value: number | null;
+    /** Classification vs. the mean low/high water marks (water levels only). */
+    stateMnwMhw?: MeasurementState;
+    /** Classification vs. the lowest/highest navigable water marks (water levels only). */
+    stateNswHsw?: MeasurementState;
 }
 /** The datum a water-level series is measured from (Pegelnullpunkt). */
 export interface GaugeZero {
@@ -41,14 +59,37 @@ export interface GaugeZero {
     /** Date the datum applies from, e.g. "2019-11-01". */
     validFrom?: string;
 }
+/**
+ * An operator's note on a timeseries, present while something is wrong with it — e.g.
+ * "Funktionsstörung, fehlerhafte Messwerte" (malfunction, faulty readings) at RINTELN,
+ * "Techn. Störung", "Behelfspegel - Messwerte können Fehler aufweisen" (temporary gauge,
+ * values may be wrong), "vorübergehend außer Betrieb". A current measurement whose state
+ * is `commented` points here.
+ */
+export interface TimeseriesComment {
+    shortDescription: string;
+    longDescription?: string;
+}
 /** Metadata for one timeseries of a station (e.g. "W" water level, "Q" flow). */
 export interface TimeseriesInfo {
     shortname: string;
     longname: string;
+    /**
+     * The unit of every value of this series, as the API publishes it. Read it; never
+     * assume it from the shortname: most `W` (water level) series are in `cm`, but canal
+     * and reservoir gauges publish `W` in `m+NN` (metres above sea level) or `m+PNP`
+     * (metres above the gauge zero) — 69 of 737 W series on 5 October 2026, e.g. MÜNSTER OW
+     * at 56.54 m+NN. `Q` is usually `m³/s`, temperatures `°C`.
+     */
     unit: string;
     equidistance?: number;
     /** Gauge zero of a water-level series (absent on e.g. flow series). */
     gaugeZero?: GaugeZero;
+    /**
+     * The operator's note while the series is disturbed (see {@link TimeseriesComment});
+     * absent otherwise. Read it whenever a reading's state is `commented`.
+     */
+    comment?: TimeseriesComment;
     currentMeasurement?: CurrentMeasurement;
     /**
      * Characteristic values (gauge marks), present only when requested; an empty
@@ -59,13 +100,19 @@ export interface TimeseriesInfo {
 /** One point of a measurements series. */
 export interface Measurement {
     timestamp: string;
-    value: number;
+    /**
+     * The reading in the timeseries' unit, or `null` for a point without a value (the
+     * sentinel `99999`, mapped by the client). Skip `null` points before a minimum, maximum
+     * or trend.
+     */
+    value: number | null;
 }
 /** Parameters for the stations listing. */
 export interface StationListParams {
     /**
      * Station identifiers (uuid/number/shortname/longname); sent comma-separated.
-     * At least one, none blank.
+     * At least one, none blank. A name may match more than one station (NEUSTADT: LEINE
+     * and OSTSEE) and an unknown one matches none, silently: `stationListNotes` reports both.
      */
     ids?: string[];
     /** Water shortname filter; not blank. */

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

@@ -8,6 +8,16 @@ export type Problem<T = unknown> = (value: T) => string | undefined;
  * synchronous throw.
  */
 export declare function assertValid<T>(name: string, value: T, problem: Problem<T>): T;
+/**
+ * The form in which an id, name or filter value is sent: surrounding whitespace removed
+ * and composed (NFC). The API matches station names, waters and ids exactly, so
+ * `"RHEIN "` (a trailing space from a copy) listed no station and `"BONN "` was a 404, and
+ * a decomposed umlaut ("KO" + U+0308 + "LN", as pasted from macOS file names or some
+ * PDFs) found nothing either; no name upstream begins or ends with whitespace. NFC, not
+ * NFKC: an id lookup must not rewrite compatibility characters, and case is left alone
+ * (the API ignores it for station ids, but not everywhere).
+ */
+export declare function normalizeInput(value: string): string;
 /** True for an empty or whitespace-only string. */
 export declare function isBlank(value: string): boolean;
 /**
@@ -32,8 +42,9 @@ export declare const idListProblem: Problem<unknown>;
 export declare const baseUrlWhitespaceProblem: Problem<unknown>;
 /**
  * The full base-URL rule set, in order: no whitespace or control characters
- * (baseUrlWhitespaceProblem), an absolute URL, an `http:`/`https:` scheme, and no
- * query or fragment. Request paths are appended to the base URL as a string, so a
+ * (baseUrlWhitespaceProblem), an absolute URL, an `http:`/`https:` scheme, no
+ * query or fragment, and no `%` in the userinfo that doesn't start a valid escape
+ * (`%25` for a literal one). Request paths are appended to the base URL as a string, so a
  * `?` or `#` in it would swallow every path: `http://h/?x=1` requests
  * `/?x=1/webservices/...` and `http://h/#f` requests `/`. A path prefix is fine, and
  * userinfo is allowed (Node sends it as Basic auth). The reasons name no URL, so a
@@ -49,3 +60,13 @@ export declare const baseUrlProblem: Problem<unknown>;
  * injection). Checked by char code so the source stays free of control bytes.
  */
 export declare const headerValueProblem: Problem<unknown>;
+/**
+ * A parameter object of a client method: a plain object whose own keys are all in
+ * `allowed` (an `undefined` value counts as unset and is ignored). A misspelled key
+ * (`water` for `waters`, `fuzzyID`), `__proto__` or `constructor` was dropped silently
+ * and the API answered with every station; TypeScript catches a typo, JavaScript and a
+ * JSON config do not. The reason names the key, a close match and the allowed keys.
+ */
+export declare function knownKeysProblem(allowed: readonly string[]): Problem<unknown>;
+/** An optional flag (`includeTimeseries` …): `true`, `false` or unset — not "yes", 1 or "false". */
+export declare const optionalBooleanProblem: Problem<unknown>;

package/dist/src/client/validate.js

@@ -17,6 +17,18 @@ export function assertValid(name, value, problem) {
         throw new PegelValidationError(`Invalid ${name}: ${reason}`);
     return value;
 }
+/**
+ * The form in which an id, name or filter value is sent: surrounding whitespace removed
+ * and composed (NFC). The API matches station names, waters and ids exactly, so
+ * `"RHEIN "` (a trailing space from a copy) listed no station and `"BONN "` was a 404, and
+ * a decomposed umlaut ("KO" + U+0308 + "LN", as pasted from macOS file names or some
+ * PDFs) found nothing either; no name upstream begins or ends with whitespace. NFC, not
+ * NFKC: an id lookup must not rewrite compatibility characters, and case is left alone
+ * (the API ignores it for station ids, but not everywhere).
+ */
+export function normalizeInput(value) {
+    return value.trim().normalize("NFC");
+}
 /** True for an empty or whitespace-only string. */
 export function isBlank(value) {
     return value.trim() === "";
@@ -62,8 +74,9 @@ export const baseUrlWhitespaceProblem = (value) => {
 };
 /**
  * The full base-URL rule set, in order: no whitespace or control characters
- * (baseUrlWhitespaceProblem), an absolute URL, an `http:`/`https:` scheme, and no
- * query or fragment. Request paths are appended to the base URL as a string, so a
+ * (baseUrlWhitespaceProblem), an absolute URL, an `http:`/`https:` scheme, no
+ * query or fragment, and no `%` in the userinfo that doesn't start a valid escape
+ * (`%25` for a literal one). Request paths are appended to the base URL as a string, so a
  * `?` or `#` in it would swallow every path: `http://h/?x=1` requests
  * `/?x=1/webservices/...` and `http://h/#f` requests `/`. A path prefix is fine, and
  * userinfo is allowed (Node sends it as Basic auth). The reasons name no URL, so a
@@ -84,6 +97,16 @@ export const baseUrlProblem = (value) => {
         return "Only http and https URLs are supported.";
     if (/[?#]/.test(value))
         return "A base URL cannot have a query (?) or fragment (#).";
+    // Node decodes the userinfo into the Authorization header and throws "URI malformed"
+    // for a "%" that isn't an escape — at request time, as a network error. Reject it here.
+    for (const part of [url.username, url.password]) {
+        try {
+            decodeURIComponent(part);
+        }
+        catch {
+            return 'The user name or password has a "%" that is not followed by two hex digits; write a literal "%" as %25.';
+        }
+    }
     return undefined;
 };
 /**
@@ -106,3 +129,27 @@ export const headerValueProblem = (value) => {
     }
     return undefined;
 };
+/**
+ * A parameter object of a client method: a plain object whose own keys are all in
+ * `allowed` (an `undefined` value counts as unset and is ignored). A misspelled key
+ * (`water` for `waters`, `fuzzyID`), `__proto__` or `constructor` was dropped silently
+ * and the API answered with every station; TypeScript catches a typo, JavaScript and a
+ * JSON config do not. The reason names the key, a close match and the allowed keys.
+ */
+export function knownKeysProblem(allowed) {
+    return (value) => {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            return "Expected an object.";
+        for (const [key, v] of Object.entries(value)) {
+            if (v === undefined || allowed.includes(key))
+                continue;
+            const lower = key.toLowerCase();
+            const hint = allowed.find((name) => name.toLowerCase().includes(lower) || lower.includes(name.toLowerCase()));
+            return (`Unknown key ${JSON.stringify(key)}` +
+                (hint === undefined ? `; the keys are ${allowed.join(", ")}.` : ` (did you mean ${hint}?).`));
+        }
+        return undefined;
+    };
+}
+/** An optional flag (`includeTimeseries` …): `true`, `false` or unset — not "yes", 1 or "false". */
+export const optionalBooleanProblem = (value) => value === undefined || typeof value === "boolean" ? undefined : "Expected true or false.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maschinenlesbar.org/pegel-online-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "TypeScript API client and CLI for the open PEGELONLINE water-level REST API (pegelonline.wsv.de)",
   "type": "module",
   "bin": {
@@ -21,7 +21,7 @@
     "CONTRIBUTING.md"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.12"
   },
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
@@ -64,7 +64,7 @@
     "commander": "15.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.5.1",
+    "@types/node": "^22.20.5",
     "typescript": "7.0.2"
   }
 }