103 lines
2.7 KiB
TypeScript
103 lines
2.7 KiB
TypeScript
/**
|
||
* Interfaces for stock fundamental data (financials from SEC filings)
|
||
* Separate from stock price data (OHLCV) to maintain clean architecture
|
||
*/
|
||
|
||
// Request types for fundamental data
|
||
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;
|
||
|
||
// Per-share metrics
|
||
earningsPerShareBasic?: number;
|
||
earningsPerShareDiluted?: number;
|
||
sharesOutstanding?: number;
|
||
weightedAverageSharesOutstanding?: number;
|
||
|
||
// Income statement (annual USD)
|
||
revenue?: number;
|
||
netIncome?: number;
|
||
operatingIncome?: number;
|
||
grossProfit?: number;
|
||
costOfRevenue?: number;
|
||
|
||
// Balance sheet (annual USD)
|
||
assets?: number;
|
||
liabilities?: number;
|
||
stockholdersEquity?: number;
|
||
cash?: number;
|
||
propertyPlantEquipment?: number;
|
||
|
||
// Calculated metrics (requires current price)
|
||
marketCap?: number; // price × sharesOutstanding
|
||
priceToEarnings?: number; // price / EPS
|
||
priceToBook?: number; // marketCap / stockholdersEquity
|
||
|
||
// Metadata
|
||
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; // Custom cache TTL for this provider
|
||
}
|
||
|
||
/**
|
||
* 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[];
|
||
}
|