sentisense 0.63.1 → 0.66.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/README.md CHANGED
@@ -67,6 +67,7 @@ npx -y sentisense@latest health
67
67
  | Command | What you get |
68
68
  |---------|--------------|
69
69
  | `auth [key]` | Store a key, show what is configured, or `--remove` it |
70
+ | `init` | A temporary key with no signup, printed as `SENTISENSE_API_KEY=...`, plus a link to keep it |
70
71
  | `health` | Reachability, key validity, latency, and the resolved base URL |
71
72
  | `quote <ticker>...` | Price, day range, 52-week range, market cap, P/E. One request per ticker; ETFs show AUM, expense ratio and NAV |
72
73
  | `sentiment <ticker>` | SentiSense Score, tone, attention, per-source breakdown, `--days N` history |
@@ -79,12 +80,23 @@ npx -y sentisense@latest health
79
80
  | `congress [ticker]` | Congressional disclosures, market-wide or for one symbol |
80
81
  | `news [ticker]` | Clustered news stories with impact and tone |
81
82
  | `flows [ticker]` | Institutional 13F flows, or one ticker's holders and notable changes |
82
- | `options <ticker>` | End-of-day options positioning, IV rank, walls, unusual contracts |
83
- | `screen --filter ...` | Screen the universe on Score, analyst, technical, and price fields |
83
+ | `options <ticker>` | End-of-day options positioning, IV rank, walls, unusual contracts; `--intraday` for the session's 15-minute series (PRO) |
84
+ | `screen --filter ...` | Screen the universe on Score, analyst, technical, price, and end-of-day options fields |
84
85
  | `search <name>` | Resolve a name, alias, ticker or slug to a symbol and the entity handle |
85
86
 
86
87
  Run `sentisense help <command>` for its flags and examples.
87
88
 
89
+ ### Getting a key with no signup
90
+
91
+ `init` is built for coding agents: it asks nothing and writes nothing into your project.
92
+
93
+ ```bash
94
+ npx -y sentisense@latest init # prints SENTISENSE_API_KEY=<key> and a keep link
95
+ npx -y sentisense@latest init --json # the same, as JSON
96
+ ```
97
+
98
+ It prints a temporary free key as `SENTISENSE_API_KEY=<key>`. Store it the way your project already stores secrets; the SDK and every command read `SENTISENSE_API_KEY` from the environment. To keep the key, open the link it prints, sign in or create a free account, and the same key stays on your account with nothing else to change. Until it is kept, the key stops working after a few days and has request limits; the link still keeps it for about two weeks. When a key is already configured, `init` says so and makes no new one; `--new` asks for a fresh temporary key anyway. To tell machines that share a network apart, the request carries a random per-install id, stored as `install-id` in the CLI's config directory; it identifies nothing about you.
99
+
88
100
  Three of these chain into each other. Start from a name, land on a person:
89
101
 
90
102
  ```bash
@@ -183,9 +195,9 @@ Affected: every method whose declared return type is `PreviewResponse<T>`. A tes
183
195
  | `institutional` | `getFlows` `getHolders` `getActivists` |
184
196
  | `options` | `getOverview` |
185
197
  | `politicians` | `getActivity` `getFilings` `getMembers` `getMember` |
186
- | `stocks` | `getSentiment` `getKpis` `getOptionsSummary` `getOptionsHistory` |
198
+ | `stocks` | `getSentiment` `getKpis` `getOptionsSummary` `getOptionsHistory` `getOptionsIntradayHistory` |
187
199
 
188
- The envelope itself is always an object, so test the payload rather than the response. Two of these declare a `data` that can be null: `stocks.getOptionsSummary`, for a ticker outside the covered options universe, and `options.getOverview`, before its first nightly build. Everywhere else `data` is an array or an object.
200
+ The envelope itself is always an object, so test the payload rather than the response. Three of these declare a `data` that can be null: `stocks.getOptionsSummary`, for a ticker outside the covered options universe, `options.getOverview`, before its first nightly build, and `stocks.getOptionsIntradayHistory`, on a FREE key's `PRO_REQUIRED` preview. Everywhere else `data` is an array or an object.
189
201
 
190
202
  ```typescript
191
203
  const flows = await client.institutional.getFlows();
@@ -244,6 +256,7 @@ client.stocks.getFloat("GME") // Free float
244
256
  client.stocks.getGraph("AAPL", { depth: 1 }) // Company knowledge graph: people, products, peers
245
257
  client.stocks.getOptionsSummary("NVDA") // End-of-day options dossier
246
258
  client.stocks.getOptionsHistory("NVDA", { window: "2y" }) // Daily options aggregates over time
259
+ client.stocks.getOptionsIntradayHistory("NVDA") // One session's intraday options series (PRO)
247
260
  client.stocks.getRating("AAPL") // SentiSense Rating: score, letter, percentile, dimensions
248
261
  client.stocks.getAISummary("AAPL", { depth: "deep" }) // AI report (PRO)
249
262
  ```
@@ -521,11 +534,29 @@ End-of-day options positioning: where implied volatility, put/call flow and skew
521
534
  client.options.getOverview() // Market-wide radar, ranked
522
535
  client.stocks.getOptionsSummary("NVDA") // One name's full dossier
523
536
  client.stocks.getOptionsHistory("NVDA", { window: "2y" }) // That name's daily series
537
+ client.stocks.getOptionsIntradayHistory("NVDA", { session: "2026-10-14" }) // Every 15-minute cycle of one session (PRO)
524
538
  ```
