@iflow-mcp/kitfunso-luminus 0.2.0

package/dist/lib/auth.js

@@ -0,0 +1,199 @@
+import { z } from "zod";
+import { readFile, stat } from "node:fs/promises";
+import { timingSafeEqual } from "node:crypto";
+import { join } from "node:path";
+import { homedir } from "node:os";
+// ConfigurationError
+export class ConfigurationError extends Error {
+    constructor(keyName) {
+        super(`API key "${keyName}" is not configured.\n\n` +
+            `Resolution order:\n` +
+            `  1. Environment variable: ${keyName}\n` +
+            `  2. Key file: ${join(homedir(), ".luminus", "keys.json")} → { "${keyName}": "..." }\n\n` +
+            `Set one of the above and restart the server.`);
+        this.name = "ConfigurationError";
+    }
+}
+// Key file schema + cache
+const KeyFileSchema = z.record(z.string(), z.string());
+let cachedKeyFile = null;
+let keyFileChecked = false;
+const KEYS_PATH = join(homedir(), ".luminus", "keys.json");
+async function warnOpenPermissions(filePath) {
+    if (process.platform === "win32")
+        return;
+    try {
+        const info = await stat(filePath);
+        const mode = info.mode & 0o777;
+        if (mode & 0o077) {
+            process.stderr.write(`[luminus] WARNING: ${filePath} is readable by others (mode ${mode.toString(8)}). ` +
+                `Run: chmod 600 ${filePath}\n`);
+        }
+    }
+    catch {
+        // stat failed — file may not exist, which is fine
+    }
+}
+async function loadKeyFile() {
+    if (keyFileChecked)
+        return cachedKeyFile ?? {};
+    keyFileChecked = true;
+    try {
+        await warnOpenPermissions(KEYS_PATH);
+        const raw = await readFile(KEYS_PATH, "utf-8");
+        const parsed = KeyFileSchema.parse(JSON.parse(raw));
+        cachedKeyFile = parsed;
+        return parsed;
+    }
+    catch (err) {
+        // Distinguish "file not found" (normal) from "file exists but is broken" (warn)
+        const isNotFound = err instanceof Error && "code" in err && err.code === "ENOENT";
+        if (!isNotFound) {
+            process.stderr.write(`[luminus] WARNING: failed to load ${KEYS_PATH}: ${err instanceof Error ? err.message : String(err)}\n`);
+        }
+        cachedKeyFile = null;
+        return {};
+    }
+}
+// Resolved key cache (in-memory, per-process)
+const resolvedKeys = new Map();
+/**
+ * Resolve an API key by name. Tries environment variables first, then
+ * ~/.luminus/keys.json. Throws ConfigurationError if not found.
+ * Resolved values are cached in memory for the process lifetime.
+ */
+export async function resolveApiKey(name) {
+    const cached = resolvedKeys.get(name);
+    if (cached !== undefined)
+        return cached;
+    // Layer 1: environment variable
+    const envValue = process.env[name];
+    if (envValue) {
+        resolvedKeys.set(name, envValue);
+        return envValue;
+    }
+    // Layer 2: key file
+    const fileKeys = await loadKeyFile();
+    const fileValue = fileKeys[name];
+    if (fileValue) {
+        resolvedKeys.set(name, fileValue);
+        return fileValue;
+    }
+    // Not found
+    throw new ConfigurationError(name);
+}
+/** Constant-time string comparison. Reserved for future client authentication. */
+export function timingSafeCompare(a, b) {
+    const bufA = Buffer.from(a);
+    const bufB = Buffer.from(b);
+    if (bufA.length !== bufB.length)
+        return false;
+    return timingSafeEqual(bufA, bufB);
+}
+/**
+ * Map of tool name to required API key names.
+ * Empty array = public API, no key needed.
+ */
+export const TOOL_KEY_REQUIREMENTS = {
+    // ENTSO-E tools
+    get_generation_mix: ["ENTSOE_API_KEY"],
+    get_day_ahead_prices: ["ENTSOE_API_KEY"],
+    get_cross_border_flows: ["ENTSOE_API_KEY"],
+    get_carbon_intensity: ["ENTSOE_API_KEY"],
+    get_balancing_prices: ["ENTSOE_API_KEY"],
+    get_renewable_forecast: ["ENTSOE_API_KEY"],
+    get_demand_forecast: ["ENTSOE_API_KEY"],
+    get_outages: ["ENTSOE_API_KEY"],
+    get_net_positions: ["ENTSOE_API_KEY"],
+    get_transfer_capacities: ["ENTSOE_API_KEY"],
+    get_hydro_reservoir: ["ENTSOE_API_KEY"],
+    get_intraday_prices: ["ENTSOE_API_KEY"],
+    get_imbalance_prices: ["ENTSOE_API_KEY"],
+    get_intraday_da_spread: ["ENTSOE_API_KEY"],
+    get_realtime_generation: ["ENTSOE_API_KEY"],
+    get_balancing_actions: ["ENTSOE_API_KEY"],
+    get_ancillary_prices: ["ENTSOE_API_KEY"],
+    get_remit_messages: ["ENTSOE_API_KEY"],
+    get_price_spread_analysis: ["ENTSOE_API_KEY"],
+    // GIE (Gas Infrastructure Europe) tools
+    get_gas_storage: ["GIE_API_KEY"],
+    get_lng_terminals: ["GIE_API_KEY"],
+    // EIA (US Energy Information Administration)
+    get_us_gas_data: ["EIA_API_KEY"],
+    // Fingrid (Finnish grid)
+    get_fingrid_data: ["FINGRID_API_KEY"],
+    // REE ESIOS (Spanish grid)
+    get_ree_esios: ["ESIOS_API_TOKEN"],
+    // Storm Glass (marine weather)
+    get_stormglass: ["STORMGLASS_API_KEY"],
+    // Public APIs — no key required
+    get_weather_forecast: [],
+    get_uk_carbon_intensity: [],
+    get_uk_grid_demand: [],
+    get_power_plants: [],
+    get_auction_results: [],
+    get_solar_irradiance: [],
+    get_eu_frequency: [],
+    get_transmission_lines: [],
+    get_energy_charts: [],
+    get_commodity_prices: [],
+    get_nordpool_prices: [],
+    get_smard_data: [],
+    get_entsog_data: [],
+    get_elexon_bmrs: [],
+    get_era5_weather: [],
+    get_regelleistung: [],
+    get_rte_france: [],
+    get_energi_data: [],
+    get_hydro_inflows: [],
+    get_acer_remit: [],
+    get_terna_data: [],
+    get_eu_gas_price: [],
+    get_terrain_analysis: [],
+    get_grid_proximity: [],
+    get_grid_connection_queue: [],
+    get_grid_connection_intelligence: [],
+    get_land_constraints: [],
+    get_agricultural_land: [],
+    get_flood_risk: [],
+    screen_site: [],
+    verify_gis_sources: [],
+    compare_sites: [],
+    estimate_site_revenue: ["ENTSOE_API_KEY"],
+};
+/**
+ * Check whether all API keys for a tool are resolvable right now.
+ * Checks environment variables and the cached key file synchronously.
+ * Returns true for tools with no key requirements.
+ */
+export function hasRequiredKeys(toolName) {
+    const requirements = TOOL_KEY_REQUIREMENTS[toolName];
+    if (!requirements || requirements.length === 0)
+        return true;
+    return requirements.every((keyName) => {
+        // Check in-memory cache first
+        if (resolvedKeys.has(keyName))
+            return true;
+        // Check env
+        if (process.env[keyName])
+            return true;
+        // Check file cache (loaded asynchronously, may not be ready yet)
+        if (cachedKeyFile?.[keyName])
+            return true;
+        return false;
+    });
+}
+/** Check whether a specific API key name is available (env or key file). */
+export function isKeyConfigured(keyName) {
+    if (resolvedKeys.has(keyName))
+        return true;
+    if (process.env[keyName])
+        return true;
+    if (cachedKeyFile?.[keyName])
+        return true;
+    return false;
+}
+/** Pre-load keys.json so hasRequiredKeys works immediately. */
+export async function preloadKeyFile() {
+    await loadKeyFile();
+}

