sentisense 0.68.0 → 0.69.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -134,6 +134,16 @@ interface StockSocialDominance {
134
134
  rank: number;
135
135
  percentile: number;
136
136
  }
137
+ /**
138
+ * One separately listed share class of a company, as carried in `shareClasses`
139
+ * on {@link StockProfile} and on the primary class's {@link StockDetail} row.
140
+ */
141
+ interface ShareClass {
142
+ /** The class's ticker, e.g. `"BRK.A"`. */
143
+ ticker: string;
144
+ /** `true` for the company's primary class, which is always listed first. */
145
+ primary: boolean;
146
+ }
137
147
  /**
138
148
  * Stock with company name and entity metadata.
139
149
  *
@@ -156,6 +166,12 @@ interface StockDetail {
156
166
  /** Brand hex colour. Null for roughly two thirds of the universe. */
157
167
  brandColor?: string | null;
158
168
  socialDominance?: StockSocialDominance | null;
169
+ /**
170
+ * Present only on the row of a company whose separately listed classes are tracked
171
+ * as one company: every class, primary first (the `GOOGL` row lists `GOOGL` then
172
+ * `GOOG`). Those other classes have no row of their own. Absent on every other row.
173
+ */
174
+ shareClasses?: ShareClass[];
159
175
  }
160
176
  interface SimilarStock {
161
177
  symbol: string;
@@ -193,6 +209,12 @@ interface StockProfile {
193
209
  * assigned, and for ordinary stocks.
194
210
  */
195
211
  imageUrl?: string | null;
212
+ /**
213
+ * Every separately listed class of a multi-class company, primary first: `GOOGL`
214
+ * then `GOOG`, `BRK.B` then `BRK.A`, `ZG` then `Z`. The same whichever class you
215
+ * request. Absent for a single-class company and for ETFs.
216
+ */
217
+ shareClasses?: ShareClass[];
196
218
  [key: string]: unknown;
197
219
  }
198
220
  /**
@@ -1888,6 +1910,96 @@ interface GetHoldersOptions {
1888
1910
  /** Sort direction. Server default is `"desc"`. Requires `limit`. */
1889
1911
  sortDir?: "asc" | "desc";
1890
1912
  }
