ibapi 5.2.0

//! # Order Management
//!
//! This module provides comprehensive order management capabilities including
//! order creation, modification, cancellation, and execution tracking.
//! It supports various order types and advanced trading features.
//!
//! ## Features
//!
//! - **Order Placement**: Submit market, limit, stop, and other order types
//! - **Order Modification**: Modify existing orders with new parameters
//! - **Order Cancellation**: Cancel individual orders or all open orders
//! - **Execution Tracking**: Monitor order fills and execution details
//! - **Commission Reports**: Track commission charges for executed trades
//! - **Order Status Updates**: Real-time updates on order state changes
//!
//! ## Order Types
//!
//! The module supports various order types including:
//! - Market orders
//! - Limit orders
//! - Stop orders
//! - Stop-limit orders
//! - Trailing stop orders
//! - VWAP/TWAP algorithmic orders
//! - And many more specialized order types
//!
//! ## Usage
//!
//! Orders are created using the `Order` struct and can be customized with various
//! parameters. [`OrderBuilder`](crate::orders::OrderBuilder), reached through `Client::order`, provides a fluent API
//! for constructing complex orders; the `order_builder` module holds free functions
//! that return preset `Order` values.

// Common implementation modules
pub(crate) mod common;

/// Fluent builder APIs for constructing orders.
pub mod builder;

/// Order condition types for conditional orders.
pub mod conditions;
mod exercise_options_builder;

/// Convenience re-export for low-level order builder helpers.
pub use common::order_builder;

// Builder types: `order_builder` and `types` are `pub(crate)` so `orders::*`
// is the only public spelling.
pub use crate::client::ids::OrderId;
pub use builder::order_builder::{AttachedOrdersBuilder, BracketOrderBuilder, ClientBound, Detached, OrderBuilder};
pub use builder::types::{AttachedOrderIds, BracketOrderIds};
pub use exercise_options_builder::ExerciseOptionsBuilder;

// Re-export condition types and builders
pub use conditions::{
    ExecutionCondition, ExecutionConditionBuilder, MarginCondition, MarginConditionBuilder, PercentChangeCondition, PercentChangeConditionBuilder,
    PriceCondition, PriceConditionBuilder, TimeCondition, TimeConditionBuilder, UnknownCondition, VolumeCondition, VolumeConditionBuilder,
};

use std::convert::From;
use std::fmt::Debug;

use serde::{Deserialize, Serialize};

use crate::contracts::Contract;

// Public types - always available regardless of feature flags

use crate::contracts::TagValue;

pub(crate) const COMPETE_AGAINST_BEST_OFFSET_UP_TO_MID: Option<f64> = Some(f64::INFINITY);

