tn-financial-data 0.1.1 → 0.1.2

package/README.md

@@ -26,7 +26,7 @@ This package is the hosted agent-facing surface only. The repo's website, local
 ## Features
 
 - Company facts, financials, prices, news, insider trades, ownership, and global rates through one hosted API
-- Agent-friendly CLI with JSON output and self-description via `tn-financial-data describe opencli`
+- 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
 - Stable production default at `https://api.truenorth-financial.ai/v1`
@@ -135,6 +135,17 @@ tn-financial-data describe opencli
 Installing the skill bundle does not provision API access. Agents still need the same runtime credential for live reads.
 For OpenCode, that means the `opencode` process itself must see `TN_FINANCIAL_DATA_API_KEY` in its environment.
 
+## Rate Limits
+
+The hosted API returns standard rate-limit headers:
+
+- `X-RateLimit-Limit`
+- `X-RateLimit-Remaining`
+- `X-RateLimit-Reset`
+- `Retry-After` on `429`
+
+When the CLI is throttled, it prints a clean retry message instead of a stack trace.
+
 ## Agent Integration
 
 Agents only need two surfaces:
@@ -155,8 +166,9 @@ const client = new TnFinancialData({
   apiKey: process.env.TN_FINANCIAL_DATA_API_KEY!,
 });
 
-const company = await client.getCompanyFacts({ ticker: "AAPL" });
+const company = await client.getCompanyFacts("AAPL");
 console.log(company.company_facts.name);