package/dist/lib/cache.d.ts

@@ -0,0 +1,25 @@
+/** Simple in-memory TTL cache */
+export declare class TtlCache {
+    private store;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, data: T, ttlMs: number): void;
+    clear(): void;
+}
+/** Cache TTL constants in milliseconds */
+export declare const TTL: {
+    readonly REALTIME: number;
+    readonly PRICES: number;
+    readonly CAPACITY: number;
+    readonly FLOWS: number;
+    readonly STORAGE: number;
+    readonly WEATHER: number;
+    readonly EIA: number;
+    readonly FORECAST: number;
+    readonly BALANCING: number;
+    readonly STATIC_DATA: number;
+    readonly AUCTION: number;
+    readonly ANCILLARY: number;
+    readonly OUTAGES: number;
+    readonly FREQUENCY: number;
+    readonly INTRADAY: number;
+};

package/dist/lib/cache.js

@@ -0,0 +1,38 @@
+/** Simple in-memory TTL cache */
+export class TtlCache {
+    store = new Map();
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return entry.data;
+    }
+    set(key, data, ttlMs) {
+        this.store.set(key, { data, expiresAt: Date.now() + ttlMs });
+    }
+    clear() {
+        this.store.clear();
+    }
+}
+/** Cache TTL constants in milliseconds */
+export const TTL = {
+    REALTIME: 5 * 60 * 1000, // 5 min
+    PRICES: 60 * 60 * 1000, // 1 hour
+    CAPACITY: 24 * 60 * 60 * 1000, // 24 hours
+    FLOWS: 5 * 60 * 1000, // 5 min
+    STORAGE: 60 * 60 * 1000, // 1 hour
+    WEATHER: 30 * 60 * 1000, // 30 min
+    EIA: 60 * 60 * 1000, // 1 hour
+    FORECAST: 60 * 60 * 1000, // 1 hour
+    BALANCING: 5 * 60 * 1000, // 5 min
+    STATIC_DATA: 24 * 60 * 60 * 1000, // 24 hours
+    AUCTION: 60 * 60 * 1000, // 1 hour
+    ANCILLARY: 60 * 60 * 1000, // 1 hour
+    OUTAGES: 15 * 60 * 1000, // 15 min
+    FREQUENCY: 30 * 1000, // 30 sec
+    INTRADAY: 15 * 60 * 1000, // 15 min
+};