525
539
 
526
540
  The radar carries two separately-ranked boards: `data.rows` for stocks and `data.etfRows` for ETFs. Keep them apart. Every reading behind a row's `interestScore` is a percentile of that ticker's own trailing history, so a ranking built across both boards compares numbers measured against different baselines. The aggregates split the same way, with the `etf`-prefixed fields describing the ETF board alone.
527
541
 
528
- During the trading session the dossier and the radar also carry a few intraday fields, the same on every tier: `intradayFlow` (a count of the ticker's unusual contracts so far, when the first one was flagged, and the board's own clock), `largePrintCount` and `largestPrintPctl` on the dossier, and `intradayActiveCount` with `intradayRanking` on the radar. They carry no contract, strike, price or premium, and are absent before the day's first board. `capabilities.intradayBoard` says where the contract-level board lives; its rows are served in the SentiSense app, not by the API.
542
+ During the trading session the dossier and the radar also carry a few intraday fields, the same on every tier: `intradayFlow` (a count of the ticker's unusual contracts so far, when the first one was flagged, and the board's own clock), `largePrintCount` and `largestPrintPctl` on the dossier, and `intradayActiveCount` with `intradayRanking` on the radar. They carry no contract, strike, price or premium, and are absent before the day's first board. On the radar, `intradayAsOf` (epoch seconds) and `intradayAsOfEt` date the board the ranking was read from. `capabilities.intradayBoard` says where the contract-level board lives; its rows are served in the SentiSense app, not by the API.
543
+
544
+ `getOptionsIntradayHistory` keeps every cycle of that board for one ticker, so you can test an intraday signal against what the board showed at each point in the day and then compare it with the session's end-of-day row from `getOptionsHistory`:
545
+
546
+ ```typescript
547
+ const day = await client.stocks.getOptionsIntradayHistory("NVDA", { session: "2026-10-14" });
548
+ if (day.data === null) {
549
+ console.log(day.upgrade?.message); // PRO only: a FREE key gets a preview with no series
550
+ } else {
551
+ for (const point of day.data.series) { // oldest cycle first
552
+ console.log(point.asOfEt, point.callVol, point.putVol, point.pcVol, point.unusualCount, point.atmIv);
553
+ }
554
+ }
555
+ ```
556
+
557
+ Each point carries call and put volume so far, the put/call ratio, the unusual-contract count, the percentile of the largest qualifying contract against the ticker's own year (`maxPremiumPctl1y`) and the ATM implied volatility; readings that are unavailable are absent, never zero. Omit `session` for the session the board ran most recently, and read `data.session` for the date served. A ticker appears only on cycles where it was on the board, so gaps show in each point's `cycle`, and `missingCycles` lists cycles whose stored point could not be read. A weekend, a holiday, a ticker outside the board and an unknown symbol all return an empty `series`, not a null payload. A malformed or future date rejects with an `APIError` whose `code` is `"invalid_session"`. From the CLI: `sentisense options NVDA --intraday`, or `--session YYYY-MM-DD` for another day.
558
+
559
+ A FREE key that has spent its ten monthly dossiers receives a headline preview from `getOptionsSummary`: `asOf`, `sentiment` and six flat readings, `ivRank1y`, `atmIv`, `expectedMove1d`, `pcVol`, `pcVolPctl1y` and `maxPain`, with no `latest`, `context` or `oiWalls`. On a full dossier those six are absent and the same readings live in the nested objects, so branch on `isPreview`.
529
560
 
530
561
  A row whose baseline is still building carries its raw readings with the percentiles and `interestScore` omitted, which means "not enough history yet" rather than "nothing interesting". `getOptionsSummary` reports an uncovered ticker as a null payload inside the usual envelope, so the check is `result.data === null`: the response object itself is always truthy, and a bare `if (summary === null)` never fires. `getOptionsHistory` reports it as an empty `series` instead, so check the array's length rather than null-checking there.
531
562
 
@@ -578,7 +609,7 @@ An empty array is the normal answer for a query that matches nothing, so branch
578
609
 
579
610
  ### Screener
580
611
 
581
- Filter the tracked universe on the SentiSense Score, attention, analyst consensus, technicals and price in one query. Screening on analyst ratings alone is something a dozen free tools do; screening on analyst ratings *where the Score disagrees* is not.
612
+ Filter the tracked universe on the SentiSense Score, attention, analyst consensus, technicals, price and end-of-day options readings in one query. Screening on analyst ratings alone is something a dozen free tools do; screening on analyst ratings *where the Score disagrees* is not.
582
613
 
583
614
  ```typescript
584
615
  client.screener.fields() // Every filterable field, both universes, with units + operators
@@ -609,6 +640,18 @@ const res = await client.screener.run({
609
640
  for (const row of res.results) {
610
641
  console.log(row.ticker, row.sentiSenseScore7D, row.analystBuyRatioPct);
611
642
  }
643
+
644
+ // Options positioning: implied volatility in the top quarter of its own year
645
+ const highIv = await client.screener.run({
646
+ plan: {
647
+ filters: [{ fieldName: "IV_RANK_1Y", op: "GTE", value: 75 }],
648
+ sort: { fieldName: "IV_RANK_1Y", dir: "DESC" },
649
+ },
650
+ limit: 25,
651
+ });
652
+ for (const row of highIv.results) {
653
+ console.log(row.ticker, row.ivRank1y, row.expectedMove20d, row.optionsAsOf);
654
+ }
612
655
  ```
