@maschinenlesbar.org/pegel-online-cli 0.0.1

package/dist/src/cli/shared.js

@@ -0,0 +1,81 @@
+// Shared helpers used across CLI command groups: option parsers, the global
+// option resolver, and the JSON result renderer.
+import { InvalidArgumentError } from "commander";
+import { PegelError } from "../client/errors.js";
+/** commander value-parser: a non-negative integer. */
+export function parseIntArg(value) {
+    // Require a plain decimal integer. Reject blank/whitespace ("" and " " coerce
+    // to 0 via Number()), hex/scientific encodings (0x10, 1e3), and signs/decimals.
+    if (!/^[0-9]+$/.test(value)) {
+        throw new InvalidArgumentError("Expected a non-negative integer.");
+    }
+    const n = Number(value);
+    // Number() can still produce a non-exact integer for very large inputs (beyond
+    // 2^53); reject those rather than silently using a different value.
+    if (!Number.isSafeInteger(n)) {
+        throw new InvalidArgumentError("Expected a non-negative integer.");
+    }
+    return n;
+}
+/**
+ * Validate a required positional argument: reject an empty/blank value rather
+ * than forwarding it into the URL path (which would produce a malformed request
+ * like `/stations//W/...`). Returns the trimmed value.
+ */
+export function requireArg(name, value) {
+    if (value === undefined || value.trim() === "") {
+        throw new PegelError(`Missing required <${name}> argument.`);
+    }
+    // Reject "." / ".." which encodeURIComponent leaves untouched and which would
+    // otherwise inject a relative path segment into the request URL.
+    if (value === "." || value === "..") {
+        throw new PegelError(`Invalid <${name}> argument: "${value}".`);
+    }
+    return value;
+}
+/**
+ * Normalise an optional `[timeseries]` positional: an empty/blank value behaves
+ * like omitting it and defaults to "W" (water level), matching the documented
+ * default. (`??` alone would forward an empty string into the path.)
+ */
+export function timeseriesOr(value, fallback = "W") {
+    return value && value.trim() !== "" ? value : fallback;
+}
+/** Translate resolved global CLI options into client EngineOptions. */
+export function toEngineOptions(global) {
+    const options = {};
+    if (global.baseUrl !== undefined)
+        options.baseUrl = global.baseUrl;
+    if (global.timeout !== undefined)
+        options.timeoutMs = global.timeout;
+    if (global.userAgent !== undefined)
+        options.userAgent = global.userAgent;
+    if (global.maxRetries !== undefined)
+        options.maxRetries = global.maxRetries;
+    if (global.maxResponseBytes !== undefined)
+        options.maxResponseBytes = global.maxResponseBytes;
+    return options;
+}
+/** Render a JSON value to stdout, pretty by default, compact with --compact. */
+export function renderJson(deps, global, value) {
+    const text = global.compact ? JSON.stringify(value) : JSON.stringify(value, null, 2);
+    deps.io.out(text);
+}
+/**
+ * Wrap an async command action with consistent global-option resolution and
+ * client construction. The callback receives a context (client + resolved global
+ * options + this command's options) and the command's positional arguments.
+ *
+ * Commander invokes actions as (arg1, ..., argN, options, command); we slice off
+ * the trailing options object and command instance to recover the positionals.
+ */
+export function action(deps, fn) {
+    return async (...args) => {
+        const command = args[args.length - 1];
+        const positionals = args.slice(0, Math.max(0, args.length - 2));
+        const global = command.optsWithGlobals();
+        const client = deps.createClient(toEngineOptions(global));
+        await fn({ client, global, opts: command.opts() }, positionals);
+    };
+}
+//# sourceMappingURL=shared.js.map

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

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

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

