libfmp 1.3.1

Async, typed Rust client for the Financial Modeling Prep API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157

//! Commitment of Traders endpoint contracts.

use crate::{
    Client, Result,
    endpoints::{
        EndpointSpec, QueryEncoder, QueryParameters,
        metadata::{EndpointBounds, EndpointMetadata},
    },
    responses::commitment_of_traders::{CotAnalysis, CotReport, CotReportListing},
    types::{Date, Ticker},
};

/// Independently optional filters shared by the COT report and analysis routes.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct CotQuery {
    symbol: Option<Ticker>,
    from: Option<Date>,
    to: Option<Date>,
}

impl CotQuery {
    /// Creates an unfiltered query.
    pub const fn new() -> Self {
        Self {
            symbol: None,
            from: None,
            to: None,
        }
    }

    /// Filters by a provider COT symbol.
    pub fn with_symbol(mut self, symbol: Ticker) -> Self {
        self.symbol = Some(symbol);
        self
    }

    /// Sets the optional inclusive start date.
    pub const fn with_from(mut self, from: Date) -> Self {
        self.from = Some(from);
        self
    }

    /// Sets the optional inclusive end date.
    pub const fn with_to(mut self, to: Date) -> Self {
        self.to = Some(to);
        self
    }

    /// Borrows the optional provider COT symbol.
    pub const fn symbol(&self) -> Option<&Ticker> {
        self.symbol.as_ref()
    }

    /// Returns the optional inclusive start date.
    pub const fn from(&self) -> Option<Date> {
        self.from
    }

    /// Returns the optional inclusive end date.
    pub const fn to(&self) -> Option<Date> {
        self.to
    }
}

impl QueryParameters for CotQuery {
    fn encode(&self, encoder: &mut QueryEncoder<'_>) {
        encoder.optional("symbol", self.symbol.as_ref());
        encoder.optional("from", self.from);
        encoder.optional("to", self.to);
    }
}

const ANALYSIS_METADATA: EndpointMetadata =
    EndpointMetadata::new().with_bounds(EndpointBounds::new().with_date_range_days(90));

/// Describes `GET commitment-of-traders-report` without binding a transport.
pub fn cot_report(query: CotQuery) -> EndpointSpec<CotQuery, Vec<CotReport>> {
    EndpointSpec::get(
        "commitment-of-traders-report",
        "commitment-of-traders-report",
        query,
    )
}

/// Describes `GET commitment-of-traders-analysis` without binding a transport.
pub fn cot_analysis(query: CotQuery) -> EndpointSpec<CotQuery, Vec<CotAnalysis>> {
    EndpointSpec::get(
        "commitment-of-traders-analysis",
        "commitment-of-traders-analysis",
        query,
    )
    .with_metadata(ANALYSIS_METADATA)
}

/// Describes `GET commitment-of-traders-list` without binding a transport.
pub fn cot_report_list() -> EndpointSpec<(), Vec<CotReportListing>> {
    EndpointSpec::get(
        "commitment-of-traders-list",
        "commitment-of-traders-list",
        (),
    )
}

impl Client {
    /// Retrieves detailed Commitment of Traders reports.
    pub async fn cot_report(&self, query: CotQuery) -> Result<Vec<CotReport>> {
        self.execute(&cot_report(query)).await
    }

    /// Retrieves derived Commitment of Traders market analysis.
    pub async fn cot_analysis(&self, query: CotQuery) -> Result<Vec<CotAnalysis>> {
        self.execute(&cot_analysis(query)).await
    }

    /// Lists the Commitment of Traders reports available from the provider.
    pub async fn cot_report_list(&self) -> Result<Vec<CotReportListing>> {
        self.execute(&cot_report_list()).await
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn encoded(query: &impl QueryParameters) -> Vec<(String, String)> {
        let mut pairs = Vec::new();
        let mut visitor = |name: &str, value: &str| {
            pairs.push((name.to_owned(), value.to_owned()));
        };
        query.encode(&mut QueryEncoder::new(&mut visitor));
        pairs
    }

    #[test]
    fn query_encodes_exact_order_and_independent_omissions() {
        let from = Date::parse("2024-01-01").unwrap();
        let to = Date::parse("2024-03-01").unwrap();
        assert!(encoded(&CotQuery::new()).is_empty());
        assert_eq!(
            encoded(
                &CotQuery::new()
                    .with_symbol(Ticker::new("VX / Index").unwrap())
                    .with_from(from)
                    .with_to(to)
            ),
            [
                ("symbol".into(), "VX / Index".into()),
                ("from".into(), "2024-01-01".into()),
                ("to".into(), "2024-03-01".into()),
            ]
        );
        assert_eq!(
            encoded(&CotQuery::new().with_to(to)),
            [("to".into(), "2024-03-01".into())]
        );
    }
}