@fin.cx/opendata 3.5.0 → 3.6.0

package/ts/laws/index.ts

@@ -0,0 +1,3 @@
+export * from './interfaces.law.js';
+export * from './classes.lawrecord.js';
+export * from './classes.lawservice.js';

package/ts/laws/interfaces.law.ts

@@ -0,0 +1,48 @@
+export type TJurisdiction = 'de' | 'eu' | 'us';
+
+export type TLawSource =
+  | 'gesetze-im-internet'
+  | 'eur-lex'
+  | 'law-cornell-lii'
+  | 'govinfo-plaw'
+  | 'govinfo-uscode';
+
+export type TRawLawFormat = 'xml' | 'html' | 'text' | 'json';
+
+export type TUsLawCollection = 'PLAW' | 'USCODE';
+
+export interface ILawServiceConfig {
+  dbFolderPath?: string;
+  dbName?: string;
+  govInfoApiKey?: string;
+}
+
+export interface ILawLookupRequest {
+  jurisdiction: TJurisdiction;
+  identifier: string;
+  language?: string;
+  usCollection?: TUsLawCollection;
+  forceSync?: boolean;
+}
+
+export interface ILawSyncRequest {
+  jurisdiction: TJurisdiction;
+  limit?: number;
+  offset?: number;
+  language?: string;
+  govInfoApiKey?: string;
+  usCollection?: TUsLawCollection;
+  since?: Date;
+}
+
+export interface ILawSearchRequest {
+  query: string;
+  jurisdiction?: TJurisdiction;
+  limit?: number;
+}
+
+export interface ILawSyncResult {
+  jurisdiction: TJurisdiction;
+  syncedCount: number;
+  identifiers: string[];
+}

package/ts/plugins.ts

@@ -1,7 +1,9 @@
 // node native scope
+import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 
 export {
+  fs,
   path,
 }
 
@@ -14,23 +16,40 @@ 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 { SmartFs, SmartFsProviderNode } from '@push.rocks/smartfs';
 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';
+import * as smartdb from '@push.rocks/smartdb';
 import * as smartstream from '@push.rocks/smartstream';
 import * as smartunique from '@push.rocks/smartunique';
 import * as smartxml from '@push.rocks/smartxml'; 
 
+const smartfs = new SmartFs(new SmartFsProviderNode());
+const smartfileFactory = new smartfile.SmartFileFactory(smartfs);
+
+const getErrorMessage = (error: unknown) => {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+};
+
 export {
+  getErrorMessage,
   lik,
   qenv,
   smartarchive,
   smartarray,
   smartbrowser,
+  smartdb,
   smartdata,
   smartdelay,
   smartfile,
+  smartfileFactory,
+  smartfs,
   smartlog,
   smartpath,
   smartpromise,

package/ts/stocks/classes.fundamentalsservice.ts

@@ -166,7 +166,7 @@ export class FundamentalsService implements IFundamentalsProviderRegistry {
         lastError = error as Error;
 
         console.warn(
-          `Provider ${provider.name} failed for ${this.getRequestDescription(request)}: ${error.message}`
+          `Provider ${provider.name} failed for ${this.getRequestDescription(request)}: ${plugins.getErrorMessage(error)}`
         );
       }
     }

package/ts/stocks/classes.stockdataservice.ts

@@ -32,7 +32,17 @@ export class StockDataService {
 
   private logger = console;
 
-  private config: Required<IStockDataServiceConfig> = {
+  private config: {
+    cache: {
+      priceTTL: number;
+      fundamentalsTTL: number;
+      maxEntries: number;
+    };
+    timeout: {
+      price: number;
+      fundamentals: number;
+    };
+  } = {
     cache: {
       priceTTL: 24 * 60 * 60 * 1000, // 24 hours
       fundamentalsTTL: 90 * 24 * 60 * 60 * 1000, // 90 days
@@ -200,7 +210,7 @@ export class StockDataService {
         entry.lastErrorTime = new Date();
         lastError = error as Error;
 
-        console.warn(`Provider ${provider.name} failed for ${ticker}: ${error.message}`);
+        console.warn(`Provider ${provider.name} failed for ${ticker}: ${plugins.getErrorMessage(error)}`);
       }
     }
 
@@ -250,7 +260,7 @@ export class StockDataService {
         entry.lastErrorTime = new Date();
         lastError = error as Error;
 
-        console.warn(`Provider ${provider.name} failed for batch prices: ${error.message}`);
+        console.warn(`Provider ${provider.name} failed for batch prices: ${plugins.getErrorMessage(error)}`);
       }
     }
 
@@ -301,7 +311,7 @@ export class StockDataService {
         entry.lastErrorTime = new Date();
         lastError = error as Error;
 
-        console.warn(`Provider ${provider.name} failed for ${ticker} fundamentals: ${error.message}`);
+        console.warn(`Provider ${provider.name} failed for ${ticker} fundamentals: ${plugins.getErrorMessage(error)}`);
       }
     }
 
@@ -352,7 +362,7 @@ export class StockDataService {
         entry.lastErrorTime = new Date();
         lastError = error as Error;
 
-        console.warn(`Provider ${provider.name} failed for batch fundamentals: ${error.message}`);
+        console.warn(`Provider ${provider.name} failed for batch fundamentals: ${plugins.getErrorMessage(error)}`);
       }
     }
 
