@maschinenlesbar.org/luftqualitaet-cli 0.0.1

package/dist/src/cli/run.js

@@ -0,0 +1,48 @@
+// Run the CLI and resolve to a process exit code. Kept separate from the bin
+// shim so tests can call run() directly with injected deps and assert on the
+// captured output and exit code without spawning a subprocess.
+import { CommanderError } from "commander";
+import { buildProgram, defaultDeps } from "./program.js";
+import { LuftApiError, LuftError } from "../client/errors.js";
+/**
+ * Apply exitOverride + output redirection to every command in the tree.
+ * commander does not propagate these to subcommands, so a parse error on a
+ * subcommand would otherwise call process.exit() and bypass our error handling.
+ */
+function configureTree(command, deps) {
+    command.exitOverride();
+    command.configureOutput({
+        writeOut: (str) => deps.io.out(str.replace(/\n$/, "")),
+        writeErr: (str) => deps.io.err(str.replace(/\n$/, "")),
+    });
+    for (const child of command.commands)
+        configureTree(child, deps);
+}
+export async function run(argv, deps = defaultDeps) {
+    const program = buildProgram(deps);
+    configureTree(program, deps);
+    try {
+        await program.parseAsync(argv, { from: "user" });
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            // Help/version requests exit 0; genuine parse errors carry their own code.
+            return err.exitCode;
+        }
+        if (err instanceof LuftApiError) {
+            deps.io.err(`Error: ${err.message}`);
+            // Map a few notable statuses to distinct exit codes for scripting.
+            if (err.status === 404)
+                return 4;
+            return 1;
+        }
+        if (err instanceof LuftError) {
+            deps.io.err(`Error: ${err.message}`);
+            return 1;
+        }
+        deps.io.err(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}
+//# sourceMappingURL=run.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../src/cli/run.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,6EAA6E;AAC7E,+DAA+D;AAE/D,OAAO,EAAE,cAAc,EAAgB,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEzD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE9D;;;;GAIG;AACH,SAAS,aAAa,CAAC,OAAgB,EAAE,IAAa;IACpD,OAAO,CAAC,YAAY,EAAE,CAAC;IACvB,OAAO,CAAC,eAAe,CAAC;QACtB,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACtD,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;KACvD,CAAC,CAAC;IACH,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,QAAQ;QAAE,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,IAAc,EAAE,OAAgB,WAAW;IACnE,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACnC,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAE7B,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACjD,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;YAClC,2EAA2E;YAC3E,OAAO,GAAG,CAAC,QAAQ,CAAC;QACtB,CAAC;QACD,IAAI,GAAG,YAAY,YAAY,EAAE,CAAC;YAChC,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACrC,mEAAmE;YACnE,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;gBAAE,OAAO,CAAC,CAAC;YACjC,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,GAAG,YAAY,SAAS,EAAE,CAAC;YAC7B,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACrC,OAAO,CAAC,CAAC;QACX,CAAC;QACD,IAAI,CAAC,EAAE,CAAC,GAAG,CAAC,qBAAqB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrF,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC"}

package/dist/src/cli/shared.d.ts

@@ -0,0 +1,65 @@
+import type { CliDeps } from "./io.js";
+import type { EngineOptions } from "../client/engine.js";
+import type { IndexKind, Lang } from "../client/enums.js";
+/** commander value-parser: a non-negative integer. */
+export declare function parseIntArg(value: string): number;
+/**
+ * commander value-parser: a positive integer (>= 1). Used for ids — station,
+ * component and scope ids are 1-based in this API, so `0` is a user error that
+ * should be caught locally rather than sent.
+ */
+export declare function parsePositiveIntArg(value: string): number;
+/**
+ * commander value-parser: an hour in the API's hour-ending range `1..24`.
+ * (The UBA API uses hour-ending times; `0` and `> 24` are invalid.)
+ */
+export declare function parseHour(value: string): number;
+/** commander value-parser: a four-digit year, `>= 2016` (the API's earliest). */
+export declare function parseYear(value: string): number;
+/**
+ * commander value-parser for `--lang`. Rejects a flag-like value (one starting
+ * with `-`): commander would otherwise consume the *next* option (e.g. `--index`)
+ * as this option's value, producing a confusing downstream "too many arguments"
+ * error. Membership in the allowed set is still validated later by `lang()`.
+ */
+export declare function parseLangArg(value: string): string;
+/** commander value-parser for `--index`; see `parseLangArg`. */
+export declare function parseIndexArg(value: string): string;
+/**
+ * Validate a positional argument against an allowed set (commander does not
+ * support .choices() on positional args). Throws a LuftError so run() prints a
+ * clear message and exits 1.
+ */
+export declare function assertEnum<T extends string>(value: string, allowed: readonly T[], argName: string): T;
+/** Resolve and validate the optional `--lang` option shared by many commands. */
+export declare function lang(opts: Record<string, unknown>): Lang | undefined;
+/** Resolve and validate the optional `--index` option shared by many commands. */
+export declare function index(opts: Record<string, unknown>): IndexKind | undefined;
+export interface GlobalOptions {
+    baseUrl?: string;
+    timeout?: number;
+    userAgent?: string;
+    maxRetries?: number;
+    maxResponseBytes?: number;
+    compact?: boolean;
+}
+/** Translate resolved global CLI options into client EngineOptions. */
+export declare function toEngineOptions(global: GlobalOptions): EngineOptions;
+/** Render a JSON value to stdout, pretty by default, compact with --compact. */
+export declare function renderJson(deps: CliDeps, global: GlobalOptions, value: unknown): void;
+export interface ActionContext {
+    client: ReturnType<CliDeps["createClient"]>;
+    global: GlobalOptions;
+    /** This command's own parsed options. */
+    opts: Record<string, unknown>;
+}
+/**
+ * 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 declare function action(deps: CliDeps, fn: (ctx: ActionContext, positionals: string[]) => Promise<void>): (...args: unknown[]) => Promise<void>;
+//# sourceMappingURL=shared.d.ts.map

package/dist/src/cli/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/cli/shared.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAmB1D,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMzD;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED,iFAAiF;AACjF,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKlD;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKnD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,EACzC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,OAAO,EAAE,MAAM,GACd,CAAC,CAKH;AAED,iFAAiF;AACjF,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAIpE;AAED,kFAAkF;AAClF,wBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,SAAS,CAI1E;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAQpE;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAGrF;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;IAC5C,MAAM,EAAE,aAAa,CAAC;IACtB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CACpB,IAAI,EAAE,OAAO,EACb,EAAE,EAAE,CAAC,GAAG,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,GAC/D,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAQvC"}

package/dist/src/cli/shared.js

@@ -0,0 +1,142 @@
+// Shared helpers used across CLI command groups: option parsers, the global
+// option resolver, and the JSON result renderer.
+import { InvalidArgumentError } from "commander";
+import { LuftError } from "../client/errors.js";
+import { IndexValues, LangValues } from "../client/enums.js";
+/**
+ * Strictly parse a plain decimal integer string into a number.
+ *
+ * Unlike `Number()`, this rejects hex (`0x..`), binary (`0b..`), octal (`0o..`),
+ * scientific (`1e3`), explicit-sign (`+5`), and whitespace-padded forms: only an
+ * optional leading `-` followed by ASCII digits is accepted. It also rejects
+ * values that cannot be represented exactly as a JS integer (`> 2^53 - 1`), so a
+ * user-supplied id is never silently rounded before being sent. Returns
+ * `undefined` on any non-conforming input; callers map that to a clear error.
+ */
+function parseStrictInt(value) {
+    if (!/^-?\d+$/.test(value))
+        return undefined;
+    const n = Number(value);
+    if (!Number.isSafeInteger(n))
+        return undefined;
+    return n;
+}
+/** commander value-parser: a non-negative integer. */
+export function parseIntArg(value) {
+    const n = parseStrictInt(value);
+    if (n === undefined || n < 0) {
+        throw new InvalidArgumentError("Expected a non-negative integer.");
+    }
+    return n;
+}
+/**
+ * commander value-parser: a positive integer (>= 1). Used for ids — station,
+ * component and scope ids are 1-based in this API, so `0` is a user error that
+ * should be caught locally rather than sent.
+ */
+export function parsePositiveIntArg(value) {
+    const n = parseStrictInt(value);
+    if (n === undefined || n < 1) {
+        throw new InvalidArgumentError("Expected a positive integer (>= 1).");
+    }
+    return n;
+}
+/**
+ * commander value-parser: an hour in the API's hour-ending range `1..24`.
+ * (The UBA API uses hour-ending times; `0` and `> 24` are invalid.)
+ */
+export function parseHour(value) {
+    const n = parseStrictInt(value);
+    if (n === undefined || n < 1 || n > 24) {
+        throw new InvalidArgumentError("Expected an hour in the range 1..24.");
+    }
+    return n;
+}
+/** commander value-parser: a four-digit year, `>= 2016` (the API's earliest). */
+export function parseYear(value) {
+    const n = parseStrictInt(value);
+    if (n === undefined || n < 2016 || n > 9999) {
+        throw new InvalidArgumentError("Expected a four-digit year >= 2016.");
+    }
+    return n;
+}
+/**
+ * commander value-parser for `--lang`. Rejects a flag-like value (one starting
+ * with `-`): commander would otherwise consume the *next* option (e.g. `--index`)
+ * as this option's value, producing a confusing downstream "too many arguments"
+ * error. Membership in the allowed set is still validated later by `lang()`.
+ */
+export function parseLangArg(value) {
+    if (value.startsWith("-")) {
+        throw new InvalidArgumentError("Option '--lang' requires a value (e.g. de | en).");
+    }
+    return value;
+}
+/** commander value-parser for `--index`; see `parseLangArg`. */
+export function parseIndexArg(value) {
+    if (value.startsWith("-")) {
+        throw new InvalidArgumentError("Option '--index' requires a value (e.g. id | code).");
+    }
+    return value;
+}
+/**
+ * Validate a positional argument against an allowed set (commander does not
+ * support .choices() on positional args). Throws a LuftError so run() prints a
+ * clear message and exits 1.
+ */
+export function assertEnum(value, allowed, argName) {
+    if (!allowed.includes(value)) {
+        throw new LuftError(`Invalid ${argName} "${value}". Expected one of: ${allowed.join(", ")}.`);
+    }
+    return value;
+}
+/** Resolve and validate the optional `--lang` option shared by many commands. */
+export function lang(opts) {
+    return opts["lang"] === undefined
+        ? undefined
+        : assertEnum(String(opts["lang"]), LangValues, "lang");
+}
+/** Resolve and validate the optional `--index` option shared by many commands. */
+export function index(opts) {
+    return opts["index"] === undefined
+        ? undefined
+        : assertEnum(String(opts["index"]), IndexValues, "index");
+}
+/** 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,30 @@
+import { type EngineOptions } from "./engine.js";
+import type { AirDataResult, ListParams, WindowParams, MeasuresParams, YearComponentParams, ThresholdParams, MetaParams } from "./types.js";
+import type { Lang } from "./enums.js";
+export declare class LuftqualitaetClient {
+    private readonly engine;
+    constructor(options?: EngineOptions);
+    /** Air-quality index data for a station over a time window. */
+    airquality(params: WindowParams): Promise<AirDataResult>;
+    /** The available date range per station for air-quality data. */
+    airqualityLimits(): Promise<AirDataResult>;
+    /** Raw measurement data for a station over a window (optional component/scope). */
+    measures(params: MeasuresParams): Promise<AirDataResult>;
+    /** The available date range per scope/component/station for measurements. */
+    measuresLimits(): Promise<AirDataResult>;
+    /** Annual tabulations for a component and year (>= 2016). */
+    annualBalances(params: YearComponentParams): Promise<AirDataResult>;
+    /** Exceedance (Überschreitungen) data for a component and year. */
+    transgressions(params: YearComponentParams): Promise<AirDataResult>;
+    components(params?: ListParams): Promise<AirDataResult>;
+    networks(params?: ListParams): Promise<AirDataResult>;
+    scopes(params?: ListParams): Promise<AirDataResult>;
+    stationSettings(lang?: Lang): Promise<AirDataResult>;
+    stationTypes(lang?: Lang): Promise<AirDataResult>;
+    transgressionTypes(lang?: Lang): Promise<AirDataResult>;
+    /** Thresholds for a use (airquality | measure), optional component/scope. */
+    thresholds(params: ThresholdParams): Promise<AirDataResult>;
+    /** Combined metadata for a use (components, scopes, networks, stations, ...). */
+    meta(params: MetaParams): Promise<AirDataResult>;
+}
+//# 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":"AAMA,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EACV,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,UAAU,EACX,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAavC,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;gBAE3B,OAAO,GAAE,aAAkB;IAMvC,+DAA+D;IAC/D,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAIxD,iEAAiE;IACjE,gBAAgB,IAAI,OAAO,CAAC,aAAa,CAAC;IAI1C,mFAAmF;IACnF,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAIxD,6EAA6E;IAC7E,cAAc,IAAI,OAAO,CAAC,aAAa,CAAC;IAMxC,6DAA6D;IAC7D,cAAc,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC;IAInE,mEAAmE;IACnE,cAAc,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC;IAMnE,UAAU,CAAC,MAAM,GAAE,UAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IAI3D,QAAQ,CAAC,MAAM,GAAE,UAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IAIzD,MAAM,CAAC,MAAM,GAAE,UAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IAIvD,eAAe,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC;IAIpD,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC;IAIjD,kBAAkB,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC;IAIvD,6EAA6E;IAC7E,UAAU,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC;IAI3D,iFAAiF;IACjF,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;CAGjD"}