1913
+ /** Options for `institutional.getHoldersHistory`. */
1914
+ interface GetHoldersHistoryOptions {
1915
+ /**
1916
+ * How many of the newest quarters to cover. Server default is 12; values above 20 are
1917
+ * capped server-side, and values below 1 are rejected with a 400.
1918
+ */
1919
+ quarters?: number;
1920
+ }
1921
+ /**
1922
+ * One quarter of a stock's 13F ownership history.
1923
+ *
1924
+ * `holderCount` and the share and value totals roll multi-filer managers up into one holder
1925
+ * the same way `institutional.getHolders()` does, so a settled quarter here agrees with that
1926
+ * quarter's holders response. The flow fields repeat the `institutional.getFlows()`
1927
+ * arithmetic for this one ticker.
1928
+ *
1929
+ * A quarter with `status` `"filing"` holds only the institutions that have filed so far, so
1930
+ * its counts and totals are partial.
1931
+ */
1932
+ interface HoldersHistoryQuarter {
1933
+ /** Quarter end, ISO date (`YYYY-MM-DD`). */
1934
+ reportDate: string;
1935
+ /** Quarter id in `YYYYQN` form, e.g. `"2026Q2"`. */
1936
+ value: string;
1937
+ /** Display label, e.g. `"Q2 2026"`. */
1938
+ label: string;
1939
+ /** `settled` once the quarter's filing deadline has passed, `filing` before. */
1940
+ status: "settled" | "filing" | (string & {});
1941
+ /** True while `status` is `filing`; same rule as {@link Quarter.pending}. */
1942
+ pending: boolean;
1943
+ /** Institutional holders, with multi-filer managers counted once. */
1944
+ holderCount: number;
1945
+ /** Shares held by all reporting institutions. */
1946
+ totalInstitutionalShares: number;
1947
+ /** Reported value of those shares, in US dollars. */
1948
+ totalInstitutionalValue: number;
1949
+ /**
1950
+ * The share class's shares outstanding as last filed on the day the quarter settles
1951
+ * (today, while it is still filing). Absent for ADRs and other unsupported security
1952
+ * types, when no dated per-class count exists, or when institutions report more than
1953
+ * 150% of it, which signals a unit mismatch.
1954
+ */
1955
+ sharesOutstanding?: number;
1956
+ /**
1957
+ * `totalInstitutionalShares` as a percent of `sharesOutstanding` (`84.94` means 84.94%).
1958
+ * Can pass 100 because lent shares are reported by both lender and buyer. Absent
1959
+ * whenever `sharesOutstanding` is.
1960
+ */
1961
+ institutionalOwnershipPct?: number;
1962
+ /** Shares bought minus shares sold over the quarter, summed across filers. */
1963
+ netSharesChange: number;
1964
+ /** Sum of share increases across filers that added or opened a position. */
1965
+ totalSharesBought: number;
1966
+ /**
1967
+ * Sum of share decreases across filers that trimmed or reported a zero position, as a
1968
+ * positive number.
1969
+ */
1970
+ totalSharesSold: number;
1971
+ /** Filer positions opened this quarter. */
1972
+ newPositions: number;
1973
+ /** Filer positions added to. */
1974
+ increasedPositions: number;
1975
+ /** Filer positions trimmed. */
1976
+ decreasedPositions: number;
1977
+ /**
1978
+ * Filers that reported this position at zero shares. A filer that leaves the position out
1979
+ * of its filing entirely is not counted here.
1980
+ */
1981
+ soldOutPositions: number;
1982
+ /** The quarter's average closing price, in US dollars. Absent when the quarter is unpriced. */
1983
+ avgClosePrice?: number;
1984
+ /**
1985
+ * `netSharesChange * avgClosePrice`, in US dollars. Absent when `avgClosePrice` is,
1986
+ * never a stand-in zero.
1987
+ */
1988
+ dollarFlowUsd?: number;
1989
+ }
1990
+ /**
1991
+ * A stock's 13F ownership by quarter, newest first: the `data` payload of
1992
+ * `institutional.getHoldersHistory()`, which returns `PreviewResponse<HoldersHistory>`.
1993
+ *
1994
+ * Quarters with no holdings for the security, such as those before it listed, are omitted,
1995
+ * so `quarters` can be shorter than the window you asked for and is empty for a ticker with
1996
+ * no 13F coverage.
1997
+ */
1998
+ interface HoldersHistory {
1999
+ /** The security answered for, in SentiSense's spelling (`BRK.B`, `GOOG`). */
2000
+ ticker: string;
2001
+ quarters: HoldersHistoryQuarter[];
2002
+ }
1891
2003
  /**
1892
2004
  * Optional wire keys inside an institution detail's preview envelope.
1893
2005
  * Opt in with PreviewResponse<InstitutionDetail>; getInstitutionDetail retains
@@ -2481,6 +2593,18 @@ interface RankedEarnings {
2481
2593
  reported: RankedEarningsSection<RankedReportedEarnings>;
2482
2594
  upcoming: RankedEarningsSection<RankedUpcomingEarnings>;
2483
2595
  }
2596
+ /**
2597
+ * The response of `earnings.getSummaries()`: the usual {@link PreviewResponse}
2598
+ * envelope over a quarter array, plus the envelope `ticker`.
2599
+ */
2600
+ interface EarningsSummariesResponse extends PreviewResponse<EarningsQuarter[]> {
2601
+ /**
2602
+ * The listing the quarters' per-share figures (such as EPS highlights) are quoted
2603
+ * for. Summaries are stored under a company's primary share class, so `BRK-A`
2604
+ * answers `"BRK.B"` and `GOOG` answers `"GOOGL"`. Absent on older responses.
2605
+ */
2606
+ ticker?: string;
2607
+ }
2484
2608
  interface GetEarningsSummariesOptions {
2485
2609
  /**
2486
2610
  * Max quarters returned, 1 to 40. Omitted, the API applies its own default
@@ -3530,6 +3654,12 @@ interface AnalystEarningsSurprise {
3530
3654
  [key: string]: unknown;
3531
3655
  }
3532
3656
  interface AnalystEstimatesResponse {
3657
+ /**
3658
+ * The listing the per-share figures are quoted for. Estimates are stored under a
3659
+ * company's primary share class, so `BRK-A` answers `"BRK.B"` and `GOOG` answers
3660
+ * `"GOOGL"`. Absent on older responses.
3661
+ */
3662
+ ticker?: string;
3533
3663
  estimates: AnalystEstimate[];
3534
3664
  surprises: AnalystEarningsSurprise[];
3535
3665
  }
