futucli/cmd/analysis/company/financials/

calendar.rs

use anyhow::{Result, anyhow, bail};
use prost::Message;
use tabled::Tabled;

use crate::common::connect_gateway;
use crate::output::OutputFormat;

use super::super::{display_opt, display_opt_i32, display_opt_i64};

pub struct FinancialCalendarCommand<'a> {
    pub begin_date: &'a str,
    pub end_date: &'a str,
    pub markets: &'a [String],
    pub pub_types: &'a [String],
    pub stock_types: &'a [String],
    pub count: Option<i32>,
    pub ranking_type: Option<i32>,
    pub estimate_types: &'a [String],
    pub custom_filters: &'a [String],
    pub watchlist_only: bool,
    pub positions_only: bool,
    pub watchlist_stock_ids: &'a [u64],
    pub holding_stock_ids: &'a [u64],
}

pub struct FinancialCalendarTargetCommand<'a> {
    pub stock_ids: &'a [u64],
    pub markets: &'a [String],
    pub size: i32,
    pub start: Option<i32>,
}

fn validate_yyyymmdd(field: &str, value: &str) -> Result<()> {
    if value.len() != 8 || !value.bytes().all(|b| b.is_ascii_digit()) {
        bail!("{field} must be YYYYMMDD, got {value:?}");
    }
    Ok(())
}

fn normalize_enum_token(value: &str) -> String {
    value.trim().replace(['-', ' '], "_").to_ascii_uppercase()
}

fn parse_named_i32(value: &str, field: &str, mapping: &[(&str, i32)]) -> Result<i32> {
    let trimmed = value.trim();
    if let Ok(parsed) = trimmed.parse::<i32>() {
        return Ok(parsed);
    }
    let normalized = normalize_enum_token(trimmed);
    mapping
        .iter()
        .find_map(|(name, code)| (*name == normalized).then_some(*code))
        .ok_or_else(|| {
            anyhow!(
                "unknown {field} {value:?}; expected integer or one of {}",
                mapping
                    .iter()
                    .map(|(name, _)| *name)
                    .collect::<Vec<_>>()
                    .join("|")
            )
        })
}

fn parse_named_i32_list(
    values: &[String],
    field: &str,
    mapping: &[(&str, i32)],
) -> Result<Vec<i32>> {
    values
        .iter()
        .map(|value| parse_named_i32(value, field, mapping))
        .collect()
}

fn parse_financial_calendar_market_list(values: &[String]) -> Result<Vec<i32>> {
    // Values come from mobile/moomoo financial_calendar.Market.
    parse_named_i32_list(
        values,
        "market",
        &[
            ("HK", 1),
            ("US", 2),
            ("CN", 3),
            ("AU", 4),
            ("SG", 5),
            ("CA", 6),
            ("JP", 7),
            ("MY", 8),
        ],
    )
}

fn parse_financial_calendar_pub_type_list(values: &[String]) -> Result<Vec<i32>> {
    // Values come from mobile/moomoo financial_calendar.PubType.
    parse_named_i32_list(
        values,
        "pub_type",
        &[
            ("REGULAR", 0),
            ("TODAY", 0),
            ("SAME_DAY", 0),
            ("BEFORE", 1),
            ("PRE", 1),
            ("PRE_MARKET", 1),
            ("AFTER", 2),
            ("POST", 2),
            ("AFTER_HOURS", 2),
        ],
    )
}

fn parse_financial_calendar_stock_type_list(values: &[String]) -> Result<Vec<i32>> {
    // Values come from mobile/moomoo financial_calendar.StockType.
    parse_named_i32_list(
        values,
        "stock_type",
        &[
            ("WATCHLIST", 1),
            ("WATCH", 1),
            ("FAVORITE", 1),
            ("POSITION", 2),
            ("POS", 2),
            ("HOLDING", 2),
            ("SPECIAL", 3),
            ("SPECIAL_WATCH", 3),
        ],
    )
}

