maxt 0.2.1

//! Request builders for the calls that take more than one argument.

use rust_decimal::Decimal;

use crate::error::{Error, Result};
use crate::types::{
    Cursor, Interval, MarginMode, Market, Network, OrderStatus, OrderType, Side, Size, TimeInForce,
    Timestamp, TransferDestination,
};

/// Selects one deposit address for an asset and network.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DepositAddressRequest {
    /// Asset symbol, uppercase.
    pub asset: String,
    /// Canonical network.
    pub network: Network,
    /// Amount required by address-per-payment networks such as Lightning.
    pub amount: Option<Decimal>,
}

impl DepositAddressRequest {
    /// Builds a deposit-address request.
    pub fn new(asset: impl Into<String>, network: Network) -> Self {
        Self {
            asset: asset.into().to_ascii_uppercase(),
            network,
            amount: None,
        }
    }

    /// Sets the amount for networks that issue an address or invoice per payment.
    #[must_use]
    pub fn amount(mut self, amount: Decimal) -> Self {
        self.amount = Some(amount);
        self
    }
}

/// A withdrawal to an exchange-issued or direct on-chain destination.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WithdrawRequest {
    /// Asset symbol, uppercase.
    pub asset: String,
    /// Canonical source and destination network.
    pub network: Network,
    /// Amount before provider fees.
    pub amount: Decimal,
    /// Destination address and optional memo.
    pub destination: TransferDestination,
    /// Caller idempotency identifier, when the provider supports one.
    pub client_id: Option<String>,
}

impl WithdrawRequest {
    /// Builds a withdrawal request.
    pub fn new(
        asset: impl Into<String>,
        network: Network,
        amount: Decimal,
        destination: TransferDestination,
    ) -> Self {
        Self {
            asset: asset.into().to_ascii_uppercase(),
            network,
            amount,
            destination,
            client_id: None,
        }
    }

    /// Sets a caller-controlled idempotency identifier.
    #[must_use]
    pub fn client_id(mut self, client_id: impl Into<String>) -> Self {
        self.client_id = Some(client_id.into());
        self
    }
}

/// Identifies one deposit or withdrawal by the exchange UUID or transaction ID.
///
/// Both currently supported exchanges require the asset symbol for a precise
/// lookup. Exactly one reference is required; this deliberately never falls
/// back to the provider's newest transfer.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TransferLookupRequest {
    /// Asset symbol, uppercase.
    pub asset: String,
    /// Exchange-issued transfer UUID, when used as the reference.
    pub id: Option<String>,
    /// On-chain transaction ID, when used as the reference.
    pub tx_id: Option<String>,
}

impl TransferLookupRequest {
    /// Looks up one transfer by its exchange-issued UUID.
    pub fn by_id(asset: impl Into<String>, id: impl Into<String>) -> Self {
        Self {
            asset: asset.into().to_ascii_uppercase(),
            id: Some(id.into()),
            tx_id: None,
        }
    }

    /// Looks up one transfer by its on-chain transaction ID.
    pub fn by_tx_id(asset: impl Into<String>, tx_id: impl Into<String>) -> Self {
        Self {
            asset: asset.into().to_ascii_uppercase(),
            id: None,
            tx_id: Some(tx_id.into()),
        }
    }

    /// Validates that this request identifies exactly one transfer.
    pub fn validate(&self) -> Result<()> {
        self.reference().map(|_| ())
    }

    pub(crate) fn reference(&self) -> Result<(&'static str, &str)> {
        if self.asset.trim().is_empty() {
            return Err(Error::invalid_request("asset", "asset must not be empty"));
        }
        match (&self.id, &self.tx_id) {
            (Some(id), None) if !id.trim().is_empty() => Ok(("uuid", id)),
            (None, Some(tx_id)) if !tx_id.trim().is_empty() => Ok(("txid", tx_id)),
            (None, None) => Err(Error::invalid_request(
                "reference",
                "set either an exchange transfer ID or a transaction ID",
            )),
            (Some(_), Some(_)) => Err(Error::invalid_request(
                "reference",
                "set exactly one of the exchange transfer ID or transaction ID",
            )),
            (Some(_), None) => Err(Error::invalid_request(
                "id",
                "exchange transfer ID must not be empty",
            )),
            (None, Some(_)) => Err(Error::invalid_request(
                "tx_id",
                "transaction ID must not be empty",
            )),
        }
    }
}

