market-feed 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # market-feed Changelog
 
+## 0.6.0 — 2026-03-12
+
+### New provider
+
+**`TwelveDataProvider`** — Twelve Data (free tier: 800 credits/day, 8 calls/minute).
+
+```ts
+import { MarketFeed, TwelveDataProvider } from "market-feed";
+
+const feed = new MarketFeed([
+  new TwelveDataProvider({ apiKey: process.env.TWELVE_DATA_KEY! }),
+]);
+
+const quote   = await feed.quote(["AAPL", "BTC/USD", "EUR/USD"]);
+const bars    = await feed.historical("AAPL", { interval: "1wk" });
+const results = await feed.search("apple");
+const profile = await feed.company("AAPL");
+```
+
+Supports: `quote`, `historical`, `search`, `company`.
+
+Strong coverage for global equities, forex, and crypto pairs. Symbol normalisation handles all common formats:
+- US stocks: `AAPL` (unchanged)
+- Crypto: `BTC-USD` / `BTC/USD` / `X:BTCUSD` → `BTC/USD`
+- Forex: `EURUSD=X` / `C:EURUSD` → `EUR/USD`
+
+Free plan sign-up: https://twelvedata.com
+
+#### Interval mapping
+
+| market-feed | Twelve Data |
+|-------------|-------------|
+| `1m` | `1min` |
+| `5m` | `5min` |
+| `15m` | `15min` |
+| `30m` | `30min` |
+| `1h` | `1h` |
+| `1d` | `1day` |
+| `1wk` | `1week` |
+| `1mo` | `1month` |
+
+### New utility
+
+**`toTwelveDataSymbol(symbol)`** — exported from main `market-feed` entry point. Converts any supported symbol format (Yahoo/Polygon/standard) to the slash-pair notation that Twelve Data expects for crypto and forex.
+
+### CLI
+
+`--td-key <key>` flag adds `TwelveDataProvider` to the CLI provider chain.
+
+### Breaking changes
+
+None. All v0.5.x imports continue to work unchanged.
+
+### Other changes
+
+- `TwelveDataProvider` and `TwelveDataProviderOptions` exported from main `market-feed` entry point
+- `toTwelveDataSymbol` exported from main `market-feed` entry point
+- 30 new unit tests (456 total across 22 test files)
+
+---
+
+## 0.5.1 — 2026-03-12
+
+### CLI additions
+
+Three new commands expose the v0.5.0 corporate-action data from the terminal:
+
+```bash
+market-feed earnings AAPL --limit 8
+market-feed dividends AAPL --from 2020-01-01
+market-feed splits AAPL --json
+```
+
+New flags `--from <date>` and `--to <date>` scope the dividend/split history by date range (ISO 8601). `--limit` and `--json` work on all three commands.
+
+### Breaking changes
+
+None.
+
+---
+
 ## 0.5.0 — 2026-03-11
 
 ### New modules

package/README.md

@@ -1,7 +1,7 @@
 # market-feed
 
 > Unified TypeScript client for financial market data.
-> Wraps Yahoo Finance, Alpha Vantage, Polygon.io, and Finnhub under one consistent interface — with caching and automatic fallback built in.
+> Wraps Yahoo Finance, Alpha Vantage, Polygon.io, Finnhub, and Twelve Data 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. Four providers. Zero API key required for Yahoo Finance.
+One interface. Five providers. Zero API key required for Yahoo Finance.
 
 ---
 

package/dist/cli.js

@@ -1585,6 +1585,206 @@ function subtractOneYear3() {
   return d;
 }
 
