tn-financial-data 0.3.1 → 0.4.0

package/README.md

@@ -25,7 +25,7 @@ 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
+- Company facts, financials, prices, news, insider trades, ownership, earnings transcript structure, stored macro history, 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
 - Cross-ticker news search over article title, summary, and body text with ticker, provider, publisher, and date filters
@@ -33,6 +33,7 @@ This package is the hosted agent-facing surface only. The repo's website, local
 - Packaged skill bundle for Claude and OpenCode installs
 - Typed TypeScript client from the root package export
 - Stable production default at `https://api.truenorth-financial.ai/v1`
+- Stored macro endpoints for FRED-backed US rates and economic indicators, plus global central-bank rate history through `global-rates`, `us-rates`, and `us-economic-indicators`
 
 ## Installation
 
@@ -71,8 +72,11 @@ 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-transcripts --ticker AAPL --limit 4
 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 us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000
+tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120
 tn-financial-data query company --ticker AAPL
 tn-financial-data query news-search --query "tariff semiconductor" --ticker NVDA --limit 10
 tn-financial-data query filings --ticker AAPL --filing-type 8-K --limit 5
@@ -103,10 +107,13 @@ tn-financial-data query financial-metrics-snapshot --tickers AAPL,MSFT,NVDA --pe
 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-transcripts --ticker AAPL --limit 4
 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 us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000
+tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120
 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
