opendata/ts/stocks/interfaces/fundamentals.ts

/**
 * 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[];
}