3.2.0

.serena/.gitignore

@@ -0,0 +1 @@
+/cache

.serena/project.yml

@@ -0,0 +1,67 @@
+# language of the project (csharp, python, rust, java, typescript, go, cpp, or ruby)
+#  * For C, use cpp
+#  * For JavaScript, use typescript
+# Special requirements:
+#  * csharp: Requires the presence of a .sln file in the project folder.
+language: typescript
+
+# whether to use the project's gitignore file to ignore files
+# Added on 2025-04-07
+ignore_all_files_in_gitignore: true
+# list of additional paths to ignore
+# same syntax as gitignore, so you can use * and **
+# Was previously called `ignored_dirs`, please update your config if you are using that.
+# Added (renamed) on 2025-04-07
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""
+
+project_name: "opendata"

changelog.md

@@ -1,5 +1,95 @@
 # Changelog
 
+## 2025-11-01 - 3.2.0 - feat(StockDataService)
+Add unified StockDataService and BaseProviderService with new stockdata interfaces, provider integrations, tests and README updates
+
+- Introduce StockDataService: unified API to fetch prices and fundamentals with automatic enrichment and caching
+- Add IStockData and IStockDataServiceConfig interfaces to define combined price+fundamentals payloads and configuration
+- Implement BaseProviderService abstraction to share provider registration, health, stats and caching logic
+- Add classes.stockdataservice.ts implementing batch/single fetch, enrichment, caching, health checks and provider stats
+- Export new stockdata module and classes from ts/stocks/index.ts
+- Add comprehensive tests: test/test.stockdata.service.node.ts to cover setup, provider registration, fetching, caching, enrichment, health and error handling
+- Update README with Unified Stock Data API examples, usage, and documentation reflecting new unified service
+- Minor infra: add .claude/settings.local.json permissions for local tooling and web fetch domains
+
+## 2025-11-01 - 3.1.0 - feat(fundamentals)
+Add FundamentalsService and SEC EDGAR provider with caching, rate-limiting, tests, and docs updates
+
+- Introduce FundamentalsService to manage fundamentals providers, caching, retry logic and provider statistics
+- Add SecEdgarProvider to fetch SEC EDGAR company facts (CIK lookup, company facts parsing) with rate limiting and local caches
+- Expose fundamentals interfaces and services from ts/stocks (exports updated)
+- Add comprehensive tests for FundamentalsService and SecEdgarProvider (new test files)
+- Update README with new Fundamentals module documentation, usage examples, and configuration guidance
+- Implement caching and TTL handling for fundamentals data and provider-specific cache TTL support
+- Add .claude/settings.local.json (local permissions) and various test improvements
+
+## 2025-10-31 - 3.0.0 - BREAKING CHANGE(stocks)
+Unify stock provider API to discriminated IStockDataRequest and add company name/fullname enrichment
+
+- Replace legacy provider methods (fetchPrice/fetchPrices) with a single fetchData(request: IStockDataRequest) on IStockProvider — providers must be migrated to the new signature.
+- Migrate StockPriceService to the unified getData(request: IStockDataRequest) API. Convenience helpers getPrice/getPrices now wrap getData.
+- Add companyName and companyFullName fields to IStockPrice and populate them in provider mappings (Marketstack mapping updated; Yahoo provider updated to support the unified API).
+- MarketstackProvider: added buildCompanyFullName helper and improved mapping to include company identification fields and full name formatting.
+- YahooFinanceProvider: updated to implement fetchData and to route current/batch requests through the new unified request types; historical/intraday throw explicit errors.
+- Updated tests to exercise the new unified API, company-name enrichment, caching behavior, and provider direct methods.
+- Note: This is a breaking change for external providers and integrations that implemented the old fetchPrice/fetchPrices API. Bump major version.
+
+## 2025-10-31 - 2.1.0 - feat(stocks)
+Add unified stock data API (getData) with historical/OHLCV support, smart caching and provider enhancements
+
+- Introduce discriminated union request types (IStockDataRequest) and a unified getData() method (replaces legacy getPrice/getPrices for new use cases)
+- Add OHLCV fields (open, high, low, volume, adjusted) and metadata (dataType, fetchedAt) to IStockPrice
+- Implement data-type aware smart caching with TTLs (historical = never expire, EOD = 24h, live = 30s, intraday matches interval)
+- Extend StockPriceService: new getData(), data-specific cache keys, cache maxEntries increased (default 10000), and TTL-aware add/get cache logic
+- Enhance Marketstack provider: unified fetchData(), historical date-range retrieval with pagination, exchange filtering, batch current fetch, OHLCV mapping, and intraday placeholder
+- Update Yahoo provider to include dataType and fetchedAt (live data) and maintain legacy fetchPrice/fetchPrices compatibility
+- Add/adjust tests to cover unified API, historical retrieval, OHLCV presence and smart caching behavior; test setup updated to require explicit OpenData directory paths
+- Update README to document v2.1 changes, migration examples, and new stock provider capabilities
+
+## 2025-10-31 - 2.0.0 - BREAKING CHANGE(OpenData)
+Require explicit directory paths for OpenData (nogit/download/germanBusinessData); remove automatic .nogit creation; update HandelsRegister, JsonlDataProcessor, tests and README.
+
+- Breaking: OpenData constructor now requires a config object with nogitDir, downloadDir and germanBusinessDataDir. The constructor will throw if these paths are not provided.
+- Removed automatic creation/export of .nogit/download/germanBusinessData from ts/paths. OpenData.start now ensures the required directories exist.
+- HandelsRegister API changed: constructor now accepts downloadDir and manages its own unique download folder; screenshot and download paths now use the configured downloadDir.
+- JsonlDataProcessor now accepts a germanBusinessDataDir parameter and uses it when ensuring/storing data instead of relying on global paths.
+- Updated tests to provide explicit path configuration (tests now set testNogitDir, testDownloadDir, testGermanBusinessDataDir and write outputs accordingly) and to use updated constructors and qenv usage.
+- Documentation updated (README) to document the breaking change and show examples for required directory configuration when instantiating OpenData.
+- Added .claude/settings.local.json for local permissions/config used in development/CI environments.
+
+## 2025-10-11 - 1.7.0 - feat(stocks)
+Add Marketstack provider (EOD) with tests, exports and documentation updates
+
+- Add MarketstackProvider implementation (ts/stocks/providers/provider.marketstack.ts) providing EOD single and batch fetching, availability checks and mapping to IStockPrice.
+- Export MarketstackProvider from ts/stocks/index.ts so it is available via the public API.
+- Add comprehensive Marketstack tests (test/test.marketstack.node.ts) covering registration, health checks, single/batch fetches, caching, ticker/market validation, provider stats and sample output.
+- Update README with Marketstack usage examples, configuration, API key instructions and provider/health documentation.
+- Bump dev dependency @git.zone/tstest to ^2.4.2 in package.json.
+- Add project helper/config files (.claude/settings.local.json, .serena/project.yml and .serena/.gitignore) to support CI/tooling.
+
+## 2025-09-24 - 1.6.1 - fix(stocks)
+Fix Yahoo provider request handling and bump dependency versions
+
+- Refactored Yahoo Finance provider to use SmartRequest.create() builder and await response.json() for HTTP responses (replaces direct getJson usage).
+- Improved batch and single-price fetching to use the SmartRequest API, keeping User-Agent header and timeouts.
+- Added a compile-time type-check alias to ensure IStockPrice matches tsclass.finance.IStockPrice.
+- Bumped development and runtime dependency versions (notable bumps include @git.zone/tsbuild, @git.zone/tstest, @push.rocks/qenv, @push.rocks/smartarchive, @push.rocks/smartdata, @push.rocks/smartfile, @push.rocks/smartlog, @push.rocks/smartpath, @push.rocks/smartrequest, @tsclass/tsclass).
+- Added .claude/settings.local.json to grant local CI permissions for a few Bash commands.
+
+## 2025-07-12 - 1.6.0 - feat(readme)
+Revamp documentation and package description for enhanced clarity
+
+- Restructured README to highlight real-time stock data and German business data, streamlining quick start and advanced examples
+- Updated package.json description to better reflect library capabilities
+- Added .claude/settings.local.json to define permissions for external tools
+- Refined code examples in tests and documentation for improved clarity and consistency
+
+## 2025-04-09 - 1.5.3 - fix(test)
+Await file writes in Handelsregister tests to ensure all downloads complete before test end
+
+- Replaced array.map with await Promise.all to properly await asynchronous file writes in test/test.handelsregister.ts
+- Improved robustness of asynchronous operations in test suite
+
 ## 2025-04-09 - 1.5.2 - fix(readme)
 Improve .env configuration code block formatting in documentation
 

package.json

