attio-mcp 0.1.1 → 1.0.0

package/dist/services/CachingService.js

@@ -0,0 +1,421 @@
+/**
+ * CachingService - Centralized caching utilities for universal handlers
+ *
+ * Extracted from shared-handlers.ts as part of Issue #489 Phase 2.
+ * Provides task caching, 404 response caching, and attribute discovery caching
+ * functionality with configurable TTLs and automatic cleanup.
+ */
+import { enhancedPerformanceTracker } from '../middleware/performance-enhanced.js';
+import { generateIdCacheKey } from '../utils/validation/id-validation.js';
+import { DEFAULT_TASKS_CACHE_TTL, DEFAULT_404_CACHE_TTL, DEFAULT_ATTRIBUTES_CACHE_TTL, MAX_CACHE_ENTRIES, } from '../constants/universal.constants.js';
+/**
+ * CachingService provides centralized caching functionality for universal handlers
+ */
+export class CachingService {
+    // Simple in-memory cache for tasks pagination performance optimization
+    static tasksCache = new Map();
+    // Attribute discovery cache for performance optimization
+    static attributesCache = new Map();
+    // 404 response cache to prevent repeated failed lookups
+    static notFoundCache = new Map();
+    // Cache statistics for monitoring
+    static stats = {
+        tasks: { hits: 0, misses: 0, entries: 0 },
+        attributes: { hits: 0, misses: 0, entries: 0 },
+        notFound: { hits: 0, misses: 0, entries: 0 },
+    };
+    /**
+     * Get cached tasks with automatic TTL management
+     *
+     * @param cacheKey - Cache key for the tasks
+     * @param ttl - Time to live in milliseconds (default: 30 seconds)
+     * @returns Cached tasks if available and valid, undefined otherwise
+     */
+    static getCachedTasks(cacheKey, ttl = DEFAULT_TASKS_CACHE_TTL) {
+        const now = Date.now();
+        if (this.tasksCache.has(cacheKey)) {
+            const cached = this.tasksCache.get(cacheKey);
+            if (now - cached.timestamp < ttl) {
+                this.stats.tasks.hits++;
+                return cached.data;
+            }
+            // Remove expired cache entry
+            this.tasksCache.delete(cacheKey);
+            this.stats.tasks.entries--;
+        }
+        return undefined;
+    }
+    /**
+     * Cache tasks data with timestamp
+     *
+     * @param cacheKey - Cache key for the tasks
+     * @param data - Tasks data to cache
+     */
+    static setCachedTasks(cacheKey, data) {
+        const now = Date.now();
+        this.tasksCache.set(cacheKey, { data, timestamp: now });
+        this.stats.tasks.entries++;
+        this.performCacheCleanup();
+    }
+    /**
+     * Generate cache key for tasks list
+     *
+     * @returns Standard cache key for tasks list
+     */
+    static getTasksListCacheKey() {
+        return 'tasks_list_all';
+    }
+    /**
+     * Check if a 404 response is cached for a given resource
+     *
+     * @param resourceType - Type of resource (e.g., 'companies', 'people')
+     * @param recordId - ID of the record
+     * @returns True if 404 is cached, false otherwise
+     */
+    static isCached404(resourceType, recordId) {
+        const cacheKey = generateIdCacheKey(resourceType, recordId);
+        const cached404 = enhancedPerformanceTracker.getCached404(cacheKey);
+        return !!cached404;
+    }
+    /**
+     * Cache a 404 response for a resource
+     *
+     * @param resourceType - Type of resource (e.g., 'companies', 'people')
+     * @param recordId - ID of the record
+     * @param ttl - Time to live in milliseconds (default: 60 seconds)
+     */
+    static cache404Response(resourceType, recordId, ttl = DEFAULT_404_CACHE_TTL) {
+        const cacheKey = generateIdCacheKey(resourceType, recordId);
+        const now = Date.now();
+        this.notFoundCache.set(cacheKey, {
+            timestamp: now,
+            resourceType,
+            recordId,
+        });
+        this.stats.notFound.entries++;
+        enhancedPerformanceTracker.cache404Response(cacheKey, { error: 'Not found' }, ttl);
+        this.performCacheCleanup();
+    }
+    // ========================================
+    // Attribute Discovery Caching
+    // ========================================
+    /**
+     * Generate cache key for attribute discovery
+     *
+     * @param resourceType - The resource type
+     * @param objectSlug - Optional object slug for records
+     * @returns Cache key string
+     */
+    static getAttributeCacheKey(resourceType, objectSlug) {
+        return objectSlug
+            ? `attributes:${resourceType}:${objectSlug}`
+            : `attributes:${resourceType}`;
+    }
+    /**
+     * Get cached attribute discovery results
+     *
+     * @param resourceType - The resource type
+     * @param objectSlug - Optional object slug for records
+     * @param ttl - Time to live in milliseconds
+     * @returns Cached attributes if available and valid, undefined otherwise
+     */
+    static getCachedAttributes(resourceType, objectSlug, ttl = DEFAULT_ATTRIBUTES_CACHE_TTL) {
+        const cacheKey = this.getAttributeCacheKey(resourceType, objectSlug);
+        const now = Date.now();
+        if (this.attributesCache.has(cacheKey)) {
+            const cached = this.attributesCache.get(cacheKey);
+            if (now - cached.timestamp < ttl) {
+                this.stats.attributes.hits++;
+                return cached.data;
+            }
+            // Remove expired cache entry
+            this.attributesCache.delete(cacheKey);
+            this.stats.attributes.entries--;
+        }
+        this.stats.attributes.misses++;
+        return undefined;
+    }
+    /**
+     * Cache attribute discovery results
+     *
+     * @param resourceType - The resource type
+     * @param data - Attribute discovery results to cache
+     * @param objectSlug - Optional object slug for records
+     */
+    static setCachedAttributes(resourceType, data, objectSlug) {
+        const cacheKey = this.getAttributeCacheKey(resourceType, objectSlug);
+        const now = Date.now();
+        this.attributesCache.set(cacheKey, {
+            data,
+            timestamp: now,
+            resourceType,
+            objectSlug,
+        });
+        this.stats.attributes.entries++;
+        this.performCacheCleanup();
+    }
+    /**
+     * Invalidate attribute cache for a specific resource type
+     *
+     * @param resourceType - The resource type to invalidate
+     * @param objectSlug - Optional object slug to invalidate specific records cache
+     */
+    static invalidateAttributeCache(resourceType, objectSlug) {
+        if (objectSlug) {
+            const cacheKey = this.getAttributeCacheKey(resourceType, objectSlug);
+            if (this.attributesCache.delete(cacheKey)) {
+                this.stats.attributes.entries--;
+            }
+        }
+        else {
+            // Invalidate all cache entries for this resource type
+            const keysToDelete = [];
+            for (const [key, entry] of Array.from(this.attributesCache.entries())) {
+                if (entry.resourceType === resourceType) {
+                    keysToDelete.push(key);
+                }
+            }
+            for (const key of keysToDelete) {
+                this.attributesCache.delete(key);
+                this.stats.attributes.entries--;
+            }
+        }
+    }
+    /**
+     * Manage attribute caching with automatic data loading
+     *
+     * @param dataLoader - Function to load attribute data when cache miss occurs
+     * @param resourceType - The resource type
+     * @param objectSlug - Optional object slug for records
+     * @param ttl - Time to live in milliseconds
+     * @returns Cached or freshly loaded attribute data
+     */
+    static async getOrLoadAttributes(dataLoader, resourceType, objectSlug, ttl = DEFAULT_ATTRIBUTES_CACHE_TTL) {
+        // Check cache first
+        const cachedAttributes = this.getCachedAttributes(resourceType, objectSlug, ttl);
+        if (cachedAttributes) {
+            return { data: cachedAttributes, fromCache: true };
+        }
+        // Load fresh data
+        const freshData = await dataLoader();
+        // Cache the fresh data
+        this.setCachedAttributes(resourceType, freshData, objectSlug);
+        return { data: freshData, fromCache: false };
+    }
+    // ========================================
+    // Cache Management & Cleanup
+    // ========================================
+    /**
+     * Clear all tasks cache entries
+     */
+    static clearTasksCache() {
+        this.tasksCache.clear();
+        this.stats.tasks.entries = 0;
+    }
+    /**
+     * Clear all attributes cache entries
+     */
+    static clearAttributesCache() {
+        this.attributesCache.clear();
+        this.stats.attributes.entries = 0;
+    }
+    /**
+     * Clear all 404 cache entries
+     */
+    static clearNotFoundCache() {
+        this.notFoundCache.clear();
+        this.stats.notFound.entries = 0;
+    }
+    /**
+     * Clear all cache entries
+     */
+    static clearAllCache() {
+        this.clearTasksCache();
+        this.clearAttributesCache();
+        this.clearNotFoundCache();
+        // Reset stats
+        this.stats = {
+            tasks: { hits: 0, misses: 0, entries: 0 },
+            attributes: { hits: 0, misses: 0, entries: 0 },
+            notFound: { hits: 0, misses: 0, entries: 0 },
+        };
+    }
+    /**
+     * Clear expired cache entries for all cache types
+     */
+    static clearExpiredCache() {
+        this.clearExpiredTasksCache();
+        this.clearExpiredAttributesCache();
+        this.clearExpiredNotFoundCache();
+    }
+    /**
+     * Clear expired tasks cache entries
+     *
+     * @param ttl - Time to live in milliseconds
+     */
+    static clearExpiredTasksCache(ttl = DEFAULT_TASKS_CACHE_TTL) {
+        const now = Date.now();
+        let deletedCount = 0;
+        for (const [key, entry] of Array.from(this.tasksCache.entries())) {
+            if (now - entry.timestamp >= ttl) {
+                this.tasksCache.delete(key);
+                deletedCount++;
+            }
+        }
+        this.stats.tasks.entries -= deletedCount;
+    }
+    /**
+     * Clear expired attributes cache entries
+     *
+     * @param ttl - Time to live in milliseconds
+     */
+    static clearExpiredAttributesCache(ttl = DEFAULT_ATTRIBUTES_CACHE_TTL) {
+        const now = Date.now();
+        let deletedCount = 0;
+        for (const [key, entry] of Array.from(this.attributesCache.entries())) {
+            if (now - entry.timestamp >= ttl) {
+                this.attributesCache.delete(key);
+                deletedCount++;
+            }
+        }
+        this.stats.attributes.entries -= deletedCount;
+    }
+    /**
+     * Clear expired 404 cache entries
+     *
+     * @param ttl - Time to live in milliseconds
+     */
+    static clearExpiredNotFoundCache(ttl = DEFAULT_404_CACHE_TTL) {
+        const now = Date.now();
+        let deletedCount = 0;
+        for (const [key, entry] of Array.from(this.notFoundCache.entries())) {
+            if (now - entry.timestamp >= ttl) {
+                this.notFoundCache.delete(key);
+                deletedCount++;
+            }
+        }
+        this.stats.notFound.entries -= deletedCount;
+    }
+    /**
+     * Perform automatic cache cleanup when cache size exceeds limits
+     */
+    static performCacheCleanup() {
+        const totalEntries = this.tasksCache.size +
+            this.attributesCache.size +
+            this.notFoundCache.size;
+        if (totalEntries > MAX_CACHE_ENTRIES) {
+            // Clear expired entries first
+            this.clearExpiredCache();
+            // If still too large, clear oldest entries
+            const remainingEntries = this.tasksCache.size +
+                this.attributesCache.size +
+                this.notFoundCache.size;
+            if (remainingEntries > MAX_CACHE_ENTRIES) {
+                this.clearOldestEntries();
+            }
+        }
+    }
+    /**
+     * Clear oldest cache entries to maintain cache size limits
+     */
+    static clearOldestEntries() {
+        // Collect all entries with timestamps
+        const allEntries = [];
+        // Collect tasks entries
+        for (const [key, entry] of Array.from(this.tasksCache.entries())) {
+            allEntries.push({ key, timestamp: entry.timestamp, type: 'tasks' });
+        }
+        // Collect attributes entries
+        for (const [key, entry] of Array.from(this.attributesCache.entries())) {
+            allEntries.push({ key, timestamp: entry.timestamp, type: 'attributes' });
+        }
+        // Collect 404 entries
+        for (const [key, entry] of Array.from(this.notFoundCache.entries())) {
+            allEntries.push({ key, timestamp: entry.timestamp, type: 'notFound' });
+        }
+        // Sort by timestamp (oldest first)
+        allEntries.sort((a, b) => a.timestamp - b.timestamp);
+        // Remove oldest entries until under limit
+        const entriesToRemove = allEntries.length - Math.floor(MAX_CACHE_ENTRIES * 0.8); // Keep 80% of max
+        for (let i = 0; i < entriesToRemove && i < allEntries.length; i++) {
+            const entry = allEntries[i];
+            switch (entry.type) {
+                case 'tasks':
+                    this.tasksCache.delete(entry.key);
+                    this.stats.tasks.entries--;
+                    break;
+                case 'attributes':
+                    this.attributesCache.delete(entry.key);
+                    this.stats.attributes.entries--;
+                    break;
+                case 'notFound':
+                    this.notFoundCache.delete(entry.key);
+                    this.stats.notFound.entries--;
+                    break;
+            }
+        }
+    }
+    /**
+     * Get comprehensive cache statistics for monitoring
+     *
+     * @returns Detailed cache statistics
+     */
+    static getCacheStats() {
+        const totalHits = this.stats.tasks.hits +
+            this.stats.attributes.hits +
+            this.stats.notFound.hits;
+        const totalRequests = totalHits +
+            this.stats.tasks.misses +
+            this.stats.attributes.misses +
+            this.stats.notFound.misses;
+        return {
+            ...this.stats,
+            totalEntries: this.tasksCache.size +
+                this.attributesCache.size +
+                this.notFoundCache.size,
+            tasksCacheSize: this.tasksCache.size,
+            tasksCacheEntries: Array.from(this.tasksCache.keys()),
+            cacheEfficiency: {
+                tasks: this.stats.tasks.hits + this.stats.tasks.misses > 0
+                    ? this.stats.tasks.hits /
+                        (this.stats.tasks.hits + this.stats.tasks.misses)
+                    : 0,
+                attributes: this.stats.attributes.hits + this.stats.attributes.misses > 0
+                    ? this.stats.attributes.hits /
+                        (this.stats.attributes.hits + this.stats.attributes.misses)
+                    : 0,
+                notFound: this.stats.notFound.hits + this.stats.notFound.misses > 0
+                    ? this.stats.notFound.hits /
+                        (this.stats.notFound.hits + this.stats.notFound.misses)
+                    : 0,
+                overall: totalRequests > 0 ? totalHits / totalRequests : 0,
+            },
+        };
+    }
+    /**
+     * Manage task caching with automatic data loading
+     *
+     * This method encapsulates the common pattern of:
+     * 1. Check cache for valid data
+     * 2. Load data if cache miss
+     * 3. Cache the loaded data
+     *
+     * @param dataLoader - Function to load data when cache miss occurs
+     * @param cacheKey - Cache key (default: standard tasks list key)
+     * @param ttl - Time to live in milliseconds
+     * @returns Cached or freshly loaded data
+     */
+    static async getOrLoadTasks(dataLoader, cacheKey = this.getTasksListCacheKey(), ttl = DEFAULT_TASKS_CACHE_TTL) {
+        // Check cache first
+        const cachedTasks = this.getCachedTasks(cacheKey, ttl);
+        if (cachedTasks) {
+            return { data: cachedTasks, fromCache: true };
+        }
+        // Load fresh data
+        const freshData = await dataLoader();
+        // Cache the fresh data
+        this.setCachedTasks(cacheKey, freshData);
+        return { data: freshData, fromCache: false };
+    }
+}
+//# sourceMappingURL=CachingService.js.map

