nautilus_betfair/http/

parse.rs

// -------------------------------------------------------------------------------------------------
//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
//  https://nautechsystems.io
//
//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
//  You may not use this file except in compliance with the License.
//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
// -------------------------------------------------------------------------------------------------

//! Parsing utilities that convert Betfair HTTP/REST responses into Nautilus domain models.

use nautilus_core::UnixNanos;
use nautilus_model::{
    enums::{LiquiditySide, OrderSide, OrderStatus, OrderType, TimeInForce},
    identifiers::{AccountId, ClientOrderId, TradeId, VenueOrderId},
    reports::{FillReport, OrderStatusReport},
    types::{Currency, Money, Price, Quantity},
};
use rust_decimal::Decimal;

use crate::{
    common::{
        enums::{BetfairOrderStatus, BetfairOrderType, resolve_order_status},
        parse::{
            make_instrument_id, parse_betfair_price, parse_betfair_quantity,
            parse_betfair_timestamp,
        },
    },
    http::models::CurrentOrderSummary,
};

/// Parses a Betfair [`CurrentOrderSummary`] into a Nautilus [`OrderStatusReport`].
///
/// # Errors
///
/// Returns an error if the placed date cannot be parsed.
pub fn parse_current_order_report(
    order: &CurrentOrderSummary,
    account_id: AccountId,
    ts_init: UnixNanos,
) -> anyhow::Result<OrderStatusReport> {
    let instrument_id = make_instrument_id(&order.market_id, order.selection_id, order.handicap);

    let order_side = OrderSide::from(order.side);
    let order_type = OrderType::from(order.order_type);

    // The venue can report a non-BSP persistence type on SP bets; the
    // on-close instruction defines the time in force
    let time_in_force = if uses_liability_based_quantity(order) {
        TimeInForce::AtTheClose
    } else {
        TimeInForce::from(order.persistence_type)
    };

    let size_matched = order.size_matched.unwrap_or(Decimal::ZERO);
    let size_remaining = order.size_remaining.unwrap_or(Decimal::ZERO);
    let size_cancelled = order.size_cancelled.unwrap_or(Decimal::ZERO);
    let size_lapsed = order.size_lapsed.unwrap_or(Decimal::ZERO);
    let size_voided = order.size_voided.unwrap_or(Decimal::ZERO);

    // Include lapsed/voided in the closed quantity for status resolution
    let size_closed = size_cancelled + size_lapsed + size_voided;
    let order_status = if order.status == BetfairOrderStatus::ExecutionComplete
        && size_voided > Decimal::ZERO
        && size_cancelled.is_zero()
        && size_lapsed.is_zero()
    {
        OrderStatus::Voided
    } else if is_resting_sp_bet(order) {
        OrderStatus::Accepted
    } else {
        resolve_order_status(order.status, size_matched, size_closed)
    };

    // Prefer lifecycle sum when price_size.size is zero. Use bsp_liability for
    // on-close orders that report liability without stake/size.
    let total_size = order.price_size.size;
    let lifecycle_qty = size_matched + size_remaining + size_cancelled + size_lapsed + size_voided;
    let qty = if total_size > Decimal::ZERO {
        total_size
    } else if lifecycle_qty > Decimal::ZERO {
        lifecycle_qty
    } else if uses_liability_based_quantity(order) && order.bsp_liability > Decimal::ZERO {
        order.bsp_liability
    } else {
        Decimal::ZERO
    };
    anyhow::ensure!(
        qty > Decimal::ZERO,
        "failed to resolve positive quantity for current order {} \
         (order_type={:?}, persistence_type={:?}, price_size={}, bsp_liability={}, \
         size_matched={}, size_remaining={}, size_cancelled={}, size_lapsed={}, size_voided={})",
        order.bet_id,
        order.order_type,
        order.persistence_type,
        order.price_size.size,
        order.bsp_liability,
        size_matched,
        size_remaining,
        size_cancelled,
        size_lapsed,
        size_voided,
    );
    let quantity = parse_betfair_quantity(qty)?;
    let filled_qty = parse_betfair_quantity(size_matched)?;

    let ts_accepted = parse_betfair_timestamp(&order.placed_date)?;
    let ts_last = order
        .matched_date
        .as_deref()
        .and_then(|d| parse_betfair_timestamp(d).ok())
        .unwrap_or(ts_accepted);

    let venue_order_id = VenueOrderId::from(order.bet_id.as_str());
    let client_order_id = order
        .customer_order_ref
        .as_deref()
        .filter(|s| !s.is_empty())
        .map(ClientOrderId::from);

    let price = parse_betfair_price(order.price_size.price)?;

    let mut report = OrderStatusReport::new(
        account_id,
        instrument_id,
        client_order_id,
        venue_order_id,
        order_side.into(),
        order_type,
        time_in_force,
        order_status,
        quantity,
        filled_qty,
        ts_accepted,
        ts_last,
        ts_init,
        None,
    )
    .with_price(price);

    report.avg_px = order.average_price_matched;

    Ok(report)
}