#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
/// Order describes the order.
pub struct Order {
    /// The API client's order id.
    pub order_id: i32,
    /// The Solicited field should be used for orders initiated or recommended by the broker or adviser that were approved by the client (by phone, email, chat, verbally, etc.) prior to entry. Please note that orders that the adviser or broker placed without specifically discussing with the client are discretionary orders, not solicited.
    pub solicited: bool,
    /// The API client id which placed the order.
    pub client_id: i32,
    /// The Host order identifier.
    pub perm_id: i64,
    /// Identifies the side.
    /// Generally available values are BUY and SELL.
    /// Additionally, SSHORT and SLONG are available in some institutional-accounts only.
    /// For general account types, a SELL order will be able to enter a short position automatically if the order quantity is larger than your current long position.
    /// SSHORT is only supported for institutional account configured with Long/Short account segments or clearing with a separate account.
    /// SLONG is available in specially-configured institutional accounts to indicate that long position not yet delivered is being sold.
    pub action: Action,
    /// The number of positions being bought/sold.
    pub total_quantity: f64,
    /// The order's type.
    pub order_type: String,
    /// The LIMIT price.
    /// Used for limit, stop-limit and relative orders. In all other cases specify zero. For relative orders with no limit price, also specify zero.
    pub limit_price: Option<f64>,
    /// Generic field to contain the stop price for STP LMT orders, trailing amount, etc.
    pub aux_price: Option<f64>,
    /// The time in force - specifies how long the order remains active.
    ///
    /// See [`TimeInForce`] for available options and their behavior.
    pub tif: TimeInForce,
    /// One-Cancels-All group identifier.
    pub oca_group: String,
    /// Tells how to handle remaining orders in an OCA group when one order or part of an order executes.
    ///
    /// See [`OcaType`] for available options. "With block" provides overfill protection by ensuring
    /// only one order in the group is routed at a time.
    pub oca_type: OcaType,
    /// The order reference.
    /// Intended for institutional customers only, although all customers may use it to identify the API client that sent the order when multiple API clients are running.
    pub order_ref: String,
    /// Specifies whether the order will be transmitted by TWS. If set to false, the order will be created at TWS but will not be sent.
    pub transmit: bool,
    /// If set to true, the order is de-activated (inactive). Since TWS 10.48, `reqOpenOrders`
    /// returns de-activated orders; this flag distinguishes them from active orders.
    ///
    /// Requires TWS/Gateway server version 216 (`ADDITIONAL_ORDER_PARAMS_1`) or later.
    pub deactivate: bool,
    /// The order ID of the parent order, used for bracket and auto trailing stop orders.
    pub parent_id: i32,
    /// Order ID for a stop-loss that TWS attaches to this order from its order presets.
    ///
    /// `Some(id)` asks TWS to create the child under `id`, pricing it from the stop-loss preset
    /// configured in TWS (Global Configuration → Presets) for the instrument; the API sends no
    /// price. Allocate the id with [`next_order_id`](crate::Client::next_order_id). Requires
    /// server version 218.
    ///
    /// If no preset is defined, TWS discards this order as well (error 10355, then status
    /// `Cancelled`). Request-only: always `None` on orders read back from TWS.
    ///
    /// The builder path is [`OrderBuilder::preset_stop_loss`], which allocates the id.
    /// Set the field directly to get a subscription from `place_order`:
    ///
    /// ```no_run
    /// # #[cfg(feature = "async")]
    /// # async fn run(client: &ibapi::Client) -> Result<(), ibapi::Error> {
    /// use ibapi::contracts::Contract;
    ///
    /// let contract = Contract::stock("AAPL").build();
    /// let mut order = client.order(&contract).buy(100).limit(150.0).build_order()?;
    /// let order_id = client.next_order_id();
    /// order.preset_stop_loss_order_id = Some(client.next_order_id());
    /// order.preset_profit_taker_order_id = Some(client.next_order_id());
    /// let _updates = client.place_order(order_id, &contract, &order).await?;
    /// # Ok(())
    /// # }
    /// ```
    pub preset_stop_loss_order_id: Option<i32>,
    /// Order ID for a profit-taker that TWS attaches to this order from its order presets.
    ///
    /// Same contract as [`preset_stop_loss_order_id`](Self::preset_stop_loss_order_id), using
    /// the profit-taker preset.
    pub preset_profit_taker_order_id: Option<i32>,
    /// If set to true, specifies that the order is an ISE Block order.
    pub block_order: bool,
    /// If set to true, specifies that the order is a Sweep-to-Fill order.
    pub sweep_to_fill: bool,
    /// The publicly disclosed order size, used when placing Iceberg orders.
    pub display_size: Option<i32>,
    /// Specifies how Simulated Stop, Stop-Limit and Trailing Stop orders are triggered.
    ///
    /// See [`conditions::TriggerMethod`] for available options.
    pub trigger_method: conditions::TriggerMethod,
    /// If set to true, allows orders to also trigger or fill outside of regular trading hours.
    pub outside_rth: bool,
    /// If set to true, the order will not be visible when viewing the market depth. This option only applies to orders routed to the NASDAQ exchange.
    pub hidden: bool,
    /// Specifies the date and time after which the order will be active.
    /// Format: yyyymmdd hh:mm:ss {optional Timezone}.
    pub good_after_time: String,
    /// The date and time until the order will be active.
    /// You must enter GTD as the time in force to use this string. The trade's "Good Till Date," format "yyyyMMdd HH:mm:ss (optional time zone)" or UTC "yyyyMMdd-HH:mm:ss".
    pub good_till_date: String,
    /// Overrides TWS constraints.
    /// Precautionary constraints are defined on the TWS Presets page, and help ensure that your price and size order values are reasonable. Orders sent from the API are also validated against these safety constraints, and may be rejected if any constraint is violated. To override validation, set this parameter's value to True.
    pub override_percentage_constraints: bool,
    /// NYSE Rule 80A designation values:
    /// - Individual = `I`
    /// - Agency = `A`
    /// - AgentOtherMember = `W`
    /// - IndividualPTIA = `J`
    /// - AgencyPTIA = `U`
    /// - AgentOtherMemberPTIA = `M`
    /// - IndividualPT = `K`
    /// - AgencyPT = `Y`
    /// - AgentOtherMemberPT = `N`
    pub rule_80_a: Option<Rule80A>,
    /// Indicates whether or not all the order has to be filled on a single execution.
    pub all_or_none: bool,
    /// Identifies a minimum quantity order type.
    pub min_qty: Option<i32>,
    /// The percent offset amount for relative orders.
    pub percent_offset: Option<f64>,
    /// Trail stop price for TRAIL LIMIT orders.
    pub trail_stop_price: Option<f64>,
    /// Specifies the trailing amount of a trailing stop order as a percentage.
    ///
    /// Observe the following guidelines when using the trailingPercent field:
    /// - This field is mutually exclusive with the existing trailing amount. That is, the API client can send one
    ///   or the other but not both.
    /// - This field is read AFTER the stop price (barrier price) as follows: deltaNeutralAuxPrice stopPrice,
    ///   trailingPercent, scale order attributes.
    /// - The field will also be sent to the API in the openOrder message if the API client version is >= 56.
    ///   It is sent after the stopPrice field as follows: stopPrice, trailingPct, basisPoint.    
    pub trailing_percent: Option<f64>,
    /// The Financial Advisor group the trade will be allocated to. Use an empty string if not applicable.
    pub fa_group: String,
    /// The Financial Advisor allocation profile the trade will be allocated to. Use an empty string if not applicable.
    pub fa_profile: String,
    /// The Financial Advisor allocation method the trade will be allocated to. Use an empty string if not applicable.
    pub fa_method: String,
    /// The Financial Advisor percentage concerning the trade's allocation. Use an empty string if not applicable.
    pub fa_percentage: String,
    /// For institutional customers only. Valid values are O (open) and C (close).
    ///
    /// Available for institutional clients to determine if this order is to open or close a position.
    /// - When Action = "BUY" and OpenClose = "O" this will open a new position.
    /// - When Action = "BUY" and OpenClose = "C" this will close an existing short position.
    pub open_close: Option<OrderOpenClose>,
    /// The order's origin. Same as TWS "Origin" column. Identifies the type of customer from which the order originated.
    ///
    /// See [`OrderOrigin`] for available options.
    pub origin: OrderOrigin,
    /// For institutions only. Specifies the short sale slot.
    ///
    /// See [`ShortSaleSlot`] for available options.
    pub short_sale_slot: ShortSaleSlot,
    /// For institutions only. Indicates the location where the shares to short come from.
    /// Used only when short sale slot is set to `ThirdParty`.
    pub designated_location: String,
    /// Only available with IB Execution-Only accounts with applicable securities.
    /// Mark order as exempt from short sale uptick rule.
    pub exempt_code: i32,
    /// The amount off the limit price allowed for discretionary orders.
    pub discretionary_amt: f64,
    /// Use to opt out of default SmartRouting for orders routed directly to ASX.
    /// This attribute defaults to false unless explicitly set to true.
    /// When set to false, orders routed directly to ASX will NOT use SmartRouting.
    /// When set to true, orders routed directly to ASX orders WILL use SmartRouting.
    pub opt_out_smart_routing: bool,
    /// The auction's starting price. For BOX orders only.
    pub starting_price: Option<f64>,
    /// The stock's reference price.
    /// The reference price is used for VOL orders to compute the limit price sent to an exchange (whether or not Continuous Update is selected), and for price range monitoring.    
    pub stock_ref_price: Option<f64>,
    /// The stock's Delta. For orders on BOX only.
    pub delta: Option<f64>,
    /// The lower value for the acceptable underlying stock price range.
    /// For price improvement option orders on BOX and VOL orders with dynamic management.    
    pub stock_range_lower: Option<f64>,
    /// The upper value for the acceptable underlying stock price range.
    /// For price improvement option orders on BOX and VOL orders with dynamic management.
    pub stock_range_upper: Option<f64>,
    /// The option price in volatility, as calculated by TWS' Option Analytics.
    /// This value is expressed as a percent and is used to calculate the limit price sent to the exchange.
    pub volatility: Option<f64>,
    /// VOL orders only. See [`VolatilityType`] for available options.
    pub volatility_type: Option<VolatilityType>,
    /// Specifies whether TWS will automatically update the limit price of the order as the underlying price moves. VOL orders only.
    pub continuous_update: bool,
    /// Specifies how you want TWS to calculate the limit price for options, and for stock range price monitoring.
    /// VOL orders only.
    ///
    /// See [`ReferencePriceType`] for available options.
    pub reference_price_type: Option<ReferencePriceType>,
    /// Enter an order type to instruct TWS to submit a delta neutral trade on full or partial execution of the VOL order. VOL orders only. For no hedge delta order to be sent, specify NONE.
    pub delta_neutral_order_type: String,
    /// Use this field to enter a value if the value in the deltaNeutralOrderType field is an order type that requires an Aux price, such as a REL order. VOL orders only.
    pub delta_neutral_aux_price: Option<f64>,
    /// The unique contract identifier specifying the security in Delta Neutral order.
    pub delta_neutral_con_id: i32,
    /// Indicates the firm which will settle the Delta Neutral trade. Institutions only.
    pub delta_neutral_settling_firm: String,
    /// Specifies the beneficiary of the Delta Neutral order.
    pub delta_neutral_clearing_account: String,
    /// Specifies where the clients want their shares to be cleared at. Must be specified by execution-only clients.
    ///
    /// Valid values are:
    /// - `IB`
    /// - `Away`
    /// - `PTA` (post trade allocation)
    pub delta_neutral_clearing_intent: String,
    /// Specifies whether the order is an Open or a Close order and is used when the hedge involves a CFD and and the order is clearing away.
    pub delta_neutral_open_close: String,
    /// Used when the hedge involves a stock and indicates whether or not it is sold short.
    pub delta_neutral_short_sale: bool,
    /// Indicates a short sale Delta Neutral order. Has a value of 1 (the clearing broker holds shares) or 2 (delivered from a third party). If you use 2, then you must specify a deltaNeutralDesignatedLocation.
    pub delta_neutral_short_sale_slot: i32,
    /// Identifies third party order origin. Used only when deltaNeutralShortSaleSlot = 2.
    pub delta_neutral_designated_location: String,
    /// Specifies Basis Points for EFP order. The values increment in 0.01% = 1 basis point. For EFP orders only.
    pub basis_points: Option<f64>,
    /// Specifies the increment of the Basis Points. For EFP orders only.
    pub basis_points_type: Option<i32>,
    /// Defines the size of the first, or initial, order component. For Scale orders only.
    pub scale_init_level_size: Option<i32>,
    /// Defines the order size of the subsequent scale order components. For Scale orders only. Used in conjunction with scaleInitLevelSize().
    pub scale_subs_level_size: Option<i32>,
    /// Defines the price increment between scale components. For Scale orders only. This value is compulsory.
    pub scale_price_increment: Option<f64>,
    /// Modifies the value of the Scale order. For extended Scale orders.
    pub scale_price_adjust_value: Option<f64>,
    /// Specifies the interval when the price is adjusted. For extended Scale orders.
    pub scale_price_adjust_interval: Option<i32>,
    /// Specifies the offset when to adjust profit. For extended scale orders.
    pub scale_profit_offset: Option<f64>,
    /// Restarts the Scale series if the order is cancelled. For extended scale orders.
    pub scale_auto_reset: bool,
    /// The initial position of the Scale order. For extended scale orders.
    pub scale_init_position: Option<i32>,
    /// Specifies the initial quantity to be filled. For extended scale orders.
    pub scale_init_fill_qty: Option<i32>,
    /// Defines the random percent by which to adjust the position. For extended scale orders.
    pub scale_random_percent: bool,
    /// For hedge orders.
    ///
    /// Possible values include:
    /// - `D` - Delta
    /// - `B` - Beta
    /// - `F` - FX
    /// - `P` - Pair
    pub hedge_type: String,
    /// For hedge orders.
    /// Beta = x for Beta hedge orders, ratio = y for Pair hedge order
    pub hedge_param: String,
    /// For hedge orders. The maximum size of the hedge order.
    ///
    /// Requires TWS/Gateway server version 223 (`HEDGE_MAX_SIZE`) or later.
    pub hedge_max_size: Option<i32>,
    /// The account the trade will be allocated to.
    pub account: String,
    /// Indicates the firm which will settle the trade. Institutions only.
    pub settling_firm: String,
    /// Specifies the true beneficiary of the order.
    /// For IBExecution customers. This value is required for FUT/FOP orders for reporting to the exchange.
    pub clearing_account: String,
    /// For execution-only clients to know where do they want their shares to be cleared at.
    ///
    /// Valid values are:
    /// - `IB`
    /// - `Away`
    /// - `PTA` (post trade allocation)
    pub clearing_intent: String,
    /// The algorithm strategy.
    ///
    /// As of API version 9.6, the following algorithms are supported:
    /// - `ArrivalPx` - Arrival Price
    /// - `DarkIce` - Dark Ice
    /// - `PctVol` - Percentage of Volume
    /// - `Twap` - TWAP (Time Weighted Average Price)
    /// - `Vwap` - VWAP (Volume Weighted Average Price)
    ///
    /// For more information about IB's API algorithms, refer to [https://www.interactivebrokers.com/en/software/api/apiguide/tables/ibalgo_parameters.htm](https://www.interactivebrokers.com/en/software/api/apiguide/tables/ibalgo_parameters.htm)
    pub algo_strategy: String,
    /// The list of parameters for the IB algorithm.
    /// For more information about IB's API algorithms, refer to [https://www.interactivebrokers.com/en/software/api/apiguide/tables/ibalgo_parameters.htm](https://www.interactivebrokers.com/en/software/api/apiguide/tables/ibalgo_parameters.htm)
    pub algo_params: Vec<TagValue>,
    /// Allows to retrieve the commissions and margin information.
    /// When placing an order with this attribute set to true, the order will not be placed as such. Instead it will used to request the commissions and margin information that would result from this order.
    pub what_if: bool,
    /// Identifies orders generated by algorithmic trading.
    pub algo_id: String,
    /// Orders routed to IBDARK are tagged as "post only" and are held in IB's order book, where incoming SmartRouted orders from other IB customers are eligible to trade against them.
    /// For IBDARK orders only.
    pub not_held: bool,
    /// Advanced parameters for Smart combo routing.
    /// These features are for both guaranteed and non-guaranteed combination orders routed to Smart, and are available based on combo type and order type. SmartComboRoutingParams is similar to AlgoParams in that it makes use of tag/value pairs to add parameters to combo orders.
    /// Make sure that you fully understand how Advanced Combo Routing works in TWS itself first: <https://guides.interactivebrokers.com/tws/twsguide.htm#usersguidebook/specializedorderentry/advanced_combo_routing.htm>
    /// The parameters cover the following capabilities:
    ///
    /// * Non-Guaranteed - Determine if the combo order is Guaranteed or Non-Guaranteed.
    ///   <br/>Tag = NonGuaranteed
    ///   <br/>Value = 0: The order is guaranteed
    ///   <br/>Value = 1: The order is non-guaranteed
    ///
    /// * Select Leg to Fill First - User can specify which leg to be executed first.
    ///   <br/>Tag = LeginPrio
    ///   <br/>Value = -1: No priority is assigned to either combo leg
    ///   <br/>Value = 0: Priority is assigned to the first leg being added to the comboLeg
    ///   <br/>Value = 1: Priority is assigned to the second leg being added to the comboLeg
    ///   <br/>Note: The LeginPrio parameter can only be applied to two-legged combo.
    ///
    /// * Maximum Leg-In Combo Size - Specify the maximum allowed leg-in size per segment
    ///   <br/>Tag = MaxSegSize
    ///   <br/>Value = Unit of combo size
    ///
    /// * Do Not Start Next Leg-In if Previous Leg-In Did Not Finish - Specify whether or not the system should attempt to fill the next segment before the current segment fills.
    ///   <br/>Tag = DontLeginNext
    ///   <br/>Value = 0: Start next leg-in even if previous leg-in did not finish
    ///   <br/>Value = 1: Do not start next leg-in if previous leg-in did not finish
    ///
    /// * Price Condition - Combo order will be rejected or cancelled if the leg market price is outside of the specified price range [CondPriceMin, CondPriceMax]
    ///   <br/>Tag = PriceCondConid: The ContractID of the combo leg to specify price condition on
    ///   <br/>Value = The ContractID
    ///   <br/>Tag = CondPriceMin: The lower price range of the price condition
    ///   <br/>Value = The lower price
    ///   <br/>Tag = CondPriceMax: The upper price range of the price condition
    ///   <br/>Value = The upper price    
    pub smart_combo_routing_params: Vec<TagValue>,
    /// List of Per-leg price following the same sequence combo legs are added. The combo price must be left unspecified when using per-leg prices.
    pub order_combo_legs: Vec<OrderComboLeg>,
    /// For internal use only. Use the default value XYZ.
    pub order_misc_options: Vec<TagValue>,
    /// Defines the start time of GTC orders.
    pub active_start_time: String,
    /// Defines the stop time of GTC orders.
    pub active_stop_time: String,
    /// The list of scale orders. Used for scale orders.
    pub scale_table: String,
    /// Is used to place an order to a model. For example, "Technology" model can be used for tech stocks first created in TWS.
    pub model_code: String,
    /// This is a regulatory attribute that applies to all US Commodity (Futures) Exchanges, provided to allow client to comply with CFTC Tag 50 Rules.
    pub ext_operator: String,
    /// The native cash quantity.
    pub cash_qty: Option<f64>,
    /// Identifies a person as the responsible party for investment decisions within the firm. Orders covered by MiFID 2 (Markets in Financial Instruments Directive 2) must include either Mifid2DecisionMaker or Mifid2DecisionAlgo field (but not both). Requires TWS 969+.
    pub mifid2_decision_maker: String,
    /// Identifies the algorithm responsible for investment decisions within the firm. Orders covered under MiFID 2 must include either Mifid2DecisionMaker or Mifid2DecisionAlgo, but cannot have both. Requires TWS 969+.
    pub mifid2_decision_algo: String,
    /// For MiFID 2 reporting; identifies a person as the responsible party for the execution of a transaction within the firm. Requires TWS 969+.
    pub mifid2_execution_trader: String,
    /// For MiFID 2 reporting; identifies the algorithm responsible for the execution of a transaction within the firm. Requires TWS 969+.
    pub mifid2_execution_algo: String,
    /// Don't use auto price for hedge.
    pub dont_use_auto_price_for_hedge: bool,
    /// Specifies the date to auto cancel the order.
    pub auto_cancel_date: String,
    /// Specifies the initial order quantity to be filled.
    pub filled_quantity: f64,
    /// Identifies the reference future conId.
    pub ref_futures_con_id: Option<i32>,
    /// Cancels the parent order if child order was cancelled.
    pub auto_cancel_parent: bool,
    /// Identifies the Shareholder.
    pub shareholder: String,
    /// Used to specify "imbalance only open orders" or "imbalance only closing orders".
    pub imbalance_only: bool,
    /// Routes market order to Best Bid Offer.
    ///
    /// Requires TWS/Gateway server version 217 (`ADDITIONAL_ORDER_PARAMS_2`) or later.
    pub route_marketable_to_bbo: bool,
    /// Parent order Id.
    pub parent_perm_id: Option<i64>,
    /// Accepts a list with parameters obtained from advancedOrderRejectJson.
    pub advanced_error_override: String,
    /// Used by brokers and advisors when manually entering an order request. Format should be “YYYYMMDD-HH:mm:ss” using UTC as the timezone value.
    pub manual_order_time: String,
    /// Defines the minimum trade quantity to fill. For IBKRATS orders.
    pub min_trade_qty: Option<i32>,
    /// Defines the minimum size to compete. For IBKRATS orders.
    pub min_compete_size: Option<i32>,
    /// Specifies the offset off the midpoint that will be applied to the order. For IBKRATS orders.
    /// `f64::INFINITY` means compete up to the midpoint, using `mid_offset_at_whole` / `mid_offset_at_half`.
    pub compete_against_best_offset: Option<f64>,
    /// This offset is applied when the spread is an even number of cents wide. This offset must be in whole-penny increments or zero. For IBKRATS orders.
    pub mid_offset_at_whole: Option<f64>,
    /// This offset is applied when the spread is an odd number of cents wide. This offset must be in half-penny increments. For IBKRATS orders.
    pub mid_offset_at_half: Option<f64>,
    /// Randomizes the order's size. Only for Volatility and Pegged to Volatility orders.
    pub randomize_size: bool,
    /// Randomizes the order's price. Only for Volatility and Pegged to Volatility orders.
    pub randomize_price: bool,
    /// Pegged-to-benchmark orders: this attribute will contain the conId of the contract against which the order will be pegged.
    pub reference_contract_id: i32,
    /// Pegged-to-benchmark orders: indicates whether the order's pegged price should increase or decreases.
    pub is_pegged_change_amount_decrease: bool,
    /// Pegged-to-benchmark orders: amount by which the order's pegged price should move.
    pub pegged_change_amount: Option<f64>,
    /// Pegged-to-benchmark orders: the amount the reference contract needs to move to adjust the pegged order.
    pub reference_change_amount: Option<f64>,
    /// Pegged-to-benchmark orders: the exchange against which we want to observe the reference contract.
    pub reference_exchange: String,
    /// Adjusted Stop orders: the parent order will be adjusted to the given type when the adjusted trigger price is penetrated.
    pub adjusted_order_type: String,
    /// Adjusted Stop orders: specifies the trigger price to execute.
    pub trigger_price: Option<f64>,
    /// Adjusted Stop orders: specifies the price offset for the stop to move in increments.
    pub limit_price_offset: Option<f64>,
    /// Adjusted Stop orders: specifies the stop price of the adjusted (STP) parent.
    pub adjusted_stop_price: Option<f64>,
    /// Adjusted Stop orders: specifies the stop limit price of the adjusted (STPL LMT) parent.
    pub adjusted_stop_limit_price: Option<f64>,
    /// Adjusted Stop orders: specifies the trailing amount of the adjusted (TRAIL) parent.
    pub adjusted_trailing_amount: Option<f64>,
    /// Adjusted Stop orders: specifies where the trailing unit is an amount (set to 0) or a percentage (set to 1)
    pub adjustable_trailing_unit: i32,
    /// Conditions determining when the order will be activated or canceled.
    pub conditions: Vec<OrderCondition>,
    /// Indicates whether or not conditions will also be valid outside Regular Trading Hours.
    pub conditions_ignore_rth: bool,
    /// Conditions can determine if an order should become active or canceled.
    pub conditions_cancel_order: bool,
    /// Indicates whether or not conditions will also be valid during the OVERNIGHT trading session.
    /// Takes effect with [`include_overnight`](Self::include_overnight). Requires server version 226.
    pub conditions_include_overnight: bool,
    /// Define the Soft Dollar Tier used for the order. Only provided for registered professional advisors and hedge and mutual funds.
    pub soft_dollar_tier: SoftDollarTier,
    /// Set to true to create tickets from API orders when TWS is used as an OMS.
    pub is_oms_container: bool,
    /// Set to true to convert order of type 'Primary Peg' to 'D-Peg'.
    pub discretionary_up_to_limit_price: bool,
    /// Specifies wether to use Price Management Algo. CTCI users only.
    pub use_price_mgmt_algo: bool,
    /// Indicates the duration of the order in seconds.
    pub duration: Option<i32>,
    /// Value must be positive, and it is number of seconds that SMART order would be parked for at IBKRATS before being routed to exchange.
    pub post_to_ats: Option<i32>,
    /// Customer account information for completed orders.
    pub customer_account: String,
    /// Indicates if this is a professional customer order.
    pub professional_customer: bool,
    /// Accrued interest for bond orders.
    pub bond_accrued_interest: String,
    /// Include overnight trading.
    pub include_overnight: bool,
    /// Manual order indicator.
    pub manual_order_indicator: Option<i32>,
    /// Identifies the submitter of the order.
    pub submitter: String,
}

