tradestation-api 0.1.0

//! Market data endpoints: historical bars, quotes, symbols, crypto, and options.
//!
//! Covers TradeStation v3 endpoints:
//! - `GET /v3/marketdata/barcharts/{symbol}`
//! - `GET /v3/marketdata/quotes/{symbols}`
//! - `GET /v3/marketdata/symbols/{symbols}`
//! - `GET /v3/marketdata/symbollists/cryptopairs/symbolnames`
//! - `GET /v3/marketdata/options/expirations/{underlying}`
//! - `GET /v3/marketdata/options/strikes/{underlying}`
//! - `GET /v3/marketdata/options/spreadtypes`
//! - `POST /v3/marketdata/options/riskreward`

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

use crate::Client;
use crate::Error;

/// OHLCV bar from the barcharts endpoint.
///
/// All numeric fields are returned as strings by the API. Use [`Bar::ohlcv`]
/// to parse them into native types.
///
/// # Example
///
/// ```
/// # use tradestation_api::Bar;
/// # let bar = Bar {
/// #     high: "150.00".into(), low: "148.00".into(),
/// #     open: "149.00".into(), close: "149.50".into(),
/// #     time_stamp: "2024-01-15T10:00:00Z".into(), total_volume: "1000".into(),
/// #     down_ticks: None, down_volume: None, open_interest: None,
/// #     total_ticks: None, unchanged_ticks: None, unchanged_volume: None,
/// #     up_ticks: None, up_volume: None,
/// #     is_realtime: None, is_end_of_history: None, epoch: None, bar_status: None,
/// # };
/// if let Some((o, h, l, c, v)) = bar.ohlcv() {
///     println!("close={c}, volume={v}");
/// }
/// ```
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "PascalCase")]
pub struct Bar {
    /// Highest price during the bar period.
    pub high: String,
    /// Lowest price during the bar period.
    pub low: String,
    /// Opening price.
    pub open: String,
    /// Closing price.
    pub close: String,
    /// Bar timestamp (RFC 3339).
    pub time_stamp: String,
    /// Total volume traded during the bar period.
    pub total_volume: String,
    /// Number of down ticks.
    #[serde(default)]
    pub down_ticks: Option<serde_json::Value>,
    /// Volume on down ticks.
    #[serde(default)]
    pub down_volume: Option<serde_json::Value>,
    /// Open interest (futures/options).
    #[serde(default)]
    pub open_interest: Option<serde_json::Value>,
    /// Total number of ticks.
    #[serde(default)]
    pub total_ticks: Option<serde_json::Value>,
    /// Number of unchanged ticks.
    #[serde(default)]
    pub unchanged_ticks: Option<serde_json::Value>,
    /// Volume on unchanged ticks.
    #[serde(default)]
    pub unchanged_volume: Option<serde_json::Value>,
    /// Number of up ticks.
    #[serde(default)]
    pub up_ticks: Option<serde_json::Value>,
    /// Volume on up ticks.
    #[serde(default)]
    pub up_volume: Option<serde_json::Value>,
    /// Whether this bar is from real-time data.
    #[serde(default)]
    pub is_realtime: Option<bool>,
    /// Whether this is the last bar in the history.
    #[serde(default)]
    pub is_end_of_history: Option<bool>,
    /// Unix epoch timestamp in milliseconds.
    #[serde(default)]
    pub epoch: Option<u64>,
    /// Bar status (e.g., "Closed", "Open").
    #[serde(default)]
    pub bar_status: Option<String>,
}

impl Bar {
    /// Parse OHLCV string fields into `(open, high, low, close, volume)`.
    ///
    /// Returns `None` if any field fails to parse.
    pub fn ohlcv(&self) -> Option<(f64, f64, f64, f64, u64)> {
        Some((
            self.open.parse().ok()?,
            self.high.parse().ok()?,
            self.low.parse().ok()?,
            self.close.parse().ok()?,
            self.total_volume.parse().ok()?,
        ))
    }

    /// Parse the bar timestamp into a `DateTime<Utc>`.
    ///
    /// Returns `None` if the timestamp is not valid RFC 3339.
    pub fn timestamp(&self) -> Option<DateTime<Utc>> {
        DateTime::parse_from_rfc3339(&self.time_stamp)
            .ok()
            .map(|dt| dt.with_timezone(&Utc))
    }
}

/// Response from barcharts endpoint.
#[derive(Debug, Deserialize)]
#[serde(rename_all = "PascalCase")]
pub struct BarChartResponse {
    pub bars: Vec<Bar>,
}

