sentisense 0.49.0 → 0.50.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/sentisense.svg)](https://www.npmjs.com/package/sentisense)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-Official JavaScript/TypeScript SDK and CLI for the [SentiSense](https://sentisense.ai) market intelligence API: stock prices, news and social sentiment, the SentiSense Score, insider and congressional trading, institutional 13F flows, options positioning, analyst ratings, earnings analysis, and a cross-signal screener.
+Official JavaScript/TypeScript SDK and CLI for the [SentiSense](https://sentisense.ai) market intelligence API: stock prices, news and social sentiment, the SentiSense Score, the SentiSense Rating, insider and congressional trading, institutional 13F flows, options positioning, analyst ratings, earnings analysis, and a cross-signal screener.
 
 - Full TypeScript support with detailed type definitions
 - Works in Node.js 18+, Deno, Bun, and browsers
@@ -212,6 +212,7 @@ 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.getRating("AAPL")                         // SentiSense Rating: letter, percentile, dimensions
 client.stocks.getAISummary("AAPL", { depth: "deep" })   // AI report (PRO)
 ```
 
@@ -332,6 +333,11 @@ const { data: book } = await client.analyst.coverage("NVDA");
 console.log(`${book.firmCount} firms, ${book.namedAnalystCount} named analysts`);
 console.log(`${book.attributedNoteCount} of ${book.noteCount} notes name someone`);
 
+const buckets = book.ratingBuckets;
+if (buckets) {
+  console.log(`${buckets.buy} buy, ${buckets.hold} hold, ${buckets.sell} sell, ${buckets.unrated} unrated of ${buckets.total}`);
+}
+
 for (const row of book.coverage.slice(0, 5)) {
   if (row.noteCount === 0) {
     // A desk can cover a stock on rating actions alone, with no price target.
@@ -351,6 +357,8 @@ for (const row of book.coverage.slice(0, 5)) {
 
 Two shapes to read rather than assume. A firm can appear with `noteCount: 0`, a `null` `latestNote` and a populated `firmRating`, because coverage means a price target **or** a rating action in the window. And a large, publisher-dependent share of notes name no individual, so an empty `analysts` array alongside a non-zero `noteCount` is normal: read `attributedNoteCount` and `unattributedNoteCount` off the response rather than hardcoding a rate. The response-level counts survive the free truncation, so they describe the whole window even when only 5 rows come back. An unknown slug throws `NotFoundError`, which keeps "published nothing we hold" distinguishable from "does not exist".
 
+`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.
+
 ### 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. Both return the preview envelope.
@@ -418,7 +426,7 @@ client.entityMetrics.getDistribution("AAPL", "sentiment")
 client.entityMetrics.getDistribution("AAPL", "mentions", { dimension: "source" })
 ```
 
-Available metric types: `mentions`, `sentiment`, `sentisense`, `social_dominance`, `creators`.
+Available metric types: `mentions`, `sentiment`, `sentisense_score`, `sentisense_rating`, `social_dominance`, `creators`. `sentisense_rating` is the SentiSense Rating percentile and is a time series only: it has no source breakdown, so `getDistribution` answers with an empty distribution for it.
 
 ### Options
 
@@ -434,6 +442,28 @@ The radar carries two separately-ranked boards: `data.rows` for stocks and `data
 
 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.
 
+### SentiSense Rating
+
+Where a stock ranks against the other stocks rated that day, as a letter and a percentile, plus the six 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).
+
+```typescript
+const rating = await client.stocks.getRating("AAPL");
+if (rating.rated) {
+  console.log(rating.letter, rating.percentile, "of", rating.ratedCount, "rated stocks");
+  for (const dim of rating.dimensions.filter((d) => d.present)) {
+    console.log(" ", dim.label, dim.percentile);
+  }
+} else {
+  console.log("no grade today:", rating.reason);
+}
+```
+
+`StockRating` is a discriminated union on `rated`, so the `if` narrows to `letter`, `percentile`, `composite`, `ratedCount` and `methodologyVersion`, and the `else` narrows to `reason`, `dimensionsPresent` and `presentDimensions`. Branch on that flag rather than testing a field for `undefined`.
+
+Having no grade is a normal 200, not a 404: ETFs and tickers outside the swept universe answer that way, and `reason` is one of `stale`, `not_rated_today`, `insufficient_dimensions` or `insufficient_coverage_weight`. Only a ticker that resolves to nothing we track rejects with `NotFoundError`.
+
+`dimensions` always holds all six rows in a fixed order, including the ones with no data, which arrive with `present` false and a `null` percentile. Read `present` first and never substitute zero for a missing percentile: zero is the bottom of the cross-section, absence is not a position on it. Only the smart-money dimension carries `subLegs`. `letter` is served as stored rather than derived from `percentile`, so read it instead of computing your own bucket edges. For the daily history of a stock's percentile, ask `entityMetrics.getMetrics` for the `sentisense_rating` metric.
+
 ### Market mood & knowledge base
 
 ```typescript

package/dist/cli.cjs

@@ -1037,7 +1037,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.49.0";
+var VERSION = "0.50.0";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -2069,6 +2069,38 @@ var Stocks = class {
       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.
+   *
+   * The Rating is a *relative*, automatically generated research signal, for informational
+   * and educational purposes only. It ranks a stock against its cross-section; it is not
+   * financial, investment or trading advice and it is not a recommendation about any
+   * security. `disclaimer` carries the wording to display alongside a grade. Methodology:
+   * https://sentisense.ai/methodology/#sentisense-rating
+   *
+   * **A discriminated union on `rated`.** `if (rating.rated)` narrows to `letter`,
+   * `percentile`, `composite`, `ratedCount` and `methodologyVersion`; the `else` branch
+   * narrows to `reason`, `dimensionsPresent` and `presentDimensions`. Branch on the flag
+   * rather than testing a field for `undefined`.
+   *
+   * **Having no grade is a normal 200, not a 404.** ETFs and tickers outside the swept
+   * universe answer with `rated` false, and the composition still arrives so a card can
+   * render. Only a ticker that resolves to nothing we track rejects with
+   * {@link NotFoundError}; a request with no usable key rejects with
+   * {@link AuthenticationError}.
+   *
+   * `dimensions` always holds all six rows in a fixed order, including the ones with no
+   * data, which arrive with `present` false and a `null` percentile. Read `present` first
+   * and never read a missing percentile as zero. `letter` is served as stored rather than
+   * derived from `percentile`, so read it instead of computing your own bucket edges.
+   *
+   * For the daily history of a stock's percentile, ask `client.entityMetrics.getMetrics`
+   * for the `sentisense_rating` metric.
+   */
+  async getRating(ticker) {
+    return this.client.get(`/api/v1/rating/${encodeURIComponent(ticker.toUpperCase())}`);
+  }
 };
 
 // src/resources/indexes.ts

package/dist/index.cjs

@@ -1104,6 +1104,38 @@ var Stocks = class {
       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.
+   *
+   * The Rating is a *relative*, automatically generated research signal, for informational
+   * and educational purposes only. It ranks a stock against its cross-section; it is not
+   * financial, investment or trading advice and it is not a recommendation about any
+   * security. `disclaimer` carries the wording to display alongside a grade. Methodology:
+   * https://sentisense.ai/methodology/#sentisense-rating
+   *
+   * **A discriminated union on `rated`.** `if (rating.rated)` narrows to `letter`,
+   * `percentile`, `composite`, `ratedCount` and `methodologyVersion`; the `else` branch
+   * narrows to `reason`, `dimensionsPresent` and `presentDimensions`. Branch on the flag
+   * rather than testing a field for `undefined`.
+   *
+   * **Having no grade is a normal 200, not a 404.** ETFs and tickers outside the swept
+   * universe answer with `rated` false, and the composition still arrives so a card can
+   * render. Only a ticker that resolves to nothing we track rejects with
+   * {@link NotFoundError}; a request with no usable key rejects with
+   * {@link AuthenticationError}.
+   *
+   * `dimensions` always holds all six rows in a fixed order, including the ones with no
+   * data, which arrive with `present` false and a `null` percentile. Read `present` first
+   * and never read a missing percentile as zero. `letter` is served as stored rather than
+   * derived from `percentile`, so read it instead of computing your own bucket edges.
+   *
+   * For the daily history of a stock's percentile, ask `client.entityMetrics.getMetrics`
+   * for the `sentisense_rating` metric.
+   */
+  async getRating(ticker) {
+    return this.client.get(`/api/v1/rating/${encodeURIComponent(ticker.toUpperCase())}`);
+  }
 };
 
 // src/resources/indexes.ts
@@ -1183,7 +1215,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.49.0";
+var VERSION = "0.50.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";