impl Default for Order {
    fn default() -> Self {
        Self {
            order_id: 0,
            solicited: false,
            client_id: 0,
            perm_id: 0,
            action: Action::Buy,
            total_quantity: 0.0,
            order_type: "".to_owned(),
            limit_price: None,
            aux_price: None,
            tif: TimeInForce::Day,
            oca_group: "".to_owned(),
            oca_type: OcaType::None,
            order_ref: "".to_owned(),
            transmit: true,
            deactivate: false,
            parent_id: 0,
            preset_stop_loss_order_id: None,
            preset_profit_taker_order_id: None,
            block_order: false,
            sweep_to_fill: false,
            display_size: Some(0),
            trigger_method: conditions::TriggerMethod::Default,
            outside_rth: false,
            hidden: false,
            good_after_time: "".to_owned(),
            good_till_date: "".to_owned(),
            override_percentage_constraints: false,
            rule_80_a: None,
            all_or_none: false,
            min_qty: None,
            percent_offset: None,
            trail_stop_price: None,
            trailing_percent: None,
            fa_group: "".to_owned(),
            fa_profile: "".to_owned(),
            fa_method: "".to_owned(),
            fa_percentage: "".to_owned(),
            open_close: None,
            origin: OrderOrigin::Customer,
            short_sale_slot: ShortSaleSlot::None,
            designated_location: "".to_owned(),
            exempt_code: -1,
            discretionary_amt: 0.0,
            opt_out_smart_routing: false,
            starting_price: None,
            stock_ref_price: None,
            delta: None,
            stock_range_lower: None,
            stock_range_upper: None,
            volatility: None,
            volatility_type: None,
            continuous_update: false,
            reference_price_type: None,
            delta_neutral_order_type: "".to_owned(),
            delta_neutral_aux_price: None,
            delta_neutral_con_id: 0,
            delta_neutral_settling_firm: "".to_owned(),
            delta_neutral_clearing_account: "".to_owned(),
            delta_neutral_clearing_intent: "".to_owned(),
            delta_neutral_open_close: "".to_owned(),
            delta_neutral_short_sale: false,
            delta_neutral_short_sale_slot: 0,
            delta_neutral_designated_location: "".to_owned(),
            basis_points: Some(0.0),
            basis_points_type: Some(0),
            scale_init_level_size: None,
            scale_subs_level_size: None,
            scale_price_increment: None,
            scale_price_adjust_value: None,
            scale_price_adjust_interval: None,
            scale_profit_offset: None,
            scale_auto_reset: false,
            scale_init_position: None,
            scale_init_fill_qty: None,
            scale_random_percent: false,
            hedge_type: "".to_owned(),
            hedge_param: "".to_owned(),
            hedge_max_size: None,
            account: "".to_owned(),
            settling_firm: "".to_owned(),
            clearing_account: "".to_owned(),
            clearing_intent: "".to_owned(),
            algo_strategy: "".to_owned(),
            algo_params: vec![],
            what_if: false,
            algo_id: "".to_owned(),
            not_held: false,
            smart_combo_routing_params: vec![],
            order_combo_legs: vec![],
            order_misc_options: vec![],
            active_start_time: "".to_owned(),
            active_stop_time: "".to_owned(),
            scale_table: "".to_owned(),
            model_code: "".to_owned(),
            ext_operator: "".to_owned(),
            cash_qty: None,
            mifid2_decision_maker: "".to_owned(),
            mifid2_decision_algo: "".to_owned(),
            mifid2_execution_trader: "".to_owned(),
            mifid2_execution_algo: "".to_owned(),
            dont_use_auto_price_for_hedge: false,
            auto_cancel_date: "".to_owned(),
            filled_quantity: 0.0,
            ref_futures_con_id: Some(0),
            auto_cancel_parent: false,
            shareholder: "".to_owned(),
            imbalance_only: false,
            route_marketable_to_bbo: false,
            parent_perm_id: None,
            advanced_error_override: "".to_owned(),
            manual_order_time: "".to_owned(),
            min_trade_qty: None,
            min_compete_size: None,
            compete_against_best_offset: None,
            mid_offset_at_whole: None,
            mid_offset_at_half: None,
            randomize_size: false,
            randomize_price: false,
            reference_contract_id: 0,
            is_pegged_change_amount_decrease: false,
            pegged_change_amount: Some(0.0),
            reference_change_amount: Some(0.0),
            reference_exchange: "".to_owned(),
            adjusted_order_type: "".to_owned(),
            trigger_price: None,
            limit_price_offset: None,
            adjusted_stop_price: None,
            adjusted_stop_limit_price: None,
            adjusted_trailing_amount: None,
            adjustable_trailing_unit: 0,
            conditions: vec![],
            conditions_ignore_rth: false,
            conditions_cancel_order: false,
            conditions_include_overnight: false,
            soft_dollar_tier: SoftDollarTier::default(),
            is_oms_container: false,
            discretionary_up_to_limit_price: false,
            use_price_mgmt_algo: false,
            duration: None,
            post_to_ats: None,
            customer_account: String::new(),
            professional_customer: false,
            bond_accrued_interest: String::new(),
            include_overnight: false,
            manual_order_indicator: None,
            submitter: String::new(),
        }
    }
}

