@cyanheads/eia-energy-mcp-server 0.2.0

package/dist/services/eia/eia-service.js

@@ -0,0 +1,497 @@
+/**
+ * @fileoverview EIA API v2 service. Wraps api.eia.gov/v2 with retry/timeout,
+ * route tree caching, per-route facet metadata caching, and Fuse.js fuzzy
+ * search. Exposes browse, describe, query, and search methods consumed by MCP
+ * tool handlers. Rate-limit detection: EIA returns `OVER_RATE_LIMIT` in the
+ * response body — classified as ServiceUnavailable (retryable).
+ * @module services/eia/eia-service
+ */
+import { McpError, notFound, serviceUnavailable, validationError, } from '@cyanheads/mcp-ts-core/errors';
+import { withRetry } from '@cyanheads/mcp-ts-core/utils';
+import { getServerConfig } from '../../config/server-config.js';
+import { addSteoSeriesToIndex, getChildren, getIndexSize, getNode, initRouteCache, isLeafNode, isRouteCacheReady, normalizeDescription, searchRoutes, } from './route-cache.js';
+/** Per-route merged metadata cache (populated by describe). */
+const _routeMetaCache = new Map();
+/** Pending initialization promise (prevents duplicate warm-up). */
+let _initPromise;
+class EiaApiService {
+    get baseUrl() {
+        return getServerConfig().baseUrl;
+    }
+    get apiKey() {
+        return getServerConfig().apiKey;
+    }
+    buildUrl(path, params = {}) {
+        const url = new URL(`${this.baseUrl}/${path}`);
+        url.searchParams.set('api_key', this.apiKey);
+        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.toString();
+    }
+    fetchJson(path, params = {}, ctx) {
+        const url = this.buildUrl(path, params);
+        return withRetry(async () => {
+            const response = await fetch(url, { signal: ctx.signal });
+            const text = await response.text();
+            if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
+                throw serviceUnavailable('EIA API returned HTML — likely rate-limited or unavailable.', {
+                    reason: 'rate_limited',
+                });
+            }
+            if (!response.ok) {
+                if (response.status === 429 || text.includes('OVER_RATE_LIMIT')) {
+                    throw serviceUnavailable('EIA rate limit exceeded.', {
+                        reason: 'rate_limited',
+                    });
+                }
+                // Parse EIA's error body — it often includes an actionable message.
+                // Shape: { error: string, code: number } or plain text.
+                let upstreamMessage;
+                try {
+                    const errBody = JSON.parse(text);
+                    if (typeof errBody.error === 'string')
+                        upstreamMessage = errBody.error;
+                }
+                catch {
+                    // non-JSON body — ignore
+                }
+                const detail = upstreamMessage
+                    ? `EIA API error: ${upstreamMessage}`
+                    : `EIA API returned HTTP ${response.status}.`;
+                if (response.status === 404) {
+                    // 404s are definitive — NotFound code is not transient, withRetry won't retry
+                    throw notFound(detail, { status: response.status });
+                }
+                if (response.status === 400) {
+                    // 400s are definitive — ValidationError code is not transient, withRetry won't retry
+                    throw validationError(detail, { status: response.status });
+                }
+                // 5xx and other status codes — transient, eligible for retry
+                throw serviceUnavailable(detail, { status: response.status });
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                throw serviceUnavailable('EIA API returned non-JSON response.', {
+                    reason: 'rate_limited',
+                });
+            }
+            const parsedResponse = typeof parsed === 'object' && parsed !== null && 'response' in parsed
+                ? parsed.response
+                : undefined;
+            if (typeof parsedResponse === 'string' && parsedResponse.includes('OVER_RATE_LIMIT')) {
+                throw serviceUnavailable('EIA rate limit exceeded (OVER_RATE_LIMIT).', {
+                    reason: 'rate_limited',
+                });
+            }
+            return parsed;
+        }, {
+            operation: 'EiaApiService.fetchJson',
+            baseDelayMs: 1000,
+            signal: ctx.signal,
+        });
+    }
+    /**
+     * Warm the route tree cache. Called lazily on first browse/search.
+     * Fetches top-level routes, recursively discovers children via the cache
+     * structure from GET /v2/ and per-node GETs, then builds the Fuse.js index.
+     * STEO series are fetched in parallel and appended to the index.
+     */
+    async ensureCacheWarmed(ctx) {
+        if (isRouteCacheReady())
+            return;
+        if (_initPromise) {
+            await _initPromise;
+            return;
+        }
+        _initPromise = this.warmCache(ctx);
+        try {
+            await _initPromise;
+        }
+        finally {
+            _initPromise = undefined;
+        }
+    }
+    async warmCache(ctx) {
+        ctx.log.info('Warming EIA route tree cache');
+        // Fetch root to get top-level route IDs
+        const rootResponse = await this.fetchJson('', {}, ctx);
+        const topLevelNodes = rootResponse?.response?.routes ?? [];
+        if (topLevelNodes.length === 0) {
+            throw serviceUnavailable('EIA root endpoint returned no routes.');
+        }
+        // For each top-level node, fetch its metadata to discover sub-routes and
+        // leaf status. We do this recursively until we hit leaf nodes.
+        // Strategy: fetch each top-level node and recurse into non-leaf children.
+        const fullTree = await this.buildRouteTree(topLevelNodes, ctx);
+        // Build route map and index (without STEO series initially)
+        initRouteCache(fullTree, []);
+        // Fetch STEO series in the background to populate the index
+        this.fetchSteoSeries(ctx).catch((err) => {
+            ctx.log.warning('Failed to index STEO series', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        });
+        ctx.log.info('EIA route tree cache warmed', { indexSize: getIndexSize() });
+    }
+    async buildRouteTree(nodes, ctx, depth = 0, parentPath = '') {
+        // Limit recursion depth to avoid excessive API calls
+        if (depth > 5)
+            return nodes;
+        const enriched = await Promise.all(nodes.map(async (node) => {
+            const nodePath = parentPath ? `${parentPath}/${node.id}` : node.id;
+            // If the node already has sub-routes or leaf indicators, use as-is
+            if (node.routes?.length || node.frequency || node.facets || node.data) {
+                if (node.routes?.length) {
+                    const children = await this.buildRouteTree(node.routes, ctx, depth + 1, nodePath);
+                    return { ...node, routes: children };
+                }
+                return node;
+            }
+            // Otherwise fetch the node's metadata using its full path.
+            // Preserve node.id — EIA leaf responses return the domain category in
+            // their top-level `id` field (e.g. "petroleum"), not the route segment
+            // (e.g. "gnd"). Without this guard the merge would overwrite the
+            // segment ID and corrupt the path when buildNodeMap runs later.
+            try {
+                const resp = await this.fetchJson(nodePath, {}, ctx);
+                const fetched = resp?.response;
+                if (!fetched)
+                    return node;
+                // Preserve id and name from the stub — EIA leaf responses use the
+                // domain category as `id` (not the route segment) and often omit `name`.
+                const merged = { ...fetched, id: node.id, name: node.name ?? fetched.id };
+                if (merged.routes?.length) {
+                    const children = await this.buildRouteTree(merged.routes, ctx, depth + 1, nodePath);
+                    return { ...merged, routes: children };
+                }
+                return merged;
+            }
+            catch {
+                return node;
+            }
+        }));
+        return enriched;
+    }
+    async fetchSteoSeries(ctx) {
+        // Fetch STEO series via facet endpoint
+        const resp = await this.fetchJson('steo/facet/seriesId', {}, ctx);
+        const facets = resp?.response?.facets ?? [];
+        if (facets.length === 0)
+            return;
+        const entries = facets.map((f) => ({
+            route: 'steo',
+            name: f.name,
+            description: `STEO series: ${f.name} (${f.id})${f.alias ? ` — ${f.alias}` : ''}`,
+            isLeaf: true,
+            category: 'steo',
+            filter_hint: { seriesId: f.id },
+        }));
+        addSteoSeriesToIndex(entries);
+        ctx.log.info('STEO series indexed', { count: entries.length });
+    }
+    /**
+     * Browse child routes at a given path. Returns list of children with leaf
+     * classification.
+     */
+    async browse(path, ctx) {
+        await this.ensureCacheWarmed(ctx);
+        const normalizedPath = path?.trim() ?? '';
+        // Check if the path itself is a leaf
+        if (normalizedPath) {
+            const node = getNode(normalizedPath);
+            if (!node) {
+                throw notFound(`Route "${normalizedPath}" not found in the EIA taxonomy.`, {
+                    reason: 'route_not_found',
+                    recovery: {
+                        hint: 'Call eia_browse_routes without a path to see valid top-level categories.',
+                    },
+                });
+            }
+            const selfIsLeaf = isLeafNode(node);
+            if (selfIsLeaf) {
+                return { path: normalizedPath, children: [], isLeaf: true };
+            }
+            const childEntries = getChildren(normalizedPath);
+            const children = childEntries.map(({ id, route, node: childNode }) => ({
+                id,
+                name: childNode.name,
+                description: childNode.description ?? '',
+                route,
+                isLeaf: isLeafNode(childNode),
+            }));
+            return { path: normalizedPath, children, isLeaf: false };
+        }
+        // Root browse
+        const rootChildren = getChildren('');
+        const children = rootChildren.map(({ id, route, node }) => ({
+            id,
+            name: node.name,
+            description: node.description ?? '',
+            route,
+            isLeaf: isLeafNode(node),
+        }));
+        return { path: '', children, isLeaf: false };
+    }
+    /**
+     * Describe a leaf route — returns full metadata including facets with values.
+     * Results are cached per-route to avoid repeat fan-out.
+     */
+    async describe(route, ctx) {
+        const cached = _routeMetaCache.get(route);
+        if (cached)
+            return cached;
+        await this.ensureCacheWarmed(ctx);
+        const node = route ? getNode(route) : undefined;
+        if (!node && route) {
+            // Try fetching directly from EIA in case route tree walk missed it
+            await this.fetchAndCacheMetadata(route, ctx);
+            const meta = _routeMetaCache.get(route);
+            if (!meta) {
+                throw notFound(`Route "${route}" not found in the EIA taxonomy.`, {
+                    reason: 'route_not_found',
+                    recovery: {
+                        hint: 'Use eia_browse_routes or eia_search_routes to discover valid route paths.',
+                    },
+                });
+            }
+            return meta;
+        }
+        if (node && !isLeafNode(node)) {
+            throw validationError(`Route "${route}" is a category, not a leaf — it has no data to query.`, {
+                reason: 'route_not_queryable',
+                recovery: {
+                    hint: 'Use eia_browse_routes to drill into sub-routes, or eia_search_routes to find leaf routes.',
+                },
+            });
+        }
+        await this.fetchAndCacheMetadata(route, ctx);
+        const meta = _routeMetaCache.get(route);
+        if (!meta) {
+            throw notFound(`Could not retrieve metadata for route "${route}".`, {
+                reason: 'route_not_found',
+            });
+        }
+        return meta;
+    }
+    async fetchAndCacheMetadata(route, ctx) {
+        // Fetch route metadata — remap 404 to a typed route_not_found error
+        let metaRespRaw;
+        try {
+            metaRespRaw = await this.fetchJson(`${route}`, {}, ctx);
+        }
+        catch (err) {
+            if (err instanceof McpError && err.code === -32001 /* NotFound */) {
+                throw notFound(`Route "${route}" not found in the EIA taxonomy.`, {
+                    reason: 'route_not_found',
+                    recovery: {
+                        hint: 'Use eia_browse_routes or eia_search_routes to discover valid route paths.',
+                    },
+                });
+            }
+            throw err;
+        }
+        const rawNode = metaRespRaw?.response;
+        if (!rawNode) {
+            throw notFound(`Route "${route}" returned empty metadata.`, { reason: 'route_not_found' });
+        }
+        if (!isLeafNode(rawNode)) {
+            throw validationError(`Route "${route}" is a category, not a leaf.`, {
+                reason: 'route_not_queryable',
+                recovery: {
+                    hint: 'Use eia_browse_routes to drill into sub-routes, or eia_search_routes to find leaf routes.',
+                },
+            });
+        }
+        // Fan out facet value fetches
+        const facetMetas = rawNode.facets ?? [];
+        const facetResults = await Promise.all(facetMetas.map(async (f) => {
+            try {
+                const resp = await this.fetchJson(`${route}/facet/${f.id}`, {}, ctx);
+                const values = resp?.response?.facets ?? [];
+                return {
+                    id: f.id,
+                    description: f.description,
+                    // Filter null id/name entries — EIA returns null for some facet
+                    // values (e.g. international route), which carry no usable filter value.
+                    values: values
+                        .filter((v) => v.id != null && v.name != null)
+                        .map((v) => ({
+                        id: v.id,
+                        name: v.name,
+                        ...(v.alias !== undefined && { alias: v.alias }),
+                    })),
+                };
+            }
+            catch {
+                // If a single facet fetch fails, return with empty values
+                return { id: f.id, description: f.description, values: [] };
+            }
+        }));
+        // Normalize data columns. EIA uses two data field shapes:
+        //   Standard: { colId: { alias: string, units: string }, ... }
+        //   Value-array: { value: [] } — time-series routes where the single data
+        //     column is always named "value". Synthesize a minimal DataColumn entry
+        //     so query() can auto-populate data[]=value and return actual measurements.
+        const dataObj = rawNode.data ?? {};
+        const dataColumns = Object.entries(dataObj)
+            .filter(([, meta]) => meta !== null && typeof meta === 'object' && !Array.isArray(meta))
+            .map(([id, meta]) => {
+            const col = meta;
+            // alias and units may be undefined for some EIA routes (e.g. crude-oil-imports)
+            return { id, alias: col.alias ?? id, units: col.units ?? '' };
+        });
+        // Handle the value-array variant: { value: [] }
+        if (dataColumns.length === 0 && 'value' in dataObj && Array.isArray(dataObj.value)) {
+            dataColumns.push({ id: 'value', alias: 'Value', units: '' });
+        }
+        const frequencies = rawNode.frequency ?? [];
+        const meta = {
+            route,
+            description: normalizeDescription(rawNode.description),
+            facets: facetResults,
+            dataColumns,
+            frequencies,
+            dateRange: {
+                start: rawNode.startPeriod ?? '',
+                end: rawNode.endPeriod ?? '',
+            },
+            defaultFrequency: rawNode.defaultFrequency ?? frequencies[0]?.id ?? '',
+            defaultDateFormat: rawNode.defaultDateFormat ?? '',
+        };
+        _routeMetaCache.set(route, meta);
+    }
+    /**
+     * Fetch data from a leaf route. Returns rows (all string values per EIA API),
+     * total count, and any warnings.
+     */
+    async query(route, opts, ctx) {
+        if ((opts.length ?? 100) > 5000) {
+            throw validationError('length exceeds EIA maximum of 5000 rows per request.', {
+                reason: 'length_exceeded',
+                maxLength: 5000,
+                recovery: {
+                    hint: 'Reduce length to 5000 or use offset pagination to retrieve more rows.',
+                },
+            });
+        }
+        // Pre-flight: if the route is in the cache as a category node, fail early
+        // with a typed error rather than letting the EIA API return a generic 404.
+        await this.ensureCacheWarmed(ctx);
+        const cachedNode = getNode(route);
+        if (cachedNode && !isLeafNode(cachedNode)) {
+            throw validationError(`Route "${route}" is a category, not a leaf — it has no data to query.`, {
+                reason: 'route_not_found',
+                recovery: {
+                    hint: 'Use eia_browse_routes or eia_search_routes to find a valid leaf route path.',
+                },
+            });
+        }
+        const params = {};
+        if (opts.frequency)
+            params.frequency = opts.frequency;
+        if (opts.start)
+            params.start = opts.start;
+        if (opts.end)
+            params.end = opts.end;
+        if (opts.offset !== undefined)
+            params.offset = String(opts.offset);
+        if (opts.length !== undefined)
+            params.length = String(opts.length);
+        // EIA only returns value fields when data[] params are explicitly set.
+        // When the caller omits columns, auto-populate from route metadata so
+        // all available data columns are included by default.
+        let columnsToRequest = opts.columns;
+        if (!columnsToRequest?.length) {
+            const cached = _routeMetaCache.get(route);
+            if (cached?.dataColumns.length) {
+                columnsToRequest = cached.dataColumns.map((c) => c.id);
+            }
+        }
+        if (columnsToRequest?.length) {
+            params['data[]'] = columnsToRequest;
+        }
+        if (opts.filters) {
+            for (const [facetId, values] of Object.entries(opts.filters)) {
+                const arr = Array.isArray(values) ? values : [values];
+                params[`facets[${facetId}][]`] = arr;
+            }
+        }
+        for (const [i, s] of (opts.sort ?? []).entries()) {
+            params[`sort[${i}][column]`] = s.column;
+            params[`sort[${i}][direction]`] = s.direction;
+        }
+        let resp;
+        try {
+            resp = await this.fetchJson(`${route}/data/`, params, ctx);
+        }
+        catch (err) {
+            if (err instanceof McpError) {
+                if (err.code === -32001 /* NotFound */) {
+                    throw notFound(`Route "${route}" not found in the EIA taxonomy.`, {
+                        reason: 'route_not_found',
+                        recovery: {
+                            hint: 'Use eia_browse_routes or eia_search_routes to find a valid leaf route path.',
+                        },
+                    });
+                }
+                if (err.code === -32007 /* ValidationError */) {
+                    // 400 from EIA — likely an invalid facet key. Surface the EIA message
+                    // plus the contract recovery hint.
+                    const eiaMsg = err.message;
+                    throw validationError(eiaMsg, {
+                        reason: 'invalid_facet',
+                        recovery: {
+                            hint: 'Call eia_describe_route to see valid facet IDs for this route.',
+                        },
+                    });
+                }
+            }
+            throw err;
+        }
+        const response = resp?.response;
+        if (!response) {
+            throw notFound(`Route "${route}" returned no data response.`, { reason: 'no_data' });
+        }
+        const total = parseInt(response.total ?? '0', 10);
+        const data = response.data ?? [];
+        return {
+            total,
+            dateFormat: response.dateFormat ?? '',
+            frequency: response.frequency ?? opts.frequency ?? '',
+            data,
+            warnings: response.warnings ?? undefined,
+        };
+    }
+    /** Fuzzy search across the route index. */
+    async search(query, limit, ctx) {
+        await this.ensureCacheWarmed(ctx);
+        const results = searchRoutes(query, limit);
+        return { results, totalIndexed: getIndexSize() };
+    }
+}
+let _service;
+export function initEiaApiService() {
+    _service = new EiaApiService();
+}
+export function getEiaApiService() {
+    if (!_service)
+        throw new Error('EiaApiService not initialized — call initEiaApiService() in setup()');
+    return _service;
+}
+/** Reset for tests. */
+export function _resetEiaApiService() {
+    _service = undefined;
+    _routeMetaCache.clear();
+    _initPromise = undefined;
+}
+//# sourceMappingURL=eia-service.js.map

