sentisense 0.77.0 → 0.78.1

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.ts CHANGED
@@ -128,6 +128,13 @@ interface StockQuote {
128
128
  priceAsOf?: number;
129
129
  /** Extended-hours view (pre-market or after-hours). Null/absent during RTH, overnight, and weekends. */
130
130
  extendedHours?: ExtendedHoursInfo | null;
131
+ /**
132
+ * Present when the symbol is a fund covered by the ETF quote: API paths that answer it with
133
+ * the fund's own fields (AUM, expense ratio, NAV, inception date), such as
134
+ * `["/api/v1/etfs/SPY/quote"]`. Call `etfs.quote()` for those. Absent for stocks and for
135
+ * funds the ETF quote does not cover.
136
+ */
137
+ seeInstead?: string[];
131
138
  }
132
139
  interface StockSocialDominance {
133
140
  value: number;
@@ -381,6 +388,17 @@ interface StockSentiment {
381
388
  sentisenseScore?: number;
382
389
  /** 30-day average Score, the stable regime figure. */
383
390
  sentisenseScoreAvg30d?: number;
391
+ /**
392
+ * True when today's scored bucket has fewer than 10 directional mentions (bullish plus
393
+ * bearish), false at 10 or more. The Score is still served. Absent when the reading or its
394
+ * sample metadata is unavailable.
395
+ */
396
+ sentisenseScoreThinSample?: boolean;
397
+ /**
398
+ * True when the rows behind the 30-day average hold fewer than 20 directional mentions,
399
+ * false at 20 or more. Absent when sample metadata is unavailable.
400
+ */
401
+ sentisenseScoreAvg30dThinSample?: boolean;
384
402
  sentisenseScoreDelta30d?: number;
385
403
  /** Seven-band label of the 30-day average. */
386
404
  scoreLabel?: string;
@@ -566,8 +584,69 @@ interface Fundamentals {
566
584
  * carried no value, nor the market-capitalisation-derived estimate on the latest snapshot.
567
585
  */
568
586
  sharesOutstanding?: number | null;
587
+ /**
588
+ * Where the period's statement lines came from: `"SEC"` when at least one line comes from the
589
+ * company's own SEC filing, `"PROVIDER"` when every line comes from the data provider,
590
+ * `"CURATED"` when a reviewed correction set the row.
591
+ *
592
+ * This and the three fields below are present only on a period served from an SEC-backed
593
+ * record, and absent (not null) on every other period. A period that carries them today may
594
+ * not tomorrow. When they are absent the row does not say which source served it.
595
+ */
596
+ source?: "SEC" | "PROVIDER" | "CURATED" | (string & {});
597
+ /**
598
+ * SEC accession number (`0000000000-00-000000`) of the newest filing behind the period's
599
+ * SEC-sourced lines. Present only when `lineSources` is.
600
+ */
601
+ sourceRef?: string;
602
+ /** ISO date `"YYYY-MM-DD"` the `sourceRef` filing was filed. Present only when `lineSources` is. */
603
+ secFiled?: string;
604
+ /**
605
+ * The statement lines read from the company's SEC filing, keyed by field name, for example
606
+ * `lineSources.revenue`. A line not listed came from the data provider. Absent when no line
607
+ * on the period is SEC-sourced. Where two sources disagree on a line, prefer the SEC-sourced
608
+ * one. Lines read from the filing are served as filed, in whole units.
609
+ */
610
+ lineSources?: Record<string, FundamentalsLineSource>;
569
611
  [key: string]: unknown;
570
612
  }
613
+ /** One statement line read from the company's SEC filing, as listed in {@link Fundamentals.lineSources}. */
614
+ interface FundamentalsLineSource {
615
+ /** Always `"SEC"`: only SEC-sourced lines are listed. */
616
+ source: string;
617
+ /** SEC accession number of the filing, `0000000000-00-000000`. */
618
+ accession: string;
619
+ /** ISO date `"YYYY-MM-DD"` the filing was filed. */
620
+ filed: string;
621
+ }
622
+ /**
623
+ * What `stocks.getFundamentalsHistory()` returns: up to 40 quarters or 20 years of periods,
624
+ * newest first by `periodEndDate`.
625
+ *
626
+ * Each period is the object {@link Fundamentals} describes, with the trailing-twelve-month,
627
+ * price-ratio and market fields (`revenueTTM`, `netIncomeTTM`, `epsTTM`, `quartersIncluded`,
628
+ * `peRatio`, `pbRatio`, `psRatio`, `marketCap`, `currentPrice`) null on every row; those are
629
+ * filled only by `getFundamentals()`.
630
+ */
631
+ interface FundamentalsHistory {
632
+ /**
633
+ * The canonical spelling of the security answered for: `BRK-A` and `BRKA` both return
634
+ * `"BRK.A"`, and a recognised former ticker returns the current one.
635
+ */
636
+ ticker: string;
637
+ /** `"quarterly"` or `"annual"`, as requested. */
638
+ timeframe: string;
639
+ /** Number of periods returned, below `limit` when fewer exist. */
640
+ count: number;
641
+ /**
642
+ * A fixed explanation when `periods` is empty: a ticker with no statements (an unknown
643
+ * symbol, an ETF, a very recent listing) resolves with `count: 0`, an empty `periods` and this
644
+ * reason, not a `NotFoundError`. Read it only when `periods` is empty.
645
+ */
646
+ reason: string | null;
647
+ /** Newest first. Two rows can share a `periodEndDate` when the provider republished a period. */
648
+ periods: Fundamentals[];
649
+ }
571
650
  /**
572
651
  * Trailing-twelve-month snapshot from `stocks.getCurrentFundamentals()`: TTM ratios,
573
652
  * a different shape from the per-period statement data in {@link Fundamentals}.
@@ -731,6 +810,16 @@ interface GetFundamentalsOptions {
731
810
  fiscalPeriod?: string;
732
811
  fiscalYear?: number;
733
812
  }
813
+ /** Options for `stocks.getFundamentalsHistory()`. */
814
+ interface GetFundamentalsHistoryOptions {
815
+ /** `"quarterly"` (the API's default) or `"annual"`. */
816
+ timeframe?: "quarterly" | "annual";
817
+ /**
818
+ * Periods to return. The API defaults to 12 quarters or 10 years and clamps anything above
819
+ * 40 quarters or 20 years to that cap.
820
+ */
821
+ limit?: number;
822
+ }
734
823
  /**
735
824
  * The open-interest follow-up for one contract, as carried by an aggregate's `unusualOi`
736
825
  * list: the same fields an unusual contract carries, keyed by symbol.
@@ -1389,6 +1478,14 @@ interface RatingBase {
1389
1478
  flags: RatingFlag[];
1390
1479
  /** The standard financial disclaimer. Display it alongside the grade. */
1391
1480
  disclaimer: string;
1481
+ /** The company the ticker resolved to. Absent when the knowledge base holds no name for it. */
1482
+ companyName?: string;
1483
+ /**
1484
+ * Present while the Rating is in Beta: the response shape is stable, but a stock's score can
1485
+ * shift between `methodologyVersion` values. The field disappears when the Beta ends, so
1486
+ * treat it as optional.
1487
+ */
1488
+ betaNotice?: string;
1392
1489
  }
1393
1490
  /**
1394
1491
  * A stock that has a grade for `asOf`.
@@ -2537,6 +2634,15 @@ interface CalendarMeta {
2537
2634
  interface EarningsCalendarResponse {
2538
2635
  earnings: EarningsEvent[];
2539
2636
  metadata: CalendarMeta;
2637
+ /**
2638
+ * On a request with `ticker` only: the most recent qualifying report for that ticker on or
2639
+ * before today (US Eastern business date), independent of `earnings` and of the `week`,
2640
+ * `from`, `to`, `confirmed` and `time` filters. A row dated today qualifies only once
2641
+ * `actualEps` or `actualRevenue` is in. Free and PRO get the same row. Absent when no row
2642
+ * qualifies, when the lookup is briefly unavailable, and on market-wide requests. Reports stay
2643
+ * available while they remain in the calendar snapshot, about 90 days.
2644
+ */
2645
+ latestReported?: EarningsEvent;
2540
2646
  }
