sentisense 0.62.0 → 0.63.0

package/README.md

@@ -252,6 +252,8 @@ Price fields carry `priceAsOf` (Unix milliseconds) for the age of the market dat
 
 Short interest and short volume come back newest first, and an unknown ticker returns an empty `dataPoints` array rather than an error. Every identifier in `getGraph` is a slug, the same handle the metric and document endpoints take. An ETF symbol is refused by `getQuote` with an `APIError` whose `code` is `"ticker_is_etf"`; use `etfs.quote()` for funds.
 
+Product nodes (`type === "PRODUCT_OR_SERVICE"`) in `stocks.getGraph` now carry optional `category` when known. Other nodes and products without a category omit it.
+
 ### Documents & news
 
 ```typescript
@@ -292,6 +294,18 @@ client.institutional.getHolders("AAPL", "2025-02-14")
 client.institutional.getActivists("2025-02-14")
 ```
 
+`positionsHeld` on an institution detail counts the full portfolio's held positions:
+`max(0, holdingsCount - soldOutPositions)`, even when the holdings list is truncated.
+`getInstitutionDetail` keeps its `Promise<unknown>` signature. The exported all-optional
+`InstitutionDetail` type is available for callers who want to opt in:
+
+```typescript
+import type { InstitutionDetail, PreviewResponse } from "sentisense";
+
+const detail = await client.institutional.getInstitutionDetail("1067983") as PreviewResponse<InstitutionDetail>;
+console.log(detail.data.positionsHeld); // undefined when an older response omits it
+```
+
 **Paging the holder list.** A widely held ticker returns thousands of rows: a megacap quarter is roughly 6,000 holders and 1.5 MB on the wire. Pass `limit` unless you really want the whole list; omitting the options object sends the original unbounded request, so existing code keeps working.
 
 | Option | Values |
@@ -417,6 +431,8 @@ Two shapes to read rather than assume. A firm can appear with `noteCount: 0`, a
 
 `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.
 
+Surprise rows now carry optional `surprisePct`, the signed true percent rounded half-up to two decimals: `(actualEps - estimateEps) * 100 / abs(estimateEps)`. It is `null` when either EPS is missing or the estimate is zero, and `undefined` on older responses. The existing `surprisePercent` fraction is unchanged (`0.03` means about 3%).
+
 ### 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. Summaries, recent reports, statistics, and rankings return the preview envelope; per-ticker reactions return a direct payload.
@@ -451,6 +467,8 @@ if (quarter) {
 
 The forward-looking half of the family is `client.calendar.getEarnings()`, which covers scheduled dates and consensus EPS rather than results.
 
+`earnings.getSummaries` exposes optional `totalCount` on the envelope on both PRO and FREE. It counts indexed quarters; returned rows can be fewer because of `limit` or an unavailable body. Older responses without the count still read as `undefined`.
+
 ### Company KPIs (PRO)
 
 ```typescript
@@ -511,6 +529,8 @@ During the trading session the dossier and the radar also carry a few intraday f
 
 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.
 
+On a delisted symbol, the options summary carries `listingStatus === "DELISTED"` and, when known, `delistedDate` (YYYY-MM-DD). This marks a frozen last dossier, so read `asOf` before treating it as current. Listed and pending symbols omit both fields.
+
 ### 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).

package/dist/cli.cjs