+console.log(company._rateLimit);
 ```
 
 ## Package Scope

package/dist/cli.js

@@ -7,6 +7,43 @@ import { pathToFileURL } from "url";
 
 // src/client/index.ts
 var DEFAULT_API_BASE_URL = "https://api.truenorth-financial.ai/v1";
+function parseOptionalInt(value) {
+  if (!value) {
+    return null;
+  }
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function parseOptionalUnixTimestamp(value) {
+  const parsed = parseOptionalInt(value);
+  if (parsed === null) {
+    return null;
+  }
+  return new Date(parsed * 1e3).toISOString();
+}
+function parseRateLimitInfo(headers) {
+  const info = {
+    limit: parseOptionalInt(headers.get("X-RateLimit-Limit")),
+    remaining: parseOptionalInt(headers.get("X-RateLimit-Remaining")),
+    resetAt: parseOptionalUnixTimestamp(headers.get("X-RateLimit-Reset")),
+    retryAfterSeconds: parseOptionalInt(headers.get("Retry-After"))
+  };
+  return Object.values(info).some((value) => value !== null) ? info : null;
+}
+var ApiError = class extends Error {
+  status;
+  code;
+  body;
+  rateLimit;
+  constructor(options) {
+    super(`API error ${options.status}: ${options.message}`);
+    this.name = "ApiError";
+    this.status = options.status;
+    this.code = options.code;
+    this.body = options.body;
+    this.rateLimit = options.rateLimit;
+  }
+};
 var TnFinancialData = class {
   apiKey;
   baseUrl;
@@ -27,21 +64,44 @@ var TnFinancialData = class {
       headers
     });
     if (!res.ok) {
-      const errorMessage = await this.extractErrorMessage(res);
-      throw new Error(`API error ${res.status}: ${errorMessage}`);
+      const errorBody = await this.extractErrorBody(res);
+      throw new ApiError({
+        status: res.status,
+        code: errorBody.code,
+        message: errorBody.message,
+        body: errorBody.rawBody,
+        rateLimit: parseRateLimitInfo(res.headers)
+      });
     }
-    return res.json();
+    const payload = await res.json();
+    Object.defineProperty(payload, "_rateLimit", {
+      value: parseRateLimitInfo(res.headers),
+      enumerable: false,
+      configurable: true,
+      writable: false
+    });
+    return payload;
   }
-  async extractErrorMessage(res) {
+  async extractErrorBody(res) {
     const rawBody = await res.text().catch(() => "");
     const trimmed = rawBody.trim();
-    if (trimmed.length === 0) return "Unknown error";
+    if (trimmed.length === 0) {
+      return { message: "Unknown error", code: null, rawBody: "" };
+    }
     try {
       const parsed = JSON.parse(trimmed);
       const code = parsed.code ? `[${parsed.code}] ` : "";
-      return `${code}${parsed.error?.trim() || trimmed}`;
+      return {
+        message: `${code}${parsed.error?.trim() || trimmed}`,
+        code: parsed.code?.trim() || null,
+        rawBody: trimmed
+      };
     } catch {
-      return trimmed;
+      return {
+        message: trimmed,
+        code: null,
+        rawBody: trimmed
+      };
     }
   }
   appendLimitParam(params, limit) {
@@ -1124,6 +1184,273 @@ function buildOpenCliDocument() {
   };
 }
 
+// src/cli/query-subcommand-help.ts
+function renderHelp(command, description, options, example) {
+  return [
+    `tn-financial-data query ${command}`,
+    "",
+    ...description,
+    "",
+    "Options:",
+    ...options.map((line) => `  ${line}`),
+    "",
+    "Example:",
+    `  ${example}`
+  ].join("\n");
+}
+var QUERY_SUBCOMMAND_HELP = {
+  "available-tickers": renderHelp(
+    "available-tickers",
+    ["List tickers currently supported by the hosted read API."],
+    [
+      "--api-key <key>    API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>   API base URL override."
+    ],
+    "tn-financial-data query available-tickers"
+  ),
+  company: renderHelp(
+    "company",
+    ["Fetch the basic company identity record for a single ticker."],
+    [
+      "--ticker <symbol> Required. Stock ticker symbol.",
+      "--api-key <key>   API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>  API base URL override."
+    ],
+    "tn-financial-data query company --ticker AAPL"
+  ),
+  "general-overview": renderHelp(
+    "general-overview",
+    ["Fetch the bundled company, financials, price snapshot, and news overview for one ticker."],
+    [
+      "--ticker <symbol>       Required. Stock ticker symbol.",
+      "--period <period>       annual | quarterly | ttm. Default: annual.",
+      "--financial-limit <n>   Number of financial periods to return.",
+      "--news-limit <n>        Number of news items to return.",
+      "--api-key <key>         API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>        API base URL override."
+    ],
+    "tn-financial-data query general-overview --ticker AAPL --period quarterly --financial-limit 4 --news-limit 5"
+  ),
+  financials: renderHelp(
+    "financials",
+    [
+      "Fetch income statements, balance sheets, cash flow statements, or key statistics for a single ticker."
+    ],
+    [
+      "--ticker <symbol>          Required. Stock ticker symbol.",
+      "--period <period>          annual | quarterly | ttm. Required unless --statement key-stats.",
+      "--statement <type>         all | income | balance | cash-flow | key-stats. Default: all.",
+      "--limit <n>                Number of periods to return.",
+      "--report-period <date>     Exact report period (YYYY-MM-DD).",
+      "--report-period-gte <date> Report period >= date.",
+      "--report-period-lte <date> Report period <= date.",
+      "--report-period-gt <date>  Report period > date.",
+      "--report-period-lt <date>  Report period < date.",
+      "--api-key <key>            API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>           API base URL override."
+    ],
+    "tn-financial-data query financials --ticker AAPL --period annual --statement income --limit 4"
+  ),
+  "financial-metrics": renderHelp(
+    "financial-metrics",
+    ["Fetch derived profitability, leverage, liquidity, and growth metrics for a single ticker."],
+    [
+      "--ticker <symbol>          Required. Stock ticker symbol.",
+      "--period <period>          annual | quarterly | ttm. Default: annual.",
+      "--limit <n>                Number of periods to return.",
+      "--report-period <date>     Exact report period (YYYY-MM-DD).",
+      "--report-period-gte <date> Report period >= date.",
+      "--report-period-lte <date> Report period <= date.",
+      "--report-period-gt <date>  Report period > date.",
+      "--report-period-lt <date>  Report period < date.",
+      "--api-key <key>            API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>           API base URL override."
+    ],
+    "tn-financial-data query financial-metrics --ticker AAPL --period quarterly --limit 8"
+  ),
+  "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."
+    ],
+    "tn-financial-data query financial-metrics-snapshot --ticker AAPL --period quarterly"
+  ),
+  earnings: renderHelp(
+    "earnings",
+    ["Fetch reported earnings rows and consensus surprise fields for a single ticker."],
+    [
+      "--ticker <symbol>          Required. Stock ticker symbol.",
+      "--period <period>          annual | quarterly | ttm. Default: quarterly.",
+      "--limit <n>                Number of periods to return.",
+      "--report-period <date>     Exact report period (YYYY-MM-DD).",
+      "--report-period-gte <date> Report period >= date.",
+      "--report-period-lte <date> Report period <= date.",
+      "--report-period-gt <date>  Report period > date.",
+      "--report-period-lt <date>  Report period < date.",
+      "--api-key <key>            API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>           API base URL override."
+    ],
+    "tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8"
+  ),
+  "quarterly-highlights": renderHelp(
+    "quarterly-highlights",
+    [
+      "Fetch issuer-reported supplemental quarterly highlights such as segment mix and selected KPIs."
+    ],
+    [
+      "--ticker <symbol>      Required. Stock ticker symbol.",
+      "--report-period <date> Exact 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 quarterly-highlights --ticker AAPL"
+  ),
+  "analyst-estimates": renderHelp(
+    "analyst-estimates",
+    ["Fetch analyst EPS/revenue estimate rows and the current price-target snapshot for a ticker."],
+    [
+      "--ticker <symbol> Required. Stock ticker symbol.",
+      "--api-key <key>   API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>  API base URL override."
+    ],
+    "tn-financial-data query analyst-estimates --ticker AAPL"
+  ),
+  prices: renderHelp(
+    "prices",
+    ["Fetch historical price bars for a single ticker."],
+    [
+      "--ticker <symbol>    Required. Stock ticker symbol.",
+      "--interval <period>  day | 1h.",
+      "--start-date <date>  Required. Start date (YYYY-MM-DD).",
+      "--end-date <date>    Required. End date (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 prices --ticker AAPL --interval day --start-date 2025-01-01 --end-date 2025-01-31"
+  ),
+  snapshot: renderHelp(
+    "snapshot",
+    ["Fetch the latest price snapshot for a single ticker."],
+    [
+      "--ticker <symbol> Required. Stock ticker symbol.",
+      "--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"
+  ),
+  news: renderHelp(
+    "news",
+    ["Fetch curated issuer news 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).",
+      "--publisher <name>  Optional publisher filter.",
+      "--limit <n>         Number of articles to return.",
+      "--api-key <key>     API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>    API base URL override."
+    ],
+    "tn-financial-data query news --ticker AAPL --limit 10"
+  ),
+  "insider-trades": renderHelp(
+    "insider-trades",
+    ["Fetch SEC Form 4 insider-trade rows for a single issuer."],
+    [
+      "--ticker <symbol>              Required. Stock ticker symbol.",
+      "--start-date <date>            Optional start date (YYYY-MM-DD).",
+      "--end-date <date>              Optional end date (YYYY-MM-DD).",
+      "--reporting-owner-cik <cik>    Optional reporting owner filter.",
+      "--transaction-code <csv>       Optional comma-separated transaction codes.",
+      "--security-type <type>         all | non_derivative | derivative.",
+      "--limit <n>                    Number of 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 insider-trades --ticker AAPL --transaction-code P,S --limit 25"
+  ),
+  "institutional-ownership": renderHelp(
+    "institutional-ownership",
+    ["Fetch issuer-centric institutional holder rows for a single ticker."],
+    [
+      "--ticker <symbol> Required. Stock ticker symbol.",
+      "--limit <n>       Number of holder 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 institutional-ownership --ticker AAPL --limit 20"
+  ),
+  "investor-portfolio": renderHelp(
+    "investor-portfolio",
+    ["Fetch investor-centric SEC 13F holdings by filer CIK or known investor alias."],
+    [
+      "--cik <cik>       SEC filer CIK.",
+      "--investor <id>   Known investor alias such as vanguard.",
+      "--limit <n>       Number of holdings to return.",
+      "--api-key <key>   API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>  API base URL override."
+    ],
+    "tn-financial-data query investor-portfolio --investor vanguard --limit 20"
+  ),
+  "global-rates": renderHelp(
+    "global-rates",
+    ["Fetch curated global policy and money-market rate series."],
+    [
+      "--series <csv>     Optional comma-separated 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 global-rates --series ecb_refi,boe_sonia --limit 10"
+  ),
+  "segmented-revenues": renderHelp(
+    "segmented-revenues",
+    ["Fetch reported segment revenue rows for a single issuer."],
+    [
+      "--ticker <symbol>          Required. Stock ticker symbol.",
+      "--period <period>          annual | quarterly | ttm.",
+      "--limit <n>                Number of periods to return.",
+      "--segment-type <type>      Optional segment type filter.",
+      "--report-period <date>     Exact report period (YYYY-MM-DD).",
+      "--report-period-gte <date> Report period >= date.",
+      "--report-period-lte <date> Report period <= date.",
+      "--report-period-gt <date>  Report period > date.",
+      "--report-period-lt <date>  Report period < date.",
+      "--api-key <key>            API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>           API base URL override."
+    ],
+    "tn-financial-data query segmented-revenues --ticker AAPL --period quarterly --limit 4"
+  ),
+  screen: renderHelp(
+    "screen",
+    ["Run the hosted equity screener with one or more filter expressions."],
+    [
+      '--filter "field operator value" Required. Repeat for multiple filters.',
+      "--limit <n>                    Number of 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 screen --filter "trailing_pe < 25" --filter "recommendation_key = buy" --limit 10'
+  ),
+  "screen-fields": renderHelp(
+    "screen-fields",
+    ["List the supported screener fields and operator metadata."],
+    [
+      "--api-key <key>   API key. Overrides TN_FINANCIAL_DATA_API_KEY.",
+      "--base-url <url>  API base URL override."
+    ],
+    "tn-financial-data query screen-fields"
+  )
+};
+function getQuerySubcommandHelp(resource) {
+  return QUERY_SUBCOMMAND_HELP[resource] ?? null;
+}
+
 // src/cli/skill.ts
 import { cpSync, existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2, rmSync } from "fs";
 import { homedir as defaultHomedir } from "os";
@@ -1224,6 +1551,23 @@ function installSkill(options = {}) {
 // src/cli/index.ts
 var CliUsageError = class extends Error {
 };
+function isCliDebugEnabled(runtime) {
+  const debug = runtime.env.DEBUG?.trim().toLowerCase();
+  return debug === "1" || debug === "true" || debug === "tn-financial-data";
+}
+function formatRateLimitError(error) {
+  const retryAfterSeconds = error.rateLimit?.retryAfterSeconds;
+  const remaining = error.rateLimit?.remaining;
+  const limit = error.rateLimit?.limit;
+  const segments = ["Rate limit exceeded."];
+  if (remaining !== null && remaining !== void 0 && limit !== null && limit !== void 0) {
+    segments.push(`${remaining}/${limit} requests remaining.`);
+  }
+  if (retryAfterSeconds !== null && retryAfterSeconds !== void 0) {
+    segments.push(`Retry after ${retryAfterSeconds} seconds.`);
+  }
+  return segments.join(" ");
+}
 function logCliErrorDetails(runtime, error, prefix = "") {
   runtime.stderr(`${prefix}${error.message}`);
   const pgLikeError = error;
@@ -1252,12 +1596,29 @@ function logCliError(runtime, error) {
     runtime.stderr("Unknown CLI error.");
     return;
   }
-  if (error instanceof CliUsageError) {
+  if (!isCliDebugEnabled(runtime)) {
+    if (error instanceof CliUsageError) {
+      runtime.stderr(error.message);
+      return;
+    }
+    if (error instanceof ApiError && error.status === 429) {
+      runtime.stderr(formatRateLimitError(error));
+      return;
+    }
     runtime.stderr(error.message);
     return;
   }
   logCliErrorDetails(runtime, error);
 }
+function getCliExitCode(error) {
+  if (error instanceof CliUsageError) {
+    return 2;
+  }
+  if (error instanceof ApiError && error.status === 400) {
+    return 2;
+  }
+  return 1;
+}
 function createRuntime(overrides = {}) {
   return {
     stdout: overrides.stdout ?? ((line) => process.stdout.write(`${line}
