sentisense 0.61.0 → 0.63.0

package/README.md

@@ -68,7 +68,7 @@ npx -y sentisense@latest health
 |---------|--------------|
 | `auth [key]` | Store a key, show what is configured, or `--remove` it |
 | `health` | Reachability, key validity, latency, and the resolved base URL |
-| `quote <ticker>...` | Price, day range, 52-week range, market cap, P/E. One request per ticker |
+| `quote <ticker>...` | Price, day range, 52-week range, market cap, P/E. One request per ticker; ETFs show AUM, expense ratio and NAV |
 | `sentiment <ticker>` | SentiSense Score, tone, attention, per-source breakdown, `--days N` history |
 | `mood` | Composite market sentiment, the signals behind it, and the sector map |
 | `analysts <ticker>` | Consensus, price target band, recent upgrades and downgrades. `--coverage` for who covers it, by firm |
@@ -238,7 +238,10 @@ client.stocks.getProfile("AAPL")                        // Company profile
 client.stocks.getChart("AAPL", { timeframe: "6M" })     // OHLCV chart data
 client.stocks.getMarketStatus()                         // Market open/closed
 client.stocks.getFundamentals("AAPL")                   // Financial data
-client.stocks.getShortInterest("GME")                   // Short interest
+client.stocks.getShortInterest("GME", { limit: 12 })    // Short interest by settlement date
+client.stocks.getShortVolume("GME")                     // Daily short volume
+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.getRating("AAPL")                         // SentiSense Rating: score, letter, percentile, dimensions
@@ -247,6 +250,10 @@ client.stocks.getAISummary("AAPL", { depth: "deep" })   // AI report (PRO)
 
 Price fields carry `priceAsOf` (Unix milliseconds) for the age of the market data; read that for freshness rather than `timestamp`, which is when the response was served.
 
+Short interest and short volume come back newest first, and an unknown ticker returns an empty `dataPoints` array rather than an error. Every identifier in `getGraph` is a slug, the same handle the metric and document endpoints take. An ETF symbol is refused by `getQuote` with an `APIError` whose `code` is `"ticker_is_etf"`; use `etfs.quote()` for funds.
+
+Product nodes (`type === "PRODUCT_OR_SERVICE"`) in `stocks.getGraph` now carry optional `category` when known. Other nodes and products without a category omit it.
+
 ### Documents & news
 
 ```typescript
@@ -287,6 +294,18 @@ client.institutional.getHolders("AAPL", "2025-02-14")
 client.institutional.getActivists("2025-02-14")
 ```
 
+`positionsHeld` on an institution detail counts the full portfolio's held positions:
+`max(0, holdingsCount - soldOutPositions)`, even when the holdings list is truncated.
+`getInstitutionDetail` keeps its `Promise<unknown>` signature. The exported all-optional
+`InstitutionDetail` type is available for callers who want to opt in:
+
+```typescript
+import type { InstitutionDetail, PreviewResponse } from "sentisense";
+
+const detail = await client.institutional.getInstitutionDetail("1067983") as PreviewResponse<InstitutionDetail>;
+console.log(detail.data.positionsHeld); // undefined when an older response omits it
+```
+
 **Paging the holder list.** A widely held ticker returns thousands of rows: a megacap quarter is roughly 6,000 holders and 1.5 MB on the wire. Pass `limit` unless you really want the whole list; omitting the options object sends the original unbounded request, so existing code keeps working.
 
 | Option | Values |
@@ -412,6 +431,8 @@ Two shapes to read rather than assume. A firm can appear with `noteCount: 0`, a
 
 `ratingBuckets` sizes the same book by rating tier: `buy`, `hold`, `sell`, `unrated` and `total`, counted over every covering firm before the free truncation, so `buy + hold + sell + unrated === total` and a free key reads the same numbers as a PRO one. `unrated` is a desk with no current rating on record, such as a price-target-only firm. These count the firms in this coverage book, a different population from the `strongBuy` through `strongSell` figures on `client.analyst.consensus`, which come from the provider's analyst survey. Read one or the other, do not reconcile them.
 
