opendata/readme.hints.md

# OpenData Project Hints

## Stocks Module

### Overview
The stocks module provides real-time stock price data through various provider implementations. Currently supports Yahoo Finance with an extensible architecture for additional providers.

### Architecture
- **Provider Pattern**: Each stock data source implements the `IStockProvider` interface
- **Service Registry**: `StockPriceService` manages providers with priority-based selection
- **Caching**: Built-in cache with configurable TTL to reduce API calls
- **Fallback Logic**: Automatic failover between providers if one fails

### Yahoo Finance Provider Notes
- Uses public API endpoints (no authentication required)
- Two main endpoints:
  - `/v8/finance/chart/{ticker}` - Single ticker with full data
  - `/v8/finance/spark?symbols={tickers}` - Multiple tickers with basic data
- Response data is in `response.body` when using smartrequest
- Requires User-Agent header to avoid rate limiting

### Usage Example
```typescript
import { StockPriceService, YahooFinanceProvider } from '@fin.cx/opendata';

const stockService = new StockPriceService({ ttl: 60000 });
const yahooProvider = new YahooFinanceProvider();
stockService.register(yahooProvider);

const price = await stockService.getPrice({ ticker: 'AAPL' });
console.log(`${price.ticker}: $${price.price}`);
```

### Testing
- Tests use real API calls (be mindful of rate limits)
- Mock invalid ticker 'INVALID_TICKER_XYZ' for error testing
- Clear cache between tests to ensure fresh data
- The spark endpoint may return fewer results than requested

### Future Providers
To add a new provider:
1. Create `ts/stocks/providers/provider.{name}.ts`
2. Implement the `IStockProvider` interface
3. Register with `StockPriceService`
4. No changes needed to existing code