package/dist/lib/cli.d.ts

@@ -0,0 +1 @@
+export declare function parseProfileArg(argv: string[]): string;

package/dist/lib/cli.js

@@ -0,0 +1,10 @@
+export function parseProfileArg(argv) {
+    const idx = argv.indexOf("--profile");
+    if (idx === -1)
+        return "full";
+    const value = argv[idx + 1];
+    if (!value || value.startsWith("--")) {
+        throw new Error("Missing value for --profile.");
+    }
+    return value;
+}

package/dist/lib/corine.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CORINE Land Cover 2018 — EEA ArcGIS REST client.
+ *
+ * Data source: Copernicus Land Monitoring Service / EEA
+ * Licence: Copernicus (free, attribution required)
+ * Coverage: EU27 + EEA/EFTA. Great Britain is NOT covered (UK left the
+ * programme after CLC 2012). Return null for GB queries.
+ *
+ * CLC uses a three-level hierarchical nomenclature with 44 classes.
+ * We return the raw code (string, e.g. "211"), the human label, the
+ * top-level class group, and a conservative `is_planning_exclusion` flag.
+ */
+/** EU member states + EEA/EFTA covered by CORINE 2018. */
+export declare const CORINE_COVERED_COUNTRIES: Set<string>;
+export interface CorineResult {
+    /** 3-digit CLC code string, e.g. "211" */
+    code: string;
+    /** Human-readable label, e.g. "Non-irrigated arable land" */
+    label: string;
+    /** Top-level CLC class group */
+    class_group: string;
+    /**
+     * True if this land-cover type typically faces strong planning barriers
+     * for PV/BESS development. Conservative: only wetlands, water bodies,
+     * and semi-natural woodland are flagged. Agricultural land is NOT flagged
+     * here — that risk is assessed separately by ALC/national tools.
+     */
+    is_planning_exclusion: boolean;
+    source: "corine-land-cover-2018";
+}
+export declare function queryCorineAtPoint(lat: number, lon: number): Promise<CorineResult | null>;

