@lagoon-protocol/lagoon-mcp 0.1.0

package/dist/cache/index.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Caching Layer
+ *
+ * In-memory caching with TTL using node-cache
+ */
+import NodeCache from 'node-cache';
+/**
+ * Shared cache instance
+ */
+export declare const cache: NodeCache;
+/**
+ * Cache TTL configuration by data type (in seconds)
+ *
+ * TTL Selection Criteria:
+ *
+ * 1. **Data Volatility**: How frequently the underlying data changes
+ *    - High volatility (user actions, market prices) = shorter TTL
+ *    - Low volatility (configuration, historical data) = longer TTL
+ *
+ * 2. **User Expectations**: How "fresh" users expect data to be
+ *    - Real-time needs (portfolio values) = shorter TTL
+ *    - Historical analysis (past performance) = longer TTL
+ *
+ * 3. **API Load Impact**: Balance between freshness and server load
+ *    - Frequently accessed endpoints = moderate TTL for load reduction
+ *    - Expensive queries (aggregations) = longer TTL for performance
+ *
+ * 4. **Data Type Characteristics**:
+ *    - Static reference data (schema, glossary) = 24h+
+ *    - Analytical results (predictions, risk) = 15-60min
+ *    - User-specific data (portfolio) = 5min
+ *    - Search/filter results = 10min
+ *    - Historical data (performance, prices) = 30min
+ */
+export declare const cacheTTL: {
+    readonly vaultData: 900;
+    readonly userPortfolio: 300;
+    readonly searchResults: 600;
+    readonly performance: 1800;
+    readonly transactions: 300;
+    readonly schema: 86400;
+    readonly comparison: 900;
+    readonly priceHistory: 1800;
+    readonly riskAnalysis: 900;
+    readonly yieldPrediction: 3600;
+    readonly portfolioOptimization: 300;
+};
+/**
+ * Search filters type for cache key generation
+ */
+type SearchFilters = {
+    filterHash: string;
+};
+/**
+ * Cache key generators
+ *
+ * Provides consistent cache key formatting for different data types
+ */
+export declare const cacheKeys: {
+    vaultData: (address: string, chainId: number) => string;
+    userPortfolio: (address: string) => string;
+    searchVaults: (filters: SearchFilters) => string;
+    vaultPerformance: (address: string, chainId: number, range: string) => string;
+    transactions: ({ vaultAddress, chainId, filterHash, first, skip, orderBy, orderDirection, }: {
+        vaultAddress: string;
+        chainId: number;
+        filterHash: string;
+        first: number;
+        skip: number;
+        orderBy: string;
+        orderDirection: string;
+    }) => string;
+    schema: () => string;
+    compareVaults: (addresses: string[], chainId: number) => string;
+    priceHistory: (address: string, chainId: number, range: string) => string;
+};
+/**
+ * Generate cache key based on cache tag and parameters
+ *
+ * NEW: Generic cache key generator for fragment-level caching
+ * Used to create consistent cache keys across different tools
+ *
+ * @param tag - Cache tag identifying the data type
+ * @param params - Parameters for cache key generation
+ * @returns Generated cache key string
+ */
+export declare function generateCacheKey(tag: string, params: Record<string, string | number>): string;
+/**
+ * Cache statistics
+ */
+export declare function getCacheStats(): NodeCache.Stats;
+/**
+ * Clear all cache entries
+ */
+export declare function clearCache(): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,SAAS,MAAM,YAAY,CAAC;AAGnC;;GAEG;AACH,eAAO,MAAM,KAAK,WAKhB,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;CAYX,CAAC;AAEX;;GAEG;AACH,KAAK,aAAa,GAAG;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS;yBACC,MAAM,WAAW,MAAM,KAAG,MAAM;6BAE5B,MAAM,KAAG,MAAM;4BAEhB,aAAa,KAAG,MAAM;gCAElB,MAAM,WAAW,MAAM,SAAS,MAAM,KAAG,MAAM;iGAWxE;QACD,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,cAAc,EAAE,MAAM,CAAC;KACxB,KAAG,MAAM;kBAGE,MAAM;+BAES,MAAM,EAAE,WAAW,MAAM,KAAG,MAAM;4BAKrC,MAAM,WAAW,MAAM,SAAS,MAAM,KAAG,MAAM;CAExE,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAa7F;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,SAAS,CAAC,KAAK,CAE/C;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}

