sentisense 0.49.0 → 0.51.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: score, 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 score and is a time series only: it has no source breakdown, so `getDistribution` answers with an empty distribution for it.
 
 ### Options
 
@@ -434,6 +442,33 @@ 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 score, 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.score, "percentile", rating.percentile, "of", rating.ratedCount);
+  for (const adj of rating.riskAdjustments ?? []) console.log(" ", adj.condition, -adj.points);
+  for (const dim of rating.dimensions.filter((d) => d.present)) {
+    console.log(" ", dim.label, dim.percentile);
+  }
+} else {
+  console.log("no grade today:", rating.reason);
+}
+```
+
+`getRating` returns `StockRatingResponse`, a discriminated union on `rated` of `StockRating` (graded) and `StockNotRated`. The `if` narrows to `score`, `letter`, `percentile`, `composite`, `ratedCount` and `methodologyVersion`, the `else` 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`.
+
+**`score` is not `percentile`.** `percentile` is the rank of the blended signals against the day's rated set. `score = percentile - sum(riskAdjustments.map((a) => a.points))`, floored at 10 when fewer than five dimensions are available, and it is the number `letter` bands (A 90, B 70, C 30, D 10). `bucketLetter` is the band the percentile alone would give, so the two letters differ by exactly what the conditions cost. `riskAdjustments` itemises that cost, `penaltyPoints` totals it, and `riskConditions` names the active ones from the `RiskCondition` union: `thin_coverage`, `weak_dimension`, `unprofitable`, `no_fundamentals`, `high_leverage`, `unseasoned_listing`, `small_market_cap`, `thin_liquidity`, `extended_price`, `insider_selling` and `institutional_outflow`.
+
+All five are optional: a response served before they shipped omits them. For the daily history of a stock's score, 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.51.0";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -2069,6 +2069,49 @@ 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 `score`,
+   * `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.
+   *
+   * **`score` and `percentile` are different numbers.** `percentile` is the rank of the
+   * blended signals against the day's rated set, and
+   * `score = percentile - sum(riskAdjustments.map((a) => a.points))`, floored at 10 when
+   * fewer than five dimensions are available and at 0 otherwise. `letter` is the band
+   * `score` falls in, at edges 90, 70, 30 and 10, while `bucketLetter` is the band the
+   * percentile alone would fall in, so a difference between the two letters is exactly
+   * what the conditions cost. `riskConditions` names the active ones, `riskAdjustments`
+   * gives the points each cost (graded, up to 12 apiece), and `penaltyPoints` is their
+   * sum. `letter` is served as stored, so read it instead of computing your own bucket
+   * edges. The five fields arrive from the next API deploy onward and are optional, so a
+   * response served before then still parses.
+   *
+   * For the daily history of a stock's score, 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,49 @@ 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 `score`,
+   * `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.
+   *
+   * **`score` and `percentile` are different numbers.** `percentile` is the rank of the
+   * blended signals against the day's rated set, and
+   * `score = percentile - sum(riskAdjustments.map((a) => a.points))`, floored at 10 when
+   * fewer than five dimensions are available and at 0 otherwise. `letter` is the band
+   * `score` falls in, at edges 90, 70, 30 and 10, while `bucketLetter` is the band the
+   * percentile alone would fall in, so a difference between the two letters is exactly
+   * what the conditions cost. `riskConditions` names the active ones, `riskAdjustments`
+   * gives the points each cost (graded, up to 12 apiece), and `penaltyPoints` is their
+   * sum. `letter` is served as stored, so read it instead of computing your own bucket
+   * edges. The five fields arrive from the next API deploy onward and are optional, so a
+   * response served before then still parses.
+   *
+   * For the daily history of a stock's score, 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 +1226,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.49.0";
+var VERSION = "0.51.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";