longbridge/fundamental/

context.rs

use std::sync::Arc;

use longbridge_httpcli::{DcRegion, HttpClient, Json, Method};
use serde::{Serialize, de::DeserializeOwned};
use tracing::{Subscriber, dispatcher, instrument::WithSubscriber};

use crate::{Config, Market, Result, fundamental::types::*};

/// Convert a Unix-seconds string to RFC 3339.
fn unix_secs_str_to_rfc3339(s: &str) -> String {
    s.parse::<i64>()
        .ok()
        .and_then(|ts| time::OffsetDateTime::from_unix_timestamp(ts).ok())
        .map(|dt| {
            use time::format_description::well_known::Rfc3339;
            dt.format(&Rfc3339).unwrap_or_default()
        })
        .unwrap_or_else(|| s.to_string())
}

struct InnerFundamentalContext {
    http_cli: HttpClient,
    log_subscriber: Arc<dyn Subscriber + Send + Sync>,
}

impl Drop for InnerFundamentalContext {
    fn drop(&mut self) {
        dispatcher::with_default(&self.log_subscriber.clone().into(), || {
            tracing::info!("fundamental context dropped");
        });
    }
}

/// Fundamental data context — financial reports, analyst ratings, dividends,
/// valuation, company overview and more.
#[derive(Clone)]
pub struct FundamentalContext(Arc<InnerFundamentalContext>);

impl FundamentalContext {
    /// Create a [`FundamentalContext`]
    pub fn new(config: Arc<Config>) -> Self {
        let log_subscriber = config.create_log_subscriber("fundamental");
        dispatcher::with_default(&log_subscriber.clone().into(), || {
            tracing::info!(language = ?config.language, "creating fundamental context");
        });
        let ctx = Self(Arc::new(InnerFundamentalContext {
            http_cli: config.create_http_client(),
            log_subscriber,
        }));
        dispatcher::with_default(&ctx.0.log_subscriber.clone().into(), || {
            tracing::info!("fundamental context created");
        });
        ctx
    }

    /// Returns the log subscriber
    #[inline]
    pub fn log_subscriber(&self) -> Arc<dyn Subscriber + Send + Sync> {
        self.0.log_subscriber.clone()
    }

