@fin.cx/opendata 3.0.0 → 3.1.0

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@fin.cx/opendata',
-    version: '3.0.0',
+    version: '3.1.0',
     description: 'A comprehensive TypeScript library for accessing business data and real-time financial information. Features include German company data management with MongoDB integration, JSONL bulk processing, automated Handelsregister interactions, and real-time stock market data from multiple providers.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSxrQkFBa0I7SUFDeEIsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHVTQUF1UztDQUNyVCxDQUFBIn0=

package/dist_ts/stocks/classes.fundamentalsservice.d.ts

@@ -0,0 +1,104 @@
+import type { IFundamentalsProvider, IFundamentalsProviderConfig, IFundamentalsProviderRegistry, IStockFundamentals, IFundamentalsRequest } from './interfaces/fundamentals.js';
+/**
+ * Service for managing fundamental data providers and caching
+ * Parallel to StockPriceService but for fundamental data instead of prices
+ */
+export declare class FundamentalsService implements IFundamentalsProviderRegistry {
+    private providers;
+    private cache;
+    private logger;
+    private cacheConfig;
+    constructor(cacheConfig?: {
+        ttl?: number;
+        maxEntries?: number;
+    });
+    /**
+     * Register a fundamentals provider
+     */
+    register(provider: IFundamentalsProvider, config?: IFundamentalsProviderConfig): void;
+    /**
+     * Unregister a provider
+     */
+    unregister(providerName: string): void;
+    /**
+     * Get a specific provider by name
+     */
+    getProvider(name: string): IFundamentalsProvider | undefined;
+    /**
+     * Get all registered providers
+     */
+    getAllProviders(): IFundamentalsProvider[];
+    /**
+     * Get enabled providers sorted by priority
+     */
+    getEnabledProviders(): IFundamentalsProvider[];
+    /**
+     * Get fundamental data for a single ticker
+     */
+    getFundamentals(ticker: string): Promise<IStockFundamentals>;
+    /**
+     * Get fundamental data for multiple tickers
+     */
+    getBatchFundamentals(tickers: string[]): Promise<IStockFundamentals[]>;
+    /**
+     * Unified data fetching method
+     */
+    getData(request: IFundamentalsRequest): Promise<IStockFundamentals | IStockFundamentals[]>;
+    /**
+     * Enrich fundamentals with calculated metrics using current price
+     */
+    enrichWithPrice(fundamentals: IStockFundamentals, price: number): Promise<IStockFundamentals>;
+    /**
+     * Enrich batch fundamentals with prices
+     */
+    enrichBatchWithPrices(fundamentalsList: IStockFundamentals[], priceMap: Map<string, number>): Promise<IStockFundamentals[]>;
+    /**
+     * Check health of all providers
+     */
+    checkProvidersHealth(): Promise<Map<string, boolean>>;
+    /**
+     * Get provider statistics
+     */
+    getProviderStats(): Map<string, {
+        successCount: number;
+        errorCount: number;
+        lastError?: string;
+        lastErrorTime?: Date;
+    }>;
+    /**
+     * Clear all cached data
+     */
+    clearCache(): void;
+    /**
+     * Set cache TTL
+     */
+    setCacheTTL(ttl: number): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        maxEntries: number;
+        ttl: number;
+    };
+    /**
+     * Fetch with retry logic
+     */
+    private fetchWithRetry;
+    /**
+     * Generate cache key for request
+     */
+    private getCacheKey;
+    /**
+     * Get from cache if not expired
+     */
+    private getFromCache;
+    /**
+     * Add to cache with TTL
+     */
+    private addToCache;
+    /**
+     * Get human-readable request description
+     */
+    private getRequestDescription;
+}

package/dist_ts/stocks/classes.fundamentalsservice.js

