sentisense 0.53.0 → 0.55.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` `consensusHistory` `calledIt` `actions` `estimates` `marketActivity` `coverage` `profile` `calls` |
+| `calendar` | `getEarnings` |
+| `earnings` | `getSummaries` `getRecent` `getStatistics` `getRanked` |
+| `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();
@@ -349,6 +364,8 @@ The price target cone (mean, high, low, upside %) and consensus are free for eve
 
 ```typescript
 client.analyst.consensus("AAPL")                        // Price target cone + consensus. Free, full data.
+client.analyst.consensusHistory("AAPL", { limit: 90 })  // Daily history. Free: last 30 days; distribution fields null.
+client.analyst.calledIt("AAPL", { limit: 10 })         // Recorded calls for 20% moves over five sessions. Free: newest move, up to 5 calls, move counts intact.
 client.analyst.actions("AAPL", { lookbackDays: 30 })    // Upgrade/downgrade feed. Free: 3 most recent.
 client.analyst.estimates("AAPL")                        // Forward EPS + surprises. Free: 1 quarter.
 client.analyst.marketActivity({ lookbackDays: 7 })      // Market-wide analyst actions (PRO).
@@ -396,11 +413,14 @@ Two shapes to read rather than assume. A firm can appear with `noteCount: 0`, a
 
 ### 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.
+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.
 
 ```typescript
 client.earnings.getSummaries("AAPL", { limit: 4 })   // Per-quarter analysis, newest first. Free: latest quarter, shaped.
 client.earnings.getRecent({ days: 7, limit: 25 })    // Who reported in the last N days. Full window on every key.
+client.earnings.getReactions("AAPL")                 // Up to twelve measured post-report moves. Full series on every key.
+client.earnings.getStatistics({ window: "week_to_date" }) // Market-wide outcomes, reaction rates, baseline, and coverage.
+client.earnings.getRanked({ reportedDays: 14, upcomingDays: 7 }) // Free: first 3 rows per section. PRO: full ranking.
 ```
 
 ```typescript
