sentisense 0.52.0 → 0.54.0

package/README.md

@@ -170,7 +170,22 @@ Most methods resolve to the payload directly, but two families wrap it. The retu
 
 **1. Tier-gated endpoints return a preview envelope.** The payload is in `data`, and `isPreview` tells you whether it was truncated for your tier. `totalCount` carries the untruncated size whenever the server knows it: on a truncated response, so you can render "showing N of M", and on a paged endpoint such as `politicians.getActivity`, where it is the full match count on every tier including PRO. A missing `totalCount` means "count `data` yourself", never "zero results".
 
-Affected: `institutional.getFlows` / `getHolders` / `getActivists`, and all five `insights` methods.
+Affected: every method whose declared return type is `PreviewResponse<T>`. A test keeps this table in step with the source, so it is the full list rather than a sample.
+
+| Namespace | Methods |
+|-----------|---------|
+| `analyst` | `consensus` `actions` `estimates` `marketActivity` `coverage` `profile` `calls` |
+| `calendar` | `getEarnings` |
+| `earnings` | `getSummaries` `getRecent` |
+| `etfs` | `analystAggregate` `insiderAggregate` `sentimentAggregate` |
+| `insider` | `getActivity` `getTrades` `getClusterBuys` |
+| `insights` | `stock` `stockRange` `market` `latest` `user` |
+| `institutional` | `getFlows` `getHolders` `getActivists` |
+| `options` | `getOverview` |
+| `politicians` | `getActivity` `getFilings` `getMembers` `getMember` |
+| `stocks` | `getSentiment` `getKpis` `getOptionsSummary` `getOptionsHistory` |
+
+The envelope itself is always an object, so test the payload rather than the response. Two of these declare a `data` that can be null: `stocks.getOptionsSummary`, for a ticker outside the covered options universe, and `options.getOverview`, before its first nightly build. Everywhere else `data` is an array or an object.
 
 ```typescript
 const flows = await client.institutional.getFlows();
@@ -241,6 +256,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
@@ -454,11 +490,11 @@ client.stocks.getOptionsHistory("NVDA", { window: "2y" })  // That name's daily
 
 The radar carries two separately-ranked boards: `data.rows` for stocks and `data.etfRows` for ETFs. Keep them apart. Every reading behind a row's `interestScore` is a percentile of that ticker's own trailing history, so a ranking built across both boards compares numbers measured against different baselines. The aggregates split the same way, with the `etf`-prefixed fields describing the ETF board alone.
 
-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.
+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 inside the usual envelope, so the check is `result.data === null`: the response object itself is always truthy, and a bare `if (summary === null)` never fires. `getOptionsHistory` reports it as an empty `series` instead, so check the array's length 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).
+Where a stock ranks against the other stocks rated that day, as a score, a letter and a percentile, plus the seven 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");
@@ -477,7 +513,7 @@ if (rating.rated) {
 
 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`.
+`dimensions` always holds all seven 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`.
 

package/dist/cli.cjs

@@ -1324,7 +1324,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.52.0";
+var VERSION = "0.54.0";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -1507,7 +1507,14 @@ var Documents = class {
   async getStories(options) {
     return this.client.get("/api/v1/documents/stories", options);
   }
-  /** Get full story detail by cluster ID. */
+  /**
+   * Get full story detail by cluster ID.
+   *
+   * Deliberately untyped: narrow it yourself. The response carries `storySource` and
+   * `isLive` alongside the story body, plus a `timeline` array of dated updates,
+   * newest first and empty when the story has none. {@link StoryTimelineEntry} is
+   * exported for that array.
+   */
   async getStoryDetail(clusterId) {
     return this.client.get(`/api/v1/documents/stories/${encodeURIComponent(clusterId)}`);
   }
@@ -3445,6 +3452,7 @@ var optionsCommand = {
         kind: "facts",
         items: fields(
           field("ATM IV", fixed(latest.atmIv, 4)),
+          field("Exp move 1d", fixed(latest.expectedMove1d, 4)),
           field("Skew 25d", signed(latest.skew25d, 4)),
           field("Call vol", humanize(latest.callVol, 1)),
           field("Put vol", humanize(latest.putVol, 1)),

package/dist/index.cjs

@@ -255,7 +255,14 @@ var Documents = class {
   async getStories(options) {
     return this.client.get("/api/v1/documents/stories", options);
   }
-  /** Get full story detail by cluster ID. */
+  /**
+   * Get full story detail by cluster ID.
+   *
+   * Deliberately untyped: narrow it yourself. The response carries `storySource` and
+   * `isLive` alongside the story body, plus a `timeline` array of dated updates,
+   * newest first and empty when the story has none. {@link StoryTimelineEntry} is
+   * exported for that array.
+   */
   async getStoryDetail(clusterId) {
     return this.client.get(`/api/v1/documents/stories/${encodeURIComponent(clusterId)}`);
   }
@@ -1242,7 +1249,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.52.0";
+var VERSION = "0.54.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";