impl Order {
    /// Returns `true` if delta-neutral parameters are configured.
    pub fn is_delta_neutral(&self) -> bool {
        !self.delta_neutral_order_type.is_empty()
    }

    /// Returns `true` if scale order parameters are configured.
    pub fn is_scale_order(&self) -> bool {
        match self.scale_price_increment {
            Some(price_increment) => price_increment > 0.0,
            _ => false,
        }
    }
}

/// Identifies the side.
/// Generally available values are BUY and SELL.
/// Additionally, SSHORT and SLONG are available in some institutional-accounts only.
/// For general account types, a SELL order will be able to enter a short position automatically if the order quantity is larger than your current long position.
/// SSHORT is only supported for institutional account configured with Long/Short account segments or clearing with a separate account.
/// SLONG is available in specially-configured institutional accounts to indicate that long position not yet delivered is being sold.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, Default, PartialEq, Eq, Copy, Serialize, Deserialize)]
pub enum Action {
    #[default]
    /// Buy-side order.
    Buy,
    /// Sell-side order.
    Sell,
    /// SSHORT is only supported for institutional account configured with Long/Short account segments or clearing with a separate account.
    SellShort,
    /// SLONG is available in specially-configured institutional accounts to indicate that long position not yet delivered is being sold.
    SellLong,
}

impl Action {
    /// Return the logical opposite action (buy ↔ sell).
    pub fn reverse(self) -> Action {
        match self {
            Action::Buy => Action::Sell,
            Action::Sell => Action::Buy,
            Action::SellShort => Action::SellLong,
            Action::SellLong => Action::SellShort,
        }
    }

    /// Return the TWS wire string (`"BUY"`, `"SELL"`, `"SSHORT"`, `"SLONG"`).
    pub fn as_str(&self) -> &'static str {
        match self {
            Action::Buy => "BUY",
            Action::Sell => "SELL",
            Action::SellShort => "SSHORT",
            Action::SellLong => "SLONG",
        }
    }

    fn from_wire(s: &str) -> Option<Self> {
        match s {
            "BUY" => Some(Self::Buy),
            "SELL" => Some(Self::Sell),
            "SSHORT" => Some(Self::SellShort),
            "SLONG" => Some(Self::SellLong),
            _ => None,
        }
    }
}

// Closed on purpose: the four sides are fixed by account type, not a
// growing vocabulary, and `Unknown(String)` would cost `Copy` on a type the
// builder and validation paths pass by value. An unrecognized side on an
// inbound order fails that decode with `Error::Parse`.
impl_wire_enum!(Action);

/// The lifecycle state of an order, as reported by TWS.
///
/// See the [IB OrderStatus reference](https://www.interactivebrokers.com/docs/tws-api/doc/order-management/order-status/understanding-order-status-message).
///
/// Default is [`OrderStatusKind::Submitted`] to match the [`Action`] enum's
/// pragmatic default; [`OrderStatus::default`] callers should overwrite it
/// before reading.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub enum OrderStatusKind {
    /// Order has not yet been sent to the IB server, e.g. while waiting for a
    /// security definition lookup. Uncommon in practice.
    ApiPending,
    /// Order has been transmitted to the destination but no acknowledgment has
    /// been received yet.
    PendingSubmit,
    /// A cancellation request has been sent but the destination has not yet
    /// confirmed it. Cancellation is not guaranteed at this point.
    PendingCancel,
    /// A simulated order type has been accepted by the IB system and is held
    /// pending its election criteria; once met, it is transmitted to the
    /// destination.
    PreSubmitted,
    /// Order has been accepted by the system and is working at the
    /// destination.
    #[default]
    Submitted,
    /// API client requested cancellation after submission but before
    /// acknowledgment, producing this transitional state.
    ApiCancelled,
    /// Destination has confirmed the order is fully cancelled. Terminal.
    /// May also occur if IB or the destination unexpectedly rejects the
    /// order.
    Cancelled,
    /// Order has been completely filled. Terminal.
    /// (Market orders may not always trigger this state.)
    Filled,
    /// Order was received but is no longer active because it was rejected or
    /// cancelled. Terminal.
    Inactive,
    /// Status string not modeled by this version of the API. Carries the raw
    /// wire value so callers can log, store, or act on it. Neither
    /// [`is_active`](Self::is_active) nor [`is_terminal`](Self::is_terminal).
    /// Matching is exact and case-sensitive, so a case-variant of a known
    /// status also lands here rather than being silently coerced. See
    /// `docs/migration-4.0.md` §9.
    Unknown(String),
}