/// One page of deposit or withdrawal history.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct TransferHistoryRequest {
    /// Optional asset filter.
    pub asset: Option<String>,
    /// Optional canonical network filter.
    pub network: Option<Network>,
    /// Provider cursor returned by a previous page.
    pub cursor: Option<Cursor>,
    /// Target page size.
    pub limit: Option<u32>,
}

impl TransferHistoryRequest {
    /// Starts an unfiltered history request.
    pub fn new() -> Self {
        Self::default()
    }

    /// Filters by asset.
    #[must_use]
    pub fn asset(mut self, asset: impl Into<String>) -> Self {
        self.asset = Some(asset.into().to_ascii_uppercase());
        self
    }

    /// Filters by network.
    #[must_use]
    pub fn network(mut self, network: Network) -> Self {
        self.network = Some(network);
        self
    }

    /// Resumes from a provider cursor.
    #[must_use]
    pub fn cursor(mut self, cursor: Cursor) -> Self {
        self.cursor = Some(cursor);
        self
    }

    /// Sets the target page size.
    #[must_use]
    pub fn limit(mut self, limit: u32) -> Self {
        self.limit = Some(limit);
        self
    }
}

/// Which candles to read.
///
/// Results are sorted oldest first.
///
/// - `from`: inclusive lower bound. Without `limit`, reads through `to` or now.
/// - `to`: exclusive upper bound.
/// - `limit`: selects the oldest matches when `from` is set, otherwise the
///   newest.
/// - Paging: at most 100 exchange calls per request.
///
/// With all optional fields unset, returns the exchange's most recent page.
/// Requests estimated to exceed the paging limit return
/// [`Error::InvalidRequest`](crate::Error::InvalidRequest) before the first
/// exchange call.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CandleRequest {
    /// The market to read candles for.
    pub market: Market,
    /// The candle interval.
    pub interval: Interval,
    /// Oldest candle to return, by open time, inclusive.
    pub from: Option<Timestamp>,
    /// Newest candle to return, by open time, exclusive.
    pub to: Option<Timestamp>,
    /// Target number of candles. Must be at least one when set.
    ///
    /// This may span multiple provider responses, subject to the request's
    /// paging limit.
    pub limit: Option<u32>,
}

impl CandleRequest {
    /// The most recent candles for a market at one interval.
    pub fn new(market: Market, interval: Interval) -> Self {
        Self {
            market,
            interval,
            from: None,
            to: None,
            limit: None,
        }
    }

    /// Sets the inclusive bound `open_time >= from`.
    #[must_use]
    pub fn from(mut self, from: Timestamp) -> Self {
        self.from = Some(from);
        self
    }

    /// Sets the exclusive bound `open_time < to`.
    #[must_use]
    pub fn to(mut self, to: Timestamp) -> Self {
        self.to = Some(to);
        self
    }

    /// Returns at most this many candles.
    #[must_use]
    pub fn limit(mut self, limit: u32) -> Self {
        self.limit = Some(limit);
        self
    }
}

/// An order to place.
///
/// Build it with [`OrderRequest::market`], [`OrderRequest::limit`], or
/// [`OrderRequest::best`], which keep price and size in step. Only a limit
/// order carries a caller-selected price.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OrderRequest {
    /// The market to trade.
    pub market: Market,
    /// Buy or sell.
    pub side: Side,
    /// Market, limit, or exchange-priced best.
    pub order_type: OrderType,
    /// How much, in base or quote terms.
    pub size: Size,
    /// The limit price. `None` for market and best orders.
    pub price: Option<Decimal>,
    /// How long the order stays live. `None` leaves it to the exchange default.
    pub time_in_force: Option<TimeInForce>,
    /// Whether the order may only reduce an existing position.
    ///
    /// Derivatives only. Set it with [`OrderRequest::reduce_only`].
    pub reduce_only: bool,
    /// Caller-assigned order identifier, when the exchange supports one.
    pub client_id: Option<String>,
}

