sentisense 0.31.0 → 0.34.0

package/README.md

@@ -16,7 +16,7 @@ npm install sentisense
 ```typescript
 import SentiSense from "sentisense";
 
-const client = new SentiSense({ apiKey: "ss_live_YOUR_KEY" });
+const client = new SentiSense({ apiKey: process.env.SENTISENSE_API_KEY });
 
 const price = await client.stocks.getPrice("AAPL");
 console.log(price.currentPrice);
@@ -40,8 +40,11 @@ Most methods resolve to the payload directly, but two families wrap it. The retu
 describe the wrapper, so `.data` / `.documents` type-check natively, no cast.
 
 **1. Tier-gated endpoints return a preview envelope.** The payload is in `data`, and
-`isPreview` tells you whether it was truncated for your tier. On a truncated response
-`totalCount` carries the untruncated size, so you can render "showing N of M".
+`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.
@@ -125,6 +128,98 @@ client.institutional.getHolders("AAPL", "2025-02-14")
 client.institutional.getActivists("2025-02-14")
 ```
 
+#### 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 |
+|--------|--------|
+| `limit` | Maximum rows to return. Must be >= 1; values above 1000 are capped server-side. Omit for the full list. |
+| `offset` | Row offset to start from. Server default is 0. Requires `limit`. |
+| `sortBy` | `"shares"` (server default), `"valueUsd"`, or `"sharesChangePct"`. Requires `limit`. |
+| `sortDir` | `"desc"` (server default) or `"asc"`. Requires `limit`. |
+
+`limit` is the switch for the whole set. Send `offset`, `sortBy`, or `sortDir` without it
+and the server ignores them, returning the full unsorted list with a 200 and no warning.
+
+```typescript
+import SentiSense from "sentisense";
+
+const client = new SentiSense({ apiKey: process.env.SENTISENSE_API_KEY });
+
+// Top 10 holders by position value, largest first
+const top = await client.institutional.getHolders("AAPL", "2026-03-31", {
+  limit: 10,
+  sortBy: "valueUsd",
+  sortDir: "desc",
+});
+for (const holder of top.data.holders) {
+  console.log(holder.filerName, holder.valueUsd);
+}
+
+// Walk the list a page at a time
+const page = await client.institutional.getHolders("AAPL", "2026-03-31", {
+  limit: 100,
+  offset: 100,
+});
+console.log(`${page.data.holders.length} rows of ${page.data.holderCount}`);
+```
+
+A response to a request carrying `limit` also has three fields the unbounded response does
+not: `returnedCount` (rows on this page, smaller than your `limit` on the last one),
+`offset` (echoed back), and `notableChanges`, a ticker-wide summary of the quarter's biggest
+position moves so you do not have to scan every page to find them.
+
+```typescript
+const page = await client.institutional.getHolders("AAPL", "2026-03-31", { limit: 100 });
+console.log(`${page.data.returnedCount} of ${page.data.holderCount} holders`);
+for (const mover of page.data.notableChanges?.top ?? []) {
+  console.log(mover.filerName, mover.changeType, mover.sharesChangePct);
+}
+```
+
+Each holder row also carries `entitySlug`, which you can hand straight to
+`institutional.getInstitutionDetail()`, and `cikCount` when the row rolls up several SEC
+filers under one manager. Both are null for filers we have not matched to an institution
+page, so check before building a link.
+
+### Congressional Trading
+
+```typescript
+client.politicians.getActivity({ lookbackDays: 90 })  // Market-wide STOCK Act feed
+client.politicians.getFilings("NVDA")                 // Trades in one stock
+client.politicians.getMembers()                       // Tracked members + trade stats
+client.politicians.getMember("nancy-pelosi")          // One member's profile and trades
+```
+
+#### Paging the activity feed
+
+A 90-day window is routinely well over a thousand disclosures, and without `limit` the
+server returns the first 200 with nothing in the payload to say it stopped. `totalCount` on
+the envelope is the real size on every tier, so size the walk from that rather than from
+`data.length`.
+
+| Option | Values |
+|--------|--------|
+| `lookbackDays` | Days to look back (1-365). Defaults to 90. |
+| `limit` | Rows to return. Must be >= 1; anything above 500 is capped at 500. Omit for the default 200. |
+| `offset` | Row offset to start from. Defaults to 0. Works with or without `limit`. |
+
+```typescript
+const first = await client.politicians.getActivity({ limit: 100 });
+console.log(`${first.data.length} of ${first.totalCount} disclosures`);
+
+for (let offset = 100; offset < (first.totalCount ?? 0); offset += 100) {
+  const page = await client.politicians.getActivity({ limit: 100, offset });
+  for (const trade of page.data) {
+    console.log(trade.politicianName, trade.ticker, trade.transactionType);
+  }
+}
+```
+
 ### Entity Metrics
 
 ```typescript
