sentisense 0.28.0 → 0.30.0

package/README.md

@@ -36,13 +36,8 @@ const flows = await client.institutional.getFlows();
 
 ## Response shapes
 
-Most methods resolve to the payload directly, but two families wrap it.
-
-> **Known issue: some declared return types describe the inner payload rather than the
-> wrapper.** For the methods listed below, the runtime value is the wrapper, so reading the
-> declared shape gives you `undefined` even though it compiles. Cast to the wrapper type
-> (each is exported) until the declarations are corrected in a future release. The runtime
-> behavior is stable and is what is documented here.
+Most methods resolve to the payload directly, but two families wrap it. The return types
+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
@@ -52,11 +47,7 @@ Affected: `institutional.getFlows` / `getHolders` / `getActivists`, and all five
 `insights` methods.
 
 ```typescript
-import type { InstitutionalFlows, PreviewResponse, TickerHolders } from "sentisense";
-
-const flows = (await client.institutional.getFlows()) as unknown as
-  PreviewResponse<InstitutionalFlows>;
-
+const flows = await client.institutional.getFlows();
 if (flows.isPreview) {
   console.log(`Preview: ${flows.data.inflows.length} of ${flows.totalCount}`);
 }
@@ -65,10 +56,15 @@ for (const flow of flows.data.inflows) {
 }
 
 // holders nest one level deeper: ticker-level totals plus the rows
-const holders = (await client.institutional.getHolders("AAPL", "2026-06-30")) as unknown as
-  PreviewResponse<TickerHolders>;
+const holders = await client.institutional.getHolders("AAPL", "2026-06-30");
 console.log(`${holders.data.holderCount} holders`);
 const newPositions = holders.data.holders.filter((h) => h.changeType === "NEW");
+
+// insights use the same envelope, wrapping a plain array
+const insights = await client.insights.stock("AAPL");
+for (const insight of insights.data) {
+  console.log(insight.insightText);
+}
 ```
 
 **2. Document endpoints return a search wrapper.** This is not the preview envelope:
@@ -78,11 +74,7 @@ Affected: `documents.getByTicker` / `getByTickerRange` / `getByEntity` / `search
 `getBySource`. Also `stocks.getFundamentalsPeriods`, whose periods are in `periods`.
 
 ```typescript