@@ -461,7 +481,7 @@ client.entityMetrics.getDistribution("AAPL", "sentiment")
 client.entityMetrics.getDistribution("AAPL", "mentions", { dimension: "source" })
 ```
 
-Available metric types: `mentions`, `sentiment`, `sentisense_score`, `sentisense_rating`, `social_dominance`, `creators`. `sentisense_rating` is the SentiSense Rating score and is a time series only: it has no source breakdown, so `getDistribution` answers with an empty distribution for it.
+Available metric types: `mentions`, `sentiment`, `sentisense_score`, `sentisense_rating`, `social_dominance`, `creators`. `sentisense` is an alias for `sentisense_score`; either spelling returns the same series, and keys are case-insensitive. Responses always name the canonical type, so a `sentisense` request answers with `SENTISENSE_SCORE`. `sentisense_rating` is the SentiSense Rating score and is a time series only: it has no source breakdown, so `getDistribution` answers with an empty distribution for it.
 
 ### Options
 
@@ -475,11 +495,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");
@@ -498,7 +518,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

@@ -36,6 +36,13 @@ var RateLimitError = class extends SentiSenseError {
     this.retryAfter = retryAfter;
   }
 };
+var TemporarilyUnavailableError = class extends SentiSenseError {
+  constructor(message, retryAfter, code) {
+    super(message, 503, code);
+    this.name = "TemporarilyUnavailableError";
+    this.retryAfter = retryAfter;
+  }
+};
 var APIError = class extends SentiSenseError {
   constructor(message, status, code) {
     super(message, status, code);
@@ -1324,7 +1331,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.53.0";
+var VERSION = "0.55.0";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -1340,6 +1347,38 @@ var Analyst = class {
       `/api/v1/analyst/${encodeURIComponent(ticker.toUpperCase())}/consensus`
     );
   }
+  /**
+   * Get daily consensus observations, ordered by `snapshotDate` ascending.
+   * Each row describes the target fields as observed on that date. When
+   * `countsObserved` is `false`, the vendor panel did not come back that day and the
+   * distribution counts are carried forward.
+   *
+   * A PRO key receives the requested window. A FREE key receives the last 30 days;
+   * `targetMedian`, `recommendationMean`, and the five distribution fields are `null`.
+   * The envelope's `totalCount` still sizes the full requested window.
+   */
+  async consensusHistory(ticker, options) {
+    return this.client.get(
+      `/api/v1/analyst/${encodeURIComponent(ticker.toUpperCase())}/consensus/history`,
+      options
+    );
+  }
+  /**
+   * Get factual call history as recorded when a stock moved 20% or more over five
+   * sessions, newest move first by `moveEndDate`.
+   *
+   * PRO receives full moves and calls. FREE receives the newest move with up to five
+   * calls and all move-level counts intact. The envelope's `totalCount` counts all
+   * available moves before the limit. A known stock with no qualifying move returns
+   * an empty `moves` array. Each call includes `analystName`: it is `null`, never
+   * absent, when the publisher named nobody.
+   */
+  async calledIt(ticker, options) {
+    return this.client.get(
+      `/api/v1/analyst/${encodeURIComponent(ticker.toUpperCase())}/called-it`,
+      options
+    );
+  }
   /**
    * Get recent analyst upgrade/downgrade actions for a ticker, newest first.
    * Free users receive the 3 most recent.
@@ -1572,6 +1611,52 @@ var Earnings = class {
   async getRecent(options) {
     return this.client.get("/api/v1/earnings/recent", options);
   }
+  /**
+   * Measured price reactions to a ticker's last earnings reports, newest first.
+   *
+   * Use this after {@link getRecent} when you need one company's realized
+   * post-report history. `client.calendar.getEarnings()` is the forward-looking
+   * schedule instead. This endpoint returns its payload directly, without a
+   * preview envelope, and every API key receives the full series.
+   *
+   * `timing` is always present on each row and can be `null` when the reacting
+   * session was inferred rather than observed.
+   */
+  async getReactions(ticker) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/earnings/reactions`
+    );
+  }
+  /**
+   * Market-wide earnings outcomes and realized reaction statistics.
+   *
+   * Use this for aggregate beat, miss, inline, and post-report move rates.
+   * {@link getRecent} returns individual recent reports, while
+   * `client.calendar.getEarnings()` covers upcoming dates. The response uses
+   * the preview envelope, but every API key receives the full body and
+   * `isPreview` is always `false`.
+   *
+   * `baseline` and `deviation` are omitted for long-span windows, and rates can
+   * be `null` when their denominator is zero.
+   */
+  async getStatistics(options) {
+    return this.client.get("/api/v1/earnings/statistics", options);
+  }
+  /**
+   * Important recently reported and upcoming earnings in one ranking.
+   *
+   * Use this to prioritize a cross-ticker sweep. Follow reported rows with
+   * {@link getReactions} for realized history; use {@link getRecent} for an
+   * unranked recent feed or `client.calendar.getEarnings()` for the broader
+   * forward schedule.
+   *
+   * A PRO key receives the full ranking. A FREE key receives the first three
+   * rows in each section with `totalInWindow` left intact. Optional row fields
+   * are omitted when null, so check them before use.
+   */
+  async getRanked(options) {
+    return this.client.get("/api/v1/earnings/ranked", options);
+  }
 };
 
 // src/resources/entityMetrics.ts
