sentisense 0.46.0 → 0.47.0

package/README.md

@@ -117,12 +117,12 @@ If you set `SENTISENSE_AGENT_NAME` (what your agent is called) and `SENTISENSE_S
 
 ```bash
 export SENTISENSE_AGENT_NAME=research-desk
-export SENTISENSE_SKILL=stock-analysis
+export SENTISENSE_SKILL=us-stocks-analysis
 npx -y sentisense@latest quote NVDA
-# User-Agent: sentisense-node/{version} sentisense-cli/{version} (stock-analysis; agent/research-desk)
+# User-Agent: sentisense-node/{version} sentisense-cli/{version} (us-stocks-analysis; agent/research-desk)
 ```
 
-Either can also be a flag (`--agent`, `--skill`) or a stored setting (`sentisense auth --agent research-desk --skill stock-analysis`), resolved flag first, then environment, then config. Values are reduced to letters, digits, dot, underscore and hyphen, and capped at 32 characters, so nothing you set can reshape the header.
+Either can also be a flag (`--agent`, `--skill`) or a stored setting (`sentisense auth --agent research-desk --skill us-stocks-analysis`), resolved flag first, then environment, then config. Values are reduced to letters, digits, dot, underscore and hyphen, and capped at 32 characters, so nothing you set can reshape the header.
 
 Research data, not investment advice.
 
@@ -211,6 +211,7 @@ client.stocks.getMarketStatus()                         // Market open/closed
 client.stocks.getFundamentals("AAPL")                   // Financial data
 client.stocks.getShortInterest("GME")                   // Short interest
 client.stocks.getOptionsSummary("NVDA")                 // End-of-day options dossier
+client.stocks.getOptionsHistory("NVDA", { window: "2y" })  // Daily options aggregates over time
 client.stocks.getAISummary("AAPL", { depth: "deep" })   // AI report (PRO)
 ```
 
@@ -386,6 +387,20 @@ client.entityMetrics.getDistribution("AAPL", "mentions", { dimension: "source" }
 
 Available metric types: `mentions`, `sentiment`, `sentisense`, `social_dominance`, `creators`.
 
+### Options
+
+End-of-day options positioning: where implied volatility, put/call flow and skew are unusual today, and how a name's readings have trended.
+
+```typescript
+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
+```
+
+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.
+
+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; `getOptionsHistory` reports it as an empty `series` instead, so check the array rather than null-checking there.
+
 ### Market mood & knowledge base
 
 ```typescript

package/dist/cli.cjs

@@ -1038,7 +1038,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.46.0";
+var VERSION = "0.47.0";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -1623,6 +1623,39 @@ var MarketSummaryResource = class {
   }
 };
 
+// src/resources/options.ts
+var Options = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get the market-wide options radar: where implied volatility, put/call flow and skew are
+   * unusual today, ranked.
+   *
+   * End of day, not live. `asOf` is the latest completed session and the build refreshes the
+   * following morning, so this is positioning, not a quote feed.
+   *
+   * **The response carries two separately-ranked boards.** `data.rows` is the covered stock
+   * universe and `data.etfRows` is the covered ETF universe. Do not merge them: each row's
+   * readings are percentiles of that ticker's own trailing history, so a rank built across
+   * both boards compares numbers measured against different baselines. The aggregates are
+   * split the same way, with the `etf`-prefixed fields describing the ETF board alone.
+   *
+   * `data` is `null` before the first nightly build populates it, which is a cold-start
+   * state rather than an error.
+   *
+   * Tiering: a PRO key receives every row. A FREE key receives the top 25 stock rows plus
+   * all the aggregates, with `isPreview` true and the envelope's `totalCount` reporting the
+   * full stock board; `data.etfTotalCount` does the same for the ETF board.
+   *
+   * Drill into any row with `client.stocks.getOptionsSummary(ticker)` for its full dossier,
+   * or `client.stocks.getOptionsHistory(ticker)` to chart how a reading has trended.
+   */
+  async getOverview() {
+    return this.client.get("/api/v1/options/overview");
+  }
+};
+
 // src/resources/screener.ts
 var Screener = class {
   constructor(client) {
@@ -1704,6 +1737,12 @@ var Screener = class {
 };
 
 // src/resources/stocks.ts
+function withLegacyName(rows) {
+  if (!Array.isArray(rows)) return rows;
+  return rows.map(
+    (row) => row && !row.name ? { ...row, name: row.simpleName || row.companyName || "" } : row
+  );
+}
 var Stocks = class {
   constructor(client) {
     this.client = client;
@@ -1712,9 +1751,10 @@ var Stocks = class {
   async list() {
     return this.client.get("/api/v1/stocks");
   }
-  /** List all stocks with name, kbEntityId, urlSlug. */
+  /** List all stocks with company names, kbEntityId, urlSlug. */
   async listDetailed() {
-    return this.client.get("/api/v1/stocks/detailed");
+    const rows = await this.client.get("/api/v1/stocks/detailed");
+    return withLegacyName(rows);
   }
   /** Get popular ticker symbols. */
   async listPopular() {
@@ -1722,7 +1762,8 @@ var Stocks = class {
   }
   /** Get popular stocks with details. */
   async listPopularDetailed() {
-    return this.client.get("/api/v1/stocks/popular/detailed");
+    const rows = await this.client.get("/api/v1/stocks/popular/detailed");
+    return withLegacyName(rows);
   }
   /** Get real-time price for a single ticker. */
   async getPrice(ticker) {
@@ -1923,6 +1964,29 @@ var Stocks = class {
       `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/options/summary`
     );
   }
+  /**
+   * Get the daily options aggregates for one stock or ETF as a time series, oldest first.
+   * Use it to chart how a reading has trended: implied volatility, put/call flow, skew.
+   *
+   * Each element has the same shape as the dossier's `latest` aggregate, so a chart built
+   * off `getOptionsSummary` reads this series without a second mapping.
+   *
+   * **A null payload is not how this one reports no coverage.** Unlike
+   * {@link Stocks.getOptionsSummary}, an uncovered ticker, an unknown symbol and a covered
+   * ticker with nothing stored yet all answer with a populated object whose `series` is
+   * empty. Check the array's length, not the payload.
+   *
+   * The window served is not always the window requested: an unrecognised value clamps to
+   * `"1y"` rather than erroring, and a FREE key always receives `"1y"`. Read `data.window`
+   * for what you actually got. `"5y"` means all stored history, currently a little over two
+   * years, so it can answer with nearly the same series as `"2y"`.
+   */
+  async getOptionsHistory(ticker, options) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/options/history`,
+      options
+    );
+  }
 };
 
 // src/resources/indexes.ts
