@cyanheads/eurostat-mcp-server 0.1.1

package/dist/services/eurostat-catalogue/eurostat-catalogue-service.js

@@ -0,0 +1,254 @@
+/**
+ * @fileoverview Eurostat Catalogue Service — fetches and caches the TOC TXT file,
+ * provides dataset search and theme tree navigation.
+ * @module services/eurostat-catalogue/eurostat-catalogue-service
+ */
+import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { fetchWithTimeout, withRetry } from '@cyanheads/mcp-ts-core/utils';
+import { getServerConfig } from '../../config/server-config.js';
+// Context satisfies the runtime contract of RequestContext (requestId, tenantId, etc.)
+// but lacks the [key: string]: unknown index signature required by fetchWithTimeout/withRetry.
+const asReqCtx = (ctx) => ctx;
+export class EurostatCatalogueService {
+    cache;
+    // config and storage accepted to match the standard service init pattern;
+    // this service uses only the Eurostat public API and per-request config.
+    // eslint-disable-next-line @typescript-eslint/no-useless-constructor
+    constructor(_config, _storage) { }
+    /** Ensure the TOC is loaded, fetching if not yet cached. */
+    async ensureLoaded(ctx) {
+        if (this.cache)
+            return this.cache;
+        this.cache = await this.fetchAndParseToc(ctx);
+        return this.cache;
+    }
+    async fetchAndParseToc(ctx) {
+        const { baseUrl, requestTimeoutMs } = getServerConfig();
+        const url = `${baseUrl}/catalogue/toc/txt?lang=en`;
+        ctx.log.info('Fetching Eurostat TOC', { url });
+        const text = await withRetry(async () => {
+            const response = await fetchWithTimeout(url, requestTimeoutMs, asReqCtx(ctx), {
+                signal: ctx.signal,
+            });
+            const body = await response.text();
+            if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(body)) {
+                throw serviceUnavailable('Eurostat TOC returned HTML instead of TSV — likely rate-limited or temporarily unavailable.');
+            }
+            return body;
+        }, { operation: 'fetchToc', context: asReqCtx(ctx), baseDelayMs: 1000, signal: ctx.signal });
+        const entries = this.parseToc(text);
+        const codeIndex = new Map();
+        for (let i = 0; i < entries.length; i++) {
+            // noUncheckedIndexedAccess: entries[i] is always defined in a length-bounded loop
+            const e = entries[i];
+            if (e)
+                codeIndex.set(e.code, i);
+        }
+        ctx.log.info('TOC loaded', { entryCount: entries.length });
+        return { entries, codeIndex, loadedAt: new Date() };
+    }
+    /**
+     * Parse the TSV TOC format.
+     * Header: title, code, type, last update of data, last table structure change,
+     *         data start, data end, values (datasets only — 7 vs 8 cols).
+     * Title column uses 4 spaces per depth level as indentation.
+     */
+    parseToc(text) {
+        const lines = text.split('\n');
+        const entries = [];
+        // Stack of [depth, entryIndex] for tracking parent relationships.
+        const depthStack = [];
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            // Split tab-separated fields. Each non-numeric field is double-quoted.
+            const cols = line.split('\t');
+            if (cols.length < 7)
+                continue;
+            // cols.length >= 7 is asserted above — these accesses are safe
+            const rawTitle = this.unquote(cols[0]);
+            if (!rawTitle)
+                continue;
+            // First column is the raw header row
+            const code = this.unquote(cols[1]);
+            const typeRaw = this.unquote(cols[2]);
+            // Skip header row
+            if (code === 'code')
+                continue;
+            if (!code)
+                continue;
+            const type = this.parseType(typeRaw);
+            const depth = this.measureDepth(rawTitle);
+            const label = rawTitle.trimStart();
+            // Resolve parent index from the depth stack
+            while (depthStack.length > 0) {
+                const top = depthStack[depthStack.length - 1];
+                if (top === undefined || top.depth < depth)
+                    break;
+                depthStack.pop();
+            }
+            const stackTop = depthStack[depthStack.length - 1];
+            const parentIndex = stackTop !== undefined ? stackTop.index : -1;
+            const lastUpdated = cols[3] ? this.unquote(cols[3]) || undefined : undefined;
+            const dataStart = cols[5] ? this.unquote(cols[5]) || undefined : undefined;
+            const dataEnd = cols[6] ? this.unquote(cols[6]) || undefined : undefined;
+            // 8th column (index 7) is obs count — only present for datasets/tables
+            let obsCount;
+            const col7 = cols[7];
+            if (cols.length >= 8 && col7) {
+                const raw = col7.trim();
+                if (raw) {
+                    const n = parseInt(raw, 10);
+                    if (!isNaN(n))
+                        obsCount = n;
+                }
+            }
+            const entry = {
+                label,
+                code,
+                type,
+                depth,
+                parentIndex,
+                ...(lastUpdated && { lastUpdated }),
+                ...(dataStart && { dataStart }),
+                ...(dataEnd && { dataEnd }),
+                ...(obsCount !== undefined && { obsCount }),
+            };
+            const idx = entries.length;
+            entries.push(entry);
+            depthStack.push({ depth, index: idx });
+        }
+        return entries;
+    }
+    unquote(s) {
+        const t = s?.trim() ?? '';
+        if (t.startsWith('"') && t.endsWith('"'))
+            return t.slice(1, -1).trim();
+        return t;
+    }
+    measureDepth(title) {
+        let spaces = 0;
+        for (const c of title) {
+            if (c === ' ')
+                spaces++;
+            else
+                break;
+        }
+        return Math.floor(spaces / 4);
+    }
+    parseType(raw) {
+        if (raw === 'dataset')
+            return 'dataset';
+        if (raw === 'table')
+            return 'table';
+        return 'folder';
+    }
+    /**
+     * Build a breadcrumb path from root to a given entry (exclusive of the entry itself).
+     */
+    buildPath(entries, entryIndex) {
+        const path = [];
+        let current = entries[entryIndex];
+        while (current !== undefined && current.parentIndex >= 0) {
+            const parent = entries[current.parentIndex];
+            if (parent === undefined)
+                break;
+            path.unshift(parent.label);
+            current = parent;
+        }
+        return path;
+    }
+    /**
+     * Find the "root" of the TOC — the 11 second-level theme folders.
+     * The TOC has a single depth-0 root ("Database by themes"); we skip it
+     * and return its depth-1 children as the practical entry points.
+     */
+    findRootChildren(entries) {
+        const rootIdx = entries.findIndex((e) => e.depth === 0 && e.type === 'folder');
+        if (rootIdx === -1) {
+            return entries.map((_, i) => i).filter((i) => (entries[i]?.depth ?? -1) === 0);
+        }
+        return entries.map((_, i) => i).filter((i) => entries[i]?.parentIndex === rootIdx);
+    }
+    /** Get immediate children of a folder code, or root theme folders if code is undefined. */
+    async browse(themeCode, ctx) {
+        const toc = await this.ensureLoaded(ctx);
+        if (!themeCode) {
+            const childIndexes = this.findRootChildren(toc.entries);
+            const items = childIndexes.flatMap((i) => {
+                const item = this.toBrowseItem(toc.entries, i);
+                return item ? [item] : [];
+            });
+            return { items, parentPath: [] };
+        }
+        const folderIdxMaybe = toc.codeIndex.get(themeCode);
+        const folderEntry = folderIdxMaybe !== undefined ? toc.entries[folderIdxMaybe] : undefined;
+        if (folderIdxMaybe === undefined ||
+            folderEntry === undefined ||
+            folderEntry.type !== 'folder') {
+            throw notFound(`Theme "${themeCode}" not found in the Eurostat TOC. Use eurostat_browse_themes without theme_code to see top-level themes, then navigate from there.`, { themeCode });
+        }
+        const folderIdx = folderIdxMaybe;
+        const childIndexes = toc.entries
+            .map((_, i) => i)
+            .filter((i) => toc.entries[i]?.parentIndex === folderIdx);
+        const items = childIndexes.flatMap((i) => {
+            const item = this.toBrowseItem(toc.entries, i);
+            return item ? [item] : [];
+        });
+        const parentPath = this.buildPath(toc.entries, folderIdx);
+        parentPath.push(folderEntry.label);
+        return { items, parentPath };
+    }
+    toBrowseItem(entries, index) {
+        const e = entries[index];
+        if (!e)
+            return;
+        const hasChildren = e.type === 'folder' && entries.some((c) => c.parentIndex === index);
+        return {
+            code: e.code,
+            label: e.label,
+            type: e.type,
+            hasChildren,
+            ...(e.dataStart && { dataStart: e.dataStart }),
+            ...(e.dataEnd && { dataEnd: e.dataEnd }),
+            ...(e.obsCount !== undefined && { obsCount: e.obsCount }),
+        };
+    }
+    /**
+     * Search datasets by case-insensitive substring match against labels.
+     * Returns datasets only (not folders), up to `limit` results.
+     */
+    async search(query, limit, ctx) {
+        const toc = await this.ensureLoaded(ctx);
+        const q = query.toLowerCase();
+        const matched = toc.entries
+            .map((e, i) => ({ e, i }))
+            .filter(({ e }) => e.type !== 'folder' && e.label.toLowerCase().includes(q));
+        const totalMatches = matched.length;
+        const sliced = matched.slice(0, limit);
+        const datasets = sliced.map(({ e, i }) => ({
+            code: e.code,
+            label: e.label,
+            type: e.type,
+            ...(e.dataStart && { dataStart: e.dataStart }),
+            ...(e.dataEnd && { dataEnd: e.dataEnd }),
+            ...(e.lastUpdated && { lastUpdated: e.lastUpdated }),
+            ...(e.obsCount !== undefined && { obsCount: e.obsCount }),
+            themePath: this.buildPath(toc.entries, i),
+        }));
+        return { datasets, totalMatches };
+    }
+}
+// --- Init/accessor pattern ---
+let _service;
+export function initEurostatCatalogueService(config, storage) {
+    _service = new EurostatCatalogueService(config, storage);
+}
+export function getEurostatCatalogueService() {
+    if (!_service) {
+        throw new Error('EurostatCatalogueService not initialized — call initEurostatCatalogueService() in setup()');
+    }
+    return _service;
+}
+//# sourceMappingURL=eurostat-catalogue-service.js.map