@@ -0,0 +1,298 @@
+import * as plugins from '../plugins.js';
+/**
+ * Service for managing fundamental data providers and caching
+ * Parallel to StockPriceService but for fundamental data instead of prices
+ */
+export class FundamentalsService {
+    constructor(cacheConfig) {
+        this.providers = new Map();
+        this.cache = new Map();
+        this.logger = console;
+        this.cacheConfig = {
+            ttl: 90 * 24 * 60 * 60 * 1000, // 90 days default (fundamentals change quarterly)
+            maxEntries: 10000
+        };
+        if (cacheConfig) {
+            this.cacheConfig = { ...this.cacheConfig, ...cacheConfig };
+        }
+    }
+    /**
+     * Register a fundamentals provider
+     */
+    register(provider, config) {
+        const defaultConfig = {
+            enabled: true,
+            priority: provider.priority,
+            timeout: 30000, // Longer timeout for fundamental data
+            retryAttempts: 2,
+            retryDelay: 1000,
+            cacheTTL: this.cacheConfig.ttl
+        };
+        const mergedConfig = { ...defaultConfig, ...config };
+        this.providers.set(provider.name, {
+            provider,
+            config: mergedConfig,
+            successCount: 0,
+            errorCount: 0
+        });
+        console.log(`Registered fundamentals provider: ${provider.name}`);
+    }
+    /**
+     * Unregister a provider
+     */
+    unregister(providerName) {
+        this.providers.delete(providerName);
+        console.log(`Unregistered fundamentals provider: ${providerName}`);
+    }
+    /**
+     * Get a specific provider by name
+     */
+    getProvider(name) {
+        return this.providers.get(name)?.provider;
+    }
+    /**
+     * Get all registered providers
+     */
+    getAllProviders() {
+        return Array.from(this.providers.values()).map(entry => entry.provider);
+    }
+    /**
+     * Get enabled providers sorted by priority
+     */
+    getEnabledProviders() {
+        return Array.from(this.providers.values())
+            .filter(entry => entry.config.enabled)
+            .sort((a, b) => (b.config.priority || 0) - (a.config.priority || 0))
+            .map(entry => entry.provider);
+    }
+    /**
+     * Get fundamental data for a single ticker
+     */
+    async getFundamentals(ticker) {
+        const result = await this.getData({
+            type: 'fundamentals-current',
+            ticker
+        });
+        return result;
+    }
+    /**
+     * Get fundamental data for multiple tickers
+     */
+    async getBatchFundamentals(tickers) {
+        const result = await this.getData({
+            type: 'fundamentals-batch',
+            tickers
+        });
+        return result;
+    }
+    /**
+     * Unified data fetching method
+     */
+    async getData(request) {
+        const cacheKey = this.getCacheKey(request);
+        const cached = this.getFromCache(cacheKey);
+        if (cached) {
+            console.log(`Cache hit for ${this.getRequestDescription(request)}`);
+            return cached;
+        }
+        const providers = this.getEnabledProviders();
+        if (providers.length === 0) {
+            throw new Error('No fundamentals providers available');
+        }
+        let lastError;
+        for (const provider of providers) {
+            const entry = this.providers.get(provider.name);
+            try {
+                const result = await this.fetchWithRetry(() => provider.fetchData(request), entry.config);
+                entry.successCount++;
+                // Use provider-specific cache TTL or default
+                const ttl = entry.config.cacheTTL || this.cacheConfig.ttl;
+                this.addToCache(cacheKey, result, ttl);
+                console.log(`Successfully fetched ${this.getRequestDescription(request)} from ${provider.name}`);
+                return result;
+            }
+            catch (error) {
+                entry.errorCount++;
+                entry.lastError = error;
+                entry.lastErrorTime = new Date();
+                lastError = error;
+                console.warn(`Provider ${provider.name} failed for ${this.getRequestDescription(request)}: ${error.message}`);
+            }
+        }
+        throw new Error(`Failed to fetch ${this.getRequestDescription(request)} from all providers. Last error: ${lastError?.message}`);
+    }
+    /**
+     * Enrich fundamentals with calculated metrics using current price
+     */
+    async enrichWithPrice(fundamentals, price) {
+        const enriched = { ...fundamentals };
+        // Calculate market cap: price × shares outstanding
+        if (fundamentals.sharesOutstanding) {
+            enriched.marketCap = price * fundamentals.sharesOutstanding;
+        }
+        // Calculate P/E ratio: price / EPS
+        if (fundamentals.earningsPerShareDiluted && fundamentals.earningsPerShareDiluted > 0) {
+            enriched.priceToEarnings = price / fundamentals.earningsPerShareDiluted;
+        }
+        // Calculate price-to-book: market cap / stockholders equity
+        if (enriched.marketCap && fundamentals.stockholdersEquity && fundamentals.stockholdersEquity > 0) {
+            enriched.priceToBook = enriched.marketCap / fundamentals.stockholdersEquity;
+        }
+        return enriched;
+    }
+    /**
+     * Enrich batch fundamentals with prices
+     */
+    async enrichBatchWithPrices(fundamentalsList, priceMap) {
+        return Promise.all(fundamentalsList.map(fundamentals => {
+            const price = priceMap.get(fundamentals.ticker);
+            if (price) {
+                return this.enrichWithPrice(fundamentals, price);
+            }
+            return Promise.resolve(fundamentals);
+        }));
+    }
+    /**
+     * Check health of all providers
+     */
+    async checkProvidersHealth() {
+        const health = new Map();
+        for (const [name, entry] of this.providers) {
+            if (!entry.config.enabled) {
+                health.set(name, false);
+                continue;
+            }
+            try {
+                const isAvailable = await entry.provider.isAvailable();
+                health.set(name, isAvailable);
+            }
+            catch (error) {
+                health.set(name, false);
+                console.error(`Health check failed for ${name}:`, error);
+            }
+        }
+        return health;
+    }
+    /**
+     * Get provider statistics
+     */
+    getProviderStats() {
+        const stats = new Map();
+        for (const [name, entry] of this.providers) {
+            stats.set(name, {
+                successCount: entry.successCount,
+                errorCount: entry.errorCount,
+                lastError: entry.lastError?.message,
+                lastErrorTime: entry.lastErrorTime
+            });
+        }
+        return stats;
+    }
+    /**
+     * Clear all cached data
+     */
+    clearCache() {
+        this.cache.clear();
+        console.log('Fundamentals cache cleared');
+    }
+    /**
+     * Set cache TTL
+     */
+    setCacheTTL(ttl) {
+        this.cacheConfig.ttl = ttl;
+        console.log(`Fundamentals cache TTL set to ${ttl}ms`);
+    }
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        return {
+            size: this.cache.size,
+            maxEntries: this.cacheConfig.maxEntries,
+            ttl: this.cacheConfig.ttl
+        };
+    }
+    /**
+     * Fetch with retry logic
+     */
+    async fetchWithRetry(fetchFn, config) {
+        const maxAttempts = config.retryAttempts || 1;
+        let lastError;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                return await fetchFn();
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt < maxAttempts) {
+                    const delay = (config.retryDelay || 1000) * attempt;
+                    console.log(`Retry attempt ${attempt} after ${delay}ms`);
+                    await plugins.smartdelay.delayFor(delay);
+                }
+            }
+        }
+        throw lastError || new Error('Unknown error during fetch');
+    }
+    /**
+     * Generate cache key for request
+     */
+    getCacheKey(request) {
+        switch (request.type) {
+            case 'fundamentals-current':
+                return `fundamentals:${request.ticker}`;
+            case 'fundamentals-batch':
+                const tickers = request.tickers.sort().join(',');
+                return `fundamentals-batch:${tickers}`;
+            default:
+                return `unknown:${JSON.stringify(request)}`;
+        }
+    }
+    /**
+     * Get from cache if not expired
+     */
+    getFromCache(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            return null;
+        }
+        // Check if cache entry has expired
+        const age = Date.now() - entry.timestamp.getTime();
+        if (entry.ttl !== Infinity && age > entry.ttl) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.fundamentals;
+    }
+    /**
+     * Add to cache with TTL
+     */
+    addToCache(key, fundamentals, ttl) {
+        // Enforce max entries limit
+        if (this.cache.size >= this.cacheConfig.maxEntries) {
+            // Remove oldest entry
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey) {
+                this.cache.delete(oldestKey);
+            }
+        }
+        this.cache.set(key, {
+            fundamentals,
+            timestamp: new Date(),
+            ttl: ttl || this.cacheConfig.ttl
+        });
+    }
+    /**
+     * Get human-readable request description
+     */
+    getRequestDescription(request) {
+        switch (request.type) {
+            case 'fundamentals-current':
+                return `fundamentals for ${request.ticker}`;
+            case 'fundamentals-batch':
+                return `fundamentals for ${request.tickers.length} tickers`;
+            default:
+                return 'fundamentals data';
+        }
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5mdW5kYW1lbnRhbHNzZXJ2aWNlLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvc3RvY2tzL2NsYXNzZXMuZnVuZGFtZW50YWxzc2VydmljZS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQXdCekM7OztHQUdHO0FBQ0gsTUFBTSxPQUFPLG1CQUFtQjtJQVU5QixZQUFZLFdBQW1EO1FBVHZELGNBQVMsR0FBRyxJQUFJLEdBQUcsRUFBMEIsQ0FBQztRQUM5QyxVQUFLLEdBQUcsSUFBSSxHQUFHLEVBQXVCLENBQUM7UUFDdkMsV0FBTSxHQUFHLE9BQU8sQ0FBQztRQUVqQixnQkFBVyxHQUFHO1lBQ3BCLEdBQUcsRUFBRSxFQUFFLEdBQUcsRUFBRSxHQUFHLEVBQUUsR0FBRyxFQUFFLEdBQUcsSUFBSSxFQUFFLGtEQUFrRDtZQUNqRixVQUFVLEVBQUUsS0FBSztTQUNsQixDQUFDO1FBR0EsSUFBSSxXQUFXLEVBQUUsQ0FBQztZQUNoQixJQUFJLENBQUMsV0FBVyxHQUFHLEVBQUUsR0FBRyxJQUFJLENBQUMsV0FBVyxFQUFFLEdBQUcsV0FBVyxFQUFFLENBQUM7UUFDN0QsQ0FBQztJQUNILENBQUM7SUFFRDs7T0FFRztJQUNJLFFBQVEsQ0FBQyxRQUErQixFQUFFLE1BQW9DO1FBQ25GLE1BQU0sYUFBYSxHQUFnQztZQUNqRCxPQUFPLEVBQUUsSUFBSTtZQUNiLFFBQVEsRUFBRSxRQUFRLENBQUMsUUFBUTtZQUMzQixPQUFPLEVBQUUsS0FBSyxFQUFFLHNDQUFzQztZQUN0RCxhQUFhLEVBQUUsQ0FBQztZQUNoQixVQUFVLEVBQUUsSUFBSTtZQUNoQixRQUFRLEVBQUUsSUFBSSxDQUFDLFdBQVcsQ0FBQyxHQUFHO1NBQy9CLENBQUM7UUFFRixNQUFNLFlBQVksR0FBRyxFQUFFLEdBQUcsYUFBYSxFQUFFLEdBQUcsTUFBTSxFQUFFLENBQUM7UUFFckQsSUFBSSxD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

package/dist_ts/stocks/index.d.ts

@@ -1,5 +1,8 @@
 export * from './interfaces/stockprice.js';
 export * from './interfaces/provider.js';
+export * from './interfaces/fundamentals.js';
 export * from './classes.stockservice.js';
+export * from './classes.fundamentalsservice.js';
 export * from './providers/provider.yahoo.js';
 export * from './providers/provider.marketstack.js';
+export * from './providers/provider.secedgar.js';

package/dist_ts/stocks/index.js

@@ -1,9 +1,12 @@
 // Export all interfaces
 export * from './interfaces/stockprice.js';
 export * from './interfaces/provider.js';
-// Export main service
+export * from './interfaces/fundamentals.js';
+// Export main services
 export * from './classes.stockservice.js';
+export * from './classes.fundamentalsservice.js';
 // Export providers
 export * from './providers/provider.yahoo.js';
 export * from './providers/provider.marketstack.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9zdG9ja3MvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsd0JBQXdCO0FBQ3hCLGNBQWMsNEJBQTRCLENBQUM7QUFDM0MsY0FBYywwQkFBMEIsQ0FBQztBQUV6QyxzQkFBc0I7QUFDdEIsY0FBYywyQkFBMkIsQ0FBQztBQUUxQyxtQkFBbUI7QUFDbkIsY0FBYywrQkFBK0IsQ0FBQztBQUM5QyxjQUFjLHFDQUFxQyxDQUFDIn0=
+export * from './providers/provider.secedgar.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9zdG9ja3MvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsd0JBQXdCO0FBQ3hCLGNBQWMsNEJBQTRCLENBQUM7QUFDM0MsY0FBYywwQkFBMEIsQ0FBQztBQUN6QyxjQUFjLDhCQUE4QixDQUFDO0FBRTdDLHVCQUF1QjtBQUN2QixjQUFjLDJCQUEyQixDQUFDO0FBQzFDLGNBQWMsa0NBQWtDLENBQUM7QUFFakQsbUJBQW1CO0FBQ25CLGNBQWMsK0JBQStCLENBQUM7QUFDOUMsY0FBYyxxQ0FBcUMsQ0FBQztBQUNwRCxjQUFjLGtDQUFrQyxDQUFDIn0=

package/dist_ts/stocks/interfaces/fundamentals.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Interfaces for stock fundamental data (financials from SEC filings)
+ * Separate from stock price data (OHLCV) to maintain clean architecture
+ */
+export interface IFundamentalsCurrentRequest {
+    type: 'fundamentals-current';
+    ticker: string;
+}
+export interface IFundamentalsBatchRequest {
+    type: 'fundamentals-batch';
+    tickers: string[];
+}
+export type IFundamentalsRequest = IFundamentalsCurrentRequest | IFundamentalsBatchRequest;
+/**
+ * Stock fundamental data from SEC filings (10-K, 10-Q)
+ * Contains financial metrics like EPS, Revenue, Assets, etc.
+ */
+export interface IStockFundamentals {
+    ticker: string;
+    cik: string;
+    companyName: string;
+    provider: string;
+    timestamp: Date;
+    fetchedAt: Date;
+    earningsPerShareBasic?: number;
+    earningsPerShareDiluted?: number;
+    sharesOutstanding?: number;
+    weightedAverageSharesOutstanding?: number;
+    revenue?: number;
+    netIncome?: number;
+    operatingIncome?: number;
+    grossProfit?: number;
+    costOfRevenue?: number;
+    assets?: number;
+    liabilities?: number;
+    stockholdersEquity?: number;
+    cash?: number;
+    propertyPlantEquipment?: number;
+    marketCap?: number;
+    priceToEarnings?: number;
+    priceToBook?: number;
+    fiscalYear?: string;
+    fiscalQuarter?: string;
+    filingDate?: Date;
+    form?: '10-K' | '10-Q' | string;
+}
+/**
+ * Provider interface for fetching fundamental data
+ * Parallel to IStockProvider but for fundamentals instead of prices
+ */
+export interface IFundamentalsProvider {
+    name: string;
+    priority: number;
+    fetchData(request: IFundamentalsRequest): Promise<IStockFundamentals | IStockFundamentals[]>;
+    isAvailable(): Promise<boolean>;
+    readonly requiresAuth: boolean;
+    readonly rateLimit?: {
+        requestsPerMinute: number;
+        requestsPerDay?: number;
+    };
+}
+/**
+ * Configuration for fundamentals providers
+ */
+export interface IFundamentalsProviderConfig {
+    enabled: boolean;
+    priority?: number;
+    timeout?: number;
+    retryAttempts?: number;
+    retryDelay?: number;
+    cacheTTL?: number;
+}
+/**
+ * Registry for managing fundamental data providers
+ */
+export interface IFundamentalsProviderRegistry {
+    register(provider: IFundamentalsProvider, config?: IFundamentalsProviderConfig): void;
+    unregister(providerName: string): void;
+    getProvider(name: string): IFundamentalsProvider | undefined;
+    getAllProviders(): IFundamentalsProvider[];
+    getEnabledProviders(): IFundamentalsProvider[];
+}

package/dist_ts/stocks/interfaces/fundamentals.js

@@ -0,0 +1,6 @@
+/**
+ * Interfaces for stock fundamental data (financials from SEC filings)
+ * Separate from stock price data (OHLCV) to maintain clean architecture
+ */
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZnVuZGFtZW50YWxzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vdHMvc3RvY2tzL2ludGVyZmFjZXMvZnVuZGFtZW50YWxzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7R0FHRyJ9

package/dist_ts/stocks/providers/provider.secedgar.d.ts

@@ -0,0 +1,102 @@
+import type { IFundamentalsProvider, IStockFundamentals, IFundamentalsRequest } from '../interfaces/fundamentals.js';
+/**
+ * Configuration for SEC EDGAR provider
+ */
+export interface ISecEdgarConfig {
+    userAgent: string;
+    cikCacheTTL?: number;
+    fundamentalsCacheTTL?: number;
+    timeout?: number;
+}
+/**
+ * SEC EDGAR Fundamental Data Provider
+ *
+ * Features:
+ * - Free public access (no API key required)
+ * - All US public companies
+ * - Financial data from 10-K/10-Q filings
+ * - US GAAP standardized metrics
+ * - Historical data back to ~2009
+ * - < 1 minute filing delay
+ *
+ * Documentation: https://www.sec.gov/edgar/sec-api-documentation
+ *
+ * Rate Limits:
+ * - 10 requests per second (enforced by SEC)
+ * - Requires User-Agent header in format: "Company Name Email"
+ *
+ * Data Sources:
+ * - Company Facts API: /api/xbrl/companyfacts/CIK##########.json
+ * - Ticker Lookup: /files/company_tickers.json
+ */
+export declare class SecEdgarProvider implements IFundamentalsProvider {
+    name: string;
+    priority: number;
+    readonly requiresAuth = false;
+    readonly rateLimit: {
+        requestsPerMinute: number;
+        requestsPerDay: any;
+    };
+    private logger;
+    private baseUrl;
+    private tickersUrl;
+    private userAgent;
+    private config;
+    private cikCache;
+    private tickerListCache;
+    private rateLimiter;
+    constructor(config: ISecEdgarConfig);
+    /**
+     * Unified data fetching method
+     */
+    fetchData(request: IFundamentalsRequest): Promise<IStockFundamentals | IStockFundamentals[]>;
+    /**
+     * Fetch fundamental data for a single ticker
+     */
+    private fetchFundamentals;
+    /**
+     * Fetch fundamental data for multiple tickers
+     */
+    private fetchBatchFundamentals;
+    /**
+     * Get CIK (Central Index Key) for a ticker symbol
+     * Uses SEC's public ticker-to-CIK mapping file
+     */
+    private getCIK;
+    /**
+     * Fetch the SEC ticker-to-CIK mapping list
+     * Cached for 24 hours (list updates daily)
+     */
+    private fetchTickerList;
+    /**
+     * Fetch company facts from SEC EDGAR
+     */
+    private fetchCompanyFacts;
+    /**
+     * Parse SEC company facts into structured fundamental data
+     */
+    private parseCompanyFacts;
+    /**
+     * Get the latest value for a US GAAP metric
+     */
+    private getLatestValue;
+    /**
+     * Get metadata from the latest data point
+     */
+    private getLatestMetadata;
+    /**
+     * Check if SEC EDGAR API is available
+     */
+    isAvailable(): Promise<boolean>;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        cikCacheSize: number;
+        hasTickerList: boolean;
+    };
+    /**
+     * Clear all caches
+     */
+    clearCache(): void;
+}