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

package/dist/src/client/client.js

@@ -6,8 +6,45 @@
 //   client.timeseries.currentMeasurement("BONN", "W")
 //   client.timeseries.measurements("BONN", "W", { start: "P3D" })
 import { RequestEngine } from "./engine.js";
+import { PegelError } from "./errors.js";
+import { assertValid, idListProblem, nonEmptyProblem } from "./validate.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));
+}
+/**
+ * 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 : assertValid(name, value, nonEmptyProblem);
+}
+/** An optional filter value (optionalValue), composed to NFC like every name the API matches. */
+function optionalFilter(name, value) {
+    const checked = optionalValue(name, value);
+    return checked === undefined ? undefined : nfc(checked);
+}
 /** Drop undefined values so only the parameters the caller set are sent. */
 function prune(params) {
     const out = {};
@@ -17,6 +54,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,
@@ -30,19 +81,22 @@ 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 = {}) {
         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 === undefined ? undefined : assertValid("ids", params.ids, idListProblem).map(nfc).join(","),
+            waters: optionalFilter("waters", params.waters),
+            fuzzyId: optionalFilter("fuzzyId", 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 +106,15 @@ 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 }));
+    /** 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: optionalValue("start", params.start), end: optionalValue("end", params.end) }));
     }
 }
 export class PegelOnlineClient {
@@ -76,4 +131,3 @@ export class PegelOnlineClient {
         return this.engine.getJson(`${API}/waters.json`);
     }
 }
-//# sourceMappingURL=client.js.map

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

@@ -6,6 +6,11 @@ export interface RawResponse {
     contentType: string;
     status: number;
 }
+/**
+ * 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.
+ */
 export interface EngineOptions {
     /** Base URL of the API. Defaults to https://www.pegelonline.wsv.de */
     baseUrl?: string;
@@ -23,14 +28,26 @@ export interface EngineOptions {
     headers?: Record<string, string>;
     /**
      * Time limit per request in milliseconds, covering the whole response body, not
-     * only idle gaps (0 disables; capped at `MAX_TIMEOUT_MS`, 2^31 - 1 ms).
+     * only idle gaps (0 disables; at most `MAX_TIMEOUT_MS`, 2^31 - 1 ms).
      */
     timeoutMs?: number;
-    /** Number of automatic retries for transient (429/503) responses. */
+    /**
+     * 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`.
+     */
     maxRetries?: number;
-    /** Base backoff between retries in milliseconds (grows linearly). */
+    /**
+     * Base backoff between retries in milliseconds (grows linearly); used without a
+     * Retry-After. At most `MAX_RETRY_AFTER_MS`.
+     */
     retryDelayMs?: number;
-    /** Number of HTTP redirects (301/302/303/307/308) to follow. Defaults to 5. */
+    /**
+     * Number of HTTP redirects (301/302/303/307/308) to follow, 0..20. Defaults to 5. Any
+     * other 3xx, one with a missing or malformed Location, and one past this limit
+     * surface as a PegelApiError naming the target.
+     */
     maxRedirects?: number;
     /**
      * Hard cap on response body size in bytes (defends against memory exhaustion
@@ -40,6 +57,35 @@ export interface EngineOptions {
     /** Injectable sleep, primarily for deterministic tests. */
     sleep?: (ms: number) => Promise<void>;
 }
+/** Most automatic retries a caller may ask for (the CLI's --max-retries shares it). */
+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.
+ */
+export declare const MAX_RETRY_AFTER_MS = 30000;
+/**
+ * Parse a `Retry-After` header into a delay in milliseconds (RFC 9110 §10.2.3):
+ * either delay-seconds (`"120"`) or an HTTP-date (`"Wed, 21 Oct 2026 07:28:00 GMT"`,
+ * turned into the time left from `now`; a date in the past gives 0).
+ *
+ * Returns `undefined` when the header is absent or malformed — negative (`"-1"`),
+ * fractional (`"1.5"`), padded inside, any other date format — so the caller falls
+ * back to its own backoff. The strict patterns matter: `Date.parse` alone would
+ * read `"1.5"` as a date in 2001 and retry at once.
+ */
+export declare function parseRetryAfter(header: string | string[] | undefined, now?: number): number | undefined;
+/**
+ * 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 readonly transport;
@@ -52,7 +98,16 @@ export declare class RequestEngine {
     private readonly maxResponseBytes;
     private readonly sleep;
     constructor(options?: EngineOptions);
-    /** Build a fully-qualified URL from a path and optional query parameters. */
+    /**
+     * 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
+     * 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).
+     * Neither can name a resource. (Percent-encoded forms such as "%2e%2e" are safe:
+     * encodeURIComponent turns their "%" into "%25".)
+     */
     buildUrl(path: string, query?: QueryParams): string;
     /** Perform a request with Accept negotiation and transient-error retries. */
     request(method: string, path: string, options?: {
@@ -63,4 +118,3 @@ export declare class RequestEngine {
     getJson<T>(path: string, query?: QueryParams): Promise<T>;
     private toApiError;
 }
-//# sourceMappingURL=engine.d.ts.map

package/dist/src/client/engine.js

@@ -1,12 +1,66 @@
 // The request engine: turns logical (method, path, query) calls into HTTP
 // requests via a Transport, applies retry/backoff for transient statuses
 // (429, 503), and decodes responses.
-import { nodeHttpTransport } from "./http.js";
+import { MAX_TIMEOUT_MS, nodeHttpTransport } from "./http.js";
 import { buildQueryString } from "./query.js";
-import { PegelApiError, PegelError, PegelNetworkError, PegelParseError } from "./errors.js";
+import { PegelApiError, PegelError, PegelParseError, redactUrl } from "./errors.js";
+import { assertValid, baseUrlProblem, headerValueProblem } from "./validate.js";
 export const DEFAULT_BASE_URL = "https://www.pegelonline.wsv.de";
 const DEFAULT_USER_AGENT = "pegel-online-cli";
 const DEFAULT_MAX_RESPONSE_BYTES = 100 * 1024 * 1024;
+/** Most automatic retries a caller may ask for (the CLI's --max-retries shares it). */
+export const MAX_RETRIES = 10;
+/** Most redirects a caller may let the engine follow (the Fetch standard's limit). */
+const MAX_REDIRECTS = 20;
+/**
+ * Read a numeric engine option: `undefined` gives the default; anything but an
+ * integer in [0, max] throws. Without this a negative or NaN `timeoutMs` silently
+ * disabled the timeout, and `maxRetries: NaN` silently meant no retries.
+ */
+function intOption(name, value, fallback, max) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < 0 || value > max) {
+        throw new PegelError(`Invalid option ${name}: expected an integer from 0 to ${max}, got ${String(value)}.`);
+    }
+    return value;
+}
+/**
+ * The redirect statuses the engine follows. 300 (a choice for the user), 304 (a
+ * cache answer to a conditional request this client never sends) and 305/306
+ * (deprecated) are not redirects to follow; they surface as a PegelApiError.
+ */
+const FOLLOWED_REDIRECTS = new Set([301, 302, 303, 307, 308]);
+/**
+ * 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.
+ */
+export const MAX_RETRY_AFTER_MS = 30_000;
+/** An IMF-fixdate (RFC 9110 §5.6.7), the one HTTP-date form senders must generate. */
+const IMF_FIXDATE = /^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} GMT$/;
+/**
+ * Parse a `Retry-After` header into a delay in milliseconds (RFC 9110 §10.2.3):
+ * either delay-seconds (`"120"`) or an HTTP-date (`"Wed, 21 Oct 2026 07:28:00 GMT"`,
+ * turned into the time left from `now`; a date in the past gives 0).
+ *
+ * Returns `undefined` when the header is absent or malformed — negative (`"-1"`),
+ * fractional (`"1.5"`), padded inside, any other date format — so the caller falls
+ * back to its own backoff. The strict patterns matter: `Date.parse` alone would
+ * read `"1.5"` as a date in 2001 and retry at once.
+ */
+export function parseRetryAfter(header, now = Date.now()) {
+    const value = (Array.isArray(header) ? header[0] : header)?.trim();
+    if (value === undefined || value === "")
+        return undefined;
+    if (/^\d+$/.test(value))
+        return Number(value) * 1000;
+    if (!IMF_FIXDATE.test(value))
+        return undefined;
+    const when = Date.parse(value);
+    return Number.isNaN(when) ? undefined : Math.max(0, when - now);
+}
 /**
  * Credential-bearing headers that must never be carried across an origin boundary
  * on a redirect. Stored lower-cased and compared case-insensitively so a header
@@ -51,22 +105,15 @@ function sanitizeServerText(text) {
     return out;
 }
 /**
- * Reject a base URL whose scheme is not http(s). The default transport already
- * gates this per hop, but the engine is exported as a library and may be handed a
- * custom transport that does no such check, so gate the configured base URL here
- * too (a `file:`/`ftp:` base URL fails fast with a typed error).
+ * 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.
  */