@@ -1,42 +1,42 @@
 {
   "name": "@fin.cx/opendata",
-  "version": "1.5.2",
+  "version": "3.2.0",
   "private": false,
-  "description": "A comprehensive TypeScript library that manages open business data for German companies by integrating MongoDB, processing JSONL bulk data, and automating browser interactions for Handelsregister data retrieval.",
+  "description": "A comprehensive TypeScript library for accessing business data and real-time financial information. Features include German company data management with MongoDB integration, JSONL bulk processing, automated Handelsregister interactions, and real-time stock market data from multiple providers.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "type": "module",
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "scripts": {
-    "test": "(tstest test/ --web)",
+    "test": "(tstest test/ --verbose)",
     "build": "(tsbuild --web --allowimplicitany)",
     "buildDocs": "(tsdoc)"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.3.2",
+    "@git.zone/tsbuild": "^2.6.8",
-    "@git.zone/tsbundle": "^2.2.5",
+    "@git.zone/tsbundle": "^2.5.1",
     "@git.zone/tsrun": "^1.3.3",
-    "@git.zone/tstest": "^1.0.96",
+    "@git.zone/tstest": "^2.4.2",
-    "@push.rocks/tapbundle": "^5.6.2",
     "@types/node": "^22.14.0"
   },
   "dependencies": {
-    "@push.rocks/lik": "^6.1.0",
+    "@push.rocks/lik": "^6.2.2",
-    "@push.rocks/qenv": "^6.1.0",
+    "@push.rocks/qenv": "^6.1.3",
-    "@push.rocks/smartarchive": "^4.0.39",
+    "@push.rocks/smartarchive": "^4.2.2",
     "@push.rocks/smartarray": "^1.1.0",
     "@push.rocks/smartbrowser": "^2.0.8",
-    "@push.rocks/smartdata": "^5.2.12",
+    "@push.rocks/smartdata": "^5.16.4",
     "@push.rocks/smartdelay": "^3.0.5",
-    "@push.rocks/smartfile": "^11.2.0",
+    "@push.rocks/smartfile": "^11.2.7",
-    "@push.rocks/smartpath": "^5.0.18",
+    "@push.rocks/smartlog": "^3.1.10",
+    "@push.rocks/smartpath": "^6.0.0",
     "@push.rocks/smartpromise": "^4.2.3",
-    "@push.rocks/smartrequest": "^2.1.0",
+    "@push.rocks/smartrequest": "^4.3.1",
     "@push.rocks/smartstream": "^3.2.5",
     "@push.rocks/smartunique": "^3.0.9",
     "@push.rocks/smartxml": "^1.1.1",
-    "@tsclass/tsclass": "^8.2.0"
+    "@tsclass/tsclass": "^9.3.0"
   },
   "repository": {
     "type": "git",

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

readme.plan.md

@@ -0,0 +1,193 @@
+# 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. The architecture will support multiple providers, but we'll start with implementing only Yahoo Finance API. The design will make it easy to add additional providers (Alpha Vantage, IEX Cloud, etc.) in the future without changing the core architecture.
+
+## 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 (for all providers)
+    └── providers/
+        ├── provider.yahoo.ts   # Yahoo Finance implementation
+        └── (future: provider.alphavantage.ts, provider.iex.ts, etc.)
+```
+
+### 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 with provider registry
+- [ ] Implement provider interface for pluggable providers
+- [ ] Register Yahoo provider (with ability to add more later)
+- [ ] Add method for single ticker lookup
+- [ ] Add method for batch ticker lookup
+- [ ] Implement error handling with graceful degradation
+- [ ] Design fallback mechanism (ready for multiple providers)
+
+## Phase 2: Core Features
+
+### 2.1 Service Architecture  
+- [ ] Create provider registry pattern for managing multiple providers
+- [ ] Implement provider priority and selection logic
+- [ ] Design provider health check interface
+- [ ] Create provider configuration system
+- [ ] Implement provider discovery mechanism
+- [ ] Add provider capability querying (which tickers/markets supported)
+
+## 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
+- [ ] Provider configuration (timeout, retry settings)
+- [ ] Cache configuration (TTL, max entries)
+- [ ] Request timeout configuration
+- [ ] Error handling 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: Service Architecture**
+   - Create extensible provider system
+   - Implement provider interface
+   - Add provider registration
+
+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)
+- Alternative endpoints to explore:
+  - `/v7/finance/quote` - Simplified quote data
+  - `/v10/finance/quoteSummary` - Detailed company data
+
+## Success Criteria
+
+1. Can fetch current stock prices for any valid ticker
+2. Extensible architecture for future providers
+3. Response time < 1 second for cached data
+4. Response time < 3 seconds for fresh data
+5. Proper error handling and recovery
+6. Comprehensive test coverage (>80%)
+
+## Notes
+
+- Yahoo Finance provides free stock data without authentication
+- **Architecture designed for multiple providers**: While only implementing Yahoo Finance initially, all interfaces, classes, and patterns are designed to support multiple stock data providers
+- The provider registry pattern allows adding new providers without modifying existing code
+- Each provider implements the same IStockProvider interface for consistency
+- Future providers can be added by simply creating a new provider class and registering it
+- 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
+- Focus on clean, extensible architecture for future growth
+
+## Future Provider Addition Example
+
+When ready to add a new provider (e.g., Alpha Vantage), the process will be:
+1. Create `ts/stocks/providers/provider.alphavantage.ts`
+2. Implement the `IStockProvider` interface
+3. Register the provider in the StockPriceService
+4. No changes needed to existing code or interfaces

test/test.fundamentals.service.node.ts

@@ -0,0 +1,287 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as opendata from '../ts/index.js';
+
+const TEST_USER_AGENT = 'fin.cx test@fin.cx';
+
+tap.test('FundamentalsService - Provider Registration', async () => {
+  const service = new opendata.FundamentalsService();
+  const provider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+
+  await tap.test('should register provider', async () => {
+    service.register(provider);
+
+    const registered = service.getProvider('SEC EDGAR');
+    expect(registered).toBeDefined();
+    expect(registered?.name).toEqual('SEC EDGAR');
+  });
+
+  await tap.test('should get all providers', async () => {
+    const providers = service.getAllProviders();
+    expect(providers.length).toBeGreaterThan(0);
+    expect(providers[0].name).toEqual('SEC EDGAR');
+  });
+
+  await tap.test('should get enabled providers', async () => {
+    const providers = service.getEnabledProviders();
+    expect(providers.length).toBeGreaterThan(0);
+  });
+
+  await tap.test('should unregister provider', async () => {
+    service.unregister('SEC EDGAR');
+
+    const registered = service.getProvider('SEC EDGAR');
+    expect(registered).toBeUndefined();
+
+    // Re-register for other tests
+    service.register(provider);
+  });
+});
+
+tap.test('FundamentalsService - Fetch Fundamentals', async () => {
+  const service = new opendata.FundamentalsService();
+  const provider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+
+  service.register(provider);
+
+  await tap.test('should fetch fundamentals for single ticker', async () => {
+    const fundamentals = await service.getFundamentals('AAPL');
+
+    expect(fundamentals).toBeDefined();
+    expect(fundamentals.ticker).toEqual('AAPL');
+    expect(fundamentals.companyName).toEqual('Apple Inc.');
+    expect(fundamentals.provider).toEqual('SEC EDGAR');
+    expect(fundamentals.earningsPerShareDiluted).toBeGreaterThan(0);
+    expect(fundamentals.sharesOutstanding).toBeGreaterThan(0);
+
+    console.log('\n📊 Fetched via Service:');
+    console.log(`  ${fundamentals.ticker}: ${fundamentals.companyName}`);
+    console.log(`  EPS: $${fundamentals.earningsPerShareDiluted?.toFixed(2)}`);
+    console.log(`  Shares: ${(fundamentals.sharesOutstanding! / 1_000_000_000).toFixed(2)}B`);
+  });
+
+  await tap.test('should fetch fundamentals for multiple tickers', async () => {
+    const fundamentalsList = await service.getBatchFundamentals(['AAPL', 'MSFT']);
+
+    expect(fundamentalsList).toBeInstanceOf(Array);
+    expect(fundamentalsList.length).toEqual(2);
+
+    const apple = fundamentalsList.find(f => f.ticker === 'AAPL');
+    const msft = fundamentalsList.find(f => f.ticker === 'MSFT');
+
+    expect(apple).toBeDefined();
+    expect(msft).toBeDefined();
+    expect(apple!.companyName).toEqual('Apple Inc.');
+    expect(msft!.companyName).toContain('Microsoft');
+
+    console.log('\n📊 Batch Fetch via Service:');
+    fundamentalsList.forEach(f => {
+      console.log(`  ${f.ticker}: ${f.companyName} - EPS: $${f.earningsPerShareDiluted?.toFixed(2)}`);
+    });
+  });
+});
+
+tap.test('FundamentalsService - Caching', async () => {
+  const service = new opendata.FundamentalsService({
+    ttl: 60000, // 60 seconds for testing
+    maxEntries: 100
+  });
+
+  const provider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+
+  service.register(provider);
+
+  await tap.test('should cache fundamentals data', async () => {
+    // Clear cache first
+    service.clearCache();
+
+    let stats = service.getCacheStats();
+    expect(stats.size).toEqual(0);
+
+    // First fetch (should hit API)
+    const start1 = Date.now();
+    await service.getFundamentals('AAPL');
+    const duration1 = Date.now() - start1;
+
+    stats = service.getCacheStats();
+    expect(stats.size).toEqual(1);
+
+    // Second fetch (should hit cache - much faster)
+    const start2 = Date.now();
+    await service.getFundamentals('AAPL');
+    const duration2 = Date.now() - start2;
+
+    expect(duration2).toBeLessThan(duration1);
+
+    console.log('\n⚡ Cache Performance:');
+    console.log(`  First fetch: ${duration1}ms`);
+    console.log(`  Cached fetch: ${duration2}ms`);
+    console.log(`  Speedup: ${Math.round(duration1 / duration2)}x`);
+  });
+
+  await tap.test('should respect cache TTL', async () => {
+    // Set very short TTL
+    service.setCacheTTL(100); // 100ms
+
+    // Fetch and cache
+    await service.getFundamentals('MSFT');
+
+    // Wait for TTL to expire
+    await new Promise(resolve => setTimeout(resolve, 150));
+
+    // This should fetch again (cache expired)
+    const stats = service.getCacheStats();
+    console.log(`\n⏱️  Cache TTL: ${stats.ttl}ms`);
+  });
+
+  await tap.test('should clear cache', async () => {
+    service.clearCache();
+
+    const stats = service.getCacheStats();
+    expect(stats.size).toEqual(0);
+  });
+});
+
+tap.test('FundamentalsService - Price Enrichment', async () => {
+  const service = new opendata.FundamentalsService();
+  const provider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+
+  service.register(provider);
+
+  await tap.test('should enrich fundamentals with price to calculate market cap', async () => {
+    const fundamentals = await service.getFundamentals('AAPL');
+
+    // Simulate current price
+    const currentPrice = 270.37;
+
+    const enriched = await service.enrichWithPrice(fundamentals, currentPrice);
+
+    expect(enriched.marketCap).toBeDefined();
+    expect(enriched.priceToEarnings).toBeDefined();
+    expect(enriched.priceToBook).toBeDefined();
+
+    expect(enriched.marketCap).toBeGreaterThan(0);
+    expect(enriched.priceToEarnings).toBeGreaterThan(0);
+
+    console.log('\n💰 Enriched with Price ($270.37):');
+    console.log(`  Market Cap: $${(enriched.marketCap! / 1_000_000_000_000).toFixed(2)}T`);
+    console.log(`  P/E Ratio: ${enriched.priceToEarnings!.toFixed(2)}`);
+    console.log(`  P/B Ratio: ${enriched.priceToBook?.toFixed(2) || 'N/A'}`);
+
+    // Verify calculations
+    const expectedMarketCap = fundamentals.sharesOutstanding! * currentPrice;
+    expect(Math.abs(enriched.marketCap! - expectedMarketCap)).toBeLessThan(1); // Allow for rounding
+
+    const expectedPE = currentPrice / fundamentals.earningsPerShareDiluted!;
+    expect(Math.abs(enriched.priceToEarnings! - expectedPE)).toBeLessThan(0.01);
+  });
+
+  await tap.test('should enrich batch fundamentals with prices', async () => {
+    const fundamentalsList = await service.getBatchFundamentals(['AAPL', 'MSFT']);
+
+    const priceMap = new Map<string, number>([
+      ['AAPL', 270.37],
+      ['MSFT', 425.50]
+    ]);
+
+    const enriched = await service.enrichBatchWithPrices(fundamentalsList, priceMap);
+
+    expect(enriched.length).toEqual(2);
+
+    const apple = enriched.find(f => f.ticker === 'AAPL')!;
+    const msft = enriched.find(f => f.ticker === 'MSFT')!;
+
+    expect(apple.marketCap).toBeGreaterThan(0);
+    expect(msft.marketCap).toBeGreaterThan(0);
+
+    console.log('\n💰 Batch Enrichment:');
+    console.log(`  AAPL: Market Cap $${(apple.marketCap! / 1_000_000_000_000).toFixed(2)}T, P/E ${apple.priceToEarnings!.toFixed(2)}`);
+    console.log(`  MSFT: Market Cap $${(msft.marketCap! / 1_000_000_000_000).toFixed(2)}T, P/E ${msft.priceToEarnings!.toFixed(2)}`);
+  });
+});
+
+tap.test('FundamentalsService - Provider Health', async () => {
+  const service = new opendata.FundamentalsService();
+  const provider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+
+  service.register(provider);
+
+  await tap.test('should check provider health', async () => {
+    const health = await service.checkProvidersHealth();
+
+    expect(health.size).toEqual(1);
+    expect(health.get('SEC EDGAR')).toBe(true);
+
+    console.log('\n💚 Provider Health:');
+    health.forEach((isHealthy, name) => {
+      console.log(`  ${name}: ${isHealthy ? '✅ Healthy' : '❌ Unhealthy'}`);
+    });
+  });
+});
+
+tap.test('FundamentalsService - Provider Statistics', async () => {
+  const service = new opendata.FundamentalsService();
+  const provider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+
+  service.register(provider);
+
+  await tap.test('should track provider statistics', async () => {
+    // Make some requests
+    await service.getFundamentals('AAPL');
+    await service.getFundamentals('MSFT');
+
+    const stats = service.getProviderStats();
+
+    expect(stats.size).toEqual(1);
+
+    const secStats = stats.get('SEC EDGAR');
+    expect(secStats).toBeDefined();
+    expect(secStats!.successCount).toBeGreaterThan(0);
+
+    console.log('\n📈 Provider Stats:');
+    console.log(`  Success Count: ${secStats!.successCount}`);
+    console.log(`  Error Count: ${secStats!.errorCount}`);
+  });
+});
+
+tap.test('FundamentalsService - Error Handling', async () => {
+  const service = new opendata.FundamentalsService();
+  const provider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+
+  service.register(provider);
+
+  await tap.test('should throw error for invalid ticker', async () => {
+    try {
+      await service.getFundamentals('INVALIDTICKER123456');
+      throw new Error('Should have thrown error');
+    } catch (error) {
+      expect(error.message).toContain('CIK not found');
+    }
+  });
+
+  await tap.test('should throw error when no providers available', async () => {
+    const emptyService = new opendata.FundamentalsService();
+
+    try {
+      await emptyService.getFundamentals('AAPL');
+      throw new Error('Should have thrown error');
+    } catch (error) {
+      expect(error.message).toContain('No fundamentals providers available');
+    }
+  });
+});
+
+export default tap.start();

test/test.handelsregister.ts

@@ -1,12 +1,24 @@
-import { expect, expectAsync, tap } from '@push.rocks/tapbundle';
+import { expect, tap } from '@git.zone/tstest/tapbundle';
 import * as opendata from '../ts/index.js'
+import * as paths from '../ts/paths.js';
+import * as plugins from '../ts/plugins.js';
 
 import { BusinessRecord } from '../ts/classes.businessrecord.js';
 
+// Test configuration - explicit paths required
+const testNogitDir = plugins.path.join(paths.packageDir, '.nogit');
+const testDownloadDir = plugins.path.join(testNogitDir, 'downloads');
+const testGermanBusinessDataDir = plugins.path.join(testNogitDir, 'germanbusinessdata');
+const testOutputDir = plugins.path.join(testNogitDir, 'testoutput');
+
 let testOpenDataInstance: opendata.OpenData;
 
 tap.test('first test', async () => {
-  testOpenDataInstance = new opendata.OpenData();
+  testOpenDataInstance = new opendata.OpenData({
+    nogitDir: testNogitDir,
+    downloadDir: testDownloadDir,
+    germanBusinessDataDir: testGermanBusinessDataDir
+  });
   expect(testOpenDataInstance).toBeInstanceOf(opendata.OpenData);
 });
 
@@ -27,14 +39,14 @@ tap.test('should get the data for a specific company', async () => {
   const result = await testOpenDataInstance.handelsregister.getSpecificCompany(testCompany);
   console.log(result);
 
-  result.files.map(async (file) => {
+  await Promise.all(result.files.map(async (file) => {
-    await file.writeToDir('./.nogit/testoutput');
+    await file.writeToDir(testOutputDir);
-  });
+  }));
 
 
 });
 
-tap.test('should stop the instance', async () => {
+tap.test('should stop the instance', async (toolsArg) => {
   await testOpenDataInstance.stop();
 });
 

test/test.marketstack.node.ts

@@ -0,0 +1,572 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as opendata from '../ts/index.js';
+import * as paths from '../ts/paths.js';
+import * as plugins from '../ts/plugins.js';
+
+// Test configuration - explicit paths required
+const testNogitDir = plugins.path.join(paths.packageDir, '.nogit');
+
+// Test data
+const testTickers = ['AAPL', 'MSFT', 'GOOGL'];
+const invalidTicker = 'INVALID_TICKER_XYZ';
+
+let stockService: opendata.StockPriceService;
+let marketstackProvider: opendata.MarketstackProvider;
+let testQenv: plugins.qenv.Qenv;
+
+tap.test('should create StockPriceService instance', async () => {
+  stockService = new opendata.StockPriceService({
+    ttl: 30000, // 30 seconds cache
+    maxEntries: 100
+  });
+  expect(stockService).toBeInstanceOf(opendata.StockPriceService);
+});
+
+tap.test('should create MarketstackProvider instance', async () => {
+  try {
+    // Create qenv and get API key
+    testQenv = new plugins.qenv.Qenv(paths.packageDir, testNogitDir);
+    const apiKey = await testQenv.getEnvVarOnDemand('MARKETSTACK_COM_TOKEN');
+
+    marketstackProvider = new opendata.MarketstackProvider(apiKey, {
+      enabled: true,
+      timeout: 10000,
+      retryAttempts: 2,
+      retryDelay: 500
+    });
+    expect(marketstackProvider).toBeInstanceOf(opendata.MarketstackProvider);
+    expect(marketstackProvider.name).toEqual('Marketstack');
+    expect(marketstackProvider.requiresAuth).toEqual(true);
+    expect(marketstackProvider.priority).toEqual(80);
+  } catch (error) {
+    if (error.message.includes('MARKETSTACK_COM_TOKEN')) {
+      console.log('⚠️  MARKETSTACK_COM_TOKEN not set - skipping Marketstack tests');
+      tap.test('Marketstack token not available', async () => {
+        expect(true).toEqual(true); // Skip gracefully
+      });
+      return;
+    }
+    throw error;
+  }
+});
+
+tap.test('should register Marketstack provider with the service', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  stockService.register(marketstackProvider);
+  const providers = stockService.getAllProviders();
+  expect(providers).toContainEqual(marketstackProvider);
+  expect(stockService.getProvider('Marketstack')).toEqual(marketstackProvider);
+});
+
+tap.test('should check provider health', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  const health = await stockService.checkProvidersHealth();
+  expect(health.get('Marketstack')).toEqual(true);
+});
+
+tap.test('should fetch single stock price', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  const price = await stockService.getPrice({ ticker: 'AAPL' });
+
+  expect(price).toHaveProperty('ticker');
+  expect(price).toHaveProperty('price');
+  expect(price).toHaveProperty('currency');
+  expect(price).toHaveProperty('change');
+  expect(price).toHaveProperty('changePercent');
+  expect(price).toHaveProperty('previousClose');
+  expect(price).toHaveProperty('timestamp');
+  expect(price).toHaveProperty('provider');
+  expect(price).toHaveProperty('marketState');
+
+  expect(price.ticker).toEqual('AAPL');
+  expect(price.price).toBeGreaterThan(0);
+  expect(price.provider).toEqual('Marketstack');
+  expect(price.timestamp).toBeInstanceOf(Date);
+  expect(price.marketState).toEqual('CLOSED'); // EOD data
+
+  console.log(`✓ Fetched AAPL: $${price.price} (${price.changePercent >= 0 ? '+' : ''}${price.changePercent.toFixed(2)}%)`);
+});
+
+tap.test('should fetch multiple stock prices', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  const prices = await stockService.getPrices({
+    tickers: testTickers
+  });
+
+  expect(prices).toBeArray();
+  expect(prices.length).toBeGreaterThan(0);
+  expect(prices.length).toBeLessThanOrEqual(testTickers.length);
+
+  for (const price of prices) {
+    expect(testTickers).toContain(price.ticker);
+    expect(price.price).toBeGreaterThan(0);
+    expect(price.provider).toEqual('Marketstack');
+    expect(price.marketState).toEqual('CLOSED');
+    console.log(`  ${price.ticker}: $${price.price}`);
+  }
+});
+
+tap.test('should serve cached prices on subsequent requests', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  // First request - should hit the API
+  const firstRequest = await stockService.getPrice({ ticker: 'AAPL' });
+
+  // Second request - should be served from cache
+  const secondRequest = await stockService.getPrice({ ticker: 'AAPL' });
+
+  expect(secondRequest.ticker).toEqual(firstRequest.ticker);
+  expect(secondRequest.price).toEqual(firstRequest.price);
+  expect(secondRequest.timestamp).toEqual(firstRequest.timestamp);
+
+  console.log('✓ Cache working correctly');
+});
+
+tap.test('should handle invalid ticker gracefully', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  try {
+    await stockService.getPrice({ ticker: invalidTicker });
+    throw new Error('Should have thrown an error for invalid ticker');
+  } catch (error) {
+    expect(error.message).toInclude('Failed to fetch');
+    console.log('✓ Invalid ticker handled correctly');
+  }
+});
+
+tap.test('should support market checking', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  expect(marketstackProvider.supportsMarket('US')).toEqual(true);
+  expect(marketstackProvider.supportsMarket('UK')).toEqual(true);
+  expect(marketstackProvider.supportsMarket('DE')).toEqual(true);
+  expect(marketstackProvider.supportsMarket('JP')).toEqual(true);
+  expect(marketstackProvider.supportsMarket('INVALID')).toEqual(false);
+
+  console.log('✓ Market support check working');
+});
+
+tap.test('should validate ticker format', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  expect(marketstackProvider.supportsTicker('AAPL')).toEqual(true);
+  expect(marketstackProvider.supportsTicker('MSFT')).toEqual(true);
+  expect(marketstackProvider.supportsTicker('BRK.B')).toEqual(true);
+  expect(marketstackProvider.supportsTicker('123456789012')).toEqual(false);
+  expect(marketstackProvider.supportsTicker('invalid@ticker')).toEqual(false);
+
+  console.log('✓ Ticker validation working');
+});
+
+tap.test('should get provider statistics', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  const stats = stockService.getProviderStats();
+  const marketstackStats = stats.get('Marketstack');
+
+  expect(marketstackStats).not.toEqual(undefined);
+  expect(marketstackStats.successCount).toBeGreaterThan(0);
+  expect(marketstackStats.errorCount).toBeGreaterThanOrEqual(0);
+
+  console.log(`✓ Provider stats: ${marketstackStats.successCount} successes, ${marketstackStats.errorCount} errors`);
+});
+
+tap.test('should test direct provider methods', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  console.log('\n🔍 Testing direct provider methods:');
+
+  // Test isAvailable
+  const available = await marketstackProvider.isAvailable();
+  expect(available).toEqual(true);
+  console.log('  ✓ isAvailable() returned true');
+
+  // Test fetchData for single ticker
+  const price = await marketstackProvider.fetchData({ type: 'current', ticker: 'MSFT' }) as opendata.IStockPrice;
+  expect(price.ticker).toEqual('MSFT');
+  expect(price.provider).toEqual('Marketstack');
+  expect(price.price).toBeGreaterThan(0);
+  console.log(`  ✓ fetchData (current) for MSFT: $${price.price}`);
+
+  // Test fetchData for batch
+  const prices = await marketstackProvider.fetchData({
+    type: 'batch',
+    tickers: ['AAPL', 'GOOGL']
+  }) as opendata.IStockPrice[];
+  expect(prices.length).toBeGreaterThan(0);
+  console.log(`  ✓ fetchData (batch) returned ${prices.length} prices`);
+
+  for (const p of prices) {
+    console.log(`    ${p.ticker}: $${p.price}`);
+  }
+});
+
+tap.test('should fetch sample EOD data', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  console.log('\n📊 Sample EOD Stock Data from Marketstack:');
+  console.log('═'.repeat(65));
+
+  const sampleTickers = [
+    { ticker: 'AAPL', name: 'Apple Inc.' },
+    { ticker: 'MSFT', name: 'Microsoft Corp.' },
+    { ticker: 'GOOGL', name: 'Alphabet Inc.' },
+    { ticker: 'AMZN', name: 'Amazon.com Inc.' },
+    { ticker: 'TSLA', name: 'Tesla Inc.' }
+  ];
+
+  try {
+    const prices = await marketstackProvider.fetchData({
+      type: 'batch',
+      tickers: sampleTickers.map(t => t.ticker)
+    }) as opendata.IStockPrice[];
+
+    const priceMap = new Map(prices.map(p => [p.ticker, p]));
+
+    for (const stock of sampleTickers) {
+      const price = priceMap.get(stock.ticker);
+      if (price) {
+        const changeSymbol = price.change >= 0 ? '↑' : '↓';
+        const changeColor = price.change >= 0 ? '\x1b[32m' : '\x1b[31m';
+        const resetColor = '\x1b[0m';
+
+        console.log(
+          `${stock.name.padEnd(20)} ${price.price.toLocaleString('en-US', {
+            minimumFractionDigits: 2,
+            maximumFractionDigits: 2
+          }).padStart(10)} ${changeColor}${changeSymbol} ${price.change >= 0 ? '+' : ''}${price.change.toFixed(2)} (${price.changePercent >= 0 ? '+' : ''}${price.changePercent.toFixed(2)}%)${resetColor}`
+        );
+      }
+    }
+
+    console.log('═'.repeat(65));
+    console.log(`Provider: Marketstack (EOD Data)`);
+    console.log(`Last updated: ${new Date().toLocaleString()}\n`);
+  } catch (error) {
+    console.log('Error fetching sample data:', error.message);
+  }
+
+  expect(true).toEqual(true);
+});
+
+tap.test('should clear cache', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  // Ensure we have something in cache
+  await stockService.getPrice({ ticker: 'AAPL' });
+
+  // Clear cache
+  stockService.clearCache();
+  console.log('✓ Cache cleared');
+
+  // Next request should hit the API again
+  const price = await stockService.getPrice({ ticker: 'AAPL' });
+  expect(price).not.toEqual(undefined);
+});
+
+// Phase 1 Feature Tests
+
+tap.test('should fetch data using new unified API (current price)', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  console.log('\n🎯 Testing Phase 1: Unified getData API');
+
+  const price = await stockService.getData({
+    type: 'current',
+    ticker: 'MSFT'
+  });
+
+  expect(price).not.toEqual(undefined);
+  expect((price as opendata.IStockPrice).ticker).toEqual('MSFT');
+  expect((price as opendata.IStockPrice).dataType).toEqual('eod');
+  expect((price as opendata.IStockPrice).fetchedAt).toBeInstanceOf(Date);
+
+  console.log(`✓ Fetched current price: $${(price as opendata.IStockPrice).price}`);
+});
+
+tap.test('should fetch historical data with date range', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  console.log('\n📅 Testing Phase 1: Historical Data Retrieval');
+
+  const fromDate = new Date('2024-12-01');
+  const toDate = new Date('2024-12-31');
+
+  const prices = await stockService.getData({
+    type: 'historical',
+    ticker: 'AAPL',
+    from: fromDate,
+    to: toDate,
+    sort: 'DESC'
+  });
+
+  expect(prices).toBeArray();
+  expect((prices as opendata.IStockPrice[]).length).toBeGreaterThan(0);
+
+  console.log(`✓ Fetched ${(prices as opendata.IStockPrice[]).length} historical prices`);
+
+  // Verify all data types are 'eod'
+  for (const price of (prices as opendata.IStockPrice[])) {
+    expect(price.dataType).toEqual('eod');
+    expect(price.ticker).toEqual('AAPL');
+  }
+
+  console.log('✓ All prices have correct dataType');
+});
+
+tap.test('should include OHLCV data in responses', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  console.log('\n📊 Testing Phase 1: OHLCV Data');
+
+  const price = await stockService.getData({
+    type: 'current',
+    ticker: 'GOOGL'
+  });
+
+  const stockPrice = price as opendata.IStockPrice;
+
+  // Verify OHLCV fields are present
+  expect(stockPrice.open).not.toEqual(undefined);
+  expect(stockPrice.high).not.toEqual(undefined);
+  expect(stockPrice.low).not.toEqual(undefined);
+  expect(stockPrice.price).not.toEqual(undefined); // close
+  expect(stockPrice.volume).not.toEqual(undefined);
+
+  console.log(`✓ OHLCV Data:`);
+  console.log(`  Open:   $${stockPrice.open}`);
+  console.log(`  High:   $${stockPrice.high}`);
+  console.log(`  Low:    $${stockPrice.low}`);
+  console.log(`  Close:  $${stockPrice.price}`);
+  console.log(`  Volume: ${stockPrice.volume?.toLocaleString()}`);
+});
+
+tap.test('should support exchange filtering', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  console.log('\n🌍 Testing Phase 1: Exchange Filtering');
+
+  // Note: This test may fail if the exchange doesn't have data for the ticker
+  // In production, you'd test with tickers known to exist on specific exchanges
+  try {
+    const price = await stockService.getData({
+      type: 'current',
+      ticker: 'AAPL',
+      exchange: 'XNAS' // NASDAQ
+    });
+
+    expect(price).not.toEqual(undefined);
+    console.log(`✓ Successfully filtered by exchange: ${(price as opendata.IStockPrice).exchange}`);
+  } catch (error) {
+    console.log('⚠️  Exchange filtering test inconclusive (may need tier upgrade)');
+    expect(true).toEqual(true); // Don't fail test
+  }
+});
+
+tap.test('should verify smart caching with historical data', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  console.log('\n💾 Testing Phase 1: Smart Caching');
+
+  const fromDate = new Date('2024-11-01');
+  const toDate = new Date('2024-11-30');
+
+  // First request - should hit API
+  const start1 = Date.now();
+  const prices1 = await stockService.getData({
+    type: 'historical',
+    ticker: 'TSLA',
+    from: fromDate,
+    to: toDate
+  });
+  const duration1 = Date.now() - start1;
+
+  // Second request - should be cached (historical data cached forever)
+  const start2 = Date.now();
+  const prices2 = await stockService.getData({
+    type: 'historical',
+    ticker: 'TSLA',
+    from: fromDate,
+    to: toDate
+  });
+  const duration2 = Date.now() - start2;
+
+  expect((prices1 as opendata.IStockPrice[]).length).toEqual((prices2 as opendata.IStockPrice[]).length);
+  expect(duration2).toBeLessThan(duration1); // Cached should be much faster
+
+  console.log(`✓ First request:  ${duration1}ms (API call)`);
+  console.log(`✓ Second request: ${duration2}ms (cached)`);
+  console.log(`✓ Speed improvement: ${Math.round((duration1 / duration2) * 10) / 10}x faster`);
+});
+
+// Company Name Feature Tests
+
+tap.test('should include company name in single price request', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  console.log('\n🏢 Testing Company Name Feature: Single Request');
+
+  const price = await stockService.getPrice({ ticker: 'AAPL' });
+
+  expect(price.companyName).not.toEqual(undefined);
+  expect(typeof price.companyName).toEqual('string');
+  expect(price.companyName).toInclude('Apple');
+
+  console.log(`✓ Company name retrieved: "${price.companyName}"`);
+  console.log(`  Ticker: ${price.ticker}`);
+  console.log(`  Price: $${price.price}`);
+  console.log(`  Company: ${price.companyName}`);
+});
+
+tap.test('should include company names in batch price request', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  console.log('\n🏢 Testing Company Name Feature: Batch Request');
+
+  const prices = await stockService.getPrices({
+    tickers: ['AAPL', 'MSFT', 'GOOGL']
+  });
+
+  expect(prices).toBeArray();
+  expect(prices.length).toBeGreaterThan(0);
+
+  console.log(`✓ Fetched ${prices.length} prices with company names:`);
+
+  for (const price of prices) {
+    expect(price.companyName).not.toEqual(undefined);
+    expect(typeof price.companyName).toEqual('string');
+    console.log(`  ${price.ticker.padEnd(6)} - ${price.companyName}`);
+  }
+});
+
+tap.test('should include company name in historical data', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  console.log('\n🏢 Testing Company Name Feature: Historical Data');
+
+  const prices = await stockService.getData({
+    type: 'historical',
+    ticker: 'TSLA',
+    from: new Date('2025-10-01'),
+    to: new Date('2025-10-05')
+  });
+
+  expect(prices).toBeArray();
+  const historicalPrices = prices as opendata.IStockPrice[];
+  expect(historicalPrices.length).toBeGreaterThan(0);
+
+  // All historical records should have the same company name
+  for (const price of historicalPrices) {
+    expect(price.companyName).not.toEqual(undefined);
+    expect(typeof price.companyName).toEqual('string');
+  }
+
+  const firstPrice = historicalPrices[0];
+  console.log(`✓ Historical records include company name: "${firstPrice.companyName}"`);
+  console.log(`  Ticker: ${firstPrice.ticker}`);
+  console.log(`  Records: ${historicalPrices.length}`);
+  console.log(`  Date range: ${historicalPrices[historicalPrices.length - 1].timestamp.toISOString().split('T')[0]} to ${firstPrice.timestamp.toISOString().split('T')[0]}`);
+});
+
+tap.test('should verify company name is included with zero extra API calls', async () => {
+  if (!marketstackProvider) {
+    console.log('⚠️  Skipping - Marketstack provider not initialized');
+    return;
+  }
+
+  console.log('\n⚡ Testing Company Name Efficiency: Zero Extra API Calls');
+
+  // Clear cache to ensure we're making fresh API calls
+  stockService.clearCache();
+
+  // Single request timing
+  const start1 = Date.now();
+  const singlePrice = await stockService.getPrice({ ticker: 'AMZN' });
+  const duration1 = Date.now() - start1;
+
+  expect(singlePrice.companyName).not.toEqual(undefined);
+
+  // Batch request timing
+  stockService.clearCache();
+  const start2 = Date.now();
+  const batchPrices = await stockService.getPrices({ tickers: ['NVDA', 'AMD', 'INTC'] });
+  const duration2 = Date.now() - start2;
+
+  for (const price of batchPrices) {
+    expect(price.companyName).not.toEqual(undefined);
+  }
+
+  console.log(`✓ Single request (with company name): ${duration1}ms`);
+  console.log(`✓ Batch request (with company names): ${duration2}ms`);
+  console.log(`✓ Company names included in standard EOD response - zero extra calls!`);
+  console.log(`  Single: ${singlePrice.ticker} - "${singlePrice.companyName}"`);
+  for (const price of batchPrices) {
+    console.log(`  Batch:  ${price.ticker} - "${price.companyName}"`);
+  }
+});
+
+export default tap.start();

test/test.secedgar.provider.node.ts

@@ -0,0 +1,261 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as opendata from '../ts/index.js';
+
+// Test configuration
+const TEST_USER_AGENT = 'fin.cx test@fin.cx';
+const TEST_TICKER = 'AAPL'; // Apple Inc - well-known test case
+const RATE_LIMIT_DELAY = 150; // 150ms between requests (< 10 req/sec)
+
+tap.test('SEC EDGAR Provider - Constructor', async () => {
+  await tap.test('should create provider with valid User-Agent', async () => {
+    const provider = new opendata.SecEdgarProvider({
+      userAgent: TEST_USER_AGENT
+    });
+
+    expect(provider.name).toEqual('SEC EDGAR');
+    expect(provider.priority).toEqual(100);
+    expect(provider.requiresAuth).toBe(false);
+    expect(provider.rateLimit?.requestsPerMinute).toEqual(600);
+  });
+
+  await tap.test('should throw error if User-Agent is missing', async () => {
+    expect(() => {
+      new opendata.SecEdgarProvider({
+        userAgent: ''
+      });
+    }).toThrow('User-Agent is required');
+  });
+
+  await tap.test('should throw error if User-Agent format is invalid', async () => {
+    expect(() => {
+      new opendata.SecEdgarProvider({
+        userAgent: 'InvalidFormat'
+      });
+    }).toThrow('Invalid User-Agent format');
+  });
+
+  await tap.test('should accept valid User-Agent with space and email', async () => {
+    const provider = new opendata.SecEdgarProvider({
+      userAgent: 'MyCompany contact@example.com'
+    });
+
+    expect(provider).toBeInstanceOf(opendata.SecEdgarProvider);
+  });
+});
+
+tap.test('SEC EDGAR Provider - Availability', async () => {
+  const provider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+
+  await tap.test('should report as available', async () => {
+    const isAvailable = await provider.isAvailable();
+    expect(isAvailable).toBe(true);
+  });
+});
+
+tap.test('SEC EDGAR Provider - Fetch Fundamentals', async () => {
+  const provider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT,
+    timeout: 30000
+  });
+
+  await tap.test('should fetch fundamentals for Apple (AAPL)', async () => {
+    const fundamentals = await provider.fetchData({
+      type: 'fundamentals-current',
+      ticker: TEST_TICKER
+    });
+
+    // Verify structure
+    expect(fundamentals).toBeDefined();
+    expect(fundamentals).not.toBeInstanceOf(Array);
+
+    const data = fundamentals as opendata.IStockFundamentals;
+
+    // Basic fields
+    expect(data.ticker).toEqual('AAPL');
+    expect(data.cik).toBeDefined();
+    expect(data.companyName).toEqual('Apple Inc.');
+    expect(data.provider).toEqual('SEC EDGAR');
+    expect(data.timestamp).toBeInstanceOf(Date);
+    expect(data.fetchedAt).toBeInstanceOf(Date);
+
+    // Financial metrics (Apple should have all of these)
+    expect(data.earningsPerShareDiluted).toBeDefined();
+    expect(data.earningsPerShareDiluted).toBeGreaterThan(0);
+
+    expect(data.sharesOutstanding).toBeDefined();
+    expect(data.sharesOutstanding).toBeGreaterThan(0);
+
+    expect(data.revenue).toBeDefined();
+    expect(data.revenue).toBeGreaterThan(0);
+
+    expect(data.netIncome).toBeDefined();
+    expect(data.assets).toBeDefined();
+    expect(data.assets).toBeGreaterThan(0);
+
+    expect(data.liabilities).toBeDefined();
+    expect(data.stockholdersEquity).toBeDefined();
+
+    // Metadata
+    expect(data.fiscalYear).toBeDefined();
+
+    console.log('\n📊 Sample Apple Fundamentals:');
+    console.log(`  Company: ${data.companyName} (CIK: ${data.cik})`);
+    console.log(`  EPS (Diluted): $${data.earningsPerShareDiluted?.toFixed(2)}`);
+    console.log(`  Shares Outstanding: ${(data.sharesOutstanding! / 1_000_000_000).toFixed(2)}B`);
+    console.log(`  Revenue: $${(data.revenue! / 1_000_000_000).toFixed(2)}B`);
+    console.log(`  Net Income: $${(data.netIncome! / 1_000_000_000).toFixed(2)}B`);
+    console.log(`  Assets: $${(data.assets! / 1_000_000_000).toFixed(2)}B`);
+    console.log(`  Fiscal Year: ${data.fiscalYear}`);
+  });
+
+  await tap.test('should throw error for invalid ticker', async () => {
+    try {
+      await provider.fetchData({
+        type: 'fundamentals-current',
+        ticker: 'INVALIDTICKER123456'
+      });
+      throw new Error('Should have thrown error');
+    } catch (error) {
+      expect(error.message).toContain('CIK not found');
+    }
+  });
+});
+
+tap.test('SEC EDGAR Provider - Batch Fetch', async () => {
+  const provider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT,
+    timeout: 30000
+  });
+
+  await tap.test('should fetch fundamentals for multiple tickers', async () => {
+    const result = await provider.fetchData({
+      type: 'fundamentals-batch',
+      tickers: ['AAPL', 'MSFT']
+    });
+
+    expect(result).toBeInstanceOf(Array);
+
+    const fundamentalsList = result as opendata.IStockFundamentals[];
+    expect(fundamentalsList.length).toEqual(2);
+
+    // Check Apple
+    const apple = fundamentalsList.find(f => f.ticker === 'AAPL');
+    expect(apple).toBeDefined();
+    expect(apple!.companyName).toEqual('Apple Inc.');
+    expect(apple!.earningsPerShareDiluted).toBeGreaterThan(0);
+
+    // Check Microsoft
+    const microsoft = fundamentalsList.find(f => f.ticker === 'MSFT');
+    expect(microsoft).toBeDefined();
+    expect(microsoft!.companyName).toContain('Microsoft');
+    expect(microsoft!.earningsPerShareDiluted).toBeGreaterThan(0);
+
+    console.log('\n📊 Batch Fetch Results:');
+    fundamentalsList.forEach(f => {
+      console.log(`  ${f.ticker}: ${f.companyName} - EPS: $${f.earningsPerShareDiluted?.toFixed(2)}`);
+    });
+  });
+});
+
+tap.test('SEC EDGAR Provider - CIK Caching', async () => {
+  const provider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+
+  await tap.test('should cache CIK lookups', async () => {
+    // Clear cache first
+    provider.clearCache();
+
+    let stats = provider.getCacheStats();
+    expect(stats.cikCacheSize).toEqual(0);
+
+    // First fetch (should populate cache)
+    await provider.fetchData({
+      type: 'fundamentals-current',
+      ticker: 'AAPL'
+    });
+
+    stats = provider.getCacheStats();
+    expect(stats.cikCacheSize).toBeGreaterThan(0);
+
+    console.log(`\n💾 CIK Cache: ${stats.cikCacheSize} entries`);
+  });
+
+  await tap.test('should clear cache', async () => {
+    provider.clearCache();
+
+    const stats = provider.getCacheStats();
+    expect(stats.cikCacheSize).toEqual(0);
+    expect(stats.hasTickerList).toBe(false);
+  });
+});
+
+tap.test('SEC EDGAR Provider - Rate Limiting', async () => {
+  const provider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+
+  await tap.test('should handle multiple rapid requests without exceeding rate limit', async () => {
+    // Make 5 requests in succession
+    // Rate limiter should ensure we don't exceed 10 req/sec
+    const tickers = ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'META'];
+    const startTime = Date.now();
+
+    const promises = tickers.map(ticker =>
+      provider.fetchData({
+        type: 'fundamentals-current',
+        ticker
+      })
+    );
+
+    const results = await Promise.all(promises);
+    const duration = Date.now() - startTime;
+
+    expect(results.length).toEqual(5);
+    console.log(`\n⏱️  5 requests completed in ${duration}ms (avg: ${Math.round(duration / 5)}ms/request)`);
+
+    // Verify all results are valid
+    results.forEach((result, index) => {
+      expect(result).toBeDefined();
+      const data = result as opendata.IStockFundamentals;
+      expect(data.ticker).toEqual(tickers[index]);
+      expect(data.earningsPerShareDiluted).toBeGreaterThan(0);
+    });
+  });
+});
+
+tap.test('SEC EDGAR Provider - Market Cap Calculation', async () => {
+  const provider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+
+  await tap.test('should provide data needed for market cap calculation', async () => {
+    const fundamentals = await provider.fetchData({
+      type: 'fundamentals-current',
+      ticker: 'AAPL'
+    }) as opendata.IStockFundamentals;
+
+    expect(fundamentals.sharesOutstanding).toBeDefined();
+    expect(fundamentals.earningsPerShareDiluted).toBeDefined();
+
+    // Simulate current price (in real usage, this comes from price provider)
+    const simulatedPrice = 270.37;
+
+    // Calculate market cap
+    const marketCap = fundamentals.sharesOutstanding! * simulatedPrice;
+    const pe = simulatedPrice / fundamentals.earningsPerShareDiluted!;
+
+    console.log('\n💰 Calculated Metrics (with simulated price $270.37):');
+    console.log(`  Shares Outstanding: ${(fundamentals.sharesOutstanding! / 1_000_000_000).toFixed(2)}B`);
+    console.log(`  Market Cap: $${(marketCap / 1_000_000_000_000).toFixed(2)}T`);
+    console.log(`  EPS: $${fundamentals.earningsPerShareDiluted!.toFixed(2)}`);
+    console.log(`  P/E Ratio: ${pe.toFixed(2)}`);
+
+    expect(marketCap).toBeGreaterThan(0);
+    expect(pe).toBeGreaterThan(0);
+  });
+});
+
+export default tap.start();

test/test.stockdata.service.node.ts

@@ -0,0 +1,418 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as opendata from '../ts/index.js';
+
+const TEST_USER_AGENT = 'fin.cx test@fin.cx';
+
+tap.test('StockDataService - Basic Setup', async () => {
+  await tap.test('should create StockDataService instance', async () => {
+    const service = new opendata.StockDataService({
+      cache: {
+        priceTTL: 60000, // 1 minute for testing
+        fundamentalsTTL: 120000, // 2 minutes for testing
+        maxEntries: 100
+      }
+    });
+
+    expect(service).toBeInstanceOf(opendata.StockDataService);
+
+    const stats = service.getCacheStats();
+    expect(stats.priceCache.ttl).toEqual(60000);
+    expect(stats.fundamentalsCache.ttl).toEqual(120000);
+    expect(stats.maxEntries).toEqual(100);
+  });
+});
+
+tap.test('StockDataService - Provider Registration', async () => {
+  const service = new opendata.StockDataService();
+
+  await tap.test('should register price provider', async () => {
+    const yahooProvider = new opendata.YahooFinanceProvider();
+    service.registerPriceProvider(yahooProvider);
+
+    const providers = service.getPriceProviders();
+    expect(providers.length).toEqual(1);
+    expect(providers[0].name).toEqual('Yahoo Finance');
+  });
+
+  await tap.test('should register fundamentals provider', async () => {
+    const secProvider = new opendata.SecEdgarProvider({
+      userAgent: TEST_USER_AGENT
+    });
+    service.registerFundamentalsProvider(secProvider);
+
+    const providers = service.getFundamentalsProviders();
+    expect(providers.length).toEqual(1);
+    expect(providers[0].name).toEqual('SEC EDGAR');
+  });
+
+  await tap.test('should unregister providers', async () => {
+    service.unregisterPriceProvider('Yahoo Finance');
+    service.unregisterFundamentalsProvider('SEC EDGAR');
+
+    expect(service.getPriceProviders().length).toEqual(0);
+    expect(service.getFundamentalsProviders().length).toEqual(0);
+  });
+});
+
+tap.test('StockDataService - Price Fetching', async () => {
+  const service = new opendata.StockDataService();
+  const yahooProvider = new opendata.YahooFinanceProvider();
+  service.registerPriceProvider(yahooProvider);
+
+  await tap.test('should fetch single price', async () => {
+    const price = await service.getPrice('AAPL');
+
+    expect(price).toBeDefined();
+    expect(price.ticker).toEqual('AAPL');
+    expect(price.price).toBeGreaterThan(0);
+    expect(price.provider).toEqual('Yahoo Finance');
+    expect(price.timestamp).toBeInstanceOf(Date);
+
+    console.log(`\n💵 Single Price: ${price.ticker} = $${price.price.toFixed(2)}`);
+  });
+
+  await tap.test('should fetch batch prices', async () => {
+    const prices = await service.getPrices(['AAPL', 'MSFT', 'GOOGL']);
+
+    expect(prices).toBeInstanceOf(Array);
+    expect(prices.length).toBeGreaterThan(0);
+    expect(prices.length).toBeLessThanOrEqual(3);
+
+    console.log('\n💵 Batch Prices:');
+    prices.forEach(p => {
+      console.log(`  ${p.ticker}: $${p.price.toFixed(2)}`);
+    });
+  });
+
+  await tap.test('should cache prices', async () => {
+    // Clear cache
+    service.clearCache();
+
+    const stats1 = service.getCacheStats();
+    expect(stats1.priceCache.size).toEqual(0);
+
+    // Fetch price (should hit API)
+    const start1 = Date.now();
+    await service.getPrice('AAPL');
+    const duration1 = Date.now() - start1;
+
+    const stats2 = service.getCacheStats();
+    expect(stats2.priceCache.size).toEqual(1);
+
+    // Fetch again (should hit cache - much faster)
+    const start2 = Date.now();
+    await service.getPrice('AAPL');
+    const duration2 = Date.now() - start2;
+
+    expect(duration2).toBeLessThan(duration1);
+
+    console.log('\n⚡ Cache Performance:');
+    console.log(`  First fetch: ${duration1}ms`);
+    console.log(`  Cached fetch: ${duration2}ms`);
+    console.log(`  Speedup: ${Math.round(duration1 / duration2)}x`);
+  });
+});
+
+tap.test('StockDataService - Fundamentals Fetching', async () => {
+  const service = new opendata.StockDataService();
+  const secProvider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+  service.registerFundamentalsProvider(secProvider);
+
+  await tap.test('should fetch single fundamentals', async () => {
+    const fundamentals = await service.getFundamentals('AAPL');
+
+    expect(fundamentals).toBeDefined();
+    expect(fundamentals.ticker).toEqual('AAPL');
+    expect(fundamentals.companyName).toEqual('Apple Inc.');
+    expect(fundamentals.provider).toEqual('SEC EDGAR');
+    expect(fundamentals.earningsPerShareDiluted).toBeGreaterThan(0);
+    expect(fundamentals.sharesOutstanding).toBeGreaterThan(0);
+
+    console.log('\n📊 Single Fundamentals:');
+    console.log(`  ${fundamentals.ticker}: ${fundamentals.companyName}`);
+    console.log(`  EPS: $${fundamentals.earningsPerShareDiluted?.toFixed(2)}`);
+    console.log(`  Shares: ${(fundamentals.sharesOutstanding! / 1_000_000_000).toFixed(2)}B`);
+  });
+
+  await tap.test('should fetch batch fundamentals', async () => {
+    const fundamentals = await service.getBatchFundamentals(['AAPL', 'MSFT']);
+
+    expect(fundamentals).toBeInstanceOf(Array);
+    expect(fundamentals.length).toEqual(2);
+
+    console.log('\n📊 Batch Fundamentals:');
+    fundamentals.forEach(f => {
+      console.log(`  ${f.ticker}: ${f.companyName} - EPS: $${f.earningsPerShareDiluted?.toFixed(2)}`);
+    });
+  });
+
+  await tap.test('should cache fundamentals', async () => {
+    // Clear cache
+    service.clearCache();
+
+    const stats1 = service.getCacheStats();
+    expect(stats1.fundamentalsCache.size).toEqual(0);
+
+    // Fetch fundamentals (should hit API)
+    await service.getFundamentals('AAPL');
+
+    const stats2 = service.getCacheStats();
+    expect(stats2.fundamentalsCache.size).toEqual(1);
+  });
+});
+
+tap.test('StockDataService - Complete Stock Data', async () => {
+  const service = new opendata.StockDataService();
+
+  // Register both providers
+  const yahooProvider = new opendata.YahooFinanceProvider();
+  const secProvider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+
+  service.registerPriceProvider(yahooProvider);
+  service.registerFundamentalsProvider(secProvider);
+
+  await tap.test('should fetch complete stock data with string', async () => {
+    const data = await service.getStockData('AAPL');
+
+    expect(data).toBeDefined();
+    expect(data.ticker).toEqual('AAPL');
+    expect(data.price).toBeDefined();
+    expect(data.price.ticker).toEqual('AAPL');
+    expect(data.fundamentals).toBeDefined();
+    expect(data.fundamentals?.ticker).toEqual('AAPL');
+    expect(data.fetchedAt).toBeInstanceOf(Date);
+
+    // Check automatic enrichment
+    expect(data.fundamentals?.marketCap).toBeDefined();
+    expect(data.fundamentals?.priceToEarnings).toBeDefined();
+    expect(data.fundamentals?.marketCap).toBeGreaterThan(0);
+    expect(data.fundamentals?.priceToEarnings).toBeGreaterThan(0);
+
+    console.log('\n✨ Complete Stock Data (Auto-Enriched):');
+    console.log(`  ${data.ticker}: ${data.fundamentals?.companyName}`);
+    console.log(`  Price: $${data.price.price.toFixed(2)}`);
+    console.log(`  Market Cap: $${(data.fundamentals!.marketCap! / 1_000_000_000_000).toFixed(2)}T`);
+    console.log(`  P/E Ratio: ${data.fundamentals!.priceToEarnings!.toFixed(2)}`);
+  });
+
+  await tap.test('should fetch complete stock data with request object', async () => {
+    const data = await service.getStockData({
+      ticker: 'MSFT',
+      includeFundamentals: true,
+      enrichFundamentals: true
+    });
+
+    expect(data).toBeDefined();
+    expect(data.ticker).toEqual('MSFT');
+    expect(data.price).toBeDefined();
+    expect(data.fundamentals).toBeDefined();
+    expect(data.fundamentals?.marketCap).toBeDefined();
+    expect(data.fundamentals?.priceToEarnings).toBeDefined();
+  });
+
+  await tap.test('should fetch complete stock data without fundamentals', async () => {
+    const data = await service.getStockData({
+      ticker: 'GOOGL',
+      includeFundamentals: false
+    });
+
+    expect(data).toBeDefined();
+    expect(data.ticker).toEqual('GOOGL');
+    expect(data.price).toBeDefined();
+    expect(data.fundamentals).toBeUndefined();
+  });
+
+  await tap.test('should handle fundamentals fetch failure gracefully', async () => {
+    // Try a ticker that might not have fundamentals
+    const data = await service.getStockData({
+      ticker: 'BTC-USD', // Crypto - no SEC filings
+      includeFundamentals: true
+    });
+
+    expect(data).toBeDefined();
+    expect(data.price).toBeDefined();
+    // Fundamentals might be undefined due to error
+    console.log(`\n⚠️  ${data.ticker} - Price available, Fundamentals: ${data.fundamentals ? 'Yes' : 'No'}`);
+  });
+});
+
+tap.test('StockDataService - Batch Complete Stock Data', async () => {
+  const service = new opendata.StockDataService();
+
+  const yahooProvider = new opendata.YahooFinanceProvider();
+  const secProvider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+
+  service.registerPriceProvider(yahooProvider);
+  service.registerFundamentalsProvider(secProvider);
+
+  await tap.test('should fetch batch complete data with array', async () => {
+    const data = await service.getBatchStockData(['AAPL', 'MSFT']);
+
+    expect(data).toBeInstanceOf(Array);
+    expect(data.length).toEqual(2);
+
+    data.forEach(stock => {
+      expect(stock.ticker).toBeDefined();
+      expect(stock.price).toBeDefined();
+      expect(stock.fundamentals).toBeDefined();
+      expect(stock.fundamentals?.marketCap).toBeGreaterThan(0);
+      expect(stock.fundamentals?.priceToEarnings).toBeGreaterThan(0);
+    });
+
+    console.log('\n✨ Batch Complete Data:');
+    data.forEach(stock => {
+      console.log(`  ${stock.ticker}: Price $${stock.price.price.toFixed(2)}, P/E ${stock.fundamentals!.priceToEarnings!.toFixed(2)}`);
+    });
+  });
+
+  await tap.test('should fetch batch complete data with request object', async () => {
+    const data = await service.getBatchStockData({
+      tickers: ['AAPL', 'GOOGL'],
+      includeFundamentals: true,
+      enrichFundamentals: true
+    });
+
+    expect(data).toBeInstanceOf(Array);
+    expect(data.length).toEqual(2);
+
+    data.forEach(stock => {
+      expect(stock.fundamentals?.marketCap).toBeGreaterThan(0);
+    });
+  });
+
+  await tap.test('should fetch batch without enrichment', async () => {
+    const data = await service.getBatchStockData({
+      tickers: ['AAPL', 'MSFT'],
+      includeFundamentals: true,
+      enrichFundamentals: false
+    });
+
+    expect(data).toBeInstanceOf(Array);
+
+    // Check that fundamentals exist but enrichment might not be complete
+    data.forEach(stock => {
+      if (stock.fundamentals) {
+        expect(stock.fundamentals.ticker).toBeDefined();
+        expect(stock.fundamentals.companyName).toBeDefined();
+      }
+    });
+  });
+});
+
+tap.test('StockDataService - Health & Statistics', async () => {
+  const service = new opendata.StockDataService();
+
+  const yahooProvider = new opendata.YahooFinanceProvider();
+  const secProvider = new opendata.SecEdgarProvider({
+    userAgent: TEST_USER_AGENT
+  });
+
+  service.registerPriceProvider(yahooProvider);
+  service.registerFundamentalsProvider(secProvider);
+
+  await tap.test('should check providers health', async () => {
+    const health = await service.checkProvidersHealth();
+
+    expect(health.size).toEqual(2);
+    expect(health.get('Yahoo Finance (price)')).toBe(true);
+    expect(health.get('SEC EDGAR (fundamentals)')).toBe(true);
+
+    console.log('\n💚 Provider Health:');
+    health.forEach((isHealthy, name) => {
+      console.log(`  ${name}: ${isHealthy ? '✅ Healthy' : '❌ Unhealthy'}`);
+    });
+  });
+
+  await tap.test('should track provider statistics', async () => {
+    // Make some requests to generate stats
+    await service.getPrice('AAPL');
+    await service.getFundamentals('AAPL');
+
+    const stats = service.getProviderStats();
+
+    expect(stats.size).toEqual(2);
+
+    const yahooStats = stats.get('Yahoo Finance');
+    expect(yahooStats).toBeDefined();
+    expect(yahooStats!.type).toEqual('price');
+    expect(yahooStats!.successCount).toBeGreaterThan(0);
+
+    const secStats = stats.get('SEC EDGAR');
+    expect(secStats).toBeDefined();
+    expect(secStats!.type).toEqual('fundamentals');
+    expect(secStats!.successCount).toBeGreaterThan(0);
+
+    console.log('\n📈 Provider Statistics:');
+    stats.forEach((stat, name) => {
+      console.log(`  ${name} (${stat.type}): Success=${stat.successCount}, Errors=${stat.errorCount}`);
+    });
+  });
+
+  await tap.test('should clear all caches', async () => {
+    service.clearCache();
+
+    const stats = service.getCacheStats();
+    expect(stats.priceCache.size).toEqual(0);
+    expect(stats.fundamentalsCache.size).toEqual(0);
+  });
+});
+
+tap.test('StockDataService - Error Handling', async () => {
+  await tap.test('should throw error when no price provider available', async () => {
+    const service = new opendata.StockDataService();
+
+    try {
+      await service.getPrice('AAPL');
+      throw new Error('Should have thrown error');
+    } catch (error) {
+      expect(error.message).toContain('No price providers available');
+    }
+  });
+
+  await tap.test('should throw error when no fundamentals provider available', async () => {
+    const service = new opendata.StockDataService();
+
+    try {
+      await service.getFundamentals('AAPL');
+      throw new Error('Should have thrown error');
+    } catch (error) {
+      expect(error.message).toContain('No fundamentals providers available');
+    }
+  });
+
+  await tap.test('should handle invalid ticker for price', async () => {
+    const service = new opendata.StockDataService();
+    const yahooProvider = new opendata.YahooFinanceProvider();
+    service.registerPriceProvider(yahooProvider);
+
+    try {
+      await service.getPrice('INVALIDTICKER123456');
+      throw new Error('Should have thrown error');
+    } catch (error) {
+      expect(error.message).toContain('Failed to fetch price');
+    }
+  });
+
+  await tap.test('should handle invalid ticker for fundamentals', async () => {
+    const service = new opendata.StockDataService();
+    const secProvider = new opendata.SecEdgarProvider({
+      userAgent: TEST_USER_AGENT
+    });
+    service.registerFundamentalsProvider(secProvider);
+
+    try {
+      await service.getFundamentals('INVALIDTICKER123456');
+      throw new Error('Should have thrown error');
+    } catch (error) {
+      expect(error.message).toContain('CIK not found');
+    }
+  });
+});
+
+export default tap.start();

test/test.stocks.ts

@@ -0,0 +1,280 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as opendata from '../ts/index.js';
+
+// Test data
+const testTickers = ['AAPL', 'MSFT', 'GOOGL'];
+const invalidTicker = 'INVALID_TICKER_XYZ';
+
+let stockService: opendata.StockPriceService;
+let yahooProvider: opendata.YahooFinanceProvider;
+
+tap.test('should create StockPriceService instance', async () => {
+  stockService = new opendata.StockPriceService({
+    ttl: 30000, // 30 seconds cache
+    maxEntries: 100
+  });
+  expect(stockService).toBeInstanceOf(opendata.StockPriceService);
+});
+
+tap.test('should create YahooFinanceProvider instance', async () => {
+  yahooProvider = new opendata.YahooFinanceProvider({
+    enabled: true,
+    timeout: 10000,
+    retryAttempts: 2,
+    retryDelay: 500
+  });
+  expect(yahooProvider).toBeInstanceOf(opendata.YahooFinanceProvider);
+  expect(yahooProvider.name).toEqual('Yahoo Finance');
+  expect(yahooProvider.requiresAuth).toEqual(false);
+});
+
+tap.test('should register Yahoo provider with the service', async () => {
+  stockService.register(yahooProvider);
+  const providers = stockService.getAllProviders();
+  expect(providers).toContainEqual(yahooProvider);
+  expect(stockService.getProvider('Yahoo Finance')).toEqual(yahooProvider);
+});
+
+tap.test('should check provider health', async () => {
+  const health = await stockService.checkProvidersHealth();
+  expect(health.get('Yahoo Finance')).toEqual(true);
+});
+
+tap.test('should fetch single stock price', async () => {
+  const price = await stockService.getPrice({ ticker: 'AAPL' });
+  
+  expect(price).toHaveProperty('ticker');
+  expect(price).toHaveProperty('price');
+  expect(price).toHaveProperty('currency');
+  expect(price).toHaveProperty('change');
+  expect(price).toHaveProperty('changePercent');
+  expect(price).toHaveProperty('previousClose');
+  expect(price).toHaveProperty('timestamp');
+  expect(price).toHaveProperty('provider');
+  expect(price).toHaveProperty('marketState');
+  
+  expect(price.ticker).toEqual('AAPL');
+  expect(price.price).toBeGreaterThan(0);
+  expect(price.provider).toEqual('Yahoo Finance');
+  expect(price.timestamp).toBeInstanceOf(Date);
+});
+
+tap.test('should fetch multiple stock prices', async () => {
+  const prices = await stockService.getPrices({ 
+    tickers: testTickers 
+  });
+  
+  expect(prices).toBeArray();
+  expect(prices.length).toBeGreaterThan(0);
+  expect(prices.length).toBeLessThanOrEqual(testTickers.length);
+  
+  for (const price of prices) {
+    expect(testTickers).toContain(price.ticker);
+    expect(price.price).toBeGreaterThan(0);
+    expect(price.provider).toEqual('Yahoo Finance');
+  }
+});
+
+tap.test('should serve cached prices on subsequent requests', async () => {
+  // First request - should hit the API
+  const firstRequest = await stockService.getPrice({ ticker: 'AAPL' });
+  
+  // Second request - should be served from cache
+  const secondRequest = await stockService.getPrice({ ticker: 'AAPL' });
+  
+  expect(secondRequest.ticker).toEqual(firstRequest.ticker);
+  expect(secondRequest.price).toEqual(firstRequest.price);
+  expect(secondRequest.timestamp).toEqual(firstRequest.timestamp);
+});
+
+tap.test('should handle invalid ticker gracefully', async () => {
+  try {
+    await stockService.getPrice({ ticker: invalidTicker });
+    throw new Error('Should have thrown an error for invalid ticker');
+  } catch (error) {
+    expect(error.message).toInclude('Failed to fetch price');
+    expect(error.message).toInclude(invalidTicker);
+  }
+});
+
+tap.test('should support market checking', async () => {
+  expect(yahooProvider.supportsMarket('US')).toEqual(true);
+  expect(yahooProvider.supportsMarket('UK')).toEqual(true);
+  expect(yahooProvider.supportsMarket('DE')).toEqual(true);
+  expect(yahooProvider.supportsMarket('INVALID')).toEqual(false);
+});
+
+tap.test('should validate ticker format', async () => {
+  expect(yahooProvider.supportsTicker('AAPL')).toEqual(true);
+  expect(yahooProvider.supportsTicker('MSFT')).toEqual(true);
+  expect(yahooProvider.supportsTicker('BRK.B')).toEqual(true);
+  expect(yahooProvider.supportsTicker('123456789012')).toEqual(false);
+  expect(yahooProvider.supportsTicker('invalid@ticker')).toEqual(false);
+});
+
+tap.test('should get provider statistics', async () => {
+  const stats = stockService.getProviderStats();
+  const yahooStats = stats.get('Yahoo Finance');
+  
+  expect(yahooStats).not.toEqual(undefined);
+  expect(yahooStats.successCount).toBeGreaterThan(0);
+  expect(yahooStats.errorCount).toBeGreaterThanOrEqual(0);
+});
+
+tap.test('should clear cache', async () => {
+  // Ensure we have something in cache
+  await stockService.getPrice({ ticker: 'AAPL' });
+  
+  // Clear cache
+  stockService.clearCache();
+  
+  // Next request should hit the API again (we can't directly test this, 
+  // but we can verify the method doesn't throw)
+  const price = await stockService.getPrice({ ticker: 'AAPL' });
+  expect(price).not.toEqual(undefined);
+});
+
+tap.test('should handle provider unavailability', async () => {
+  // Clear cache first to ensure we don't get cached results
+  stockService.clearCache();
+  
+  // Unregister all providers
+  stockService.unregister('Yahoo Finance');
+  
+  try {
+    // Use a different ticker to avoid any caching
+    await stockService.getPrice({ ticker: 'TSLA' });
+    throw new Error('Should have thrown an error with no providers');
+  } catch (error: any) {
+    expect(error.message).toEqual('No stock price providers available');
+  }
+});
+
+tap.test('should fetch major market indicators', async () => {
+  // Re-register provider if needed
+  if (!stockService.getProvider('Yahoo Finance')) {
+    stockService.register(yahooProvider);
+  }
+  
+  const marketIndicators = [
+    // Indices
+    { ticker: '^GSPC', name: 'S&P 500' },
+    { ticker: '^IXIC', name: 'NASDAQ' },
+    { ticker: '^DJI', name: 'DOW Jones' },
+    // Tech Stocks
+    { ticker: 'AAPL', name: 'Apple' },
+    { ticker: 'AMZN', name: 'Amazon' },
+    { ticker: 'GOOGL', name: 'Google' },
+    { ticker: 'META', name: 'Meta' },
+    { ticker: 'MSFT', name: 'Microsoft' },
+    { ticker: 'PLTR', name: 'Palantir' },
+    // Crypto
+    { ticker: 'BTC-USD', name: 'Bitcoin' },
+    { ticker: 'ETH-USD', name: 'Ethereum' },
+    { ticker: 'ADA-USD', name: 'Cardano' },
+    // Forex & Commodities
+    { ticker: 'EURUSD=X', name: 'EUR/USD' },
+    { ticker: 'GC=F', name: 'Gold Futures' },
+    { ticker: 'CL=F', name: 'Crude Oil Futures' }
+  ];
+
+  console.log('\n📊 Current Market Values:');
+  console.log('═'.repeat(65));
+  
+  // Fetch all prices in batch for better performance
+  try {
+    const prices = await stockService.getPrices({ 
+      tickers: marketIndicators.map(i => i.ticker) 
+    });
+    
+    // Create a map for easy lookup
+    const priceMap = new Map(prices.map(p => [p.ticker, p]));
+    
+    // Check which tickers are missing and fetch them individually
+    const missingTickers: typeof marketIndicators = [];
+    for (const indicator of marketIndicators) {
+      if (!priceMap.has(indicator.ticker)) {
+        missingTickers.push(indicator);
+      }
+    }
+    
+    // Fetch missing tickers individually
+    if (missingTickers.length > 0) {
+      for (const indicator of missingTickers) {
+        try {
+          const price = await stockService.getPrice({ ticker: indicator.ticker });
+          priceMap.set(indicator.ticker, price);
+        } catch (error) {
+          // Ignore individual errors
+        }
+      }
+    }
+    
+    // Display all results with section headers
+    let lastSection = '';
+    for (const indicator of marketIndicators) {
+      // Add section headers
+      if (indicator.ticker.startsWith('^') && lastSection !== 'indices') {
+        console.log('\n📈 Market Indices');
+        console.log('─'.repeat(65));
+        lastSection = 'indices';
+      } else if (['AAPL', 'AMZN', 'GOOGL', 'META', 'MSFT', 'PLTR'].includes(indicator.ticker) && lastSection !== 'stocks') {
+        console.log('\n💻 Tech Stocks');
+        console.log('─'.repeat(65));
+        lastSection = 'stocks';
+      } else if (indicator.ticker.includes('-USD') && lastSection !== 'crypto') {
+        console.log('\n🪙 Cryptocurrencies');
+        console.log('─'.repeat(65));
+        lastSection = 'crypto';
+      } else if ((indicator.ticker.includes('=') || indicator.ticker.includes('=F')) && lastSection !== 'forex') {
+        console.log('\n💱 Forex & Commodities');
+        console.log('─'.repeat(65));
+        lastSection = 'forex';
+      }
+      
+      const price = priceMap.get(indicator.ticker);
+      if (price) {
+        const changeSymbol = price.change >= 0 ? '↑' : '↓';
+        const changeColor = price.change >= 0 ? '\x1b[32m' : '\x1b[31m'; // Green or Red
+        const resetColor = '\x1b[0m';
+        
+        console.log(
+          `${indicator.name.padEnd(20)} ${price.price.toLocaleString('en-US', { 
+            minimumFractionDigits: 2, 
+            maximumFractionDigits: indicator.name.includes('coin') || indicator.name.includes('EUR') || indicator.name === 'Cardano' ? 4 : 2 
+          }).padStart(12)} ${changeColor}${changeSymbol} ${price.change >= 0 ? '+' : ''}${price.change.toFixed(2)} (${price.changePercent >= 0 ? '+' : ''}${price.changePercent.toFixed(2)}%)${resetColor}`
+        );
+      } else {
+        console.log(`${indicator.name.padEnd(20)} Data not available`);
+      }
+    }
+  } catch (error) {
+    console.log('Error fetching market data:', error);
+    // Fallback to individual fetches
+    for (const indicator of marketIndicators) {
+      try {
+        const price = await stockService.getPrice({ ticker: indicator.ticker });
+        const changeSymbol = price.change >= 0 ? '↑' : '↓';
+        const changeColor = price.change >= 0 ? '\x1b[32m' : '\x1b[31m';
+        const resetColor = '\x1b[0m';
+        
+        console.log(
+          `${indicator.name.padEnd(20)} ${price.price.toLocaleString('en-US', { 
+            minimumFractionDigits: 2, 
+            maximumFractionDigits: indicator.name.includes('coin') || indicator.name.includes('EUR') || indicator.name === 'Cardano' ? 4 : 2 
+          }).padStart(12)} ${changeColor}${changeSymbol} ${price.change >= 0 ? '+' : ''}${price.change.toFixed(2)} (${price.changePercent >= 0 ? '+' : ''}${price.changePercent.toFixed(2)}%)${resetColor}`
+        );
+      } catch (error) {
+        console.log(`${indicator.name.padEnd(20)} Error fetching data`);
+      }
+    }
+  }
+  
+  console.log('═'.repeat(65));
+  console.log(`Last updated: ${new Date().toLocaleString()}\n`);
+  
+  // Test passes if we successfully fetch at least some indicators
+  expect(true).toEqual(true);
+});
+
+export default tap.start();

test/test.ts

@@ -1,12 +1,23 @@
-import { expect, expectAsync, tap } from '@push.rocks/tapbundle';
+import { expect, tap } from '@git.zone/tstest/tapbundle';
 import * as opendata from '../ts/index.js'
+import * as paths from '../ts/paths.js';
+import * as plugins from '../ts/plugins.js';
 
 import { BusinessRecord } from '../ts/classes.businessrecord.js';
 
+// Test configuration - explicit paths required
+const testNogitDir = plugins.path.join(paths.packageDir, '.nogit');
+const testDownloadDir = plugins.path.join(testNogitDir, 'downloads');
+const testGermanBusinessDataDir = plugins.path.join(testNogitDir, 'germanbusinessdata');
+
 let testOpenDataInstance: opendata.OpenData;
 
 tap.test('first test', async () => {
-  testOpenDataInstance = new opendata.OpenData();
+  testOpenDataInstance = new opendata.OpenData({
+    nogitDir: testNogitDir,
+    downloadDir: testDownloadDir,
+    germanBusinessDataDir: testGermanBusinessDataDir
+  });
   expect(testOpenDataInstance).toBeInstanceOf(opendata.OpenData);
 });
 

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/opendata',
-  version: '1.5.2',
+  version: '3.2.0',
-  description: 'A comprehensive TypeScript library that manages open business data for German companies by integrating MongoDB, processing JSONL bulk data, and automating browser interactions for Handelsregister data retrieval.'
+  description: 'A comprehensive TypeScript library for accessing business data and real-time financial information. Features include German company data management with MongoDB integration, JSONL bulk processing, automated Handelsregister interactions, and real-time stock market data from multiple providers.'
 }

ts/classes.handelsregister.ts

@@ -1,7 +1,6 @@
 import type { BusinessRecord } from './classes.businessrecord.js';
 import type { OpenData } from './classes.main.opendata.js';
 import * as plugins from './plugins.js';
-import * as paths from './paths.js';
 
 /**
  * the HandlesRegister exposed as a class
@@ -9,13 +8,16 @@ import * as paths from './paths.js';
 export class HandelsRegister {
   private openDataRef: OpenData;
   private asyncExecutionStack = new plugins.lik.AsyncExecutionStack();
-  private uniqueDowloadFolder = plugins.path.join(paths.downloadDir, plugins.smartunique.uniSimple()); 
+  private downloadDir: string;
+  private uniqueDowloadFolder: string;
 
   // Puppeteer wrapper instance
   public smartbrowserInstance = new plugins.smartbrowser.SmartBrowser();
 
-  constructor(openDataRef: OpenData) {
+  constructor(openDataRef: OpenData, downloadDirArg: string) {
     this.openDataRef = openDataRef;
+    this.downloadDir = downloadDirArg;
+    this.uniqueDowloadFolder = plugins.path.join(this.downloadDir, plugins.smartunique.uniSimple());
   }
 
   public async start() {
@@ -76,7 +78,7 @@ export class HandelsRegister {
         timeout: 30000,
       })
       .catch(async (err) => {
-        await pageArg.screenshot({ path: paths.downloadDir + '/error.png' });
+        await pageArg.screenshot({ path: this.downloadDir + '/error.png' });
         throw err;
       });
 

ts/classes.jsonldata.ts

@@ -1,5 +1,4 @@
 import * as plugins from './plugins.js';
-import * as paths from './paths.js';
 import type { OpenData } from './classes.main.opendata.js';
 
 export type SeedEntryType = {
@@ -41,8 +40,11 @@ export type SeedEntryType = {
 };
 
 export class JsonlDataProcessor<T> {
+  private germanBusinessDataDir: string;
   public forEachFunction: (entryArg: T) => Promise<void>;
-  constructor(forEachFunctionArg: typeof this.forEachFunction) {
+
+  constructor(germanBusinessDataDirArg: string, forEachFunctionArg: typeof this.forEachFunction) {
+    this.germanBusinessDataDir = germanBusinessDataDirArg;
     this.forEachFunction = forEachFunctionArg;
   }
 
@@ -51,9 +53,9 @@ export class JsonlDataProcessor<T> {
     dataUrlArg = 'https://daten.offeneregister.de/de_companies_ocdata.jsonl.bz2'
   ) {
     const done = plugins.smartpromise.defer();
-    const dataExists = await plugins.smartfile.fs.isDirectory(paths.germanBusinessDataDir);
+    const dataExists = await plugins.smartfile.fs.isDirectory(this.germanBusinessDataDir);
     if (!dataExists) {
-      await plugins.smartfile.fs.ensureDir(paths.germanBusinessDataDir);
+      await plugins.smartfile.fs.ensureDir(this.germanBusinessDataDir);
     } else {
     }
 

ts/classes.main.opendata.ts

@@ -4,16 +4,39 @@ import { JsonlDataProcessor, type SeedEntryType } from './classes.jsonldata.js';
 import * as paths from './paths.js';
 import * as plugins from './plugins.js';
 
+export interface IOpenDataConfig {
+  downloadDir: string;
+  germanBusinessDataDir: string;
+  nogitDir: string;
+}
+
 export class OpenData {
   public db: plugins.smartdata.SmartdataDb;
-  private serviceQenv = new plugins.qenv.Qenv(paths.packageDir, paths.nogitDir);
+  private serviceQenv: plugins.qenv.Qenv;
+  private config: IOpenDataConfig;
 
   public jsonLDataProcessor: JsonlDataProcessor<SeedEntryType>;
   public handelsregister: HandelsRegister;
 
   public CBusinessRecord = plugins.smartdata.setDefaultManagerForDoc(this, BusinessRecord);
 
+  constructor(configArg: IOpenDataConfig) {
+    if (!configArg) {
+      throw new Error('@fin.cx/opendata: Configuration is required. You must provide downloadDir, germanBusinessDataDir, and nogitDir paths.');
+    }
+    if (!configArg.downloadDir || !configArg.germanBusinessDataDir || !configArg.nogitDir) {
+      throw new Error('@fin.cx/opendata: All directory paths are required (downloadDir, germanBusinessDataDir, nogitDir).');
+    }
+    this.config = configArg;
+    this.serviceQenv = new plugins.qenv.Qenv(paths.packageDir, this.config.nogitDir);
+  }
+
   public async start() {
+    // Ensure configured directories exist
+    await plugins.smartfile.fs.ensureDir(this.config.nogitDir);
+    await plugins.smartfile.fs.ensureDir(this.config.downloadDir);
+    await plugins.smartfile.fs.ensureDir(this.config.germanBusinessDataDir);
+
     this.db = new plugins.smartdata.SmartdataDb({
       mongoDbUrl: await this.serviceQenv.getEnvVarOnDemand('MONGODB_URL'),
       mongoDbName: await this.serviceQenv.getEnvVarOnDemand('MONGODB_NAME'),
@@ -21,18 +44,21 @@ export class OpenData {
       mongoDbPass: await this.serviceQenv.getEnvVarOnDemand('MONGODB_PASS'),
     });
     await this.db.init();
-    this.jsonLDataProcessor = new JsonlDataProcessor(async (entryArg) => {
+    this.jsonLDataProcessor = new JsonlDataProcessor(
-      const businessRecord = new this.CBusinessRecord();
+      this.config.germanBusinessDataDir,
-      businessRecord.id = await this.CBusinessRecord.getNewId();
+      async (entryArg) => {
-      businessRecord.data.name = entryArg.name;
+        const businessRecord = new this.CBusinessRecord();
-      businessRecord.data.germanParsedRegistration = {
+        businessRecord.id = await this.CBusinessRecord.getNewId();
-        court: entryArg.all_attributes.registered_office,
+        businessRecord.data.name = entryArg.name;
-        number: entryArg.all_attributes._registerNummer,
+        businessRecord.data.germanParsedRegistration = {
-        type: entryArg.all_attributes._registerArt as 'HRA' | 'HRB',
+          court: entryArg.all_attributes.registered_office,
-      };
+          number: entryArg.all_attributes._registerNummer,
-      await businessRecord.save();
+          type: entryArg.all_attributes._registerArt as 'HRA' | 'HRB',
-    });
+        };
-    this.handelsregister = new HandelsRegister(this);
+        await businessRecord.save();
+      }
+    );
+    this.handelsregister = new HandelsRegister(this, this.config.downloadDir);
     await this.handelsregister.start();
   }
 

ts/index.ts

@@ -1 +1,2 @@
 export * from './classes.main.opendata.js';
+export * from './stocks/index.js';

ts/paths.ts

@@ -4,12 +4,3 @@ export const packageDir = plugins.path.join(
   plugins.smartpath.get.dirnameFromImportMetaUrl(import.meta.url),
   '../'
 );
-
-export const nogitDir = plugins.path.join(packageDir, './.nogit/');
-plugins.smartfile.fs.ensureDirSync(nogitDir);
-
-export const downloadDir = plugins.path.join(nogitDir, 'downloads');
-plugins.smartfile.fs.ensureDirSync(downloadDir);
-
-
-export const germanBusinessDataDir = plugins.path.join(nogitDir, 'germanbusinessdata');

ts/plugins.ts

@@ -14,6 +14,7 @@ import * as smartbrowser from '@push.rocks/smartbrowser';
 import * as smartdata from '@push.rocks/smartdata';
 import * as smartdelay from '@push.rocks/smartdelay';
 import * as smartfile from '@push.rocks/smartfile';
+import * as smartlog from '@push.rocks/smartlog';
 import * as smartpath from '@push.rocks/smartpath';
 import * as smartpromise from '@push.rocks/smartpromise';
 import * as smartrequest from '@push.rocks/smartrequest';
@@ -30,6 +31,7 @@ export {
   smartdata,
   smartdelay,
   smartfile,
+  smartlog,
   smartpath,
   smartpromise,
   smartrequest,

ts/stocks/classes.baseproviderservice.ts

@@ -0,0 +1,296 @@
+import * as plugins from '../plugins.js';
+
+/**
+ * Base provider entry for tracking provider state
+ */
+export interface IBaseProviderEntry<TProvider> {
+  provider: TProvider;
+  config: IBaseProviderConfig;
+  lastError?: Error;
+  lastErrorTime?: Date;
+  successCount: number;
+  errorCount: number;
+}
+
+/**
+ * Base provider configuration
+ */
+export interface IBaseProviderConfig {
+  enabled: boolean;
+  priority: number;
+  timeout?: number;
+  retryAttempts?: number;
+  retryDelay?: number;
+  cacheTTL?: number;
+}
+
+/**
+ * Base provider interface
+ */
+export interface IBaseProvider {
+  name: string;
+  priority: number;
+  isAvailable(): Promise<boolean>;
+  readonly requiresAuth: boolean;
+  readonly rateLimit?: {
+    requestsPerMinute: number;
+    requestsPerDay?: number;
+  };
+}
+
+/**
+ * Cache entry for any data type
+ */
+export interface IBaseCacheEntry<TData> {
+  data: TData;
+  timestamp: Date;
+  ttl: number;
+}
+
+/**
+ * Base service for managing data providers with caching
+ * Shared logic extracted from StockPriceService and FundamentalsService
+ */
+export abstract class BaseProviderService<TProvider extends IBaseProvider, TData> {
+  protected providers = new Map<string, IBaseProviderEntry<TProvider>>();
+  protected cache = new Map<string, IBaseCacheEntry<TData>>();
+  protected logger = console;
+
+  protected cacheConfig = {
+    ttl: 60000, // Default 60 seconds
+    maxEntries: 10000
+  };
+
+  constructor(cacheConfig?: { ttl?: number; maxEntries?: number }) {
+    if (cacheConfig) {
+      this.cacheConfig = { ...this.cacheConfig, ...cacheConfig };
+    }
+  }
+
+  /**
+   * Register a provider
+   */
+  public register(provider: TProvider, config?: Partial<IBaseProviderConfig>): void {
+    const defaultConfig: IBaseProviderConfig = {
+      enabled: true,
+      priority: provider.priority,
+      timeout: 30000,
+      retryAttempts: 2,
+      retryDelay: 1000,
+      cacheTTL: this.cacheConfig.ttl
+    };
+
+    const mergedConfig = { ...defaultConfig, ...config };
+
+    this.providers.set(provider.name, {
+      provider,
+      config: mergedConfig,
+      successCount: 0,
+      errorCount: 0
+    });
+
+    console.log(`Registered provider: ${provider.name}`);
+  }
+
+  /**
+   * Unregister a provider
+   */
+  public unregister(providerName: string): void {
+    this.providers.delete(providerName);
+    console.log(`Unregistered provider: ${providerName}`);
+  }
+
+  /**
+   * Get a specific provider by name
+   */
+  public getProvider(name: string): TProvider | undefined {
+    return this.providers.get(name)?.provider;
+  }
+
+  /**
+   * Get all registered providers
+   */
+  public getAllProviders(): TProvider[] {
+    return Array.from(this.providers.values()).map(entry => entry.provider);
+  }
+
+  /**
+   * Get enabled providers sorted by priority
+   */
+  public getEnabledProviders(): TProvider[] {
+    return Array.from(this.providers.values())
+      .filter(entry => entry.config.enabled)
+      .sort((a, b) => (b.config.priority || 0) - (a.config.priority || 0))
+      .map(entry => entry.provider);
+  }
+
+  /**
+   * Check health of all providers
+   */
+  public async checkProvidersHealth(): Promise<Map<string, boolean>> {
+    const health = new Map<string, boolean>();
+
+    for (const [name, entry] of this.providers) {
+      if (!entry.config.enabled) {
+        health.set(name, false);
+        continue;
+      }
+
+      try {
+        const isAvailable = await entry.provider.isAvailable();
+        health.set(name, isAvailable);
+      } catch (error) {
+        health.set(name, false);
+        console.error(`Health check failed for ${name}:`, error);
+      }
+    }
+
+    return health;
+  }
+
+  /**
+   * Get provider statistics
+   */
+  public getProviderStats(): Map<
+    string,
+    {
+      successCount: number;
+      errorCount: number;
+      lastError?: string;
+      lastErrorTime?: Date;
+    }
+  > {
+    const stats = new Map();
+
+    for (const [name, entry] of this.providers) {
+      stats.set(name, {
+        successCount: entry.successCount,
+        errorCount: entry.errorCount,
+        lastError: entry.lastError?.message,
+        lastErrorTime: entry.lastErrorTime
+      });
+    }
+
+    return stats;
+  }
+
+  /**
+   * Clear all cached data
+   */
+  public clearCache(): void {
+    this.cache.clear();
+    console.log('Cache cleared');
+  }
+
+  /**
+   * Set cache TTL
+   */
+  public setCacheTTL(ttl: number): void {
+    this.cacheConfig.ttl = ttl;
+    console.log(`Cache TTL set to ${ttl}ms`);
+  }
+
+  /**
+   * Get cache statistics
+   */
+  public getCacheStats(): {
+    size: number;
+    maxEntries: number;
+    ttl: number;
+  } {
+    return {
+      size: this.cache.size,
+      maxEntries: this.cacheConfig.maxEntries,
+      ttl: this.cacheConfig.ttl
+    };
+  }
+
+  /**
+   * Fetch with retry logic
+   */
+  protected async fetchWithRetry<T>(
+    fetchFn: () => Promise<T>,
+    config: IBaseProviderConfig
+  ): Promise<T> {
+    const maxAttempts = config.retryAttempts || 1;
+    let lastError: Error | undefined;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fetchFn();
+      } catch (error) {
+        lastError = error as Error;
+
+        if (attempt < maxAttempts) {
+          const delay = (config.retryDelay || 1000) * attempt;
+          console.log(`Retry attempt ${attempt} after ${delay}ms`);
+          await plugins.smartdelay.delayFor(delay);
+        }
+      }
+    }
+
+    throw lastError || new Error('Unknown error during fetch');
+  }
+
+  /**
+   * Get from cache if not expired
+   */
+  protected getFromCache(key: string): TData | null {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      return null;
+    }
+
+    // Check if cache entry has expired
+    const age = Date.now() - entry.timestamp.getTime();
+    if (entry.ttl !== Infinity && age > entry.ttl) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.data;
+  }
+
+  /**
+   * Add to cache with TTL
+   */
+  protected addToCache(key: string, data: TData, ttl?: number): void {
+    // Enforce max entries limit
+    if (this.cache.size >= this.cacheConfig.maxEntries) {
+      // Remove oldest entry
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey) {
+        this.cache.delete(oldestKey);
+      }
+    }
+
+    this.cache.set(key, {
+      data,
+      timestamp: new Date(),
+      ttl: ttl || this.cacheConfig.ttl
+    });
+  }
+
+  /**
+   * Track successful fetch for provider
+   */
+  protected trackSuccess(providerName: string): void {
+    const entry = this.providers.get(providerName);
+    if (entry) {
+      entry.successCount++;
+    }
+  }
+
+  /**
+   * Track failed fetch for provider
+   */
+  protected trackError(providerName: string, error: Error): void {
+    const entry = this.providers.get(providerName);
+    if (entry) {
+      entry.errorCount++;
+      entry.lastError = error;
+      entry.lastErrorTime = new Date();
+    }
+  }
+}

ts/stocks/classes.fundamentalsservice.ts

@@ -0,0 +1,404 @@
+import * as plugins from '../plugins.js';
+import type {
+  IFundamentalsProvider,
+  IFundamentalsProviderConfig,
+  IFundamentalsProviderRegistry,
+  IStockFundamentals,
+  IFundamentalsRequest
+} from './interfaces/fundamentals.js';
+
+interface IProviderEntry {
+  provider: IFundamentalsProvider;
+  config: IFundamentalsProviderConfig;
+  lastError?: Error;
+  lastErrorTime?: Date;
+  successCount: number;
+  errorCount: number;
+}
+
+interface ICacheEntry {
+  fundamentals: IStockFundamentals | IStockFundamentals[];
+  timestamp: Date;
+  ttl: number;
+}
+
+/**
+ * Service for managing fundamental data providers and caching
+ * Parallel to StockPriceService but for fundamental data instead of prices
+ */
+export class FundamentalsService implements IFundamentalsProviderRegistry {
+  private providers = new Map<string, IProviderEntry>();
+  private cache = new Map<string, ICacheEntry>();
+  private logger = console;
+
+  private cacheConfig = {
+    ttl: 90 * 24 * 60 * 60 * 1000, // 90 days default (fundamentals change quarterly)
+    maxEntries: 10000
+  };
+
+  constructor(cacheConfig?: { ttl?: number; maxEntries?: number }) {
+    if (cacheConfig) {
+      this.cacheConfig = { ...this.cacheConfig, ...cacheConfig };
+    }
+  }
+
+  /**
+   * Register a fundamentals provider
+   */
+  public register(provider: IFundamentalsProvider, config?: IFundamentalsProviderConfig): void {
+    const defaultConfig: IFundamentalsProviderConfig = {
+      enabled: true,
+      priority: provider.priority,
+      timeout: 30000, // Longer timeout for fundamental data
+      retryAttempts: 2,
+      retryDelay: 1000,
+      cacheTTL: this.cacheConfig.ttl
+    };
+
+    const mergedConfig = { ...defaultConfig, ...config };
+
+    this.providers.set(provider.name, {
+      provider,
+      config: mergedConfig,
+      successCount: 0,
+      errorCount: 0
+    });
+
+    console.log(`Registered fundamentals provider: ${provider.name}`);
+  }
+
+  /**
+   * Unregister a provider
+   */
+  public unregister(providerName: string): void {
+    this.providers.delete(providerName);
+    console.log(`Unregistered fundamentals provider: ${providerName}`);
+  }
+
+  /**
+   * Get a specific provider by name
+   */
+  public getProvider(name: string): IFundamentalsProvider | undefined {
+    return this.providers.get(name)?.provider;
+  }
+
+  /**
+   * Get all registered providers
+   */
+  public getAllProviders(): IFundamentalsProvider[] {
+    return Array.from(this.providers.values()).map(entry => entry.provider);
+  }
+
+  /**
+   * Get enabled providers sorted by priority
+   */
+  public getEnabledProviders(): IFundamentalsProvider[] {
+    return Array.from(this.providers.values())
+      .filter(entry => entry.config.enabled)
+      .sort((a, b) => (b.config.priority || 0) - (a.config.priority || 0))
+      .map(entry => entry.provider);
+  }
+
+  /**
+   * Get fundamental data for a single ticker
+   */
+  public async getFundamentals(ticker: string): Promise<IStockFundamentals> {
+    const result = await this.getData({
+      type: 'fundamentals-current',
+      ticker
+    });
+    return result as IStockFundamentals;
+  }
+
+  /**
+   * Get fundamental data for multiple tickers
+   */
+  public async getBatchFundamentals(tickers: string[]): Promise<IStockFundamentals[]> {
+    const result = await this.getData({
+      type: 'fundamentals-batch',
+      tickers
+    });
+    return result as IStockFundamentals[];
+  }
+
+  /**
+   * Unified data fetching method
+   */
+  public async getData(
+    request: IFundamentalsRequest
+  ): Promise<IStockFundamentals | IStockFundamentals[]> {
+    const cacheKey = this.getCacheKey(request);
+    const cached = this.getFromCache(cacheKey);
+
+    if (cached) {
+      console.log(`Cache hit for ${this.getRequestDescription(request)}`);
+      return cached;
+    }
+
+    const providers = this.getEnabledProviders();
+    if (providers.length === 0) {
+      throw new Error('No fundamentals providers available');
+    }
+
+    let lastError: Error | undefined;
+
+    for (const provider of providers) {
+      const entry = this.providers.get(provider.name)!;
+
+      try {
+        const result = await this.fetchWithRetry(
+          () => provider.fetchData(request),
+          entry.config
+        );
+
+        entry.successCount++;
+
+        // Use provider-specific cache TTL or default
+        const ttl = entry.config.cacheTTL || this.cacheConfig.ttl;
+        this.addToCache(cacheKey, result, ttl);
+
+        console.log(`Successfully fetched ${this.getRequestDescription(request)} from ${provider.name}`);
+        return result;
+      } catch (error) {
+        entry.errorCount++;
+        entry.lastError = error as Error;
+        entry.lastErrorTime = new Date();
+        lastError = error as Error;
+
+        console.warn(
+          `Provider ${provider.name} failed for ${this.getRequestDescription(request)}: ${error.message}`
+        );
+      }
+    }
+
+    throw new Error(
+      `Failed to fetch ${this.getRequestDescription(request)} from all providers. Last error: ${lastError?.message}`
+    );
+  }
+
+  /**
+   * Enrich fundamentals with calculated metrics using current price
+   */
+  public async enrichWithPrice(
+    fundamentals: IStockFundamentals,
+    price: number
+  ): Promise<IStockFundamentals> {
+    const enriched = { ...fundamentals };
+
+    // Calculate market cap: price × shares outstanding
+    if (fundamentals.sharesOutstanding) {
+      enriched.marketCap = price * fundamentals.sharesOutstanding;
+    }
+
+    // Calculate P/E ratio: price / EPS
+    if (fundamentals.earningsPerShareDiluted && fundamentals.earningsPerShareDiluted > 0) {
+      enriched.priceToEarnings = price / fundamentals.earningsPerShareDiluted;
+    }
+
+    // Calculate price-to-book: market cap / stockholders equity
+    if (enriched.marketCap && fundamentals.stockholdersEquity && fundamentals.stockholdersEquity > 0) {
+      enriched.priceToBook = enriched.marketCap / fundamentals.stockholdersEquity;
+    }
+
+    return enriched;
+  }
+
+  /**
+   * Enrich batch fundamentals with prices
+   */
+  public async enrichBatchWithPrices(
+    fundamentalsList: IStockFundamentals[],
+    priceMap: Map<string, number>
+  ): Promise<IStockFundamentals[]> {
+    return Promise.all(
+      fundamentalsList.map(fundamentals => {
+        const price = priceMap.get(fundamentals.ticker);
+        if (price) {
+          return this.enrichWithPrice(fundamentals, price);
+        }
+        return Promise.resolve(fundamentals);
+      })
+    );
+  }
+
+  /**
+   * Check health of all providers
+   */
+  public async checkProvidersHealth(): Promise<Map<string, boolean>> {
+    const health = new Map<string, boolean>();
+
+    for (const [name, entry] of this.providers) {
+      if (!entry.config.enabled) {
+        health.set(name, false);
+        continue;
+      }
+
+      try {
+        const isAvailable = await entry.provider.isAvailable();
+        health.set(name, isAvailable);
+      } catch (error) {
+        health.set(name, false);
+        console.error(`Health check failed for ${name}:`, error);
+      }
+    }
+
+    return health;
+  }
+
+  /**
+   * Get provider statistics
+   */
+  public getProviderStats(): Map<
+    string,
+    {
+      successCount: number;
+      errorCount: number;
+      lastError?: string;
+      lastErrorTime?: Date;
+    }
+  > {
+    const stats = new Map();
+
+    for (const [name, entry] of this.providers) {
+      stats.set(name, {
+        successCount: entry.successCount,
+        errorCount: entry.errorCount,
+        lastError: entry.lastError?.message,
+        lastErrorTime: entry.lastErrorTime
+      });
+    }
+
+    return stats;
+  }
+
+  /**
+   * Clear all cached data
+   */
+  public clearCache(): void {
+    this.cache.clear();
+    console.log('Fundamentals cache cleared');
+  }
+
+  /**
+   * Set cache TTL
+   */
+  public setCacheTTL(ttl: number): void {
+    this.cacheConfig.ttl = ttl;
+    console.log(`Fundamentals cache TTL set to ${ttl}ms`);
+  }
+
+  /**
+   * Get cache statistics
+   */
+  public getCacheStats(): {
+    size: number;
+    maxEntries: number;
+    ttl: number;
+  } {
+    return {
+      size: this.cache.size,
+      maxEntries: this.cacheConfig.maxEntries,
+      ttl: this.cacheConfig.ttl
+    };
+  }
+
+  /**
+   * Fetch with retry logic
+   */
+  private async fetchWithRetry<T>(
+    fetchFn: () => Promise<T>,
+    config: IFundamentalsProviderConfig
+  ): Promise<T> {
+    const maxAttempts = config.retryAttempts || 1;
+    let lastError: Error | undefined;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fetchFn();
+      } catch (error) {
+        lastError = error as Error;
+
+        if (attempt < maxAttempts) {
+          const delay = (config.retryDelay || 1000) * attempt;
+          console.log(`Retry attempt ${attempt} after ${delay}ms`);
+          await plugins.smartdelay.delayFor(delay);
+        }
+      }
+    }
+
+    throw lastError || new Error('Unknown error during fetch');
+  }
+
+  /**
+   * Generate cache key for request
+   */
+  private getCacheKey(request: IFundamentalsRequest): string {
+    switch (request.type) {
+      case 'fundamentals-current':
+        return `fundamentals:${request.ticker}`;
+      case 'fundamentals-batch':
+        const tickers = request.tickers.sort().join(',');
+        return `fundamentals-batch:${tickers}`;
+      default:
+        return `unknown:${JSON.stringify(request)}`;
+    }
+  }
+
+  /**
+   * Get from cache if not expired
+   */
+  private getFromCache(key: string): IStockFundamentals | IStockFundamentals[] | null {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      return null;
+    }
+
+    // Check if cache entry has expired
+    const age = Date.now() - entry.timestamp.getTime();
+    if (entry.ttl !== Infinity && age > entry.ttl) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.fundamentals;
+  }
+
+  /**
+   * Add to cache with TTL
+   */
+  private addToCache(
+    key: string,
+    fundamentals: IStockFundamentals | IStockFundamentals[],
+    ttl?: number
+  ): void {
+    // Enforce max entries limit
+    if (this.cache.size >= this.cacheConfig.maxEntries) {
+      // Remove oldest entry
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey) {
+        this.cache.delete(oldestKey);
+      }
+    }
+
+    this.cache.set(key, {
+      fundamentals,
+      timestamp: new Date(),
+      ttl: ttl || this.cacheConfig.ttl
+    });
+  }
+
+  /**
+   * Get human-readable request description
+   */
+  private getRequestDescription(request: IFundamentalsRequest): string {
+    switch (request.type) {
+      case 'fundamentals-current':
+        return `fundamentals for ${request.ticker}`;
+      case 'fundamentals-batch':
+        return `fundamentals for ${request.tickers.length} tickers`;
+      default:
+        return 'fundamentals data';
+    }
+  }
+}

ts/stocks/classes.stockdataservice.ts

@@ -0,0 +1,647 @@
+import * as plugins from '../plugins.js';
+import type { IStockProvider, IProviderConfig } from './interfaces/provider.js';
+import type { IFundamentalsProvider, IFundamentalsProviderConfig, IStockFundamentals } from './interfaces/fundamentals.js';
+import type { IStockPrice, IStockDataRequest as IPriceRequest } from './interfaces/stockprice.js';
+import type { IStockData, IStockDataServiceConfig, ICompleteStockDataRequest, ICompleteStockDataBatchRequest } from './interfaces/stockdata.js';
+
+interface IProviderEntry<T> {
+  provider: T;
+  config: IProviderConfig | IFundamentalsProviderConfig;
+  lastError?: Error;
+  lastErrorTime?: Date;
+  successCount: number;
+  errorCount: number;
+}
+
+interface ICacheEntry<T> {
+  data: T;
+  timestamp: Date;
+  ttl: number;
+}
+
+/**
+ * Unified service for managing both stock prices and fundamentals
+ * Provides automatic enrichment and convenient combined data access
+ */
+export class StockDataService {
+  private priceProviders = new Map<string, IProviderEntry<IStockProvider>>();
+  private fundamentalsProviders = new Map<string, IProviderEntry<IFundamentalsProvider>>();
+
+  private priceCache = new Map<string, ICacheEntry<IStockPrice | IStockPrice[]>>();
+  private fundamentalsCache = new Map<string, ICacheEntry<IStockFundamentals | IStockFundamentals[]>>();
+
+  private logger = console;
+
+  private config: Required<IStockDataServiceConfig> = {
+    cache: {
+      priceTTL: 24 * 60 * 60 * 1000, // 24 hours
+      fundamentalsTTL: 90 * 24 * 60 * 60 * 1000, // 90 days
+      maxEntries: 10000
+    },
+    timeout: {
+      price: 10000, // 10 seconds
+      fundamentals: 30000 // 30 seconds
+    }
+  };
+
+  constructor(config?: IStockDataServiceConfig) {
+    if (config) {
+      this.config = {
+        cache: { ...this.config.cache, ...config.cache },
+        timeout: { ...this.config.timeout, ...config.timeout }
+      };
+    }
+  }
+
+  // ========== Provider Management ==========
+
+  /**
+   * Register a price provider
+   */
+  public registerPriceProvider(provider: IStockProvider, config?: IProviderConfig): void {
+    const defaultConfig: IProviderConfig = {
+      enabled: true,
+      priority: provider.priority,
+      timeout: this.config.timeout.price,
+      retryAttempts: 2,
+      retryDelay: 1000
+    };
+
+    const mergedConfig = { ...defaultConfig, ...config };
+
+    this.priceProviders.set(provider.name, {
+      provider,
+      config: mergedConfig,
+      successCount: 0,
+      errorCount: 0
+    });
+
+    console.log(`Registered price provider: ${provider.name}`);
+  }
+
+  /**
+   * Register a fundamentals provider
+   */
+  public registerFundamentalsProvider(
+    provider: IFundamentalsProvider,
+    config?: IFundamentalsProviderConfig
+  ): void {
+    const defaultConfig: IFundamentalsProviderConfig = {
+      enabled: true,
+      priority: provider.priority,
+      timeout: this.config.timeout.fundamentals,
+      retryAttempts: 2,
+      retryDelay: 1000,
+      cacheTTL: this.config.cache.fundamentalsTTL
+    };
+
+    const mergedConfig = { ...defaultConfig, ...config };
+
+    this.fundamentalsProviders.set(provider.name, {
+      provider,
+      config: mergedConfig,
+      successCount: 0,
+      errorCount: 0
+    });
+
+    console.log(`Registered fundamentals provider: ${provider.name}`);
+  }
+
+  /**
+   * Unregister a price provider
+   */
+  public unregisterPriceProvider(providerName: string): void {
+    this.priceProviders.delete(providerName);
+    console.log(`Unregistered price provider: ${providerName}`);
+  }
+
+  /**
+   * Unregister a fundamentals provider
+   */
+  public unregisterFundamentalsProvider(providerName: string): void {
+    this.fundamentalsProviders.delete(providerName);
+    console.log(`Unregistered fundamentals provider: ${providerName}`);
+  }
+
+  /**
+   * Get all registered price providers
+   */
+  public getPriceProviders(): IStockProvider[] {
+    return Array.from(this.priceProviders.values()).map(entry => entry.provider);
+  }
+
+  /**
+   * Get all registered fundamentals providers
+   */
+  public getFundamentalsProviders(): IFundamentalsProvider[] {
+    return Array.from(this.fundamentalsProviders.values()).map(entry => entry.provider);
+  }
+
+  /**
+   * Get enabled price providers sorted by priority
+   */
+  private getEnabledPriceProviders(): IStockProvider[] {
+    return Array.from(this.priceProviders.values())
+      .filter(entry => entry.config.enabled)
+      .sort((a, b) => (b.config.priority || 0) - (a.config.priority || 0))
+      .map(entry => entry.provider);
+  }
+
+  /**
+   * Get enabled fundamentals providers sorted by priority
+   */
+  private getEnabledFundamentalsProviders(): IFundamentalsProvider[] {
+    return Array.from(this.fundamentalsProviders.values())
+      .filter(entry => entry.config.enabled)
+      .sort((a, b) => (b.config.priority || 0) - (a.config.priority || 0))
+      .map(entry => entry.provider);
+  }
+
+  // ========== Data Fetching Methods ==========
+
+  /**
+   * Get current price for a single ticker
+   */
+  public async getPrice(ticker: string): Promise<IStockPrice> {
+    const cacheKey = `price:${ticker}`;
+    const cached = this.getFromCache(this.priceCache, cacheKey);
+
+    if (cached) {
+      console.log(`Cache hit for price: ${ticker}`);
+      return cached as IStockPrice;
+    }
+
+    const providers = this.getEnabledPriceProviders();
+    if (providers.length === 0) {
+      throw new Error('No price providers available');
+    }
+
+    let lastError: Error | undefined;
+
+    for (const provider of providers) {
+      const entry = this.priceProviders.get(provider.name)!;
+
+      try {
+        const result = await this.fetchWithRetry(
+          () => provider.fetchData({ type: 'current', ticker }),
+          entry.config
+        );
+
+        entry.successCount++;
+
+        const price = result as IStockPrice;
+        this.addToCache(this.priceCache, cacheKey, price, this.config.cache.priceTTL);
+
+        console.log(`Successfully fetched price for ${ticker} from ${provider.name}`);
+        return price;
+      } catch (error) {
+        entry.errorCount++;
+        entry.lastError = error as Error;
+        entry.lastErrorTime = new Date();
+        lastError = error as Error;
+
+        console.warn(`Provider ${provider.name} failed for ${ticker}: ${error.message}`);
+      }
+    }
+
+    throw new Error(
+      `Failed to fetch price for ${ticker} from all providers. Last error: ${lastError?.message}`
+    );
+  }
+
+  /**
+   * Get current prices for multiple tickers
+   */
+  public async getPrices(tickers: string[]): Promise<IStockPrice[]> {
+    const cacheKey = `prices:${tickers.sort().join(',')}`;
+    const cached = this.getFromCache(this.priceCache, cacheKey);
+
+    if (cached) {
+      console.log(`Cache hit for prices: ${tickers.length} tickers`);
+      return cached as IStockPrice[];
+    }
+
+    const providers = this.getEnabledPriceProviders();
+    if (providers.length === 0) {
+      throw new Error('No price providers available');
+    }
+
+    let lastError: Error | undefined;
+
+    for (const provider of providers) {
+      const entry = this.priceProviders.get(provider.name)!;
+
+      try {
+        const result = await this.fetchWithRetry(
+          () => provider.fetchData({ type: 'batch', tickers }),
+          entry.config
+        );
+
+        entry.successCount++;
+
+        const prices = result as IStockPrice[];
+        this.addToCache(this.priceCache, cacheKey, prices, this.config.cache.priceTTL);
+
+        console.log(`Successfully fetched ${prices.length} prices from ${provider.name}`);
+        return prices;
+      } catch (error) {
+        entry.errorCount++;
+        entry.lastError = error as Error;
+        entry.lastErrorTime = new Date();
+        lastError = error as Error;
+
+        console.warn(`Provider ${provider.name} failed for batch prices: ${error.message}`);
+      }
+    }
+
+    throw new Error(
+      `Failed to fetch prices for ${tickers.length} tickers from all providers. Last error: ${lastError?.message}`
+    );
+  }
+
+  /**
+   * Get fundamentals for a single ticker
+   */
+  public async getFundamentals(ticker: string): Promise<IStockFundamentals> {
+    const cacheKey = `fundamentals:${ticker}`;
+    const cached = this.getFromCache(this.fundamentalsCache, cacheKey);
+
+    if (cached) {
+      console.log(`Cache hit for fundamentals: ${ticker}`);
+      return cached as IStockFundamentals;
+    }
+
+    const providers = this.getEnabledFundamentalsProviders();
+    if (providers.length === 0) {
+      throw new Error('No fundamentals providers available');
+    }
+
+    let lastError: Error | undefined;
+
+    for (const provider of providers) {
+      const entry = this.fundamentalsProviders.get(provider.name)!;
+
+      try {
+        const result = await this.fetchWithRetry(
+          () => provider.fetchData({ type: 'fundamentals-current', ticker }),
+          entry.config
+        );
+
+        entry.successCount++;
+
+        const fundamentals = result as IStockFundamentals;
+        const ttl = (entry.config as IFundamentalsProviderConfig).cacheTTL || this.config.cache.fundamentalsTTL;
+        this.addToCache(this.fundamentalsCache, cacheKey, fundamentals, ttl);
+
+        console.log(`Successfully fetched fundamentals for ${ticker} from ${provider.name}`);
+        return fundamentals;
+      } catch (error) {
+        entry.errorCount++;
+        entry.lastError = error as Error;
+        entry.lastErrorTime = new Date();
+        lastError = error as Error;
+
+        console.warn(`Provider ${provider.name} failed for ${ticker} fundamentals: ${error.message}`);
+      }
+    }
+
+    throw new Error(
+      `Failed to fetch fundamentals for ${ticker} from all providers. Last error: ${lastError?.message}`
+    );
+  }
+
+  /**
+   * Get fundamentals for multiple tickers
+   */
+  public async getBatchFundamentals(tickers: string[]): Promise<IStockFundamentals[]> {
+    const cacheKey = `fundamentals-batch:${tickers.sort().join(',')}`;
+    const cached = this.getFromCache(this.fundamentalsCache, cacheKey);
+
+    if (cached) {
+      console.log(`Cache hit for batch fundamentals: ${tickers.length} tickers`);
+      return cached as IStockFundamentals[];
+    }
+
+    const providers = this.getEnabledFundamentalsProviders();
+    if (providers.length === 0) {
+      throw new Error('No fundamentals providers available');
+    }
+
+    let lastError: Error | undefined;
+
+    for (const provider of providers) {
+      const entry = this.fundamentalsProviders.get(provider.name)!;
+
+      try {
+        const result = await this.fetchWithRetry(
+          () => provider.fetchData({ type: 'fundamentals-batch', tickers }),
+          entry.config
+        );
+
+        entry.successCount++;
+
+        const fundamentals = result as IStockFundamentals[];
+        const ttl = (entry.config as IFundamentalsProviderConfig).cacheTTL || this.config.cache.fundamentalsTTL;
+        this.addToCache(this.fundamentalsCache, cacheKey, fundamentals, ttl);
+
+        console.log(`Successfully fetched ${fundamentals.length} fundamentals from ${provider.name}`);
+        return fundamentals;
+      } catch (error) {
+        entry.errorCount++;
+        entry.lastError = error as Error;
+        entry.lastErrorTime = new Date();
+        lastError = error as Error;
+
+        console.warn(`Provider ${provider.name} failed for batch fundamentals: ${error.message}`);
+      }
+    }
+
+    throw new Error(
+      `Failed to fetch fundamentals for ${tickers.length} tickers from all providers. Last error: ${lastError?.message}`
+    );
+  }
+
+  /**
+   * ✨ Get complete stock data (price + fundamentals) with automatic enrichment
+   */
+  public async getStockData(request: string | ICompleteStockDataRequest): Promise<IStockData> {
+    const normalizedRequest = typeof request === 'string'
+      ? { ticker: request, includeFundamentals: true, enrichFundamentals: true }
+      : { includeFundamentals: true, enrichFundamentals: true, ...request };
+
+    const price = await this.getPrice(normalizedRequest.ticker);
+
+    let fundamentals: IStockFundamentals | undefined;
+
+    if (normalizedRequest.includeFundamentals) {
+      try {
+        fundamentals = await this.getFundamentals(normalizedRequest.ticker);
+
+        // Enrich fundamentals with price calculations
+        if (normalizedRequest.enrichFundamentals && fundamentals) {
+          fundamentals = this.enrichWithPrice(fundamentals, price.price);
+        }
+      } catch (error) {
+        console.warn(`Failed to fetch fundamentals for ${normalizedRequest.ticker}: ${error.message}`);
+        // Continue without fundamentals
+      }
+    }
+
+    return {
+      ticker: normalizedRequest.ticker,
+      price,
+      fundamentals,
+      fetchedAt: new Date()
+    };
+  }
+
+  /**
+   * ✨ Get complete stock data for multiple tickers with automatic enrichment
+   */
+  public async getBatchStockData(request: string[] | ICompleteStockDataBatchRequest): Promise<IStockData[]> {
+    const normalizedRequest = Array.isArray(request)
+      ? { tickers: request, includeFundamentals: true, enrichFundamentals: true }
+      : { includeFundamentals: true, enrichFundamentals: true, ...request };
+
+    const prices = await this.getPrices(normalizedRequest.tickers);
+    const priceMap = new Map(prices.map(p => [p.ticker, p]));
+
+    let fundamentalsMap = new Map<string, IStockFundamentals>();
+
+    if (normalizedRequest.includeFundamentals) {
+      try {
+        const fundamentals = await this.getBatchFundamentals(normalizedRequest.tickers);
+
+        // Enrich with prices if requested
+        if (normalizedRequest.enrichFundamentals) {
+          for (const fund of fundamentals) {
+            const price = priceMap.get(fund.ticker);
+            if (price) {
+              fundamentalsMap.set(fund.ticker, this.enrichWithPrice(fund, price.price));
+            } else {
+              fundamentalsMap.set(fund.ticker, fund);
+            }
+          }
+        } else {
+          fundamentalsMap = new Map(fundamentals.map(f => [f.ticker, f]));
+        }
+      } catch (error) {
+        console.warn(`Failed to fetch batch fundamentals: ${error.message}`);
+        // Continue without fundamentals
+      }
+    }
+
+    return normalizedRequest.tickers.map(ticker => ({
+      ticker,
+      price: priceMap.get(ticker)!,
+      fundamentals: fundamentalsMap.get(ticker),
+      fetchedAt: new Date()
+    }));
+  }
+
+  // ========== Helper Methods ==========
+
+  /**
+   * Enrich fundamentals with calculated metrics using current price
+   */
+  private enrichWithPrice(fundamentals: IStockFundamentals, price: number): IStockFundamentals {
+    const enriched = { ...fundamentals };
+
+    // Calculate market cap: price × shares outstanding
+    if (fundamentals.sharesOutstanding) {
+      enriched.marketCap = price * fundamentals.sharesOutstanding;
+    }
+
+    // Calculate P/E ratio: price / EPS
+    if (fundamentals.earningsPerShareDiluted && fundamentals.earningsPerShareDiluted > 0) {
+      enriched.priceToEarnings = price / fundamentals.earningsPerShareDiluted;
+    }
+
+    // Calculate price-to-book: market cap / stockholders equity
+    if (enriched.marketCap && fundamentals.stockholdersEquity && fundamentals.stockholdersEquity > 0) {
+      enriched.priceToBook = enriched.marketCap / fundamentals.stockholdersEquity;
+    }
+
+    return enriched;
+  }
+
+  /**
+   * Fetch with retry logic
+   */
+  private async fetchWithRetry<T>(
+    fetchFn: () => Promise<T>,
+    config: IProviderConfig | IFundamentalsProviderConfig
+  ): Promise<T> {
+    const maxAttempts = config.retryAttempts || 1;
+    let lastError: Error | undefined;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fetchFn();
+      } catch (error) {
+        lastError = error as Error;
+
+        if (attempt < maxAttempts) {
+          const delay = (config.retryDelay || 1000) * attempt;
+          console.log(`Retry attempt ${attempt} after ${delay}ms`);
+          await plugins.smartdelay.delayFor(delay);
+        }
+      }
+    }
+
+    throw lastError || new Error('Unknown error during fetch');
+  }
+
+  /**
+   * Get from cache if not expired
+   */
+  private getFromCache<T>(cache: Map<string, ICacheEntry<T>>, key: string): T | null {
+    const entry = cache.get(key);
+
+    if (!entry) {
+      return null;
+    }
+
+    // Check if cache entry has expired
+    const age = Date.now() - entry.timestamp.getTime();
+    if (entry.ttl !== Infinity && age > entry.ttl) {
+      cache.delete(key);
+      return null;
+    }
+
+    return entry.data;
+  }
+
+  /**
+   * Add to cache with TTL
+   */
+  private addToCache<T>(cache: Map<string, ICacheEntry<T>>, key: string, data: T, ttl: number): void {
+    // Enforce max entries limit
+    if (cache.size >= this.config.cache.maxEntries) {
+      // Remove oldest entry
+      const oldestKey = cache.keys().next().value;
+      if (oldestKey) {
+        cache.delete(oldestKey);
+      }
+    }
+
+    cache.set(key, {
+      data,
+      timestamp: new Date(),
+      ttl
+    });
+  }
+
+  // ========== Health & Statistics ==========
+
+  /**
+   * Check health of all providers (both price and fundamentals)
+   */
+  public async checkProvidersHealth(): Promise<Map<string, boolean>> {
+    const health = new Map<string, boolean>();
+
+    // Check price providers
+    for (const [name, entry] of this.priceProviders) {
+      if (!entry.config.enabled) {
+        health.set(`${name} (price)`, false);
+        continue;
+      }
+
+      try {
+        const isAvailable = await entry.provider.isAvailable();
+        health.set(`${name} (price)`, isAvailable);
+      } catch (error) {
+        health.set(`${name} (price)`, false);
+        console.error(`Health check failed for ${name}:`, error);
+      }
+    }
+
+    // Check fundamentals providers
+    for (const [name, entry] of this.fundamentalsProviders) {
+      if (!entry.config.enabled) {
+        health.set(`${name} (fundamentals)`, false);
+        continue;
+      }
+
+      try {
+        const isAvailable = await entry.provider.isAvailable();
+        health.set(`${name} (fundamentals)`, isAvailable);
+      } catch (error) {
+        health.set(`${name} (fundamentals)`, false);
+        console.error(`Health check failed for ${name}:`, error);
+      }
+    }
+
+    return health;
+  }
+
+  /**
+   * Get statistics for all providers
+   */
+  public getProviderStats(): Map<
+    string,
+    {
+      type: 'price' | 'fundamentals';
+      successCount: number;
+      errorCount: number;
+      lastError?: string;
+      lastErrorTime?: Date;
+    }
+  > {
+    const stats = new Map();
+
+    // Price provider stats
+    for (const [name, entry] of this.priceProviders) {
+      stats.set(name, {
+        type: 'price',
+        successCount: entry.successCount,
+        errorCount: entry.errorCount,
+        lastError: entry.lastError?.message,
+        lastErrorTime: entry.lastErrorTime
+      });
+    }
+
+    // Fundamentals provider stats
+    for (const [name, entry] of this.fundamentalsProviders) {
+      stats.set(name, {
+        type: 'fundamentals',
+        successCount: entry.successCount,
+        errorCount: entry.errorCount,
+        lastError: entry.lastError?.message,
+        lastErrorTime: entry.lastErrorTime
+      });
+    }
+
+    return stats;
+  }
+
+  /**
+   * Clear all caches
+   */
+  public clearCache(): void {
+    this.priceCache.clear();
+    this.fundamentalsCache.clear();
+    console.log('All caches cleared');
+  }
+
+  /**
+   * Get cache statistics
+   */
+  public getCacheStats(): {
+    priceCache: { size: number; ttl: number };
+    fundamentalsCache: { size: number; ttl: number };
+    maxEntries: number;
+  } {
+    return {
+      priceCache: {
+        size: this.priceCache.size,
+        ttl: this.config.cache.priceTTL
+      },
+      fundamentalsCache: {
+        size: this.fundamentalsCache.size,
+        ttl: this.config.cache.fundamentalsTTL
+      },
+      maxEntries: this.config.cache.maxEntries
+    };
+  }
+}

ts/stocks/classes.stockservice.ts

@@ -0,0 +1,373 @@
+import * as plugins from '../plugins.js';
+import type { IStockProvider, IProviderConfig, IProviderRegistry } from './interfaces/provider.js';
+import type {
+  IStockPrice,
+  IStockPriceError,
+  IStockDataRequest,
+  IStockCurrentRequest,
+  IStockHistoricalRequest,
+  IStockIntradayRequest,
+  IStockBatchCurrentRequest,
+  TIntervalType
+} from './interfaces/stockprice.js';
+
+// Simple request interfaces for convenience methods
+interface ISimpleQuoteRequest {
+  ticker: string;
+}
+
+interface ISimpleBatchRequest {
+  tickers: string[];
+}
+
+interface IProviderEntry {
+  provider: IStockProvider;
+  config: IProviderConfig;
+  lastError?: Error;
+  lastErrorTime?: Date;
+  successCount: number;
+  errorCount: number;
+}
+
+interface ICacheEntry {
+  price: IStockPrice | IStockPrice[];
+  timestamp: Date;
+  ttl: number; // Specific TTL for this entry
+}
+
+export class StockPriceService implements IProviderRegistry {
+  private providers = new Map<string, IProviderEntry>();
+  private cache = new Map<string, ICacheEntry>();
+  private logger = console;
+
+  private cacheConfig = {
+    ttl: 60000, // 60 seconds default (for backward compatibility)
+    maxEntries: 10000 // Increased for historical data
+  };
+
+  constructor(cacheConfig?: { ttl?: number; maxEntries?: number }) {
+    if (cacheConfig) {
+      this.cacheConfig = { ...this.cacheConfig, ...cacheConfig };
+    }
+  }
+
+  /**
+   * Get data-type aware TTL for smart caching
+   */
+  private getCacheTTL(dataType: 'eod' | 'historical' | 'intraday' | 'live', interval?: TIntervalType): number {
+    switch (dataType) {
+      case 'historical':
+        return Infinity; // Historical data never changes
+      case 'eod':
+        return 24 * 60 * 60 * 1000; // 24 hours (EOD is static after market close)
+      case 'intraday':
+        // Match cache TTL to interval
+        return this.getIntervalMs(interval);
+      case 'live':
+        return 30 * 1000; // 30 seconds for live data
+      default:
+        return this.cacheConfig.ttl; // Fallback to default
+    }
+  }
+
+  /**
+   * Convert interval to milliseconds
+   */
+  private getIntervalMs(interval?: TIntervalType): number {
+    if (!interval) return 60 * 1000; // Default 1 minute
+
+    const intervalMap: Record<TIntervalType, number> = {
+      '1min': 60 * 1000,
+      '5min': 5 * 60 * 1000,
+      '10min': 10 * 60 * 1000,
+      '15min': 15 * 60 * 1000,
+      '30min': 30 * 60 * 1000,
+      '1hour': 60 * 60 * 1000
+    };
+
+    return intervalMap[interval] || 60 * 1000;
+  }
+
+  public register(provider: IStockProvider, config?: IProviderConfig): void {
+    const defaultConfig: IProviderConfig = {
+      enabled: true,
+      priority: provider.priority,
+      timeout: 10000,
+      retryAttempts: 2,
+      retryDelay: 1000
+    };
+
+    const mergedConfig = { ...defaultConfig, ...config };
+    
+    this.providers.set(provider.name, {
+      provider,
+      config: mergedConfig,
+      successCount: 0,
+      errorCount: 0
+    });
+
+    console.log(`Registered provider: ${provider.name}`);
+  }
+
+  public unregister(providerName: string): void {
+    this.providers.delete(providerName);
+    console.log(`Unregistered provider: ${providerName}`);
+  }
+
+  public getProvider(name: string): IStockProvider | undefined {
+    return this.providers.get(name)?.provider;
+  }
+
+  public getAllProviders(): IStockProvider[] {
+    return Array.from(this.providers.values()).map(entry => entry.provider);
+  }
+
+  public getEnabledProviders(): IStockProvider[] {
+    return Array.from(this.providers.values())
+      .filter(entry => entry.config.enabled)
+      .sort((a, b) => (b.config.priority || 0) - (a.config.priority || 0))
+      .map(entry => entry.provider);
+  }
+
+  /**
+   * Convenience method: Get current price for a single ticker
+   */
+  public async getPrice(request: ISimpleQuoteRequest): Promise<IStockPrice> {
+    const result = await this.getData({
+      type: 'current',
+      ticker: request.ticker
+    });
+    return result as IStockPrice;
+  }
+
+  /**
+   * Convenience method: Get current prices for multiple tickers
+   */
+  public async getPrices(request: ISimpleBatchRequest): Promise<IStockPrice[]> {
+    const result = await this.getData({
+      type: 'batch',
+      tickers: request.tickers
+    });
+    return result as IStockPrice[];
+  }
+
+  /**
+   * New unified data fetching method supporting all request types
+   */
+  public async getData(request: IStockDataRequest): Promise<IStockPrice | IStockPrice[]> {
+    const cacheKey = this.getDataCacheKey(request);
+    const cached = this.getFromCache(cacheKey);
+
+    if (cached) {
+      console.log(`Cache hit for ${this.getRequestDescription(request)}`);
+      return cached;
+    }
+
+    const providers = this.getEnabledProviders();
+    if (providers.length === 0) {
+      throw new Error('No stock price providers available');
+    }
+
+    let lastError: Error | undefined;
+
+    for (const provider of providers) {
+      const entry = this.providers.get(provider.name)!;
+
+      try {
+        const result = await this.fetchWithRetry(
+          () => provider.fetchData(request),
+          entry.config
+        ) as IStockPrice | IStockPrice[];
+
+        entry.successCount++;
+
+        // Determine TTL based on request type
+        const ttl = this.getRequestTTL(request, result);
+        this.addToCache(cacheKey, result, ttl);
+
+        console.log(`Successfully fetched ${this.getRequestDescription(request)} from ${provider.name}`);
+        return result;
+      } catch (error) {
+        entry.errorCount++;
+        entry.lastError = error as Error;
+        entry.lastErrorTime = new Date();
+        lastError = error as Error;
+
+        console.warn(
+          `Provider ${provider.name} failed for ${this.getRequestDescription(request)}: ${error.message}`
+        );
+      }
+    }
+
+    throw new Error(
+      `Failed to fetch ${this.getRequestDescription(request)} from all providers. Last error: ${lastError?.message}`
+    );
+  }
+
+  /**
+   * Get TTL based on request type and result
+   */
+  private getRequestTTL(request: IStockDataRequest, result: IStockPrice | IStockPrice[]): number {
+    switch (request.type) {
+      case 'historical':
+        return Infinity; // Historical data never changes
+      case 'current':
+        return this.getCacheTTL('eod');
+      case 'batch':
+        return this.getCacheTTL('eod');
+      case 'intraday':
+        return this.getCacheTTL('intraday', request.interval);
+      default:
+        return this.cacheConfig.ttl;
+    }
+  }
+
+  /**
+   * Get human-readable description of request
+   */
+  private getRequestDescription(request: IStockDataRequest): string {
+    switch (request.type) {
+      case 'current':
+        return `current price for ${request.ticker}${request.exchange ? ` on ${request.exchange}` : ''}`;
+      case 'historical':
+        return `historical prices for ${request.ticker} from ${request.from.toISOString().split('T')[0]} to ${request.to.toISOString().split('T')[0]}`;
+      case 'intraday':
+        return `intraday ${request.interval} prices for ${request.ticker}`;
+      case 'batch':
+        return `batch prices for ${request.tickers.length} tickers`;
+      default:
+        return 'data';
+    }
+  }
+
+  public async checkProvidersHealth(): Promise<Map<string, boolean>> {
+    const health = new Map<string, boolean>();
+    
+    for (const [name, entry] of this.providers) {
+      if (!entry.config.enabled) {
+        health.set(name, false);
+        continue;
+      }
+
+      try {
+        const isAvailable = await entry.provider.isAvailable();
+        health.set(name, isAvailable);
+      } catch (error) {
+        health.set(name, false);
+        console.error(`Health check failed for ${name}:`, error);
+      }
+    }
+
+    return health;
+  }
+
+  public getProviderStats(): Map<string, { 
+    successCount: number; 
+    errorCount: number; 
+    lastError?: string;
+    lastErrorTime?: Date;
+  }> {
+    const stats = new Map();
+    
+    for (const [name, entry] of this.providers) {
+      stats.set(name, {
+        successCount: entry.successCount,
+        errorCount: entry.errorCount,
+        lastError: entry.lastError?.message,
+        lastErrorTime: entry.lastErrorTime
+      });
+    }
+
+    return stats;
+  }
+
+  public clearCache(): void {
+    this.cache.clear();
+    console.log('Cache cleared');
+  }
+
+  public setCacheTTL(ttl: number): void {
+    this.cacheConfig.ttl = ttl;
+    console.log(`Cache TTL set to ${ttl}ms`);
+  }
+
+  private async fetchWithRetry<T>(
+    fetchFn: () => Promise<T>,
+    config: IProviderConfig
+  ): Promise<T> {
+    const maxAttempts = config.retryAttempts || 1;
+    let lastError: Error | undefined;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fetchFn();
+      } catch (error) {
+        lastError = error as Error;
+        
+        if (attempt < maxAttempts) {
+          const delay = (config.retryDelay || 1000) * attempt;
+          console.log(`Retry attempt ${attempt} after ${delay}ms`);
+          await plugins.smartdelay.delayFor(delay);
+        }
+      }
+    }
+
+    throw lastError || new Error('Unknown error during fetch');
+  }
+
+  /**
+   * New cache key generation for discriminated union requests
+   */
+  private getDataCacheKey(request: IStockDataRequest): string {
+    switch (request.type) {
+      case 'current':
+        return `current:${request.ticker}${request.exchange ? `:${request.exchange}` : ''}`;
+      case 'historical':
+        const fromStr = request.from.toISOString().split('T')[0];
+        const toStr = request.to.toISOString().split('T')[0];
+        return `historical:${request.ticker}:${fromStr}:${toStr}${request.exchange ? `:${request.exchange}` : ''}`;
+      case 'intraday':
+        const dateStr = request.date ? request.date.toISOString().split('T')[0] : 'latest';
+        return `intraday:${request.ticker}:${request.interval}:${dateStr}${request.exchange ? `:${request.exchange}` : ''}`;
+      case 'batch':
+        const tickers = request.tickers.sort().join(',');
+        return `batch:${tickers}${request.exchange ? `:${request.exchange}` : ''}`;
+      default:
+        return `unknown:${JSON.stringify(request)}`;
+    }
+  }
+
+  private getFromCache(key: string): IStockPrice | IStockPrice[] | null {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      return null;
+    }
+
+    // Check if cache entry has expired
+    const age = Date.now() - entry.timestamp.getTime();
+    if (entry.ttl !== Infinity && age > entry.ttl) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.price;
+  }
+
+  private addToCache(key: string, price: IStockPrice | IStockPrice[], ttl?: number): void {
+    // Enforce max entries limit
+    if (this.cache.size >= this.cacheConfig.maxEntries) {
+      // Remove oldest entry
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey) {
+        this.cache.delete(oldestKey);
+      }
+    }
+
+    this.cache.set(key, {
+      price,
+      timestamp: new Date(),
+      ttl: ttl || this.cacheConfig.ttl
+    });
+  }
+}

ts/stocks/index.ts

@@ -0,0 +1,18 @@
+// Export all interfaces
+export * from './interfaces/stockprice.js';
+export * from './interfaces/provider.js';
+export * from './interfaces/fundamentals.js';
+export * from './interfaces/stockdata.js';
+
+// Export main services
+export * from './classes.stockservice.js';
+export * from './classes.fundamentalsservice.js';
+export * from './classes.stockdataservice.js'; // ✨ New unified service
+
+// Export base service (for advanced use cases)
+export * from './classes.baseproviderservice.js';
+
+// Export providers
+export * from './providers/provider.yahoo.js';
+export * from './providers/provider.marketstack.js';
+export * from './providers/provider.secedgar.js';

ts/stocks/interfaces/fundamentals.ts

@@ -0,0 +1,102 @@
+/**
+ * Interfaces for stock fundamental data (financials from SEC filings)
+ * Separate from stock price data (OHLCV) to maintain clean architecture
+ */
+
+// Request types for fundamental data
+export interface IFundamentalsCurrentRequest {
+  type: 'fundamentals-current';
+  ticker: string;
+}
+
+export interface IFundamentalsBatchRequest {
+  type: 'fundamentals-batch';
+  tickers: string[];
+}
+
+export type IFundamentalsRequest =
+  | IFundamentalsCurrentRequest
+  | IFundamentalsBatchRequest;
+
+/**
+ * Stock fundamental data from SEC filings (10-K, 10-Q)
+ * Contains financial metrics like EPS, Revenue, Assets, etc.
+ */
+export interface IStockFundamentals {
+  ticker: string;
+  cik: string;
+  companyName: string;
+  provider: string;
+  timestamp: Date;
+  fetchedAt: Date;
+
+  // Per-share metrics
+  earningsPerShareBasic?: number;
+  earningsPerShareDiluted?: number;
+  sharesOutstanding?: number;
+  weightedAverageSharesOutstanding?: number;
+
+  // Income statement (annual USD)
+  revenue?: number;
+  netIncome?: number;
+  operatingIncome?: number;
+  grossProfit?: number;
+  costOfRevenue?: number;
+
+  // Balance sheet (annual USD)
+  assets?: number;
+  liabilities?: number;
+  stockholdersEquity?: number;
+  cash?: number;
+  propertyPlantEquipment?: number;
+
+  // Calculated metrics (requires current price)
+  marketCap?: number;        // price × sharesOutstanding
+  priceToEarnings?: number;  // price / EPS
+  priceToBook?: number;      // marketCap / stockholdersEquity
+
+  // Metadata
+  fiscalYear?: string;
+  fiscalQuarter?: string;
+  filingDate?: Date;
+  form?: '10-K' | '10-Q' | string;
+}
+
+/**
+ * Provider interface for fetching fundamental data
+ * Parallel to IStockProvider but for fundamentals instead of prices
+ */
+export interface IFundamentalsProvider {
+  name: string;
+  priority: number;
+  fetchData(request: IFundamentalsRequest): Promise<IStockFundamentals | IStockFundamentals[]>;
+  isAvailable(): Promise<boolean>;
+  readonly requiresAuth: boolean;
+  readonly rateLimit?: {
+    requestsPerMinute: number;
+    requestsPerDay?: number;
+  };
+}
+
+/**
+ * Configuration for fundamentals providers
+ */
+export interface IFundamentalsProviderConfig {
+  enabled: boolean;
+  priority?: number;
+  timeout?: number;
+  retryAttempts?: number;
+  retryDelay?: number;
+  cacheTTL?: number; // Custom cache TTL for this provider
+}
+
+/**
+ * Registry for managing fundamental data providers
+ */
+export interface IFundamentalsProviderRegistry {
+  register(provider: IFundamentalsProvider, config?: IFundamentalsProviderConfig): void;
+  unregister(providerName: string): void;
+  getProvider(name: string): IFundamentalsProvider | undefined;
+  getAllProviders(): IFundamentalsProvider[];
+  getEnabledProviders(): IFundamentalsProvider[];
+}

ts/stocks/interfaces/provider.ts

@@ -0,0 +1,35 @@
+import type { IStockPrice, IStockDataRequest } from './stockprice.js';
+
+export interface IStockProvider {
+  name: string;
+  priority: number;
+
+  fetchData(request: IStockDataRequest): Promise<IStockPrice | IStockPrice[]>;
+  isAvailable(): Promise<boolean>;
+
+  supportsMarket?(market: string): boolean;
+  supportsTicker?(ticker: string): boolean;
+
+  readonly requiresAuth: boolean;
+  readonly rateLimit?: {
+    requestsPerMinute: number;
+    requestsPerDay?: number;
+  };
+}
+
+export interface IProviderConfig {
+  enabled: boolean;
+  priority?: number;
+  apiKey?: string;
+  timeout?: number;
+  retryAttempts?: number;
+  retryDelay?: number;
+}
+
+export interface IProviderRegistry {
+  register(provider: IStockProvider, config?: IProviderConfig): void;
+  unregister(providerName: string): void;
+  getProvider(name: string): IStockProvider | undefined;
+  getAllProviders(): IStockProvider[];
+  getEnabledProviders(): IStockProvider[];
+}

ts/stocks/interfaces/stockdata.ts

@@ -0,0 +1,65 @@
+import type { IStockPrice } from './stockprice.js';
+import type { IStockFundamentals } from './fundamentals.js';
+
+/**
+ * Combined stock data with price and fundamentals
+ * All calculated metrics (market cap, P/E, P/B) are automatically included
+ */
+export interface IStockData {
+  /** Stock ticker symbol */
+  ticker: string;
+
+  /** Price information */
+  price: IStockPrice;
+
+  /** Fundamental data (optional - may not be available for all stocks) */
+  fundamentals?: IStockFundamentals;
+
+  /** When this combined data was fetched */
+  fetchedAt: Date;
+}
+
+/**
+ * Configuration for StockDataService
+ */
+export interface IStockDataServiceConfig {
+  /** Cache configuration */
+  cache?: {
+    /** TTL for price data (default: 24 hours) */
+    priceTTL?: number;
+    /** TTL for fundamentals data (default: 90 days) */
+    fundamentalsTTL?: number;
+    /** Max cache entries (default: 10000) */
+    maxEntries?: number;
+  };
+
+  /** Provider timeouts */
+  timeout?: {
+    /** Timeout for price providers (default: 10000ms) */
+    price?: number;
+    /** Timeout for fundamentals providers (default: 30000ms) */
+    fundamentals?: number;
+  };
+}
+
+/**
+ * Request type for getting complete stock data
+ */
+export interface ICompleteStockDataRequest {
+  ticker: string;
+  /** Whether to include fundamentals (default: true) */
+  includeFundamentals?: boolean;
+  /** Whether to enrich fundamentals with price calculations (default: true) */
+  enrichFundamentals?: boolean;
+}
+
+/**
+ * Batch request for multiple stocks
+ */
+export interface ICompleteStockDataBatchRequest {
+  tickers: string[];
+  /** Whether to include fundamentals (default: true) */
+  includeFundamentals?: boolean;
+  /** Whether to enrich fundamentals with price calculations (default: true) */
+  enrichFundamentals?: boolean;
+}

ts/stocks/interfaces/stockprice.ts

@@ -0,0 +1,94 @@
+// Enhanced stock price interface with additional OHLCV data
+export interface IStockPrice {
+  ticker: string;
+  price: number;
+  currency: string;
+  change: number;
+  changePercent: number;
+  previousClose: number;
+  timestamp: Date;
+  provider: string;
+  marketState: 'PRE' | 'REGULAR' | 'POST' | 'CLOSED';
+  exchange?: string;
+  exchangeName?: string;
+
+  // Phase 1 enhancements
+  volume?: number;           // Trading volume
+  open?: number;            // Opening price
+  high?: number;            // Day high
+  low?: number;             // Day low
+  adjusted?: boolean;       // If price is split/dividend adjusted
+  dataType: 'eod' | 'intraday' | 'live'; // What kind of data this is
+  fetchedAt: Date;          // When we fetched (vs data timestamp)
+
+  // Company identification
+  companyName?: string;      // Company name (e.g., "Apple Inc.")
+  companyFullName?: string;  // Full company name with exchange (e.g., "Apple Inc. (NASDAQ:AAPL)")
+}
+
+export interface IStockPriceError {
+  ticker: string;
+  error: string;
+  provider: string;
+  timestamp: Date;
+}
+
+// Pagination support for large datasets
+export interface IPaginatedResponse<T> {
+  data: T[];
+  pagination: {
+    currentPage: number;
+    totalPages: number;
+    totalRecords: number;
+    hasMore: boolean;
+    limit: number;
+    offset: number;
+  };
+}
+
+// Phase 1: Discriminated union types for different request types
+export type TIntervalType = '1min' | '5min' | '10min' | '15min' | '30min' | '1hour';
+export type TSortOrder = 'ASC' | 'DESC';
+
+// Current price request (latest EOD or live)
+export interface IStockCurrentRequest {
+  type: 'current';
+  ticker: string;
+  exchange?: string; // MIC code like 'XNAS', 'XNYS', 'XLON'
+}
+
+// Historical price request (date range)
+export interface IStockHistoricalRequest {
+  type: 'historical';
+  ticker: string;
+  from: Date;
+  to: Date;
+  exchange?: string;
+  sort?: TSortOrder;
+  limit?: number; // Max results per page (default 1000)
+  offset?: number; // For pagination
+}
+
+// Intraday price request (real-time intervals)
+export interface IStockIntradayRequest {
+  type: 'intraday';
+  ticker: string;
+  interval: TIntervalType;
+  exchange?: string;
+  limit?: number; // Number of bars to return
+  date?: Date; // Specific date for historical intraday
+}
+
+// Batch current prices request
+export interface IStockBatchCurrentRequest {
+  type: 'batch';
+  tickers: string[];
+  exchange?: string;
+}
+
+// Union type for all stock data requests
+export type IStockDataRequest =
+  | IStockCurrentRequest
+  | IStockHistoricalRequest
+  | IStockIntradayRequest
+  | IStockBatchCurrentRequest;

ts/stocks/providers/provider.marketstack.ts

@@ -0,0 +1,376 @@
+import * as plugins from '../../plugins.js';
+import type { IStockProvider, IProviderConfig } from '../interfaces/provider.js';
+import type {
+  IStockPrice,
+  IStockDataRequest,
+  IStockCurrentRequest,
+  IStockHistoricalRequest,
+  IStockIntradayRequest,
+  IStockBatchCurrentRequest
+} from '../interfaces/stockprice.js';
+
+/**
+ * Marketstack API v2 Provider - Enhanced
+ * Documentation: https://docs.apilayer.com/marketstack/docs/marketstack-api-v2-v-2-0-0
+ *
+ * Features:
+ * - End-of-Day (EOD) stock prices with historical data
+ * - Intraday pricing with multiple intervals (1min, 5min, 15min, 30min, 1hour)
+ * - Exchange filtering via MIC codes (XNAS, XNYS, XLON, etc.)
+ * - Supports 500,000+ tickers across 72+ exchanges worldwide
+ * - OHLCV data (Open, High, Low, Close, Volume)
+ * - Pagination for large datasets
+ * - Requires API key authentication
+ *
+ * Rate Limits:
+ * - Free Plan: 100 requests/month (EOD only)
+ * - Basic Plan: 10,000 requests/month
+ * - Professional Plan: 100,000 requests/month (intraday access)
+ *
+ * Phase 1 Enhancements:
+ * - Historical data retrieval with date ranges
+ * - Exchange filtering
+ * - OHLCV data support
+ * - Pagination handling
+ */
+export class MarketstackProvider implements IStockProvider {
+  public name = 'Marketstack';
+  public priority = 80; // Lower than Yahoo (100) due to rate limits and EOD-only data
+  public readonly requiresAuth = true;
+  public readonly rateLimit = {
+    requestsPerMinute: undefined, // No per-minute limit specified
+    requestsPerDay: undefined // Varies by plan
+  };
+
+  private logger = console;
+  private baseUrl = 'https://api.marketstack.com/v2';
+  private apiKey: string;
+
+  constructor(apiKey: string, private config?: IProviderConfig) {
+    if (!apiKey) {
+      throw new Error('API key is required for Marketstack provider');
+    }
+
+    this.apiKey = apiKey;
+  }
+
+  /**
+   * Unified data fetching method supporting all request types
+   */
+  public async fetchData(request: IStockDataRequest): Promise<IStockPrice[] | IStockPrice> {
+    switch (request.type) {
+      case 'current':
+        return this.fetchCurrentPrice(request);
+      case 'historical':
+        return this.fetchHistoricalPrices(request);
+      case 'intraday':
+        return this.fetchIntradayPrices(request);
+      case 'batch':
+        return this.fetchBatchCurrentPrices(request);
+      default:
+        throw new Error(`Unsupported request type: ${(request as any).type}`);
+    }
+  }
+
+  /**
+   * Fetch current/latest EOD price for a single ticker (new API)
+   */
+  private async fetchCurrentPrice(request: IStockCurrentRequest): Promise<IStockPrice> {
+    try {
+      let url = `${this.baseUrl}/tickers/${request.ticker}/eod/latest?access_key=${this.apiKey}`;
+
+      // Add exchange filter if specified
+      if (request.exchange) {
+        url += `&exchange=${request.exchange}`;
+      }
+
+      const response = await plugins.smartrequest.SmartRequest.create()
+        .url(url)
+        .timeout(this.config?.timeout || 10000)
+        .get();
+
+      const responseData = await response.json() as any;
+
+      // Check for API errors
+      if (responseData.error) {
+        throw new Error(`Marketstack API error: ${responseData.error.message || JSON.stringify(responseData.error)}`);
+      }
+
+      // For single ticker endpoint, response is direct object (not wrapped in data field)
+      if (!responseData || !responseData.close) {
+        throw new Error(`No data found for ticker ${request.ticker}`);
+      }
+
+      return this.mapToStockPrice(responseData, 'eod');
+    } catch (error) {
+      this.logger.error(`Failed to fetch current price for ${request.ticker}:`, error);
+      throw new Error(`Marketstack: Failed to fetch current price for ${request.ticker}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Fetch historical EOD prices for a ticker with date range
+   */
+  private async fetchHistoricalPrices(request: IStockHistoricalRequest): Promise<IStockPrice[]> {
+    try {
+      const allPrices: IStockPrice[] = [];
+      let offset = request.offset || 0;
+      const limit = request.limit || 1000; // Max per page
+      const maxRecords = 10000; // Safety limit
+
+      while (true) {
+        let url = `${this.baseUrl}/eod?access_key=${this.apiKey}`;
+        url += `&symbols=${request.ticker}`;
+        url += `&date_from=${this.formatDate(request.from)}`;
+        url += `&date_to=${this.formatDate(request.to)}`;
+        url += `&limit=${limit}`;
+        url += `&offset=${offset}`;
+
+        if (request.exchange) {
+          url += `&exchange=${request.exchange}`;
+        }
+
+        if (request.sort) {
+          url += `&sort=${request.sort}`;
+        }
+
+        const response = await plugins.smartrequest.SmartRequest.create()
+          .url(url)
+          .timeout(this.config?.timeout || 15000)
+          .get();
+
+        const responseData = await response.json() as any;
+
+        // Check for API errors
+        if (responseData.error) {
+          throw new Error(`Marketstack API error: ${responseData.error.message || JSON.stringify(responseData.error)}`);
+        }
+
+        if (!responseData?.data || !Array.isArray(responseData.data)) {
+          throw new Error('Invalid response format from Marketstack API');
+        }
+
+        // Map data to stock prices
+        for (const data of responseData.data) {
+          try {
+            allPrices.push(this.mapToStockPrice(data, 'eod'));
+          } catch (error) {
+            this.logger.warn(`Failed to parse historical data for ${data.symbol}:`, error);
+          }
+        }
+
+        // Check if we have more pages
+        const pagination = responseData.pagination;
+        const hasMore = pagination && offset + limit < pagination.total;
+
+        // Safety check: don't fetch more than maxRecords
+        if (!hasMore || allPrices.length >= maxRecords) {
+          break;
+        }
+
+        offset += limit;
+      }
+
+      return allPrices;
+    } catch (error) {
+      this.logger.error(`Failed to fetch historical prices for ${request.ticker}:`, error);
+      throw new Error(`Marketstack: Failed to fetch historical prices for ${request.ticker}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Fetch intraday prices with specified interval (Phase 2 placeholder)
+   */
+  private async fetchIntradayPrices(request: IStockIntradayRequest): Promise<IStockPrice[]> {
+    throw new Error('Intraday data support coming in Phase 2. For now, use EOD data with type: "current" or "historical"');
+  }
+
+  /**
+   * Fetch current prices for multiple tickers (new API)
+   */
+  private async fetchBatchCurrentPrices(request: IStockBatchCurrentRequest): Promise<IStockPrice[]> {
+    try {
+      const symbols = request.tickers.join(',');
+      let url = `${this.baseUrl}/eod/latest?access_key=${this.apiKey}&symbols=${symbols}`;
+
+      if (request.exchange) {
+        url += `&exchange=${request.exchange}`;
+      }
+
+      const response = await plugins.smartrequest.SmartRequest.create()
+        .url(url)
+        .timeout(this.config?.timeout || 15000)
+        .get();
+
+      const responseData = await response.json() as any;
+
+      // Check for API errors
+      if (responseData.error) {
+        throw new Error(`Marketstack API error: ${responseData.error.message || JSON.stringify(responseData.error)}`);
+      }
+
+      if (!responseData?.data || !Array.isArray(responseData.data)) {
+        throw new Error('Invalid response format from Marketstack API');
+      }
+
+      const prices: IStockPrice[] = [];
+
+      for (const data of responseData.data) {
+        try {
+          prices.push(this.mapToStockPrice(data, 'eod'));
+        } catch (error) {
+          this.logger.warn(`Failed to parse data for ${data.symbol}:`, error);
+          // Continue processing other tickers
+        }
+      }
+
+      if (prices.length === 0) {
+        throw new Error('No valid price data received from batch request');
+      }
+
+      return prices;
+    } catch (error) {
+      this.logger.error(`Failed to fetch batch current prices:`, error);
+      throw new Error(`Marketstack: Failed to fetch batch current prices: ${error.message}`);
+    }
+  }
+
+  /**
+   * Check if the Marketstack API is available and accessible
+   */
+  public async isAvailable(): Promise<boolean> {
+    try {
+      // Test with a well-known ticker
+      const url = `${this.baseUrl}/tickers/AAPL/eod/latest?access_key=${this.apiKey}`;
+
+      const response = await plugins.smartrequest.SmartRequest.create()
+        .url(url)
+        .timeout(5000)
+        .get();
+
+      const responseData = await response.json() as any;
+
+      // Check if we got valid data (not an error)
+      // Single ticker endpoint returns direct object, not wrapped in data field
+      return !responseData.error && responseData.close !== undefined;
+    } catch (error) {
+      this.logger.warn('Marketstack provider is not available:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Check if a market is supported
+   * Marketstack supports 72+ exchanges worldwide
+   */
+  public supportsMarket(market: string): boolean {
+    // Marketstack has broad international coverage including:
+    // US, UK, DE, FR, JP, CN, HK, AU, CA, IN, etc.
+    const supportedMarkets = [
+      'US', 'UK', 'GB', 'DE', 'FR', 'JP', 'CN', 'HK', 'AU', 'CA',
+      'IN', 'BR', 'MX', 'IT', 'ES', 'NL', 'SE', 'CH', 'NO', 'DK'
+    ];
+    return supportedMarkets.includes(market.toUpperCase());
+  }
+
+  /**
+   * Check if a ticker format is supported
+   */
+  public supportsTicker(ticker: string): boolean {
+    // Basic validation - Marketstack supports most standard ticker formats
+    return /^[A-Z0-9\.\-]{1,10}$/.test(ticker.toUpperCase());
+  }
+
+  /**
+   * Map Marketstack API response to IStockPrice interface
+   */
+  private mapToStockPrice(data: any, dataType: 'eod' | 'intraday' | 'live' = 'eod'): IStockPrice {
+    if (!data.close) {
+      throw new Error('Missing required price data');
+    }
+
+    // Calculate change and change percent
+    // EOD data: previous close is typically open price of the same day
+    // For better accuracy, we'd need previous day's close, but that requires another API call
+    const currentPrice = data.close;
+    const previousClose = data.open || currentPrice;
+    const change = currentPrice - previousClose;
+    const changePercent = previousClose !== 0 ? (change / previousClose) * 100 : 0;
+
+    // Parse timestamp
+    const timestamp = data.date ? new Date(data.date) : new Date();
+    const fetchedAt = new Date();
+
+    const stockPrice: IStockPrice = {
+      ticker: data.symbol.toUpperCase(),
+      price: currentPrice,
+      currency: data.price_currency || 'USD',
+      change: change,
+      changePercent: changePercent,
+      previousClose: previousClose,
+      timestamp: timestamp,
+      provider: this.name,
+      marketState: 'CLOSED', // EOD data is always for closed markets
+      exchange: data.exchange,
+      exchangeName: data.exchange_code || data.name,
+
+      // Phase 1 enhancements: OHLCV data
+      volume: data.volume,
+      open: data.open,
+      high: data.high,
+      low: data.low,
+      adjusted: data.adj_close !== undefined, // If adj_close exists, price is adjusted
+      dataType: dataType,
+      fetchedAt: fetchedAt,
+
+      // Company identification
+      companyName: data.company_name || data.name || undefined,
+      companyFullName: this.buildCompanyFullName(data)
+    };
+
+    return stockPrice;
+  }
+
+  /**
+   * Build full company name with exchange and ticker information
+   * Example: "Apple Inc (NASDAQ:AAPL)"
+   */
+  private buildCompanyFullName(data: any): string | undefined {
+    // Check if API already provides full name
+    if (data.full_name || data.long_name) {
+      return data.full_name || data.long_name;
+    }
+
+    // Build from available data
+    const companyName = data.company_name || data.name;
+    const exchangeCode = data.exchange_code; // e.g., "NASDAQ"
+    const symbol = data.symbol; // e.g., "AAPL"
+
+    if (!companyName) {
+      return undefined;
+    }
+
+    // If we have exchange and symbol, build full name: "Apple Inc (NASDAQ:AAPL)"
+    if (exchangeCode && symbol) {
+      return `${companyName} (${exchangeCode}:${symbol})`;
+    }
+
+    // If we only have symbol: "Apple Inc (AAPL)"
+    if (symbol) {
+      return `${companyName} (${symbol})`;
+    }
+
+    // Otherwise just return company name
+    return companyName;
+  }
+
+  /**
+   * Format date to YYYY-MM-DD for API requests
+   */
+  private formatDate(date: Date): string {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+  }
+}

ts/stocks/providers/provider.secedgar.ts

@@ -0,0 +1,429 @@
+import * as plugins from '../../plugins.js';
+import type {
+  IFundamentalsProvider,
+  IStockFundamentals,
+  IFundamentalsRequest,
+  IFundamentalsCurrentRequest,
+  IFundamentalsBatchRequest
+} from '../interfaces/fundamentals.js';
+
+/**
+ * Configuration for SEC EDGAR provider
+ */
+export interface ISecEdgarConfig {
+  userAgent: string; // Required: Format "Company Name Email" (e.g., "fin.cx info@fin.cx")
+  cikCacheTTL?: number; // Default: 30 days (CIK codes rarely change)
+  fundamentalsCacheTTL?: number; // Default: 90 days (quarterly filings)
+  timeout?: number; // Request timeout in ms
+}
+
+/**
+ * Rate limiter for SEC EDGAR API
+ * SEC requires: 10 requests per second maximum
+ */
+class RateLimiter {
+  private requestTimes: number[] = [];
+  private readonly maxRequestsPerSecond = 10;
+
+  public async waitForSlot(): Promise<void> {
+    const now = Date.now();
+    const oneSecondAgo = now - 1000;
+
+    // Remove requests older than 1 second
+    this.requestTimes = this.requestTimes.filter(time => time > oneSecondAgo);
+
+    // If we've hit the limit, wait
+    if (this.requestTimes.length >= this.maxRequestsPerSecond) {
+      const oldestRequest = this.requestTimes[0];
+      const waitTime = 1000 - (now - oldestRequest) + 10; // +10ms buffer
+      await plugins.smartdelay.delayFor(waitTime);
+      return this.waitForSlot(); // Recursively check again
+    }
+
+    // Record this request
+    this.requestTimes.push(now);
+  }
+}
+
+/**
+ * SEC EDGAR Fundamental Data Provider
+ *
+ * Features:
+ * - Free public access (no API key required)
+ * - All US public companies
+ * - Financial data from 10-K/10-Q filings
+ * - US GAAP standardized metrics
+ * - Historical data back to ~2009
+ * - < 1 minute filing delay
+ *
+ * Documentation: https://www.sec.gov/edgar/sec-api-documentation
+ *
+ * Rate Limits:
+ * - 10 requests per second (enforced by SEC)
+ * - Requires User-Agent header in format: "Company Name Email"
+ *
+ * Data Sources:
+ * - Company Facts API: /api/xbrl/companyfacts/CIK##########.json
+ * - Ticker Lookup: /files/company_tickers.json
+ */
+export class SecEdgarProvider implements IFundamentalsProvider {
+  public name = 'SEC EDGAR';
+  public priority = 100; // High priority - free, authoritative, comprehensive
+  public readonly requiresAuth = false; // No API key needed!
+  public readonly rateLimit = {
+    requestsPerMinute: 600, // 10 requests/second = 600/minute
+    requestsPerDay: undefined // No daily limit
+  };
+
+  private logger = console;
+  private baseUrl = 'https://data.sec.gov/api/xbrl';
+  private tickersUrl = 'https://www.sec.gov/files/company_tickers.json';
+  private userAgent: string;
+  private config: Required<ISecEdgarConfig>;
+
+  // Caching
+  private cikCache = new Map<string, { cik: string; timestamp: Date }>();
+  private tickerListCache: { data: any; timestamp: Date } | null = null;
+
+  // Rate limiting
+  private rateLimiter = new RateLimiter();
+
+  constructor(config: ISecEdgarConfig) {
+    // Validate User-Agent
+    if (!config.userAgent) {
+      throw new Error('User-Agent is required for SEC EDGAR provider (format: "Company Name Email")');
+    }
+
+    // Validate User-Agent format (must contain space and @ symbol)
+    if (!config.userAgent.includes(' ') || !config.userAgent.includes('@')) {
+      throw new Error(
+        'Invalid User-Agent format. Required: "Company Name Email" (e.g., "fin.cx info@fin.cx")'
+      );
+    }
+
+    this.userAgent = config.userAgent;
+    this.config = {
+      userAgent: config.userAgent,
+      cikCacheTTL: config.cikCacheTTL || 30 * 24 * 60 * 60 * 1000, // 30 days
+      fundamentalsCacheTTL: config.fundamentalsCacheTTL || 90 * 24 * 60 * 60 * 1000, // 90 days
+      timeout: config.timeout || 30000
+    };
+  }
+
+  /**
+   * Unified data fetching method
+   */
+  public async fetchData(
+    request: IFundamentalsRequest
+  ): Promise<IStockFundamentals | IStockFundamentals[]> {
+    switch (request.type) {
+      case 'fundamentals-current':
+        return this.fetchFundamentals(request);
+      case 'fundamentals-batch':
+        return this.fetchBatchFundamentals(request);
+      default:
+        throw new Error(`Unsupported request type: ${(request as any).type}`);
+    }
+  }
+
+  /**
+   * Fetch fundamental data for a single ticker
+   */
+  private async fetchFundamentals(request: IFundamentalsCurrentRequest): Promise<IStockFundamentals> {
+    try {
+      // 1. Get CIK for ticker (with caching)
+      const cik = await this.getCIK(request.ticker);
+
+      // 2. Fetch company facts from SEC (with rate limiting)
+      const companyFacts = await this.fetchCompanyFacts(cik);
+
+      // 3. Parse facts into structured fundamental data
+      return this.parseCompanyFacts(request.ticker, cik, companyFacts);
+    } catch (error) {
+      this.logger.error(`Failed to fetch fundamentals for ${request.ticker}:`, error);
+      throw new Error(`SEC EDGAR: Failed to fetch fundamentals for ${request.ticker}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Fetch fundamental data for multiple tickers
+   */
+  private async fetchBatchFundamentals(
+    request: IFundamentalsBatchRequest
+  ): Promise<IStockFundamentals[]> {
+    const results: IStockFundamentals[] = [];
+    const errors: string[] = [];
+
+    for (const ticker of request.tickers) {
+      try {
+        const fundamentals = await this.fetchFundamentals({
+          type: 'fundamentals-current',
+          ticker
+        });
+        results.push(fundamentals);
+      } catch (error) {
+        this.logger.warn(`Failed to fetch fundamentals for ${ticker}:`, error);
+        errors.push(`${ticker}: ${error.message}`);
+        // Continue with other tickers
+      }
+    }
+
+    if (results.length === 0) {
+      throw new Error(`Failed to fetch fundamentals for all tickers. Errors: ${errors.join(', ')}`);
+    }
+
+    return results;
+  }
+
+  /**
+   * Get CIK (Central Index Key) for a ticker symbol
+   * Uses SEC's public ticker-to-CIK mapping file
+   */
+  private async getCIK(ticker: string): Promise<string> {
+    const tickerUpper = ticker.toUpperCase();
+
+    // Check cache first
+    const cached = this.cikCache.get(tickerUpper);
+    if (cached) {
+      const age = Date.now() - cached.timestamp.getTime();
+      if (age < this.config.cikCacheTTL) {
+        return cached.cik;
+      }
+      // Cache expired, remove it
+      this.cikCache.delete(tickerUpper);
+    }
+
+    // Fetch ticker list (with caching at list level)
+    const tickers = await this.fetchTickerList();
+
+    // Find ticker in list (case-insensitive)
+    const entry = Object.values(tickers).find((t: any) => t.ticker === tickerUpper);
+
+    if (!entry) {
+      throw new Error(`CIK not found for ticker ${ticker}`);
+    }
+
+    const cik = String((entry as any).cik_str);
+
+    // Cache the result
+    this.cikCache.set(tickerUpper, {
+      cik,
+      timestamp: new Date()
+    });
+
+    return cik;
+  }
+
+  /**
+   * Fetch the SEC ticker-to-CIK mapping list
+   * Cached for 24 hours (list updates daily)
+   */
+  private async fetchTickerList(): Promise<any> {
+    // Check cache
+    if (this.tickerListCache) {
+      const age = Date.now() - this.tickerListCache.timestamp.getTime();
+      if (age < 24 * 60 * 60 * 1000) { // 24 hours
+        return this.tickerListCache.data;
+      }
+    }
+
+    // Wait for rate limit slot
+    await this.rateLimiter.waitForSlot();
+
+    // Fetch from SEC
+    const response = await plugins.smartrequest.SmartRequest.create()
+      .url(this.tickersUrl)
+      .headers({
+        'User-Agent': this.userAgent,
+        'Accept': 'application/json'
+      })
+      .timeout(this.config.timeout)
+      .get();
+
+    const data = await response.json();
+
+    // Cache the list
+    this.tickerListCache = {
+      data,
+      timestamp: new Date()
+    };
+
+    return data;
+  }
+
+  /**
+   * Fetch company facts from SEC EDGAR
+   */
+  private async fetchCompanyFacts(cik: string): Promise<any> {
+    // Pad CIK to 10 digits
+    const paddedCIK = cik.padStart(10, '0');
+    const url = `${this.baseUrl}/companyfacts/CIK${paddedCIK}.json`;
+
+    // Wait for rate limit slot
+    await this.rateLimiter.waitForSlot();
+
+    // Fetch from SEC
+    const response = await plugins.smartrequest.SmartRequest.create()
+      .url(url)
+      .headers({
+        'User-Agent': this.userAgent,
+        'Accept': 'application/json',
+        'Accept-Encoding': 'gzip, deflate',
+        'Host': 'data.sec.gov'
+      })
+      .timeout(this.config.timeout)
+      .get();
+
+    const data = await response.json();
+
+    // Validate response
+    if (!data || !data.facts) {
+      throw new Error('Invalid response from SEC EDGAR API');
+    }
+
+    return data;
+  }
+
+  /**
+   * Parse SEC company facts into structured fundamental data
+   */
+  private parseCompanyFacts(ticker: string, cik: string, data: any): IStockFundamentals {
+    const usGaap = data.facts?.['us-gaap'];
+
+    if (!usGaap) {
+      throw new Error('No US GAAP data available');
+    }
+
+    // Extract latest values for key metrics
+    const fundamentals: IStockFundamentals = {
+      ticker: ticker.toUpperCase(),
+      cik: cik,
+      companyName: data.entityName,
+      provider: this.name,
+      timestamp: new Date(),
+      fetchedAt: new Date(),
+
+      // Per-share metrics
+      earningsPerShareBasic: this.getLatestValue(usGaap, 'EarningsPerShareBasic'),
+      earningsPerShareDiluted: this.getLatestValue(usGaap, 'EarningsPerShareDiluted'),
+      sharesOutstanding: this.getLatestValue(usGaap, 'CommonStockSharesOutstanding'),
+      weightedAverageSharesOutstanding: this.getLatestValue(
+        usGaap,
+        'WeightedAverageNumberOfSharesOutstandingBasic'
+      ),
+
+      // Income statement
+      revenue: this.getLatestValue(usGaap, 'Revenues') ||
+               this.getLatestValue(usGaap, 'RevenueFromContractWithCustomerExcludingAssessedTax'),
+      netIncome: this.getLatestValue(usGaap, 'NetIncomeLoss'),
+      operatingIncome: this.getLatestValue(usGaap, 'OperatingIncomeLoss'),
+      grossProfit: this.getLatestValue(usGaap, 'GrossProfit'),
+      costOfRevenue: this.getLatestValue(usGaap, 'CostOfRevenue'),
+
+      // Balance sheet
+      assets: this.getLatestValue(usGaap, 'Assets'),
+      liabilities: this.getLatestValue(usGaap, 'Liabilities'),
+      stockholdersEquity: this.getLatestValue(usGaap, 'StockholdersEquity'),
+      cash: this.getLatestValue(usGaap, 'CashAndCashEquivalentsAtCarryingValue'),
+      propertyPlantEquipment: this.getLatestValue(usGaap, 'PropertyPlantAndEquipmentNet'),
+
+      // Metadata (from latest available data point)
+      fiscalYear: this.getLatestMetadata(usGaap, 'EarningsPerShareDiluted')?.fy,
+      fiscalQuarter: this.getLatestMetadata(usGaap, 'EarningsPerShareDiluted')?.fp,
+      filingDate: this.getLatestMetadata(usGaap, 'EarningsPerShareDiluted')?.filed
+        ? new Date(this.getLatestMetadata(usGaap, 'EarningsPerShareDiluted')!.filed)
+        : undefined,
+      form: this.getLatestMetadata(usGaap, 'EarningsPerShareDiluted')?.form
+    };
+
+    return fundamentals;
+  }
+
+  /**
+   * Get the latest value for a US GAAP metric
+   */
+  private getLatestValue(usGaap: any, metricName: string): number | undefined {
+    const metric = usGaap[metricName];
+    if (!metric?.units) {
+      return undefined;
+    }
+
+    // Get the first unit type (USD, shares, etc.)
+    const unitType = Object.keys(metric.units)[0];
+    const values = metric.units[unitType];
+
+    if (!values || !Array.isArray(values) || values.length === 0) {
+      return undefined;
+    }
+
+    // Get the latest value (last in array)
+    const latest = values[values.length - 1];
+    return latest?.val;
+  }
+
+  /**
+   * Get metadata from the latest data point
+   */
+  private getLatestMetadata(usGaap: any, metricName: string): any | undefined {
+    const metric = usGaap[metricName];
+    if (!metric?.units) {
+      return undefined;
+    }
+
+    const unitType = Object.keys(metric.units)[0];
+    const values = metric.units[unitType];
+
+    if (!values || !Array.isArray(values) || values.length === 0) {
+      return undefined;
+    }
+
+    return values[values.length - 1];
+  }
+
+  /**
+   * Check if SEC EDGAR API is available
+   */
+  public async isAvailable(): Promise<boolean> {
+    try {
+      // Test with Apple's well-known CIK
+      const url = `${this.baseUrl}/companyfacts/CIK0000320193.json`;
+
+      const response = await plugins.smartrequest.SmartRequest.create()
+        .url(url)
+        .headers({
+          'User-Agent': this.userAgent,
+          'Accept': 'application/json'
+        })
+        .timeout(5000)
+        .get();
+
+      const data = await response.json();
+      return data && data.facts !== undefined;
+    } catch (error) {
+      this.logger.warn('SEC EDGAR provider is not available:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Get cache statistics
+   */
+  public getCacheStats(): {
+    cikCacheSize: number;
+    hasTickerList: boolean;
+  } {
+    return {
+      cikCacheSize: this.cikCache.size,
+      hasTickerList: this.tickerListCache !== null
+    };
+  }
+
+  /**
+   * Clear all caches
+   */
+  public clearCache(): void {
+    this.cikCache.clear();
+    this.tickerListCache = null;
+    this.logger.log('SEC EDGAR cache cleared');
+  }
+}

ts/stocks/providers/provider.yahoo.ts

@@ -0,0 +1,194 @@
+import * as plugins from '../../plugins.js';
+import type { IStockProvider, IProviderConfig } from '../interfaces/provider.js';
+import type {
+  IStockPrice,
+  IStockDataRequest,
+  IStockCurrentRequest,
+  IStockBatchCurrentRequest
+} from '../interfaces/stockprice.js';
+
+export class YahooFinanceProvider implements IStockProvider {
+  public name = 'Yahoo Finance';
+  public priority = 100;
+  public readonly requiresAuth = false;
+  public readonly rateLimit = {
+    requestsPerMinute: 100, // Conservative estimate
+    requestsPerDay: undefined
+  };
+
+  private logger = console;
+  private baseUrl = 'https://query1.finance.yahoo.com';
+  private userAgent = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+
+  constructor(private config?: IProviderConfig) {}
+
+  /**
+   * Unified data fetching method
+   */
+  public async fetchData(request: IStockDataRequest): Promise<IStockPrice | IStockPrice[]> {
+    switch (request.type) {
+      case 'current':
+        return this.fetchCurrentPrice(request);
+      case 'batch':
+        return this.fetchBatchCurrentPrices(request);
+      case 'historical':
+        throw new Error('Yahoo Finance provider does not support historical data. Use Marketstack provider instead.');
+      case 'intraday':
+        throw new Error('Yahoo Finance provider does not support intraday data yet. Use Marketstack provider instead.');
+      default:
+        throw new Error(`Unsupported request type: ${(request as any).type}`);
+    }
+  }
+
+  /**
+   * Fetch current price for a single ticker
+   */
+  private async fetchCurrentPrice(request: IStockCurrentRequest): Promise<IStockPrice> {
+    try {
+      const url = `${this.baseUrl}/v8/finance/chart/${request.ticker}`;
+      const response = await plugins.smartrequest.SmartRequest.create()
+        .url(url)
+        .headers({
+          'User-Agent': this.userAgent
+        })
+        .timeout(this.config?.timeout || 10000)
+        .get();
+
+      const responseData = await response.json() as any;
+      
+      if (!responseData?.chart?.result?.[0]) {
+        throw new Error(`No data found for ticker ${request.ticker}`);
+      }
+
+      const data = responseData.chart.result[0];
+      const meta = data.meta;
+      
+      if (!meta.regularMarketPrice) {
+        throw new Error(`No price data available for ${request.ticker}`);
+      }
+
+      const stockPrice: IStockPrice = {
+        ticker: request.ticker.toUpperCase(),
+        price: meta.regularMarketPrice,
+        currency: meta.currency || 'USD',
+        change: meta.regularMarketPrice - meta.previousClose,
+        changePercent: ((meta.regularMarketPrice - meta.previousClose) / meta.previousClose) * 100,
+        previousClose: meta.previousClose,
+        timestamp: new Date(meta.regularMarketTime * 1000),
+        provider: this.name,
+        marketState: this.determineMarketState(meta),
+        exchange: meta.exchange,
+        exchangeName: meta.exchangeName,
+        dataType: 'live', // Yahoo provides real-time/near real-time data
+        fetchedAt: new Date()
+      };
+
+      return stockPrice;
+    } catch (error) {
+      console.error(`Failed to fetch price for ${request.ticker}:`, error);
+      throw new Error(`Yahoo Finance: Failed to fetch price for ${request.ticker}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Fetch batch current prices
+   */
+  private async fetchBatchCurrentPrices(request: IStockBatchCurrentRequest): Promise<IStockPrice[]> {
+    try {
+      const symbols = request.tickers.join(',');
+      const url = `${this.baseUrl}/v8/finance/spark?symbols=${symbols}&range=1d&interval=5m`;
+      
+      const response = await plugins.smartrequest.SmartRequest.create()
+        .url(url)
+        .headers({
+          'User-Agent': this.userAgent
+        })
+        .timeout(this.config?.timeout || 15000)
+        .get();
+
+      const responseData = await response.json() as any;
+      const prices: IStockPrice[] = [];
+      
+      for (const [ticker, data] of Object.entries(responseData)) {
+        if (!data || typeof data !== 'object') continue;
+        
+        const sparkData = data as any;
+        if (!sparkData.previousClose || !sparkData.close?.length) {
+          console.warn(`Incomplete data for ${ticker}, skipping`);
+          continue;
+        }
+
+        const currentPrice = sparkData.close[sparkData.close.length - 1];
+        const timestamp = sparkData.timestamp?.[sparkData.timestamp.length - 1];
+        
+        prices.push({
+          ticker: ticker.toUpperCase(),
+          price: currentPrice,
+          currency: sparkData.currency || 'USD',
+          change: currentPrice - sparkData.previousClose,
+          changePercent: ((currentPrice - sparkData.previousClose) / sparkData.previousClose) * 100,
+          previousClose: sparkData.previousClose,
+          timestamp: timestamp ? new Date(timestamp * 1000) : new Date(),
+          provider: this.name,
+          marketState: sparkData.marketState || 'REGULAR',
+          exchange: sparkData.exchange,
+          exchangeName: sparkData.exchangeName,
+          dataType: 'live', // Yahoo provides real-time/near real-time data
+          fetchedAt: new Date()
+        });
+      }
+
+      if (prices.length === 0) {
+        throw new Error('No valid price data received from batch request');
+      }
+
+      return prices;
+    } catch (error) {
+      console.error(`Failed to fetch batch prices:`, error);
+      throw new Error(`Yahoo Finance: Failed to fetch batch prices: ${error.message}`);
+    }
+  }
+
+  public async isAvailable(): Promise<boolean> {
+    try {
+      // Test with a well-known ticker
+      await this.fetchData({ type: 'current', ticker: 'AAPL' });
+      return true;
+    } catch (error) {
+      console.warn('Yahoo Finance provider is not available:', error);
+      return false;
+    }
+  }
+
+  public supportsMarket(market: string): boolean {
+    // Yahoo Finance supports most major markets
+    const supportedMarkets = ['US', 'UK', 'DE', 'FR', 'JP', 'CN', 'HK', 'AU', 'CA'];
+    return supportedMarkets.includes(market.toUpperCase());
+  }
+
+  public supportsTicker(ticker: string): boolean {
+    // Basic validation - Yahoo supports most tickers
+    return /^[A-Z0-9\.\-]{1,10}$/.test(ticker.toUpperCase());
+  }
+
+  private determineMarketState(meta: any): 'PRE' | 'REGULAR' | 'POST' | 'CLOSED' {
+    const marketState = meta.marketState?.toUpperCase();
+    
+    switch (marketState) {
+      case 'PRE':
+        return 'PRE';
+      case 'POST':
+        return 'POST';
+      case 'REGULAR':
+        return 'REGULAR';
+      default:
+        // Check if market is currently open based on timestamps
+        const now = Date.now() / 1000;
+        const regularMarketTime = meta.regularMarketTime;
+        const timeDiff = now - regularMarketTime;
+        
+        // If last update was more than 1 hour ago, market is likely closed
+        return timeDiff > 3600 ? 'CLOSED' : 'REGULAR';
+    }
+  }
+}