+Surprise rows now carry optional `surprisePct`, the signed true percent rounded half-up to two decimals: `(actualEps - estimateEps) * 100 / abs(estimateEps)`. It is `null` when either EPS is missing or the estimate is zero, and `undefined` on older responses. The existing `surprisePercent` fraction is unchanged (`0.03` means about 3%).
+
 ### Earnings
 
 The earnings analysis report is the assembled version of a quarter: one object per fiscal period carrying the editorial headline, the KPI cards with year-over-year deltas, the guidance language as management phrased it, and a summary of the earnings call. Pair it with the recent-reporters feed to drive a post-earnings sweep. Summaries, recent reports, statistics, and rankings return the preview envelope; per-ticker reactions return a direct payload.
@@ -446,6 +467,8 @@ if (quarter) {
 
 The forward-looking half of the family is `client.calendar.getEarnings()`, which covers scheduled dates and consensus EPS rather than results.
 
+`earnings.getSummaries` exposes optional `totalCount` on the envelope on both PRO and FREE. It counts indexed quarters; returned rows can be fewer because of `limit` or an unavailable body. Older responses without the count still read as `undefined`.
+
 ### Company KPIs (PRO)
 
 ```typescript
@@ -459,6 +482,7 @@ Composition data is public; the holdings-weighted aggregate views follow the sam
 
 ```typescript
 client.etfs.list()                                              // Every ETF tracked
+client.etfs.quote("SPY")                                        // Price, ranges, AUM, expense ratio, NAV
 client.etfs.holdings("QQQ")                                     // Full composition + freshness metadata
 client.etfs.analystAggregate("QQQ")                             // Holdings-weighted analyst consensus
 client.etfs.insiderAggregate("ARKK", { lookbackDays: 90 })      // Holdings-weighted Form 4 net flow
@@ -505,6 +529,8 @@ During the trading session the dossier and the radar also carry a few intraday f
 
 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.
 
+On a delisted symbol, the options summary carries `listingStatus === "DELISTED"` and, when known, `delistedDate` (YYYY-MM-DD). This marks a frozen last dossier, so read `asOf` before treating it as current. Listed and pending symbols omit both fields.
+
 ### SentiSense Rating
 
 Where a stock ranks against the other stocks rated that day, as a score, a letter and a percentile, plus the seven dimensions the rank is blended from. It is a relative research signal for informational and educational purposes, not financial, investment or trading advice, and not a recommendation about any security. Every response carries the wording to display alongside a grade in `disclaimer`. [Methodology](https://sentisense.ai/methodology/#sentisense-rating).

package/dist/cli.cjs

@@ -502,10 +502,22 @@ async function verifyTickerOnEmpty(api, ticker) {
     await api.stocks.getQuote(ticker);
     return void 0;
   } catch (error) {
+    if (isEtfRedirect(error)) return void 0;
     if (error instanceof NotFoundError) throw new UnknownTickerError(ticker);
     return `could not verify ${ticker}, so the empty result is unconfirmed`;
   }
 }
+function isEtfRedirect(error) {
+  return error instanceof APIError && error.code === "ticker_is_etf";
+}
+async function quoteAnyTicker(api, ticker) {
+  try {
+    return { kind: "stock", quote: await api.stocks.getQuote(ticker) };
+  } catch (error) {
+    if (!isEtfRedirect(error)) throw error;
+    return { kind: "etf", quote: await api.etfs.quote(ticker) };
+  }
+}
 var EMPTY_VERIFY_NOTE = "An empty result verifies the ticker before reporting no data, so a typo exits 4 rather";
 var EMPTY_VERIFY_NOTE_2 = "than looking like a company with nothing to report.";
 
@@ -518,11 +530,13 @@ function actionTone(actionType) {
   return void 0;
 }
 function primaryAnalyst(row) {
-  const named = row.latestNote?.analyst;
-  const match = (named ? row.analysts.find((analyst) => analyst.name === named) : void 0) ?? row.analysts[0];
-  const name = match?.name ?? named ?? "";
+  const named = row.latestNote?.analyst ?? null;
+  const match = (named ? row.analysts.find(
+    (analyst) => named.slug !== null && analyst.slug === named.slug || analyst.name === named.name
+  ) : void 0) ?? row.analysts[0];
+  const name = match?.name ?? named?.name ?? "";
   const extra = row.analysts.length > 1 ? ` +${row.analysts.length - 1}` : "";
-  return { name: name ? `${name}${extra}` : "", slug: match?.slug ?? "" };
+  return { name: name ? `${name}${extra}` : "", slug: match?.slug ?? named?.slug ?? "" };
 }
 var analystsCommand = {
   name: "analysts",
@@ -1331,7 +1345,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.61.0";
+var VERSION = "0.63.0";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -1590,9 +1604,11 @@ var Earnings = class {
    * management phrased it, and a summary of the earnings call.
    *
    * Branch on `isPreview`: a PRO key receives every hydrated quarter in full, a
-   * FREE key receives the latest quarter shaped rather than truncated, plus
-   * `totalCount`. {@link EarningsQuarter} documents which fields each tier
-   * carries.
+   * FREE key receives the latest quarter shaped rather than truncated.
+   * `totalCount` on the envelope counts indexed quarters on both tiers. The
+   * returned array can be shorter when a body is unavailable or limit cuts it.
+   * Older responses may omit the count. {@link EarningsQuarter} documents
+   * which fields each tier carries.
    *
    * A quarter typically appears within 48 hours of the company reporting, and
    * the call summary can arrive after the press-release content for the same
@@ -1726,6 +1742,19 @@ var Etfs = class {
   async list() {
     return this.client.get("/api/v1/etfs");
   }
+  /**
+   * Get the quote snapshot for an ETF: price, day and 52-week range, volume, dividend
+   * yield, AUM, expense ratio, NAV and inception date.
+   *
+   * Fails with a 400 `APIError` whose `code` is `"ticker_is_not_etf"` when the symbol is a
+   * stock (use `stocks.getQuote()` for those), and a `NotFoundError` when there is no
+   * price data for the fund.
+   */
+  async quote(ticker) {
+    return this.client.get(
+      `/api/v1/etfs/${encodeURIComponent(ticker.toUpperCase())}/quote`
+    );
+  }
   /**
    * Get the full holdings composition for an ETF, including per-holding weights
    * and freshness metadata. Returns 404 for unknown ETFs or commodity-only funds.
@@ -2054,6 +2083,10 @@ var Institutional = class {
    * Resolved by URL slug (e.g. `Berkshire-Hathaway`) or numeric SEC CIK.
    * Free users receive the profile and top 10 holdings; PRO users receive the
    * full holdings array. Returns 404 if the slug or CIK is unknown.
+   *
+   * The signature remains unknown for compatibility. Opt in to the exported
+   * PreviewResponse<InstitutionDetail> type to read data.positionsHeld, the full
+   * portfolio count excluding SOLD_OUT rows, even on a truncated holdings list.
    */
   async getInstitutionDetail(slugOrCik) {
     return this.client.get(
@@ -2320,6 +2353,22 @@ var Stocks = class {
   async getEntities(ticker) {
     return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/entities`);
   }
+  /**
+   * Get the company knowledge graph around a stock: the people, products, peers and other
+   * entities linked to the company, and the typed relationships between them.
+   *
+   * Every identifier in the response is a slug, the same handle the metric and document
+   * endpoints take, so a node can be passed straight to them. `depth` is 1 (default) or 2,
+   * `cap` limits the number of non-root nodes (1 to 200, default 75); the root is always
+   * included in addition. Out-of-range values are rejected with a 400. A ticker with no
+   * graph returns a `NotFoundError`.
+   */
+  async getGraph(ticker, options) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/graph`,
+      options
+    );
+  }
   /**
    * Get AI-generated stock analysis report. Requires PRO tier.
    *
@@ -2382,17 +2431,23 @@ var Stocks = class {
   async getHistoricalRevenue(ticker) {
     return this.client.get("/api/v1/stocks/fundamentals/historical/revenue", { ticker });
   }
-  /** Get short interest metrics (FINRA). */
-  async getShortInterest(ticker) {
-    return this.client.get("/api/v1/stocks/short-interest", { ticker });
+  /**
+   * Get short interest history (FINRA), newest first: shares short, days to cover and
+   * average daily volume per settlement date. `limit` defaults to 24 settlement dates.
+   */
+  async getShortInterest(ticker, options) {
+    return this.client.get("/api/v1/stocks/short-interest", { ticker, ...options });
   }
   /** Get float information. */
   async getFloat(ticker) {
     return this.client.get("/api/v1/stocks/float", { ticker });
   }
-  /** Get short volume trading data. */
-  async getShortVolume(ticker) {
-    return this.client.get("/api/v1/stocks/short-volume", { ticker });
+  /**
+   * Get daily short volume, newest first: shares sold short against total volume on the
+   * reporting venues. `limit` defaults to 90 trading days.
+   */
+  async getShortVolume(ticker, options) {
+    return this.client.get("/api/v1/stocks/short-volume", { ticker, ...options });
   }
   /**
    * Get company-specific KPI time-series for a ticker. Returns curated GAAP and
@@ -3641,6 +3696,37 @@ var optionsCommand = {
 };
 
 // src/cli/commands/quote.ts
+function valuation(row) {
+  if (row.kind === "etf") {
+    const etf = row.quote;
+    return {
+      kind: "facts",
+      items: fields(
+        field("AUM", humanize(etf.aum)),
+        // Both ratios, like `dividendYield` on the stock quote.
+        field("Expense ratio", ratioPercent(etf.expenseRatio)),
+        field("NAV", fixed(etf.nav)),
+        field("Div yield", ratioPercent(etf.dividendYield)),
+        field("52w", `${fixed(etf.week52Low)} to ${fixed(etf.week52High)}`)
+      )
+    };
+  }
+  const quote = row.quote;
+  return {
+    kind: "facts",
+    items: fields(
+      field("Mkt cap", humanize(quote.marketCap)),
+      field("P/E", fixed(quote.peRatio)),
+      field("EPS TTM", fixed(quote.epsTTM)),
+      // A ratio, unlike `changePercent` and the other percentages in the same payload.
+      field("Div yield", ratioPercent(quote.dividendYield)),
+      field(
+        "52w",
+        `${fixed(quote.week52Low)} to ${fixed(quote.week52High)}`
+      )
+    )
+  };
+}
 function single(row, full) {
   const { quote, profile } = row;
   const tone = direction(quote.changePercent);
@@ -3668,20 +3754,7 @@ function single(row, full) {
         field("Prev close", fixed(quote.previousClose))
       )
     },
-    {
-      kind: "facts",
-      items: fields(
-        field("Mkt cap", humanize(quote.marketCap)),
-        field("P/E", fixed(quote.peRatio)),
-        field("EPS TTM", fixed(quote.epsTTM)),
-        // A ratio, unlike `changePercent` and the other percentages in the same payload.
-        field("Div yield", ratioPercent(quote.dividendYield)),
-        field(
-          "52w",
-          `${fixed(quote.week52Low)} to ${fixed(quote.week52High)}`
-        )
-      )
-    }
+    valuation(row)
   ];
   if (quote.extendedHours) {
     const ext = quote.extendedHours;
@@ -3700,25 +3773,33 @@ function single(row, full) {
       )
     });
   }
-  if (full) {
+  if (full && row.kind === "etf") {
+    blocks.push({
+      kind: "kv",
+      items: fields(
+        row.quote.inceptionDate ? field("inception", row.quote.inceptionDate) : void 0
+      )
+    });
+  } else if (full && row.kind === "stock") {
     blocks.push({
       kind: "kv",
       items: fields(
-        field("200d average", fixed(quote.movingAverage200Day)),
-        quote.reportedCurrency ? field("reported currency", quote.reportedCurrency) : void 0,
+        field("200d average", fixed(row.quote.movingAverage200Day)),
+        row.quote.reportedCurrency ? field("reported currency", row.quote.reportedCurrency) : void 0,
         profile?.sector ? field("sector", String(profile.sector)) : void 0,
         profile?.industry ? field("industry", String(profile.industry)) : void 0,
         profile?.ceo ? field("ceo", String(profile.ceo)) : void 0
       )
     });
   }
-  if (quote.listingStatus === "DELISTED") {
+  const listingStatus = row.kind === "stock" ? row.quote.listingStatus : void 0;
+  if (row.kind === "stock" && listingStatus === "DELISTED") {
     blocks.push({
       kind: "text",
-      text: `Delisted on ${quote.delistedDate ?? "an unrecorded date"}. Every figure above is frozen at the last trade, not a live market move.`,
+      text: `Delisted on ${row.quote.delistedDate ?? "an unrecorded date"}. Every figure above is frozen at the last trade, not a live market move.`,
       tone: "down"
     });
-  } else if (quote.listingStatus === "PENDING_DELISTING") {
+  } else if (listingStatus === "PENDING_DELISTING") {
     blocks.push({
       kind: "text",
       text: "A merger or take-private is scheduled. The stock still trades, so these figures are current.",
@@ -3745,7 +3826,8 @@ function table(rows, full) {
         cell(signed(row.quote.change), tone),
         cell(signedPercent(row.quote.changePercent), tone),
         cell(humanize(row.quote.volume, 1)),
-        cell(humanize(row.quote.marketCap))
+        // An ETF has no market cap; its AUM is a different number and stays out of this column.
+        cell(humanize(row.kind === "stock" ? row.quote.marketCap : void 0))
       ];
       return full ? [cell(row.ticker), cell(row.profile?.name ?? ""), ...tail] : [cell(row.ticker), ...tail];
     })
@@ -3767,7 +3849,9 @@ var quoteCommand = {
     "Use canonical symbols, for example GOOGL rather than GOOG and BRK.B rather than BRK-B.",
     "One request per ticker. The company name costs a second request, so it is fetched only",
     "for the terminal layout: piped and --json output carry the quote alone.",
-    "JSON is the exact quote response for one ticker, and an object keyed by ticker for more."
+    "JSON is the exact quote response for one ticker, and an object keyed by ticker for more.",
+    "An ETF symbol answers with the ETF quote: AUM, expense ratio and NAV in place of market",
+    "cap, P/E and EPS. That costs one extra request per ETF symbol."
   ],
   flags: {},
   async run({ args, client, full, mode }) {
@@ -3779,12 +3863,12 @@ var quoteCommand = {
     const wantName = mode === "pretty";
     const rows = await Promise.all(
       tickers.map(async (ticker) => {
-        const [quote, profile] = await Promise.all([
-          api.stocks.getQuote(ticker),
+        const [answer, profile] = await Promise.all([
+          quoteAnyTicker(api, ticker),
           // A name is a nicety, not the answer. A ticker with no profile still gets a quote.
           wantName ? api.stocks.getProfile(ticker).catch(() => null) : Promise.resolve(null)
         ]);
-        return { ticker, quote, profile };
+        return { ...answer, ticker, profile };
       })
     );
     if (rows.length === 1) {

package/dist/index.cjs

@@ -339,9 +339,11 @@ var Earnings = class {
    * management phrased it, and a summary of the earnings call.
    *
    * Branch on `isPreview`: a PRO key receives every hydrated quarter in full, a
-   * FREE key receives the latest quarter shaped rather than truncated, plus
-   * `totalCount`. {@link EarningsQuarter} documents which fields each tier
-   * carries.
+   * FREE key receives the latest quarter shaped rather than truncated.
+   * `totalCount` on the envelope counts indexed quarters on both tiers. The
+   * returned array can be shorter when a body is unavailable or limit cuts it.
+   * Older responses may omit the count. {@link EarningsQuarter} documents
+   * which fields each tier carries.
    *
    * A quarter typically appears within 48 hours of the company reporting, and
    * the call summary can arrive after the press-release content for the same
@@ -475,6 +477,19 @@ var Etfs = class {
   async list() {
     return this.client.get("/api/v1/etfs");
   }
+  /**
+   * Get the quote snapshot for an ETF: price, day and 52-week range, volume, dividend
+   * yield, AUM, expense ratio, NAV and inception date.
+   *
+   * Fails with a 400 `APIError` whose `code` is `"ticker_is_not_etf"` when the symbol is a
+   * stock (use `stocks.getQuote()` for those), and a `NotFoundError` when there is no
+   * price data for the fund.
+   */
+  async quote(ticker) {
+    return this.client.get(
+      `/api/v1/etfs/${encodeURIComponent(ticker.toUpperCase())}/quote`
+    );
+  }
   /**
    * Get the full holdings composition for an ETF, including per-holding weights
    * and freshness metadata. Returns 404 for unknown ETFs or commodity-only funds.
@@ -803,6 +818,10 @@ var Institutional = class {
    * Resolved by URL slug (e.g. `Berkshire-Hathaway`) or numeric SEC CIK.
    * Free users receive the profile and top 10 holdings; PRO users receive the
    * full holdings array. Returns 404 if the slug or CIK is unknown.
+   *
+   * The signature remains unknown for compatibility. Opt in to the exported
+   * PreviewResponse<InstitutionDetail> type to read data.positionsHeld, the full
+   * portfolio count excluding SOLD_OUT rows, even on a truncated holdings list.
    */
   async getInstitutionDetail(slugOrCik) {
     return this.client.get(
@@ -1069,6 +1088,22 @@ var Stocks = class {
   async getEntities(ticker) {
     return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/entities`);
   }
+  /**
+   * Get the company knowledge graph around a stock: the people, products, peers and other
+   * entities linked to the company, and the typed relationships between them.
+   *
+   * Every identifier in the response is a slug, the same handle the metric and document
+   * endpoints take, so a node can be passed straight to them. `depth` is 1 (default) or 2,
+   * `cap` limits the number of non-root nodes (1 to 200, default 75); the root is always
+   * included in addition. Out-of-range values are rejected with a 400. A ticker with no
+   * graph returns a `NotFoundError`.
+   */
+  async getGraph(ticker, options) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/graph`,
+      options
+    );
+  }
   /**
    * Get AI-generated stock analysis report. Requires PRO tier.
    *
@@ -1131,17 +1166,23 @@ var Stocks = class {
   async getHistoricalRevenue(ticker) {
     return this.client.get("/api/v1/stocks/fundamentals/historical/revenue", { ticker });
   }
-  /** Get short interest metrics (FINRA). */
-  async getShortInterest(ticker) {
-    return this.client.get("/api/v1/stocks/short-interest", { ticker });
+  /**
+   * Get short interest history (FINRA), newest first: shares short, days to cover and
+   * average daily volume per settlement date. `limit` defaults to 24 settlement dates.
+   */
+  async getShortInterest(ticker, options) {
+    return this.client.get("/api/v1/stocks/short-interest", { ticker, ...options });
   }
   /** Get float information. */
   async getFloat(ticker) {
     return this.client.get("/api/v1/stocks/float", { ticker });
   }
-  /** Get short volume trading data. */
-  async getShortVolume(ticker) {
-    return this.client.get("/api/v1/stocks/short-volume", { ticker });
+  /**
+   * Get daily short volume, newest first: shares sold short against total volume on the
+   * reporting venues. `limit` defaults to 90 trading days.
+   */
+  async getShortVolume(ticker, options) {
+    return this.client.get("/api/v1/stocks/short-volume", { ticker, ...options });
   }
   /**
    * Get company-specific KPI time-series for a ticker. Returns curated GAAP and
@@ -1353,7 +1394,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.61.0";
+var VERSION = "0.63.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";