@cyanheads/eurostat-mcp-server 0.1.1

package/dist/mcp-server/tools/definitions/eurostat-query-dataset.tool.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Tool for querying statistical data from a Eurostat dataset.
+ * @module mcp-server/tools/definitions/eurostat-query-dataset.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const eurostatQueryDataset: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    dataset_code: z.ZodString;
+    filters: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    geo_level: z.ZodOptional<z.ZodEnum<{
+        aggregate: "aggregate";
+        country: "country";
+        nuts1: "nuts1";
+        nuts2: "nuts2";
+        nuts3: "nuts3";
+    }>>;
+    since_period: z.ZodOptional<z.ZodString>;
+    until_period: z.ZodOptional<z.ZodString>;
+    last_n_periods: z.ZodOptional<z.ZodNumber>;
+    lang: z.ZodDefault<z.ZodEnum<{
+        EN: "EN";
+        FR: "FR";
+        DE: "DE";
+    }>>;
+}, z.core.$strip>, z.ZodObject<{
+    datasetCode: z.ZodString;
+    datasetLabel: z.ZodString;
+    dimensionsUsed: z.ZodArray<z.ZodString>;
+    observations: z.ZodArray<z.ZodObject<{
+        dimensions: z.ZodObject<{}, z.core.$loose>;
+        value: z.ZodNullable<z.ZodNumber>;
+        status: z.ZodOptional<z.ZodObject<{
+            code: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    obsCount: z.ZodNumber;
+    timeRange: z.ZodObject<{
+        start: z.ZodString;
+        end: z.ZodString;
+    }, z.core.$strip>;
+    missingObsCount: z.ZodNumber;
+}, z.core.$strip>, readonly [{
+    readonly reason: "not_found";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The dataset code does not exist (HTTP 404, Eurostat error id 100).";
+    readonly recovery: "Use eurostat_search_datasets or eurostat_browse_themes to find a valid dataset code.";
+}, {
+    readonly reason: "no_results";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "The query returned no observations — valid dataset but the filter combination matched no data.";
+    readonly recovery: "Verify dimension values with eurostat_get_dimension_values; invalid dimension values silently return no data.";
+}, {
+    readonly reason: "async_response";
+    readonly code: JsonRpcErrorCode.ServiceUnavailable;
+    readonly when: "Eurostat returned an async warning — the query matched too many observations.";
+    readonly retryable: false;
+    readonly recovery: "Add dimension filters (geo, unit, na_item) to reduce the result size, then retry.";
+}, {
+    readonly reason: "invalid_dimension";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "A dimension code in filters does not exist in this dataset (HTTP 400, Eurostat error id 150).";
+    readonly recovery: "Use eurostat_get_dataset_info to see valid dimension codes for this dataset.";
+}, {
+    readonly reason: "conflicting_params";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "Both \"geo\" filter and geo_level were provided simultaneously.";
+    readonly recovery: "Use either a \"geo\" key in filters or the geo_level parameter — not both.";
+}]>;
+//# sourceMappingURL=eurostat-query-dataset.tool.d.ts.map

package/dist/mcp-server/tools/definitions/eurostat-query-dataset.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eurostat-query-dataset.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/eurostat-query-dataset.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAIjE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4L/B,CAAC"}

package/dist/mcp-server/tools/definitions/eurostat-query-dataset.tool.js

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Tool for querying statistical data from a Eurostat dataset.
+ * @module mcp-server/tools/definitions/eurostat-query-dataset.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getEurostatDataService } from '../../../services/eurostat-data/eurostat-data-service.js';
+import { GEO_LEVEL_VALUES } from '../../../services/eurostat-data/types.js';
+export const eurostatQueryDataset = tool('eurostat_query_dataset', {
+    title: 'Query Eurostat Dataset',
+    description: 'Fetch statistical data from a Eurostat dataset with dimension filters. Returns decoded observations with dimension codes and labels, numeric values, and status flags (e.g., "p" = provisional, "e" = estimated). Call eurostat_get_dataset_info first to discover valid dimension codes and values. Apply filters to keep the result set manageable — large unfiltered queries may trigger an async response error. Use filters.geo for specific country/region codes, or geo_level for NUTS hierarchy filtering (mutually exclusive). Use last_n_periods for the N most recent periods without knowing the end date.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        dataset_code: z.string().min(1).describe('Dataset code (e.g., "nama_10_gdp"). Required.'),
+        filters: z
+            .record(z.string(), z.array(z.string()))
+            .default({})
+            .describe('Dimension filters as a map of dimension code → array of valid values. Example: {"unit": ["CP_MEUR"], "na_item": ["B1GQ"], "geo": ["DE", "FR"]}. Do not include "geo" here if using geo_level. Invalid dimension values silently return no data — verify with eurostat_get_dimension_values first.'),
+        geo_level: z
+            .enum(GEO_LEVEL_VALUES)
+            .optional()
+            .describe('Filter by NUTS hierarchy level. Mutually exclusive with a "geo" key in filters. Options: "aggregate" (EU/EA totals), "country" (41 member/candidate states), "nuts1" (127 major regions), "nuts2" (309 basic regions), "nuts3" (1,343 small regions).'),
+        since_period: z
+            .string()
+            .optional()
+            .describe('Start of time range (e.g., "2020", "2023-Q1", "2024-01"). Mutually exclusive with last_n_periods.'),
+        until_period: z
+            .string()
+            .optional()
+            .describe('End of time range (e.g., "2024"). Omit for data through the latest available period. Mutually exclusive with last_n_periods.'),
+        last_n_periods: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .describe('Return only the N most recent periods. Mutually exclusive with since_period and until_period.'),
+        lang: z
+            .enum(['EN', 'FR', 'DE'])
+            .default('EN')
+            .describe('Language for labels in the response. Default is "EN". Options: "EN", "FR", "DE".'),
+    }),
+    output: z.object({
+        datasetCode: z.string().describe('Dataset code as provided.'),
+        datasetLabel: z.string().describe('Human-readable dataset title.'),
+        dimensionsUsed: z
+            .array(z.string())
+            .describe('Ordered list of dimension codes present in the response (e.g., ["freq", "unit", "na_item", "geo", "time"]).'),
+        observations: z
+            .array(z
+            .object({
+            // dimensions is a dynamic map (keys = dimension codes from dimensionsUsed).
+            // Using passthrough so the full {code, label} pairs flow to structuredContent
+            // even though the keys are not known at schema definition time.
+            dimensions: z
+                .object({})
+                .passthrough()
+                .describe('Map of dimension code → {code, label}. One entry per dimension in dimensionsUsed, keyed by dimension code (e.g., {"geo": {"code": "DE", "label": "Germany"}, "time": {"code": "2023", "label": "2023"}}).'),
+            value: z
+                .number()
+                .nullable()
+                .describe('Numeric observation value, or null when missing (flagged as unavailable in the source data).'),
+            status: z
+                .object({
+                code: z.string().describe('Status flag code (e.g., "p", "e", "d").'),
+                label: z
+                    .string()
+                    .describe('Status description (e.g., "provisional", "estimated", "definition differs").'),
+            })
+                .optional()
+                .describe('Status flag for this observation. Omitted for normal observations.'),
+        })
+            .describe('A single decoded observation with dimension values, numeric value, and optional status.'))
+            .describe('Decoded observations. Each entry has one dimension entry per dimension in dimensionsUsed, plus value and optional status.'),
+        obsCount: z.number().describe('Number of observations returned.'),
+        timeRange: z
+            .object({
+            start: z.string().describe('Earliest period in this result.'),
+            end: z.string().describe('Most recent period in this result.'),
+        })
+            .describe('Time coverage of the returned observations.'),
+        missingObsCount: z
+            .number()
+            .describe('Number of observations with null value (missing data points in the source).'),
+    }),
+    errors: [
+        {
+            reason: 'not_found',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'The dataset code does not exist (HTTP 404, Eurostat error id 100).',
+            recovery: 'Use eurostat_search_datasets or eurostat_browse_themes to find a valid dataset code.',
+        },
+        {
+            reason: 'no_results',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'The query returned no observations — valid dataset but the filter combination matched no data.',
+            recovery: 'Verify dimension values with eurostat_get_dimension_values; invalid dimension values silently return no data.',
+        },
+        {
+            reason: 'async_response',
+            code: JsonRpcErrorCode.ServiceUnavailable,
+            when: 'Eurostat returned an async warning — the query matched too many observations.',
+            retryable: false,
+            recovery: 'Add dimension filters (geo, unit, na_item) to reduce the result size, then retry.',
+        },
+        {
+            reason: 'invalid_dimension',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'A dimension code in filters does not exist in this dataset (HTTP 400, Eurostat error id 150).',
+            recovery: 'Use eurostat_get_dataset_info to see valid dimension codes for this dataset.',
+        },
+        {
+            reason: 'conflicting_params',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'Both "geo" filter and geo_level were provided simultaneously.',
+            recovery: 'Use either a "geo" key in filters or the geo_level parameter — not both.',
+        },
+    ],
+    async handler(input, ctx) {
+        const svc = getEurostatDataService();
+        const sinceP = input.since_period?.trim() || undefined;
+        const untilP = input.until_period?.trim() || undefined;
+        const result = await svc.queryDataset(input.dataset_code, input.filters, input.geo_level, sinceP, untilP, input.last_n_periods, input.lang, ctx);
+        ctx.log.info('Dataset query complete', {
+            datasetCode: input.dataset_code,
+            obsCount: result.obsCount,
+            missingObsCount: result.missingObsCount,
+        });
+        return result;
+    },
+    format: (result) => {
+        const lines = [
+            `# ${result.datasetLabel} (\`${result.datasetCode}\`)`,
+            `**Observations:** ${result.obsCount} (${result.missingObsCount} missing) | **Period:** ${result.timeRange.start} – ${result.timeRange.end}`,
+            `**Dimensions:** ${result.dimensionsUsed.join(', ')}\n`,
+        ];
+        const maxRows = 200;
+        const shown = result.observations.slice(0, maxRows);
+        for (const obs of shown) {
+            // dimensions is typed as {} from passthrough() — cast to the runtime shape for rendering
+            const dims = obs.dimensions;
+            const dimParts = result.dimensionsUsed.map((dim) => `${dim}=${dims[dim]?.code ?? '?'} (${dims[dim]?.label ?? '?'})`);
+            const val = obs.value != null ? String(obs.value) : 'N/A';
+            const statusPart = obs.status ? ` [${obs.status.code}: ${obs.status.label}]` : '';
+            lines.push(`${dimParts.join(' | ')} → ${val}${statusPart}`);
+        }
+        if (result.observations.length > maxRows) {
+            lines.push(`\n_(${result.observations.length - maxRows} more observations not shown)_`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=eurostat-query-dataset.tool.js.map

package/dist/mcp-server/tools/definitions/eurostat-query-dataset.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eurostat-query-dataset.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/eurostat-query-dataset.tool.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server/tools/definitions/eurostat-search-datasets.tool.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Tool for searching the Eurostat dataset catalogue by keyword.
+ * @module mcp-server/tools/definitions/eurostat-search-datasets.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+export declare const eurostatSearchDatasets: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    query: z.ZodString;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    datasets: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodEnum<{
+            dataset: "dataset";
+            table: "table";
+        }>;
+        dataStart: z.ZodOptional<z.ZodString>;
+        dataEnd: z.ZodOptional<z.ZodString>;
+        lastUpdated: z.ZodOptional<z.ZodString>;
+        obsCount: z.ZodOptional<z.ZodNumber>;
+        themePath: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    totalMatches: z.ZodNumber;
+}, z.core.$strip>, readonly [{
+    readonly reason: "no_match";
+    readonly code: JsonRpcErrorCode.NotFound;
+    readonly when: "No datasets matched the query string.";
+    readonly recovery: "Try a broader or different search term. Use eurostat_browse_themes to explore themes without text search.";
+}]>;
+//# sourceMappingURL=eurostat-search-datasets.tool.d.ts.map

package/dist/mcp-server/tools/definitions/eurostat-search-datasets.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eurostat-search-datasets.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/eurostat-search-datasets.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;GAqHjC,CAAC"}

package/dist/mcp-server/tools/definitions/eurostat-search-datasets.tool.js

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Tool for searching the Eurostat dataset catalogue by keyword.
+ * @module mcp-server/tools/definitions/eurostat-search-datasets.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { getEurostatCatalogueService } from '../../../services/eurostat-catalogue/eurostat-catalogue-service.js';
+export const eurostatSearchDatasets = tool('eurostat_search_datasets', {
+    title: 'Search Eurostat Datasets',
+    description: 'Search the Eurostat catalogue (8,933 datasets) by keyword. Returns matching datasets with codes, descriptions, period coverage, and theme breadcrumbs. Use this to discover dataset codes before calling eurostat_get_dataset_info or eurostat_query_dataset. Results are ranked by label match and limited to datasets and predefined tables — folders are excluded. The catalogue is loaded once per session from the Eurostat TOC file.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    input: z.object({
+        query: z
+            .string()
+            .min(1)
+            .describe('Search terms — case-insensitive substring match against dataset labels.'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(20)
+            .describe('Maximum number of results to return (1–100). Default is 20.'),
+    }),
+    output: z.object({
+        datasets: z
+            .array(z
+            .object({
+            code: z
+                .string()
+                .describe('Dataset code (e.g., "nama_10_gdp"). Use this in eurostat_get_dataset_info and eurostat_query_dataset.'),
+            label: z.string().describe('Human-readable dataset title.'),
+            type: z
+                .enum(['dataset', 'table'])
+                .describe('Entry type: "dataset" for standard datasets, "table" for predefined tables.'),
+            dataStart: z
+                .string()
+                .optional()
+                .describe('Earliest data period available (e.g., "1975"). Omitted when not reported by Eurostat.'),
+            dataEnd: z
+                .string()
+                .optional()
+                .describe('Most recent data period available (e.g., "2025"). Omitted when not reported by Eurostat.'),
+            lastUpdated: z
+                .string()
+                .optional()
+                .describe('Date of last data update (e.g., "22.05.2026"). Omitted when not reported.'),
+            obsCount: z
+                .number()
+                .optional()
+                .describe('Approximate number of observations. Omitted when not reported by Eurostat.'),
+            themePath: z
+                .array(z.string())
+                .describe('Breadcrumb path from root theme to this dataset (e.g., ["Economy and finance", "National accounts"]). Empty for top-level entries.'),
+        })
+            .describe('A matched dataset entry.'))
+            .describe('Matching datasets, up to the requested limit.'),
+        totalMatches: z
+            .number()
+            .describe('Total number of datasets matching the query before the limit is applied.'),
+    }),
+    errors: [
+        {
+            reason: 'no_match',
+            code: JsonRpcErrorCode.NotFound,
+            when: 'No datasets matched the query string.',
+            recovery: 'Try a broader or different search term. Use eurostat_browse_themes to explore themes without text search.',
+        },
+    ],
+    async handler(input, ctx) {
+        const svc = getEurostatCatalogueService();
+        const { datasets, totalMatches } = await svc.search(input.query, input.limit, ctx);
+        if (datasets.length === 0) {
+            throw ctx.fail('no_match', `No datasets matched "${input.query}".`, {
+                recovery: {
+                    hint: `Try a broader term or use eurostat_browse_themes to explore themes without text search.`,
+                },
+            });
+        }
+        ctx.log.info('Dataset search complete', {
+            query: input.query,
+            totalMatches,
+            returned: datasets.length,
+        });
+        return { datasets, totalMatches };
+    },
+    format: (result) => {
+        const lines = [
+            `**${result.totalMatches} total match${result.totalMatches !== 1 ? 'es' : ''}** (showing ${result.datasets.length})\n`,
+        ];
+        for (const d of result.datasets) {
+            lines.push(`## ${d.label}`);
+            lines.push(`**Code:** ${d.code} | **Type:** ${d.type}`);
+            if (d.dataStart || d.dataEnd) {
+                lines.push(`**Period:** ${d.dataStart ?? '?'} – ${d.dataEnd ?? '?'}`);
+            }
+            if (d.obsCount != null)
+                lines.push(`**Observations:** ${d.obsCount.toLocaleString()}`);
+            if (d.lastUpdated)
+                lines.push(`**Last updated:** ${d.lastUpdated}`);
+            if (d.themePath.length > 0)
+                lines.push(`**Theme:** ${d.themePath.join(' › ')}`);
+        }
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=eurostat-search-datasets.tool.js.map

package/dist/mcp-server/tools/definitions/eurostat-search-datasets.tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eurostat-search-datasets.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/eurostat-search-datasets.tool.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,53 @@
+/**
+ * @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 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 { BrowseItem, DatasetResult } from './types.js';
+export declare class EurostatCatalogueService {
+    private cache;
+    constructor(_config: AppConfig, _storage: StorageService);
+    /** Ensure the TOC is loaded, fetching if not yet cached. */
+    private ensureLoaded;
+    private fetchAndParseToc;
+    /**
+     * 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.
+     */
+    private parseToc;
+    private unquote;
+    private measureDepth;
+    private parseType;
+    /**
+     * Build a breadcrumb path from root to a given entry (exclusive of the entry itself).
+     */
+    private buildPath;
+    /**
+     * 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.
+     */
+    private findRootChildren;
+    /** Get immediate children of a folder code, or root theme folders if code is undefined. */
+    browse(themeCode: string | undefined, ctx: Context): Promise<{
+        items: BrowseItem[];
+        parentPath: string[];
+    }>;
+    private toBrowseItem;
+    /**
+     * Search datasets by case-insensitive substring match against labels.
+     * Returns datasets only (not folders), up to `limit` results.
+     */
+    search(query: string, limit: number, ctx: Context): Promise<{
+        datasets: DatasetResult[];
+        totalMatches: number;
+    }>;
+}
+export declare function initEurostatCatalogueService(config: AppConfig, storage: StorageService): void;
+export declare function getEurostatCatalogueService(): EurostatCatalogueService;
+//# sourceMappingURL=eurostat-catalogue-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"eurostat-catalogue-service.d.ts","sourceRoot":"","sources":["../../../src/services/eurostat-catalogue/eurostat-catalogue-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,EAAE,UAAU,EAAE,aAAa,EAAY,MAAM,YAAY,CAAC;AActE,qBAAa,wBAAwB;IACnC,OAAO,CAAC,KAAK,CAAuB;gBAKxB,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc;IAExD,4DAA4D;YAC9C,YAAY;YAMZ,gBAAgB;IAgC9B;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAyEhB,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,SAAS;IAMjB;;OAEG;IACH,OAAO,CAAC,SAAS;IAYjB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAQxB,2FAA2F;IACrF,MAAM,CACV,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QAAE,KAAK,EAAE,UAAU,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAwCzD,OAAO,CAAC,YAAY;IAepB;;;OAGG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,OAAO,GACX,OAAO,CAAC;QAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;CAwBhE;AAMD,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAE7F;AAED,wBAAgB,2BAA2B,IAAI,wBAAwB,CAOtE"}