market-feed 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,128 @@
 # market-feed Changelog
 
+## 0.5.0 — 2026-03-11
+
+### New modules
+
+**`market-feed/backtest`** — Pure-function backtesting engine over `HistoricalBar[]`.
+
+```ts
+import { backtest } from "market-feed/backtest";
+import type { EntrySignal, ExitSignal } from "market-feed/backtest";
+
+const entry: EntrySignal = (bars, i) => i > 0 && bars[i]!.close > bars[i - 1]!.close;
+const exit: ExitSignal  = (bars, i) => i > 0 && bars[i]!.close < bars[i - 1]!.close;
+
+const result = backtest("AAPL", bars, entry, exit, { initialCapital: 10_000 });
+console.log(`Total return: ${(result.totalReturn * 100).toFixed(2)}%`);
+console.log(`Sharpe ratio: ${result.sharpeRatio.toFixed(2)}`);
+console.log(`Max drawdown: ${(result.maxDrawdown * 100).toFixed(2)}%`);
+```
+
+| Field | Description |
+|-------|-------------|
+| `totalReturn` | Fraction, e.g. 0.25 = 25% |
+| `annualizedReturn` | CAGR as a fraction |
+| `sharpeRatio` | Annualised Sharpe (risk-free rate = 0) |
+| `maxDrawdown` | Peak-to-trough as a positive fraction |
+| `winRate` | Fraction of profitable trades |
+| `profitFactor` | Gross profit / gross loss (`Infinity` when no losses) |
+| `totalTrades` | Number of completed round-trip trades |
+| `trades` | Full `BacktestTrade[]` ledger |
+
+**`market-feed/alerts`** — Poll a feed and yield `AlertEvent` when conditions are met.
+
+```ts
+import { watchAlerts } from "market-feed/alerts";
+import { MarketFeed } from "market-feed";
+
+const feed = new MarketFeed();
+const controller = new AbortController();
+
+for await (const event of watchAlerts(feed, [
+  { symbol: "AAPL", condition: { type: "price_above", threshold: 200 }, once: true },
+  { symbol: "TSLA", condition: { type: "change_pct_below", threshold: -5 }, debounceMs: 60_000 },
+], { signal: controller.signal })) {
+  console.log(`${event.alert.symbol} triggered: $${event.quote.price}`);
+}
+```
+
+| Condition type | Description |
+|----------------|-------------|
+| `price_above` | `quote.price > threshold` |
+| `price_below` | `quote.price < threshold` |
+| `change_pct_above` | Daily `%` change exceeds threshold |
+| `change_pct_below` | Daily `%` change falls below threshold |
+| `volume_above` | `quote.volume > threshold` |
+
+`AlertConfig` options: `once` (fire at most once), `debounceMs` (suppress re-fires within window).
+
+### New data: earnings, dividends, splits
+
+Three new methods on `MarketFeed` (and on individual providers):
+
+```ts
+const feed = new MarketFeed([new PolygonProvider({ apiKey: "..." })]);
+
+const earnings  = await feed.earnings("AAPL", { limit: 8 });
+const dividends = await feed.dividends("AAPL");
+const splits    = await feed.splits("AAPL");
+```
+
+#### Provider support
+
+| Method | `YahooProvider` | `PolygonProvider` | `FinnhubProvider` | `AlphaVantageProvider` |
+|--------|-----------------|-------------------|-------------------|------------------------|
+| `earnings` | ✓ quoteSummary `earningsHistory` | — | ✓ `/stock/earnings` | — |
+| `dividends` | ✓ chart `events=div` | ✓ `/v3/reference/dividends` | — | — |
+| `splits` | ✓ chart `events=split` | ✓ `/v3/reference/splits` | — | — |
+
+#### `EarningsEvent`
+
+```ts
+interface EarningsEvent {
+  symbol: string; date: Date; period?: string;
+  epsActual?: number; epsEstimate?: number; epsSurprisePct?: number;
+  revenueActual?: number; revenueEstimate?: number;
+  provider: string; raw?: unknown;
+}
+```
+
+#### `DividendEvent`
+
+```ts
+interface DividendEvent {
+  symbol: string; exDate: Date; payDate?: Date; declaredDate?: Date;
+  amount: number; currency: string;
+  frequency?: "annual" | "semi-annual" | "quarterly" | "monthly" | "irregular";
+  provider: string; raw?: unknown;
+}
+```
+
+#### `SplitEvent`
+
+```ts
+interface SplitEvent {
+  symbol: string; date: Date;
+  ratio: number;      // 4-for-1 forward split → 4; 1-for-10 reverse → 0.1
+  description?: string;
+  provider: string; raw?: unknown;
+}
+```
+
+### Other changes
+
+- `CacheMethod` extended with `"earnings" | "dividends" | "splits"` (TTLs: earnings 1 h, dividends/splits 24 h)
+- All new types exported from main `market-feed` entry point
+- 51 new unit tests (392 total across 21 test files)
+- 9 tsup library entry points + 1 CLI binary: `index`, `calendar`, `stream`, `consensus`, `indicators`, `portfolio`, `ws`, `backtest`, `alerts`, `cli`
+
+### Breaking changes
+
+None. All v0.4.0 imports continue to work unchanged.
+
+---
+
 ## 0.4.0 — 2026-03-11
 
 ### New module

