sentisense 0.51.0 → 0.53.0

package/README.md

@@ -71,7 +71,8 @@ npx -y sentisense@latest health
 | `quote <ticker>...` | Price, day range, 52-week range, market cap, P/E. One request per ticker |
 | `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 |
+| `analysts <ticker>` | Consensus, price target band, recent upgrades and downgrades. `--coverage` for who covers it, by firm |
+| `analyst <slug>` | One analyst: their firms, their coverage book, and `--calls` for their price target notes |
 | `earnings [ticker]` | Forward calendar with no ticker, per-quarter analysis with one (`earnings AAPL`) |
 | `insiders <ticker>` | Filed Form 4 transactions, including whether they were pre-planned |
 | `insights <ticker>` | Generated signals, filterable by `--urgency` and `--type` |
@@ -80,9 +81,22 @@ npx -y sentisense@latest health
 | `flows [ticker]` | Institutional 13F flows, or one ticker's holders and notable changes |
 | `options <ticker>` | End-of-day options positioning, IV rank, walls, unusual contracts |
 | `screen --filter ...` | Screen the universe on Score, analyst, technical, and price fields |
+| `search <name>` | Resolve a name, alias, ticker or slug to a symbol and the entity handle |
 
 Run `sentisense help <command>` for its flags and examples.
 
+Three of these chain into each other. Start from a name, land on a person:
+
+```bash
+npx -y sentisense@latest search Tesla --type company   # "Tesla" -> TSLA, plus the entity slug
+npx -y sentisense@latest analysts NVDA --coverage      # who covers it, by firm, with analyst slugs
+npx -y sentisense@latest analyst quinn-bolton --calls  # that analyst's firms, book, and notes
+```
+
+`analyst` takes a slug, not a name: slugs are lowercase and hyphenated, and every named analyst in a `--coverage` row carries the one that addresses them. A name is rejected before a request is spent. What comes back is call history, not accuracy scoring: there is no hit rate, no ranking, and nothing in it rates the person.
+
+Ranking on `search` is the API's own, and a company can sort below its own products, so pass `--type company` when what you want is the issuer.
+
 ### Output modes
 
 Readable in a terminal, plain text when piped, and exact API JSON on request:
@@ -227,6 +241,27 @@ client.documents.getStories({ limit: 10 })
 client.documents.getStoryDetail("cluster_abc123")
 ```
 
+A story's `cluster` says where it came from and whether it has settled. `storySource` is
+`"ORIGINAL"` for an editorially authored SentiSense Original and `"AI"` for a
+pipeline-generated story, and `isLive` is true while the story is still being revised as
+the event develops. Both are optional: against an API build that predates them they are
+`undefined`, which means "not known" rather than `"AI"` or `false`.
+
+`getStoryDetail` returns `unknown`, so narrow it yourself. It carries the same two fields
+plus a `timeline` array of dated updates, newest first and empty when a story has none.
+The `StoryTimelineEntry` type is exported for that array:
+
+```typescript
+import type { StoryTimelineEntry } from "sentisense";
+
+const detail = (await client.documents.getStoryDetail("cluster_abc123")) as {
+  timeline: StoryTimelineEntry[];
+};
+for (const update of detail.timeline) {
+  console.log(new Date(update.publishedAt), update.updateType, update.content);
+}
+```
+
 ### Institutional flows (13F)
 
 ```typescript
@@ -474,8 +509,18 @@ All five are optional: a response served before they shipped omits them. For the
 ```typescript
 client.marketMood.get()             // Composite market sentiment with sub-signals
 client.kb.getPopularEntities()      // Most-tracked entities
+client.kb.searchEntities("Tesla")   // Resolve a name, alias, ticker or slug to what we track
 ```
 
+Entity search is resolution, not enumeration: the query must be at least 2 characters, the match count is capped at 25, and it returns a bare `EntitySearchResult[]` rather than a `PreviewResponse` envelope. Each hit carries `name`, `type`, the `ticker` for a listed entity (`null` for everything else), and the `urlSlug` the metric endpoints address that entity by, which is the only way to get a handle for a person, product or topic with no ticker.
+
+```typescript
+const hits = await client.kb.searchEntities("Tesla", { type: "company", limit: 5 });
+const symbol = hits.find((hit) => hit.ticker)?.ticker;   // "TSLA"
+```
+
+An empty array is the normal answer for a query that matches nothing, so branch on `length` rather than catching.
+
 ### Screener
 
 Filter the tracked universe on the SentiSense Score, attention, analyst consensus, technicals and price in one query. Screening on analyst ratings alone is something a dozen free tools do; screening on analyst ratings *where the Score disagrees* is not.