package/dist/services/eurostat-catalogue/eurostat-catalogue-service.js.map

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

package/dist/services/eurostat-catalogue/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Domain types for the Eurostat Catalogue (TOC) service.
+ * @module services/eurostat-catalogue/types
+ */
+/** A single entry from the parsed Eurostat TOC TXT file. */
+export interface TocEntry {
+    /** Dataset or folder code (e.g., "nama_10_gdp", "econ"). */
+    code: string;
+    /** End of data coverage (e.g., "2025"). */
+    dataEnd?: string;
+    /** Start of data coverage (e.g., "1975"). */
+    dataStart?: string;
+    /** Depth level in the hierarchy (0-based). */
+    depth: number;
+    /** Human-readable label (with leading spaces stripped). */
+    label: string;
+    /** Date of last data update (e.g., "22.05.2026"). */
+    lastUpdated?: string;
+    /** Number of observations (datasets/tables only). */
+    obsCount?: number;
+    /** Index of parent entry in the flat entries array, or -1 for root. */
+    parentIndex: number;
+    /** Entry type from the raw TOC. */
+    type: 'dataset' | 'table' | 'folder';
+}
+/** A dataset result from search or browse. */
+export interface DatasetResult {
+    code: string;
+    dataEnd?: string;
+    dataStart?: string;
+    label: string;
+    lastUpdated?: string;
+    obsCount?: number;
+    /** Breadcrumb path from root to this entry's parent folder. */
+    themePath: string[];
+    type: 'dataset' | 'table';
+}
+/** A theme or dataset item returned from browse. */
+export interface BrowseItem {
+    code: string;
+    dataEnd?: string;
+    dataStart?: string;
+    hasChildren: boolean;
+    label: string;
+    obsCount?: number;
+    type: 'folder' | 'dataset' | 'table';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/eurostat-catalogue/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/eurostat-catalogue/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,QAAQ;IACvB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;CACtC;AAED,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;CAC3B;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;CACtC"}

package/dist/services/eurostat-catalogue/types.js

@@ -0,0 +1,6 @@
+/**
+ * @fileoverview Domain types for the Eurostat Catalogue (TOC) service.
+ * @module services/eurostat-catalogue/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/services/eurostat-catalogue/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/eurostat-catalogue/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/services/eurostat-data/eurostat-data-service.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Eurostat Data Service — HTTP client for the Statistics API (JSON-stat 2.0),
+ * includes JSON-stat parsing and stride-based index decoding.
+ * @module services/eurostat-data/eurostat-data-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
+import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
+import type { DatasetMeta, DimensionValuesResult, GeoLevel, QueryResult } from './types.js';
+export declare class EurostatDataService {
+    constructor(_config: AppConfig, _storage: StorageService);
+    private buildUrl;
+    private fetchJson;
+    private checkResponseErrors;
+    /**
+     * Decode a JSON-stat 2.0 response into labeled observations using stride-based indexing.
+     */
+    private decodeObservations;
+    private extractAnnotation;
+    private extractMetadata;
+    /** Fetch dataset metadata using a minimal lastTimePeriod=1 query. */
+    getDatasetInfo(datasetCode: string, ctx: Context): Promise<DatasetMeta>;
+    /**
+     * Get all valid values for a specific dimension.
+     * For 'geo', applies geoLevel filter; for others, uses lastTimePeriod=1.
+     */
+    getDimensionValues(datasetCode: string, dimension: string, geoLevel: GeoLevel | undefined, ctx: Context): Promise<DimensionValuesResult>;
+    /**
+     * Query dataset observations with dimension filters.
+     * Returns decoded observations.
+     */
+    queryDataset(datasetCode: string, filters: Record<string, string[]>, geoLevel: GeoLevel | undefined, sinceP: string | undefined, untilP: string | undefined, lastN: number | undefined, lang: string, ctx: Context): Promise<QueryResult>;
+}
+export declare function initEurostatDataService(config: AppConfig, storage: StorageService): void;
+export declare function getEurostatDataService(): EurostatDataService;
+//# sourceMappingURL=eurostat-data-service.d.ts.map

