sentisense 0.28.0 → 0.29.0

package/dist/index.d.mts

@@ -117,10 +117,38 @@ interface Fundamentals {
     timeframe: string;
     [key: string]: unknown;
 }
+/**
+ * Trailing-twelve-month snapshot from `stocks.getCurrentFundamentals()`: TTM ratios,
+ * a different shape from the per-period statement data in {@link Fundamentals}.
+ */
+interface TtmFundamentals {
+    ticker: string;
+    currentPrice?: number;
+    peTTM?: number | null;
+    psTTM?: number | null;
+    epsTTM?: number | null;
+    revenueTTM?: number | null;
+    quartersIncluded?: number;
+    /** False when there is not enough filed history to compute the TTM figures. */
+    available?: boolean;
+    /** Populated when `available` is false, explaining why. */
+    reason?: string | null;
+    [key: string]: unknown;
+}
 interface FundamentalsPeriod {
     fiscalPeriod: string;
     fiscalYear: number;
 }
+/**
+ * What `stocks.getFundamentalsPeriods()` returns: the periods are in `periods`, not at
+ * the top level.
+ */
+interface FundamentalsPeriodsResponse {
+    ticker: string;
+    periods: FundamentalsPeriod[];
+    /** Populated when no periods are available, explaining why. */
+    reason?: string | null;
+}
 interface ShortInterest {
     ticker: string;
     [key: string]: unknown;
@@ -187,6 +215,23 @@ interface Document {
     reliability: number;
     sentiment: SentimentEntry[];
 }
+/**
+ * What the document-metrics endpoints return: `documents.getByTicker()`,
+ * `getByTickerRange()`, `getByEntity()`, `search()` and `getBySource()` all resolve to
+ * this. The rows are in `documents`, and this is NOT the {@link PreviewResponse}
+ * envelope: there is no `isPreview` or `data`.
+ */
+interface DocumentSearchResponse {
+    documents: Document[];
+    /** Total matching documents before any limit was applied. */
+    totalCount: number;
+    /** Ticker the query resolved to, or `null` when the query was not ticker-scoped. */
+    searchTicker: string | null;
+    /** Source filter applied, or `"ALL"` when unfiltered. */
+    source: string;
+    startDate: string;
+    endDate: string;
+}
 /** Story cluster with title, sentiment, and metrics. */
 interface StoryCluster {
     id: string;
@@ -300,13 +345,23 @@ interface Holder {
     sharesChangePct: number;
 }
 /**
- * The flows payload itself: what the server puts inside the response envelope.
- *
- * Note `institutional.getFlows()` is currently declared as returning this shape directly,
- * but the endpoint wraps it: the value you get back at runtime is
- * `{ isPreview, previewReason, data }` with these fields under `data`. Until the
- * declaration is corrected, read the flows as `(result as unknown as
- * PreviewResponse<InstitutionalFlows>).data.inflows`.
+ * Institutional ownership for one ticker: the `data` payload of
+ * `institutional.getHolders()`, which returns `PreviewResponse<TickerHolders>`. The
+ * holder rows are in `holders`, so read them as `result.data.holders` (two levels down),
+ * alongside ticker-level totals like `holderCount`.
+ */
+interface TickerHolders {
+    ticker: string;
+    companyName: string;
+    reportDate: string;
+    totalInstitutionalShares: number;
+    totalInstitutionalValue: number;
+    holderCount: number;
+    holders: Holder[];
+}
+/**
+ * The flows payload inside the response envelope: `institutional.getFlows()` returns
+ * `PreviewResponse<InstitutionalFlows>`, so read the flows as `result.data.inflows`.
  */
 interface InstitutionalFlows {
     inflows: InstitutionalFlow[];
@@ -330,7 +385,11 @@ interface InstitutionalFlows {
      */
     baselineFilerCount?: number;
 }
-/** Alias of {@link InstitutionalFlows}; same shape. */
+/**
+ * @deprecated Names the INNER flows payload, but `getFlows()` returns the envelope
+ * {@link PreviewResponse}<{@link InstitutionalFlows}>. Kept as an alias of the inner
+ * shape so an existing import still resolves; will be removed in a future release.
+ */
 type InstitutionalFlowsResponse = InstitutionalFlows;
 interface GetFlowsOptions {
     limit?: number;
@@ -692,7 +751,11 @@ interface LockedInsight {
     urgency: string;
     generatedAt: number;
 }
-/** Preview response returned to free/unauthenticated users on insights endpoints. */
+/**
+ * @deprecated The insights endpoints return `PreviewResponse<Insight[]>`, not this shape.
+ * No endpoint emits `insights` or `locked`. Kept only so an existing import resolves;
+ * will be removed in a future release.
+ */
 interface InsightPreviewResponse {
     isPreview: true;
     previewReason: "PRO_REQUIRED";
@@ -1031,16 +1094,16 @@ declare class Calendar {
 declare class Documents {
     private client;
     constructor(client: APIClient);
-    /** Get document metrics for a stock. */
-    getByTicker(ticker: string, options?: GetByTickerOptions): Promise<Document[]>;
-    /** Get document metrics for a stock within a date range. */
-    getByTickerRange(ticker: string, options: GetByTickerRangeOptions): Promise<Document[]>;
-    /** Get document metrics for a KB entity. */
-    getByEntity(entityId: string, options?: GetByEntityOptions): Promise<Document[]>;
-    /** Smart search with natural language query parsing. */
-    search(query: string, options?: SearchDocumentsOptions): Promise<Document[]>;
-    /** Get latest document metrics from a source type. */
-    getBySource(source: DocumentSource, options?: GetBySourceOptions): Promise<Document[]>;
+    /** Get document metrics for a stock. The rows are in `documents`. */
+    getByTicker(ticker: string, options?: GetByTickerOptions): Promise<DocumentSearchResponse>;
+    /** Get document metrics for a stock within a date range. The rows are in `documents`. */
+    getByTickerRange(ticker: string, options: GetByTickerRangeOptions): Promise<DocumentSearchResponse>;
+    /** Get document metrics for a KB entity. The rows are in `documents`. */
+    getByEntity(entityId: string, options?: GetByEntityOptions): Promise<DocumentSearchResponse>;
+    /** Smart search with natural language query parsing. The rows are in `documents`. */
+    search(query: string, options?: SearchDocumentsOptions): Promise<DocumentSearchResponse>;
+    /** Get latest document metrics from a source type. The rows are in `documents`. */
+    getBySource(source: DocumentSource, options?: GetBySourceOptions): Promise<DocumentSearchResponse>;
     /** Get AI-curated news story clusters. */
     getStories(options?: GetStoriesOptions): Promise<Story[]>;
     /** Get full story detail by cluster ID. */
@@ -1333,40 +1396,42 @@ declare class Insights {
     /**
      * 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.
      */
-    stock(ticker: string, options?: GetInsightsOptions): Promise<Insight[] | InsightPreviewResponse>;
+    stock(ticker: string, options?: GetInsightsOptions): Promise<PreviewResponse<Insight[]>>;
     /**
      * 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`.
      */
-    stockRange(ticker: string, options: GetStockInsightsRangeOptions): Promise<Insight[] | InsightPreviewResponse>;
+    stockRange(ticker: string, options: GetStockInsightsRangeOptions): Promise<PreviewResponse<Insight[]>>;
     /**
      * 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.
      */
-    market(): Promise<Insight[] | InsightPreviewResponse>;
+    market(): Promise<PreviewResponse<Insight[]>>;
     /**
      * 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).
      */
-    latest(options?: GetLatestInsightsOptions): Promise<Insight[] | InsightPreviewResponse>;
+    latest(options?: GetLatestInsightsOptions): Promise<PreviewResponse<Insight[]>>;
     /**
      * Get personalized insights for the authenticated user.
      *
      * 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`.
      */
-    user(options?: GetUserInsightsOptions): Promise<Insight[] | InsightPreviewResponse>;
+    user(options?: GetUserInsightsOptions): Promise<PreviewResponse<Insight[]>>;
     /**
      * Get available insight types for a specific stock.
      * No authentication required.
@@ -1387,12 +1452,26 @@ declare class Institutional {
      * `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`.
      */
-    getFlows(reportDate?: string, options?: GetFlowsOptions): Promise<InstitutionalFlowsResponse>;
-    /** Get institutional holders for a specific stock. */
-    getHolders(ticker: string, reportDate: string): Promise<Holder[]>;
-    /** Get activist investor positions (NEW or INCREASED). */
-    getActivists(reportDate: string): Promise<Holder[]>;
+    getFlows(reportDate?: string, options?: GetFlowsOptions): Promise<PreviewResponse<InstitutionalFlows>>;
+    /**
+     * 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`.
+     */
+    getHolders(ticker: string, reportDate: string): Promise<PreviewResponse<TickerHolders>>;
+    /**
+     * Get activist investor positions (NEW or INCREASED).
+     *
+     * Returns the preview envelope, so read the rows as `.data`.
+     */
+    getActivists(reportDate: string): Promise<PreviewResponse<Holder[]>>;
     /**
      * Discover institutions: a paginated, AUM-ranked list of filers (slug + metadata)
      * so you can find what to query without knowing slugs upfront.
@@ -1488,10 +1567,13 @@ declare class Stocks {
     getMarketStatus(): Promise<MarketStatus>;
     /** Get financial statement data. */
     getFundamentals(ticker: string, options?: GetFundamentalsOptions): Promise<Fundamentals>;
-    /** Get available fiscal periods. */
-    getFundamentalsPeriods(ticker: string): Promise<FundamentalsPeriod[]>;
-    /** Get most recent fundamentals snapshot. */
-    getCurrentFundamentals(ticker: string): Promise<Fundamentals>;
+    /** Get available fiscal periods. The periods are in `periods`. */
+    getFundamentalsPeriods(ticker: string): Promise<FundamentalsPeriodsResponse>;
+    /**
+     * Get the trailing-twelve-month fundamentals snapshot: TTM ratios, a different
+     * shape from the per-period statement data `getFundamentals()` returns.
+     */
+    getCurrentFundamentals(ticker: string): Promise<TtmFundamentals>;
     /** Get historical revenue data. */
     getHistoricalRevenue(ticker: string): Promise<unknown>;
     /** Get short interest metrics (FINRA). */
@@ -1615,6 +1697,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.28.0";
+declare const VERSION = "0.29.0";
 
-export { type AISummary, APIError, type AnalystAction, type AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, type Document, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfSentimentAggregate, type EtfSentimentReading, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEtfInsiderAggregateOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticiansOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MentionCount, type MentionData, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type PoliticianDetail, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentData, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockPrice, type StockProfile, type StockQuote, type Story, type StoryCluster, type TrackerEvent, type TrackerGeoEntry, type TrackerHeadlineMetric, type TrackerListResponse, type TrackerListing, type TrackerMetricValue, type TrackerSignal, type TrackerSnapshot, type TrackerSnapshotResponse, type TrackerSourceRef, type TrackerTableRow, type TrackerTimeSeriesPoint, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };
+export { type AISummary, APIError, type AnalystAction, type AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfSentimentAggregate, type EtfSentimentReading, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEtfInsiderAggregateOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticiansOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlows, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MentionCount, type MentionData, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type PoliticianDetail, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentData, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockPrice, type StockProfile, type StockQuote, type Story, type StoryCluster, type TickerHolders, type TrackerEvent, type TrackerGeoEntry, type TrackerHeadlineMetric, type TrackerListResponse, type TrackerListing, type TrackerMetricValue, type TrackerSignal, type TrackerSnapshot, type TrackerSnapshotResponse, type TrackerSourceRef, type TrackerTableRow, type TrackerTimeSeriesPoint, type TtmFundamentals, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };

package/dist/index.d.ts

@@ -117,10 +117,38 @@ interface Fundamentals {
     timeframe: string;
     [key: string]: unknown;
 }
+/**
+ * Trailing-twelve-month snapshot from `stocks.getCurrentFundamentals()`: TTM ratios,
+ * a different shape from the per-period statement data in {@link Fundamentals}.
+ */
+interface TtmFundamentals {
+    ticker: string;
+    currentPrice?: number;
+    peTTM?: number | null;
+    psTTM?: number | null;
+    epsTTM?: number | null;
+    revenueTTM?: number | null;
+    quartersIncluded?: number;
+    /** False when there is not enough filed history to compute the TTM figures. */
+    available?: boolean;
+    /** Populated when `available` is false, explaining why. */
+    reason?: string | null;
+    [key: string]: unknown;
+}
 interface FundamentalsPeriod {
     fiscalPeriod: string;
     fiscalYear: number;
 }
+/**
+ * What `stocks.getFundamentalsPeriods()` returns: the periods are in `periods`, not at
+ * the top level.
+ */
+interface FundamentalsPeriodsResponse {
+    ticker: string;
+    periods: FundamentalsPeriod[];
+    /** Populated when no periods are available, explaining why. */
+    reason?: string | null;
+}
 interface ShortInterest {
     ticker: string;
     [key: string]: unknown;
@@ -187,6 +215,23 @@ interface Document {
     reliability: number;
     sentiment: SentimentEntry[];
 }
+/**
+ * What the document-metrics endpoints return: `documents.getByTicker()`,
+ * `getByTickerRange()`, `getByEntity()`, `search()` and `getBySource()` all resolve to
+ * this. The rows are in `documents`, and this is NOT the {@link PreviewResponse}
+ * envelope: there is no `isPreview` or `data`.
+ */
+interface DocumentSearchResponse {
+    documents: Document[];
+    /** Total matching documents before any limit was applied. */
+    totalCount: number;
+    /** Ticker the query resolved to, or `null` when the query was not ticker-scoped. */
+    searchTicker: string | null;
+    /** Source filter applied, or `"ALL"` when unfiltered. */
+    source: string;
+    startDate: string;
+    endDate: string;
+}
 /** Story cluster with title, sentiment, and metrics. */
 interface StoryCluster {
     id: string;
@@ -300,13 +345,23 @@ interface Holder {
     sharesChangePct: number;
 }
 /**
- * The flows payload itself: what the server puts inside the response envelope.
- *
- * Note `institutional.getFlows()` is currently declared as returning this shape directly,
- * but the endpoint wraps it: the value you get back at runtime is
- * `{ isPreview, previewReason, data }` with these fields under `data`. Until the
- * declaration is corrected, read the flows as `(result as unknown as
- * PreviewResponse<InstitutionalFlows>).data.inflows`.
+ * Institutional ownership for one ticker: the `data` payload of
+ * `institutional.getHolders()`, which returns `PreviewResponse<TickerHolders>`. The
+ * holder rows are in `holders`, so read them as `result.data.holders` (two levels down),
+ * alongside ticker-level totals like `holderCount`.
+ */
+interface TickerHolders {
+    ticker: string;
+    companyName: string;
+    reportDate: string;
+    totalInstitutionalShares: number;
+    totalInstitutionalValue: number;
+    holderCount: number;
+    holders: Holder[];
+}
+/**
+ * The flows payload inside the response envelope: `institutional.getFlows()` returns
+ * `PreviewResponse<InstitutionalFlows>`, so read the flows as `result.data.inflows`.
  */
 interface InstitutionalFlows {
     inflows: InstitutionalFlow[];
@@ -330,7 +385,11 @@ interface InstitutionalFlows {
      */
     baselineFilerCount?: number;
 }
-/** Alias of {@link InstitutionalFlows}; same shape. */
+/**
+ * @deprecated Names the INNER flows payload, but `getFlows()` returns the envelope
+ * {@link PreviewResponse}<{@link InstitutionalFlows}>. Kept as an alias of the inner
+ * shape so an existing import still resolves; will be removed in a future release.
+ */
 type InstitutionalFlowsResponse = InstitutionalFlows;
 interface GetFlowsOptions {
     limit?: number;
@@ -692,7 +751,11 @@ interface LockedInsight {
     urgency: string;
     generatedAt: number;
 }
-/** Preview response returned to free/unauthenticated users on insights endpoints. */
+/**
+ * @deprecated The insights endpoints return `PreviewResponse<Insight[]>`, not this shape.
+ * No endpoint emits `insights` or `locked`. Kept only so an existing import resolves;
+ * will be removed in a future release.
+ */
 interface InsightPreviewResponse {
     isPreview: true;
     previewReason: "PRO_REQUIRED";
@@ -1031,16 +1094,16 @@ declare class Calendar {
 declare class Documents {
     private client;
     constructor(client: APIClient);
-    /** Get document metrics for a stock. */
-    getByTicker(ticker: string, options?: GetByTickerOptions): Promise<Document[]>;
-    /** Get document metrics for a stock within a date range. */
-    getByTickerRange(ticker: string, options: GetByTickerRangeOptions): Promise<Document[]>;
-    /** Get document metrics for a KB entity. */
-    getByEntity(entityId: string, options?: GetByEntityOptions): Promise<Document[]>;
-    /** Smart search with natural language query parsing. */
-    search(query: string, options?: SearchDocumentsOptions): Promise<Document[]>;
-    /** Get latest document metrics from a source type. */
-    getBySource(source: DocumentSource, options?: GetBySourceOptions): Promise<Document[]>;
+    /** Get document metrics for a stock. The rows are in `documents`. */
+    getByTicker(ticker: string, options?: GetByTickerOptions): Promise<DocumentSearchResponse>;
+    /** Get document metrics for a stock within a date range. The rows are in `documents`. */
+    getByTickerRange(ticker: string, options: GetByTickerRangeOptions): Promise<DocumentSearchResponse>;
+    /** Get document metrics for a KB entity. The rows are in `documents`. */
+    getByEntity(entityId: string, options?: GetByEntityOptions): Promise<DocumentSearchResponse>;
+    /** Smart search with natural language query parsing. The rows are in `documents`. */
+    search(query: string, options?: SearchDocumentsOptions): Promise<DocumentSearchResponse>;
+    /** Get latest document metrics from a source type. The rows are in `documents`. */
+    getBySource(source: DocumentSource, options?: GetBySourceOptions): Promise<DocumentSearchResponse>;
     /** Get AI-curated news story clusters. */
     getStories(options?: GetStoriesOptions): Promise<Story[]>;
     /** Get full story detail by cluster ID. */
@@ -1333,40 +1396,42 @@ declare class Insights {
     /**
      * 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.
      */
-    stock(ticker: string, options?: GetInsightsOptions): Promise<Insight[] | InsightPreviewResponse>;
+    stock(ticker: string, options?: GetInsightsOptions): Promise<PreviewResponse<Insight[]>>;
     /**
      * 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`.
      */
-    stockRange(ticker: string, options: GetStockInsightsRangeOptions): Promise<Insight[] | InsightPreviewResponse>;
+    stockRange(ticker: string, options: GetStockInsightsRangeOptions): Promise<PreviewResponse<Insight[]>>;
     /**
      * 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.
      */
-    market(): Promise<Insight[] | InsightPreviewResponse>;
+    market(): Promise<PreviewResponse<Insight[]>>;
     /**
      * 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).
      */
-    latest(options?: GetLatestInsightsOptions): Promise<Insight[] | InsightPreviewResponse>;
+    latest(options?: GetLatestInsightsOptions): Promise<PreviewResponse<Insight[]>>;
     /**
      * Get personalized insights for the authenticated user.
      *
      * 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`.
      */
-    user(options?: GetUserInsightsOptions): Promise<Insight[] | InsightPreviewResponse>;
+    user(options?: GetUserInsightsOptions): Promise<PreviewResponse<Insight[]>>;
     /**
      * Get available insight types for a specific stock.
      * No authentication required.
@@ -1387,12 +1452,26 @@ declare class Institutional {
      * `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`.
      */
-    getFlows(reportDate?: string, options?: GetFlowsOptions): Promise<InstitutionalFlowsResponse>;
-    /** Get institutional holders for a specific stock. */
-    getHolders(ticker: string, reportDate: string): Promise<Holder[]>;
-    /** Get activist investor positions (NEW or INCREASED). */
-    getActivists(reportDate: string): Promise<Holder[]>;
+    getFlows(reportDate?: string, options?: GetFlowsOptions): Promise<PreviewResponse<InstitutionalFlows>>;
+    /**
+     * 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`.
+     */
+    getHolders(ticker: string, reportDate: string): Promise<PreviewResponse<TickerHolders>>;
+    /**
+     * Get activist investor positions (NEW or INCREASED).
+     *
+     * Returns the preview envelope, so read the rows as `.data`.
+     */
+    getActivists(reportDate: string): Promise<PreviewResponse<Holder[]>>;
     /**
      * Discover institutions: a paginated, AUM-ranked list of filers (slug + metadata)
      * so you can find what to query without knowing slugs upfront.
@@ -1488,10 +1567,13 @@ declare class Stocks {
     getMarketStatus(): Promise<MarketStatus>;
     /** Get financial statement data. */
     getFundamentals(ticker: string, options?: GetFundamentalsOptions): Promise<Fundamentals>;
-    /** Get available fiscal periods. */
-    getFundamentalsPeriods(ticker: string): Promise<FundamentalsPeriod[]>;
-    /** Get most recent fundamentals snapshot. */
-    getCurrentFundamentals(ticker: string): Promise<Fundamentals>;
+    /** Get available fiscal periods. The periods are in `periods`. */
+    getFundamentalsPeriods(ticker: string): Promise<FundamentalsPeriodsResponse>;
+    /**
+     * Get the trailing-twelve-month fundamentals snapshot: TTM ratios, a different
+     * shape from the per-period statement data `getFundamentals()` returns.
+     */
+    getCurrentFundamentals(ticker: string): Promise<TtmFundamentals>;
     /** Get historical revenue data. */
     getHistoricalRevenue(ticker: string): Promise<unknown>;
     /** Get short interest metrics (FINRA). */
@@ -1615,6 +1697,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.28.0";
+declare const VERSION = "0.29.0";
 
-export { type AISummary, APIError, type AnalystAction, type AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, type Document, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfSentimentAggregate, type EtfSentimentReading, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEtfInsiderAggregateOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticiansOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MentionCount, type MentionData, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type PoliticianDetail, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentData, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockPrice, type StockProfile, type StockQuote, type Story, type StoryCluster, type TrackerEvent, type TrackerGeoEntry, type TrackerHeadlineMetric, type TrackerListResponse, type TrackerListing, type TrackerMetricValue, type TrackerSignal, type TrackerSnapshot, type TrackerSnapshotResponse, type TrackerSourceRef, type TrackerTableRow, type TrackerTimeSeriesPoint, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };
+export { type AISummary, APIError, type AnalystAction, type AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfSentimentAggregate, type EtfSentimentReading, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEtfInsiderAggregateOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticiansOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlows, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MentionCount, type MentionData, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type PoliticianDetail, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentData, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockPrice, type StockProfile, type StockQuote, type Story, type StoryCluster, type TickerHolders, type TrackerEvent, type TrackerGeoEntry, type TrackerHeadlineMetric, type TrackerListResponse, type TrackerListing, type TrackerMetricValue, type TrackerSignal, type TrackerSnapshot, type TrackerSnapshotResponse, type TrackerSourceRef, type TrackerTableRow, type TrackerTimeSeriesPoint, type TtmFundamentals, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };