sentisense 0.66.0 → 0.67.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
@@ -796,6 +796,28 @@ interface OptionsOiWalls {
796
796
  maxPain?: number;
797
797
  callWalls?: OptionsWall[];
798
798
  putWalls?: OptionsWall[];
799
+ /**
800
+ * Call open interest summed across every strike of the expiry, when present. Omitted on
801
+ * snapshots built before the field existed.
802
+ */
803
+ totalCallOi?: number;
804
+ /**
805
+ * Put open interest summed across every strike of the expiry, when present. Omitted on
806
+ * snapshots built before the field existed.
807
+ */
808
+ totalPutOi?: number;
809
+ /**
810
+ * Call open interest at the `maxPain` strike, when present, even when that strike is not
811
+ * one of the walls. `0` when no calls are open there; omitted on snapshots built before
812
+ * the field existed.
813
+ */
814
+ maxPainCallOi?: number;
815
+ /**
816
+ * Put open interest at the `maxPain` strike, when present, even when that strike is not
817
+ * one of the walls. `0` when no puts are open there; omitted on snapshots built before
818
+ * the field existed.
819
+ */
820
+ maxPainPutOi?: number;
799
821
  }
800
822
  /** A contract whose session volume far exceeds its open interest: fresh positioning. */
801
823
  interface OptionsUnusualContract {
@@ -1565,8 +1587,9 @@ interface Quarter {
1565
1587
  label: string;
1566
1588
  reportDate: string;
1567
1589
  /**
1568
- * True while this quarter's 13F filing window is still open, which is the 45 days after
1569
- * quarter end.
1590
+ * True while this quarter's 13F filing window is still open: through the effective SEC
1591
+ * filing deadline day in New York, which is 45 days after quarter end rolled past
1592
+ * weekends and federal holidays.
1570
1593
  *
1571
1594
  * Read it before you pick a quarter to query. The list leads with the current quarter, so
1572
1595
  * the newest entry is pending for six weeks of every quarter, and a holders request against
@@ -1578,6 +1601,19 @@ interface Quarter {
1578
1601
  * every row.
1579
1602
  */
1580
1603
  pending?: boolean;
1604
+ /**
1605
+ * True from the New York calendar day after the effective SEC filing deadline. It does
1606
+ * not certify that every institution filed.
1607
+ *
1608
+ * Typed optional so existing object literals keep compiling; the API sends the key on
1609
+ * every row.
1610
+ */
1611
+ ownershipEligible?: boolean;
1612
+ /**
1613
+ * ISO date (New York calendar day) on which the quarter becomes eligible: the day after
1614
+ * the effective filing deadline.
1615
+ */
1616
+ ownershipEligibleAt?: string;
1581
1617
  }
1582
1618
  interface InstitutionalFlow {
1583
1619
  ticker: string;
@@ -1637,6 +1673,82 @@ interface Holder {
1637
1673
  * read it as "1 or unknown" rather than zero.
1638
1674
  */
1639
1675
  cikCount?: number | null;
1676
+ /**
1677
+ * Whether this row's quarter-over-quarter change is backed by a complete comparison.
1678
+ * Only `AVAILABLE` supports a change claim for this holder; the legacy change fields
1679
+ * (`changeType`, `sharesChange`, `sharesChangePct`) can still be present under the other
1680
+ * statuses. Check it per row: a holder can be `AVAILABLE` while the response-level
1681
+ * {@link TickerHolders.comparisonStatus} summary reads incomplete.
1682
+ */
1683
+ comparisonStatus?: HolderComparisonStatus;
1684
+ }
1685
+ /**
1686
+ * Comparison status for quarter-over-quarter share changes, on the holders response and on
1687
+ * each holder row. Only `AVAILABLE` supports a change claim.
1688
+ */
1689
+ type HolderComparisonStatus = "AVAILABLE" | "PRIOR_QUARTER_UNAVAILABLE" | "INCOMPLETE_INPUT" | "INCOMPLETE_FAMILY_COVERAGE" | "UNAVAILABLE" | (string & {});
1690
+ /**
1691
+ * How `institutional.getHolders()` chose the quarter it answered.
1692
+ */
1693
+ interface OwnershipSelection {
1694
+ /** `EXPLICIT` when the request named a `reportDate`, `DEFAULT` when the server chose. */
1695
+ mode: "DEFAULT" | "EXPLICIT" | (string & {});
1696
+ /** `settled` once the quarter's filing deadline has passed, `filing` before that. */
1697
+ status: "settled" | "filing" | (string & {});
1698
+ /** Identifier of the quarter-selection rule, e.g. `"v2-sec-deadline-next-day"`. */
1699
+ policyVersion: string;
1700
+ /** The newest eligible quarter across the market (ISO date). */
1701
+ marketDefaultReportDate?: string;
1702
+ /**
1703
+ * True when this response is for an older quarter than `marketDefaultReportDate`. An
1704
+ * explicit `reportDate` is still the quarter you asked for.
1705
+ */
1706
+ isStaleForMarket: boolean;
1707
+ }
1708
+ /**
1709
+ * A newer quarter that is still filing for this ticker, reported beside the selected
1710
+ * quarter rather than mixed into its holder rows.
1711
+ */
1712
+ interface EarlyFilers {
1713
+ /** Quarter end of the filing quarter (ISO date). */
1714
+ reportDate: string;
1715
+ /** Always `filing`. */
1716
+ status: "filing" | (string & {});
1717
+ /** Holder families with a positive position in this ticker so far. */
1718
+ holderCount: number;
1719
+ /** Distinct filers that have reported for the newer quarter, market-wide. */
1720
+ distinctFilerCount: number;
1721
+ /** Distinct filers in the selected settled quarter, market-wide, as a baseline. */
1722
+ baselineFilerCount: number;
1723
+ /**
1724
+ * Share of this ticker's selected-quarter institutional value held by filers confirmed
1725
+ * to have filed for the newer quarter, including filers that have since exited the
1726
+ * ticker, as a percentage. Omitted when filing presence or the baseline value is
1727
+ * unavailable or does not reconcile.
1728
+ */
1729
+ coveragePct?: number;
1730
+ }
1731
+ /**
1732
+ * A well-known institution matched against the selected quarter's full roster. Free keys
1733
+ * receive identifiers only; PRO also receives the position and change fields.
1734
+ */
1735
+ interface NotableHolder {
1736
+ filerCik: string;
1737
+ filerName: string;
1738
+ /** URL slug for `institutional.getInstitutionDetail()`, or null when unmapped. */
1739
+ entitySlug?: string | null;
1740
+ /** PRO only. */
1741
+ shares?: number;
1742
+ /** PRO only. */
1743
+ valueUsd?: number;
1744
+ /** PRO only. */
1745
+ changeType?: "NEW" | "INCREASED" | "DECREASED" | "SOLD_OUT" | "UNCHANGED";
1746
+ /** PRO only. */
1747
+ sharesChange?: number;
1748
+ /** PRO only. Omitted on a `NEW` position, which has no prior-position baseline. */
1749
+ sharesChangePct?: number;
1750
+ /** PRO only. Only `AVAILABLE` supports a quarter-change claim for this holder. */
1751
+ comparisonStatus?: HolderComparisonStatus;
1640
1752
  }
1641
1753
  /**
1642
1754
  * A server-side shortlist of the quarter's significant position changes, so a caller
@@ -1662,7 +1774,18 @@ interface HolderNotableChanges {
1662
1774
  interface TickerHolders {
1663
1775
  ticker: string;
1664
1776
  companyName: string;
1777
+ /** The quarter actually served (ISO date). */
1665
1778
  reportDate: string;
1779
+ /** How the quarter was chosen, and whether it trails the market's newest eligible one. */
1780
+ selection?: OwnershipSelection;
1781
+ /**
1782
+ * `AVAILABLE` when `earlyFilers` is present, `NONE` when no newer filing quarter is
1783
+ * observed, `UNAVAILABLE` when that supplementary read failed. The selected quarter's
1784
+ * holders are served either way.
1785
+ */
1786
+ earlyFilersStatus?: "AVAILABLE" | "NONE" | "UNAVAILABLE" | (string & {});
1787
+ /** A newer quarter still filing for this ticker. Sent only when `earlyFilersStatus` is `AVAILABLE`. */
1788
+ earlyFilers?: EarlyFilers;
1666
1789
  totalInstitutionalShares: number;
1667
1790
  totalInstitutionalValue: number;
1668
1791
  /** Every institutional holder of this ticker for the quarter, ignoring any paging. */
@@ -1684,6 +1807,26 @@ interface TickerHolders {
1684
1807
  * passed `limit`, since it exists to spare a paging caller a full scan.
1685
1808
  */
1686
1809
  notableChanges?: HolderNotableChanges;
1810
+ /**
1811
+ * Well-known institutions holding a positive position, matched against the selected
1812
+ * quarter's full roster rather than the returned page. Free keys get up to five names
1813
+ * and identifiers; it does not expand the `holders` preview. Omitted when the
1814
+ * full-roster lookup is unavailable; an empty array means a verified search found none.
1815
+ */
1816
+ notableHolders?: NotableHolder[];
1817
+ /** `full_roster` when `notableHolders` was checked against the quarter's full roster. */
1818
+ notableHoldersScope?: "full_roster" | (string & {});
1819
+ /**
1820
+ * The immediately preceding calendar quarter targeted for share-change comparisons (ISO
1821
+ * date). Can be present while `comparisonStatus` reads unavailable or incomplete.
1822
+ */
1823
+ comparisonReportDate?: string;
1824
+ /**
1825
+ * Conservative summary across the whole response. A holder can still carry valid
1826
+ * changes while this reads incomplete, so check each row's
1827
+ * {@link Holder.comparisonStatus}.
1828
+ */
1829
+ comparisonStatus?: HolderComparisonStatus;
1687
1830
  }
1688
1831
  /**
1689
1832
  * The flows payload inside the response envelope: `institutional.getFlows()` returns
@@ -4275,7 +4418,13 @@ declare class Insights {
4275
4418
  declare class Institutional {
4276
4419
  private client;
4277
4420
  constructor(client: APIClient);
4278
- /** Get available 13F reporting quarters. */
4421
+ /**
4422
+ * Get available 13F reporting quarters, newest first.
4423
+ *
4424
+ * The first entry is usually the quarter that is still filing, so pick by the flag rather
4425
+ * than by position: `quarters.find((q) => !q.pending)?.reportDate`. Each row also carries
4426
+ * `ownershipEligible` and `ownershipEligibleAt`.
4427
+ */
4279
4428
  getQuarters(): Promise<Quarter[]>;
4280
4429
  /**
4281
4430
  * Get aggregate institutional activity per ticker for a quarter.
@@ -4291,6 +4440,11 @@ declare class Institutional {
4291
4440
  /**
4292
4441
  * Get institutional holders for a specific stock.
4293
4442
  *
4443
+ * `reportDate` is optional: omit it (or pass `undefined` ahead of `options`) and the
4444
+ * request carries no date, so the server serves this ticker's latest settled quarter,
4445
+ * echoes it in `data.reportDate` with `data.selection.mode` set to `DEFAULT`, and reports
4446
+ * any newer still-filing quarter separately in `data.earlyFilers`.
4447
+ *
4294
4448
  * Returns the preview envelope wrapping a {@link TickerHolders} object, so the rows
4295
4449
  * are two levels down: `(await getHolders(t, d)).data.holders`, alongside ticker-level
4296
4450
  * totals like `holderCount`. Free callers get a truncated `holders` array with
@@ -4304,8 +4458,15 @@ declare class Institutional {
4304
4458
  * `returnedCount`, `offset`, and a `notableChanges` summary, so you can walk the list
4305
4459
  * without re-counting it. Without it, `offset` / `sortBy` / `sortDir` are ignored by the
4306
4460
  * server and you get the full unsorted list back with a 200.
4461
+ *
4462
+ * The payload also says how its quarter was chosen (`selection`), reports a newer
4463
+ * still-filing quarter separately (`earlyFilersStatus`, `earlyFilers`), lists well-known
4464
+ * institutions matched against the full roster (`notableHolders`), and summarizes the
4465
+ * quarter-over-quarter comparison (`comparisonReportDate`, `comparisonStatus`). Each
4466
+ * holder row has its own `comparisonStatus`; only `AVAILABLE` on that row supports its
4467
+ * change figures.
4307
4468
  */
4308
- getHolders(ticker: string, reportDate: string, options?: GetHoldersOptions): Promise<PreviewResponse<TickerHolders>>;
4469
+ getHolders(ticker: string, reportDate?: string, options?: GetHoldersOptions): Promise<PreviewResponse<TickerHolders>>;
4309
4470
  /**
4310
4471
  * Get activist investor positions (NEW or INCREASED).
4311
4472
  *
@@ -4968,6 +5129,6 @@ declare class APIError extends SentiSenseError {
4968
5129
  constructor(message: string, status: number, code?: string);
4969
5130
  }
4970
5131
 
4971
- declare const VERSION = "0.66.0";
5132
+ declare const VERSION = "0.67.0";
4972
5133
 
4973
- 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 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 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 OptionsIntradayHistory, type OptionsIntradayPoint, 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 };
5134
+ 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 };
package/dist/index.d.ts CHANGED
@@ -796,6 +796,28 @@ interface OptionsOiWalls {
796
796
  maxPain?: number;
797
797
  callWalls?: OptionsWall[];
798
798
  putWalls?: OptionsWall[];
799
+ /**
800
+ * Call open interest summed across every strike of the expiry, when present. Omitted on
801
+ * snapshots built before the field existed.
802
+ */
803
+ totalCallOi?: number;
804
+ /**
805
+ * Put open interest summed across every strike of the expiry, when present. Omitted on
806
+ * snapshots built before the field existed.
807
+ */
808
+ totalPutOi?: number;
809
+ /**
810
+ * Call open interest at the `maxPain` strike, when present, even when that strike is not
811
+ * one of the walls. `0` when no calls are open there; omitted on snapshots built before
812
+ * the field existed.
813
+ */
814
+ maxPainCallOi?: number;
815
+ /**
816
+ * Put open interest at the `maxPain` strike, when present, even when that strike is not
817
+ * one of the walls. `0` when no puts are open there; omitted on snapshots built before
818
+ * the field existed.
819
+ */
820
+ maxPainPutOi?: number;
799
821
  }
800
822
  /** A contract whose session volume far exceeds its open interest: fresh positioning. */
801
823
  interface OptionsUnusualContract {
@@ -1565,8 +1587,9 @@ interface Quarter {
1565
1587
  label: string;
1566
1588
  reportDate: string;
1567
1589
  /**
1568
- * True while this quarter's 13F filing window is still open, which is the 45 days after
1569
- * quarter end.
1590
+ * True while this quarter's 13F filing window is still open: through the effective SEC
1591
+ * filing deadline day in New York, which is 45 days after quarter end rolled past
1592
+ * weekends and federal holidays.
1570
1593
  *
1571
1594
  * Read it before you pick a quarter to query. The list leads with the current quarter, so
1572
1595
  * the newest entry is pending for six weeks of every quarter, and a holders request against
@@ -1578,6 +1601,19 @@ interface Quarter {
1578
1601
  * every row.
1579
1602
  */
1580
1603
  pending?: boolean;
1604
+ /**
1605
+ * True from the New York calendar day after the effective SEC filing deadline. It does
1606
+ * not certify that every institution filed.
1607
+ *
1608
+ * Typed optional so existing object literals keep compiling; the API sends the key on
1609
+ * every row.
1610
+ */
1611
+ ownershipEligible?: boolean;
1612
+ /**
1613
+ * ISO date (New York calendar day) on which the quarter becomes eligible: the day after
1614
+ * the effective filing deadline.
1615
+ */
1616
+ ownershipEligibleAt?: string;
1581
1617
  }
1582
1618
  interface InstitutionalFlow {
1583
1619
  ticker: string;
@@ -1637,6 +1673,82 @@ interface Holder {
1637
1673
  * read it as "1 or unknown" rather than zero.
1638
1674
  */
1639
1675
  cikCount?: number | null;
1676
+ /**
1677
+ * Whether this row's quarter-over-quarter change is backed by a complete comparison.
1678
+ * Only `AVAILABLE` supports a change claim for this holder; the legacy change fields
1679
+ * (`changeType`, `sharesChange`, `sharesChangePct`) can still be present under the other
1680
+ * statuses. Check it per row: a holder can be `AVAILABLE` while the response-level
1681
+ * {@link TickerHolders.comparisonStatus} summary reads incomplete.
1682
+ */
1683
+ comparisonStatus?: HolderComparisonStatus;
1684
+ }
1685
+ /**
1686
+ * Comparison status for quarter-over-quarter share changes, on the holders response and on
1687
+ * each holder row. Only `AVAILABLE` supports a change claim.
1688
+ */
1689
+ type HolderComparisonStatus = "AVAILABLE" | "PRIOR_QUARTER_UNAVAILABLE" | "INCOMPLETE_INPUT" | "INCOMPLETE_FAMILY_COVERAGE" | "UNAVAILABLE" | (string & {});
1690
+ /**
1691
+ * How `institutional.getHolders()` chose the quarter it answered.
1692
+ */
1693
+ interface OwnershipSelection {
1694
+ /** `EXPLICIT` when the request named a `reportDate`, `DEFAULT` when the server chose. */
1695
+ mode: "DEFAULT" | "EXPLICIT" | (string & {});
1696
+ /** `settled` once the quarter's filing deadline has passed, `filing` before that. */
1697
+ status: "settled" | "filing" | (string & {});
1698
+ /** Identifier of the quarter-selection rule, e.g. `"v2-sec-deadline-next-day"`. */
1699
+ policyVersion: string;
1700
+ /** The newest eligible quarter across the market (ISO date). */
1701
+ marketDefaultReportDate?: string;
1702
+ /**
1703
+ * True when this response is for an older quarter than `marketDefaultReportDate`. An
1704
+ * explicit `reportDate` is still the quarter you asked for.
1705
+ */
1706
+ isStaleForMarket: boolean;
1707
+ }
1708
+ /**
1709
+ * A newer quarter that is still filing for this ticker, reported beside the selected
1710
+ * quarter rather than mixed into its holder rows.
1711
+ */
1712
+ interface EarlyFilers {
1713
+ /** Quarter end of the filing quarter (ISO date). */
1714
+ reportDate: string;
1715
+ /** Always `filing`. */
1716
+ status: "filing" | (string & {});
1717
+ /** Holder families with a positive position in this ticker so far. */
1718
+ holderCount: number;
1719
+ /** Distinct filers that have reported for the newer quarter, market-wide. */
1720
+ distinctFilerCount: number;
1721
+ /** Distinct filers in the selected settled quarter, market-wide, as a baseline. */
1722
+ baselineFilerCount: number;
1723
+ /**
1724
+ * Share of this ticker's selected-quarter institutional value held by filers confirmed
1725
+ * to have filed for the newer quarter, including filers that have since exited the
1726
+ * ticker, as a percentage. Omitted when filing presence or the baseline value is
1727
+ * unavailable or does not reconcile.
1728
+ */
1729
+ coveragePct?: number;
1730
+ }
1731
+ /**
1732
+ * A well-known institution matched against the selected quarter's full roster. Free keys
1733
+ * receive identifiers only; PRO also receives the position and change fields.
1734
+ */
1735
+ interface NotableHolder {
1736
+ filerCik: string;
1737
+ filerName: string;
1738
+ /** URL slug for `institutional.getInstitutionDetail()`, or null when unmapped. */
1739
+ entitySlug?: string | null;
1740
+ /** PRO only. */
1741
+ shares?: number;
1742
+ /** PRO only. */
1743
+ valueUsd?: number;
1744
+ /** PRO only. */
1745
+ changeType?: "NEW" | "INCREASED" | "DECREASED" | "SOLD_OUT" | "UNCHANGED";
1746
+ /** PRO only. */
1747
+ sharesChange?: number;
1748
+ /** PRO only. Omitted on a `NEW` position, which has no prior-position baseline. */
1749
+ sharesChangePct?: number;
1750
+ /** PRO only. Only `AVAILABLE` supports a quarter-change claim for this holder. */
1751
+ comparisonStatus?: HolderComparisonStatus;
1640
1752
  }
1641
1753
  /**
1642
1754
  * A server-side shortlist of the quarter's significant position changes, so a caller
@@ -1662,7 +1774,18 @@ interface HolderNotableChanges {
1662
1774
  interface TickerHolders {
1663
1775
  ticker: string;
1664
1776
  companyName: string;
1777
+ /** The quarter actually served (ISO date). */
1665
1778
  reportDate: string;
1779
+ /** How the quarter was chosen, and whether it trails the market's newest eligible one. */
1780
+ selection?: OwnershipSelection;
1781
+ /**
1782
+ * `AVAILABLE` when `earlyFilers` is present, `NONE` when no newer filing quarter is
1783
+ * observed, `UNAVAILABLE` when that supplementary read failed. The selected quarter's
1784
+ * holders are served either way.
1785
+ */
1786
+ earlyFilersStatus?: "AVAILABLE" | "NONE" | "UNAVAILABLE" | (string & {});
1787
+ /** A newer quarter still filing for this ticker. Sent only when `earlyFilersStatus` is `AVAILABLE`. */
1788
+ earlyFilers?: EarlyFilers;
1666
1789
  totalInstitutionalShares: number;
1667
1790
  totalInstitutionalValue: number;
1668
1791
  /** Every institutional holder of this ticker for the quarter, ignoring any paging. */
@@ -1684,6 +1807,26 @@ interface TickerHolders {
1684
1807
  * passed `limit`, since it exists to spare a paging caller a full scan.
1685
1808
  */
1686
1809
  notableChanges?: HolderNotableChanges;
1810
+ /**
1811
+ * Well-known institutions holding a positive position, matched against the selected
1812
+ * quarter's full roster rather than the returned page. Free keys get up to five names
1813
+ * and identifiers; it does not expand the `holders` preview. Omitted when the
1814
+ * full-roster lookup is unavailable; an empty array means a verified search found none.
1815
+ */
1816
+ notableHolders?: NotableHolder[];
1817
+ /** `full_roster` when `notableHolders` was checked against the quarter's full roster. */
1818
+ notableHoldersScope?: "full_roster" | (string & {});
1819
+ /**
1820
+ * The immediately preceding calendar quarter targeted for share-change comparisons (ISO
1821
+ * date). Can be present while `comparisonStatus` reads unavailable or incomplete.
1822
+ */
1823
+ comparisonReportDate?: string;
1824
+ /**
1825
+ * Conservative summary across the whole response. A holder can still carry valid
1826
+ * changes while this reads incomplete, so check each row's
1827
+ * {@link Holder.comparisonStatus}.
1828
+ */
1829
+ comparisonStatus?: HolderComparisonStatus;
1687
1830
  }
1688
1831
  /**
1689
1832
  * The flows payload inside the response envelope: `institutional.getFlows()` returns
@@ -4275,7 +4418,13 @@ declare class Insights {
4275
4418
  declare class Institutional {
4276
4419
  private client;
4277
4420
  constructor(client: APIClient);
4278
- /** Get available 13F reporting quarters. */
4421
+ /**
4422
+ * Get available 13F reporting quarters, newest first.
4423
+ *
4424
+ * The first entry is usually the quarter that is still filing, so pick by the flag rather
4425
+ * than by position: `quarters.find((q) => !q.pending)?.reportDate`. Each row also carries
4426
+ * `ownershipEligible` and `ownershipEligibleAt`.
4427
+ */
4279
4428
  getQuarters(): Promise<Quarter[]>;
4280
4429
  /**
4281
4430
  * Get aggregate institutional activity per ticker for a quarter.
@@ -4291,6 +4440,11 @@ declare class Institutional {
4291
4440
  /**
4292
4441
  * Get institutional holders for a specific stock.
4293
4442
  *
4443
+ * `reportDate` is optional: omit it (or pass `undefined` ahead of `options`) and the
4444
+ * request carries no date, so the server serves this ticker's latest settled quarter,
4445
+ * echoes it in `data.reportDate` with `data.selection.mode` set to `DEFAULT`, and reports
4446
+ * any newer still-filing quarter separately in `data.earlyFilers`.
4447
+ *
4294
4448
  * Returns the preview envelope wrapping a {@link TickerHolders} object, so the rows
4295
4449
  * are two levels down: `(await getHolders(t, d)).data.holders`, alongside ticker-level
4296
4450
  * totals like `holderCount`. Free callers get a truncated `holders` array with
@@ -4304,8 +4458,15 @@ declare class Institutional {
4304
4458
  * `returnedCount`, `offset`, and a `notableChanges` summary, so you can walk the list
4305
4459
  * without re-counting it. Without it, `offset` / `sortBy` / `sortDir` are ignored by the
4306
4460
  * server and you get the full unsorted list back with a 200.
4461
+ *
4462
+ * The payload also says how its quarter was chosen (`selection`), reports a newer
4463
+ * still-filing quarter separately (`earlyFilersStatus`, `earlyFilers`), lists well-known
4464
+ * institutions matched against the full roster (`notableHolders`), and summarizes the
4465
+ * quarter-over-quarter comparison (`comparisonReportDate`, `comparisonStatus`). Each
4466
+ * holder row has its own `comparisonStatus`; only `AVAILABLE` on that row supports its
4467
+ * change figures.
4307
4468
  */
4308
- getHolders(ticker: string, reportDate: string, options?: GetHoldersOptions): Promise<PreviewResponse<TickerHolders>>;
4469
+ getHolders(ticker: string, reportDate?: string, options?: GetHoldersOptions): Promise<PreviewResponse<TickerHolders>>;
4309
4470
  /**
4310
4471
  * Get activist investor positions (NEW or INCREASED).
4311
4472
  *
@@ -4968,6 +5129,6 @@ declare class APIError extends SentiSenseError {
4968
5129
  constructor(message: string, status: number, code?: string);
4969
5130
  }
4970
5131
 
4971
- declare const VERSION = "0.66.0";
5132
+ declare const VERSION = "0.67.0";
4972
5133
 
4973
- 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 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 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 OptionsIntradayHistory, type OptionsIntradayPoint, 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 };
5134
+ 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 };
package/dist/index.mjs CHANGED
@@ -707,7 +707,13 @@ var Institutional = class {
707
707
  constructor(client) {
708
708
  this.client = client;
709
709
  }
710
- /** Get available 13F reporting quarters. */
710
+ /**
711
+ * Get available 13F reporting quarters, newest first.
712
+ *
713
+ * The first entry is usually the quarter that is still filing, so pick by the flag rather
714
+ * than by position: `quarters.find((q) => !q.pending)?.reportDate`. Each row also carries
715
+ * `ownershipEligible` and `ownershipEligibleAt`.
716
+ */
711
717
  async getQuarters() {
712
718
  return this.client.get("/api/v1/institutional/quarters");
713
719
  }
@@ -730,6 +736,11 @@ var Institutional = class {
730
736
  /**
731
737
  * Get institutional holders for a specific stock.
732
738
  *
739
+ * `reportDate` is optional: omit it (or pass `undefined` ahead of `options`) and the
740
+ * request carries no date, so the server serves this ticker's latest settled quarter,
741
+ * echoes it in `data.reportDate` with `data.selection.mode` set to `DEFAULT`, and reports
742
+ * any newer still-filing quarter separately in `data.earlyFilers`.
743
+ *
733
744
  * Returns the preview envelope wrapping a {@link TickerHolders} object, so the rows
734
745
  * are two levels down: `(await getHolders(t, d)).data.holders`, alongside ticker-level
735
746
  * totals like `holderCount`. Free callers get a truncated `holders` array with
@@ -743,6 +754,13 @@ var Institutional = class {
743
754
  * `returnedCount`, `offset`, and a `notableChanges` summary, so you can walk the list
744
755
  * without re-counting it. Without it, `offset` / `sortBy` / `sortDir` are ignored by the
745
756
  * server and you get the full unsorted list back with a 200.
757
+ *
758
+ * The payload also says how its quarter was chosen (`selection`), reports a newer
759
+ * still-filing quarter separately (`earlyFilersStatus`, `earlyFilers`), lists well-known
760
+ * institutions matched against the full roster (`notableHolders`), and summarizes the
761
+ * quarter-over-quarter comparison (`comparisonReportDate`, `comparisonStatus`). Each
762
+ * holder row has its own `comparisonStatus`; only `AVAILABLE` on that row supports its
763
+ * change figures.
746
764
  */
747
765
  async getHolders(ticker, reportDate, options) {
748
766
  return this.client.get(
@@ -1388,7 +1406,7 @@ var Trackers = class {
1388
1406
  };
1389
1407
 
1390
1408
  // src/version.ts
1391
- var VERSION = "0.66.0";
1409
+ var VERSION = "0.67.0";
1392
1410
 
1393
1411
  // src/client.ts
1394
1412
  var DEFAULT_BASE_URL = "https://app.sentisense.ai";