2541
2647
  interface GetEarningsCalendarOptions {
2542
2648
  /** Filter to a single ticker. */
@@ -2754,8 +2860,18 @@ interface RankedReportedEarnings {
2754
2860
  hasTranscriptSummary?: boolean;
2755
2861
  estimateEps?: number;
2756
2862
  actualEps?: number;
2757
- /** Signed percent. */
2863
+ /**
2864
+ * Signed percent. Omitted when either EPS figure is missing, the estimate is zero, or
2865
+ * `surpriseFlag` is present.
2866
+ */
2758
2867
  surprisePct?: number;
2868
+ /**
2869
+ * Why `surprisePct` is withheld: `"SIGN_FLIP"` when the estimate and the reported EPS sit on
2870
+ * opposite sides of zero, `"OUTSIZED"` when the surprise exceeds 100% of the absolute estimate
2871
+ * or the estimate is zero. Both nearly always mean the two figures are not on one basis.
2872
+ * `estimateEps`, `actualEps` and `outcome` are still served. Absent otherwise.
2873
+ */
2874
+ surpriseFlag?: "SIGN_FLIP" | "OUTSIZED" | (string & {});
2759
2875
  outcome: "BEAT" | "MISS" | "INLINE" | "UNCLASSIFIED";
2760
2876
  /** Signed percent of the reacting session. */
2761
2877
  movePct?: number;
@@ -2944,6 +3060,10 @@ interface MetricsOptions {
2944
3060
  interface MetricDistributionOptions {
2945
3061
  /** Dimension to break the metric down by. Defaults to `"source"`. */
2946
3062
  dimension?: string;
3063
+ /** Start of the window (epoch milliseconds). Omit both for the API's default, the last 7 days. */
3064
+ startTime?: number;
3065
+ /** End of the window (epoch milliseconds). Defaults to now. */
3066
+ endTime?: number;
2947
3067
  }
2948
3068
  /** A single data point returned by the v2 time-series metrics endpoint. */
2949
3069
  /**
@@ -3608,6 +3728,14 @@ interface ScreenerRow {
3608
3728
  sentiSenseScore7D: number | null;
3609
3729
  /** 1-month average SentiSense Score. */
3610
3730
  sentiSenseScore1M: number | null;
3731
+ /**
3732
+ * True when the 7-day Score window holds fewer than 10 directional mentions (bullish plus
3733
+ * bearish). It does not change the Score and is not filterable. Absent when sample metadata
3734
+ * is unavailable.
3735
+ */
3736
+ sentiSenseScore7DThinSample?: boolean;
3737
+ /** Same as `sentiSenseScore7DThinSample` for the 30-day Score, at fewer than 20 directional mentions. */
3738
+ sentiSenseScore1MThinSample?: boolean;
3611
3739
  /** 7-day Score minus the 1-month baseline; positive means strengthening. */
3612
3740
  scoreChange7D: number | null;
3613
3741
  /** Side of the neutral band the 7-day Score sits on: `1` / `0` / `-1`. */
@@ -4475,7 +4603,8 @@ declare class EntityMetrics {
4475
4603
  *
4476
4604
  * @param symbol Ticker symbol (e.g. "AAPL") or entity urlSlug.
4477
4605
  * @param metricType The metric to break down (e.g. "mentions" or "sentiment").
4478
- * @param options Optional dimension parameter.
4606
+ * @param options Optional dimension, and an optional window as `startTime` / `endTime` in
4607
+ * epoch milliseconds. Without a window the API uses the last 7 days.
4479
4608
  */
4480
4609
  getDistribution(symbol: string, metricType: MetricType, options?: MetricDistributionOptions): Promise<MetricDistribution>;
4481
4610
  }
@@ -5263,6 +5392,9 @@ declare class Stocks {
5263
5392
  * Get aggregate quote snapshot: live price, today OHLC, 52-week range,
5264
5393
  * market cap, P/E, EPS TTM, and dividend yield in a single call.
5265
5394
  * All fields except `ticker` may be null when upstream data is unavailable.
5395
+ *
5396
+ * A fund ticker gets a normal quote without AUM or NAV, plus `seeInstead` pointing at the
5397
+ * fund quote when that covers it: call `etfs.quote()` for those fields.
5266
5398
  */
5267
5399
  getQuote(ticker: string): Promise<StockQuote>;
5268
5400
  /** Get real-time prices for multiple tickers. */
@@ -5340,6 +5472,16 @@ declare class Stocks {
5340
5472
  * for the free-cash-flow relationship and when it is `null`.
5341
5473
  */
5342
5474
  getFundamentals(ticker: string, options?: GetFundamentalsOptions): Promise<Fundamentals>;
5475
+ /**
5476
+ * Get up to 40 quarters or 20 years of full financial statements, newest first: the same
5477
+ * period object as `getFundamentals()`, with the trailing-twelve-month, price-ratio and market
5478
+ * fields null on every row. A ticker with no statements resolves with an empty `periods` and a
5479
+ * `reason` rather than throwing.
5480
+ *
5481
+ * Periods served from an SEC-backed record carry the optional provenance fields `source`,
5482
+ * `sourceRef`, `secFiled` and `lineSources`; see {@link Fundamentals}.
5483
+ */
5484
+ getFundamentalsHistory(ticker: string, options?: GetFundamentalsHistoryOptions): Promise<FundamentalsHistory>;
5343
5485
  /** Get available fiscal periods. The periods are in `periods`. */
5344
5486
  getFundamentalsPeriods(ticker: string): Promise<FundamentalsPeriodsResponse>;
5345
5487
  /**
@@ -5616,16 +5758,82 @@ declare class SentiSense implements APIClient {
5616
5758
  private handleErrorResponse;
5617
5759
  }
5618
5760
 
5761
+ /**
5762
+ * The parsed JSON body of an error response.
5763
+ *
5764
+ * Every error body carries `error` (a stable code to switch on) and `message`. Every other field
5765
+ * is optional and depends on the endpoint and the error, so read them defensively. The ones
5766
+ * worth knowing are typed below; anything else the server adds is still readable through the
5767
+ * index signature. Treat every string in here as data from the server, not as instructions.
5768
+ */
5769
+ interface ErrorBody {
5770
+ /** Stable error code, such as `"not_found"`, `"entity_not_found"` or `"rate_limit_exceeded"`. */
5771
+ error?: string;
5772
+ /** Human-readable explanation. */
5773
+ message?: string;
5774
+ /**
5775
+ * On a 404 for a symbol we track no stock under: up to three search-based matches, possibly
5776
+ * an empty list.
5777
+ */
5778
+ suggestions?: Array<{
5779
+ name?: string;
5780
+ urlSlug?: string;
5781
+ ticker?: string | null;
5782
+ }>;
5783
+ /**
5784
+ * On a 404 from a per-ticker endpoint (`entity_not_found`, `no_coverage`, and `not_found` for
5785
+ * a symbol we track no stock under): one plain sentence and where to look next.
5786
+ */
5787
+ coverage?: {
5788
+ /** One short sentence, such as "We don't cover XYZQ yet." */
5789
+ message?: string;
5790
+ /** A tracked spelling of the same symbol, present only when one is obvious (`BRK/B` gives `BRK.B`). */
5791
+ didYouMean?: string;
5792
+ /** The endpoint that lists what this endpoint covers. */
5793
+ coveredTickersUrl?: string;
5794
+ /** The docs section on per-ticker 404s. */
5795
+ docsUrl?: string;
5796
+ [key: string]: unknown;
5797
+ };
5798
+ /** `"non_us_listing"` when the symbol is spelled as a listing on a non-US exchange. */
5799
+ reason?: string;
5800
+ /**
5801
+ * On a 404 where the symbol is a fund or index (`ticker_is_etf`, `ticker_is_index`): API paths
5802
+ * that answer the question for it instead.
5803
+ */
5804
+ seeInstead?: string[];
5805
+ /**
5806
+ * On a free key's 429: what PRO adds. PRO and the plans above it never receive it.
5807
+ */
5808
+ upgrade?: {
5809
+ plan?: string;
5810
+ message?: string;
5811
+ requestsPerMinute?: number;
5812
+ unlimitedMonthlyRequests?: boolean;
5813
+ url?: string;
5814
+ [key: string]: unknown;
5815
+ };
5816
+ [key: string]: unknown;
5817
+ }
5619
5818
  declare class SentiSenseError extends Error {
5620
5819
  status?: number;
5621
5820
  code?: string;
5622
- constructor(message: string, status?: number, code?: string);
5821
+ /**
5822
+ * The parsed JSON body of the error response, so fields beyond `code` and `message` are
5823
+ * readable: a 404's `suggestions` and `coverage` block (`coverage.didYouMean`,
5824
+ * `coverage.coveredTickersUrl`), a free key's 429 `upgrade` block, a fund's `seeInstead`.
5825
+ *
5826
+ * `undefined` when the response body was not a JSON object, and when the error did not come
5827
+ * from an HTTP response at all (a timeout or a network failure).
5828
+ */
5829
+ body?: ErrorBody;
5830
+ constructor(message: string, status?: number, code?: string, body?: ErrorBody);
5623
5831
  }
5624
5832
  declare class AuthenticationError extends SentiSenseError {
5625
- constructor(message: string, status: number, code?: string);
5833
+ constructor(message: string, status: number, code?: string, body?: ErrorBody);
5626
5834
  }
5627
5835
  declare class NotFoundError extends SentiSenseError {
5628
- constructor(message: string, code?: string);
5836
+ constructor(message: string, code?: string, body?: ErrorBody);
5629
5837
  }
5630
5838
  /**
5631
5839
  * Thrown when a deep chart range is still being assembled.
@@ -5647,6 +5855,8 @@ declare class DeepHistoryUnavailableError extends SentiSenseError {
5647
5855
  * response without retrying, and `message` says when the allowance resets.
5648
5856
  * - `"key_limit_reached"`: a temporary key from `sentisense init` used its daily or total
5649
5857
  * allowance. Thrown on the first response without retrying; keeping the key lifts it.
5858
+ *
5859
+ * On a free key, `body.upgrade` says what PRO adds.
5650
5860
  */
5651
5861
  declare class RateLimitError extends SentiSenseError {
5652
5862
  /**
@@ -5656,7 +5866,7 @@ declare class RateLimitError extends SentiSenseError {
5656
5866
  * `NaN`, so `setTimeout(fn, err.retryAfter * 1000)` can never fire immediately.
5657
5867
  */
5658
5868
  retryAfter?: number;
5659
- constructor(message: string, code?: string, retryAfter?: number);
5869
+ constructor(message: string, code?: string, retryAfter?: number, body?: ErrorBody);
5660
5870
  }
5661
5871
  declare class TemporarilyUnavailableError extends SentiSenseError {
5662
5872
  /**
@@ -5669,12 +5879,12 @@ declare class TemporarilyUnavailableError extends SentiSenseError {
5669
5879
  * server that has told you it is not ready.
5670
5880
  */
5671
5881
  retryAfter?: number;
5672
- constructor(message: string, retryAfter?: number, code?: string);
5882
+ constructor(message: string, retryAfter?: number, code?: string, body?: ErrorBody);
5673
5883
  }
5674
5884
  declare class APIError extends SentiSenseError {
5675
- constructor(message: string, status: number, code?: string);
5885
+ constructor(message: string, status: number, code?: string, body?: ErrorBody);
5676
5886
  }
5677
5887
 
5678
- declare const VERSION = "0.77.0";
5888
+ declare const VERSION = "0.78.1";
5679
5889
 
5680
- 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 EtfMembership, 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 GetInstitutionDetailOptions, type GetInstitutionHistoryOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, type GetOptionsIntradayHistoryOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticianMemberOptions, type GetPoliticiansOptions, type GetRankedEarningsOptions, type GetRecentEarningsOptions, type GetShortInterestOptions, type GetShortVolumeOptions, type GetStockEtfsOptions, 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 InstitutionChangeFilter, type InstitutionChangeType, type InstitutionDetail, type InstitutionHistory, type InstitutionHistoryQuarter, type InstitutionHolding, type InstitutionList, type InstitutionListResponse, type InstitutionMatchTotals, type InstitutionPositionPoint, 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 TrackerFilter, type TrackerGeoEntry, type TrackerGetParams, 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 };
5890
+ 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 ErrorBody, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfMembership, type EtfQuote, type EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type ExtendedHoursInfo, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsHistory, type FundamentalsLineSource, 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 GetFundamentalsHistoryOptions, type GetHoldersHistoryOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetInstitutionDetailOptions, type GetInstitutionHistoryOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, type GetOptionsIntradayHistoryOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticianMemberOptions, type GetPoliticiansOptions, type GetRankedEarningsOptions, type GetRecentEarningsOptions, type GetShortInterestOptions, type GetShortVolumeOptions, type GetStockEtfsOptions, 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 InstitutionChangeFilter, type InstitutionChangeType, type InstitutionDetail, type InstitutionHistory, type InstitutionHistoryQuarter, type InstitutionHolding, type InstitutionList, type InstitutionListResponse, type InstitutionMatchTotals, type InstitutionPositionPoint, 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 TrackerFilter, type TrackerGeoEntry, type TrackerGetParams, 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
@@ -1,21 +1,22 @@
1
1
  // src/errors.ts
2
2
  var SentiSenseError = class extends Error {
3
- constructor(message, status, code) {
3
+ constructor(message, status, code, body) {
4
4
  super(message);
5
5
  this.name = "SentiSenseError";
6
6
  this.status = status;
7
7
  this.code = code;
8
+ this.body = body;
8
9
  }
9
10
  };
10
11
  var AuthenticationError = class extends SentiSenseError {
11
- constructor(message, status, code) {
12
- super(message, status, code);
12
+ constructor(message, status, code, body) {
13
+ super(message, status, code, body);
13
14
  this.name = "AuthenticationError";
14
15
  }
15
16
  };
16
17
  var NotFoundError = class extends SentiSenseError {
17
- constructor(message, code) {
18
- super(message, 404, code);
18
+ constructor(message, code, body) {
19
+ super(message, 404, code, body);
19
20
  this.name = "NotFoundError";
20
21
  }
21
22
  };
@@ -27,22 +28,22 @@ var DeepHistoryUnavailableError = class extends SentiSenseError {
27
28
  }
28
29
  };
29
30
  var RateLimitError = class extends SentiSenseError {
30
- constructor(message, code, retryAfter) {
31
- super(message, 429, code);
31
+ constructor(message, code, retryAfter, body) {
32
+ super(message, 429, code, body);
32
33
  this.name = "RateLimitError";
33
34
  this.retryAfter = retryAfter;
34
35
  }
35
36
  };
36
37
  var TemporarilyUnavailableError = class extends SentiSenseError {
37
- constructor(message, retryAfter, code) {
38
- super(message, 503, code);
38
+ constructor(message, retryAfter, code, body) {
39
+ super(message, 503, code, body);
39
40
  this.name = "TemporarilyUnavailableError";
40
41
  this.retryAfter = retryAfter;
41
42
  }
42
43
  };
43
44
  var APIError = class extends SentiSenseError {
44
- constructor(message, status, code) {
45
- super(message, status, code);
45
+ constructor(message, status, code, body) {
46
+ super(message, status, code, body);
46
47
  this.name = "APIError";
47
48
  }
48
49
  };
@@ -434,13 +435,18 @@ var EntityMetrics = class {
434
435
  *
435
436
  * @param symbol Ticker symbol (e.g. "AAPL") or entity urlSlug.
436
437
  * @param metricType The metric to break down (e.g. "mentions" or "sentiment").
437
- * @param options Optional dimension parameter.
438
+ * @param options Optional dimension, and an optional window as `startTime` / `endTime` in
439
+ * epoch milliseconds. Without a window the API uses the last 7 days.
438
440
  */
439
441
  async getDistribution(symbol, metricType, options = {}) {
440
- const { dimension = "source" } = options;
442
+ const { dimension = "source", startTime, endTime } = options;
441
443
  return this.client.get(
442
444
  `/api/v2/metrics/entity/${encodeURIComponent(symbol)}/distribution/${encodeURIComponent(metricType)}`,
443
- { dimension }
445
+ {
446
+ dimension,
447
+ ...startTime !== void 0 && { startTime },
448
+ ...endTime !== void 0 && { endTime }
449
+ }
444
450
  );
445
451
  }
446
452
  };
@@ -1122,6 +1128,9 @@ var Stocks = class {
1122
1128
  * Get aggregate quote snapshot: live price, today OHLC, 52-week range,
1123
1129
  * market cap, P/E, EPS TTM, and dividend yield in a single call.
1124
1130
  * All fields except `ticker` may be null when upstream data is unavailable.
1131
+ *
1132
+ * A fund ticker gets a normal quote without AUM or NAV, plus `seeInstead` pointing at the
1133
+ * fund quote when that covers it: call `etfs.quote()` for those fields.
1125
1134
  */
1126
1135
  async getQuote(ticker) {
1127
1136
  return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/quote`);
@@ -1250,6 +1259,18 @@ var Stocks = class {
1250
1259
  async getFundamentals(ticker, options) {
1251
1260
  return this.client.get("/api/v1/stocks/fundamentals", { ticker, ...options });
1252
1261
  }
1262
+ /**
1263
+ * Get up to 40 quarters or 20 years of full financial statements, newest first: the same
1264
+ * period object as `getFundamentals()`, with the trailing-twelve-month, price-ratio and market
1265
+ * fields null on every row. A ticker with no statements resolves with an empty `periods` and a
1266
+ * `reason` rather than throwing.
1267
+ *
1268
+ * Periods served from an SEC-backed record carry the optional provenance fields `source`,
1269
+ * `sourceRef`, `secFiled` and `lineSources`; see {@link Fundamentals}.
1270
+ */
1271
+ async getFundamentalsHistory(ticker, options) {
1272
+ return this.client.get("/api/v1/stocks/fundamentals/history", { ticker, ...options });
1273
+ }
1253
1274
  /** Get available fiscal periods. The periods are in `periods`. */
1254
1275
  async getFundamentalsPeriods(ticker) {
1255
1276
  return this.client.get("/api/v1/stocks/fundamentals/periods", { ticker });
@@ -1536,7 +1557,7 @@ function serializeTrackerParams(params) {
1536
1557
  }
1537
1558
 
1538
1559
  // src/version.ts
1539
- var VERSION = "0.77.0";
1560
+ var VERSION = "0.78.1";
1540
1561
 
1541
1562
  // src/client.ts
1542
1563
  var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -1566,6 +1587,14 @@ function clampRetryAfter(raw, maxWaitS) {
1566
1587
  function retryAfterSeconds(raw, defaultS, maxWaitS) {
1567
1588
  return clampRetryAfter(raw, maxWaitS) ?? defaultS;
1568
1589
  }
1590
+ async function readErrorBody(response) {
1591
+ try {
1592
+ const parsed = await response.json();
1593
+ return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : void 0;
1594
+ } catch {
1595
+ return void 0;
1596
+ }
1597
+ }
1569
1598
  function sleep(ms) {
1570
1599
  return new Promise((resolve) => setTimeout(resolve, ms));
1571
1600
  }
@@ -1667,13 +1696,12 @@ var SentiSense = class {
1667
1696
  Number.POSITIVE_INFINITY
1668
1697
  );
1669
1698
  if (requestedS > MAX_RATE_LIMIT_WAIT_S) {
1670
- try {
1671
- await response.body?.cancel();
1672
- } catch {
1673
- }
1699
+ const body = await readErrorBody(response);
1674
1700
  throw new TemporarilyUnavailableError(
1675
1701
  `Server asked for a ${Math.round(requestedS)}s wait, longer than this client's ${MAX_RATE_LIMIT_WAIT_S}s budget`,
1676
- requestedS
1702
+ requestedS,
1703
+ void 0,
1704
+ body
1677
1705
  );
1678
1706
  }
1679
1707
  delayMs = requestedS * 1e3;
@@ -1754,32 +1782,29 @@ var SentiSense = class {
1754
1782
  return url.toString();
1755
1783
  }
1756
1784
  async handleErrorResponse(response) {
1757
- let body = {};
1758
- try {
1759
- body = await response.json();
1760
- } catch {
1761
- }
1762
- const message = body.message ?? response.statusText ?? "API request failed";
1763
- const code = body.error;
1785
+ const body = await readErrorBody(response);
1786
+ const message = body?.message ?? response.statusText ?? "API request failed";
1787
+ const code = body?.error;
1764
1788
  switch (response.status) {
1765
1789
  case 401:
1766
1790
  case 403:
1767
1791
  throw new AuthenticationError(
1768
1792
  this.apiKey ? message : `${message} ${MISSING_KEY_HINT}`,
1769
1793
  response.status,
1770
- code
1794
+ code,
1795
+ body
1771
1796
  );
1772
1797
  case 404:
1773
- throw new NotFoundError(message, code);
1798
+ throw new NotFoundError(message, code, body);
1774
1799
  case 429: {
1775
1800
  const retryAfter = clampRetryAfter(
1776
1801
  response.headers.get("Retry-After"),
1777
1802
  MAX_RATE_LIMIT_WAIT_S
1778
1803
  );
1779
- throw new RateLimitError(message, code, retryAfter);
1804
+ throw new RateLimitError(message, code, retryAfter, body);
1780
1805
  }
1781
1806
  default:
1782
- throw new APIError(message, response.status, code);
1807
+ throw new APIError(message, response.status, code, body);
1783
1808
  }
1784
1809
  }
1785
1810
  };