sentisense 0.41.0 → 0.43.0

package/dist/cli.cjs

@@ -0,0 +1,3904 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/errors.ts
+var SentiSenseError = class extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.name = "SentiSenseError";
+    this.status = status;
+    this.code = code;
+  }
+};
+var AuthenticationError = class extends SentiSenseError {
+  constructor(message, status, code) {
+    super(message, status, code);
+    this.name = "AuthenticationError";
+  }
+};
+var NotFoundError = class extends SentiSenseError {
+  constructor(message, code) {
+    super(message, 404, code);
+    this.name = "NotFoundError";
+  }
+};
+var DeepHistoryUnavailableError = class extends SentiSenseError {
+  constructor(message, retryAfter) {
+    super(message, 202);
+    this.name = "DeepHistoryUnavailableError";
+    this.retryAfter = retryAfter;
+  }
+};
+var RateLimitError = class extends SentiSenseError {
+  constructor(message, code, retryAfter) {
+    super(message, 429, code);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var APIError = class extends SentiSenseError {
+  constructor(message, status, code) {
+    super(message, status, code);
+    this.name = "APIError";
+  }
+};
+
+// src/cli/errors.ts
+var EXIT = {
+  OK: 0,
+  ERROR: 1,
+  USAGE: 2,
+  AUTH: 3,
+  NOT_FOUND: 4,
+  RATE_LIMIT: 5,
+  NETWORK: 6
+};
+var EXIT_TABLE = [
+  [EXIT.OK, "success"],
+  [EXIT.ERROR, "API error or unexpected failure"],
+  [EXIT.USAGE, "bad usage: unknown command, flag, or missing argument"],
+  [EXIT.AUTH, "missing or rejected API key"],
+  [EXIT.NOT_FOUND, "no data for that symbol or identifier"],
+  [EXIT.RATE_LIMIT, "rate limited"],
+  [EXIT.NETWORK, "network failure or timeout"]
+];
+var KEY_URL = "https://app.sentisense.ai/get-api-key";
+var CliUsageError = class extends Error {
+  constructor(message, hint) {
+    super(message);
+    this.name = "CliUsageError";
+    this.hint = hint;
+  }
+};
+var UnknownTickerError = class extends Error {
+  constructor(ticker) {
+    super(`unknown ticker "${ticker}".`);
+    this.name = "UnknownTickerError";
+    this.ticker = ticker;
+  }
+};
+var MissingKeyError = class extends Error {
+  constructor() {
+    super("no API key configured.");
+    this.name = "MissingKeyError";
+  }
+};
+function describeError(error, debug) {
+  const report = classify(error);
+  if (debug && error instanceof Error && error.stack) {
+    report.lines.push(error.stack);
+  }
+  return report;
+}
+function classify(error) {
+  if (error instanceof MissingKeyError) {
+    return {
+      exitCode: EXIT.AUTH,
+      lines: [
+        "error: no API key configured.",
+        `next: run "sentisense auth <key>", or set SENTISENSE_API_KEY. Get a key at ${KEY_URL}`
+      ]
+    };
+  }
+  if (error instanceof UnknownTickerError) {
+    return {
+      exitCode: EXIT.NOT_FOUND,
+      lines: [
+        `error: ${error.message}`,
+        "next: check the symbol. Use canonical tickers, for example GOOGL rather than GOOG and BRK.B rather than BRK-B."
+      ]
+    };
+  }
+  if (error instanceof CliUsageError) {
+    return {
+      exitCode: EXIT.USAGE,
+      lines: [
+        `error: ${error.message}`,
+        `next: ${error.hint ?? 'run "sentisense --help" for the command list.'}`
+      ]
+    };
+  }
+  if (error instanceof AuthenticationError) {
+    return {
+      exitCode: EXIT.AUTH,
+      lines: [
+        `error: the API key was rejected (${error.status ?? 401}): ${error.message}`,
+        `next: check the stored key with "sentisense auth", or get a new one at ${KEY_URL}`
+      ]
+    };
+  }
+  if (error instanceof NotFoundError) {
+    return {
+      exitCode: EXIT.NOT_FOUND,
+      lines: [
+        `error: not found: ${error.message}`,
+        "next: check the symbol. Use canonical tickers, for example GOOGL rather than GOOG."
+      ]
+    };
+  }
+  if (error instanceof RateLimitError) {
+    const wait = error.retryAfter ? Math.ceil(error.retryAfter) : 60;
+    return {
+      exitCode: EXIT.RATE_LIMIT,
+      lines: [
+        `error: rate limited: ${error.message}`,
+        `next: wait ${wait} seconds and run it again. The CLI does not retry for you.`
+      ]
+    };
+  }
+  if (error instanceof SentiSenseError) {
+    if (error.status === void 0) {
+      return {
+        exitCode: EXIT.NETWORK,
+        lines: [
+          `error: could not reach the API: ${error.message}`,
+          'next: check the network and the base URL, then run "sentisense health".'
+        ]
+      };
+    }
+    return {
+      exitCode: EXIT.ERROR,
+      lines: [
+        `error: request failed (${error.status}): ${error.message}`,
+        'next: run "sentisense health" to check the service, then try again.'
+      ]
+    };
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  return {
+    exitCode: EXIT.ERROR,
+    lines: [
+      `error: ${message}`,
+      "next: run the same command with --debug for the stack trace."
+    ]
+  };
+}
+
+// src/cli/ticker.ts
+function rejectSurplus(args, name, allowed) {
+  if (args.positionals.length <= allowed) return;
+  throw new CliUsageError(
+    `${name} takes one ticker, and got ${args.positionals.length}.`,
+    "run it once per ticker. Only quote accepts more than one."
+  );
+}
+function oneTicker(args, name) {
+  rejectSurplus(args, name, 1);
+  const ticker = args.positionals[0];
+  if (!ticker) {
+    throw new CliUsageError(
+      `${name} needs a ticker.`,
+      `for example: sentisense ${name} NVDA`
+    );
+  }
+  return ticker.toUpperCase();
+}
+function optionalTicker(args, name) {
+  rejectSurplus(args, name, 1);
+  return args.positionals[0]?.toUpperCase();
+}
+function rejectPositionals(args, name) {
+  if (args.positionals.length === 0) return;
+  throw new CliUsageError(
+    `${name} takes no ticker, and got ${args.positionals.length}.`,
+    `run "sentisense help ${name}" for what it accepts.`
+  );
+}
+async function verifyTickerOnEmpty(api, ticker) {
+  try {
+    await api.stocks.getQuote(ticker);
+    return void 0;
+  } catch (error) {
+    if (error instanceof NotFoundError) throw new UnknownTickerError(ticker);
+    return `could not verify ${ticker}, so the empty result is unconfirmed`;
+  }
+}
+var EMPTY_VERIFY_NOTE = "An empty result verifies the ticker before reporting no data, so a typo exits 4 rather";
+var EMPTY_VERIFY_NOTE_2 = "than looking like a company with nothing to report.";
+
+// src/cli/render/doc.ts
+function cell(text, tone) {
+  return tone ? { text, tone } : { text };
+}
+function field(label, text, tone) {
+  return { label, value: cell(text, tone) };
+}
+function fields(...items) {
+  return items.filter((item) => item !== void 0);
+}
+function doc(...blocks) {
+  return { blocks: blocks.filter((block) => block !== void 0) };
+}
+
+// src/cli/render/num.ts
+var ABSENT = "n/a";
+var SPARK_LEVELS = ["\u2581", "\u2582", "\u2583", "\u2584", "\u2585", "\u2586", "\u2587", "\u2588"];
+function isNum(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function trim(text) {
+  return text.includes(".") ? text.replace(/\.?0+$/, "") : text;
+}
+function fixed(value, decimals = 2) {
+  return isNum(value) ? value.toFixed(decimals) : ABSENT;
+}
+function humanize(value, decimals = 2) {
+  if (!isNum(value)) return ABSENT;
+  const sign = value < 0 ? "-" : "";
+  const abs = Math.abs(value);
+  const units = [
+    [1e12, "T"],
+    [1e9, "B"],
+    [1e6, "M"],
+    [1e3, "k"]
+  ];
+  for (const [scale, suffix] of units) {
+    if (abs >= scale) return `${sign}${trim((abs / scale).toFixed(decimals))}${suffix}`;
+  }
+  return `${sign}${trim(abs.toFixed(decimals))}`;
+}
+function signed(value, decimals = 2) {
+  if (!isNum(value)) return ABSENT;
+  return `${value > 0 ? "+" : ""}${value.toFixed(decimals)}`;
+}
+function signedPercent(value, decimals = 2) {
+  if (!isNum(value)) return ABSENT;
+  return `${value > 0 ? "+" : ""}${value.toFixed(decimals)}%`;
+}
+function percent(value, decimals = 1) {
+  return isNum(value) ? `${value.toFixed(decimals)}%` : ABSENT;
+}
+function money(value, decimals = 2) {
+  return isNum(value) ? `$${value.toFixed(decimals)}` : ABSENT;
+}
+function direction(value) {
+  if (!isNum(value) || value === 0) return void 0;
+  return value > 0 ? "up" : "down";
+}
+function sparkline(series) {
+  const numbers = series.filter(isNum);
+  if (numbers.length === 0) return "";
+  const min = Math.min(...numbers);
+  const max = Math.max(...numbers);
+  const span = max - min;
+  return series.map((point) => {
+    if (!isNum(point)) return " ";
+    if (span === 0) return SPARK_LEVELS[3];
+    const level = Math.round((point - min) / span * (SPARK_LEVELS.length - 1));
+    return SPARK_LEVELS[level];
+  }).join("");
+}
+function timestamp(ms) {
+  if (!isNum(ms)) return ABSENT;
+  const iso = new Date(ms).toISOString();
+  return `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;
+}
+function dateFromSeconds(seconds) {
+  if (!isNum(seconds)) return ABSENT;
+  return new Date(seconds * 1e3).toISOString().slice(0, 10);
+}
+function truncate(text, max) {
+  if (text.length <= max) return text;
+  return `${text.slice(0, Math.max(0, max - 3))}...`;
+}
+
+// src/cli/commands/analysts.ts
+var DEFAULT_ACTIONS = 5;
+function actionTone(actionType) {
+  if (actionType === "UPGRADE") return "up";
+  if (actionType === "DOWNGRADE") return "down";
+  return void 0;
+}
+var analystsCommand = {
+  name: "analysts",
+  summary: "Wall Street consensus, price target band, and recent rating changes",
+  usage: "sentisense analysts <ticker> [--days N]",
+  examples: [
+    "sentisense analysts NVDA",
+    "sentisense analysts NVDA --days 180 --full",
+    "sentisense analysts NVDA --json"
+  ],
+  notes: [
+    "The price target band and analyst count come back in full on every key.",
+    "The buy / hold / sell distribution and the longer action history are PRO.",
+    "A ticker with no analyst coverage exits 4 rather than returning an empty band."
+  ],
+  flags: {
+    days: { type: "number", placeholder: "N", describe: "Days of rating history (default 90)" }
+  },
+  async run({ args, client, full }) {
+    const ticker = oneTicker(args, "analysts");
+    const lookbackDays = typeof args.flags.days === "number" ? args.flags.days : void 0;
+    const api = client();
+    const notes = [];
+    const [consensus, actions] = await Promise.all([
+      api.analyst.consensus(ticker),
+      // Supplementary: the consensus is the answer, so a failure here trims the output
+      // rather than failing the command, and says so on stderr instead of vanishing.
+      api.analyst.actions(ticker, lookbackDays === void 0 ? void 0 : { lookbackDays }).catch(() => {
+        notes.push("rating history unavailable, showing the consensus without it");
+        return null;
+      })
+    ]);
+    const data = consensus.data;
+    const blocks = [
+      {
+        kind: "head",
+        title: field("ticker", ticker),
+        right: fields(
+          field("target mean", money(data?.targetMean)),
+          field(
+            "upside",
+            signedPercent(data?.upsidePercent),
+            direction(data?.upsidePercent)
+          )
+        )
+      },
+      {
+        kind: "facts",
+        items: fields(
+          field("Analysts", data?.numberOfAnalysts === void 0 ? "n/a" : String(data.numberOfAnalysts)),
+          field("Consensus", data?.consensusLabel ?? "n/a"),
+          field("Low", fixed(data?.targetLow)),
+          field("Median", fixed(data?.targetMedian)),
+          field("High", fixed(data?.targetHigh))
+        )
+      },
+      {
+        kind: "facts",
+        items: fields(
+          field("Strong buy", String(data?.strongBuy ?? 0)),
+          field("Buy", String(data?.buy ?? 0)),
+          field("Hold", String(data?.hold ?? 0)),
+          field("Sell", String(data?.sell ?? 0)),
+          field("Strong sell", String(data?.strongSell ?? 0))
+        )
+      }
+    ];
+    const rows = actions?.data ?? [];
+    if (rows.length > 0) {
+      const shown = full ? rows : rows.slice(0, DEFAULT_ACTIONS);
+      blocks.push({ kind: "blank" });
+      blocks.push({
+        kind: "table",
+        head: ["DATE", "FIRM", "ACTION", "FROM", "TO"],
+        rows: shown.map((action) => [
+          cell(action.actionDate),
+          cell(action.firm),
+          cell(action.actionType, actionTone(action.actionType)),
+          cell(action.fromGrade ?? ""),
+          cell(action.toGrade ?? "")
+        ])
+      });
+      if (!full && rows.length > shown.length) {
+        blocks.push({
+          kind: "text",
+          text: `Showing ${shown.length} of ${rows.length} rating changes. Add --full for the rest.`,
+          tone: "dim"
+        });
+      }
+    }
+    if (consensus.isPreview) {
+      blocks.push({
+        kind: "text",
+        text: "Preview response: the rating distribution reads zero and the history is trimmed on a free key.",
+        tone: "dim"
+      });
+    }
+    return { json: { consensus, actions }, doc: doc(...blocks), notes };
+  }
+};
+
+// src/cli/config.ts
+var import_node_fs = require("fs");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var CONFIG_FILE = "config.json";
+function resolveConfigDir(env, override) {
+  if (override) return override;
+  const explicit = env.SENTISENSE_CONFIG_DIR?.trim();
+  if (explicit) return explicit;
+  const xdg = env.XDG_CONFIG_HOME?.trim();
+  if (xdg) return (0, import_node_path.join)(xdg, "sentisense");
+  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".config", "sentisense");
+}
+function configPath(dir) {
+  return (0, import_node_path.join)(dir, CONFIG_FILE);
+}
+function readConfig(dir) {
+  const path = configPath(dir);
+  if (!(0, import_node_fs.existsSync)(path)) return {};
+  try {
+    const parsed = JSON.parse((0, import_node_fs.readFileSync)(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    const raw = parsed;
+    const config = {};
+    if (typeof raw.apiKey === "string") config.apiKey = raw.apiKey;
+    if (typeof raw.agentName === "string") config.agentName = raw.agentName;
+    if (typeof raw.baseUrl === "string") config.baseUrl = raw.baseUrl;
+    return config;
+  } catch {
+    return {};
+  }
+}
+function writeConfig(dir, config) {
+  (0, import_node_fs.mkdirSync)(dir, { recursive: true, mode: 448 });
+  const path = configPath(dir);
+  (0, import_node_fs.writeFileSync)(path, `${JSON.stringify(config, null, 2)}
+`, { mode: 384 });
+  (0, import_node_fs.chmodSync)(path, 384);
+  return path;
+}
+function clearConfig(dir) {
+  const path = configPath(dir);
+  if (!(0, import_node_fs.existsSync)(path)) return false;
+  (0, import_node_fs.unlinkSync)(path);
+  return true;
+}
+function maskKey(key) {
+  if (key.length <= 8) return "*".repeat(key.length);
+  return `${key.slice(0, 4)}...${key.slice(-4)}`;
+}
+
+// src/cli/commands/auth.ts
+var authCommand = {
+  name: "auth",
+  summary: "Store an API key, show what is configured, or remove it",
+  usage: "sentisense auth [<key>] [--agent <name>] [--remove]",
+  examples: [
+    "sentisense auth $SENTISENSE_API_KEY",
+    "sentisense auth --agent research-desk",
+    "sentisense auth",
+    "sentisense auth --remove"
+  ],
+  notes: [
+    "Settings live in config.json under $SENTISENSE_CONFIG_DIR, $XDG_CONFIG_HOME/sentisense,",
+    "or ~/.config/sentisense, written owner-readable only (0600).",
+    "The key is never printed back in full, and never has to be pasted into a command again.",
+    "An agent name is optional. When set, it rides along in the User-Agent so your own",
+    "traffic is easy to tell apart from everything else calling the API."
+  ],
+  flags: {
+    remove: { type: "boolean", describe: "Delete the stored settings" }
+  },
+  async run({ args, context }) {
+    const dir = context.configDir;
+    const path = configPath(dir);
+    if (args.flags.remove === true) {
+      const removed = clearConfig(dir);
+      return {
+        json: { removed, path },
+        doc: doc(
+          { kind: "text", text: removed ? `Removed ${path}` : `Nothing stored at ${path}` }
+        )
+      };
+    }
+    const key = args.positionals[0];
+    const agent = typeof args.flags.agent === "string" ? args.flags.agent : void 0;
+    const baseUrl = typeof args.flags["base-url"] === "string" ? args.flags["base-url"] : void 0;
+    if (key || agent || baseUrl) {
+      const stored2 = readConfig(dir);
+      const next = {
+        ...stored2,
+        ...key ? { apiKey: key } : {},
+        ...agent ? { agentName: agent } : {},
+        ...baseUrl ? { baseUrl } : {}
+      };
+      writeConfig(dir, next);
+      return {
+        json: {
+          path,
+          apiKey: next.apiKey ? maskKey(next.apiKey) : null,
+          agentName: next.agentName ?? null,
+          baseUrl: next.baseUrl ?? null
+        },
+        doc: doc(
+          { kind: "text", text: `Saved to ${path}` },
+          {
+            kind: "kv",
+            items: fields(
+              next.apiKey ? field("api key", maskKey(next.apiKey)) : void 0,
+              next.agentName ? field("agent", next.agentName) : void 0,
+              next.baseUrl ? field("base url", next.baseUrl) : void 0
+            )
+          }
+        )
+      };
+    }
+    const stored = readConfig(dir);
+    const resolved = context.apiKey;
+    return {
+      json: {
+        path,
+        configured: Boolean(stored.apiKey),
+        apiKey: resolved ? maskKey(resolved) : null,
+        apiKeySource: context.apiKeySource,
+        agentName: context.agentName ?? null,
+        baseUrl: context.baseUrl ?? null
+      },
+      doc: doc(
+        {
+          kind: "kv",
+          items: fields(
+            field("api key", resolved ? maskKey(resolved) : "not configured"),
+            field("source", resolved ? context.apiKeySource : "none"),
+            field("config", path),
+            context.agentName ? field("agent", context.agentName) : void 0,
+            context.baseUrl ? field("base url", context.baseUrl) : void 0
+          )
+        },
+        resolved ? void 0 : {
+          kind: "text",
+          text: `Store one with "sentisense auth <key>". Get a key at ${KEY_URL}`
+        }
+      )
+    };
+  }
+};
+
+// src/cli/commands/congress.ts
+var congressCommand = {
+  name: "congress",
+  summary: "Congressional stock disclosures, market-wide or for one ticker",
+  usage: "sentisense congress [ticker] [--days N] [--limit N]",
+  examples: [
+    "sentisense congress",
+    "sentisense congress NVDA",
+    "sentisense congress --days 30 --limit 50 --full",
+    "sentisense congress NVDA --json"
+  ],
+  notes: [
+    "Disclosures are filed after the fact, so the gap between the trade date and the",
+    "disclosure date is part of the picture. The delay column carries it in days.",
+    "Amounts are the filed ranges, never exact figures: that is how the filings work.",
+    "A free key sees a short preview of either feed.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
+  ],
+  flags: {
+    days: { type: "number", placeholder: "N", describe: "Look-back window, 1 to 365 (default 90)" },
+    limit: { type: "number", placeholder: "N", describe: "Rows to request, market-wide feed only" }
+  },
+  async run({ args, client, full }) {
+    const api = client();
+    const ticker = optionalTicker(args, "congress");
+    const notes = [];
+    const lookbackDays = typeof args.flags.days === "number" ? args.flags.days : void 0;
+    const limit = typeof args.flags.limit === "number" ? args.flags.limit : void 0;
+    let envelope;
+    if (ticker) {
+      envelope = await api.politicians.getFilings(
+        ticker,
+        lookbackDays === void 0 ? void 0 : { lookbackDays }
+      );
+    } else {
+      const options = {
+        ...lookbackDays === void 0 ? {} : { lookbackDays },
+        ...limit === void 0 ? {} : { limit }
+      };
+      envelope = await api.politicians.getActivity(
+        Object.keys(options).length > 0 ? options : void 0
+      );
+    }
+    const trades = envelope.data ?? [];
+    if (ticker && trades.length === 0) {
+      const note = await verifyTickerOnEmpty(api, ticker);
+      if (note) notes.push(note);
+    }
+    const shown = full ? trades : trades.slice(0, 20);
+    const blocks = [
+      {
+        kind: "head",
+        title: field("scope", ticker ?? "All disclosures"),
+        right: fields(
+          field("rows", String(trades.length)),
+          envelope.totalCount === void 0 ? void 0 : field("matching", String(envelope.totalCount))
+        )
+      }
+    ];
+    if (shown.length === 0) {
+      blocks.push({ kind: "text", text: "No disclosures in this window." });
+    } else {
+      const head = ticker ? ["TRADED", "MEMBER", "PARTY", "TYPE", "AMOUNT", "DELAY"] : ["TRADED", "MEMBER", "TICKER", "TYPE", "AMOUNT", "DELAY"];
+      blocks.push({
+        kind: "table",
+        head,
+        align: ["left", "left", "left", "left", "left", "right"],
+        rows: shown.map((trade) => [
+          cell(trade.transactionDate),
+          cell(truncate(trade.politicianName, full ? 40 : 22)),
+          // Party and state are absent on some disclosures, so build the label from what is
+          // actually there rather than printing a placeholder.
+          cell(ticker ? [trade.party, trade.state].filter(Boolean).join(" ") : trade.ticker),
+          cell(
+            trade.transactionType,
+            trade.transactionType === "PURCHASE" ? "up" : trade.transactionType === "SALE" ? "down" : void 0
+          ),
+          cell(trade.amountRange),
+          cell(`${trade.disclosureDelayDays}d`)
+        ])
+      });
+      if (!full && trades.length > shown.length) {
+        blocks.push({
+          kind: "text",
+          text: `Showing ${shown.length} of ${trades.length}. Add --full for the rest.`,
+          tone: "dim"
+        });
+      }
+    }
+    if (envelope.isPreview) {
+      blocks.push({
+        kind: "text",
+        text: "Preview response: a PRO key returns the full feed.",
+        tone: "dim"
+      });
+    }
+    return { json: envelope, doc: doc(...blocks), notes };
+  }
+};
+
+// src/cli/commands/earnings.ts
+var TIME_LABEL = {
+  before_open: "pre-open",
+  after_close: "post-close",
+  during_market: "intraday",
+  unknown: "unknown"
+};
+var earningsCommand = {
+  name: "earnings",
+  summary: "Upcoming report dates, or the quarter-by-quarter analysis for one ticker",
+  usage: "sentisense earnings [ticker] [--week this|next] [--limit N]",
+  examples: [
+    "sentisense earnings",
+    "sentisense earnings --week next",
+    "sentisense earnings AAPL",
+    "sentisense earnings AAPL --limit 4 --full"
+  ],
+  notes: [
+    "With no ticker this is the forward calendar: who reports, when, and the consensus EPS.",
+    "With a ticker it is the backward-looking analysis: one entry per reported quarter with",
+    "the editorial headline, and on a PRO key the written summary and guidance language.",
+    "A free key sees the current week of the calendar and the latest quarter of the analysis.",
+    "Coverage of the per-ticker analysis is not the whole market, so a tracked company can",
+    "have no stored quarter yet.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
+  ],
+  flags: {
+    week: { type: "string", placeholder: "this|next", describe: "Calendar window shorthand" },
+    from: { type: "string", placeholder: "YYYY-MM-DD", describe: "Calendar lower bound" },
+    to: { type: "string", placeholder: "YYYY-MM-DD", describe: "Calendar upper bound" },
+    confirmed: { type: "boolean", describe: "Calendar: only company-confirmed dates" },
+    limit: { type: "number", placeholder: "N", describe: "Quarters to return for a ticker" }
+  },
+  async run({ args, client, full }) {
+    const api = client();
+    const ticker = optionalTicker(args, "earnings");
+    const notes = [];
+    if (ticker) {
+      const limit = typeof args.flags.limit === "number" ? args.flags.limit : void 0;
+      const envelope2 = await api.earnings.getSummaries(
+        ticker,
+        limit === void 0 ? void 0 : { limit }
+      );
+      const quarters = envelope2.data ?? [];
+      if (quarters.length === 0) {
+        const note = await verifyTickerOnEmpty(api, ticker);
+        if (note) notes.push(note);
+      }
+      const blocks2 = [
+        {
+          kind: "head",
+          title: field("ticker", ticker),
+          right: fields(
+            field("quarters", String(quarters.length)),
+            envelope2.totalCount === void 0 ? void 0 : field("available", String(envelope2.totalCount))
+          )
+        }
+      ];
+      if (quarters.length === 0) {
+        blocks2.push({ kind: "text", text: "No stored quarters for this ticker yet." });
+      } else {
+        blocks2.push({
+          kind: "table",
+          head: ["PERIOD", "REPORTED", "CALL", "HEADLINE"],
+          rows: quarters.map((quarter) => [
+            cell(quarter.fiscalPeriod),
+            cell(quarter.reportDate),
+            cell(quarter.hasTranscript ? "yes" : "no", quarter.hasTranscript ? "up" : "dim"),
+            cell(truncate(quarter.headline ?? "", full ? 200 : 60))
+          ])
+        });
+        if (full) {
+          for (const quarter of quarters) {
+            blocks2.push({ kind: "blank" });
+            blocks2.push({
+              kind: "head",
+              title: field("period", quarter.fiscalPeriod),
+              subtitle: field("reported", quarter.reportDate)
+            });
+            const highlights = quarter.kpiHighlights ?? [];
+            if (highlights.length > 0) {
+              blocks2.push({
+                kind: "kv",
+                items: highlights.map(
+                  (kpi) => field(kpi.label, kpi.yoy ? `${kpi.value}  ${kpi.yoy}` : kpi.value)
+                )
+              });
+            }
+            if (quarter.guidance) {
+              blocks2.push({ kind: "text", text: `Guidance: ${quarter.guidance}` });
+            } else if (quarter.guidanceDirection) {
+              blocks2.push({ kind: "text", text: `Guidance direction: ${quarter.guidanceDirection}` });
+            }
+            if (quarter.summaryMd) blocks2.push({ kind: "text", text: quarter.summaryMd });
+            blocks2.push({
+              kind: "text",
+              text: `written ${dateFromSeconds(quarter.generatedAt)} from the ${quarter.source === "transcript" ? "earnings call" : "press release"}`,
+              tone: "dim"
+            });
+          }
+        }
+      }
+      if (envelope2.isPreview) {
+        blocks2.push({
+          kind: "text",
+          text: "Preview response: a PRO key returns every quarter with the written body and guidance.",
+          tone: "dim"
+        });
+      }
+      return { json: envelope2, doc: doc(...blocks2), notes };
+    }
+    const week = typeof args.flags.week === "string" ? args.flags.week : void 0;
+    if (week && week !== "this" && week !== "next") {
+      throw new CliUsageError(
+        `--week takes "this" or "next", got "${week}".`,
+        "for example: --week next"
+      );
+    }
+    const options = {
+      ...week ? { week } : {},
+      ...typeof args.flags.from === "string" ? { from: args.flags.from } : {},
+      ...typeof args.flags.to === "string" ? { to: args.flags.to } : {},
+      ...args.flags.confirmed === true ? { confirmed: true } : {}
+    };
+    const envelope = await api.calendar.getEarnings(
+      Object.keys(options).length > 0 ? options : void 0
+    );
+    const events = envelope.data?.earnings ?? [];
+    const meta = envelope.data?.metadata;
+    const shown = full ? events : events.slice(0, 25);
+    const blocks = [
+      {
+        kind: "head",
+        title: field("window", "Earnings calendar"),
+        right: fields(
+          field("from", meta?.windowStart ?? "n/a"),
+          field("to", meta?.windowEnd ?? "n/a"),
+          field("events", String(events.length))
+        )
+      }
+    ];
+    if (shown.length === 0) {
+      blocks.push({ kind: "text", text: "No scheduled reports in this window." });
+    } else {
+      blocks.push({
+        kind: "table",
+        head: ["DATE", "TICKER", "WHEN", "PERIOD", "EPS EST", "CONFIRMED"],
+        align: ["left", "left", "left", "left", "right", "left"],
+        rows: shown.map((event) => [
+          cell(event.earningsDate),
+          cell(event.ticker),
+          cell(TIME_LABEL[event.earningsTime] ?? event.earningsTime),
+          cell(event.fiscalQuarter ?? ""),
+          cell(fixed(event.estimatedEps)),
+          cell(event.confirmed ? "yes" : "no", event.confirmed ? "up" : "dim")
+        ])
+      });
+      if (!full && events.length > shown.length) {
+        blocks.push({
+          kind: "text",
+          text: `Showing ${shown.length} of ${events.length}. Add --full for the rest.`,
+          tone: "dim"
+        });
+      }
+    }
+    if (envelope.isPreview) {
+      blocks.push({
+        kind: "text",
+        text: "Preview response: a free key sees the current week, a PRO key sees about 30 days ahead.",
+        tone: "dim"
+      });
+    }
+    return { json: envelope, doc: doc(...blocks) };
+  }
+};
+
+// src/cli/commands/flows.ts
+var DEFAULT_ROWS = 10;
+function latestSettledQuarter(quarters) {
+  const dated = quarters.filter(
+    (q) => typeof q.reportDate === "string"
+  );
+  const newestFirst = [...dated].sort((a, b) => b.reportDate.localeCompare(a.reportDate));
+  const settled = newestFirst.find((q) => q.pending !== true);
+  return (settled ?? newestFirst[0])?.reportDate;
+}
+var flowsCommand = {
+  name: "flows",
+  summary: "Institutional 13F activity: market-wide flows, or one ticker's holders",
+  usage: "sentisense flows [ticker] [--limit N] [--quarter YYYY-MM-DD]",
+  examples: [
+    "sentisense flows",
+    "sentisense flows NVDA",
+    "sentisense flows NVDA --limit 25 --full",
+    "sentisense flows --json"
+  ],
+  notes: [
+    "With no ticker this is the quarter's biggest net share inflows and outflows across the",
+    "market. With a ticker it is that stock's institutional ownership and the quarter's",
+    "notable position changes, since flows are only published market-wide.",
+    "13F filings land up to 45 days after quarter end, so a still-open quarter shows only",
+    "early filers and says so, and a ticker reads the newest quarter that has closed.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
+  ],
+  flags: {
+    limit: { type: "number", placeholder: "N", describe: `Rows per side (default ${DEFAULT_ROWS})` },
+    quarter: { type: "string", placeholder: "YYYY-MM-DD", describe: "Report date to read" }
+  },
+  async run({ args, client, full }) {
+    const api = client();
+    const ticker = optionalTicker(args, "flows");
+    const notes = [];
+    const limit = typeof args.flags.limit === "number" ? args.flags.limit : DEFAULT_ROWS;
+    const quarter = typeof args.flags.quarter === "string" ? args.flags.quarter : void 0;
+    if (ticker) {
+      let reportDate = quarter;
+      if (!reportDate) {
+        reportDate = latestSettledQuarter(await api.institutional.getQuarters());
+      }
+      if (!reportDate) {
+        return {
+          json: { quarters: [] },
+          doc: doc({ kind: "text", text: "No reporting quarters are available yet." })
+        };
+      }
+      const envelope2 = await api.institutional.getHolders(ticker, reportDate, {
+        limit: full ? Math.max(limit, 50) : limit,
+        sortBy: "valueUsd",
+        sortDir: "desc"
+      });
+      const data2 = envelope2.data;
+      const holders = data2?.holders ?? [];
+      if (holders.length === 0) {
+        const note = await verifyTickerOnEmpty(api, ticker);
+        if (note) notes.push(note);
+      }
+      const blocks2 = [
+        {
+          kind: "head",
+          title: field("ticker", ticker),
+          subtitle: data2?.companyName ? field("name", data2.companyName) : void 0,
+          right: fields(
+            field("quarter", data2?.reportDate ?? reportDate),
+            field("holders", String(data2?.holderCount ?? holders.length)),
+            field("value", humanize(data2?.totalInstitutionalValue))
+          )
+        }
+      ];
+      if (holders.length === 0) {
+        blocks2.push({ kind: "text", text: "No institutional holders on file for this quarter." });
+      } else {
+        blocks2.push({
+          kind: "table",
+          head: ["FILER", "CATEGORY", "SHARES", "VALUE", "CHANGE", "CHANGE%"],
+          align: ["left", "left", "right", "right", "left", "right"],
+          rows: holders.map((holder) => [
+            cell(truncate(holder.filerName, full ? 44 : 28)),
+            cell(holder.filerCategory ?? ""),
+            cell(humanize(holder.shares, 1)),
+            cell(humanize(holder.valueUsd)),
+            cell(
+              holder.changeType,
+              holder.changeType === "NEW" || holder.changeType === "INCREASED" ? "up" : holder.changeType === "SOLD_OUT" || holder.changeType === "DECREASED" ? "down" : void 0
+            ),
+            cell(percent(holder.sharesChangePct, 1))
+          ])
+        });
+      }
+      const notable = data2?.notableChanges;
+      if (full && notable && notable.top.length > 0) {
+        blocks2.push({ kind: "blank" });
+        blocks2.push({
+          kind: "text",
+          text: `${notable.count} holders changed position materially this quarter. Top movers:`
+        });
+        blocks2.push({
+          kind: "table",
+          head: ["FILER", "CHANGE", "SHARES", "CHANGE%"],
+          align: ["left", "left", "right", "right"],
+          rows: notable.top.map((holder) => [
+            cell(truncate(holder.filerName, 44)),
+            cell(holder.changeType),
+            cell(humanize(holder.sharesChange, 1)),
+            cell(percent(holder.sharesChangePct, 1))
+          ])
+        });
+      }
+      if (envelope2.isPreview) {
+        blocks2.push({
+          kind: "text",
+          text: "Preview response: a PRO key returns the whole holder list.",
+          tone: "dim"
+        });
+      }
+      return { json: envelope2, doc: doc(...blocks2), notes };
+    }
+    const envelope = await api.institutional.getFlows(quarter, { limit });
+    const data = envelope.data;
+    const blocks = [
+      {
+        kind: "head",
+        title: field("scope", "Institutional flows"),
+        right: fields(
+          field("quarter", data?.reportDate ?? quarter ?? "latest"),
+          data?.isPending ? field("filers", `${data.filerCount ?? "?"} of ${data.baselineFilerCount ?? "?"}`) : void 0
+        )
+      }
+    ];
+    if (data?.isPending) {
+      blocks.push({
+        kind: "text",
+        text: "This quarter is still open, so only early filers are represented and the totals are partial.",
+        tone: "dim"
+      });
+    }
+    const side = (title, rows, tone) => {
+      blocks.push({ kind: "blank" });
+      blocks.push({ kind: "text", text: title });
+      blocks.push({
+        kind: "table",
+        head: ["TICKER", "COMPANY", "NET SHARES", "DOLLAR FLOW", "NEW", "SOLD OUT"],
+        align: ["left", "left", "right", "right", "right", "right"],
+        rows: rows.map((flow) => [
+          cell(flow.ticker),
+          cell(truncate(flow.companyName ?? "", full ? 40 : 26)),
+          cell(humanize(flow.netSharesChange, 1), tone),
+          cell(humanize(flow.dollarFlowUsd), tone),
+          cell(String(flow.newPositions)),
+          cell(String(flow.soldOutPositions))
+        ])
+      });
+    };
+    if (data?.inflows?.length) side("Largest net buying", data.inflows, "up");
+    if (data?.outflows?.length) side("Largest net selling", data.outflows, "down");
+    if (!data?.inflows?.length && !data?.outflows?.length) {
+      blocks.push({ kind: "text", text: "No flows recorded for this quarter." });
+    }
+    if (envelope.isPreview) {
+      blocks.push({
+        kind: "text",
+        text: "Preview response: a PRO key returns the full flow tables.",
+        tone: "dim"
+      });
+    }
+    return { json: envelope, doc: doc(...blocks) };
+  }
+};
+
+// src/version.ts
+var VERSION = "0.43.0";
+
+// src/resources/analyst.ts
+var Analyst = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get the aggregate Wall Street consensus for a ticker. Returns 404 if no
+   * coverage exists.
+   */
+  async consensus(ticker) {
+    return this.client.get(
+      `/api/v1/analyst/${encodeURIComponent(ticker.toUpperCase())}/consensus`
+    );
+  }
+  /**
+   * Get recent analyst upgrade/downgrade actions for a ticker, newest first.
+   * Free users receive the 3 most recent.
+   */
+  async actions(ticker, options) {
+    return this.client.get(
+      `/api/v1/analyst/${encodeURIComponent(ticker.toUpperCase())}/actions`,
+      options
+    );
+  }
+  /**
+   * Get forward EPS estimates and earnings surprise history for a ticker.
+   * Free users receive 1 estimate (current quarter) plus the 2 most recent surprises.
+   */
+  async estimates(ticker) {
+    return this.client.get(
+      `/api/v1/analyst/${encodeURIComponent(ticker.toUpperCase())}/estimates`
+    );
+  }
+  /**
+   * Get market-wide recent analyst actions across all covered tickers, newest first.
+   * Free users receive the 5 most recent.
+   */
+  async marketActivity(options) {
+    return this.client.get("/api/v1/analyst/activity", options);
+  }
+};
+
+// src/resources/calendar.ts
+var Calendar = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Upcoming company earnings, sorted by date.
+   *
+   * Key-required. A FREE key returns the current week (`isPreview: true`); a PRO
+   * key returns the full forward window (about 30 days). Field richness is
+   * identical across tiers: the gate is how far ahead you can see, not which
+   * columns you get. On a preview, `totalCount` is the full-window event count.
+   */
+  async getEarnings(options) {
+    return this.client.get("/api/v1/calendar/earnings", options);
+  }
+};
+
+// src/resources/documents.ts
+var Documents = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Get document metrics for a stock. The rows are in `documents`. */
+  async getByTicker(ticker, options) {
+    return this.client.get(`/api/v1/documents/ticker/${encodeURIComponent(ticker)}`, options);
+  }
+  /** Get document metrics for a stock within a date range. The rows are in `documents`. */
+  async getByTickerRange(ticker, options) {
+    return this.client.get(
+      `/api/v1/documents/ticker/${encodeURIComponent(ticker)}/range`,
+      options
+    );
+  }
+  /** Get document metrics for a KB entity. The rows are in `documents`. */
+  async getByEntity(entityId, options) {
+    return this.client.get(
+      `/api/v1/documents/entity/${encodeURIComponent(entityId)}`,
+      options
+    );
+  }
+  /** Smart search with natural language query parsing. The rows are in `documents`. */
+  async search(query, options) {
+    return this.client.get("/api/v1/documents/search", { query, ...options });
+  }
+  /** Get latest document metrics from a source type. The rows are in `documents`. */
+  async getBySource(source, options) {
+    return this.client.get(
+      `/api/v1/documents/source/${encodeURIComponent(source)}`,
+      options
+    );
+  }
+  /** Get AI-curated news story clusters. */
+  async getStories(options) {
+    return this.client.get("/api/v1/documents/stories", options);
+  }
+  /** Get full story detail by cluster ID. */
+  async getStoryDetail(clusterId) {
+    return this.client.get(`/api/v1/documents/stories/${encodeURIComponent(clusterId)}`);
+  }
+  /** Get stories for a specific stock. */
+  async getStoriesByTicker(ticker, options) {
+    return this.client.get(
+      `/api/v1/documents/stories/ticker/${encodeURIComponent(ticker)}`,
+      options
+    );
+  }
+};
+
+// src/resources/earnings.ts
+var Earnings = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Per-quarter earnings analysis report for one ticker, newest first.
+   *
+   * Each quarter carries the editorial headline, the KPI cards that matter for
+   * that company with year-over-year deltas, the guidance language as
+   * management phrased it, and a summary of the earnings call.
+   *
+   * Branch on `isPreview`: a PRO key receives every hydrated quarter in full, a
+   * FREE key receives the latest quarter shaped rather than truncated, plus
+   * `totalCount`. {@link EarningsQuarter} documents which fields each tier
+   * carries.
+   *
+   * A quarter typically appears within 48 hours of the company reporting, and
+   * the call summary can arrive after the press-release content for the same
+   * quarter, so read `generatedAt` and `transcriptGeneratedAt` rather than
+   * assuming a fixed lag. A ticker with no stored quarter answers with an empty
+   * `data` array, not a 404.
+   *
+   * Use canonical ticker symbols: `GOOGL` (not `GOOG`), `BRK.B` (not `BRK-B`).
+   */
+  async getSummaries(ticker, options) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/earnings-summaries`,
+      options
+    );
+  }
+  /**
+   * Which covered companies reported on or after `today - days`, newest first.
+   *
+   * Every API key receives the full window it asks for, so `isPreview` is
+   * always `false` here. The window is bounded by `reportDate`, so a quarter
+   * reported inside it appears even when its call summary lands later, and an
+   * empty `data` array means nobody in the covered set reported in that window.
+   *
+   * This is the backward-looking feed; `client.calendar.getEarnings()` is the
+   * forward-looking one.
+   */
+  async getRecent(options) {
+    return this.client.get("/api/v1/earnings/recent", options);
+  }
+};
+
+// src/resources/entityMetrics.ts
+var EntityMetrics = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get time-series metric data for an entity using the v2 Serving Metrics API.
+   *
+   * @param symbol   Ticker symbol (e.g. "AAPL") or entity urlSlug (e.g. "Nancy-Pelosi",
+   *                 case-insensitive; discover slugs via stocks.getEntities()).
+   * @param options  Metric type and optional time range / resolution.
+   */
+  async getMetrics(symbol, options = {}) {
+    const { metricType = "sentiment", startTime, endTime, maxDataPoints } = options;
+    return this.client.get(
+      `/api/v2/metrics/entity/${encodeURIComponent(symbol)}/metric/${encodeURIComponent(metricType)}`,
+      {
+        ...startTime !== void 0 && { startTime },
+        ...endTime !== void 0 && { endTime },
+        ...maxDataPoints !== void 0 && { maxDataPoints }
+      }
+    );
+  }
+  /**
+   * Get distribution data for a metric, broken down by a dimension (default: source).
+   *
+   * @param symbol     Ticker symbol (e.g. "AAPL") or entity urlSlug.
+   * @param metricType The metric to break down (e.g. "mentions", "sentiment").
+   * @param options    Optional dimension parameter.
+   */
+  async getDistribution(symbol, metricType, options = {}) {
+    const { dimension = "source" } = options;
+    return this.client.get(
+      `/api/v2/metrics/entity/${encodeURIComponent(symbol)}/distribution/${encodeURIComponent(metricType)}`,
+      { dimension }
+    );
+  }
+};
+
+// src/resources/etfs.ts
+var Etfs = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List every ETF tracked by SentiSense, sorted by ticker.
+   */
+  async list() {
+    return this.client.get("/api/v1/etfs");
+  }
+  /**
+   * Get the full holdings composition for an ETF, including per-holding weights
+   * and freshness metadata. Returns 404 for unknown ETFs or commodity-only funds.
+   */
+  async holdings(ticker) {
+    return this.client.get(
+      `/api/v1/etfs/${encodeURIComponent(ticker.toUpperCase())}/holdings`
+    );
+  }
+  /**
+   * Get the holdings-weighted analyst consensus for an ETF, including the
+   * top per-holding contributors that drive the weighted upside.
+   */
+  async analystAggregate(ticker) {
+    return this.client.get(
+      `/api/v1/etfs/${encodeURIComponent(ticker.toUpperCase())}/aggregates/analyst`
+    );
+  }
+  /**
+   * Get the holdings-weighted SEC Form 4 insider aggregate for an ETF over a
+   * configurable trailing window, including per-holding `topContributors` with
+   * signed contribution to the weighted headline.
+   */
+  async insiderAggregate(ticker, options) {
+    return this.client.get(
+      `/api/v1/etfs/${encodeURIComponent(ticker.toUpperCase())}/aggregates/insider`,
+      options
+    );
+  }
+  /**
+   * Get two SentiSense Score readings side-by-side: `constituentsWeighted`
+   * (precomputed daily weighted average across the fund's holdings) and `direct`
+   * (score from mentions of the fund's own ticker). The two can diverge, and the
+   * gap is itself information.
+   */
+  async sentimentAggregate(ticker) {
+    return this.client.get(
+      `/api/v1/etfs/${encodeURIComponent(ticker.toUpperCase())}/aggregates/sentiment`
+    );
+  }
+};
+
+// src/resources/insider.ts
+var Insider = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get market-wide insider activity: top buys and sells aggregated by ticker.
+   *
+   * PRO-gated. Free-tier users receive a preview (top 5 per direction)
+   * with `isPreview: true` in the response.
+   */
+  async getActivity(options) {
+    return this.client.get("/api/v1/insider/activity", options);
+  }
+  /**
+   * Get individual insider transactions for a specific stock.
+   *
+   * PRO-gated. Free users receive a preview of the top 5 transactions.
+   */
+  async getTrades(ticker, options) {
+    return this.client.get(
+      `/api/v1/insider/trades/${encodeURIComponent(ticker.toUpperCase())}`,
+      options
+    );
+  }
+  /**
+   * Get cluster buy signals: stocks where 3+ distinct insiders bought recently.
+   *
+   * PRO-gated. Free users receive a preview of the top 3 signals.
+   */
+  async getClusterBuys(options) {
+    return this.client.get("/api/v1/insider/cluster-buys", options);
+  }
+};
+
+// src/resources/politicians.ts
+var Politicians = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get recent congressional STOCK Act trading activity across all politicians.
+   *
+   * PRO-gated. Free-tier users receive a preview (top 5 trades)
+   * with `isPreview: true` in the response.
+   *
+   * The feed is longer than one response: a default 90-day window is routinely well over a
+   * thousand disclosures, and without `limit` the server sends the first 200 with no marker
+   * that it stopped. `totalCount` on the envelope is the real size on every tier, so page
+   * with `limit` and `offset` rather than reading `data.length` as the total.
+   *
+   * ```typescript
+   * const first = await client.politicians.getActivity({ limit: 100 });
+   * for (let offset = 100; offset < first.totalCount!; offset += 100) {
+   *   const page = await client.politicians.getActivity({ limit: 100, offset });
+   *   // ... page.data
+   * }
+   * ```
+   */
+  async getActivity(options) {
+    return this.client.get("/api/v1/politicians/activity", options);
+  }
+  /**
+   * Get congressional trades for a specific stock.
+   *
+   * PRO-gated. Free users receive a preview of the top 3 trades.
+   */
+  async getFilings(ticker, options) {
+    return this.client.get(
+      `/api/v1/politicians/filings/${encodeURIComponent(ticker.toUpperCase())}`,
+      options
+    );
+  }
+  /**
+   * Discover tracked members of Congress and the page slug identifying each, so you
+   * can find who to query without knowing slugs upfront.
+   *
+   * Summary only, no trade data; use `getMember` for a member's filings.
+   *
+   * Unlike `getMembers`, this includes members who have **left Congress**, carrying
+   * `former` and `servedUntil`. That roster lists who currently holds office, so a
+   * former member is otherwise reachable only if you already know their slug.
+   *
+   * Requires an API key but does not consume monthly quota (per-minute rate limits
+   * still apply), and is not tier-gated. Returns the unwrapped list payload.
+   */
+  async getDirectory(options) {
+    const resp = await this.client.get(
+      "/api/v1/politicians/directory",
+      { ...options }
+    );
+    return resp.data;
+  }
+  /**
+   * Get all tracked politicians with trading summary statistics.
+   *
+   * PRO-gated. Free users receive a preview of the top 5 members.
+   *
+   * Serves only members currently in office. Use `getDirectory` to enumerate
+   * everyone tracked, former members included.
+   */
+  async getMembers() {
+    return this.client.get("/api/v1/politicians/members");
+  }
+  /**
+   * Get detailed profile for a single politician: summary, recent trades, top tickers.
+   *
+   * PRO-gated. Free users receive a preview-wrapped response.
+   *
+   * `data.recentTrades` is one page of the member's history, not all of it. Most members
+   * have a few dozen disclosures and arrive complete in the default page; a handful have
+   * thousands. `totalCount` on the envelope is the size of the whole history on every
+   * tier, so page with `limit` and `offset` rather than reading `recentTrades.length` as
+   * the total. `data.profile` and `data.topTickers` describe the whole history whatever
+   * page you ask for, so `profile.totalTrades` does not shrink with a small `limit`.
+   *
+   * ```typescript
+   * const first = await client.politicians.getMember("Ro-Khanna", { limit: 500 });
+   * for (let offset = 500; offset < first.totalCount!; offset += 500) {
+   *   const page = await client.politicians.getMember("Ro-Khanna", { limit: 500, offset });
+   *   // ... page.data.recentTrades
+   * }
+   * ```
+   */
+  async getMember(slug, options) {
+    return this.client.get(
+      `/api/v1/politicians/member/${encodeURIComponent(slug)}`,
+      options
+    );
+  }
+};
+
+// src/resources/insights.ts
+var Insights = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get AI-generated insights for a specific stock, sorted by urgency then confidence.
+   *
+   * Returns the preview envelope: read the insights as `.data`. PRO callers get the
+   * full list with `isPreview: false`; free callers get the top 3 with `isPreview: true`
+   * and `totalCount` carrying the untruncated size.
+   */
+  async stock(ticker, options) {
+    return this.client.get(
+      `/api/v1/insights/stock/${encodeURIComponent(ticker.toUpperCase())}`,
+      options
+    );
+  }
+  /**
+   * Get AI insights for a stock within a date range.
+   *
+   * Returns the preview envelope: read the insights as `.data`. Free callers receive
+   * the top 3, PRO callers the full list. The server returns 400 if `startDate` is
+   * after `endDate`.
+   */
+  async stockRange(ticker, options) {
+    return this.client.get(
+      `/api/v1/insights/stock/${encodeURIComponent(ticker.toUpperCase())}/range`,
+      options
+    );
+  }
+  /**
+   * Get AI-generated market-level insights, sorted by urgency then confidence.
+   *
+   * Returns the preview envelope: read the insights as `.data`. PRO callers get the
+   * full list with `isPreview: false`; free callers get the top 5 with `isPreview: true`
+   * and `totalCount` carrying the untruncated size.
+   */
+  async market() {
+    return this.client.get("/api/v1/insights/market");
+  }
+  /**
+   * Get the latest AI insights across all tracked stocks, newest first.
+   *
+   * Returns the preview envelope: read the insights as `.data`. Free callers receive
+   * the top 5, PRO callers up to `limit` (clamped to 1-200).
+   */
+  async latest(options) {
+    return this.client.get("/api/v1/insights/latest", options);
+  }
+  /**
+   * Get personalized insights for the authenticated user.
+   *
+   * Biased toward the user's watchlist and portfolio when available; falls back
+   * to market-level insights otherwise. API key authentication required.
+   * Returns the preview envelope: read the insights as `.data`.
+   */
+  async user(options) {
+    return this.client.get("/api/v1/insights/user", options);
+  }
+  /**
+   * Get available insight types for a specific stock.
+   * API key required.
+   *
+   * Returns an array of insight type strings (e.g., `["sentiment_shift", "options_activity"]`).
+   */
+  async types(ticker) {
+    return this.client.get(
+      `/api/v1/insights/stock/${encodeURIComponent(ticker.toUpperCase())}/types`
+    );
+  }
+};
+
+// src/resources/institutional.ts
+var Institutional = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Get available 13F reporting quarters. */
+  async getQuarters() {
+    return this.client.get("/api/v1/institutional/quarters");
+  }
+  /**
+   * Get aggregate institutional activity per ticker for a quarter.
+   *
+   * `reportDate` is optional: omit it to get the latest available quarter, which may be
+   * a still-open one holding only early filers. The response then carries `reportDate`
+   * plus `isPending` and filer coverage counts so a partial quarter is clearly labeled.
+   *
+   * Returns the preview envelope, so the flows are one level down:
+   * `const { data } = await client.institutional.getFlows(); data.inflows`.
+   */
+  async getFlows(reportDate, options) {
+    return this.client.get("/api/v1/institutional/flows", {
+      reportDate,
+      ...options
+    });
+  }
+  /**
+   * Get institutional holders for a specific stock.
+   *
+   * Returns the preview envelope wrapping a {@link TickerHolders} object, so the rows
+   * are two levels down: `(await getHolders(t, d)).data.holders`, alongside ticker-level
+   * totals like `holderCount`. Free callers get a truncated `holders` array with
+   * `isPreview: true`.
+   *
+   * A widely held ticker returns thousands of rows: a megacap quarter is about
+   * 6,000 holders and 1.5 MB. Pass `limit` unless you really want all of them.
+   * Omitting `options` sends the original unbounded request.
+   *
+   * `limit` is the switch for the whole option set. With it, the response also carries
+   * `returnedCount`, `offset`, and a `notableChanges` summary, so you can walk the list
+   * without re-counting it. Without it, `offset` / `sortBy` / `sortDir` are ignored by the
+   * server and you get the full unsorted list back with a 200.
+   */
+  async getHolders(ticker, reportDate, options) {
+    return this.client.get(
+      `/api/v1/institutional/holders/${encodeURIComponent(ticker)}`,
+      { reportDate, ...options }
+    );
+  }
+  /**
+   * Get activist investor positions (NEW or INCREASED).
+   *
+   * Returns the preview envelope, so read the rows as `.data`.
+   */
+  async getActivists(reportDate) {
+    return this.client.get("/api/v1/institutional/activist", { reportDate });
+  }
+  /**
+   * Discover institutions: a paginated, AUM-ranked list of filers (slug + metadata)
+   * so you can find what to query without knowing slugs upfront.
+   *
+   * Each institution is rolled up by parent filer, so a multi-filer manager
+   * (e.g. Vanguard) appears once with combined AUM. Summary only; use
+   * `getInstitutionDetail` for a filer's full holdings.
+   *
+   * Requires an API key but does not consume monthly quota (per-minute rate
+   * limits still apply). Returns the unwrapped list payload.
+   */
+  async listInstitutions(options) {
+    const resp = await this.client.get(
+      "/api/v1/institutional/institutions",
+      { ...options }
+    );
+    return resp.data;
+  }
+  /**
+   * Get the full profile, summary stats, and current-quarter holdings for a
+   * specific institutional filer.
+   *
+   * Resolved by URL slug (e.g. `Berkshire-Hathaway`) or numeric SEC CIK.
+   * Free users receive the profile and top 10 holdings; PRO users receive the
+   * full holdings array. Returns 404 if the slug or CIK is unknown.
+   */
+  async getInstitutionDetail(slugOrCik) {
+    return this.client.get(
+      `/api/v1/institutional/institution/${encodeURIComponent(slugOrCik)}`
+    );
+  }
+};
+
+// src/resources/kb.ts
+var KB = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Get popular entities for search suggestions. */
+  async getPopularEntities() {
+    return this.client.get("/api/v1/kb/entities/popular");
+  }
+};
+
+// src/resources/marketMood.ts
+var MarketMoodResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Get market mood data (scores, history, sectors). */
+  async get() {
+    return this.client.get("/api/v2/market-mood");
+  }
+  // TODO: accept a `days` param to control history length (the endpoint supports ?days=N).
+  //
+  // Market Mood is also reachable through `client.indexes`, which serves it in the shared
+  // index envelope alongside fed-sentiment and ai-sentiment. Use this resource when you want
+  // the phase band, weekly change, per-signal breakdown and per-sector map; use `indexes`
+  // when you want every index to answer the same shape. Both report the same headline number.
+};
+
+// src/resources/marketSummary.ts
+var MarketSummaryResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** Get the AI-generated market summary with headline and analysis. */
+  async get() {
+    return this.client.get("/api/v1/market-summary");
+  }
+};
+
+// src/resources/screener.ts
+var Screener = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Every filterable field, with its unit, operators and description, for both
+   * universes.
+   *
+   * Build a filter UI from this rather than hardcoding the list and you inherit
+   * new fields as they ship. The ETF `STRING` fields (`ISSUER`, `ASSET_CLASS`,
+   * `TRACKED_INDEX`) come back with their `values` populated from the live
+   * universe, so pickers stay current without a redeploy.
+   */
+  async fields() {
+    return this.client.get("/api/v1/screener/fields");
+  }
+  /**
+   * The curated screens shipped in the product, each with a runnable plan.
+   *
+   * Each `plan` round-trips straight into {@link run} (or {@link runEtfs} when
+   * `plan.universe === "ETF"`) with nothing to rebuild.
+   *
+   * Their filters identify the field with `field` rather than `fieldName`.
+   * Both keys are accepted on the way in, so read either when inspecting a plan
+   * you did not build yourself.
+   */
+  async screens() {
+    return this.client.get("/api/v1/screener/screens");
+  }
+  /**
+   * Run a screen against the stock universe.
+   *
+   * `tickers` is optional: omit it to screen the whole tracked universe, pass a
+   * list to screen a watchlist. `limit` sits next to the plan rather than
+   * inside it, because a plan is a stored object and paging is a transport
+   * concern; it defaults to 100 and caps at 500.
+   *
+   * Read `matched` before you read `results`: it is the count before `limit`
+   * was applied, so a `matched` above your `limit` means you are holding the
+   * top slice under the plan's sort, not the whole answer.
+   *
+   * @example
+   * ```ts
+   * const res = await client.screener.run({
+   *   plan: {
+   *     filters: [
+   *       { fieldName: "SENTI_SCORE_7D", op: "GTE", value: 13 },
+   *       { fieldName: "ANALYST_BUY_RATIO_PCT", op: "LTE", value: 30 },
+   *       { fieldName: "ANALYST_COUNT", op: "GTE", value: 5 },
+   *     ],
+   *     sort: { fieldName: "SENTI_SCORE_7D", dir: "DESC" },
+   *   },
+   *   limit: 25,
+   * });
+   * ```
+   */
+  async run(options) {
+    return this.client.post("/api/v1/screener/execute", options);
+  }
+  /**
+   * Run a screen against the ETF universe.
+   *
+   * Same request shape as {@link run}, against a different field vocabulary:
+   * take the ETF names from `fields().etf`. `IN` / `NOT_IN` take a `values`
+   * array instead of `value` and are the operators for the string fields
+   * (`ISSUER`, `ASSET_CLASS`, `TRACKED_INDEX`).
+   *
+   * `CONSTITUENTS_WEIGHTED_SENTISENSE` is the holdings-weighted SentiSense
+   * Score across what the fund owns and is usually the one you want;
+   * `DIRECT_SENTISENSE` is the Score from chatter about the fund ticker itself,
+   * which on a broad index fund is mostly macro noise. `WEIGHT_COVERED_PCT`
+   * tells you how much of the fund's weight had constituent data behind the
+   * weighted number.
+   */
+  async runEtfs(options) {
+    return this.client.post("/api/v1/screener/etfs/execute", options);
+  }
+};
+
+// src/resources/stocks.ts
+var Stocks = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /** List all available ticker symbols. */
+  async list() {
+    return this.client.get("/api/v1/stocks");
+  }
+  /** List all stocks with name, kbEntityId, urlSlug. */
+  async listDetailed() {
+    return this.client.get("/api/v1/stocks/detailed");
+  }
+  /** Get popular ticker symbols. */
+  async listPopular() {
+    return this.client.get("/api/v1/stocks/popular");
+  }
+  /** Get popular stocks with details. */
+  async listPopularDetailed() {
+    return this.client.get("/api/v1/stocks/popular/detailed");
+  }
+  /** Get real-time price for a single ticker. */
+  async getPrice(ticker) {
+    return this.client.get("/api/v1/stocks/price", { ticker });
+  }
+  /**
+   * Get aggregate quote snapshot: live price, today OHLC, 52-week range,
+   * market cap, P/E, EPS TTM, and dividend yield in a single call.
+   * All fields except `ticker` may be null when upstream data is unavailable.
+   */
+  async getQuote(ticker) {
+    return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/quote`);
+  }
+  /** Get real-time prices for multiple tickers. */
+  async getPrices(tickers) {
+    return this.client.get("/api/v1/stocks/prices", {
+      tickers: tickers.join(",")
+    });
+  }
+  /** Get batch company logo URLs. */
+  async getImages(tickers, options) {
+    return this.client.get("/api/v1/stocks/images", {
+      tickers: tickers.join(","),
+      ...options
+    });
+  }
+  /** Get company profiles with branding, market cap, sector. */
+  async getDescriptions(tickers, options) {
+    return this.client.get("/api/v1/stocks/descriptions", {
+      tickers: tickers.join(","),
+      ...options
+    });
+  }
+  /** Get peer/similar stocks. */
+  async getSimilar(ticker, options) {
+    return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/similar`, options);
+  }
+  /** Get company profile (CEO, sector, industry, market data). */
+  async getProfile(ticker, options) {
+    return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/profile`, options);
+  }
+  /**
+   * Get the headline sentiment picture for a stock in one call.
+   *
+   * Returns the SentiSense Score with its 30-day regime, mention volume and social
+   * dominance, per-source tone in `bySource`, plus related tickers, story drivers, a
+   * narrative and an FAQ. Available in full on every API-key tier.
+   *
+   * Use `entityMetrics.getMetrics(ticker, "sentiment", ...)` instead when you need a time
+   * series over a specific window rather than the headline read. Returns 404 for tickers
+   * with no sentiment coverage.
+   */
+  async getSentiment(ticker) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker)}/sentiment`
+    );
+  }
+  /** Get related KB entities (people, products, partners). */
+  async getEntities(ticker) {
+    return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/entities`);
+  }
+  /**
+   * Get AI-generated stock analysis report. Requires PRO tier.
+   *
+   * `depth: "deep"` returns the full curated report and consumes one report view on
+   * metered tiers; the default `"basic"` returns the one-paragraph summary.
+   *
+   * The deprecated `forceRefresh` option is accepted and discarded, not forwarded.
+   */
+  async getAISummary(ticker, options) {
+    const { forceRefresh: _forceRefresh, ...params } = options ?? {};
+    return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/ai-summary`, params);
+  }
+  /** Get sentiment/mention metrics breakdown by entity. */
+  async getMetricsBreakdown(ticker, metricType, options) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker)}/metrics/${encodeURIComponent(metricType)}/breakdown`,
+      options
+    );
+  }
+  /**
+   * Get historical OHLCV chart data.
+   *
+   * The API returns a bare array of points; this normalizes it to
+   * `{ ticker, timeframe, data }`. `timeframe` echoes the requested value
+   * (defaulting to "1M", matching the server default when omitted).
+   */
+  async getChart(ticker, options) {
+    const data = await this.client.get("/api/v1/stocks/chart", {
+      ticker,
+      ...options
+    });
+    return { ticker, timeframe: options?.timeframe ?? "1M", data };
+  }
+  /** Get current market open/closed/pre-market/after-hours status. */
+  async getMarketStatus() {
+    return this.client.get("/api/v1/stocks/market-status");
+  }
+  /**
+   * Get financial statement data for one reporting period: income statement, balance sheet,
+   * and cash flow, including `capitalExpenditure` and `freeCashFlow`.
+   *
+   * Capital expenditure is signed as filed, so normally negative. See {@link Fundamentals}
+   * for the free-cash-flow relationship and when it is `null`.
+   */
+  async getFundamentals(ticker, options) {
+    return this.client.get("/api/v1/stocks/fundamentals", { ticker, ...options });
+  }
+  /** Get available fiscal periods. The periods are in `periods`. */
+  async getFundamentalsPeriods(ticker) {
+    return this.client.get("/api/v1/stocks/fundamentals/periods", { ticker });
+  }
+  /**
+   * Get the trailing-twelve-month fundamentals snapshot: TTM ratios, a different
+   * shape from the per-period statement data `getFundamentals()` returns.
+   */
+  async getCurrentFundamentals(ticker) {
+    return this.client.get("/api/v1/stocks/fundamentals/current", { ticker });
+  }
+  /** Get historical revenue data. */
+  async getHistoricalRevenue(ticker) {
+    return this.client.get("/api/v1/stocks/fundamentals/historical/revenue", { ticker });
+  }
+  /** Get short interest metrics (FINRA). */
+  async getShortInterest(ticker) {
+    return this.client.get("/api/v1/stocks/short-interest", { ticker });
+  }
+  /** Get float information. */
+  async getFloat(ticker) {
+    return this.client.get("/api/v1/stocks/float", { ticker });
+  }
+  /** Get short volume trading data. */
+  async getShortVolume(ticker) {
+    return this.client.get("/api/v1/stocks/short-volume", { ticker });
+  }
+  /**
+   * Get company-specific KPI time-series for a ticker. Returns curated GAAP and
+   * non-GAAP metrics from earnings filings (e.g. iPhone unit sales, Tesla deliveries,
+   * AWS revenue).
+   *
+   * Free users receive metadata only with an empty `kpis` list; PRO users receive
+   * the full series. Returns 404 for tickers that do not yet have curated coverage.
+   *
+   * Coverage today: near-complete for the S&P 500 plus extended universe
+   * (~500 tickers). Use `listKpiCoverage()` to enumerate.
+   */
+  async getKpis(ticker) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/kpis`
+    );
+  }
+  /**
+   * List every ticker with curated KPI coverage. Returns `{count, tickers: [...]}`
+   * with lightweight metadata (ticker, companyName, lastUpdated, kpiCount).
+   * Sorted alphabetically by ticker.
+   *
+   * Auth: API key required, but the call does NOT consume your monthly quota
+   * (rate-limit-per-minute still applies).
+   */
+  async listKpiCoverage() {
+    return this.client.get("/api/v1/stocks/with-kpis");
+  }
+  /**
+   * List the KPI metadata tuples available for a ticker (`id, name, category,
+   * chartType`) without paying the cost of the full series payload. Mirrors
+   * the `/api/v1/insights/stock/{ticker}/types` precedent.
+   *
+   * Auth: API key required, no quota cost. 404 if the ticker has no curated KPIs.
+   */
+  async getKpiTypes(ticker) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/kpis/types`
+    );
+  }
+  /**
+   * Get the end-of-day options dossier for one stock or ETF: the session's aggregate, its
+   * percentile context, the open-interest wall structure with max pain, and the contracts
+   * whose volume ran far ahead of their open interest.
+   *
+   * End of day, not live. `asOf` is the prior trading session and the data refreshes the
+   * following morning, so this is positioning, not a quote feed.
+   *
+   * **`data` is `null` for a ticker outside the covered universe**, which is the most
+   * actively optioned US names plus the tracked ETFs, and for a covered ticker with no
+   * snapshot yet. An unknown symbol behaves the same way rather than answering 404, so treat
+   * a null as "no coverage", never as an error. A covered ticker still building its baseline
+   * returns its raw readings with the percentiles omitted.
+   *
+   * Percentiles compare a ticker to its own trailing history, never to another ticker, so an
+   * ETF's readings are not comparable with a single stock's.
+   *
+   * Tiering: a PRO key always receives the full dossier. A FREE key receives it for the first
+   * ten calls each calendar month and a headline-only preview after that, with `isPreview`
+   * true; calls that return a null `data` never spend that allowance.
+   */
+  async getOptionsSummary(ticker) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/options/summary`
+    );
+  }
+};
+
+// src/resources/indexes.ts
+var Indexes = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List every index the platform publishes: id, display name, one-line
+   * description, the scale it lives on, its access tier, and where its richest
+   * view lives.
+   *
+   * Iterate this rather than hardcoding ids. Every `indexId` it advertises
+   * resolves on {@link get} and {@link history}.
+   */
+  async list() {
+    return this.client.get("/api/v1/indexes");
+  }
+  /**
+   * Latest reading for one index.
+   *
+   * Check `constituents` for `null` before iterating: it is `null` on a
+   * composite index like `market-mood`, which has no constituents by
+   * construction. For Market Mood this is the narrowed view; the phase band,
+   * weekly change, per-signal breakdown and per-sector map live on
+   * `client.marketMood.get()`, and both report the same headline number.
+   *
+   * @param indexId slug from {@link list}, e.g. `"fed-sentiment"`.
+   */
+  async get(indexId) {
+    return this.client.get(`/api/v1/indexes/${indexId}`);
+  }
+  /**
+   * Historical scalar series for one index, for charting.
+   *
+   * Thin or low-coverage buckets are withheld, so the series can be shorter
+   * than `days` and can contain gaps. Plot against each point's `date`.
+   *
+   * @param indexId slug from {@link list}.
+   * @param days days of history to return. Defaults to the API's own 180.
+   */
+  async history(indexId, days) {
+    return this.client.get(
+      `/api/v1/indexes/${indexId}/history`,
+      days === void 0 ? void 0 : { days }
+    );
+  }
+};
+
+// src/resources/trackers.ts
+var Trackers = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List every publicly-visible tracker: id, display name, category,
+   * one-line description, and the methodology anchor to link out to.
+   */
+  async list() {
+    return this.client.get("/api/v1/trackers");
+  }
+  /**
+   * Standardized snapshot envelope for one tracker.
+   *
+   * Returns the envelope as-is: `{ isPreview, previewReason, totalCount?, data }`.
+   * When `data.viewType === "table"` the rows live at `data.rows[]`; when
+   * `"choropleth"` they live at `data.geo[]`; etc. Dispatch on `viewType`
+   * in your renderer.
+   *
+   * @param trackerId slug from {@link list}, e.g. `"institution-concentration"`.
+   * @param params provider-specific query params (e.g. `{ scope: "us" }` for
+   *   geographically-scoped trackers like hantavirus). Unknown keys are ignored.
+   */
+  async get(trackerId, params) {
+    return this.client.get(`/api/v1/trackers/${trackerId}`, params);
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://app.sentisense.ai";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var BASE_DELAY_MS = 1e3;
+var MAX_DELAY_MS = 6e4;
+var DEEP_HISTORY_FALLBACK_WAIT_S = 3;
+var MAX_DEEP_HISTORY_WAIT_S = 30;
+var MAX_RATE_LIMIT_WAIT_S = 120;
+var RATE_LIMIT_FALLBACK_WAIT_S = 60;
+function clampRetryAfter(raw, maxWaitS) {
+  if (!raw) return void 0;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return void 0;
+  return Math.min(Math.max(0.5, parsed), maxWaitS);
+}
+function retryAfterSeconds(raw, defaultS, maxWaitS) {
+  return clampRetryAfter(raw, maxWaitS) ?? defaultS;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+var SentiSense = class {
+  constructor(options = {}) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const suffix = options.userAgentSuffix?.replace(/[\r\n]+/g, " ").trim();
+    this.userAgent = suffix ? `sentisense-node/${VERSION} ${suffix}` : `sentisense-node/${VERSION}`;
+    this.stocks = new Stocks(this);
+    this.documents = new Documents(this);
+    this.etfs = new Etfs(this);
+    this.institutional = new Institutional(this);
+    this.insider = new Insider(this);
+    this.politicians = new Politicians(this);
+    this.insights = new Insights(this);
+    this.analyst = new Analyst(this);
+    this.entityMetrics = new EntityMetrics(this);
+    this.marketMood = new MarketMoodResource(this);
+    this.marketSummary = new MarketSummaryResource(this);
+    this.kb = new KB(this);
+    this.indexes = new Indexes(this);
+    this.trackers = new Trackers(this);
+    this.calendar = new Calendar(this);
+    this.earnings = new Earnings(this);
+    this.screener = new Screener(this);
+  }
+  /** @internal */
+  async get(path, params) {
+    const url = this.buildUrl(path, params);
+    const headers = {
+      "Accept": "application/json"
+    };
+    if (this.apiKey) {
+      headers["X-SentiSense-API-Key"] = this.apiKey;
+    }
+    if (typeof process !== "undefined" && process.versions?.node) {
+      headers["User-Agent"] = this.userAgent;
+    }
+    let delayMs = 0;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      if (delayMs > 0) {
+        await sleep(delayMs);
+        delayMs = 0;
+      }
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(url, {
+          method: "GET",
+          headers,
+          signal: controller.signal
+        });
+        if (response.status === 202) {
+          const waitSeconds = retryAfterSeconds(
+            response.headers.get("Retry-After"),
+            DEEP_HISTORY_FALLBACK_WAIT_S,
+            MAX_DEEP_HISTORY_WAIT_S
+          );
+          try {
+            await response.body?.cancel();
+          } catch {
+          }
+          if (attempt < this.maxRetries) {
+            delayMs = waitSeconds * 1e3;
+            continue;
+          }
+          throw new DeepHistoryUnavailableError(
+            "Deep history is still being assembled. Retry in a few seconds.",
+            waitSeconds
+          );
+        }
+        if (!response.ok) {
+          const isRetryable = response.status === 429 || response.status >= 500;
+          if (isRetryable && attempt < this.maxRetries) {
+            if (response.status === 429) {
+              delayMs = retryAfterSeconds(
+                response.headers.get("Retry-After"),
+                RATE_LIMIT_FALLBACK_WAIT_S,
+                MAX_RATE_LIMIT_WAIT_S
+              ) * 1e3;
+            } else {
+              delayMs = Math.min(BASE_DELAY_MS * Math.pow(2, attempt), MAX_DELAY_MS) + Math.random() * 1e3;
+            }
+            try {
+              await response.body?.cancel();
+            } catch {
+            }
+            continue;
+          }
+          await this.handleErrorResponse(response);
+        }
+        return await response.json();
+      } catch (error) {
+        if (error instanceof SentiSenseError) throw error;
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new SentiSenseError(`Request timed out after ${this.timeout}ms`);
+        }
+        throw new SentiSenseError(
+          error instanceof Error ? error.message : "Unknown error"
+        );
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    throw new SentiSenseError("All retries exhausted");
+  }
+  /** @internal */
+  async post(path, body) {
+    const url = this.buildUrl(path);
+    const headers = {
+      "Accept": "application/json",
+      "Content-Type": "application/json"
+    };
+    if (this.apiKey) {
+      headers["X-SentiSense-API-Key"] = this.apiKey;
+    }
+    if (typeof process !== "undefined" && process.versions?.node) {
+      headers["User-Agent"] = this.userAgent;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+      return await response.json();
+    } catch (error) {
+      if (error instanceof SentiSenseError) throw error;
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new SentiSenseError(`Request timed out after ${this.timeout}ms`);
+      }
+      throw new SentiSenseError(
+        error instanceof Error ? error.message : "Unknown error"
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  buildUrl(path, params) {
+    const url = new URL(path, this.baseUrl);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0 && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    return url.toString();
+  }
+  async handleErrorResponse(response) {
+    let body = {};
+    try {
+      body = await response.json();
+    } catch {
+    }
+    const message = body.message ?? response.statusText ?? "API request failed";
+    const code = body.error;
+    switch (response.status) {
+      case 401:
+      case 403:
+        throw new AuthenticationError(message, response.status, code);
+      case 404:
+        throw new NotFoundError(message, code);
+      case 429: {
+        const retryAfter = clampRetryAfter(
+          response.headers.get("Retry-After"),
+          MAX_RATE_LIMIT_WAIT_S
+        );
+        throw new RateLimitError(message, code, retryAfter);
+      }
+      default:
+        throw new APIError(message, response.status, code);
+    }
+  }
+};
+
+// src/cli/parse.ts
+var GLOBAL_FLAGS = {
+  json: { type: "boolean", describe: "Print the exact API response as JSON" },
+  plain: { type: "boolean", describe: "Force plain text with no colour" },
+  pretty: { type: "boolean", describe: "Force the terminal layout" },
+  "no-color": { type: "boolean", describe: "Drop colour from the terminal layout" },
+  full: { type: "boolean", describe: "Show more rows and more detail" },
+  debug: { type: "boolean", describe: "Print stack traces on failure" },
+  help: { type: "boolean", describe: "Show help for this command" },
+  version: { type: "boolean", describe: "Print the version" },
+  "api-key": { type: "string", placeholder: "key", describe: "API key for this call only" },
+  "base-url": { type: "string", placeholder: "url", describe: "Override the API base URL" },
+  agent: {
+    type: "string",
+    placeholder: "name",
+    describe: "Label this call in the User-Agent"
+  }
+};
+var SHORT_FLAGS = {
+  "-h": "--help",
+  "-v": "--version"
+};
+function editDistance(a, b) {
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  let previous = Array.from({ length: cols }, (_, i) => i);
+  for (let i = 1; i < rows; i++) {
+    const current = [i];
+    for (let j = 1; j < cols; j++) {
+      current[j] = Math.min(
+        previous[j] + 1,
+        current[j - 1] + 1,
+        previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+    }
+    previous = current;
+  }
+  return previous[cols - 1];
+}
+function nearest(word, candidates) {
+  let best;
+  let bestScore = Number.POSITIVE_INFINITY;
+  for (const candidate of candidates) {
+    const score = editDistance(word.toLowerCase(), candidate.toLowerCase());
+    if (score < bestScore) {
+      bestScore = score;
+      best = candidate;
+    }
+  }
+  const budget = Math.max(2, Math.floor(word.length / 3));
+  return best !== void 0 && bestScore <= budget ? best : void 0;
+}
+function splitCommand(argv) {
+  const first = argv[0];
+  if (first === void 0) return { rest: [] };
+  if (first.startsWith("-")) return { rest: argv };
+  return { command: first, rest: argv.slice(1) };
+}
+function parseArgs(argv, specs) {
+  const positionals = [];
+  const flags = {};
+  const names = Object.keys(specs);
+  for (let i = 0; i < argv.length; i++) {
+    let token = argv[i];
+    if (token === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (SHORT_FLAGS[token]) token = SHORT_FLAGS[token];
+    if (!token.startsWith("--")) {
+      if (token.startsWith("-") && token.length > 1 && !/^-\d/.test(token)) {
+        throw new CliUsageError(
+          `unknown flag "${token}".`,
+          'run "sentisense --help" for the flag list.'
+        );
+      }
+      positionals.push(token);
+      continue;
+    }
+    const equals = token.indexOf("=");
+    const name = equals === -1 ? token.slice(2) : token.slice(2, equals);
+    const inline = equals === -1 ? void 0 : token.slice(equals + 1);
+    const spec = specs[name];
+    if (!spec) {
+      const suggestion = nearest(name, names);
+      throw new CliUsageError(
+        `unknown flag "--${name}".`,
+        suggestion ? `did you mean "--${suggestion}"?` : 'run "sentisense help <command>" for the flags it accepts.'
+      );
+    }
+    if (spec.type === "boolean") {
+      if (inline !== void 0 && inline !== "true" && inline !== "false") {
+        throw new CliUsageError(
+          `--${name} is a switch and takes no value.`,
+          `drop the "=${inline}".`
+        );
+      }
+      flags[name] = inline !== "false";
+      continue;
+    }
+    const raw = inline ?? argv[++i];
+    if (raw === void 0 || inline === void 0 && raw.startsWith("--")) {
+      throw new CliUsageError(
+        `--${name} needs a value.`,
+        `for example: --${name} ${spec.placeholder ?? "value"}`
+      );
+    }
+    if (spec.type === "number") {
+      const value = Number(raw);
+      if (!Number.isFinite(value)) {
+        throw new CliUsageError(
+          `--${name} expects a number, got "${raw}".`,
+          `for example: --${name} 30`
+        );
+      }
+      flags[name] = value;
+      continue;
+    }
+    if (spec.repeat) {
+      const existing = Array.isArray(flags[name]) ? flags[name] : [];
+      flags[name] = [...existing, raw];
+    } else {
+      flags[name] = raw;
+    }
+  }
+  return { positionals, flags };
+}
+function flagString(flags, name) {
+  const value = flags[name];
+  return typeof value === "string" ? value : void 0;
+}
+function flagList(flags, name) {
+  const value = flags[name];
+  if (Array.isArray(value)) return value;
+  return typeof value === "string" ? [value] : [];
+}
+
+// src/cli/context.ts
+function resolveContext({ flags, env, configDir }) {
+  const dir = resolveConfigDir(env, configDir);
+  const stored = readConfig(dir);
+  const pick = (flagValue, envValue, configValue) => {
+    if (flagValue) return { value: flagValue, source: "flag" };
+    if (envValue && envValue.trim()) return { value: envValue.trim(), source: "env" };
+    if (configValue) return { value: configValue, source: "config" };
+    return { source: "default" };
+  };
+  const key = pick(flagString(flags, "api-key"), env.SENTISENSE_API_KEY, stored.apiKey);
+  const base = pick(flagString(flags, "base-url"), env.SENTISENSE_BASE_URL, stored.baseUrl);
+  const agent = pick(flagString(flags, "agent"), env.SENTISENSE_AGENT_NAME, stored.agentName);
+  return {
+    configDir: dir,
+    apiKey: key.value,
+    apiKeySource: key.source,
+    baseUrl: base.value,
+    baseUrlSource: base.source,
+    agentName: agent.value,
+    agentSource: agent.source
+  };
+}
+var DEFAULT_BASE_URL2 = "https://app.sentisense.ai";
+function effectiveBaseUrl(context) {
+  return context.baseUrl ?? DEFAULT_BASE_URL2;
+}
+function sanitizeAgent(name) {
+  return name.trim().replace(/\s+/g, "-").replace(/[^A-Za-z0-9._-]/g, "");
+}
+function userAgentSuffix(context) {
+  const parts = [`sentisense-cli/${VERSION}`];
+  const agent = context.agentName ? sanitizeAgent(context.agentName) : "";
+  if (agent) parts.push(`agent/${agent}`);
+  return parts.join(" ");
+}
+function createClient(context, options = {}) {
+  if (!options.anonymous && !context.apiKey) throw new MissingKeyError();
+  return new SentiSense({
+    apiKey: options.anonymous ? void 0 : context.apiKey,
+    baseUrl: context.baseUrl,
+    maxRetries: 0,
+    userAgentSuffix: userAgentSuffix(context)
+  });
+}
+
+// src/cli/commands/health.ts
+async function probe(run) {
+  const started = Date.now();
+  try {
+    await run();
+    return { ok: true, detail: "ok", latencyMs: Date.now() - started };
+  } catch (error) {
+    const latencyMs = Date.now() - started;
+    if (error instanceof AuthenticationError) {
+      return { ok: false, detail: `rejected (${error.status ?? 401})`, latencyMs };
+    }
+    if (error instanceof SentiSenseError && error.status === void 0) {
+      return { ok: false, detail: `unreachable: ${error.message}`, latencyMs };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, detail: message, latencyMs };
+  }
+}
+var healthCommand = {
+  name: "health",
+  summary: "Check that the API is reachable and the key works",
+  usage: "sentisense health",
+  examples: ["sentisense health", "sentisense health --json"],
+  notes: [
+    "Run this first on a new machine. It answers three questions in one call each:",
+    "is the host up, is the key accepted, and how slow is the round trip.",
+    "Exits 3 when the key is missing or rejected, 6 when the host cannot be reached."
+  ],
+  flags: {},
+  async run({ args, context }) {
+    rejectPositionals(args, "health");
+    const baseUrl = effectiveBaseUrl(context);
+    const anonymous = createClient(context, { anonymous: true });
+    const reach = await probe(() => anonymous.stocks.getMarketStatus());
+    const reachable = reach.ok || reach.detail.startsWith("rejected");
+    let keyState;
+    if (!context.apiKey) {
+      keyState = { ok: false, detail: "not configured" };
+    } else if (!reachable) {
+      keyState = { ok: false, detail: "not checked" };
+    } else {
+      const keyed = createClient(context);
+      keyState = await probe(() => keyed.stocks.getMarketStatus());
+    }
+    const exitCode = !reachable ? EXIT.NETWORK : keyState.ok ? EXIT.OK : EXIT.AUTH;
+    const latency = keyState.latencyMs ?? reach.latencyMs;
+    const nextStep = !reachable ? `check the network and the base URL (${baseUrl}).` : !context.apiKey ? `run "sentisense auth <key>", or set SENTISENSE_API_KEY. Get a key at ${KEY_URL}` : keyState.ok ? void 0 : `the stored key was refused. Replace it with "sentisense auth <key>" or get a new one at ${KEY_URL}`;
+    return {
+      exitCode,
+      json: {
+        ok: exitCode === EXIT.OK,
+        baseUrl,
+        reachable,
+        apiKey: context.apiKey ? maskKey(context.apiKey) : null,
+        apiKeySource: context.apiKeySource,
+        apiKeyValid: keyState.ok,
+        latencyMs: latency ?? null,
+        cliVersion: VERSION,
+        sdkVersion: VERSION
+      },
+      doc: doc(
+        {
+          kind: "kv",
+          items: [
+            field(
+              "reachable",
+              reachable ? "yes" : reach.detail,
+              reachable ? "up" : "down"
+            ),
+            field(
+              "api key",
+              keyState.ok ? `ok (${context.apiKey ? maskKey(context.apiKey) : ""})` : keyState.detail,
+              keyState.ok ? "up" : "down"
+            ),
+            field("latency", latency === void 0 ? "n/a" : `${latency} ms`),
+            field("base url", baseUrl),
+            field("cli", `sentisense-cli/${VERSION}`),
+            field("sdk", `sentisense-node/${VERSION}`)
+          ]
+        },
+        nextStep ? { kind: "text", text: `next: ${nextStep}` } : void 0
+      )
+    };
+  }
+};
+
+// src/cli/commands/insiders.ts
+var insidersCommand = {
+  name: "insiders",
+  summary: "Form 4 insider transactions for one ticker",
+  usage: "sentisense insiders <ticker> [--days N]",
+  examples: [
+    "sentisense insiders NVDA",
+    "sentisense insiders NVDA --days 180 --full",
+    "sentisense insiders NVDA --json"
+  ],
+  notes: [
+    "Rows are individual filed transactions, newest first, not a net total.",
+    "The plan column says whether the trade was under a confirmed pre-arranged 10b5-1 plan,",
+    "which is the difference between a scheduled sale and a discretionary one.",
+    "A free key sees the top few transactions; a PRO key sees the window you asked for.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
+  ],
+  flags: {
+    days: { type: "number", placeholder: "N", describe: "Look-back window, 1 to 365 (default 90)" }
+  },
+  async run({ args, client, full }) {
+    const ticker = oneTicker(args, "insiders");
+    const lookbackDays = typeof args.flags.days === "number" ? args.flags.days : void 0;
+    const api = client();
+    const notes = [];
+    const envelope = await api.insider.getTrades(
+      ticker,
+      lookbackDays === void 0 ? void 0 : { lookbackDays }
+    );
+    const trades = envelope.data ?? [];
+    if (trades.length === 0) {
+      const note = await verifyTickerOnEmpty(api, ticker);
+      if (note) notes.push(note);
+    }
+    const shown = full ? trades : trades.slice(0, 15);
+    const buys = trades.filter((trade) => trade.transactionType === "BUY");
+    const sells = trades.filter((trade) => trade.transactionType === "SELL");
+    const sum = (rows) => rows.reduce((total, row) => total + (row.totalValue || 0), 0);
+    const blocks = [
+      {
+        kind: "head",
+        title: field("ticker", ticker),
+        right: fields(
+          field("trades", String(trades.length)),
+          field("bought", humanize(sum(buys)), buys.length > 0 ? "up" : void 0),
+          field("sold", humanize(sum(sells)), sells.length > 0 ? "down" : void 0)
+        )
+      }
+    ];
+    if (shown.length === 0) {
+      blocks.push({ kind: "text", text: "No filed insider transactions in this window." });
+    } else {
+      blocks.push({
+        kind: "table",
+        head: ["DATE", "INSIDER", "ROLE", "TYPE", "SHARES", "VALUE", "PLAN"],
+        align: ["left", "left", "left", "left", "right", "right", "left"],
+        rows: shown.map((trade) => [
+          cell(trade.transactionDate),
+          cell(truncate(trade.insiderName, full ? 40 : 22)),
+          cell(truncate(trade.insiderTitle ?? "", full ? 40 : 18)),
+          cell(
+            trade.transactionType,
+            trade.transactionType === "BUY" ? "up" : trade.transactionType === "SELL" ? "down" : void 0
+          ),
+          cell(humanize(trade.sharesTransacted, 1)),
+          cell(humanize(trade.totalValue)),
+          cell(trade.rule10b51 ? "10b5-1" : "")
+        ])
+      });
+      if (!full && trades.length > shown.length) {
+        blocks.push({
+          kind: "text",
+          text: `Showing ${shown.length} of ${trades.length}. Add --full for the rest.`,
+          tone: "dim"
+        });
+      }
+    }
+    if (envelope.isPreview) {
+      blocks.push({
+        kind: "text",
+        text: `Preview response: ${envelope.totalCount ?? "more"} transactions exist, a PRO key returns them all.`,
+        tone: "dim"
+      });
+    }
+    return { json: envelope, doc: doc(...blocks), notes };
+  }
+};
+
+// src/cli/commands/insights.ts
+function urgencyTone(urgency) {
+  if (urgency === "high") return "accent";
+  if (urgency === "low") return "dim";
+  return void 0;
+}
+var insightsCommand = {
+  name: "insights",
+  summary: "Generated signals for one ticker, most urgent first",
+  usage: "sentisense insights <ticker> [--urgency low|medium|high] [--type <name>]",
+  examples: [
+    "sentisense insights NVDA",
+    "sentisense insights NVDA --urgency high",
+    "sentisense insights NVDA --type institutional_position_change --full"
+  ],
+  notes: [
+    "Signals are generated observations about filings, flows, and attention, ordered by",
+    "urgency then confidence. They describe what the data shows, not what to do about it.",
+    "A free key sees the top three; a PRO key sees the whole list.",
+    "Signal types vary by ticker and over time, so take --type from what a plain run reports",
+    "rather than guessing a name.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
+  ],
+  flags: {
+    urgency: { type: "string", placeholder: "level", describe: "Filter to low, medium, or high" },
+    type: { type: "string", placeholder: "name", describe: "Filter to one signal type" }
+  },
+  async run({ args, client, full }) {
+    const ticker = oneTicker(args, "insights");
+    const urgency = typeof args.flags.urgency === "string" ? args.flags.urgency : void 0;
+    if (urgency && !["low", "medium", "high"].includes(urgency)) {
+      throw new CliUsageError(
+        `--urgency takes low, medium, or high, got "${urgency}".`,
+        "for example: --urgency high"
+      );
+    }
+    const options = {
+      ...urgency ? { urgency } : {},
+      ...typeof args.flags.type === "string" ? { insightType: args.flags.type } : {}
+    };
+    const api = client();
+    const notes = [];
+    const envelope = await api.insights.stock(
+      ticker,
+      Object.keys(options).length > 0 ? options : void 0
+    );
+    const insights = envelope.data ?? [];
+    if (insights.length === 0) {
+      const note = await verifyTickerOnEmpty(api, ticker);
+      if (note) notes.push(note);
+    }
+    const shown = full ? insights : insights.slice(0, 8);
+    const blocks = [
+      {
+        kind: "head",
+        title: field("ticker", ticker),
+        right: fields(
+          field("signals", String(insights.length)),
+          envelope.totalCount === void 0 ? void 0 : field("available", String(envelope.totalCount))
+        )
+      }
+    ];
+    if (shown.length === 0) {
+      blocks.push({ kind: "text", text: "No signals match that filter right now." });
+    } else if (full) {
+      for (const insight of shown) {
+        blocks.push({ kind: "blank" });
+        blocks.push({
+          kind: "head",
+          title: field("type", insight.insightType),
+          right: fields(
+            field("urgency", insight.urgency, urgencyTone(insight.urgency)),
+            field("confidence", percent(insight.confidence * 100, 0)),
+            field("generated", dateFromSeconds(insight.generatedAt))
+          )
+        });
+        blocks.push({ kind: "text", text: insight.insightText });
+      }
+    } else {
+      blocks.push({
+        kind: "table",
+        head: ["URGENCY", "CONF", "TYPE", "SIGNAL"],
+        align: ["left", "right", "left", "left"],
+        rows: shown.map((insight) => [
+          cell(insight.urgency, urgencyTone(insight.urgency)),
+          cell(percent(insight.confidence * 100, 0)),
+          cell(insight.insightType),
+          cell(truncate(insight.insightText, 60))
+        ])
+      });
+      blocks.push({
+        kind: "text",
+        text: "Add --full for the complete text of each signal.",
+        tone: "dim"
+      });
+    }
+    if (envelope.isPreview) {
+      blocks.push({
+        kind: "text",
+        text: "Preview response: a PRO key returns every signal.",
+        tone: "dim"
+      });
+    }
+    return { json: envelope, doc: doc(...blocks), notes };
+  }
+};
+
+// src/cli/commands/mood.ts
+function readMarket(payload) {
+  if (!payload || typeof payload !== "object") return {};
+  const market = payload.market;
+  return market && typeof market === "object" ? market : {};
+}
+function readSectors(payload) {
+  if (!payload || typeof payload !== "object") return [];
+  const sectors = payload.sectors;
+  if (!sectors || typeof sectors !== "object") return [];
+  return Object.entries(sectors).sort(
+    (a, b) => (b[1]?.currentScore ?? 0) - (a[1]?.currentScore ?? 0)
+  );
+}
+var moodCommand = {
+  name: "mood",
+  summary: "Composite market sentiment, its signals, and the sector map",
+  usage: "sentisense mood",
+  examples: ["sentisense mood", "sentisense mood --full", "sentisense mood --json"],
+  notes: [
+    "One 0 to 100 score for the whole market, with the six signals behind it and a",
+    "per-sector breakdown. Bands: 0-15 extreme fear, 16-30 fear, 31-45 anxiety,",
+    "46-55 neutral, 56-70 optimism, 71-85 greed, 86-100 extreme greed."
+  ],
+  flags: {},
+  async run({ args, client, full }) {
+    rejectPositionals(args, "mood");
+    const payload = await client().marketMood.get();
+    const market = readMarket(payload);
+    const sectors = readSectors(payload);
+    const history = (market.history ?? []).map((point) => point?.score).filter((score) => typeof score === "number" && Number.isFinite(score));
+    const blocks = [
+      {
+        kind: "head",
+        title: field("index", "Market Mood"),
+        right: fields(
+          field("score", fixed(market.currentScore, 1), "accent"),
+          market.phase ? field("phase", String(market.phase)) : void 0,
+          field(
+            "weekly change",
+            `${signed(market.weeklyChange, 1)} wk`,
+            direction(market.weeklyChange)
+          )
+        )
+      }
+    ];
+    const signals = market.signals ?? [];
+    if (signals.length > 0) {
+      blocks.push({
+        kind: "facts",
+        items: signals.map(
+          (signal) => field(signal.label ?? signal.key ?? "signal", fixed(signal.value, 1))
+        )
+      });
+    }
+    if (history.length > 0) {
+      const tail = full ? history : history.slice(-60);
+      blocks.push({
+        kind: "spark",
+        label: `${tail.length}d`,
+        series: tail,
+        note: market.history?.[market.history.length - 1]?.date ? `to ${market.history[market.history.length - 1].date}` : void 0
+      });
+    }
+    if (sectors.length > 0) {
+      blocks.push({ kind: "blank" });
+      blocks.push({
+        kind: "table",
+        head: ["SECTOR", "SCORE", "PHASE", "WEEK"],
+        align: ["left", "right", "left", "right"],
+        rows: sectors.map(([name, band]) => [
+          cell(name),
+          cell(fixed(band?.currentScore, 1)),
+          cell(band?.phase ?? "n/a"),
+          cell(signed(band?.weeklyChange, 1), direction(band?.weeklyChange))
+        ])
+      });
+    }
+    if (full && signals.length > 0) {
+      blocks.push({ kind: "blank" });
+      blocks.push({
+        kind: "table",
+        head: ["SIGNAL", "VALUE", "CHANGE"],
+        align: ["left", "right", "right"],
+        rows: signals.map((signal) => [
+          cell(signal.label ?? signal.key ?? "signal"),
+          cell(fixed(signal.value, 1)),
+          cell(signed(signal.change, 1), direction(signal.change))
+        ])
+      });
+    }
+    return { json: payload, doc: doc(...blocks) };
+  }
+};
+
+// src/cli/commands/news.ts
+var DEFAULT_LIMIT = 10;
+var newsCommand = {
+  name: "news",
+  summary: "Clustered news stories, market-wide or for one ticker",
+  usage: "sentisense news [ticker] [--limit N] [--days N]",
+  examples: [
+    "sentisense news",
+    "sentisense news NVDA",
+    "sentisense news --limit 25 --full",
+    "sentisense news NVDA --json"
+  ],
+  notes: [
+    "A story is a cluster of articles covering the same event, not a single headline, so",
+    "the size column is how many sources picked it up and impact ranks how much it moved.",
+    "Tone is the average sentiment across the cluster, between -1 and 1.",
+    "--days only applies to the market-wide feed.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
+  ],
+  flags: {
+    limit: { type: "number", placeholder: "N", describe: `Stories to return (default ${DEFAULT_LIMIT})` },
+    days: { type: "number", placeholder: "N", describe: "Look-back window, market-wide feed only" }
+  },
+  async run({ args, client, full }) {
+    const api = client();
+    const ticker = optionalTicker(args, "news");
+    const notes = [];
+    const limit = typeof args.flags.limit === "number" ? args.flags.limit : DEFAULT_LIMIT;
+    const days = typeof args.flags.days === "number" ? args.flags.days : void 0;
+    const stories = ticker ? await api.documents.getStoriesByTicker(ticker, { limit }) : await api.documents.getStories({ limit, ...days === void 0 ? {} : { days } });
+    if (ticker && stories.length === 0) {
+      const note = await verifyTickerOnEmpty(api, ticker);
+      if (note) notes.push(note);
+    }
+    const blocks = [
+      {
+        kind: "head",
+        title: field("scope", ticker ?? "Top stories"),
+        right: fields(field("stories", String(stories.length)))
+      }
+    ];
+    if (stories.length === 0) {
+      blocks.push({ kind: "text", text: "No stories in this window." });
+    } else if (full) {
+      for (const story of stories) {
+        blocks.push({ kind: "blank" });
+        blocks.push({
+          kind: "head",
+          title: field("story", truncate(story.cluster.title, 70)),
+          right: fields(
+            field("impact", fixed(story.impactScore, 1), "accent"),
+            field(
+              "tone",
+              signed(story.cluster.averageSentiment, 2),
+              story.cluster.averageSentiment > 0 ? "up" : story.cluster.averageSentiment < 0 ? "down" : void 0
+            )
+          )
+        });
+        blocks.push({
+          kind: "kv",
+          items: fields(
+            field("id", story.cluster.id),
+            field("sources", String(story.cluster.clusterSize)),
+            field("broke", dateFromSeconds(story.brokeAt)),
+            field("tickers", story.tickers.join(", ") || "none")
+          )
+        });
+      }
+    } else {
+      blocks.push({
+        kind: "table",
+        head: ["BROKE", "IMPACT", "TONE", "SRC", "TICKERS", "STORY"],
+        align: ["left", "right", "right", "right", "left", "left"],
+        rows: stories.map((story) => [
+          cell(dateFromSeconds(story.brokeAt)),
+          cell(fixed(story.impactScore, 1)),
+          cell(
+            signed(story.cluster.averageSentiment, 2),
+            story.cluster.averageSentiment > 0 ? "up" : story.cluster.averageSentiment < 0 ? "down" : void 0
+          ),
+          cell(String(story.cluster.clusterSize)),
+          cell(truncate(story.tickers.join(","), 14)),
+          cell(truncate(story.cluster.title, 44))
+        ])
+      });
+      blocks.push({
+        kind: "text",
+        text: "Add --full for story ids, source counts, and the full ticker list.",
+        tone: "dim"
+      });
+    }
+    return { json: stories, doc: doc(...blocks), notes };
+  }
+};
+
+// src/cli/commands/options.ts
+function contractTone(type) {
+  const side = type?.toUpperCase();
+  if (side === "CALL") return "up";
+  if (side === "PUT") return "down";
+  return void 0;
+}
+function walls(rows) {
+  if (!rows || rows.length === 0) return "n/a";
+  return rows.map((wall) => `${fixed(wall.strike, 0)} (${humanize(wall.oi, 1)})`).join("  ");
+}
+var optionsCommand = {
+  name: "options",
+  summary: "End-of-day options positioning for one stock or ETF",
+  usage: "sentisense options <ticker>",
+  examples: [
+    "sentisense options NVDA",
+    "sentisense options SPY --full",
+    "sentisense options NVDA --json"
+  ],
+  notes: [
+    "End of day, not live: readings describe the latest completed session and refresh the",
+    "following morning. Percentiles are against that ticker's own trailing history, so they",
+    "compare a stock to its past self, never to another stock.",
+    "Coverage is the most actively optioned names plus the tracked ETFs. A real ticker",
+    "outside that set reports no coverage and exits 0, the same as any other empty result.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2,
+    "A free key gets the full dossier for the first ten calls each month, then a headline",
+    "preview. Calls that return no dossier do not count against that."
+  ],
+  flags: {},
+  async run({ args, client, full }) {
+    const ticker = oneTicker(args, "options");
+    const api = client();
+    const envelope = await api.stocks.getOptionsSummary(ticker);
+    const data = envelope.data;
+    if (!data) {
+      const note = await verifyTickerOnEmpty(api, ticker);
+      return {
+        json: envelope,
+        doc: doc({ kind: "text", text: `No options coverage for ${ticker}.` }),
+        notes: note ? [note] : void 0
+      };
+    }
+    const latest = data.latest ?? {};
+    const context = data.context ?? {};
+    const blocks = [
+      {
+        kind: "head",
+        title: field("ticker", ticker),
+        right: fields(
+          field("positioning", signed(data.sentiment, 2), direction(data.sentiment)),
+          field("iv rank 1y", fixed(context.ivRank1y, 1)),
+          field("put/call vol", fixed(latest.pcVol, 2))
+        )
+      },
+      {
+        kind: "facts",
+        items: fields(
+          field("ATM IV", fixed(latest.atmIv, 4)),
+          field("Skew 25d", signed(latest.skew25d, 4)),
+          field("Call vol", humanize(latest.callVol, 1)),
+          field("Put vol", humanize(latest.putVol, 1)),
+          field("Notional", humanize(latest.notionalVol))
+        )
+      },
+      {
+        kind: "facts",
+        items: fields(
+          field("Max pain", fixed(data.oiWalls?.maxPain, 0)),
+          field("Wall expiry", data.oiWalls?.expiry ?? "n/a"),
+          field("Call OI", humanize(latest.callOi, 1)),
+          field("Put OI", humanize(latest.putOi, 1)),
+          field("Contracts", humanize(latest.contracts, 0))
+        )
+      },
+      {
+        kind: "kv",
+        items: fields(
+          field("call walls", walls(data.oiWalls?.callWalls)),
+          field("put walls", walls(data.oiWalls?.putWalls))
+        )
+      }
+    ];
+    if (full) {
+      blocks.push({
+        kind: "kv",
+        items: fields(
+          field("term structure", `60d ${fixed(latest.atmIv60, 4)}   90d ${fixed(latest.atmIv90, 4)}`),
+          field("net delta", humanize(latest.netDelta, 1)),
+          field("put/call OI", fixed(latest.pcOi, 2)),
+          field("pc vol percentile 1y", fixed(context.pcVolPctl1y, 1)),
+          field("skew percentile 1y", fixed(context.skewPctl1y, 1)),
+          field("observations 1y", fixed(context.observations1y, 0))
+        )
+      });
+    }
+    const unusual = data.unusual ?? [];
+    if (unusual.length > 0) {
+      blocks.push({ kind: "blank" });
+      blocks.push({
+        kind: "table",
+        head: ["CONTRACT", "TYPE", "STRIKE", "EXPIRY", "DTE", "VOLUME", "OI", "VOL/OI", "PREMIUM"],
+        align: ["left", "left", "right", "left", "right", "right", "right", "right", "right"],
+        rows: unusual.map((row) => [
+          cell(row.contract ?? ""),
+          cell(row.type ?? "", contractTone(row.type)),
+          cell(fixed(row.strike, 0)),
+          cell(row.expiry ?? ""),
+          cell(row.dte === void 0 ? "" : String(row.dte)),
+          cell(humanize(row.volume, 0)),
+          cell(humanize(row.oi, 0)),
+          cell(fixed(row.volOiRatio, 1)),
+          cell(humanize(row.premium))
+        ])
+      });
+    }
+    blocks.push({
+      kind: "text",
+      text: `session of ${data.asOf ?? latest.date ?? "an unrecorded date"}`,
+      tone: "dim"
+    });
+    if (envelope.isPreview) {
+      blocks.push({
+        kind: "text",
+        text: "Preview response: the free monthly dossier allowance is spent, so only the headline readings are shown.",
+        tone: "dim"
+      });
+    }
+    return { json: envelope, doc: doc(...blocks) };
+  }
+};
+
+// src/cli/commands/quote.ts
+function single(row, full) {
+  const { quote, profile } = row;
+  const tone = direction(quote.changePercent);
+  const blocks = [
+    {
+      kind: "head",
+      title: field("ticker", row.ticker),
+      subtitle: profile?.name ? field("name", profile.name) : void 0,
+      right: fields(
+        field("price", money(quote.currentPrice)),
+        field(
+          "change",
+          `${signed(quote.change)} (${signedPercent(quote.changePercent)})`,
+          tone
+        )
+      )
+    },
+    {
+      kind: "facts",
+      items: fields(
+        field("Open", fixed(quote.open)),
+        field("High", fixed(quote.dayHigh)),
+        field("Low", fixed(quote.dayLow)),
+        field("Volume", humanize(quote.volume, 1)),
+        field("Prev close", fixed(quote.previousClose))
+      )
+    },
+    {
+      kind: "facts",
+      items: fields(
+        field("Mkt cap", humanize(quote.marketCap)),
+        field("P/E", fixed(quote.peRatio)),
+        field("EPS TTM", fixed(quote.epsTTM)),
+        field("Div yield", percent(quote.dividendYield, 2)),
+        field(
+          "52w",
+          `${fixed(quote.week52Low)} to ${fixed(quote.week52High)}`
+        )
+      )
+    }
+  ];
+  if (quote.extendedHours) {
+    const ext = quote.extendedHours;
+    blocks.push({
+      kind: "facts",
+      items: fields(
+        field(
+          ext.session === "pre" ? "Pre-market" : "After hours",
+          money(ext.price)
+        ),
+        field(
+          "Extended change",
+          `${signed(ext.change)} (${signedPercent(ext.changePercent)})`,
+          direction(ext.changePercent)
+        )
+      )
+    });
+  }
+  if (full) {
+    blocks.push({
+      kind: "kv",
+      items: fields(
+        field("200d average", fixed(quote.movingAverage200Day)),
+        quote.reportedCurrency ? field("reported currency", quote.reportedCurrency) : void 0,
+        profile?.sector ? field("sector", String(profile.sector)) : void 0,
+        profile?.industry ? field("industry", String(profile.industry)) : void 0,
+        profile?.ceo ? field("ceo", String(profile.ceo)) : void 0
+      )
+    });
+  }
+  if (quote.listingStatus === "DELISTED") {
+    blocks.push({
+      kind: "text",
+      text: `Delisted on ${quote.delistedDate ?? "an unrecorded date"}. Every figure above is frozen at the last trade, not a live market move.`,
+      tone: "down"
+    });
+  } else if (quote.listingStatus === "PENDING_DELISTING") {
+    blocks.push({
+      kind: "text",
+      text: "A merger or take-private is scheduled. The stock still trades, so these figures are current.",
+      tone: "dim"
+    });
+  }
+  blocks.push({
+    kind: "text",
+    text: quote.priceAsOf ? `price as of ${timestamp(quote.priceAsOf)}` : `served ${timestamp(quote.timestamp)}, price age not reported`,
+    tone: "dim"
+  });
+  return blocks;
+}
+function table(rows, full) {
+  const head = full ? ["TICKER", "NAME", "PRICE", "CHANGE", "CHANGE%", "VOLUME", "MKT CAP"] : ["TICKER", "PRICE", "CHANGE", "CHANGE%", "VOLUME", "MKT CAP"];
+  return {
+    kind: "table",
+    head,
+    align: full ? ["left", "left", "right", "right", "right", "right", "right"] : ["left", "right", "right", "right", "right", "right"],
+    rows: rows.map((row) => {
+      const tone = direction(row.quote.changePercent);
+      const tail = [
+        cell(fixed(row.quote.currentPrice), void 0),
+        cell(signed(row.quote.change), tone),
+        cell(signedPercent(row.quote.changePercent), tone),
+        cell(humanize(row.quote.volume, 1)),
+        cell(humanize(row.quote.marketCap))
+      ];
+      return full ? [cell(row.ticker), cell(row.profile?.name ?? ""), ...tail] : [cell(row.ticker), ...tail];
+    })
+  };
+}
+var quoteCommand = {
+  name: "quote",
+  summary: "Price, day range, and valuation for one or more tickers",
+  usage: "sentisense quote <ticker> [ticker...]",
+  examples: [
+    "sentisense quote NVDA",
+    "sentisense quote NVDA AAPL MSFT",
+    "sentisense quote NVDA --json",
+    "sentisense quote NVDA --full"
+  ],
+  notes: [
+    "Several tickers in one invocation is one process and one set of round trips, which is",
+    "cheaper than calling the command once per symbol.",
+    "Use canonical symbols, for example GOOGL rather than GOOG and BRK.B rather than BRK-B.",
+    "One request per ticker. The company name costs a second request, so it is fetched only",
+    "for the terminal layout: piped and --json output carry the quote alone.",
+    "JSON is the exact quote response for one ticker, and an object keyed by ticker for more."
+  ],
+  flags: {},
+  async run({ args, client, full, mode }) {
+    const tickers = args.positionals.map((t) => t.toUpperCase());
+    if (tickers.length === 0) {
+      throw new CliUsageError("quote needs at least one ticker.", "for example: sentisense quote NVDA");
+    }
+    const api = client();
+    const wantName = mode === "pretty";
+    const rows = await Promise.all(
+      tickers.map(async (ticker) => {
+        const [quote, profile] = await Promise.all([
+          api.stocks.getQuote(ticker),
+          // A name is a nicety, not the answer. A ticker with no profile still gets a quote.
+          wantName ? api.stocks.getProfile(ticker).catch(() => null) : Promise.resolve(null)
+        ]);
+        return { ticker, quote, profile };
+      })
+    );
+    if (rows.length === 1) {
+      return { json: rows[0].quote, doc: doc(...single(rows[0], full)) };
+    }
+    const json = {};
+    for (const row of rows) json[row.ticker] = row.quote;
+    return { json, doc: doc(table(rows, full)) };
+  }
+};
+
+// src/cli/commands/screen.ts
+var OPS = ["GTE", "LTE", "GT", "LT", "EQ", "NEQ", "IN", "NOT_IN"];
+function parseFilter(raw) {
+  const parts = raw.split(":");
+  if (parts.length < 3) {
+    throw new CliUsageError(
+      `--filter takes FIELD:OP:VALUE, got "${raw}".`,
+      "for example: --filter SENTI_SCORE_7D:GTE:13"
+    );
+  }
+  const fieldName = parts[0].toUpperCase();
+  const op = parts[1].toUpperCase();
+  const value = parts.slice(2).join(":");
+  if (!OPS.includes(op)) {
+    throw new CliUsageError(
+      `unknown filter operator "${parts[1]}".`,
+      `operators are ${OPS.join(", ")}.`
+    );
+  }
+  if (op === "IN" || op === "NOT_IN") {
+    return { fieldName, op, values: value.split(",").map((v) => v.trim()).filter(Boolean) };
+  }
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    throw new CliUsageError(
+      `--filter ${fieldName}:${op} expects a number, got "${value}".`,
+      "for example: --filter SENTI_SCORE_7D:GTE:13"
+    );
+  }
+  return { fieldName, op, value: numeric };
+}
+function parseSort(raw) {
+  const [name, dirRaw] = raw.split(":");
+  const dir = (dirRaw ?? "DESC").toUpperCase();
+  if (dir !== "ASC" && dir !== "DESC") {
+    throw new CliUsageError(
+      `--sort direction takes ASC or DESC, got "${dirRaw}".`,
+      "for example: --sort SENTI_SCORE_7D:DESC"
+    );
+  }
+  return { fieldName: name.toUpperCase(), dir };
+}
+var screenCommand = {
+  name: "screen",
+  summary: "Filter the tracked universe on Score, analyst, technical, and price fields",
+  usage: "sentisense screen [--filter FIELD:OP:VALUE]... [--sort FIELD:DIR] [--limit N]",
+  examples: [
+    "sentisense screen --list",
+    "sentisense screen --fields",
+    "sentisense screen --filter SENTI_SCORE_7D:GTE:13 --filter ANALYST_COUNT:GTE:5",
+    "sentisense screen --filter SENTI_SCORE_7D:GTE:13 --sort SENTI_SCORE_7D:DESC --limit 25",
+    "sentisense screen --etf --filter ISSUER:IN:Vanguard,iShares"
+  ],
+  notes: [
+    "Filters are ANDed. Operators: GTE, LTE, GT, LT, EQ, NEQ, IN, NOT_IN.",
+    "Start from --fields for the real field names and their operators, or --list for the",
+    "curated screens, which are also worked examples of the plan shape.",
+    "Two field semantics catch people out: ANALYST_RATING_MEAN runs 1 to 5 with 1 as strong",
+    "buy, so bullish is LTE 2.5, and the Score fields are banded at 5, 13, and 23 either side",
+    "of zero, so filtering on 0.5 means any positive score.",
+    "Nulls never match in either direction, so two opposite filters do not partition the",
+    "universe: a stock with no data for that field is in neither result.",
+    "Rows read a snapshot that refreshes every 20 minutes, so prices here are not live."
+  ],
+  flags: {
+    filter: {
+      type: "string",
+      placeholder: "FIELD:OP:VALUE",
+      repeat: true,
+      describe: "Filter leg, may be repeated"
+    },
+    sort: { type: "string", placeholder: "FIELD:DIR", describe: "Sort field and direction" },
+    limit: { type: "number", placeholder: "N", describe: "Rows to return, caps at 500" },
+    tickers: { type: "string", placeholder: "A,B,C", describe: "Screen only these symbols" },
+    screen: { type: "string", placeholder: "id", describe: "Run a curated screen by id" },
+    list: { type: "boolean", describe: "List the curated screens and exit" },
+    fields: { type: "boolean", describe: "List the filterable fields and exit" },
+    etf: { type: "boolean", describe: "Screen the ETF universe" }
+  },
+  async run({ args, client, full }) {
+    rejectPositionals(args, "screen");
+    const api = client();
+    const etf = args.flags.etf === true;
+    if (args.flags.fields === true) {
+      const catalog = await api.screener.fields();
+      const list = etf ? catalog.etf : catalog.stock;
+      return {
+        json: catalog,
+        doc: doc(
+          {
+            kind: "head",
+            title: field("universe", etf ? "ETF fields" : "Stock fields"),
+            right: fields(field("count", String(list.length)))
+          },
+          {
+            kind: "table",
+            head: ["FIELD", "GROUP", "TYPE", "UNIT", "OPS"],
+            rows: list.map((descriptor) => [
+              cell(descriptor.name),
+              cell(descriptor.group),
+              cell(descriptor.type),
+              cell(descriptor.unit ?? ""),
+              cell(descriptor.ops.join(","))
+            ])
+          }
+        )
+      };
+    }
+    if (args.flags.list === true) {
+      const response2 = await api.screener.screens();
+      return {
+        json: response2,
+        doc: doc(
+          {
+            kind: "head",
+            title: field("scope", "Curated screens"),
+            right: fields(field("count", String(response2.screens.length)))
+          },
+          {
+            kind: "table",
+            head: ["ID", "NAME", "SUMMARY"],
+            rows: response2.screens.map((screen) => [
+              cell(screen.id),
+              cell(screen.name),
+              cell(truncate(screen.summary, full ? 160 : 60))
+            ])
+          },
+          { kind: "text", text: 'Run one with "sentisense screen --screen <id>".', tone: "dim" }
+        )
+      };
+    }
+    const limit = typeof args.flags.limit === "number" ? args.flags.limit : void 0;
+    const tickers = typeof args.flags.tickers === "string" ? args.flags.tickers.split(",").map((t) => t.trim().toUpperCase()).filter(Boolean) : void 0;
+    let plan;
+    let planName;
+    let runEtfUniverse = etf;
+    const screenId = typeof args.flags.screen === "string" ? args.flags.screen : void 0;
+    if (screenId) {
+      const response2 = await api.screener.screens();
+      const found = response2.screens.find((screen) => screen.id === screenId);
+      if (!found) {
+        throw new CliUsageError(
+          `no curated screen with id "${screenId}".`,
+          'run "sentisense screen --list" for the ids.'
+        );
+      }
+      plan = found.plan;
+      planName = found.name;
+      runEtfUniverse = etf || found.plan.universe === "ETF";
+    } else {
+      const legs = flagList(args.flags, "filter").map(parseFilter);
+      if (legs.length === 0) {
+        throw new CliUsageError(
+          "screen needs at least one --filter, or a --screen id.",
+          'try "sentisense screen --list", or --filter SENTI_SCORE_7D:GTE:13'
+        );
+      }
+      plan = {
+        filters: legs,
+        ...typeof args.flags.sort === "string" ? { sort: parseSort(args.flags.sort) } : {}
+      };
+      planName = "custom";
+    }
+    const request = {
+      plan,
+      ...limit === void 0 ? {} : { limit },
+      ...tickers ? { tickers } : {}
+    };
+    if (runEtfUniverse) {
+      const response2 = await api.screener.runEtfs(request);
+      const rows2 = response2.results ?? [];
+      const blocks2 = [
+        {
+          kind: "head",
+          title: field("screen", planName),
+          right: fields(
+            field("matched", String(response2.matched)),
+            field("returned", String(rows2.length))
+          )
+        }
+      ];
+      if (rows2.length === 0) {
+        blocks2.push({ kind: "text", text: "No ETFs match this plan." });
+      } else {
+        blocks2.push({
+          kind: "table",
+          head: ["TICKER", "NAME", "ISSUER", "PRICE", "CHANGE%", "AUM", "EXPENSE", "SCORE"],
+          align: ["left", "left", "left", "right", "right", "right", "right", "right"],
+          rows: rows2.map((row) => [
+            cell(row.ticker),
+            cell(truncate(row.name ?? "", full ? 40 : 24)),
+            cell(truncate(row.issuer ?? "", 14)),
+            cell(fixed(row.currentPrice)),
+            cell(fixed(row.changePercent), direction(row.changePercent)),
+            cell(humanize(row.marketCap)),
+            cell(percent(row.expenseRatio, 2)),
+            cell(fixed(row.constituentsWeightedSentisense, 1), "accent")
+          ])
+        });
+      }
+      if (response2.matched > rows2.length) {
+        blocks2.push({
+          kind: "text",
+          text: `Matched ${response2.matched}, showing the top ${rows2.length} under the plan sort. Raise --limit for more.`,
+          tone: "dim"
+        });
+      }
+      return { json: response2, doc: doc(...blocks2) };
+    }
+    const response = await api.screener.run(request);
+    const rows = response.results ?? [];
+    const blocks = [
+      {
+        kind: "head",
+        title: field("screen", planName),
+        right: fields(
+          field("matched", String(response.matched)),
+          field("returned", String(rows.length))
+        )
+      }
+    ];
+    if (rows.length === 0) {
+      blocks.push({ kind: "text", text: "No stocks match this plan." });
+    } else {
+      blocks.push({
+        kind: "table",
+        head: ["TICKER", "PRICE", "CHANGE%", "SCORE 7D", "VS 1M", "MKT CAP", "BUY%", "ANALYSTS"],
+        align: ["left", "right", "right", "right", "right", "right", "right", "right"],
+        rows: rows.map((row) => [
+          cell(row.ticker),
+          cell(fixed(row.currentPrice)),
+          cell(fixed(row.changePercent), direction(row.changePercent)),
+          cell(fixed(row.sentiSenseScore7D, 1), "accent"),
+          cell(signed(row.scoreChange7D, 1), direction(row.scoreChange7D)),
+          cell(humanize(row.marketCap)),
+          cell(fixed(row.analystBuyRatioPct, 0)),
+          cell(row.analystCount === null || row.analystCount === void 0 ? "n/a" : String(row.analystCount))
+        ])
+      });
+    }
+    if (response.matched > rows.length) {
+      blocks.push({
+        kind: "text",
+        text: `Matched ${response.matched}, showing the top ${rows.length} under the plan sort. Raise --limit for more.`,
+        tone: "dim"
+      });
+    }
+    return { json: response, doc: doc(...blocks) };
+  }
+};
+
+// src/cli/commands/sentiment.ts
+var DEFAULT_DAYS = 30;
+function toneForDirection(value) {
+  if (value === "Bullish") return "up";
+  if (value === "Bearish") return "down";
+  return void 0;
+}
+function seriesValues(metrics, fallback) {
+  if (metrics && metrics.length > 0) {
+    const points = metrics.map((point) => point.value).filter((value) => typeof value === "number" && Number.isFinite(value));
+    if (points.length > 0) return points;
+  }
+  return fallback ?? [];
+}
+var sentimentCommand = {
+  name: "sentiment",
+  summary: "SentiSense Score, tone, attention, and where the conversation is",
+  usage: "sentisense sentiment <ticker> [--days N]",
+  examples: [
+    "sentisense sentiment NVDA",
+    "sentisense sentiment NVDA --days 90",
+    "sentisense sentiment NVDA --json",
+    "sentisense sentiment NVDA --full"
+  ],
+  notes: [
+    "The SentiSense Score is a composite of tone and attention centred on zero, not a",
+    "polarity: it is unbounded, and the bands sit at 5, 13, and 23 either side of zero.",
+    "Tone per source is the separate polarity reading, always between -1 and 1, and it is",
+    "reported per source rather than blended into one number.",
+    "--days sets the Score history window used for the sparkline. Default is 30."
+  ],
+  flags: {
+    days: { type: "number", placeholder: "N", describe: `Days of Score history (default ${DEFAULT_DAYS})` }
+  },
+  async run({ args, client, full }) {
+    const ticker = oneTicker(args, "sentiment");
+    const days = typeof args.flags.days === "number" ? args.flags.days : DEFAULT_DAYS;
+    if (days < 1) {
+      throw new CliUsageError("--days must be at least 1.", "for example: --days 30");
+    }
+    const api = client();
+    const endTime = Date.now();
+    const startTime = endTime - days * 24 * 60 * 60 * 1e3;
+    const notes = [];
+    const [envelope, metrics] = await Promise.all([
+      api.stocks.getSentiment(ticker),
+      // Supplementary: the headline reading already carries its own sparkline, so a gap in
+      // the time series degrades the display rather than failing the command. It says so on
+      // stderr, because a silent gap looks the same as a quiet week.
+      api.entityMetrics.getMetrics(ticker, {
+        metricType: "sentisense_score",
+        startTime,
+        endTime,
+        maxDataPoints: days
+      }).catch(() => {
+        notes.push("score history unavailable, showing the reading without it");
+        return null;
+      })
+    ]);
+    const data = envelope.data ?? {};
+    const series = seriesValues(metrics, data.scoreSparkline);
+    const blocks = [
+      {
+        kind: "head",
+        title: field("ticker", ticker),
+        subtitle: data.companyName ? field("name", data.companyName) : void 0,
+        right: fields(
+          field("score 30d", fixed(data.sentisenseScoreAvg30d, 1), "accent"),
+          data.scoreLabel ? field("band", data.scoreLabel) : void 0,
+          data.direction ? field("direction", data.direction, toneForDirection(data.direction)) : void 0
+        )
+      },
+      {
+        kind: "facts",
+        items: fields(
+          field("Latest", fixed(data.sentisenseScore, 1)),
+          field(
+            "30d change",
+            signed(data.sentisenseScoreDelta30d, 1),
+            typeof data.sentisenseScoreDelta30d === "number" ? data.sentisenseScoreDelta30d > 0 ? "up" : data.sentisenseScoreDelta30d < 0 ? "down" : void 0 : void 0
+          ),
+          data.trend ? field("Trend", data.trend) : void 0
+        )
+      },
+      {
+        kind: "facts",
+        items: fields(
+          field("Mentions", humanize(data.mentions, 1)),
+          field("30d avg", humanize(data.mentionsAvg30d, 1)),
+          field(
+            "Dominance",
+            typeof data.socialDominance === "number" ? percent(data.socialDominance * 100, 2) : "n/a"
+          )
+        )
+      }
+    ];
+    if (series.length > 0) {
+      blocks.push({
+        kind: "spark",
+        label: `${days}d`,
+        series,
+        note: data.asOf ? `as of ${data.asOf}` : void 0
+      });
+    }
+    if (data.bySource && data.bySource.length > 0) {
+      blocks.push({ kind: "blank" });
+      blocks.push({
+        kind: "table",
+        head: ["SOURCE", "TONE", "SHARE", "VALUE"],
+        align: ["left", "left", "right", "right"],
+        rows: data.bySource.map((source) => [
+          cell(source.source),
+          cell(source.direction, toneForDirection(source.direction)),
+          cell(percent(source.mentionShare, 0)),
+          cell(signed(source.value, 2))
+        ])
+      });
+      blocks.push({
+        kind: "text",
+        text: "Shares are rounded per source, so they sum to about 100 rather than exactly 100.",
+        tone: "dim"
+      });
+    }
+    if (full && data.drivers && data.drivers.length > 0) {
+      blocks.push({ kind: "blank" });
+      blocks.push({
+        kind: "table",
+        head: ["TONE", "DRIVER"],
+        align: ["right", "left"],
+        rows: data.drivers.map((driver) => [
+          cell(signed(driver.tone, 2), driver.tone > 0 ? "up" : driver.tone < 0 ? "down" : void 0),
+          cell(driver.title)
+        ])
+      });
+    }
+    if (full && data.narrative) {
+      blocks.push({ kind: "blank" });
+      blocks.push({ kind: "text", text: data.narrative });
+    }
+    if (envelope.isPreview) {
+      blocks.push({
+        kind: "text",
+        text: "Preview response: a PRO key returns the full reading.",
+        tone: "dim"
+      });
+    }
+    return {
+      json: { sentiment: envelope, series: metrics },
+      doc: doc(...blocks),
+      notes
+    };
+  }
+};
+
+// src/cli/commands/index.ts
+var COMMANDS = [
+  authCommand,
+  healthCommand,
+  quoteCommand,
+  sentimentCommand,
+  moodCommand,
+  analystsCommand,
+  earningsCommand,
+  insidersCommand,
+  insightsCommand,
+  congressCommand,
+  newsCommand,
+  flowsCommand,
+  optionsCommand,
+  screenCommand
+];
+var COMMAND_NAMES = COMMANDS.map((command) => command.name);
+function findCommand(name) {
+  return COMMANDS.find((command) => command.name === name);
+}
+var OFFLINE_COMMANDS = /* @__PURE__ */ new Set(["auth"]);
+
+// src/cli/help.ts
+var EXAMPLE = {
+  auth: "sentisense auth $SENTISENSE_API_KEY",
+  health: "sentisense health",
+  quote: "sentisense quote NVDA AAPL",
+  sentiment: "sentisense sentiment NVDA --days 30",
+  mood: "sentisense mood",
+  analysts: "sentisense analysts NVDA",
+  earnings: "sentisense earnings --week next",
+  insiders: "sentisense insiders NVDA",
+  insights: "sentisense insights NVDA",
+  congress: "sentisense congress NVDA",
+  news: "sentisense news NVDA",
+  flows: "sentisense flows NVDA",
+  options: "sentisense options NVDA",
+  screen: "sentisense screen --filter SENTI_SCORE_7D:GTE:13"
+};
+function pad(text, width) {
+  return text.length >= width ? text : text + " ".repeat(width - text.length);
+}
+function flagLines(specs) {
+  const entries = Object.entries(specs);
+  if (entries.length === 0) return [];
+  const rendered = entries.map(([name, spec]) => ({
+    left: spec.type === "boolean" ? `--${name}` : `--${name} <${spec.placeholder ?? "value"}>`,
+    describe: spec.describe
+  }));
+  const width = Math.max(...rendered.map((entry) => entry.left.length));
+  return rendered.map((entry) => `  ${pad(entry.left, width)}  ${entry.describe}`);
+}
+function mainHelp() {
+  const width = Math.max(...COMMANDS.map((command) => command.name.length));
+  const lines = [
+    `sentisense ${VERSION}`,
+    "Market data, sentiment, and filings from the command line.",
+    "",
+    "Usage: sentisense <command> [arguments] [flags]",
+    "",
+    "Commands:",
+    ...COMMANDS.map(
+      (command) => `  ${pad(command.name, width)}  ${command.summary}
+  ${" ".repeat(width)}  ${EXAMPLE[command.name] ?? ""}`
+    ),
+    "",
+    "Output:",
+    "  Pretty in a terminal, plain text when piped, exact API JSON with --json.",
+    "  --full widens a command, --plain and --no-color force text, --debug shows stack traces.",
+    "",
+    "Setup:",
+    `  sentisense auth <key>     store a key at ~/.config/sentisense/config.json (0600)`,
+    "  SENTISENSE_API_KEY=<key>  or pass it in the environment",
+    `  Get a key at ${KEY_URL}`,
+    "",
+    'Run "sentisense help <command>" for flags, examples, and exit codes.',
+    "",
+    "Research data, not investment advice."
+  ];
+  return `${lines.join("\n")}
+`;
+}
+function commandHelp(command) {
+  const lines = [
+    `sentisense ${command.name}  ${command.summary}`,
+    "",
+    `Usage: ${command.usage}`
+  ];
+  if (command.notes && command.notes.length > 0) {
+    lines.push("", ...command.notes);
+  }
+  const own = flagLines(command.flags);
+  if (own.length > 0) lines.push("", "Flags:", ...own);
+  lines.push("", "Common flags:", ...flagLines(GLOBAL_FLAGS));
+  lines.push("", "Examples:", ...command.examples.map((example) => `  ${example}`));
+  lines.push(
+    "",
+    "Exit codes:",
+    ...EXIT_TABLE.map(([code, meaning]) => `  ${code}  ${meaning}`)
+  );
+  return `${lines.join("\n")}
+`;
+}
+function versionLine() {
+  return `${VERSION}
+`;
+}
+
+// src/cli/render/ansi.ts
+var CODES = {
+  up: "32",
+  down: "31",
+  accent: "33",
+  dim: "2",
+  bold: "1"
+};
+var ESC = "\x1B";
+function wrap(text, code) {
+  return `${ESC}[${code}m${text}${ESC}[0m`;
+}
+function createStyler(enabled) {
+  if (!enabled) {
+    const passthrough = (text) => text;
+    return { enabled: false, tone: passthrough, bold: passthrough, dim: passthrough };
+  }
+  return {
+    enabled: true,
+    tone: (text, tone) => tone ? wrap(text, CODES[tone]) : text,
+    bold: (text) => wrap(text, CODES.bold),
+    dim: (text) => wrap(text, CODES.dim)
+  };
+}
+function shouldColor({ pretty, noColorFlag, env, isTTY }) {
+  if (!pretty || noColorFlag) return false;
+  if (env.NO_COLOR !== void 0 && env.NO_COLOR !== "") return false;
+  return isTTY === true;
+}
+
+// src/cli/render/json.ts
+function renderJson(payload) {
+  return `${JSON.stringify(payload, null, 2)}
+`;
+}
+
+// src/cli/render/plain.ts
+function padEnd(text, width) {
+  return text.length >= width ? text : text + " ".repeat(width - text.length);
+}
+function padStart(text, width) {
+  return text.length >= width ? text : " ".repeat(width - text.length) + text;
+}
+function renderFields(items) {
+  if (items.length === 0) return [];
+  const width = Math.max(...items.map((f) => f.label.length + 1));
+  return items.map((f) => `${padEnd(`${f.label}:`, width)} ${f.value.text}`);
+}
+function renderBlock(block) {
+  switch (block.kind) {
+    case "head":
+      return renderFields([block.title, ...block.subtitle ? [block.subtitle] : [], ...block.right ?? []]);
+    case "facts":
+    case "kv":
+      return renderFields(block.items);
+    case "spark": {
+      const line = `${block.label}: ${sparkline(block.series)}`;
+      return block.note ? [line, `${block.label} note: ${block.note}`] : [line];
+    }
+    case "table": {
+      if (block.rows.length === 0) return [];
+      const widths = block.head.map(
+        (header, i) => Math.max(header.length, ...block.rows.map((row) => row[i]?.text.length ?? 0))
+      );
+      const align = (i) => block.align?.[i] ?? "left";
+      const pad2 = (text, i) => align(i) === "right" ? padStart(text, widths[i]) : padEnd(text, widths[i]);
+      const line = (cells) => cells.map((text, i) => pad2(text, i)).join("  ").trimEnd();
+      return [
+        line(block.head),
+        ...block.rows.map((row) => line(block.head.map((_, i) => row[i]?.text ?? "")))
+      ];
+    }
+    case "text":
+      return [block.text];
+    case "blank":
+      return [""];
+  }
+}
+function renderPlain(document) {
+  const lines = [];
+  for (const block of document.blocks) lines.push(...renderBlock(block));
+  return lines.length === 0 ? "" : `${lines.join("\n")}
+`;
+}
+
+// src/cli/render/pretty.ts
+var WIDTH = 78;
+function padEnd2(text, width) {
+  return text.length >= width ? text : text + " ".repeat(width - text.length);
+}
+function padStart2(text, width) {
+  return text.length >= width ? text : " ".repeat(width - text.length) + text;
+}
+function renderBlock2(block, s) {
+  switch (block.kind) {
+    case "head": {
+      const left = block.subtitle ? `${s.bold(block.title.value.text)}  ${s.dim(block.subtitle.value.text)}` : s.bold(block.title.value.text);
+      const plainLeftWidth = block.title.value.text.length + (block.subtitle ? block.subtitle.value.text.length + 2 : 0);
+      if (!block.right || block.right.length === 0) return [left];
+      const rightPlain = block.right.map((f) => f.value.text).join("  ");
+      const right = block.right.map((f) => s.tone(f.value.text, f.value.tone)).join("  ");
+      const gap = Math.max(2, WIDTH - plainLeftWidth - rightPlain.length);
+      return [`${left}${" ".repeat(gap)}${right}`];
+    }
+    case "facts":
+      if (block.items.length === 0) return [];
+      return [
+        block.items.map((f) => `${s.dim(f.label)} ${s.tone(f.value.text, f.value.tone)}`).join("   ")
+      ];
+    case "kv": {
+      if (block.items.length === 0) return [];
+      const width = Math.max(...block.items.map((f) => f.label.length));
+      return block.items.map(
+        (f) => `${s.dim(padEnd2(f.label, width))}  ${s.tone(f.value.text, f.value.tone)}`
+      );
+    }
+    case "spark": {
+      const line = `${s.dim(block.label)} ${sparkline(block.series)}`;
+      return [block.note ? `${line}   ${s.dim(block.note)}` : line];
+    }
+    case "table": {
+      if (block.rows.length === 0) return [];
+      const columns = block.head.length;
+      const widths = block.head.map(
+        (header, i) => Math.max(header.length, ...block.rows.map((row) => row[i]?.text.length ?? 0))
+      );
+      const align = (i) => block.align?.[i] ?? "left";
+      const pad2 = (text, i) => align(i) === "right" ? padStart2(text, widths[i]) : padEnd2(text, widths[i]);
+      const lines = [
+        s.dim(
+          block.head.map((header, i) => pad2(header, i)).join("  ").trimEnd()
+        )
+      ];
+      for (const row of block.rows) {
+        const cells = [];
+        for (let i = 0; i < columns; i++) {
+          const value = row[i] ?? { text: "" };
+          const padded = pad2(value.text, i);
+          cells.push(value.tone ? s.tone(padded, value.tone) : padded);
+        }
+        lines.push(cells.join("  ").trimEnd());
+      }
+      return lines;
+    }
+    case "text":
+      return [s.tone(block.text, block.tone)];
+    case "blank":
+      return [""];
+  }
+}
+function renderPretty(document, color) {
+  const s = createStyler(color);
+  const lines = [];
+  for (const block of document.blocks) lines.push(...renderBlock2(block, s));
+  return lines.length === 0 ? "" : `${lines.join("\n")}
+`;
+}
+
+// src/cli/run.ts
+function outputMode(flags, isTTY) {
+  if (flags.json === true) return "json";
+  if (flags.plain === true) return "plain";
+  if (flags.pretty === true) return "pretty";
+  return isTTY === true ? "pretty" : "plain";
+}
+async function runCli(argv, io) {
+  const { command: name, rest } = splitCommand(argv);
+  if (!name) {
+    const bare = parseArgs(rest, GLOBAL_FLAGS);
+    if (bare.flags.version === true) {
+      io.stdout(versionLine());
+      return EXIT.OK;
+    }
+    io.stdout(mainHelp());
+    return EXIT.OK;
+  }
+  try {
+    if (name === "help") {
+      const target = rest.find((token) => !token.startsWith("-"));
+      if (!target) {
+        io.stdout(mainHelp());
+        return EXIT.OK;
+      }
+      const command2 = findCommand(target);
+      if (!command2) throw unknownCommand(target);
+      io.stdout(commandHelp(command2));
+      return EXIT.OK;
+    }
+    const command = findCommand(name);
+    if (!command) throw unknownCommand(name);
+    const specs = { ...GLOBAL_FLAGS, ...command.flags };
+    const args = parseArgs(rest, specs);
+    if (args.flags.help === true) {
+      io.stdout(commandHelp(command));
+      return EXIT.OK;
+    }
+    if (args.flags.version === true) {
+      io.stdout(versionLine());
+      return EXIT.OK;
+    }
+    const context = resolveContext({ flags: args.flags, env: io.env, configDir: io.configDir });
+    let cached;
+    const client = () => {
+      if (!cached) cached = createClient(context);
+      return cached;
+    };
+    const mode = outputMode(args.flags, io.isTTY);
+    const result = await command.run({
+      args,
+      context,
+      io: { env: io.env, isTTY: io.isTTY, configDir: io.configDir },
+      client: OFFLINE_COMMANDS.has(command.name) ? () => {
+        throw new Error(`${command.name} does not call the API`);
+      } : client,
+      full: args.flags.full === true,
+      mode
+    });
+    const color = shouldColor({
+      pretty: mode === "pretty",
+      noColorFlag: args.flags["no-color"] === true,
+      env: io.env,
+      isTTY: io.isTTY
+    });
+    for (const note of result.notes ?? []) {
+      io.stderr(`${createStyler(color).dim(`note: ${note}`)}
+`);
+    }
+    if (mode === "json") {
+      io.stdout(renderJson(result.json));
+    } else if (mode === "pretty") {
+      io.stdout(renderPretty(result.doc, color));
+    } else {
+      io.stdout(renderPlain(result.doc));
+    }
+    return result.exitCode ?? EXIT.OK;
+  } catch (error) {
+    const debug = argv.includes("--debug");
+    const report = describeError(error, debug);
+    for (const line of report.lines) io.stderr(`${line}
+`);
+    return report.exitCode;
+  }
+}
+function unknownCommand(name) {
+  const suggestion = nearest(name, COMMAND_NAMES);
+  return new CliUsageError(
+    `unknown command "${name}".`,
+    suggestion ? `did you mean "${suggestion}"? Run "sentisense --help" for the full list.` : 'run "sentisense --help" for the command list.'
+  );
+}
+
+// src/cli/main.ts
+async function main() {
+  process.exitCode = await runCli(process.argv.slice(2), {
+    stdout: (chunk) => process.stdout.write(chunk),
+    stderr: (chunk) => process.stderr.write(chunk),
+    env: process.env,
+    isTTY: Boolean(process.stdout.isTTY)
+  });
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`error: ${message}
+`);
+  process.stderr.write("next: run the same command with --debug for the stack trace.\n");
+  process.exitCode = 1;
+});