package/dist/cache/index.js

@@ -0,0 +1,106 @@
+/**
+ * Caching Layer
+ *
+ * In-memory caching with TTL using node-cache
+ */
+import NodeCache from 'node-cache';
+import { config } from '../config.js';
+/**
+ * Shared cache instance
+ */
+export const cache = new NodeCache({
+    stdTTL: config.cache.stdTTL,
+    checkperiod: config.cache.checkperiod,
+    useClones: false, // Performance optimization
+    maxKeys: config.cache.maxKeys,
+});
+/**
+ * Cache TTL configuration by data type (in seconds)
+ *
+ * TTL Selection Criteria:
+ *
+ * 1. **Data Volatility**: How frequently the underlying data changes
+ *    - High volatility (user actions, market prices) = shorter TTL
+ *    - Low volatility (configuration, historical data) = longer TTL
+ *
+ * 2. **User Expectations**: How "fresh" users expect data to be
+ *    - Real-time needs (portfolio values) = shorter TTL
+ *    - Historical analysis (past performance) = longer TTL
+ *
+ * 3. **API Load Impact**: Balance between freshness and server load
+ *    - Frequently accessed endpoints = moderate TTL for load reduction
+ *    - Expensive queries (aggregations) = longer TTL for performance
+ *
+ * 4. **Data Type Characteristics**:
+ *    - Static reference data (schema, glossary) = 24h+
+ *    - Analytical results (predictions, risk) = 15-60min
+ *    - User-specific data (portfolio) = 5min
+ *    - Search/filter results = 10min
+ *    - Historical data (performance, prices) = 30min
+ */
+export const cacheTTL = {
+    vaultData: 900, // 15 minutes - vault fundamentals change infrequently
+    userPortfolio: 300, // 5 minutes - positions change with user actions
+    searchResults: 600, // 10 minutes - discovery queries, balanced freshness
+    performance: 1800, // 30 minutes - historical metrics, computation-heavy
+    transactions: 300, // 5 minutes - transaction history updates
+    schema: 86400, // 24 hours - schema changes require deployment
+    comparison: 900, // 15 minutes - derived metrics from vault data
+    priceHistory: 1800, // 30 minutes - historical OHLCV data, expensive query
+    riskAnalysis: 900, // 15 minutes - multi-factor calculation, moderate cost
+    yieldPrediction: 3600, // 60 minutes - ML-based forecast, expensive computation
+    portfolioOptimization: 300, // 5 minutes - user-specific, interactive use case
+};
+/**
+ * Cache key generators
+ *
+ * Provides consistent cache key formatting for different data types
+ */
+export const cacheKeys = {
+    vaultData: (address, chainId) => `vault:${address}:${chainId}`,
+    userPortfolio: (address) => `portfolio:${address}`,
+    searchVaults: (filters) => `search:${filters.filterHash}`,
+    vaultPerformance: (address, chainId, range) => `perf:${address}:${chainId}:${range}`,
+    transactions: ({ vaultAddress, chainId, filterHash, first, skip, orderBy, orderDirection, }) => `transactions:${vaultAddress}:${chainId}:${filterHash}:${first}:${skip}:${orderBy}:${orderDirection}`,
+    schema: () => 'schema:latest',
+    compareVaults: (addresses, chainId) => {
+        const sortedAddresses = [...addresses].sort().join(',');
+        return `compare:${sortedAddresses}:${chainId}`;
+    },
+    priceHistory: (address, chainId, range) => `price_history:${address}:${chainId}:${range}`,
+};
+/**
+ * Generate cache key based on cache tag and parameters
+ *
+ * NEW: Generic cache key generator for fragment-level caching
+ * Used to create consistent cache keys across different tools
+ *
+ * @param tag - Cache tag identifying the data type
+ * @param params - Parameters for cache key generation
+ * @returns Generated cache key string
+ */
+export function generateCacheKey(tag, params) {
+    // For vault data, use the standard vault cache key format
+    if (tag === 'VAULT' && 'address' in params && 'chainId' in params) {
+        return cacheKeys.vaultData(String(params.address), Number(params.chainId));
+    }
+    // Generic fallback for other cache keys
+    const sortedParams = Object.entries(params)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => `${key}:${value}`)
+        .join(':');
+    return `${tag.toLowerCase()}:${sortedParams}`;
+}
+/**
+ * Cache statistics
+ */
+export function getCacheStats() {
+    return cache.getStats();
+}
+/**
+ * Clear all cache entries
+ */
+export function clearCache() {
+    cache.flushAll();
+}
+//# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Configuration management for Lagoon MCP
+ *
+ * Centralized configuration with validated environment variables.
+ * All environment variables are validated at startup using Zod schema.
+ * The application will exit with clear error messages if misconfigured.
+ */
+/**
+ * Application configuration
+ *
+ * This configuration is validated at startup to ensure all required
+ * environment variables are properly set. The application will not
+ * start if configuration is invalid.
+ */
+export declare const config: {
+    readonly graphql: {
+        readonly endpoint: string;
+        readonly timeout: 30000;
+    };
+    readonly cache: {
+        readonly stdTTL: number;
+        readonly checkperiod: 120;
+        readonly maxKeys: number;
+    };
+    readonly server: {
+        readonly name: "lagoon-mcp";
+        readonly version: "0.1.0";
+    };
+    readonly isDevelopment: boolean;
+    readonly isProduction: boolean;
+    readonly isTest: boolean;
+};
+export type Config = typeof config;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH;;;;;;GAMG;AACH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;CAwBT,CAAC;AAEX,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC"}

