@gotza02/sequential-thinking 2026.2.40 → 2026.2.41

package/dist/tools/sports/core/base.d.ts

@@ -0,0 +1,169 @@
+/**
+ * SPORTS MODULE BASE CLASSES
+ * Abstract base classes and interfaces for data providers
+ */
+import { Match, Team, Player, TableEntry, APIResponse, ProviderStatus, ProviderType } from './types.js';
+import { CacheService } from './cache.js';
+/**
+ * Base interface for all data providers
+ */
+export interface IDataProvider {
+    /**
+     * Provider name/type
+     */
+    readonly type: ProviderType;
+    /**
+     * Check if provider is available
+     */
+    isAvailable(): boolean;
+    /**
+     * Get provider status
+     */
+    getStatus(): ProviderStatus;
+    /**
+     * Fetch a match by ID
+     */
+    getMatch(matchId: string): Promise<APIResponse<Match>>;
+    /**
+     * Fetch live matches for a league
+     */
+    getLiveMatches(leagueId?: string): Promise<APIResponse<Match[]>>;
+    /**
+     * Fetch league standings
+     */
+    getStandings(leagueId: string, season?: string): Promise<APIResponse<TableEntry[]>>;
+    /**
+     * Fetch team information
+     */
+    getTeam(teamId: string): Promise<APIResponse<Team>>;
+    /**
+     * Fetch player information
+     */
+    getPlayer(playerId: string): Promise<APIResponse<Player>>;
+    /**
+     * Search for teams
+     */
+    searchTeams(query: string): Promise<APIResponse<Team[]>>;
+    /**
+     * Search for players
+     */
+    searchPlayers(query: string): Promise<APIResponse<Player[]>>;
+}
+/**
+ * Abstract base class for API-based providers
+ */
+export declare abstract class APIProviderBase implements IDataProvider {
+    readonly type: ProviderType;
+    protected apiKey: string;
+    protected baseUrl: string;
+    protected rateLimit: number;
+    protected cache: CacheService;
+    protected rateLimitUntil: Date | null;
+    protected lastCall: Date | null;
+    protected callCount: number;
+    constructor(type: ProviderType, apiKey: string, baseUrl: string, rateLimit?: number);
+    /**
+     * Check if provider has valid credentials
+     */
+    isAvailable(): boolean;
+    /**
+     * Check if currently rate limited
+     */
+    isRateLimited(): boolean;
+    /**
+     * Get current provider status
+     */
+    getStatus(): ProviderStatus;
+    /**
+     * Abstract methods to be implemented by concrete providers
+     */
+    abstract getMatch(matchId: string): Promise<APIResponse<Match>>;
+    abstract getLiveMatches(leagueId?: string): Promise<APIResponse<Match[]>>;
+    abstract getStandings(leagueId: string, season?: string): Promise<APIResponse<TableEntry[]>>;
+    abstract getTeam(teamId: string): Promise<APIResponse<Team>>;
+    abstract getPlayer(playerId: string): Promise<APIResponse<Player>>;
+    abstract searchTeams(query: string): Promise<APIResponse<Team[]>>;
+    abstract searchPlayers(query: string): Promise<APIResponse<Player[]>>;
+    /**
+     * Make a rate-limited API call
+     */
+    protected callAPI<T>(endpoint: string, options?: RequestInit): Promise<APIResponse<T>>;
+    /**
+     * Get authentication headers for the API
+     */
+    protected abstract getAuthHeaders(): Record<string, string>;
+    /**
+     * Transform raw API response to standard format
+     */
+    protected abstract transformResponse<T>(data: any): T;
+    /**
+     * Reset rate limit tracking (for testing)
+     */
+    resetRateLimit(): void;
+}
+/**
+ * Abstract base class for scraper-based providers
+ */
+export declare abstract class ScraperProviderBase implements IDataProvider {
+    protected cache: CacheService;
+    readonly type: ProviderType;
+    constructor();
+    isAvailable(): boolean;
+    getStatus(): ProviderStatus;
+    abstract getMatch(matchId: string): Promise<APIResponse<Match>>;
+    abstract getLiveMatches(leagueId?: string): Promise<APIResponse<Match[]>>;
+    abstract getStandings(leagueId: string, season?: string): Promise<APIResponse<TableEntry[]>>;
+    abstract getTeam(teamId: string): Promise<APIResponse<Team>>;
+    abstract getPlayer(playerId: string): Promise<APIResponse<Player>>;
+    abstract searchTeams(query: string): Promise<APIResponse<Team[]>>;
+    abstract searchPlayers(query: string): Promise<APIResponse<Player[]>>;
+    /**
+     * Scrape a webpage and extract structured data
+     */
+    protected scrape<T>(url: string, extractor: (html: string) => T): Promise<APIResponse<T>>;
+}
+/**
+ * Fallback provider that tries multiple sources in order
+ */
+export declare class FallbackProvider implements IDataProvider {
+    private providers;
+    private cache;
+    readonly type: ProviderType;
+    constructor(providers: IDataProvider[], cache?: CacheService);
+    isAvailable(): boolean;
+    getStatus(): ProviderStatus;
+    /**
+     * Try each provider in sequence until one succeeds
+     */
+    private tryProviders;
+    getMatch(matchId: string): Promise<APIResponse<Match>>;
+    getLiveMatches(leagueId?: string): Promise<APIResponse<Match[]>>;
+    getStandings(leagueId: string, season?: string): Promise<APIResponse<TableEntry[]>>;
+    getTeam(teamId: string): Promise<APIResponse<Team>>;
+    getPlayer(playerId: string): Promise<APIResponse<Player>>;
+    searchTeams(query: string): Promise<APIResponse<Team[]>>;
+    searchPlayers(query: string): Promise<APIResponse<Player[]>>;
+}
+/**
+ * Base class for sports tools
+ */
+export declare abstract class SportsToolBase {
+    protected cache: CacheService;
+    constructor(cache?: CacheService);
+    /**
+     * Format error message for user
+     */
+    protected formatError(error: unknown, context: string): string;
+    /**
+     * Sanitize user input
+     */
+    protected sanitizeInput(input: string): string;
+    /**
+     * Format a team name for search
+     */
+    protected formatTeamName(name: string): string;
+    /**
+     * Format date to readable string
+     */
+    protected formatDate(date: Date): string;
+}

