sentisense 0.54.0 → 0.55.0

package/README.md

@@ -174,9 +174,9 @@ Affected: every method whose declared return type is `PreviewResponse<T>`. A tes
 
 | Namespace | Methods |
 |-----------|---------|
-| `analyst` | `consensus` `actions` `estimates` `marketActivity` `coverage` `profile` `calls` |
+| `analyst` | `consensus` `consensusHistory` `calledIt` `actions` `estimates` `marketActivity` `coverage` `profile` `calls` |
 | `calendar` | `getEarnings` |
-| `earnings` | `getSummaries` `getRecent` |
+| `earnings` | `getSummaries` `getRecent` `getStatistics` `getRanked` |
 | `etfs` | `analystAggregate` `insiderAggregate` `sentimentAggregate` |
 | `insider` | `getActivity` `getTrades` `getClusterBuys` |
 | `insights` | `stock` `stockRange` `market` `latest` `user` |
@@ -364,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).
@@ -411,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
@@ -476,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
 

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.54.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;
             }

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.54.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