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

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

@@ -7,9 +7,29 @@ export declare 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 declare function redactUrl(url: string): string;
+/**
+ * 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 declare function credentialsIn(value: string): string[];
+/**
+ * `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 declare function redactCredentials(text: string, credentials: readonly string[]): string;
 /**
  * The API responded with a non-2xx status code. `detail` holds a human-readable
  * message extracted from the response body when one is present.
@@ -26,6 +46,12 @@ export declare class PegelApiError extends PegelError {
      * redacted. The message names it.
      */
     readonly location: string | undefined;
+    /**
+     * 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.
+     */
+    readonly retryAfterMs: number | undefined;
     constructor(args: {
         status: number;
         url: string;
@@ -35,14 +61,24 @@ export declare class PegelApiError extends PegelError {
         location?: string;
         /** Redirects already followed when the limit stopped this one (> 0 only). */
         redirectsFollowed?: number;
+        /** A Retry-After longer than the client waits (not retried). */
+        retryAfterMs?: number;
+        /** Advice appended to the message (e.g. that a redirect dropped the credentials). */
+        hint?: string;
     });
     /** True for statuses the API documents as transient and retry-able. */
     get isRetryable(): boolean;
 }
+/**
+ * An input the library rejects before sending any request: a client option or a
+ * method argument that breaks one of the rules in `validate.ts`. The message reads
+ * `Invalid <name>: <reason>`. The CLI reports it as a usage error (exit 2).
+ */
+export declare class PegelValidationError extends PegelError {
+}
 /** A transport-level failure (DNS, connection reset, timeout, ...). */
 export declare class PegelNetworkError extends PegelError {
 }
 /** The response body could not be parsed as the expected JSON shape. */
 export declare class PegelParseError extends PegelError {
 }
-//# sourceMappingURL=errors.d.ts.map

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,16 +127,23 @@ 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() {
         return this.status === 429 || this.status === 503;
     }
 }
+/**
+ * An input the library rejects before sending any request: a client option or a
+ * method argument that breaks one of the rules in `validate.ts`. The message reads
+ * `Invalid <name>: <reason>`. The CLI reports it as a usage error (exit 2).
+ */
+export class PegelValidationError extends PegelError {
+}
 /** A transport-level failure (DNS, connection reset, timeout, ...). */
 export class PegelNetworkError extends PegelError {
 }
 /** The response body could not be parsed as the expected JSON shape. */
 export class PegelParseError extends PegelError {
 }
-//# sourceMappingURL=errors.js.map

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.
@@ -28,4 +54,3 @@ export declare const MAX_TIMEOUT_MS = 2147483647;
  * (connection errors, timeouts, malformed URLs).
  */
 export declare const nodeHttpTransport: Transport;
-//# sourceMappingURL=http.d.ts.map

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 }));
@@ -109,4 +124,3 @@ export const nodeHttpTransport = (request) => new Promise((resolve, reject) => {
         req.write(request.body);
     req.end();
 });
-//# sourceMappingURL=http.js.map

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

@@ -1,10 +1,12 @@
-export { PegelOnlineClient } from "./client.js";
-export { RequestEngine, DEFAULT_BASE_URL, MAX_RETRIES, MAX_RETRY_AFTER_MS, parseRetryAfter, } 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, redactUrl } from "./errors.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";
-//# sourceMappingURL=index.d.ts.map

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, } 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, redactUrl } from "./errors.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";
-//# sourceMappingURL=index.js.map

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

@@ -6,4 +6,3 @@ export type QueryParams = Record<string, QueryValue>;
  * Returns an empty string when no parameters survive filtering.
  */
 export declare function buildQueryString(params: QueryParams): string;
-//# sourceMappingURL=query.d.ts.map

package/dist/src/client/query.js

@@ -30,4 +30,3 @@ export function buildQueryString(params) {
     // URLSearchParams encodes spaces as "+"; "%20" is more broadly interoperable.
     return search.toString().replace(/\+/g, "%20");
 }
-//# sourceMappingURL=query.js.map

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,14 +100,24 @@ 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. */
+    /**
+     * Station identifiers (uuid/number/shortname/longname); sent comma-separated.
+     * 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. */
+    /** Water shortname filter; not blank. */
     waters?: string;
+    /** Fuzzy id match; not blank. */
     fuzzyId?: string;
     /** Embed each station's timeseries list. */
     includeTimeseries?: boolean;
@@ -90,9 +141,8 @@ export interface IncludeParams {
     includeCurrentMeasurement?: boolean;
     includeCharacteristicValues?: boolean;
 }
-/** Time window for a measurements request (ISO-8601 instants or periods, e.g. "P7D"). */
+/** Time window for a measurements request (ISO-8601 instants or periods, e.g. "P7D"); neither bound may be blank. */
 export interface MeasurementsParams {
     start?: string;
     end?: string;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/src/client/types.js

@@ -1,4 +1,3 @@
 // Domain types for the PEGELONLINE REST API v2 (pegelonline.wsv.de), the
 // Wasserstraßen- und Schifffahrtsverwaltung's water-level web service.
 export {};
-//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,72 @@
+/** A rule: the reason `value` is invalid (e.g. `"Expected a non-empty value."`), or `undefined` when it is valid. */
+export type Problem<T = unknown> = (value: T) => string | undefined;
+/**
+ * Throw a {@link PegelValidationError} with the message `Invalid <name>: <reason>`
+ * when `problem(value)` finds a reason; otherwise return `value` unchanged. Call it
+ * before any request, so a rejected input sends nothing. Async methods call it
+ * inside their body, so the rejection arrives as a rejected promise rather than a
+ * 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;
+/**
+ * A filter or query value must be a non-blank string: the API treats an empty
+ * parameter (`?waters=`, `?start=`) as no filter, so a blank value would silently
+ * return the unfiltered set or the default window.
+ */
+export declare const nonEmptyProblem: Problem<unknown>;
+/**
+ * The `ids` filter of `stations.list`: at least one id, none of them blank. An
+ * empty list would be dropped and list every station; a blank entry would be sent
+ * as `ids=BONN,%20`.
+ */
+export declare const idListProblem: Problem<unknown>;
+/**
+ * Whitespace and control characters in a base URL. `new URL()` silently trims
+ * surrounding whitespace and strips an interior tab or newline, so the URL checks
+ * pass, but the engine concatenates request paths onto the raw string:
+ * `"https://h/ "` would request `/%20/webservices/...`, and a custom transport would
+ * get the raw padded value.
+ */
+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, 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
+ * credential in it never reaches a message.
+ */
+export declare const baseUrlProblem: Problem<unknown>;
+/**
+ * A value that goes into an HTTP header (the User-Agent): non-blank, no C0 control
+ * or DEL (tab is allowed, as in HTTP), nothing above U+00FF. A blank value would be
+ * sent as an empty header instead of the default; Node's HTTP layer refuses the
+ * others with an opaque "Invalid character in header content" TypeError at request
+ * time, and an injected transport would send a CR/LF value as is (header
+ * 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>;