impl OrderRequest {
    /// An order that takes whatever the book offers, immediately.
    pub fn market(market: Market, side: Side, size: Size) -> Self {
        Self {
            market,
            side,
            order_type: OrderType::Market,
            size,
            price: None,
            time_in_force: None,
            reduce_only: false,
            client_id: None,
        }
    }

    /// An order that rests on the book at a stated price.
    pub fn limit(market: Market, side: Side, size: Size, price: Decimal) -> Self {
        Self {
            market,
            side,
            order_type: OrderType::Limit,
            size,
            price: Some(price),
            time_in_force: None,
            reduce_only: false,
            client_id: None,
        }
    }

    /// An order priced from the best opposing quote at submission time.
    ///
    /// Exchanges that support this shape require immediate-or-cancel or
    /// fill-or-kill. The accepted size unit is exchange-specific.
    pub fn best(market: Market, side: Side, size: Size, time_in_force: TimeInForce) -> Self {
        Self {
            market,
            side,
            order_type: OrderType::Best,
            size,
            price: None,
            time_in_force: Some(time_in_force),
            reduce_only: false,
            client_id: None,
        }
    }

    /// Sets how long the order stays live.
    #[must_use]
    pub fn time_in_force(mut self, time_in_force: TimeInForce) -> Self {
        self.time_in_force = Some(time_in_force);
        self
    }

    /// Restricts the order to reducing an existing position.
    ///
    /// Rejected as [`Error::Unsupported`](crate::Error::Unsupported) on spot
    /// markets, which have no positions to reduce.
    #[must_use]
    pub fn reduce_only(mut self) -> Self {
        self.reduce_only = true;
        self
    }

    /// Sets the caller-assigned order identifier.
    #[must_use]
    pub fn client_id(mut self, client_id: impl Into<String>) -> Self {
        self.client_id = Some(client_id.into());
        self
    }
}

/// Which identifier namespace to use for a multi-order lookup.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum OrderIdKind {
    /// Identifiers assigned by the exchange.
    Exchange,
    /// Identifiers supplied by the caller when placing orders.
    Client,
}

/// Looks up up to 100 orders by one identifier namespace.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct OrderLookupRequest {
    /// Exchange-assigned or caller-assigned identifiers.
    pub kind: OrderIdKind,
    /// One to 100 identifiers. Missing orders may be omitted by the provider.
    pub ids: Vec<String>,
    /// Optional market filter.
    pub market: Option<Market>,
}

impl OrderLookupRequest {
    /// Looks up exchange-assigned order identifiers.
    pub fn exchange(ids: impl IntoIterator<Item = impl Into<String>>) -> Self {
        Self {
            kind: OrderIdKind::Exchange,
            ids: ids.into_iter().map(Into::into).collect(),
            market: None,
        }
    }

    /// Looks up caller-assigned order identifiers.
    pub fn client(ids: impl IntoIterator<Item = impl Into<String>>) -> Self {
        Self {
            kind: OrderIdKind::Client,
            ids: ids.into_iter().map(Into::into).collect(),
            market: None,
        }
    }

    /// Filters the lookup by market.
    #[must_use]
    pub fn market(mut self, market: Market) -> Self {
        self.market = Some(market);
        self
    }
}

/// Orders to cancel by one identifier namespace.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CancelOrdersRequest {
    /// Exchange-assigned or caller-assigned identifiers.
    pub kind: OrderIdKind,
    /// Identifiers to cancel. Provider batch limits differ.
    pub ids: Vec<String>,
}

impl CancelOrdersRequest {
    /// Cancels orders by exchange-assigned identifiers.
    pub fn exchange(ids: impl IntoIterator<Item = impl Into<String>>) -> Self {
        Self {
            kind: OrderIdKind::Exchange,
            ids: ids.into_iter().map(Into::into).collect(),
        }
    }

    /// Cancels orders by caller-assigned identifiers.
    pub fn client(ids: impl IntoIterator<Item = impl Into<String>>) -> Self {
        Self {
            kind: OrderIdKind::Client,
            ids: ids.into_iter().map(Into::into).collect(),
        }
    }
}