@@ -0,0 +1,28 @@
+import { RequestEngine, type EngineOptions } from "./engine.js";
+import type { Station, Water, TimeseriesInfo, CurrentMeasurement, Measurement, StationListParams, IncludeParams, MeasurementsParams } from "./types.js";
+/** Stations: list with filters, or fetch one by uuid/number/shortname/longname. */
+declare class StationsResource {
+    private readonly e;
+    constructor(e: RequestEngine);
+    list(params?: StationListParams): Promise<Station[]>;
+    get(station: string, params?: IncludeParams): Promise<Station>;
+}
+/** Timeseries: metadata, the current measurement, a window of measurements, gauge marks. */
+declare class TimeseriesResource {
+    private readonly e;
+    constructor(e: RequestEngine);
+    /** Timeseries metadata (e.g. "W" = water level, "Q" = flow). */
+    get(station: string, timeseries?: string, params?: IncludeParams): Promise<TimeseriesInfo>;
+    currentMeasurement(station: string, timeseries?: string): Promise<CurrentMeasurement>;
+    measurements(station: string, timeseries?: string, params?: MeasurementsParams): Promise<Measurement[]>;
+}
+export declare class PegelOnlineClient {
+    private readonly engine;
+    readonly stations: StationsResource;
+    readonly timeseries: TimeseriesResource;
+    constructor(options?: EngineOptions);
+    /** List all bodies of water (Gewässer) covered by the service. */
+    waters(): Promise<Water[]>;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/client/client.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,KAAK,EACV,OAAO,EACP,KAAK,EACL,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAsBpB,mFAAmF;AACnF,cAAM,gBAAgB;IACR,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,aAAa;IAE7C,IAAI,CAAC,MAAM,GAAE,iBAAsB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAYxD,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;CAGnE;AAED,4FAA4F;AAC5F,cAAM,kBAAkB;IACV,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,aAAa;IAE7C,gEAAgE;IAChE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,SAAM,EAAE,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;IAO3F,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,SAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAMlF,YAAY,CACV,OAAO,EAAE,MAAM,EACf,UAAU,SAAM,EAChB,MAAM,GAAE,kBAAuB,GAC9B,OAAO,CAAC,WAAW,EAAE,CAAC;CAM1B;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IAEvC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;gBAE5B,OAAO,GAAE,aAAkB;IAMvC,kEAAkE;IAClE,MAAM,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;CAG3B"}

package/dist/src/client/client.js

@@ -0,0 +1,79 @@
+// PegelOnlineClient — a typed client over the open (no-auth) PEGELONLINE REST
+// API v2 (https://www.pegelonline.wsv.de/webservices/rest-api/v2).
+//
+//   client.stations.list({ waters: "RHEIN" })
+//   client.stations.get("BONN", { includeCurrentMeasurement: true })
+//   client.timeseries.currentMeasurement("BONN", "W")
+//   client.timeseries.measurements("BONN", "W", { start: "P3D" })
+import { RequestEngine } from "./engine.js";
+const API = "/webservices/rest-api/v2";
+const enc = encodeURIComponent;
+/** Drop undefined values so only the parameters the caller set are sent. */
+function prune(params) {
+    const out = {};
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+function includeQuery(p) {
+    return prune({
+        includeTimeseries: p.includeTimeseries,
+        includeCurrentMeasurement: p.includeCurrentMeasurement,
+        includeCharacteristicValues: p.includeCharacteristicValues,
+    });
+}
+/** Stations: list with filters, or fetch one by uuid/number/shortname/longname. */
+class StationsResource {
+    e;
+    constructor(e) {
+        this.e = e;
+    }
+    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,
+        });
+        return this.e.getJson(`${API}/stations.json`, query);
+    }
+    get(station, params = {}) {
+        return this.e.getJson(`${API}/stations/${enc(station)}.json`, includeQuery(params));
+    }
+}
+/** Timeseries: metadata, the current measurement, a window of measurements, gauge marks. */
+class TimeseriesResource {
+    e;
+    constructor(e) {
+        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));
+    }
+    currentMeasurement(station, timeseries = "W") {
+        return this.e.getJson(`${API}/stations/${enc(station)}/${enc(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 }));
+    }
+}
+export class PegelOnlineClient {
+    engine;
+    stations;
+    timeseries;
+    constructor(options = {}) {
+        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`);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/src/client/client.js.map

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

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

@@ -0,0 +1,54 @@
+import { type Transport } from "./http.js";
+import { type QueryParams } from "./query.js";
+export declare const DEFAULT_BASE_URL = "https://www.pegelonline.wsv.de";
+export interface RawResponse {
+    data: Buffer;
+    contentType: string;
+    status: number;
+}
+export interface EngineOptions {
+    /** Base URL of the API. Defaults to https://www.pegelonline.wsv.de */
+    baseUrl?: string;
+    /** Swappable transport. Defaults to the built-in node http/https transport. */
+    transport?: Transport;
+    /** Value of the User-Agent header. */
+    userAgent?: string;
+    /** Per-request timeout in milliseconds (0 disables). */
+    timeoutMs?: number;
+    /** Number of automatic retries for transient (429/503) responses. */
+    maxRetries?: number;
+    /** Base backoff between retries in milliseconds (grows linearly). */
+    retryDelayMs?: number;
+    /** Number of HTTP redirects (301/302/303/307/308) to follow. Defaults to 5. */
+    maxRedirects?: number;
+    /**
+     * Hard cap on response body size in bytes (defends against memory exhaustion
+     * from a hostile/buggy endpoint). Defaults to 100 MiB; set to 0 for no limit.
+     */
+    maxResponseBytes?: number;
+    /** Injectable sleep, primarily for deterministic tests. */
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare class RequestEngine {
+    private readonly baseUrl;
+    private readonly transport;
+    private readonly userAgent;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly retryDelayMs;
+    private readonly maxRedirects;
+    private readonly maxResponseBytes;
+    private readonly sleep;
+    constructor(options?: EngineOptions);
+    /** Build a fully-qualified URL from a path and optional query parameters. */
+    buildUrl(path: string, query?: QueryParams): string;
+    /** Perform a request with Accept negotiation and transient-error retries. */
+    request(method: string, path: string, options?: {
+        query?: QueryParams;
+        accept: string;
+    }): Promise<RawResponse>;
+    /** Perform a GET expecting JSON and parse it into `T`. */
+    getJson<T>(path: string, query?: QueryParams): Promise<T>;
+    private toApiError;
+}
+//# sourceMappingURL=engine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/client/engine.ts"],"names":[],"mappings":"AAIA,OAAO,EAAqB,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAoB,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAGhE,eAAO,MAAM,gBAAgB,mCAAmC,CAAC;AAGjE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAOD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;gBAE1C,OAAO,GAAE,aAAkB;IAkBvC,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,MAAM;IAMnD,6EAA6E;IACvE,OAAO,CACX,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,WAAW,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAmC,GAChF,OAAO,CAAC,WAAW,CAAC;IAsDvB,0DAA0D;IACpD,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IAU/D,OAAO,CAAC,UAAU;CAYnB"}

package/dist/src/client/engine.js

@@ -0,0 +1,120 @@
+// 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 { buildQueryString } from "./query.js";
+import { PegelApiError, PegelError, PegelParseError } from "./errors.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;
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class RequestEngine {
+    baseUrl;
+    transport;
+    userAgent;
+    timeoutMs;
+    maxRetries;
+    retryDelayMs;
+    maxRedirects;
+    maxResponseBytes;
+    sleep;
+    constructor(options = {}) {
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        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.");
+        }
+        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.sleep = options.sleep ?? realSleep;
+    }
+    /** Build a fully-qualified URL from a path and optional query parameters. */
+    buildUrl(path, query) {
+        const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+        const qs = query ? buildQueryString(query) : "";
+        return `${this.baseUrl}${normalizedPath}${qs ? `?${qs}` : ""}`;
+    }
+    /** Perform a request with Accept negotiation and transient-error retries. */
+    async request(method, path, options = { accept: "application/json" }) {
+        let url = this.buildUrl(path, options.query);
+        const headers = {
+            Accept: options.accept,
+            "User-Agent": this.userAgent,
+        };
+        let attempt = 0;
+        let redirects = 0;
+        // attempts = initial try + maxRetries (redirects are counted separately)
+        for (;;) {
+            const response = await this.transport({
+                method,
+                url,
+                headers,
+                timeoutMs: this.timeoutMs,
+                ...(this.maxResponseBytes > 0 ? { maxResponseBytes: this.maxResponseBytes } : {}),
+            });
+            const status = response.status;
+            const retryable = status === 429 || status === 503;
+            if (retryable && attempt < this.maxRetries) {
+                attempt += 1;
+                await this.sleep(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 origins. The
+                    // CLI sends none today, but this guards a future Authorization/Cookie
+                    // header from leaking to an attacker-controlled redirect target.
+                    if (next.origin !== new URL(url).origin) {
+                        delete headers["Authorization"];
+                        delete headers["Cookie"];
+                    }
+                    url = next.toString();
+                    redirects += 1;
+                    continue;
+                }
+            }
+            const contentType = String(response.headers["content-type"] ?? "");
+            if (status < 200 || status >= 300) {
+                throw this.toApiError(method, url, status, response.body);
+            }
+            return { data: response.body, contentType, status };
+        }
+    }
+    /** Perform a GET expecting JSON and parse it into `T`. */
+    async getJson(path, query) {
+        const res = await this.request("GET", path, { query, accept: "application/json" });
+        const text = res.data.toString("utf8");
+        try {
+            return JSON.parse(text);
+        }
+        catch (cause) {
+            throw new PegelParseError(`Failed to parse JSON response from ${path}`, { cause });
+        }
+    }
+    toApiError(method, url, status, body) {
+        const text = body.toString("utf8");
+        let detail;
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed && typeof parsed.detail === "string")
+                detail = parsed.detail;
+            else if (parsed && typeof parsed.message === "string")
+                detail = parsed.message;
+        }
+        catch {
+            // Non-JSON error body; leave detail undefined.
+        }
+        return new PegelApiError({ status, url, method, body: text, detail });
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/src/client/engine.js.map

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

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

@@ -0,0 +1,33 @@
+/** Base class for every error originating from this client. */
+export declare class PegelError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The API responded with a non-2xx status code. `detail` holds a human-readable
+ * message extracted from the response body when one is present.
+ */
+export declare class PegelApiError extends PegelError {
+    readonly status: number;
+    readonly detail: string | undefined;
+    readonly url: string;
+    readonly method: string;
+    readonly body: string;
+    constructor(args: {
+        status: number;
+        url: string;
+        method: string;
+        body: string;
+        detail?: string;
+    });
+    /** True for statuses the API documents as transient and retry-able. */
+    get isRetryable(): boolean;
+}
+/** 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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/client/errors.ts"],"names":[],"mappings":"AAGA,+DAA+D;AAC/D,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED;;;GAGG;AACH,qBAAa,aAAc,SAAQ,UAAU;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;IAUD,uEAAuE;IACvE,IAAI,WAAW,IAAI,OAAO,CAEzB;CACF;AAED,uEAAuE;AACvE,qBAAa,iBAAkB,SAAQ,UAAU;CAAG;AAEpD,wEAAwE;AACxE,qBAAa,eAAgB,SAAQ,UAAU;CAAG"}

package/dist/src/client/errors.js

@@ -0,0 +1,40 @@
+// Error types raised by the client. Kept free of any I/O so they are trivial to
+// construct in tests and to `instanceof`-check by consumers.
+/** Base class for every error originating from this client. */
+export class PegelError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+/**
+ * The API responded with a non-2xx status code. `detail` holds a human-readable
+ * message extracted from the response body when one is present.
+ */
+export class PegelApiError extends PegelError {
+    status;
+    detail;
+    url;
+    method;
+    body;
+    constructor(args) {
+        const detailPart = args.detail ? `: ${args.detail}` : "";
+        super(`HTTP ${args.status} for ${args.method} ${args.url}${detailPart}`);
+        this.status = args.status;
+        this.url = args.url;
+        this.method = args.method;
+        this.body = args.body;
+        this.detail = args.detail;
+    }
+    /** True for statuses the API documents as transient and retry-able. */
+    get isRetryable() {
+        return this.status === 429 || this.status === 503;
+    }
+}
+/** 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/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/client/errors.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,6DAA6D;AAE7D,+DAA+D;AAC/D,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IAC9B,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,aAAc,SAAQ,UAAU;IAClC,MAAM,CAAS;IACf,MAAM,CAAqB;IAC3B,GAAG,CAAS;IACZ,MAAM,CAAS;IACf,IAAI,CAAS;IAEtB,YAAY,IAMX;QACC,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,KAAK,CAAC,QAAQ,IAAI,CAAC,MAAM,QAAQ,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,GAAG,UAAU,EAAE,CAAC,CAAC;QACzE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;QACpB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED,uEAAuE;IACvE,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC;IACpD,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,OAAO,iBAAkB,SAAQ,UAAU;CAAG;AAEpD,wEAAwE;AACxE,MAAM,OAAO,eAAgB,SAAQ,UAAU;CAAG"}

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

@@ -0,0 +1,26 @@
+import http from "node:http";
+export interface HttpRequest {
+    method: string;
+    /** Fully-qualified absolute URL. */
+    url: string;
+    headers?: Record<string, string>;
+    /** Optional request body (already serialised). */
+    body?: string | Buffer;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Hard cap on the response body size in bytes; the request aborts if exceeded. */
+    maxResponseBytes?: number;
+}
+export interface HttpResponse {
+    status: number;
+    headers: http.IncomingHttpHeaders;
+    body: Buffer;
+}
+export type Transport = (request: HttpRequest) => Promise<HttpResponse>;
+/**
+ * Default transport. Resolves with the raw response (including non-2xx) — status
+ * interpretation is the client's job. Rejects only on transport-level failures
+ * (connection errors, timeouts, malformed URLs).
+ */
+export declare const nodeHttpTransport: Transport;
+//# sourceMappingURL=http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/client/http.ts"],"names":[],"mappings":"AAQA,OAAO,IAAI,MAAM,WAAW,CAAC;AAI7B,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kDAAkD;IAClD,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,IAAI,CAAC,mBAAmB,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAwE5B,CAAC"}