@@ -382,7 +392,7 @@ export class StockDataService {
           fundamentals = this.enrichWithPrice(fundamentals, price.price);
         }
       } catch (error) {
-        console.warn(`Failed to fetch fundamentals for ${normalizedRequest.ticker}: ${error.message}`);
+        console.warn(`Failed to fetch fundamentals for ${normalizedRequest.ticker}: ${plugins.getErrorMessage(error)}`);
         // Continue without fundamentals
       }
     }
@@ -426,7 +436,7 @@ export class StockDataService {
           fundamentalsMap = new Map(fundamentals.map(f => [f.ticker, f]));
         }
       } catch (error) {
-        console.warn(`Failed to fetch batch fundamentals: ${error.message}`);
+        console.warn(`Failed to fetch batch fundamentals: ${plugins.getErrorMessage(error)}`);
         // Continue without fundamentals
       }
     }

package/ts/stocks/classes.stockservice.ts

@@ -205,7 +205,7 @@ export class StockPriceService implements IProviderRegistry {
         lastError = error as Error;
 
         console.warn(
-          `Provider ${provider.name} failed for ${this.getRequestDescription(request)}: ${error.message}`
+          `Provider ${provider.name} failed for ${this.getRequestDescription(request)}: ${plugins.getErrorMessage(error)}`
         );
       }
     }
@@ -522,4 +522,4 @@ export class StockPriceService implements IProviderRegistry {
       ttl: ttl || this.cacheConfig.ttl
     });
   }
-}
+}

package/ts/stocks/providers/provider.marketstack.ts

@@ -45,7 +45,7 @@ export class MarketstackProvider implements IStockProvider {
   public priority = 90; // Increased from 80 - now supports real-time intraday data during market hours
   public readonly requiresAuth = true;
   public readonly rateLimit = {
-    requestsPerMinute: undefined, // No per-minute limit specified
+    requestsPerMinute: 0, // No per-minute limit specified
     requestsPerDay: undefined // Varies by plan
   };
 
@@ -99,8 +99,9 @@ export class MarketstackProvider implements IStockProvider {
       }
     } catch (error) {
       // If intraday fails, fallback to EOD with warning
-      if (error.message?.includes('intraday') || error.message?.includes('Marketstack API error')) {
-        this.logger.warn(`Intraday endpoint failed for ${request.ticker}, falling back to EOD:`, error.message);
+      const errorMessage = plugins.getErrorMessage(error);
+      if (errorMessage.includes('intraday') || errorMessage.includes('Marketstack API error')) {
+        this.logger.warn(`Intraday endpoint failed for ${request.ticker}, falling back to EOD:`, errorMessage);
         try {
           return await this.fetchCurrentPriceEod(request);
         } catch (eodError) {
@@ -245,7 +246,7 @@ export class MarketstackProvider implements IStockProvider {
       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}`);
+      throw new Error(`Marketstack: Failed to fetch historical prices for ${request.ticker}: ${plugins.getErrorMessage(error)}`);
     }
   }
 
@@ -337,7 +338,7 @@ export class MarketstackProvider implements IStockProvider {
       return allPrices;
     } catch (error) {
       this.logger.error(`Failed to fetch intraday prices for ${request.ticker}:`, error);
-      throw new Error(`Marketstack: Failed to fetch intraday prices for ${request.ticker}: ${error.message}`);
+      throw new Error(`Marketstack: Failed to fetch intraday prices for ${request.ticker}: ${plugins.getErrorMessage(error)}`);
     }
   }
 
@@ -359,8 +360,9 @@ export class MarketstackProvider implements IStockProvider {
       }
     } catch (error) {
       // Fallback to EOD if intraday fails
-      if (error.message?.includes('intraday') || error.message?.includes('Marketstack API error')) {
-        this.logger.warn(`Intraday batch endpoint failed, falling back to EOD:`, error.message);
+      const errorMessage = plugins.getErrorMessage(error);
+      if (errorMessage.includes('intraday') || errorMessage.includes('Marketstack API error')) {
+        this.logger.warn(`Intraday batch endpoint failed, falling back to EOD:`, errorMessage);
         try {
           return await this.fetchBatchCurrentPricesEod(request);
         } catch (eodError) {

package/ts/stocks/providers/provider.secedgar.ts

@@ -141,7 +141,7 @@ export class SecEdgarProvider implements IFundamentalsProvider {
       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}`);
+      throw new Error(`SEC EDGAR: Failed to fetch fundamentals for ${request.ticker}: ${plugins.getErrorMessage(error)}`);
     }
   }
 
@@ -163,7 +163,7 @@ export class SecEdgarProvider implements IFundamentalsProvider {
         results.push(fundamentals);
       } catch (error) {
         this.logger.warn(`Failed to fetch fundamentals for ${ticker}:`, error);
-        errors.push(`${ticker}: ${error.message}`);
+        errors.push(`${ticker}: ${plugins.getErrorMessage(error)}`);
         // Continue with other tickers
       }
     }