fn parse_financial_calendar_estimate_type_list(values: &[String]) -> Result<Vec<i32>> {
    if values.is_empty() {
        return Ok(vec![1, 2, 3]);
    }
    // Values come from mobile/moomoo financial_calendar.EstimateType.
    parse_named_i32_list(
        values,
        "estimate_type",
        &[("EPS_GAAP", 1), ("EPS", 1), ("REVENUE", 2), ("EBIT", 3)],
    )
}

fn is_financial_calendar_ranking_type(value: i32) -> bool {
    (1..=7).contains(&value) || value == 100
}

fn validate_financial_calendar_ranking_type(value: Option<i32>) -> Result<()> {
    if let Some(value) = value
        && !is_financial_calendar_ranking_type(value)
    {
        bail!("ranking_type must be 1..=7 or 100, got {value}");
    }
    Ok(())
}

fn parse_financial_calendar_custom_filter_type(value: &str) -> Result<i32> {
    let filter_type = parse_named_i32(
        value,
        "custom_filter",
        &[
            ("MARKET_CAP", 1),
            ("OPTION_VOLUME", 2),
            ("IV", 3),
            ("IV_RANK", 4),
            ("IV_PCTL", 5),
            ("IV_PERCENTILE", 5),
            ("RT_MARKET_CAP", 6),
        ],
    )?;
    if !(1..=6).contains(&filter_type) {
        bail!("custom_filter type must be 1..=6, got {filter_type}");
    }
    Ok(filter_type)
}

fn parse_optional_i64_bound(raw: &str, field: &str) -> Result<Option<i64>> {
    if raw.trim().is_empty() {
        return Ok(None);
    }
    raw.trim()
        .parse::<i64>()
        .map(Some)
        .map_err(|err| anyhow!("{field} must be an integer, got {raw:?}: {err}"))
}

fn parse_financial_calendar_custom_filter(
    value: &str,
) -> Result<futu_backend::proto_internal::financial_calendar::CustomFilter> {
    let parts: Vec<&str> = value.split(':').collect();
    if parts.is_empty() || parts.len() > 3 || parts[0].trim().is_empty() {
        bail!("custom_filter must be TYPE[:MIN[:MAX]], got {value:?}");
    }
    let customer_filter_type = parse_financial_calendar_custom_filter_type(parts[0])?;
    let customer_filter_value_start_at = parts
        .get(1)
        .map(|raw| parse_optional_i64_bound(raw, "custom_filter min"))
        .transpose()?
        .flatten();
    let customer_filter_value_end_at = parts
        .get(2)
        .map(|raw| parse_optional_i64_bound(raw, "custom_filter max"))
        .transpose()?
        .flatten();
    if let (Some(start), Some(end)) = (customer_filter_value_start_at, customer_filter_value_end_at)
        && start > end
    {
        bail!("custom_filter min must be <= max, got {start}>{end}");
    }
    Ok(
        futu_backend::proto_internal::financial_calendar::CustomFilter {
            customer_filter_type: Some(customer_filter_type),
            customer_filter_value_start_at,
            customer_filter_value_end_at,
        },
    )
}

fn parse_financial_calendar_custom_filter_list(
    values: &[String],
) -> Result<Vec<futu_backend::proto_internal::financial_calendar::CustomFilter>> {
    values
        .iter()
        .map(|value| parse_financial_calendar_custom_filter(value))
        .collect()
}

fn financial_calendar_new_pc_field_selector()
-> futu_backend::proto_internal::financial_calendar::NewPcFieldSelector {
    futu_backend::proto_internal::financial_calendar::NewPcFieldSelector {
        with_pub_type: Some(true),
        with_pub_time: Some(true),
        with_financial_period: Some(true),
        with_option_volume: Some(true),
        with_iv: Some(true),
        with_iv_rank: Some(true),
        with_iv_pctl: Some(true),
        with_rt_market_cap: Some(true),
        with_rt_price: Some(true),
        with_rt_pe_ttm: Some(true),
        with_rt_price_last_close: Some(true),
    }
}