package/dist/lib/corine.js

@@ -0,0 +1,137 @@
+/**
+ * CORINE Land Cover 2018 — EEA ArcGIS REST client.
+ *
+ * Data source: Copernicus Land Monitoring Service / EEA
+ * Licence: Copernicus (free, attribution required)
+ * Coverage: EU27 + EEA/EFTA. Great Britain is NOT covered (UK left the
+ * programme after CLC 2012). Return null for GB queries.
+ *
+ * CLC uses a three-level hierarchical nomenclature with 44 classes.
+ * We return the raw code (string, e.g. "211"), the human label, the
+ * top-level class group, and a conservative `is_planning_exclusion` flag.
+ */
+import { guardArcGisFields } from "./schema-guard.js";
+const CORINE_QUERY_URL = "https://image.discomap.eea.europa.eu/arcgis/rest/services/Corine/CLC2018_WM/MapServer/0/query";
+/** EU member states + EEA/EFTA covered by CORINE 2018. */
+export const CORINE_COVERED_COUNTRIES = new Set([
+    "AT", "BE", "BG", "CY", "CZ", "DE", "DK", "EE", "ES", "FI",
+    "FR", "GR", "HR", "HU", "IE", "IT", "LT", "LU", "LV", "MT",
+    "NL", "PL", "PT", "RO", "SE", "SI", "SK",
+    // EEA/EFTA (also in CORINE)
+    "IS", "LI", "NO", "TR", "AL", "BA", "ME", "MK", "RS", "XK",
+]);
+/** Subset of the 44-class CLC 2018 nomenclature.
+ *  Codes not in this map fall back to group-level labelling.
+ */
+const CLC_CODES = {
+    // 1xx — Artificial surfaces
+    "111": { label: "Continuous urban fabric", group: "Artificial surfaces", exclusion: false },
+    "112": { label: "Discontinuous urban fabric", group: "Artificial surfaces", exclusion: false },
+    "121": { label: "Industrial or commercial units", group: "Artificial surfaces", exclusion: false },
+    "122": { label: "Road and rail networks and associated land", group: "Artificial surfaces", exclusion: false },
+    "123": { label: "Port areas", group: "Artificial surfaces", exclusion: false },
+    "124": { label: "Airports", group: "Artificial surfaces", exclusion: false },
+    "131": { label: "Mineral extraction sites", group: "Artificial surfaces", exclusion: false },
+    "132": { label: "Dump sites", group: "Artificial surfaces", exclusion: false },
+    "133": { label: "Construction sites", group: "Artificial surfaces", exclusion: false },
+    "141": { label: "Green urban areas", group: "Artificial surfaces", exclusion: false },
+    "142": { label: "Sport and leisure facilities", group: "Artificial surfaces", exclusion: false },
+    // 2xx — Agricultural areas
+    "211": { label: "Non-irrigated arable land", group: "Agricultural areas", exclusion: false },
+    "212": { label: "Permanently irrigated land", group: "Agricultural areas", exclusion: false },
+    "213": { label: "Rice fields", group: "Agricultural areas", exclusion: false },
+    "221": { label: "Vineyards", group: "Agricultural areas", exclusion: false },
+    "222": { label: "Fruit trees and berry plantations", group: "Agricultural areas", exclusion: false },
+    "223": { label: "Olive groves", group: "Agricultural areas", exclusion: false },
+    "231": { label: "Pastures", group: "Agricultural areas", exclusion: false },
+    "241": { label: "Annual crops associated with permanent crops", group: "Agricultural areas", exclusion: false },
+    "242": { label: "Complex cultivation patterns", group: "Agricultural areas", exclusion: false },
+    "243": { label: "Land principally occupied by agriculture with significant areas of natural vegetation", group: "Agricultural areas", exclusion: false },
+    "244": { label: "Agro-forestry areas", group: "Agricultural areas", exclusion: false },
+    // 3xx — Forest and semi-natural areas
+    "311": { label: "Broad-leaved forest", group: "Forest and semi-natural areas", exclusion: true },
+    "312": { label: "Coniferous forest", group: "Forest and semi-natural areas", exclusion: true },
+    "313": { label: "Mixed forest", group: "Forest and semi-natural areas", exclusion: true },
+    "321": { label: "Natural grasslands", group: "Forest and semi-natural areas", exclusion: false },
+    "322": { label: "Moors and heathland", group: "Forest and semi-natural areas", exclusion: false },
+    "323": { label: "Sclerophyllous vegetation", group: "Forest and semi-natural areas", exclusion: false },
+    "324": { label: "Transitional woodland-shrub", group: "Forest and semi-natural areas", exclusion: false },
+    "331": { label: "Beaches, dunes, sands", group: "Forest and semi-natural areas", exclusion: false },
+    "332": { label: "Bare rocks", group: "Forest and semi-natural areas", exclusion: false },
+    "333": { label: "Sparsely vegetated areas", group: "Forest and semi-natural areas", exclusion: false },
+    "334": { label: "Burnt areas", group: "Forest and semi-natural areas", exclusion: false },
+    "335": { label: "Glaciers and perpetual snow", group: "Forest and semi-natural areas", exclusion: false },
+    // 4xx — Wetlands
+    "411": { label: "Inland marshes", group: "Wetlands", exclusion: true },
+    "412": { label: "Peat bogs", group: "Wetlands", exclusion: true },
+    "421": { label: "Salt marshes", group: "Wetlands", exclusion: true },
+    "422": { label: "Salines", group: "Wetlands", exclusion: true },
+    "423": { label: "Intertidal flats", group: "Wetlands", exclusion: true },
+    // 5xx — Water bodies
+    "511": { label: "Water courses", group: "Water bodies", exclusion: true },
+    "512": { label: "Water bodies", group: "Water bodies", exclusion: true },
+    "521": { label: "Coastal lagoons", group: "Water bodies", exclusion: true },
+    "522": { label: "Estuaries", group: "Water bodies", exclusion: true },
+    "523": { label: "Sea and ocean", group: "Water bodies", exclusion: true },
+};
+function getGroupFromCode(code) {
+    const first = code.charAt(0);
+    switch (first) {
+        case "1": return "Artificial surfaces";
+        case "2": return "Agricultural areas";
+        case "3": return "Forest and semi-natural areas";
+        case "4": return "Wetlands";
+        case "5": return "Water bodies";
+        default: return "Unknown";
+    }
+}
+function mapClcCode(code) {
+    const entry = CLC_CODES[code];
+    if (entry)
+        return { label: entry.label, group: entry.group, exclusion: entry.exclusion };
+    const group = getGroupFromCode(code);
+    return { label: `CLC code ${code}`, group, exclusion: false };
+}
+// ---------------------------------------------------------------------------
+// API client
+// ---------------------------------------------------------------------------
+export async function queryCorineAtPoint(lat, lon) {
+    const url = new URL(CORINE_QUERY_URL);
+    const p = url.searchParams;
+    p.set("geometry", `${lon},${lat}`);
+    p.set("geometryType", "esriGeometryPoint");
+    p.set("inSR", "4326");
+    p.set("spatialRel", "esriSpatialRelIntersects");
+    p.set("outFields", "Code_18");
+    p.set("returnGeometry", "false");
+    p.set("resultRecordCount", "1");
+    p.set("f", "json");
+    const response = await fetch(url.toString());
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`CORINE API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json = await response.json();
+    if (json.error) {
+        throw new Error(`CORINE API error: ${json.error.message ?? JSON.stringify(json.error)}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const features = json.features ?? [];
+    if (features.length === 0) {
+        // No polygon hit — typically offshore, or at the very edge of coverage.
+        return null;
+    }
+    guardArcGisFields(features, ["Code_18"], "CORINE Land Cover");
+    const code = String(features[0].attributes?.Code_18 ?? "").trim();
+    if (!code)
+        return null;
+    const { label, group, exclusion } = mapClcCode(code);
+    return {
+        code,
+        label,
+        class_group: group,
+        is_planning_exclusion: exclusion,
+        source: "corine-land-cover-2018",
+    };
+}