@@ -1345,7 +1345,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.62.0";
+var VERSION = "0.63.0";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -1604,9 +1604,11 @@ var Earnings = class {
    * management phrased it, and a summary of the earnings call.
    *
    * Branch on `isPreview`: a PRO key receives every hydrated quarter in full, a
-   * FREE key receives the latest quarter shaped rather than truncated, plus
-   * `totalCount`. {@link EarningsQuarter} documents which fields each tier
-   * carries.
+   * FREE key receives the latest quarter shaped rather than truncated.
+   * `totalCount` on the envelope counts indexed quarters on both tiers. The
+   * returned array can be shorter when a body is unavailable or limit cuts it.
+   * Older responses may omit the count. {@link EarningsQuarter} documents
+   * which fields each tier carries.
    *
    * A quarter typically appears within 48 hours of the company reporting, and
    * the call summary can arrive after the press-release content for the same
@@ -2081,6 +2083,10 @@ var Institutional = class {
    * Resolved by URL slug (e.g. `Berkshire-Hathaway`) or numeric SEC CIK.
    * Free users receive the profile and top 10 holdings; PRO users receive the
    * full holdings array. Returns 404 if the slug or CIK is unknown.
+   *
+   * The signature remains unknown for compatibility. Opt in to the exported
+   * PreviewResponse<InstitutionDetail> type to read data.positionsHeld, the full
+   * portfolio count excluding SOLD_OUT rows, even on a truncated holdings list.
    */
   async getInstitutionDetail(slugOrCik) {
     return this.client.get(
@@ -2353,8 +2359,9 @@ var Stocks = class {
    *
    * Every identifier in the response is a slug, the same handle the metric and document
    * endpoints take, so a node can be passed straight to them. `depth` is 1 (default) or 2,
-   * `cap` limits the node count (1 to 200, default 75); out-of-range values are rejected
-   * with a 400. A ticker with no graph returns a `NotFoundError`.
+   * `cap` limits the number of non-root nodes (1 to 200, default 75); the root is always
+   * included in addition. Out-of-range values are rejected with a 400. A ticker with no
+   * graph returns a `NotFoundError`.
    */
   async getGraph(ticker, options) {
     return this.client.get(

package/dist/index.cjs

@@ -339,9 +339,11 @@ var Earnings = class {
    * management phrased it, and a summary of the earnings call.
    *
    * Branch on `isPreview`: a PRO key receives every hydrated quarter in full, a
-   * FREE key receives the latest quarter shaped rather than truncated, plus
-   * `totalCount`. {@link EarningsQuarter} documents which fields each tier
-   * carries.
+   * FREE key receives the latest quarter shaped rather than truncated.
+   * `totalCount` on the envelope counts indexed quarters on both tiers. The
+   * returned array can be shorter when a body is unavailable or limit cuts it.
+   * Older responses may omit the count. {@link EarningsQuarter} documents
+   * which fields each tier carries.
    *
    * A quarter typically appears within 48 hours of the company reporting, and
    * the call summary can arrive after the press-release content for the same
@@ -816,6 +818,10 @@ var Institutional = class {
    * Resolved by URL slug (e.g. `Berkshire-Hathaway`) or numeric SEC CIK.
    * Free users receive the profile and top 10 holdings; PRO users receive the
    * full holdings array. Returns 404 if the slug or CIK is unknown.
+   *
+   * The signature remains unknown for compatibility. Opt in to the exported
+   * PreviewResponse<InstitutionDetail> type to read data.positionsHeld, the full
+   * portfolio count excluding SOLD_OUT rows, even on a truncated holdings list.
    */
   async getInstitutionDetail(slugOrCik) {
     return this.client.get(
@@ -1088,8 +1094,9 @@ var Stocks = class {
    *
    * Every identifier in the response is a slug, the same handle the metric and document
    * endpoints take, so a node can be passed straight to them. `depth` is 1 (default) or 2,
-   * `cap` limits the node count (1 to 200, default 75); out-of-range values are rejected
-   * with a 400. A ticker with no graph returns a `NotFoundError`.
+   * `cap` limits the number of non-root nodes (1 to 200, default 75); the root is always
+   * included in addition. Out-of-range values are rejected with a 400. A ticker with no
+   * graph returns a `NotFoundError`.
    */
   async getGraph(ticker, options) {
     return this.client.get(
@@ -1387,7 +1394,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.62.0";
+var VERSION = "0.63.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";