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

package/dist/src/client/client.js

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

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

@@ -9,7 +9,9 @@ export interface RawResponse {
 /**
  * Options for {@link RequestEngine} and the client. The numeric options must be
  * integers within their documented range; anything else (negative, fractional,
- * NaN, Infinity, too large) makes the constructor throw a PegelError.
+ * NaN, Infinity, too large) makes the constructor throw a PegelValidationError, as
+ * does a `transport` or `sleep` that is not a function and a `headers` value an HTTP
+ * header can't carry.
  */
 export interface EngineOptions {
     /** Base URL of the API. Defaults to https://www.pegelonline.wsv.de */
@@ -32,15 +34,16 @@ export interface EngineOptions {
      */
     timeoutMs?: number;
     /**
-     * Number of automatic retries for transient (429/503) responses, 0..`MAX_RETRIES`
-     * (10). Each waits the
-     * response's `Retry-After` (up to `MAX_RETRY_AFTER_MS`; a longer one is not
-     * retried), or else `retryDelayMs * attempt`.
+     * Number of automatic retries for transient (429/503) responses and reset
+     * connections (ECONNRESET, EPIPE, ECONNABORTED, undici's UND_ERR_SOCKET, anywhere in
+     * the error's `cause` chain; GET and HEAD only), 0..`MAX_RETRIES` (10). Each waits
+     * `retryDelayMs * attempt`, or longer when the response's `Retry-After` asks (up to
+     * `MAX_RETRY_AFTER_MS`; a longer one is not retried). Timeouts are not retried.
      */
     maxRetries?: number;
     /**
-     * Base backoff between retries in milliseconds (grows linearly); used without a
-     * Retry-After. At most `MAX_RETRY_AFTER_MS`.
+     * Base backoff between retries in milliseconds (grows linearly); the floor of every
+     * wait, Retry-After or not. At most `MAX_RETRY_AFTER_MS`.
      */
     retryDelayMs?: number;
     /**
@@ -62,8 +65,10 @@ export declare const MAX_RETRIES = 10;
 /**
  * Longest `Retry-After` the engine waits out before retrying a 429/503. When the
  * server asks for longer, the engine does not retry at all and surfaces the error at
- * once: retrying early would only land inside the window the server asked us to wait
- * out, and a hostile value must not stall the CLI.
+ * once, naming the requested wait (`PegelApiError.retryAfterMs`): retrying early would
+ * only land inside the window the server asked us to wait out, and a hostile value must
+ * not stall the CLI. A shorter `Retry-After` never makes a wait shorter than the normal
+ * backoff.
  */
 export declare const MAX_RETRY_AFTER_MS = 30000;
 /**
@@ -77,11 +82,26 @@ export declare const MAX_RETRY_AFTER_MS = 30000;
  * read `"1.5"` as a date in 2001 and retry at once.
  */
 export declare function parseRetryAfter(header: string | string[] | undefined, now?: number): number | undefined;
+/**
+ * True for a PegelNetworkError caused by a reset or aborted connection, which the
+ * engine retries — whichever transport raised it (a Node error, fetch's TypeError with
+ * an undici cause). A refused connection, a DNS failure or a timeout is not transient
+ * in that sense and is not retried.
+ */
+export declare function isTransientNetworkError(err: unknown): boolean;
+/**
+ * Check a base URL against the library's rules (baseUrlProblem: no whitespace or
+ * control characters, an absolute http(s) URL, no query or fragment) and return it
+ * without trailing slashes. Throws PegelValidationError `Invalid baseUrl: …`: a
+ * configuration mistake, not a PegelNetworkError. The RequestEngine constructor
+ * calls it on the raw value, so a custom transport never sees a bad base URL; the
+ * default transport still re-checks the scheme on every hop.
+ */
+export declare function validateBaseUrl(raw: string): string;
 export declare class RequestEngine {
-    private readonly baseUrl;
+    #private;
     private readonly transport;
     private readonly userAgent;
-    private readonly extraHeaders;
     private readonly timeoutMs;
     private readonly maxRetries;
     private readonly retryDelayMs;
@@ -92,7 +112,7 @@ export declare class RequestEngine {
     /**
      * Build a fully-qualified URL from a path and optional query parameters.
      *
-     * Throws a PegelError for a path with a "." or ".." segment. The resource methods
+     * Throws a PegelValidationError for a path with a "." or ".." segment. The resource methods
      * put ids into the path with `encodeURIComponent`, which leaves those two
      * unchanged, and URL parsing then resolves them: `currentMeasurement("BONN", "..")`
      * would request `/stations/currentmeasurement.json` (a station of that name).
@@ -100,6 +120,25 @@ export declare class RequestEngine {
      * encodeURIComponent turns their "%" into "%25".)
      */
     buildUrl(path: string, query?: QueryParams): string;
+    /**
+     * `text` without the base URL's credentials: server text (an error body that echoes
+     * the request URL) and transport text (fetch's "Failed to fetch <url>") can carry them.
+     */
+    private scrub;
+    /**
+     * A transport failure as the `cause` of the error the engine raises: the original
+     * when its text carries no credentials, otherwise a copy with them scrubbed (message,
+     * `code` and the cause chain kept), so logging the error with its causes can't reveal
+     * the base URL's password.
+     */
+    private scrubCause;
+    /**
+     * Call the transport under the overall deadline (`timeoutMs`): the request gets an
+     * AbortSignal that fires at the deadline, and the call rejects then whether the
+     * transport stops or not — a custom transport (fetch, a node:http wrapper) that
+     * ignores `timeoutMs` can't hang the caller. A synchronous throw becomes a rejection.
+     */
+    private callTransport;
     /** Perform a request with Accept negotiation and transient-error retries. */
     request(method: string, path: string, options?: {
         query?: QueryParams;
@@ -109,4 +148,3 @@ export declare class RequestEngine {
     getJson<T>(path: string, query?: QueryParams): Promise<T>;
     private toApiError;
 }
-//# sourceMappingURL=engine.d.ts.map