package/dist/src/client/client.js

@@ -0,0 +1,76 @@
+// LuftqualitaetClient — a typed client over the open (no-auth) Air Data API of
+// the Umweltbundesamt (https://www.umweltbundesamt.de/api/air_data/v3).
+//
+//   client.components({ lang: "de" })
+//   client.airquality({ date_from: "2024-01-01", time_from: 1, date_to: "2024-01-01", time_to: 24, station: 143 })
+import { RequestEngine } from "./engine.js";
+const API = "/api/air_data/v3";
+/** 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;
+}
+export class LuftqualitaetClient {
+    engine;
+    constructor(options = {}) {
+        this.engine = new RequestEngine(options);
+    }
+    // --- Air-quality index & raw measures -------------------------------------
+    /** Air-quality index data for a station over a time window. */
+    airquality(params) {
+        return this.engine.getJson(`${API}/airquality/json`, prune({ ...params }));
+    }
+    /** The available date range per station for air-quality data. */
+    airqualityLimits() {
+        return this.engine.getJson(`${API}/airquality/limits`);
+    }
+    /** Raw measurement data for a station over a window (optional component/scope). */
+    measures(params) {
+        return this.engine.getJson(`${API}/measures/json`, prune({ ...params }));
+    }
+    /** The available date range per scope/component/station for measurements. */
+    measuresLimits() {
+        return this.engine.getJson(`${API}/measures/limits`);
+    }
+    // --- Aggregations ---------------------------------------------------------
+    /** Annual tabulations for a component and year (>= 2016). */
+    annualBalances(params) {
+        return this.engine.getJson(`${API}/annualbalances/json`, prune({ ...params }));
+    }
+    /** Exceedance (Überschreitungen) data for a component and year. */
+    transgressions(params) {
+        return this.engine.getJson(`${API}/transgressions/json`, prune({ ...params }));
+    }
+    // --- Reference lists ------------------------------------------------------
+    components(params = {}) {
+        return this.engine.getJson(`${API}/components/json`, prune({ ...params }));
+    }
+    networks(params = {}) {
+        return this.engine.getJson(`${API}/networks/json`, prune({ ...params }));
+    }
+    scopes(params = {}) {
+        return this.engine.getJson(`${API}/scopes/json`, prune({ ...params }));
+    }
+    stationSettings(lang) {
+        return this.engine.getJson(`${API}/stationsettings/json`, prune({ lang }));
+    }
+    stationTypes(lang) {
+        return this.engine.getJson(`${API}/stationtypes/json`, prune({ lang }));
+    }
+    transgressionTypes(lang) {
+        return this.engine.getJson(`${API}/transgressiontypes/json`, prune({ lang }));
+    }
+    /** Thresholds for a use (airquality | measure), optional component/scope. */
+    thresholds(params) {
+        return this.engine.getJson(`${API}/thresholds/json`, prune({ ...params }));
+    }
+    /** Combined metadata for a use (components, scopes, networks, stations, ...). */
+    meta(params) {
+        return this.engine.getJson(`${API}/meta/json`, prune({ ...params }));
+    }
+}
+//# 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.umweltbundesamt.de";
+export interface RawResponse {
+    data: Buffer;
+    contentType: string;
+    status: number;
+}
+export interface EngineOptions {
+    /** Base URL of the API. Defaults to https://www.umweltbundesamt.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;IAYvC,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;IAwDvB,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,117 @@
+// 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 { LuftApiError, LuftParseError } from "./errors.js";
+export const DEFAULT_BASE_URL = "https://www.umweltbundesamt.de";
+const DEFAULT_USER_AGENT = "luftqualitaet-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;
+        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 target = new URL(location, url);
+                    // Cross-origin redirect: strip request headers so any sensitive
+                    // header (e.g. an Authorization/token added later) is never leaked to
+                    // a different origin. Today only Accept/User-Agent are sent, so we
+                    // re-add those benign defaults to keep negotiation working.
+                    if (target.origin !== new URL(url).origin) {
+                        for (const key of Object.keys(headers))
+                            delete headers[key];
+                        headers["Accept"] = options.accept;
+                        headers["User-Agent"] = this.userAgent;
+                    }
+                    url = target.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 LuftParseError(`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 LuftApiError({ 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/enums.d.ts

@@ -0,0 +1,13 @@
+/** Response language. */
+export declare const LangValues: readonly ["de", "en"];
+export type Lang = (typeof LangValues)[number];
+/** How reference lists are keyed in the response. */
+export declare const IndexValues: readonly ["id", "code"];
+export type IndexKind = (typeof IndexValues)[number];
+/** `use` values for the combined metadata endpoint. */
+export declare const MetaUseValues: readonly ["airquality", "measure", "transgression", "annualbalance", "map"];
+export type MetaUse = (typeof MetaUseValues)[number];
+/** `use` values for the thresholds endpoint. */
+export declare const ThresholdUseValues: readonly ["airquality", "measure"];
+export type ThresholdUse = (typeof ThresholdUseValues)[number];
+//# sourceMappingURL=enums.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"enums.d.ts","sourceRoot":"","sources":["../../../src/client/enums.ts"],"names":[],"mappings":"AAGA,yBAAyB;AACzB,eAAO,MAAM,UAAU,uBAAwB,CAAC;AAChD,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/C,qDAAqD;AACrD,eAAO,MAAM,WAAW,yBAA0B,CAAC;AACnD,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,uDAAuD;AACvD,eAAO,MAAM,aAAa,6EAMhB,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,gDAAgD;AAChD,eAAO,MAAM,kBAAkB,oCAAqC,CAAC;AACrE,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/src/client/enums.js

@@ -0,0 +1,17 @@
+// Enum-like value sets. These const arrays double as runtime CLI choice
+// validators and as TS union types.
+/** Response language. */
+export const LangValues = ["de", "en"];
+/** How reference lists are keyed in the response. */
+export const IndexValues = ["id", "code"];
+/** `use` values for the combined metadata endpoint. */
+export const MetaUseValues = [
+    "airquality",
+    "measure",
+    "transgression",
+    "annualbalance",
+    "map",
+];
+/** `use` values for the thresholds endpoint. */
+export const ThresholdUseValues = ["airquality", "measure"];
+//# sourceMappingURL=enums.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"enums.js","sourceRoot":"","sources":["../../../src/client/enums.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,oCAAoC;AAEpC,yBAAyB;AACzB,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,IAAI,CAAU,CAAC;AAGhD,qDAAqD;AACrD,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,CAAU,CAAC;AAGnD,uDAAuD;AACvD,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,YAAY;IACZ,SAAS;IACT,eAAe;IACf,eAAe;IACf,KAAK;CACG,CAAC;AAGX,gDAAgD;AAChD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,YAAY,EAAE,SAAS,CAAU,CAAC"}