opendata/readme.plan.md

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

// 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