sentisense 0.79.0 → 0.81.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.79.0";
1495
+ var VERSION = "0.81.0";
1493
1496
 
1494
1497
  // src/resources/analyst.ts
1495
1498
  var Analyst = class {
@@ -2442,9 +2445,10 @@ var Options = class {
2442
2445
  * `data` is `null` before the first nightly build populates it, which is a cold-start
2443
2446
  * state rather than an error.
2444
2447
  *
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.
2448
+ * Tiering: a PRO key receives every row. A FREE key receives the top 25 rows of each board
2449
+ * and the top 3 session highlights of each board, plus every aggregate for both boards, with
2450
+ * `isPreview` true and the envelope's `totalCount` reporting the full stock board;
2451
+ * `data.etfTotalCount` does the same for the ETF board.
2448
2452
  *
2449
2453
  * Drill into any row with `client.stocks.getOptionsSummary(ticker)` for its full dossier,
2450
2454
  * or `client.stocks.getOptionsHistory(ticker)` to chart how a reading has trended.
@@ -2807,7 +2811,9 @@ var Stocks = class {
2807
2811
  * ten calls each calendar month and a headline-only preview after that, with `isPreview`
2808
2812
  * true; calls that return a null `data` never spend that allowance. The headline preview has
2809
2813
  * no nested objects: its readings arrive flat as `data.ivRank1y`, `data.atmIv`,
2810
- * `data.expectedMove1d`, `data.pcVol`, `data.pcVolPctl1y` and `data.maxPain`.
2814
+ * `data.expectedMove1d`, `data.pcVol`, `data.pcVolPctl1y` and `data.maxPain`. On a FREE key
2815
+ * the envelope's `dossierAllowance`, when available, says how many full dossiers are left
2816
+ * this calendar month and when the count resets.
2811
2817
  */
2812
2818
  async getOptionsSummary(ticker) {
2813
2819
  return this.client.get(
@@ -2853,8 +2859,10 @@ var Stocks = class {
2853
2859
  *
2854
2860
  * **No data is an empty `series`, not a null payload.** A weekend, a holiday, a session from
2855
2861
  * 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
2862
+ * with `data.series` empty. `data.missingCycles` lists cycles with no stored history (a cycle
2863
+ * that published no board, or one whose history was lost), where the ticker's numbers are
2864
+ * unknown rather than zero. `data.cycles` counts the session's stored cycles, so `series` can
2865
+ * be shorter. A malformed or future `session` rejects with
2858
2866
  * an `APIError` (status 400, code `invalid_session`). A 503 means the stored series could
2859
2867
  * not be read; it is retried like any other 503 and never answered with a partial series.
2860
2868
  */
@@ -4192,7 +4200,7 @@ var moodCommand = {
4192
4200
  const payload = await client().marketMood.get();
4193
4201
  const market = readMarket(payload);
4194
4202
  const sectors = readSectors(payload);
4195
- const history = (market.history ?? []).map((point) => point?.score).filter((score) => typeof score === "number" && Number.isFinite(score));
4203
+ const history2 = (market.history ?? []).map((point) => point?.score).filter((score) => typeof score === "number" && Number.isFinite(score));
4196
4204
  const blocks = [
4197
4205
  {
4198
4206
  kind: "head",
@@ -4217,8 +4225,8 @@ var moodCommand = {
4217
4225
  )
4218
4226
  });
4219
4227
  }
4220
- if (history.length > 0) {
4221
- const tail = full ? history : history.slice(-60);
4228
+ if (history2.length > 0) {
4229
+ const tail = full ? history2 : history2.slice(-60);
4222
4230
  blocks.push({
4223
4231
  kind: "spark",
4224
4232
  label: `${tail.length}d`,
@@ -4365,6 +4373,12 @@ var newsCommand = {
4365
4373
 
4366
4374
  // src/cli/commands/options.ts
4367
4375
  var SESSION_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
4376
+ var DEFAULT_RADAR_ROWS = 15;
4377
+ var DEFAULT_HISTORY_ROWS = 20;
4378
+ var HISTORY_WINDOWS = { "1y": true, "2y": true, "5y": true };
4379
+ function isHistoryWindow(value) {
4380
+ return Object.prototype.hasOwnProperty.call(HISTORY_WINDOWS, value);
4381
+ }
4368
4382
  function contractTone(type) {
4369
4383
  const side = type?.toUpperCase();
4370
4384
  if (side === "CALL") return "up";
@@ -4373,7 +4387,263 @@ function contractTone(type) {
4373
4387
  }
4374
4388
  function walls(rows) {
4375
4389
  if (!rows || rows.length === 0) return "n/a";
4376
- return rows.map((wall) => `${fixed(wall.strike, 0)} (${humanize(wall.oi, 1)})`).join(" ");
4390
+ return rows.map((wall) => `${strike(wall.strike)} (${humanize(wall.oi, 1)})`).join(" ");
4391
+ }
4392
+ function signedCount(value) {
4393
+ const text = humanize(value, 1);
4394
+ return typeof value === "number" && value > 0 ? `+${text}` : text;
4395
+ }
4396
+ function allowanceLine(allowance) {
4397
+ if (!allowance) return void 0;
4398
+ return {
4399
+ kind: "text",
4400
+ text: `${allowance.remaining} of ${allowance.limit} full dossiers left this month, resets ${dateFromSeconds(allowance.resetsAt)}.`,
4401
+ tone: "dim"
4402
+ };
4403
+ }
4404
+ function hasFollowUp(row) {
4405
+ return row.oiPrior !== void 0 || row.oiNext !== void 0 || row.oiChange !== void 0 || row.oiConfirmation !== void 0;
4406
+ }
4407
+ var TICKER_EXAMPLE = {
4408
+ "--history": "sentisense options NVDA --history",
4409
+ "--window": "sentisense options NVDA --window 2y",
4410
+ "--intraday": "sentisense options NVDA --intraday",
4411
+ "--session": "sentisense options NVDA --session 2026-10-14"
4412
+ };
4413
+ function pickView(args) {
4414
+ const ticker = optionalTicker(args, "options");
4415
+ if (args.positionals.length > 0 && args.positionals[0].trim() === "") {
4416
+ throw new CliUsageError("options needs a ticker.", "for example: sentisense options NVDA");
4417
+ }
4418
+ const flags = args.flags;
4419
+ const session = typeof flags.session === "string" ? flags.session : void 0;
4420
+ const rawWindow = typeof flags.window === "string" ? flags.window : void 0;
4421
+ const limit = typeof flags.limit === "number" ? flags.limit : void 0;
4422
+ const etfs = flags.etfs === true;
4423
+ if (session !== void 0 && !SESSION_PATTERN.test(session)) {
4424
+ throw new CliUsageError("--session must be a date, YYYY-MM-DD.", "for example: --session 2026-10-14");
4425
+ }
4426
+ if (rawWindow !== void 0 && !isHistoryWindow(rawWindow)) {
4427
+ throw new CliUsageError(`--window takes 1y, 2y or 5y, got "${rawWindow}".`, "for example: --window 2y");
4428
+ }
4429
+ const window = rawWindow;
4430
+ if (limit !== void 0 && (!Number.isInteger(limit) || limit < 1)) {
4431
+ throw new CliUsageError("--limit must be a whole number, at least 1.", "for example: --limit 25");
4432
+ }
4433
+ const intradayFlag = flags.intraday === true ? "--intraday" : session !== void 0 ? "--session" : void 0;
4434
+ const historyFlag = flags.history === true ? "--history" : window !== void 0 ? "--window" : void 0;
4435
+ if (intradayFlag && historyFlag) {
4436
+ throw new CliUsageError(
4437
+ `${historyFlag} and ${intradayFlag} do not go together.`,
4438
+ "pass one or the other: --window implies --history, and --session implies --intraday."
4439
+ );
4440
+ }
4441
+ if (etfs && (intradayFlag || historyFlag)) {
4442
+ throw new CliUsageError(
4443
+ `--etfs and ${intradayFlag ?? historyFlag} do not go together.`,
4444
+ "--etfs picks the Radar's ETF board; --history and --intraday read one ticker."
4445
+ );
4446
+ }
4447
+ if (etfs && ticker) {
4448
+ throw new CliUsageError(
4449
+ "--etfs picks the Radar's ETF board, which takes no ticker.",
4450
+ `drop the ticker for the ETF board, or drop --etfs for ${ticker}'s dossier.`
4451
+ );
4452
+ }
4453
+ if (!ticker) {
4454
+ const needsTicker = intradayFlag ?? historyFlag;
4455
+ if (needsTicker) {
4456
+ throw new CliUsageError(`${needsTicker} needs a ticker.`, `for example: ${TICKER_EXAMPLE[needsTicker]}`);
4457
+ }
4458
+ return { kind: "radar", etfs, limit };
4459
+ }
4460
+ if (historyFlag) return { kind: "history", ticker, window, limit };
4461
+ if (limit !== void 0) {
4462
+ throw new CliUsageError(
4463
+ "--limit applies to the Radar and to --history.",
4464
+ `drop it, or run "sentisense options ${ticker} --history --limit ${limit}".`
4465
+ );
4466
+ }
4467
+ if (intradayFlag) return { kind: "intraday", ticker, session };
4468
+ return { kind: "dossier", ticker };
4469
+ }
4470
+ async function radar(api, etfs, limit, full) {
4471
+ const envelope = await api.options.getOverview();
4472
+ const data = envelope.data;
4473
+ if (!data) {
4474
+ return {
4475
+ json: envelope,
4476
+ doc: doc({
4477
+ kind: "text",
4478
+ text: "No options board yet: the Radar is built after each session closes, and no build has been published."
4479
+ })
4480
+ };
4481
+ }
4482
+ const board = etfs ? {
4483
+ name: "ETFs",
4484
+ rows: data.etfRows ?? [],
4485
+ highlights: data.etfHighlights ?? [],
4486
+ medianIvRank: data.etfMedianIvRank,
4487
+ marketPcVol: data.etfMarketPcVol,
4488
+ extremeCount: data.etfExtremeCount,
4489
+ coverageCount: data.etfCoverageCount,
4490
+ totalCount: data.etfTotalCount,
4491
+ present: data.etfRows !== void 0
4492
+ } : {
4493
+ name: "stocks",
4494
+ rows: data.rows ?? [],
4495
+ highlights: data.highlights ?? [],
4496
+ medianIvRank: data.medianIvRank,
4497
+ marketPcVol: data.marketPcVol,
4498
+ extremeCount: data.extremeCount,
4499
+ coverageCount: data.coverageCount,
4500
+ totalCount: envelope.totalCount,
4501
+ present: true
4502
+ };
4503
+ const extreme = board.extremeCount === void 0 ? "n/a" : board.coverageCount === void 0 ? String(board.extremeCount) : `${board.extremeCount} of ${board.coverageCount}`;
4504
+ const blocks = [
4505
+ {
4506
+ kind: "head",
4507
+ title: field("board", `Options Radar, ${board.name}`),
4508
+ right: fields(field("session", data.asOf ?? "n/a"))
4509
+ }
4510
+ ];
4511
+ if (!board.present) {
4512
+ blocks.push({ kind: "text", text: "This build has no ETF board." });
4513
+ return { json: envelope, doc: doc(...blocks) };
4514
+ }
4515
+ blocks.push({
4516
+ kind: "facts",
4517
+ items: fields(
4518
+ field("Median IV rank", fixed(board.medianIvRank, 1)),
4519
+ field("Market put/call", fixed(board.marketPcVol, 2)),
4520
+ field("Names at an extreme", extreme)
4521
+ )
4522
+ });
4523
+ const served = board.rows.length;
4524
+ const shown = full ? board.rows : board.rows.slice(0, limit ?? DEFAULT_RADAR_ROWS);
4525
+ if (served === 0) {
4526
+ blocks.push({ kind: "text", text: `No rows on the ${board.name} board in this build.` });
4527
+ } else {
4528
+ blocks.push({ kind: "blank" });
4529
+ blocks.push({
4530
+ kind: "table",
4531
+ head: ["#", "TICKER", "NAME", "SCORE", "SENT", "P/C", "P/C PCTL", "IV RANK", "SKEW", "SKEW PCTL", "NOTIONAL"],
4532
+ align: ["right", "left", "left", "right", "right", "right", "right", "right", "right", "right", "right"],
4533
+ rows: shown.map((row, index) => [
4534
+ cell(String(index + 1)),
4535
+ cell(row.ticker ?? ""),
4536
+ cell(truncate(row.name ?? "", full ? 40 : 18)),
4537
+ cell(fixed(row.interestScore, 1)),
4538
+ cell(signed(row.sentiment, 2), direction(row.sentiment)),
4539
+ cell(fixed(row.pcVol, 2)),
4540
+ cell(fixed(row.pcVolPctl1y, 1)),
4541
+ cell(fixed(row.ivRank1y, 1)),
4542
+ cell(signed(row.skew25d, 4)),
4543
+ cell(fixed(row.skewPctl1y, 1)),
4544
+ cell(humanize(row.notionalVol))
4545
+ ])
4546
+ });
4547
+ const fullBoard = board.totalCount !== void 0 && board.totalCount > served ? board.totalCount : void 0;
4548
+ if (shown.length < served) {
4549
+ blocks.push({
4550
+ kind: "text",
4551
+ 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.`,
4552
+ tone: "dim"
4553
+ });
4554
+ } else if (fullBoard) {
4555
+ blocks.push({
4556
+ kind: "text",
4557
+ text: `Showing all ${served} served; the full board has ${fullBoard} names.`,
4558
+ tone: "dim"
4559
+ });
4560
+ }
4561
+ }
4562
+ if (board.highlights.length > 0) {
4563
+ blocks.push({ kind: "blank" });
4564
+ blocks.push({ kind: "text", text: "Session highlights, each ticker's highest-premium unusual contract:" });
4565
+ blocks.push({
4566
+ kind: "table",
4567
+ head: ["TICKER", "CONTRACT", "TYPE", "VOLUME", "VOL/OI", "PREMIUM"],
4568
+ align: ["left", "left", "left", "right", "right", "right"],
4569
+ rows: board.highlights.map((row) => [
4570
+ cell(row.ticker ?? ""),
4571
+ cell(row.contract ?? ""),
4572
+ cell(row.type ?? "", contractTone(row.type)),
4573
+ cell(humanize(row.volume, 0)),
4574
+ cell(fixed(row.volOiRatio, 1)),
4575
+ cell(humanize(row.premium))
4576
+ ])
4577
+ });
4578
+ }
4579
+ if (!etfs && (data.etfRows?.length ?? 0) > 0) {
4580
+ blocks.push({ kind: "text", text: "The ETF board is ranked separately: add --etfs.", tone: "dim" });
4581
+ }
4582
+ if (envelope.isPreview) {
4583
+ blocks.push({
4584
+ kind: "text",
4585
+ 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.",
4586
+ tone: "dim"
4587
+ });
4588
+ }
4589
+ return { json: envelope, doc: doc(...blocks) };
4590
+ }
4591
+ async function history(api, ticker, window, limit, full) {
4592
+ const envelope = await api.stocks.getOptionsHistory(ticker, window === void 0 ? void 0 : { window });
4593
+ const data = envelope.data;
4594
+ const series = data?.series ?? [];
4595
+ if (series.length === 0) {
4596
+ const note = await verifyTickerOnEmpty(api, ticker);
4597
+ return {
4598
+ json: envelope,
4599
+ doc: doc({ kind: "text", text: `No options coverage for ${ticker}.` }),
4600
+ notes: note ? [note] : void 0
4601
+ };
4602
+ }
4603
+ const served = data?.window ?? "n/a";
4604
+ const count = full ? series.length : Math.min(limit ?? DEFAULT_HISTORY_ROWS, series.length);
4605
+ const newest = series.slice(series.length - count).reverse();
4606
+ const blocks = [
4607
+ {
4608
+ kind: "head",
4609
+ title: field("ticker", ticker),
4610
+ right: fields(field("window", served), field("sessions", String(series.length)))
4611
+ },
4612
+ {
4613
+ kind: "table",
4614
+ head: ["DATE", "CALL VOL", "PUT VOL", "P/C", "CALL OI", "PUT OI", "ATM IV", "SKEW", "MAX UNUSUAL"],
4615
+ align: ["left", "right", "right", "right", "right", "right", "right", "right", "right"],
4616
+ rows: newest.map((row) => [
4617
+ cell(row.date ?? ""),
4618
+ cell(humanize(row.callVol, 1)),
4619
+ cell(humanize(row.putVol, 1)),
4620
+ cell(fixed(row.pcVol, 2)),
4621
+ cell(humanize(row.callOi, 1)),
4622
+ cell(humanize(row.putOi, 1)),
4623
+ cell(fixed(row.atmIv, 4)),
4624
+ cell(signed(row.skew25d, 4)),
4625
+ cell(humanize(row.maxUnusualPremium))
4626
+ ])
4627
+ },
4628
+ {
4629
+ kind: "text",
4630
+ 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.`,
4631
+ tone: "dim"
4632
+ }
4633
+ ];
4634
+ if (window !== void 0 && served !== window) {
4635
+ blocks.push({
4636
+ kind: "text",
4637
+ text: `Asked for ${window}, served ${served}: a free key is served 1y for every ticker except the sample companies.`,
4638
+ tone: "dim"
4639
+ });
4640
+ }
4641
+ blocks.push({
4642
+ kind: "text",
4643
+ text: "Open interest is the count going into each session, at the previous close.",
4644
+ tone: "dim"
4645
+ });
4646
+ return { json: envelope, doc: doc(...blocks, sampleNote(envelope, ticker)) };
4377
4647
  }
4378
4648
  async function intraday(api, ticker, session) {
4379
4649
  const envelope = await api.stocks.getOptionsIntradayHistory(ticker, { session });
@@ -4427,7 +4697,7 @@ async function intraday(api, ticker, session) {
4427
4697
  if (missing.length > 0) {
4428
4698
  blocks.push({
4429
4699
  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.`,
4700
+ 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
4701
  tone: "dim"
4432
4702
  });
4433
4703
  }
@@ -4438,13 +4708,163 @@ async function intraday(api, ticker, session) {
4438
4708
  });
4439
4709
  return { json: envelope, doc: doc(...blocks, sampleNote(envelope, ticker)) };
4440
4710
  }
4711
+ async function dossier(api, ticker, full) {
4712
+ const envelope = await api.stocks.getOptionsSummary(ticker);
4713
+ const data = envelope.data;
4714
+ if (!data) {
4715
+ const note = await verifyTickerOnEmpty(api, ticker);
4716
+ return {
4717
+ json: envelope,
4718
+ doc: doc({ kind: "text", text: `No options coverage for ${ticker}.` }),
4719
+ notes: note ? [note] : void 0
4720
+ };
4721
+ }
4722
+ const latest = data.latest ?? {};
4723
+ const context = data.context ?? {};
4724
+ const oiWalls = data.oiWalls ?? {};
4725
+ const ivRank = context.ivRank1y ?? data.ivRank1y;
4726
+ const pcVol = latest.pcVol ?? data.pcVol;
4727
+ const maxPain = data.oiWalls?.maxPain ?? data.maxPain;
4728
+ const blocks = [
4729
+ {
4730
+ kind: "head",
4731
+ title: field("ticker", ticker),
4732
+ right: fields(
4733
+ field("positioning", signed(data.sentiment, 2), direction(data.sentiment)),
4734
+ field("iv rank 1y", fixed(ivRank, 1)),
4735
+ field("put/call vol", fixed(pcVol, 2))
4736
+ )
4737
+ }
4738
+ ];
4739
+ if (data.listingStatus === "DELISTED") {
4740
+ const when = data.delistedDate ? ` (${data.delistedDate})` : "";
4741
+ const asOf = data.asOf ? `, as of ${data.asOf}` : "";
4742
+ blocks.push({
4743
+ kind: "text",
4744
+ text: `${ticker} is delisted${when}: this is the last dossier on record${asOf}.`
4745
+ });
4746
+ }
4747
+ blocks.push(
4748
+ {
4749
+ kind: "facts",
4750
+ items: fields(
4751
+ field("ATM IV", fixed(latest.atmIv ?? data.atmIv, 4)),
4752
+ field("Exp move 1d", fixed(latest.expectedMove1d ?? data.expectedMove1d, 4)),
4753
+ field("Skew 25d", signed(latest.skew25d, 4)),
4754
+ field("Call vol", humanize(latest.callVol, 1)),
4755
+ field("Put vol", humanize(latest.putVol, 1)),
4756
+ field("Notional", humanize(latest.notionalVol))
4757
+ )
4758
+ },
4759
+ {
4760
+ kind: "facts",
4761
+ items: fields(
4762
+ field("Max pain", strike(maxPain)),
4763
+ field("Wall expiry", data.oiWalls?.expiry ?? "n/a"),
4764
+ field("Call OI", humanize(latest.callOi, 1)),
4765
+ field("Put OI", humanize(latest.putOi, 1)),
4766
+ field("Contracts", humanize(latest.contracts, 0))
4767
+ )
4768
+ },
4769
+ {
4770
+ kind: "kv",
4771
+ items: fields(
4772
+ field("call walls", walls(data.oiWalls?.callWalls)),
4773
+ field("put walls", walls(data.oiWalls?.putWalls))
4774
+ )
4775
+ }
4776
+ );
4777
+ if (full) {
4778
+ blocks.push({
4779
+ kind: "kv",
4780
+ items: fields(
4781
+ field("term structure", `60d ${fixed(latest.atmIv60, 4)} 90d ${fixed(latest.atmIv90, 4)}`),
4782
+ field("net delta", humanize(latest.netDelta, 1)),
4783
+ field("put/call OI", fixed(latest.pcOi, 2)),
4784
+ field("pc vol percentile 1y", fixed(context.pcVolPctl1y ?? data.pcVolPctl1y, 1)),
4785
+ field("skew percentile 1y", fixed(context.skewPctl1y, 1)),
4786
+ field("observations 1y", fixed(context.observations1y, 0))
4787
+ )
4788
+ });
4789
+ blocks.push({
4790
+ kind: "kv",
4791
+ items: fields(
4792
+ field("pc vol percentile 5y", fixed(context.pcVolPctl5y, 1)),
4793
+ field("put/call OI percentile 1y", fixed(context.pcOiPctl1y, 1)),
4794
+ field("unusual premium percentile 1y", fixed(context.unusualPremiumPctl1y, 1)),
4795
+ field("exp move 5d", fixed(latest.expectedMove5d, 4)),
4796
+ field("exp move 20d", fixed(latest.expectedMove20d, 4)),
4797
+ field("wall expiry OI", `calls ${humanize(oiWalls.totalCallOi, 1)} puts ${humanize(oiWalls.totalPutOi, 1)}`),
4798
+ field("OI at max pain", `calls ${humanize(oiWalls.maxPainCallOi, 1)} puts ${humanize(oiWalls.maxPainPutOi, 1)}`)
4799
+ )
4800
+ });
4801
+ }
4802
+ const unusual = data.unusual ?? [];
4803
+ if (unusual.length > 0) {
4804
+ blocks.push({ kind: "blank" });
4805
+ blocks.push({
4806
+ kind: "table",
4807
+ head: ["CONTRACT", "TYPE", "STRIKE", "EXPIRY", "DTE", "VOLUME", "OI", "VOL/OI", "PREMIUM"],
4808
+ align: ["left", "left", "right", "left", "right", "right", "right", "right", "right"],
4809
+ rows: unusual.map((row) => [
4810
+ cell(row.contract ?? ""),
4811
+ cell(row.type ?? "", contractTone(row.type)),
4812
+ cell(strike(row.strike)),
4813
+ cell(row.expiry ?? ""),
4814
+ cell(row.dte === void 0 ? "" : String(row.dte)),
4815
+ cell(humanize(row.volume, 0)),
4816
+ cell(humanize(row.oi, 0)),
4817
+ cell(fixed(row.volOiRatio, 1)),
4818
+ cell(humanize(row.premium))
4819
+ ])
4820
+ });
4821
+ const followed = full ? unusual.filter(hasFollowUp) : [];
4822
+ if (followed.length > 0) {
4823
+ const vintage = followed.some((row) => row.oiVintage !== void 0);
4824
+ blocks.push({ kind: "blank" });
4825
+ blocks.push({ kind: "text", text: "Open interest follow-up on those contracts:" });
4826
+ blocks.push({
4827
+ kind: "table",
4828
+ head: ["CONTRACT", "OI PRIOR", "OI NEXT", "OI CHANGE", "FOLLOW-UP", ...vintage ? ["VINTAGE"] : []],
4829
+ align: ["left", "right", "right", "right", "left", "left"],
4830
+ rows: followed.map((row) => [
4831
+ cell(row.contract ?? ""),
4832
+ cell(humanize(row.oiPrior, 1)),
4833
+ cell(humanize(row.oiNext, 1)),
4834
+ cell(signedCount(row.oiChange)),
4835
+ cell(row.oiConfirmation ?? "n/a"),
4836
+ ...vintage ? [cell(row.oiVintage ?? "n/a")] : []
4837
+ ])
4838
+ });
4839
+ }
4840
+ }
4841
+ blocks.push({
4842
+ kind: "text",
4843
+ text: `session of ${data.asOf ?? latest.date ?? "an unrecorded date"}`,
4844
+ tone: "dim"
4845
+ });
4846
+ if (envelope.isPreview) {
4847
+ blocks.push({
4848
+ kind: "text",
4849
+ text: "Preview response: the free monthly dossier allowance is spent, so only the headline readings are shown.",
4850
+ tone: "dim"
4851
+ });
4852
+ }
4853
+ return {
4854
+ json: envelope,
4855
+ doc: doc(...blocks, allowanceLine(envelope.dossierAllowance), sampleNote(envelope, ticker))
4856
+ };
4857
+ }
4441
4858
  var optionsCommand = {
4442
4859
  name: "options",
4443
- summary: "End-of-day options positioning for one stock or ETF",
4444
- usage: "sentisense options <ticker> [--intraday] [--session YYYY-MM-DD]",
4860
+ summary: "End-of-day options: the market Radar, or one stock or ETF's positioning and history",
4861
+ usage: "sentisense options [--etfs] [--limit N] | sentisense options <ticker> [--history [--window 1y|2y|5y] [--limit N] | --intraday [--session YYYY-MM-DD]]",
4445
4862
  examples: [
4863
+ "sentisense options",
4864
+ "sentisense options --etfs --limit 25",
4446
4865
  "sentisense options NVDA",
4447
4866
  "sentisense options SPY --full",
4867
+ "sentisense options NVDA --history --window 2y",
4448
4868
  "sentisense options NVDA --json",
4449
4869
  "sentisense options NVDA --intraday",
4450
4870
  "sentisense options SPY --session 2026-10-14"
@@ -4453,18 +4873,39 @@ var optionsCommand = {
4453
4873
  "End of day, not live: readings describe the latest completed session and refresh the",
4454
4874
  "following morning. Percentiles are against that ticker's own trailing history, so they",
4455
4875
  "compare a stock to its past self, never to another stock.",
4876
+ "With no ticker it prints the Radar: the session's market aggregates, the stock board",
4877
+ "ranked by interest score, and the session highlights. --etfs shows the ETF board, which",
4878
+ "is ranked separately. A free key gets the top 25 rows and the top 3 highlights of each",
4879
+ "board, with every aggregate. --limit sets the rows printed (default 15).",
4456
4880
  "Coverage is the most actively optioned names plus the tracked ETFs. A real ticker",
4457
4881
  "outside that set reports no coverage and exits 0, the same as any other empty result.",
4458
4882
  EMPTY_VERIFY_NOTE,
4459
4883
  EMPTY_VERIFY_NOTE_2,
4460
4884
  "A free key gets the full dossier for the first ten calls each month, then a headline",
4461
4885
  "preview. Calls that return no dossier do not count against that. Sample companies are",
4462
- "always full and spend none of the ten.",
4886
+ "always full and spend none of the ten. On a free key the dossier says how many are left",
4887
+ "and when the count resets, whenever the API reports the count.",
4888
+ "--history shows the ticker's daily sessions, newest first (default 20, --limit changes",
4889
+ "it). --window picks 1y, 2y or 5y and implies --history. A free key is served 1y for every",
4890
+ "ticker except the sample companies, and the output names the window it was served.",
4463
4891
  "--intraday shows one session's intraday series instead: the ticker's volumes, put/call",
4464
4892
  "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."
4893
+ "--session picks the session and implies --intraday; omitted, the latest one.",
4894
+ "--full adds every served row to the Radar and --history, and more readings to a dossier."
4466
4895
  ],
4467
4896
  flags: {
4897
+ etfs: { type: "boolean", describe: "With no ticker, show the Radar's ETF board instead of the stock board" },
4898
+ limit: {
4899
+ type: "number",
4900
+ placeholder: "N",
4901
+ describe: `Rows to print: the Radar (default ${DEFAULT_RADAR_ROWS}) or --history (default ${DEFAULT_HISTORY_ROWS})`
4902
+ },
4903
+ history: { type: "boolean", describe: "Show the ticker's daily sessions, newest first" },
4904
+ window: {
4905
+ type: "string",
4906
+ placeholder: "1y|2y|5y",
4907
+ describe: "Window for --history (default 1y); implies --history"
4908
+ },
4468
4909
  intraday: { type: "boolean", describe: "Show the session's intraday series, every 15-minute cycle (PRO or a sample company)" },
4469
4910
  session: {
4470
4911
  type: "string",
@@ -4473,115 +4914,17 @@ var optionsCommand = {
4473
4914
  }
4474
4915
  },
4475
4916
  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
- });
4917
+ const view = pickView(args);
4918
+ switch (view.kind) {
4919
+ case "radar":
4920
+ return radar(client(), view.etfs, view.limit, full);
4921
+ case "history":
4922
+ return history(client(), view.ticker, view.window, view.limit, full);
4923
+ case "intraday":
4924
+ return intraday(client(), view.ticker, view.session);
4925
+ case "dossier":
4926
+ return dossier(client(), view.ticker, full);
4583
4927
  }
4584
- return { json: envelope, doc: doc(...blocks, sampleNote(envelope, ticker)) };
4585
4928
  }
4586
4929
  };
4587
4930