@@ -202,6 +209,22 @@ const calendar = await client.getEarningsCalendar({
 
 console.log(calendar.events.map((row) => `${row.ticker}:${row.event_date_start}`));
 
+const transcripts = await client.getEarningsTranscripts({
+  ticker: "NVDA",
+  limit: 1,
+});
+
+console.log(transcripts.transcripts[0]?.quarter_label, transcripts.transcripts[0]?.question_count);
+
+const usRates = await client.getUsInterestRates({
+  series: ["us_treasury_10y", "fed_funds_rate"],
+  startDate: "2021-01-01",
+  endDate: "2026-04-01",
+  limit: 2000,
+});
+
+console.log(usRates.rates.map((row) => `${row.key}:${row.latest?.value}`));
+
 const filings = await client.getFilings("AAPL", {
   filingTypes: ["8-K"],
   limit: 3,

package/dist/cli.js

@@ -274,6 +274,12 @@ var TnFinancialData = class {
       `/earnings?${this.buildOptionalFinancialParams(ticker, opts)}`
     );
   }
+  async getEarningsTranscripts(ticker, opts) {
+    const params = new URLSearchParams({ ticker });
+    if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+    if (opts?.reportPeriod) params.set("report_period", opts.reportPeriod);
+    return this.request(`/earnings/transcripts?${params.toString()}`);
+  }
   async getEarningsCalendar(opts) {
     const params = this.buildEarningsCalendarParams(opts);
     return this.request(
@@ -369,12 +375,24 @@ var TnFinancialData = class {
     return this.request(`/institutional-ownership/investor?${params}`);
   }
   async getGlobalInterestRates(opts) {
+    const params = this.buildMacroSeriesParams(opts);
+    return this.request(`/macro/interest-rates/global?${params}`);
+  }
+  async getUsInterestRates(opts) {
+    const params = this.buildMacroSeriesParams(opts);
+    return this.request(`/macro/interest-rates/us?${params}`);
+  }
+  async getUsEconomicIndicators(opts) {
+    const params = this.buildMacroSeriesParams(opts);
+    return this.request(`/macro/economic-indicators/us?${params}`);
+  }
+  buildMacroSeriesParams(opts) {
     const params = new URLSearchParams();
     if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
     if (opts?.startDate) params.set("start_date", opts.startDate);
     if (opts?.endDate) params.set("end_date", opts.endDate);
     if (opts?.series && opts.series.length > 0) params.set("series", opts.series.join(","));
-    return this.request(`/macro/interest-rates/global?${params}`);
+    return params;
   }
   async getAnalystEstimates(ticker) {
     return this.request(
@@ -666,7 +684,7 @@ function rootHelp() {
     "tn-financial-data",
     "",
     "Usage:",
-    "  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|news-search|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-transcripts|earnings-calendar|quarterly-highlights|analyst-estimates|prices|snapshot|dividends|splits|news|news-search|insider-trades|institutional-ownership|investor-portfolio|global-rates|us-rates|us-economic-indicators|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",
@@ -684,6 +702,7 @@ function rootHelp() {
     "  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-transcripts --ticker AAPL --limit 4",
     "  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",
@@ -695,6 +714,8 @@ function rootHelp() {
     "  tn-financial-data query institutional-ownership --ticker AAPL --limit 20",
     "  tn-financial-data query investor-portfolio --investor vanguard --limit 20",
     "  tn-financial-data query global-rates --series ecb_refi,boe_sonia --limit 10",
+    "  tn-financial-data query us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000",
+    "  tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120",
     '  tn-financial-data query screen --filter "trailing_pe < 25" --filter "recommendation_key = buy" --limit 10',
     "  tn-financial-data skill install --tool opencode",
     "  tn-financial-data skill install --tool claude",
@@ -723,6 +744,7 @@ function queryHelp() {
     "  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> | --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-transcripts --ticker <symbol> [--limit <n>] [--report-period <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>]",
@@ -736,6 +758,8 @@ function queryHelp() {
     "  tn-financial-data query institutional-ownership --ticker <symbol> [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query investor-portfolio (--cik <cik> | --investor <alias>) [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query global-rates [--series <csv>] [--start-date <date>] [--end-date <date>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
+    "  tn-financial-data query us-rates [--series <csv>] [--start-date <date>] [--end-date <date>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
+    "  tn-financial-data query us-economic-indicators [--series <csv>] [--start-date <date>] [--end-date <date>] [--limit <n>] [--api-key <key>] [--base-url <url>]",
     "  tn-financial-data query segmented-revenues --ticker <symbol> --period <annual|quarterly|ttm> [--limit <n>] [--segment-type <type>] [--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 screen --filter "field operator value" [--filter "field operator value"] [--limit <n>] [--api-key <key>] [--base-url <url>]',
     "  tn-financial-data query screen-fields [--api-key <key>] [--base-url <url>]",
@@ -799,7 +823,7 @@ function buildOpenCliDocument() {
     info: {
       title: "tn-financial-data",
       summary: "Server-backed US equity financial data CLI for agents and operators.",
-      description: "Query company facts, SEC financial statements, issuer-centric ownership data, investor-centric SEC 13F portfolios, global central-bank rate series, and daily or hourly prices from the tn-financial-data API.",
+      description: "Query company facts, SEC financial statements, issuer-centric ownership data, investor-centric SEC 13F portfolios, global and US macro series, and daily or hourly prices from the tn-financial-data API.",
       version,
       license: {
         identifier: "MIT",
@@ -849,6 +873,7 @@ function buildOpenCliDocument() {
       "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-transcripts --ticker AAPL --limit 4",
       "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",
@@ -861,6 +886,8 @@ function buildOpenCliDocument() {
       "tn-financial-data query institutional-ownership --ticker AAPL --limit 20",
       "tn-financial-data query investor-portfolio --investor vanguard --limit 20",
       "tn-financial-data query global-rates --series ecb_refi,boe_sonia --limit 10",
+      "tn-financial-data query us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000",
+      "tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120",
       'tn-financial-data query screen --filter "trailing_pe < 25" --filter "recommendation_key = buy" --limit 10',
       "tn-financial-data skill install --tool opencode",
       "tn-financial-data skill install --tool claude",
@@ -1356,6 +1383,34 @@ function buildOpenCliDocument() {
               }
             ]
           },
+          {
+            name: "earnings-transcripts",
+            description: "Fetch normalized earnings call transcript metadata, participants, and speaker-turn structure for a single ticker.",
+            options: [
+              {
+                name: "ticker",
+                required: true,
+                arguments: [{ name: "ticker", required: true, description: "Ticker symbol." }],
+                description: "Ticker to fetch."
+              },
+              {
+                name: "limit",
+                arguments: [{ name: "limit", required: true, description: "Positive integer." }],
+                description: "Maximum number of transcript artifacts to return."
+              },
+              {
+                name: "report-period",
+                arguments: [
+                  {
+                    name: "date",
+                    required: true,
+                    description: "Exact linked reporting-period end date."
+                  }
+                ],
+                description: "Exact linked report-period filter."
+              }
+            ]
+          },
           {
             name: "quarterly-highlights",
             description: "Fetch issuer-reported supplemental quarterly highlights from the linked SEC Exhibit 99.1 release for supported companies.",
@@ -1540,6 +1595,79 @@ function buildOpenCliDocument() {
               }
             ]
           },
+          {
+            name: "us-rates",
+            description: "Fetch US Treasury and Fed funds series with historical observations.",
+            options: [
+              {
+                name: "series",
+                arguments: [
+                  {
+                    name: "series",
+                    required: true,
+                    acceptedValues: [
+                      "us_treasury_3m",
+                      "us_treasury_2y",
+                      "us_treasury_5y",
+                      "us_treasury_10y",
+                      "us_treasury_30y",
+                      "fed_funds_rate"
+                    ],
+                    description: "Comma-separated series key list."
+                  }
+                ],
+                description: "Comma-separated US rates series list. Defaults to all supported US rates."
+              },
+              {
+                name: "start-date",
+                arguments: [{ name: "date", required: true, description: "Window start date." }],
+                description: "Inclusive start date filter."
+              },
+              {
+                name: "end-date",
+                arguments: [{ name: "date", required: true, description: "Window end date." }],
+                description: "Inclusive end date filter."
+              },
+              {
+                name: "limit",
+                arguments: [{ name: "limit", required: true, description: "Positive integer." }],
+                description: "Maximum observations per series to return."
+              }
+            ]
+          },
+          {
+            name: "us-economic-indicators",
+            description: "Fetch US CPI, GDP, and unemployment series with historical observations.",
+            options: [
+              {
+                name: "series",
+                arguments: [
+                  {
+                    name: "series",
+                    required: true,
+                    acceptedValues: ["us_cpi", "us_gdp", "us_unemployment"],
+                    description: "Comma-separated series key list."
+                  }
+                ],
+                description: "Comma-separated US economic indicator series list. Defaults to all supported indicators."
+              },
+              {
+                name: "start-date",
+                arguments: [{ name: "date", required: true, description: "Window start date." }],
+                description: "Inclusive start date filter."
+              },
+              {
+                name: "end-date",
+                arguments: [{ name: "date", required: true, description: "Window end date." }],
+                description: "Inclusive end date filter."
+              },
+              {
+                name: "limit",
+                arguments: [{ name: "limit", required: true, description: "Positive integer." }],
+                description: "Maximum observations per series to return."
+              }
+            ]
+          },
           {
             name: "snapshot",
             description: "Fetch the latest daily price snapshot for one ticker or a small ticker batch.",
@@ -1940,6 +2068,20 @@ var GLOBAL_INTEREST_RATE_SERIES_KEYS = [
   "rba_3m",
   "snb_call_money"
 ];
+var US_INTEREST_RATE_SERIES_KEYS = [
+  "us_treasury_3m",
+  "us_treasury_2y",
+  "us_treasury_5y",
+  "us_treasury_10y",
+  "us_treasury_30y",
+  "fed_funds_rate"
+];
+var US_ECONOMIC_INDICATOR_SERIES_KEYS = ["us_cpi", "us_gdp", "us_unemployment"];
+var MACRO_SERIES_KEYS = [
+  ...GLOBAL_INTEREST_RATE_SERIES_KEYS,
+  ...US_INTEREST_RATE_SERIES_KEYS,
+  ...US_ECONOMIC_INDICATOR_SERIES_KEYS
+];
 
 // src/reference-data/global-rates-series.ts
 var GLOBAL_INTEREST_RATE_SERIES_ALIASES = {
@@ -1966,6 +2108,61 @@ function normalizeGlobalInterestRateSeriesKey(value) {
   return GLOBAL_INTEREST_RATE_SERIES_ALIASES[normalized] ?? null;
 }
 
+// src/reference-data/us-macro-series.ts
+var US_INTEREST_RATE_SERIES_ALIASES = {
+  "3m": "us_treasury_3m",
+  "3mo": "us_treasury_3m",
+  "3_month": "us_treasury_3m",
+  treasury_3m: "us_treasury_3m",
+  us_3m: "us_treasury_3m",
+  us_tbill_3m: "us_treasury_3m",
+  "2y": "us_treasury_2y",
+  treasury_2y: "us_treasury_2y",
+  us_2y: "us_treasury_2y",
+  "5y": "us_treasury_5y",
+  treasury_5y: "us_treasury_5y",
+  us_5y: "us_treasury_5y",
+  "10y": "us_treasury_10y",
+  treasury_10y: "us_treasury_10y",
+  us_10y: "us_treasury_10y",
+  "30y": "us_treasury_30y",
+  treasury_30y: "us_treasury_30y",
+  us_30y: "us_treasury_30y",
+  fed_funds: "fed_funds_rate",
+  fedfunds: "fed_funds_rate",
+  fedfundsrate: "fed_funds_rate",
+  ffr: "fed_funds_rate"
+};
+var US_ECONOMIC_INDICATOR_SERIES_ALIASES = {
+  cpi: "us_cpi",
+  gdp: "us_gdp",
+  unemployment: "us_unemployment",
+  unemployment_rate: "us_unemployment"
+};
+function canonicalizeSeriesKeyInput2(value) {
+  return value.trim().toLowerCase().replace(/[\s-]+/g, "_");
+}
+function normalizeUsInterestRateSeriesKey(value) {
+  const normalized = canonicalizeSeriesKeyInput2(value);
+  if (!normalized) {
+    return null;
+  }
+  if (US_INTEREST_RATE_SERIES_KEYS.includes(normalized)) {
+    return normalized;
+  }
+  return US_INTEREST_RATE_SERIES_ALIASES[normalized] ?? null;
+}
+function normalizeUsEconomicIndicatorSeriesKey(value) {
+  const normalized = canonicalizeSeriesKeyInput2(value);
+  if (!normalized) {
+    return null;
+  }
+  if (US_ECONOMIC_INDICATOR_SERIES_KEYS.includes(normalized)) {
+    return normalized;
+  }
+  return US_ECONOMIC_INDICATOR_SERIES_ALIASES[normalized] ?? null;
+}
+
 // src/cli/query-subcommand-help.ts
 function renderHelp(command, description, options, example) {
   return [
@@ -2123,6 +2320,20 @@ var QUERY_SUBCOMMAND_HELP = {
     ],
     "tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8"
   ),
+  "earnings-transcripts": renderHelp(
+    "earnings-transcripts",
+    [
+      "Fetch normalized earnings call transcript metadata, participants, and speaker-turn structure for a single ticker."
+    ],
+    [
+      "--ticker <symbol>      Required. Stock ticker symbol.",
+      "--limit <n>            Number of transcript artifacts to return.",
+      "--report-period <date> Exact linked report period (YYYY-MM-DD).",
+      "--api-key <key>        API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>       API base URL override."
+    ],
+    "tn-financial-data query earnings-transcripts --ticker AAPL --limit 4"
+  ),
   "earnings-calendar": renderHelp(
     "earnings-calendar",
     [
@@ -2284,7 +2495,7 @@ var QUERY_SUBCOMMAND_HELP = {
   ),
   "global-rates": renderHelp(
     "global-rates",
-    ["Fetch curated global policy and money-market rate series."],
+    ["Fetch stored global policy and money-market rate history from the hosted API."],
     [
       "--series <csv>     Optional comma-separated series keys.",
       "--start-date <date> Optional start date (YYYY-MM-DD).",
@@ -2295,6 +2506,32 @@ var QUERY_SUBCOMMAND_HELP = {
     ],
     "tn-financial-data query global-rates --series ecb_refi,boe_sonia --limit 10"
   ),
+  "us-rates": renderHelp(
+    "us-rates",
+    ["Fetch stored US Treasury and Fed funds history from the hosted API."],
+    [
+      "--series <csv>      Optional comma-separated US rates series keys.",
+      "--start-date <date> Optional start date (YYYY-MM-DD).",
+      "--end-date <date>   Optional end date (YYYY-MM-DD).",
+      "--limit <n>         Number of observations to return per series.",
+      "--api-key <key>     API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>    API base URL override."
+    ],
+    "tn-financial-data query us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000"
+  ),
+  "us-economic-indicators": renderHelp(
+    "us-economic-indicators",
+    ["Fetch stored US CPI, GDP, and unemployment history from the hosted API."],
+    [
+      "--series <csv>      Optional comma-separated US economic indicator keys.",
+      "--start-date <date> Optional start date (YYYY-MM-DD).",
+      "--end-date <date>   Optional end date (YYYY-MM-DD).",
+      "--limit <n>         Number of observations to return per series.",
+      "--api-key <key>     API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>    API base URL override."
+    ],
+    "tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120"
+  ),
   "segmented-revenues": renderHelp(
     "segmented-revenues",
     ["Fetch reported segment revenue rows for a single issuer."],
@@ -2524,6 +2761,17 @@ function buildEarningsCalendarCliOptions(parsed) {
   }
   return options;
 }
+function parseMacroSeriesSelection(value, acceptedValues, normalize) {
+  return value?.split(",").map((item) => item.trim()).filter((item) => item.length > 0).map((item) => {
+    const normalized = normalize(item);
+    if (!normalized) {
+      throw new CliUsageError(
+        `series must be a comma-separated list of: ${acceptedValues.join(", ")}.`
+      );
+    }
+    return normalized;
+  });
+}
 async function handleQuery(parsed, runtime, deps) {
   const resource = parsed.positionals[1];
   if (!resource) {
@@ -2702,6 +2950,20 @@ async function handleQuery(parsed, runtime, deps) {
       printJson(runtime, await client.getEarningsCalendar(buildEarningsCalendarCliOptions(parsed)));
       return 0;
     }
+    case "earnings-transcripts": {
+      const ticker = requireOption(parsed, "ticker");
+      const options = {};
+      const limit = getOption(parsed, "limit");
+      const reportPeriod = getOption(parsed, "report-period");
+      if (limit) {
+        options.limit = parsePositiveInt(limit, "limit");
+      }
+      if (reportPeriod) {
+        options.reportPeriod = reportPeriod;
+      }
+      printJson(runtime, await client.getEarningsTranscripts(ticker, options));
+      return 0;
+    }
     case "quarterly-highlights": {
       const ticker = requireOption(parsed, "ticker");
       const options = {};
@@ -2848,15 +3110,11 @@ async function handleQuery(parsed, runtime, deps) {
     }
     case "global-rates": {
       const limit = getOption(parsed, "limit");
-      const series = getOption(parsed, "series")?.split(",").map((value) => value.trim()).filter((value) => value.length > 0).map((value) => {
-        const normalized = normalizeGlobalInterestRateSeriesKey(value);
-        if (!normalized) {
-          throw new CliUsageError(
-            `series must be a comma-separated list of: ${GLOBAL_INTEREST_RATE_SERIES_KEYS.join(", ")}.`
-          );
-        }
-        return normalized;
-      });
+      const series = parseMacroSeriesSelection(
+        getOption(parsed, "series"),
+        GLOBAL_INTEREST_RATE_SERIES_KEYS,
+        normalizeGlobalInterestRateSeriesKey
+      );
       printJson(
         runtime,
         await client.getGlobalInterestRates({
@@ -2868,6 +3126,46 @@ async function handleQuery(parsed, runtime, deps) {
       );
       return 0;
     }
+    case "us-rates": {
+      const limit = getOption(parsed, "limit");
+      const series = parseMacroSeriesSelection(
+        getOption(parsed, "series"),
+        US_INTEREST_RATE_SERIES_KEYS,
+        normalizeUsInterestRateSeriesKey
+      );
+      const options = {
+        startDate: getOption(parsed, "start-date"),
+        endDate: getOption(parsed, "end-date")
+      };
+      if (limit) {
+        options.limit = parsePositiveInt(limit, "limit");
+      }
+      if (series && series.length > 0) {
+        options.series = series;
+      }
+      printJson(runtime, await client.getUsInterestRates(options));
+      return 0;
+    }
+    case "us-economic-indicators": {
+      const limit = getOption(parsed, "limit");
+      const series = parseMacroSeriesSelection(
+        getOption(parsed, "series"),
+        US_ECONOMIC_INDICATOR_SERIES_KEYS,
+        normalizeUsEconomicIndicatorSeriesKey
+      );
+      const options = {
+        startDate: getOption(parsed, "start-date"),
+        endDate: getOption(parsed, "end-date")
+      };
+      if (limit) {
+        options.limit = parsePositiveInt(limit, "limit");
+      }
+      if (series && series.length > 0) {
+        options.series = series;
+      }
+      printJson(runtime, await client.getUsEconomicIndicators(options));
+      return 0;
+    }
     case "segmented-revenues": {
       const ticker = requireOption(parsed, "ticker");
       const period = assertAcceptedValue(

package/dist/client/index.d.ts

@@ -35,6 +35,10 @@ interface ScreenerStringInFilter {
 type ScreenerFilter = ScreenerNumericFilter | ScreenerStringEqFilter | ScreenerStringInFilter;
 declare const GLOBAL_INTEREST_RATE_SERIES_KEYS: readonly ["ecb_refi", "ecb_deposit", "boj_call_money", "boe_sonia", "boc_call_money", "rba_3m", "snb_call_money"];
 type GlobalInterestRateSeriesKey = (typeof GLOBAL_INTEREST_RATE_SERIES_KEYS)[number];
+declare const US_INTEREST_RATE_SERIES_KEYS: readonly ["us_treasury_3m", "us_treasury_2y", "us_treasury_5y", "us_treasury_10y", "us_treasury_30y", "fed_funds_rate"];
+type UsInterestRateSeriesKey = (typeof US_INTEREST_RATE_SERIES_KEYS)[number];
+declare const US_ECONOMIC_INDICATOR_SERIES_KEYS: readonly ["us_cpi", "us_gdp", "us_unemployment"];
+type UsEconomicIndicatorSeriesKey = (typeof US_ECONOMIC_INDICATOR_SERIES_KEYS)[number];
 
 interface IncomeStatementData {
     ticker: string;
@@ -470,6 +474,10 @@ interface FinancialMetricsOpts extends OptionalFinancialQueryOpts {
 }
 interface EarningsOpts extends OptionalFinancialQueryOpts {
 }
+interface EarningsTranscriptsOpts {
+    limit?: number;
+    reportPeriod?: string;
+}
 interface EarningsCalendarOpts {
     ticker?: string;
     tickers?: readonly string[];
@@ -499,6 +507,18 @@ interface GlobalInterestRatesOpts {
     endDate?: string;
     series?: readonly GlobalInterestRateSeriesKey[];
 }
+interface UsInterestRatesOpts {
+    limit?: number;
+    startDate?: string;
+    endDate?: string;
+    series?: readonly UsInterestRateSeriesKey[];
+}
+interface UsEconomicIndicatorsOpts {
+    limit?: number;
+    startDate?: string;
+    endDate?: string;
+    series?: readonly UsEconomicIndicatorSeriesKey[];
+}
 interface IncomeStatementsResponse extends ReadMetadata {
     period: FinancialPeriod;
     income_statements: IncomeStatement[];
@@ -536,6 +556,33 @@ interface EarningsResponse extends ReadMetadata {
     period: FinancialPeriod;
     earnings: EarningsRow[];
 }
+interface EarningsTranscriptParticipant {
+    participant_index: number;
+    name: string;
+    title: string | null;
+    firm: string | null;
+    role: string;
+}
+interface EarningsTranscriptSpeakerTurn {
+    turn_index: number;
+    speaker: string;
+    role: string;
+}
+interface EarningsTranscript {
+    headline: string;
+    report_period: string | null;
+    quarter_label: string | null;
+    published_at: string | null;
+    call_date: string | null;
+    question_count: number;
+    total_speaker_turns: number;
+    qa_turn_start_index: number | null;
+    participants: EarningsTranscriptParticipant[];
+    speaker_turns: EarningsTranscriptSpeakerTurn[];
+}
+interface EarningsTranscriptsResponse extends ReadMetadata {
+    transcripts: EarningsTranscript[];
+}
 interface EarningsCalendarEvent extends SnakeCasedProperties<Omit<EarningsCalendarEventData, "refreshedAt">> {
     name: string;
     refreshed_at: string;
@@ -813,7 +860,7 @@ interface GlobalInterestRateSeries {
     label: string;
     region: string;
     country_code: string;
-    frequency: "daily" | "monthly";
+    frequency: "daily" | "monthly" | "quarterly";
     latest: GlobalInterestRateObservation | null;
     observations: GlobalInterestRateObservation[];
 }
@@ -823,6 +870,38 @@ interface GlobalInterestRatesResponse {
     as_of: string | null;
     rates: GlobalInterestRateSeries[];
 }
+interface UsInterestRateSeries {
+    key: UsInterestRateSeriesKey;
+    series_id: string;
+    label: string;
+    region: string;
+    country_code: string;
+    frequency: "daily" | "monthly" | "quarterly";
+    latest: GlobalInterestRateObservation | null;
+    observations: GlobalInterestRateObservation[];
+}
+interface UsInterestRatesResponse {
+    source: "fred";
+    availability: DataAvailability;
+    as_of: string | null;
+    rates: UsInterestRateSeries[];
+}
+interface UsEconomicIndicatorSeries {
+    key: UsEconomicIndicatorSeriesKey;
+    series_id: string;
+    label: string;
+    region: string;
+    country_code: string;
+    frequency: "daily" | "monthly" | "quarterly";
+    latest: GlobalInterestRateObservation | null;
+    observations: GlobalInterestRateObservation[];
+}
+interface UsEconomicIndicatorsResponse {
+    source: "fred";
+    availability: DataAvailability;
+    as_of: string | null;
+    indicators: UsEconomicIndicatorSeries[];
+}
 type AnalystEstimate = SnakeCasedProperties<Omit<AnalystEstimateData, "ticker">>;
 type AnalystPriceTarget = SnakeCasedProperties<AnalystPriceTargetData>;
 interface AnalystEstimatesResponse {
@@ -956,6 +1035,7 @@ declare class TnFinancialData {
     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>>;
+    getEarningsTranscripts(ticker: string, opts?: EarningsTranscriptsOpts): Promise<ApiResponse<EarningsTranscriptsResponse>>;
     getEarningsCalendar(opts?: EarningsCalendarOpts): Promise<ApiResponse<EarningsCalendarResponse>>;
     getGeneralOverview(ticker: string, opts?: GeneralOverviewOpts): Promise<ApiResponse<GeneralOverviewResponse>>;
     getKeyStatistics(ticker: string): Promise<ApiResponse<KeyStatisticsResponse>>;
@@ -975,6 +1055,9 @@ declare class TnFinancialData {
     getInstitutionalOwnership(ticker: string, opts?: InstitutionalOwnershipOpts): Promise<ApiResponse<InstitutionalOwnershipResponse>>;
     getInvestorPortfolio(opts: InvestorPortfolioOpts): Promise<ApiResponse<InvestorPortfolioResponse>>;
     getGlobalInterestRates(opts?: GlobalInterestRatesOpts): Promise<ApiResponse<GlobalInterestRatesResponse>>;
+    getUsInterestRates(opts?: UsInterestRatesOpts): Promise<ApiResponse<UsInterestRatesResponse>>;
+    getUsEconomicIndicators(opts?: UsEconomicIndicatorsOpts): Promise<ApiResponse<UsEconomicIndicatorsResponse>>;
+    private buildMacroSeriesParams;
     getAnalystEstimates(ticker: string): Promise<ApiResponse<AnalystEstimatesResponse>>;
     getCompanyFacts(ticker: string): Promise<ApiResponse<{
         company_facts: CompanyFacts;
@@ -985,4 +1068,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 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 NewsSearchArticle, type NewsSearchOpts, type NewsSearchResponse, 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 };
+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 EarningsTranscript, type EarningsTranscriptParticipant, type EarningsTranscriptSpeakerTurn, type EarningsTranscriptsOpts, type EarningsTranscriptsResponse, 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 NewsSearchArticle, type NewsSearchOpts, type NewsSearchResponse, 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, type UsEconomicIndicatorSeries, type UsEconomicIndicatorsOpts, type UsEconomicIndicatorsResponse, type UsInterestRateSeries, type UsInterestRatesOpts, type UsInterestRatesResponse };

package/dist/client/index.js

@@ -272,6 +272,12 @@ var TnFinancialData = class {
       `/earnings?${this.buildOptionalFinancialParams(ticker, opts)}`
     );
   }
+  async getEarningsTranscripts(ticker, opts) {
+    const params = new URLSearchParams({ ticker });
+    if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+    if (opts?.reportPeriod) params.set("report_period", opts.reportPeriod);
+    return this.request(`/earnings/transcripts?${params.toString()}`);
+  }
   async getEarningsCalendar(opts) {
     const params = this.buildEarningsCalendarParams(opts);
     return this.request(
@@ -367,12 +373,24 @@ var TnFinancialData = class {
     return this.request(`/institutional-ownership/investor?${params}`);
   }
   async getGlobalInterestRates(opts) {
+    const params = this.buildMacroSeriesParams(opts);
+    return this.request(`/macro/interest-rates/global?${params}`);
+  }
+  async getUsInterestRates(opts) {
+    const params = this.buildMacroSeriesParams(opts);
+    return this.request(`/macro/interest-rates/us?${params}`);
+  }
+  async getUsEconomicIndicators(opts) {
+    const params = this.buildMacroSeriesParams(opts);
+    return this.request(`/macro/economic-indicators/us?${params}`);
+  }
+  buildMacroSeriesParams(opts) {
     const params = new URLSearchParams();
     if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
     if (opts?.startDate) params.set("start_date", opts.startDate);
     if (opts?.endDate) params.set("end_date", opts.endDate);
     if (opts?.series && opts.series.length > 0) params.set("series", opts.series.join(","));
-    return this.request(`/macro/interest-rates/global?${params}`);
+    return params;
   }
   async getAnalystEstimates(ticker) {
     return this.request(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tn-financial-data",
-  "version": "0.3.1",
+  "version": "0.4.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, corporate actions, 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 or US macro series through the tn-financial-data CLI.
 license: MIT
 ---
 
@@ -29,7 +29,7 @@ Covered reads include:
 - 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
-- curated global central-bank and rate series
+- stored global central-bank history plus FRED-backed US macro history through the hosted `tn-financial-data` API
 
 ## Routing Principles
 
@@ -70,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-transcripts --ticker AAPL --limit 4
 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
@@ -87,6 +88,8 @@ tn-financial-data query investor-portfolio --investor vanguard --limit 20
 tn-financial-data query screen-fields
 tn-financial-data query screen --filter "trailing_pe < 25" --filter "recommendation_key = buy" --limit 10
 tn-financial-data query global-rates --series ecb_refi,boe_sonia --limit 10
+tn-financial-data query us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000
+tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120
 ```
 
 Practical defaults:
@@ -94,13 +97,15 @@ 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-transcripts` when the user wants call participants, speaker order, or analyst-question structure rather than transcript prose
 - 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`, `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
+- Use `global-rates` for central-bank and cross-country rate-comparison prompts
+- Use `us-rates` and `us-economic-indicators` for FRED-backed US macro history such as Treasury yields, Fed funds, CPI, GDP, and unemployment
 
 ## References
 

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

@@ -19,6 +19,7 @@ Auth rule:
 - for compare prompts, try to use matching command families and comparable periods across the names
 - for investor-filer prompts like "what does Vanguard hold?", start with `investor-portfolio`
 - for central-bank / global-rate comparisons, start with `global-rates`
+- for US Treasury, Fed, CPI, GDP, or unemployment prompts, start with `us-rates` or `us-economic-indicators`
 
 ## Query Commands
 
@@ -136,6 +137,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 transcripts:
+
+```bash
+tn-financial-data query earnings-transcripts --ticker AAPL --limit 4
+tn-financial-data query earnings-transcripts --ticker AAPL --report-period 2025-12-27
+```
+
+Meaning:
+- structured transcript metadata view over stored earnings transcript artifacts
+- returns `headline`, linked `report_period`, `quarter_label`, `published_at`, `call_date`, `question_count`, participant roster, and ordered `speaker_turns`
+- this surface intentionally excludes upstream source provenance fields such as source URL, parser version, and raw payload references
+- use it when the question is about who joined the call, how many analyst questions there were, or the speaking order rather than the full transcript prose
+
 Earnings calendar:
 
 ```bash
@@ -332,8 +346,33 @@ tn-financial-data query global-rates --series ecb_refi,boe_sonia --limit 10
 
 Meaning:
 - preferred first read for central-bank and global-rate prompts
+- reads stored macro history from the hosted API, including FRED-backed US series
 - natural-language mappings include ECB refi, ECB deposit, BOE Sonia, SNB call money, BOJ call money, BOC call money, and RBA 3M
 
+US rates:
+
+```bash
+tn-financial-data query us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000
+```
+
+Meaning:
+- preferred first read for US Treasury curve and Fed funds prompts
+- reads stored macro history from the hosted API, including FRED-backed US series
+- returns historical observations plus a `latest` point per series
+- natural-language aliases include `2y`, `5y`, `10y`, `30y`, and `fedfunds`
+
+US economic indicators:
+
+```bash
+tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120
+```
+
+Meaning:
+- preferred first read for US CPI, GDP, and unemployment prompts
+- reads stored macro history from the hosted API
+- raw series only: `us_cpi` is the CPI index level, not a computed YoY inflation transform
+- natural-language aliases include `cpi`, `gdp`, and `unemployment`
+
 Shared query options:
 - `--api-key`
 - `--base-url`