fn uses_liability_based_quantity(order: &CurrentOrderSummary) -> bool {
    matches!(
        order.order_type,
        BetfairOrderType::LimitOnClose
            | BetfairOrderType::MarketOnClose
            | BetfairOrderType::MarketAtTheClose
    )
}

// An SP bet rests as execution-complete with no matched, cancelled, lapsed,
// or voided quantity, and cannot be cancelled until BSP reconciliation.
fn is_resting_sp_bet(order: &CurrentOrderSummary) -> bool {
    order.status == BetfairOrderStatus::ExecutionComplete
        && uses_liability_based_quantity(order)
        && order.size_matched.unwrap_or(Decimal::ZERO) <= Decimal::ZERO
        && order.size_cancelled.unwrap_or(Decimal::ZERO) <= Decimal::ZERO
        && order.size_lapsed.unwrap_or(Decimal::ZERO) <= Decimal::ZERO
        && order.size_voided.unwrap_or(Decimal::ZERO) <= Decimal::ZERO
}

/// Parses a Betfair [`CurrentOrderSummary`] into a Nautilus [`FillReport`].
///
/// The caller supplies an incremental quantity and price derived from the
/// cumulative order state.
///
/// # Errors
///
/// Returns an error if the order timestamps cannot be parsed.
pub fn parse_current_order_fill_report(
    order: &CurrentOrderSummary,
    account_id: AccountId,
    currency: Currency,
    trade_id: TradeId,
    last_qty: Quantity,
    last_px: Price,
    ts_init: UnixNanos,
) -> anyhow::Result<FillReport> {
    let instrument_id = make_instrument_id(&order.market_id, order.selection_id, order.handicap);
    let venue_order_id = VenueOrderId::from(order.bet_id.as_str());
    let client_order_id = order
        .customer_order_ref
        .as_deref()
        .filter(|s| !s.is_empty())
        .map(ClientOrderId::from);
    let order_side = OrderSide::from(order.side);

    let ts_event = order
        .matched_date
        .as_deref()
        .and_then(|d| parse_betfair_timestamp(d).ok())
        .unwrap_or(parse_betfair_timestamp(&order.placed_date)?);

    Ok(FillReport::new(
        account_id,
        instrument_id,
        venue_order_id,
        trade_id,
        order_side,
        last_qty,
        last_px,
        Money::zero(currency),
        LiquiditySide::NoLiquiditySide,
        client_order_id,
        None,
        ts_event,
        ts_init,
        None,
    ))
}

#[cfg(test)]
mod tests {
    use nautilus_model::{
        enums::{OrderSide, OrderStatus},
        types::{Price, Quantity},
    };
    use rstest::rstest;

    use super::*;
    use crate::{
        common::testing::{load_test_json, parse_jsonrpc},
        http::models::CurrentOrderSummaryReport,
    };