+// src/providers/twelve-data/transform.ts
+var PROVIDER5 = "twelve-data";
+function transformQuote5(data, raw) {
+  return {
+    symbol: data.symbol,
+    name: data.name,
+    price: Number(data.close),
+    change: Number(data.change),
+    changePercent: Number(data.percent_change),
+    open: Number(data.open),
+    high: Number(data.high),
+    low: Number(data.low),
+    close: Number(data.close),
+    previousClose: Number(data.previous_close),
+    volume: Number(data.volume),
+    ...data.average_volume !== void 0 ? { avgVolume: Number(data.average_volume) } : {},
+    ...data.fifty_two_week !== void 0 ? {
+      fiftyTwoWeekHigh: Number(data.fifty_two_week.high),
+      fiftyTwoWeekLow: Number(data.fifty_two_week.low)
+    } : {},
+    currency: data.currency,
+    exchange: data.exchange,
+    timestamp: new Date(data.timestamp * 1e3),
+    provider: PROVIDER5,
+    ...raw !== void 0 ? { raw } : {}
+  };
+}
+function transformHistoricalBar2(bar, raw) {
+  return {
+    date: new Date(bar.datetime),
+    open: Number(bar.open),
+    high: Number(bar.high),
+    low: Number(bar.low),
+    close: Number(bar.close),
+    volume: Number(bar.volume),
+    ...raw !== void 0 ? { raw } : {}
+  };
+}
+function transformSearch5(result, raw) {
+  return {
+    symbol: result.symbol,
+    name: result.instrument_name,
+    type: mapInstrumentType(result.instrument_type),
+    exchange: result.exchange || void 0,
+    provider: PROVIDER5,
+    ...raw !== void 0 ? { raw } : {}
+  };
+}
+function transformProfile(data, raw) {
+  return {
+    symbol: data.symbol,
+    name: data.name,
+    description: data.description || void 0,
+    sector: data.sector || void 0,
+    industry: data.industry || void 0,
+    country: data.country || void 0,
+    employees: data.employees || void 0,
+    website: data.website || void 0,
+    ceo: data.CEO || void 0,
+    exchange: data.exchange || void 0,
+    provider: PROVIDER5,
+    ...raw !== void 0 ? { raw } : {}
+  };
+}
+function mapInstrumentType(type) {
+  const t = type.toLowerCase();
+  if (t.includes("common stock") || t === "cs") return "stock";
+  if (t.includes("etf") || t.includes("exchange traded fund")) return "etf";
+  if (t.includes("crypto")) return "crypto";
+  if (t.includes("forex") || t.includes("currency")) return "forex";
+  if (t.includes("mutual fund") || t.includes("fund")) return "mutual-fund";
+  if (t.includes("future")) return "future";
+  if (t.includes("index")) return "index";
+  return "unknown";
+}
+
+// src/providers/twelve-data/index.ts
+var TwelveDataProvider = class {
+  constructor(options) {
+    this.options = options;
+    this.apiKey = options.apiKey;
+    this.http = new HttpClient("twelve-data", {
+      baseUrl: "https://api.twelvedata.com",
+      ...options.timeoutMs !== void 0 ? { timeoutMs: options.timeoutMs } : {},
+      ...options.retries !== void 0 ? { retries: options.retries } : {}
+    });
+    this.limiter = options.rateLimiter ?? new RateLimiter("twelve-data", 8, 8 / 60);
+  }
+  name = "twelve-data";
+  http;
+  limiter;
+  apiKey;
+  // ---------------------------------------------------------------------------
+  // Quote
+  // ---------------------------------------------------------------------------
+  async quote(symbols, options) {
+    return Promise.all(symbols.map((s) => this.fetchSingleQuote(s, options)));
+  }
+  async fetchSingleQuote(symbol, options) {
+    this.limiter.consume();
+    const s = normalise(symbol);
+    const data = await this.http.get("/quote", {
+      params: { symbol: s, apikey: this.apiKey }
+    });
+    if (data.code !== void 0) {
+      throw new ProviderError(
+        data.message ?? `No quote data for symbol "${s}"`,
+        this.name,
+        data.code
+      );
+    }
+    return transformQuote5(data, options?.raw ? data : void 0);
+  }
+  // ---------------------------------------------------------------------------
+  // Historical (time series)
+  // ---------------------------------------------------------------------------
+  async historical(symbol, options) {
+    this.limiter.consume();
+    const s = normalise(symbol);
+    const interval = toInterval(options?.interval ?? "1d");
+    const params = {
+      symbol: s,
+      interval,
+      outputsize: 5e3,
+      apikey: this.apiKey
+    };
+    if (options?.period1 !== void 0) {
+      params["start_date"] = typeof options.period1 === "string" ? options.period1 : options.period1.toISOString().slice(0, 10);
+    }
+    if (options?.period2 !== void 0) {
+      params["end_date"] = typeof options.period2 === "string" ? options.period2 : options.period2.toISOString().slice(0, 10);
+    }
+    const data = await this.http.get("/time_series", { params });
+    if (data.code !== void 0 || data.status === "error") {
+      throw new ProviderError(
+        data.message ?? `No historical data for symbol "${s}"`,
+        this.name,
+        data.code
+      );
+    }
+    if (!Array.isArray(data.values) || data.values.length === 0) {
+      throw new ProviderError(`No historical data for symbol "${s}"`, this.name);
+    }
+    return [...data.values].reverse().map((bar) => transformHistoricalBar2(bar, options?.raw ? bar : void 0));
+  }
+  // ---------------------------------------------------------------------------
+  // Search
+  // ---------------------------------------------------------------------------
+  async search(query, options) {
+    this.limiter.consume();
+    const limit = options?.limit ?? 10;
+    const data = await this.http.get("/symbol_search", {
+      params: { symbol: query, apikey: this.apiKey }
+    });
+    if (data.code !== void 0 || data.status === "error") {
+      return [];
+    }
+    return (data.data ?? []).slice(0, limit).map((r) => transformSearch5(r, options?.raw ? r : void 0));
+  }
+  // ---------------------------------------------------------------------------
+  // Company (profile)
+  // ---------------------------------------------------------------------------
+  async company(symbol, options) {
+    this.limiter.consume();
+    const s = normalise(symbol);
+    const data = await this.http.get("/profile", {
+      params: { symbol: s, apikey: this.apiKey }
+    });
+    if (data.code !== void 0 || !data.name) {
+      throw new ProviderError(
+        data.message ?? `No company data for symbol "${s}"`,
+        this.name,
+        data.code
+      );
+    }
+    return transformProfile(data, options?.raw ? data : void 0);
+  }
+};
+function toInterval(interval) {
+  const map = {
+    "1m": "1min",
+    "2m": "2min",
+    "5m": "5min",
+    "15m": "15min",
+    "30m": "30min",
+    "45m": "45min",
+    "60m": "1h",
+    "90m": "90min",
+    "1h": "1h",
+    "2h": "2h",
+    "4h": "4h",
+    "1d": "1day",
+    "5d": "1week",
+    "1wk": "1week",
+    "1mo": "1month",
+    "3mo": "3month"
+  };
+  return map[interval] ?? "1day";
+}
+
 // src/cli/index.ts
 var HELP = `
 Usage: market-feed <command> [options]
@@ -1595,16 +1795,22 @@ Commands:
   search     <query>        Search for symbols
   company    <symbol>       Fetch company profile
   news       <symbol>       Fetch recent news
+  earnings   <symbol>       Fetch EPS history (actuals vs. estimates)
+  dividends  <symbol>       Fetch cash dividend history
+  splits     <symbol>       Fetch stock split history
 
 Options:
   --av-key <key>        Alpha Vantage API key
   --polygon-key <key>   Polygon.io API key
   --finnhub-key <key>   Finnhub API key
+  --td-key <key>        Twelve Data API key
   --json                Output raw JSON
   --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)
+  --from <date>         Dividends/splits start date (ISO 8601)
+  --to <date>           Dividends/splits end date (ISO 8601)
   -h, --help            Show this help message
 
 Examples:
@@ -1613,6 +1819,9 @@ Examples:
   market-feed search "apple inc"
   market-feed company AAPL --json
   market-feed news AAPL --limit 5
+  market-feed earnings AAPL --limit 8
+  market-feed dividends AAPL --from 2020-01-01
+  market-feed splits AAPL --json
 `.trim();
 function parseArgs(argv) {
   const args = argv.slice(2);
@@ -1641,6 +1850,9 @@ function parseArgs(argv) {
     } else if (arg === "--finnhub-key") {
       result.finnhubKey = args[++i];
       i++;
+    } else if (arg === "--td-key") {
+      result.tdKey = args[++i];
+      i++;
     } else if (arg === "--limit") {
       result.limit = Number(args[++i]) || 10;
       i++;
@@ -1653,6 +1865,12 @@ function parseArgs(argv) {
     } else if (arg === "--period2") {
       result.period2 = args[++i];
       i++;
+    } else if (arg === "--from") {
+      result.from = args[++i];
+      i++;
+    } else if (arg === "--to") {
+      result.to = args[++i];
+      i++;
     } else if (!arg.startsWith("-") && !result.command) {
       result.command = arg;
       i++;
@@ -1666,12 +1884,11 @@ function parseArgs(argv) {
   return result;
 }
 function buildFeed(args) {
-  const providers = [
-    new YahooProvider()
-  ];
+  const providers = [new YahooProvider()];
   if (args.avKey) providers.push(new AlphaVantageProvider({ apiKey: args.avKey }));
   if (args.polygonKey) providers.push(new PolygonProvider({ apiKey: args.polygonKey }));
   if (args.finnhubKey) providers.push(new FinnhubProvider({ apiKey: args.finnhubKey }));
+  if (args.tdKey) providers.push(new TwelveDataProvider({ apiKey: args.tdKey }));
   return new MarketFeed({ providers });
 }
 function pad(s, n) {
@@ -1771,6 +1988,82 @@ async function runNews(feed, symbol, args) {
     console.log("");
   }
 }
+async function runEarnings(feed, symbol, args) {
+  const events = await feed.earnings(symbol, { limit: args.limit });
+  if (args.json) {
+    console.log(JSON.stringify(events, null, 2));
+    return;
+  }
+  if (events.length === 0) {
+    console.log("No earnings data found.");
+    return;
+  }
+  console.log(
+    `${pad("Date", 12)} ${pad("Period", 12)} ${pad("Actual", 9)} ${pad("Estimate", 9)} ${pad("Surprise%", 10)} Provider`
+  );
+  console.log("-".repeat(70));
+  for (const e of events) {
+    const date = e.date.toISOString().slice(0, 10);
+    const period = e.period ?? "-";
+    const actual = e.epsActual !== void 0 ? fmtNum(e.epsActual, 2) : "-";
+    const estimate = e.epsEstimate !== void 0 ? fmtNum(e.epsEstimate, 2) : "-";
+    const surprise = e.epsSurprisePct !== void 0 ? `${e.epsSurprisePct >= 0 ? "+" : ""}${fmtNum(e.epsSurprisePct, 2)}%` : "-";
+    console.log(
+      `${pad(date, 12)} ${pad(period, 12)} ${pad(actual, 9)} ${pad(estimate, 9)} ${pad(surprise, 10)} ${e.provider}`
+    );
+  }
+}
+async function runDividends(feed, symbol, args) {
+  const events = await feed.dividends(symbol, {
+    limit: args.limit,
+    ...args.from ? { from: args.from } : {},
+    ...args.to ? { to: args.to } : {}
+  });
+  if (args.json) {
+    console.log(JSON.stringify(events, null, 2));
+    return;
+  }
+  if (events.length === 0) {
+    console.log("No dividend data found.");
+    return;
+  }
+  console.log(
+    `${pad("Ex Date", 12)} ${pad("Amount", 9)} ${pad("Frequency", 14)} ${pad("Pay Date", 12)} Provider`
+  );
+  console.log("-".repeat(66));
+  for (const e of events) {
+    const exDate = e.exDate.toISOString().slice(0, 10);
+    const amount = `$${fmtNum(e.amount, 4)}`;
+    const freq = e.frequency ?? "-";
+    const payDate = e.payDate ? e.payDate.toISOString().slice(0, 10) : "-";
+    console.log(
+      `${pad(exDate, 12)} ${pad(amount, 9)} ${pad(freq, 14)} ${pad(payDate, 12)} ${e.provider}`
+    );
+  }
+}
+async function runSplits(feed, symbol, args) {
+  const events = await feed.splits(symbol, {
+    limit: args.limit,
+    ...args.from ? { from: args.from } : {},
+    ...args.to ? { to: args.to } : {}
+  });
+  if (args.json) {
+    console.log(JSON.stringify(events, null, 2));
+    return;
+  }
+  if (events.length === 0) {
+    console.log("No split data found.");
+    return;
+  }
+  console.log(`${pad("Date", 12)} ${pad("Ratio", 8)} ${pad("Description", 14)} Provider`);
+  console.log("-".repeat(50));
+  for (const e of events) {
+    const date = e.date.toISOString().slice(0, 10);
+    const ratio = fmtNum(e.ratio, 4);
+    const desc = e.description ?? "-";
+    console.log(`${pad(date, 12)} ${pad(ratio, 8)} ${pad(desc, 14)} ${e.provider}`);
+  }
+}
 async function main() {
   const args = parseArgs(process.argv);
   if (!args.command || args.command === "help") {
@@ -1825,6 +2118,33 @@ async function main() {
         await runNews(feed, symbol, args);
         break;
       }
+      case "earnings": {
+        const [symbol] = args.positionals;
+        if (!symbol) {
+          console.error("Error: earnings requires a symbol\n");
+          process.exit(1);
+        }
+        await runEarnings(feed, symbol, args);
+        break;
+      }
+      case "dividends": {
+        const [symbol] = args.positionals;
+        if (!symbol) {
+          console.error("Error: dividends requires a symbol\n");
+          process.exit(1);
+        }
+        await runDividends(feed, symbol, args);
+        break;
+      }
+      case "splits": {
+        const [symbol] = args.positionals;
+        if (!symbol) {
+          console.error("Error: splits requires a symbol\n");
+          process.exit(1);
+        }
+        await runSplits(feed, symbol, args);
+        break;
+      }
       default: {
         console.error(`Unknown command: "${args.command}"
 `);