sentisense 0.62.0 → 0.63.1

package/README.md

@@ -157,7 +157,7 @@ const client = new SentiSense({
 | `apiKey` | none | Sent as `X-SentiSense-API-Key`. Required by every endpoint. |
 | `baseUrl` | `https://app.sentisense.ai` | Override for a non-production host. |
 | `timeout` | `30000` | Per-request timeout in milliseconds. |
-| `maxRetries` | `3` | Retries on 429 and 5xx, honouring `Retry-After`. Set `0` to fail fast. |
+| `maxRetries` | `3` | Retries the per-minute 429 and 5xx, honouring `Retry-After`. The monthly-allowance 429 is never retried. Set `0` to fail fast. |
 | `userAgentSuffix` | none | Appended to the User-Agent, after `sentisense-node/{version}`. |
 
 `userAgentSuffix` is how you say what is calling on top of the SDK, so your traffic is legible in your own logs and in ours. A tool name and version works (`"my-bot/1.4"`), optionally with an agent label (`"my-bot/1.4 agent/research-desk"`). Node only, since browsers set the header themselves. Newlines are collapsed and an empty value is ignored.
@@ -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).
@@ -616,7 +636,12 @@ try {
   if (error instanceof AuthenticationError) {
     // 401 or 403: invalid/missing API key or insufficient tier
   } else if (error instanceof RateLimitError) {
-    // 429: quota exceeded
+    if (error.code === "quota_exceeded") {
+      // 429: monthly allowance used up. Not retried; error.message says when it resets.
+    } else {
+      // 429: per-minute limit ("rate_limit_exceeded"), thrown once retries are used up.
+      // error.retryAfter is the server's wait in seconds.
+    }
   }
 }
 ```
@@ -625,7 +650,7 @@ try {
 |------------|-------------|------|
 | `AuthenticationError` | 401, 403 | Invalid API key or insufficient tier |
 | `NotFoundError` | 404 | Resource not found |
-| `RateLimitError` | 429 | Quota exceeded |
+| `RateLimitError` | 429 | Per-minute limit (`code: "rate_limit_exceeded"`, retried first) or monthly allowance used up (`code: "quota_exceeded"`, thrown immediately) |
 | `APIError` | Other 4xx/5xx | General API error |
 
 All errors extend `SentiSenseError` and include `status`, `code`, and `message` properties.

package/dist/cli.cjs

@@ -66,10 +66,12 @@ var EXIT_TABLE = [
   [EXIT.USAGE, "bad usage, caught before any request was sent"],
   [EXIT.AUTH, "missing or rejected API key"],
   [EXIT.NOT_FOUND, "no data for that symbol or identifier"],
-  [EXIT.RATE_LIMIT, "rate limited"],
+  [EXIT.RATE_LIMIT, "rate limited, or the monthly request allowance is used up"],
   [EXIT.NETWORK, "network failure or timeout"]
 ];
 var KEY_URL = "https://app.sentisense.ai/get-api-key";
+var PRICING_URL = "https://app.sentisense.ai/pricing";
+var QUOTA_EXCEEDED = "quota_exceeded";
 var CliUsageError = class extends Error {
   constructor(message, hint) {
     super(message);
@@ -158,6 +160,15 @@ function classify(error, command) {
     };
   }
   if (error instanceof RateLimitError) {
+    if (error.code === QUOTA_EXCEEDED) {
+      return {
+        exitCode: EXIT.RATE_LIMIT,
+        lines: [
+          `error: monthly request allowance used up: ${error.message}`,
+          `next: the free monthly allowance resets at the start of next month, so running it again before then will not help. PRO has no monthly cap: ${PRICING_URL}`
+        ]
+      };
+    }
     const wait = error.retryAfter ? Math.ceil(error.retryAfter) : 60;
     return {
       exitCode: EXIT.RATE_LIMIT,
@@ -1345,7 +1356,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.62.0";
+var VERSION = "0.63.1";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -1604,9 +1615,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 +2094,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 +2370,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(
@@ -2661,6 +2679,15 @@ var DEEP_HISTORY_FALLBACK_WAIT_S = 3;
 var MAX_DEEP_HISTORY_WAIT_S = 30;
 var MAX_RATE_LIMIT_WAIT_S = 120;
 var RATE_LIMIT_FALLBACK_WAIT_S = 60;
+var QUOTA_EXCEEDED_CODE = "quota_exceeded";
+async function isQuotaExceeded(response) {
+  try {
+    const body = await response.clone().json();
+    return body?.error === QUOTA_EXCEEDED_CODE;
+  } catch {
+    return false;
+  }
+}
 function clampRetryAfter(raw, maxWaitS) {
   if (!raw) return void 0;
   const parsed = Number(raw);
@@ -2746,6 +2773,9 @@ var SentiSense = class {
           );
         }
         if (!response.ok) {
+          if (response.status === 429 && await isQuotaExceeded(response)) {
+            await this.handleErrorResponse(response);
+          }
           const isRetryable = response.status === 429 || response.status >= 500;
           if (isRetryable && attempt < this.maxRetries) {
             if (response.status === 429 || response.status === 503) {

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.1";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -1399,6 +1406,15 @@ var DEEP_HISTORY_FALLBACK_WAIT_S = 3;
 var MAX_DEEP_HISTORY_WAIT_S = 30;
 var MAX_RATE_LIMIT_WAIT_S = 120;
 var RATE_LIMIT_FALLBACK_WAIT_S = 60;
+var QUOTA_EXCEEDED_CODE = "quota_exceeded";
+async function isQuotaExceeded(response) {
+  try {
+    const body = await response.clone().json();
+    return body?.error === QUOTA_EXCEEDED_CODE;
+  } catch {
+    return false;
+  }
+}
 function clampRetryAfter(raw, maxWaitS) {
   if (!raw) return void 0;
   const parsed = Number(raw);
@@ -1484,6 +1500,9 @@ var SentiSense = class {
           );
         }
         if (!response.ok) {
+          if (response.status === 429 && await isQuotaExceeded(response)) {
+            await this.handleErrorResponse(response);
+          }
           const isRetryable = response.status === 429 || response.status >= 500;
           if (isRetryable && attempt < this.maxRetries) {
             if (response.status === 429 || response.status === 503) {