/// One newest-first page of completed or cancelled orders.
///
/// Leave [`OrderHistoryRequest::statuses`] empty to include both completed and
/// cancelled orders. Providers reject any status that is not final.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct OrderHistoryRequest {
    /// Optional market filter.
    pub market: Option<Market>,
    /// Final statuses to include. Empty means all final statuses.
    pub statuses: Vec<OrderStatus>,
    /// Oldest creation time to include.
    pub from: Option<Timestamp>,
    /// Newest creation-time boundary, exclusive.
    pub to: Option<Timestamp>,
    /// Provider cursor returned by a previous page.
    pub cursor: Option<Cursor>,
    /// Target page size.
    pub limit: Option<u32>,
}

impl OrderHistoryRequest {
    /// Starts an unfiltered final-order history request.
    pub fn new() -> Self {
        Self::default()
    }

    /// Filters by market.
    #[must_use]
    pub fn market(mut self, market: Market) -> Self {
        self.market = Some(market);
        self
    }

    /// Filters by one final status.
    #[must_use]
    pub fn status(mut self, status: OrderStatus) -> Self {
        self.statuses = vec![status];
        self
    }

    /// Filters by final statuses.
    #[must_use]
    pub fn statuses(mut self, statuses: impl IntoIterator<Item = OrderStatus>) -> Self {
        self.statuses = statuses.into_iter().collect();
        self
    }

    /// Sets the inclusive creation-time lower bound.
    #[must_use]
    pub fn from(mut self, from: Timestamp) -> Self {
        self.from = Some(from);
        self
    }

    /// Sets the exclusive creation-time upper bound.
    #[must_use]
    pub fn to(mut self, to: Timestamp) -> Self {
        self.to = Some(to);
        self
    }

    /// Resumes from a cursor returned by a previous page.
    #[must_use]
    pub fn cursor(mut self, cursor: Cursor) -> Self {
        self.cursor = Some(cursor);
        self
    }

    /// Sets the target page size.
    #[must_use]
    pub fn limit(mut self, limit: u32) -> Self {
        self.limit = Some(limit);
        self
    }
}

/// A window of history to read, one page at a time.
///
/// Leave [`HistoryRequest::cursor`] unset for the first page, then pass the
/// [`Page::next`](crate::Page::next) cursor back for each page after that.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct HistoryRequest {
    /// The market to read history for.
    pub market: Market,
    /// Oldest entry to return, inclusive.
    pub from: Option<Timestamp>,
    /// Newest entry to return, exclusive.
    pub to: Option<Timestamp>,
    /// Where to resume from. `None` starts at the beginning of the window.
    pub cursor: Option<Cursor>,
    /// Target page size, not a hard maximum.
    ///
    /// A provider may return more entries to avoid splitting entries that share
    /// one timestamp.
    pub limit: Option<u32>,
}

impl HistoryRequest {
    /// The first page of history for a market.
    pub fn new(market: Market) -> Self {
        Self {
            market,
            from: None,
            to: None,
            cursor: None,
            limit: None,
        }
    }

    /// Sets the inclusive bound `item.timestamp >= from`.
    #[must_use]
    pub fn from(mut self, from: Timestamp) -> Self {
        self.from = Some(from);
        self
    }

    /// Sets the exclusive bound `item.timestamp < to`.
    #[must_use]
    pub fn to(mut self, to: Timestamp) -> Self {
        self.to = Some(to);
        self
    }

    /// Resumes from a cursor returned by a previous page.
    #[must_use]
    pub fn cursor(mut self, cursor: Cursor) -> Self {
        self.cursor = Some(cursor);
        self
    }

    /// Sets the target page size, not a hard maximum.
    ///
    /// A page may be longer when trimming it would split entries sharing one
    /// timestamp and make the cursor skip entries. Do not size a fixed buffer
    /// from this value. Zero is invalid; provider maximums differ.
    #[must_use]
    pub fn limit(mut self, limit: u32) -> Self {
        self.limit = Some(limit);
        self
    }
}

/// A change to how margin backs one market.
///
/// At least one of leverage or margin mode must be set. A request that changes
/// nothing is rejected as
/// [`Error::InvalidRequest`](crate::Error::InvalidRequest).
///
/// Provider constraints differ. Some accept either field; others require both.
/// Applying both is not guaranteed to be atomic.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MarginRequest {
    /// The market to configure.
    pub market: Market,
    /// The leverage to set.
    pub leverage: Option<Decimal>,
    /// The margin mode to set.
    pub margin_mode: Option<MarginMode>,
}