package/dist/tools/sports/core/base.js

@@ -0,0 +1,289 @@
+/**
+ * SPORTS MODULE BASE CLASSES
+ * Abstract base classes and interfaces for data providers
+ */
+import { CacheService } from './cache.js';
+import { logger } from '../../../utils.js';
+/**
+ * Abstract base class for API-based providers
+ */
+export class APIProviderBase {
+    type;
+    apiKey;
+    baseUrl;
+    rateLimit;
+    cache;
+    rateLimitUntil = null;
+    lastCall = null;
+    callCount = 0;
+    constructor(type, apiKey, baseUrl, rateLimit = 10 // calls per minute
+    ) {
+        this.type = type;
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl;
+        this.rateLimit = rateLimit;
+        this.cache = new CacheService();
+    }
+    /**
+     * Check if provider has valid credentials
+     */
+    isAvailable() {
+        return !!this.apiKey && !this.isRateLimited();
+    }
+    /**
+     * Check if currently rate limited
+     */
+    isRateLimited() {
+        if (!this.rateLimitUntil)
+            return false;
+        return new Date() < this.rateLimitUntil;
+    }
+    /**
+     * Get current provider status
+     */
+    getStatus() {
+        return {
+            name: this.type,
+            available: this.isAvailable(),
+            quotaRemaining: Math.max(0, this.rateLimit - this.callCount),
+            quotaLimit: this.rateLimit,
+            rateLimitUntil: this.rateLimitUntil || undefined,
+            lastCall: this.lastCall || undefined,
+        };
+    }
+    /**
+     * Make a rate-limited API call
+     */
+    async callAPI(endpoint, options = {}) {
+        // Check rate limit
+        if (this.isRateLimited()) {
+            return {
+                success: false,
+                error: `Rate limited until ${this.rateLimitUntil}`,
+                rateLimited: true,
+            };
+        }
+        // Check availability
+        if (!this.isAvailable()) {
+            return {
+                success: false,
+                error: 'Provider not available (missing API key)',
+            };
+        }
+        try {
+            const url = `${this.baseUrl}${endpoint}`;
+            const response = await fetch(url, {
+                ...options,
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...this.getAuthHeaders(),
+                    ...options.headers,
+                },
+            });
+            this.lastCall = new Date();
+            this.callCount++;
+            if (!response.ok) {
+                // Handle rate limiting
+                if (response.status === 429) {
+                    const retryAfter = response.headers.get('Retry-After');
+                    this.rateLimitUntil = new Date(Date.now() + (retryAfter ? parseInt(retryAfter) * 1000 : 60000));
+                    return {
+                        success: false,
+                        error: 'Rate limited',
+                        rateLimited: true,
+                    };
+                }
+                return {
+                    success: false,
+                    error: `HTTP ${response.status}: ${response.statusText}`,
+                };
+            }
+            const data = await response.json();
+            return {
+                success: true,
+                data: this.transformResponse(data),
+                provider: this.type,
+            };
+        }
+        catch (error) {
+            logger.error(`${this.type} API error: ${error}`);
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Reset rate limit tracking (for testing)
+     */
+    resetRateLimit() {
+        this.rateLimitUntil = null;
+        this.callCount = 0;
+    }
+}
+/**
+ * Abstract base class for scraper-based providers
+ */
+export class ScraperProviderBase {
+    cache;
+    type = 'scraper';
+    constructor() {
+        this.cache = new CacheService();
+    }
+    isAvailable() {
+        return true; // Scraping is always "available"
+    }
+    getStatus() {
+        return {
+            name: this.type,
+            available: true,
+            quotaRemaining: Infinity,
+            quotaLimit: Infinity,
+        };
+    }
+    /**
+     * Scrape a webpage and extract structured data
+     */
+    async scrape(url, extractor) {
+        try {
+            const { fetchWithRetry } = await import('../../../utils.js');
+            const response = await fetchWithRetry(url);
+            const html = await response.text();
+            const data = extractor(html);
+            return {
+                success: true,
+                data,
+                provider: 'scraper',
+            };
+        }
+        catch (error) {
+            logger.error(`Scraping error for ${url}: ${error}`);
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+}
+/**
+ * Fallback provider that tries multiple sources in order
+ */
+export class FallbackProvider {
+    providers;
+    cache;
+    type = 'scraper';
+    constructor(providers, cache = new CacheService()) {
+        this.providers = providers;
+        this.cache = cache;
+    }
+    isAvailable() {
+        return this.providers.some(p => p.isAvailable());
+    }
+    getStatus() {
+        const available = this.providers.filter(p => p.isAvailable());
+        return {
+            name: this.type,
+            available: available.length > 0,
+            quotaRemaining: available.length,
+            quotaLimit: this.providers.length,
+        };
+    }
+    /**
+     * Try each provider in sequence until one succeeds
+     */
+    async tryProviders(fn) {
+        const errors = [];
+        for (const provider of this.providers) {
+            if (!provider.isAvailable()) {
+                continue;
+            }
+            const result = await fn(provider);
+            if (result.success) {
+                return result;
+            }
+            errors.push(`${provider.type}: ${result.error || 'Unknown error'}`);
+        }
+        return {
+            success: false,
+            error: `All providers failed:\n${errors.join('\n')}`,
+        };
+    }
+    async getMatch(matchId) {
+        const cacheKey = CacheService.generateKey('match', matchId);
+        return this.cache.getOrSet(cacheKey, () => this.tryProviders(p => p.getMatch(matchId)), 5 * 60 * 1000 // 5 minutes
+        );
+    }
+    async getLiveMatches(leagueId) {
+        const cacheKey = CacheService.generateKey('live', leagueId || 'all');
+        return this.cache.getOrSet(cacheKey, () => this.tryProviders(p => p.getLiveMatches(leagueId)), 60 * 1000 // 1 minute
+        );
+    }
+    async getStandings(leagueId, season) {
+        const cacheKey = CacheService.generateKey('standings', leagueId, season || 'current');
+        return this.cache.getOrSet(cacheKey, () => this.tryProviders(p => p.getStandings(leagueId, season)), 30 * 60 * 1000 // 30 minutes
+        );
+    }
+    async getTeam(teamId) {
+        const cacheKey = CacheService.generateKey('team', teamId);
+        return this.cache.getOrSet(cacheKey, () => this.tryProviders(p => p.getTeam(teamId)), 60 * 60 * 1000 // 1 hour
+        );
+    }
+    async getPlayer(playerId) {
+        const cacheKey = CacheService.generateKey('player', playerId);
+        return this.cache.getOrSet(cacheKey, () => this.tryProviders(p => p.getPlayer(playerId)), 60 * 60 * 1000 // 1 hour
+        );
+    }
+    async searchTeams(query) {
+        const cacheKey = CacheService.generateKey('search', 'team', query);
+        return this.cache.getOrSet(cacheKey, () => this.tryProviders(p => p.searchTeams(query)), 60 * 60 * 1000 // 1 hour
+        );
+    }
+    async searchPlayers(query) {
+        const cacheKey = CacheService.generateKey('search', 'player', query);
+        return this.cache.getOrSet(cacheKey, () => this.tryProviders(p => p.searchPlayers(query)), 60 * 60 * 1000 // 1 hour
+        );
+    }
+}
+/**
+ * Base class for sports tools
+ */
+export class SportsToolBase {
+    cache;
+    constructor(cache) {
+        this.cache = cache || new CacheService();
+    }
+    /**
+     * Format error message for user
+     */
+    formatError(error, context) {
+        if (error instanceof Error) {
+            return `Error in ${context}: ${error.message}`;
+        }
+        return `Unknown error in ${context}`;
+    }
+    /**
+     * Sanitize user input
+     */
+    sanitizeInput(input) {
+        return input.trim().replace(/[<>]/g, '');
+    }
+    /**
+     * Format a team name for search
+     */
+    formatTeamName(name) {
+        return this.sanitizeInput(name).toLowerCase();
+    }
+    /**
+     * Format date to readable string
+     */
+    formatDate(date) {
+        return date.toLocaleDateString('en-US', {
+            weekday: 'short',
+            year: 'numeric',
+            month: 'short',
+            day: 'numeric',
+            hour: '2-digit',
+            minute: '2-digit',
+        });
+    }
+}

package/dist/tools/sports/core/cache.d.ts

@@ -0,0 +1,106 @@
+/**
+ * SPORTS MODULE CACHE SERVICE
+ * TTL-based caching with file persistence for the football intelligence system
+ */
+/**
+ * CacheService - Thread-safe TTL-based caching with persistence
+ */
+export declare class CacheService {
+    private cache;
+    private cachePath;
+    private maxAge;
+    private maxSize;
+    private savePending;
+    private saveTimer;
+    constructor(cachePath?: string, maxAge?: number, maxSize?: number);
+    /**
+     * Generate a cache key from components
+     */
+    static generateKey(...parts: (string | number)[]): string;
+    /**
+     * Get a value from cache
+     */
+    get<T>(key: string): T | null;
+    /**
+     * Set a value in cache
+     */
+    set<T>(key: string, data: T, ttl?: number): void;
+    /**
+     * Check if a key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a specific key
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+        hits: number;
+        entries: Array<{
+            key: string;
+            hits: number;
+            age: number;
+            ttl: number;
+        }>;
+    };
+    /**
+     * Clean up expired entries
+     */
+    cleanup(): number;
+    /**
+     * Evict the oldest entry (LRU)
+     */
+    private evictOldest;
+    /**
+     * Schedule a save operation (debounced)
+     */
+    private scheduleSave;
+    /**
+     * Save cache to file
+     */
+    private saveToFile;
+    /**
+     * Load cache from file
+     */
+    private loadFromFile;
+    /**
+     * Force save cache to file immediately
+     */
+    flush(): Promise<void>;
+    /**
+     * Get or set pattern - returns cached value or computes and caches it
+     */
+    getOrSet<T>(key: string, factory: () => T | Promise<T>, ttl?: number): Promise<T>;
+    /**
+     * Get multiple keys at once
+     */
+    getMultiple<T>(keys: string[]): Map<string, T>;
+    /**
+     * Set multiple keys at once
+     */
+    setMultiple<T>(entries: Map<string, T>, ttl?: number): void;
+    /**
+     * Invalidate cache by pattern
+     */
+    invalidatePattern(pattern: string): number;
+    /**
+     * Get cache size breakdown by key prefix
+     */
+    getBreakdown(): Record<string, number>;
+}
+/**
+ * Get or create the global cache instance
+ */
+export declare function getGlobalCache(): CacheService;
+/**
+ * Reset the global cache instance
+ */
+export declare function resetGlobalCache(): void;