sentisense 0.63.1 → 0.65.0

package/README.md

@@ -79,8 +79,8 @@ npx -y sentisense@latest health
 | `congress [ticker]` | Congressional disclosures, market-wide or for one symbol |
 | `news [ticker]` | Clustered news stories with impact and tone |
 | `flows [ticker]` | Institutional 13F flows, or one ticker's holders and notable changes |
-| `options <ticker>` | End-of-day options positioning, IV rank, walls, unusual contracts |
-| `screen --filter ...` | Screen the universe on Score, analyst, technical, and price fields |
+| `options <ticker>` | End-of-day options positioning, IV rank, walls, unusual contracts; `--intraday` for the session's 15-minute series (PRO) |
+| `screen --filter ...` | Screen the universe on Score, analyst, technical, price, and end-of-day options fields |
 | `search <name>` | Resolve a name, alias, ticker or slug to a symbol and the entity handle |
 
 Run `sentisense help <command>` for its flags and examples.
@@ -183,9 +183,9 @@ Affected: every method whose declared return type is `PreviewResponse<T>`. A tes
 | `institutional` | `getFlows` `getHolders` `getActivists` |
 | `options` | `getOverview` |
 | `politicians` | `getActivity` `getFilings` `getMembers` `getMember` |
-| `stocks` | `getSentiment` `getKpis` `getOptionsSummary` `getOptionsHistory` |
+| `stocks` | `getSentiment` `getKpis` `getOptionsSummary` `getOptionsHistory` `getOptionsIntradayHistory` |
 
-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.
+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.
 
 ```typescript
 const flows = await client.institutional.getFlows();
@@ -244,6 +244,7 @@ client.stocks.getFloat("GME")                           // Free float
 client.stocks.getGraph("AAPL", { depth: 1 })            // Company knowledge graph: people, products, peers
 client.stocks.getOptionsSummary("NVDA")                 // End-of-day options dossier
 client.stocks.getOptionsHistory("NVDA", { window: "2y" })  // Daily options aggregates over time
+client.stocks.getOptionsIntradayHistory("NVDA")         // One session's intraday options series (PRO)
 client.stocks.getRating("AAPL")                         // SentiSense Rating: score, letter, percentile, dimensions
 client.stocks.getAISummary("AAPL", { depth: "deep" })   // AI report (PRO)
 ```
@@ -521,11 +522,29 @@ End-of-day options positioning: where implied volatility, put/call flow and skew
 client.options.getOverview()                            // Market-wide radar, ranked
 client.stocks.getOptionsSummary("NVDA")                 // One name's full dossier
 client.stocks.getOptionsHistory("NVDA", { window: "2y" })  // That name's daily series
+client.stocks.getOptionsIntradayHistory("NVDA", { session: "2026-10-14" })  // Every 15-minute cycle of one session (PRO)
 ```
 
 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.
 
-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.
+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.
+
+`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`:
+
+```typescript
+const day = await client.stocks.getOptionsIntradayHistory("NVDA", { session: "2026-10-14" });
+if (day.data === null) {
+  console.log(day.upgrade?.message);    // PRO only: a FREE key gets a preview with no series
+} else {
+  for (const point of day.data.series) { // oldest cycle first
+    console.log(point.asOfEt, point.callVol, point.putVol, point.pcVol, point.unusualCount, point.atmIv);
+  }
+}
+```
+
+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.
+
+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`.
 
 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.
 
@@ -578,7 +597,7 @@ An empty array is the normal answer for a query that matches nothing, so branch
 
 ### Screener
 
-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.
+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.
 
 ```typescript
 client.screener.fields()                      // Every filterable field, both universes, with units + operators
@@ -609,6 +628,18 @@ const res = await client.screener.run({
 for (const row of res.results) {
   console.log(row.ticker, row.sentiSenseScore7D, row.analystBuyRatioPct);
 }
+
+// Options positioning: implied volatility in the top quarter of its own year
+const highIv = await client.screener.run({
+  plan: {
+    filters: [{ fieldName: "IV_RANK_1Y", op: "GTE", value: 75 }],
+    sort: { fieldName: "IV_RANK_1Y", dir: "DESC" },
+  },
+  limit: 25,
+});
+for (const row of highIv.results) {
+  console.log(row.ticker, row.ivRank1y, row.expectedMove20d, row.optionsAsOf);
+}
 ```
 
 `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 +654,11 @@ The Score fields (`SENTI_SCORE_7D`, `SENTI_SCORE_1M`, `SCORE_CHANGE_7D`) are the
 
 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.
 
-Screens read a snapshot that refreshes every 20 minutes, so this is not a quote feed. Use `client.stocks.getQuote()` for current quotes.
+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`.
+
+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.
+
+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.
 
 ## Error handling
 