@@ -3938,9 +4068,12 @@ declare class Earnings {
3938
4068
  * assuming a fixed lag. A ticker with no stored quarter answers with an empty
3939
4069
  * `data` array, not a 404.
3940
4070
  *
4071
+ * The envelope `ticker` names the listing the per-share figures are quoted
4072
+ * for: `"BRK.B"` for `BRK-A`, `"GOOGL"` for `GOOG`.
4073
+ *
3941
4074
  * Use canonical ticker symbols: `GOOGL` (not `GOOG`), `BRK.B` (not `BRK-B`).
3942
4075
  */
3943
- getSummaries(ticker: string, options?: GetEarningsSummariesOptions): Promise<PreviewResponse<EarningsQuarter[]>>;
4076
+ getSummaries(ticker: string, options?: GetEarningsSummariesOptions): Promise<EarningsSummariesResponse>;
3944
4077
  /**
3945
4078
  * Which covered companies reported on or after `today - days`, newest first.
3946
4079
  *
@@ -4471,6 +4604,29 @@ declare class Institutional {
4471
4604
  * change figures.
4472
4605
  */
4473
4606
  getHolders(ticker: string, reportDate?: string, options?: GetHoldersOptions): Promise<PreviewResponse<TickerHolders>>;
4607
+ /**
4608
+ * Get a stock's institutional ownership quarter by quarter, newest first.
4609
+ *
4610
+ * Returns the preview envelope wrapping a {@link HoldersHistory} object, so the rows are
4611
+ * two levels down: `(await getHoldersHistory(t)).data.quarters`. Each row carries the
4612
+ * holder count, the share of the class institutions held (`institutionalOwnershipPct`),
4613
+ * and the quarter's net shares bought or sold, dollar flow and position counts.
4614
+ *
4615
+ * The newest quarter can still be filing (`status: "filing"`), in which case its figures
4616
+ * cover only the institutions that have filed so far. Quarters in which the security had
4617
+ * no holdings are omitted.
4618
+ *
4619
+ * Free keys receive the newest four quarters with `isPreview: true` and `totalCount`
4620
+ * holding the number of quarters in the full window. PRO receives the whole window
4621
+ * without `totalCount`.
4622
+ *
4623
+ * Share classes are answered separately (`GOOG` and `GOOGL`, `BRK.A` and `BRK.B`).
4624
+ *
4625
+ * @example
4626
+ * const { data } = await client.institutional.getHoldersHistory("AAPL", { quarters: 8 });
4627
+ * for (const q of data.quarters) console.log(q.label, q.status, q.institutionalOwnershipPct);
4628
+ */
4629
+ getHoldersHistory(ticker: string, options?: GetHoldersHistoryOptions): Promise<PreviewResponse<HoldersHistory>>;
4474
4630
  /**
4475
4631
  * Get activist investor positions (NEW or INCREASED).
4476
4632
  *
@@ -5133,6 +5289,6 @@ declare class APIError extends SentiSenseError {
5133
5289
  constructor(message: string, status: number, code?: string);
5134
5290
  }
5135
5291
 
5136
- declare const VERSION = "0.68.0";
5292
+ declare const VERSION = "0.69.0";
5137
5293
 
5138
- 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 EarlyFilers, 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 GetOptionsIntradayHistoryOptions, 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 HolderComparisonStatus, 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 NotableHolder, type OptionsAggregate, type OptionsCapabilities, type OptionsContext, type OptionsHighlight, type OptionsHistory, type OptionsHistoryWindow, type OptionsIntradayBoardCapability, type OptionsIntradayFlow, type OptionsIntradayHistory, type OptionsIntradayPoint, type OptionsOiFollowUp, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type OwnershipSelection, 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 };
5294
+ 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 EarlyFilers, 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 EarningsSummariesResponse, 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 GetHoldersHistoryOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, type GetOptionsIntradayHistoryOptions, 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 HolderComparisonStatus, type HolderNotableChanges, type HoldersHistory, type HoldersHistoryQuarter, 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 NotableHolder, type OptionsAggregate, type OptionsCapabilities, type OptionsContext, type OptionsHighlight, type OptionsHistory, type OptionsHistoryWindow, type OptionsIntradayBoardCapability, type OptionsIntradayFlow, type OptionsIntradayHistory, type OptionsIntradayPoint, type OptionsOiFollowUp, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type OwnershipSelection, 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 ShareClass, 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 CHANGED
@@ -134,6 +134,16 @@ interface StockSocialDominance {
134
134
  rank: number;
135
135
  percentile: number;
136
136
  }
137
+ /**
138
+ * One separately listed share class of a company, as carried in `shareClasses`
139
+ * on {@link StockProfile} and on the primary class's {@link StockDetail} row.
140
+ */
141
+ interface ShareClass {
142
+ /** The class's ticker, e.g. `"BRK.A"`. */
143
+ ticker: string;
144
+ /** `true` for the company's primary class, which is always listed first. */
145
+ primary: boolean;
146
+ }
137
147
  /**
138
148
  * Stock with company name and entity metadata.
139
149
  *
@@ -156,6 +166,12 @@ interface StockDetail {
156
166
  /** Brand hex colour. Null for roughly two thirds of the universe. */
157
167
  brandColor?: string | null;
158
168
  socialDominance?: StockSocialDominance | null;
169
+ /**
170
+ * Present only on the row of a company whose separately listed classes are tracked
171
+ * as one company: every class, primary first (the `GOOGL` row lists `GOOGL` then
172
+ * `GOOG`). Those other classes have no row of their own. Absent on every other row.
173
+ */
174
+ shareClasses?: ShareClass[];
159
175
  }