package/README.md

@@ -59,6 +59,9 @@ One interface. Four providers. Zero API key required for Yahoo Finance.
 - **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
+- **Backtesting** — pure-function engine: total return, CAGR, Sharpe ratio, max drawdown, win rate, profit factor
+- **Price alerts** — async generator that fires `AlertEvent` on price/volume/change conditions, with debounce
+- **Earnings, dividends, splits** — structured historical corporate action data from Yahoo, Polygon, and Finnhub
 - **CLI** — `npx market-feed quote AAPL` — no install required
 - **Crypto & Forex** — `isCrypto()` / `isForex()` helpers, CRYPTO calendar exchange (always open)
 
@@ -66,7 +69,7 @@ One interface. Four providers. Zero API key required for Yahoo Finance.
 
 ## Subpath modules
 
-`market-feed` ships six optional subpath modules alongside the core client.
+`market-feed` ships eight optional subpath modules alongside the core client.
 
 ### `market-feed/ws`
 
@@ -404,6 +407,117 @@ portfolio.snapshot(feed)         // Promise<PortfolioSnapshot>
 
 ---
 
+### `market-feed/backtest`
+
+Pure-function backtesting engine over `HistoricalBar[]`. No network, no side effects.
+
+```ts
+import { backtest } from "market-feed/backtest";
+import type { EntrySignal, ExitSignal } from "market-feed/backtest";
+import { MarketFeed } from "market-feed";
+
+const feed = new MarketFeed();
+const bars = await feed.historical("AAPL", { period1: "2020-01-01", interval: "1d" });
+
+// Buy when today's close > yesterday's close (momentum)
+const entry: EntrySignal = (bars, i) => i > 0 && bars[i]!.close > bars[i - 1]!.close;
+
+// Sell when today's close < yesterday's close
+const exit: ExitSignal = (bars, i, _entryPrice) => i > 0 && bars[i]!.close < bars[i - 1]!.close;
+
+const result = backtest("AAPL", bars, entry, exit, {
+  initialCapital: 10_000,
+  quantity: 10,
+  commission: 1,
+});
+
+console.log(`Total return:    ${(result.totalReturn * 100).toFixed(2)}%`);
+console.log(`Annualised CAGR: ${(result.annualizedReturn * 100).toFixed(2)}%`);
+console.log(`Sharpe ratio:    ${result.sharpeRatio.toFixed(2)}`);
+console.log(`Max drawdown:    ${(result.maxDrawdown * 100).toFixed(2)}%`);
+console.log(`Win rate:        ${(result.winRate * 100).toFixed(1)}%`);
+console.log(`Trades:          ${result.totalTrades}`);
+```
+
+Signals fire at bar[i].close. Any open position is closed at the last bar. At most one position is held at a time.
+
+#### `BacktestOptions`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `initialCapital` | `number` | `100_000` | Starting capital |
+| `quantity` | `number` | `1` | Shares per trade |
+| `commission` | `number` | `0` | One-way commission per trade |
+
+#### `BacktestResult`
+
+| Field | Description |
+|-------|-------------|
+| `totalReturn` | Fraction — e.g. `0.25` = 25% |
+| `annualizedReturn` | CAGR as a fraction |
+| `sharpeRatio` | Annualised Sharpe (risk-free rate = 0) |
+| `maxDrawdown` | Positive fraction — peak-to-trough |
+| `winRate` | Fraction of profitable trades |
+| `profitFactor` | Gross profit / gross loss (`Infinity` = no losses) |
+| `totalTrades` | Completed round-trip trades |
+| `trades` | `BacktestTrade[]` ledger |
+
+---
+
+### `market-feed/alerts`
+
+Poll a quote feed and yield `AlertEvent` whenever a configured condition is met.
+
+```ts
+import { watchAlerts } from "market-feed/alerts";
+import type { AlertConfig } from "market-feed/alerts";
+import { MarketFeed } from "market-feed";
+
+const feed = new MarketFeed();
+const controller = new AbortController();
+
+const alerts: AlertConfig[] = [
+  // Fire once when AAPL crosses $200
+  { symbol: "AAPL", condition: { type: "price_above", threshold: 200 }, once: true },
+  // Alert on TSLA intraday crash; debounce 5 min to avoid spam
+  { symbol: "TSLA", condition: { type: "change_pct_below", threshold: -5 }, debounceMs: 300_000 },
+  // Unusual volume spike on MSFT
+  { symbol: "MSFT", condition: { type: "volume_above", threshold: 100_000_000 } },
+];
+
+for await (const event of watchAlerts(feed, alerts, {
+  intervalMs: 5_000,
+  signal: controller.signal,
+})) {
+  console.log(
+    `[${event.triggeredAt.toISOString()}] ${event.alert.symbol} triggered: $${event.quote.price}`,
+  );
+}
+```
+
+#### Alert conditions
+
+| `type` | Fires when |
+|--------|-----------|
+| `price_above` | `quote.price > threshold` |
+| `price_below` | `quote.price < threshold` |
+| `change_pct_above` | `quote.changePercent > threshold` |
+| `change_pct_below` | `quote.changePercent < threshold` |
+| `volume_above` | `quote.volume > threshold` |
+
+#### `AlertConfig`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `symbol` | `string` | Ticker to watch |
+| `condition` | `AlertCondition` | Trigger condition |
+| `once` | `boolean?` | Remove after first fire. Default: `false` |
+| `debounceMs` | `number?` | Suppress re-fires within this window. Default: `0` |
+
+When all `once` alerts have fired, the generator terminates automatically. Permanent alerts (`once: false`) run until `signal.abort()` is called. Transient fetch errors are silently retried.
+
+---
+
 ### CLI (`npx market-feed`)
 
 A zero-config CLI powered by Yahoo Finance (no API key needed). Add keys to unlock more providers.