package/dist/services/CachingService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CachingService.js","sourceRoot":"","sources":["../../src/services/CachingService.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,0BAA0B,EAAE,MAAM,uCAAuC,CAAC;AACnF,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAE1E,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,4BAA4B,EAC5B,iBAAiB,GAClB,MAAM,qCAAqC,CAAC;AAkD7C;;GAEG;AACH,MAAM,OAAO,cAAc;IACzB,uEAAuE;IAC/D,MAAM,CAAC,UAAU,GAAG,IAAI,GAAG,EAAsB,CAAC;IAE1D,yDAAyD;IACjD,MAAM,CAAC,eAAe,GAAG,IAAI,GAAG,EAA+B,CAAC;IAExE,wDAAwD;IAChD,MAAM,CAAC,aAAa,GAAG,IAAI,GAAG,EAA8B,CAAC;IAErE,kCAAkC;IAC1B,MAAM,CAAC,KAAK,GAAe;QACjC,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;QACzC,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;QAC9C,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;KAC7C,CAAC;IAEF;;;;;;OAMG;IACH,MAAM,CAAC,cAAc,CACnB,QAAgB,EAChB,MAAc,uBAAuB;QAErC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClC,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAE,CAAC;YAC9C,IAAI,GAAG,GAAG,MAAM,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC;gBACjC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;gBACxB,OAAO,MAAM,CAAC,IAAI,CAAC;YACrB,CAAC;YACD,6BAA6B;YAC7B,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACjC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QAC7B,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,QAAgB,EAAE,IAAmB;QACzD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC,mBAAmB,EAAE,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,oBAAoB;QACzB,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,WAAW,CAAC,YAAoB,EAAE,QAAgB;QACvD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QAC5D,MAAM,SAAS,GAAG,0BAA0B,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QACpE,OAAO,CAAC,CAAC,SAAS,CAAC;IACrB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,gBAAgB,CACrB,YAAoB,EACpB,QAAgB,EAChB,MAAc,qBAAqB;QAEnC,MAAM,QAAQ,GAAG,kBAAkB,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;QAC5D,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,EAAE;YAC/B,SAAS,EAAE,GAAG;YACd,YAAY;YACZ,QAAQ;SACT,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QAE9B,0BAA0B,CAAC,gBAAgB,CACzC,QAAQ,EACR,EAAE,KAAK,EAAE,WAAW,EAAE,EACtB,GAAG,CACJ,CAAC;QACF,IAAI,CAAC,mBAAmB,EAAE,CAAC;IAC7B,CAAC;IAED,2CAA2C;IAC3C,8BAA8B;IAC9B,2CAA2C;IAE3C;;;;;;OAMG;IACK,MAAM,CAAC,oBAAoB,CACjC,YAAmC,EACnC,UAAmB;QAEnB,OAAO,UAAU;YACf,CAAC,CAAC,cAAc,YAAY,IAAI,UAAU,EAAE;YAC5C,CAAC,CAAC,cAAc,YAAY,EAAE,CAAC;IACnC,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,mBAAmB,CACxB,YAAmC,EACnC,UAAmB,EACnB,MAAc,4BAA4B;QAE1C,MAAM,QAAQ,GAAG,IAAI,CAAC,oBAAoB,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QACrE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvC,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAE,CAAC;YACnD,IAAI,GAAG,GAAG,MAAM,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC;gBACjC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;gBAC7B,OAAO,MAAM,CAAC,IAAI,CAAC;YACrB,CAAC;YACD,6BAA6B;YAC7B,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACtC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;QAClC,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,mBAAmB,CACxB,YAAmC,EACnC,IAA6B,EAC7B,UAAmB;QAEnB,MAAM,QAAQ,GAAG,IAAI,CAAC,oBAAoB,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;QACrE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,QAAQ,EAAE;YACjC,IAAI;YACJ,SAAS,EAAE,GAAG;YACd,YAAY;YACZ,UAAU;SACX,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;QAChC,IAAI,CAAC,mBAAmB,EAAE,CAAC;IAC7B,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,wBAAwB,CAC7B,YAAmC,EACnC,UAAmB;QAEnB,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,QAAQ,GAAG,IAAI,CAAC,oBAAoB,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;YACrE,IAAI,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC1C,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;YAClC,CAAC;QACH,CAAC;aAAM,CAAC;YACN,sDAAsD;YACtD,MAAM,YAAY,GAAa,EAAE,CAAC;YAClC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;gBACtE,IAAI,KAAK,CAAC,YAAY,KAAK,YAAY,EAAE,CAAC;oBACxC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACzB,CAAC;YACH,CAAC;YACD,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;gBAC/B,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;YAClC,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAC9B,UAAkD,EAClD,YAAmC,EACnC,UAAmB,EACnB,MAAc,4BAA4B;QAE1C,oBAAoB;QACpB,MAAM,gBAAgB,GAAG,IAAI,CAAC,mBAAmB,CAC/C,YAAY,EACZ,UAAU,EACV,GAAG,CACJ,CAAC;QACF,IAAI,gBAAgB,EAAE,CAAC;YACrB,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QACrD,CAAC;QAED,kBAAkB;QAClB,MAAM,SAAS,GAAG,MAAM,UAAU,EAAE,CAAC;QAErC,uBAAuB;QACvB,IAAI,CAAC,mBAAmB,CAAC,YAAY,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;QAE9D,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC/C,CAAC;IAED,2CAA2C;IAC3C,6BAA6B;IAC7B,2CAA2C;IAE3C;;OAEG;IACH,MAAM,CAAC,eAAe;QACpB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,oBAAoB;QACzB,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QAC7B,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,GAAG,CAAC,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,kBAAkB;QACvB,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC;QAC3B,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,GAAG,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,aAAa;QAClB,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC5B,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAE1B,cAAc;QACd,IAAI,CAAC,KAAK,GAAG;YACX,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;YACzC,UAAU,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;YAC9C,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE;SAC7C,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,iBAAiB;QACtB,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAC9B,IAAI,CAAC,2BAA2B,EAAE,CAAC;QACnC,IAAI,CAAC,yBAAyB,EAAE,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,sBAAsB,CAAC,MAAc,uBAAuB;QACjE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,YAAY,GAAG,CAAC,CAAC;QAErB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;YACjE,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE,CAAC;gBACjC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC5B,YAAY,EAAE,CAAC;YACjB,CAAC;QACH,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,IAAI,YAAY,CAAC;IAC3C,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,2BAA2B,CAChC,MAAc,4BAA4B;QAE1C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,YAAY,GAAG,CAAC,CAAC;QAErB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;YACtE,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE,CAAC;gBACjC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjC,YAAY,EAAE,CAAC;YACjB,CAAC;QACH,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,IAAI,YAAY,CAAC;IAChD,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,yBAAyB,CAAC,MAAc,qBAAqB;QAClE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,YAAY,GAAG,CAAC,CAAC;QAErB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;YACpE,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,IAAI,GAAG,EAAE,CAAC;gBACjC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC/B,YAAY,EAAE,CAAC;YACjB,CAAC;QACH,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,IAAI,YAAY,CAAC;IAC9C,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,mBAAmB;QAChC,MAAM,YAAY,GAChB,IAAI,CAAC,UAAU,CAAC,IAAI;YACpB,IAAI,CAAC,eAAe,CAAC,IAAI;YACzB,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;QAE1B,IAAI,YAAY,GAAG,iBAAiB,EAAE,CAAC;YACrC,8BAA8B;YAC9B,IAAI,CAAC,iBAAiB,EAAE,CAAC;YAEzB,2CAA2C;YAC3C,MAAM,gBAAgB,GACpB,IAAI,CAAC,UAAU,CAAC,IAAI;gBACpB,IAAI,CAAC,eAAe,CAAC,IAAI;gBACzB,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;YAC1B,IAAI,gBAAgB,GAAG,iBAAiB,EAAE,CAAC;gBACzC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACK,MAAM,CAAC,kBAAkB;QAC/B,sCAAsC;QACtC,MAAM,UAAU,GAIX,EAAE,CAAC;QAER,wBAAwB;QACxB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;YACjE,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACtE,CAAC;QAED,6BAA6B;QAC7B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;YACtE,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;QAC3E,CAAC;QAED,sBAAsB;QACtB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;YACpE,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;QACzE,CAAC;QAED,mCAAmC;QACnC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;QAErD,0CAA0C;QAC1C,MAAM,eAAe,GACnB,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAiB,GAAG,GAAG,CAAC,CAAC,CAAC,kBAAkB;QAE7E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,eAAe,IAAI,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAClE,MAAM,KAAK,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;YAE5B,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;gBACnB,KAAK,OAAO;oBACV,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;oBAClC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;oBAC3B,MAAM;gBACR,KAAK,YAAY;oBACf,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;oBACvC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;oBAChC,MAAM;gBACR,KAAK,UAAU;oBACb,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;oBACrC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;oBAC9B,MAAM;YACV,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,aAAa;QAWlB,MAAM,SAAS,GACb,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI;YACrB,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI;YAC1B,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAC3B,MAAM,aAAa,GACjB,SAAS;YACT,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM;YACvB,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM;YAC5B,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;QAE7B,OAAO;YACL,GAAG,IAAI,CAAC,KAAK;YACb,YAAY,EACV,IAAI,CAAC,UAAU,CAAC,IAAI;gBACpB,IAAI,CAAC,eAAe,CAAC,IAAI;gBACzB,IAAI,CAAC,aAAa,CAAC,IAAI;YACzB,cAAc,EAAE,IAAI,CAAC,UAAU,CAAC,IAAI;YACpC,iBAAiB,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;YACrD,eAAe,EAAE;gBACf,KAAK,EACH,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;oBACjD,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI;wBACrB,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC;oBACnD,CAAC,CAAC,CAAC;gBACP,UAAU,EACR,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;oBAC3D,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI;wBAC1B,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC;oBAC7D,CAAC,CAAC,CAAC;gBACP,QAAQ,EACN,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;oBACvD,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI;wBACxB,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC;oBACzD,CAAC,CAAC,CAAC;gBACP,OAAO,EAAE,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;aAC3D;SACF,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,KAAK,CAAC,cAAc,CACzB,UAAwC,EACxC,WAAmB,IAAI,CAAC,oBAAoB,EAAE,EAC9C,MAAc,uBAAuB;QAErC,oBAAoB;QACpB,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;QACvD,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAChD,CAAC;QAED,kBAAkB;QAClB,MAAM,SAAS,GAAG,MAAM,UAAU,EAAE,CAAC;QAErC,uBAAuB;QACvB,IAAI,CAAC,cAAc,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAEzC,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC/C,CAAC"}