160
176
  interface SimilarStock {
161
177
  symbol: string;
@@ -193,6 +209,12 @@ interface StockProfile {
193
209
  * assigned, and for ordinary stocks.
194
210
  */
195
211
  imageUrl?: string | null;
212
+ /**
213
+ * Every separately listed class of a multi-class company, primary first: `GOOGL`
214
+ * then `GOOG`, `BRK.B` then `BRK.A`, `ZG` then `Z`. The same whichever class you
215
+ * request. Absent for a single-class company and for ETFs.
216
+ */
217
+ shareClasses?: ShareClass[];
196
218
  [key: string]: unknown;
197
219
  }
198
220
  /**
@@ -1888,6 +1910,96 @@ interface GetHoldersOptions {
1888
1910
  /** Sort direction. Server default is `"desc"`. Requires `limit`. */
1889
1911
  sortDir?: "asc" | "desc";
1890
1912
  }
1913
+ /** Options for `institutional.getHoldersHistory`. */
1914
+ interface GetHoldersHistoryOptions {
1915
+ /**
1916
+ * How many of the newest quarters to cover. Server default is 12; values above 20 are
1917
+ * capped server-side, and values below 1 are rejected with a 400.
1918
+ */
1919
+ quarters?: number;
1920
+ }
1921
+ /**
1922
+ * One quarter of a stock's 13F ownership history.
1923
+ *
1924
+ * `holderCount` and the share and value totals roll multi-filer managers up into one holder
1925
+ * the same way `institutional.getHolders()` does, so a settled quarter here agrees with that
1926
+ * quarter's holders response. The flow fields repeat the `institutional.getFlows()`
1927
+ * arithmetic for this one ticker.
1928
+ *
1929
+ * A quarter with `status` `"filing"` holds only the institutions that have filed so far, so
1930
+ * its counts and totals are partial.
1931
+ */
1932
+ interface HoldersHistoryQuarter {
1933
+ /** Quarter end, ISO date (`YYYY-MM-DD`). */
1934
+ reportDate: string;
1935
+ /** Quarter id in `YYYYQN` form, e.g. `"2026Q2"`. */
1936
+ value: string;
1937
+ /** Display label, e.g. `"Q2 2026"`. */
1938
+ label: string;
1939
+ /** `settled` once the quarter's filing deadline has passed, `filing` before. */
1940
+ status: "settled" | "filing" | (string & {});
1941
+ /** True while `status` is `filing`; same rule as {@link Quarter.pending}. */
1942
+ pending: boolean;
1943
+ /** Institutional holders, with multi-filer managers counted once. */
1944
+ holderCount: number;
1945
+ /** Shares held by all reporting institutions. */
1946
+ totalInstitutionalShares: number;
1947
+ /** Reported value of those shares, in US dollars. */
1948
+ totalInstitutionalValue: number;
1949
+ /**
1950
+ * The share class's shares outstanding as last filed on the day the quarter settles
1951
+ * (today, while it is still filing). Absent for ADRs and other unsupported security
1952
+ * types, when no dated per-class count exists, or when institutions report more than
1953
+ * 150% of it, which signals a unit mismatch.
1954
+ */
1955
+ sharesOutstanding?: number;
1956
+ /**
1957
+ * `totalInstitutionalShares` as a percent of `sharesOutstanding` (`84.94` means 84.94%).
1958
+ * Can pass 100 because lent shares are reported by both lender and buyer. Absent
1959
+ * whenever `sharesOutstanding` is.
1960
+ */
1961
+ institutionalOwnershipPct?: number;
1962
+ /** Shares bought minus shares sold over the quarter, summed across filers. */
1963
+ netSharesChange: number;
1964
+ /** Sum of share increases across filers that added or opened a position. */
1965
+ totalSharesBought: number;
1966
+ /**
1967
+ * Sum of share decreases across filers that trimmed or reported a zero position, as a
1968
+ * positive number.
1969
+ */
1970
+ totalSharesSold: number;
1971
+ /** Filer positions opened this quarter. */
1972
+ newPositions: number;
1973
+ /** Filer positions added to. */
1974
+ increasedPositions: number;
1975
+ /** Filer positions trimmed. */
1976
+ decreasedPositions: number;
1977
+ /**
1978
+ * Filers that reported this position at zero shares. A filer that leaves the position out
1979
+ * of its filing entirely is not counted here.
1980
+ */
1981
+ soldOutPositions: number;
1982
+ /** The quarter's average closing price, in US dollars. Absent when the quarter is unpriced. */
1983
+ avgClosePrice?: number;
1984
+ /**
1985
+ * `netSharesChange * avgClosePrice`, in US dollars. Absent when `avgClosePrice` is,
1986
+ * never a stand-in zero.
1987
+ */
1988
+ dollarFlowUsd?: number;
1989
+ }
1990
+ /**
1991
+ * A stock's 13F ownership by quarter, newest first: the `data` payload of
1992
+ * `institutional.getHoldersHistory()`, which returns `PreviewResponse<HoldersHistory>`.
1993
+ *
1994
+ * Quarters with no holdings for the security, such as those before it listed, are omitted,
1995
+ * so `quarters` can be shorter than the window you asked for and is empty for a ticker with
1996
+ * no 13F coverage.
1997
+ */
1998
+ interface HoldersHistory {
1999
+ /** The security answered for, in SentiSense's spelling (`BRK.B`, `GOOG`). */
2000
+ ticker: string;
2001
+ quarters: HoldersHistoryQuarter[];
2002
+ }
1891
2003
  /**
1892
2004
  * Optional wire keys inside an institution detail's preview envelope.
1893
2005
  * Opt in with PreviewResponse<InstitutionDetail>; getInstitutionDetail retains
@@ -2481,6 +2593,18 @@ interface RankedEarnings {
2481
2593
  reported: RankedEarningsSection<RankedReportedEarnings>;
2482
2594
  upcoming: RankedEarningsSection<RankedUpcomingEarnings>;
2483
2595
  }
2596
+ /**
2597
+ * The response of `earnings.getSummaries()`: the usual {@link PreviewResponse}
2598
+ * envelope over a quarter array, plus the envelope `ticker`.
2599
+ */
2600
+ interface EarningsSummariesResponse extends PreviewResponse<EarningsQuarter[]> {
2601
+ /**
2602
+ * The listing the quarters' per-share figures (such as EPS highlights) are quoted
2603
+ * for. Summaries are stored under a company's primary share class, so `BRK-A`
2604
+ * answers `"BRK.B"` and `GOOG` answers `"GOOGL"`. Absent on older responses.
2605
+ */
2606
+ ticker?: string;
2607
+ }
2484
2608
  interface GetEarningsSummariesOptions {
2485
2609
  /**
2486
2610
  * Max quarters returned, 1 to 40. Omitted, the API applies its own default
@@ -3530,6 +3654,12 @@ interface AnalystEarningsSurprise {
3530
3654
  [key: string]: unknown;
3531
3655
  }
3532
3656
  interface AnalystEstimatesResponse {
3657
+ /**
3658
+ * The listing the per-share figures are quoted for. Estimates are stored under a
3659
+ * company's primary share class, so `BRK-A` answers `"BRK.B"` and `GOOG` answers
3660
+ * `"GOOGL"`. Absent on older responses.
3661
+ */
3662
+ ticker?: string;
3533
3663
  estimates: AnalystEstimate[];
3534
3664
  surprises: AnalystEarningsSurprise[];
3535
3665
  }
