# 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