sentisense 0.33.0 → 0.35.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

@@ -322,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);
@@ -462,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 }
     );
   }
   /**
@@ -531,7 +553,11 @@ var MarketMoodResource = class {
     return this.client.get("/api/v2/market-mood");
   }
   // TODO: accept a `days` param to control history length (the endpoint supports ?days=N).
-  // TODO: add a sibling `indexes` resource for /api/v1/indexes/{id} (+ /history), e.g. fed-sentiment.
+  //
+  // Market Mood is also reachable through `client.indexes`, which serves it in the shared
+  // index envelope alongside fed-sentiment and ai-sentiment. Use this resource when you want
+  // the phase band, weekly change, per-signal breakdown and per-sector map; use `indexes`
+  // when you want every index to answer the same shape. Both report the same headline number.
 };
 
 // src/resources/marketSummary.ts
@@ -626,9 +652,17 @@ var Stocks = class {
   async getEntities(ticker) {
     return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/entities`);
   }
-  /** Get AI-generated stock analysis report. Requires PRO tier. */
+  /**
+   * Get AI-generated stock analysis report. Requires PRO tier.
+   *
+   * `depth: "deep"` returns the full curated report and consumes one report view on
+   * metered tiers; the default `"basic"` returns the one-paragraph summary.
+   *
+   * The deprecated `forceRefresh` option is accepted and discarded, not forwarded.
+   */
   async getAISummary(ticker, options) {
-    return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/ai-summary`, options);
+    const { forceRefresh: _forceRefresh, ...params } = options ?? {};
+    return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/ai-summary`, params);
   }
   /** Get sentiment/mention metrics breakdown by entity. */
   async getMetricsBreakdown(ticker, metricType, options) {
@@ -720,8 +754,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.
@@ -733,13 +767,60 @@ var Stocks = class {
   }
 };
 
+// src/resources/indexes.ts
+var Indexes = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List every index the platform publishes: id, display name, one-line
+   * description, the scale it lives on, its access tier, and where its richest
+   * view lives.
+   *
+   * Iterate this rather than hardcoding ids. Every `indexId` it advertises
+   * resolves on {@link get} and {@link history}.
+   */
+  async list() {
+    return this.client.get("/api/v1/indexes");
+  }
+  /**
+   * Latest reading for one index.
+   *
+   * Check `constituents` for `null` before iterating: it is `null` on a
+   * composite index like `market-mood`, which has no constituents by
+   * construction. For Market Mood this is the narrowed view; the phase band,
+   * weekly change, per-signal breakdown and per-sector map live on
+   * `client.marketMood.get()`, and both report the same headline number.
+   *
+   * @param indexId slug from {@link list}, e.g. `"fed-sentiment"`.
+   */
+  async get(indexId) {
+    return this.client.get(`/api/v1/indexes/${indexId}`);
+  }
+  /**
+   * Historical scalar series for one index, for charting.
+   *
+   * Thin or low-coverage buckets are withheld, so the series can be shorter
+   * than `days` and can contain gaps. Plot against each point's `date`.
+   *
+   * @param indexId slug from {@link list}.
+   * @param days days of history to return. Defaults to the API's own 180.
+   */
+  async history(indexId, days) {
+    return this.client.get(
+      `/api/v1/indexes/${indexId}/history`,
+      days === void 0 ? void 0 : { days }
+    );
+  }
+};
+
 // src/resources/trackers.ts
 var Trackers = class {
   constructor(client) {
     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() {
@@ -753,8 +834,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) {
@@ -763,7 +844,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.33.0";
+var VERSION = "0.35.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -775,12 +856,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;
-function retryAfterSeconds(raw, defaultS, maxWaitS) {
-  if (!raw) return defaultS;
+function clampRetryAfter(raw, maxWaitS) {
+  if (!raw) return void 0;
   const parsed = Number(raw);
-  if (!Number.isFinite(parsed)) return defaultS;
+  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));
 }
@@ -802,6 +886,7 @@ var SentiSense = class {
     this.marketMood = new MarketMoodResource(this);
     this.marketSummary = new MarketSummaryResource(this);
     this.kb = new KB(this);
+    this.indexes = new Indexes(this);
     this.trackers = new Trackers(this);
     this.calendar = new Calendar(this);
   }
@@ -949,8 +1034,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);