@@ -612,6 +726,15 @@ feed.news(symbol: string, options?: NewsOptions): Promise<NewsItem[]>
 // Market status
 feed.marketStatus(market?: string): Promise<MarketStatus>
 
+// Earnings history (EPS actuals vs. estimates)
+feed.earnings(symbol: string, options?: EarningsOptions): Promise<EarningsEvent[]>
+
+// Cash dividend history
+feed.dividends(symbol: string, options?: DividendOptions): Promise<DividendEvent[]>
+
+// Stock split history
+feed.splits(symbol: string, options?: SplitOptions): Promise<SplitEvent[]>
+
 // Cache management
 feed.clearCache(): Promise<void>
 feed.invalidate(key: string): Promise<void>

package/dist/alerts.cjs

@@ -0,0 +1,70 @@
+'use strict';
+
+// market-feed — Unified financial market data client
+// https://github.com/piyushgupta344/market-feed
+
+// src/alerts/index.ts
+function conditionMet(condition, quote) {
+  switch (condition.type) {
+    case "price_above":
+      return quote.price > condition.threshold;
+    case "price_below":
+      return quote.price < condition.threshold;
+    case "change_pct_above":
+      return quote.changePercent > condition.threshold;
+    case "change_pct_below":
+      return quote.changePercent < condition.threshold;
+    case "volume_above":
+      return (quote.volume ?? 0) > condition.threshold;
+  }
+}
+async function* watchAlerts(feed, alerts, options) {
+  if (alerts.length === 0) return;
+  const intervalMs = options?.intervalMs ?? 5e3;
+  const signal = options?.signal;
+  const lastFired = /* @__PURE__ */ new Map();
+  const active = new Set(alerts);
+  while (active.size > 0) {
+    if (signal?.aborted) return;
+    const symbols = [...new Set([...active].map((a) => a.symbol))];
+    let quotes;
+    try {
+      quotes = await feed.quote(symbols);
+    } catch {
+      await sleep(intervalMs, signal);
+      continue;
+    }
+    if (signal?.aborted) return;
+    const quoteMap = new Map(quotes.map((q) => [q.symbol.toUpperCase(), q]));
+    const now = Date.now();
+    for (const alert of [...active]) {
+      const quote = quoteMap.get(alert.symbol.toUpperCase());
+      if (!quote) continue;
+      if (!conditionMet(alert.condition, quote)) continue;
+      const last = lastFired.get(alert);
+      if (last !== void 0 && alert.debounceMs && now - last < alert.debounceMs) continue;
+      lastFired.set(alert, now);
+      yield { type: "triggered", alert, quote, triggeredAt: new Date(now) };
+      if (alert.once) active.delete(alert);
+    }
+    if (active.size === 0) break;
+    await sleep(intervalMs, signal);
+  }
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      resolve();
+    }, { once: true });
+  });
+}
+
+exports.watchAlerts = watchAlerts;
+//# sourceMappingURL=alerts.cjs.map
+//# sourceMappingURL=alerts.cjs.map