package/dist/services/ErrorService.d.ts

@@ -0,0 +1,63 @@
+/**
+ * ErrorService - Centralized error handling and suggestion utilities
+ *
+ * Extracted from shared-handlers.ts as part of Issue #489 Phase 3.
+ * Provides universal error creation and contextual suggestions for better user experience.
+ */
+import type { AxiosErrorLike } from '../types/service-types.js';
+/**
+ * ErrorService provides centralized error handling and suggestion functionality
+ */
+export declare class ErrorService {
+    /**
+     * Enhanced error handling utility for universal operations
+     *
+     * @param operation - The operation being performed (e.g., 'create', 'update', 'search')
+     * @param resourceType - Type of resource (e.g., 'companies', 'people', 'tasks')
+     * @param originalError - The original error that occurred
+     * @returns Enhanced error with contextual suggestions
+     */
+    static createUniversalError(operation: string, resourceType: string, originalError: unknown): Error;
+    /**
+     * Get helpful suggestions based on the operation and error
+     *
+     * @param operation - The operation being performed
+     * @param resourceType - Type of resource
+     * @param error - The error that occurred
+     * @returns Contextual suggestion string or undefined
+     */
+    static getOperationSuggestion(operation: string, resourceType: string, error: unknown): string | undefined;
+    /**
+     * Get deal-specific error suggestions
+     *
+     * @param errorMessage - Lowercase error message
+     * @returns Deal-specific suggestion or undefined
+     */
+    private static getDealSpecificSuggestion;
+    /**
+     * Map Axios/HTTP errors to appropriate Universal errors
+     *
+     * @param error - Axios error object
+     * @returns Universal error object with proper classification
+     */
+    static fromAxios(error: AxiosErrorLike): {
+        code: number;
+        type: 'not_found' | 'validation_error' | 'unauthorized' | 'forbidden' | 'conflict' | 'rate_limit' | 'server_error';
+        name: string;
+        message: string;
+        details?: {
+            validation_errors?: Array<{
+                field?: string;
+                path?: string;
+                code?: string;
+                message: string;
+            }>;
+        };
+        suggestion?: string;
+        attio?: {
+            status_code?: number;
+            correlation_id?: string;
+        };
+    };
+}
+//# sourceMappingURL=ErrorService.d.ts.map