impl OrderStatusKind {
    /// Return the canonical wire string for this status — for
    /// [`Unknown`](Self::Unknown), the raw value as received.
    pub fn as_str(&self) -> &str {
        match self {
            OrderStatusKind::ApiPending => "ApiPending",
            OrderStatusKind::PendingSubmit => "PendingSubmit",
            OrderStatusKind::PendingCancel => "PendingCancel",
            OrderStatusKind::PreSubmitted => "PreSubmitted",
            OrderStatusKind::Submitted => "Submitted",
            OrderStatusKind::ApiCancelled => "ApiCancelled",
            OrderStatusKind::Cancelled => "Cancelled",
            OrderStatusKind::Filled => "Filled",
            OrderStatusKind::Inactive => "Inactive",
            OrderStatusKind::Unknown(raw) => raw,
        }
    }

    fn from_wire(s: &str) -> Option<Self> {
        match s {
            "ApiPending" => Some(Self::ApiPending),
            "PendingSubmit" => Some(Self::PendingSubmit),
            "PendingCancel" => Some(Self::PendingCancel),
            "PreSubmitted" => Some(Self::PreSubmitted),
            "Submitted" => Some(Self::Submitted),
            "ApiCancelled" => Some(Self::ApiCancelled),
            "Cancelled" => Some(Self::Cancelled),
            "Filled" => Some(Self::Filled),
            "Inactive" => Some(Self::Inactive),
            _ => None,
        }
    }

    /// Order is still working in the market: `PreSubmitted`, `PendingSubmit`,
    /// `PendingCancel`, `Submitted`.
    ///
    /// Note that [`is_active`](Self::is_active) and
    /// [`is_terminal`](Self::is_terminal) do not partition the variants —
    /// `ApiPending` and `Unknown` are neither, so do not assume
    /// `!is_active() ⇒ is_terminal()`.
    pub fn is_active(&self) -> bool {
        matches!(self, Self::PreSubmitted | Self::PendingSubmit | Self::PendingCancel | Self::Submitted)
    }

    /// Order has reached a final state: `Filled`, `Cancelled`, `ApiCancelled`,
    /// `Inactive`.
    pub fn is_terminal(&self) -> bool {
        matches!(self, Self::Filled | Self::Cancelled | Self::ApiCancelled | Self::Inactive)
    }
}

impl_wire_enum!(OrderStatusKind, fallback Unknown);

// Serde as the plain wire string in both directions, so `Unknown("X")`
// round-trips as `"X"` — not the externally tagged `{"Unknown":"X"}` a
// derive would produce for the one payload variant. Deserialize is the
// simple owned-String form on purpose: serde is not on the wire path
// (decoding goes through `parse_required` → `FromStr`).
//
// The utoipa schema is hand-written for the same reason — the derive
// mirrors serde's *default* representation, which is not what the manual
// impls emit. The schema is exactly a string.
#[cfg(feature = "utoipa")]
impl utoipa::PartialSchema for OrderStatusKind {
    fn schema() -> utoipa::openapi::RefOr<utoipa::openapi::schema::Schema> {
        String::schema()
    }
}

#[cfg(feature = "utoipa")]
impl utoipa::ToSchema for OrderStatusKind {}

impl Serialize for OrderStatusKind {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_str())
    }
}

impl<'de> Deserialize<'de> for OrderStatusKind {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let s = String::deserialize(deserializer)?;
        s.parse().map_err(serde::de::Error::custom)
    }
}

/// Time in force specifies how long an order remains active.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub enum TimeInForce {
    /// Valid for the day only.
    #[default]
    Day,
    /// Good until canceled. The order will continue to work within the system and in the marketplace
    /// until it executes or is canceled. GTC orders will be automatically cancelled under certain conditions.
    GoodTillCanceled,
    /// Immediate or Cancel. Any portion that is not filled as soon as it becomes available in the
    /// market is canceled.
    ImmediateOrCancel,
    /// Good until Date. It will remain working within the system and in the marketplace until it
    /// executes or until the close of the market on the date specified.
    GoodTillDate,
    /// Market-on-open (MOO) or limit-on-open (LOO) order.
    OnOpen,
    /// Fill-or-Kill. If the entire order does not execute as soon as it becomes available, the entire
    /// order is canceled.
    FillOrKill,
    /// Day until Canceled.
    DayTillCanceled,
    /// Auction - for auction orders.
    Auction,
    /// Good until Crossing (GTX).
    GoodTillCrossing,
    /// Time-in-force string not modeled by this version of the API. Carries the
    /// raw wire value so callers can log, store, or act on it, rather than
    /// having an unrecognized value silently decode as [`Day`](Self::Day).
    /// Matching is exact and case-sensitive. Sending one back through
    /// [`OrderBuilder::time_in_force`](crate::orders::OrderBuilder::time_in_force)
    /// or `Order.tif` puts the raw string on the wire unchanged, so an order
    /// read from TWS round-trips. See `docs/migration-4.0.md` §13.
    Unknown(String),
}

impl TimeInForce {
    /// Return the TWS wire string for this time-in-force — for
    /// [`Unknown`](Self::Unknown), the raw value as received.
    pub fn as_str(&self) -> &str {
        match self {
            TimeInForce::Day => "DAY",
            TimeInForce::GoodTillCanceled => "GTC",
            TimeInForce::ImmediateOrCancel => "IOC",
            TimeInForce::GoodTillDate => "GTD",
            TimeInForce::OnOpen => "OPG",
            TimeInForce::FillOrKill => "FOK",
            TimeInForce::DayTillCanceled => "DTC",
            TimeInForce::Auction => "AUC",
            TimeInForce::GoodTillCrossing => "GTX",
            TimeInForce::Unknown(raw) => raw,
        }
    }

    fn from_wire(s: &str) -> Option<Self> {
        match s {
            "DAY" => Some(TimeInForce::Day),
            "GTC" => Some(TimeInForce::GoodTillCanceled),
            "IOC" => Some(TimeInForce::ImmediateOrCancel),
            "GTD" => Some(TimeInForce::GoodTillDate),
            "OPG" => Some(TimeInForce::OnOpen),
            "FOK" => Some(TimeInForce::FillOrKill),
            "DTC" => Some(TimeInForce::DayTillCanceled),
            "AUC" => Some(TimeInForce::Auction),
            "GTX" => Some(TimeInForce::GoodTillCrossing),
            _ => None,
        }
    }
}

impl_wire_enum!(TimeInForce, fallback Unknown);

// Serde as the plain wire string in both directions, so `Unknown("X")`
// round-trips as `"X"` rather than the externally tagged `{"Unknown":"X"}` a
// derive would produce for the one payload variant. This also keeps the JSON
// stable against Rust-side renames — see `OrderStatusKind` for the same
// reasoning, including why the utoipa schema is hand-written.
#[cfg(feature = "utoipa")]
impl utoipa::PartialSchema for TimeInForce {
    fn schema() -> utoipa::openapi::RefOr<utoipa::openapi::schema::Schema> {
        String::schema()
    }
}

#[cfg(feature = "utoipa")]
impl utoipa::ToSchema for TimeInForce {}

impl Serialize for TimeInForce {
    fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
        serializer.serialize_str(self.as_str())
    }
}

impl<'de> Deserialize<'de> for TimeInForce {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let s = String::deserialize(deserializer)?;
        s.parse().map_err(serde::de::Error::custom)
    }
}

impl From<String> for TimeInForce {
    fn from(value: String) -> Self {
        Self::from(value.as_str())
    }
}

// Infallible, unlike the `FromStr` the macro generates: the empty string has
// nowhere to go but `Unknown("")`, which `some_str` in the proto encoder then
// omits from the wire exactly as `EClientUtils` does upstream. Callers that
// need the empty case rejected should use `FromStr`.
impl From<&str> for TimeInForce {
    fn from(value: &str) -> Self {
        Self::from_wire(value).unwrap_or_else(|| TimeInForce::Unknown(value.to_string()))
    }
}

/// Tells how to handle remaining orders in an OCA group when one order or part of an order executes.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum OcaType {
    /// Not part of OCA group. Wire code `0`.
    #[default]
    None,
    /// Cancel all remaining orders with block (overfill protection - only one order routed at a time). Wire code `1`.
    CancelWithBlock,
    /// Proportionally reduce remaining orders with block. Wire code `2`.
    ReduceWithBlock,
    /// Proportionally reduce remaining orders without block. Wire code `3`.
    ReduceWithoutBlock,
    /// OCA type code not modeled by this version of the API.
    Unknown(i32),
}

impl From<OcaType> for i32 {
    fn from(value: OcaType) -> i32 {
        match value {
            OcaType::None => 0,
            OcaType::CancelWithBlock => 1,
            OcaType::ReduceWithBlock => 2,
            OcaType::ReduceWithoutBlock => 3,
            OcaType::Unknown(code) => code,
        }
    }
}

impl From<i32> for OcaType {
    fn from(value: i32) -> Self {
        match value {
            0 => OcaType::None,
            1 => OcaType::CancelWithBlock,
            2 => OcaType::ReduceWithBlock,
            3 => OcaType::ReduceWithoutBlock,
            code => OcaType::Unknown(code),
        }
    }
}

/// The order's origin. Identifies the type of customer from which the order originated.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum OrderOrigin {
    /// Customer order. Wire code `0`.
    #[default]
    Customer,
    /// Firm order (institutional customers only). Wire code `1`.
    Firm,
    /// Origin code not modeled by this version of the API.
    Unknown(i32),
}

impl From<OrderOrigin> for i32 {
    fn from(value: OrderOrigin) -> i32 {
        match value {
            OrderOrigin::Customer => 0,
            OrderOrigin::Firm => 1,
            OrderOrigin::Unknown(code) => code,
        }
    }
}

impl From<i32> for OrderOrigin {
    fn from(value: i32) -> Self {
        match value {
            0 => OrderOrigin::Customer,
            1 => OrderOrigin::Firm,
            code => OrderOrigin::Unknown(code),
        }
    }
}

