futu_mcp/tool_args/qot/

f10.rs

//! MCP QOT F10, financials, research, and valuation request schemas.

use rmcp::schemars;
use serde::Deserialize;

fn validate_optional_i32_range(
    tool: &str,
    field: &str,
    value: Option<i32>,
    min: i32,
    max: i32,
) -> Result<(), String> {
    if let Some(value) = value
        && !(min..=max).contains(&value)
    {
        return Err(format!(
            "{field} must be in {min}..={max} for {tool}, got {value}"
        ));
    }
    Ok(())
}

fn validate_optional_i32_where(
    tool: &str,
    field: &str,
    value: Option<i32>,
    expected: &str,
    is_valid: impl Fn(i32) -> bool,
) -> Result<(), String> {
    if let Some(value) = value
        && !is_valid(value)
    {
        return Err(format!(
            "{field} must be {expected} for {tool}, got {value}"
        ));
    }
    Ok(())
}

fn is_financial_statements_f10_type(value: i32) -> bool {
    // C++ Qot_GetFinancialsStatements accepts Qot_Common.F10Type
    // 0..7 and 9..11. Ref:
    // FutuOpenD/Src/APIServer/Business/Quote/APIServer_Qot_FinancialsStatements.cpp:107-117
    (0..=7).contains(&value) || (9..=11).contains(&value)
}

fn is_revenue_breakdown_f10_type(value: i32) -> bool {
    // C++ Qot_GetFinancialsRevenueBreakdown accepts Qot_Common.F10Type
    // 0..7 and 9. Ref:
    // FutuOpenD/Src/APIServer/Business/Quote/APIServer_Qot_FinancialsRevenueBreakdown.cpp:50-59
    (0..=7).contains(&value) || value == 9
}

fn is_valuation_type_with_unknown(value: i32) -> bool {
    // Qot_Common.ValuationType: Unknown(0), PE(1), PB(2), PS(3).
    (0..=3).contains(&value)
}

fn is_valuation_plate_sort_id(value: i32) -> bool {
    // C++ maps public SortField Unknown/MarketCap/Valuation/
    // ForwardValuation/HistoricalPercentile and rejects everything else.
    // Ref: FutuOpenD/Src/APIServer/Business/Quote/APIServer_Qot_ValuationPlateStockList.cpp:82-96
    matches!(value, 0 | 51 | 52 | 53 | 54)
}

#[derive(Debug, Deserialize, schemars::JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct CompanyExecutiveBackgroundReq {
    #[schemars(
        description = "Security symbol in MARKET.CODE format, e.g. HK.00700, US.AAPL \
                       (alias: code / stock / security for SDK compat)"
    )]
    #[serde(alias = "code", alias = "stock", alias = "security")]
    pub symbol: String,
    #[schemars(description = "Executive/director leader name from get_company_executives")]
    #[serde(alias = "leaderName")]
    pub leader_name: String,
}

#[derive(Debug, Deserialize, schemars::JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct CompanyOperationalEfficiencyReq {
    #[schemars(
        description = "Security symbol in MARKET.CODE format, e.g. HK.00700, US.AAPL \
                       (alias: code / stock / security for SDK compat)"
    )]
    #[serde(alias = "code", alias = "stock", alias = "security")]
    pub symbol: String,
    #[schemars(description = "Pagination key from previous response; alias: nextKey")]
    #[serde(default, alias = "nextKey")]
    pub next_key: Option<String>,
    #[schemars(description = "Rows per page, 1-50. Omit to use backend default 10.")]
    #[serde(default)]
    pub num: Option<i32>,
    #[schemars(description = "Currency code, e.g. CNY / USD / HKD; alias: currencyCode")]
    #[serde(default, alias = "currencyCode")]
    pub currency_code: Option<String>,
    #[schemars(
        description = "Compatibility-only field; the backend ignores financialType for company operational efficiency and always queries the fixed annual view. Alias: financialType"
    )]
    #[serde(default, alias = "financialType")]
    pub financial_type: Option<i32>,
}

impl CompanyOperationalEfficiencyReq {
    pub fn validate(&self) -> Result<(), String> {
        validate_optional_i32_range(
            "futu_get_company_operational_efficiency",
            "num",
            self.num,
            1,
            50,
        )
    }
}

#[derive(Debug, Deserialize, schemars::JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct FinancialsEarningsPriceMoveReq {
    #[schemars(
        description = "Security symbol in MARKET.CODE format, e.g. HK.00700, US.AAPL \
                       (alias: code / stock / security for SDK compat)"
    )]
    #[serde(alias = "code", alias = "stock", alias = "security")]
    pub symbol: String,
    #[schemars(description = "Financial period count, 1-50. Omit to use backend default 10.")]
    #[serde(default, alias = "periodCount")]
    pub period_count: Option<i32>,
}