#[derive(Tabled)]
struct FinancialCalendarRow {
    #[tabled(rename = "Date")]
    date: String,
    #[tabled(rename = "Total")]
    total: String,
    #[tabled(rename = "Stock ID")]
    stock_id: String,
    #[tabled(rename = "Pub Type")]
    pub_type: String,
    #[tabled(rename = "Published")]
    is_published: String,
    #[tabled(rename = "Quarter")]
    earnings_quarter: String,
    #[tabled(rename = "Pub Time")]
    pub_time: String,
    #[tabled(rename = "Estimate Items")]
    estimate_items: String,
}

#[derive(Tabled)]
struct TargetFinancialCalendarRow {
    #[tabled(rename = "Pub Date")]
    pub_date: String,
    #[tabled(rename = "Stock ID")]
    stock_id: String,
    #[tabled(rename = "Pub Type")]
    pub_type: String,
    #[tabled(rename = "Quarter")]
    earnings_quarter: String,
    #[tabled(rename = "Pub Time")]
    pub_time: String,
    #[tabled(rename = "Predict")]
    is_predict: String,
}

pub async fn run_financial_calendar(
    gateway: &str,
    command: FinancialCalendarCommand<'_>,
    format: OutputFormat,
) -> Result<()> {
    validate_yyyymmdd("begin_date", command.begin_date)?;
    validate_yyyymmdd("end_date", command.end_date)?;
    if command.begin_date >= command.end_date {
        bail!("begin_date must be earlier than end_date");
    }
    if let Some(count) = command.count
        && !(1..=1000).contains(&count)
    {
        bail!("count must be in 1..=1000, got {count}");
    }
    validate_financial_calendar_ranking_type(command.ranking_type)?;

    let market_list = parse_financial_calendar_market_list(command.markets)?;
    let pub_type_list = parse_financial_calendar_pub_type_list(command.pub_types)?;
    let mut stock_type_tokens = command.stock_types.to_vec();
    if command.watchlist_only {
        stock_type_tokens.push("watchlist".to_string());
    }
    if command.positions_only {
        stock_type_tokens.push("position".to_string());
    }
    let stock_type_list = parse_financial_calendar_stock_type_list(&stock_type_tokens)?;
    let estimate_type_list = parse_financial_calendar_estimate_type_list(command.estimate_types)?;
    let custom_filter_list = parse_financial_calendar_custom_filter_list(command.custom_filters)?;

    let (client, _rx) = connect_gateway(gateway, "futucli-financial-calendar").await?;
    let req =
        futu_backend::proto_internal::financial_calendar::GetFinancialStatementCalendarViewReq {
            market_list,
            pub_type_list,
            stock_type_list,
            count: command.count,
            begin_date: Some(command.begin_date.to_string()),
            end_date: Some(command.end_date.to_string()),
            ranking_type: command.ranking_type,
            estimate_type_list,
            custom_filter_list,
            watchlist_stock_ids: command.watchlist_stock_ids.to_vec(),
            holding_stock_ids: command.holding_stock_ids.to_vec(),
            field_selector: None,
            new_pc_field_selector: Some(financial_calendar_new_pc_field_selector()),
        };
    let body = req.encode_to_vec();
    let frame = client
        .request(
            futu_core::proto_id::QOT_GET_FINANCIAL_CALENDAR_VIEW_INTERNAL,
            body,
        )
        .await?;
    let resp =
        futu_backend::proto_internal::financial_calendar::GetFinancialStatementCalendarViewRsp::decode(
            frame.body.as_ref(),
        )
        .map_err(|e| anyhow!("decode financial_calendar: {e}"))?;
    if resp.ret_code.unwrap_or(0) != 0 {
        bail!(
            "financial_calendar ret_code={:?} message={:?}",
            resp.ret_code,
            resp.message
        );
    }

    let rows: Vec<FinancialCalendarRow> = resp
        .financial_statement_group_list
        .iter()
        .flat_map(|group| {
            group
                .financial_statement_list
                .iter()
                .map(move |statement| FinancialCalendarRow {
                    date: display_opt(&group.that_date),
                    total: display_opt_i64(group.total),
                    stock_id: statement
                        .stock_id
                        .map(|v| v.to_string())
                        .unwrap_or_default(),
                    pub_type: display_opt_i32(statement.pub_type),
                    is_published: display_opt_i32(statement.is_published),
                    earnings_quarter: display_opt(&statement.earnings_quarter),
                    pub_time: display_opt_i64(statement.pub_time),
                    estimate_items: statement.estimate_item.len().to_string(),
                })
        })
        .collect();
    let json = serde_json::json!({
        "begin_date": command.begin_date,
        "end_date": command.end_date,
        "ret_code": resp.ret_code,
        "message": resp.message,
        "financial_statement_group_list": resp.financial_statement_group_list,
    });
    format.print_rows(&rows, &[json])?;
    Ok(())
}