/// Specifies the short sale slot (for institutional short sales).
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum ShortSaleSlot {
    /// Not a short sale. Wire code `0`.
    #[default]
    None,
    /// Broker holds shares. Wire code `1`.
    Broker,
    /// Shares come from elsewhere (third party). Use with `designated_location` field. Wire code `2`.
    ThirdParty,
    /// Short sale slot code not modeled by this version of the API.
    Unknown(i32),
}

impl From<ShortSaleSlot> for i32 {
    fn from(value: ShortSaleSlot) -> i32 {
        match value {
            ShortSaleSlot::None => 0,
            ShortSaleSlot::Broker => 1,
            ShortSaleSlot::ThirdParty => 2,
            ShortSaleSlot::Unknown(code) => code,
        }
    }
}

impl From<i32> for ShortSaleSlot {
    fn from(value: i32) -> Self {
        match value {
            0 => ShortSaleSlot::None,
            1 => ShortSaleSlot::Broker,
            2 => ShortSaleSlot::ThirdParty,
            code => ShortSaleSlot::Unknown(code),
        }
    }
}

/// Volatility type for VOL orders.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum VolatilityType {
    /// Daily volatility. Wire code `1`.
    Daily,
    /// Annual volatility. Wire code `2`.
    Annual,
    /// Volatility type code not modeled by this version of the API.
    Unknown(i32),
}

impl From<VolatilityType> for i32 {
    fn from(value: VolatilityType) -> i32 {
        match value {
            VolatilityType::Daily => 1,
            VolatilityType::Annual => 2,
            VolatilityType::Unknown(code) => code,
        }
    }
}

impl From<i32> for VolatilityType {
    fn from(value: i32) -> Self {
        match value {
            1 => VolatilityType::Daily,
            2 => VolatilityType::Annual,
            code => VolatilityType::Unknown(code),
        }
    }
}

/// Reference price type for VOL orders.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub enum ReferencePriceType {
    /// Average of National Best Bid/Offer. Wire code `1`.
    AverageOfNBBO,
    /// NBB or NBO depending on action and right. Wire code `2`.
    NBBO,
    /// Reference price type code not modeled by this version of the API.
    Unknown(i32),
}

impl From<ReferencePriceType> for i32 {
    fn from(value: ReferencePriceType) -> i32 {
        match value {
            ReferencePriceType::AverageOfNBBO => 1,
            ReferencePriceType::NBBO => 2,
            ReferencePriceType::Unknown(code) => code,
        }
    }
}

impl From<i32> for ReferencePriceType {
    fn from(value: i32) -> Self {
        match value {
            1 => ReferencePriceType::AverageOfNBBO,
            2 => ReferencePriceType::NBBO,
            code => ReferencePriceType::Unknown(code),
        }
    }
}

/// NYSE Rule 80A designations for institutional trading.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub enum Rule80A {
    /// Individual customer.
    Individual,
    /// Agency transaction.
    Agency,
    /// Agent for other member.
    AgentOtherMember,
    /// Individual principal transaction in agency cross.
    IndividualPTIA,
    /// Agency principal transaction in agency cross.
    AgencyPTIA,
    /// Agent for other member principal transaction in agency cross.
    AgentOtherMemberPTIA,
    /// Individual principal transaction.
    IndividualPT,
    /// Agency principal transaction.
    AgencyPT,
    /// Agent for other member principal transaction.
    AgentOtherMemberPT,
    /// Rule 80A code not modeled by this version of the API. Carries the raw
    /// wire value as received on an inbound order; sent back unchanged.
    Unknown(String),
}

impl Rule80A {
    /// Return the TWS wire code (`"I"`, `"A"`, ...) — for
    /// [`Unknown`](Self::Unknown), the raw value as received.
    pub fn as_str(&self) -> &str {
        match self {
            Rule80A::Individual => "I",
            Rule80A::Agency => "A",
            Rule80A::AgentOtherMember => "W",
            Rule80A::IndividualPTIA => "J",
            Rule80A::AgencyPTIA => "U",
            Rule80A::AgentOtherMemberPTIA => "M",
            Rule80A::IndividualPT => "K",
            Rule80A::AgencyPT => "Y",
            Rule80A::AgentOtherMemberPT => "N",
            Rule80A::Unknown(raw) => raw,
        }
    }

    fn from_wire(s: &str) -> Option<Self> {
        match s {
            "I" => Some(Rule80A::Individual),
            "A" => Some(Rule80A::Agency),
            "W" => Some(Rule80A::AgentOtherMember),
            "J" => Some(Rule80A::IndividualPTIA),
            "U" => Some(Rule80A::AgencyPTIA),
            "M" => Some(Rule80A::AgentOtherMemberPTIA),
            "K" => Some(Rule80A::IndividualPT),
            "Y" => Some(Rule80A::AgencyPT),
            "N" => Some(Rule80A::AgentOtherMemberPT),
            _ => None,
        }
    }
}

// Open: an optional field on inbound OpenOrder frames whose code letters are
// assigned by the exchange, not by this crate.
impl_wire_enum!(Rule80A, fallback Unknown);

/// Represents the price component of a combo leg order.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct OrderComboLeg {
    /// The price for this combo leg.
    pub price: Option<f64>,
}

/// Order condition types for conditional orders.
///
/// Each variant wraps a specific condition type that defines when the order
/// should be activated or canceled based on market conditions.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub enum OrderCondition {
    /// Price-based condition that triggers when a contract reaches a specified price.
    Price(PriceCondition),
    /// Time-based condition that triggers at a specified time.
    Time(TimeCondition),
    /// Margin-based condition that triggers when margin cushion percentage changes.
    Margin(MarginCondition),
    /// Execution-based condition that triggers when a specific contract is executed.
    Execution(ExecutionCondition),
    /// Volume-based condition that triggers when a contract reaches a specified volume.
    Volume(VolumeCondition),
    /// Percent change condition that triggers when a contract's price changes by a specified percentage.
    PercentChange(PercentChangeCondition),
    /// A condition type this crate does not model, preserved so it round-trips unchanged.
    Unknown(UnknownCondition),
}

impl OrderCondition {
    /// Returns the condition type discriminator as used by the TWS API.
    pub fn condition_type(&self) -> i32 {
        match self {
            Self::Price(_) => 1,
            Self::Time(_) => 3,
            Self::Margin(_) => 4,
            Self::Execution(_) => 5,
            Self::Volume(_) => 6,
            Self::PercentChange(_) => 7,
            Self::Unknown(c) => c.condition_type,
        }
    }

    /// Returns whether this is a conjunction (AND) condition.
    pub fn is_conjunction(&self) -> bool {
        match self {
            Self::Price(c) => c.is_conjunction,
            Self::Time(c) => c.is_conjunction,
            Self::Margin(c) => c.is_conjunction,
            Self::Execution(c) => c.is_conjunction,
            Self::Volume(c) => c.is_conjunction,
            Self::PercentChange(c) => c.is_conjunction,
            Self::Unknown(c) => c.is_conjunction,
        }
    }
}

/// Stores Soft Dollar Tier information.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct SoftDollarTier {
    /// Soft dollar tier name.
    pub name: String,
    /// Tier identifier value.
    pub value: String,
    /// User-friendly display name.
    pub display_name: String,
}

/// Contains order information including the order, contract, and order state.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct OrderData {
    /// The order's unique id
    pub order_id: i32,
    /// The order's Contract.
    pub contract: Contract,
    /// The currently active order
    pub order: Order,
    /// The order's OrderState
    pub order_state: OrderState,
}

/// Provides an active order's current state.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct OrderState {
    /// The order's current status. See [`OrderStatusKind`].
    pub status: OrderStatusKind,
    /// The account's current initial margin.
    pub initial_margin_before: Option<f64>,
    /// The account's current maintenance margin
    pub maintenance_margin_before: Option<f64>,
    /// The account's current equity with loan
    pub equity_with_loan_before: Option<f64>,
    /// The change of the account's initial margin.
    pub initial_margin_change: Option<f64>,
    /// The change of the account's maintenance margin
    pub maintenance_margin_change: Option<f64>,
    /// The change of the account's equity with loan
    pub equity_with_loan_change: Option<f64>,
    /// The order's impact on the account's initial margin.
    pub initial_margin_after: Option<f64>,
    /// The order's impact on the account's maintenance margin
    pub maintenance_margin_after: Option<f64>,
    /// Shows the impact the order would have on the account's equity with loan
    pub equity_with_loan_after: Option<f64>,
    /// The order's generated commission.
    pub commission: Option<f64>,
    /// The execution's minimum commission.
    pub minimum_commission: Option<f64>,
    /// The executions maximum commission.
    pub maximum_commission: Option<f64>,
    /// The generated commission currency
    pub commission_currency: String,
    /// Margin currency
    pub margin_currency: String,
    /// The account's current initial margin outside RTH
    pub initial_margin_before_outside_rth: Option<f64>,
    /// The account's current maintenance margin outside RTH
    pub maintenance_margin_before_outside_rth: Option<f64>,
    /// The account's current equity with loan outside RTH
    pub equity_with_loan_before_outside_rth: Option<f64>,
    /// The change of the account's initial margin outside RTH
    pub initial_margin_change_outside_rth: Option<f64>,
    /// The change of the account's maintenance margin outside RTH
    pub maintenance_margin_change_outside_rth: Option<f64>,
    /// The change of the account's equity with loan outside RTH
    pub equity_with_loan_change_outside_rth: Option<f64>,
    /// The order's impact on the account's initial margin outside RTH
    pub initial_margin_after_outside_rth: Option<f64>,
    /// The order's impact on the account's maintenance margin outside RTH
    pub maintenance_margin_after_outside_rth: Option<f64>,
    /// Shows the impact the order would have on the account's equity with loan outside RTH
    pub equity_with_loan_after_outside_rth: Option<f64>,
    /// Suggested order size
    pub suggested_size: Option<f64>,
    /// Reject reason
    pub reject_reason: String,
    /// Order allocations
    pub order_allocations: Vec<OrderAllocation>,
    /// If the order is warranted, a descriptive message will be provided.
    pub warning_text: String,
    /// Timestamp when the order completed execution.
    pub completed_time: String,
    /// Free-form descriptive status sent at completion (e.g. `"Cancelled by Trader"`,
    /// `"Filled Size: 1"`). For the canonical lifecycle state, use [`status`](Self::status).
    pub completed_status: String,
}