package/dist/src/client/http.js

@@ -0,0 +1,82 @@
+// HTTP transport built on Node's built-in `http`/`https` modules — no axios,
+// no fetch polyfill, no third-party HTTP client.
+//
+// The transport is a plain function so it can be trivially swapped out in tests
+// (inject a `mock.fn()` returning a canned HttpResponse) without touching the
+// network. The default implementation below is exercised against a real local
+// `http.createServer` in the test-suite.
+import http from "node:http";
+import https from "node:https";
+import { PegelNetworkError } from "./errors.js";
+/**
+ * Default transport. Resolves with the raw response (including non-2xx) — status
+ * interpretation is the client's job. Rejects only on transport-level failures
+ * (connection errors, timeouts, malformed URLs).
+ */
+export const nodeHttpTransport = (request) => new Promise((resolve, reject) => {
+    let url;
+    try {
+        url = new URL(request.url);
+    }
+    catch {
+        reject(new PegelNetworkError(`Invalid URL: ${request.url}`));
+        return;
+    }
+    // Only http/https are supported. Reject anything else up front with a clear,
+    // typed error instead of letting Node throw an opaque ERR_INVALID_PROTOCOL
+    // (and so this never reaches the file:/ftp:/etc. drivers).
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        reject(new PegelNetworkError(`Unsupported protocol "${url.protocol}" in URL: ${request.url}`));
+        return;
+    }
+    const isHttps = url.protocol === "https:";
+    const driver = isHttps ? https : http;
+    const maxBytes = request.maxResponseBytes;
+    const req = driver.request(url, {
+        method: request.method,
+        headers: request.headers,
+    }, (res) => {
+        const chunks = [];
+        let received = 0;
+        let aborted = false;
+        res.on("data", (chunk) => {
+            if (aborted)
+                return;
+            received += chunk.length;
+            if (maxBytes !== undefined && received > maxBytes) {
+                aborted = true;
+                res.destroy();
+                reject(new PegelNetworkError(`Response exceeded maxResponseBytes (${maxBytes})`));
+                return;
+            }
+            chunks.push(chunk);
+        });
+        res.on("end", () => {
+            if (aborted)
+                return;
+            resolve({
+                status: res.statusCode ?? 0,
+                headers: res.headers,
+                body: Buffer.concat(chunks),
+            });
+        });
+        res.on("error", (err) => {
+            if (aborted)
+                return; // we already rejected with the size-cap error
+            reject(new PegelNetworkError(`Response stream error: ${err.message}`, { cause: err }));
+        });
+    });
+    if (request.timeoutMs && request.timeoutMs > 0) {
+        req.setTimeout(request.timeoutMs, () => {
+            req.destroy(new PegelNetworkError(`Request timed out after ${request.timeoutMs}ms`));
+        });
+    }
+    req.on("error", (err) => {
+        // A timeout destroy already passes an PegelNetworkError; don't double-wrap.
+        reject(err instanceof PegelNetworkError ? err : new PegelNetworkError(err.message, { cause: err }));
+    });
+    if (request.body !== undefined)
+        req.write(request.body);
+    req.end();
+});
+//# sourceMappingURL=http.js.map

package/dist/src/client/http.js.map

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

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

@@ -0,0 +1,10 @@
+export { PegelOnlineClient } from "./client.js";
+export { RequestEngine, DEFAULT_BASE_URL } from "./engine.js";
+export type { EngineOptions, RawResponse } from "./engine.js";
+export { 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 } from "./errors.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9D,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC9C,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE5F,cAAc,YAAY,CAAC"}

package/dist/src/client/index.js

@@ -0,0 +1,8 @@
+// Public entry point for the API client library.
+export { PegelOnlineClient } from "./client.js";
+export { RequestEngine, DEFAULT_BASE_URL } from "./engine.js";
+export { nodeHttpTransport } from "./http.js";
+export { buildQueryString } from "./query.js";
+export { PegelError, PegelApiError, PegelNetworkError, PegelParseError } from "./errors.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/src/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA,iDAAiD;AAEjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE5F,cAAc,YAAY,CAAC"}