sentisense 0.47.2 → 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)
 ```
 
@@ -318,6 +319,46 @@ client.analyst.estimates("AAPL")                        // Forward EPS + surpris
 client.analyst.marketActivity({ lookbackDays: 7 })      // Market-wide analyst actions (PRO).
 ```
 
+Coverage answers "who covers this stock and what did they say" in one call, and it is the entry point into the per-analyst surfaces: every named analyst carries the slug that addresses their profile and their calls.
+
+```typescript
+client.analyst.coverage("NVDA", { lookbackDays: 365 })  // Who covers it, by firm. Free: 5 firms.
+client.analyst.profile("gil-luria")                     // One analyst's firms + coverage book.
+client.analyst.calls("gil-luria", { limit: 25 })        // Their price target notes, newest first.
+```
+
+```typescript
+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.
+    console.log(`${row.firm}: rating only, ${row.firmRating?.rating}`);
+    continue;
+  }
+  const who = row.latestNote?.analyst ?? "unattributed";
+  console.log(`${row.firm}: ${row.latestNote?.priceTarget} (${who})`);
+
+  for (const analyst of row.analysts) {
+    if (!analyst.slug) continue;
+    const calls = await client.analyst.calls(analyst.slug, { limit: 10 });
+    console.log(`  ${analyst.name}: ${calls.totalCount} notes on record`);
+  }
+}
+```
+
+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.
@@ -385,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
 
@@ -401,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.47.1";
+var VERSION = "0.50.0";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -1079,6 +1079,89 @@ var Analyst = class {
   async marketActivity(options) {
     return this.client.get("/api/v1/analyst/activity", options);
   }
+  /**
+   * Get who covers a ticker and what they most recently said, grouped by firm, most
+   * recently active firm first.
+   *
+   * This is the one-call answer to "who covers AMD and what do they say". Each row in
+   * `data.coverage` is a firm, the individual analysts we can name on that firm's desk,
+   * that firm's most recent price target note, and that firm's most recent rating action.
+   *
+   * A PRO key receives every firm. A FREE key receives the 5 most recently active firms
+   * with every response-level count intact, so the counts describe the full window even
+   * when the rows do not.
+   *
+   * Two shapes to read rather than assume. **A firm can cover a stock without publishing
+   * a price target**, because coverage means a note or a rating action in the window: that
+   * row carries `noteCount: 0`, a `null` `latestNote` and a populated `firmRating`, so
+   * read `noteCount` on the row instead of expecting a note. And **not every note names
+   * its analyst**, at a rate that is a property of the publisher and varies enormously by
+   * ticker, so a firm can appear with an empty `analysts` array and a non-zero
+   * `noteCount`, and `latestNote.analyst` can be `null`. Read `attributedNoteCount` and
+   * `unattributedNoteCount` off the response you received rather than hardcoding a rate.
+   *
+   * `firmRating` belongs to the firm, not to a person: rating actions are published at
+   * firm level with no individual attached.
+   *
+   * Each named analyst carries the `slug` that addresses {@link profile} and
+   * {@link calls}, so a coverage response is the natural entry point into a person.
+   */
+  async coverage(ticker, options) {
+    return this.client.get(
+      `/api/v1/analyst/${encodeURIComponent(ticker.toUpperCase())}/coverage`,
+      options
+    );
+  }
+  /**
+   * Get one analyst: the firms they have published under, the window of notes we hold at
+   * each, and the tickers they cover. Throws `NotFoundError` when the slug matches no
+   * analyst.
+   *
+   * A PRO key receives the full book. A FREE key receives the profile with
+   * `data.coverage` truncated to the 5 most recently covered tickers, and the envelope's
+   * `totalCount` reporting how many there are in full.
+   *
+   * `firstSeen` and `lastSeen` are observation windows, not employment dates: they bound
+   * the notes we hold from that analyst at that firm. `mostRecentFirm` says where they
+   * last published, not where they work today. Do not render either as a hire or
+   * departure date.
+   *
+   * This is call history, not a scorecard. There is no accuracy score, hit rate or
+   * ranking here, and nothing in the response should be read as a rating of the person.
+   *
+   * @param slug Analyst slug, lowercased and hyphenated (e.g. `"dan-ives"`). You do not
+   *   have to guess one: every named analyst in a {@link coverage} response carries it.
+   */
+  async profile(slug) {
+    return this.client.get(
+      `/api/v1/analyst/people/${encodeURIComponent(slug)}`
+    );
+  }
+  /**
+   * Get one analyst's price target notes, newest first, paged. Throws `NotFoundError`
+   * when the slug matches no analyst, which keeps "this analyst has published nothing we
+   * hold" (an empty page) distinguishable from "this analyst does not exist".
+   *
+   * Ordered by published date descending with the row id as the final tie-break, a total
+   * order, so walking the history with `offset` never drops or repeats a row. That
+   * matters more than it looks: a single roundup article carries several of one analyst's
+   * notes at an identical timestamp.
+   *
+   * A FREE key receives the first 25 rows as a complete response (`isPreview: false`);
+   * asking for a larger `limit` or an `offset` past row 25 returns the free in-allowance
+   * slice with `previewReason: "PRO_REQUIRED"`. A PRO key pages the whole history. The
+   * envelope's `totalCount` is the analyst's whole attributed history rather than the page
+   * size, so `offset + data.length < totalCount` tells you another page is available.
+   *
+   * Dates are day granularity on purpose. Publisher timestamps are not comparable across
+   * sources, so a time of day would advertise precision the data does not have.
+   */
+  async calls(slug, options) {
+    return this.client.get(
+      `/api/v1/analyst/people/${encodeURIComponent(slug)}/calls`,
+      options
+    );
+  }
 };
 
 // src/resources/calendar.ts