    #[rstest]
    fn test_parse_current_order_single() {
        let data = load_test_json("rest/list_current_orders_single.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);
        let order = &resp.current_orders[0];

        let report =
            parse_current_order_report(order, AccountId::from("BETFAIR-001"), UnixNanos::default())
                .unwrap();

        assert_eq!(
            report.venue_order_id,
            VenueOrderId::from(order.bet_id.as_str())
        );
        assert_eq!(report.order_side, Some(OrderSide::from(order.side)),);
        assert!(report.price.is_some());
    }

    #[rstest]
    fn test_parse_current_order_executable() {
        let data = load_test_json("rest/list_current_orders_executable.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);

        for order in &resp.current_orders {
            let report = parse_current_order_report(
                order,
                AccountId::from("BETFAIR-001"),
                UnixNanos::default(),
            )
            .unwrap();

            // Executable orders are either Accepted or PartiallyFilled
            assert!(
                report.order_status == OrderStatus::Accepted
                    || report.order_status == OrderStatus::PartiallyFilled,
                "unexpected status: {:?}",
                report.order_status,
            );
        }
    }

    #[rstest]
    fn test_parse_current_order_execution_complete() {
        let data = load_test_json("rest/list_current_orders_execution_complete.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);

        // Fixture contains a mix of Executable and ExecutionComplete orders
        let mut has_filled = false;

        for order in &resp.current_orders {
            let report = parse_current_order_report(
                order,
                AccountId::from("BETFAIR-001"),
                UnixNanos::default(),
            )
            .unwrap();

            assert!(
                matches!(
                    report.order_status,
                    OrderStatus::Filled
                        | OrderStatus::Canceled
                        | OrderStatus::Accepted
                        | OrderStatus::PartiallyFilled,
                ),
                "unexpected status: {:?}",
                report.order_status,
            );

            if report.order_status == OrderStatus::Filled {
                has_filled = true;
            }
        }

        assert!(
            has_filled,
            "fixture should contain at least one filled order"
        );
    }

    #[rstest]
    fn test_parse_current_order_lapsed() {
        let data = load_test_json("rest/list_current_orders_lapsed.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);

        // First order: BACK, fully lapsed, no matches
        let order = &resp.current_orders[0];
        let report =
            parse_current_order_report(order, AccountId::from("BETFAIR-001"), UnixNanos::default())
                .unwrap();

        assert_eq!(report.order_side, Some(OrderSide::Sell));
        assert_eq!(report.order_status, OrderStatus::Canceled);
        assert_eq!(report.filled_qty, Quantity::from("0.00"));
        assert_eq!(report.quantity, Quantity::from("20.00"));
        assert_eq!(report.venue_order_id, VenueOrderId::from("229430281400"));
    }

    #[rstest]
    fn test_parse_current_order_sp_resting() {
        let data = load_test_json("rest/list_current_orders_sp_resting.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);
        let order = &resp.current_orders[0];

        let report =
            parse_current_order_report(order, AccountId::from("BETFAIR-001"), UnixNanos::default())
                .unwrap();

        // A resting SP bet reports execution-complete with zero size fields,
        // but cannot be cancelled and is still open until BSP reconciliation
        assert_eq!(report.order_status, OrderStatus::Accepted);
        // SP identity survives the report despite persistenceType LAPSE
        assert_eq!(report.time_in_force, TimeInForce::AtTheClose);
        assert_eq!(report.quantity, Quantity::from("2.00"));
        assert_eq!(report.filled_qty, Quantity::from("0.00"));
        assert_eq!(report.venue_order_id, VenueOrderId::from("442849719274"));
    }

    #[rstest]
    fn test_parse_current_order_sp_matched() {
        let data = load_test_json("rest/list_current_orders_sp_matched.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);
        let order = &resp.current_orders[0];

        let report =
            parse_current_order_report(order, AccountId::from("BETFAIR-001"), UnixNanos::default())
                .unwrap();

        // Once matched at BSP reconciliation the same bet resolves Filled
        assert_eq!(report.order_status, OrderStatus::Filled);
        assert_eq!(report.time_in_force, TimeInForce::AtTheClose);
        assert_eq!(report.quantity, Quantity::from("2.00"));
        assert_eq!(report.filled_qty, Quantity::from("2.00"));
    }

    #[rstest]
    fn test_parse_current_order_partially_filled_and_voided() {
        let data = load_test_json("rest/list_current_orders_lapsed.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);

        // Second order: LAY, sizeMatched=30, sizeLapsed=10, sizeVoided=10
        let order = &resp.current_orders[1];
        let report =
            parse_current_order_report(order, AccountId::from("BETFAIR-001"), UnixNanos::default())
                .unwrap();

        assert_eq!(report.order_side, Some(OrderSide::Buy));
        assert_eq!(report.order_status, OrderStatus::Canceled);
        assert_eq!(report.filled_qty, Quantity::from("30.00"));
        assert_eq!(report.quantity, Quantity::from("50.00"));
        assert_eq!(report.avg_px, Some(Decimal::new(24, 1)));
    }

    #[rstest]
    fn test_parse_current_order_pure_void_is_terminal_voided() {
        let data = load_test_json("rest/list_current_orders_lapsed.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);
        let mut order = resp.current_orders[1].clone();
        order.size_lapsed = Some(Decimal::ZERO);
        order.size_cancelled = Some(Decimal::ZERO);

        let report = parse_current_order_report(
            &order,
            AccountId::from("BETFAIR-001"),
            UnixNanos::default(),
        )
        .unwrap();

        assert_eq!(report.order_status, OrderStatus::Voided);
        assert_eq!(report.filled_qty, Quantity::from("30.00"));
        assert_eq!(report.quantity, Quantity::from("50.00"));
    }

    #[rstest]
    fn test_parse_current_order_working_after_partial_void_is_not_terminal() {
        let data = load_test_json("rest/list_current_orders_lapsed.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);
        let mut order = resp.current_orders[1].clone();
        order.status = BetfairOrderStatus::Executable;
        order.size_matched = Some(Decimal::new(20, 0));
        order.size_remaining = Some(Decimal::new(20, 0));
        order.size_lapsed = Some(Decimal::ZERO);
        order.size_cancelled = Some(Decimal::ZERO);
        order.size_voided = Some(Decimal::new(10, 0));

        let report = parse_current_order_report(
            &order,
            AccountId::from("BETFAIR-001"),
            UnixNanos::default(),
        )
        .unwrap();

        assert_eq!(report.order_status, OrderStatus::PartiallyFilled);
        assert_eq!(report.filled_qty, Quantity::from("20.00"));
        assert_eq!(report.quantity, Quantity::from("50.00"));
    }

    #[rstest]
    fn test_parse_current_order_market_on_close_uses_bsp_liability() {
        let data = r#"{
          "jsonrpc": "2.0",
          "id": 1,
          "result": {
            "currentOrders": [
              {
                "betId": "424009603606",
                "marketId": "1.256134154",
                "selectionId": 86018523,
                "handicap": 0.0,
                "priceSize": {
                  "price": 1.01,
                  "size": 0.0
                },
                "bspLiability": 2.0,
                "side": "BACK",
                "status": "EXECUTABLE",
                "persistenceType": "MARKET_ON_CLOSE",
                "orderType": "MARKET_ON_CLOSE",
                "placedDate": "2026-04-03T00:51:29.000Z",
                "averagePriceMatched": 0.0,
                "sizeMatched": 0.0,
                "sizeRemaining": 0.0,
                "sizeLapsed": 0.0,
                "sizeCancelled": 0.0,
                "sizeVoided": 0.0
              }
            ],
            "moreAvailable": false
          }
        }"#;
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(data);
        let order = &resp.current_orders[0];

        let report =
            parse_current_order_report(order, AccountId::from("BETFAIR-001"), UnixNanos::default())
                .unwrap();

        assert_eq!(report.order_type, OrderType::Market);
        assert_eq!(report.time_in_force, TimeInForce::AtTheClose);
        assert_eq!(report.quantity, Quantity::from("2.00"));
    }

    #[rstest]
    fn test_parse_current_order_zero_quantity_sources_fails() {
        let data = r#"{
          "jsonrpc": "2.0",
          "id": 1,
          "result": {
            "currentOrders": [
              {
                "betId": "424009603607",
                "marketId": "1.256134154",
                "selectionId": 86018523,
                "handicap": 0.0,
                "priceSize": {
                  "price": 1.01,
                  "size": 0.0
                },
                "bspLiability": 0.0,
                "side": "BACK",
                "status": "EXECUTABLE",
                "persistenceType": "LAPSE",
                "orderType": "LIMIT",
                "placedDate": "2026-04-03T00:51:29.000Z",
                "averagePriceMatched": 0.0,
                "sizeMatched": 0.0,
                "sizeRemaining": 0.0,
                "sizeLapsed": 0.0,
                "sizeCancelled": 0.0,
                "sizeVoided": 0.0
              }
            ],
            "moreAvailable": false
          }
        }"#;
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(data);
        let order = &resp.current_orders[0];

        let result =
            parse_current_order_report(order, AccountId::from("BETFAIR-001"), UnixNanos::default());

        assert!(result.is_err());
        assert!(
            result
                .unwrap_err()
                .to_string()
                .contains("failed to resolve positive quantity for current order 424009603607")
        );
    }

    #[rstest]
    fn test_parse_current_order_customer_order_ref() {
        let data = load_test_json("rest/list_current_orders_lapsed.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);

        // First order has customerOrderRef, second does not
        let report1 = parse_current_order_report(
            &resp.current_orders[0],
            AccountId::from("BETFAIR-001"),
            UnixNanos::default(),
        )
        .unwrap();
        let report2 = parse_current_order_report(
            &resp.current_orders[1],
            AccountId::from("BETFAIR-001"),
            UnixNanos::default(),
        )
        .unwrap();

        assert_eq!(
            report1.client_order_id,
            Some(ClientOrderId::from("O-20210730-001"))
        );
        assert!(report2.client_order_id.is_none());
    }

    #[rstest]
    fn test_parse_fill_report_matched_order() {
        let data = load_test_json("rest/list_current_orders_execution_complete.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);

        // Second order: BACK, fully matched, sizeMatched=10, avgPx=1.9
        let order = &resp.current_orders[1];
        let currency = Currency::from("GBP");
        let report = parse_cumulative_fill_fixture(order, currency).unwrap();

        assert_eq!(report.venue_order_id, VenueOrderId::from("228059821049"));
        assert_eq!(report.order_side, OrderSide::Sell);
        assert_eq!(report.last_qty, Quantity::from("10.00"));
        assert_eq!(report.last_px, Price::from("1.90"));
        assert_eq!(report.trade_id, TradeId::new("228059821049-10.00"));
        assert_eq!(report.commission, Money::zero(currency));
        assert_eq!(report.liquidity_side, LiquiditySide::NoLiquiditySide);
    }

    #[rstest]
    fn test_parse_fill_report_unmatched_order_skips() {
        let data = load_test_json("rest/list_current_orders_execution_complete.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);

        // First order: sizeMatched=0, should still parse but with zero qty
        let order = &resp.current_orders[0];
        let report = parse_cumulative_fill_fixture(order, Currency::from("GBP")).unwrap();

        assert_eq!(report.last_qty, Quantity::from("0.00"));
    }

    #[rstest]
    fn test_parse_fill_report_lay_side() {
        let data = load_test_json("rest/list_current_orders_execution_complete.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);

        // Third order: LAY side
        let order = &resp.current_orders[2];
        let report = parse_cumulative_fill_fixture(order, Currency::from("GBP")).unwrap();

        assert_eq!(report.order_side, OrderSide::Buy);
        assert_eq!(report.last_qty, Quantity::from("10.00"));
        assert_eq!(report.last_px, Price::from("1.92"));
    }

    #[rstest]
    fn test_parse_fill_report_partially_matched() {
        let data = load_test_json("rest/list_current_orders_lapsed.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);

        // Second order: sizeMatched=30, avgPx=2.4
        let order = &resp.current_orders[1];
        let report = parse_cumulative_fill_fixture(order, Currency::from("GBP")).unwrap();

        assert_eq!(report.last_qty, Quantity::from("30.00"));
        assert_eq!(report.last_px, Price::from("2.40"));
        assert_eq!(report.trade_id, TradeId::new("229430281401-30.00"));
    }

    #[rstest]
    fn test_parse_fill_report_customer_order_ref() {
        let data = load_test_json("rest/list_current_orders_lapsed.json");
        let resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);

        // First order has customerOrderRef
        let order = &resp.current_orders[0];
        let report = parse_cumulative_fill_fixture(order, Currency::from("GBP")).unwrap();

        assert_eq!(
            report.client_order_id,
            Some(ClientOrderId::from("O-20210730-001"))
        );

        // Second order has no customerOrderRef
        let order2 = &resp.current_orders[1];
        let report2 = parse_cumulative_fill_fixture(order2, Currency::from("GBP")).unwrap();

        assert!(report2.client_order_id.is_none());
    }

    #[rstest]
    fn test_parse_current_order_blank_customer_order_ref_normalizes_to_none() {
        let data = load_test_json("rest/list_current_orders_lapsed.json");
        let mut resp: CurrentOrderSummaryReport = parse_jsonrpc(&data);

        // Some venues serialize a blank string instead of omitting the field.
        // ClientOrderId rejects empty strings, so the parser must treat blank
        // refs as missing rather than panicking.
        resp.current_orders[0].customer_order_ref = Some(String::new());

        let report = parse_current_order_report(
            &resp.current_orders[0],
            AccountId::from("BETFAIR-001"),
            UnixNanos::default(),
        )
        .unwrap();
        assert!(report.client_order_id.is_none());
        assert_eq!(report.venue_order_id, VenueOrderId::from("229430281400"));
        assert_eq!(report.order_side, Some(OrderSide::Sell));
        assert_eq!(report.quantity, Quantity::from("20.00"));
        assert_eq!(report.price.unwrap(), Price::from("6.00"));

        let fill =
            parse_cumulative_fill_fixture(&resp.current_orders[0], Currency::from("GBP")).unwrap();
        assert!(fill.client_order_id.is_none());
        assert_eq!(fill.venue_order_id, VenueOrderId::from("229430281400"));
        assert_eq!(fill.order_side, OrderSide::Sell);
        assert_eq!(fill.last_qty, Quantity::from("0.00"));
        // Lapsed order has averagePriceMatched=0.0, so the fill report uses 0.00.
        assert_eq!(fill.last_px, Price::from("0.00"));
    }

    fn parse_cumulative_fill_fixture(
        order: &CurrentOrderSummary,
        currency: Currency,
    ) -> anyhow::Result<FillReport> {
        let size_matched = order.size_matched.unwrap_or(Decimal::ZERO);
        let last_qty = parse_betfair_quantity(size_matched)?;
        let last_px = parse_betfair_price(
            order
                .average_price_matched
                .unwrap_or(order.price_size.price),
        )?;
        let trade_id = TradeId::new(format!("{}-{}", order.bet_id, last_qty.as_decimal(),));

        parse_current_order_fill_report(
            order,
            AccountId::from("BETFAIR-001"),
            currency,
            trade_id,
            last_qty,
            last_px,
            UnixNanos::default(),
        )
    }
}