/// Quote snapshot for a single symbol.
///
/// Returned by [`Client::get_quotes`].
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "PascalCase")]
pub struct Quote {
    /// Ticker symbol.
    pub symbol: String,
    /// Last traded price.
    pub last: String,
    /// Best ask price.
    pub ask: String,
    /// Best bid price.
    pub bid: String,
    /// Cumulative volume.
    pub volume: String,
    /// Previous session close.
    #[serde(default)]
    pub close: Option<String>,
    /// Session high.
    #[serde(default)]
    pub high: Option<String>,
    /// Session low.
    #[serde(default)]
    pub low: Option<String>,
    /// Session open.
    #[serde(default)]
    pub open: Option<String>,
    /// Net change from previous close.
    #[serde(default)]
    pub net_change: Option<String>,
    /// Net change as a percentage.
    #[serde(default)]
    pub net_change_pct: Option<String>,
    /// Time of the last trade.
    #[serde(rename = "TradeTime", default)]
    pub trade_time: Option<String>,
}

/// Response from quotes endpoint.
#[derive(Debug, Deserialize)]
#[serde(rename_all = "PascalCase")]
pub struct QuoteResponse {
    pub quotes: Vec<Quote>,
}

/// Symbol definition metadata.
///
/// Returned by [`Client::get_symbol_info`].
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "PascalCase")]
pub struct SymbolInfo {
    /// Ticker symbol.
    pub symbol: String,
    /// Human-readable description.
    pub description: Option<String>,
    /// Exchange where the symbol is listed.
    pub exchange: Option<String>,
    /// Asset category (e.g., "Stock", "Future").
    pub category: Option<String>,
    /// Trading currency.
    #[serde(default)]
    pub currency: Option<String>,
    /// Contract point value (futures/options).
    #[serde(default)]
    pub point_value: Option<String>,
    /// Minimum price movement.
    #[serde(default)]
    pub min_move: Option<String>,
}

/// Response from symbols endpoint.
#[derive(Debug, Deserialize)]
#[serde(rename_all = "PascalCase")]
struct SymbolResponse {
    definitions: Vec<SymbolInfo>,
}

/// Query parameters for the barcharts endpoint.
///
/// Use the builder constructors [`BarChartQuery::minute_bars`] or
/// [`BarChartQuery::daily_bars`] for common cases.
///
/// # Example
///
/// ```
/// use tradestation_api::BarChartQuery;
///
/// let query = BarChartQuery::minute_bars("AAPL", 100);
/// let daily = BarChartQuery::daily_bars("MSFT", 30);
/// let range = BarChartQuery::daily_bars("GOOG", 0)
///     .with_dates("2024-01-01", "2024-03-01");
/// ```
pub struct BarChartQuery {
    /// Target symbol.
    pub symbol: String,
    /// Bar interval (e.g., "1", "5", "15").
    pub interval: String,
    /// Bar unit (e.g., "Minute", "Daily", "Weekly").
    pub unit: String,
    /// Number of bars to fetch (mutually exclusive with date range).
    pub bars_back: Option<u32>,
    /// Start date for date-range queries.
    pub first_date: Option<String>,
    /// End date for date-range queries.
    pub last_date: Option<String>,
    /// Session template (e.g., "Default", "USEQPre").
    pub session_template: Option<String>,
}

impl BarChartQuery {
    /// Create a query for 1-minute bars.
    pub fn minute_bars(symbol: impl Into<String>, bars_back: u32) -> Self {
        Self {
            symbol: symbol.into(),
            interval: "1".to_string(),
            unit: "Minute".to_string(),
            bars_back: Some(bars_back),
            first_date: None,
            last_date: None,
            session_template: None,
        }
    }

    /// Create a query for daily bars.
    pub fn daily_bars(symbol: impl Into<String>, bars_back: u32) -> Self {
        Self {
            symbol: symbol.into(),
            interval: "1".to_string(),
            unit: "Daily".to_string(),
            bars_back: Some(bars_back),
            first_date: None,
            last_date: None,
            session_template: None,
        }
    }

    /// Set a date range, clearing `bars_back`.
    pub fn with_dates(mut self, first_date: &str, last_date: &str) -> Self {
        self.first_date = Some(first_date.to_string());
        self.last_date = Some(last_date.to_string());
        self.bars_back = None;
        self
    }

