1use std::fmt::{self, Write};
2
3use crate::{AShareCode, Thscode, ValidationError};
4
5#[derive(Debug, Clone, Copy, PartialEq, Eq)]
7pub struct EndpointInfo {
8 pub name: &'static str,
9 pub path: &'static str,
10}
11
12macro_rules! define_endpoints {
13 ($($constant:ident => ($name:literal, $path:literal)),+ $(,)?) => {
14 $(pub(crate) const $constant: &str = $path;)+
15
16 pub const SUPPORTED_ENDPOINTS: &[EndpointInfo] = &[
18 $(EndpointInfo { name: $name, path: $path },)+
19 ];
20 };
21}
22
23define_endpoints! {
24 INDEX_CATALOG => ("index_catalog_ths_index_list", "/api/a-share-index/catalog/ths-index-list"),
25 INDEX_CONSTITUENTS => ("index_constituents_ths_stock_list", "/api/a-share-index/constituents/ths-stock-list"),
26 INDEX_HISTORICAL => ("index_prices_historical", "/api/a-share-index/prices/historical"),
27 INDEX_SNAPSHOT => ("index_prices_snapshot", "/api/a-share-index/prices/snapshot"),
28 AUCTION_BENCHMARK => ("a_share_auction_short_term_benchmark", "/api/a-share/auction/short-term-benchmark"),
29 AUCTION_SNAPSHOT => ("a_share_auction_snapshot", "/api/a-share/auction/snapshot"),
30 TRADING_DAYS => ("calendar_trading_days", "/api/a-share/calendar/trading-days"),
31 ADJUSTMENT_FACTORS => ("corp_actions_adjustment_factors", "/api/a-share/corporate-actions/adjustment-factors"),
32 BALANCE_SHEETS => ("financials_balance_sheets", "/api/a-share/financials/balance-sheets"),
33 CASH_FLOW_STATEMENTS => ("financials_cash_flow_statements", "/api/a-share/financials/cash-flow-statements"),
34 INCOME_STATEMENTS => ("financials_income_statements", "/api/a-share/financials/income-statements"),
35 FINANCIAL_INDICATORS => ("financials_indicators", "/api/a-share/financials/indicators"),
36 PRICES_HISTORICAL => ("prices_historical", "/api/a-share/prices/historical"),
37 PRICES_SNAPSHOT => ("prices_snapshot", "/api/a-share/prices/snapshot"),
38 ANOMALY_LIST => ("special_data_anomaly_analysis_list", "/api/a-share/special-data/anomaly-analysis-list"),
39 ANOMALY_STOCK => ("special_data_anomaly_analysis_stock", "/api/a-share/special-data/anomaly-analysis-stock"),
40 DRAGON_TIGER => ("special_data_dragon_tiger_list", "/api/a-share/special-data/dragon-tiger-list"),
41 HOT_STOCK_LIST => ("special_data_hot_stock_list", "/api/a-share/special-data/hot-stock-list"),
42 HOT_STOCK_HISTORY => ("special_data_hot_stock_list_history", "/api/a-share/special-data/hot-stock-list-history"),
43 HOT_STOCK_TREND => ("special_data_hot_stock_rank_trend", "/api/a-share/special-data/hot-stock-rank-trend"),
44 LIMIT_BREAK_POOL => ("special_data_limit_break_pool", "/api/a-share/special-data/limit-break-pool"),
45 LIMIT_DOWN_POOL => ("special_data_limit_down_pool", "/api/a-share/special-data/limit-down-pool"),
46 LIMIT_UP_LADDER => ("special_data_limit_up_ladder", "/api/a-share/special-data/limit-up-ladder"),
47 LIMIT_UP_POOL => ("special_data_limit_up_pool", "/api/a-share/special-data/limit-up-pool"),
48 SKYROCKET_LIST => ("special_data_skyrocket_list", "/api/a-share/special-data/skyrocket-list"),
49 VALUATIONS_SNAPSHOT => ("a_share_valuations_snapshot", "/api/a-share/valuations/snapshot"),
50 DUMP_ADJUSTMENT_FACTORS => ("market_dump_adjustment_factors", "/api/dump/market-dumps/adjustment-factors/download-url"),
51 DUMP_DAILY_K_10D => ("market_dump_daily_k_10d", "/api/dump/market-dumps/daily-k-10d/download-url"),
52 DUMP_DAILY_K => ("market_dump_daily_k", "/api/dump/market-dumps/daily-k/download-url"),
53 FUND_COMPANY_DETAIL => ("fund_companies_detail", "/api/fund/companies/detail"),
54 FUND_DIVIDENDS => ("fund_corporate_actions_dividends", "/api/fund/corporate-actions/dividends"),
55 FUND_DIAGNOSTICS => ("fund_diagnostics_detail", "/api/fund/diagnostics/detail"),
56 FUND_BALANCE_SHEETS => ("fund_financials_balance_sheets", "/api/fund/financials/balance-sheets"),
57 FUND_INCOME_STATEMENTS => ("fund_financials_income_statements", "/api/fund/financials/income-statements"),
58 FUND_INDICATORS => ("fund_financials_indicators", "/api/fund/financials/indicators"),
59 FUND_HOLDERS_DETAIL => ("fund_holders_detail", "/api/fund/holders/detail"),
60 FUND_HOLDERS_TOP => ("fund_holders_top", "/api/fund/holders/top"),
61 FUND_MANAGER_DETAIL => ("fund_managers_detail", "/api/fund/managers/detail"),
62 FUND_MANAGER_EXPERIENCE => ("fund_managers_experience", "/api/fund/managers/experience"),
63 FUND_MANAGER_STYLE => ("fund_managers_investment_style", "/api/fund/managers/investment-style"),
64 FUND_MANAGER_PERFORMANCE => ("fund_managers_performance", "/api/fund/managers/performance"),
65 FUND_MARKET_HISTORICAL => ("fund_market_historical", "/api/fund/market/historical"),
66 FUND_MARKET_SNAPSHOT => ("fund_market_snapshot", "/api/fund/market/snapshot"),
67 FUND_NEWS => ("fund_news_article_list", "/api/fund/news/article-list"),
68 FUND_OFFERINGS => ("fund_offerings_list", "/api/fund/offerings/list"),
69 FUND_DRAWDOWNS => ("fund_performance_drawdowns", "/api/fund/performance/drawdowns"),
70 FUND_INDICATORS_HISTORICAL => ("fund_performance_indicators_historical", "/api/fund/performance/indicators-historical"),
71 FUND_NAV => ("fund_performance_nav", "/api/fund/performance/nav"),
72 FUND_RETURNS => ("fund_performance_returns", "/api/fund/performance/returns"),
73 FUND_ASSET_ALLOCATION => ("fund_portfolio_asset_allocation", "/api/fund/portfolio/asset-allocation"),
74 FUND_BOND_HISTORY => ("fund_portfolio_bond_history", "/api/fund/portfolio/bond-history"),
75 FUND_BOND_REPORT_DATES => ("fund_portfolio_bond_report_dates", "/api/fund/portfolio/bond-report-dates"),
76 FUND_HOLDINGS => ("fund_portfolio_holdings", "/api/fund/portfolio/holdings"),
77 FUND_INDUSTRY_ALLOCATION => ("fund_portfolio_industry_allocation", "/api/fund/portfolio/industry-allocation"),
78 FUND_STOCK_HISTORY => ("fund_portfolio_stock_history", "/api/fund/portfolio/stock-history"),
79 FUND_STOCK_REPORT_DATES => ("fund_portfolio_stock_report_dates", "/api/fund/portfolio/stock-report-dates"),
80 FUND_PROFILE => ("fund_profile_detail", "/api/fund/profile/detail"),
81 TICKERS_LIST => ("tickers_list", "/api/meta/tickers/list"),
82 TICKERS_SEARCH => ("tickers_search", "/api/meta/tickers/search"),
83}
84
85pub(crate) fn join_values<T: fmt::Display>(
86 field: &'static str,
87 values: &[T],
88 maximum: Option<usize>,
89) -> Result<String, ValidationError> {
90 validate_value_count(field, values.len(), maximum)?;
91 let mut joined = String::new();
92 for value in values {
93 if !joined.is_empty() {
94 joined.push(',');
95 }
96 write!(&mut joined, "{value}").expect("writing to a String cannot fail");
97 }
98 Ok(joined)
99}
100
101pub(crate) fn join_a_share_codes(
102 values: impl IntoIterator<Item = impl TryInto<AShareCode, Error: Into<ValidationError>>>,
103 maximum: Option<usize>,
104) -> Result<String, ValidationError> {
105 join_converted_values::<AShareCode>("thscodes", values, maximum)
106}
107
108pub(crate) fn join_thscodes(
109 values: impl IntoIterator<Item = impl TryInto<Thscode, Error: Into<ValidationError>>>,
110 maximum: Option<usize>,
111) -> Result<String, ValidationError> {
112 join_converted_values::<Thscode>("thscodes", values, maximum)
113}
114
115fn join_converted_values<T: fmt::Display>(
116 field: &'static str,
117 values: impl IntoIterator<Item = impl TryInto<T, Error: Into<ValidationError>>>,
118 maximum: Option<usize>,
119) -> Result<String, ValidationError> {
120 let mut joined = String::new();
121 let mut length = 0;
122 for value in values {
123 length += 1;
124 validate_value_count(field, length, maximum)?;
125 if !joined.is_empty() {
126 joined.push(',');
127 }
128 let value: T = value.try_into().map_err(Into::into)?;
129 write!(&mut joined, "{value}").expect("writing to a String cannot fail");
130 }
131 validate_value_count(field, length, None)?;
132 Ok(joined)
133}
134
135fn validate_value_count(
136 field: &'static str,
137 length: usize,
138 maximum: Option<usize>,
139) -> Result<(), ValidationError> {
140 if length == 0 {
141 return Err(ValidationError::new(field, "must not be empty"));
142 }
143 if maximum.is_some_and(|maximum| length > maximum) {
144 return Err(ValidationError::new(
145 field,
146 "contains more values than the endpoint allows",
147 ));
148 }
149 Ok(())
150}
151
152#[cfg(test)]
153mod tests {
154 use super::join_values;
155
156 #[test]
157 fn list_query_encoding_enforces_presence_and_optional_capacity() {
158 assert!(join_values::<u8>("values", &[], None).is_err());
159 assert_eq!(join_values("values", &[1, 2], Some(2)).unwrap(), "1,2");
160
161 let error = join_values("values", &[1, 2, 3], Some(2)).unwrap_err();
162 assert_eq!(error.field(), "values");
163 assert_eq!(
164 error.problem(),
165 "contains more values than the endpoint allows"
166 );
167 }
168}