@@ -2300,7 +2385,7 @@ var Stocks = class {
    * the full series. Returns 404 for tickers that do not yet have curated coverage.
    *
    * Coverage today: near-complete for the S&P 500 plus extended universe
-   * (~500 tickers). Use `listKpiCoverage()` to enumerate.
+   * (900+ tickers). Use `listKpiCoverage()` to enumerate.
    */
   async getKpis(ticker) {
     return this.client.get(
@@ -2597,12 +2682,23 @@ var SentiSense = class {
         if (!response.ok) {
           const isRetryable = response.status === 429 || response.status >= 500;
           if (isRetryable && attempt < this.maxRetries) {
-            if (response.status === 429) {
-              delayMs = retryAfterSeconds(
+            if (response.status === 429 || response.status === 503) {
+              const requestedS = retryAfterSeconds(
                 response.headers.get("Retry-After"),
                 RATE_LIMIT_FALLBACK_WAIT_S,
-                MAX_RATE_LIMIT_WAIT_S
-              ) * 1e3;
+                Number.POSITIVE_INFINITY
+              );
+              if (requestedS > MAX_RATE_LIMIT_WAIT_S) {
+                try {
+                  await response.body?.cancel();
+                } catch {
+                }
+                throw new TemporarilyUnavailableError(
+                  `Server asked for a ${Math.round(requestedS)}s wait, longer than this client's ${MAX_RATE_LIMIT_WAIT_S}s budget`,
+                  requestedS
+                );
+              }
+              delayMs = requestedS * 1e3;
             } else {
               delayMs = Math.min(BASE_DELAY_MS * Math.pow(2, attempt), MAX_DELAY_MS) + Math.random() * 1e3;
             }
@@ -3452,6 +3548,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

@@ -27,6 +27,7 @@ __export(index_exports, {
   RateLimitError: () => RateLimitError,
   SentiSense: () => SentiSense,
   SentiSenseError: () => SentiSenseError,
+  TemporarilyUnavailableError: () => TemporarilyUnavailableError,
   VERSION: () => VERSION,
   default: () => SentiSense
 });
@@ -67,6 +68,13 @@ var RateLimitError = class extends SentiSenseError {
     this.retryAfter = retryAfter;
   }
 };
+var TemporarilyUnavailableError = class extends SentiSenseError {
+  constructor(message, retryAfter, code) {
+    super(message, 503, code);
+    this.name = "TemporarilyUnavailableError";
+    this.retryAfter = retryAfter;
+  }
+};
 var APIError = class extends SentiSenseError {
   constructor(message, status, code) {
     super(message, status, code);
@@ -88,6 +96,38 @@ var Analyst = class {
       `/api/v1/analyst/${encodeURIComponent(ticker.toUpperCase())}/consensus`
     );
   }
+  /**
+   * Get daily consensus observations, ordered by `snapshotDate` ascending.
+   * Each row describes the target fields as observed on that date. When
+   * `countsObserved` is `false`, the vendor panel did not come back that day and the
+   * distribution counts are carried forward.
+   *
+   * A PRO key receives the requested window. A FREE key receives the last 30 days;
+   * `targetMedian`, `recommendationMean`, and the five distribution fields are `null`.
+   * The envelope's `totalCount` still sizes the full requested window.
+   */
+  async consensusHistory(ticker, options) {
+    return this.client.get(
+      `/api/v1/analyst/${encodeURIComponent(ticker.toUpperCase())}/consensus/history`,
+      options
+    );
+  }
+  /**
+   * Get factual call history as recorded when a stock moved 20% or more over five
+   * sessions, newest move first by `moveEndDate`.
+   *
+   * PRO receives full moves and calls. FREE receives the newest move with up to five
+   * calls and all move-level counts intact. The envelope's `totalCount` counts all
+   * available moves before the limit. A known stock with no qualifying move returns
+   * an empty `moves` array. Each call includes `analystName`: it is `null`, never
+   * absent, when the publisher named nobody.
+   */
+  async calledIt(ticker, options) {
+    return this.client.get(
+      `/api/v1/analyst/${encodeURIComponent(ticker.toUpperCase())}/called-it`,
+      options
+    );
+  }
   /**
    * Get recent analyst upgrade/downgrade actions for a ticker, newest first.
    * Free users receive the 3 most recent.
@@ -320,6 +360,52 @@ var Earnings = class {
   async getRecent(options) {
     return this.client.get("/api/v1/earnings/recent", options);
   }
+  /**
+   * Measured price reactions to a ticker's last earnings reports, newest first.
+   *
+   * Use this after {@link getRecent} when you need one company's realized
+   * post-report history. `client.calendar.getEarnings()` is the forward-looking
+   * schedule instead. This endpoint returns its payload directly, without a
+   * preview envelope, and every API key receives the full series.
+   *
+   * `timing` is always present on each row and can be `null` when the reacting
+   * session was inferred rather than observed.
+   */
+  async getReactions(ticker) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/earnings/reactions`
+    );
+  }
+  /**
+   * Market-wide earnings outcomes and realized reaction statistics.
+   *
+   * Use this for aggregate beat, miss, inline, and post-report move rates.
+   * {@link getRecent} returns individual recent reports, while
+   * `client.calendar.getEarnings()` covers upcoming dates. The response uses
+   * the preview envelope, but every API key receives the full body and
+   * `isPreview` is always `false`.
+   *
+   * `baseline` and `deviation` are omitted for long-span windows, and rates can
+   * be `null` when their denominator is zero.
+   */
+  async getStatistics(options) {
+    return this.client.get("/api/v1/earnings/statistics", options);
+  }
+  /**
+   * Important recently reported and upcoming earnings in one ranking.
+   *
+   * Use this to prioritize a cross-ticker sweep. Follow reported rows with
+   * {@link getReactions} for realized history; use {@link getRecent} for an
+   * unranked recent feed or `client.calendar.getEarnings()` for the broader
+   * forward schedule.
+   *
+   * A PRO key receives the full ranking. A FREE key receives the first three
+   * rows in each section with `totalInWindow` left intact. Optional row fields
+   * are omitted when null, so check them before use.
+   */
+  async getRanked(options) {
+    return this.client.get("/api/v1/earnings/ranked", options);
+  }
 };
 
 // src/resources/entityMetrics.ts
@@ -1048,7 +1134,7 @@ var Stocks = class {
    * the full series. Returns 404 for tickers that do not yet have curated coverage.
    *
    * Coverage today: near-complete for the S&P 500 plus extended universe
-   * (~500 tickers). Use `listKpiCoverage()` to enumerate.
+   * (900+ tickers). Use `listKpiCoverage()` to enumerate.
    */
   async getKpis(ticker) {
     return this.client.get(
@@ -1249,7 +1335,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.53.0";
+var VERSION = "0.55.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -1348,12 +1434,23 @@ var SentiSense = class {
         if (!response.ok) {
           const isRetryable = response.status === 429 || response.status >= 500;
           if (isRetryable && attempt < this.maxRetries) {
-            if (response.status === 429) {
-              delayMs = retryAfterSeconds(
+            if (response.status === 429 || response.status === 503) {
+              const requestedS = retryAfterSeconds(
                 response.headers.get("Retry-After"),
                 RATE_LIMIT_FALLBACK_WAIT_S,
-                MAX_RATE_LIMIT_WAIT_S
-              ) * 1e3;
+                Number.POSITIVE_INFINITY
+              );
+              if (requestedS > MAX_RATE_LIMIT_WAIT_S) {
+                try {
+                  await response.body?.cancel();
+                } catch {
+                }
+                throw new TemporarilyUnavailableError(
+                  `Server asked for a ${Math.round(requestedS)}s wait, longer than this client's ${MAX_RATE_LIMIT_WAIT_S}s budget`,
+                  requestedS
+                );
+              }
+              delayMs = requestedS * 1e3;
             } else {
               delayMs = Math.min(BASE_DELAY_MS * Math.pow(2, attempt), MAX_DELAY_MS) + Math.random() * 1e3;
             }
@@ -1464,6 +1561,7 @@ var SentiSense = class {
   RateLimitError,
   SentiSense,
   SentiSenseError,
+  TemporarilyUnavailableError,
   VERSION
 });
 //# sourceMappingURL=index.cjs.map