pub async fn run_financial_calendar_target(
    gateway: &str,
    command: FinancialCalendarTargetCommand<'_>,
    format: OutputFormat,
) -> Result<()> {
    if command.stock_ids.is_empty() || command.stock_ids.contains(&0) {
        bail!("stock_id list must be non-empty and positive");
    }
    if command.size <= 0 {
        bail!("size must be positive, got {}", command.size);
    }
    if let Some(start) = command.start
        && start < 0
    {
        bail!("start must be non-negative, got {start}");
    }

    let market_list = parse_financial_calendar_market_list(command.markets)?;
    let (client, _rx) = connect_gateway(gateway, "futucli-financial-calendar-target").await?;
    let req =
        futu_backend::proto_internal::financial_calendar::SearchTargetStockFinancialCalendarReq {
            stock_id: command.stock_ids.to_vec(),
            market_list,
            size: Some(command.size),
            start: command.start,
        };
    let body = req.encode_to_vec();
    let frame = client
        .request(
            futu_core::proto_id::QOT_SEARCH_TARGET_FINANCIAL_CALENDAR,
            body,
        )
        .await?;
    let resp =
        futu_backend::proto_internal::financial_calendar::SearchTargetStockFinancialCalendarRsp::decode(
            frame.body.as_ref(),
        )
        .map_err(|e| anyhow!("decode target_financial_calendar: {e}"))?;
    if resp.code.unwrap_or(0) != 0 {
        bail!(
            "target_financial_calendar code={:?} message={:?}",
            resp.code,
            resp.message
        );
    }

    let rows: Vec<TargetFinancialCalendarRow> = resp
        .target_stock_financial_calendar_list
        .iter()
        .map(|item| {
            let statement = item.financial_statement_list.as_ref();
            TargetFinancialCalendarRow {
                pub_date: display_opt(&item.pub_date),
                stock_id: statement
                    .and_then(|s| s.stock_id)
                    .map(|value| value.to_string())
                    .unwrap_or_default(),
                pub_type: statement
                    .and_then(|s| s.pub_type)
                    .map(|value| value.to_string())
                    .unwrap_or_default(),
                earnings_quarter: statement
                    .and_then(|s| s.earnings_quarter.clone())
                    .unwrap_or_default(),
                pub_time: statement
                    .and_then(|s| s.pub_time)
                    .map(|value| value.to_string())
                    .unwrap_or_default(),
                is_predict: statement
                    .and_then(|s| s.is_predict)
                    .map(|value| value.to_string())
                    .unwrap_or_default(),
            }
        })
        .collect();
    let json = serde_json::json!({
        "code": resp.code,
        "message": resp.message,
        "has_more": resp.has_more,
        "target_stock_financial_calendar_list": resp.target_stock_financial_calendar_list,
    });
    format.print_rows(&rows, &[json])?;
    Ok(())
}

#[cfg(test)]
#[path = "calendar_tests.rs"]
mod calendar_tests;