@fin.cx/opendata 1.5.3 → 1.6.0

package/readme.hints.md

@@ -0,0 +1,45 @@
+# 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