-import type { DocumentSearchResponse } from "sentisense";
-
-const results = (await client.documents.search("NVDA earnings", { days: 7 })) as unknown as
-  DocumentSearchResponse;
-
+const results = await client.documents.search("NVDA earnings", { days: 7 });
 console.log(`${results.totalCount} matches`);
 for (const doc of results.documents) {
   console.log(doc.url, doc.averageSentiment);
@@ -91,7 +83,12 @@ for (const doc of results.documents) {
 
 Everything else, including `stocks.getPrice()`, `documents.getStories()`,
 `insights.types()` and `institutional.getQuarters()`, resolves to the value itself with no
-wrapper and needs no cast.
+wrapper.
+
+> **Upgrading from 0.28.x or earlier?** These return types were corrected in 0.29.0. If your
+> code read the flat shape (`flows.inflows`, `holders.filter(...)`), it was returning
+> `undefined` / throwing at runtime already; switch to `flows.data.inflows` /
+> `holders.data.holders`. See [CHANGELOG.md](./CHANGELOG.md) for the full mapping.
 
 ## API Reference
 
@@ -151,7 +148,6 @@ Available metric types: `mentions`, `sentiment`, `sentisense`, `social_dominance
 
 ```typescript
 client.kb.getPopularEntities()
-client.kb.getEntity("entity-id")
 client.kb.getAllEntities()
 ```
 

package/dist/index.cjs

@@ -131,29 +131,29 @@ var Documents = class {
   constructor(client) {
     this.client = client;
   }
-  /** Get document metrics for a stock. */
+  /** Get document metrics for a stock. The rows are in `documents`. */
   async getByTicker(ticker, options) {
     return this.client.get(`/api/v1/documents/ticker/${encodeURIComponent(ticker)}`, options);
   }
-  /** Get document metrics for a stock within a date range. */
+  /** Get document metrics for a stock within a date range. The rows are in `documents`. */
   async getByTickerRange(ticker, options) {
     return this.client.get(
       `/api/v1/documents/ticker/${encodeURIComponent(ticker)}/range`,
       options
     );
   }
-  /** Get document metrics for a KB entity. */
+  /** Get document metrics for a KB entity. The rows are in `documents`. */
   async getByEntity(entityId, options) {
     return this.client.get(
       `/api/v1/documents/entity/${encodeURIComponent(entityId)}`,
       options
     );
   }
-  /** Smart search with natural language query parsing. */
+  /** Smart search with natural language query parsing. The rows are in `documents`. */
   async search(query, options) {
     return this.client.get("/api/v1/documents/search", { query, ...options });
   }
-  /** Get latest document metrics from a source type. */
+  /** Get latest document metrics from a source type. The rows are in `documents`. */
   async getBySource(source, options) {
     return this.client.get(
       `/api/v1/documents/source/${encodeURIComponent(source)}`,
@@ -182,7 +182,6 @@ var EntityMetrics = class {
   constructor(client) {
     this.client = client;
   }
-  // ── v2 API methods ──────────────────────────────────────────
   /**
    * Get time-series metric data for an entity using the v2 Serving Metrics API.
    *
@@ -214,61 +213,6 @@ var EntityMetrics = class {
       { dimension }
     );
   }
-  // ── Deprecated v1 methods (kept for backward compatibility) ─
-  /**
-   * @deprecated Use `getMetrics(symbol, { metricType: "mentions" })` instead.
-   */
-  async getMentions(symbol, options) {
-    return this.client.get(
-      `/api/v1/entity-metrics/stocks/${encodeURIComponent(symbol)}/mentions`,
-      options
-    );
-  }
-  /**
-   * @deprecated Use `getDistribution(symbol, "mentions", { dimension: "source" })` instead.
-   */
-  async getMentionCountBySource(symbol, options) {
-    return this.client.get(
-      `/api/v1/entity-metrics/stocks/${encodeURIComponent(symbol)}/mentions/count/by-source`,
-      options
-    );
-  }
-  /**
-   * @deprecated Use `getMetrics(symbol, { metricType: "mentions" })` instead.
-   */
-  async getMentionCount(symbol, options) {
-    return this.client.get(
-      `/api/v1/entity-metrics/stocks/${encodeURIComponent(symbol)}/mentions/count`,
-      options
-    );
-  }
-  /**
-   * @deprecated Use `getMetrics(symbol, { metricType: "sentiment" })` instead.
-   */
-  async getSentiment(symbol, options) {
-    return this.client.get(
-      `/api/v1/entity-metrics/stocks/${encodeURIComponent(symbol)}/sentiment`,
-      options
-    );
-  }
-  /**
-   * @deprecated Use `getDistribution(symbol, "sentiment", { dimension: "source" })` instead.
-   */
-  async getSentimentBySource(symbol, options) {
-    return this.client.get(
-      `/api/v1/entity-metrics/stocks/${encodeURIComponent(symbol)}/sentiment/by-source`,
-      options
-    );
-  }
-  /**
-   * @deprecated Use `getMetrics(symbol, { metricType: "sentiment" })` instead.
-   */
-  async getAverageSentiment(symbol, options) {
-    return this.client.get(
-      `/api/v1/entity-metrics/stocks/${encodeURIComponent(symbol)}/sentiment/average`,
-      options
-    );
-  }
 };
 
 // src/resources/etfs.ts
@@ -412,10 +356,9 @@ var Insights = class {
   /**
    * Get AI-generated insights for a specific stock, sorted by urgency then confidence.
    *
-   * PRO users receive a flat array of Insight objects.
-   * Free/unauthenticated users receive a preview with `isPreview: true`,
-   * the top 3 insights in full, and a `locked` array with metadata-only entries
-   * (type, urgency, timestamp) showing what additional signals exist.
+   * Returns the preview envelope: read the insights as `.data`. PRO callers get the
+   * full list with `isPreview: false`; free callers get the top 3 with `isPreview: true`
+   * and `totalCount` carrying the untruncated size.
    */
   async stock(ticker, options) {
     return this.client.get(
@@ -426,8 +369,9 @@ var Insights = class {
   /**
    * Get AI insights for a stock within a date range.
    *
-   * Free users receive the top 3; PRO users receive the full list.
-   * The server returns 400 if `startDate` is after `endDate`.
+   * Returns the preview envelope: read the insights as `.data`. Free callers receive
+   * the top 3, PRO callers the full list. The server returns 400 if `startDate` is
+   * after `endDate`.
    */
   async stockRange(ticker, options) {
     return this.client.get(
@@ -438,9 +382,9 @@ var Insights = class {
   /**
    * Get AI-generated market-level insights, sorted by urgency then confidence.
    *
-   * PRO users receive a flat array of Insight objects.
-   * Free/unauthenticated users receive a preview with `isPreview: true`,
-   * the top 5 insights in full, and a `locked` array with metadata-only entries.
+   * Returns the preview envelope: read the insights as `.data`. PRO callers get the
+   * full list with `isPreview: false`; free callers get the top 5 with `isPreview: true`
+   * and `totalCount` carrying the untruncated size.
    */
   async market() {
     return this.client.get("/api/v1/insights/market");
@@ -448,7 +392,8 @@ var Insights = class {
   /**
    * Get the latest AI insights across all tracked stocks, newest first.
    *
-   * Free users receive the top 5; PRO users receive up to `limit` (clamped to 1-200).
+   * Returns the preview envelope: read the insights as `.data`. Free callers receive
+   * the top 5, PRO callers up to `limit` (clamped to 1-200).
    */
   async latest(options) {
     return this.client.get("/api/v1/insights/latest", options);
@@ -458,6 +403,7 @@ var Insights = class {
    *
    * Biased toward the user's watchlist and portfolio when available; falls back
    * to market-level insights otherwise. API key authentication required.
+   * Returns the preview envelope: read the insights as `.data`.
    */
   async user(options) {
     return this.client.get("/api/v1/insights/user", options);
@@ -490,6 +436,9 @@ var Institutional = class {
    * `reportDate` is optional: omit it to get the latest available quarter, which may be
    * a still-open one holding only early filers. The response then carries `reportDate`
    * plus `isPending` and filer coverage counts so a partial quarter is clearly labeled.
+   *
+   * Returns the preview envelope, so the flows are one level down:
+   * `const { data } = await client.institutional.getFlows(); data.inflows`.
    */
   async getFlows(reportDate, options) {
     return this.client.get("/api/v1/institutional/flows", {
@@ -497,14 +446,25 @@ var Institutional = class {
       ...options
     });
   }
-  /** Get institutional holders for a specific stock. */
+  /**
+   * Get institutional holders for a specific stock.
+   *
+   * Returns the preview envelope wrapping a {@link TickerHolders} object, so the rows
+   * 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`.
+   */
   async getHolders(ticker, reportDate) {
     return this.client.get(
       `/api/v1/institutional/holders/${encodeURIComponent(ticker)}`,
       { reportDate }
     );
   }
-  /** Get activist investor positions (NEW or INCREASED). */
+  /**
+   * Get activist investor positions (NEW or INCREASED).
+   *
+   * Returns the preview envelope, so read the rows as `.data`.
+   */
   async getActivists(reportDate) {
     return this.client.get("/api/v1/institutional/activist", { reportDate });
   }
@@ -550,10 +510,6 @@ var KB = class {
   async getPopularEntities() {
     return this.client.get("/api/v1/kb/entities/popular");
   }
-  /** Get entity detail with metrics and relationships. */
-  async getEntity(entityId) {
-    return this.client.get(`/api/v1/kb/entities/${encodeURIComponent(entityId)}`);
-  }
   /** Get all tracked entities. */
   async getAllEntities() {
     return this.client.get("/api/v1/kb/entities/all");
@@ -682,11 +638,14 @@ var Stocks = class {
   async getFundamentals(ticker, options) {
     return this.client.get("/api/v1/stocks/fundamentals", { ticker, ...options });
   }
-  /** Get available fiscal periods. */
+  /** Get available fiscal periods. The periods are in `periods`. */
   async getFundamentalsPeriods(ticker) {
     return this.client.get("/api/v1/stocks/fundamentals/periods", { ticker });
   }
-  /** Get most recent fundamentals snapshot. */
+  /**
+   * Get the trailing-twelve-month fundamentals snapshot: TTM ratios, a different
+   * shape from the per-period statement data `getFundamentals()` returns.
+   */
   async getCurrentFundamentals(ticker) {
     return this.client.get("/api/v1/stocks/fundamentals/current", { ticker });
   }
@@ -777,7 +736,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.28.0";
+var VERSION = "0.30.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";