finance_query/models/calendar/
market.rs

1//! Market-wide calendar models.
2//!
3//! Returned by the [`Capability::CALENDAR`](crate::Capability::CALENDAR) route
4//! via [`Providers::calendar`](crate::Providers::calendar). These span the whole
5//! market over a date range, unlike [`CalendarEvent`](super::CalendarEvent),
6//! which builds a per-symbol timeline from already-fetched Yahoo quote data.
7
8use serde::{Deserialize, Serialize};
9
10/// Which market-wide calendar to fetch.
11#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
12#[non_exhaustive]
13pub enum CalendarKind {
14    /// Earnings releases.
15    Earnings,
16    /// Initial public offerings.
17    Ipo,
18    /// Dividend payments.
19    Dividend,
20    /// Stock splits.
21    Split,
22    /// Macro-economic releases.
23    Economic,
24    /// Market holidays and early closes.
25    MarketHoliday,
26    /// Live exchange open/closed status — a snapshot, not a dated event, so
27    /// providers serving it ignore the `from`/`to` range.
28    MarketStatus,
29}
30
31impl CalendarKind {
32    /// The [`Operation`](crate::providers::Operation) this kind dispatches as.
33    pub(crate) fn operation(self) -> crate::providers::Operation {
34        use crate::providers::Operation;
35        match self {
36            Self::Earnings => Operation::EarningsCalendar,
37            Self::Ipo => Operation::IpoCalendar,
38            Self::Dividend => Operation::DividendCalendar,
39            Self::Split => Operation::SplitCalendar,
40            Self::Economic => Operation::EconomicCalendar,
41            Self::MarketHoliday => Operation::HolidayCalendar,
42            Self::MarketStatus => Operation::MarketStatus,
43        }
44    }
45}
46
47/// One market-wide calendar entry.
48///
49/// The `kind`-specific payload lives in [`MarketCalendarEntry::detail`].
50#[derive(Debug, Clone, Serialize, Deserialize)]
51#[non_exhaustive]
52pub struct MarketCalendarEntry {
53    /// Ticker symbol. `None` for economic releases, which are market-wide.
54    pub symbol: Option<String>,
55    /// Event date as reported by the provider (`YYYY-MM-DD`, or a timestamp
56    /// string for economic releases).
57    pub date: Option<String>,
58    /// Event-specific payload.
59    pub detail: CalendarDetail,
60}
61
62/// The event-specific payload of a [`MarketCalendarEntry`].
63#[derive(Debug, Clone, Serialize, Deserialize)]
64#[non_exhaustive]
65#[serde(tag = "type", rename_all = "snake_case")]
66pub enum CalendarDetail {
67    /// An earnings release, with actuals once reported.
68    Earnings {
69        /// Reported EPS, if already released.
70        eps: Option<f64>,
71        /// Consensus EPS estimate.
72        eps_estimated: Option<f64>,
73        /// Reported revenue, if already released.
74        revenue: Option<f64>,
75        /// Consensus revenue estimate.
76        revenue_estimated: Option<f64>,
77        /// End of the fiscal period being reported (`YYYY-MM-DD`).
78        fiscal_date_ending: Option<String>,
79        /// Time of day for the release (e.g. `"amc"`, `"bmo"`).
80        time: Option<String>,
81    },
82    /// An initial public offering.
83    Ipo {
84        /// Company name.
85        company: Option<String>,
86        /// Listing exchange.
87        exchange: Option<String>,
88        /// Corporate action description (e.g. `"expected"`, `"priced"`).
89        actions: Option<String>,
90        /// Shares offered.
91        shares: Option<f64>,
92        /// Offering price range as reported (e.g. `"17.00-19.00"`).
93        price_range: Option<String>,
94        /// Market capitalisation at offering.
95        market_cap: Option<f64>,
96    },
97    /// A dividend payment.
98    Dividend {
99        /// Dividend amount per share.
100        dividend: Option<f64>,
101        /// Split-adjusted dividend amount per share.
102        adj_dividend: Option<f64>,
103        /// Record date (`YYYY-MM-DD`).
104        record_date: Option<String>,
105        /// Payment date (`YYYY-MM-DD`).
106        payment_date: Option<String>,
107        /// Declaration date (`YYYY-MM-DD`).
108        declaration_date: Option<String>,
109    },
110    /// A stock split.
111    Split {
112        /// Split ratio numerator (new shares).
113        numerator: Option<f64>,
114        /// Split ratio denominator (old shares).
115        denominator: Option<f64>,
116    },
117    /// A market holiday or early close.
118    MarketHoliday {
119        /// Holiday name (e.g. `"Thanksgiving"`).
120        name: Option<String>,
121        /// Exchange the holiday applies to (e.g. `"NYSE"`).
122        exchange: Option<String>,
123        /// Status (e.g. `"closed"`, `"early-close"`).
124        status: Option<String>,
125        /// Open time, when the exchange opens late or closes early.
126        open: Option<String>,
127        /// Close time, when the exchange closes early.
128        close: Option<String>,
129    },
130    /// A macro-economic release.
131    Economic {
132        /// Event name (e.g. `"CPI m/m"`).
133        event: Option<String>,
134        /// Country code or name.
135        country: Option<String>,
136        /// Reported value, if already released.
137        actual: Option<f64>,
138        /// Previous period's value.
139        previous: Option<f64>,
140        /// Consensus estimate.
141        estimate: Option<f64>,
142        /// Absolute change from the previous value.
143        change: Option<f64>,
144        /// Percentage change from the previous value.
145        change_percentage: Option<f64>,
146        /// Provider-assigned impact rating (e.g. `"High"`).
147        impact: Option<String>,
148    },
149}
finance_query/models/calendar/market.rs

finance_query/models/calendar/
market.rs