/// Allocation of an order across accounts.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct OrderAllocation {
    /// Allocation account
    pub account: String,
    /// Position
    pub position: Option<f64>,
    /// Desired position
    pub position_desired: Option<f64>,
    /// Position after
    pub position_after: Option<f64>,
    /// Desired allocation quantity
    pub desired_alloc_qty: Option<f64>,
    /// Allowed allocation quantity
    pub allowed_alloc_qty: Option<f64>,
    /// Is monetary
    pub is_monetary: bool,
}

/// For institutional customers only. Valid values are O (open) and C (close).
/// Available for institutional clients to determine if this order is to open or close a position.
/// When Action = "BUY" and OpenClose = "O" this will open a new position.
/// When Action = "BUY" and OpenClose = "C" this will close and existing short position.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub enum OrderOpenClose {
    /// Open a new position.
    Open,
    /// Close an existing position.
    Close,
    /// Open/close value not modeled by this version of the API. Carries the
    /// raw wire value as received on an inbound order; sent back unchanged.
    Unknown(String),
}

impl OrderOpenClose {
    /// Return the TWS wire string (`"O"` / `"C"`) — for
    /// [`Unknown`](Self::Unknown), the raw value as received.
    pub fn as_str(&self) -> &str {
        match self {
            OrderOpenClose::Open => "O",
            OrderOpenClose::Close => "C",
            OrderOpenClose::Unknown(raw) => raw,
        }
    }

    fn from_wire(s: &str) -> Option<Self> {
        match s {
            "O" => Some(OrderOpenClose::Open),
            "C" => Some(OrderOpenClose::Close),
            _ => None,
        }
    }
}

// Open: an optional field on inbound OpenOrder frames. The value is binary
// today, but unlike `ExecutionSide` the type is already not `Copy`, so
// preserving a surprise costs nothing and keeps the order streams up.
impl_wire_enum!(OrderOpenClose, fallback Unknown);

/// Represents the commission generated by an execution.
///
/// # Correlating commissions with executions
///
/// A `CommissionReport` joins to its [`Execution`] by
/// [`execution_id`](CommissionReport::execution_id) — the same value carried on
/// [`Execution::execution_id`]. TWS sends the [`ExecutionData`] first and the
/// matching `CommissionReport` shortly after, with unrelated frames (order
/// status, open-order updates) possibly in between, so the two are not
/// adjacent. Both arrive on the same streams
/// ([`executions`](crate::Client::executions),
/// [`place_order`](crate::Client::place_order), and
/// [`order_update_stream`](crate::Client::order_update_stream)); index
/// commissions by `execution_id` rather than by position in the stream.
///
/// # Examples
///
/// ```
/// use ibapi::orders::{CommissionReport, Execution};
/// use std::collections::HashMap;
///
/// // The execution arrives first: index it by execution_id.
/// let mut executions: HashMap<String, Execution> = HashMap::new();
/// let execution = Execution {
///     execution_id: "0000e1a7.0001.01".to_string(),
///     shares: 100.0,
///     ..Default::default()
/// };
/// executions.insert(execution.execution_id.clone(), execution);
///
/// // The commission follows: join it to its execution by execution_id.
/// let report = CommissionReport {
///     execution_id: "0000e1a7.0001.01".to_string(),
///     commission: 1.25,
///     ..Default::default()
/// };
/// if let Some(execution) = executions.remove(&report.execution_id) {
///     println!("{} shares, commission {}", execution.shares, report.commission);
/// }
/// ```
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, Default)]
pub struct CommissionReport {
    /// The [`Execution::execution_id`] this commission belongs to. Use it to
    /// join the commission to its execution deterministically (see the
    /// type-level docs).
    pub execution_id: String,
    /// the commissions cost.
    pub commission: f64,
    /// the reporting currency.
    pub currency: String,
    /// the realized profit and loss
    pub realized_pnl: Option<f64>,
    /// The income return.
    pub yields: Option<f64>,
    /// date expressed in yyyymmdd format.
    pub yield_redemption_date: String,
}

/// Liquidity types for executions.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, Default, PartialEq)]
pub enum Liquidity {
    /// No liquidity information. Wire code `0`.
    #[default]
    None,
    /// Added liquidity to the market. Wire code `1`.
    AddedLiquidity,
    /// Removed liquidity from the market. Wire code `2`.
    RemovedLiquidity,
    /// Liquidity was routed out. Wire code `3`.
    LiquidityRoutedOut,
    /// Liquidity code not modeled by this version of the API.
    Unknown(i32),
}

impl From<i32> for Liquidity {
    fn from(val: i32) -> Self {
        match val {
            0 => Liquidity::None,
            1 => Liquidity::AddedLiquidity,
            2 => Liquidity::RemovedLiquidity,
            3 => Liquidity::LiquidityRoutedOut,
            value => Liquidity::Unknown(value),
        }
    }
}

/// Describes an order's execution.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, Default)]
pub struct Execution {
    /// The API client's order Id. May not be unique to an account.
    pub order_id: i32,
    /// The API client identifier which placed the order which originated this execution.
    pub client_id: i32,
    /// The execution's identifier. Each partial fill has a separate ExecId.
    /// A correction is indicated by an ExecId which differs from a previous ExecId in only the digits after the final period,
    /// e.g. an ExecId ending in ".02" would be a correction of a previous execution with an ExecId ending in ".01"
    pub execution_id: String,
    /// The execution's server time.
    pub time: String,
    /// The account to which the order was allocated.
    pub account_number: String,
    /// The exchange where the execution took place.
    pub exchange: String,
    /// Specifies if the transaction was buy or sale: [`ExecutionSide::Bought`]
    /// for `"BOT"`, [`ExecutionSide::Sold`] for `"SLD"`.
    pub side: ExecutionSide,
    /// The number of shares filled.
    pub shares: f64,
    /// The order's execution price excluding commissions.
    pub price: f64,
    /// The TWS order identifier. The PermId can be 0 for trades originating outside IB.
    pub perm_id: i64,
    /// Identifies whether an execution occurred because of an IB-initiated liquidation.
    pub liquidation: i32,
    /// Cumulative quantity.
    // Used in regular trades, combo trades and legs of the combo.
    pub cumulative_quantity: f64,
    /// Average price.
    /// Used in regular trades, combo trades and legs of the combo. Does not include commissions.
    pub average_price: f64,
    /// The OrderRef is a user-customizable string that can be set from the API or TWS and will be associated with an order for its lifetime.
    pub order_reference: String,
    /// The Economic Value Rule name and the respective optional argument.
    /// The two values should be separated by a colon. For example, aussieBond:YearsToExpiration=3. When the optional argument is not present, the first value will be followed by a colon.
    pub ev_rule: String,
    /// Tells you approximately how much the market value of a contract would change if the price were to change by 1.
    /// It cannot be used to get market value by multiplying the price by the approximate multiplier.
    pub ev_multiplier: Option<f64>,
    /// model code
    pub model_code: String,
    /// Liquidity type of the execution (requires TWS 968+ / API v973.05+).
    pub last_liquidity: Liquidity,
    /// Indicates whether a price revision is pending.
    pub pending_price_revision: bool,
    /// Identifies the submitter of the execution.
    pub submitter: String,
}

/// Contains execution information including the request ID, contract, and execution details.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, Default)]
pub struct ExecutionData {
    /// The request ID associated with this execution.
    pub request_id: i32,
    /// The contract that was executed.
    pub contract: Contract,
    /// The execution details.
    pub execution: Execution,
}

/// Responses from placing an order.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug)]
#[allow(clippy::large_enum_variant)]
pub enum PlaceOrder {
    /// Order status update.
    OrderStatus(OrderStatus),
    /// Open order information.
    OpenOrder(OrderData),
    /// Execution data.
    ExecutionData(ExecutionData),
    /// Commission report.
    CommissionReport(CommissionReport),
}

/// Updates received when monitoring order activity.
/// This enum is used by `order_update_stream` to deliver real-time order updates.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug)]
#[allow(clippy::large_enum_variant)]
pub enum OrderUpdate {
    /// Order status update.
    OrderStatus(OrderStatus),
    /// Open order information.
    OpenOrder(OrderData),
    /// Mapping from a permanent order ID to an API client's order ID.
    OrderBound(OrderBound),
    /// Execution data.
    ExecutionData(ExecutionData),
    /// Commission report.
    CommissionReport(CommissionReport),
}

/// An account-wide permanent order identity bound to an API client's order ID.
///
/// API order IDs are scoped to `client_id`. This notification does not grant
/// another API client permission to modify or cancel the order.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq)]
pub struct OrderBound {
    /// Permanent order ID assigned by TWS.
    pub perm_id: i64,
    /// API client to which the order is bound.
    pub client_id: i32,
    /// Order ID in that API client's namespace.
    pub order_id: i32,
}