    async fn get<R, Q>(&self, path: &'static str, query: Q) -> Result<R>
    where
        R: DeserializeOwned + Send + Sync + 'static,
        Q: Serialize + Send + Sync,
    {
        Ok(self
            .0
            .http_cli
            .request(Method::GET, path)
            .query_params(query)
            .response::<Json<R>>()
            .send()
            .with_subscriber(self.0.log_subscriber.clone())
            .await?
            .0)
    }

    /// Like [`get`](Self::get), but restricted to a single data center. Used by
    /// region-limited endpoints (e.g. AP-only fundamentals).
    async fn get_dc<R, Q>(&self, path: &'static str, query: Q, dc_restrict: DcRegion) -> Result<R>
    where
        R: DeserializeOwned + Send + Sync + 'static,
        Q: Serialize + Send + Sync,
    {
        Ok(self
            .0
            .http_cli
            .request(Method::GET, path)
            .dc_restrict(dc_restrict)
            .query_params(query)
            .response::<Json<R>>()
            .send()
            .with_subscriber(self.0.log_subscriber.clone())
            .await?
            .0)
    }

    // ── financial_report ─────────────────────────────────────────

    /// Get financial reports for a security.
    ///
    /// Path: `GET /v1/quote/financial-reports`
    pub async fn financial_report(
        &self,
        symbol: impl Into<String>,
        kind: FinancialReportKind,
        period: Option<FinancialReportPeriod>,
    ) -> Result<FinancialReports> {
        let kind_str = match kind {
            FinancialReportKind::IncomeStatement => "IS",
            FinancialReportKind::BalanceSheet => "BS",
            FinancialReportKind::CashFlow => "CF",
            FinancialReportKind::All => "ALL",
        };
        let period_str = period.map(|p| match p {
            FinancialReportPeriod::Annual => "af",
            FinancialReportPeriod::SemiAnnual => "saf",
            FinancialReportPeriod::Q1 => "q1",
            FinancialReportPeriod::Q2 => "q2",
            FinancialReportPeriod::Q3 => "q3",
            FinancialReportPeriod::QuarterlyFull => "qf",
            FinancialReportPeriod::ThreeQ => "3q",
        });
        #[derive(Serialize)]
        struct Query {
            symbol: String,
            kind: &'static str,
            #[serde(skip_serializing_if = "Option::is_none")]
            report: Option<&'static str>,
        }
        self.get(
            "/v1/quote/financial-reports",
            Query {
                symbol: symbol.into(),
                kind: kind_str,
                report: period_str,
            },
        )
        .await
    }

    // ── institution_rating ────────────────────────────────────────

    /// Get analyst ratings for a security (combines latest + historical).
    ///
    /// Path: `GET /v1/quote/institution-rating-latest` +
    ///       `GET /v1/quote/institution-ratings`
    pub async fn institution_rating(&self, symbol: impl Into<String>) -> Result<InstitutionRating> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        let sym = symbol.into();
        let (latest, summary) = tokio::join!(
            self.get::<InstitutionRatingLatest, _>(
                "/v1/quote/institution-rating-latest",
                Query {
                    symbol: sym.clone()
                }
            ),
            self.get::<InstitutionRatingSummary, _>(
                "/v1/quote/institution-ratings",
                Query {
                    symbol: sym.clone()
                }
            ),
        );
        Ok(InstitutionRating {
            latest: latest?,
            summary: summary?,
        })
    }

    /// Get historical analyst rating details for a security.
    ///
    /// Path: `GET /v1/quote/institution-ratings/detail`
    pub async fn institution_rating_detail(
        &self,
        symbol: impl Into<String>,
    ) -> Result<InstitutionRatingDetail> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/institution-ratings/detail",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    // ── dividend ──────────────────────────────────────────────────

    /// Get dividend history for a security.
    ///
    /// Path: `GET /v1/quote/dividends`
    pub async fn dividend(&self, symbol: impl Into<String>) -> Result<DividendList> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/dividends",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    /// Get detailed dividend information for a security.
    ///
    /// Path: `GET /v1/quote/dividends/details`
    pub async fn dividend_detail(&self, symbol: impl Into<String>) -> Result<DividendList> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/dividends/details",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    // ── forecast_eps ──────────────────────────────────────────────

    /// Get EPS forecasts for a security.
    ///
    /// Path: `GET /v1/quote/forecast-eps`
    pub async fn forecast_eps(&self, symbol: impl Into<String>) -> Result<ForecastEps> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/forecast-eps",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    // ── consensus ─────────────────────────────────────────────────

    /// Get financial consensus estimates for a security.
    ///
    /// Path: `GET /v1/quote/financial-consensus-detail`
    pub async fn consensus(&self, symbol: impl Into<String>) -> Result<FinancialConsensus> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/financial-consensus-detail",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    // ── valuation ─────────────────────────────────────────────────

    /// Get valuation metrics (PE/PB/PS/dividend yield) for a security.
    ///
    /// Path: `GET /v1/quote/valuation`
    pub async fn valuation(&self, symbol: impl Into<String>) -> Result<ValuationData> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
            indicator: &'static str,
            range: &'static str,
        }
        self.get(
            "/v1/quote/valuation",
            Query {
                symbol: symbol.into(),
                indicator: "pe",
                range: "1",
            },
        )
        .await
    }

    /// Get historical valuation data for a security.
    ///
    /// Path: `GET /v1/quote/valuation/detail`
    pub async fn valuation_history(
        &self,
        symbol: impl Into<String>,
    ) -> Result<ValuationHistoryResponse> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/valuation/detail",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    // ── industry_valuation ────────────────────────────────────────

    /// Get valuation comparison against industry peers.
    ///
    /// Path: `GET /v1/quote/industry-valuation-comparison`
    pub async fn industry_valuation(
        &self,
        symbol: impl Into<String>,
    ) -> Result<IndustryValuationList> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/industry-valuation-comparison",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    /// Get valuation distribution within the industry.
    ///
    /// Path: `GET /v1/quote/industry-valuation-distribution`
    pub async fn industry_valuation_dist(
        &self,
        symbol: impl Into<String>,
    ) -> Result<IndustryValuationDist> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/industry-valuation-distribution",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    // ── company ───────────────────────────────────────────────────

    /// Get company overview information.
    ///
    /// Path: `GET /v1/quote/comp-overview`
    pub async fn company(&self, symbol: impl Into<String>) -> Result<CompanyOverview> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/comp-overview",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    // ── executive ─────────────────────────────────────────────────

    /// Get executive and board member information.
    ///
    /// Path: `GET /v1/quote/company-professionals`
    pub async fn executive(&self, symbol: impl Into<String>) -> Result<ExecutiveList> {
        #[derive(Serialize)]
        struct Query {
            // The endpoint takes a comma-separated list, so the parameter is
            // plural: `symbol=` is silently ignored and returns an empty group.
            symbols: String,
        }
        self.get(
            "/v1/quote/company-professionals",
            Query {
                symbols: symbol.into(),
            },
        )
        .await
    }

    // ── shareholder ───────────────────────────────────────────────

    /// Get major shareholders for a security.
    ///
    /// Path: `GET /v1/quote/shareholders`
    pub async fn shareholder(&self, symbol: impl Into<String>) -> Result<ShareholderList> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/shareholders",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    // ── fund_holder ───────────────────────────────────────────────

    /// Get funds and ETFs that hold a security.
    ///
    /// Path: `GET /v1/quote/fund-holders`
    pub async fn fund_holder(&self, symbol: impl Into<String>) -> Result<FundHolders> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/fund-holders",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    // ── corp_action ───────────────────────────────────────────────

    /// Get corporate actions (dividends, splits, buybacks, etc.).
    ///
    /// Path: `GET /v1/quote/company-act`
    pub async fn corp_action(&self, symbol: impl Into<String>) -> Result<CorpActions> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
            req_type: &'static str,
            version: &'static str,
        }
        self.get(
            "/v1/quote/company-act",
            Query {
                symbol: symbol.into(),
                req_type: "1",
                version: "3",
            },
        )
        .await
    }

    // ── invest_relation ───────────────────────────────────────────

    /// Get investor relations / investment holdings.
    ///
    /// Path: `GET /v1/quote/invest-relations`
    pub async fn invest_relation(&self, symbol: impl Into<String>) -> Result<InvestRelations> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
            count: &'static str,
        }
        self.get(
            "/v1/quote/invest-relations",
            Query {
                symbol: symbol.into(),
                count: "0",
            },
        )
        .await
    }

    // ── operating ─────────────────────────────────────────────────

    /// Get operating metrics and financial report summaries.
    ///
    /// Path: `GET /v1/quote/operatings`
    pub async fn operating(&self, symbol: impl Into<String>) -> Result<OperatingList> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get_dc(
            "/v1/quote/operatings",
            Query {
                symbol: symbol.into(),
            },
            DcRegion::Ap,
        )
        .await
    }

    // ── buyback ───────────────────────────────────────────────────

    /// Get buyback data for a security.
    ///
    /// Path: `GET /v1/quote/buy-backs`
    pub async fn buyback(&self, symbol: impl Into<String>) -> Result<BuybackData> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/buy-backs",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    // ── ratings ───────────────────────────────────────────────────

    // TODO: temporarily disabled — endpoint not yet open (/v1/quote/ratings)
    // /// Get stock ratings for a security.
    // ///
    // /// Path: `GET /v1/quote/ratings`
    // pub async fn ratings(&self, symbol: impl Into<String>) ->
    // Result<StockRatings> {     #[derive(Serialize)]
    //     struct Query {
    //         symbol: String,
    //     }
    //     self.get(
    //         "/v1/quote/ratings",
    //         Query {
    //             symbol: symbol.into(),
    //         },
    //     )
    //     .await
    // }

    // ── business_segments ────────────────────────────────────────

    /// Get the latest business segment breakdown for a security.
    ///
    /// Path: `GET /v1/quote/fundamentals/business-segments`
    pub async fn business_segments(&self, symbol: impl Into<String>) -> Result<BusinessSegments> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/fundamentals/business-segments",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    /// Get historical business segment breakdowns for a security.
    ///
    /// Path: `GET /v1/quote/fundamentals/business-segments/history`
    pub async fn business_segments_history(
        &self,
        symbol: impl Into<String>,
        report: Option<&'static str>,
        cate: Option<String>,
    ) -> Result<BusinessSegmentsHistory> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
            #[serde(skip_serializing_if = "Option::is_none")]
            report: Option<&'static str>,
            #[serde(skip_serializing_if = "Option::is_none")]
            cate: Option<String>,
        }
        self.get(
            "/v1/quote/fundamentals/business-segments/history",
            Query {
                symbol: symbol.into(),
                report,
                cate,
            },
        )
        .await
    }

    // ── shareholder_top ───────────────────────────────────────────

    /// Get a ranked list of top shareholders for a security.
    ///
    /// Path: `GET /v1/quote/shareholders/top`
    pub async fn shareholder_top(
        &self,
        symbol: impl Into<String>,
    ) -> Result<ShareholderTopResponse> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        let raw: serde_json::Value = self
            .get(
                "/v1/quote/shareholders/top",
                Query {
                    symbol: symbol.into(),
                },
            )
            .await?;
        Ok(ShareholderTopResponse { data: raw })
    }

    // ── institution_rating_views ──────────────────────────────────

    /// Get historical institutional rating view time-series for a security.
    ///
    /// Path: `GET /v1/quote/ratings/institutional`
    pub async fn institution_rating_views(
        &self,
        symbol: impl Into<String>,
    ) -> Result<InstitutionRatingViews> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/ratings/institutional",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    // ── shareholder_detail ────────────────────────────────────────

    /// Get holding history and detail for one shareholder object.
    ///
    /// Path: `GET /v1/quote/shareholders/holding`
    pub async fn shareholder_detail(
        &self,
        symbol: impl Into<String>,
        object_id: i64,
    ) -> Result<ShareholderDetailResponse> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
            object_id: String,
        }
        let raw: serde_json::Value = self
            .get(
                "/v1/quote/shareholders/holding",
                Query {
                    symbol: symbol.into(),
                    object_id: object_id.to_string(),
                },
            )
            .await?;
        Ok(ShareholderDetailResponse { data: raw })
    }

    // ── industry_rank ─────────────────────────────────────────────

    /// Get industry rank for a market.
    ///
    /// `limit` is the number of results to return; the server defaults to 20
    /// when it is `0`.
    ///
    /// Path: `GET /v1/quote/industry/rank`
    pub async fn industry_rank(
        &self,
        market: Market,
        indicator: IndustryRankIndicator,
        sort_type: IndustryRankSortType,
        limit: u32,
    ) -> Result<IndustryRankResponse> {
        #[derive(Serialize)]
        struct Query {
            market: Market,
            indicator: &'static str,
            sort_type: &'static str,
            #[serde(skip_serializing_if = "is_zero")]
            limit: u32,
        }
        fn is_zero(v: &u32) -> bool {
            *v == 0
        }
        self.get(
            "/v1/quote/industry/rank",
            Query {
                market,
                indicator: indicator.as_str(),
                sort_type: sort_type.as_str(),
                limit,
            },
        )
        .await
    }

    // ── industry_peers ────────────────────────────────────────────

    /// Get the industry peer chain for a security or industry.
    ///
    /// Path: `GET /v1/quote/industries/peers`
    pub async fn industry_peers(
        &self,
        symbol: impl Into<String>,
        market: impl Into<String>,
        industry_id: Option<String>,
    ) -> Result<IndustryPeersResponse> {
        let sym = symbol.into();
        #[derive(Serialize)]
        struct Query {
            #[serde(rename = "type")]
            kind: &'static str,
            market: String,
            industry_id: String,
            symbol: String,
        }
        self.get(
            "/v1/quote/industries/peers",
            Query {
                kind: "1",
                market: market.into(),
                industry_id: industry_id.unwrap_or_default(),
                symbol: sym,
            },
        )
        .await
    }

    // ── financial_report_snapshot ─────────────────────────────────

    /// Get a financial report snapshot (earnings snapshot) for a security.
    ///
    /// Path: `GET /v1/quote/financials/earnings-snapshot`
    pub async fn financial_report_snapshot(
        &self,
        symbol: impl Into<String>,
        report: Option<&'static str>,
        fiscal_year: Option<i32>,
        fiscal_period: Option<&'static str>,
    ) -> Result<FinancialReportSnapshot> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
            #[serde(skip_serializing_if = "Option::is_none")]
            report: Option<&'static str>,
            #[serde(skip_serializing_if = "Option::is_none")]
            fiscal_year: Option<i32>,
            #[serde(skip_serializing_if = "Option::is_none")]
            fiscal_period: Option<&'static str>,
        }
        self.get(
            "/v1/quote/financials/earnings-snapshot",
            Query {
                symbol: symbol.into(),
                report,
                fiscal_year,
                fiscal_period,
            },
        )
        .await
    }

    // ── valuation_comparison ──────────────────────────────────────

    /// Get valuation comparison between a security and optional peers.
    ///
    /// Path: `GET /v1/quote/compare/valuation`
    pub async fn valuation_comparison(
        &self,
        symbol: impl Into<String>,
        currency: impl Into<String>,
        comparison_symbols: Option<Vec<String>>,
    ) -> Result<ValuationComparisonResponse> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
            currency: String,
            #[serde(skip_serializing_if = "Option::is_none")]
            comparison_symbols: Option<Vec<String>>,
        }
        let raw: serde_json::Value = self
            .get(
                "/v1/quote/compare/valuation",
                Query {
                    symbol: symbol.into(),
                    currency: currency.into(),
                    comparison_symbols,
                },
            )
            .await?;
        let list = raw["list"]
            .as_array()
            .cloned()
            .unwrap_or_default()
            .into_iter()
            .map(|item| {
                let history = item["history"]
                    .as_array()
                    .cloned()
                    .unwrap_or_default()
                    .into_iter()
                    .map(|h| ValuationHistoryPoint {
                        date: unix_secs_str_to_rfc3339(h["date"].as_str().unwrap_or("")),
                        pe: h["pe"].as_str().unwrap_or("").to_string(),
                        pb: h["pb"].as_str().unwrap_or("").to_string(),
                        ps: h["ps"].as_str().unwrap_or("").to_string(),
                    })
                    .collect();
                ValuationComparisonItem {
                    symbol: item["symbol"].as_str().unwrap_or("").to_string(),
                    name: item["name"].as_str().unwrap_or("").to_string(),
                    currency: item["currency"].as_str().unwrap_or("").to_string(),
                    market_value: item["market_value"].as_str().unwrap_or("").to_string(),
                    price_close: item["price_close"].as_str().unwrap_or("").to_string(),
                    pe: item["pe"].as_str().unwrap_or("").to_string(),
                    pb: item["pb"].as_str().unwrap_or("").to_string(),
                    ps: item["ps"].as_str().unwrap_or("").to_string(),
                    roe: item["roe"].as_str().unwrap_or("").to_string(),
                    eps: item["eps"].as_str().unwrap_or("").to_string(),
                    bps: item["bps"].as_str().unwrap_or("").to_string(),
                    dps: item["dps"].as_str().unwrap_or("").to_string(),
                    div_yld: item["div_yld"].as_str().unwrap_or("").to_string(),
                    assets: item["assets"].as_str().unwrap_or("").to_string(),
                    history,
                }
            })
            .collect();
        Ok(ValuationComparisonResponse { list })
    }

    // ── etf_asset_allocation ─────────────────────────────────────

    /// Get ETF asset allocation (holdings / regional / asset class /
    /// industry).
    ///
    /// Path: `GET /v1/quote/etf-asset-allocation`
    pub async fn etf_asset_allocation(
        &self,
        symbol: impl Into<String>,
    ) -> Result<AssetAllocationResponse> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get(
            "/v1/quote/etf-asset-allocation",
            Query {
                symbol: symbol.into(),
            },
        )
        .await
    }

    // ── macroeconomic ────────────────────────────────────────────────

    /// List macroeconomic indicators.
    ///
    /// `country` accepts a market code string (e.g. `"US"`, `"HK"`, `"ALL"`).
    /// `keyword` optionally filters indicators by name (fuzzy,
    /// case-insensitive). `offset` and `limit` are kept for backward
    /// compatibility but ignored by v2.
    ///
    /// Path: `GET /v2/quote/macrodata`
    pub async fn macroeconomic_indicators(
        &self,
        country: Option<MacroeconomicCountry>,
        keyword: Option<impl Into<String>>,
        offset: Option<i32>,
        limit: Option<i32>,
    ) -> Result<MacroeconomicIndicatorListResponse> {
        self.macroeconomic_indicators_v2(country, keyword, offset, limit)
            .await
    }

    /// List macroeconomic indicators (v2) with optional keyword filter.
    ///
    /// Path: `GET /v2/quote/macrodata`
    pub(crate) async fn macroeconomic_indicators_v2(
        &self,
        country: Option<MacroeconomicCountry>,
        keyword: Option<impl Into<String>>,
        offset: Option<i32>,
        limit: Option<i32>,
    ) -> Result<MacroeconomicIndicatorListResponse> {
        #[derive(Serialize)]
        struct Query {
            market: String,
            #[serde(skip_serializing_if = "Option::is_none")]
            keyword: Option<String>,
            #[serde(skip_serializing_if = "Option::is_none")]
            offset: Option<i32>,
            #[serde(skip_serializing_if = "Option::is_none")]
            limit: Option<i32>,
        }
        let market = country
            .map(|c| match c {
                MacroeconomicCountry::HongKong => "HK",
                MacroeconomicCountry::China => "CN",
                MacroeconomicCountry::UnitedStates => "US",
                MacroeconomicCountry::EuroZone => "EU",
                MacroeconomicCountry::Japan => "JP",
                MacroeconomicCountry::Singapore => "SG",
            })
            .unwrap_or("ALL")
            .to_string();

        let raw: V2MacroIndicatorListResponse = self
            .get(
                "/v2/quote/macrodata",
                Query {
                    market,
                    keyword: keyword.map(|k| k.into()),
                    offset,
                    limit,
                },
            )
            .await?;

        let total = raw.total;
        let data = raw
            .indicator_list
            .into_iter()
            .map(|ind| MacroeconomicIndicator {
                indicator_code: ind.indicator_id.to_string(),
                country: ind.market,
                name: ind.indicator_name,
                periodicity: ind.frequence,
                describe: ind.description,
                importance: ind.importance,
                ..Default::default()
            })
            .collect::<Vec<_>>();
        let count = if total > 0 { total } else { data.len() as i32 };
        Ok(MacroeconomicIndicatorListResponse { data, count })
    }

    /// Get historical data for a macroeconomic indicator.
    ///
    /// `indicator_code` is the indicator ID (integer as string in v2).
    /// `start_date` and `end_date` are `"YYYY-MM-DD"` format.
    /// `sort` can be `"asc"` or `"desc"` (new in v2).
    ///
    /// Path: `GET /v2/quote/macrodata/{indicator_id}`
    pub async fn macroeconomic(
        &self,
        indicator_code: impl Into<String>,
        start_date: Option<impl Into<String>>,
        end_date: Option<impl Into<String>>,
        offset: Option<i32>,
        limit: Option<i32>,
    ) -> Result<MacroeconomicResponse> {
        self.macroeconomic_v2(
            indicator_code,
            start_date,
            end_date,
            offset,
            limit,
            None::<String>,
        )
        .await
    }

    /// Get historical data for a macroeconomic indicator (v2) with sort
    /// support.
    ///
    /// Path: `GET /v2/quote/macrodata/{indicator_id}`
    pub(crate) async fn macroeconomic_v2(
        &self,
        indicator_code: impl Into<String>,
        start_date: Option<impl Into<String>>,
        end_date: Option<impl Into<String>>,
        offset: Option<i32>,
        limit: Option<i32>,
        sort: Option<impl Into<String>>,
    ) -> Result<MacroeconomicResponse> {
        #[derive(Serialize)]
        struct Query {
            #[serde(skip_serializing_if = "Option::is_none")]
            start_date: Option<String>,
            #[serde(skip_serializing_if = "Option::is_none")]
            end_date: Option<String>,
            #[serde(skip_serializing_if = "Option::is_none")]
            offset: Option<i32>,
            #[serde(skip_serializing_if = "Option::is_none")]
            limit: Option<i32>,
            #[serde(skip_serializing_if = "Option::is_none")]
            sort: Option<String>,
        }
        let path = format!("/v2/quote/macrodata/{}", indicator_code.into());
        let raw: V2MacroIndicatorDataResponse = self
            .0
            .http_cli
            .request(Method::GET, path)
            .query_params(Query {
                start_date: start_date.map(|d| d.into()),
                end_date: end_date.map(|d| d.into()),
                offset,
                limit,
                sort: Some(sort.map(|s| s.into()).unwrap_or_else(|| "desc".to_string())),
            })
            .response::<Json<V2MacroIndicatorDataResponse>>()
            .send()
            .with_subscriber(self.0.log_subscriber.clone())
            .await?
            .0;

        let total = raw.total;
        let detail = raw.indicator;
        let unit_english = detail.unit.clone();
        let count = detail.indicator_data.len() as i32;

        let info = MacroeconomicIndicator {
            indicator_code: detail.indicator_id.to_string(),
            country: detail.market,
            name: detail.indicator_name,
            describe: detail.description,
            periodicity: detail.frequence,
            importance: detail.importance,
            ..Default::default()
        };

        let data = detail
            .indicator_data
            .into_iter()
            .map(|d| {
                use time::format_description::well_known::Rfc3339;
                let release_at = time::OffsetDateTime::parse(&d.published_time, &Rfc3339)
                    .ok()
                    .or_else(|| {
                        // Try without timezone suffix
                        time::PrimitiveDateTime::parse(
                            &d.published_time,
                            &time::macros::format_description!(
                                "[year]-[month]-[day]T[hour]:[minute]:[second]"
                            ),
                        )
                        .ok()
                        .map(|dt| dt.assume_utc())
                    });
                Macroeconomic {
                    period: d.observation_date,
                    release_at,
                    actual_value: d.actual_data,
                    previous_value: d.previous_data,
                    forecast_value: d.estimated_data,
                    unit: unit_english.clone(),
                    ..Default::default()
                }
            })
            .collect();

        let count = if total > 0 { total } else { count };
        Ok(MacroeconomicResponse { info, data, count })
    }

    // ── US-market APIs (US token required)
    // ────────────────────────────────────

    /// Get US company overview.
    ///
    /// Path: `GET /v1/us/stock-info/company-overview`
    ///
    /// US token required — returns
    /// [`longbridge_httpcli::HttpClientError::DcRegionRestricted`]
    /// for non-US credentials.
    pub async fn us_company_overview(
        &self,
        symbol: impl Into<String>,
    ) -> Result<USCompanyOverview> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get_dc(
            "/v1/us/stock-info/company-overview",
            Query {
                symbol: symbol.into(),
            },
            DcRegion::Us,
        )
        .await
    }

    /// Get US valuation overview snapshot.
    ///
    /// Path: `GET /v1/us/stock-info/valuation-overview`
    ///
    /// US token required.
    pub async fn us_valuation_overview(
        &self,
        symbol: impl Into<String>,
    ) -> Result<USValuationOverview> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get_dc(
            "/v1/us/stock-info/valuation-overview",
            Query {
                symbol: symbol.into(),
            },
            DcRegion::Us,
        )
        .await
    }

    /// Get US financial overview (revenue, net income, EPS, cash flow).
    ///
    /// `report`: `"annual"` or `"quarterly"`.
    ///
    /// Path: `GET /v1/us/stock-info/finn-overview`
    ///
    /// US token required. Returns raw JSON for maximum flexibility.
    pub async fn us_financial_overview(
        &self,
        symbol: impl Into<String>,
        report: impl Into<String>,
    ) -> Result<USFinancialOverview> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
            report: String,
        }
        self.get_dc(
            "/v1/us/stock-info/finn-overview",
            Query {
                symbol: symbol.into(),
                report: report.into(),
            },
            DcRegion::Us,
        )
        .await
    }

    /// Get US financial statement detail (IS / BS / CF).
    ///
    /// `kind` selects one statement — the endpoint has no "all statements"
    /// mode and answers with an empty list when `kind` is `ALL` or missing.
    /// `report`: `"annual"` or `"quarterly"`.
    ///
    /// Path: `GET /v1/us/quote/financials/statements`
    ///
    /// US token required.
    pub async fn us_financial_statement(
        &self,
        symbol: impl Into<String>,
        kind: FinancialStatementKind,
        report: impl Into<String>,
    ) -> Result<USFinancialStatement> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
            kind: &'static str,
            report: String,
        }
        self.get_dc(
            "/v1/us/quote/financials/statements",
            Query {
                symbol: symbol.into(),
                kind: kind.as_str(),
                report: report.into(),
            },
            DcRegion::Us,
        )
        .await
    }

    /// Get key financial metrics (ROE, margins, leverage ratios).
    ///
    /// `report`: `"annual"` or `"quarterly"`.
    ///
    /// Path: `GET /v1/us/stock-info/fin-keyfactor`
    ///
    /// US token required. Returns raw JSON.
    pub async fn us_key_financial_metrics(
        &self,
        symbol: impl Into<String>,
        report: impl Into<String>,
    ) -> Result<USKeyFinancialMetrics> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
            report: String,
        }
        self.get_dc(
            "/v1/us/stock-info/fin-keyfactor",
            Query {
                symbol: symbol.into(),
                report: report.into(),
            },
            DcRegion::Us,
        )
        .await
    }

    /// Get analyst consensus estimates (EPS and revenue forecasts).
    ///
    /// `report`: `"annual"` or `"quarterly"`.
    ///
    /// Path: `GET /v1/us/stock-info/fin-consensus`
    ///
    /// US token required. Returns raw JSON.
    pub async fn us_analyst_consensus(
        &self,
        symbol: impl Into<String>,
        report: impl Into<String>,
    ) -> Result<USAnalystConsensus> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
            report: String,
        }
        self.get_dc(
            "/v1/us/stock-info/fin-consensus",
            Query {
                symbol: symbol.into(),
                report: report.into(),
            },
            DcRegion::Us,
        )
        .await
    }

    /// Get ETF dividend history.
    ///
    /// Path: `GET /v1/us/stock-info/etf-dividend-info`
    ///
    /// US token required.
    pub async fn us_etf_dividend_info(
        &self,
        symbol: impl Into<String>,
    ) -> Result<USETFDividendInfo> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get_dc(
            "/v1/us/stock-info/etf-dividend-info",
            Query {
                symbol: symbol.into(),
            },
            DcRegion::Us,
        )
        .await
    }

    /// Get company historical dividend payments.
    ///
    /// Path: `GET /v1/us/stock-info/company-dividends`
    ///
    /// US token required.
    pub async fn us_company_dividends(
        &self,
        symbol: impl Into<String>,
    ) -> Result<USCompanyDividends> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
        }
        self.get_dc(
            "/v1/us/stock-info/company-dividends",
            Query {
                symbol: symbol.into(),
            },
            DcRegion::Us,
        )
        .await
    }

    /// Get ETF document list (prospectus, annual reports, etc.).
    ///
    /// `size`: number of files to return; `None` returns all (server default 0
    /// = all).
    ///
    /// Path: `GET /v1/us/stock-info/etf-files`
    ///
    /// US token required.
    pub async fn us_etf_files(
        &self,
        symbol: impl Into<String>,
        size: Option<u32>,
    ) -> Result<USETFFilesResponse> {
        #[derive(Serialize)]
        struct Query {
            symbol: String,
            #[serde(skip_serializing_if = "Option::is_none")]
            size: Option<u32>,
        }
        self.get_dc(
            "/v1/us/stock-info/etf-files",
            Query {
                symbol: symbol.into(),
                size,
            },
            DcRegion::Us,
        )
        .await
    }
}