183 lines
5.3 KiB
Markdown
183 lines
5.3 KiB
Markdown
# Stock Prices Module Implementation Plan
|
|
|
|
Command to reread guidelines: Read /home/philkunz/.claude/CLAUDE.md
|
|
|
|
## Overview
|
|
Implementation of a stocks module for fetching current stock prices using various APIs, starting with Yahoo Finance API.
|
|
|
|
## Phase 1: Yahoo Finance Implementation
|
|
|
|
### 1.1 Research & Documentation
|
|
- [ ] Research Yahoo Finance API endpoints (no official API, using public endpoints)
|
|
- [ ] Document available data fields and formats
|
|
- [ ] Identify rate limits and restrictions
|
|
- [ ] Test endpoints manually with curl
|
|
|
|
### 1.2 Module Structure
|
|
```
|
|
ts/
|
|
├── index.ts # Main exports
|
|
├── plugins.ts # External dependencies
|
|
└── stocks/
|
|
├── index.ts # Stocks module exports
|
|
├── classes.stockservice.ts # Main StockPriceService class
|
|
├── interfaces/
|
|
│ ├── stockprice.ts # IStockPrice interface
|
|
│ └── provider.ts # IStockProvider interface
|
|
└── providers/
|
|
└── provider.yahoo.ts # Yahoo Finance implementation
|
|
```
|
|
|
|
### 1.3 Core Interfaces
|
|
```typescript
|
|
// IStockPrice - Standardized stock price data
|
|
interface IStockPrice {
|
|
ticker: string;
|
|
price: number;
|
|
currency: string;
|
|
change: number;
|
|
changePercent: number;
|
|
timestamp: Date;
|
|
provider: string;
|
|
}
|
|
|
|
// IStockProvider - Provider implementation contract
|
|
interface IStockProvider {
|
|
name: string;
|
|
fetchPrice(ticker: string): Promise<IStockPrice>;
|
|
fetchPrices(tickers: string[]): Promise<IStockPrice[]>;
|
|
isAvailable(): Promise<boolean>;
|
|
}
|
|
```
|
|
|
|
### 1.4 Yahoo Finance Provider Implementation
|
|
- [ ] Create YahooFinanceProvider class
|
|
- [ ] Implement HTTP requests to Yahoo Finance endpoints
|
|
- [ ] Parse response data into IStockPrice format
|
|
- [ ] Handle errors and edge cases
|
|
- [ ] Add request throttling/rate limiting
|
|
|
|
### 1.5 Main Service Class
|
|
- [ ] Create StockPriceService class
|
|
- [ ] Integrate Yahoo provider
|
|
- [ ] Add method for single ticker lookup
|
|
- [ ] Add method for batch ticker lookup
|
|
- [ ] Implement error handling with graceful degradation
|
|
|
|
## Phase 2: Core Features
|
|
|
|
### 2.1 Service Architecture
|
|
- [ ] Create extensible provider architecture
|
|
- [ ] Design provider interface for future additions
|
|
- [ ] Implement provider registration system
|
|
|
|
## Phase 3: Advanced Features
|
|
|
|
### 3.1 Caching System
|
|
- [ ] Design cache interface
|
|
- [ ] Implement in-memory cache with TTL
|
|
- [ ] Add cache invalidation logic
|
|
- [ ] Make cache configurable per ticker
|
|
|
|
### 3.2 Configuration
|
|
- [ ] Environment variable support for API keys
|
|
- [ ] Provider configuration (enabled/disabled, priority)
|
|
- [ ] Cache configuration (TTL, max entries)
|
|
- [ ] Request timeout configuration
|
|
|
|
### 3.3 Error Handling
|
|
- [ ] Define custom error types
|
|
- [ ] Implement retry logic with exponential backoff
|
|
- [ ] Add circuit breaker pattern for failing providers
|
|
- [ ] Comprehensive error logging
|
|
|
|
## Phase 4: Testing
|
|
|
|
### 4.1 Unit Tests
|
|
- [ ] Test each provider independently
|
|
- [ ] Mock HTTP requests for predictable testing
|
|
- [ ] Test error scenarios
|
|
- [ ] Test data transformation logic
|
|
|
|
### 4.2 Integration Tests
|
|
- [ ] Test with real API calls (rate limit aware)
|
|
- [ ] Test provider fallback scenarios
|
|
- [ ] Test batch operations
|
|
- [ ] Test cache behavior
|
|
|
|
### 4.3 Performance Tests
|
|
- [ ] Measure response times
|
|
- [ ] Test concurrent request handling
|
|
- [ ] Validate cache effectiveness
|
|
|
|
## Implementation Order
|
|
|
|
1. **Week 1: Yahoo Finance Provider**
|
|
- Research and test Yahoo endpoints
|
|
- Implement basic provider and service
|
|
- Create core interfaces
|
|
- Basic error handling
|
|
|
|
2. **Week 2: Additional Providers**
|
|
- Implement Alpha Vantage provider
|
|
- Implement IEX Cloud provider
|
|
- Add provider fallback logic
|
|
|
|
3. **Week 3: Advanced Features**
|
|
- Implement caching system
|
|
- Add configuration management
|
|
- Enhance error handling
|
|
|
|
4. **Week 4: Testing & Documentation**
|
|
- Write comprehensive tests
|
|
- Create usage documentation
|
|
- Performance optimization
|
|
|
|
## Dependencies
|
|
|
|
### Required
|
|
- `@push.rocks/smartrequest` - HTTP requests
|
|
- `@push.rocks/smartpromise` - Promise utilities
|
|
- `@push.rocks/smartlog` - Logging
|
|
|
|
### Development
|
|
- `@git.zone/tstest` - Testing framework
|
|
- `@git.zone/tsrun` - TypeScript execution
|
|
|
|
## API Endpoints Research
|
|
|
|
### Yahoo Finance
|
|
- Base URL: `https://query1.finance.yahoo.com/v8/finance/chart/{ticker}`
|
|
- No authentication required
|
|
- Returns JSON with price data
|
|
- Rate limits unknown (need to test)
|
|
|
|
### Alpha Vantage
|
|
- Base URL: `https://www.alphavantage.co/query`
|
|
- Requires API key (free tier available)
|
|
- 5 requests per minute, 500 requests per day (free)
|
|
- Good documentation
|
|
|
|
### IEX Cloud
|
|
- Base URL: `https://cloud.iexapis.com/stable`
|
|
- Requires authentication token
|
|
- Free tier: 50,000 messages/month
|
|
- Sandbox environment available
|
|
|
|
## Success Criteria
|
|
|
|
1. Can fetch current stock prices for any valid ticker
|
|
2. Graceful fallback between providers
|
|
3. Response time < 1 second for cached data
|
|
4. Response time < 3 seconds for fresh data
|
|
5. 99% uptime with at least one provider
|
|
6. Comprehensive test coverage (>80%)
|
|
|
|
## Notes
|
|
|
|
- Start with Yahoo Finance as it requires no authentication
|
|
- Implement proper TypeScript types for all data structures
|
|
- Follow the project's coding standards (prefix interfaces with 'I')
|
|
- Use plugins.ts for all external dependencies
|
|
- Keep filenames lowercase
|
|
- Write tests using @git.zone/tstest with smartexpect syntax |