package/dist/lib/eea-natura2000.d.ts

@@ -0,0 +1,7 @@
+export interface EeaConstraintFeature {
+    name: string;
+    type: string;
+    area_ha: number | null;
+    source: string;
+}
+export declare function queryNatura2000Layer(lat: number, lon: number, radiusKm: number): Promise<EeaConstraintFeature[]>;

package/dist/lib/eea-natura2000.js

@@ -0,0 +1,53 @@
+import { guardArcGisFields } from "./schema-guard.js";
+const EEA_NATURA2000_BASE = "https://bio.discomap.eea.europa.eu/arcgis/rest/services/ProtectedSites/Natura2000_Dyna_WM/MapServer/0/query";
+const BIRDS_DIRECTIVE_CODES = new Set(["A", "C", "D", "F", "H", "J"]);
+const HABITATS_DIRECTIVE_CODES = new Set(["B", "E", "G", "I", "K", "c"]);
+function buildEnvelopeGeometry(lat, lon, radiusKm) {
+    const latDelta = radiusKm / 111.32;
+    const lonDelta = radiusKm / (111.32 * Math.cos(lat * (Math.PI / 180)));
+    return `${lon - lonDelta},${lat - latDelta},${lon + lonDelta},${lat + latDelta}`;
+}
+function mapSiteType(siteType) {
+    const value = String(siteType ?? "").trim();
+    if (BIRDS_DIRECTIVE_CODES.has(value))
+        return "natura2000_birds";
+    if (HABITATS_DIRECTIVE_CODES.has(value))
+        return "natura2000_habitats";
+    return "natura2000";
+}
+export async function queryNatura2000Layer(lat, lon, radiusKm) {
+    const url = new URL(EEA_NATURA2000_BASE);
+    const p = url.searchParams;
+    p.set("where", "1=1");
+    p.set("geometry", buildEnvelopeGeometry(lat, lon, radiusKm));
+    p.set("geometryType", "esriGeometryEnvelope");
+    p.set("inSR", "4326");
+    p.set("spatialRel", "esriSpatialRelIntersects");
+    p.set("outFields", "SITECODE,SITENAME,SITETYPE,MS,Area_km2");
+    p.set("returnGeometry", "false");
+    p.set("resultRecordCount", "50");
+    p.set("f", "json");
+    const response = await fetch(url.toString());
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`EEA Natura 2000 API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json = await response.json();
+    if (json.error) {
+        throw new Error(`EEA Natura 2000 API error: ${json.error.message ?? JSON.stringify(json.error)}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const features = json.features ?? [];
+    guardArcGisFields(features, ["SITECODE", "SITENAME", "SITETYPE", "MS", "Area_km2"], "EEA Natura 2000");
+    return features.map((feature) => {
+        const attrs = feature.attributes ?? {};
+        const areaKm2 = attrs.Area_km2;
+        return {
+            name: String(attrs.SITENAME ?? attrs.SITECODE ?? "Unknown Natura 2000 site"),
+            type: mapSiteType(attrs.SITETYPE),
+            area_ha: typeof areaKm2 === "number" ? Math.round(areaKm2 * 100 * 100) / 100 : null,
+            source: "eea-natura2000",
+        };
+    });
+}