@@ -1986,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

@@ -114,6 +114,89 @@ var Analyst = class {
   async marketActivity(options) {
     return this.client.get("/api/v1/analyst/activity", options);
   }
+  /**
+   * Get who covers a ticker and what they most recently said, grouped by firm, most
+   * recently active firm first.
+   *
+   * This is the one-call answer to "who covers AMD and what do they say". Each row in
+   * `data.coverage` is a firm, the individual analysts we can name on that firm's desk,
+   * that firm's most recent price target note, and that firm's most recent rating action.
+   *
+   * A PRO key receives every firm. A FREE key receives the 5 most recently active firms
+   * with every response-level count intact, so the counts describe the full window even
+   * when the rows do not.
+   *
+   * Two shapes to read rather than assume. **A firm can cover a stock without publishing
+   * a price target**, because coverage means a note or a rating action in the window: that
+   * row carries `noteCount: 0`, a `null` `latestNote` and a populated `firmRating`, so
+   * read `noteCount` on the row instead of expecting a note. And **not every note names
+   * its analyst**, at a rate that is a property of the publisher and varies enormously by
+   * ticker, so a firm can appear with an empty `analysts` array and a non-zero
+   * `noteCount`, and `latestNote.analyst` can be `null`. Read `attributedNoteCount` and
+   * `unattributedNoteCount` off the response you received rather than hardcoding a rate.
+   *
+   * `firmRating` belongs to the firm, not to a person: rating actions are published at
+   * firm level with no individual attached.
+   *
+   * Each named analyst carries the `slug` that addresses {@link profile} and
+   * {@link calls}, so a coverage response is the natural entry point into a person.
+   */
+  async coverage(ticker, options) {
+    return this.client.get(
+      `/api/v1/analyst/${encodeURIComponent(ticker.toUpperCase())}/coverage`,
+      options
+    );
+  }
+  /**
+   * Get one analyst: the firms they have published under, the window of notes we hold at
+   * each, and the tickers they cover. Throws `NotFoundError` when the slug matches no
+   * analyst.
+   *
+   * A PRO key receives the full book. A FREE key receives the profile with
+   * `data.coverage` truncated to the 5 most recently covered tickers, and the envelope's
+   * `totalCount` reporting how many there are in full.
+   *
+   * `firstSeen` and `lastSeen` are observation windows, not employment dates: they bound
+   * the notes we hold from that analyst at that firm. `mostRecentFirm` says where they
+   * last published, not where they work today. Do not render either as a hire or
+   * departure date.
+   *
+   * This is call history, not a scorecard. There is no accuracy score, hit rate or
+   * ranking here, and nothing in the response should be read as a rating of the person.
+   *
+   * @param slug Analyst slug, lowercased and hyphenated (e.g. `"dan-ives"`). You do not
+   *   have to guess one: every named analyst in a {@link coverage} response carries it.
+   */
+  async profile(slug) {
+    return this.client.get(
+      `/api/v1/analyst/people/${encodeURIComponent(slug)}`
+    );
+  }
+  /**
+   * Get one analyst's price target notes, newest first, paged. Throws `NotFoundError`
+   * when the slug matches no analyst, which keeps "this analyst has published nothing we
+   * hold" (an empty page) distinguishable from "this analyst does not exist".
+   *
+   * Ordered by published date descending with the row id as the final tie-break, a total
+   * order, so walking the history with `offset` never drops or repeats a row. That
+   * matters more than it looks: a single roundup article carries several of one analyst's
+   * notes at an identical timestamp.
+   *
+   * A FREE key receives the first 25 rows as a complete response (`isPreview: false`);
+   * asking for a larger `limit` or an `offset` past row 25 returns the free in-allowance
+   * slice with `previewReason: "PRO_REQUIRED"`. A PRO key pages the whole history. The
+   * envelope's `totalCount` is the analyst's whole attributed history rather than the page
+   * size, so `offset + data.length < totalCount` tells you another page is available.
+   *
+   * Dates are day granularity on purpose. Publisher timestamps are not comparable across
+   * sources, so a time of day would advertise precision the data does not have.
+   */
+  async calls(slug, options) {
+    return this.client.get(
+      `/api/v1/analyst/people/${encodeURIComponent(slug)}/calls`,
+      options
+    );
+  }
 };
 
 // src/resources/calendar.ts
@@ -1021,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
@@ -1100,7 +1215,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.47.1";
+var VERSION = "0.50.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";