@@ -3938,9 +4068,12 @@ declare class Earnings {
3938
4068
  * assuming a fixed lag. A ticker with no stored quarter answers with an empty
3939
4069
  * `data` array, not a 404.
3940
4070
  *
4071
+ * The envelope `ticker` names the listing the per-share figures are quoted
4072
+ * for: `"BRK.B"` for `BRK-A`, `"GOOGL"` for `GOOG`.
4073
+ *
3941
4074
  * Use canonical ticker symbols: `GOOGL` (not `GOOG`), `BRK.B` (not `BRK-B`).
3942
4075
  */
3943
- getSummaries(ticker: string, options?: GetEarningsSummariesOptions): Promise<PreviewResponse<EarningsQuarter[]>>;
4076
+ getSummaries(ticker: string, options?: GetEarningsSummariesOptions): Promise<EarningsSummariesResponse>;
3944
4077
  /**
3945
4078
  * Which covered companies reported on or after `today - days`, newest first.
3946
4079
  *
@@ -4471,6 +4604,29 @@ declare class Institutional {
4471
4604
  * change figures.
4472
4605
  */
4473
4606
  getHolders(ticker: string, reportDate?: string, options?: GetHoldersOptions): Promise<PreviewResponse<TickerHolders>>;
4607
+ /**
4608
+ * Get a stock's institutional ownership quarter by quarter, newest first.
4609
+ *
4610
+ * Returns the preview envelope wrapping a {@link HoldersHistory} object, so the rows are
4611
+ * two levels down: `(await getHoldersHistory(t)).data.quarters`. Each row carries the
4612
+ * holder count, the share of the class institutions held (`institutionalOwnershipPct`),
4613
+ * and the quarter's net shares bought or sold, dollar flow and position counts.
4614
+ *
4615
+ * The newest quarter can still be filing (`status: "filing"`), in which case its figures
4616
+ * cover only the institutions that have filed so far. Quarters in which the security had
4617
+ * no holdings are omitted.
4618
+ *
4619
+ * Free keys receive the newest four quarters with `isPreview: true` and `totalCount`
4620
+ * holding the number of quarters in the full window. PRO receives the whole window
4621
+ * without `totalCount`.
4622
+ *
4623
+ * Share classes are answered separately (`GOOG` and `GOOGL`, `BRK.A` and `BRK.B`).
4624
+ *
4625
+ * @example
4626
+ * const { data } = await client.institutional.getHoldersHistory("AAPL", { quarters: 8 });
4627
+ * for (const q of data.quarters) console.log(q.label, q.status, q.institutionalOwnershipPct);
4628
+ */
4629
+ getHoldersHistory(ticker: string, options?: GetHoldersHistoryOptions): Promise<PreviewResponse<HoldersHistory>>;
4474
4630
  /**
4475
4631
  * Get activist investor positions (NEW or INCREASED).
4476
4632
  *
@@ -5133,6 +5289,6 @@ declare class APIError extends SentiSenseError {
5133
5289
  constructor(message: string, status: number, code?: string);
5134
5290
  }
5135
5291
 
5136
- declare const VERSION = "0.68.0";
5292
+ declare const VERSION = "0.69.0";
5137
5293
 
5138
- 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 EarlyFilers, 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 GetOptionsIntradayHistoryOptions, 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 HolderComparisonStatus, 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 NotableHolder, type OptionsAggregate, type OptionsCapabilities, type OptionsContext, type OptionsHighlight, type OptionsHistory, type OptionsHistoryWindow, type OptionsIntradayBoardCapability, type OptionsIntradayFlow, type OptionsIntradayHistory, type OptionsIntradayPoint, type OptionsOiFollowUp, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type OwnershipSelection, 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 };
5294
+ 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 EarlyFilers, 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 EarningsSummariesResponse, 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 GetHoldersHistoryOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, type GetOptionsIntradayHistoryOptions, 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 HolderComparisonStatus, type HolderNotableChanges, type HoldersHistory, type HoldersHistoryQuarter, 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 NotableHolder, type OptionsAggregate, type OptionsCapabilities, type OptionsContext, type OptionsHighlight, type OptionsHistory, type OptionsHistoryWindow, type OptionsIntradayBoardCapability, type OptionsIntradayFlow, type OptionsIntradayHistory, type OptionsIntradayPoint, type OptionsOiFollowUp, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type OwnershipSelection, 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 ShareClass, 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 CHANGED
@@ -316,6 +316,9 @@ var Earnings = class {
316
316
  * assuming a fixed lag. A ticker with no stored quarter answers with an empty
317
317
  * `data` array, not a 404.
318
318
  *
319
+ * The envelope `ticker` names the listing the per-share figures are quoted
320
+ * for: `"BRK.B"` for `BRK-A`, `"GOOGL"` for `GOOG`.
321
+ *
319
322
  * Use canonical ticker symbols: `GOOGL` (not `GOOG`), `BRK.B` (not `BRK-B`).
320
323
  */
321
324
  async getSummaries(ticker, options) {
@@ -768,6 +771,34 @@ var Institutional = class {
768
771
  { reportDate, ...options }
769
772
  );
770
773
  }
774
+ /**
775
+ * Get a stock's institutional ownership quarter by quarter, newest first.
776
+ *
777
+ * Returns the preview envelope wrapping a {@link HoldersHistory} object, so the rows are
778
+ * two levels down: `(await getHoldersHistory(t)).data.quarters`. Each row carries the
779
+ * holder count, the share of the class institutions held (`institutionalOwnershipPct`),
780
+ * and the quarter's net shares bought or sold, dollar flow and position counts.
781
+ *
782
+ * The newest quarter can still be filing (`status: "filing"`), in which case its figures
783
+ * cover only the institutions that have filed so far. Quarters in which the security had
784
+ * no holdings are omitted.
785
+ *
786
+ * Free keys receive the newest four quarters with `isPreview: true` and `totalCount`
787
+ * holding the number of quarters in the full window. PRO receives the whole window
788
+ * without `totalCount`.
789
+ *
790
+ * Share classes are answered separately (`GOOG` and `GOOGL`, `BRK.A` and `BRK.B`).
791
+ *
792
+ * @example
793
+ * const { data } = await client.institutional.getHoldersHistory("AAPL", { quarters: 8 });
794
+ * for (const q of data.quarters) console.log(q.label, q.status, q.institutionalOwnershipPct);
795
+ */
796
+ async getHoldersHistory(ticker, options) {
797
+ return this.client.get(
798
+ `/api/v1/institutional/holders/${encodeURIComponent(ticker)}/history`,
799
+ { ...options }
800
+ );
801
+ }
771
802
  /**
772
803
  * Get activist investor positions (NEW or INCREASED).
773
804
  *
@@ -1406,7 +1437,7 @@ var Trackers = class {
1406
1437
  };
1407
1438
 
1408
1439
  // src/version.ts
1409
- var VERSION = "0.68.0";
1440
+ var VERSION = "0.69.0";
1410
1441
 
1411
1442
  // src/client.ts
1412
1443
  var DEFAULT_BASE_URL = "https://app.sentisense.ai";