Skip to main content

financial_api/
meta.rs

1use serde::Serialize;
2
3use crate::endpoints;
4use crate::{AssetType, Client, Error, Exchange, Response, SearchQuery, TickerData};
5
6/// Parameters for target search and cross-market disambiguation.
7#[derive(Debug, Clone, Serialize)]
8pub struct TickerSearchRequest {
9    q: SearchQuery,
10    #[serde(skip_serializing_if = "Option::is_none")]
11    exchange: Option<Exchange>,
12    #[serde(skip_serializing_if = "Option::is_none")]
13    asset_type: Option<String>,
14    limit: u8,
15}
16
17impl TickerSearchRequest {
18    #[must_use]
19    pub const fn new(q: SearchQuery) -> Self {
20        Self {
21            q,
22            exchange: None,
23            asset_type: None,
24            limit: 10,
25        }
26    }
27
28    #[must_use]
29    pub const fn exchange(mut self, exchange: Exchange) -> Self {
30        self.exchange = Some(exchange);
31        self
32    }
33
34    #[must_use]
35    pub fn asset_types(mut self, asset_types: impl IntoIterator<Item = AssetType>) -> Self {
36        self.asset_type = join_asset_types(asset_types);
37        self
38    }
39
40    pub fn limit(mut self, limit: u8) -> Result<Self, crate::ValidationError> {
41        if !(1..=50).contains(&limit) {
42            return Err(crate::ValidationError::new(
43                "limit",
44                "must be in the range 1..=50",
45            ));
46        }
47        self.limit = limit;
48        Ok(self)
49    }
50}
51
52impl Client {
53    /// Search targets by complete code, local ticker, or name.
54    pub async fn tickers_search(
55        &self,
56        request: &TickerSearchRequest,
57    ) -> Result<Response<TickerData>, Error> {
58        self.get(endpoints::TICKERS_SEARCH, request).await
59    }
60}
61
62#[cfg(test)]
63mod tests {
64    use super::{TickerListRequest, TickerSearchRequest};
65    use crate::SearchQuery;
66
67    #[test]
68    fn request_builders_enforce_documented_page_bounds() {
69        let search = || TickerSearchRequest::new(SearchQuery::new("600519").unwrap());
70        assert!(search().limit(0).is_err());
71        assert!(search().limit(1).is_ok());
72        assert!(search().limit(50).is_ok());
73        assert!(search().limit(51).is_err());
74
75        assert!(TickerListRequest::new().page(0, 0).is_err());
76        assert!(TickerListRequest::new().page(1, 0).is_ok());
77        assert!(TickerListRequest::new().page(10_000, u32::MAX).is_ok());
78        assert!(TickerListRequest::new().page(10_001, 0).is_err());
79    }
80}
81
82/// Parameters for browsing the target code table.
83#[derive(Debug, Clone, Serialize)]
84pub struct TickerListRequest {
85    #[serde(skip_serializing_if = "Option::is_none")]
86    asset_type: Option<String>,
87    limit: u16,
88    offset: u32,
89}
90
91impl TickerListRequest {
92    #[must_use]
93    pub const fn new() -> Self {
94        Self {
95            asset_type: None,
96            limit: 1_000,
97            offset: 0,
98        }
99    }
100
101    #[must_use]
102    pub fn asset_types(mut self, asset_types: impl IntoIterator<Item = AssetType>) -> Self {
103        self.asset_type = join_asset_types(asset_types);
104        self
105    }
106
107    pub fn page(mut self, limit: u16, offset: u32) -> Result<Self, crate::ValidationError> {
108        if limit == 0 || limit > 10_000 {
109            return Err(crate::ValidationError::new(
110                "limit",
111                "must be in the range 1..=10000",
112            ));
113        }
114        self.limit = limit;
115        self.offset = offset;
116        Ok(self)
117    }
118}
119
120fn join_asset_types(asset_types: impl IntoIterator<Item = AssetType>) -> Option<String> {
121    let mut values = Vec::new();
122    for asset_type in asset_types {
123        let value = asset_type.as_str();
124        if !values.contains(&value) {
125            values.push(value);
126        }
127    }
128    (!values.is_empty()).then(|| values.join(","))
129}
130
131impl Default for TickerListRequest {
132    fn default() -> Self {
133        Self::new()
134    }
135}
136
137impl Client {
138    /// Browse the normalized target code table.
139    pub async fn tickers_list(
140        &self,
141        request: &TickerListRequest,
142    ) -> Result<Response<TickerData>, Error> {
143        self.get(endpoints::TICKERS_LIST, request).await
144    }
145}