@@ -1613,10 +1974,14 @@ function buildFinancialCliOptions(parsed, statement) {
 }
 async function handleQuery(parsed, runtime) {
   const resource = parsed.positionals[1];
-  if (!resource || hasOption(parsed, "help")) {
+  if (!resource) {
     runtime.stdout(queryHelp());
     return 0;
   }
+  if (hasOption(parsed, "help")) {
+    runtime.stdout(getQuerySubcommandHelp(resource) ?? queryHelp());
+    return 0;
+  }
   const client = createClient(parsed, runtime);
   switch (resource) {
     case "available-tickers":
@@ -2029,7 +2394,7 @@ async function runCli(argv, runtimeOverrides = {}) {
     }
   } catch (error) {
     logCliError(runtime, error);
-    return error instanceof CliUsageError ? 2 : 1;
+    return getCliExitCode(error);
   }
 }
 function isMainModule() {

package/dist/client/index.d.ts

@@ -250,6 +250,12 @@ interface ClientOptions {
     baseUrl?: string;
     fetch?: typeof fetch;
 }
+interface RateLimitInfo {
+    limit: number | null;
+    remaining: number | null;
+    resetAt: string | null;
+    retryAfterSeconds: number | null;
+}
 type SnakeCase<T extends string> = T extends `${infer Head}${infer Tail}` ? Tail extends Uncapitalize<Tail> ? `${Lowercase<Head>}${SnakeCase<Tail>}` : `${Lowercase<Head>}_${SnakeCase<Tail>}` : T;
 type SnakeCasedProperties<T> = {
     [Key in keyof T as Key extends string ? SnakeCase<Key> : Key]: T[Key];
@@ -701,14 +707,31 @@ interface ScreenerResponse {
     filters_applied: ScreenerFilter[];
     results: ScreenerResultRow[];
 }
+interface RateLimitAnnotatedResponse {
+    _rateLimit?: RateLimitInfo | null;
+}
+type ApiResponse<T extends object> = T & RateLimitAnnotatedResponse;
 declare const DEFAULT_API_BASE_URL = "https://api.truenorth-financial.ai/v1";
+declare class ApiError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    readonly body: string;
+    readonly rateLimit: RateLimitInfo | null;
+    constructor(options: {
+        status: number;
+        code: string | null;
+        message: string;
+        body: string;
+        rateLimit: RateLimitInfo | null;
+    });
+}
 declare class TnFinancialData {
     private apiKey;
     private baseUrl;
     private fetchFn;
     constructor(opts: ClientOptions);
     private request;
-    private extractErrorMessage;
+    private extractErrorBody;
     private appendLimitParam;
     private appendReportPeriodParams;
     private buildFinancialParams;
@@ -717,31 +740,31 @@ declare class TnFinancialData {
     private buildSegmentedRevenueParams;
     private buildQuarterlyHighlightsParams;
     private buildInsiderTradeParams;
-    getIncomeStatements(ticker: string, opts: FinancialOpts): Promise<IncomeStatementsResponse>;
-    getBalanceSheets(ticker: string, opts: FinancialOpts): Promise<BalanceSheetsResponse>;
-    getCashFlowStatements(ticker: string, opts: FinancialOpts): Promise<CashFlowStatementsResponse>;
-    getFinancials(ticker: string, opts: FinancialOpts): Promise<FinancialsResponse>;
-    getFinancialMetrics(ticker: string, opts?: FinancialMetricsOpts): Promise<FinancialMetricsResponse>;
-    getFinancialMetricsSnapshot(ticker: string, opts?: Pick<FinancialMetricsOpts, "period">): Promise<FinancialMetricsSnapshotResponse>;
-    getEarnings(ticker: string, opts?: EarningsOpts): Promise<EarningsResponse>;
-    getGeneralOverview(ticker: string, opts?: GeneralOverviewOpts): Promise<GeneralOverviewResponse>;
-    getKeyStatistics(ticker: string): Promise<KeyStatisticsResponse>;
-    getAvailableTickers(): Promise<AvailableTickersResponse>;
-    getPrices(ticker: string, opts: PriceOpts): Promise<PriceHistoryResponse>;
-    getPriceSnapshot(ticker: string): Promise<PriceSnapshotResponse>;
-    getNews(ticker: string, opts?: NewsOpts): Promise<NewsResponse>;
-    getInsiderTrades(ticker: string, opts?: InsiderTradesOpts): Promise<InsiderTradesResponse>;
-    getInstitutionalOwnership(ticker: string, opts?: InstitutionalOwnershipOpts): Promise<InstitutionalOwnershipResponse>;
-    getInvestorPortfolio(opts: InvestorPortfolioOpts): Promise<InvestorPortfolioResponse>;
-    getGlobalInterestRates(opts?: GlobalInterestRatesOpts): Promise<GlobalInterestRatesResponse>;
-    getAnalystEstimates(ticker: string): Promise<AnalystEstimatesResponse>;
-    getCompanyFacts(ticker: string): Promise<{
+    getIncomeStatements(ticker: string, opts: FinancialOpts): Promise<ApiResponse<IncomeStatementsResponse>>;
+    getBalanceSheets(ticker: string, opts: FinancialOpts): Promise<ApiResponse<BalanceSheetsResponse>>;
+    getCashFlowStatements(ticker: string, opts: FinancialOpts): Promise<ApiResponse<CashFlowStatementsResponse>>;
+    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>>;
+    getEarnings(ticker: string, opts?: EarningsOpts): Promise<ApiResponse<EarningsResponse>>;
+    getGeneralOverview(ticker: string, opts?: GeneralOverviewOpts): Promise<ApiResponse<GeneralOverviewResponse>>;
+    getKeyStatistics(ticker: string): Promise<ApiResponse<KeyStatisticsResponse>>;
+    getAvailableTickers(): Promise<ApiResponse<AvailableTickersResponse>>;
+    getPrices(ticker: string, opts: PriceOpts): Promise<ApiResponse<PriceHistoryResponse>>;
+    getPriceSnapshot(ticker: string): Promise<ApiResponse<PriceSnapshotResponse>>;
+    getNews(ticker: string, opts?: NewsOpts): Promise<ApiResponse<NewsResponse>>;
+    getInsiderTrades(ticker: string, opts?: InsiderTradesOpts): Promise<ApiResponse<InsiderTradesResponse>>;
+    getInstitutionalOwnership(ticker: string, opts?: InstitutionalOwnershipOpts): Promise<ApiResponse<InstitutionalOwnershipResponse>>;
+    getInvestorPortfolio(opts: InvestorPortfolioOpts): Promise<ApiResponse<InvestorPortfolioResponse>>;
+    getGlobalInterestRates(opts?: GlobalInterestRatesOpts): Promise<ApiResponse<GlobalInterestRatesResponse>>;
+    getAnalystEstimates(ticker: string): Promise<ApiResponse<AnalystEstimatesResponse>>;
+    getCompanyFacts(ticker: string): Promise<ApiResponse<{
         company_facts: CompanyFacts;
-    }>;
-    getSegmentedRevenues(ticker: string, opts: SegmentedRevenuesOpts): Promise<SegmentedRevenuesResponse>;
-    getQuarterlyHighlights(ticker: string, opts?: QuarterlyHighlightsOpts): Promise<QuarterlyHighlightsResponse>;
-    getScreenerFields(): Promise<ScreenerFieldsResponse>;
-    screen(request: ScreenerRequest): Promise<ScreenerResponse>;
+    }>>;
+    getSegmentedRevenues(ticker: string, opts: SegmentedRevenuesOpts): Promise<ApiResponse<SegmentedRevenuesResponse>>;
+    getQuarterlyHighlights(ticker: string, opts?: QuarterlyHighlightsOpts): Promise<ApiResponse<QuarterlyHighlightsResponse>>;
+    getScreenerFields(): Promise<ApiResponse<ScreenerFieldsResponse>>;
+    screen(request: ScreenerRequest): Promise<ApiResponse<ScreenerResponse>>;
 }
 
-export { type AnalystEstimate, type AnalystEstimatesResponse, type AnalystPriceTarget, 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 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 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 CashFlowStatement, type CashFlowStatementsResponse, type ClientOptions, type CompanyFacts, type ConsensusSurprise, DEFAULT_API_BASE_URL, type DataAvailability, type EarningsOpts, type EarningsResponse, type EarningsRow, 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 };

package/dist/client/index.js

@@ -1,5 +1,42 @@
 // src/client/index.ts
 var DEFAULT_API_BASE_URL = "https://api.truenorth-financial.ai/v1";
+function parseOptionalInt(value) {
+  if (!value) {
+    return null;
+  }
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function parseOptionalUnixTimestamp(value) {
+  const parsed = parseOptionalInt(value);
+  if (parsed === null) {
+    return null;
+  }
+  return new Date(parsed * 1e3).toISOString();
+}
+function parseRateLimitInfo(headers) {
+  const info = {
+    limit: parseOptionalInt(headers.get("X-RateLimit-Limit")),
+    remaining: parseOptionalInt(headers.get("X-RateLimit-Remaining")),
+    resetAt: parseOptionalUnixTimestamp(headers.get("X-RateLimit-Reset")),
+    retryAfterSeconds: parseOptionalInt(headers.get("Retry-After"))
+  };
+  return Object.values(info).some((value) => value !== null) ? info : null;
+}
+var ApiError = class extends Error {
+  status;
+  code;
+  body;
+  rateLimit;
+  constructor(options) {
+    super(`API error ${options.status}: ${options.message}`);
+    this.name = "ApiError";
+    this.status = options.status;
+    this.code = options.code;
+    this.body = options.body;
+    this.rateLimit = options.rateLimit;
+  }
+};
 var TnFinancialData = class {
   apiKey;
   baseUrl;
@@ -20,21 +57,44 @@ var TnFinancialData = class {
       headers
     });
     if (!res.ok) {
-      const errorMessage = await this.extractErrorMessage(res);
-      throw new Error(`API error ${res.status}: ${errorMessage}`);
+      const errorBody = await this.extractErrorBody(res);
+      throw new ApiError({
+        status: res.status,
+        code: errorBody.code,
+        message: errorBody.message,
+        body: errorBody.rawBody,
+        rateLimit: parseRateLimitInfo(res.headers)
+      });
     }
-    return res.json();
+    const payload = await res.json();
+    Object.defineProperty(payload, "_rateLimit", {
+      value: parseRateLimitInfo(res.headers),
+      enumerable: false,
+      configurable: true,
+      writable: false
+    });
+    return payload;
   }
-  async extractErrorMessage(res) {
+  async extractErrorBody(res) {
     const rawBody = await res.text().catch(() => "");
     const trimmed = rawBody.trim();
-    if (trimmed.length === 0) return "Unknown error";
+    if (trimmed.length === 0) {
+      return { message: "Unknown error", code: null, rawBody: "" };
+    }
     try {
       const parsed = JSON.parse(trimmed);
       const code = parsed.code ? `[${parsed.code}] ` : "";
-      return `${code}${parsed.error?.trim() || trimmed}`;
+      return {
+        message: `${code}${parsed.error?.trim() || trimmed}`,
+        code: parsed.code?.trim() || null,
+        rawBody: trimmed
+      };
     } catch {
-      return trimmed;
+      return {
+        message: trimmed,
+        code: null,
+        rawBody: trimmed
+      };
     }
   }
   appendLimitParam(params, limit) {
@@ -223,6 +283,7 @@ var TnFinancialData = class {
   }
 };
 export {
+  ApiError,
   DEFAULT_API_BASE_URL,
   TnFinancialData
 };

package/package.json

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

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

@@ -22,7 +22,7 @@ Covered reads include:
 
 - company facts and broad one-company overviews
 - financial statements, derived financial metrics, earnings, and analyst estimates
-- issuer-reported supplemental quarterly highlights for supported companies
+- 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
 - insider trades, issuer-level institutional ownership, and investor `13F` portfolios
@@ -33,7 +33,7 @@ Covered reads include:
 
 - For a broad single-company prompt, start with `general-overview`.
 - For a narrow ask, prefer the narrower read instead of widening the problem too early.
-- For Apple product mix or Greater China, Meta ad KPIs, Amazon `AWS` operating income or segment-profit prompts, and Tesla services-and-other or free-cash-flow prompts, start with `quarterly-highlights` before `segmented-revenues`, `financials`, or `general-overview`.
+- For Apple product mix or Greater China, Meta ad KPIs, Amazon `AWS` operating income or segment-profit prompts, and Tesla services-and-other or free-cash-flow prompts, start with `quarterly-highlights` before `segmented-revenues`, `financials`, or `general-overview`. For other covered issuers, `quarterly-highlights` now serves as a generic latest-quarter summary even when no issuer-specific release parser exists.
 - Use `segmented-revenues` when the user explicitly wants XBRL dimension tables, additive segment rows, or issuer coverage that is outside the narrower `quarterly-highlights` surface.
 - 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`).

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

@@ -5,6 +5,7 @@ Use the CLI for agent access whenever possible.
 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 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`