package/dist/alerts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/alerts/index.ts"],"names":[],"mappings":";;;;;;AASA,SAAS,YAAA,CAAa,WAA2B,KAAA,EAAuB;AACtE,EAAA,QAAQ,UAAU,IAAA;AAAM,IACtB,KAAK,aAAA;AACH,MAAA,OAAO,KAAA,CAAM,QAAQ,SAAA,CAAU,SAAA;AAAA,IACjC,KAAK,aAAA;AACH,MAAA,OAAO,KAAA,CAAM,QAAQ,SAAA,CAAU,SAAA;AAAA,IACjC,KAAK,kBAAA;AACH,MAAA,OAAO,KAAA,CAAM,gBAAgB,SAAA,CAAU,SAAA;AAAA,IACzC,KAAK,kBAAA;AACH,MAAA,OAAO,KAAA,CAAM,gBAAgB,SAAA,CAAU,SAAA;AAAA,IACzC,KAAK,cAAA;AACH,MAAA,OAAA,CAAQ,KAAA,CAAM,MAAA,IAAU,CAAA,IAAK,SAAA,CAAU,SAAA;AAAA;AAE7C;AAwBA,gBAAuB,WAAA,CACrB,IAAA,EACA,MAAA,EACA,OAAA,EAC4B;AAC5B,EAAA,IAAI,MAAA,CAAO,WAAW,CAAA,EAAG;AAEzB,EAAA,MAAM,UAAA,GAAa,SAAS,UAAA,IAAc,GAAA;AAC1C,EAAA,MAAM,SAAS,OAAA,EAAS,MAAA;AAExB,EAAA,MAAM,SAAA,uBAAgB,GAAA,EAAyB;AAC/C,EAAA,MAAM,MAAA,GAAS,IAAI,GAAA,CAAI,MAAM,CAAA;AAE7B,EAAA,OAAO,MAAA,CAAO,OAAO,CAAA,EAAG;AACtB,IAAA,IAAI,QAAQ,OAAA,EAAS;AAErB,IAAA,MAAM,OAAA,GAAU,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,MAAM,CAAA,CAAE,IAAI,CAAC,CAAA,KAAM,CAAA,CAAE,MAAM,CAAC,CAAC,CAAA;AAE7D,IAAA,IAAI,MAAA;AACJ,IAAA,IAAI;AACF,MAAA,MAAA,GAAS,MAAM,IAAA,CAAK,KAAA,CAAM,OAAO,CAAA;AAAA,IACnC,CAAA,CAAA,MAAQ;AACN,MAAA,MAAM,KAAA,CAAM,YAAY,MAAM,CAAA;AAC9B,MAAA;AAAA,IACF;AAEA,IAAA,IAAI,QAAQ,OAAA,EAAS;AAErB,IAAA,MAAM,QAAA,GAAW,IAAI,GAAA,CAAI,MAAA,CAAO,IAAI,CAAC,CAAA,KAAM,CAAC,CAAA,CAAE,MAAA,CAAO,WAAA,EAAY,EAAG,CAAC,CAAC,CAAC,CAAA;AACvE,IAAA,MAAM,GAAA,GAAM,KAAK,GAAA,EAAI;AAErB,IAAA,KAAA,MAAW,KAAA,IAAS,CAAC,GAAG,MAAM,CAAA,EAAG;AAC/B,MAAA,MAAM,QAAQ,QAAA,CAAS,GAAA,CAAI,KAAA,CAAM,MAAA,CAAO,aAAa,CAAA;AACrD,MAAA,IAAI,CAAC,KAAA,EAAO;AAEZ,MAAA,IAAI,CAAC,YAAA,CAAa,KAAA,CAAM,SAAA,EAAW,KAAK,CAAA,EAAG;AAG3C,MAAA,MAAM,IAAA,GAAO,SAAA,CAAU,GAAA,CAAI,KAAK,CAAA;AAChC,MAAA,IAAI,SAAS,MAAA,IAAa,KAAA,CAAM,cAAc,GAAA,GAAM,IAAA,GAAO,MAAM,UAAA,EAAY;AAE7E,MAAA,SAAA,CAAU,GAAA,CAAI,OAAO,GAAG,CAAA;AACxB,MAAA,MAAM,EAAE,MAAM,WAAA,EAAa,KAAA,EAAO,OAAO,WAAA,EAAa,IAAI,IAAA,CAAK,GAAG,CAAA,EAAE;AAEpE,MAAA,IAAI,KAAA,CAAM,IAAA,EAAM,MAAA,CAAO,MAAA,CAAO,KAAK,CAAA;AAAA,IACrC;AAEA,IAAA,IAAI,MAAA,CAAO,SAAS,CAAA,EAAG;AACvB,IAAA,MAAM,KAAA,CAAM,YAAY,MAAM,CAAA;AAAA,EAChC;AACF;AAEA,SAAS,KAAA,CAAM,IAAY,MAAA,EAAqC;AAC9D,EAAA,OAAO,IAAI,OAAA,CAAQ,CAAC,OAAA,KAAY;AAC9B,IAAA,IAAI,QAAQ,OAAA,EAAS;AACnB,MAAA,OAAA,EAAQ;AACR,MAAA;AAAA,IACF;AACA,IAAA,MAAM,KAAA,GAAQ,UAAA,CAAW,OAAA,EAAS,EAAE,CAAA;AACpC,IAAA,MAAA,EAAQ,gBAAA,CAAiB,SAAS,MAAM;AACtC,MAAA,YAAA,CAAa,KAAK,CAAA;AAClB,MAAA,OAAA,EAAQ;AAAA,IACV,CAAA,EAAG,EAAE,IAAA,EAAM,IAAA,EAAM,CAAA;AAAA,EACnB,CAAC,CAAA;AACH","file":"alerts.cjs","sourcesContent":["import type { Quote } from \"../types/quote.js\";\nimport type { AlertCondition, AlertConfig, AlertEvent, AlertsOptions } from \"./types.js\";\n\nexport type { AlertCondition, AlertConfig, AlertEvent, AlertsOptions } from \"./types.js\";\n\ninterface QuoteFetcher {\n  quote(symbols: string[]): Promise<Quote[]>;\n}\n\nfunction conditionMet(condition: AlertCondition, quote: Quote): boolean {\n  switch (condition.type) {\n    case \"price_above\":\n      return quote.price > condition.threshold;\n    case \"price_below\":\n      return quote.price < condition.threshold;\n    case \"change_pct_above\":\n      return quote.changePercent > condition.threshold;\n    case \"change_pct_below\":\n      return quote.changePercent < condition.threshold;\n    case \"volume_above\":\n      return (quote.volume ?? 0) > condition.threshold;\n  }\n}\n\n/**\n * Poll a quote feed and yield `AlertEvent` whenever a configured condition is met.\n *\n * - Resolves when all `once` alerts have fired, or when `options.signal` is aborted.\n * - Permanent alerts (once = false) run until the AbortSignal fires.\n * - Debounce suppresses re-fires within `debounceMs` milliseconds.\n *\n * @example\n * ```ts\n * import { watchAlerts } from \"market-feed/alerts\";\n * import { MarketFeed } from \"market-feed\";\n *\n * const feed = new MarketFeed();\n * const controller = new AbortController();\n *\n * for await (const event of watchAlerts(feed, [\n *   { symbol: \"AAPL\", condition: { type: \"price_above\", threshold: 200 }, once: true },\n * ], { signal: controller.signal })) {\n *   console.log(`AAPL crossed $200: $${event.quote.price}`);\n * }\n * ```\n */\nexport async function* watchAlerts(\n  feed: QuoteFetcher,\n  alerts: AlertConfig[],\n  options?: AlertsOptions,\n): AsyncGenerator<AlertEvent> {\n  if (alerts.length === 0) return;\n\n  const intervalMs = options?.intervalMs ?? 5_000;\n  const signal = options?.signal;\n\n  const lastFired = new Map<AlertConfig, number>();\n  const active = new Set(alerts);\n\n  while (active.size > 0) {\n    if (signal?.aborted) return;\n\n    const symbols = [...new Set([...active].map((a) => a.symbol))];\n\n    let quotes: Quote[];\n    try {\n      quotes = await feed.quote(symbols);\n    } catch {\n      await sleep(intervalMs, signal);\n      continue;\n    }\n\n    if (signal?.aborted) return;\n\n    const quoteMap = new Map(quotes.map((q) => [q.symbol.toUpperCase(), q]));\n    const now = Date.now();\n\n    for (const alert of [...active]) {\n      const quote = quoteMap.get(alert.symbol.toUpperCase());\n      if (!quote) continue;\n\n      if (!conditionMet(alert.condition, quote)) continue;\n\n      // Debounce check\n      const last = lastFired.get(alert);\n      if (last !== undefined && alert.debounceMs && now - last < alert.debounceMs) continue;\n\n      lastFired.set(alert, now);\n      yield { type: \"triggered\", alert, quote, triggeredAt: new Date(now) };\n\n      if (alert.once) active.delete(alert);\n    }\n\n    if (active.size === 0) break;\n    await sleep(intervalMs, signal);\n  }\n}\n\nfunction sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise((resolve) => {\n    if (signal?.aborted) {\n      resolve();\n      return;\n    }\n    const timer = setTimeout(resolve, ms);\n    signal?.addEventListener(\"abort\", () => {\n      clearTimeout(timer);\n      resolve();\n    }, { once: true });\n  });\n}\n"]}