613
656
 
614
657
  `limit` rides 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. `matched` is the count before `limit` was applied, so truncation is visible. `tickers` is optional: omit it to screen the whole tracked universe, pass a list to screen a watchlist.
@@ -623,7 +666,11 @@ The Score fields (`SENTI_SCORE_7D`, `SENTI_SCORE_1M`, `SCORE_CHANGE_7D`) are the
623
666
 
624
667
  On the ETF side, `CONSTITUENTS_WEIGHTED_SENTISENSE` is the holdings-weighted 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. `WEIGHT_COVERED_PCT` tells you how much of the fund's weight had constituent data behind the weighted number.
625
668
 
626
- Screens read a snapshot that refreshes every 20 minutes, so this is not a quote feed. Use `client.stocks.getQuote()` for current quotes.
669
+ Stock rows also carry seven end-of-day options readings, `ivRank1y`, `pcVol`, `pcVolPctl1y`, `skew25dPctl1y`, `optionsInterestScore`, `maxUnusualPremium` and `expectedMove20d`, plus `optionsAsOf`, the session date they are from. `expectedMove20d` is a fraction of price (`0.2` is 20%) and `optionsAsOf` is a `YYYY-MM-DD` date; filter on the options fields with names like `IV_RANK_1Y`.
670
+
671
+ Every stock row carries `priceAsOf`, when the market data behind `currentPrice`, `change` and `changePercent` is from, in epoch milliseconds (the same unit as the quote endpoints). It is `null` outside regular hours, on a previous-close fallback and when no quote was available, so read `null` as unknown rather than fresh, and judge a price's age from `priceAsOf`, not `lastUpdated`. Rated stocks also carry `ratingLetter`, `ratingScore` and `ratingPercentile`; all three are `null` for an unrated one.
672
+
673
+ Prices are 15-minute delayed quotes, refreshed at request time during the regular session from a cache at most 5 minutes old. Everything else on a row comes from a snapshot rebuilt about every 20 minutes during the session, so this is not a quote feed: use `client.stocks.getQuote()` for one ticker's current quote.
627
674
 
628
675
  ## Error handling
629
676
 