@@ -215,12 +310,16 @@ All errors extend `SentiSenseError` and include `status`, `code`, and `message`
 
 ```typescript
 const client = new SentiSense({
-  apiKey: "ss_live_YOUR_KEY",  // Get yours at app.sentisense.ai/settings/developer
-  baseUrl: "https://...",      // Default: https://app.sentisense.ai
-  timeout: 30000,              // Default: 30s (in milliseconds)
+  apiKey: process.env.SENTISENSE_API_KEY,  // Get yours at app.sentisense.ai/settings/developer
+  baseUrl: "https://...",                  // Default: https://app.sentisense.ai
+  timeout: 30000,                          // Default: 30s (in milliseconds)
+  maxRetries: 3,                           // Default: 3
 });
 ```
 
+Keep the key in the environment rather than in source. Committing a literal key leaks it
+into git history and into every registry security scan that reads your repo.
+
 ## Get an API Key
 
 Generate your API key from the [Developer Console](https://app.sentisense.ai/settings/developer).

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   APIError: () => APIError,
   AuthenticationError: () => AuthenticationError,
+  DeepHistoryUnavailableError: () => DeepHistoryUnavailableError,
   NotFoundError: () => NotFoundError,
   RateLimitError: () => RateLimitError,
   SentiSense: () => SentiSense,
@@ -52,6 +53,13 @@ var NotFoundError = class extends SentiSenseError {
     this.name = "NotFoundError";
   }
 };