package/dist/alerts.d.cts

@@ -0,0 +1,70 @@
+import { a as Quote } from './quote-Cfh_7Cgg.cjs';
+
+type AlertCondition = {
+    type: "price_above";
+    threshold: number;
+} | {
+    type: "price_below";
+    threshold: number;
+} | {
+    type: "change_pct_above";
+    threshold: number;
+} | {
+    type: "change_pct_below";
+    threshold: number;
+} | {
+    type: "volume_above";
+    threshold: number;
+};
+interface AlertConfig {
+    symbol: string;
+    condition: AlertCondition;
+    /** Emit this alert at most once, then stop watching it. Defaults to false. */
+    once?: boolean;
+    /**
+     * Suppress re-fires within this many milliseconds after the last trigger.
+     * Defaults to 0 (no debounce).
+     */
+    debounceMs?: number;
+}
+interface AlertEvent {
+    type: "triggered";
+    alert: AlertConfig;
+    quote: Quote;
+    triggeredAt: Date;
+}
+interface AlertsOptions {
+    /** Poll interval in milliseconds. Defaults to 5 000. */
+    intervalMs?: number;
+    /** AbortSignal to stop the generator. */
+    signal?: AbortSignal;
+}
+
+interface QuoteFetcher {
+    quote(symbols: string[]): Promise<Quote[]>;
+}
+/**
+ * Poll a quote feed and yield `AlertEvent` whenever a configured condition is met.
+ *
+ * - Resolves when all `once` alerts have fired, or when `options.signal` is aborted.
+ * - Permanent alerts (once = false) run until the AbortSignal fires.
+ * - Debounce suppresses re-fires within `debounceMs` milliseconds.
+ *
+ * @example
+ * ```ts
+ * import { watchAlerts } from "market-feed/alerts";
+ * import { MarketFeed } from "market-feed";
+ *
+ * const feed = new MarketFeed();
+ * const controller = new AbortController();
+ *
+ * for await (const event of watchAlerts(feed, [
+ *   { symbol: "AAPL", condition: { type: "price_above", threshold: 200 }, once: true },
+ * ], { signal: controller.signal })) {
+ *   console.log(`AAPL crossed $200: $${event.quote.price}`);
+ * }
+ * ```
+ */
+declare function watchAlerts(feed: QuoteFetcher, alerts: AlertConfig[], options?: AlertsOptions): AsyncGenerator<AlertEvent>;
+
+export { type AlertCondition, type AlertConfig, type AlertEvent, type AlertsOptions, watchAlerts };

