futu_core/

qot_subscription.rs

use std::num::NonZeroU32;

use crate::qot_stock_key::QotSecurityKey;

pub const SECURITY_TYPE_DRVT: i32 = 8;
pub const SECURITY_TYPE_FUTURE: i32 = 10;

pub const BACKEND_MARKET_HK_OPTION: i32 = 9;
pub const BACKEND_MARKET_US_OPTION: i32 = 15;

pub const US_LV2_ORDER_ARCA: u32 = 1;
pub const US_LV2_ORDER_NASDAQ_TV: u32 = 4;
pub const US_LV2_ORDER_OVERNIGHT: u32 = 128;
pub const LV2_ORDER_US_FUTURE: u32 = 1;
pub const SG_LV2_ORDER_STOCK: u32 = 1;
pub const SG_LV2_ORDER_STOCK_ODD_LOT: u32 = 2;
pub const JP_LV2_ORDER_STOCK: u32 = 1;
pub const JP_LV2_ORDER_STOCK_FULL: u32 = 2;

pub const SUB_TYPE_NONE: i32 = 0;
pub const SUB_TYPE_BASIC: i32 = 1;
pub const SUB_TYPE_ORDER_BOOK: i32 = 2;
pub const SUB_TYPE_TICKER: i32 = 4;
pub const SUB_TYPE_RT: i32 = 5;
pub const SUB_TYPE_KL_DAY: i32 = 6;
pub const SUB_TYPE_KL_5MIN: i32 = 7;
pub const SUB_TYPE_KL_15MIN: i32 = 8;
pub const SUB_TYPE_KL_30MIN: i32 = 9;
pub const SUB_TYPE_KL_60MIN: i32 = 10;
pub const SUB_TYPE_KL_1MIN: i32 = 11;
pub const SUB_TYPE_KL_WEEK: i32 = 12;
pub const SUB_TYPE_KL_MONTH: i32 = 13;
pub const SUB_TYPE_BROKER: i32 = 14;
pub const SUB_TYPE_KL_QUARTER: i32 = 15;
pub const SUB_TYPE_KL_YEAR: i32 = 16;
pub const SUB_TYPE_KL_3MIN: i32 = 17;
pub const SUB_TYPE_KL_10MIN: i32 = 18;
pub const SUB_TYPE_KL_120MIN: i32 = 19;
pub const SUB_TYPE_KL_180MIN: i32 = 20;
pub const SUB_TYPE_KL_240MIN: i32 = 21;
pub const SUB_TYPE_ORDER_BOOK_ODD: i32 = 22;