package/dist/lib/entsoe-client.d.ts

@@ -0,0 +1,22 @@
+export interface EntsoeParams {
+    documentType: string;
+    processType?: string;
+    in_Domain?: string;
+    out_Domain?: string;
+    periodStart: string;
+    periodEnd: string;
+    [key: string]: string | undefined;
+}
+/** Format a Date as ENTSO-E expects: YYYYMMDDHHmm (UTC) */
+export declare function formatEntsoeDate(date: Date): string;
+/** Build start/end timestamps for a single day query */
+export declare function dayRange(dateStr?: string): {
+    periodStart: string;
+    periodEnd: string;
+};
+/**
+ * Query the ENTSO-E API.
+ * Returns parsed XML as JS object.
+ * Caches by URL with the given TTL.
+ */
+export declare function queryEntsoe(params: EntsoeParams, ttlMs?: number): Promise<Record<string, unknown>>;

package/dist/lib/entsoe-client.js

@@ -0,0 +1,69 @@
+import { parseXml } from "./xml-parser.js";
+import { TtlCache, TTL } from "./cache.js";
+import { resolveApiKey } from "./auth.js";
+const BASE_URL = "https://web-api.tp.entsoe.eu/api";
+const cache = new TtlCache();
+async function getApiKey() {
+    try {
+        return await resolveApiKey("ENTSOE_API_KEY");
+    }
+    catch {
+        throw new Error("ENTSOE_API_KEY is required. Set it as an environment variable or in ~/.luminus/keys.json. " +
+            "Get one at https://transparency.entsoe.eu/ (register → email token).");
+    }
+}
+/** Format a Date as ENTSO-E expects: YYYYMMDDHHmm (UTC) */
+export function formatEntsoeDate(date) {
+    const y = date.getUTCFullYear();
+    const m = String(date.getUTCMonth() + 1).padStart(2, "0");
+    const d = String(date.getUTCDate()).padStart(2, "0");
+    const h = String(date.getUTCHours()).padStart(2, "0");
+    const min = String(date.getUTCMinutes()).padStart(2, "0");
+    return `${y}${m}${d}${h}${min}`;
+}
+/** Build start/end timestamps for a single day query */
+export function dayRange(dateStr) {
+    const base = dateStr ? new Date(dateStr + "T00:00:00Z") : new Date();
+    const start = new Date(Date.UTC(base.getUTCFullYear(), base.getUTCMonth(), base.getUTCDate()));
+    const end = new Date(start.getTime() + 24 * 60 * 60 * 1000);
+    return {
+        periodStart: formatEntsoeDate(start),
+        periodEnd: formatEntsoeDate(end),
+    };
+}
+/**
+ * Query the ENTSO-E API.
+ * Returns parsed XML as JS object.
+ * Caches by URL with the given TTL.
+ */
+export async function queryEntsoe(params, ttlMs = TTL.REALTIME) {
+    const url = new URL(BASE_URL);
+    url.searchParams.set("securityToken", await getApiKey());
+    for (const [key, value] of Object.entries(params)) {
+        if (value != null) {
+            url.searchParams.set(key, value);
+        }
+    }
+    const cacheKey = url.toString().replace(/securityToken=[^&]+/, "token=***");
+    const cached = cache.get(cacheKey);
+    if (cached)
+        return cached;
+    const response = await fetch(url.toString());
+    if (!response.ok) {
+        const body = await response.text();
+        // ENTSO-E returns error details in XML
+        if (body.includes("Reason")) {
+            const parsed = parseXml(body);
+            const reason = 
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            parsed?.Acknowledgement_MarketDocument?.Reason?.text ??
+                body.slice(0, 300);
+            throw new Error(`ENTSO-E API error: ${reason}`);
+        }
+        throw new Error(`ENTSO-E API returned ${response.status}: ${body.slice(0, 300)}`);
+    }
+    const xml = await response.text();
+    const result = parseXml(xml);
+    cache.set(cacheKey, result, ttlMs);
+    return result;
+}

