market-feed 0.1.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,218 @@
 # market-feed Changelog
 
+## 0.4.0 — 2026-03-11
+
+### New module
+
+**`market-feed/ws`** — True WebSocket streaming for tick-by-tick trade data.
+
+Unlike `market-feed/stream` (which is HTTP polling), `market-feed/ws` opens a
+persistent WebSocket connection and yields individual trade executions in real time.
+
+```ts
+import { connect } from "market-feed/ws";
+import { FinnhubProvider } from "market-feed";
+
+const provider = new FinnhubProvider({ apiKey: process.env.FINNHUB_KEY! });
+const controller = new AbortController();
+
+for await (const event of connect(provider, ["AAPL", "MSFT"], { signal: controller.signal })) {
+  switch (event.type) {
+    case "trade":
+      console.log(`${event.trade.symbol}: $${event.trade.price} × ${event.trade.size}`);
+      break;
+    case "connected":
+      console.log(`Connected to ${event.provider}`);
+      break;
+    case "disconnected":
+      console.log(`Disconnected (reconnecting: ${event.reconnecting})`);
+      break;
+    case "error":
+      if (!event.recoverable) throw event.error;
+      break;
+  }
+}
+```
+
+#### Provider support
+
+| Provider | WebSocket | Notes |
+|----------|-----------|-------|
+| **PolygonProvider** | Native WS | `wss://socket.polygon.io/stocks` — auth via JSON handshake, subscribes to `T.*` trade channel |
+| **FinnhubProvider** | Native WS | `wss://ws.finnhub.io?token=KEY` — per-symbol subscribe, batched trade messages |
+| **YahooProvider** | Polling fallback | Polls `provider.quote()` every 5 s; emits `WsTrade` from quote data |
+| **AlphaVantageProvider** | Polling fallback | Same as Yahoo |
+
+The `connect()` function detects provider capability automatically — no configuration required.
+
+#### `WsEvent` union
+
+| `type` | Payload | When |
+|--------|---------|------|
+| `"connected"` | `provider: string` | WS opened (and after each reconnect) |
+| `"trade"` | `trade: WsTrade` | Each trade tick |
+| `"disconnected"` | `provider`, `reconnecting`, `attempt` | WS closed unexpectedly |
+| `"error"` | `error`, `recoverable` | Protocol or network error |
+
+#### `WsTrade`
+
+```ts
+interface WsTrade {
+  symbol: string;
+  price: number;
+  size: number;         // shares / units
+  timestamp: Date;
+  conditions?: number[]; // provider-specific condition codes
+}
+```
+
+#### `WsOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `wsImpl` | `typeof globalThis.WebSocket` | `globalThis.WebSocket` | Custom WS constructor for Node 18–20 |
+| `maxReconnectAttempts` | `number` | `10` | Reconnect attempts before closing |
+| `reconnectDelayMs` | `number` | `1000` | Base delay (doubles per attempt, max 30 s) |
+| `signal` | `AbortSignal` | — | Stop the stream |
+
+#### Node 18–20 compatibility
+
+Node 21+ exposes `WebSocket` globally. For Node 18/20, install the `ws` package and inject it:
+
+```ts
+import WebSocket from "ws";
+connect(provider, ["AAPL"], { wsImpl: WebSocket as unknown as typeof globalThis.WebSocket })
+```
+
+### Other changes
+
+- `PolygonProvider` now exposes `get wsApiKey(): string` (used internally by `market-feed/ws`)
+- `FinnhubProvider` now exposes `get wsApiKey(): string` (used internally by `market-feed/ws`)
+- 27 new unit tests (341 total across 18 test files)
+- 7 tsup library entry points + 1 CLI binary: `index`, `calendar`, `stream`, `consensus`, `indicators`, `portfolio`, `ws`, `cli`
+
+### Breaking changes
+
+None. All v0.3.0 imports continue to work unchanged.
+
+---
+
+## 0.3.0 — 2026-03-11
+
+### New provider
+
+**`FinnhubProvider`** — Finnhub.io (free tier: real-time US stock data, 60 calls/minute).
+- `quote`, `historical` (candles), `search`, `company`, `news`
+- API key required — get one free at https://finnhub.io
+- Uses `X-Finnhub-Token` header; rate-limited client-side at 60 req/min
+- `historical` maps standard intervals to Finnhub resolutions (1m→"1", 1d→"D", 1wk→"W", 1mo→"M")
+- `news` fetches articles from the last 30 days by default
+
+### New modules
+
+**`market-feed/indicators`** — Technical indicators as pure functions over `HistoricalBar[]`.
+- `sma(bars, period)` — Simple Moving Average (O(1) sliding window)
+- `ema(bars, period)` — Exponential Moving Average (k = 2/(period+1), SMA-seeded)
+- `rsi(bars, period?)` — Relative Strength Index via Wilder's smoothing (default period: 14)
+- `macd(bars, fast?, slow?, signal?)` — MACD line, signal line, histogram (default 12/26/9)
+- `bollingerBands(bars, period?, stdDevMult?)` — upper/middle/lower bands (default 20/2)
+- `atr(bars, period?)` — Average True Range via Wilder's smoothing (default period: 14)
+- `vwap(bars)` — Volume-Weighted Average Price (cumulative from first bar)
+- `stochastic(bars, kPeriod?, dPeriod?)` — %K and %D oscillator (default 14/3)
+- Zero dependencies, no network, tree-shakeable per indicator
+- All functions return typed result arrays (`IndicatorPoint[]`, `MACDPoint[]`, `BollingerPoint[]`, `StochasticPoint[]`)
+
+**`market-feed/portfolio`** — Track positions and compute live P&L.
+- `new Portfolio(positions?)` — construct with an array of `Position` objects
+- `portfolio.add(position)` / `portfolio.remove(symbol)` — mutable, chainable
+- `portfolio.snapshot(feed)` — fetches live quotes and returns `PortfolioSnapshot` with per-position and aggregate P&L
+- `PositionSnapshot` includes: `marketValue`, `costBasis`, `unrealizedPnl`, `unrealizedPnlPct`, `dayChange`, `dayChangePct`, `quote`
+- `PortfolioSnapshot` includes aggregate totals: `totalMarketValue`, `totalCostBasis`, `totalUnrealizedPnl`, `totalDayChange`
+- Supports long and short positions (negative `quantity`)
+- Uses `QuoteFetcher` duck-type interface — accepts any object with a `quote(symbols)` method, including `MarketFeed`
+
+### CLI (`npx market-feed`)
+
+A zero-install CLI that uses Yahoo Finance by default (no API key needed).
+
+```
+market-feed quote AAPL MSFT GOOGL
+market-feed historical AAPL --interval 1wk --period1 2024-01-01
+market-feed search "apple inc"
+market-feed company AAPL
+market-feed news AAPL --limit 5 --json
+```
+
+Flags: `--av-key`, `--polygon-key`, `--finnhub-key`, `--json`, `--limit`, `--interval`, `--period1`, `--period2`
+
+### Crypto / Forex support
+
+- `isCrypto(symbol)` — detects `"BTC-USD"`, `"BTC/USD"`, `"X:BTCUSD"` using a known-crypto-bases set
+- `isForex(symbol)` — detects `"EURUSD=X"`, `"C:EURUSD"`, `"OANDA:EUR_USD"`, `"EUR/USD"`
+- `toFinnhubSymbol(symbol)` — normalises symbol for Finnhub
+- `CRYPTO` exchange added to the calendar — `alwaysOpen: true`, no holidays, no session boundaries
+  - `isMarketOpen("CRYPTO")` → always `true`
+  - `getSession("CRYPTO")` → always `"regular"`
+  - `isHoliday("CRYPTO")` → always `false`
+  - `nextSessionOpen("CRYPTO")` → returns `from` (already open)
+  - `nextSessionClose("CRYPTO")` → returns `from + 24h` (rolling window)
+
+### Breaking changes
+
+None. All v0.2.0 imports continue to work unchanged.
+
+### Other changes
+
+- `isCrypto`, `isForex`, `toFinnhubSymbol` exported from main `market-feed` entry point
+- `FinnhubProvider` and `FinnhubProviderOptions` exported from main `market-feed` entry point
+- 94 new unit tests (314 total across 17 test files)
+- 6 library tsup entry points + 1 CLI binary: `index`, `calendar`, `stream`, `consensus`, `indicators`, `portfolio`, `cli`
+
+---
+
+## 0.2.0 — 2026-03-11
+
+### New modules
+
+**`market-feed/calendar`** — Synchronous exchange calendar. No network required.
+- `isMarketOpen(exchange, at?)` — boolean, DST-correct via `Intl`
+- `getSession(exchange, at?)` — `"pre" | "regular" | "post" | "closed"`
+- `nextSessionOpen(exchange, from?)` / `nextSessionClose(exchange, from?)` — next UTC Date
+- `isHoliday(exchange, date?)` / `isEarlyClose(exchange, date?)` — boolean
+- `getHolidayDates(exchange, year)` — all holidays for a given year
+- `getExchangeInfo(exchange)` — name, MIC, timezone, open/close times, currency
+- Supports: NYSE, NASDAQ, LSE, TSX, ASX, XETRA, NSE, BSE
+- Holiday rules computed from first principles (Easter via Meeus/Jones/Butcher algorithm, all US federal/NYSE-specific rules, UK bank holidays, Canadian/Australian/German/Indian holidays)
+- Early-close days (NYSE: day before Thanksgiving, Independence Day, Christmas Eve)
+
+**`market-feed/stream`** — Market-hours-aware observable quote stream.
+- `watch(feed, symbols, options)` — async generator yielding typed `StreamEvent` union
+- Polls at `interval.open` (default 5s) during regular hours, `interval.prepost` (default 30s) pre/post, pauses at `interval.closed` (default 60s) when closed — saves API quota overnight and on weekends
+- Emits `market-open` / `market-close` events at session transitions
+- Emits `divergence` events when multiple configured providers disagree beyond `divergenceThreshold`
+- Graceful `AbortSignal` cancellation
+- Configurable `maxErrors` before the generator throws
+
+**`market-feed/consensus`** — Multi-provider parallel price consensus.
+- `consensus(providers, symbol, options)` — queries all providers simultaneously via `Promise.allSettled`
+- Median-based outlier detection (avoids the all-outlier edge case of mean-based approaches)
+- Staleness detection: providers with quotes older than `stalenessThreshold` receive half weight
+- Returns `ConsensusResult` with `price`, `confidence` (0–1), `spread`, `spreadPct`, per-provider breakdown, and `flags`
+- Flags: `HIGH_DIVERGENCE`, `STALE_DATA`, `SINGLE_SOURCE`, `OUTLIER_EXCLUDED`
+- Algorithm helpers exported: `normalizeWeights`, `applyStalenessPenalty`, `weightedMean`, `detectOutliers`, `computeConfidence`
+
+### Breaking changes
+
+None. All v0.1.0 imports continue to work unchanged.
+
+### Other changes
+
+- `MarketFeed` now exposes `get providers(): readonly MarketProvider[]` — read-only view of configured providers, used by `watch()` for divergence detection and `consensus()` for parallel querying
+- 78 new unit tests (220 total across 13 test files)
+- 4 tsup entry points: `index`, `calendar`, `stream`, `consensus` — each tree-shaken independently
+
+---
+
 ## 0.1.0 — 2026-03-10
 
 ### Initial release