package/dist/cli.cjs CHANGED
@@ -72,6 +72,10 @@ var EXIT_TABLE = [
72
72
  var KEY_URL = "https://app.sentisense.ai/get-api-key";
73
73
  var PRICING_URL = "https://app.sentisense.ai/pricing";
74
74
  var QUOTA_EXCEEDED = "quota_exceeded";
75
+ var KEY_LIMIT_REACHED = "key_limit_reached";
76
+ var KEY_EXPIRED = "key_expired";
77
+ var KEY_NOT_KEPT = "key_not_kept";
78
+ var KEEP_HINT = "keep the key with the keep link (in the message above, or the one sentisense init printed with the key), then run it again.";
75
79
  var CliUsageError = class extends Error {
76
80
  constructor(message, hint) {
77
81
  super(message);
@@ -94,6 +98,14 @@ var NoMatchError = class extends Error {
94
98
  this.hint = hint;
95
99
  }
96
100
  };
101
+ var CliCommandError = class extends Error {
102
+ constructor(message, hint, exitCode = EXIT.ERROR) {
103
+ super(message);
104
+ this.name = "CliCommandError";
105
+ this.hint = hint;
106
+ this.exitCode = exitCode;
107
+ }
108
+ };
97
109
  var MissingKeyError = class extends Error {
98
110
  constructor() {
99
111
  super("no API key configured.");
@@ -132,6 +144,12 @@ function classify(error, command) {
132
144
  lines: [`error: ${error.message}`, `next: ${error.hint}`]
133
145
  };
134
146
  }
147
+ if (error instanceof CliCommandError) {
148
+ return {
149
+ exitCode: error.exitCode,
150
+ lines: [`error: ${error.message}`, `next: ${error.hint}`]
151
+ };
152
+ }
135
153
  if (error instanceof CliUsageError) {
136
154
  return {
137
155
  exitCode: EXIT.USAGE,
@@ -141,6 +159,19 @@ function classify(error, command) {
141
159
  ]
142
160
  };
143
161
  }
162
+ if (error instanceof AuthenticationError && error.code === KEY_EXPIRED) {
163
+ const keepable = /\/keep-key\b/.test(error.message);
164
+ return {
165
+ exitCode: EXIT.AUTH,
166
+ lines: [
167
+ `error: ${error.message}`,
168
+ keepable ? "next: open the keep link above and sign in; the same key works again with nothing in the project to change." : `next: run "sentisense init --new" for a new key, or get one at ${KEY_URL}`
169
+ ]
170
+ };
171
+ }
172
+ if (error instanceof AuthenticationError && error.code === KEY_NOT_KEPT) {
173
+ return { exitCode: EXIT.AUTH, lines: [`error: ${error.message}`, `next: ${KEEP_HINT}`] };
174
+ }
144
175
  if (error instanceof AuthenticationError) {
145
176
  return {
146
177
  exitCode: EXIT.AUTH,
@@ -159,6 +190,9 @@ function classify(error, command) {
159
190
  ]
160
191
  };
161
192
  }
193
+ if (error instanceof RateLimitError && error.code === KEY_LIMIT_REACHED) {
194
+ return { exitCode: EXIT.RATE_LIMIT, lines: [`error: ${error.message}`, `next: ${KEEP_HINT}`] };
195
+ }
162
196
  if (error instanceof RateLimitError) {
163
197
  if (error.code === QUOTA_EXCEEDED) {
164
198
  return {
@@ -749,10 +783,13 @@ async function coverageRun({ api, ticker, lookbackDays, full, args }) {
749
783
  }
750
784
 
751
785
  // src/cli/config.ts
786
+ var import_node_crypto = require("crypto");
752
787
  var import_node_fs = require("fs");
753
788
  var import_node_os = require("os");
754
789
  var import_node_path = require("path");
755
790
  var CONFIG_FILE = "config.json";
791
+ var INSTALL_ID_FILE = "install-id";
792
+ var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
756
793
  function resolveConfigDir(env, override) {
757
794
  if (override) return override;
758
795
  const explicit = env.SENTISENSE_CONFIG_DIR?.trim();
@@ -789,6 +826,22 @@ function writeConfig(dir, config) {
789
826
  (0, import_node_fs.chmodSync)(path, 384);
790
827
  return path;
791
828
  }
829
+ function readOrCreateInstallId(dir) {
830
+ const path = (0, import_node_path.join)(dir, INSTALL_ID_FILE);
831
+ try {
832
+ if ((0, import_node_fs.existsSync)(path)) {
833
+ const stored = (0, import_node_fs.readFileSync)(path, "utf8").trim().toLowerCase();
834
+ if (UUID_PATTERN.test(stored)) return stored;
835
+ }
836
+ const id = (0, import_node_crypto.randomUUID)();
837
+ (0, import_node_fs.mkdirSync)(dir, { recursive: true, mode: 448 });
838
+ (0, import_node_fs.writeFileSync)(path, `${id}
839
+ `, { mode: 384 });
840
+ return (0, import_node_fs.readFileSync)(path, "utf8").trim() === id ? id : null;
841
+ } catch {
842
+ return null;
843
+ }
844
+ }
792
845
  function clearConfig(dir) {
793
846
  const path = configPath(dir);
794
847
  if (!(0, import_node_fs.existsSync)(path)) return false;
@@ -1356,7 +1409,7 @@ var flowsCommand = {
1356
1409
  };
1357
1410
 
1358
1411
  // src/version.ts
1359
- var VERSION = "0.63.1";
1412
+ var VERSION = "0.66.0";
1360
1413
 
1361
1414
  // src/resources/analyst.ts
1362
1415
  var Analyst = class {
@@ -2518,7 +2571,9 @@ var Stocks = class {
2518
2571
  *
2519
2572
  * Tiering: a PRO key always receives the full dossier. A FREE key receives it for the first
2520
2573
  * ten calls each calendar month and a headline-only preview after that, with `isPreview`
2521
- * true; calls that return a null `data` never spend that allowance.
2574
+ * true; calls that return a null `data` never spend that allowance. The headline preview has
2575
+ * no nested objects: its readings arrive flat as `data.ivRank1y`, `data.atmIv`,
2576
+ * `data.expectedMove1d`, `data.pcVol`, `data.pcVolPctl1y` and `data.maxPain`.
2522
2577
  */
2523
2578
  async getOptionsSummary(ticker) {
2524
2579
  return this.client.get(
@@ -2548,6 +2603,33 @@ var Stocks = class {
2548
2603
  options
2549
2604
  );
2550
2605
  }
2606
+ /**
2607
+ * Get one stock's or ETF's intraday options series for one session: its numbers at every
2608
+ * 15-minute cycle of the intraday board, oldest cycle first.
2609
+ *
2610
+ * Use it to test an intraday signal against what the board actually showed at each point in
2611
+ * the day, then compare it with the session's end-of-day row from
2612
+ * {@link Stocks.getOptionsHistory}. Each point carries call and put volume so far, the
2613
+ * put/call ratio, the unusual-contract count, the percentile of the largest qualifying
2614
+ * contract against the ticker's own year, and the ATM implied volatility. It never carries a
2615
+ * contract symbol, strike, price, premium, open interest or print size.
2616
+ *
2617
+ * **PRO only.** A FREE key receives the standard preview: `isPreview` true, `previewReason`
2618
+ * `"PRO_REQUIRED"`, an `upgrade` hint, and `data: null`.
2619
+ *
2620
+ * **No data is an empty `series`, not a null payload.** A weekend, a holiday, a session from
2621
+ * before the history was kept, a ticker outside the board and an unknown symbol all answer
2622
+ * with `data.series` empty. `data.missingCycles` lists cycles whose stored point could not be
2623
+ * read, which are unknown rather than absent. A malformed or future `session` rejects with
2624
+ * an `APIError` (status 400, code `invalid_session`). A 503 means the stored series could
2625
+ * not be read; it is retried like any other 503 and never answered with a partial series.
2626
+ */
2627
+ async getOptionsIntradayHistory(ticker, options) {
2628
+ return this.client.get(
2629
+ `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/options/intraday-history`,
2630
+ options
2631
+ );
2632
+ }
2551
2633
  /**
2552
2634
  * Get the SentiSense Rating for one stock: where it ranks against the other stocks rated
2553
2635
  * that day, and the six dimensions the rank is blended from.
@@ -2679,11 +2761,11 @@ var DEEP_HISTORY_FALLBACK_WAIT_S = 3;
2679
2761
  var MAX_DEEP_HISTORY_WAIT_S = 30;
2680
2762
  var MAX_RATE_LIMIT_WAIT_S = 120;
2681
2763
  var RATE_LIMIT_FALLBACK_WAIT_S = 60;
2682
- var QUOTA_EXCEEDED_CODE = "quota_exceeded";
2683
- async function isQuotaExceeded(response) {
2764
+ var NON_RETRYABLE_429_CODES = /* @__PURE__ */ new Set(["quota_exceeded", "key_limit_reached"]);
2765
+ async function isAllowanceExhausted(response) {
2684
2766
  try {
2685
2767
  const body = await response.clone().json();
2686
- return body?.error === QUOTA_EXCEEDED_CODE;
2768
+ return typeof body?.error === "string" && NON_RETRYABLE_429_CODES.has(body.error);
2687
2769
  } catch {
2688
2770
  return false;
2689
2771
  }
@@ -2773,7 +2855,7 @@ var SentiSense = class {
2773
2855
  );
2774
2856
  }
2775
2857
  if (!response.ok) {
2776
- if (response.status === 429 && await isQuotaExceeded(response)) {
2858
+ if (response.status === 429 && await isAllowanceExhausted(response)) {
2777
2859
  await this.handleErrorResponse(response);
2778
2860
  }
2779
2861
  const isRetryable = response.status === 429 || response.status >= 500;
@@ -2822,9 +2904,10 @@ var SentiSense = class {
2822
2904
  throw new SentiSenseError("All retries exhausted");
2823
2905
  }
2824
2906
  /** @internal */
2825
- async post(path, body) {
2907
+ async post(path, body, extraHeaders) {
2826
2908
  const url = this.buildUrl(path);
2827
2909
  const headers = {
2910
+ ...extraHeaders,
2828
2911
  "Accept": "application/json",
2829
2912
  "Content-Type": "application/json"
2830
2913
  };
@@ -3178,6 +3261,152 @@ var healthCommand = {
3178
3261
  }
3179
3262
  };
3180
3263
 
3264
+ // src/cli/commands/init.ts
3265
+ var ENV_VAR = "SENTISENSE_API_KEY";
3266
+ var KEY_PATTERN = /^[A-Za-z0-9_-]{8,128}$/;
3267
+ var PROVISION_PATH = "/api/v1/keys/provision";
3268
+ var CLIENT_ID_HEADER = "X-SentiSense-Client-Id";
3269
+ var LLMS_URL = "https://sentisense.ai/llms.txt";
3270
+ var SKILL_URL = "https://sentisense.ai/skill.md";
3271
+ var SOURCE_TEXT = {
3272
+ config: 'your own key saved with "sentisense auth"',
3273
+ flag: "the key passed with --api-key",
3274
+ env: "the key in your SENTISENSE_API_KEY environment variable"
3275
+ };
3276
+ var BY_HAND = `get a free key at ${KEY_URL}.`;
3277
+ function formatUtc(epochSeconds) {
3278
+ return `${new Date(epochSeconds * 1e3).toISOString().slice(0, 16).replace("T", " ")} UTC`;
3279
+ }
3280
+ function isProvisionedKey(value) {
3281
+ if (!value || typeof value !== "object") return false;
3282
+ const body = value;
3283
+ return typeof body.apiKey === "string" && KEY_PATTERN.test(body.apiKey) && typeof body.expiresAt === "number" && Number.isFinite(body.expiresAt) && typeof body.keepUrl === "string" && /^https?:\/\/\S+$/.test(body.keepUrl);
3284
+ }
3285
+ async function mintKey(context) {
3286
+ const client = createClient(context, { anonymous: true });
3287
+ const installId = readOrCreateInstallId(context.configDir);
3288
+ let answer;
3289
+ try {
3290
+ answer = await client.post(PROVISION_PATH, {}, installId ? { [CLIENT_ID_HEADER]: installId } : void 0);
3291
+ } catch (error) {
3292
+ if (error instanceof NotFoundError || error instanceof AuthenticationError && error.status === 401) {
3293
+ throw new CliCommandError("this SentiSense server does not hand out keys from the command line.", BY_HAND, EXIT.AUTH);
3294
+ }
3295
+ if (error instanceof RateLimitError && error.code === "keep_existing_key") {
3296
+ throw new CliCommandError(
3297
+ error.message,
3298
+ `open the keep link that came with the key init gave you before and sign in, or ${BY_HAND}`,
3299
+ EXIT.RATE_LIMIT
3300
+ );
3301
+ }
3302
+ if (error instanceof RateLimitError) {
3303
+ throw new CliCommandError(error.message, BY_HAND, EXIT.RATE_LIMIT);
3304
+ }
3305
+ if (error instanceof SentiSenseError && error.code === "provision_paused") {
3306
+ throw new CliCommandError(error.message, `try again after 00:00 UTC, or ${BY_HAND}`, EXIT.RATE_LIMIT);
3307
+ }
3308
+ if (error instanceof AuthenticationError) {
3309
+ throw new CliCommandError(error.message, BY_HAND, EXIT.AUTH);
3310
+ }
3311
+ if (error instanceof SentiSenseError && error.status !== void 0 && error.status >= 500) {
3312
+ throw new CliCommandError(error.message, `try again in a few minutes, or ${BY_HAND}`, EXIT.ERROR);
3313
+ }
3314
+ throw error;
3315
+ }
3316
+ if (!isProvisionedKey(answer)) {
3317
+ throw new CliCommandError("the server's answer did not contain a usable key.", BY_HAND, EXIT.ERROR);
3318
+ }
3319
+ return answer;
3320
+ }
3321
+ function limitsText(limits) {
3322
+ if (!limits) return "";
3323
+ const parts = [];
3324
+ if (limits.requestsPerDay) parts.push(`${limits.requestsPerDay.toLocaleString("en-US")} a day`);
3325
+ if (limits.requestsPerMinute) parts.push(`${limits.requestsPerMinute} a minute`);
3326
+ if (limits.requestsTotal) {
3327
+ const pace = parts.length ? ` (at most ${parts.join(", ")})` : "";
3328
+ return ` Until it is kept, the key has ${limits.requestsTotal.toLocaleString("en-US")} requests in all${pace}.`;
3329
+ }
3330
+ return parts.length ? ` Until it is kept, the key allows ${parts.join(" and ")}.` : "";
3331
+ }
3332
+ var initCommand = {
3333
+ name: "init",
3334
+ summary: "Get an API key with no signup and print it, with a link to keep it",
3335
+ usage: "sentisense init [--new]",
3336
+ examples: ["npx sentisense init", "npx sentisense init --json", "npx sentisense init --new"],
3337
+ notes: [
3338
+ "Runs without prompts, so a coding agent can run it. It writes nothing into your project:",
3339
+ "it prints SENTISENSE_API_KEY=<key> and a keep link. Store the key the way the project",
3340
+ "already stores secrets (an environment variable, a .env file kept out of git, a secret",
3341
+ "manager). The SDK and every sentisense command read SENTISENSE_API_KEY from the environment.",
3342
+ "The key is temporary until kept: open the link, sign in or create a free account, and the",
3343
+ "same key stays on your account. Until then it stops working after a few days and has request",
3344
+ "limits; the link keeps it for about two weeks, even after it stops working.",
3345
+ "When a key is already configured (--api-key, the environment, or sentisense auth), init says",
3346
+ "so and makes no new one; --new asks for a fresh temporary key anyway.",
3347
+ "Exits 3 when no key could be obtained, 5 when today's temporary keys for this network are",
3348
+ "used up."
3349
+ ],
3350
+ flags: {
3351
+ new: { type: "boolean", describe: "Ask for a fresh temporary key even when one is already configured" }
3352
+ },
3353
+ async run({ args, context }) {
3354
+ if (args.positionals.length > 0) {
3355
+ throw new CliUsageError(`init takes no arguments, got "${args.positionals[0]}".`, "run it as: sentisense init");
3356
+ }
3357
+ if (context.apiKey && args.flags.new !== true) {
3358
+ const source = context.apiKeySource === "default" ? "config" : context.apiKeySource;
3359
+ return {
3360
+ json: {
3361
+ apiKey: null,
3362
+ configured: { source, masked: maskKey(context.apiKey) },
3363
+ temporary: false,
3364
+ envVar: ENV_VAR,
3365
+ docs: { llms: LLMS_URL, skill: SKILL_URL }
3366
+ },
3367
+ doc: doc(
3368
+ { kind: "text", text: `A key is already configured: ${SOURCE_TEXT[source]} (${maskKey(context.apiKey)}).` },
3369
+ { kind: "text", text: 'No new key was made. Run "sentisense init --new" for a fresh temporary key.', tone: "dim" }
3370
+ )
3371
+ };
3372
+ }
3373
+ const minted = await mintKey(context);
3374
+ const keepWindow = minted.keepUntil ? `; it works until ${formatUtc(minted.keepUntil)}, even after the key stops` : "";
3375
+ return {
3376
+ json: {
3377
+ apiKey: minted.apiKey,
3378
+ envVar: ENV_VAR,
3379
+ temporary: true,
3380
+ expiresAt: minted.expiresAt,
3381
+ keepUntil: minted.keepUntil ?? null,
3382
+ keepUrl: minted.keepUrl,
3383
+ limits: minted.limits ?? null,
3384
+ docs: { llms: LLMS_URL, skill: SKILL_URL }
3385
+ },
3386
+ doc: doc(
3387
+ { kind: "text", text: `${ENV_VAR}=${minted.apiKey}` },
3388
+ { kind: "blank" },
3389
+ {
3390
+ kind: "text",
3391
+ text: `A temporary key, working until ${formatUtc(minted.expiresAt)} unless kept. Set it as the ${ENV_VAR} environment variable wherever this project keeps its secrets; the SDK and the sentisense commands read it from there.`
3392
+ },
3393
+ { kind: "blank" },
3394
+ {
3395
+ kind: "text",
3396
+ text: "Keep this key: open this link and sign in (or create a free account), and the same key stays on your account for good. Nothing else changes."
3397
+ },
3398
+ { kind: "text", text: minted.keepUrl, tone: "accent" },
3399
+ {
3400
+ kind: "text",
3401
+ text: `Save the link with the key${keepWindow}.${limitsText(minted.limits)}`,
3402
+ tone: "dim"
3403
+ },
3404
+ { kind: "text", text: `API reference for agents: ${LLMS_URL}`, tone: "dim" }
3405
+ )
3406
+ };
3407
+ }
3408
+ };
3409
+
3181
3410
  // src/cli/commands/insiders.ts
3182
3411
  var insidersCommand = {
3183
3412
  name: "insiders",
@@ -3584,6 +3813,7 @@ var newsCommand = {
3584
3813
  };
3585
3814
 
3586
3815
  // src/cli/commands/options.ts
3816
+ var SESSION_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
3587
3817
  function contractTone(type) {
3588
3818
  const side = type?.toUpperCase();
3589
3819
  if (side === "CALL") return "up";
@@ -3594,14 +3824,79 @@ function walls(rows) {
3594
3824
  if (!rows || rows.length === 0) return "n/a";
3595
3825
  return rows.map((wall) => `${fixed(wall.strike, 0)} (${humanize(wall.oi, 1)})`).join(" ");
3596
3826
  }
3827
+ async function intraday(api, ticker, session) {
3828
+ const envelope = await api.stocks.getOptionsIntradayHistory(ticker, { session });
3829
+ const data = envelope.data;
3830
+ if (envelope.isPreview && !data) {
3831
+ const lines = [
3832
+ { kind: "text", text: `Intraday options history for ${ticker} needs a PRO key.` }
3833
+ ];
3834
+ if (envelope.upgrade?.url) {
3835
+ lines.push({ kind: "text", text: envelope.upgrade.url, tone: "dim" });
3836
+ }
3837
+ return { json: envelope, doc: doc(...lines) };
3838
+ }
3839
+ const series = data?.series ?? [];
3840
+ const served = data?.session ?? session ?? "the latest session";
3841
+ if (series.length === 0) {
3842
+ const note = await verifyTickerOnEmpty(api, ticker);
3843
+ return {
3844
+ json: envelope,
3845
+ doc: doc({ kind: "text", text: `No intraday options history for ${ticker} on ${served}.` }),
3846
+ notes: note ? [note] : void 0
3847
+ };
3848
+ }
3849
+ const blocks = [
3850
+ {
3851
+ kind: "head",
3852
+ title: field("ticker", ticker),
3853
+ right: fields(
3854
+ field("session", served),
3855
+ field("board", data?.live ? "live" : "closed", data?.live ? "accent" : void 0),
3856
+ field("cycles", String(data?.cycles ?? series.length))
3857
+ )
3858
+ },
3859
+ {
3860
+ kind: "table",
3861
+ head: ["CYCLE", "TIME", "CALL VOL", "PUT VOL", "P/C", "UNUSUAL", "PCTL 1Y", "ATM IV"],
3862
+ align: ["right", "left", "right", "right", "right", "right", "right", "right"],
3863
+ rows: series.map((point) => [
3864
+ cell(String(point.cycle)),
3865
+ cell(point.asOfEt ?? ""),
3866
+ cell(humanize(point.callVol, 1)),
3867
+ cell(humanize(point.putVol, 1)),
3868
+ cell(fixed(point.pcVol, 2)),
3869
+ cell(String(point.unusualCount ?? 0)),
3870
+ cell(fixed(point.maxPremiumPctl1y, 1)),
3871
+ cell(fixed(point.atmIv, 4))
3872
+ ])
3873
+ }
3874
+ ];
3875
+ const missing = data?.missingCycles ?? [];
3876
+ if (missing.length > 0) {
3877
+ blocks.push({
3878
+ kind: "text",
3879
+ 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.`,
3880
+ tone: "dim"
3881
+ });
3882
+ }
3883
+ blocks.push({
3884
+ kind: "text",
3885
+ text: `Volumes are cumulative for the session, from chains delayed ${data?.delayMinutes ?? 15} minutes.`,
3886
+ tone: "dim"
3887
+ });
3888
+ return { json: envelope, doc: doc(...blocks) };
3889
+ }
3597
3890
  var optionsCommand = {
3598
3891
  name: "options",
3599
3892
  summary: "End-of-day options positioning for one stock or ETF",
3600
- usage: "sentisense options <ticker>",
3893
+ usage: "sentisense options <ticker> [--intraday] [--session YYYY-MM-DD]",
3601
3894
  examples: [
3602
3895
  "sentisense options NVDA",
3603
3896
  "sentisense options SPY --full",
3604
- "sentisense options NVDA --json"
3897
+ "sentisense options NVDA --json",
3898
+ "sentisense options NVDA --intraday",
3899
+ "sentisense options SPY --session 2026-10-14"
3605
3900
  ],
3606
3901
  notes: [
3607
3902
  "End of day, not live: readings describe the latest completed session and refresh the",
@@ -3612,11 +3907,28 @@ var optionsCommand = {
3612
3907
  EMPTY_VERIFY_NOTE,
3613
3908
  EMPTY_VERIFY_NOTE_2,
3614
3909
  "A free key gets the full dossier for the first ten calls each month, then a headline",
3615
- "preview. Calls that return no dossier do not count against that."
3910
+ "preview. Calls that return no dossier do not count against that.",
3911
+ "--intraday shows one session's intraday series instead: the ticker's volumes, put/call",
3912
+ "ratio, unusual-contract count and ATM IV at every 15-minute cycle (PRO keys only).",
3913
+ "--session picks the session and implies --intraday; omitted, the latest one."
3616
3914
  ],
3617
- flags: {},
3915
+ flags: {
3916
+ intraday: { type: "boolean", describe: "Show the session's intraday series, every 15-minute cycle (PRO)" },
3917
+ session: {
3918
+ type: "string",
3919
+ placeholder: "YYYY-MM-DD",
3920
+ describe: "Session for the intraday series (default: the latest)"
3921
+ }
3922
+ },
3618
3923
  async run({ args, client, full }) {
3619
3924
  const ticker = oneTicker(args, "options");
3925
+ const session = typeof args.flags.session === "string" ? args.flags.session : void 0;
3926
+ if (session !== void 0 && !SESSION_PATTERN.test(session)) {
3927
+ throw new CliUsageError("--session must be a date, YYYY-MM-DD.", "for example: --session 2026-10-14");
3928
+ }
3929
+ if (args.flags.intraday === true || session !== void 0) {
3930
+ return intraday(client(), ticker, session);
3931
+ }
3620
3932
  const api = client();
3621
3933
  const envelope = await api.stocks.getOptionsSummary(ticker);
3622
3934
  const data = envelope.data;
@@ -3630,21 +3942,24 @@ var optionsCommand = {
3630
3942
  }
3631
3943
  const latest = data.latest ?? {};
3632
3944
  const context = data.context ?? {};
3945
+ const ivRank = context.ivRank1y ?? data.ivRank1y;
3946
+ const pcVol = latest.pcVol ?? data.pcVol;
3947
+ const maxPain = data.oiWalls?.maxPain ?? data.maxPain;
3633
3948
  const blocks = [
3634
3949
  {
3635
3950
  kind: "head",
3636
3951
  title: field("ticker", ticker),
3637
3952
  right: fields(
3638
3953
  field("positioning", signed(data.sentiment, 2), direction(data.sentiment)),
3639
- field("iv rank 1y", fixed(context.ivRank1y, 1)),
3640
- field("put/call vol", fixed(latest.pcVol, 2))
3954
+ field("iv rank 1y", fixed(ivRank, 1)),
3955
+ field("put/call vol", fixed(pcVol, 2))
3641
3956
  )
3642
3957
  },
3643
3958
  {
3644
3959
  kind: "facts",
3645
3960
  items: fields(
3646
- field("ATM IV", fixed(latest.atmIv, 4)),
3647
- field("Exp move 1d", fixed(latest.expectedMove1d, 4)),
3961
+ field("ATM IV", fixed(latest.atmIv ?? data.atmIv, 4)),
3962
+ field("Exp move 1d", fixed(latest.expectedMove1d ?? data.expectedMove1d, 4)),
3648
3963
  field("Skew 25d", signed(latest.skew25d, 4)),
3649
3964
  field("Call vol", humanize(latest.callVol, 1)),
3650
3965
  field("Put vol", humanize(latest.putVol, 1)),
@@ -3654,7 +3969,7 @@ var optionsCommand = {
3654
3969
  {
3655
3970
  kind: "facts",
3656
3971
  items: fields(
3657
- field("Max pain", fixed(data.oiWalls?.maxPain, 0)),
3972
+ field("Max pain", fixed(maxPain, 0)),
3658
3973
  field("Wall expiry", data.oiWalls?.expiry ?? "n/a"),
3659
3974
  field("Call OI", humanize(latest.callOi, 1)),
3660
3975
  field("Put OI", humanize(latest.putOi, 1)),
@@ -3676,7 +3991,7 @@ var optionsCommand = {
3676
3991
  field("term structure", `60d ${fixed(latest.atmIv60, 4)} 90d ${fixed(latest.atmIv90, 4)}`),
3677
3992
  field("net delta", humanize(latest.netDelta, 1)),
3678
3993
  field("put/call OI", fixed(latest.pcOi, 2)),
3679
- field("pc vol percentile 1y", fixed(context.pcVolPctl1y, 1)),
3994
+ field("pc vol percentile 1y", fixed(context.pcVolPctl1y ?? data.pcVolPctl1y, 1)),
3680
3995
  field("skew percentile 1y", fixed(context.skewPctl1y, 1)),
3681
3996
  field("observations 1y", fixed(context.observations1y, 0))
3682
3997
  )
@@ -3947,7 +4262,7 @@ function parseSort(raw) {
3947
4262
  }
3948
4263
  var screenCommand = {
3949
4264
  name: "screen",
3950
- summary: "Filter the tracked universe on Score, analyst, technical, and price fields",
4265
+ summary: "Filter the tracked universe on Score, analyst, technical, price, and end-of-day options fields",
3951
4266
  usage: "sentisense screen [--filter FIELD:OP:VALUE]... [--sort FIELD:DIR] [--limit N]",
3952
4267
  examples: [
3953
4268
  "sentisense screen --list",
@@ -4395,6 +4710,7 @@ var sentimentCommand = {
4395
4710
  // src/cli/commands/index.ts
4396
4711
  var COMMANDS = [
4397
4712
  authCommand,
4713
+ initCommand,
4398
4714
  healthCommand,
4399
4715
  quoteCommand,
4400
4716
  sentimentCommand,
@@ -4420,6 +4736,7 @@ var OFFLINE_COMMANDS = /* @__PURE__ */ new Set(["auth"]);
4420
4736
  // src/cli/help.ts
4421
4737
  var EXAMPLE = {
4422
4738
  auth: "sentisense auth $SENTISENSE_API_KEY",
4739
+ init: "npx sentisense init",
4423
4740
  health: "sentisense health",
4424
4741
  quote: "sentisense quote NVDA AAPL",
4425
4742
  sentiment: "sentisense sentiment NVDA --days 30",
@@ -4468,6 +4785,7 @@ function mainHelp() {
4468
4785
  " --full widens a command, --plain and --no-color force text, --debug shows stack traces.",
4469
4786
  "",
4470
4787
  "Setup:",
4788
+ " sentisense init print a temporary key with no signup, and a link to keep it",
4471
4789
  ` sentisense auth <key> store a key at ~/.config/sentisense/config.json (0600)`,
4472
4790
  " SENTISENSE_API_KEY=<key> or pass it in the environment",
4473
4791
  ` Get a key at ${KEY_URL}`,