package/dist/alerts.d.ts

@@ -0,0 +1,70 @@
+import { a as Quote } from './quote-Cfh_7Cgg.js';
+
+type AlertCondition = {
+    type: "price_above";
+    threshold: number;
+} | {
+    type: "price_below";
+    threshold: number;
+} | {
+    type: "change_pct_above";
+    threshold: number;
+} | {
+    type: "change_pct_below";
+    threshold: number;
+} | {
+    type: "volume_above";
+    threshold: number;
+};
+interface AlertConfig {
+    symbol: string;
+    condition: AlertCondition;
+    /** Emit this alert at most once, then stop watching it. Defaults to false. */
+    once?: boolean;
+    /**
+     * Suppress re-fires within this many milliseconds after the last trigger.
+     * Defaults to 0 (no debounce).
+     */
+    debounceMs?: number;
+}
+interface AlertEvent {
+    type: "triggered";
+    alert: AlertConfig;
+    quote: Quote;
+    triggeredAt: Date;
+}
+interface AlertsOptions {
+    /** Poll interval in milliseconds. Defaults to 5 000. */
+    intervalMs?: number;
+    /** AbortSignal to stop the generator. */
+    signal?: AbortSignal;
+}
+
+interface QuoteFetcher {
+    quote(symbols: string[]): Promise<Quote[]>;
+}
+/**
+ * Poll a quote feed and yield `AlertEvent` whenever a configured condition is met.
+ *
+ * - Resolves when all `once` alerts have fired, or when `options.signal` is aborted.
+ * - Permanent alerts (once = false) run until the AbortSignal fires.
+ * - Debounce suppresses re-fires within `debounceMs` milliseconds.
+ *
+ * @example
+ * ```ts
+ * import { watchAlerts } from "market-feed/alerts";
+ * import { MarketFeed } from "market-feed";
+ *
+ * const feed = new MarketFeed();
+ * const controller = new AbortController();
+ *
+ * for await (const event of watchAlerts(feed, [
+ *   { symbol: "AAPL", condition: { type: "price_above", threshold: 200 }, once: true },
+ * ], { signal: controller.signal })) {
+ *   console.log(`AAPL crossed $200: $${event.quote.price}`);
+ * }
+ * ```
+ */
+declare function watchAlerts(feed: QuoteFetcher, alerts: AlertConfig[], options?: AlertsOptions): AsyncGenerator<AlertEvent>;
+
+export { type AlertCondition, type AlertConfig, type AlertEvent, type AlertsOptions, watchAlerts };