package/ts/stocks/providers/provider.yahoo.ts

@@ -86,7 +86,7 @@ export class YahooFinanceProvider implements IStockProvider {
       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}`);
+      throw new Error(`Yahoo Finance: Failed to fetch price for ${request.ticker}: ${plugins.getErrorMessage(error)}`);
     }
   }
 
@@ -145,7 +145,7 @@ export class YahooFinanceProvider implements IStockProvider {
       return prices;
     } catch (error) {
       console.error(`Failed to fetch batch prices:`, error);
-      throw new Error(`Yahoo Finance: Failed to fetch batch prices: ${error.message}`);
+      throw new Error(`Yahoo Finance: Failed to fetch batch prices: ${plugins.getErrorMessage(error)}`);
     }
   }
 
@@ -191,4 +191,4 @@ export class YahooFinanceProvider implements IStockProvider {
         return timeDiff > 3600 ? 'CLOSED' : 'REGULAR';
     }
   }
-}
+}

package/dist_ts/classes.germanbusinessdata.d.ts

@@ -1,9 +0,0 @@
-import type { OpenData } from './classes.main.opendata.js';
-export declare class GermanBusinessData {
-    openDataRef: OpenData;
-    constructor(openDataRefArg: OpenData);
-    start(): Promise<void>;
-    stop(): Promise<void>;
-    update(): Promise<void>;
-    getBusinessRecordByName(nameArg: string): Promise<import("./classes.businessrecord.js").BusinessRecord>;
-}

package/dist_ts/classes.germanbusinessdata.js

@@ -1,78 +0,0 @@
-import * as plugins from './plugins.js';
-import * as paths from './paths.js';
-export class GermanBusinessData {
-    constructor(openDataRefArg) {
-        this.openDataRef = openDataRefArg;
-    }
-    async start() {
-        await this.update();
-    }
-    async stop() { }
-    async update() {
-        const done = plugins.smartpromise.defer();
-        const promiseArray = [];
-        const dataUrl = 'https://daten.offeneregister.de/de_companies_ocdata.jsonl.bz2';
-        const dataExists = await plugins.smartfile.fs.isDirectory(paths.germanBusinessDataDir);
-        if (!dataExists) {
-            await plugins.smartfile.fs.ensureDir(paths.germanBusinessDataDir);
-        }
-        else {
-        }
-        const smartarchive = await plugins.smartarchive.SmartArchive.fromArchiveUrl(dataUrl);
-        promiseArray
-            .push();
-        const jsonlDataStream = await smartarchive.exportToStreamOfStreamFiles();
-        let totalRecordsCounter = 0;
-        let nextRest = '';
-        jsonlDataStream.pipe(new plugins.smartstream.SmartDuplex({
-            objectMode: true,
-            writeFunction: async (chunkArg, streamToolsArg) => {
-                const readStream = await chunkArg.createReadStream();
-                readStream.pipe(new plugins.smartstream.SmartDuplex({
-                    objectMode: true,
-                    writeFunction: async (chunkArg, streamToolsArg) => {
-                        const currentString = nextRest + chunkArg.toString();
-                        const lines = currentString.split('\n');
-                        nextRest = lines.pop();
-                        console.log(`Got another ${lines.length} records.`);
-                        for (const line of lines) {
-                            let entry;
-                            if (!line)
-                                continue;
-                            try {
-                                entry = JSON.parse(line);
-                            }
-                            catch (err) {
-                                console.log(line);
-                                await plugins.smartdelay.delayFor(10000);
-                            }
-                            if (!entry)
-                                continue;
-                            totalRecordsCounter++;
-                            if (totalRecordsCounter % 10000 === 0)
-                                console.log(`${totalRecordsCounter} total records.`);
-                            const businessRecord = new this.openDataRef.CBusinessRecord();
-                            businessRecord.data.name = entry.name;
-                            await businessRecord.save();
-                            // console.log(`stored ${businessRecord.data.name}`);
-                        }
-                    },
-                    finalFunction: async (streamToolsArg) => {
-                        if (!nextRest)
-                            return;
-                        JSON.parse(nextRest);
-                    }
-                }));
-            },
-        }));
-    }
-    async getBusinessRecordByName(nameArg) {
-        const businessRecord = await this.openDataRef.CBusinessRecord.getInstance({
-            data: {
-                name: { $regex: `${nameArg}`, $options: "i" },
-            }
-        });
-        return businessRecord;
-    }
-}
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5nZXJtYW5idXNpbmVzc2RhdGEuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9jbGFzc2VzLmdlcm1hbmJ1c2luZXNzZGF0YS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQUN4QyxPQUFPLEtBQUssS0FBSyxNQUFNLFlBQVksQ0FBQztBQUdwQyxNQUFNLE9BQU8sa0JBQWtCO0lBRTdCLFlBQVksY0FBd0I7UUFDbEMsSUFBSSxDQUFDLFdBQVcsR0FBRyxjQUFjLENBQUM7SUFDcEMsQ0FBQztJQUVNLEtBQUssQ0FBQyxLQUFLO1FBQ2hCLE1BQU0sSUFBSSxDQUFDLE1BQU0sRUFBRSxDQUFDO0lBQ3RCLENBQUM7SUFDTSxLQUFLLENBQUMsSUFBSSxLQUFJLENBQUM7SUFFZixLQUFLLENBQUMsTUFBTTtRQUNqQixNQUFNLElBQUksR0FBRyxPQUFPLENBQUMsWUFBWSxDQUFDLEtBQUssRUFBRSxDQUFDO1FBQzFDLE1BQU0sWUFBWSxHQUFtQixFQUFFLENBQUM7UUFDeEMsTUFBTSxPQUFPLEdBQUcsK0RBQStELENBQUM7UUFDaEYsTUFBTSxVQUFVLEdBQUcsTUFBTSxPQUFPLENBQUMsU0FBUyxDQUFDLEVBQUUsQ0FBQyxXQUFXLENBQUMsS0FBSyxDQUFDLHFCQUFxQixDQUFDLENBQUM7UUFDdkYsSUFBSSxDQUFDLFVBQVUsRUFBRTtZQUNmLE1BQU0sT0FBTyxDQUFDLFNBQVMsQ0FBQyxFQUFFLENBQUMsU0FBUyxDQUFDLEtBQUssQ0FBQyxxQkFBcUIsQ0FBQyxDQUFDO1NBQ25FO2FBQU07U0FDTjtRQUVELE1BQU0sWUFBWSxHQUFHLE1BQU0sT0FBTyxDQUFDLFlBQVksQ0FBQyxZQUFZLENBQUMsY0FBYyxDQUFDLE9BQU8sQ0FBQyxDQUFDO1FBQ3JGLFlBQVk7YUFDVCxJQUFJLEVBRUgsQ0FBQztRQUNMLE1BQU0sZUFBZSxHQUFHLE1BQU0sWUFBWSxDQUFDLDJCQUEy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

package/readme.plan.md

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