package/dist/services/eia/eia-service.js.map

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

package/dist/services/eia/route-cache.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview In-process route tree cache and Fuse.js fuzzy search index.
+ * The route tree is fetched lazily on first use and held for the process
+ * lifetime — EIA's taxonomy is stable between API releases and restarting the
+ * server is the appropriate refresh mechanism. The Fuse.js index is built once
+ * after the tree is populated and includes STEO series names so natural-language
+ * queries resolve to specific seriesId values.
+ * @module services/eia/route-cache
+ */
+import Fuse from 'fuse.js';
+import type { RawRouteNode, SearchIndexEntry } from './types.js';
+/** Holds the in-process route tree state. */
+interface CacheState {
+    /** Sorted list of all index entries for total_indexed count. */
+    entries: SearchIndexEntry[];
+    /** Fuse.js index built over all routes + STEO series. */
+    fuseIndex: Fuse<SearchIndexEntry>;
+    /** Flat map of route path → raw node (all nodes in the tree). */
+    nodeMap: Map<string, RawRouteNode>;
+}
+/**
+ * Normalize a description string from the EIA API. EIA descriptions often
+ * contain embedded `\r\n` + leading whitespace (source-level line wrapping).
+ * Collapse to a clean single-line string.
+ */
+export declare function normalizeDescription(desc: string | undefined): string;
+/** Walk the raw route tree and collect all nodes into a flat path→node map. */
+export declare function buildNodeMap(nodes: RawRouteNode[], parentPath: string, map: Map<string, RawRouteNode>): void;
+/**
+ * Classify a raw node as a leaf. A node is a leaf when it has `frequency`,
+ * `facets`, or `data` fields (queryable data endpoint) rather than a `routes`
+ * array. Root-level nodes with no sub-routes and no data fields are treated as
+ * leaves (e.g. steo).
+ */
+export declare function isLeafNode(node: RawRouteNode): boolean;
+/** Initialize the cache with the fetched route tree and optional STEO entries. */
+export declare function initRouteCache(topLevelNodes: RawRouteNode[], steoSeriesEntries: SearchIndexEntry[]): void;
+/** Return the cache, throwing if not yet initialized. */
+export declare function getRouteCache(): CacheState;
+/** True when the cache has been populated. */
+export declare function isRouteCacheReady(): boolean;
+/** Reset the cache (used in tests). */
+export declare function _resetRouteCache(): void;
+/** Get a node by route path. Returns undefined when not found. */
+export declare function getNode(path: string): RawRouteNode | undefined;
+/**
+ * Get children of a given path. For root (empty path), returns top-level nodes.
+ * Returns empty array when path has no children.
+ */
+export declare function getChildren(path: string): Array<{
+    id: string;
+    route: string;
+    node: RawRouteNode;
+}>;
+/** Fuzzy search across the index. Returns ranked matches. */
+export declare function searchRoutes(query: string, limit: number): Array<{
+    entry: SearchIndexEntry;
+    score: number;
+}>;
+/** Total number of indexed entries. */
+export declare function getIndexSize(): number;
+/** Add STEO series entries to an already-initialized cache. */
+export declare function addSteoSeriesToIndex(steoEntries: SearchIndexEntry[]): void;
+export {};
+//# sourceMappingURL=route-cache.d.ts.map