package/dist/lib/gis-sources.d.ts

@@ -0,0 +1,33 @@
+/**
+ * GIS data source metadata — provenance, reliability, and caveats.
+ *
+ * Each GIS tool response includes a `source_metadata` block drawn from
+ * these definitions. The goal is to make data quality and upstream
+ * limitations visible to callers, not hidden behind a clean API surface.
+ */
+export interface GisSourceMetadata {
+    readonly id: string;
+    readonly name: string;
+    readonly provider: string;
+    readonly licence: string;
+    readonly url: string;
+    readonly api_key_required: boolean;
+    readonly coverage: string;
+    readonly update_frequency: string;
+    readonly reliability: "high" | "medium" | "low";
+    readonly caveats: readonly string[];
+    readonly attribution: string;
+    readonly verified_at?: string;
+}
+export declare const GIS_SOURCES: Readonly<Record<string, GisSourceMetadata>>;
+/** Health check endpoint for each GIS source. */
+export interface GisHealthCheckConfig {
+    readonly source_id: string;
+    readonly url: string;
+    readonly method: "GET" | "POST";
+    readonly body?: string;
+    readonly timeout_ms: number;
+    /** A function that checks whether the response body looks sane. */
+    readonly validate: (status: number, body: string) => string | null;
+}
+export declare const GIS_HEALTH_CHECKS: readonly GisHealthCheckConfig[];