finance_query/providers/
operation.rs

1//! The [`Operation`] enum: one variant per adapter method.
2
3use super::{Capability, Provider};
4use crate::error::FinanceError;
5
6/// A single provider-adapter operation — finer-grained than [`Capability`]
7/// (e.g. `Chart`, `ChartRange`, and `Spark` all fall under `Capability::CHART`).
8///
9/// Used in [`crate::FinanceError::NotSupported`] to say exactly which method a
10/// provider doesn't implement; [`Operation::capability`] recovers the coarser
11/// bit for computing which other providers could satisfy it.
12#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
13#[non_exhaustive]
14pub enum Operation {
15    /// Single-symbol quote.
16    Quote,
17    /// Historical OHLCV chart over an interval/range.
18    Chart,
19    /// Historical OHLCV chart over a custom timestamp range.
20    ChartRange,
21    /// Financial statements (income/balance/cash flow).
22    Financials,
23    /// Symbol news.
24    News,
25    /// Similar-symbol recommendations.
26    Recommendations,
27    /// Options chain.
28    Options,
29    /// Corporate calendar events (earnings, dividends, splits).
30    Events,
31    /// Batch quotes for multiple symbols in one request.
32    QuotesBatch,
33    /// Lightweight sparkline data for multiple symbols in one request.
34    Spark,
35    /// Cryptocurrency quote.
36    CryptoQuote,
37    /// Market-wide crypto news.
38    CryptoNews,
39    /// Macro-economic data series.
40    EconomicSeries,
41    /// Foreign exchange currency pair quote.
42    ForexQuote,
43    /// Market-wide forex news.
44    ForexNews,
45    /// Stock market index quote.
46    IndicesQuote,
47    /// Futures contract quote.
48    FuturesQuote,
49    /// Commodity price quote.
50    CommoditiesQuote,
51    /// SEC EDGAR filing data.
52    Filings,
53    /// Symbol search by free-text query.
54    SymbolSearch,
55    /// Detailed reference data for one symbol.
56    SymbolDetails,
57    /// Tradable exchange listing.
58    Exchanges,
59    /// Screener query over the provider's universe.
60    Screener,
61    /// Market-wide earnings calendar.
62    EarningsCalendar,
63    /// Market-wide IPO calendar.
64    IpoCalendar,
65    /// Market-wide dividend calendar.
66    DividendCalendar,
67    /// Market-wide stock split calendar.
68    SplitCalendar,
69    /// Market-wide economic event calendar.
70    EconomicCalendar,
71    /// Sector and industry performance statistics.
72    SectorPerformance,
73    /// Market movers — gainers, losers, most active.
74    MarketMovers,
75    /// Historical sector performance.
76    SectorPerformanceHistory,
77    /// Market-wide holiday calendar.
78    HolidayCalendar,
79    /// Live exchange open/closed status.
80    MarketStatus,
81    /// Current constituents of a major index.
82    IndexConstituents,
83    /// Historical constituent changes of a major index.
84    IndexConstituentChanges,
85    /// Short interest (settlement-date positions).
86    ShortInterest,
87    /// Daily short volume.
88    ShortVolume,
89    /// Share float and shares outstanding.
90    ShareFloat,
91    /// Sectioned text of an SEC filing.
92    FilingSections,
93    /// Risk factors extracted from SEC filings.
94    RiskFactors,
95    /// Company press releases.
96    PressReleases,
97    /// Earnings call transcript, provider-neutral shape.
98    EarningsTranscript,
99    /// Total value locked in a DeFi protocol.
100    #[cfg(feature = "defi")]
101    ProtocolTvl,
102    /// Historical total value locked in a DeFi protocol.
103    #[cfg(feature = "defi")]
104    ProtocolTvlHistory,
105    /// Weekly CFTC Commitments of Traders futures positioning.
106    #[cfg(feature = "cftc")]
107    CommitmentsOfTraders,
108    /// Aggregated analyst price-target consensus.
109    PriceTargetConsensus,
110    /// Price-target publication activity over trailing windows.
111    PriceTargetSummary,
112    /// Aggregated analyst rating consensus.
113    RatingConsensus,
114    /// Trailing-twelve-month key-metrics snapshot.
115    KeyMetricsTtm,
116    /// Trailing-twelve-month ratios snapshot.
117    RatiosTtm,
118    /// Reported executive compensation.
119    ExecutiveCompensation,
120    /// Reported employee headcount.
121    EmployeeCount,
122    /// Company identity/classification profile.
123    CompanyProfile,
124    /// Cross-market snapshot for symbols spanning several asset classes.
125    UnifiedSnapshot,
126    /// Full-text search over filing content.
127    FilingSearch,
128    /// Insider transactions reported on Forms 3/4/5.
129    InsiderTrades,
130    /// Institutional holdings reported on Form 13F-HR.
131    InstitutionalHoldings,
132    /// Congressional (senate) stock-trade disclosures.
133    CongressionalTrades,
134    /// SEC fails-to-deliver data.
135    FailsToDeliver,
136    /// A macro series as it stood on a past date (vintage/ALFRED view).
137    EconomicSeriesAsOf,
138    /// Free-text search over the macro series catalog.
139    EconomicSearch,
140    /// Macro series category browsing.
141    EconomicCategories,
142    /// Scheduled macro data releases.
143    EconomicReleases,
144    /// US Treasury securities auctions, announced through settled.
145    #[cfg(feature = "fiscaldata")]
146    TreasuryAuctions,
147    /// US Treasury auctions scheduled but not yet held.
148    #[cfg(feature = "fiscaldata")]
149    UpcomingAuctions,
150    /// ETF profile and portfolio holdings.
151    EtfProfile,
152    /// Earnings-surprise history.
153    EarningsSurprises,
154    /// Raw per-analyst grade-action history.
155    GradingHistory,
156    /// The provider's whole listed-security universe.
157    ListingStatus,
158    /// Grouped daily OHLCV bars for every stock ticker on one date.
159    GroupedDaily,
160    /// Grouped daily OHLCV bars for every crypto ticker on one date.
161    CryptoGroupedDaily,
162    /// Grouped daily OHLCV bars for every forex ticker on one date.
163    ForexGroupedDaily,
164    /// Coins/nfts/categories trending in the last 24h.
165    #[cfg(feature = "crypto")]
166    CryptoTrending,
167    /// Aggregate global cryptocurrency market statistics.
168    #[cfg(feature = "crypto")]
169    CryptoGlobal,
170}
171
172impl Operation {
173    /// Short lowercase identifier (e.g. `"chart_range"`, `"crypto_quote"`).
174    pub fn as_str(self) -> &'static str {
175        match self {
176            Self::Quote => "quote",
177            Self::Chart => "chart",
178            Self::ChartRange => "chart_range",
179            Self::Financials => "financials",
180            Self::News => "news",
181            Self::Recommendations => "recommendations",
182            Self::Options => "options",
183            Self::Events => "events",
184            Self::QuotesBatch => "quotes_batch",
185            Self::Spark => "spark",
186            Self::CryptoQuote => "crypto_quote",
187            Self::CryptoNews => "crypto_news",
188            Self::EconomicSeries => "economic_series",
189            Self::ForexQuote => "forex_quote",
190            Self::ForexNews => "forex_news",
191            Self::IndicesQuote => "indices_quote",
192            Self::FuturesQuote => "futures_quote",
193            Self::CommoditiesQuote => "commodities_quote",
194            Self::Filings => "filings",
195            Self::SymbolSearch => "symbol_search",
196            Self::SymbolDetails => "symbol_details",
197            Self::Exchanges => "exchanges",
198            Self::Screener => "screener",
199            Self::EarningsCalendar => "earnings_calendar",
200            Self::IpoCalendar => "ipo_calendar",
201            Self::DividendCalendar => "dividend_calendar",
202            Self::SplitCalendar => "split_calendar",
203            Self::EconomicCalendar => "economic_calendar",
204            Self::SectorPerformance => "sector_performance",
205            Self::MarketMovers => "market_movers",
206            Self::SectorPerformanceHistory => "sector_performance_history",
207            Self::HolidayCalendar => "holiday_calendar",
208            Self::MarketStatus => "market_status",
209            Self::IndexConstituents => "index_constituents",
210            Self::IndexConstituentChanges => "index_constituent_changes",
211            Self::ShortInterest => "short_interest",
212            Self::ShortVolume => "short_volume",
213            Self::ShareFloat => "share_float",
214            Self::FilingSections => "filing_sections",
215            Self::RiskFactors => "risk_factors",
216            Self::PressReleases => "press_releases",
217            Self::EarningsTranscript => "earnings_transcript",
218            #[cfg(feature = "defi")]
219            Self::ProtocolTvl => "protocol_tvl",
220            #[cfg(feature = "defi")]
221            Self::ProtocolTvlHistory => "protocol_tvl_history",
222            #[cfg(feature = "cftc")]
223            Self::CommitmentsOfTraders => "commitments_of_traders",
224            Self::PriceTargetConsensus => "price_target_consensus",
225            Self::PriceTargetSummary => "price_target_summary",
226            Self::RatingConsensus => "rating_consensus",
227            Self::KeyMetricsTtm => "key_metrics_ttm",
228            Self::RatiosTtm => "ratios_ttm",
229            Self::ExecutiveCompensation => "executive_compensation",
230            Self::EmployeeCount => "employee_count",
231            Self::CompanyProfile => "company_profile",
232            Self::UnifiedSnapshot => "unified_snapshot",
233            Self::FilingSearch => "filing_search",
234            Self::InsiderTrades => "insider_trades",
235            Self::InstitutionalHoldings => "institutional_holdings",
236            Self::CongressionalTrades => "congressional_trades",
237            Self::FailsToDeliver => "fails_to_deliver",
238            Self::EconomicSeriesAsOf => "economic_series_as_of",
239            Self::EconomicSearch => "economic_search",
240            Self::EconomicCategories => "economic_categories",
241            Self::EconomicReleases => "economic_releases",
242            #[cfg(feature = "fiscaldata")]
243            Self::TreasuryAuctions => "treasury_auctions",
244            #[cfg(feature = "fiscaldata")]
245            Self::UpcomingAuctions => "upcoming_auctions",
246            Self::EtfProfile => "etf_profile",
247            Self::EarningsSurprises => "earnings_surprises",
248            Self::GradingHistory => "grading_history",
249            Self::ListingStatus => "listing_status",
250            Self::GroupedDaily => "grouped_daily",
251            Self::CryptoGroupedDaily => "crypto_grouped_daily",
252            Self::ForexGroupedDaily => "forex_grouped_daily",
253            #[cfg(feature = "crypto")]
254            Self::CryptoTrending => "crypto_trending",
255            #[cfg(feature = "crypto")]
256            Self::CryptoGlobal => "crypto_global",
257        }
258    }
259
260    /// The coarser [`Capability`] bit this operation falls under.
261    pub fn capability(self) -> Capability {
262        match self {
263            Self::Quote | Self::QuotesBatch | Self::UnifiedSnapshot => Capability::QUOTE,
264            Self::Chart
265            | Self::ChartRange
266            | Self::Spark
267            | Self::GroupedDaily
268            | Self::CryptoGroupedDaily
269            | Self::ForexGroupedDaily => Capability::CHART,
270            Self::Financials
271            | Self::ShortInterest
272            | Self::ShortVolume
273            | Self::ShareFloat
274            | Self::PriceTargetConsensus
275            | Self::PriceTargetSummary
276            | Self::RatingConsensus
277            | Self::KeyMetricsTtm
278            | Self::RatiosTtm
279            | Self::EtfProfile
280            | Self::EarningsSurprises
281            | Self::GradingHistory
282            | Self::CompanyProfile => Capability::FUNDAMENTALS,
283            Self::News
284            | Self::Recommendations
285            | Self::Events
286            | Self::PressReleases
287            | Self::ExecutiveCompensation
288            | Self::EmployeeCount
289            | Self::EarningsTranscript => Capability::CORPORATE,
290            Self::Options => Capability::OPTIONS,
291            Self::CryptoQuote | Self::CryptoNews => Capability::CRYPTO,
292            #[cfg(feature = "defi")]
293            Self::ProtocolTvl | Self::ProtocolTvlHistory => Capability::CRYPTO,
294            #[cfg(feature = "crypto")]
295            Self::CryptoTrending | Self::CryptoGlobal => Capability::CRYPTO,
296            Self::EconomicSeries
297            | Self::EconomicSeriesAsOf
298            | Self::EconomicSearch
299            | Self::EconomicCategories
300            | Self::EconomicReleases => Capability::ECONOMIC,
301            #[cfg(feature = "fiscaldata")]
302            Self::TreasuryAuctions | Self::UpcomingAuctions => Capability::ECONOMIC,
303            Self::ForexQuote | Self::ForexNews => Capability::FOREX,
304            Self::IndicesQuote | Self::IndexConstituents | Self::IndexConstituentChanges => {
305                Capability::INDICES
306            }
307            Self::FuturesQuote => Capability::FUTURES,
308            #[cfg(feature = "cftc")]
309            Self::CommitmentsOfTraders => Capability::FUTURES,
310            Self::CommoditiesQuote => Capability::COMMODITIES,
311            Self::Filings
312            | Self::FilingSections
313            | Self::RiskFactors
314            | Self::FilingSearch
315            | Self::InsiderTrades
316            | Self::InstitutionalHoldings
317            | Self::CongressionalTrades
318            | Self::FailsToDeliver => Capability::FILINGS,
319            Self::SymbolSearch
320            | Self::SymbolDetails
321            | Self::Exchanges
322            | Self::Screener
323            | Self::ListingStatus => Capability::DISCOVERY,
324            Self::EarningsCalendar
325            | Self::IpoCalendar
326            | Self::DividendCalendar
327            | Self::SplitCalendar
328            | Self::EconomicCalendar
329            | Self::HolidayCalendar
330            | Self::MarketStatus => Capability::CALENDAR,
331            Self::SectorPerformance | Self::MarketMovers | Self::SectorPerformanceHistory => {
332                Capability::MARKET
333            }
334        }
335    }
336
337    /// The error reported when `provider` does not serve this operation.
338    ///
339    /// Adapters reach for this when they detect the gap before dispatch has a
340    /// `&dyn ProviderAdapter` to hand (e.g. a symbol an exchange cannot name);
341    /// `ProviderCore::not_supported` is the same error built from an instance.
342    pub(crate) fn not_supported(self, provider: Provider) -> FinanceError {
343        FinanceError::NotSupported {
344            provider,
345            operation: self,
346            candidates: self.capability().candidate_providers(),
347        }
348    }
349}
350
351impl std::fmt::Display for Operation {
352    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
353        f.write_str(self.as_str())
354    }
355}
finance_query/providers/operation.rs

finance_query/providers/
operation.rs
