tn-financial-data 0.1.4 → 0.3.0

package/README.md

@@ -26,6 +26,8 @@ This package is the hosted agent-facing surface only. The repo's website, local
 ## Features
 
 - Company facts, financials, prices, news, insider trades, ownership, global rates, and raw SEC filings through one hosted API
+- Multi-ticker resolve and snapshot reads for lower-latency agent workflows
+- Earnings calendar, dividends, and stock splits through the same hosted read contract
 - Agent-friendly CLI with clean error output, scoped subcommand help, and self-description via `tn-financial-data describe opencli`
 - Packaged skill bundle for Claude and OpenCode installs
 - Typed TypeScript client from the root package export
@@ -37,7 +39,7 @@ This package is the hosted agent-facing surface only. The repo's website, local
 npm install -g tn-financial-data
 
 export TN_FINANCIAL_DATA_API_KEY=<your-api-key>
-tn-financial-data query available-tickers
+tn-financial-data query resolve-ticker --query google
 ```
 
 Live reads accept:
@@ -51,6 +53,8 @@ Optional base URL override:
 - `TN_FINANCIAL_DATA_API_BASE_URL`
 
 The published CLI reads those values from the current process environment only.
+Use `resolve-ticker` to map company or brand input to supported symbols.
+Treat `available-tickers` as the authoritative support list for exact symbols; do not silently swap an unsupported exact ticker to a different share class.
 
 Production default:
 
@@ -61,7 +65,13 @@ https://api.truenorth-financial.ai/v1
 ## Quick Start
 
 ```bash
+tn-financial-data query resolve-ticker --query google
+tn-financial-data query resolve-ticker --query google --query meta --query nvda
 tn-financial-data query available-tickers
+tn-financial-data query snapshot --tickers AAPL,MSFT,NVDA
+tn-financial-data query financial-metrics-snapshot --tickers AAPL,MSFT,NVDA --period annual
+tn-financial-data query earnings-calendar --tickers AAPL,MSFT --start-date 2026-04-02 --end-date 2026-04-16
+tn-financial-data query dividends --ticker AAPL --limit 10
 tn-financial-data query company --ticker AAPL
 tn-financial-data query filings --ticker AAPL --filing-type 8-K --limit 5
 tn-financial-data query general-overview --ticker AAPL --period quarterly --financial-limit 4 --news-limit 5