pub const VALID_QOT_SUB_TYPES: &[i32] = &[
    SUB_TYPE_BASIC,
    SUB_TYPE_ORDER_BOOK,
    SUB_TYPE_TICKER,
    SUB_TYPE_RT,
    SUB_TYPE_KL_DAY,
    SUB_TYPE_KL_5MIN,
    SUB_TYPE_KL_15MIN,
    SUB_TYPE_KL_30MIN,
    SUB_TYPE_KL_60MIN,
    SUB_TYPE_KL_1MIN,
    SUB_TYPE_KL_WEEK,
    SUB_TYPE_KL_MONTH,
    SUB_TYPE_BROKER,
    SUB_TYPE_KL_QUARTER,
    SUB_TYPE_KL_YEAR,
    SUB_TYPE_KL_3MIN,
    SUB_TYPE_KL_10MIN,
    SUB_TYPE_KL_120MIN,
    SUB_TYPE_KL_180MIN,
    SUB_TYPE_KL_240MIN,
    SUB_TYPE_ORDER_BOOK_ODD,
];

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum EventContractWireRight {
    Unknown,
    Level1,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Lv2OrderGroupPlan {
    pub lv2_type: u32,
    pub level: u32,
    pub prob2_v2: bool,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum OrderBookWireProfile {
    Generic,
    Hk { sf: bool },
    UsStock { lv2_groups: Vec<Lv2OrderGroupPlan> },
    UsFuture { level2: bool },
    JpStock { depth: Option<u32> },
    SgStock { level2: bool },
    MyStock,
    Crypto { dynamic_prob: Option<u32> },
    EventContract { right: EventContractWireRight },
}

#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub enum SubscriptionWireProfile {
    #[default]
    NonOrderBook,
    OrderBook(OrderBookWireProfile),
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct BitInfoPlan {
    pub bit: u32,
    pub prob: Option<i64>,
    pub payload: BitInfoPayloadPlan,
}

impl BitInfoPlan {
    #[must_use]
    pub const fn scalar(bit: u32, prob: Option<i64>) -> Self {
        Self {
            bit,
            prob,
            payload: BitInfoPayloadPlan::None,
        }
    }

    #[must_use]
    pub fn lv2(
        bit: u32,
        encoding: Lv2OrderEncoding,
        first: Lv2OrderItemPlan,
        additional: impl IntoIterator<Item = Lv2OrderItemPlan>,
    ) -> Self {
        let items = std::iter::once(first).chain(additional).collect();
        Self {
            bit,
            prob: None,
            payload: BitInfoPayloadPlan::Lv2Order { encoding, items },
        }
    }
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub enum BitInfoPayloadPlan {
    None,
    Lv2Order {
        encoding: Lv2OrderEncoding,
        items: Vec<Lv2OrderItemPlan>,
    },
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Lv2OrderEncoding {
    LegacyProb2,
    BytesV2,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Lv2OrderItemPlan {
    pub lv2_type: u32,
    pub level: u32,
}

#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct SubBitOptions {
    pub session: i32,
    /// The enclosing CMD6211 market command targets C++ `NN_QuoteMktType_US`.
    /// KLine subscription probabilities need this frozen routing fact because
    /// US minute KLines add pre/after-hours and overnight rehab groups.
    pub kline_us_market: bool,
    pub orderbook_detail: bool,
    pub orderbook_full_depth: bool,
    pub broker_detail: bool,
    pub us_pre_after_detail: bool,
    pub extended_time: bool,
    /// Frozen market-specific planner input derived from one facts snapshot.
    pub wire_profile: SubscriptionWireProfile,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SecurityWithOpts {
    pub stock_id: u64,
    pub ftapi_market: i32,
    pub sub_types_with_opts: Vec<(i32, SubBitOptions)>,
    pub broker_id: Option<NonZeroU32>,
}

impl SecurityWithOpts {
    #[must_use]
    pub fn new(
        stock_id: u64,
        ftapi_market: i32,
        sub_types_with_opts: Vec<(i32, SubBitOptions)>,
    ) -> Self {
        Self {
            stock_id,
            ftapi_market,
            sub_types_with_opts,
            broker_id: None,
        }
    }

    #[must_use]
    pub fn with_broker(
        stock_id: u64,
        ftapi_market: i32,
        sub_types_with_opts: Vec<(i32, SubBitOptions)>,
        broker_id: u32,
    ) -> Self {
        Self {
            stock_id,
            ftapi_market,
            sub_types_with_opts,
            broker_id: NonZeroU32::new(broker_id),
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct EmptyDesiredMarket {
    pub mkt_type: u8,
    pub is_depth: bool,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SubscriptionSecurityFacts {
    pub stock_id: u64,
    pub sec_type: i32,
    pub mkt_id: u32,
    pub market: i32,
}

#[must_use]
pub fn is_kl_sub_type(sub_type: i32) -> bool {
    matches!(
        sub_type,
        SUB_TYPE_KL_DAY
            | SUB_TYPE_KL_5MIN
            | SUB_TYPE_KL_15MIN
            | SUB_TYPE_KL_30MIN
            | SUB_TYPE_KL_60MIN
            | SUB_TYPE_KL_1MIN
            | SUB_TYPE_KL_WEEK
            | SUB_TYPE_KL_MONTH
            | SUB_TYPE_KL_QUARTER
            | SUB_TYPE_KL_YEAR
            | SUB_TYPE_KL_3MIN
            | SUB_TYPE_KL_10MIN
            | SUB_TYPE_KL_120MIN
            | SUB_TYPE_KL_180MIN
            | SUB_TYPE_KL_240MIN
    )
}

#[must_use]
pub fn is_valid_sub_type(sub_type: i32) -> bool {
    VALID_QOT_SUB_TYPES.contains(&sub_type)
}

#[must_use]
pub fn qot_sub_type_from_str_alias(s: &str) -> Option<i32> {
    Some(match s.trim().to_ascii_lowercase().as_str() {
        "basic" => SUB_TYPE_BASIC,
        "orderbook" | "order_book" => SUB_TYPE_ORDER_BOOK,
        "orderbookodd" | "orderbook_odd" | "order-book-odd" | "order_book_odd"
        | "odd_orderbook" | "odd-lot-orderbook" | "odd_lot_orderbook" => SUB_TYPE_ORDER_BOOK_ODD,
        "ticker" => SUB_TYPE_TICKER,
        "rt" => SUB_TYPE_RT,
        "kl_day" | "kl-day" | "day" => SUB_TYPE_KL_DAY,
        "kl_1min" | "kl-1min" | "1min" => SUB_TYPE_KL_1MIN,
        "kl_3min" | "kl-3min" | "3min" => SUB_TYPE_KL_3MIN,
        "kl_5min" | "kl-5min" | "5min" => SUB_TYPE_KL_5MIN,
        "kl_10min" | "kl-10min" | "10min" => SUB_TYPE_KL_10MIN,
        "kl_15min" | "kl-15min" | "15min" => SUB_TYPE_KL_15MIN,
        "kl_30min" | "kl-30min" | "30min" => SUB_TYPE_KL_30MIN,
        "kl_60min" | "kl-60min" | "60min" => SUB_TYPE_KL_60MIN,
        "kl_120min" | "kl-120min" | "120min" => SUB_TYPE_KL_120MIN,
        "kl_180min" | "kl-180min" | "180min" => SUB_TYPE_KL_180MIN,
        "kl_240min" | "kl-240min" | "240min" => SUB_TYPE_KL_240MIN,
        "kl_week" | "kl-week" | "week" => SUB_TYPE_KL_WEEK,
        "kl_month" | "kl-month" | "month" => SUB_TYPE_KL_MONTH,
        "kl_quarter" | "kl-quarter" | "quarter" => SUB_TYPE_KL_QUARTER,
        "kl_year" | "kl-year" | "year" => SUB_TYPE_KL_YEAR,
        "broker" => SUB_TYPE_BROKER,
        _ => return None,
    })
}

#[must_use]
pub const fn qot_sub_type_short_label(sub_type: i32) -> Option<&'static str> {
    Some(match sub_type {
        SUB_TYPE_BASIC => "basic",
        SUB_TYPE_ORDER_BOOK => "orderbook",
        SUB_TYPE_ORDER_BOOK_ODD => "orderbook_odd",
        SUB_TYPE_TICKER => "ticker",
        SUB_TYPE_RT => "rt",
        SUB_TYPE_KL_DAY => "kl_day",
        SUB_TYPE_KL_1MIN => "kl_1min",
        SUB_TYPE_KL_3MIN => "kl_3min",
        SUB_TYPE_KL_5MIN => "kl_5min",
        SUB_TYPE_KL_10MIN => "kl_10min",
        SUB_TYPE_KL_15MIN => "kl_15min",
        SUB_TYPE_KL_30MIN => "kl_30min",
        SUB_TYPE_KL_60MIN => "kl_60min",
        SUB_TYPE_KL_120MIN => "kl_120min",
        SUB_TYPE_KL_180MIN => "kl_180min",
        SUB_TYPE_KL_240MIN => "kl_240min",
        SUB_TYPE_KL_WEEK => "kl_week",
        SUB_TYPE_KL_MONTH => "kl_month",
        SUB_TYPE_KL_QUARTER => "kl_quarter",
        SUB_TYPE_KL_YEAR => "kl_year",
        SUB_TYPE_BROKER => "broker",
        _ => return None,
    })
}

#[must_use]
pub fn qot_kl_type_from_str_alias(s: &str) -> Option<i32> {
    Some(match s.trim().to_ascii_lowercase().as_str() {
        "day" => 2,
        "week" => 3,
        "month" => 4,
        "quarter" => 11,
        "year" => 5,
        "1min" => 1,
        "3min" => 10,
        "5min" => 6,
        "10min" => 12,
        "15min" => 7,
        "30min" => 8,
        "60min" => 9,
        "120min" => 13,
        "180min" => 14,
        "240min" => 15,
        _ => return None,
    })
}

/// Backend `FTCmdKline.KlineType` value for public FTAPI KLType.
///
/// Most values are identical, but 10/120/180/240 minute cycles are
/// non-contiguous in backend protobuf.
#[must_use]
pub const fn qot_kl_type_backend_kline_type(kl_type: i32) -> Option<u32> {
    Some(match kl_type {
        1 => 1,
        2 => 2,
        3 => 3,
        4 => 4,
        5 => 5,
        6 => 6,
        7 => 7,
        8 => 8,
        9 => 9,
        10 => 10,
        11 => 11,
        12 => 26,
        13 => 14,
        14 => 29,
        15 => 15,
        _ => return None,
    })
}

#[must_use]
pub fn unsupported_option_sub_type_name(sub_type: i32) -> Option<&'static str> {
    match sub_type {
        SUB_TYPE_NONE => Some("None"),
        SUB_TYPE_KL_30MIN => Some("KL_30Min"),
        SUB_TYPE_KL_WEEK => Some("KL_Week"),
        SUB_TYPE_KL_MONTH => Some("KL_Month"),
        SUB_TYPE_KL_QUARTER => Some("KL_Quarter"),
        SUB_TYPE_KL_YEAR => Some("KL_Year"),
        SUB_TYPE_KL_3MIN => Some("KL_3Min"),
        _ => None,
    }
}

#[must_use]
pub const fn kl_type_for_sub_type(sub_type: i32) -> Option<i32> {
    Some(match sub_type {
        SUB_TYPE_KL_1MIN => 1,
        SUB_TYPE_KL_DAY => 2,
        SUB_TYPE_KL_WEEK => 3,
        SUB_TYPE_KL_MONTH => 4,
        SUB_TYPE_KL_YEAR => 5,
        SUB_TYPE_KL_5MIN => 6,
        SUB_TYPE_KL_15MIN => 7,
        SUB_TYPE_KL_30MIN => 8,
        SUB_TYPE_KL_60MIN => 9,
        SUB_TYPE_KL_3MIN => 10,
        SUB_TYPE_KL_QUARTER => 11,
        SUB_TYPE_KL_10MIN => 12,
        SUB_TYPE_KL_120MIN => 13,
        SUB_TYPE_KL_180MIN => 14,
        SUB_TYPE_KL_240MIN => 15,
        _ => return None,
    })
}

#[must_use]
pub const fn sub_type_for_kl_type(kl_type: i32) -> Option<i32> {
    Some(match kl_type {
        1 => SUB_TYPE_KL_1MIN,
        2 => SUB_TYPE_KL_DAY,
        3 => SUB_TYPE_KL_WEEK,
        4 => SUB_TYPE_KL_MONTH,
        5 => SUB_TYPE_KL_YEAR,
        6 => SUB_TYPE_KL_5MIN,
        7 => SUB_TYPE_KL_15MIN,
        8 => SUB_TYPE_KL_30MIN,
        9 => SUB_TYPE_KL_60MIN,
        10 => SUB_TYPE_KL_3MIN,
        11 => SUB_TYPE_KL_QUARTER,
        12 => SUB_TYPE_KL_10MIN,
        13 => SUB_TYPE_KL_120MIN,
        14 => SUB_TYPE_KL_180MIN,
        15 => SUB_TYPE_KL_240MIN,
        _ => return None,
    })
}

#[must_use]
pub const fn is_minute_kl_type(kl_type: i32) -> bool {
    matches!(kl_type, 1 | 6 | 7 | 8 | 9 | 10 | 12 | 13 | 14 | 15)
}

#[must_use]
pub fn is_valid_qot_market(market: i32) -> bool {
    matches!(
        market,
        1 | 11 | 21 | 22 | 31 | 41 | 51 | 61 | 71 | 81 | 91 | 101
    )
}

#[must_use]
pub fn canonical_public_qot_market(market: i32) -> Option<i32> {
    // Ref: FutuOpenD/proto/Qot_Common.proto:8-23 and
    // APIServer_Inner_API.cpp:5513-5524. Public QotMarket=2 is the deprecated
    // HK_Future alias and must be canonicalized before any legacy TrdMarket
    // compatibility mapping can observe the same numeric value.
    if market == 2 {
        return Some(1);
    }
    if is_valid_qot_market(market) {
        return Some(market);
    }

    match market {
        3 => Some(21),
        4 => Some(1),
        5 => Some(1),
        6 => Some(31),
        7 => Some(91),
        8 => Some(51),
        15 => Some(41),
        111 => Some(61),
        112 => Some(71),
        _ => None,
    }
}

/// Explicit legacy TrdMarket compatibility mapping. This helper must never be
/// used for a public QotMarket field because both namespaces assign value 2 to
/// different markets (US versus HK_Future).
#[must_use]
pub const fn legacy_trd_market_to_qot_market(market: i32) -> Option<i32> {
    match market {
        2 => Some(11),
        3 => Some(21),
        4 | 5 => Some(1),
        6 => Some(31),
        7 => Some(91),
        8 => Some(51),
        15 => Some(41),
        111 => Some(61),
        112 => Some(71),
        _ => None,
    }
}

#[must_use]
pub fn ftapi_market_to_quote_mkt(market: i32) -> u8 {
    match market {
        1 => 1,
        11 => 2,
        21 => 3,
        22 => 4,
        5 => 5,
        6 => 6,
        9 => 9,
        13 => 13,
        31 => 15,
        15 => 7,
        14 => 8,
        16 => 16,
        41 => 25,
        61 => 27,
        23 => 10,
        91 => 17,
        // Ref: NNBase_Define_Enum.h:542 NN_QuoteMktType_EventContract=35.
        101 => 35,
        _ => 0,
    }
}

#[must_use]
pub fn is_depth_sub_type(sub_type: i32) -> bool {
    matches!(
        sub_type,
        SUB_TYPE_ORDER_BOOK | SUB_TYPE_ORDER_BOOK_ODD | SUB_TYPE_BROKER
    )
}

#[must_use]
pub fn empty_desired_market_for_sub(
    ftapi_market: i32,
    sub_type: i32,
) -> Option<EmptyDesiredMarket> {
    let mkt_type = ftapi_market_to_quote_mkt(ftapi_market);
    if mkt_type == 0 {
        return None;
    }
    Some(EmptyDesiredMarket {
        mkt_type,
        is_depth: is_depth_sub_type(sub_type),
    })
}

#[must_use]
pub fn backend_subscribe_market_for_info(
    requested_market: i32,
    info: &SubscriptionSecurityFacts,
) -> i32 {
    backend_subscribe_market_for_facts(requested_market, info.sec_type, info.mkt_id)
}

#[must_use]
pub fn backend_subscribe_market_for_facts(
    requested_market: i32,
    sec_type: i32,
    mkt_id: u32,
) -> i32 {
    backend_subscribe_market_for_security(requested_market, sec_type, mkt_id)
}

#[must_use]
pub fn backend_desired_key_for_info(
    sec_key: &str,
    info: &SubscriptionSecurityFacts,
) -> Option<(u64, i32)> {
    backend_desired_key_for_sec_key(sec_key, info.stock_id, info.sec_type, info.mkt_id)
}

#[must_use]
pub fn backend_subscribe_market_for_security(
    requested_market: i32,
    sec_type: i32,
    mkt_id: u32,
) -> i32 {
    if sec_type == SECURITY_TYPE_DRVT {
        return match mkt_id {
            7 | 8 | 570..=579 => BACKEND_MARKET_HK_OPTION,
            41..=45 => BACKEND_MARKET_US_OPTION,
            _ => match requested_market {
                1 => BACKEND_MARKET_HK_OPTION,
                11 => BACKEND_MARKET_US_OPTION,
                _ => requested_market,
            },
        };
    }

    if sec_type != SECURITY_TYPE_FUTURE {
        return requested_market;
    }

    match mkt_id {
        5 => 5,
        6 | 110..=119 => 6,
        60..=109 => 14,
        160..=179 => 13,
        185..=194 => 16,
        1400..=1449 => requested_market,
        _ => match requested_market {
            1 | 2 => 6,
            11 => 14,
            31 => 13,
            41 => 16,
            _ => requested_market,
        },
    }
}

#[must_use]
pub fn public_market_from_sec_key(sec_key: &str) -> Option<i32> {
    QotSecurityKey::parse_public_sec_key(sec_key).map(|key| key.market)
}

#[must_use]
pub fn backend_desired_key_for_sec_key(
    sec_key: &str,
    stock_id: u64,
    sec_type: i32,
    mkt_id: u32,
) -> Option<(u64, i32)> {
    if stock_id == 0 {
        return None;
    }
    let public_market = public_market_from_sec_key(sec_key)?;
    Some((
        stock_id,
        backend_subscribe_market_for_security(public_market, sec_type, mkt_id),
    ))
}