impl MarginRequest {
    /// A margin change for one market, with nothing set yet.
    pub fn new(market: Market) -> Self {
        Self {
            market,
            leverage: None,
            margin_mode: None,
        }
    }

    /// Sets the leverage.
    #[must_use]
    pub fn leverage(mut self, leverage: Decimal) -> Self {
        self.leverage = Some(leverage);
        self
    }

    /// Sets the margin mode.
    #[must_use]
    pub fn margin_mode(mut self, margin_mode: MarginMode) -> Self {
        self.margin_mode = Some(margin_mode);
        self
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::Exchange;

    fn btc_krw() -> Market {
        Market::spot(Exchange::Upbit, "BTC", "KRW")
    }

    #[test]
    fn constructors_keep_price_and_client_id_in_their_explicit_fields() {
        let market_order =
            OrderRequest::market(btc_krw(), Side::Buy, Size::Quote(Decimal::from(10_000)));
        let limit_order = OrderRequest::limit(
            btc_krw(),
            Side::Sell,
            Size::Base(Decimal::new(1, 2)),
            Decimal::from(100_000_000),
        );
        let best_order = OrderRequest::best(
            btc_krw(),
            Side::Buy,
            Size::Quote(Decimal::from(10_000)),
            TimeInForce::ImmediateOrCancel,
        )
        .client_id("client-1");

        assert_eq!(market_order.order_type, OrderType::Market);
        assert_eq!(market_order.price, None);
        assert_eq!(limit_order.order_type, OrderType::Limit);
        assert_eq!(limit_order.price, Some(Decimal::from(100_000_000)));
        assert_eq!(best_order.order_type, OrderType::Best);
        assert_eq!(best_order.price, None);
        assert_eq!(best_order.client_id.as_deref(), Some("client-1"));
    }

    #[test]
    fn orders_are_not_reduce_only_unless_asked() {
        let plain = OrderRequest::market(btc_krw(), Side::Buy, Size::Base(Decimal::ONE));
        let reducing = plain.clone().reduce_only();

        assert!(!plain.reduce_only);
        assert!(reducing.reduce_only);
    }

    #[test]
    fn builders_leave_unset_fields_alone() {
        let request = CandleRequest::new(btc_krw(), Interval::Min1).limit(200);

        assert_eq!(request.limit, Some(200));
        assert_eq!(request.from, None);
        assert_eq!(request.to, None);
    }

    #[test]
    fn a_history_page_resumes_from_the_previous_cursor() {
        let first = HistoryRequest::new(btc_krw());
        assert!(first.cursor.is_none());

        let second = HistoryRequest::new(btc_krw()).cursor(Cursor("page-2".to_string()));
        assert_eq!(second.cursor.unwrap().as_str(), "page-2");
    }

    #[test]
    fn a_margin_request_can_set_either_field_independently() {
        let leverage_only = MarginRequest::new(btc_krw()).leverage(Decimal::from(10));
        let mode_only = MarginRequest::new(btc_krw()).margin_mode(MarginMode::Isolated);

        assert_eq!(leverage_only.leverage, Some(Decimal::from(10)));
        assert_eq!(leverage_only.margin_mode, None);
        assert_eq!(mode_only.leverage, None);
        assert_eq!(mode_only.margin_mode, Some(MarginMode::Isolated));
    }

    #[test]
    fn transfer_lookup_requires_one_nonempty_reference() {
        assert_eq!(
            TransferLookupRequest::by_id("btc", "deposit-1")
                .reference()
                .expect("exchange ID"),
            ("uuid", "deposit-1")
        );
        assert_eq!(
            TransferLookupRequest::by_tx_id("btc", "tx-1")
                .reference()
                .expect("transaction ID"),
            ("txid", "tx-1")
        );
        assert!(
            TransferLookupRequest {
                asset: "BTC".to_string(),
                id: Some("deposit-1".to_string()),
                tx_id: Some("tx-1".to_string()),
            }
            .reference()
            .is_err()
        );
        assert!(
            TransferLookupRequest {
                asset: "BTC".to_string(),
                id: None,
                tx_id: None,
            }
            .validate()
            .is_err()
        );
    }
}