package/dist/services/eia/route-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-cache.d.ts","sourceRoot":"","sources":["../../../src/services/eia/route-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,IAA2B,MAAM,SAAS,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEjE,6CAA6C;AAC7C,UAAU,UAAU;IAClB,gEAAgE;IAChE,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,yDAAyD;IACzD,SAAS,EAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC;IAClC,iEAAiE;IACjE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACpC;AAID;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAOrE;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAC1B,KAAK,EAAE,YAAY,EAAE,EACrB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,GAC7B,IAAI,CAaN;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAMtD;AA+BD,kFAAkF;AAClF,wBAAgB,cAAc,CAC5B,aAAa,EAAE,YAAY,EAAE,EAC7B,iBAAiB,EAAE,gBAAgB,EAAE,GACpC,IAAI,CAYN;AAED,yDAAyD;AACzD,wBAAgB,aAAa,IAAI,UAAU,CAG1C;AAED,8CAA8C;AAC9C,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAED,uCAAuC;AACvC,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC;AAED,kEAAkE;AAClE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAO9D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,GACX,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,YAAY,CAAA;CAAE,CAAC,CAuB1D;AAED,6DAA6D;AAC7D,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,KAAK,CAAC;IAAE,KAAK,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAOnD;AAED,uCAAuC;AACvC,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAI1E"}