package/dist/cli.cjs

@@ -1356,7 +1356,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.63.1";
+var VERSION = "0.65.0";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -2518,7 +2518,9 @@ var Stocks = class {
    *
    * Tiering: a PRO key always receives the full dossier. A FREE key receives it for the first
    * ten calls each calendar month and a headline-only preview after that, with `isPreview`
-   * true; calls that return a null `data` never spend that allowance.
+   * true; calls that return a null `data` never spend that allowance. The headline preview has
+   * no nested objects: its readings arrive flat as `data.ivRank1y`, `data.atmIv`,
+   * `data.expectedMove1d`, `data.pcVol`, `data.pcVolPctl1y` and `data.maxPain`.
    */
   async getOptionsSummary(ticker) {
     return this.client.get(
@@ -2548,6 +2550,33 @@ var Stocks = class {
       options
     );
   }
+  /**
+   * Get one stock's or ETF's intraday options series for one session: its numbers at every
+   * 15-minute cycle of the intraday board, oldest cycle first.
+   *
+   * Use it to test an intraday signal against what the board actually showed at each point in
+   * the day, then compare it with the session's end-of-day row from
+   * {@link Stocks.getOptionsHistory}. 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, and the ATM implied volatility. It never carries a
+   * contract symbol, strike, price, premium, open interest or print size.
+   *
+   * **PRO only.** A FREE key receives the standard preview: `isPreview` true, `previewReason`
+   * `"PRO_REQUIRED"`, an `upgrade` hint, and `data: null`.
+   *
+   * **No data is an empty `series`, not a null payload.** A weekend, a holiday, a session from
+   * before the history was kept, a ticker outside the board and an unknown symbol all answer
+   * with `data.series` empty. `data.missingCycles` lists cycles whose stored point could not be
+   * read, which are unknown rather than absent. A malformed or future `session` rejects with
+   * an `APIError` (status 400, code `invalid_session`). A 503 means the stored series could
+   * not be read; it is retried like any other 503 and never answered with a partial series.
+   */
+  async getOptionsIntradayHistory(ticker, options) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/options/intraday-history`,
+      options
+    );
+  }
   /**
    * Get the SentiSense Rating for one stock: where it ranks against the other stocks rated
    * that day, and the six dimensions the rank is blended from.
@@ -3584,6 +3613,7 @@ var newsCommand = {
 };
 
 // src/cli/commands/options.ts
+var SESSION_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
 function contractTone(type) {
   const side = type?.toUpperCase();
   if (side === "CALL") return "up";
@@ -3594,14 +3624,79 @@ function walls(rows) {
   if (!rows || rows.length === 0) return "n/a";
   return rows.map((wall) => `${fixed(wall.strike, 0)} (${humanize(wall.oi, 1)})`).join("  ");
 }
+async function intraday(api, ticker, session) {
+  const envelope = await api.stocks.getOptionsIntradayHistory(ticker, { session });
+  const data = envelope.data;
+  if (envelope.isPreview && !data) {
+    const lines = [
+      { kind: "text", text: `Intraday options history for ${ticker} needs a PRO key.` }
+    ];
+    if (envelope.upgrade?.url) {
+      lines.push({ kind: "text", text: envelope.upgrade.url, tone: "dim" });
+    }
+    return { json: envelope, doc: doc(...lines) };
+  }
+  const series = data?.series ?? [];
+  const served = data?.session ?? session ?? "the latest session";
+  if (series.length === 0) {
+    const note = await verifyTickerOnEmpty(api, ticker);
+    return {
+      json: envelope,
+      doc: doc({ kind: "text", text: `No intraday options history for ${ticker} on ${served}.` }),
+      notes: note ? [note] : void 0
+    };
+  }
+  const blocks = [
+    {
+      kind: "head",
+      title: field("ticker", ticker),
+      right: fields(
+        field("session", served),
+        field("board", data?.live ? "live" : "closed", data?.live ? "accent" : void 0),
+        field("cycles", String(data?.cycles ?? series.length))
+      )
+    },
+    {
+      kind: "table",
+      head: ["CYCLE", "TIME", "CALL VOL", "PUT VOL", "P/C", "UNUSUAL", "PCTL 1Y", "ATM IV"],
+      align: ["right", "left", "right", "right", "right", "right", "right", "right"],
+      rows: series.map((point) => [
+        cell(String(point.cycle)),
+        cell(point.asOfEt ?? ""),
+        cell(humanize(point.callVol, 1)),
+        cell(humanize(point.putVol, 1)),
+        cell(fixed(point.pcVol, 2)),
+        cell(String(point.unusualCount ?? 0)),
+        cell(fixed(point.maxPremiumPctl1y, 1)),
+        cell(fixed(point.atmIv, 4))
+      ])
+    }
+  ];
+  const missing = data?.missingCycles ?? [];
+  if (missing.length > 0) {
+    blocks.push({
+      kind: "text",
+      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.`,
+      tone: "dim"
+    });
+  }
+  blocks.push({
+    kind: "text",
+    text: `Volumes are cumulative for the session, from chains delayed ${data?.delayMinutes ?? 15} minutes.`,
+    tone: "dim"
+  });
+  return { json: envelope, doc: doc(...blocks) };
+}
 var optionsCommand = {
   name: "options",
   summary: "End-of-day options positioning for one stock or ETF",
-  usage: "sentisense options <ticker>",
+  usage: "sentisense options <ticker> [--intraday] [--session YYYY-MM-DD]",
   examples: [
     "sentisense options NVDA",
     "sentisense options SPY --full",
-    "sentisense options NVDA --json"
+    "sentisense options NVDA --json",
+    "sentisense options NVDA --intraday",
+    "sentisense options SPY --session 2026-10-14"
   ],
   notes: [
     "End of day, not live: readings describe the latest completed session and refresh the",
@@ -3612,11 +3707,28 @@ var optionsCommand = {
     EMPTY_VERIFY_NOTE,
     EMPTY_VERIFY_NOTE_2,
     "A free key gets the full dossier for the first ten calls each month, then a headline",
-    "preview. Calls that return no dossier do not count against that."
+    "preview. Calls that return no dossier do not count against that.",
+    "--intraday shows one session's intraday series instead: the ticker's volumes, put/call",
+    "ratio, unusual-contract count and ATM IV at every 15-minute cycle (PRO keys only).",
+    "--session picks the session and implies --intraday; omitted, the latest one."
   ],
-  flags: {},
+  flags: {
+    intraday: { type: "boolean", describe: "Show the session's intraday series, every 15-minute cycle (PRO)" },
+    session: {
+      type: "string",
+      placeholder: "YYYY-MM-DD",
+      describe: "Session for the intraday series (default: the latest)"
+    }
+  },
   async run({ args, client, full }) {
     const ticker = oneTicker(args, "options");
+    const session = typeof args.flags.session === "string" ? args.flags.session : void 0;
+    if (session !== void 0 && !SESSION_PATTERN.test(session)) {
+      throw new CliUsageError("--session must be a date, YYYY-MM-DD.", "for example: --session 2026-10-14");
+    }
+    if (args.flags.intraday === true || session !== void 0) {
+      return intraday(client(), ticker, session);
+    }
     const api = client();
     const envelope = await api.stocks.getOptionsSummary(ticker);
     const data = envelope.data;
@@ -3630,21 +3742,24 @@ var optionsCommand = {
     }
     const latest = data.latest ?? {};
     const context = data.context ?? {};
+    const ivRank = context.ivRank1y ?? data.ivRank1y;
+    const pcVol = latest.pcVol ?? data.pcVol;
+    const maxPain = data.oiWalls?.maxPain ?? data.maxPain;
     const blocks = [
       {
         kind: "head",
         title: field("ticker", ticker),
         right: fields(
           field("positioning", signed(data.sentiment, 2), direction(data.sentiment)),
-          field("iv rank 1y", fixed(context.ivRank1y, 1)),
-          field("put/call vol", fixed(latest.pcVol, 2))
+          field("iv rank 1y", fixed(ivRank, 1)),
+          field("put/call vol", fixed(pcVol, 2))
         )
       },
       {
         kind: "facts",
         items: fields(
-          field("ATM IV", fixed(latest.atmIv, 4)),
-          field("Exp move 1d", fixed(latest.expectedMove1d, 4)),
+          field("ATM IV", fixed(latest.atmIv ?? data.atmIv, 4)),
+          field("Exp move 1d", fixed(latest.expectedMove1d ?? data.expectedMove1d, 4)),
           field("Skew 25d", signed(latest.skew25d, 4)),
           field("Call vol", humanize(latest.callVol, 1)),
           field("Put vol", humanize(latest.putVol, 1)),
@@ -3654,7 +3769,7 @@ var optionsCommand = {
       {
         kind: "facts",
         items: fields(
-          field("Max pain", fixed(data.oiWalls?.maxPain, 0)),
+          field("Max pain", fixed(maxPain, 0)),
           field("Wall expiry", data.oiWalls?.expiry ?? "n/a"),
           field("Call OI", humanize(latest.callOi, 1)),
           field("Put OI", humanize(latest.putOi, 1)),
@@ -3676,7 +3791,7 @@ var optionsCommand = {
           field("term structure", `60d ${fixed(latest.atmIv60, 4)}   90d ${fixed(latest.atmIv90, 4)}`),
           field("net delta", humanize(latest.netDelta, 1)),
           field("put/call OI", fixed(latest.pcOi, 2)),
-          field("pc vol percentile 1y", fixed(context.pcVolPctl1y, 1)),
+          field("pc vol percentile 1y", fixed(context.pcVolPctl1y ?? data.pcVolPctl1y, 1)),
           field("skew percentile 1y", fixed(context.skewPctl1y, 1)),
           field("observations 1y", fixed(context.observations1y, 0))
         )
@@ -3947,7 +4062,7 @@ function parseSort(raw) {
 }
 var screenCommand = {
   name: "screen",
-  summary: "Filter the tracked universe on Score, analyst, technical, and price fields",
+  summary: "Filter the tracked universe on Score, analyst, technical, price, and end-of-day options fields",
   usage: "sentisense screen [--filter FIELD:OP:VALUE]... [--sort FIELD:DIR] [--limit N]",
   examples: [
     "sentisense screen --list",

package/dist/index.cjs

@@ -1242,7 +1242,9 @@ var Stocks = class {
    *
    * Tiering: a PRO key always receives the full dossier. A FREE key receives it for the first
    * ten calls each calendar month and a headline-only preview after that, with `isPreview`
-   * true; calls that return a null `data` never spend that allowance.
+   * true; calls that return a null `data` never spend that allowance. The headline preview has
+   * no nested objects: its readings arrive flat as `data.ivRank1y`, `data.atmIv`,
+   * `data.expectedMove1d`, `data.pcVol`, `data.pcVolPctl1y` and `data.maxPain`.
    */
   async getOptionsSummary(ticker) {
     return this.client.get(
@@ -1272,6 +1274,33 @@ var Stocks = class {
       options
     );
   }
+  /**
+   * Get one stock's or ETF's intraday options series for one session: its numbers at every
+   * 15-minute cycle of the intraday board, oldest cycle first.
+   *
+   * Use it to test an intraday signal against what the board actually showed at each point in
+   * the day, then compare it with the session's end-of-day row from
+   * {@link Stocks.getOptionsHistory}. 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, and the ATM implied volatility. It never carries a
+   * contract symbol, strike, price, premium, open interest or print size.
+   *
+   * **PRO only.** A FREE key receives the standard preview: `isPreview` true, `previewReason`
+   * `"PRO_REQUIRED"`, an `upgrade` hint, and `data: null`.
+   *
+   * **No data is an empty `series`, not a null payload.** A weekend, a holiday, a session from
+   * before the history was kept, a ticker outside the board and an unknown symbol all answer
+   * with `data.series` empty. `data.missingCycles` lists cycles whose stored point could not be
+   * read, which are unknown rather than absent. A malformed or future `session` rejects with
+   * an `APIError` (status 400, code `invalid_session`). A 503 means the stored series could
+   * not be read; it is retried like any other 503 and never answered with a partial series.
+   */
+  async getOptionsIntradayHistory(ticker, options) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/options/intraday-history`,
+      options
+    );
+  }
   /**
    * Get the SentiSense Rating for one stock: where it ranks against the other stocks rated
    * that day, and the six dimensions the rank is blended from.
@@ -1394,7 +1423,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.63.1";
+var VERSION = "0.65.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";