sentisense 0.45.0 → 0.47.0

package/dist/cli.cjs

@@ -1038,7 +1038,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.45.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) {
@@ -2498,6 +2563,9 @@ var insidersCommand = {
   ],
   notes: [
     "Rows are individual filed transactions, newest first, not a net total.",
+    "The bought/sold figures count open-market rows only. Form 4 code F rows (shares withheld",
+    "to cover taxes on vesting) arrive typed SELL but are mechanical withholding, not a decision",
+    "to sell, so they are excluded from sold and shown separately as withheld.",
     "The plan column says whether the trade was under a confirmed pre-arranged 10b5-1 plan,",
     "which is the difference between a scheduled sale and a discretionary one.",
     "A free key sees the top few transactions; a PRO key sees the window you asked for.",
@@ -2522,18 +2590,22 @@ var insidersCommand = {
       if (note) notes.push(note);
     }
     const shown = full ? trades : trades.slice(0, 15);
+    const isWithholding = (row) => row.transactionCode === "F";
     const buys = trades.filter((trade) => trade.transactionType === "BUY");
-    const sells = trades.filter((trade) => trade.transactionType === "SELL");
+    const sells = trades.filter((trade) => trade.transactionType === "SELL" && !isWithholding(trade));
+    const withheld = trades.filter(isWithholding);
     const sum = (rows) => rows.reduce((total, row) => total + (row.totalValue || 0), 0);
+    const headline = [
+      field("trades", String(trades.length)),
+      field("bought", humanize(sum(buys)), buys.length > 0 ? "up" : void 0),
+      field("sold", humanize(sum(sells)), sells.length > 0 ? "down" : void 0)
+    ];
+    if (withheld.length > 0) headline.push(field("withheld", humanize(sum(withheld))));
     const blocks = [
       {
         kind: "head",
         title: field("ticker", ticker),
-        right: fields(
-          field("trades", String(trades.length)),
-          field("bought", humanize(sum(buys)), buys.length > 0 ? "up" : void 0),
-          field("sold", humanize(sum(sells)), sells.length > 0 ? "down" : void 0)
-        )
+        right: fields(...headline)
       }
     ];
     if (shown.length === 0) {
@@ -2548,8 +2620,8 @@ var insidersCommand = {
           cell(truncate(trade.insiderName, full ? 40 : 22)),
           cell(truncate(trade.insiderTitle ?? "", full ? 40 : 18)),
           cell(
-            trade.transactionType,
-            trade.transactionType === "BUY" ? "up" : trade.transactionType === "SELL" ? "down" : void 0
+            isWithholding(trade) ? "TAX-W" : trade.transactionType,
+            !isWithholding(trade) && trade.transactionType === "BUY" ? "up" : !isWithholding(trade) && trade.transactionType === "SELL" ? "down" : void 0
           ),
           cell(humanize(trade.sharesTransacted, 1)),
           cell(humanize(trade.totalValue)),

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.45.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) {