+var DeepHistoryUnavailableError = class extends SentiSenseError {
+  constructor(message, retryAfter) {
+    super(message, 202);
+    this.name = "DeepHistoryUnavailableError";
+    this.retryAfter = retryAfter;
+  }
+};
 var RateLimitError = class extends SentiSenseError {
   constructor(message, code, retryAfter) {
     super(message, 429, code);
@@ -185,7 +193,8 @@ var EntityMetrics = class {
   /**
    * Get time-series metric data for an entity using the v2 Serving Metrics API.
    *
-   * @param symbol   Ticker symbol (e.g. "AAPL") — the backend resolves the entity.
+   * @param symbol   Ticker symbol (e.g. "AAPL") or entity urlSlug (e.g. "Nancy-Pelosi",
+   *                 case-insensitive; discover slugs via stocks.getEntities()).
    * @param options  Metric type and optional time range / resolution.
    */
   async getMetrics(symbol, options = {}) {
@@ -202,7 +211,7 @@ var EntityMetrics = class {
   /**
    * Get distribution data for a metric, broken down by a dimension (default: source).
    *
-   * @param symbol     Ticker symbol (e.g. "AAPL").
+   * @param symbol     Ticker symbol (e.g. "AAPL") or entity urlSlug.
    * @param metricType The metric to break down (e.g. "mentions", "sentiment").
    * @param options    Optional dimension parameter.
    */
@@ -313,6 +322,19 @@ var Politicians = class {
    *
    * PRO-gated. Free/unauthenticated users receive a preview (top 5 trades)
    * with `isPreview: true` in the response.
+   *
+   * The feed is longer than one response: a default 90-day window is routinely well over a
+   * thousand disclosures, and without `limit` the server sends the first 200 with no marker
+   * that it stopped. `totalCount` on the envelope is the real size on every tier, so page
+   * with `limit` and `offset` rather than reading `data.length` as the total.
+   *
+   * ```typescript
+   * const first = await client.politicians.getActivity({ limit: 100 });
+   * for (let offset = 100; offset < first.totalCount!; offset += 100) {
+   *   const page = await client.politicians.getActivity({ limit: 100, offset });
+   *   // ... page.data
+   * }
+   * ```
    */
   async getActivity(options) {
     return this.client.get("/api/v1/politicians/activity", options);
@@ -453,11 +475,20 @@ var Institutional = class {
    * are two levels down: `(await getHolders(t, d)).data.holders`, alongside ticker-level
    * totals like `holderCount`. Free callers get a truncated `holders` array with
    * `isPreview: true`.
+   *
+   * A widely held ticker returns thousands of rows: a megacap quarter is about
+   * 6,000 holders and 1.5 MB. Pass `limit` unless you really want all of them.
+   * Omitting `options` sends the original unbounded request.
+   *
+   * `limit` is the switch for the whole option set. With it, the response also carries
+   * `returnedCount`, `offset`, and a `notableChanges` summary, so you can walk the list
+   * without re-counting it. Without it, `offset` / `sortBy` / `sortDir` are ignored by the
+   * server and you get the full unsorted list back with a 200.
    */
-  async getHolders(ticker, reportDate) {
+  async getHolders(ticker, reportDate, options) {
     return this.client.get(
       `/api/v1/institutional/holders/${encodeURIComponent(ticker)}`,
-      { reportDate }
+      { reportDate, ...options }
     );
   }
   /**
@@ -597,6 +628,22 @@ var Stocks = class {
   async getProfile(ticker, options) {
     return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/profile`, options);
   }
+  /**
+   * Get the headline sentiment picture for a stock in one call.
+   *
+   * Returns the SentiSense Score with its 30-day regime, mention volume and social
+   * dominance, per-source tone in `bySource`, plus related tickers, story drivers, a
+   * narrative and an FAQ. Available in full on every API-key tier.
+   *
+   * Use `entityMetrics.getMetrics(ticker, "sentiment", ...)` instead when you need a time
+   * series over a specific window rather than the headline read. Returns 404 for tickers
+   * with no sentiment coverage.
+   */
+  async getSentiment(ticker) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker)}/sentiment`
+    );
+  }
   /** Get related KB entities (people, products, partners). */
   async getEntities(ticker) {
     return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/entities`);
@@ -630,7 +677,13 @@ var Stocks = class {
   async getMarketStatus() {
     return this.client.get("/api/v1/stocks/market-status");
   }
-  /** Get financial statement data. */
+  /**
+   * Get financial statement data for one reporting period: income statement, balance sheet,
+   * and cash flow, including `capitalExpenditure` and `freeCashFlow`.
+   *
+   * Capital expenditure is signed as filed, so normally negative. See {@link Fundamentals}
+   * for the free-cash-flow relationship and when it is `null`.
+   */
   async getFundamentals(ticker, options) {
     return this.client.get("/api/v1/stocks/fundamentals", { ticker, ...options });
   }
@@ -689,8 +742,8 @@ var Stocks = class {
     return this.client.get("/api/v1/stocks/with-kpis");
   }
   /**
-   * List the KPI metadata tuples available for a ticker — `id, name, category,
-   * chartType` — without paying the cost of the full series payload. Mirrors
+   * List the KPI metadata tuples available for a ticker (`id, name, category,
+   * chartType`) without paying the cost of the full series payload. Mirrors
    * the `/api/v1/insights/stock/{ticker}/types` precedent.
    *
    * Auth: API key required, no quota cost. 404 if the ticker has no curated KPIs.
@@ -708,7 +761,7 @@ var Trackers = class {
     this.client = client;
   }
   /**
-   * List every publicly-visible tracker — id, display name, category,
+   * List every publicly-visible tracker: id, display name, category,
    * one-line description, and the methodology anchor to link out to.
    */
   async list() {
@@ -722,8 +775,8 @@ var Trackers = class {
    * `"choropleth"` they live at `data.geo[]`; etc. Dispatch on `viewType`
    * in your renderer.
    *
-   * @param trackerId — slug from {@link list}, e.g. `"institution-concentration"`.
-   * @param params — provider-specific query params (e.g. `{ scope: "us" }` for
+   * @param trackerId slug from {@link list}, e.g. `"institution-concentration"`.
+   * @param params provider-specific query params (e.g. `{ scope: "us" }` for
    *   geographically-scoped trackers like hantavirus). Unknown keys are ignored.
    */
   async get(trackerId, params) {
@@ -732,7 +785,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.31.0";
+var VERSION = "0.34.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -740,6 +793,19 @@ var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_MAX_RETRIES = 3;
 var BASE_DELAY_MS = 1e3;
 var MAX_DELAY_MS = 6e4;
+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;
+function clampRetryAfter(raw, maxWaitS) {
+  if (!raw) return void 0;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return void 0;
+  return Math.min(Math.max(0.5, parsed), maxWaitS);
+}
+function retryAfterSeconds(raw, defaultS, maxWaitS) {
+  return clampRetryAfter(raw, maxWaitS) ?? defaultS;
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -790,12 +856,34 @@ var SentiSense = class {
           headers,
           signal: controller.signal
         });
+        if (response.status === 202) {
+          const waitSeconds = retryAfterSeconds(
+            response.headers.get("Retry-After"),
+            DEEP_HISTORY_FALLBACK_WAIT_S,
+            MAX_DEEP_HISTORY_WAIT_S
+          );
+          try {
+            await response.body?.cancel();
+          } catch {
+          }
+          if (attempt < this.maxRetries) {
+            delayMs = waitSeconds * 1e3;
+            continue;
+          }
+          throw new DeepHistoryUnavailableError(
+            "Deep history is still being assembled. Retry in a few seconds.",
+            waitSeconds
+          );
+        }
         if (!response.ok) {
           const isRetryable = response.status === 429 || response.status >= 500;
           if (isRetryable && attempt < this.maxRetries) {
             if (response.status === 429) {
-              const ra = response.headers.get("Retry-After");
-              delayMs = (ra ? parseInt(ra, 10) : 60) * 1e3;
+              delayMs = retryAfterSeconds(
+                response.headers.get("Retry-After"),
+                RATE_LIMIT_FALLBACK_WAIT_S,
+                MAX_RATE_LIMIT_WAIT_S
+              ) * 1e3;
             } else {
               delayMs = Math.min(BASE_DELAY_MS * Math.pow(2, attempt), MAX_DELAY_MS) + Math.random() * 1e3;
             }
@@ -886,8 +974,11 @@ var SentiSense = class {
       case 404:
         throw new NotFoundError(message, code);
       case 429: {
-        const ra = response.headers.get("Retry-After");
-        throw new RateLimitError(message, code, ra ? parseInt(ra, 10) : void 0);
+        const retryAfter = clampRetryAfter(
+          response.headers.get("Retry-After"),
+          MAX_RATE_LIMIT_WAIT_S
+        );
+        throw new RateLimitError(message, code, retryAfter);
       }
       default:
         throw new APIError(message, response.status, code);
@@ -898,6 +989,7 @@ var SentiSense = class {
 0 && (module.exports = {
   APIError,
   AuthenticationError,
+  DeepHistoryUnavailableError,
   NotFoundError,
   RateLimitError,
   SentiSense,