package/dist/services/ErrorService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorService.d.ts","sourceRoot":"","sources":["../../src/services/ErrorService.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,OAAO,KAAK,EACV,cAAc,EAEf,MAAM,2BAA2B,CAAC;AAEnC;;GAEG;AACH,qBAAa,YAAY;IACvB;;;;;;;OAOG;IACH,MAAM,CAAC,oBAAoB,CACzB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,OAAO,GACrB,KAAK;IA8DR;;;;;;;OAOG;IACH,MAAM,CAAC,sBAAsB,CAC3B,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,OAAO,GACb,MAAM,GAAG,SAAS;IA0IrB;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,yBAAyB;IAgGxC;;;;;OAKG;IACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG;QACvC,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EACA,WAAW,GACX,kBAAkB,GAClB,cAAc,GACd,WAAW,GACX,UAAU,GACV,YAAY,GACZ,cAAc,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE;YACR,iBAAiB,CAAC,EAAE,KAAK,CAAC;gBACxB,KAAK,CAAC,EAAE,MAAM,CAAC;gBACf,IAAI,CAAC,EAAE,MAAM,CAAC;gBACd,IAAI,CAAC,EAAE,MAAM,CAAC;gBACd,OAAO,EAAE,MAAM,CAAC;aACjB,CAAC,CAAC;SACJ,CAAC;QACF,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE;YACN,WAAW,CAAC,EAAE,MAAM,CAAC;YACrB,cAAc,CAAC,EAAE,MAAM,CAAC;SACzB,CAAC;KACH;CAmMF"}