package/dist/config.js

@@ -0,0 +1,40 @@
+/**
+ * Configuration management for Lagoon MCP
+ *
+ * Centralized configuration with validated environment variables.
+ * All environment variables are validated at startup using Zod schema.
+ * The application will exit with clear error messages if misconfigured.
+ */
+import { loadAndValidateEnv } from './utils/config-loader.js';
+// Validate environment variables at startup (fails fast if misconfigured)
+const env = loadAndValidateEnv();
+/**
+ * Application configuration
+ *
+ * This configuration is validated at startup to ensure all required
+ * environment variables are properly set. The application will not
+ * start if configuration is invalid.
+ */
+export const config = {
+    // GraphQL Backend
+    graphql: {
+        endpoint: env.LAGOON_GRAPHQL_URL,
+        timeout: 30000, // 30 seconds
+    },
+    // Caching
+    cache: {
+        stdTTL: env.CACHE_TTL ?? 600, // Default 10 minutes
+        checkperiod: 120, // Check expired keys every 2 minutes
+        maxKeys: env.CACHE_MAX_KEYS ?? 1000, // Maximum cache entries
+    },
+    // Server
+    server: {
+        name: 'lagoon-mcp',
+        version: '0.1.0',
+    },
+    // Environment flags
+    isDevelopment: env.NODE_ENV === 'development',
+    isProduction: env.NODE_ENV === 'production',
+    isTest: env.NODE_ENV === 'test',
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,0EAA0E;AAC1E,MAAM,GAAG,GAAG,kBAAkB,EAAE,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,kBAAkB;IAClB,OAAO,EAAE;QACP,QAAQ,EAAE,GAAG,CAAC,kBAAkB;QAChC,OAAO,EAAE,KAAK,EAAE,aAAa;KAC9B;IAED,UAAU;IACV,KAAK,EAAE;QACL,MAAM,EAAE,GAAG,CAAC,SAAS,IAAI,GAAG,EAAE,qBAAqB;QACnD,WAAW,EAAE,GAAG,EAAE,qCAAqC;QACvD,OAAO,EAAE,GAAG,CAAC,cAAc,IAAI,IAAI,EAAE,wBAAwB;KAC9D;IAED,SAAS;IACT,MAAM,EAAE;QACN,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,OAAO;KACjB;IAED,oBAAoB;IACpB,aAAa,EAAE,GAAG,CAAC,QAAQ,KAAK,aAAa;IAC7C,YAAY,EAAE,GAAG,CAAC,QAAQ,KAAK,YAAY;IAC3C,MAAM,EAAE,GAAG,CAAC,QAAQ,KAAK,MAAM;CACvB,CAAC"}

package/dist/core/cache-adapter.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Cache Service Abstraction
+ *
+ * Provides interface for caching implementations.
+ * Allows swapping cache backends without changing tool code.
+ */
+import NodeCache from 'node-cache';
+/**
+ * Cache statistics interface
+ */
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    keys: number;
+    ksize: number;
+    vsize: number;
+}
+/**
+ * Cache service interface
+ * Abstracts away concrete caching implementation
+ */
+export interface CacheService {
+    /**
+     * Get cached value
+     * @returns Cached value or undefined if not found or expired
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Set cache value with TTL
+     * @param key Cache key
+     * @param value Value to cache
+     * @param ttl Time-to-live in seconds
+     */
+    set<T>(key: string, value: T, ttl: number): void;
+    /**
+     * Check if key exists in cache
+     */
+    has(key: string): boolean;
+    /**
+     * Delete cache entry
+     */
+    del(key: string): void;
+    /**
+     * Clear all cache entries
+     */
+    flush(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+}
+/**
+ * NodeCache adapter implementing CacheService interface
+ */
+export declare class NodeCacheAdapter implements CacheService {
+    private cache;
+    constructor(cache: NodeCache);
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttl: number): void;
+    has(key: string): boolean;
+    del(key: string): void;
+    flush(): void;
+    getStats(): CacheStats;
+}
+/**
+ * Create NodeCache adapter with configuration
+ */
+export declare function createNodeCacheAdapter(options: {
+    stdTTL: number;
+    checkperiod: number;
+    maxKeys: number;
+}): CacheService;
+//# sourceMappingURL=cache-adapter.d.ts.map