@@ -2048,6 +2112,7 @@ var SentiSense = class {
     this.calendar = new Calendar(this);
     this.earnings = new Earnings(this);
     this.screener = new Screener(this);
+    this.options = new Options(this);
   }
   /** @internal */
   async get(path, params) {

package/dist/index.cjs

@@ -657,6 +657,39 @@ var MarketSummaryResource = class {
   }
 };
 
+// src/resources/options.ts
+var Options = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get the market-wide options radar: where implied volatility, put/call flow and skew are
+   * unusual today, ranked.
+   *
+   * End of day, not live. `asOf` is the latest completed session and the build refreshes the
+   * following morning, so this is positioning, not a quote feed.
+   *
+   * **The response carries two separately-ranked boards.** `data.rows` is the covered stock
+   * universe and `data.etfRows` is the covered ETF universe. Do not merge them: each row's
+   * readings are percentiles of that ticker's own trailing history, so a rank built across
+   * both boards compares numbers measured against different baselines. The aggregates are
+   * split the same way, with the `etf`-prefixed fields describing the ETF board alone.
+   *
+   * `data` is `null` before the first nightly build populates it, which is a cold-start
+   * state rather than an error.
+   *
+   * Tiering: a PRO key receives every row. A FREE key receives the top 25 stock rows plus
+   * all the aggregates, with `isPreview` true and the envelope's `totalCount` reporting the
+   * full stock board; `data.etfTotalCount` does the same for the ETF board.
+   *
+   * Drill into any row with `client.stocks.getOptionsSummary(ticker)` for its full dossier,
+   * or `client.stocks.getOptionsHistory(ticker)` to chart how a reading has trended.
+   */
+  async getOverview() {
+    return this.client.get("/api/v1/options/overview");
+  }
+};
+
 // src/resources/screener.ts
 var Screener = class {
   constructor(client) {
@@ -738,6 +771,12 @@ var Screener = class {
 };
 
 // src/resources/stocks.ts
+function withLegacyName(rows) {
+  if (!Array.isArray(rows)) return rows;
+  return rows.map(
+    (row) => row && !row.name ? { ...row, name: row.simpleName || row.companyName || "" } : row
+  );
+}
 var Stocks = class {
   constructor(client) {
     this.client = client;
@@ -746,9 +785,10 @@ var Stocks = class {
   async list() {
     return this.client.get("/api/v1/stocks");
   }
-  /** List all stocks with name, kbEntityId, urlSlug. */
+  /** List all stocks with company names, kbEntityId, urlSlug. */
   async listDetailed() {
-    return this.client.get("/api/v1/stocks/detailed");
+    const rows = await this.client.get("/api/v1/stocks/detailed");
+    return withLegacyName(rows);
   }
   /** Get popular ticker symbols. */
   async listPopular() {
@@ -756,7 +796,8 @@ var Stocks = class {
   }
   /** Get popular stocks with details. */
   async listPopularDetailed() {
-    return this.client.get("/api/v1/stocks/popular/detailed");
+    const rows = await this.client.get("/api/v1/stocks/popular/detailed");
+    return withLegacyName(rows);
   }
   /** Get real-time price for a single ticker. */
   async getPrice(ticker) {
@@ -957,6 +998,29 @@ var Stocks = class {
       `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/options/summary`
     );
   }
+  /**
+   * Get the daily options aggregates for one stock or ETF as a time series, oldest first.
+   * Use it to chart how a reading has trended: implied volatility, put/call flow, skew.
+   *
+   * Each element has the same shape as the dossier's `latest` aggregate, so a chart built
+   * off `getOptionsSummary` reads this series without a second mapping.
+   *
+   * **A null payload is not how this one reports no coverage.** Unlike
+   * {@link Stocks.getOptionsSummary}, an uncovered ticker, an unknown symbol and a covered
+   * ticker with nothing stored yet all answer with a populated object whose `series` is
+   * empty. Check the array's length, not the payload.
+   *
+   * The window served is not always the window requested: an unrecognised value clamps to
+   * `"1y"` rather than erroring, and a FREE key always receives `"1y"`. Read `data.window`
+   * for what you actually got. `"5y"` means all stored history, currently a little over two
+   * years, so it can answer with nearly the same series as `"2y"`.
+   */
+  async getOptionsHistory(ticker, options) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/options/history`,
+      options
+    );
+  }
 };
 
 // src/resources/indexes.ts
@@ -1036,7 +1100,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.46.0";
+var VERSION = "0.47.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -1085,6 +1149,7 @@ var SentiSense = class {
     this.calendar = new Calendar(this);
     this.earnings = new Earnings(this);
     this.screener = new Screener(this);
+    this.options = new Options(this);
   }
   /** @internal */
   async get(path, params) {