impl FinancialsEarningsPriceMoveReq {
    pub fn validate(&self) -> Result<(), String> {
        validate_optional_i32_range(
            "futu_get_financials_earnings_price_move",
            "period_count",
            self.period_count,
            1,
            50,
        )
    }
}

#[derive(Debug, Deserialize, schemars::JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct FinancialsEarningsPriceHistoryReq {
    #[schemars(
        description = "Security symbol in MARKET.CODE format, e.g. HK.00700, US.AAPL \
                       (alias: code / stock / security for SDK compat)"
    )]
    #[serde(alias = "code", alias = "stock", alias = "security")]
    pub symbol: String,
}

#[derive(Debug, Deserialize, schemars::JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct FinancialsStatementsReq {
    #[schemars(
        description = "Security symbol in MARKET.CODE format, e.g. HK.00700, US.AAPL \
                       (alias: code / stock / security for SDK compat)"
    )]
    #[serde(alias = "code", alias = "stock", alias = "security")]
    pub symbol: String,
    #[schemars(
        description = "FinancialStatementsType: 0=unknown, 1=income, 2=balance_sheet, 3=cash_flow, 4=main_index; omit to use backend default 1. Alias: statementType"
    )]
    #[serde(default, alias = "statementType")]
    pub statement_type: Option<i32>,
    #[schemars(
        description = "F10Type financial period filter, supports 0-7 and 9-11; omit to use backend default 10. Alias: financialType"
    )]
    #[serde(default, alias = "financialType")]
    pub financial_type: Option<i32>,
    #[schemars(description = "Currency code, e.g. CNY / USD / HKD; alias: currencyCode")]
    #[serde(default, alias = "currencyCode")]
    pub currency_code: Option<String>,
    #[schemars(description = "Pagination key from previous response; alias: nextKey")]
    #[serde(default, alias = "nextKey")]
    pub next_key: Option<String>,
    #[schemars(description = "Rows per page, 1-50. Omit to use backend default 10.")]
    #[serde(default)]
    pub num: Option<i32>,
}

impl FinancialsStatementsReq {
    pub fn validate(&self) -> Result<(), String> {
        validate_optional_i32_range("futu_get_financials_statements", "num", self.num, 1, 50)?;
        validate_optional_i32_range(
            "futu_get_financials_statements",
            "statement_type",
            self.statement_type,
            0,
            4,
        )?;
        validate_optional_i32_where(
            "futu_get_financials_statements",
            "financial_type",
            self.financial_type,
            "0..=7 or 9..=11",
            is_financial_statements_f10_type,
        )
    }
}

#[derive(Debug, Deserialize, schemars::JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct FinancialsRevenueBreakdownReq {
    #[schemars(
        description = "Security symbol in MARKET.CODE format, e.g. HK.00700, US.AAPL \
                       (alias: code / stock / security for SDK compat)"
    )]
    #[serde(alias = "code", alias = "stock", alias = "security")]
    pub symbol: String,
    #[schemars(description = "Screen date timestamp from screenDateList; alias: screenDate")]
    #[serde(default, alias = "screenDate")]
    pub date: Option<u32>,
    #[schemars(
        description = "F10Type financial period filter, supports 0-7 and 9; omit to use backend default 0. Alias: financialType"
    )]
    #[serde(default, alias = "financialType")]
    pub financial_type: Option<i32>,
    #[schemars(description = "Currency code, e.g. CNY / USD / HKD; alias: currencyCode")]
    #[serde(default, alias = "currencyCode")]
    pub currency_code: Option<String>,
}

impl FinancialsRevenueBreakdownReq {
    pub fn validate(&self) -> Result<(), String> {
        validate_optional_i32_where(
            "futu_get_financials_revenue_breakdown",
            "financial_type",
            self.financial_type,
            "0..=7 or 9",
            is_revenue_breakdown_f10_type,
        )
    }
}

#[derive(Debug, Deserialize, schemars::JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ResearchAnalystConsensusReq {
    #[schemars(
        description = "Security symbol in MARKET.CODE format, e.g. HK.00700, US.AAPL \
                       (alias: code / stock / security for SDK compat)"
    )]
    #[serde(alias = "code", alias = "stock", alias = "security")]
    pub symbol: String,
}

#[derive(Debug, Deserialize, schemars::JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ResearchRatingSummaryReq {
    #[schemars(
        description = "Security symbol in MARKET.CODE format, e.g. US.AAPL, CA.SHOP \
                       (alias: code / stock / security for SDK compat)"
    )]
    #[serde(alias = "code", alias = "stock", alias = "security")]
    pub symbol: String,
    #[schemars(description = "ResearchRatingDimensionType: 0/1=institution, 2=analyst")]
    #[serde(default, alias = "ratingDimensionType")]
    pub rating_dimension_type: Option<i32>,
    #[schemars(description = "Institution or analyst uid; empty means summary list")]
    #[serde(default)]
    pub uid: Option<String>,
    #[schemars(description = "Pagination key; alias: nextKey")]
    #[serde(default, alias = "nextKey")]
    pub next_key: Option<String>,
    #[schemars(description = "Page size, 1..20; omitted uses backend default 10")]
    #[serde(default)]
    pub num: Option<i32>,
}