-function assertHttpScheme(baseUrl) {
-    let url;
-    try {
-        url = new URL(baseUrl);
-    }
-    catch {
-        throw new PegelNetworkError(`Invalid base URL: ${baseUrl}`);
-    }
-    if (url.protocol !== "http:" && url.protocol !== "https:") {
-        throw new PegelNetworkError(`Unsupported protocol "${url.protocol}" in base URL: ${baseUrl}`);
-    }
+export function validateBaseUrl(raw) {
+    return assertValid("baseUrl", raw, baseUrlProblem).replace(/\/+$/, "");
 }
 const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export class RequestEngine {
@@ -81,27 +128,43 @@ export class RequestEngine {
     maxResponseBytes;
     sleep;
     constructor(options = {}) {
-        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-        assertHttpScheme(this.baseUrl);
+        // The raw value, before the slash strip: the engine glues it into every URL, so
+        // "https://h/ " must not lose its slash first and slip past the check.
+        this.baseUrl = validateBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
         this.transport = options.transport ?? nodeHttpTransport;
-        this.userAgent = options.userAgent ?? DEFAULT_USER_AGENT;
-        // Reject control characters (CR/LF in particular) up front with a typed error
-        // instead of letting Node throw a raw TypeError during header validation,
-        // which would surface as an "Unexpected error". Also closes header-injection.
-        if (/[\x00-\x1f\x7f]/.test(this.userAgent)) {
-            throw new PegelError("Invalid User-Agent: control characters are not allowed.");
-        }
+        // Only `undefined` selects the default. An explicit value must be one an HTTP
+        // header can carry (headerValueProblem): not blank, which would replace the
+        // default with an empty header, and no control character (CR/LF in particular,
+        // which also closes header injection; tab is allowed) or character above U+00FF,
+        // which Node would refuse late with a raw TypeError.
+        this.userAgent =
+            options.userAgent === undefined
+                ? DEFAULT_USER_AGENT
+                : assertValid("User-Agent", options.userAgent, headerValueProblem);
         this.extraHeaders = options.headers ?? {};
-        this.timeoutMs = options.timeoutMs ?? 30_000;
-        this.maxRetries = options.maxRetries ?? 2;
-        this.retryDelayMs = options.retryDelayMs ?? 200;
-        this.maxRedirects = options.maxRedirects ?? 5;
-        this.maxResponseBytes = options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+        this.timeoutMs = intOption("timeoutMs", options.timeoutMs, 30_000, MAX_TIMEOUT_MS);
+        this.maxRetries = intOption("maxRetries", options.maxRetries, 2, MAX_RETRIES);
+        this.retryDelayMs = intOption("retryDelayMs", options.retryDelayMs, 200, MAX_RETRY_AFTER_MS);
+        this.maxRedirects = intOption("maxRedirects", options.maxRedirects, 5, MAX_REDIRECTS);
+        this.maxResponseBytes = intOption("maxResponseBytes", options.maxResponseBytes, DEFAULT_MAX_RESPONSE_BYTES, Number.MAX_SAFE_INTEGER);
         this.sleep = options.sleep ?? realSleep;
     }
-    /** Build a fully-qualified URL from a path and optional query parameters. */
+    /**
+     * 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
+     * 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).
+     * Neither can name a resource. (Percent-encoded forms such as "%2e%2e" are safe:
+     * encodeURIComponent turns their "%" into "%25".)
+     */
     buildUrl(path, query) {
         const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+        const dotSegment = normalizedPath.split("/").find((s) => s === "." || s === "..");
+        if (dotSegment !== undefined) {
+            throw new PegelError(`Invalid path segment "${dotSegment}" in ${normalizedPath}: "." and ".." cannot be used as an id.`);
+        }
         const qs = query ? buildQueryString(query) : "";
         return `${this.baseUrl}${normalizedPath}${qs ? `?${qs}` : ""}`;
     }
@@ -127,31 +190,41 @@ export class RequestEngine {
             const status = response.status;
             const retryable = status === 429 || status === 503;
             if (retryable && attempt < this.maxRetries) {
-                attempt += 1;
-                await this.sleep(this.retryDelayMs * attempt);
-                continue;
+                // Honour Retry-After; without a usable one, back off linearly. A Retry-After
+                // beyond MAX_RETRY_AFTER_MS is not retried: the error below surfaces at once.
+                const retryAfter = parseRetryAfter(response.headers["retry-after"]);
+                if (retryAfter === undefined || retryAfter <= MAX_RETRY_AFTER_MS) {
+                    attempt += 1;
+                    await this.sleep(retryAfter ?? this.retryDelayMs * attempt);
+                    continue;
+                }
             }
             // Follow redirects, resolving the Location relative to the current URL.
-            if (status >= 300 && status < 400 && redirects < this.maxRedirects) {
-                const location = response.headers["location"];
-                if (typeof location === "string" && location.length > 0) {
-                    const next = new URL(location, url);
-                    // Security: never carry credential-bearing headers across an origin
-                    // boundary. The CLI sends none today, but this guards a future
-                    // Authorization/Cookie/X-Api-Key header from leaking to an
-                    // attacker-controlled redirect target. Comparing full origin (scheme +
-                    // host + port) also strips on a same-host https->http downgrade.
-                    if (next.origin !== new URL(url).origin) {
-                        stripSensitiveHeaders(headers);
-                    }
-                    url = next.toString();
-                    redirects += 1;
-                    continue;
+            const location = response.headers["location"];
+            const next = FOLLOWED_REDIRECTS.has(status) ? resolveLocation(location, url) : undefined;
+            if (next !== undefined && redirects >= this.maxRedirects) {
+                // A loop (or a long chain): say how far it got rather than a bare 3xx.
+                // (With maxRedirects 0 nothing was followed; the plain text says enough.)
+                throw this.toApiError(method, url, status, response.body, location, redirects || undefined);
+            }
+            if (next !== undefined) {
+                // Security: never carry credential-bearing headers across an origin
+                // boundary. The CLI sends none today, but this guards a future
+                // Authorization/Cookie/X-Api-Key header from leaking to an
+                // attacker-controlled redirect target. Comparing full origin (scheme +
+                // host + port) also strips on a same-host https->http downgrade.
+                if (next.origin !== new URL(url).origin) {
+                    stripSensitiveHeaders(headers);
                 }
+                url = next.toString();
+                redirects += 1;
+                continue;
             }
+            // Any other 3xx — not a followed status, or no usable Location — falls
+            // through and surfaces as a PegelApiError naming the target.
             const contentType = String(response.headers["content-type"] ?? "");
             if (status < 200 || status >= 300) {
-                throw this.toApiError(method, url, status, response.body);
+                throw this.toApiError(method, url, status, response.body, location);
             }
             return { data: response.body, contentType, status };
         }
@@ -167,7 +240,7 @@ export class RequestEngine {
             throw new PegelParseError(`Failed to parse JSON response from ${path}`, { cause });
         }
     }
-    toApiError(method, url, status, body) {
+    toApiError(method, url, status, body, locationHeader, redirectsFollowed) {
         const text = body.toString("utf8");
         let detail;
         try {
@@ -184,7 +257,37 @@ export class RequestEngine {
         // endpoint cannot inject terminal escape sequences via the stderr error message.
         if (detail !== undefined)
             detail = sanitizeServerText(detail);
-        return new PegelApiError({ status, url, method, body: text, detail });
+        // Name the target of a redirect that was not followed.
+        const location = status >= 300 && status < 400 && locationHeader ? redirectTarget(url, locationHeader) : undefined;
+        return new PegelApiError({
+            status,
+            url,
+            method,
+            body: text,
+            detail,
+            ...(location !== undefined ? { location } : {}),
+            ...(redirectsFollowed !== undefined ? { redirectsFollowed } : {}),
+        });
     }
 }
-//# sourceMappingURL=engine.js.map
+/** Resolve a Location header against the current URL; undefined if missing or malformed. */
+function resolveLocation(location, base) {
+    if (location === undefined || location === "")
+        return undefined;
+    try {
+        return new URL(location, base);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The absolute, printable form of a `Location` header: resolved against the request
+ * URL, userinfo redacted, control characters stripped (it is server text bound for
+ * stderr). An unparseable value is shown sanitised as it came.
+ */
+function redirectTarget(requestUrl, location) {
+    const resolved = resolveLocation(location, requestUrl);
+    const clean = sanitizeServerText(resolved ? redactUrl(resolved.href) : location).trim();
+    return clean === "" ? undefined : clean;
+}

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

@@ -4,6 +4,12 @@ export declare class PegelError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * 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.
+ */
+export declare function redactUrl(url: 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.
@@ -14,20 +20,35 @@ export declare class PegelApiError extends PegelError {
     readonly url: string;
     readonly method: string;
     readonly body: string;
+    /**
+     * For a 3xx that was not followed (not a followed status, a malformed Location,
+     * or past `maxRedirects`): the redirect target, absolute, sanitised, userinfo
+     * redacted. The message names it.
+     */
+    readonly location: string | undefined;
     constructor(args: {
         status: number;
         url: string;
         method: string;
         body: string;
         detail?: string;
+        location?: string;
+        /** Redirects already followed when the limit stopped this one (> 0 only). */
+        redirectsFollowed?: number;
     });
     /** 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

@@ -7,6 +7,25 @@ export class PegelError extends Error {
         this.name = new.target.name;
     }
 }
+/**
+ * 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.
+ */
+export function redactUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return url;
+    }
+    if (parsed.username === "" && parsed.password === "")
+        return url;
+    parsed.username = "***";
+    parsed.password = "";
+    return parsed.href;
+}
 /**
  * The API responded with a non-2xx status code. `detail` holds a human-readable
  * message extracted from the response body when one is present.
@@ -17,24 +36,50 @@ export class PegelApiError extends PegelError {
     url;
     method;
     body;
+    /**
+     * For a 3xx that was not followed (not a followed status, a malformed Location,
+     * or past `maxRedirects`): the redirect target, absolute, sanitised, userinfo
+     * redacted. The message names it.
+     */
+    location;
     constructor(args) {
-        const detailPart = args.detail ? `: ${args.detail}` : "";
-        super(`HTTP ${args.status} for ${args.method} ${args.url}${detailPart}`);
+        const parts = [];
+        if (args.detail)
+            parts.push(args.detail);
+        if (args.status >= 300 && args.status < 400) {
+            const limit = args.redirectsFollowed !== undefined && args.redirectsFollowed > 0
+                ? ` (stopped after ${args.redirectsFollowed} redirects)`
+                : "";
+            parts.push(args.location
+                ? `redirect to ${args.location} not followed${limit}`
+                : "redirect not followed (no Location header)");
+        }
+        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);
+        super(`HTTP ${args.status} for ${args.method} ${url}${detailPart}`);
         this.status = args.status;
-        this.url = args.url;
+        this.url = url;
         this.method = args.method;
         this.body = args.body;
         this.detail = args.detail;
+        this.location = args.location;
     }
     /** 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

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