/// Contains all relevant information on the current status of the order execution-wise (i.e. amount filled and pending, filling price, etc.).
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq)]
pub struct OrderStatus {
    /// The order's client id.
    pub order_id: i32,
    /// The current status of the order. See [`OrderStatusKind`] for variant
    /// definitions and helpers like [`is_terminal`](OrderStatusKind::is_terminal).
    pub status: OrderStatusKind,
    /// Number of filled positions.
    pub filled: f64,
    /// The remnant positions.
    pub remaining: f64,
    /// Average filling price. `None` when IBKR did not send a value (UNSET_DOUBLE on text protocol; missing optional field on protobuf).
    pub average_fill_price: Option<f64>,
    /// The order's permId used by the TWS to identify orders.
    pub perm_id: i64,
    /// Parent's id. Used for bracket and auto trailing stop orders.
    pub parent_id: i32,
    /// Price at which the last positions were filled. `None` when IBKR did not send a value.
    pub last_fill_price: Option<f64>,
    /// API client which submitted the order.
    pub client_id: i32,
    /// This field is used to identify an order held when TWS is trying to locate shares for a short sell. The value used to indicate this is 'locate'.
    pub why_held: String,
    /// If an order has been capped, this indicates the current capped price. Requires TWS 967+ and API v973.04+. Python API specifically requires API v973.06+. `None` when IBKR did not send a value.
    pub market_cap_price: Option<f64>,
}

impl OrderStatus {
    /// How the order ended, or `None` while it is still working (partial
    /// fills included). The rule `wait_for_fill` applies to each status, for
    /// waits built on `order_status_stream`.
    ///
    /// [`Filled`](OrderOutcome::Filled) for status
    /// [`Filled`](OrderStatusKind::Filled), or nothing remaining after a fill
    /// (market orders do not always report `Filled`);
    /// [`Ended`](OrderOutcome::Ended) for any other
    /// [terminal](OrderStatusKind::is_terminal) status.
    ///
    /// # Examples
    ///
    /// ```
    /// use ibapi::orders::{OrderOutcome, OrderStatus, OrderStatusKind};
    ///
    /// let partial = OrderStatus { status: OrderStatusKind::Submitted, filled: 40.0, remaining: 60.0, ..Default::default() };
    /// assert_eq!(partial.outcome(), None);
    ///
    /// let done = OrderStatus { filled: 100.0, remaining: 0.0, ..partial };
    /// assert!(matches!(done.outcome(), Some(OrderOutcome::Filled(_))));
    /// ```
    pub fn outcome(&self) -> Option<OrderOutcome> {
        // `filled > 0` keeps an early all-zero status from counting.
        if self.status == OrderStatusKind::Filled || (self.remaining == 0.0 && self.filled > 0.0) {
            Some(OrderOutcome::Filled(self.clone()))
        } else if self.status.is_terminal() {
            Some(OrderOutcome::Ended(self.clone()))
        } else {
            None
        }
    }
}

/// How an order ended, as reported by `Client::wait_for_fill`.
///
/// [`Filled`](Self::Filled), [`Ended`](Self::Ended) and
/// [`TimedOut`](Self::TimedOut) carry the order's last [`OrderStatus`]:
/// `filled`, `remaining` and `average_fill_price` give the fill, which may be
/// partial for `Ended` and `TimedOut`. [`Rejected`](Self::Rejected) carries
/// TWS's error instead, since the order never got a status.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub enum OrderOutcome {
    /// The order filled completely: status [`Filled`](OrderStatusKind::Filled),
    /// or nothing remaining after a fill (market orders do not always report
    /// `Filled`).
    Filled(OrderStatus),
    /// The order ended without filling completely:
    /// [`Cancelled`](OrderStatusKind::Cancelled),
    /// [`ApiCancelled`](OrderStatusKind::ApiCancelled) or
    /// [`Inactive`](OrderStatusKind::Inactive).
    Ended(OrderStatus),
    /// The wait timed out with the order still working. Carries the last
    /// status seen, if any. The order is left alone; cancel it yourself if
    /// you no longer want it.
    TimedOut(Option<OrderStatus>),
    /// TWS refused the order with an error and no status, so it never
    /// worked (e.g. 110, a price off the minimum tick). A rejection TWS
    /// reports with an [`Inactive`](OrderStatusKind::Inactive) status, such as
    /// 201 for insufficient margin, is [`Ended`](Self::Ended).
    Rejected(crate::Notice),
}

/// Enumerates possible results from cancelling an order.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Debug)]
pub enum CancelOrder {
    /// Order status information.
    OrderStatus(OrderStatus),
}

/// Enumerates possible results from querying an [Order].
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Debug)]
#[allow(clippy::large_enum_variant)]
pub enum Orders {
    /// Detailed order data.
    OrderData(OrderData),
    /// Order status update.
    OrderStatus(OrderStatus),
}

/// Side filter on outbound execution requests. IBKR's wire vocabulary for
/// `ExecutionFilter.side` is `"BUY"` / `"SELL"` only.
///
/// Distinct from [`Action`] — the outbound order-side vocabulary includes
/// `SSHORT` / `SLONG`, neither accepted on the filter. A subset enum here
/// makes invalid filter values unrepresentable.
///
/// No `Default` — [`ExecutionFilter::side`] carries the no-filter state via
/// `None`. `#[non_exhaustive]` leaves headroom for IBKR vocabulary additions.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[non_exhaustive]
pub enum ExecutionFilterSide {
    /// Filter to buy fills only.
    Buy,
    /// Filter to sell fills only.
    Sell,
}

impl ExecutionFilterSide {
    /// Return the canonical IBKR wire string (`"BUY"` / `"SELL"`).
    pub fn as_str(&self) -> &'static str {
        match self {
            ExecutionFilterSide::Buy => "BUY",
            ExecutionFilterSide::Sell => "SELL",
        }
    }

    fn from_wire(s: &str) -> Option<Self> {
        match s {
            "BUY" => Some(Self::Buy),
            "SELL" => Some(Self::Sell),
            _ => None,
        }
    }
}

impl_wire_enum!(ExecutionFilterSide);

/// Side of an [`Execution`] report — direction of a filled order.
///
/// IBKR's documented wire vocabulary for `Execution.side` is two values
/// ([C# `Execution.cs:83`](https://github.com/InteractiveBrokers/tws-api/blob/master/source/csharpclient/client/Execution.cs)):
/// `"BOT"` for bought, `"SLD"` for sold. Short-sale fills (orders with
/// [`Action::SellShort`]) emit `"SLD"` on the execution — the short-sale
/// designation lives on the originating order, not the execution.
///
/// Exhaustive on purpose: the field is binary in the IBKR spec, so callers
/// get a compile-time signal if a hypothetical third variant is ever added.
/// The strict `FromStr` rejects unknown wire strings as [`Error::Parse`](crate::Error::Parse)
/// in the decoder, so a surprise addition fails loudly before any `match` fires.
///
/// `Default` is [`ExecutionSide::Bought`] — arbitrary, only observed on
/// placeholder [`Execution::default()`] instances built when an upstream
/// `ExecutionDetails` proto omits its inner `execution` field. Real
/// fills always set the variant from the wire.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)]
pub enum ExecutionSide {
    /// Buy fill — IBKR wire value `"BOT"`.
    #[default]
    Bought,
    /// Sell fill — IBKR wire value `"SLD"`.
    Sold,
}

impl ExecutionSide {
    /// Return the canonical IBKR wire string (`"BOT"` / `"SLD"`).
    pub fn as_str(&self) -> &'static str {
        match self {
            ExecutionSide::Bought => "BOT",
            ExecutionSide::Sold => "SLD",
        }
    }

    fn from_wire(s: &str) -> Option<Self> {
        match s {
            "BOT" => Some(Self::Bought),
            "SLD" => Some(Self::Sold),
            _ => None,
        }
    }
}

impl_wire_enum!(ExecutionSide);

#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Debug, Default)]
/// Filter criteria used to determine which execution reports are returned.
pub struct ExecutionFilter {
    /// The API client which placed the order.
    pub client_id: Option<i32>,
    /// The account to which the order was allocated to
    pub account_code: String,
    /// Time from which the executions will be returned yyyymmdd hh:mm:ss
    /// Only those executions reported after the specified time will be returned.
    pub time: String,
    /// The instrument's symbol
    pub symbol: String,
    /// The Contract's security's type (i.e. STK, OPT...)
    pub security_type: String,
    /// The exchange at which the execution was produced
    pub exchange: String,
    /// Side filter — `None` for no filter, `Some(ExecutionFilterSide::Buy)`
    /// or `Some(ExecutionFilterSide::Sell)` to restrict the response.
    pub side: Option<ExecutionFilterSide>,
    /// Filter executions from the last N days (0 = no filter).
    pub last_n_days: i32,
    /// Filter executions for specific dates (format: yyyymmdd, e.g., "20260130").
    pub specific_dates: Vec<String>,
}

/// Enumerates possible results from querying an [Execution].
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Debug)]
#[allow(clippy::large_enum_variant)]
pub enum Executions {
    /// Execution data payload.
    ExecutionData(ExecutionData),
    /// Commission report payload.
    CommissionReport(CommissionReport),
}

/// Exercise action for options.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Debug, Clone, Copy)]
pub enum ExerciseAction {
    /// Exercise the option.
    Exercise = 1,
    /// Let the option lapse.
    Lapse = 2,
}

/// Responses from exercising options.
#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[allow(clippy::large_enum_variant)]
pub enum ExerciseOptions {
    /// Open order information.
    OpenOrder(OrderData),
    /// Order status update.
    OrderStatus(OrderStatus),
}

// Feature-specific implementations
#[cfg(feature = "sync")]
mod sync;

#[cfg(feature = "async")]
mod r#async;

#[cfg(test)]
mod tests;