impl ResearchRatingSummaryReq {
    pub fn validate(&self) -> Result<(), String> {
        validate_optional_i32_range("futu_get_research_rating_summary", "num", self.num, 1, 20)?;
        validate_optional_i32_range(
            "futu_get_research_rating_summary",
            "rating_dimension_type",
            self.rating_dimension_type,
            0,
            2,
        )
    }
}

#[derive(Debug, Deserialize, schemars::JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ResearchMorningstarReportReq {
    #[schemars(description = "Security symbol in MARKET.CODE format, e.g. US.AAPL \
                       (alias: code / stock / security for SDK compat)")]
    #[serde(alias = "code", alias = "stock", alias = "security")]
    pub symbol: String,
}

#[derive(Debug, Deserialize, schemars::JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ValuationDetailReq {
    #[schemars(
        description = "Security symbol in MARKET.CODE format, e.g. HK.00700, US.AAPL, HK.800000 \
                       (alias: code / stock / security for SDK compat)"
    )]
    #[serde(alias = "code", alias = "stock", alias = "security")]
    pub symbol: String,
    #[schemars(
        description = "ValuationType: 0=recommended, 1=PE, 2=PB, 3=PS; alias: valuationType"
    )]
    #[serde(default, alias = "valuationType")]
    pub valuation_type: Option<i32>,
    #[schemars(
        description = "ValuationIntervalType: 0/3=1y default, 1=3m, 2=6m, 4=3y, 5=since2019, 6=5y, 7=10y, 8=2y, 9=20y, 10=30y; omit uses backend default 3. Alias: intervalType"
    )]
    #[serde(default, alias = "intervalType")]
    pub interval_type: Option<i32>,
}

impl ValuationDetailReq {
    pub fn validate(&self) -> Result<(), String> {
        validate_optional_i32_where(
            "futu_get_valuation_detail",
            "valuation_type",
            self.valuation_type,
            "0..=3",
            is_valuation_type_with_unknown,
        )?;
        validate_optional_i32_range(
            "futu_get_valuation_detail",
            "interval_type",
            self.interval_type,
            0,
            10,
        )
    }
}

#[derive(Debug, Deserialize, schemars::JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ValuationPlateStockListReq {
    #[schemars(
        description = "Plate or index symbol in MARKET.CODE format, e.g. HK.BK0001, HK.800000 \
                       (alias: code / stock / security for SDK compat)"
    )]
    #[serde(alias = "code", alias = "stock", alias = "security")]
    pub symbol: String,
    #[schemars(description = "ValuationType: 0/1=PE, 2=PB, 3=PS; alias: valuationType")]
    #[serde(default, alias = "valuationType")]
    pub valuation_type: Option<i32>,
    #[schemars(description = "Pagination key; alias: nextKey")]
    #[serde(default, alias = "nextKey")]
    pub next_key: Option<String>,
    #[schemars(description = "Page size, 1..50; omitted uses backend default 10")]
    #[serde(default)]
    pub num: Option<i32>,
    #[schemars(
        description = "SortType: 0/2=asc, 1=desc; omit to use backend default asc. Alias: sortType"
    )]
    #[serde(default, alias = "sortType")]
    pub sort_type: Option<i32>,
    #[schemars(
        description = "SortField: 51=market_cap, 52=valuation, 53=forward, 54=percentile; alias: sortId"
    )]
    #[serde(default, alias = "sortId")]
    pub sort_id: Option<i32>,
    #[schemars(
        description = "Optional plate filter for index components, MARKET.CODE; alias: filterSecurity"
    )]
    #[serde(default, alias = "filterSecurity")]
    pub filter_security: Option<String>,
}

impl ValuationPlateStockListReq {
    pub fn validate(&self) -> Result<(), String> {
        validate_optional_i32_range(
            "futu_get_valuation_plate_stock_list",
            "num",
            self.num,
            1,
            50,
        )?;
        validate_optional_i32_where(
            "futu_get_valuation_plate_stock_list",
            "valuation_type",
            self.valuation_type,
            "0..=3",
            is_valuation_type_with_unknown,
        )?;
        validate_optional_i32_where(
            "futu_get_valuation_plate_stock_list",
            "sort_id",
            self.sort_id,
            "0, 51, 52, 53, or 54",
            is_valuation_plate_sort_id,
        )
    }
}