package/README.md

@@ -1,7 +1,7 @@
 # market-feed
 
 > Unified TypeScript client for financial market data.
-> Wraps Yahoo Finance, Alpha Vantage, and Polygon.io under one consistent interface — with caching and automatic fallback built in.
+> Wraps Yahoo Finance, Alpha Vantage, Polygon.io, and Finnhub under one consistent interface — with caching and automatic fallback built in.
 
 [![CI](https://github.com/piyushgupta344/market-feed/actions/workflows/ci.yml/badge.svg)](https://github.com/piyushgupta344/market-feed/actions/workflows/ci.yml)
 [![npm version](https://badge.fury.io/js/market-feed.svg)](https://www.npmjs.com/package/market-feed)
@@ -39,7 +39,7 @@ const quote = await feed.quote("AAPL");
 console.log(quote.price); // always a number, always the same key
 ```
 
-One interface. Three providers. Zero API key required for Yahoo Finance.
+One interface. Four providers. Zero API key required for Yahoo Finance.
 
 ---
 
@@ -53,6 +53,391 @@ One interface. Three providers. Zero API key required for Yahoo Finance.
 - **Strict TypeScript** — no `any`, full autocomplete, compile-time safety
 - **Multi-runtime** — Node 18+, Bun 1+, Deno 2+, Cloudflare Workers
 - **Escape hatch** — pass `{ raw: true }` to get the original provider response
+- **Exchange calendar** — synchronous, offline-capable holiday and session detection for 8 exchanges + crypto (24/7)
+- **WebSocket streaming** — `market-feed/ws` opens a persistent WS connection to Polygon or Finnhub; polling fallback for Yahoo/AV
+- **Observable stream** — market-hours-aware HTTP polling that pauses overnight and on weekends
+- **Price consensus** — query all providers in parallel, get a weighted mean with confidence score
+- **Technical indicators** — SMA, EMA, RSI, MACD, Bollinger Bands, ATR, VWAP, Stochastic — pure functions, zero deps
+- **Portfolio tracking** — live P&L, unrealised gains, day change across all positions
+- **CLI** — `npx market-feed quote AAPL` — no install required
+- **Crypto & Forex** — `isCrypto()` / `isForex()` helpers, CRYPTO calendar exchange (always open)
+
+---
+
+## Subpath modules
+
+`market-feed` ships six optional subpath modules alongside the core client.
+
+### `market-feed/ws`
+
+True WebSocket streaming — tick-by-tick trade data from Polygon and Finnhub, with automatic polling fallback for other providers.
+
+```ts
+import { connect } from "market-feed/ws";
+import { MarketFeed, FinnhubProvider, PolygonProvider } from "market-feed";
+
+// Finnhub — real-time WebSocket
+const provider = new FinnhubProvider({ apiKey: process.env.FINNHUB_KEY! });
+
+// Polygon — real-time WebSocket (requires paid plan for true real-time)
+// const provider = new PolygonProvider({ apiKey: process.env.POLYGON_KEY! });
+
+const controller = new AbortController();
+
+for await (const event of connect(provider, ["AAPL", "MSFT", "TSLA"], {
+  signal: controller.signal,
+})) {
+  switch (event.type) {
+    case "trade":
+      console.log(`${event.trade.symbol}: $${event.trade.price} × ${event.trade.size} shares`);
+      break;
+    case "connected":
+      console.log(`Connected to ${event.provider}`);
+      break;
+    case "disconnected":
+      console.log(`Disconnected (attempt ${event.attempt}, reconnecting: ${event.reconnecting})`);
+      break;
+    case "error":
+      if (!event.recoverable) throw event.error;
+      break;
+  }
+}
+
+controller.abort(); // stop the stream
+```
+
+Unlike `market-feed/stream` (which is HTTP polling), `market-feed/ws` opens a persistent WebSocket connection and yields individual trade executions in real time.
+
+#### Provider support
+
+| Provider | WebSocket | Notes |
+|----------|-----------|-------|
+| `PolygonProvider` | Native WS | Auth via JSON handshake, subscribes to `T.*` trades |
+| `FinnhubProvider` | Native WS | Token in URL, per-symbol subscribe |
+| `YahooProvider` | Polling fallback | Polls `quote()` every 5 s |
+| `AlphaVantageProvider` | Polling fallback | Same as Yahoo |
+
+#### `WsOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `wsImpl` | `typeof WebSocket` | `globalThis.WebSocket` | Custom WS constructor for Node 18–20 |
+| `maxReconnectAttempts` | `number` | `10` | Reconnects before closing |
+| `reconnectDelayMs` | `number` | `1000` | Base delay (doubles per attempt, max 30 s) |
+| `signal` | `AbortSignal` | — | Stop the stream |
+
+#### Node 18–20
+
+Node 21+, Bun, Deno, and Cloudflare Workers expose `WebSocket` globally. For Node 18–20, install the `ws` package and inject it:
+
+```ts
+import WebSocket from "ws";
+connect(provider, ["AAPL"], { wsImpl: WebSocket as unknown as typeof globalThis.WebSocket })
+```
+
+---
+
+### `market-feed/calendar`
+
+Synchronous exchange calendar — no network, no async, works offline.
+
+```ts
+import {
+  isMarketOpen,
+  getSession,
+  nextSessionOpen,
+  nextSessionClose,
+  isHoliday,
+  isEarlyClose,
+  getHolidayDates,
+  getExchangeInfo,
+} from "market-feed/calendar";
+
+// Is NYSE open right now?
+isMarketOpen("NYSE");  // true | false
+
+// What session is it?
+getSession("NYSE");    // "pre" | "regular" | "post" | "closed"
+
+// When does it next open?
+nextSessionOpen("NYSE");   // Date (UTC)
+nextSessionClose("NYSE");  // Date (UTC)
+
+// Holiday checks
+isHoliday("LSE");                          // false
+isHoliday("NYSE", new Date("2025-04-18")); // true — Good Friday
+isEarlyClose("NYSE");                      // true on day before Thanksgiving
+
+// All holidays for a year
+getHolidayDates("NYSE", 2026);  // Date[]
+
+// Exchange metadata
+getExchangeInfo("LSE");
+// { id: "LSE", name: "London Stock Exchange", mic: "XLON",
+//   timezone: "Europe/London", openTime: "08:00", closeTime: "16:30", ... }
+```
+
+Supports **NYSE, NASDAQ, LSE, TSX, ASX, XETRA, NSE, BSE**, and **CRYPTO** (always open — no sessions, no holidays). Holiday rules are computed from first principles — Easter via the Meeus/Jones/Butcher algorithm, all NYSE-specific rules (MLK Day, Presidents' Day, Juneteenth, Memorial Day, Labor Day, Thanksgiving, Good Friday), UK bank holidays, Canadian, Australian, German, and Indian exchanges. DST is handled via `Intl.DateTimeFormat` — no manual offset arithmetic.
+
+---
+
+### `market-feed/stream`
+
+Market-hours-aware async generator. Polls during open hours, pauses when the market is closed.
+
+```ts
+import { watch } from "market-feed/stream";
+import { MarketFeed, YahooProvider, PolygonProvider } from "market-feed";
+
+const feed = new MarketFeed({
+  providers: [
+    new YahooProvider(),
+    new PolygonProvider({ apiKey: process.env.POLYGON_KEY }),
+  ],
+});
+
+const controller = new AbortController();
+
+for await (const event of watch(feed, ["AAPL", "MSFT"], {
+  exchange: "NYSE",
+  interval: {
+    open:    5_000,   // poll every 5s during regular hours
+    prepost: 30_000,  // every 30s pre/post market
+    closed:  60_000,  // check every 60s for session open
+  },
+  divergenceThreshold: 0.5,  // % spread between providers
+  signal: controller.signal,
+})) {
+  switch (event.type) {
+    case "quote":
+      console.log(`${event.symbol}: $${event.quote.price}`);
+      break;
+    case "market-open":
+      console.log(`${event.exchange} session started: ${event.session}`);
+      break;
+    case "market-close":
+      console.log(`${event.exchange} session ended`);
+      break;
+    case "divergence":
+      console.log(`${event.symbol} providers disagree: ${event.spreadPct.toFixed(2)}%`);
+      break;
+    case "error":
+      if (!event.recoverable) throw event.error;
+      break;
+  }
+}
+
+// Stop the stream
+controller.abort();
+```
+
+When `marketHoursAware: true` (default), the stream pauses completely during closed sessions — no wasted API calls overnight or on weekends. It emits `market-open` / `market-close` events at session boundaries. When the feed has multiple providers, it detects price divergence across them and emits `divergence` events.
+
+#### `WatchOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `exchange` | `ExchangeId` | `"NYSE"` | Calendar to use for session detection |
+| `interval.open` | `number` | `5000` | Poll interval (ms) during regular hours |
+| `interval.prepost` | `number` | `30000` | Poll interval (ms) during pre/post market |
+| `interval.closed` | `number` | `60000` | Check interval (ms) when market is closed |
+| `marketHoursAware` | `boolean` | `true` | Pause during closed sessions |
+| `divergenceThreshold` | `number` | `0.5` | % spread that triggers a divergence event |
+| `maxErrors` | `number` | `5` | Consecutive errors before the generator throws |
+| `signal` | `AbortSignal` | — | Cancel the stream |
+
+---
+
+### `market-feed/consensus`
+
+Queries all configured providers simultaneously and returns a statistically-weighted price consensus.
+
+Unlike `feed.quote()` which stops at the first successful provider, `consensus()` fires all providers in parallel and combines their results.
+
+```ts
+import { consensus } from "market-feed/consensus";
+import { MarketFeed, YahooProvider, AlphaVantageProvider, PolygonProvider } from "market-feed";
+
+const feed = new MarketFeed({
+  providers: [
+    new YahooProvider(),
+    new AlphaVantageProvider({ apiKey: process.env.AV_KEY }),
+    new PolygonProvider({ apiKey: process.env.POLYGON_KEY }),
+  ],
+});
+
+const result = await consensus(feed.providers, "AAPL");
+
+console.log(result.price);       // 189.82 — weighted mean
+console.log(result.confidence);  // 0.97   — 0=no agreement, 1=perfect
+console.log(result.spread);      // 0.08   — max - min across providers
+console.log(result.spreadPct);   // 0.042  — spread as % of price
+console.log(result.flags);       // [] or ["HIGH_DIVERGENCE", "STALE_DATA", ...]
+console.log(result.providers);
+// {
+//   yahoo:          { price: 189.84, weight: 0.33, stale: false, included: true },
+//   polygon:        { price: 189.80, weight: 0.33, stale: false, included: true },
+//   "alpha-vantage": { price: 189.82, weight: 0.33, stale: false, included: true },
+// }
+```
+
+#### `ConsensusOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `stalenessThreshold` | `number` | `60` | Seconds before a quote is stale. Stale providers get half weight. |
+| `divergenceThreshold` | `number` | `2.0` | % deviation from median that marks a provider as an outlier |
+| `weights` | `Record<string, number>` | equal | Custom weights per provider name (normalized automatically) |
+
+#### Flags
+
+| Flag | Meaning |
+|------|---------|
+| `HIGH_DIVERGENCE` | `spreadPct` exceeds `divergenceThreshold` |
+| `STALE_DATA` | At least one provider returned a quote older than `stalenessThreshold` |
+| `SINGLE_SOURCE` | Only one provider responded successfully |
+| `OUTLIER_EXCLUDED` | At least one provider was excluded as a price outlier |
+
+---
+
+### `market-feed/indicators`
+
+Technical indicators as pure functions over `HistoricalBar[]`. No network, no async, tree-shakeable.
+
+```ts
+import {
+  sma, ema, rsi, macd, bollingerBands, atr, vwap, stochastic,
+} from "market-feed/indicators";
+import { MarketFeed } from "market-feed";
+
+const feed = new MarketFeed();
+const bars = await feed.historical("AAPL", { period1: "2024-01-01", interval: "1d" });
+
+// Simple / Exponential Moving Average
+const sma20  = sma(bars, 20);   // IndicatorPoint[] — { date, value }[]
+const ema12  = ema(bars, 12);
+
+// Relative Strength Index
+const rsi14  = rsi(bars, 14);   // values in [0, 100]
+
+// MACD
+const macdResult = macd(bars);  // MACDPoint[] — { date, macd, signal, histogram }[]
+
+// Bollinger Bands
+const bb = bollingerBands(bars, 20, 2);  // BollingerPoint[] — { date, upper, middle, lower }[]
+
+// Average True Range
+const atr14 = atr(bars, 14);
+
+// VWAP (cumulative from first bar)
+const vwapPoints = vwap(bars);
+
+// Stochastic Oscillator
+const stoch = stochastic(bars, 14, 3);  // StochasticPoint[] — { date, k, d }[]
+```
+
+All functions return typed arrays starting from the first bar where enough data exists. They never throw for insufficient data — they return an empty array instead.
+
+| Function | Output type | Default params |
+|----------|------------|----------------|
+| `sma(bars, period)` | `IndicatorPoint[]` | — |
+| `ema(bars, period)` | `IndicatorPoint[]` | — |
+| `rsi(bars, period?)` | `IndicatorPoint[]` | period: 14 |
+| `macd(bars, fast?, slow?, signal?)` | `MACDPoint[]` | 12, 26, 9 |
+| `bollingerBands(bars, period?, stdDevMult?)` | `BollingerPoint[]` | 20, 2 |
+| `atr(bars, period?)` | `IndicatorPoint[]` | period: 14 |
+| `vwap(bars)` | `IndicatorPoint[]` | — |
+| `stochastic(bars, kPeriod?, dPeriod?)` | `StochasticPoint[]` | 14, 3 |
+
+---
+
+### `market-feed/portfolio`
+
+Track a collection of positions and compute live P&L against current market prices.
+
+```ts
+import { Portfolio } from "market-feed/portfolio";
+import { MarketFeed } from "market-feed";
+
+const feed = new MarketFeed();
+
+const portfolio = new Portfolio([
+  { symbol: "AAPL", quantity: 10, avgCost: 150.00 },
+  { symbol: "MSFT", quantity:  5, avgCost: 280.00 },
+  { symbol: "TSLA", quantity: -3, avgCost: 250.00 }, // short position
+]);
+
+// Fetch live quotes and compute P&L in one call
+const snap = await portfolio.snapshot(feed);
+
+console.log(`Total value:       $${snap.totalMarketValue.toFixed(2)}`);
+console.log(`Unrealised P&L:    $${snap.totalUnrealizedPnl.toFixed(2)}`);
+console.log(`Today's change:    $${snap.totalDayChange.toFixed(2)}`);
+
+for (const pos of snap.positions) {
+  const pct = (pos.unrealizedPnlPct * 100).toFixed(2);
+  console.log(`${pos.symbol}: $${pos.marketValue.toFixed(2)} (${pct}%)`);
+}
+```
+
+#### `Position`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `symbol` | `string` | Ticker symbol |
+| `quantity` | `number` | Units held. Negative = short. |
+| `avgCost` | `number` | Average cost per unit |
+| `currency` | `string?` | Defaults to "USD" |
+| `openedAt` | `Date?` | When the position was opened |
+| `notes` | `string?` | Free-form notes |
+
+#### `Portfolio` API
+
+```ts
+portfolio.add(position)          // add or replace a position (chainable)
+portfolio.remove(symbol)         // remove a position (chainable)
+portfolio.get(symbol)            // Position | undefined
+portfolio.list()                 // readonly Position[]
+portfolio.size                   // number
+portfolio.snapshot(feed)         // Promise<PortfolioSnapshot>
+```
+
+---
+
+### CLI (`npx market-feed`)
+
+A zero-config CLI powered by Yahoo Finance (no API key needed). Add keys to unlock more providers.
+
+```bash
+# Quotes
+npx market-feed quote AAPL MSFT GOOGL
+
+# Historical data
+npx market-feed historical AAPL --interval 1wk --period1 2024-01-01
+
+# Symbol search
+npx market-feed search "apple inc"
+
+# Company profile
+npx market-feed company AAPL
+
+# News (JSON output)
+npx market-feed news AAPL --limit 5 --json
+```
+
+#### Options
+
+| Flag | Description |
+|------|-------------|
+| `--av-key <key>` | Alpha Vantage API key |
+| `--polygon-key <key>` | Polygon.io API key |
+| `--finnhub-key <key>` | Finnhub API key |
+| `--json` | Output raw JSON instead of formatted tables |
+| `--limit <n>` | Limit results (default: 10) |
+| `--interval <i>` | Historical interval: `1m` `5m` `15m` `30m` `1h` `1d` `1wk` `1mo` (default: `1d`) |
+| `--period1 <date>` | Historical start date (ISO 8601) |
+| `--period2 <date>` | Historical end date (ISO 8601) |
+| `-h`, `--help` | Show help |
 
 ---
 
@@ -107,8 +492,9 @@ console.log(profile.sector); // "Technology"
 | **Yahoo Finance** | Not required | ✓ | ✓ | ✓ | ✓ | — | — |
 | **Alpha Vantage** | Free (25/day) | ✓ | ✓ | ✓ | ✓ | — | — |
 | **Polygon.io** | Free (delayed) | ✓ | ✓ | ✓ | ✓ | ✓ | — |
+| **Finnhub** | Free (60/min) | ✓ | ✓ | ✓ | ✓ | ✓ | — |
 
-Get free keys: [Alpha Vantage](https://www.alphavantage.co/support/#api-key) · [Polygon.io](https://polygon.io/)
+Get free keys: [Alpha Vantage](https://www.alphavantage.co/support/#api-key) · [Polygon.io](https://polygon.io/) · [Finnhub](https://finnhub.io/)
 
 ### Using multiple providers
 
@@ -118,6 +504,7 @@ import {
   YahooProvider,
   AlphaVantageProvider,
   PolygonProvider,
+  FinnhubProvider,
 } from "market-feed";
 
 const feed = new MarketFeed({
@@ -125,6 +512,7 @@ const feed = new MarketFeed({
     new YahooProvider(),
     new AlphaVantageProvider({ apiKey: process.env.AV_KEY }),
     new PolygonProvider({ apiKey: process.env.POLYGON_KEY }),
+    new FinnhubProvider({ apiKey: process.env.FINNHUB_KEY }),
   ],
   fallback: true, // auto-try next provider on failure
 });
@@ -300,7 +688,7 @@ const feed = new MarketFeed({ providers: [new MyProvider()] });
 
 | Runtime | Version | Notes |
 |---------|---------|-------|
-| Node.js | 18+ | Requires native `fetch` (available since Node 18) |
+| Node.js | 18+ | `fetch` available since Node 18; `WebSocket` global available since Node 21. For Node 18–20, inject the `ws` package via `wsImpl` for `market-feed/ws`. |
 | Bun | 1+ | Fully supported |
 | Deno | 2+ | Fully supported |
 | Cloudflare Workers | Latest | Fully supported |
@@ -323,7 +711,7 @@ pnpm test
 
 ## Disclaimer
 
-This library is not affiliated with or endorsed by Yahoo Finance, Alpha Vantage, or Polygon.io. Data is provided for informational purposes only and should not be used as the sole basis for investment decisions.
+This library is not affiliated with or endorsed by Yahoo Finance, Alpha Vantage, Polygon.io, or Finnhub. Data is provided for informational purposes only and should not be used as the sole basis for investment decisions.
 
 ---