sentisense 0.62.0 → 0.63.1

package/dist/index.d.mts

@@ -230,7 +230,7 @@ interface StockEntity {
 interface GetStockGraphOptions {
     /** Hops from the stock's own company node: `1` (default) or `2`. */
     depth?: 1 | 2;
-    /** Maximum nodes in the response, 1 to 200. Omitted, the API uses 75. */
+    /** Maximum non-root nodes, 1 to 200 (default 75). The root is always included in addition. */
     cap?: number;
 }
 /** One node in a {@link StockGraph}. Every identifier in the graph is a `slug`. */
@@ -240,6 +240,8 @@ interface GraphNode {
     displayName: string;
     /** `"COMPANY"`, `"PERSON"`, `"PRODUCT_OR_SERVICE"`, `"ORGANIZATION"`, `"PUBLISHER"`, `"TOPIC"`, ... */
     type: string;
+    /** Product category, present only on PRODUCT_OR_SERVICE nodes when known. */
+    category?: string;
 }
 /** One typed relationship in a {@link StockGraph}, between two node slugs. */
 interface GraphEdge {
@@ -260,7 +262,7 @@ interface GraphEdge {
 }
 /** A product family and the slugs of its member products. */
 interface GraphProductFamily {
-    /** Family name, e.g. `"iPhone"`. */
+    /** Parent product's slug, e.g. `"iPhone"`. Join to nodes[].slug for its displayName label. */
     family: string;
     /** Slugs of the products in the family. */
     members: string[];
@@ -914,6 +916,10 @@ interface OptionsSummary {
     largestPrintPctl?: number;
     /** Where the intraday board lives and who can open it. */
     capabilities?: OptionsCapabilities;
+    /** DELISTED marks a frozen last dossier; absent for listed or pending symbols. */
+    listingStatus?: "DELISTED";
+    /** ISO day (YYYY-MM-DD) trading stopped; absent when the date is unknown. */
+    delistedDate?: string;
 }
 /** Trailing window for `client.stocks.getOptionsHistory()`. */
 type OptionsHistoryWindow = "1y" | "2y" | "5y";
@@ -1629,6 +1635,38 @@ interface GetHoldersOptions {
     /** Sort direction. Server default is `"desc"`. Requires `limit`. */
     sortDir?: "asc" | "desc";
 }
+/**
+ * Optional wire keys inside an institution detail's preview envelope.
+ * Opt in with PreviewResponse<InstitutionDetail>; getInstitutionDetail retains
+ * Promise<unknown> for compatibility with existing callers and implementations.
+ */
+interface InstitutionDetail {
+    filerCik?: string | null;
+    displayName?: string | null;
+    urlSlug?: string | null;
+    filerCategory?: string | null;
+    /** Equity portfolio value in USD. */
+    totalValueUsd?: number;
+    /** Full row count, including synthetic SOLD_OUT rows. */
+    holdingsCount?: number;
+    /** Latest report's ISO calendar day (YYYY-MM-DD). */
+    latestReportDate?: string | null;
+    quartersTracked?: number;
+    newPositions?: number;
+    increasedPositions?: number;
+    decreasedPositions?: number;
+    soldOutPositions?: number;
+    multiCikRollup?: boolean | null;
+    childCikCount?: number | null;
+    childCiks?: string[] | null;
+    holdings?: Record<string, unknown>[] | null;
+    optionPositions?: Record<string, unknown>[];
+    returnedCount?: number;
+    offset?: number;
+    /** max(0, holdingsCount - soldOutPositions), for the full portfolio on every tier. */
+    positionsHeld?: number;
+    [key: string]: unknown;
+}
 /** A single institution summary from the discovery list. */
 interface InstitutionSummary {
     /** SEC Central Index Key of the (rolled-up) institution. */
@@ -3162,6 +3200,12 @@ interface AnalystEarningsSurprise {
      * As sent by the API: a fraction rounded to 2 decimals (0.07 = 7%), despite the name.
      */
     surprisePercent: number | null;
+    /**
+     * Signed true percent: (actualEps - estimateEps) * 100 / abs(estimateEps),
+     * rounded half-up to 2 decimals. Null when either EPS is missing or the estimate
+     * is zero. The legacy surprisePercent fraction is unchanged.
+     */
+    surprisePct?: number | null;
     [key: string]: unknown;
 }
 interface AnalystEstimatesResponse {
@@ -3561,9 +3605,11 @@ declare class Earnings {
      * management phrased it, and a summary of the earnings call.
      *
      * Branch on `isPreview`: a PRO key receives every hydrated quarter in full, a
-     * FREE key receives the latest quarter shaped rather than truncated, plus
-     * `totalCount`. {@link EarningsQuarter} documents which fields each tier
-     * carries.
+     * FREE key receives the latest quarter shaped rather than truncated.
+     * `totalCount` on the envelope counts indexed quarters on both tiers. The
+     * returned array can be shorter when a body is unavailable or limit cuts it.
+     * Older responses may omit the count. {@link EarningsQuarter} documents
+     * which fields each tier carries.
      *
      * A quarter typically appears within 48 hours of the company reporting, and
      * the call summary can arrive after the press-release content for the same
@@ -4111,6 +4157,10 @@ declare class Institutional {
      * Resolved by URL slug (e.g. `Berkshire-Hathaway`) or numeric SEC CIK.
      * Free users receive the profile and top 10 holdings; PRO users receive the
      * full holdings array. Returns 404 if the slug or CIK is unknown.
+     *
+     * The signature remains unknown for compatibility. Opt in to the exported
+     * PreviewResponse<InstitutionDetail> type to read data.positionsHeld, the full
+     * portfolio count excluding SOLD_OUT rows, even on a truncated holdings list.
      */
     getInstitutionDetail(slugOrCik: string): Promise<unknown>;
 }
@@ -4371,8 +4421,9 @@ declare class Stocks {
      *
      * Every identifier in the response is a slug, the same handle the metric and document
      * endpoints take, so a node can be passed straight to them. `depth` is 1 (default) or 2,
-     * `cap` limits the node count (1 to 200, default 75); out-of-range values are rejected
-     * with a 400. A ticker with no graph returns a `NotFoundError`.
+     * `cap` limits the number of non-root nodes (1 to 200, default 75); the root is always
+     * included in addition. Out-of-range values are rejected with a 400. A ticker with no
+     * graph returns a `NotFoundError`.
      */
     getGraph(ticker: string, options?: GetStockGraphOptions): Promise<StockGraph>;
     /**
@@ -4677,6 +4728,14 @@ declare class DeepHistoryUnavailableError extends SentiSenseError {
     retryAfter?: number;
     constructor(message: string, retryAfter?: number);
 }
+/**
+ * A 429. Check `code` to tell the two apart:
+ *
+ * - `"rate_limit_exceeded"`: the per-minute limit. The client retries it after `Retry-After`
+ *   before throwing, so you see this only once retries are used up.
+ * - `"quota_exceeded"`: the monthly request allowance is used up. It is thrown on the first
+ *   response without retrying, and `message` says when the allowance resets.
+ */
 declare class RateLimitError extends SentiSenseError {
     /**
      * Seconds to wait before retrying, from the server's `Retry-After` header, clamped to
@@ -4704,6 +4763,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.62.0";
+declare const VERSION = "0.63.1";
 
-export { type AISummary, APIError, type AnalystAction, type AnalystCall, type AnalystCalledItCall, type AnalystCalledItMove, type AnalystConsensus, type AnalystConsensusHistory, type AnalystConsensusHistoryPoint, type AnalystCoverage, type AnalystCoverageAnalyst, type AnalystCoverageBookEntry, type AnalystCoverageFirm, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatePeriodType, type AnalystEstimatesResponse, type AnalystFirmRating, type AnalystFirmTenure, type AnalystNote, type AnalystProfile, type AnalystRatingBuckets, type AnalystRef, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, DeepHistoryUnavailableError, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EarningsKpiHighlight, type EarningsOutcomeStatistics, type EarningsQuarter, type EarningsReaction, type EarningsReactionsResponse, type EarningsSource, type EarningsStatistics, type EarningsStatisticsBaseline, type EarningsStatisticsDeviation, type EarningsStatisticsThresholds, type EarningsStatisticsWindow, type EntitySearchResult, type EntitySearchType, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfQuote, type EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type ExtendedHoursInfo, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystCalledItOptions, type GetAnalystCallsOptions, type GetAnalystConsensusHistoryOptions, type GetAnalystCoverageOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsStatisticsOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticianMemberOptions, type GetPoliticiansOptions, type GetRankedEarningsOptions, type GetRecentEarningsOptions, type GetShortInterestOptions, type GetShortVolumeOptions, type GetStockGraphOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type GraphCounts, type GraphEdge, type GraphGroups, type GraphNode, type GraphProductFamily, type Holder, type HolderNotableChanges, type IndexConstituent, type IndexHistoryPoint, type IndexHistoryResponse, type IndexListResponse, type IndexListing, type IndexSnapshot, 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 MarketMoodOptions, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type OptionsAggregate, type OptionsCapabilities, type OptionsContext, type OptionsHighlight, type OptionsHistory, type OptionsHistoryWindow, type OptionsIntradayBoardCapability, type OptionsIntradayFlow, type OptionsOiFollowUp, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, type RankedEarnings, type RankedEarningsSection, type RankedReportedEarnings, type RankedUpcomingEarnings, RateLimitError, type RatingBase, type RatingDimension, type RatingDimensionKey, type RatingFlag, type RatingNotRatedReason, type RatingSubLeg, type RecentEarningsEntry, type RiskAdjustment, type RiskCondition, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, type SearchEntitiesOptions, type SearchStoriesOptions, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortInterestDataPoint, type ShortVolume, type ShortVolumeDataPoint, type SimilarStock, type StockDetail, type StockEntity, type StockGraph, type StockImage, type StockNotRated, type StockPrice, type StockProfile, type StockQuote, type StockRating, type StockRatingResponse, type StockSocialDominance, type Story, type StoryCluster, type StoryTimelineEntry, TemporarilyUnavailableError, 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 };
+export { type AISummary, APIError, type AnalystAction, type AnalystCall, type AnalystCalledItCall, type AnalystCalledItMove, type AnalystConsensus, type AnalystConsensusHistory, type AnalystConsensusHistoryPoint, type AnalystCoverage, type AnalystCoverageAnalyst, type AnalystCoverageBookEntry, type AnalystCoverageFirm, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatePeriodType, type AnalystEstimatesResponse, type AnalystFirmRating, type AnalystFirmTenure, type AnalystNote, type AnalystProfile, type AnalystRatingBuckets, type AnalystRef, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, DeepHistoryUnavailableError, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EarningsKpiHighlight, type EarningsOutcomeStatistics, type EarningsQuarter, type EarningsReaction, type EarningsReactionsResponse, type EarningsSource, type EarningsStatistics, type EarningsStatisticsBaseline, type EarningsStatisticsDeviation, type EarningsStatisticsThresholds, type EarningsStatisticsWindow, type EntitySearchResult, type EntitySearchType, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfQuote, type EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type ExtendedHoursInfo, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystCalledItOptions, type GetAnalystCallsOptions, type GetAnalystConsensusHistoryOptions, type GetAnalystCoverageOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsStatisticsOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticianMemberOptions, type GetPoliticiansOptions, type GetRankedEarningsOptions, type GetRecentEarningsOptions, type GetShortInterestOptions, type GetShortVolumeOptions, type GetStockGraphOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type GraphCounts, type GraphEdge, type GraphGroups, type GraphNode, type GraphProductFamily, type Holder, type HolderNotableChanges, type IndexConstituent, type IndexHistoryPoint, type IndexHistoryResponse, type IndexListResponse, type IndexListing, type IndexSnapshot, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionDetail, 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 MarketMoodOptions, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type OptionsAggregate, type OptionsCapabilities, type OptionsContext, type OptionsHighlight, type OptionsHistory, type OptionsHistoryWindow, type OptionsIntradayBoardCapability, type OptionsIntradayFlow, type OptionsOiFollowUp, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, type RankedEarnings, type RankedEarningsSection, type RankedReportedEarnings, type RankedUpcomingEarnings, RateLimitError, type RatingBase, type RatingDimension, type RatingDimensionKey, type RatingFlag, type RatingNotRatedReason, type RatingSubLeg, type RecentEarningsEntry, type RiskAdjustment, type RiskCondition, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, type SearchEntitiesOptions, type SearchStoriesOptions, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortInterestDataPoint, type ShortVolume, type ShortVolumeDataPoint, type SimilarStock, type StockDetail, type StockEntity, type StockGraph, type StockImage, type StockNotRated, type StockPrice, type StockProfile, type StockQuote, type StockRating, type StockRatingResponse, type StockSocialDominance, type Story, type StoryCluster, type StoryTimelineEntry, TemporarilyUnavailableError, 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

@@ -230,7 +230,7 @@ interface StockEntity {
 interface GetStockGraphOptions {
     /** Hops from the stock's own company node: `1` (default) or `2`. */
     depth?: 1 | 2;
-    /** Maximum nodes in the response, 1 to 200. Omitted, the API uses 75. */
+    /** Maximum non-root nodes, 1 to 200 (default 75). The root is always included in addition. */
     cap?: number;
 }
 /** One node in a {@link StockGraph}. Every identifier in the graph is a `slug`. */
@@ -240,6 +240,8 @@ interface GraphNode {
     displayName: string;
     /** `"COMPANY"`, `"PERSON"`, `"PRODUCT_OR_SERVICE"`, `"ORGANIZATION"`, `"PUBLISHER"`, `"TOPIC"`, ... */
     type: string;
+    /** Product category, present only on PRODUCT_OR_SERVICE nodes when known. */
+    category?: string;
 }
 /** One typed relationship in a {@link StockGraph}, between two node slugs. */
 interface GraphEdge {
@@ -260,7 +262,7 @@ interface GraphEdge {
 }
 /** A product family and the slugs of its member products. */
 interface GraphProductFamily {
-    /** Family name, e.g. `"iPhone"`. */
+    /** Parent product's slug, e.g. `"iPhone"`. Join to nodes[].slug for its displayName label. */
     family: string;
     /** Slugs of the products in the family. */
     members: string[];
@@ -914,6 +916,10 @@ interface OptionsSummary {
     largestPrintPctl?: number;
     /** Where the intraday board lives and who can open it. */
     capabilities?: OptionsCapabilities;
+    /** DELISTED marks a frozen last dossier; absent for listed or pending symbols. */
+    listingStatus?: "DELISTED";
+    /** ISO day (YYYY-MM-DD) trading stopped; absent when the date is unknown. */
+    delistedDate?: string;
 }
 /** Trailing window for `client.stocks.getOptionsHistory()`. */
 type OptionsHistoryWindow = "1y" | "2y" | "5y";
@@ -1629,6 +1635,38 @@ interface GetHoldersOptions {
     /** Sort direction. Server default is `"desc"`. Requires `limit`. */
     sortDir?: "asc" | "desc";
 }
+/**
+ * Optional wire keys inside an institution detail's preview envelope.
+ * Opt in with PreviewResponse<InstitutionDetail>; getInstitutionDetail retains
+ * Promise<unknown> for compatibility with existing callers and implementations.
+ */
+interface InstitutionDetail {
+    filerCik?: string | null;
+    displayName?: string | null;
+    urlSlug?: string | null;
+    filerCategory?: string | null;
+    /** Equity portfolio value in USD. */
+    totalValueUsd?: number;
+    /** Full row count, including synthetic SOLD_OUT rows. */
+    holdingsCount?: number;
+    /** Latest report's ISO calendar day (YYYY-MM-DD). */
+    latestReportDate?: string | null;
+    quartersTracked?: number;
+    newPositions?: number;
+    increasedPositions?: number;
+    decreasedPositions?: number;
+    soldOutPositions?: number;
+    multiCikRollup?: boolean | null;
+    childCikCount?: number | null;
+    childCiks?: string[] | null;
+    holdings?: Record<string, unknown>[] | null;
+    optionPositions?: Record<string, unknown>[];
+    returnedCount?: number;
+    offset?: number;
+    /** max(0, holdingsCount - soldOutPositions), for the full portfolio on every tier. */
+    positionsHeld?: number;
+    [key: string]: unknown;
+}
 /** A single institution summary from the discovery list. */
 interface InstitutionSummary {
     /** SEC Central Index Key of the (rolled-up) institution. */
@@ -3162,6 +3200,12 @@ interface AnalystEarningsSurprise {
      * As sent by the API: a fraction rounded to 2 decimals (0.07 = 7%), despite the name.
      */
     surprisePercent: number | null;
+    /**
+     * Signed true percent: (actualEps - estimateEps) * 100 / abs(estimateEps),
+     * rounded half-up to 2 decimals. Null when either EPS is missing or the estimate
+     * is zero. The legacy surprisePercent fraction is unchanged.
+     */
+    surprisePct?: number | null;
     [key: string]: unknown;
 }
 interface AnalystEstimatesResponse {
@@ -3561,9 +3605,11 @@ declare class Earnings {
      * management phrased it, and a summary of the earnings call.
      *
      * Branch on `isPreview`: a PRO key receives every hydrated quarter in full, a
-     * FREE key receives the latest quarter shaped rather than truncated, plus
-     * `totalCount`. {@link EarningsQuarter} documents which fields each tier
-     * carries.
+     * FREE key receives the latest quarter shaped rather than truncated.
+     * `totalCount` on the envelope counts indexed quarters on both tiers. The
+     * returned array can be shorter when a body is unavailable or limit cuts it.
+     * Older responses may omit the count. {@link EarningsQuarter} documents
+     * which fields each tier carries.
      *
      * A quarter typically appears within 48 hours of the company reporting, and
      * the call summary can arrive after the press-release content for the same
@@ -4111,6 +4157,10 @@ declare class Institutional {
      * Resolved by URL slug (e.g. `Berkshire-Hathaway`) or numeric SEC CIK.
      * Free users receive the profile and top 10 holdings; PRO users receive the
      * full holdings array. Returns 404 if the slug or CIK is unknown.
+     *
+     * The signature remains unknown for compatibility. Opt in to the exported
+     * PreviewResponse<InstitutionDetail> type to read data.positionsHeld, the full
+     * portfolio count excluding SOLD_OUT rows, even on a truncated holdings list.
      */
     getInstitutionDetail(slugOrCik: string): Promise<unknown>;
 }
@@ -4371,8 +4421,9 @@ declare class Stocks {
      *
      * Every identifier in the response is a slug, the same handle the metric and document
      * endpoints take, so a node can be passed straight to them. `depth` is 1 (default) or 2,
-     * `cap` limits the node count (1 to 200, default 75); out-of-range values are rejected
-     * with a 400. A ticker with no graph returns a `NotFoundError`.
+     * `cap` limits the number of non-root nodes (1 to 200, default 75); the root is always
+     * included in addition. Out-of-range values are rejected with a 400. A ticker with no
+     * graph returns a `NotFoundError`.
      */
     getGraph(ticker: string, options?: GetStockGraphOptions): Promise<StockGraph>;
     /**
@@ -4677,6 +4728,14 @@ declare class DeepHistoryUnavailableError extends SentiSenseError {
     retryAfter?: number;
     constructor(message: string, retryAfter?: number);
 }
+/**
+ * A 429. Check `code` to tell the two apart:
+ *
+ * - `"rate_limit_exceeded"`: the per-minute limit. The client retries it after `Retry-After`
+ *   before throwing, so you see this only once retries are used up.
+ * - `"quota_exceeded"`: the monthly request allowance is used up. It is thrown on the first
+ *   response without retrying, and `message` says when the allowance resets.
+ */
 declare class RateLimitError extends SentiSenseError {
     /**
      * Seconds to wait before retrying, from the server's `Retry-After` header, clamped to
@@ -4704,6 +4763,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.62.0";
+declare const VERSION = "0.63.1";
 
-export { type AISummary, APIError, type AnalystAction, type AnalystCall, type AnalystCalledItCall, type AnalystCalledItMove, type AnalystConsensus, type AnalystConsensusHistory, type AnalystConsensusHistoryPoint, type AnalystCoverage, type AnalystCoverageAnalyst, type AnalystCoverageBookEntry, type AnalystCoverageFirm, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatePeriodType, type AnalystEstimatesResponse, type AnalystFirmRating, type AnalystFirmTenure, type AnalystNote, type AnalystProfile, type AnalystRatingBuckets, type AnalystRef, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, DeepHistoryUnavailableError, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EarningsKpiHighlight, type EarningsOutcomeStatistics, type EarningsQuarter, type EarningsReaction, type EarningsReactionsResponse, type EarningsSource, type EarningsStatistics, type EarningsStatisticsBaseline, type EarningsStatisticsDeviation, type EarningsStatisticsThresholds, type EarningsStatisticsWindow, type EntitySearchResult, type EntitySearchType, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfQuote, type EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type ExtendedHoursInfo, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystCalledItOptions, type GetAnalystCallsOptions, type GetAnalystConsensusHistoryOptions, type GetAnalystCoverageOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsStatisticsOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticianMemberOptions, type GetPoliticiansOptions, type GetRankedEarningsOptions, type GetRecentEarningsOptions, type GetShortInterestOptions, type GetShortVolumeOptions, type GetStockGraphOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type GraphCounts, type GraphEdge, type GraphGroups, type GraphNode, type GraphProductFamily, type Holder, type HolderNotableChanges, type IndexConstituent, type IndexHistoryPoint, type IndexHistoryResponse, type IndexListResponse, type IndexListing, type IndexSnapshot, 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 MarketMoodOptions, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type OptionsAggregate, type OptionsCapabilities, type OptionsContext, type OptionsHighlight, type OptionsHistory, type OptionsHistoryWindow, type OptionsIntradayBoardCapability, type OptionsIntradayFlow, type OptionsOiFollowUp, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, type RankedEarnings, type RankedEarningsSection, type RankedReportedEarnings, type RankedUpcomingEarnings, RateLimitError, type RatingBase, type RatingDimension, type RatingDimensionKey, type RatingFlag, type RatingNotRatedReason, type RatingSubLeg, type RecentEarningsEntry, type RiskAdjustment, type RiskCondition, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, type SearchEntitiesOptions, type SearchStoriesOptions, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortInterestDataPoint, type ShortVolume, type ShortVolumeDataPoint, type SimilarStock, type StockDetail, type StockEntity, type StockGraph, type StockImage, type StockNotRated, type StockPrice, type StockProfile, type StockQuote, type StockRating, type StockRatingResponse, type StockSocialDominance, type Story, type StoryCluster, type StoryTimelineEntry, TemporarilyUnavailableError, 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 };
+export { type AISummary, APIError, type AnalystAction, type AnalystCall, type AnalystCalledItCall, type AnalystCalledItMove, type AnalystConsensus, type AnalystConsensusHistory, type AnalystConsensusHistoryPoint, type AnalystCoverage, type AnalystCoverageAnalyst, type AnalystCoverageBookEntry, type AnalystCoverageFirm, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatePeriodType, type AnalystEstimatesResponse, type AnalystFirmRating, type AnalystFirmTenure, type AnalystNote, type AnalystProfile, type AnalystRatingBuckets, type AnalystRef, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, DeepHistoryUnavailableError, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EarningsKpiHighlight, type EarningsOutcomeStatistics, type EarningsQuarter, type EarningsReaction, type EarningsReactionsResponse, type EarningsSource, type EarningsStatistics, type EarningsStatisticsBaseline, type EarningsStatisticsDeviation, type EarningsStatisticsThresholds, type EarningsStatisticsWindow, type EntitySearchResult, type EntitySearchType, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfQuote, type EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type ExtendedHoursInfo, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystCalledItOptions, type GetAnalystCallsOptions, type GetAnalystConsensusHistoryOptions, type GetAnalystCoverageOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsStatisticsOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticianMemberOptions, type GetPoliticiansOptions, type GetRankedEarningsOptions, type GetRecentEarningsOptions, type GetShortInterestOptions, type GetShortVolumeOptions, type GetStockGraphOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type GraphCounts, type GraphEdge, type GraphGroups, type GraphNode, type GraphProductFamily, type Holder, type HolderNotableChanges, type IndexConstituent, type IndexHistoryPoint, type IndexHistoryResponse, type IndexListResponse, type IndexListing, type IndexSnapshot, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionDetail, 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 MarketMoodOptions, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type OptionsAggregate, type OptionsCapabilities, type OptionsContext, type OptionsHighlight, type OptionsHistory, type OptionsHistoryWindow, type OptionsIntradayBoardCapability, type OptionsIntradayFlow, type OptionsOiFollowUp, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, type RankedEarnings, type RankedEarningsSection, type RankedReportedEarnings, type RankedUpcomingEarnings, RateLimitError, type RatingBase, type RatingDimension, type RatingDimensionKey, type RatingFlag, type RatingNotRatedReason, type RatingSubLeg, type RecentEarningsEntry, type RiskAdjustment, type RiskCondition, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, type SearchEntitiesOptions, type SearchStoriesOptions, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortInterestDataPoint, type ShortVolume, type ShortVolumeDataPoint, type SimilarStock, type StockDetail, type StockEntity, type StockGraph, type StockImage, type StockNotRated, type StockPrice, type StockProfile, type StockQuote, type StockRating, type StockRatingResponse, type StockSocialDominance, type Story, type StoryCluster, type StoryTimelineEntry, TemporarilyUnavailableError, 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.mjs

@@ -304,9 +304,11 @@ var Earnings = class {
    * management phrased it, and a summary of the earnings call.
    *
    * Branch on `isPreview`: a PRO key receives every hydrated quarter in full, a
-   * FREE key receives the latest quarter shaped rather than truncated, plus
-   * `totalCount`. {@link EarningsQuarter} documents which fields each tier
-   * carries.
+   * FREE key receives the latest quarter shaped rather than truncated.
+   * `totalCount` on the envelope counts indexed quarters on both tiers. The
+   * returned array can be shorter when a body is unavailable or limit cuts it.
+   * Older responses may omit the count. {@link EarningsQuarter} documents
+   * which fields each tier carries.
    *
    * A quarter typically appears within 48 hours of the company reporting, and
    * the call summary can arrive after the press-release content for the same
@@ -781,6 +783,10 @@ var Institutional = class {
    * Resolved by URL slug (e.g. `Berkshire-Hathaway`) or numeric SEC CIK.
    * Free users receive the profile and top 10 holdings; PRO users receive the
    * full holdings array. Returns 404 if the slug or CIK is unknown.
+   *
+   * The signature remains unknown for compatibility. Opt in to the exported
+   * PreviewResponse<InstitutionDetail> type to read data.positionsHeld, the full
+   * portfolio count excluding SOLD_OUT rows, even on a truncated holdings list.
    */
   async getInstitutionDetail(slugOrCik) {
     return this.client.get(
@@ -1053,8 +1059,9 @@ var Stocks = class {
    *
    * Every identifier in the response is a slug, the same handle the metric and document
    * endpoints take, so a node can be passed straight to them. `depth` is 1 (default) or 2,
-   * `cap` limits the node count (1 to 200, default 75); out-of-range values are rejected
-   * with a 400. A ticker with no graph returns a `NotFoundError`.
+   * `cap` limits the number of non-root nodes (1 to 200, default 75); the root is always
+   * included in addition. Out-of-range values are rejected with a 400. A ticker with no
+   * graph returns a `NotFoundError`.
    */
   async getGraph(ticker, options) {
     return this.client.get(
@@ -1352,7 +1359,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.62.0";
+var VERSION = "0.63.1";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -1364,6 +1371,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;
+var QUOTA_EXCEEDED_CODE = "quota_exceeded";
+async function isQuotaExceeded(response) {
+  try {
+    const body = await response.clone().json();
+    return body?.error === QUOTA_EXCEEDED_CODE;
+  } catch {
+    return false;
+  }
+}
 function clampRetryAfter(raw, maxWaitS) {
   if (!raw) return void 0;
   const parsed = Number(raw);
@@ -1449,6 +1465,9 @@ var SentiSense = class {
           );
         }
         if (!response.ok) {
+          if (response.status === 429 && await isQuotaExceeded(response)) {
+            await this.handleErrorResponse(response);
+          }
           const isRetryable = response.status === 429 || response.status >= 500;
           if (isRetryable && attempt < this.maxRetries) {
             if (response.status === 429 || response.status === 503) {