package/dist/core/cache-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-adapter.d.ts","sourceRoot":"","sources":["../../src/core/cache-adapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,SAAS,MAAM,YAAY,CAAC;AAEnC;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAEnC;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjD;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE1B;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAEvB;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;OAEG;IACH,QAAQ,IAAI,UAAU,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACvC,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,SAAS;IAEpC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAIlC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAIhD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAItB,KAAK,IAAI,IAAI;IAIb,QAAQ,IAAI,UAAU;CAGvB;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,YAAY,CASf"}

package/dist/core/cache-adapter.js

@@ -0,0 +1,47 @@
+/**
+ * Cache Service Abstraction
+ *
+ * Provides interface for caching implementations.
+ * Allows swapping cache backends without changing tool code.
+ */
+import NodeCache from 'node-cache';
+/**
+ * NodeCache adapter implementing CacheService interface
+ */
+export class NodeCacheAdapter {
+    cache;
+    constructor(cache) {
+        this.cache = cache;
+    }
+    get(key) {
+        return this.cache.get(key);
+    }
+    set(key, value, ttl) {
+        this.cache.set(key, value, ttl);
+    }
+    has(key) {
+        return this.cache.has(key);
+    }
+    del(key) {
+        this.cache.del(key);
+    }
+    flush() {
+        this.cache.flushAll();
+    }
+    getStats() {
+        return this.cache.getStats();
+    }
+}
+/**
+ * Create NodeCache adapter with configuration
+ */
+export function createNodeCacheAdapter(options) {
+    const cache = new NodeCache({
+        stdTTL: options.stdTTL,
+        checkperiod: options.checkperiod,
+        useClones: false, // Performance optimization
+        maxKeys: options.maxKeys,
+    });
+    return new NodeCacheAdapter(cache);
+}
+//# sourceMappingURL=cache-adapter.js.map

package/dist/core/cache-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-adapter.js","sourceRoot":"","sources":["../../src/core/cache-adapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,SAAS,MAAM,YAAY,CAAC;AAqDnC;;GAEG;AACH,MAAM,OAAO,gBAAgB;IACP;IAApB,YAAoB,KAAgB;QAAhB,UAAK,GAAL,KAAK,CAAW;IAAG,CAAC;IAExC,GAAG,CAAI,GAAW;QAChB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAI,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,GAAW;QACvC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED,GAAG,CAAC,GAAW;QACb,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC/B,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAItC;IACC,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC;QAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,SAAS,EAAE,KAAK,EAAE,2BAA2B;QAC7C,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;IAEH,OAAO,IAAI,gBAAgB,CAAC,KAAK,CAAC,CAAC;AACrC,CAAC"}

package/dist/core/cache-invalidation.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Cache Invalidation System
+ *
+ * Tag-based cache invalidation for maintaining consistency.
+ * When data changes, invalidate all related cache entries by tag.
+ */
+import type { CacheService } from './cache-adapter.js';
+/**
+ * Cache tags for organizing related entries
+ */
+export declare enum CacheTag {
+    VAULT = "vault",
+    PORTFOLIO = "portfolio",
+    TRANSACTION = "transaction",
+    ANALYTICS = "analytics",
+    APR = "apr",
+    RISK = "risk",
+    ALL = "all"
+}
+/**
+ * Cache invalidation coordinator
+ */
+export declare class CacheInvalidator {
+    private cache;
+    private tagMap;
+    constructor(cache: CacheService);
+    /**
+     * Register a cache key with its associated tags
+     */
+    register(key: string, tags: CacheTag[]): void;
+    /**
+     * Invalidate all cache entries with the given tag
+     */
+    invalidateByTag(tag: CacheTag): number;
+    /**
+     * Invalidate multiple tags at once
+     */
+    invalidateByTags(tags: CacheTag[]): number;
+    /**
+     * Invalidate a specific cache key
+     */
+    invalidateKey(key: string): boolean;
+    /**
+     * Clear all cache entries
+     */
+    invalidateAll(): void;
+    /**
+     * Get all keys associated with a tag
+     */
+    getKeysByTag(tag: CacheTag): string[];
+    /**
+     * Get cache statistics with tag information
+     */
+    getStats(): {
+        totalKeys: number;
+        tagCount: number;
+        keysByTag: Record<string, number>;
+    };
+}
+/**
+ * Example usage relationships
+ *
+ * When vault data changes:
+ * - Invalidate CacheTag.VAULT → clears vault data, apr, risk analysis
+ *
+ * When portfolio is rebalanced:
+ * - Invalidate CacheTag.PORTFOLIO → clears portfolio optimization
+ *
+ * When transaction occurs:
+ * - Invalidate [CacheTag.VAULT, CacheTag.ANALYTICS] → clears affected data
+ */
+//# sourceMappingURL=cache-invalidation.d.ts.map

package/dist/core/cache-invalidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-invalidation.d.ts","sourceRoot":"","sources":["../../src/core/cache-invalidation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;GAEG;AACH,oBAAY,QAAQ;IAClB,KAAK,UAAU;IACf,SAAS,cAAc;IACvB,WAAW,gBAAgB;IAC3B,SAAS,cAAc;IACvB,GAAG,QAAQ;IACX,IAAI,SAAS;IACb,GAAG,QAAQ;CACZ;AAOD;;GAEG;AACH,qBAAa,gBAAgB;IAGf,OAAO,CAAC,KAAK;IAFzB,OAAO,CAAC,MAAM,CAA0B;gBAEpB,KAAK,EAAE,YAAY;IAEvC;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,IAAI;IAM7C;;OAEG;IACH,eAAe,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM;IActC;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,QAAQ,EAAE,GAAG,MAAM;IAU1C;;OAEG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAKnC;;OAEG;IACH,aAAa,IAAI,IAAI;IAKrB;;OAEG;IACH,YAAY,CAAC,GAAG,EAAE,QAAQ,GAAG,MAAM,EAAE;IAYrC;;OAEG;IACH,QAAQ,IAAI;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACnC;CAaF;AAED;;;;;;;;;;;GAWG"}