package/dist/services/eurostat-data/eurostat-data-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eurostat-data-service.d.ts","sourceRoot":"","sources":["../../../src/services/eurostat-data/eurostat-data-service.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAGrE,OAAO,KAAK,EACV,WAAW,EAEX,qBAAqB,EACrB,QAAQ,EAGR,WAAW,EACZ,MAAM,YAAY,CAAC;AAMpB,qBAAa,mBAAmB;gBAIlB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc;IAExD,OAAO,CAAC,QAAQ;IAchB,OAAO,CAAC,SAAS;IA4BjB,OAAO,CAAC,mBAAmB;IAwC3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAiE1B,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,eAAe;IAqCvB,qEAAqE;IAC/D,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC;IAO7E;;;OAGG;IACG,kBAAkB,CACtB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,qBAAqB,CAAC;IAqCjC;;;OAGG;IACG,YAAY,CAChB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EACjC,QAAQ,EAAE,QAAQ,GAAG,SAAS,EAC9B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,WAAW,CAAC;CAoDxB;AAMD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAExF;AAED,wBAAgB,sBAAsB,IAAI,mBAAmB,CAO5D"}

package/dist/services/eurostat-data/eurostat-data-service.js

@@ -0,0 +1,278 @@
+/**
+ * @fileoverview Eurostat Data Service — HTTP client for the Statistics API (JSON-stat 2.0),
+ * includes JSON-stat parsing and stride-based index decoding.
+ * @module services/eurostat-data/eurostat-data-service
+ */
+import { invalidParams, notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { fetchWithTimeout, withRetry } from '@cyanheads/mcp-ts-core/utils';
+import { getServerConfig } from '../../config/server-config.js';
+// Context satisfies the runtime contract of RequestContext but lacks the index signature
+// required by fetchWithTimeout/withRetry.
+const asReqCtx = (ctx) => ctx;
+export class EurostatDataService {
+    // config and storage accepted to match the standard service init pattern;
+    // this service uses only the Eurostat public API and per-request config.
+    // eslint-disable-next-line @typescript-eslint/no-useless-constructor
+    constructor(_config, _storage) { }
+    buildUrl(datasetCode, params) {
+        const { baseUrl } = getServerConfig();
+        const url = new URL(`${baseUrl}/statistics/1.0/data/${encodeURIComponent(datasetCode)}`);
+        url.searchParams.set('format', 'JSON');
+        for (const [key, value] of Object.entries(params)) {
+            if (Array.isArray(value)) {
+                for (const v of value)
+                    url.searchParams.append(key, v);
+            }
+            else {
+                url.searchParams.set(key, value);
+            }
+        }
+        return url;
+    }
+    fetchJson(url, ctx) {
+        const { requestTimeoutMs } = getServerConfig();
+        return withRetry(async () => {
+            const response = await fetchWithTimeout(url.toString(), requestTimeoutMs, asReqCtx(ctx), {
+                signal: ctx.signal,
+            });
+            const text = await response.text();
+            if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
+                throw serviceUnavailable('Eurostat Statistics API returned HTML instead of JSON — likely rate-limited or temporarily unavailable.');
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                throw serviceUnavailable(`Eurostat Statistics API returned unparseable response. Response excerpt: ${text.slice(0, 200)}`);
+            }
+            this.checkResponseErrors(parsed, url.toString());
+            return parsed;
+        }, { operation: 'fetchJsonStat', context: asReqCtx(ctx), baseDelayMs: 1000, signal: ctx.signal });
+    }
+    checkResponseErrors(data, url) {
+        // Async response: query too large
+        if (data.warning?.status === 413) {
+            throw serviceUnavailable('Eurostat returned an asynchronous response — the query matched too many observations. ' +
+                'Add dimension filters (geo, unit, na_item, etc.) to reduce the result size and retry.', { reason: 'async_response', url });
+        }
+        // Error responses
+        if (Array.isArray(data.error) && data.error.length > 0) {
+            const err = data.error[0];
+            if (!err)
+                return; // noUncheckedIndexedAccess: length > 0 guarantees this, but guard for TS
+            if (err.status === 404 || err.id === 100) {
+                throw notFound(`Dataset not found. Eurostat error: ${err.label}. ` +
+                    `Verify the dataset code with eurostat_search_datasets or eurostat_browse_themes.`, { reason: 'not_found', eurostatError: err });
+            }
+            if (err.status === 400) {
+                if (err.id === 150) {
+                    throw invalidParams(`Invalid dimension code. Eurostat error: ${err.label}. ` +
+                        `Use eurostat_get_dataset_info to see valid dimensions for this dataset.`, { reason: 'invalid_dimension', eurostatError: err });
+                }
+                throw invalidParams(`Bad request. Eurostat error: ${err.label}.`, {
+                    reason: 'conflicting_params',
+                    eurostatError: err,
+                });
+            }
+            throw serviceUnavailable(`Eurostat API error ${err.status}: ${err.label}.`, {
+                eurostatError: err,
+            });
+        }
+    }
+    /**
+     * Decode a JSON-stat 2.0 response into labeled observations using stride-based indexing.
+     */
+    decodeObservations(data) {
+        if (!data.id || !data.size || !data.dimension)
+            return [];
+        const dims = data.id;
+        const sizes = data.size;
+        const value = data.value ?? {};
+        const status = data.status ?? {};
+        const statusLabels = data.extension?.status?.label ?? {};
+        // Compute strides: stride[i] = product of sizes[i+1..n-1]
+        const strides = new Array(dims.length).fill(1);
+        for (let i = dims.length - 2; i >= 0; i--) {
+            // noUncheckedIndexedAccess: bounds are [0..dims.length-2], so i+1 and sizes[i+1] are safe
+            strides[i] = (strides[i + 1] ?? 1) * (sizes[i + 1] ?? 1);
+        }
+        // Build dimension value arrays: index position → {code, label}
+        const dimValues = dims.map((dim) => {
+            const cat = data.dimension?.[dim]?.category;
+            if (!cat?.index)
+                return [];
+            return Object.entries(cat.index)
+                .sort(([, a], [, b]) => a - b)
+                .map(([code]) => ({
+                code,
+                label: cat.label?.[code] ?? code,
+            }));
+        });
+        const observations = [];
+        const totalCells = sizes.reduce((a, b) => a * b, 1);
+        for (let linearIdx = 0; linearIdx < totalCells; linearIdx++) {
+            const keyStr = String(linearIdx);
+            if (!(keyStr in value) && !(keyStr in status))
+                continue;
+            const dimensions = {};
+            let remaining = linearIdx;
+            for (let d = 0; d < dims.length; d++) {
+                const stride = strides[d] ?? 1;
+                const pos = Math.floor(remaining / stride);
+                remaining = remaining % stride;
+                const dimName = dims[d];
+                const dimArr = dimValues[d];
+                const dimVal = dimArr?.[pos];
+                if (dimName) {
+                    dimensions[dimName] = dimVal ?? { code: String(pos), label: String(pos) };
+                }
+            }
+            const rawValue = value[keyStr] ?? null;
+            const statusCode = status[keyStr];
+            const obs = { dimensions, value: rawValue };
+            if (statusCode) {
+                obs.status = {
+                    code: statusCode,
+                    label: statusLabels[statusCode] ?? statusCode,
+                };
+            }
+            observations.push(obs);
+        }
+        return observations;
+    }
+    extractAnnotation(data, type, field) {
+        return data.extension?.annotation?.find((a) => a.type === type)?.[field];
+    }
+    extractMetadata(data, datasetCode) {
+        const dims = data.id ?? [];
+        const dimension = data.dimension ?? {};
+        const dimensions = dims.map((dimCode) => {
+            const cat = dimension[dimCode]?.category;
+            const allValues = cat?.index ? Object.entries(cat.index).sort(([, a], [, b]) => a - b) : [];
+            return {
+                code: dimCode,
+                label: dimension[dimCode]?.label ?? dimCode,
+                valuesCount: allValues.length,
+                sampleValues: allValues.slice(0, 10).map(([code]) => ({
+                    code,
+                    label: cat?.label?.[code] ?? code,
+                })),
+            };
+        });
+        const obsCountRaw = this.extractAnnotation(data, 'OBS_COUNT', 'title');
+        const obsCount = obsCountRaw ? parseInt(obsCountRaw, 10) : 0;
+        const oldest = this.extractAnnotation(data, 'OBS_PERIOD_OVERALL_OLDEST', 'title') ?? '';
+        const latest = this.extractAnnotation(data, 'OBS_PERIOD_OVERALL_LATEST', 'title') ?? '';
+        const lastUpdated = this.extractAnnotation(data, 'UPDATE_DATA', 'date') ?? '';
+        const metadataUrl = this.extractAnnotation(data, 'ESMS_HTML', 'href');
+        return {
+            code: datasetCode,
+            label: data.label ?? datasetCode,
+            dimensions,
+            timeRange: { start: oldest, end: latest },
+            obsCount: isNaN(obsCount) ? 0 : obsCount,
+            lastUpdated,
+            ...(metadataUrl && { metadataUrl }),
+        };
+    }
+    /** Fetch dataset metadata using a minimal lastTimePeriod=1 query. */
+    async getDatasetInfo(datasetCode, ctx) {
+        ctx.log.info('Fetching dataset info', { datasetCode });
+        const url = this.buildUrl(datasetCode, { lastTimePeriod: '1' });
+        const data = await this.fetchJson(url, ctx);
+        return this.extractMetadata(data, datasetCode);
+    }
+    /**
+     * Get all valid values for a specific dimension.
+     * For 'geo', applies geoLevel filter; for others, uses lastTimePeriod=1.
+     */
+    async getDimensionValues(datasetCode, dimension, geoLevel, ctx) {
+        ctx.log.info('Fetching dimension values', { datasetCode, dimension, geoLevel });
+        const params = {};
+        if (dimension === 'geo' && geoLevel) {
+            params['geoLevel'] = geoLevel;
+        }
+        else {
+            params['lastTimePeriod'] = '1';
+        }
+        const url = this.buildUrl(datasetCode, params);
+        const data = await this.fetchJson(url, ctx);
+        const dimDef = data.dimension?.[dimension];
+        if (!dimDef) {
+            throw notFound(`Dimension "${dimension}" not found in dataset "${datasetCode}". ` +
+                `Use eurostat_get_dataset_info to see valid dimensions.`, { reason: 'not_found', datasetCode, dimension });
+        }
+        const cat = dimDef.category;
+        const allValues = cat?.index
+            ? Object.entries(cat.index)
+                .sort(([, a], [, b]) => a - b)
+                .map(([code]) => ({ code, label: cat.label?.[code] ?? code }))
+            : [];
+        return {
+            dimensionCode: dimension,
+            dimensionLabel: dimDef.label ?? dimension,
+            values: allValues,
+            totalCount: allValues.length,
+        };
+    }
+    /**
+     * Query dataset observations with dimension filters.
+     * Returns decoded observations.
+     */
+    async queryDataset(datasetCode, filters, geoLevel, sinceP, untilP, lastN, lang, ctx) {
+        ctx.log.info('Querying dataset', { datasetCode, filters, geoLevel, sinceP, untilP, lastN });
+        // Validate mutually exclusive params
+        if (filters['geo'] && geoLevel) {
+            throw invalidParams(`"geo" filter and "geo_level" cannot be used together. ` +
+                `Use one or the other: "geo" for specific country/region codes, "geo_level" for filtering by NUTS hierarchy level.`, { reason: 'conflicting_params' });
+        }
+        const params = { lang };
+        // Apply dimension filters
+        for (const [dim, values] of Object.entries(filters)) {
+            if (values.length > 0)
+                params[dim] = values;
+        }
+        if (geoLevel)
+            params['geoLevel'] = geoLevel;
+        if (sinceP && !lastN)
+            params['sinceTimePeriod'] = sinceP;
+        if (untilP && !lastN)
+            params['untilTimePeriod'] = untilP;
+        if (lastN)
+            params['lastTimePeriod'] = String(lastN);
+        const url = this.buildUrl(datasetCode, params);
+        const data = await this.fetchJson(url, ctx);
+        // Detect no-results case (empty value object, no error)
+        if (data.id && data.value !== undefined && Object.keys(data.value).length === 0) {
+            throw notFound(`Query returned no observations for dataset "${datasetCode}". ` +
+                `The dimension filter combination may not exist in the data. ` +
+                `Verify dimension values with eurostat_get_dimension_values first.`, { reason: 'no_results', datasetCode, filters });
+        }
+        const observations = this.decodeObservations(data);
+        const missingObsCount = observations.filter((o) => o.value === null).length;
+        const oldest = this.extractAnnotation(data, 'OBS_PERIOD_OVERALL_OLDEST', 'title') ?? '';
+        const latest = this.extractAnnotation(data, 'OBS_PERIOD_OVERALL_LATEST', 'title') ?? '';
+        return {
+            datasetCode,
+            datasetLabel: data.label ?? datasetCode,
+            dimensionsUsed: data.id ?? [],
+            observations,
+            obsCount: observations.length,
+            timeRange: { start: oldest, end: latest },
+            missingObsCount,
+        };
+    }
+}
+// --- Init/accessor pattern ---
+let _service;
+export function initEurostatDataService(config, storage) {
+    _service = new EurostatDataService(config, storage);
+}
+export function getEurostatDataService() {
+    if (!_service) {
+        throw new Error('EurostatDataService not initialized — call initEurostatDataService() in setup()');
+    }
+    return _service;
+}
+//# sourceMappingURL=eurostat-data-service.js.map