package/dist/alerts.js

@@ -0,0 +1,68 @@
+// market-feed — Unified financial market data client
+// https://github.com/piyushgupta344/market-feed
+
+// src/alerts/index.ts
+function conditionMet(condition, quote) {
+  switch (condition.type) {
+    case "price_above":
+      return quote.price > condition.threshold;
+    case "price_below":
+      return quote.price < condition.threshold;
+    case "change_pct_above":
+      return quote.changePercent > condition.threshold;
+    case "change_pct_below":
+      return quote.changePercent < condition.threshold;
+    case "volume_above":
+      return (quote.volume ?? 0) > condition.threshold;
+  }
+}
+async function* watchAlerts(feed, alerts, options) {
+  if (alerts.length === 0) return;
+  const intervalMs = options?.intervalMs ?? 5e3;
+  const signal = options?.signal;
+  const lastFired = /* @__PURE__ */ new Map();
+  const active = new Set(alerts);
+  while (active.size > 0) {
+    if (signal?.aborted) return;
+    const symbols = [...new Set([...active].map((a) => a.symbol))];
+    let quotes;
+    try {
+      quotes = await feed.quote(symbols);
+    } catch {
+      await sleep(intervalMs, signal);
+      continue;
+    }
+    if (signal?.aborted) return;
+    const quoteMap = new Map(quotes.map((q) => [q.symbol.toUpperCase(), q]));
+    const now = Date.now();
+    for (const alert of [...active]) {
+      const quote = quoteMap.get(alert.symbol.toUpperCase());
+      if (!quote) continue;
+      if (!conditionMet(alert.condition, quote)) continue;
+      const last = lastFired.get(alert);
+      if (last !== void 0 && alert.debounceMs && now - last < alert.debounceMs) continue;
+      lastFired.set(alert, now);
+      yield { type: "triggered", alert, quote, triggeredAt: new Date(now) };
+      if (alert.once) active.delete(alert);
+    }
+    if (active.size === 0) break;
+    await sleep(intervalMs, signal);
+  }
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      resolve();
+    }, { once: true });
+  });
+}
+
+export { watchAlerts };
+//# sourceMappingURL=alerts.js.map
+//# sourceMappingURL=alerts.js.map

