Skip to main content

financial_api/
index.rs

1use crate::endpoints;
2use crate::endpoints::join_values;
3use crate::{
4    Client, Error, IndexCatalogData, IndexConstituentsData, IndexHistoricalData, IndexTag,
5    PriceSnapshotData, Response, Thscode, UnixMillis, ValidationError,
6};
7
8const TEN_YEARS_MS: i64 = 315_576_000_000;
9
10impl Client {
11    /// List Tonghuashun indices for a catalog tag.
12    pub async fn index_catalog_ths_index_list(
13        &self,
14        tag: IndexTag,
15    ) -> Result<Response<IndexCatalogData>, Error> {
16        self.get(endpoints::INDEX_CATALOG, &[("tag", tag.to_string())])
17            .await
18    }
19
20    /// Fetch the current constituent list of one index.
21    pub async fn index_constituents_ths_stock_list(
22        &self,
23        thscode: &Thscode,
24    ) -> Result<Response<IndexConstituentsData>, Error> {
25        self.get(
26            endpoints::INDEX_CONSTITUENTS,
27            &[("thscode", thscode.to_string())],
28        )
29        .await
30    }
31
32    /// Fetch snapshots for one or more exchange or Tonghuashun indices.
33    pub async fn index_prices_snapshot(
34        &self,
35        thscodes: &[Thscode],
36    ) -> Result<Response<PriceSnapshotData>, Error> {
37        self.get(
38            endpoints::INDEX_SNAPSHOT,
39            &[("thscodes", join_values("thscodes", thscodes, None)?)],
40        )
41        .await
42    }
43
44    /// Fetch historical daily K-lines for one index.
45    pub async fn index_prices_historical(
46        &self,
47        thscode: &Thscode,
48        start: UnixMillis,
49        end: UnixMillis,
50    ) -> Result<Response<IndexHistoricalData>, Error> {
51        validate_history_window(start, end)?;
52        let query = [
53            ("thscode", thscode.to_string()),
54            ("interval", "1d".to_owned()),
55            ("start", start.to_string()),
56            ("end", end.to_string()),
57        ];
58        self.get(endpoints::INDEX_HISTORICAL, &query).await
59    }
60}
61
62fn validate_history_window(start: UnixMillis, end: UnixMillis) -> Result<(), ValidationError> {
63    if end < start {
64        return Err(ValidationError::new(
65            "end",
66            "must not be earlier than start",
67        ));
68    }
69    if end.get() - start.get() > TEN_YEARS_MS {
70        return Err(ValidationError::new(
71            "end",
72            "requested time window exceeds ten years",
73        ));
74    }
75    Ok(())
76}
77
78#[cfg(test)]
79mod tests {
80    use super::*;
81    use crate::ApiKey;
82
83    #[test]
84    fn historical_window_enforces_order_and_ten_year_limit() {
85        let start = UnixMillis::new(1_000_000_000_000).unwrap();
86        let before_start = UnixMillis::new(start.get() - 1).unwrap();
87        let limit = UnixMillis::new(start.get() + TEN_YEARS_MS).unwrap();
88        let after_limit = UnixMillis::new(limit.get() + 1).unwrap();
89
90        assert!(validate_history_window(start, before_start).is_err());
91        assert!(validate_history_window(start, limit).is_ok());
92        assert!(validate_history_window(start, after_limit).is_err());
93    }
94
95    #[tokio::test]
96    async fn historical_prices_keeps_window_validation_on_its_call_edge() {
97        let client = Client::builder(ApiKey::new("test-api-key").unwrap())
98            .base_url("http://127.0.0.1:9")
99            .build()
100            .unwrap();
101        let index = Thscode::new("000300.SH").unwrap();
102        let start = UnixMillis::new(1_000_000_000_000).unwrap();
103        let invalid_ends = [
104            UnixMillis::new(start.get() - 1).unwrap(),
105            UnixMillis::new(start.get() + TEN_YEARS_MS + 1).unwrap(),
106        ];
107
108        for end in invalid_ends {
109            let error = client
110                .index_prices_historical(&index, start, end)
111                .await
112                .unwrap_err();
113            assert!(matches!(error, Error::InvalidInput(_)));
114        }
115    }
116}