sentisense 0.53.0 → 0.55.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
@@ -453,6 +453,26 @@ interface OptionsAggregate {
453
453
  /** Raw 25-delta call and put implied volatilities. */
454
454
  iv25c?: number;
455
455
  iv25p?: number;
456
+ /**
457
+ * Calibrated 90% expected move over 1 trading session, as a fraction of price, so `0.0407`
458
+ * is 4.07%. `k * atmIv * Math.sqrt(h / 252)` with an empirical `k` (1.48 here) fit on
459
+ * SentiSense's own stored option history. The 90% is a measured historical coverage rate,
460
+ * not a guarantee, and the range carries no direction and no price target.
461
+ */
462
+ expectedMove1d?: number;
463
+ /** The same calibrated 90% range over 5 trading sessions (`k` = 1.56). */
464
+ expectedMove5d?: number;
465
+ /** The same calibrated 90% range over 20 trading sessions (`k` = 1.56). */
466
+ expectedMove20d?: number;
467
+ /**
468
+ * One-sigma expected move over 1 trading session, `atmIv * Math.sqrt(h / 252)`: the industry
469
+ * convention, roughly 68% of moves, with no calibration applied.
470
+ */
471
+ expectedMove1s1d?: number;
472
+ /** One-sigma expected move over 5 trading sessions. */
473
+ expectedMove1s5d?: number;
474
+ /** One-sigma expected move over 20 trading sessions. */
475
+ expectedMove1s20d?: number;
456
476
  netDelta?: number;
457
477
  notionalVol?: number;
458
478
  contracts?: number;
@@ -600,6 +620,18 @@ interface OptionsOverviewRow {
600
620
  notionalVol?: number;
601
621
  /** Signed change of `atmIv` against its ~20-session mean. Rank "biggest IV moves" by absolute value. */
602
622
  ivMove20?: number;
623
+ /** Calibrated 90% expected move over 1 trading session, as a fraction of price. */
624
+ expectedMove1d?: number;
625
+ /** The same calibrated 90% range over 5 trading sessions. */
626
+ expectedMove5d?: number;
627
+ /** The same calibrated 90% range over 20 trading sessions. */
628
+ expectedMove20d?: number;
629
+ /** One-sigma expected move over 1 trading session: the industry convention, uncalibrated. */
630
+ expectedMove1s1d?: number;
631
+ /** One-sigma expected move over 5 trading sessions. */
632
+ expectedMove1s5d?: number;
633
+ /** One-sigma expected move over 20 trading sessions. */
634
+ expectedMove1s20d?: number;
603
635
  /** Trailing-1y observation count, which is what drives the building-baseline state. */
604
636
  observations1y?: number;
605
637
  /** Unusually-active contracts this session. */
@@ -657,8 +689,8 @@ interface OptionsOverview {
657
689
  /** Full ETF board size on a FREE response, mirroring what the envelope's `totalCount` does for stocks. */
658
690
  etfTotalCount?: number;
659
691
  }
660
- /** The six dimensions the composite is blended from, by stable `key`. */
661
- type RatingDimensionKey = "crowd" | "smart_money" | "options" | "analysts" | "fundamentals" | "earnings";
692
+ /** The seven dimensions the composite is blended from, by stable `key`. */
693
+ type RatingDimensionKey = "crowd" | "smart_money" | "options" | "analysts" | "fundamentals" | "earnings" | "technicals";
662
694
  /**
663
695
  * Why a stock has no grade.
664
696
  *
@@ -703,9 +735,9 @@ interface RatingSubLeg {
703
735
  unit: string;
704
736
  }
705
737
  /**
706
- * One of the six dimensions the composite is blended from.
738
+ * One of the seven dimensions the composite is blended from.
707
739
  *
708
- * **All six always arrive, in a fixed order, whether or not they had data.** An absent
740
+ * **All seven always arrive, in a fixed order, whether or not they had data.** An absent
709
741
  * dimension is a full row with `present` false and a `null` percentile; the server never
710
742
  * drops it, precisely so a client cannot mistake a gap for a five-dimension rating. Read
711
743
  * `present` before reading `percentile`, and never substitute zero for a `null`: zero is the
@@ -749,7 +781,7 @@ interface RatingBase {
749
781
  kbEntityId: string;
750
782
  /** The New York calendar day this answer describes, `"YYYY-MM-DD"`. */
751
783
  asOf: string;
752
- /** Always all six, in a fixed order, absent ones with `present` false. */
784
+ /** Always all seven, in a fixed order, absent ones with `present` false. */
753
785
  dimensions: RatingDimension[];
754
786
  flags: RatingFlag[];
755
787
  /** The standard financial disclaimer. Display it alongside the grade. */
@@ -821,7 +853,7 @@ interface StockNotRated extends RatingBase {
821
853
  rated: false;
822
854
  /** Why there is no grade. */
823
855
  reason: RatingNotRatedReason;
824
- /** How many of the six dimensions had data. */
856
+ /** How many of the seven dimensions had data. */
825
857
  dimensionsPresent?: number;
826
858
  /** Which dimensions had data, by `key`. */
827
859
  presentDimensions: RatingDimensionKey[];
@@ -1241,6 +1273,8 @@ interface InsiderTrade {
1241
1273
  transactionCode: string;
1242
1274
  transactionType: "BUY" | "SELL" | "EXERCISE" | "AWARD" | "GIFT" | "OTHER";
1243
1275
  securityTitle: string;
1276
+ /** The security the row was filed in when it is not the US listing `ticker` names (e.g. "Common Shares (2330.TW)"); null on the ordinary case, and when set `pricePerShare` is null because the filed price is per foreign ordinary share. */
1277
+ securityBasis?: string | null;
1244
1278
  sharesTransacted: number;
1245
1279
  pricePerShare: number | null;
1246
1280
  totalValue: number;
@@ -1557,6 +1591,169 @@ interface RecentEarningsEntry {
1557
1591
  /** Latest content written for this quarter, epoch seconds. */
1558
1592
  generatedAt: number;
1559
1593
  }
1594
+ /** One measured session move following an earnings announcement. */
1595
+ interface EarningsReaction {
1596
+ /** Date the results were announced, ISO calendar day `"YYYY-MM-DD"`. */
1597
+ reportDate: string;
1598
+ /** Always present. `null` means the reacting session was inferred. */
1599
+ timing: "AMC" | "BMO" | null;
1600
+ /** Close immediately before the reaction session. */
1601
+ priorClose: number;
1602
+ /** Close of the reaction session. */
1603
+ nextClose: number;
1604
+ /** Signed percent change from `priorClose` to `nextClose`. */
1605
+ movePct: number;
1606
+ }
1607
+ /** Up to twelve measured earnings reactions for one ticker, newest first. */
1608
+ interface EarningsReactionsResponse {
1609
+ ticker: string;
1610
+ /** Date the response was produced, ISO calendar day `"YYYY-MM-DD"`. */
1611
+ asOf: string;
1612
+ reactions: EarningsReaction[];
1613
+ }
1614
+ /** Calendar span covered by an earnings-statistics block. */
1615
+ interface EarningsStatisticsWindow {
1616
+ /** Stable cache key for this span. */
1617
+ key: string;
1618
+ kind: string;
1619
+ /** Inclusive first day, ISO `"YYYY-MM-DD"`. */
1620
+ startDate: string;
1621
+ /** Inclusive last day, ISO `"YYYY-MM-DD"`. */
1622
+ endDate: string;
1623
+ }
1624
+ /** Counts, rates, and measured moves for one earnings outcome. */
1625
+ interface EarningsOutcomeStatistics {
1626
+ count: number;
1627
+ /** `count` divided by all classified events; `null` when the denominator is zero. */
1628
+ rate: number | null;
1629
+ withReaction: number;
1630
+ fell: number;
1631
+ rose: number;
1632
+ flat: number;
1633
+ /** `fell` divided by `withReaction`; `null` when the denominator is zero. */
1634
+ fellRate: number | null;
1635
+ /** Mean signed session move as a percent, or `null` when no move is available. */
1636
+ averageMovePct: number | null;
1637
+ }
1638
+ /** Trailing comparison span for an earnings-statistics window. */
1639
+ interface EarningsStatisticsBaseline {
1640
+ window: EarningsStatisticsWindow;
1641
+ classifiedEvents: number;
1642
+ completedReactions: number;
1643
+ distinctTickers: number;
1644
+ beatRate: number | null;
1645
+ beatsFellRate: number | null;
1646
+ coverageRatio: number | null;
1647
+ sufficientData: boolean;
1648
+ }
1649
+ /** Signed differences from the trailing baseline. */
1650
+ interface EarningsStatisticsDeviation {
1651
+ beatRate: number | null;
1652
+ beatsFellRate: number | null;
1653
+ beatRateIsMaterial: boolean;
1654
+ beatsFellRateIsMaterial: boolean;
1655
+ }
1656
+ /** Publication and materiality thresholds used for the statistics. */
1657
+ interface EarningsStatisticsThresholds {
1658
+ minClassifiedEvents: number;
1659
+ minCoverageRatio: number;
1660
+ baselineWeeks: number;
1661
+ beatRateDeviation: number;
1662
+ reactionDivergence: number;
1663
+ }
1664
+ /** Market-wide earnings outcomes and their realized price reactions. */
1665
+ interface EarningsStatistics {
1666
+ calculationVersion: string;
1667
+ /** When the figures were computed, epoch seconds. */
1668
+ asOf: number;
1669
+ window: EarningsStatisticsWindow;
1670
+ eventsInWindow: number;
1671
+ classifiedEvents: number;
1672
+ unclassifiedEvents: number;
1673
+ distinctTickers: number;
1674
+ completedReactions: number;
1675
+ pendingReactions: number;
1676
+ /** Completed reactions divided by classified events. */
1677
+ coverageRatio: number | null;
1678
+ sufficientData: boolean;
1679
+ /** Absent when `sufficientData` is true. */
1680
+ insufficientDataReason?: "SAMPLE_BELOW_FLOOR" | "COVERAGE_BELOW_FLOOR";
1681
+ beat: EarningsOutcomeStatistics;
1682
+ miss: EarningsOutcomeStatistics;
1683
+ inline: EarningsOutcomeStatistics;
1684
+ /** Mean signed session move as a percent, or `null` when no move is available. */
1685
+ averageMovePct: number | null;
1686
+ /** Absent on `trailing_52w` and `all_time`. */
1687
+ baseline?: EarningsStatisticsBaseline;
1688
+ /** Absent when there is no baseline. */
1689
+ deviation?: EarningsStatisticsDeviation;
1690
+ thresholds: EarningsStatisticsThresholds;
1691
+ }
1692
+ /** One recently reported company in the earnings ranking. */
1693
+ interface RankedReportedEarnings {
1694
+ ticker: string;
1695
+ /** ISO calendar day `"YYYY-MM-DD"`. */
1696
+ reportDate: string;
1697
+ fiscalPeriod?: string;
1698
+ headline?: string;
1699
+ hasTranscriptSummary?: boolean;
1700
+ estimateEps?: number;
1701
+ actualEps?: number;
1702
+ /** Signed percent. */
1703
+ surprisePct?: number;
1704
+ outcome: "BEAT" | "MISS" | "INLINE" | "UNCLASSIFIED";
1705
+ /** Signed percent of the reacting session. */
1706
+ movePct?: number;
1707
+ reactionPending?: boolean;
1708
+ /** Signed percent, present only while the reacting session is trading. */
1709
+ liveReactionPct?: number;
1710
+ awaitingConsensus?: boolean;
1711
+ /** US dollars. */
1712
+ marketCap?: number;
1713
+ /** 7-day average SentiSense Score. Signed and unbounded. */
1714
+ sentisenseScore7d?: number;
1715
+ /** 7-day average Score minus the 30-day average, in signed score units. Positive means strengthening. */
1716
+ scoreChange7d?: number;
1717
+ /** Ranking importance from 0 to 1. */
1718
+ importance: number;
1719
+ }
1720
+ /** One upcoming company in the earnings ranking. */
1721
+ interface RankedUpcomingEarnings {
1722
+ ticker: string;
1723
+ companyName: string;
1724
+ /** ISO calendar day `"YYYY-MM-DD"`. */
1725
+ earningsDate: string;
1726
+ earningsTime: "before_open" | "after_close" | "during_market" | "unknown";
1727
+ confirmed: boolean;
1728
+ estimatedEps?: number;
1729
+ /** US dollars. */
1730
+ marketCap?: number;
1731
+ /** 7-day average SentiSense Score. Signed and unbounded. */
1732
+ sentisenseScore7d?: number;
1733
+ /** 7-day average Score minus the 30-day average, in signed score units. Positive means strengthening. */
1734
+ scoreChange7d?: number;
1735
+ /** Ranking importance from 0 to 1. */
1736
+ importance: number;
1737
+ }
1738
+ /** A ranked earnings window and the rows returned for it. */
1739
+ interface RankedEarningsSection<T> {
1740
+ /** Inclusive first day, ISO `"YYYY-MM-DD"`. */
1741
+ windowStart: string;
1742
+ /** Inclusive last day, ISO `"YYYY-MM-DD"`. */
1743
+ windowEnd: string;
1744
+ /** Full event count before tier or limit truncation. */
1745
+ totalInWindow: number;
1746
+ rows: T[];
1747
+ }
1748
+ /** Recently reported and upcoming earnings ranked by importance. */
1749
+ interface RankedEarnings {
1750
+ /** When the ranking was computed, epoch seconds. */
1751
+ asOf: number;
1752
+ /** Revision of the ordering rules. */
1753
+ rankingVersion: string;
1754
+ reported: RankedEarningsSection<RankedReportedEarnings>;
1755
+ upcoming: RankedEarningsSection<RankedUpcomingEarnings>;
1756
+ }
1560
1757
  interface GetEarningsSummariesOptions {
1561
1758
  /**
1562
1759
  * Max quarters returned, 1 to 40. Omitted, the API applies its own default
@@ -1570,9 +1767,47 @@ interface GetRecentEarningsOptions {
1570
1767
  /** Max rows returned, 1 to 100. Omitted, the API applies its own default of 50. */
1571
1768
  limit?: number;
1572
1769
  }
1770
+ interface GetEarningsStatisticsOptions {
1771
+ /** Statistics window. Omitted, the API uses `last_completed_week`. */
1772
+ window?: "last_completed_week" | "week_to_date" | "trailing_52w" | "all_time";
1773
+ }
1774
+ interface GetRankedEarningsOptions {
1775
+ /** Reported look-back window, 1 to 31. Omitted, the API uses 14. */
1776
+ reportedDays?: number;
1777
+ /** Maximum reported rows, 1 to 50. Omitted, the API uses 12. */
1778
+ reportedLimit?: number;
1779
+ /** Upcoming window, 1 to 31. Omitted, the API uses 7. */
1780
+ upcomingDays?: number;
1781
+ /** Maximum upcoming rows, 1 to 50. Omitted, the API uses 12. */
1782
+ upcomingLimit?: number;
1783
+ }
1784
+ /**
1785
+ * What lifts the gate on a preview response, in a form you can show a user directly.
1786
+ *
1787
+ * Present only when `isPreview` is `true`. Every field is optional: the copy and the
1788
+ * offer are set server-side and can change without an SDK release, so read what is
1789
+ * there rather than depending on any one field.
1790
+ */
1791
+ interface UpgradeHint {
1792
+ /** Plan that lifts the gate, e.g. `"PRO"`. */
1793
+ plan?: string;
1794
+ /** One sentence naming what was withheld. Safe to show verbatim. */
1795
+ message?: string;
1796
+ /** Current price, including any active discount code. */
1797
+ price?: string;
1798
+ /** Where to complete the upgrade. */
1799
+ url?: string;
1800
+ /** What an automated caller should do with this object. */
1801
+ relay?: string;
1802
+ }
1573
1803
  interface PreviewResponse<T> {
1574
1804
  isPreview: boolean;
1575
1805
  previewReason: "PRO_REQUIRED" | null;
1806
+ /**
1807
+ * How to lift the gate. Present only on a preview; absent from full responses.
1808
+ * Surface `message` and `url` to your user rather than hard-coding a price.
1809
+ */
1810
+ upgrade?: UpgradeHint;
1576
1811
  /**
1577
1812
  * Size of the full result set, before any truncation your response went through.
1578
1813
  *
@@ -1927,6 +2162,8 @@ interface TrackerSnapshotResponse {
1927
2162
  previewReason: "PRO_REQUIRED" | null;
1928
2163
  /** Full row count before truncation. Only set on preview responses. */
1929
2164
  totalCount?: number;
2165
+ /** How to lift the gate. Only set on preview responses. */
2166
+ upgrade?: UpgradeHint;
1930
2167
  data: TrackerSnapshot;
1931
2168
  }
1932
2169
  /** Per-index discovery row returned by `client.indexes.list()`. */
@@ -2314,6 +2551,92 @@ interface AnalystConsensus {
2314
2551
  strongSell: number;
2315
2552
  updatedAt: string | null;
2316
2553
  }
2554
+ /** One daily observation of the analyst consensus, as observed on `snapshotDate`. */
2555
+ interface AnalystConsensusHistoryPoint {
2556
+ /** Market-calendar date of the observation, `"YYYY-MM-DD"`. */
2557
+ snapshotDate: string;
2558
+ /** UTC observation instant, formatted as ISO-8601 with whole seconds. */
2559
+ observedAt: string;
2560
+ /** UTC observation instant in epoch seconds. */
2561
+ observedAtEpoch: number;
2562
+ source: string;
2563
+ /**
2564
+ * `false` when the vendor panel did not come back that day and the distribution
2565
+ * counts are carried forward.
2566
+ */
2567
+ countsObserved: boolean;
2568
+ currentPrice: number | null;
2569
+ targetLow: number | null;
2570
+ targetMean: number | null;
2571
+ /** `null` in a free preview. */
2572
+ targetMedian: number | null;
2573
+ targetHigh: number | null;
2574
+ numberOfAnalysts: number;
2575
+ upsidePercent: number | null;
2576
+ /** `null` in a free preview. */
2577
+ recommendationMean: number | null;
2578
+ /** `null` in a free preview. */
2579
+ strongBuy: number | null;
2580
+ /** `null` in a free preview. */
2581
+ buy: number | null;
2582
+ /** `null` in a free preview. */
2583
+ hold: number | null;
2584
+ /** `null` in a free preview. */
2585
+ sell: number | null;
2586
+ /** `null` in a free preview. */
2587
+ strongSell: number | null;
2588
+ consensusLabel: string | null;
2589
+ }
2590
+ interface AnalystConsensusHistory {
2591
+ ticker: string;
2592
+ /** Inclusive first date of the served window, `"YYYY-MM-DD"`. */
2593
+ from: string;
2594
+ /** Inclusive last date of the served window, `"YYYY-MM-DD"`. */
2595
+ to: string;
2596
+ /** Rows returned after the limit and any free-preview clipping. */
2597
+ count: number;
2598
+ /** Daily observations ordered by `snapshotDate` ascending. */
2599
+ history: AnalystConsensusHistoryPoint[];
2600
+ }
2601
+ /** One recorded call associated with a stock move. */
2602
+ interface AnalystCalledItCall {
2603
+ firm: string;
2604
+ /** Always present; `null` when the publisher named nobody. */
2605
+ analystName: string | null;
2606
+ attribution: "firm" | "analyst";
2607
+ priceTarget: number | null;
2608
+ priorPriceTarget: number | null;
2609
+ /** Publication date, `"YYYY-MM-DD"`. */
2610
+ publishedOn: string;
2611
+ daysBeforeMove: number;
2612
+ }
2613
+ /** Factual call history as recorded when a stock moved 20% or more over five sessions. */
2614
+ interface AnalystCalledItMove {
2615
+ insightId: string;
2616
+ /** When the observation was generated, in epoch seconds. */
2617
+ generatedAt: number;
2618
+ /** First session date, `"YYYY-MM-DD"`. */
2619
+ moveStartDate: string;
2620
+ /** Last session date, `"YYYY-MM-DD"`. */
2621
+ moveEndDate: string;
2622
+ movePct: number;
2623
+ moveWindowSessions: number;
2624
+ lookbackDays: number;
2625
+ /** Move-level counts remain intact in a free preview. */
2626
+ coveringFirms: number;
2627
+ revisedWithMove: number;
2628
+ revisedAgainstMove: number;
2629
+ leftUnchanged: number;
2630
+ /** PRO: all recorded calls. FREE: up to five on the newest move. */
2631
+ calls: AnalystCalledItCall[];
2632
+ }
2633
+ interface GetAnalystCalledItOptions {
2634
+ /**
2635
+ * Maximum moves, newest first. Default 10; minimum 1, maximum 50.
2636
+ * The API rejects values below 1 and clamps values above 50.
2637
+ */
2638
+ limit?: number;
2639
+ }
2317
2640
  interface AnalystAction {
2318
2641
  ticker: string;
2319
2642
  actionDate: string;
@@ -2339,6 +2662,14 @@ interface GetAnalystActionsOptions {
2339
2662
  /** Days of history to return. Default 90. */
2340
2663
  lookbackDays?: number;
2341
2664
  }
2665
+ interface GetAnalystConsensusHistoryOptions {
2666
+ /** First snapshot date, inclusive, as `"YYYY-MM-DD"`. */
2667
+ from?: string;
2668
+ /** Last snapshot date, inclusive, as `"YYYY-MM-DD"`. */
2669
+ to?: string;
2670
+ /** Maximum rows to return, 1 to 366. Omitted, the API uses 90. */
2671
+ limit?: number;
2672
+ }
2342
2673
  interface GetAnalystMarketActivityOptions {
2343
2674
  /** Days of history to return. Default 30. */
2344
2675
  lookbackDays?: number;
@@ -2523,6 +2854,32 @@ declare class Analyst {
2523
2854
  * coverage exists.
2524
2855
  */
2525
2856
  consensus(ticker: string): Promise<PreviewResponse<AnalystConsensus>>;
2857
+ /**
2858
+ * Get daily consensus observations, ordered by `snapshotDate` ascending.
2859
+ * Each row describes the target fields as observed on that date. When
2860
+ * `countsObserved` is `false`, the vendor panel did not come back that day and the
2861
+ * distribution counts are carried forward.
2862
+ *
2863
+ * A PRO key receives the requested window. A FREE key receives the last 30 days;
2864
+ * `targetMedian`, `recommendationMean`, and the five distribution fields are `null`.
2865
+ * The envelope's `totalCount` still sizes the full requested window.
2866
+ */
2867
+ consensusHistory(ticker: string, options?: GetAnalystConsensusHistoryOptions): Promise<PreviewResponse<AnalystConsensusHistory>>;
2868
+ /**
2869
+ * Get factual call history as recorded when a stock moved 20% or more over five
2870
+ * sessions, newest move first by `moveEndDate`.
2871
+ *
2872
+ * PRO receives full moves and calls. FREE receives the newest move with up to five
2873
+ * calls and all move-level counts intact. The envelope's `totalCount` counts all
2874
+ * available moves before the limit. A known stock with no qualifying move returns
2875
+ * an empty `moves` array. Each call includes `analystName`: it is `null`, never
2876
+ * absent, when the publisher named nobody.
2877
+ */
2878
+ calledIt(ticker: string, options?: GetAnalystCalledItOptions): Promise<PreviewResponse<{
2879
+ ticker: string;
2880
+ count: number;
2881
+ moves: AnalystCalledItMove[];
2882
+ }>>;
2526
2883
  /**
2527
2884
  * Get recent analyst upgrade/downgrade actions for a ticker, newest first.
2528
2885
  * Free users receive the 3 most recent.
@@ -2701,6 +3058,44 @@ declare class Earnings {
2701
3058
  * forward-looking one.
2702
3059
  */
2703
3060
  getRecent(options?: GetRecentEarningsOptions): Promise<PreviewResponse<RecentEarningsEntry[]>>;
3061
+ /**
3062
+ * Measured price reactions to a ticker's last earnings reports, newest first.
3063
+ *
3064
+ * Use this after {@link getRecent} when you need one company's realized
3065
+ * post-report history. `client.calendar.getEarnings()` is the forward-looking
3066
+ * schedule instead. This endpoint returns its payload directly, without a
3067
+ * preview envelope, and every API key receives the full series.
3068
+ *
3069
+ * `timing` is always present on each row and can be `null` when the reacting
3070
+ * session was inferred rather than observed.
3071
+ */
3072
+ getReactions(ticker: string): Promise<EarningsReactionsResponse>;
3073
+ /**
3074
+ * Market-wide earnings outcomes and realized reaction statistics.
3075
+ *
3076
+ * Use this for aggregate beat, miss, inline, and post-report move rates.
3077
+ * {@link getRecent} returns individual recent reports, while
3078
+ * `client.calendar.getEarnings()` covers upcoming dates. The response uses
3079
+ * the preview envelope, but every API key receives the full body and
3080
+ * `isPreview` is always `false`.
3081
+ *
3082
+ * `baseline` and `deviation` are omitted for long-span windows, and rates can
3083
+ * be `null` when their denominator is zero.
3084
+ */
3085
+ getStatistics(options?: GetEarningsStatisticsOptions): Promise<PreviewResponse<EarningsStatistics>>;
3086
+ /**
3087
+ * Important recently reported and upcoming earnings in one ranking.
3088
+ *
3089
+ * Use this to prioritize a cross-ticker sweep. Follow reported rows with
3090
+ * {@link getReactions} for realized history; use {@link getRecent} for an
3091
+ * unranked recent feed or `client.calendar.getEarnings()` for the broader
3092
+ * forward schedule.
3093
+ *
3094
+ * A PRO key receives the full ranking. A FREE key receives the first three
3095
+ * rows in each section with `totalInWindow` left intact. Optional row fields
3096
+ * are omitted when null, so check them before use.
3097
+ */
3098
+ getRanked(options?: GetRankedEarningsOptions): Promise<PreviewResponse<RankedEarnings>>;
2704
3099
  }
2705
3100
 
2706
3101
  declare class EntityMetrics {
@@ -2740,12 +3135,19 @@ interface EtfInfo {
2740
3135
  imageUrl: string | null;
2741
3136
  }
2742
3137
  interface EtfHolding {
3138
+ /** The symbol as the issuer filed it. For an international fund this is the local exchange code, not a US ticker, so resolve stocks with `linkedTicker` instead. */
2743
3139
  ticker: string;
2744
3140
  name: string | null;
2745
3141
  /** Weight in the fund as a percentage (0-100). */
2746
3142
  weightPct: number;
2747
3143
  /** ISO date "YYYY-MM-DD". First date this holding appeared in the composition. */
2748
3144
  firstSeen: string | null;
3145
+ /** Listing venue the issuer reported for this position, verbatim (e.g. "NYSE", "SIX Swiss Exchange"). Null when the source carries no venue column. */
3146
+ exchange?: string | null;
3147
+ /** The symbol as listed on `exchange`. Same value as `ticker`, named to make it clear the symbol is venue-local and may not identify a US company. */
3148
+ localTicker?: string | null;
3149
+ /** The US stock symbol this holding resolves to, or null when it cannot be resolved to one. */
3150
+ linkedTicker?: string | null;
2749
3151
  }
2750
3152
  interface EtfHoldings {
2751
3153
  ticker: string;
@@ -3420,7 +3822,7 @@ declare class Stocks {
3420
3822
  * the full series. Returns 404 for tickers that do not yet have curated coverage.
3421
3823
  *
3422
3824
  * Coverage today: near-complete for the S&P 500 plus extended universe
3423
- * (~500 tickers). Use `listKpiCoverage()` to enumerate.
3825
+ * (900+ tickers). Use `listKpiCoverage()` to enumerate.
3424
3826
  */
3425
3827
  getKpis(ticker: string): Promise<PreviewResponse<CompanyKpisData>>;
3426
3828
  /**
@@ -3673,10 +4075,23 @@ declare class RateLimitError extends SentiSenseError {
3673
4075
  retryAfter?: number;
3674
4076
  constructor(message: string, code?: string, retryAfter?: number);
3675
4077
  }
4078
+ declare class TemporarilyUnavailableError extends SentiSenseError {
4079
+ /**
4080
+ * Seconds the server asked us to wait, from its `Retry-After` header on a 503. Unclamped,
4081
+ * because the point of this error is to hand you the server's real figure.
4082
+ *
4083
+ * The client honours short waits automatically, so you normally never see this. It is
4084
+ * thrown only when the requested wait is longer than the client will sleep for, which lets
4085
+ * a batch job keep the results it already has and resume later instead of retrying into a
4086
+ * server that has told you it is not ready.
4087
+ */
4088
+ retryAfter?: number;
4089
+ constructor(message: string, retryAfter?: number, code?: string);
4090
+ }
3676
4091
  declare class APIError extends SentiSenseError {
3677
4092
  constructor(message: string, status: number, code?: string);
3678
4093
  }
3679
4094
 
3680
- declare const VERSION = "0.53.0";
4095
+ declare const VERSION = "0.55.0";
3681
4096
 
3682
- export { type AISummary, APIError, type AnalystAction, type AnalystCall, type AnalystConsensus, type AnalystCoverage, type AnalystCoverageAnalyst, type AnalystCoverageBookEntry, type AnalystCoverageFirm, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AnalystFirmRating, type AnalystFirmTenure, type AnalystNote, type AnalystProfile, type AnalystRatingBuckets, 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 EarningsQuarter, type EarningsSource, type EntitySearchResult, type EntitySearchType, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystCallsOptions, type GetAnalystCoverageOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticianMemberOptions, type GetPoliticiansOptions, type GetRecentEarningsOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type HolderNotableChanges, type IndexConstituent, type IndexHistoryPoint, type IndexHistoryResponse, type IndexListResponse, type IndexListing, type IndexSnapshot, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlows, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type OptionsAggregate, type OptionsContext, type OptionsHistory, type OptionsHistoryWindow, 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, 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, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockNotRated, type StockPrice, type StockProfile, type StockQuote, type StockRating, type StockRatingResponse, type StockSocialDominance, type Story, type StoryCluster, type StoryTimelineEntry, 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 };
4097
+ 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 AnalystEstimatesResponse, type AnalystFirmRating, type AnalystFirmTenure, type AnalystNote, type AnalystProfile, type AnalystRatingBuckets, 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 EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystCalledItOptions, type GetAnalystCallsOptions, type GetAnalystConsensusHistoryOptions, type GetAnalystCoverageOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsStatisticsOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticianMemberOptions, type GetPoliticiansOptions, type GetRankedEarningsOptions, type GetRecentEarningsOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type HolderNotableChanges, type IndexConstituent, type IndexHistoryPoint, type IndexHistoryResponse, type IndexListResponse, type IndexListing, type IndexSnapshot, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlows, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type OptionsAggregate, type OptionsContext, type OptionsHistory, type OptionsHistoryWindow, 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, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, 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 };