    fn to_query_params(&self) -> Vec<(&str, String)> {
        let mut params = vec![
            ("interval", self.interval.clone()),
            ("unit", self.unit.clone()),
        ];
        if let Some(bars_back) = self.bars_back {
            params.push(("barsBack", bars_back.to_string()));
        }
        if let Some(first_date) = &self.first_date {
            params.push(("firstDate", first_date.clone()));
        }
        if let Some(last_date) = &self.last_date {
            params.push(("lastDate", last_date.clone()));
        }
        if let Some(session) = &self.session_template {
            params.push(("sessionTemplate", session.clone()));
        }
        params
    }
}

/// A cryptocurrency trading pair name from the symbollists endpoint.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "PascalCase")]
pub struct CryptoPair {
    /// Pair name (e.g., "BTCUSD").
    pub name: String,
}

/// Response from crypto pairs endpoint.
#[derive(Debug, Deserialize)]
#[serde(rename_all = "PascalCase")]
struct CryptoPairsResponse {
    crypto_pairs: Vec<String>,
}

/// Option expiration date and type.
///
/// Returned by [`Client::get_option_expirations`].
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "PascalCase")]
pub struct OptionExpiration {
    /// Expiration date string (e.g., "2024-03-15").
    pub date: String,
    /// Expiration type (e.g., "Weekly", "Monthly").
    #[serde(default, rename = "Type")]
    pub expiration_type: Option<String>,
}

/// Response from option expirations endpoint.
#[derive(Debug, Deserialize)]
#[serde(rename_all = "PascalCase")]
struct OptionExpirationsResponse {
    expirations: Vec<OptionExpiration>,
}

/// A single option strike price.
///
/// Returned by [`Client::get_option_strikes`].
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "PascalCase")]
pub struct OptionStrike {
    /// The strike price as a string.
    pub strike_price: String,
}

/// Response from option strikes endpoint.
#[derive(Debug, Deserialize)]
#[serde(rename_all = "PascalCase")]
struct OptionStrikesResponse {
    strikes: Vec<OptionStrike>,
}

/// Option spread type definition.
///
/// Returned by [`Client::get_option_spread_types`].
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "PascalCase")]
pub struct SpreadType {
    /// Spread type name (e.g., "Vertical", "Calendar").
    pub name: String,
    /// Human-readable description.
    #[serde(default)]
    pub description: Option<String>,
}

/// Response from spread types endpoint.
#[derive(Debug, Deserialize)]
#[serde(rename_all = "PascalCase")]
struct SpreadTypesResponse {
    spread_types: Vec<SpreadType>,
}

/// Request body for option risk/reward analysis.
///
/// Used with [`Client::get_option_risk_reward`].
#[derive(Debug, Serialize)]
#[serde(rename_all = "PascalCase")]
pub struct RiskRewardRequest {
    /// Option symbol.
    pub symbol: String,
    /// Trade action (e.g., "BUY", "SELL").
    pub trade_action: String,
    /// Number of contracts.
    pub quantity: String,
    /// Limit price for the analysis.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub limit_price: Option<String>,
    /// Stop price for the analysis.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub stop_price: Option<String>,
}

/// Response from option risk/reward analysis.
#[derive(Debug, Clone, Deserialize)]
#[serde(rename_all = "PascalCase")]
pub struct RiskRewardResponse {
    /// Maximum potential reward.
    #[serde(default)]
    pub max_reward: Option<String>,
    /// Maximum potential risk.
    #[serde(default)]
    pub max_risk: Option<String>,
    /// Break-even price.
    #[serde(default)]
    pub break_even: Option<String>,
}

/// Convenience trait for parsing string numeric fields to native types.
///
/// TradeStation returns most numeric values as JSON strings. This trait
/// provides ergonomic parsing on any type with a string field.
///
/// # Example
///
/// ```
/// use tradestation_api::market_data::ParseNumeric;
///
/// let value = "123.45";
/// assert_eq!(value.parse_f64(), Some(123.45));
/// assert_eq!("1000".parse_u64(), Some(1000));
/// assert_eq!("bad".parse_f64(), None);
/// ```
pub trait ParseNumeric {
    /// Parse this string value as `f64`, returning `None` on failure.
    fn parse_f64(&self) -> Option<f64>;
    /// Parse this string value as `u64`, returning `None` on failure.
    fn parse_u64(&self) -> Option<u64>;
}

impl ParseNumeric for str {
    fn parse_f64(&self) -> Option<f64> {
        self.parse().ok()
    }

