sentisense 0.47.2 → 0.49.0

package/README.md

@@ -318,6 +318,39 @@ 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`);
+
+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".
+
 ### 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.

package/dist/cli.cjs

@@ -1037,7 +1037,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.47.1";
+var VERSION = "0.49.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

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
@@ -1100,7 +1183,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.47.1";
+var VERSION = "0.49.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";