package/dist/core/cache-invalidation.js

@@ -0,0 +1,114 @@
+/**
+ * Cache Invalidation System
+ *
+ * Tag-based cache invalidation for maintaining consistency.
+ * When data changes, invalidate all related cache entries by tag.
+ */
+/**
+ * Cache tags for organizing related entries
+ */
+export var CacheTag;
+(function (CacheTag) {
+    CacheTag["VAULT"] = "vault";
+    CacheTag["PORTFOLIO"] = "portfolio";
+    CacheTag["TRANSACTION"] = "transaction";
+    CacheTag["ANALYTICS"] = "analytics";
+    CacheTag["APR"] = "apr";
+    CacheTag["RISK"] = "risk";
+    CacheTag["ALL"] = "all";
+})(CacheTag || (CacheTag = {}));
+/**
+ * Cache invalidation coordinator
+ */
+export class CacheInvalidator {
+    cache;
+    tagMap = new Map();
+    constructor(cache) {
+        this.cache = cache;
+    }
+    /**
+     * Register a cache key with its associated tags
+     */
+    register(key, tags) {
+        const tagSet = this.tagMap.get(key) || new Set();
+        tags.forEach((tag) => tagSet.add(tag));
+        this.tagMap.set(key, tagSet);
+    }
+    /**
+     * Invalidate all cache entries with the given tag
+     */
+    invalidateByTag(tag) {
+        let invalidated = 0;
+        for (const [key, tags] of this.tagMap.entries()) {
+            if (tags.has(tag) || tag === CacheTag.ALL) {
+                this.cache.del(key);
+                this.tagMap.delete(key);
+                invalidated++;
+            }
+        }
+        return invalidated;
+    }
+    /**
+     * Invalidate multiple tags at once
+     */
+    invalidateByTags(tags) {
+        let invalidated = 0;
+        for (const tag of tags) {
+            invalidated += this.invalidateByTag(tag);
+        }
+        return invalidated;
+    }
+    /**
+     * Invalidate a specific cache key
+     */
+    invalidateKey(key) {
+        this.cache.del(key);
+        return this.tagMap.delete(key);
+    }
+    /**
+     * Clear all cache entries
+     */
+    invalidateAll() {
+        this.cache.flush();
+        this.tagMap.clear();
+    }
+    /**
+     * Get all keys associated with a tag
+     */
+    getKeysByTag(tag) {
+        const keys = [];
+        for (const [key, tags] of this.tagMap.entries()) {
+            if (tags.has(tag)) {
+                keys.push(key);
+            }
+        }
+        return keys;
+    }
+    /**
+     * Get cache statistics with tag information
+     */
+    getStats() {
+        const keysByTag = {};
+        for (const tag of Object.values(CacheTag)) {
+            keysByTag[tag] = this.getKeysByTag(tag).length;
+        }
+        return {
+            totalKeys: this.tagMap.size,
+            tagCount: Object.keys(CacheTag).length,
+            keysByTag,
+        };
+    }
+}
+/**
+ * Example usage relationships
+ *
+ * When vault data changes:
+ * - Invalidate CacheTag.VAULT → clears vault data, apr, risk analysis
+ *
+ * When portfolio is rebalanced:
+ * - Invalidate CacheTag.PORTFOLIO → clears portfolio optimization
+ *
+ * When transaction occurs:
+ * - Invalidate [CacheTag.VAULT, CacheTag.ANALYTICS] → clears affected data
+ */
+//# sourceMappingURL=cache-invalidation.js.map