    fn parse_u64(&self) -> Option<u64> {
        self.parse().ok()
    }
}

impl ParseNumeric for String {
    fn parse_f64(&self) -> Option<f64> {
        self.parse().ok()
    }

    fn parse_u64(&self) -> Option<u64> {
        self.parse().ok()
    }
}

impl ParseNumeric for Option<String> {
    fn parse_f64(&self) -> Option<f64> {
        self.as_deref()?.parse().ok()
    }

    fn parse_u64(&self) -> Option<u64> {
        self.as_deref()?.parse().ok()
    }
}

impl Client {
    /// Fetch historical bar chart data for a symbol.
    ///
    /// # Errors
    ///
    /// Returns [`Error::Api`] if the API request fails.
    pub async fn get_bars(&mut self, query: &BarChartQuery) -> Result<Vec<Bar>, Error> {
        let path = format!("/v3/marketdata/barcharts/{}", query.symbol);
        let headers = self.auth_headers().await?;
        let url = format!("{}{}", self.base_url(), &path);

        let mut req = self.http.get(&url).headers(headers);
        for (key, value) in query.to_query_params() {
            req = req.query(&[(key, &value)]);
        }

        let resp = req.send().await?;
        if !resp.status().is_success() {
            let status = resp.status().as_u16();
            let body = resp.text().await.unwrap_or_default();
            return Err(Error::Api {
                status,
                message: body,
            });
        }

        let chart_resp: BarChartResponse = resp.json().await?;
        Ok(chart_resp.bars)
    }

    /// Fetch quote snapshots for one or more symbols.
    ///
    /// Accepts a slice of ticker symbols (e.g., `&["AAPL", "MSFT"]`).
    pub async fn get_quotes(&mut self, symbols: &[&str]) -> Result<Vec<Quote>, Error> {
        let symbols_str = symbols.join(",");
        let path = format!("/v3/marketdata/quotes/{}", symbols_str);
        let resp = self.get(&path).await?;
        let quote_resp: QuoteResponse = resp.json().await?;
        Ok(quote_resp.quotes)
    }

    /// Fetch symbol definition metadata.
    pub async fn get_symbol_info(&mut self, symbols: &[&str]) -> Result<Vec<SymbolInfo>, Error> {
        let symbols_str = symbols.join(",");
        let path = format!("/v3/marketdata/symbols/{}", symbols_str);
        let resp = self.get(&path).await?;
        let symbol_resp: SymbolResponse = resp.json().await?;
        Ok(symbol_resp.definitions)
    }

    /// Fetch available cryptocurrency trading pairs.
    pub async fn get_crypto_pairs(&mut self) -> Result<Vec<String>, Error> {
        let resp = self
            .get("/v3/marketdata/symbollists/cryptopairs/symbolnames")
            .await?;
        let data: CryptoPairsResponse = resp.json().await?;
        Ok(data.crypto_pairs)
    }

    /// Fetch option expiration dates for an underlying symbol.
    pub async fn get_option_expirations(
        &mut self,
        underlying: &str,
    ) -> Result<Vec<OptionExpiration>, Error> {
        let path = format!("/v3/marketdata/options/expirations/{}", underlying);
        let resp = self.get(&path).await?;
        let data: OptionExpirationsResponse = resp.json().await?;
        Ok(data.expirations)
    }

    /// Fetch available strike prices for an underlying symbol.
    pub async fn get_option_strikes(
        &mut self,
        underlying: &str,
    ) -> Result<Vec<OptionStrike>, Error> {
        let path = format!("/v3/marketdata/options/strikes/{}", underlying);
        let resp = self.get(&path).await?;
        let data: OptionStrikesResponse = resp.json().await?;
        Ok(data.strikes)
    }

    /// Fetch available option spread types (e.g., Vertical, Calendar).
    pub async fn get_option_spread_types(&mut self) -> Result<Vec<SpreadType>, Error> {
        let resp = self.get("/v3/marketdata/options/spreadtypes").await?;
        let data: SpreadTypesResponse = resp.json().await?;
        Ok(data.spread_types)
    }

    /// Analyze option risk/reward for a given trade.
    pub async fn get_option_risk_reward(
        &mut self,
        request: &RiskRewardRequest,
    ) -> Result<RiskRewardResponse, Error> {
        let resp = self
            .post("/v3/marketdata/options/riskreward", request)
            .await?;
        Ok(resp.json().await?)
    }
}