sentisense 0.80.0 → 0.82.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.cjs CHANGED
@@ -277,6 +277,9 @@ function trim(text) {
277
277
  function fixed(value, decimals = 2) {
278
278
  return isNum(value) ? value.toFixed(decimals) : ABSENT;
279
279
  }
280
+ function strike(value) {
281
+ return isNum(value) ? trim(value.toFixed(3)) : ABSENT;
282
+ }
280
283
  function humanize(value, decimals = 2) {
281
284
  if (!isNum(value)) return ABSENT;
282
285
  const sign = value < 0 ? "-" : "";
@@ -1489,7 +1492,7 @@ var flowsCommand = {
1489
1492
  };
1490
1493
 
1491
1494
  // src/version.ts
1492
- var VERSION = "0.80.0";
1495
+ var VERSION = "0.82.0";
1493
1496
 
1494
1497
  // src/resources/analyst.ts
1495
1498
  var Analyst = class {
@@ -1661,6 +1664,16 @@ var Calendar = class {
1661
1664
  constructor(client) {
1662
1665
  this.client = client;
1663
1666
  }
1667
+ /**
1668
+ * List the calendars the API serves, with the path of each, so a client can find them
1669
+ * without hardcoding paths.
1670
+ *
1671
+ * Every tier receives the same list, and the call does not count against the monthly quota;
1672
+ * the per-minute rate limit still applies.
1673
+ */
1674
+ async list() {
1675
+ return this.client.get("/api/v1/calendar");
1676
+ }
1664
1677
  /**
1665
1678
  * Upcoming company earnings, sorted by date.
1666
1679
  *
@@ -1842,6 +1855,14 @@ var Earnings = class {
1842
1855
  };
1843
1856
 
1844
1857
  // src/resources/entityMetrics.ts
1858
+ function requirePathSegment(method, name, value) {
1859
+ if (typeof value !== "string" || value.trim() === "" || value === "." || value === "..") {
1860
+ throw new SentiSenseError(
1861
+ `${method}: ${name} must not be empty, "." or ".." (got ${JSON.stringify(value)})`
1862
+ );
1863
+ }
1864
+ return value;
1865
+ }
1845
1866
  var EntityMetrics = class {
1846
1867
  constructor(client) {
1847
1868
  this.client = client;
@@ -1892,6 +1913,25 @@ var EntityMetrics = class {
1892
1913
  }
1893
1914
  );
1894
1915
  }
1916
+ /**
1917
+ * List the dimensions a metric can be broken down by for one entity, with the values present
1918
+ * in the data, so you can see what exists before calling `getDistribution()`.
1919
+ *
1920
+ * Returns a plain array, empty when the metric has no slices for this entity. Available on
1921
+ * every tier; each call counts against the monthly quota.
1922
+ *
1923
+ * @param symbol Ticker symbol (e.g. "AAPL") or entity urlSlug (e.g. "Nancy-Pelosi").
1924
+ * @param metricType The metric to look up (e.g. "mentions").
1925
+ * @throws {SentiSenseError} Before any request, when `symbol` or `metricType` is empty,
1926
+ * whitespace only, `"."` or `".."`.
1927
+ */
1928
+ async getSlices(symbol, metricType) {
1929
+ const entity = requirePathSegment("entityMetrics.getSlices", "symbol", symbol);
1930
+ const metric = requirePathSegment("entityMetrics.getSlices", "metricType", metricType);
1931
+ return this.client.get(
1932
+ `/api/v2/metrics/entity/${encodeURIComponent(entity)}/metric/${encodeURIComponent(metric)}/slices`
1933
+ );
1934
+ }
1895
1935
  };
1896
1936
 
1897
1937
  // src/resources/etfs.ts
@@ -2267,6 +2307,35 @@ var Institutional = class {
2267
2307
  async getActivists(reportDate) {
2268
2308
  return this.client.get("/api/v1/institutional/activist", { reportDate });
2269
2309
  }
2310
+ /**
2311
+ * Get convertible bond positions from 13F filings for one quarter, one row per issuer,
2312
+ * grouped by the issuer's equity ticker.
2313
+ *
2314
+ * `reportDate` is the quarter end as an ISO date (e.g. `"2026-06-30"`); the API requires it,
2315
+ * so take one from `getQuarters()`. Returns the preview envelope, so the rows are `.data`. A
2316
+ * FREE key receives the top three rows with `isPreview: true` and `totalCount` holding the full
2317
+ * row count; a PRO key receives the full list.
2318
+ *
2319
+ * Each row's `bondTickers` is one comma-separated string, not an array.
2320
+ */
2321
+ async getBondFlows(reportDate) {
2322
+ return this.client.get("/api/v1/institutional/bonds", { reportDate });
2323
+ }
2324
+ /**
2325
+ * Get the call and put positions institutions reported on Form 13F for one quarter, one row
2326
+ * per stock.
2327
+ *
2328
+ * These are quarter-end 13F holdings, not options market activity: for options volume, open
2329
+ * interest and implied volatility, use `client.options` and `stocks.getOptionsSummary()`.
2330
+ *
2331
+ * `reportDate` is the quarter end as an ISO date (e.g. `"2026-06-30"`); the API requires it,
2332
+ * so take one from `getQuarters()`. Returns the preview envelope, so the rows are `.data`. A
2333
+ * FREE key receives the top three rows with `isPreview: true` and `totalCount` holding the full
2334
+ * row count; a PRO key receives the full list.
2335
+ */
2336
+ async getOptionFlows(reportDate) {
2337
+ return this.client.get("/api/v1/institutional/options", { reportDate });
2338
+ }
2270
2339
  /**
2271
2340
  * Discover institutions: a paginated, AUM-ranked list of filers (slug + metadata)
2272
2341
  * so you can find what to query without knowing slugs upfront.
@@ -2408,6 +2477,37 @@ var MarketMoodResource = class {
2408
2477
  // index envelope alongside fed-sentiment and ai-sentiment. Use this resource when you want
2409
2478
  // the phase band, weekly change, per-signal breakdown and per-sector map; use `indexes`
2410
2479
  // when you want every index to answer the same shape. Both report the same headline number.
2480
+ /**
2481
+ * Get the per-sector sentiment rollup: the 11 GICS sectors, each measured against the
2482
+ * market's own news-and-social tone.
2483
+ *
2484
+ * Compare sectors on `consensusVsMarket`, the gap between a sector's bullish-versus-bearish
2485
+ * mention balance and the market's. Available on every tier with the same response; each
2486
+ * call counts against the monthly quota. It is a daily precomputed snapshot, so `generatedAt`
2487
+ * (epoch seconds) is its freshness.
2488
+ *
2489
+ * @example
2490
+ * const { sectors } = await client.marketMood.getSentimentSectors();
2491
+ * for (const s of sectors) console.log(s.sector, s.consensusVsMarket, s.consensusLabel);
2492
+ */
2493
+ async getSentimentSectors() {
2494
+ return this.client.get("/api/v1/sentiment/sectors");
2495
+ }
2496
+ /**
2497
+ * Get market-wide sentiment breadth: each day's share of the covered US stocks leaning
2498
+ * bullish, neutral or bearish, the tone analogue of an advance/decline line.
2499
+ *
2500
+ * `series` runs oldest to newest, and `latest` is the newest entry of `series`. Available on
2501
+ * every tier with the same response; each call counts against the monthly quota. It is a daily
2502
+ * precomputed snapshot, so `generatedAt` (epoch seconds) is its freshness.
2503
+ *
2504
+ * @example
2505
+ * const breadth = await client.marketMood.getSentimentBreadth();
2506
+ * console.log(breadth.latest?.date, breadth.latest?.netBreadth);
2507
+ */
2508
+ async getSentimentBreadth() {
2509
+ return this.client.get("/api/v1/sentiment/breadth");
2510
+ }
2411
2511
  };
2412
2512
 
2413
2513
  // src/resources/marketSummary.ts
@@ -2442,9 +2542,10 @@ var Options = class {
2442
2542
  * `data` is `null` before the first nightly build populates it, which is a cold-start
2443
2543
  * state rather than an error.
2444
2544
  *
2445
- * Tiering: a PRO key receives every row. A FREE key receives the top 25 stock rows plus
2446
- * all the aggregates, with `isPreview` true and the envelope's `totalCount` reporting the
2447
- * full stock board; `data.etfTotalCount` does the same for the ETF board.
2545
+ * Tiering: a PRO key receives every row. A FREE key receives the top 25 rows of each board
2546
+ * and the top 3 session highlights of each board, plus every aggregate for both boards, with
2547
+ * `isPreview` true and the envelope's `totalCount` reporting the full stock board;
2548
+ * `data.etfTotalCount` does the same for the ETF board.
2448
2549
  *
2449
2550
  * Drill into any row with `client.stocks.getOptionsSummary(ticker)` for its full dossier,
2450
2551
  * or `client.stocks.getOptionsHistory(ticker)` to chart how a reading has trended.
@@ -2807,7 +2908,9 @@ var Stocks = class {
2807
2908
  * ten calls each calendar month and a headline-only preview after that, with `isPreview`
2808
2909
  * true; calls that return a null `data` never spend that allowance. The headline preview has
2809
2910
  * no nested objects: its readings arrive flat as `data.ivRank1y`, `data.atmIv`,
2810
- * `data.expectedMove1d`, `data.pcVol`, `data.pcVolPctl1y` and `data.maxPain`.
2911
+ * `data.expectedMove1d`, `data.pcVol`, `data.pcVolPctl1y` and `data.maxPain`. On a FREE key
2912
+ * the envelope's `dossierAllowance`, when available, says how many full dossiers are left
2913
+ * this calendar month and when the count resets.
2811
2914
  */
2812
2915
  async getOptionsSummary(ticker) {
2813
2916
  return this.client.get(
@@ -2853,8 +2956,10 @@ var Stocks = class {
2853
2956
  *
2854
2957
  * **No data is an empty `series`, not a null payload.** A weekend, a holiday, a session from
2855
2958
  * before the history was kept, a ticker outside the board and an unknown symbol all answer
2856
- * with `data.series` empty. `data.missingCycles` lists cycles whose stored point could not be
2857
- * read, which are unknown rather than absent. A malformed or future `session` rejects with
2959
+ * with `data.series` empty. `data.missingCycles` lists cycles with no stored history (a cycle
2960
+ * that published no board, or one whose history was lost), where the ticker's numbers are
2961
+ * unknown rather than zero. `data.cycles` counts the session's stored cycles, so `series` can
2962
+ * be shorter. A malformed or future `session` rejects with
2858
2963
  * an `APIError` (status 400, code `invalid_session`). A 503 means the stored series could
2859
2964
  * not be read; it is retried like any other 503 and never answered with a partial series.
2860
2965
  */
@@ -4192,7 +4297,7 @@ var moodCommand = {
4192
4297
  const payload = await client().marketMood.get();
4193
4298
  const market = readMarket(payload);
4194
4299
  const sectors = readSectors(payload);
4195
- const history = (market.history ?? []).map((point) => point?.score).filter((score) => typeof score === "number" && Number.isFinite(score));
4300
+ const history2 = (market.history ?? []).map((point) => point?.score).filter((score) => typeof score === "number" && Number.isFinite(score));
4196
4301
  const blocks = [
4197
4302
  {
4198
4303
  kind: "head",
@@ -4217,8 +4322,8 @@ var moodCommand = {
4217
4322
  )
4218
4323
  });
4219
4324
  }
4220
- if (history.length > 0) {
4221
- const tail = full ? history : history.slice(-60);
4325
+ if (history2.length > 0) {
4326
+ const tail = full ? history2 : history2.slice(-60);
4222
4327
  blocks.push({
4223
4328
  kind: "spark",
4224
4329
  label: `${tail.length}d`,
@@ -4365,6 +4470,12 @@ var newsCommand = {
4365
4470
 
4366
4471
  // src/cli/commands/options.ts
4367
4472
  var SESSION_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
4473
+ var DEFAULT_RADAR_ROWS = 15;
4474
+ var DEFAULT_HISTORY_ROWS = 20;
4475
+ var HISTORY_WINDOWS = { "1y": true, "2y": true, "5y": true };
4476
+ function isHistoryWindow(value) {
4477
+ return Object.prototype.hasOwnProperty.call(HISTORY_WINDOWS, value);
4478
+ }
4368
4479
  function contractTone(type) {
4369
4480
  const side = type?.toUpperCase();
4370
4481
  if (side === "CALL") return "up";
@@ -4373,7 +4484,263 @@ function contractTone(type) {
4373
4484
  }
4374
4485
  function walls(rows) {
4375
4486
  if (!rows || rows.length === 0) return "n/a";
4376
- return rows.map((wall) => `${fixed(wall.strike, 0)} (${humanize(wall.oi, 1)})`).join(" ");
4487
+ return rows.map((wall) => `${strike(wall.strike)} (${humanize(wall.oi, 1)})`).join(" ");
4488
+ }
4489
+ function signedCount(value) {
4490
+ const text = humanize(value, 1);
4491
+ return typeof value === "number" && value > 0 ? `+${text}` : text;
4492
+ }
4493
+ function allowanceLine(allowance) {
4494
+ if (!allowance) return void 0;
4495
+ return {
4496
+ kind: "text",
4497
+ text: `${allowance.remaining} of ${allowance.limit} full dossiers left this month, resets ${dateFromSeconds(allowance.resetsAt)}.`,
4498
+ tone: "dim"
4499
+ };
4500
+ }
4501
+ function hasFollowUp(row) {
4502
+ return row.oiPrior !== void 0 || row.oiNext !== void 0 || row.oiChange !== void 0 || row.oiConfirmation !== void 0;
4503
+ }
4504
+ var TICKER_EXAMPLE = {
4505
+ "--history": "sentisense options NVDA --history",
4506
+ "--window": "sentisense options NVDA --window 2y",
4507
+ "--intraday": "sentisense options NVDA --intraday",
4508
+ "--session": "sentisense options NVDA --session 2026-10-14"
4509
+ };
4510
+ function pickView(args) {
4511
+ const ticker = optionalTicker(args, "options");
4512
+ if (args.positionals.length > 0 && args.positionals[0].trim() === "") {
4513
+ throw new CliUsageError("options needs a ticker.", "for example: sentisense options NVDA");
4514
+ }
4515
+ const flags = args.flags;
4516
+ const session = typeof flags.session === "string" ? flags.session : void 0;
4517
+ const rawWindow = typeof flags.window === "string" ? flags.window : void 0;
4518
+ const limit = typeof flags.limit === "number" ? flags.limit : void 0;
4519
+ const etfs = flags.etfs === true;
4520
+ if (session !== void 0 && !SESSION_PATTERN.test(session)) {
4521
+ throw new CliUsageError("--session must be a date, YYYY-MM-DD.", "for example: --session 2026-10-14");
4522
+ }
4523
+ if (rawWindow !== void 0 && !isHistoryWindow(rawWindow)) {
4524
+ throw new CliUsageError(`--window takes 1y, 2y or 5y, got "${rawWindow}".`, "for example: --window 2y");
4525
+ }
4526
+ const window = rawWindow;
4527
+ if (limit !== void 0 && (!Number.isInteger(limit) || limit < 1)) {
4528
+ throw new CliUsageError("--limit must be a whole number, at least 1.", "for example: --limit 25");
4529
+ }
4530
+ const intradayFlag = flags.intraday === true ? "--intraday" : session !== void 0 ? "--session" : void 0;
4531
+ const historyFlag = flags.history === true ? "--history" : window !== void 0 ? "--window" : void 0;
4532
+ if (intradayFlag && historyFlag) {
4533
+ throw new CliUsageError(
4534
+ `${historyFlag} and ${intradayFlag} do not go together.`,
4535
+ "pass one or the other: --window implies --history, and --session implies --intraday."
4536
+ );
4537
+ }
4538
+ if (etfs && (intradayFlag || historyFlag)) {
4539
+ throw new CliUsageError(
4540
+ `--etfs and ${intradayFlag ?? historyFlag} do not go together.`,
4541
+ "--etfs picks the Radar's ETF board; --history and --intraday read one ticker."
4542
+ );
4543
+ }
4544
+ if (etfs && ticker) {
4545
+ throw new CliUsageError(
4546
+ "--etfs picks the Radar's ETF board, which takes no ticker.",
4547
+ `drop the ticker for the ETF board, or drop --etfs for ${ticker}'s dossier.`
4548
+ );
4549
+ }
4550
+ if (!ticker) {
4551
+ const needsTicker = intradayFlag ?? historyFlag;
4552
+ if (needsTicker) {
4553
+ throw new CliUsageError(`${needsTicker} needs a ticker.`, `for example: ${TICKER_EXAMPLE[needsTicker]}`);
4554
+ }
4555
+ return { kind: "radar", etfs, limit };
4556
+ }
4557
+ if (historyFlag) return { kind: "history", ticker, window, limit };
4558
+ if (limit !== void 0) {
4559
+ throw new CliUsageError(
4560
+ "--limit applies to the Radar and to --history.",
4561
+ `drop it, or run "sentisense options ${ticker} --history --limit ${limit}".`
4562
+ );
4563
+ }
4564
+ if (intradayFlag) return { kind: "intraday", ticker, session };
4565
+ return { kind: "dossier", ticker };
4566
+ }
4567
+ async function radar(api, etfs, limit, full) {
4568
+ const envelope = await api.options.getOverview();
4569
+ const data = envelope.data;
4570
+ if (!data) {
4571
+ return {
4572
+ json: envelope,
4573
+ doc: doc({
4574
+ kind: "text",
4575
+ text: "No options board yet: the Radar is built after each session closes, and no build has been published."
4576
+ })
4577
+ };
4578
+ }
4579
+ const board = etfs ? {
4580
+ name: "ETFs",
4581
+ rows: data.etfRows ?? [],
4582
+ highlights: data.etfHighlights ?? [],
4583
+ medianIvRank: data.etfMedianIvRank,
4584
+ marketPcVol: data.etfMarketPcVol,
4585
+ extremeCount: data.etfExtremeCount,
4586
+ coverageCount: data.etfCoverageCount,
4587
+ totalCount: data.etfTotalCount,
4588
+ present: data.etfRows !== void 0
4589
+ } : {
4590
+ name: "stocks",
4591
+ rows: data.rows ?? [],
4592
+ highlights: data.highlights ?? [],
4593
+ medianIvRank: data.medianIvRank,
4594
+ marketPcVol: data.marketPcVol,
4595
+ extremeCount: data.extremeCount,
4596
+ coverageCount: data.coverageCount,
4597
+ totalCount: envelope.totalCount,
4598
+ present: true
4599
+ };
4600
+ const extreme = board.extremeCount === void 0 ? "n/a" : board.coverageCount === void 0 ? String(board.extremeCount) : `${board.extremeCount} of ${board.coverageCount}`;
4601
+ const blocks = [
4602
+ {
4603
+ kind: "head",
4604
+ title: field("board", `Options Radar, ${board.name}`),
4605
+ right: fields(field("session", data.asOf ?? "n/a"))
4606
+ }
4607
+ ];
4608
+ if (!board.present) {
4609
+ blocks.push({ kind: "text", text: "This build has no ETF board." });
4610
+ return { json: envelope, doc: doc(...blocks) };
4611
+ }
4612
+ blocks.push({
4613
+ kind: "facts",
4614
+ items: fields(
4615
+ field("Median IV rank", fixed(board.medianIvRank, 1)),
4616
+ field("Market put/call", fixed(board.marketPcVol, 2)),
4617
+ field("Names at an extreme", extreme)
4618
+ )
4619
+ });
4620
+ const served = board.rows.length;
4621
+ const shown = full ? board.rows : board.rows.slice(0, limit ?? DEFAULT_RADAR_ROWS);
4622
+ if (served === 0) {
4623
+ blocks.push({ kind: "text", text: `No rows on the ${board.name} board in this build.` });
4624
+ } else {
4625
+ blocks.push({ kind: "blank" });
4626
+ blocks.push({
4627
+ kind: "table",
4628
+ head: ["#", "TICKER", "NAME", "SCORE", "SENT", "P/C", "P/C PCTL", "IV RANK", "SKEW", "SKEW PCTL", "NOTIONAL"],
4629
+ align: ["right", "left", "left", "right", "right", "right", "right", "right", "right", "right", "right"],
4630
+ rows: shown.map((row, index) => [
4631
+ cell(String(index + 1)),
4632
+ cell(row.ticker ?? ""),
4633
+ cell(truncate(row.name ?? "", full ? 40 : 18)),
4634
+ cell(fixed(row.interestScore, 1)),
4635
+ cell(signed(row.sentiment, 2), direction(row.sentiment)),
4636
+ cell(fixed(row.pcVol, 2)),
4637
+ cell(fixed(row.pcVolPctl1y, 1)),
4638
+ cell(fixed(row.ivRank1y, 1)),
4639
+ cell(signed(row.skew25d, 4)),
4640
+ cell(fixed(row.skewPctl1y, 1)),
4641
+ cell(humanize(row.notionalVol))
4642
+ ])
4643
+ });
4644
+ const fullBoard = board.totalCount !== void 0 && board.totalCount > served ? board.totalCount : void 0;
4645
+ if (shown.length < served) {
4646
+ blocks.push({
4647
+ kind: "text",
4648
+ text: fullBoard ? `Showing ${shown.length} of ${served} served; the full board has ${fullBoard} names. Add --full for every served row.` : `Showing ${shown.length} of ${served} names. Add --full, or --limit N, for more.`,
4649
+ tone: "dim"
4650
+ });
4651
+ } else if (fullBoard) {
4652
+ blocks.push({
4653
+ kind: "text",
4654
+ text: `Showing all ${served} served; the full board has ${fullBoard} names.`,
4655
+ tone: "dim"
4656
+ });
4657
+ }
4658
+ }
4659
+ if (board.highlights.length > 0) {
4660
+ blocks.push({ kind: "blank" });
4661
+ blocks.push({ kind: "text", text: "Session highlights, each ticker's highest-premium unusual contract:" });
4662
+ blocks.push({
4663
+ kind: "table",
4664
+ head: ["TICKER", "CONTRACT", "TYPE", "VOLUME", "VOL/OI", "PREMIUM"],
4665
+ align: ["left", "left", "left", "right", "right", "right"],
4666
+ rows: board.highlights.map((row) => [
4667
+ cell(row.ticker ?? ""),
4668
+ cell(row.contract ?? ""),
4669
+ cell(row.type ?? "", contractTone(row.type)),
4670
+ cell(humanize(row.volume, 0)),
4671
+ cell(fixed(row.volOiRatio, 1)),
4672
+ cell(humanize(row.premium))
4673
+ ])
4674
+ });
4675
+ }
4676
+ if (!etfs && (data.etfRows?.length ?? 0) > 0) {
4677
+ blocks.push({ kind: "text", text: "The ETF board is ranked separately: add --etfs.", tone: "dim" });
4678
+ }
4679
+ if (envelope.isPreview) {
4680
+ blocks.push({
4681
+ kind: "text",
4682
+ text: "Preview response: a free key gets the top 25 rows and the top 3 highlights of each board, with every aggregate. A PRO key gets the whole board.",
4683
+ tone: "dim"
4684
+ });
4685
+ }
4686
+ return { json: envelope, doc: doc(...blocks) };
4687
+ }
4688
+ async function history(api, ticker, window, limit, full) {
4689
+ const envelope = await api.stocks.getOptionsHistory(ticker, window === void 0 ? void 0 : { window });
4690
+ const data = envelope.data;
4691
+ const series = data?.series ?? [];
4692
+ if (series.length === 0) {
4693
+ const note = await verifyTickerOnEmpty(api, ticker);
4694
+ return {
4695
+ json: envelope,
4696
+ doc: doc({ kind: "text", text: `No options coverage for ${ticker}.` }),
4697
+ notes: note ? [note] : void 0
4698
+ };
4699
+ }
4700
+ const served = data?.window ?? "n/a";
4701
+ const count = full ? series.length : Math.min(limit ?? DEFAULT_HISTORY_ROWS, series.length);
4702
+ const newest = series.slice(series.length - count).reverse();
4703
+ const blocks = [
4704
+ {
4705
+ kind: "head",
4706
+ title: field("ticker", ticker),
4707
+ right: fields(field("window", served), field("sessions", String(series.length)))
4708
+ },
4709
+ {
4710
+ kind: "table",
4711
+ head: ["DATE", "CALL VOL", "PUT VOL", "P/C", "CALL OI", "PUT OI", "ATM IV", "SKEW", "MAX UNUSUAL"],
4712
+ align: ["left", "right", "right", "right", "right", "right", "right", "right", "right"],
4713
+ rows: newest.map((row) => [
4714
+ cell(row.date ?? ""),
4715
+ cell(humanize(row.callVol, 1)),
4716
+ cell(humanize(row.putVol, 1)),
4717
+ cell(fixed(row.pcVol, 2)),
4718
+ cell(humanize(row.callOi, 1)),
4719
+ cell(humanize(row.putOi, 1)),
4720
+ cell(fixed(row.atmIv, 4)),
4721
+ cell(signed(row.skew25d, 4)),
4722
+ cell(humanize(row.maxUnusualPremium))
4723
+ ])
4724
+ },
4725
+ {
4726
+ kind: "text",
4727
+ text: count < series.length ? `Newest ${count} of ${series.length} sessions in the ${served} window. Add --full, or --limit N, for more.` : `Newest ${count} of ${series.length} sessions in the ${served} window.`,
4728
+ tone: "dim"
4729
+ }
4730
+ ];
4731
+ if (window !== void 0 && served !== window) {
4732
+ blocks.push({
4733
+ kind: "text",
4734
+ text: `Asked for ${window}, served ${served}: a free key is served 1y for every ticker except the sample companies.`,
4735
+ tone: "dim"
4736
+ });
4737
+ }
4738
+ blocks.push({
4739
+ kind: "text",
4740
+ text: "Open interest is the count going into each session, at the previous close.",
4741
+ tone: "dim"
4742
+ });
4743
+ return { json: envelope, doc: doc(...blocks, sampleNote(envelope, ticker)) };
4377
4744
  }
4378
4745
  async function intraday(api, ticker, session) {
4379
4746
  const envelope = await api.stocks.getOptionsIntradayHistory(ticker, { session });
@@ -4427,7 +4794,7 @@ async function intraday(api, ticker, session) {
4427
4794
  if (missing.length > 0) {
4428
4795
  blocks.push({
4429
4796
  kind: "text",
4430
- text: `${missing.length === 1 ? "Cycle" : "Cycles"} ${missing.join(", ")} ${missing.length === 1 ? "was" : "were"} published but could not be read, so ${ticker}'s numbers there are unknown.`,
4797
+ text: `${missing.length === 1 ? "Cycle" : "Cycles"} ${missing.join(", ")} ${missing.length === 1 ? "has" : "have"} no stored history (no board was published, or its history was lost), so ${ticker}'s numbers there are unknown.`,
4431
4798
  tone: "dim"
4432
4799
  });
4433
4800
  }
@@ -4438,13 +4805,163 @@ async function intraday(api, ticker, session) {
4438
4805
  });
4439
4806
  return { json: envelope, doc: doc(...blocks, sampleNote(envelope, ticker)) };
4440
4807
  }
4808
+ async function dossier(api, ticker, full) {
4809
+ const envelope = await api.stocks.getOptionsSummary(ticker);
4810
+ const data = envelope.data;
4811
+ if (!data) {
4812
+ const note = await verifyTickerOnEmpty(api, ticker);
4813
+ return {
4814
+ json: envelope,
4815
+ doc: doc({ kind: "text", text: `No options coverage for ${ticker}.` }),
4816
+ notes: note ? [note] : void 0
4817
+ };
4818
+ }
4819
+ const latest = data.latest ?? {};
4820
+ const context = data.context ?? {};
4821
+ const oiWalls = data.oiWalls ?? {};
4822
+ const ivRank = context.ivRank1y ?? data.ivRank1y;
4823
+ const pcVol = latest.pcVol ?? data.pcVol;
4824
+ const maxPain = data.oiWalls?.maxPain ?? data.maxPain;
4825
+ const blocks = [
4826
+ {
4827
+ kind: "head",
4828
+ title: field("ticker", ticker),
4829
+ right: fields(
4830
+ field("positioning", signed(data.sentiment, 2), direction(data.sentiment)),
4831
+ field("iv rank 1y", fixed(ivRank, 1)),
4832
+ field("put/call vol", fixed(pcVol, 2))
4833
+ )
4834
+ }
4835
+ ];
4836
+ if (data.listingStatus === "DELISTED") {
4837
+ const when = data.delistedDate ? ` (${data.delistedDate})` : "";
4838
+ const asOf = data.asOf ? `, as of ${data.asOf}` : "";
4839
+ blocks.push({
4840
+ kind: "text",
4841
+ text: `${ticker} is delisted${when}: this is the last dossier on record${asOf}.`
4842
+ });
4843
+ }
4844
+ blocks.push(
4845
+ {
4846
+ kind: "facts",
4847
+ items: fields(
4848
+ field("ATM IV", fixed(latest.atmIv ?? data.atmIv, 4)),
4849
+ field("Exp move 1d", fixed(latest.expectedMove1d ?? data.expectedMove1d, 4)),
4850
+ field("Skew 25d", signed(latest.skew25d, 4)),
4851
+ field("Call vol", humanize(latest.callVol, 1)),
4852
+ field("Put vol", humanize(latest.putVol, 1)),
4853
+ field("Notional", humanize(latest.notionalVol))
4854
+ )
4855
+ },
4856
+ {
4857
+ kind: "facts",
4858
+ items: fields(
4859
+ field("Max pain", strike(maxPain)),
4860
+ field("Wall expiry", data.oiWalls?.expiry ?? "n/a"),
4861
+ field("Call OI", humanize(latest.callOi, 1)),
4862
+ field("Put OI", humanize(latest.putOi, 1)),
4863
+ field("Contracts", humanize(latest.contracts, 0))
4864
+ )
4865
+ },
4866
+ {
4867
+ kind: "kv",
4868
+ items: fields(
4869
+ field("call walls", walls(data.oiWalls?.callWalls)),
4870
+ field("put walls", walls(data.oiWalls?.putWalls))
4871
+ )
4872
+ }
4873
+ );
4874
+ if (full) {
4875
+ blocks.push({
4876
+ kind: "kv",
4877
+ items: fields(
4878
+ field("term structure", `60d ${fixed(latest.atmIv60, 4)} 90d ${fixed(latest.atmIv90, 4)}`),
4879
+ field("net delta", humanize(latest.netDelta, 1)),
4880
+ field("put/call OI", fixed(latest.pcOi, 2)),
4881
+ field("pc vol percentile 1y", fixed(context.pcVolPctl1y ?? data.pcVolPctl1y, 1)),
4882
+ field("skew percentile 1y", fixed(context.skewPctl1y, 1)),
4883
+ field("observations 1y", fixed(context.observations1y, 0))
4884
+ )
4885
+ });
4886
+ blocks.push({
4887
+ kind: "kv",
4888
+ items: fields(
4889
+ field("pc vol percentile 5y", fixed(context.pcVolPctl5y, 1)),
4890
+ field("put/call OI percentile 1y", fixed(context.pcOiPctl1y, 1)),
4891
+ field("unusual premium percentile 1y", fixed(context.unusualPremiumPctl1y, 1)),
4892
+ field("exp move 5d", fixed(latest.expectedMove5d, 4)),
4893
+ field("exp move 20d", fixed(latest.expectedMove20d, 4)),
4894
+ field("wall expiry OI", `calls ${humanize(oiWalls.totalCallOi, 1)} puts ${humanize(oiWalls.totalPutOi, 1)}`),
4895
+ field("OI at max pain", `calls ${humanize(oiWalls.maxPainCallOi, 1)} puts ${humanize(oiWalls.maxPainPutOi, 1)}`)
4896
+ )
4897
+ });
4898
+ }
4899
+ const unusual = data.unusual ?? [];
4900
+ if (unusual.length > 0) {
4901
+ blocks.push({ kind: "blank" });
4902
+ blocks.push({
4903
+ kind: "table",
4904
+ head: ["CONTRACT", "TYPE", "STRIKE", "EXPIRY", "DTE", "VOLUME", "OI", "VOL/OI", "PREMIUM"],
4905
+ align: ["left", "left", "right", "left", "right", "right", "right", "right", "right"],
4906
+ rows: unusual.map((row) => [
4907
+ cell(row.contract ?? ""),
4908
+ cell(row.type ?? "", contractTone(row.type)),
4909
+ cell(strike(row.strike)),
4910
+ cell(row.expiry ?? ""),
4911
+ cell(row.dte === void 0 ? "" : String(row.dte)),
4912
+ cell(humanize(row.volume, 0)),
4913
+ cell(humanize(row.oi, 0)),
4914
+ cell(fixed(row.volOiRatio, 1)),
4915
+ cell(humanize(row.premium))
4916
+ ])
4917
+ });
4918
+ const followed = full ? unusual.filter(hasFollowUp) : [];
4919
+ if (followed.length > 0) {
4920
+ const vintage = followed.some((row) => row.oiVintage !== void 0);
4921
+ blocks.push({ kind: "blank" });
4922
+ blocks.push({ kind: "text", text: "Open interest follow-up on those contracts:" });
4923
+ blocks.push({
4924
+ kind: "table",
4925
+ head: ["CONTRACT", "OI PRIOR", "OI NEXT", "OI CHANGE", "FOLLOW-UP", ...vintage ? ["VINTAGE"] : []],
4926
+ align: ["left", "right", "right", "right", "left", "left"],
4927
+ rows: followed.map((row) => [
4928
+ cell(row.contract ?? ""),
4929
+ cell(humanize(row.oiPrior, 1)),
4930
+ cell(humanize(row.oiNext, 1)),
4931
+ cell(signedCount(row.oiChange)),
4932
+ cell(row.oiConfirmation ?? "n/a"),
4933
+ ...vintage ? [cell(row.oiVintage ?? "n/a")] : []
4934
+ ])
4935
+ });
4936
+ }
4937
+ }
4938
+ blocks.push({
4939
+ kind: "text",
4940
+ text: `session of ${data.asOf ?? latest.date ?? "an unrecorded date"}`,
4941
+ tone: "dim"
4942
+ });
4943
+ if (envelope.isPreview) {
4944
+ blocks.push({
4945
+ kind: "text",
4946
+ text: "Preview response: the free monthly dossier allowance is spent, so only the headline readings are shown.",
4947
+ tone: "dim"
4948
+ });
4949
+ }
4950
+ return {
4951
+ json: envelope,
4952
+ doc: doc(...blocks, allowanceLine(envelope.dossierAllowance), sampleNote(envelope, ticker))
4953
+ };
4954
+ }
4441
4955
  var optionsCommand = {
4442
4956
  name: "options",
4443
- summary: "End-of-day options positioning for one stock or ETF",
4444
- usage: "sentisense options <ticker> [--intraday] [--session YYYY-MM-DD]",
4957
+ summary: "End-of-day options: the market Radar, or one stock or ETF's positioning and history",
4958
+ usage: "sentisense options [--etfs] [--limit N] | sentisense options <ticker> [--history [--window 1y|2y|5y] [--limit N] | --intraday [--session YYYY-MM-DD]]",
4445
4959
  examples: [
4960
+ "sentisense options",
4961
+ "sentisense options --etfs --limit 25",
4446
4962
  "sentisense options NVDA",
4447
4963
  "sentisense options SPY --full",
4964
+ "sentisense options NVDA --history --window 2y",
4448
4965
  "sentisense options NVDA --json",
4449
4966
  "sentisense options NVDA --intraday",
4450
4967
  "sentisense options SPY --session 2026-10-14"
@@ -4453,18 +4970,39 @@ var optionsCommand = {
4453
4970
  "End of day, not live: readings describe the latest completed session and refresh the",
4454
4971
  "following morning. Percentiles are against that ticker's own trailing history, so they",
4455
4972
  "compare a stock to its past self, never to another stock.",
4973
+ "With no ticker it prints the Radar: the session's market aggregates, the stock board",
4974
+ "ranked by interest score, and the session highlights. --etfs shows the ETF board, which",
4975
+ "is ranked separately. A free key gets the top 25 rows and the top 3 highlights of each",
4976
+ "board, with every aggregate. --limit sets the rows printed (default 15).",
4456
4977
  "Coverage is the most actively optioned names plus the tracked ETFs. A real ticker",
4457
4978
  "outside that set reports no coverage and exits 0, the same as any other empty result.",
4458
4979
  EMPTY_VERIFY_NOTE,
4459
4980
  EMPTY_VERIFY_NOTE_2,
4460
4981
  "A free key gets the full dossier for the first ten calls each month, then a headline",
4461
4982
  "preview. Calls that return no dossier do not count against that. Sample companies are",
4462
- "always full and spend none of the ten.",
4983
+ "always full and spend none of the ten. On a free key the dossier says how many are left",
4984
+ "and when the count resets, whenever the API reports the count.",
4985
+ "--history shows the ticker's daily sessions, newest first (default 20, --limit changes",
4986
+ "it). --window picks 1y, 2y or 5y and implies --history. A free key is served 1y for every",
4987
+ "ticker except the sample companies, and the output names the window it was served.",
4463
4988
  "--intraday shows one session's intraday series instead: the ticker's volumes, put/call",
4464
4989
  "ratio, unusual-contract count and ATM IV at every 15-minute cycle (PRO keys and sample companies).",
4465
- "--session picks the session and implies --intraday; omitted, the latest one."
4990
+ "--session picks the session and implies --intraday; omitted, the latest one.",
4991
+ "--full adds every served row to the Radar and --history, and more readings to a dossier."
4466
4992
  ],
4467
4993
  flags: {
4994
+ etfs: { type: "boolean", describe: "With no ticker, show the Radar's ETF board instead of the stock board" },
4995
+ limit: {
4996
+ type: "number",
4997
+ placeholder: "N",
4998
+ describe: `Rows to print: the Radar (default ${DEFAULT_RADAR_ROWS}) or --history (default ${DEFAULT_HISTORY_ROWS})`
4999
+ },
5000
+ history: { type: "boolean", describe: "Show the ticker's daily sessions, newest first" },
5001
+ window: {
5002
+ type: "string",
5003
+ placeholder: "1y|2y|5y",
5004
+ describe: "Window for --history (default 1y); implies --history"
5005
+ },
4468
5006
  intraday: { type: "boolean", describe: "Show the session's intraday series, every 15-minute cycle (PRO or a sample company)" },
4469
5007
  session: {
4470
5008
  type: "string",
@@ -4473,115 +5011,17 @@ var optionsCommand = {
4473
5011
  }
4474
5012
  },
4475
5013
  async run({ args, client, full }) {
4476
- const ticker = oneTicker(args, "options");
4477
- const session = typeof args.flags.session === "string" ? args.flags.session : void 0;
4478
- if (session !== void 0 && !SESSION_PATTERN.test(session)) {
4479
- throw new CliUsageError("--session must be a date, YYYY-MM-DD.", "for example: --session 2026-10-14");
4480
- }
4481
- if (args.flags.intraday === true || session !== void 0) {
4482
- return intraday(client(), ticker, session);
4483
- }
4484
- const api = client();
4485
- const envelope = await api.stocks.getOptionsSummary(ticker);
4486
- const data = envelope.data;
4487
- if (!data) {
4488
- const note = await verifyTickerOnEmpty(api, ticker);
4489
- return {
4490
- json: envelope,
4491
- doc: doc({ kind: "text", text: `No options coverage for ${ticker}.` }),
4492
- notes: note ? [note] : void 0
4493
- };
4494
- }
4495
- const latest = data.latest ?? {};
4496
- const context = data.context ?? {};
4497
- const ivRank = context.ivRank1y ?? data.ivRank1y;
4498
- const pcVol = latest.pcVol ?? data.pcVol;
4499
- const maxPain = data.oiWalls?.maxPain ?? data.maxPain;
4500
- const blocks = [
4501
- {
4502
- kind: "head",
4503
- title: field("ticker", ticker),
4504
- right: fields(
4505
- field("positioning", signed(data.sentiment, 2), direction(data.sentiment)),
4506
- field("iv rank 1y", fixed(ivRank, 1)),
4507
- field("put/call vol", fixed(pcVol, 2))
4508
- )
4509
- },
4510
- {
4511
- kind: "facts",
4512
- items: fields(
4513
- field("ATM IV", fixed(latest.atmIv ?? data.atmIv, 4)),
4514
- field("Exp move 1d", fixed(latest.expectedMove1d ?? data.expectedMove1d, 4)),
4515
- field("Skew 25d", signed(latest.skew25d, 4)),
4516
- field("Call vol", humanize(latest.callVol, 1)),
4517
- field("Put vol", humanize(latest.putVol, 1)),
4518
- field("Notional", humanize(latest.notionalVol))
4519
- )
4520
- },
4521
- {
4522
- kind: "facts",
4523
- items: fields(
4524
- field("Max pain", fixed(maxPain, 0)),
4525
- field("Wall expiry", data.oiWalls?.expiry ?? "n/a"),
4526
- field("Call OI", humanize(latest.callOi, 1)),
4527
- field("Put OI", humanize(latest.putOi, 1)),
4528
- field("Contracts", humanize(latest.contracts, 0))
4529
- )
4530
- },
4531
- {
4532
- kind: "kv",
4533
- items: fields(
4534
- field("call walls", walls(data.oiWalls?.callWalls)),
4535
- field("put walls", walls(data.oiWalls?.putWalls))
4536
- )
4537
- }
4538
- ];
4539
- if (full) {
4540
- blocks.push({
4541
- kind: "kv",
4542
- items: fields(
4543
- field("term structure", `60d ${fixed(latest.atmIv60, 4)} 90d ${fixed(latest.atmIv90, 4)}`),
4544
- field("net delta", humanize(latest.netDelta, 1)),
4545
- field("put/call OI", fixed(latest.pcOi, 2)),
4546
- field("pc vol percentile 1y", fixed(context.pcVolPctl1y ?? data.pcVolPctl1y, 1)),
4547
- field("skew percentile 1y", fixed(context.skewPctl1y, 1)),
4548
- field("observations 1y", fixed(context.observations1y, 0))
4549
- )
4550
- });
4551
- }
4552
- const unusual = data.unusual ?? [];
4553
- if (unusual.length > 0) {
4554
- blocks.push({ kind: "blank" });
4555
- blocks.push({
4556
- kind: "table",
4557
- head: ["CONTRACT", "TYPE", "STRIKE", "EXPIRY", "DTE", "VOLUME", "OI", "VOL/OI", "PREMIUM"],
4558
- align: ["left", "left", "right", "left", "right", "right", "right", "right", "right"],
4559
- rows: unusual.map((row) => [
4560
- cell(row.contract ?? ""),
4561
- cell(row.type ?? "", contractTone(row.type)),
4562
- cell(fixed(row.strike, 0)),
4563
- cell(row.expiry ?? ""),
4564
- cell(row.dte === void 0 ? "" : String(row.dte)),
4565
- cell(humanize(row.volume, 0)),
4566
- cell(humanize(row.oi, 0)),
4567
- cell(fixed(row.volOiRatio, 1)),
4568
- cell(humanize(row.premium))
4569
- ])
4570
- });
4571
- }
4572
- blocks.push({
4573
- kind: "text",
4574
- text: `session of ${data.asOf ?? latest.date ?? "an unrecorded date"}`,
4575
- tone: "dim"
4576
- });
4577
- if (envelope.isPreview) {
4578
- blocks.push({
4579
- kind: "text",
4580
- text: "Preview response: the free monthly dossier allowance is spent, so only the headline readings are shown.",
4581
- tone: "dim"
4582
- });
5014
+ const view = pickView(args);
5015
+ switch (view.kind) {
5016
+ case "radar":
5017
+ return radar(client(), view.etfs, view.limit, full);
5018
+ case "history":
5019
+ return history(client(), view.ticker, view.window, view.limit, full);
5020
+ case "intraday":
5021
+ return intraday(client(), view.ticker, view.session);
5022
+ case "dossier":
5023
+ return dossier(client(), view.ticker, full);
4583
5024
  }
4584
- return { json: envelope, doc: doc(...blocks, sampleNote(envelope, ticker)) };
4585
5025
  }
4586
5026
  };
4587
5027