package/dist/core/cache-invalidation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-invalidation.js","sourceRoot":"","sources":["../../src/core/cache-invalidation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;GAEG;AACH,MAAM,CAAN,IAAY,QAQX;AARD,WAAY,QAAQ;IAClB,2BAAe,CAAA;IACf,mCAAuB,CAAA;IACvB,uCAA2B,CAAA;IAC3B,mCAAuB,CAAA;IACvB,uBAAW,CAAA;IACX,yBAAa,CAAA;IACb,uBAAW,CAAA;AACb,CAAC,EARW,QAAQ,KAAR,QAAQ,QAQnB;AAOD;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAGP;IAFZ,MAAM,GAAgB,IAAI,GAAG,EAAE,CAAC;IAExC,YAAoB,KAAmB;QAAnB,UAAK,GAAL,KAAK,CAAc;IAAG,CAAC;IAE3C;;OAEG;IACH,QAAQ,CAAC,GAAW,EAAE,IAAgB;QACpC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC;QACjD,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,eAAe,CAAC,GAAa;QAC3B,IAAI,WAAW,GAAG,CAAC,CAAC;QAEpB,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;YAChD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,KAAK,QAAQ,CAAC,GAAG,EAAE,CAAC;gBAC1C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACpB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACxB,WAAW,EAAE,CAAC;YAChB,CAAC;QACH,CAAC;QAED,OAAO,WAAW,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,gBAAgB,CAAC,IAAgB;QAC/B,IAAI,WAAW,GAAG,CAAC,CAAC;QAEpB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,WAAW,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QAC3C,CAAC;QAED,OAAO,WAAW,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,GAAW;QACvB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACpB,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED;;OAEG;IACH,aAAa;QACX,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,GAAa;QACxB,MAAM,IAAI,GAAa,EAAE,CAAC;QAE1B,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;YAChD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACjB,CAAC;QACH,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,QAAQ;QAKN,MAAM,SAAS,GAA2B,EAAE,CAAC;QAE7C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1C,SAAS,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;QACjD,CAAC;QAED,OAAO;YACL,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;YAC3B,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM;YACtC,SAAS;SACV,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;GAWG"}

package/dist/core/container.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Dependency Injection Container
+ *
+ * Provides centralized dependency management for testability and flexibility.
+ * Eliminates global singletons and enables easy mocking for tests.
+ */
+import { GraphQLClient } from 'graphql-request';
+import { Config } from '../config.js';
+import { CacheService } from './cache-adapter.js';
+import { CacheInvalidator } from './cache-invalidation.js';
+/**
+ * Service container interface
+ * All application dependencies are accessed through this container
+ */
+export interface ServiceContainer {
+    /** GraphQL client for backend communication */
+    graphqlClient: GraphQLClient;
+    /** Cache service for data caching */
+    cache: CacheService;
+    /** Cache invalidation coordinator */
+    cacheInvalidator: CacheInvalidator;
+    /** Application configuration */
+    config: Config;
+}
+/**
+ * Create production container with real implementations
+ */
+export declare function createContainer(graphqlClient: GraphQLClient, cache: CacheService, config: Config): ServiceContainer;
+/**
+ * Create test container with mock implementations
+ * Useful for unit testing without real dependencies
+ */
+export declare function createTestContainer(overrides?: Partial<ServiceContainer>): ServiceContainer;
+//# sourceMappingURL=container.d.ts.map

package/dist/core/container.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.d.ts","sourceRoot":"","sources":["../../src/core/container.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,+CAA+C;IAC/C,aAAa,EAAE,aAAa,CAAC;IAE7B,qCAAqC;IACrC,KAAK,EAAE,YAAY,CAAC;IAEpB,qCAAqC;IACrC,gBAAgB,EAAE,gBAAgB,CAAC;IAEnC,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,aAAa,EAC5B,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,MAAM,GACb,gBAAgB,CASlB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAsD3F"}