@@ -86,10 +96,15 @@ Ownership semantics:
 Common query examples:
 
 ```bash
+tn-financial-data query snapshot --tickers AAPL,MSFT,NVDA
+tn-financial-data query financial-metrics-snapshot --tickers AAPL,MSFT,NVDA --period annual
 tn-financial-data query financials --ticker AAPL --period annual --statement all
 tn-financial-data query financial-metrics --ticker AAPL --period annual --limit 4
 tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8
+tn-financial-data query earnings-calendar --tickers AAPL,MSFT --start-date 2026-04-02 --end-date 2026-04-16
 tn-financial-data query quarterly-highlights --ticker AAPL
+tn-financial-data query dividends --ticker AAPL --limit 10
+tn-financial-data query splits --ticker AAPL --limit 10
 tn-financial-data query filings --ticker AAPL --filing-type 10-K,10-Q,8-K --limit 10
 tn-financial-data query filing-items --ticker AAPL --accession-number 0000320193-26-000005 --item 2.02 --include-exhibits
 tn-financial-data query prices --ticker AAPL --interval day --start-date 2025-01-01 --end-date 2025-01-31
@@ -169,8 +184,22 @@ const client = new TnFinancialData({
   apiKey: process.env.TN_FINANCIAL_DATA_API_KEY!,
 });
 
+const resolution = await client.resolveTicker("google");
+console.log(resolution.status, resolution.resolved_ticker);
+
+const batchResolution = await client.resolveTickers(["google", "meta", "nvda"]);
+console.log(batchResolution.results.map((row) => `${row.query}:${row.status}`));
+
+const calendar = await client.getEarningsCalendar({
+  tickers: ["NVDA", "KO"],
+  startDate: "2026-04-01",
+  endDate: "2026-06-30",
+});
+
+console.log(calendar.events.map((row) => `${row.ticker}:${row.event_date_start}`));
+
 const filings = await client.getFilings("AAPL", {
-  filingType: ["8-K"],
+  filingTypes: ["8-K"],
   limit: 3,
 });
 
@@ -179,7 +208,7 @@ console.log(filings.filings[0]?.accession_number);
 const filingItems = await client.getFilingItems("AAPL", {
   accessionNumber: "0000320193-26-000005",
   filingType: "8-K",
-  item: ["2.02"],
+  items: ["2.02"],
   includeExhibits: true,
 });
 

package/dist/cli.js

@@ -135,6 +135,26 @@ var TnFinancialData = class {
     this.appendReportPeriodParams(params, opts);
     return params.toString();
   }
+  buildTickerBatchParams(tickers, extra) {
+    const params = new URLSearchParams({
+      tickers: tickers.join(",")
+    });
+    if (extra) {
+      for (const [key, value] of Object.entries(extra)) {
+        if (value !== void 0) {
+          params.set(key, value);
+        }
+      }
+    }
+    return params.toString();
+  }
+  buildRepeatedQueryParams(key, values) {
+    const params = new URLSearchParams();
+    for (const value of values) {
+      params.append(key, value);
+    }
+    return params.toString();
+  }
   buildSegmentedRevenueParams(ticker, opts) {
     const params = new URLSearchParams({ ticker, period: opts.period });
     this.appendLimitParam(params, opts.limit);
@@ -147,6 +167,22 @@ var TnFinancialData = class {
     if (opts?.reportPeriod) params.set("report_period", opts.reportPeriod);
     return params.toString();
   }
+  buildEarningsCalendarParams(opts) {
+    const params = new URLSearchParams();
+    if (opts?.ticker && opts?.tickers && opts.tickers.length > 0) {
+      throw new Error("Use either ticker or tickers, not both.");
+    }
+    if (opts?.ticker) {
+      params.set("ticker", opts.ticker);
+    }
+    if (opts?.tickers && opts.tickers.length > 0) {
+      params.set("tickers", opts.tickers.join(","));
+    }
+    this.appendLimitParam(params, opts?.limit);
+    if (opts?.startDate) params.set("start_date", opts.startDate);
+    if (opts?.endDate) params.set("end_date", opts.endDate);
+    return params.toString();
+  }
   buildInsiderTradeParams(ticker, opts) {
     const params = new URLSearchParams({ ticker });
     this.appendLimitParam(params, opts?.limit);
@@ -159,6 +195,13 @@ var TnFinancialData = class {
     if (opts?.securityType) params.set("security_type", opts.securityType);
     return params.toString();
   }
+  buildCorporateActionsParams(ticker, opts) {
+    const params = new URLSearchParams({ ticker });
+    this.appendLimitParam(params, opts?.limit);
+    if (opts?.startDate) params.set("start_date", opts.startDate);
+    if (opts?.endDate) params.set("end_date", opts.endDate);
+    return params.toString();
+  }
   buildFilingsParams(ticker, opts) {
     const params = new URLSearchParams({ ticker });
     this.appendLimitParam(params, opts?.limit);
@@ -212,11 +255,24 @@ var TnFinancialData = class {
       `/financial-metrics/snapshot?${this.buildOptionalFinancialParams(ticker, opts)}`
     );
   }
+  async getBatchFinancialMetricsSnapshots(tickers, opts) {
+    return this.request(
+      `/financial-metrics/snapshot?${this.buildTickerBatchParams(tickers, {
+        period: opts?.period
+      })}`
+    );
+  }
   async getEarnings(ticker, opts) {
     return this.request(
       `/earnings?${this.buildOptionalFinancialParams(ticker, opts)}`
     );
   }
+  async getEarningsCalendar(opts) {
+    const params = this.buildEarningsCalendarParams(opts);
+    return this.request(
+      params.length > 0 ? `/earnings/calendar?${params}` : "/earnings/calendar"
+    );
+  }
   async getGeneralOverview(ticker, opts) {
     return this.request(
       `/general-overview?${this.buildGeneralOverviewParams(ticker, opts)}`
@@ -230,6 +286,16 @@ var TnFinancialData = class {
   async getAvailableTickers() {
     return this.request("/financials/income-statements/tickers");
   }
+  async resolveTicker(query) {
+    return this.request(
+      `/tickers/resolve?${new URLSearchParams({ q: query })}`
+    );
+  }
+  async resolveTickers(queries) {
+    return this.request(
+      `/tickers/resolve/batch?${this.buildRepeatedQueryParams("query", queries)}`
+    );
+  }
   async getPrices(ticker, opts) {
     const params = new URLSearchParams({
       ticker,
@@ -244,6 +310,11 @@ var TnFinancialData = class {
       `/prices/snapshot?${new URLSearchParams({ ticker })}`
     );
   }
+  async getBatchPriceSnapshots(tickers) {
+    return this.request(
+      `/prices/snapshot?${this.buildTickerBatchParams(tickers)}`
+    );
+  }
   async getNews(ticker, opts) {
     const params = new URLSearchParams({ ticker });
     if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
@@ -252,6 +323,16 @@ var TnFinancialData = class {
     if (opts?.publisher) params.set("publisher", opts.publisher);
     return this.request(`/news?${params}`);
   }
+  async getDividends(ticker, opts) {
+    return this.request(
+      `/corporate-actions/dividends?${this.buildCorporateActionsParams(ticker, opts)}`
+    );
+  }
+  async getSplits(ticker, opts) {
+    return this.request(
+      `/corporate-actions/splits?${this.buildCorporateActionsParams(ticker, opts)}`
+    );
+  }
   async getInsiderTrades(ticker, opts) {
     return this.request(
       `/insider-trades?${this.buildInsiderTradeParams(ticker, opts)}`
@@ -568,23 +649,30 @@ function rootHelp() {
     "tn-financial-data",
     "",
     "Usage:",
-    "  tn-financial-data query <available-tickers|company|filings|filing-items|general-overview|financials|financial-metrics|financial-metrics-snapshot|earnings|quarterly-highlights|analyst-estimates|prices|snapshot|news|insider-trades|institutional-ownership|investor-portfolio|global-rates|segmented-revenues|screen|screen-fields> [options]",
+    "  tn-financial-data query <available-tickers|resolve-ticker|company|filings|filing-items|general-overview|financials|financial-metrics|financial-metrics-snapshot|earnings|earnings-calendar|quarterly-highlights|analyst-estimates|prices|snapshot|dividends|splits|news|insider-trades|institutional-ownership|investor-portfolio|global-rates|segmented-revenues|screen|screen-fields> [options]",
     "  tn-financial-data skill <install|print|targets> [--tool claude|opencode]",
     "  tn-financial-data describe opencli",
     "  tn-financial-data --version",
     "",
     "Examples:",
     "  tn-financial-data query available-tickers",
+    '  tn-financial-data query resolve-ticker --query "google"',
+    '  tn-financial-data query resolve-ticker --query "google" --query "meta" --query "nvda"',
     "  tn-financial-data query financials --ticker AAPL --period annual --statement all",
     "  tn-financial-data query filings --ticker AAPL --filing-type 8-K --limit 10",
     "  tn-financial-data query filing-items --ticker AAPL --accession-number 0000320193-26-000005 --full-text",
     "  tn-financial-data query general-overview --ticker AAPL --period quarterly --financial-limit 4 --news-limit 5",
     "  tn-financial-data query financials --ticker AAPL --statement key-stats",
     "  tn-financial-data query financial-metrics --ticker AAPL --period annual --limit 4",
+    "  tn-financial-data query snapshot --tickers AAPL,MSFT,NVDA",
+    "  tn-financial-data query financial-metrics-snapshot --tickers AAPL,MSFT,NVDA --period annual",
     "  tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8",
+    "  tn-financial-data query earnings-calendar --tickers AAPL,MSFT --start-date 2026-04-02 --end-date 2026-04-16",
     "  tn-financial-data query quarterly-highlights --ticker AAPL",
     "  tn-financial-data query analyst-estimates --ticker AAPL",
     "  tn-financial-data query prices --ticker AAPL --interval day --start-date 2025-01-01 --end-date 2025-01-31",
+    "  tn-financial-data query dividends --ticker AAPL --limit 20",
+    "  tn-financial-data query splits --ticker AAPL --limit 20",
     "  tn-financial-data query insider-trades --ticker AAPL --transaction-code P,S --limit 25",
     "  tn-financial-data query institutional-ownership --ticker AAPL --limit 20",
     "  tn-financial-data query investor-portfolio --investor vanguard --limit 20",
@@ -608,18 +696,22 @@ function queryHelp() {
   return [
     "Usage:",
     "  tn-financial-data query available-tickers [--api-key <key>] [--base-url <url>]",
+    "  tn-financial-data query resolve-ticker --query <text> [--query <text>]... [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query company --ticker <symbol> [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query filings --ticker <symbol> [--filing-type <csv>] [--start-date <date>] [--end-date <date>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query filing-items --ticker <symbol> --accession-number <accession> [--filing-type <10-K|10-Q|8-K>] [--item <csv>] [--full-text] [--include-exhibits] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query general-overview --ticker <symbol> [--period <annual|quarterly|ttm>] [--financial-limit <n>] [--news-limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query financials --ticker <symbol> [--period <annual|quarterly|ttm>] [--statement <all|income|balance|cash-flow|key-stats>] [--limit <n>] [--report-period <date>] [--report-period-gte <date>] [--report-period-lte <date>] [--report-period-gt <date>] [--report-period-lt <date>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query financial-metrics --ticker <symbol> [--period <annual|quarterly|ttm>] [--limit <n>] [--report-period <date>] [--report-period-gte <date>] [--report-period-lte <date>] [--report-period-gt <date>] [--report-period-lt <date>] [--api-key <key>] [--base-url <url>]",
-    "  tn-financial-data query financial-metrics-snapshot --ticker <symbol> [--period <annual|quarterly|ttm>] [--api-key <key>] [--base-url <url>]",
+    "  tn-financial-data query financial-metrics-snapshot (--ticker <symbol> | --tickers <csv>) [--period <annual|quarterly|ttm>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query earnings --ticker <symbol> [--period <annual|quarterly|ttm>] [--limit <n>] [--report-period <date>] [--report-period-gte <date>] [--report-period-lte <date>] [--report-period-gt <date>] [--report-period-lt <date>] [--api-key <key>] [--base-url <url>]",
+    "  tn-financial-data query earnings-calendar [--ticker <symbol> | --tickers <csv>] [--start-date <date>] [--end-date <date>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query quarterly-highlights --ticker <symbol> [--report-period <date>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query analyst-estimates --ticker <symbol> [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query prices --ticker <symbol> --interval <day|1h> --start-date <date> --end-date <date> [--api-key <key>] [--base-url <url>]",
-    "  tn-financial-data query snapshot --ticker <symbol> [--api-key <key>] [--base-url <url>]",
+    "  tn-financial-data query snapshot (--ticker <symbol> | --tickers <csv>) [--api-key <key>] [--base-url <url>]",
+    "  tn-financial-data query dividends --ticker <symbol> [--start-date <date>] [--end-date <date>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
+    "  tn-financial-data query splits --ticker <symbol> [--start-date <date>] [--end-date <date>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query news --ticker <symbol> [--start-date <date>] [--end-date <date>] [--publisher <name>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query insider-trades --ticker <symbol> [--start-date <date>] [--end-date <date>] [--reporting-owner-cik <cik>] [--transaction-code <csv>] [--security-type <all|non_derivative|derivative>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query institutional-ownership --ticker <symbol> [--limit <n>] [--api-key <key>] [--base-url <url>]",
@@ -728,16 +820,23 @@ function buildOpenCliDocument() {
     ],
     examples: [
       "tn-financial-data query available-tickers",
+      'tn-financial-data query resolve-ticker --query "google"',
+      'tn-financial-data query resolve-ticker --query "google" --query "meta" --query "nvda"',
       "tn-financial-data query filings --ticker AAPL --filing-type 8-K --limit 10",
       "tn-financial-data query filing-items --ticker AAPL --accession-number 0000320193-26-000005 --full-text",
       "tn-financial-data query general-overview --ticker AAPL --period quarterly --financial-limit 4 --news-limit 5",
       "tn-financial-data query financials --ticker AAPL --period annual --statement all",
       "tn-financial-data query financial-metrics --ticker AAPL --period annual --limit 4",
       "tn-financial-data query financial-metrics-snapshot --ticker AAPL",
+      "tn-financial-data query financial-metrics-snapshot --tickers AAPL,MSFT,NVDA --period annual",
       "tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8",
+      "tn-financial-data query earnings-calendar --tickers AAPL,MSFT --start-date 2026-04-02 --end-date 2026-04-16",
       "tn-financial-data query quarterly-highlights --ticker AAPL",
       "tn-financial-data query analyst-estimates --ticker AAPL",
+      "tn-financial-data query snapshot --tickers AAPL,MSFT,NVDA",
       "tn-financial-data query prices --ticker AAPL --interval day --start-date 2025-01-01 --end-date 2025-01-31",
+      "tn-financial-data query dividends --ticker AAPL --limit 20",
+      "tn-financial-data query splits --ticker AAPL --limit 20",
       "tn-financial-data query insider-trades --ticker AAPL --transaction-code P,S --limit 25",
       "tn-financial-data query institutional-ownership --ticker AAPL --limit 20",
       "tn-financial-data query investor-portfolio --investor vanguard --limit 20",
@@ -785,6 +884,24 @@ function buildOpenCliDocument() {
             name: "available-tickers",
             description: "Fetch the current supported ticker snapshot with financial and news freshness timestamps."
           },
+          {
+            name: "resolve-ticker",
+            description: "Resolve a company keyword or exact symbol against the supported ticker universe without silently swapping share classes.",
+            options: [
+              {
+                name: "query",
+                required: true,
+                arguments: [
+                  {
+                    name: "text",
+                    required: true,
+                    description: "Company name, brand, prompt fragment, or ticker text."
+                  }
+                ],
+                description: "Query text to resolve. Repeat to resolve multiple inputs in one request."
+              }
+            ]
+          },
           {
             name: "company",
             description: "Fetch company facts for a single ticker.",
@@ -1074,13 +1191,23 @@ function buildOpenCliDocument() {
           },
           {
             name: "financial-metrics-snapshot",
-            description: "Fetch the latest derived financial metrics row, latest daily price snapshot, and current key statistics for one ticker.",
+            description: "Fetch the latest derived financial metrics row, latest daily price snapshot, and current key statistics for one ticker or a small ticker batch.",
             options: [
               {
                 name: "ticker",
-                required: true,
                 arguments: [{ name: "ticker", required: true, description: "Ticker symbol." }],
-                description: "Ticker to fetch."
+                description: "Single ticker to fetch."
+              },
+              {
+                name: "tickers",
+                arguments: [
+                  {
+                    name: "tickers",
+                    required: true,
+                    description: "Comma-separated ticker symbols, max 10."
+                  }
+                ],
+                description: "Ticker batch to fetch instead of --ticker."
               },
               {
                 name: "period",
@@ -1168,6 +1295,47 @@ function buildOpenCliDocument() {
               }
             ]
           },
+          {
+            name: "earnings-calendar",
+            description: "Fetch stored upcoming earnings calendar events over a date window, optionally filtered to one ticker or a small ticker batch.",
+            options: [
+              {
+                name: "ticker",
+                arguments: [{ name: "ticker", required: true, description: "Ticker symbol." }],
+                description: "Optional single ticker filter."
+              },
+              {
+                name: "tickers",
+                arguments: [
+                  {
+                    name: "tickers",
+                    required: true,
+                    description: "Comma-separated ticker symbols, max 10."
+                  }
+                ],
+                description: "Optional ticker batch filter instead of --ticker."
+              },
+              {
+                name: "start-date",
+                arguments: [
+                  { name: "date", required: true, description: "Inclusive lower bound." }
+                ],
+                description: "Optional inclusive event-date lower bound. Defaults to today."
+              },
+              {
+                name: "end-date",
+                arguments: [
+                  { name: "date", required: true, description: "Inclusive upper bound." }
+                ],
+                description: "Optional inclusive event-date upper bound. Defaults to start date + 14 days."
+              },
+              {
+                name: "limit",
+                arguments: [{ name: "limit", required: true, description: "Positive integer." }],
+                description: "Maximum number of events to return."
+              }
+            ]
+          },
           {
             name: "quarterly-highlights",
             description: "Fetch issuer-reported supplemental quarterly highlights from the linked SEC Exhibit 99.1 release for supported companies.",
@@ -1354,13 +1522,85 @@ function buildOpenCliDocument() {
           },
           {
             name: "snapshot",
-            description: "Fetch the latest daily price snapshot for a single ticker.",
+            description: "Fetch the latest daily price snapshot for one ticker or a small ticker batch.",
+            options: [
+              {
+                name: "ticker",
+                arguments: [{ name: "ticker", required: true, description: "Ticker symbol." }],
+                description: "Single ticker to fetch."
+              },
+              {
+                name: "tickers",
+                arguments: [
+                  {
+                    name: "tickers",
+                    required: true,
+                    description: "Comma-separated ticker symbols, max 10."
+                  }
+                ],
+                description: "Ticker batch to fetch instead of --ticker."
+              }
+            ]
+          },
+          {
+            name: "dividends",
+            description: "Fetch stored dividend ex-date rows for a single ticker.",
             options: [
               {
                 name: "ticker",
                 required: true,
                 arguments: [{ name: "ticker", required: true, description: "Ticker symbol." }],
                 description: "Ticker to fetch."
+              },
+              {
+                name: "start-date",
+                arguments: [
+                  { name: "date", required: true, description: "Inclusive lower bound." }
+                ],
+                description: "Optional inclusive ex-date lower bound."
+              },
+              {
+                name: "end-date",
+                arguments: [
+                  { name: "date", required: true, description: "Inclusive upper bound." }
+                ],
+                description: "Optional inclusive ex-date upper bound."
+              },
+              {
+                name: "limit",
+                arguments: [{ name: "limit", required: true, description: "Positive integer." }],
+                description: "Maximum number of dividend rows to return."
+              }
+            ]
+          },
+          {
+            name: "splits",
+            description: "Fetch stored stock-split rows for a single ticker.",
+            options: [
+              {
+                name: "ticker",
+                required: true,
+                arguments: [{ name: "ticker", required: true, description: "Ticker symbol." }],
+                description: "Ticker to fetch."
+              },
+              {
+                name: "start-date",
+                arguments: [
+                  { name: "date", required: true, description: "Inclusive lower bound." }
+                ],
+                description: "Optional inclusive split-date lower bound."
+              },
+              {
+                name: "end-date",
+                arguments: [
+                  { name: "date", required: true, description: "Inclusive upper bound." }
+                ],
+                description: "Optional inclusive split-date upper bound."
+              },
+              {
+                name: "limit",
+                arguments: [{ name: "limit", required: true, description: "Positive integer." }],
+                description: "Maximum number of split rows to return."
               }
             ]
           },
@@ -1675,6 +1915,19 @@ var QUERY_SUBCOMMAND_HELP = {
     ],
     "tn-financial-data query available-tickers"
   ),
+  "resolve-ticker": renderHelp(
+    "resolve-ticker",
+    [
+      "Resolve a company keyword or exact symbol against the supported ticker universe without silently swapping share classes."
+    ],
+    [
+      "--query <text>    Required. Company name, brand, prompt fragment, or ticker text.",
+      "--query <text>    Repeat to resolve multiple inputs in one request.",
+      "--api-key <key>   API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>  API base URL override."
+    ],
+    'tn-financial-data query resolve-ticker --query "google" --query "meta" --query "nvda"'
+  ),
   company: renderHelp(
     "company",
     ["Fetch the basic company identity record for a single ticker."],
@@ -1766,14 +2019,17 @@ var QUERY_SUBCOMMAND_HELP = {
   ),
   "financial-metrics-snapshot": renderHelp(
     "financial-metrics-snapshot",
-    ["Fetch the latest metrics bundle, price snapshot, and key statistics for one ticker."],
     [
-      "--ticker <symbol> Required. Stock ticker symbol.",
-      "--period <period> annual | quarterly | ttm. Default: annual.",
-      "--api-key <key>   API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
-      "--base-url <url>  API base URL override."
+      "Fetch the latest metrics bundle, price snapshot, and key statistics for one ticker or a small ticker batch."
+    ],
+    [
+      "--ticker <symbol>  Exact stock ticker symbol.",
+      "--tickers <csv>    Comma-separated ticker batch. Use instead of --ticker.",
+      "--period <period>  annual | quarterly | ttm. Default: annual.",
+      "--api-key <key>    API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>   API base URL override."
     ],
-    "tn-financial-data query financial-metrics-snapshot --ticker AAPL --period quarterly"
+    "tn-financial-data query financial-metrics-snapshot --tickers AAPL,MSFT,NVDA --period quarterly"
   ),
   earnings: renderHelp(
     "earnings",
@@ -1792,6 +2048,22 @@ var QUERY_SUBCOMMAND_HELP = {
     ],
     "tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8"
   ),
+  "earnings-calendar": renderHelp(
+    "earnings-calendar",
+    [
+      "Fetch stored upcoming earnings calendar events over a date window, optionally filtered to one ticker or a small ticker batch."
+    ],
+    [
+      "--ticker <symbol>      Optional single ticker filter.",
+      "--tickers <csv>        Optional comma-separated ticker batch filter. Use instead of --ticker.",
+      "--start-date <date>    Optional inclusive start date (YYYY-MM-DD). Default: today.",
+      "--end-date <date>      Optional inclusive end date (YYYY-MM-DD). Default: start date + 14 days.",
+      "--limit <n>            Maximum number of events to return.",
+      "--api-key <key>        API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>       API base URL override."
+    ],
+    "tn-financial-data query earnings-calendar --tickers AAPL,MSFT --start-date 2026-04-02 --end-date 2026-04-16"
+  ),
   "quarterly-highlights": renderHelp(
     "quarterly-highlights",
     [
@@ -1830,13 +2102,40 @@ var QUERY_SUBCOMMAND_HELP = {
   ),
   snapshot: renderHelp(
     "snapshot",
-    ["Fetch the latest price snapshot for a single ticker."],
+    ["Fetch the latest daily price snapshot for one ticker or a small ticker batch."],
     [
-      "--ticker <symbol> Required. Stock ticker symbol.",
-      "--api-key <key>   API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
-      "--base-url <url>  API base URL override."
+      "--ticker <symbol>  Exact stock ticker symbol.",
+      "--tickers <csv>    Comma-separated ticker batch. Use instead of --ticker.",
+      "--api-key <key>    API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>   API base URL override."
+    ],
+    "tn-financial-data query snapshot --tickers AAPL,MSFT,NVDA"
+  ),
+  dividends: renderHelp(
+    "dividends",
+    ["Fetch stored dividend ex-date rows for a single ticker."],
+    [
+      "--ticker <symbol>   Required. Stock ticker symbol.",
+      "--start-date <date> Optional start date (YYYY-MM-DD).",
+      "--end-date <date>   Optional end date (YYYY-MM-DD).",
+      "--limit <n>         Number of dividend rows to return.",
+      "--api-key <key>     API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>    API base URL override."
     ],
-    "tn-financial-data query snapshot --ticker AAPL"
+    "tn-financial-data query dividends --ticker AAPL --limit 20"
+  ),
+  splits: renderHelp(
+    "splits",
+    ["Fetch stored stock-split rows for a single ticker."],
+    [
+      "--ticker <symbol>   Required. Stock ticker symbol.",
+      "--start-date <date> Optional start date (YYYY-MM-DD).",
+      "--end-date <date>   Optional end date (YYYY-MM-DD).",
+      "--limit <n>         Number of split rows to return.",
+      "--api-key <key>     API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>    API base URL override."
+    ],
+    "tn-financial-data query splits --ticker AAPL --limit 20"
   ),
   news: renderHelp(
     "news",
@@ -2049,6 +2348,90 @@ function buildFinancialCliOptions(parsed, statement) {
   if (reportPeriodLt) options.reportPeriodLt = reportPeriodLt;
   return options;
 }
+function parseTickerSelection(parsed) {
+  const ticker = getOption(parsed, "ticker");
+  const tickersValue = getOption(parsed, "tickers");
+  if (ticker && tickersValue) {
+    throw new CliUsageError("Use either --ticker or --tickers, not both.");
+  }
+  if (ticker) {
+    return {
+      kind: "single",
+      ticker
+    };
+  }
+  if (tickersValue) {
+    const tickers = parseCsvValues(tickersValue, "tickers");
+    if (tickers.length > 10) {
+      throw new CliUsageError("--tickers must contain between 1 and 10 values.");
+    }
+    return {
+      kind: "batch",
+      tickers
+    };
+  }
+  throw new CliUsageError("Missing required option --ticker or --tickers.");
+}
+function parseQuerySelection(parsed) {
+  const rawQueries = getOptions(parsed, "query");
+  if (rawQueries.length === 0) {
+    throw new CliUsageError("Missing required option --query.");
+  }
+  if (rawQueries.some((value) => value === "true")) {
+    throw new CliUsageError("Missing required value for --query.");
+  }
+  const queries = [...new Set(rawQueries.map((value) => value.trim()))].filter(
+    (value) => value.length > 0
+  );
+  if (queries.length === 0) {
+    throw new CliUsageError("Missing required option --query.");
+  }
+  if (queries.length > 10) {
+    throw new CliUsageError("--query may be provided at most 10 times.");
+  }
+  return queries.length === 1 ? {
+    kind: "single",
+    query: queries[0]
+  } : {
+    kind: "batch",
+    queries
+  };
+}
+function buildCorporateActionsCliOptions(parsed) {
+  const options = {
+    startDate: getOption(parsed, "start-date"),
+    endDate: getOption(parsed, "end-date")
+  };
+  const limit = getOption(parsed, "limit");
+  if (limit) {
+    options.limit = parsePositiveInt(limit, "limit");
+  }
+  return options;
+}
+function buildEarningsCalendarCliOptions(parsed) {
+  const ticker = getOption(parsed, "ticker");
+  const tickersValue = getOption(parsed, "tickers");
+  if (ticker && tickersValue) {
+    throw new CliUsageError("Use either --ticker or --tickers, not both.");
+  }
+  const options = {
+    ticker,
+    startDate: getOption(parsed, "start-date"),
+    endDate: getOption(parsed, "end-date")
+  };
+  if (tickersValue) {
+    const tickers = parseCsvValues(tickersValue, "tickers");
+    if (tickers.length > 10) {
+      throw new CliUsageError("--tickers must contain between 1 and 10 values.");
+    }
+    options.tickers = tickers;
+  }
+  const limit = getOption(parsed, "limit");
+  if (limit) {
+    options.limit = parsePositiveInt(limit, "limit");
+  }
+  return options;
+}
 async function handleQuery(parsed, runtime, deps) {
   const resource = parsed.positionals[1];
   if (!resource) {
@@ -2064,6 +2447,14 @@ async function handleQuery(parsed, runtime, deps) {
     case "available-tickers":
       printJson(runtime, await client.getAvailableTickers());
       return 0;
+    case "resolve-ticker": {
+      const querySelection = parseQuerySelection(parsed);
+      printJson(
+        runtime,
+        querySelection.kind === "single" ? await client.resolveTicker(querySelection.query) : await client.resolveTickers(querySelection.queries)
+      );
+      return 0;
+    }
     case "company": {
       const ticker = requireOption(parsed, "ticker");
       printJson(runtime, await client.getCompanyFacts(ticker));
@@ -2176,16 +2567,14 @@ async function handleQuery(parsed, runtime, deps) {
       return 0;
     }
     case "financial-metrics-snapshot": {
-      const ticker = requireOption(parsed, "ticker");
+      const tickerSelection = parseTickerSelection(parsed);
       const period = getOption(parsed, "period");
+      const options = period ? {
+        period: assertAcceptedValue(period, "period", FINANCIAL_PERIODS)
+      } : void 0;
       printJson(
         runtime,
-        await client.getFinancialMetricsSnapshot(
-          ticker,
-          period ? {
-            period: assertAcceptedValue(period, "period", FINANCIAL_PERIODS)
-          } : void 0
-        )
+        tickerSelection.kind === "single" ? await client.getFinancialMetricsSnapshot(tickerSelection.ticker, options) : await client.getBatchFinancialMetricsSnapshots(tickerSelection.tickers, options)
       );
       return 0;
     }
@@ -2217,6 +2606,10 @@ async function handleQuery(parsed, runtime, deps) {
       printJson(runtime, await client.getEarnings(ticker, options));
       return 0;
     }
+    case "earnings-calendar": {
+      printJson(runtime, await client.getEarningsCalendar(buildEarningsCalendarCliOptions(parsed)));
+      return 0;
+    }
     case "quarterly-highlights": {
       const ticker = requireOption(parsed, "ticker");
       const options = {};
@@ -2250,8 +2643,24 @@ async function handleQuery(parsed, runtime, deps) {
       return 0;
     }
     case "snapshot": {
+      const tickerSelection = parseTickerSelection(parsed);
+      printJson(
+        runtime,
+        tickerSelection.kind === "single" ? await client.getPriceSnapshot(tickerSelection.ticker) : await client.getBatchPriceSnapshots(tickerSelection.tickers)
+      );
+      return 0;
+    }
+    case "dividends": {
+      const ticker = requireOption(parsed, "ticker");
+      printJson(
+        runtime,
+        await client.getDividends(ticker, buildCorporateActionsCliOptions(parsed))
+      );
+      return 0;
+    }
+    case "splits": {
       const ticker = requireOption(parsed, "ticker");
-      printJson(runtime, await client.getPriceSnapshot(ticker));
+      printJson(runtime, await client.getSplits(ticker, buildCorporateActionsCliOptions(parsed)));
       return 0;
     }
     case "news": {

package/dist/client/index.d.ts

@@ -156,6 +156,20 @@ interface PriceData {
     close: number;
     volume: number;
 }
+interface DividendEventData {
+    ticker: string;
+    exDate: string;
+    amount: number;
+    refreshedAt: string;
+}
+interface SplitEventData {
+    ticker: string;
+    exDate: string;
+    numerator: number;
+    denominator: number;
+    splitRatio: string;
+    refreshedAt: string;
+}
 interface CompanyFactsData {
     ticker: string;
     name: string;
@@ -208,6 +222,20 @@ interface KeyStatisticsData {
     shortPercentOfFloat: number | null;
     refreshedAt: string;
 }
+interface EarningsCalendarEventData {
+    ticker: string;
+    source: string;
+    eventDateStart: string;
+    eventDateEnd: string | null;
+    sourceUrl: string | null;
+    epsEstimateAvg: number | null;
+    epsEstimateLow: number | null;
+    epsEstimateHigh: number | null;
+    revenueEstimateAvg: number | null;
+    revenueEstimateLow: number | null;
+    revenueEstimateHigh: number | null;
+    refreshedAt: string;
+}
 interface AnalystEstimateData {
     ticker: string;
     periodLabel: string;
@@ -270,6 +298,8 @@ type CashFlowStatement = SnakeCasedProperties<CashFlowData>;
 type PriceBar = Omit<SnakeCasedProperties<PriceData>, "ticker">;
 type CompanyFacts = SnakeCasedProperties<CompanyFactsData>;
 type KeyStatistics = SnakeCasedProperties<KeyStatisticsData>;
+type DividendEvent = Omit<SnakeCasedProperties<DividendEventData>, "ticker">;
+type SplitEvent = Omit<SnakeCasedProperties<SplitEventData>, "ticker">;
 type DataAvailability = "ready" | "no_data";
 type ConsensusSurprise = "BEAT" | "MISS" | "MEET";
 interface FinancialMetricData {
@@ -393,6 +423,11 @@ interface NewsOpts {
     endDate?: string;
     publisher?: string;
 }
+interface CorporateActionsOpts {
+    limit?: number;
+    startDate?: string;
+    endDate?: string;
+}
 interface InsiderTradesOpts {
     limit?: number;
     startDate?: string;
@@ -422,6 +457,13 @@ interface FinancialMetricsOpts extends OptionalFinancialQueryOpts {
 }
 interface EarningsOpts extends OptionalFinancialQueryOpts {
 }
+interface EarningsCalendarOpts {
+    ticker?: string;
+    tickers?: readonly string[];
+    startDate?: string;
+    endDate?: string;
+    limit?: number;
+}
 interface QuarterlyHighlightsOpts {
     reportPeriod?: string;
 }
@@ -481,6 +523,20 @@ interface EarningsResponse extends ReadMetadata {
     period: FinancialPeriod;
     earnings: EarningsRow[];
 }
+interface EarningsCalendarEvent extends SnakeCasedProperties<Omit<EarningsCalendarEventData, "refreshedAt">> {
+    name: string;
+    refreshed_at: string;
+}
+interface EarningsCalendarResponse {
+    availability: DataAvailability;
+    as_of: string | null;
+    count: number;
+    limit: number;
+    start_date: string;
+    end_date: string;
+    requested_tickers?: string[];
+    events: EarningsCalendarEvent[];
+}
 interface KeyStatisticsResponse {
     ticker: string;
     availability: DataAvailability;
@@ -498,6 +554,60 @@ interface AvailableTickersResponse {
     as_of: string | null;
     tickers: AvailableTicker[];
 }
+type TickerResolutionStatus = "exact_supported" | "resolved" | "ambiguous" | "exact_unsupported" | "none";
+type TickerResolutionIntent = "ticker" | "keyword";
+type TickerResolutionMatchKind = "ticker_exact" | "ticker_format" | "alias_exact" | "company_name" | "company_prefix" | "company_tokens";
+type TickerResolutionRelationship = "supported" | "format_alias" | "brand_alias" | "deprecated_symbol" | "same_issuer_other_share_class";
+type TickerResolutionConfidence = "high" | "medium" | "low";
+interface TickerResolutionCandidate {
+    ticker: string;
+    name: string;
+    financials_updated_at: string | null;
+    news_updated_at: string | null;
+    updated_at: string;
+    match_kind: TickerResolutionMatchKind;
+    relationship: TickerResolutionRelationship;
+    confidence: TickerResolutionConfidence;
+    matched_alias: string | null;
+}
+interface TickerResolutionResponse {
+    query: string;
+    normalized_query: string;
+    intent: TickerResolutionIntent;
+    as_of: string | null;
+    extracted_query?: string;
+    status: TickerResolutionStatus;
+    resolved_ticker: string | null;
+    resolved_name: string | null;
+    candidates: TickerResolutionCandidate[];
+}
+interface BatchNotFoundEntry {
+    status: "not_found";
+    ticker: string;
+    error: string;
+    details?: {
+        ticker_resolution?: TickerResolutionResponse;
+    };
+}
+type BatchPriceSnapshotEntry = ({
+    status: "ok";
+} & PriceSnapshotResponse) | BatchNotFoundEntry;
+interface BatchPriceSnapshotsResponse {
+    requested_tickers: string[];
+    results: Record<string, BatchPriceSnapshotEntry>;
+}
+type BatchFinancialMetricsSnapshotEntry = ({
+    status: "ok";
+} & FinancialMetricsSnapshotResponse) | BatchNotFoundEntry;
+interface BatchFinancialMetricsSnapshotsResponse {
+    period: FinancialPeriod;
+    requested_tickers: string[];
+    results: Record<string, BatchFinancialMetricsSnapshotEntry>;
+}
+interface BatchTickerResolutionResponse {
+    queries: string[];
+    results: Record<string, TickerResolutionResponse>;
+}
 interface PriceHistoryResponse extends ReadMetadata {
     interval: PriceInterval;
     prices: PriceBar[];
@@ -505,6 +615,16 @@ interface PriceHistoryResponse extends ReadMetadata {
 interface NewsResponse extends ReadMetadata {
     news: NewsArticle[];
 }
+interface DividendsResponse extends ReadMetadata {
+    count: number;
+    limit: number;
+    dividends: DividendEvent[];
+}
+interface SplitsResponse extends ReadMetadata {
+    count: number;
+    limit: number;
+    splits: SplitEvent[];
+}
 interface InsiderTrade {
     filing_accession: string;
     filing_date: string;
@@ -797,9 +917,13 @@ declare class TnFinancialData {
     private buildFinancialParams;
     private buildGeneralOverviewParams;
     private buildOptionalFinancialParams;
+    private buildTickerBatchParams;
+    private buildRepeatedQueryParams;
     private buildSegmentedRevenueParams;
     private buildQuarterlyHighlightsParams;
+    private buildEarningsCalendarParams;
     private buildInsiderTradeParams;
+    private buildCorporateActionsParams;
     private buildFilingsParams;
     private buildFilingItemsParams;
     getIncomeStatements(ticker: string, opts: FinancialOpts): Promise<ApiResponse<IncomeStatementsResponse>>;
@@ -808,13 +932,20 @@ declare class TnFinancialData {
     getFinancials(ticker: string, opts: FinancialOpts): Promise<ApiResponse<FinancialsResponse>>;
     getFinancialMetrics(ticker: string, opts?: FinancialMetricsOpts): Promise<ApiResponse<FinancialMetricsResponse>>;
     getFinancialMetricsSnapshot(ticker: string, opts?: Pick<FinancialMetricsOpts, "period">): Promise<ApiResponse<FinancialMetricsSnapshotResponse>>;
+    getBatchFinancialMetricsSnapshots(tickers: readonly string[], opts?: Pick<FinancialMetricsOpts, "period">): Promise<ApiResponse<BatchFinancialMetricsSnapshotsResponse>>;
     getEarnings(ticker: string, opts?: EarningsOpts): Promise<ApiResponse<EarningsResponse>>;
+    getEarningsCalendar(opts?: EarningsCalendarOpts): Promise<ApiResponse<EarningsCalendarResponse>>;
     getGeneralOverview(ticker: string, opts?: GeneralOverviewOpts): Promise<ApiResponse<GeneralOverviewResponse>>;
     getKeyStatistics(ticker: string): Promise<ApiResponse<KeyStatisticsResponse>>;
     getAvailableTickers(): Promise<ApiResponse<AvailableTickersResponse>>;
+    resolveTicker(query: string): Promise<ApiResponse<TickerResolutionResponse>>;
+    resolveTickers(queries: readonly string[]): Promise<ApiResponse<BatchTickerResolutionResponse>>;
     getPrices(ticker: string, opts: PriceOpts): Promise<ApiResponse<PriceHistoryResponse>>;
     getPriceSnapshot(ticker: string): Promise<ApiResponse<PriceSnapshotResponse>>;
+    getBatchPriceSnapshots(tickers: readonly string[]): Promise<ApiResponse<BatchPriceSnapshotsResponse>>;
     getNews(ticker: string, opts?: NewsOpts): Promise<ApiResponse<NewsResponse>>;
+    getDividends(ticker: string, opts?: CorporateActionsOpts): Promise<ApiResponse<DividendsResponse>>;
+    getSplits(ticker: string, opts?: CorporateActionsOpts): Promise<ApiResponse<SplitsResponse>>;
     getInsiderTrades(ticker: string, opts?: InsiderTradesOpts): Promise<ApiResponse<InsiderTradesResponse>>;
     getFilings(ticker: string, opts?: FilingsOpts): Promise<ApiResponse<FilingsResponse>>;
     getFilingItems(ticker: string, opts: FilingItemsOpts): Promise<ApiResponse<FilingItemsResponse>>;
@@ -831,4 +962,4 @@ declare class TnFinancialData {
     screen(request: ScreenerRequest): Promise<ApiResponse<ScreenerResponse>>;
 }
 
-export { type AnalystEstimate, type AnalystEstimatesResponse, type AnalystPriceTarget, ApiError, type ApiResponse, type AvailableTicker, type AvailableTickersResponse, type BalanceSheet, type BalanceSheetsResponse, type CashFlowStatement, type CashFlowStatementsResponse, type ClientOptions, type CompanyFacts, type ConsensusSurprise, DEFAULT_API_BASE_URL, type DataAvailability, type EarningsOpts, type EarningsResponse, type EarningsRow, type FilingExhibit, type FilingItemSection, type FilingItemsOpts, type FilingItemsResponse, type FilingMetadata, type FilingsOpts, type FilingsResponse, type FinancialMetric, type FinancialMetricsOpts, type FinancialMetricsResponse, type FinancialMetricsSnapshotResponse, type FinancialOpts, type FinancialsResponse, type GeneralOverviewFinancials, type GeneralOverviewNews, type GeneralOverviewOpts, type GeneralOverviewPriceSnapshot, type GeneralOverviewResponse, type GlobalInterestRateObservation, type GlobalInterestRateSeries, type GlobalInterestRatesOpts, type GlobalInterestRatesResponse, type IncomeStatement, type IncomeStatementsResponse, type InsiderTrade, type InsiderTradesOpts, type InsiderTradesResponse, type InstitutionalOwnershipEntry, type InstitutionalOwnershipOpts, type InstitutionalOwnershipResponse, type InvestorPortfolioHolding, type InvestorPortfolioInvestor, type InvestorPortfolioOpts, type InvestorPortfolioResponse, type InvestorPortfolioSummary, type KeyStatistics, type KeyStatisticsResponse, type NewsArticle, type NewsOpts, type NewsResponse, type OptionalFinancialQueryOpts, type PriceBar, type PriceHistoryResponse, type PriceOpts, type PriceSnapshot, type PriceSnapshotResponse, type QuarterlyHighlightsMetric, type QuarterlyHighlightsOpts, type QuarterlyHighlightsPayload, type QuarterlyHighlightsResponse, type RateLimitAnnotatedResponse, type RateLimitInfo, type ReadMetadata, type ReportPeriodFilterOpts, type ScreenerFieldMetadata, type ScreenerFieldsResponse, type ScreenerRequest, type ScreenerResponse, type ScreenerResultRow, type SegmentedRevenueItem, type SegmentedRevenuePeriod, type SegmentedRevenuesOpts, type SegmentedRevenuesResponse, type SnakeCase, TnFinancialData };
+export { type AnalystEstimate, type AnalystEstimatesResponse, type AnalystPriceTarget, ApiError, type ApiResponse, type AvailableTicker, type AvailableTickersResponse, type BalanceSheet, type BalanceSheetsResponse, type BatchFinancialMetricsSnapshotEntry, type BatchFinancialMetricsSnapshotsResponse, type BatchNotFoundEntry, type BatchPriceSnapshotEntry, type BatchPriceSnapshotsResponse, type BatchTickerResolutionResponse, type CashFlowStatement, type CashFlowStatementsResponse, type ClientOptions, type CompanyFacts, type ConsensusSurprise, type CorporateActionsOpts, DEFAULT_API_BASE_URL, type DataAvailability, type DividendEvent, type DividendsResponse, type EarningsCalendarEvent, type EarningsCalendarOpts, type EarningsCalendarResponse, type EarningsOpts, type EarningsResponse, type EarningsRow, type FilingExhibit, type FilingItemSection, type FilingItemsOpts, type FilingItemsResponse, type FilingMetadata, type FilingsOpts, type FilingsResponse, type FinancialMetric, type FinancialMetricsOpts, type FinancialMetricsResponse, type FinancialMetricsSnapshotResponse, type FinancialOpts, type FinancialsResponse, type GeneralOverviewFinancials, type GeneralOverviewNews, type GeneralOverviewOpts, type GeneralOverviewPriceSnapshot, type GeneralOverviewResponse, type GlobalInterestRateObservation, type GlobalInterestRateSeries, type GlobalInterestRatesOpts, type GlobalInterestRatesResponse, type IncomeStatement, type IncomeStatementsResponse, type InsiderTrade, type InsiderTradesOpts, type InsiderTradesResponse, type InstitutionalOwnershipEntry, type InstitutionalOwnershipOpts, type InstitutionalOwnershipResponse, type InvestorPortfolioHolding, type InvestorPortfolioInvestor, type InvestorPortfolioOpts, type InvestorPortfolioResponse, type InvestorPortfolioSummary, type KeyStatistics, type KeyStatisticsResponse, type NewsArticle, type NewsOpts, type NewsResponse, type OptionalFinancialQueryOpts, type PriceBar, type PriceHistoryResponse, type PriceOpts, type PriceSnapshot, type PriceSnapshotResponse, type QuarterlyHighlightsMetric, type QuarterlyHighlightsOpts, type QuarterlyHighlightsPayload, type QuarterlyHighlightsResponse, type RateLimitAnnotatedResponse, type RateLimitInfo, type ReadMetadata, type ReportPeriodFilterOpts, type ScreenerFieldMetadata, type ScreenerFieldsResponse, type ScreenerRequest, type ScreenerResponse, type ScreenerResultRow, type SegmentedRevenueItem, type SegmentedRevenuePeriod, type SegmentedRevenuesOpts, type SegmentedRevenuesResponse, type SnakeCase, type SplitEvent, type SplitsResponse, type TickerResolutionCandidate, type TickerResolutionConfidence, type TickerResolutionIntent, type TickerResolutionMatchKind, type TickerResolutionRelationship, type TickerResolutionResponse, type TickerResolutionStatus, TnFinancialData };

package/dist/client/index.js

@@ -133,6 +133,26 @@ var TnFinancialData = class {
     this.appendReportPeriodParams(params, opts);
     return params.toString();
   }
+  buildTickerBatchParams(tickers, extra) {
+    const params = new URLSearchParams({
+      tickers: tickers.join(",")
+    });
+    if (extra) {
+      for (const [key, value] of Object.entries(extra)) {
+        if (value !== void 0) {
+          params.set(key, value);
+        }
+      }
+    }
+    return params.toString();
+  }
+  buildRepeatedQueryParams(key, values) {
+    const params = new URLSearchParams();
+    for (const value of values) {
+      params.append(key, value);
+    }
+    return params.toString();
+  }
   buildSegmentedRevenueParams(ticker, opts) {
     const params = new URLSearchParams({ ticker, period: opts.period });
     this.appendLimitParam(params, opts.limit);
@@ -145,6 +165,22 @@ var TnFinancialData = class {
     if (opts?.reportPeriod) params.set("report_period", opts.reportPeriod);
     return params.toString();
   }
+  buildEarningsCalendarParams(opts) {
+    const params = new URLSearchParams();
+    if (opts?.ticker && opts?.tickers && opts.tickers.length > 0) {
+      throw new Error("Use either ticker or tickers, not both.");
+    }
+    if (opts?.ticker) {
+      params.set("ticker", opts.ticker);
+    }
+    if (opts?.tickers && opts.tickers.length > 0) {
+      params.set("tickers", opts.tickers.join(","));
+    }
+    this.appendLimitParam(params, opts?.limit);
+    if (opts?.startDate) params.set("start_date", opts.startDate);
+    if (opts?.endDate) params.set("end_date", opts.endDate);
+    return params.toString();
+  }
   buildInsiderTradeParams(ticker, opts) {
     const params = new URLSearchParams({ ticker });
     this.appendLimitParam(params, opts?.limit);
@@ -157,6 +193,13 @@ var TnFinancialData = class {
     if (opts?.securityType) params.set("security_type", opts.securityType);
     return params.toString();
   }
+  buildCorporateActionsParams(ticker, opts) {
+    const params = new URLSearchParams({ ticker });
+    this.appendLimitParam(params, opts?.limit);
+    if (opts?.startDate) params.set("start_date", opts.startDate);
+    if (opts?.endDate) params.set("end_date", opts.endDate);
+    return params.toString();
+  }
   buildFilingsParams(ticker, opts) {
     const params = new URLSearchParams({ ticker });
     this.appendLimitParam(params, opts?.limit);
@@ -210,11 +253,24 @@ var TnFinancialData = class {
       `/financial-metrics/snapshot?${this.buildOptionalFinancialParams(ticker, opts)}`
     );
   }
+  async getBatchFinancialMetricsSnapshots(tickers, opts) {
+    return this.request(
+      `/financial-metrics/snapshot?${this.buildTickerBatchParams(tickers, {
+        period: opts?.period
+      })}`
+    );
+  }
   async getEarnings(ticker, opts) {
     return this.request(
       `/earnings?${this.buildOptionalFinancialParams(ticker, opts)}`
     );
   }
+  async getEarningsCalendar(opts) {
+    const params = this.buildEarningsCalendarParams(opts);
+    return this.request(
+      params.length > 0 ? `/earnings/calendar?${params}` : "/earnings/calendar"
+    );
+  }
   async getGeneralOverview(ticker, opts) {
     return this.request(
       `/general-overview?${this.buildGeneralOverviewParams(ticker, opts)}`
@@ -228,6 +284,16 @@ var TnFinancialData = class {
   async getAvailableTickers() {
     return this.request("/financials/income-statements/tickers");
   }
+  async resolveTicker(query) {
+    return this.request(
+      `/tickers/resolve?${new URLSearchParams({ q: query })}`
+    );
+  }
+  async resolveTickers(queries) {
+    return this.request(
+      `/tickers/resolve/batch?${this.buildRepeatedQueryParams("query", queries)}`
+    );
+  }
   async getPrices(ticker, opts) {
     const params = new URLSearchParams({
       ticker,
@@ -242,6 +308,11 @@ var TnFinancialData = class {
       `/prices/snapshot?${new URLSearchParams({ ticker })}`
     );
   }
+  async getBatchPriceSnapshots(tickers) {
+    return this.request(
+      `/prices/snapshot?${this.buildTickerBatchParams(tickers)}`
+    );
+  }
   async getNews(ticker, opts) {
     const params = new URLSearchParams({ ticker });
     if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
@@ -250,6 +321,16 @@ var TnFinancialData = class {
     if (opts?.publisher) params.set("publisher", opts.publisher);
     return this.request(`/news?${params}`);
   }
+  async getDividends(ticker, opts) {
+    return this.request(
+      `/corporate-actions/dividends?${this.buildCorporateActionsParams(ticker, opts)}`
+    );
+  }
+  async getSplits(ticker, opts) {
+    return this.request(
+      `/corporate-actions/splits?${this.buildCorporateActionsParams(ticker, opts)}`
+    );
+  }
   async getInsiderTrades(ticker, opts) {
     return this.request(
       `/insider-trades?${this.buildInsiderTradeParams(ticker, opts)}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tn-financial-data",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "Hosted US equity financial data and SEC filings CLI and client for agents",
   "keywords": [
     "agent",

package/skills/tn-financial-data/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tn-financial-data
-description: Use this skill first for covered US equity data questions and covered-universe screens. Query server-backed company facts, general overviews, financials, analyst estimates, segmented revenues, prices, news, insider trades, institutional ownership, investor 13F portfolios, raw SEC filings, and global interest rates through the tn-financial-data CLI.
+description: Use this skill first for covered US equity data questions and covered-universe screens. Query server-backed company facts, general overviews, financials, analyst estimates, segmented revenues, prices, corporate actions, news, insider trades, institutional ownership, investor 13F portfolios, raw SEC filings, and global interest rates through the tn-financial-data CLI.
 license: MIT
 ---
 
@@ -25,7 +25,7 @@ Covered reads include:
 - financial statements, derived financial metrics, earnings, and analyst estimates
 - quarterly highlights, including issuer-reported release metrics when available and generic latest-quarter summaries otherwise
 - segment and geographic revenue mix
-- price history, latest price snapshot, and stored company news
+- price history, latest price snapshot, stored dividends and splits, and stored company news
 - insider trades, issuer-level institutional ownership, and investor `13F` portfolios
 - SEC filing discovery plus bounded raw filing text for `10-K`, `10-Q`, and `8-K`
 - covered-universe screening and ranking
@@ -40,7 +40,10 @@ Covered reads include:
 - For raw SEC filing prompts, use `filings` to find the filing and accession number first, then use `filing-items` for specific sections or bounded raw text. Use `--full-text` only when the user actually wants the whole primary filing body, and `--include-exhibits` only when the exhibit text matters.
 - For covered-universe filter or ranking questions, use `screen-fields` and `screen`.
 - Keep issuer-centric ownership (`institutional-ownership`) separate from investor-centric portfolio lookup (`investor-portfolio`).
-- If the company mapping is ambiguous, use `available-tickers` before guessing a ticker.
+- If the company mapping is ambiguous or the prompt names a company without a trusted ticker, use `resolve-ticker` before guessing a ticker.
+- Use `available-tickers` when you need the full support snapshot or freshness timestamps for the covered ticker universe.
+- Treat an exact user-supplied ticker as exact. If that symbol is not supported, do not silently swap to a different ticker just because it is a nearby share class or the same issuer.
+- If only a different supported line exists for the issuer, call out that mismatch explicitly before using it. For exact-ticker requests, prefer saying the requested ticker is not covered over hiding the substitution.
 - Only leave this skill when the user explicitly wants outside sources or the stored dataset does not cover the question.
 
 ## Answer Principles
@@ -58,6 +61,8 @@ Covered reads include:
 These are the main commands an agent should reach for first. For full flags and examples, read [references/cli.md](references/cli.md).
 
 ```bash
+tn-financial-data query resolve-ticker --query google
+tn-financial-data query resolve-ticker --query google --query meta --query nvda
 tn-financial-data query available-tickers
 tn-financial-data query company --ticker AAPL
 tn-financial-data query general-overview --ticker AAPL
@@ -65,6 +70,7 @@ tn-financial-data query financials --ticker AAPL --period annual --statement all
 tn-financial-data query financial-metrics --ticker AAPL --period annual --limit 4
 tn-financial-data query financial-metrics-snapshot --ticker AAPL
 tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8
+tn-financial-data query earnings-calendar --tickers AAPL,MSFT --start-date 2026-04-02 --end-date 2026-04-16
 tn-financial-data query quarterly-highlights --ticker AAPL
 tn-financial-data query filings --ticker AAPL --filing-type 8-K --limit 10
 tn-financial-data query filing-items --ticker AAPL --accession-number 0000320193-26-000005 --item 2.02 --include-exhibits
@@ -72,6 +78,8 @@ tn-financial-data query analyst-estimates --ticker AAPL
 tn-financial-data query segmented-revenues --ticker AAPL --period annual --limit 4
 tn-financial-data query prices --ticker AAPL --interval day --start-date 2025-01-01 --end-date 2025-01-31
 tn-financial-data query snapshot --ticker AAPL
+tn-financial-data query dividends --ticker AAPL --limit 20
+tn-financial-data query splits --ticker AAPL --limit 20
 tn-financial-data query news --ticker AAPL --limit 20
 tn-financial-data query insider-trades --ticker AAPL --transaction-code P,S --limit 25
 tn-financial-data query institutional-ownership --ticker AAPL --limit 20
@@ -84,10 +92,13 @@ tn-financial-data query global-rates --series ecb_refi,boe_sonia --limit 10
 Practical defaults:
 
 - Use `general-overview` for broad one-ticker prompts like “what’s up with NVDA?”
+- Use `resolve-ticker` first when the user gives a company name, brand name, or broad one-company phrase without a trusted symbol
+- Repeat `--query` on `resolve-ticker` when the user gives multiple ambiguous company names and you need to normalize them before batch comparisons
+- Use `earnings-calendar` for upcoming date-window questions like “what earnings are coming up this week?” or “show me the next AAPL and MSFT earnings dates”
 - Use `quarterly-highlights` first for Apple product mix, Greater China, Meta ad KPIs, Amazon segment profitability, and Tesla services-and-other or free-cash-flow prompts
 - Use `filings` plus `filing-items` when the user explicitly asks for an SEC filing, `8-K`, `10-K`, `10-Q`, or raw filing text
 - Do not start Apple product-mix prompts with `segmented-revenues`; that surface only exposes broad `Product` and `Service` rollups, while `quarterly-highlights` carries the product-line fields the prompt usually wants
-- Use `financials`, `financial-metrics`, `earnings`, `analyst-estimates`, `segmented-revenues`, `news`, `prices`, or `snapshot` when the user asks for a specific slice
+- Use `financials`, `financial-metrics`, `earnings`, `analyst-estimates`, `segmented-revenues`, `prices`, `snapshot`, `dividends`, `splits`, or `news` when the user asks for a specific slice
 - Use `investor-portfolio` for prompts like “What does Vanguard hold?” or “Show Berkshire’s latest 13F portfolio.”
 - Use `global-rates` for central-bank and rate-comparison prompts
 

package/skills/tn-financial-data/agents/claude.md

@@ -5,4 +5,4 @@ Canonical instructions live in [../SKILL.md](../SKILL.md).
 
 Live reads require `TN_FINANCIAL_DATA_API_KEY` or `TN_FINANCIAL_DATA_API_KEYS` in the runtime environment.
 
-Use `tn-financial-data` before web search for covered US equity data, ownership, screening, global-rate questions, and raw SEC filing prompts. Start broad one-company prompts with the overview path. For narrower asks, choose the narrower covered read directly. Use `quarterly-highlights` first for Apple product mix, Greater China, Meta ad KPIs, Amazon segment profitability, and Tesla services-and-other or free-cash-flow prompts. Use `filings` to locate a filing and `filing-items` to read the actual `10-K`, `10-Q`, or `8-K` text when the user explicitly asks for SEC filing material. Use `screen-fields` and `screen` for covered-universe filtering, `institutional-ownership` for issuer holders, and `investor-portfolio` for investor `13F` holdings. Resolve ambiguous company names with `available-tickers` instead of guessing. Prefer synthesized, structured answers over raw dumps.
+Use `tn-financial-data` before web search for covered US equity data, ownership, screening, global-rate questions, and raw SEC filing prompts. Start broad one-company prompts with the overview path. For narrower asks, choose the narrower covered read directly. Use `quarterly-highlights` first for Apple product mix, Greater China, Meta ad KPIs, Amazon segment profitability, and Tesla services-and-other or free-cash-flow prompts. Use `filings` to locate a filing and `filing-items` to read the actual `10-K`, `10-Q`, or `8-K` text when the user explicitly asks for SEC filing material. Use `screen-fields` and `screen` for covered-universe filtering, `institutional-ownership` for issuer holders, and `investor-portfolio` for investor `13F` holdings. Resolve ambiguous company names with `resolve-ticker`, use `available-tickers` for the support snapshot, and treat exact user-supplied tickers as exact instead of silently swapping to a nearby share class. Prefer synthesized, structured answers over raw dumps.

package/skills/tn-financial-data/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "TN Financial Data"
   short_description: "Use this first for covered US equity data and screening questions"
-  default_prompt: "Use $tn-financial-data before web search for covered US equity data, ownership, screening, global-rate questions, and raw SEC filing requests. Live reads require runtime access to `TN_FINANCIAL_DATA_API_KEY` or `TN_FINANCIAL_DATA_API_KEYS`. Start broad one-company prompts with the overview path, choose narrower covered reads when the ask is specific, use `filings` plus `filing-items` for explicit `10-K`, `10-Q`, or `8-K` prompts, resolve ambiguous names with `available-tickers`, and keep answers synthesized, structured, and user-facing."
+  default_prompt: "Use $tn-financial-data before web search for covered US equity data, ownership, screening, global-rate questions, and raw SEC filing requests. Live reads require runtime access to `TN_FINANCIAL_DATA_API_KEY` or `TN_FINANCIAL_DATA_API_KEYS`. Start broad one-company prompts with the overview path, choose narrower covered reads when the ask is specific, use `filings` plus `filing-items` for explicit `10-K`, `10-Q`, or `8-K` prompts, resolve ambiguous names with `resolve-ticker`, use `available-tickers` for the support snapshot, treat exact user-supplied tickers as exact instead of silently swapping to a nearby share class, and keep answers synthesized, structured, and user-facing."
 
 policy:
   allow_implicit_invocation: true

package/skills/tn-financial-data/agents/opencode.md

@@ -5,7 +5,7 @@ Canonical instructions live in [../SKILL.md](../SKILL.md).
 
 Live reads require `TN_FINANCIAL_DATA_API_KEY` or `TN_FINANCIAL_DATA_API_KEYS` in the runtime environment.
 
-Prefer the `tn-financial-data` CLI over handwritten HTTP calls when it is installed. Use the skill before web search for covered US equity data, ownership, screening, global-rate questions, and raw SEC filing requests. For broad one-company prompts, start with the overview path. For narrower asks, choose the matching narrow read directly. Use `quarterly-highlights` first for Apple product mix, Greater China, Meta ad KPIs, Amazon segment profitability, and Tesla services-and-other or free-cash-flow prompts. Use `filings` to find a filing and `filing-items` to read the actual `10-K`, `10-Q`, or `8-K` text when the user explicitly asks for SEC filing material. Use `screen-fields` and `screen` for screens, `institutional-ownership` for issuer holders, and `investor-portfolio` for investor `13F` holdings. Resolve ambiguous company names with `available-tickers`, and keep answers structured, synthesized, and user-facing.
+Prefer the `tn-financial-data` CLI over handwritten HTTP calls when it is installed. Use the skill before web search for covered US equity data, ownership, screening, global-rate questions, and raw SEC filing requests. For broad one-company prompts, start with the overview path. For narrower asks, choose the matching narrow read directly. Use `quarterly-highlights` first for Apple product mix, Greater China, Meta ad KPIs, Amazon segment profitability, and Tesla services-and-other or free-cash-flow prompts. Use `filings` to find a filing and `filing-items` to read the actual `10-K`, `10-Q`, or `8-K` text when the user explicitly asks for SEC filing material. Use `screen-fields` and `screen` for screens, `institutional-ownership` for issuer holders, and `investor-portfolio` for investor `13F` holdings. Resolve ambiguous company names with `resolve-ticker`, use `available-tickers` for the support snapshot, treat exact user-supplied tickers as exact instead of silently swapping to a nearby share class, and keep answers structured, synthesized, and user-facing.
 
 Do not start Apple product-mix prompts with `segmented-revenues`; go straight to `tn-financial-data query quarterly-highlights --ticker AAPL` unless the user explicitly asks for XBRL segment tables.
 For prompts that ask for a table plus one short bullet, keep the bullet descriptive and grounded in the fetched fields. Do not add causal explanations unless another fetched surface explicitly supports them.

package/skills/tn-financial-data/references/cli.md

@@ -10,6 +10,7 @@ Auth rule:
 - the published package reads credentials from flags and ambient process env, not from project-local `.env`
 - if there is any doubt, pass `--api-key` and `--base-url` explicitly
 - throttling surfaces as a clean CLI error; raw HTTP callers should read `X-RateLimit-*` and `Retry-After`
+- for ambiguous company, brand, or free-form one-company prompts, start with `resolve-ticker`
 - for broad ticker prompts like "what's up with NVDA?", start with `general-overview`
 - for covered recent-news prompts like "show me recent Nvidia news", start with `news`
 - for latest-quarter product mix, supplemental KPIs, AWS segment profitability, or Tesla free-cash-flow prompts, start with `quarterly-highlights`
@@ -20,6 +21,23 @@ Auth rule:
 
 ## Query Commands
 
+Resolve ticker:
+
+```bash
+tn-financial-data query resolve-ticker --query google
+tn-financial-data query resolve-ticker --query GOOGL
+tn-financial-data query resolve-ticker --query google --query meta --query nvda
+```
+
+Use this to resolve a company keyword, brand name, prompt fragment, or exact symbol against the hosted supported universe.
+
+Resolution semantics:
+- returns one of `exact_supported`, `resolved`, `ambiguous`, `exact_unsupported`, or `none`
+- use this before guessing a ticker from a company or brand prompt
+- repeat `--query` when you need to normalize several ambiguous inputs before calling a batch snapshot read
+- `exact_unsupported` can suggest a nearby supported line, but that suggestion is a hint, not an automatic substitution
+- exact share-class mismatches must stay explicit to the user
+
 Available tickers:
 
 ```bash
@@ -28,6 +46,11 @@ tn-financial-data query available-tickers
 
 Use this to fetch the current supported ticker snapshot from the API. It returns ticker symbols plus the latest financial-data and news-data timestamps tracked in the database.
 
+Support rule:
+- treat this list as the package's authoritative support snapshot
+- if the user asks for an exact ticker that is not in this list, do not silently substitute another ticker or share class
+- if you intentionally continue with a different supported line for the same issuer, make that mismatch explicit to the user
+
 Company facts:
 
 ```bash
@@ -112,6 +135,19 @@ Meaning:
 - if no matching quarterly statement exists for a reported quarter, the row still appears but statement-derived fields can be `null`
 - do not use Yahoo key-statistics growth fields as a substitute for statement-line YoY when the question is about revenue, operating income, net income, or EPS
 
+Earnings calendar:
+
+```bash
+tn-financial-data query earnings-calendar --tickers AAPL,MSFT --start-date 2026-04-02 --end-date 2026-04-16
+tn-financial-data query earnings-calendar --ticker AAPL
+```
+
+Meaning:
+- upcoming date-window view over stored Yahoo-backed earnings calendar events
+- use it for prompts like “what earnings are coming up this week?” or “show me the next Apple and Microsoft earnings dates”
+- omit ticker filters to scan the whole covered universe
+- `event_date_start` is the earliest announced date and `event_date_end` is only present when Yahoo returns a date range
+
 Quarterly highlights:
 
 ```bash
@@ -186,6 +222,18 @@ Snapshot:
 tn-financial-data query snapshot --ticker AAPL
 ```
 
+Corporate actions:
+
+```bash
+tn-financial-data query dividends --ticker AAPL --limit 20
+tn-financial-data query splits --ticker AAPL --limit 20
+```
+
+Meaning:
+- use `dividends` for stored dividend ex-date rows and `splits` for stored stock-split rows
+- both support optional `--start-date`, `--end-date`, and `--limit`
+- use these when the user asks about payout timing, split history, or recent capital-return events that are already captured in the Yahoo price ingest
+
 News:
 
 ```bash