@fin.cx/opendata
Version:
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 stoc
106 lines (105 loc) • 2.89 kB
TypeScript
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: undefined;
};
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)
* Uses native fetch for automatic gzip decompression
*/
private fetchTickerList;
/**
* Fetch company facts from SEC EDGAR
* Uses native fetch for automatic gzip decompression
*/
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
* Uses native fetch for automatic gzip decompression
*/
isAvailable(): Promise<boolean>;
/**
* Get cache statistics
*/
getCacheStats(): {
cikCacheSize: number;
hasTickerList: boolean;
};
/**
* Clear all caches
*/
clearCache(): void;
}