package/dist/alerts.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/alerts/index.ts"],"names":[],"mappings":"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","file":"alerts.js","sourcesContent":["import type { Quote } from \"../types/quote.js\";\nimport type { AlertCondition, AlertConfig, AlertEvent, AlertsOptions } from \"./types.js\";\n\nexport type { AlertCondition, AlertConfig, AlertEvent, AlertsOptions } from \"./types.js\";\n\ninterface QuoteFetcher {\n  quote(symbols: string[]): Promise<Quote[]>;\n}\n\nfunction conditionMet(condition: AlertCondition, quote: Quote): boolean {\n  switch (condition.type) {\n    case \"price_above\":\n      return quote.price > condition.threshold;\n    case \"price_below\":\n      return quote.price < condition.threshold;\n    case \"change_pct_above\":\n      return quote.changePercent > condition.threshold;\n    case \"change_pct_below\":\n      return quote.changePercent < condition.threshold;\n    case \"volume_above\":\n      return (quote.volume ?? 0) > condition.threshold;\n  }\n}\n\n/**\n * Poll a quote feed and yield `AlertEvent` whenever a configured condition is met.\n *\n * - Resolves when all `once` alerts have fired, or when `options.signal` is aborted.\n * - Permanent alerts (once = false) run until the AbortSignal fires.\n * - Debounce suppresses re-fires within `debounceMs` milliseconds.\n *\n * @example\n * ```ts\n * import { watchAlerts } from \"market-feed/alerts\";\n * import { MarketFeed } from \"market-feed\";\n *\n * const feed = new MarketFeed();\n * const controller = new AbortController();\n *\n * for await (const event of watchAlerts(feed, [\n *   { symbol: \"AAPL\", condition: { type: \"price_above\", threshold: 200 }, once: true },\n * ], { signal: controller.signal })) {\n *   console.log(`AAPL crossed $200: $${event.quote.price}`);\n * }\n * ```\n */\nexport async function* watchAlerts(\n  feed: QuoteFetcher,\n  alerts: AlertConfig[],\n  options?: AlertsOptions,\n): AsyncGenerator<AlertEvent> {\n  if (alerts.length === 0) return;\n\n  const intervalMs = options?.intervalMs ?? 5_000;\n  const signal = options?.signal;\n\n  const lastFired = new Map<AlertConfig, number>();\n  const active = new Set(alerts);\n\n  while (active.size > 0) {\n    if (signal?.aborted) return;\n\n    const symbols = [...new Set([...active].map((a) => a.symbol))];\n\n    let quotes: Quote[];\n    try {\n      quotes = await feed.quote(symbols);\n    } catch {\n      await sleep(intervalMs, signal);\n      continue;\n    }\n\n    if (signal?.aborted) return;\n\n    const quoteMap = new Map(quotes.map((q) => [q.symbol.toUpperCase(), q]));\n    const now = Date.now();\n\n    for (const alert of [...active]) {\n      const quote = quoteMap.get(alert.symbol.toUpperCase());\n      if (!quote) continue;\n\n      if (!conditionMet(alert.condition, quote)) continue;\n\n      // Debounce check\n      const last = lastFired.get(alert);\n      if (last !== undefined && alert.debounceMs && now - last < alert.debounceMs) continue;\n\n      lastFired.set(alert, now);\n      yield { type: \"triggered\", alert, quote, triggeredAt: new Date(now) };\n\n      if (alert.once) active.delete(alert);\n    }\n\n    if (active.size === 0) break;\n    await sleep(intervalMs, signal);\n  }\n}\n\nfunction sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise((resolve) => {\n    if (signal?.aborted) {\n      resolve();\n      return;\n    }\n    const timer = setTimeout(resolve, ms);\n    signal?.addEventListener(\"abort\", () => {\n      clearTimeout(timer);\n      resolve();\n    }, { once: true });\n  });\n}\n"]}