Skip to main content

cripsy_binary_api/broker/
trait_.rs

1//! Trait `Broker`: interfaz común async (object-safe vía `async_trait`).
2
3use async_trait::async_trait;
4use futures_core::Stream;
5
6use crate::domain::{
7    AccountType, Asset, Balance, BuyBinaryRequest, Candle, CandleRequest, CandleSubscribe, Event,
8    MarketStatus, OperationResult, OptionType, OrderId, Payout, PayoutQuote, PositionHistory,
9};
10
11use super::config::BrokerParams;
12use super::error::BrokerError;
13use super::extras::IqOptionExtras;
14use super::session::Session;
15
16/// Stream async de velas.
17pub type CandleStream = std::pin::Pin<Box<dyn Stream<Item = Result<Candle, BrokerError>> + Send>>;
18
19/// Stream async de eventos del ciclo de vida.
20pub type EventStream = std::pin::Pin<Box<dyn Stream<Item = Event> + Send>>;
21
22/// Contrato que todo adaptador de bróker cumple.
23///
24/// Diseño type-erased a propósito: sin associated types para que
25/// `Box<dyn Broker>` y `MultiBroker` compilen (ver `docs/01_introduccion.es.md`).
26#[async_trait]
27pub trait Broker: Send + Sync {
28    /// Nombre estable del adaptador, p. ej. `iq_option`.
29    fn name(&self) -> &'static str;
30
31    /// Constructor de la sesión: autentica y deja el bróker operativo.
32    async fn connect(params: BrokerParams) -> Result<Self, BrokerError>
33    where
34        Self: Sized;
35
36    async fn disconnect(&mut self) -> Result<(), BrokerError>;
37    async fn is_connected(&self) -> bool;
38
39    /// Metadatos de la sesión activa (copia: la sesión se actualiza en caliente).
40    async fn session(&self) -> Result<Session, BrokerError>;
41
42    // -------- Cuenta y balance --------
43
44    async fn get_balance(&self) -> Result<Balance, BrokerError>;
45    async fn get_account_type(&self) -> Result<AccountType, BrokerError>;
46    async fn switch_account(&mut self, kind: AccountType) -> Result<(), BrokerError>;
47
48    // -------- Activos y mercado --------
49
50    async fn list_assets(&self) -> Result<Vec<Asset>, BrokerError>;
51    async fn asset_status(&self, symbol: &str) -> Result<MarketStatus, BrokerError>;
52
53    // -------- Velas --------
54
55    async fn get_candles(&self, req: CandleRequest) -> Result<Vec<Candle>, BrokerError>;
56    async fn subscribe_candles(&self, req: CandleSubscribe) -> Result<CandleStream, BrokerError>;
57
58    /// Historial de posiciones cerradas (cartera): para analítica de cuenta.
59    /// `limit` ≤ 100 por página, `offset` para paginar.
60    async fn get_position_history(
61        &self,
62        symbol: Option<&str>,
63        limit: usize,
64        offset: usize,
65    ) -> Result<PositionHistory, BrokerError>;
66
67    // -------- Payout --------
68
69    /// Payout **publicado en el catálogo** para el activo.
70    ///
71    /// `expiration_seconds` se devuelve en el resultado pero no altera la
72    /// consulta: no se pide una cotización por expiración ni por strike. Los
73    /// cambios en vivo llegan por `Event::PayoutChanged`.
74    async fn get_payout(
75        &self,
76        symbol: &str,
77        expiration_seconds: u64,
78    ) -> Result<Payout, BrokerError>;
79
80    /// Cotización por expiración y tipo de opción.
81    ///
82    /// La referencia actual es **CALL**: Deriv traduce `OptionType::Binary` a
83    /// `CALL` y la cotización digital de IQ usa `call.bid` del spot. El tipo no
84    /// transporta dirección, así que no se debe asumir que PUT paga lo mismo.
85    ///
86    /// El default no inventa un payout: devuelve `available: false` con
87    /// `profit_percent: None`. Un adaptador que pueda cotizar debe
88    /// sobrescribirlo.
89    async fn quote_payout(
90        &self,
91        symbol: &str,
92        option_type: OptionType,
93        expiration_seconds: u64,
94        amount: f64,
95    ) -> Result<PayoutQuote, BrokerError> {
96        let _ = amount;
97        Ok(PayoutQuote::unavailable(
98            symbol,
99            option_type,
100            expiration_seconds,
101        ))
102    }
103
104    // -------- Indicadores técnicos del bróker --------
105
106    // -------- Órdenes --------
107
108    /// Compra clásica (turbo o binary según la duración).
109    ///
110    /// BLITZ tiene su propia petición: [`Broker::buy_blitz`].
111    async fn buy_binary(&self, req: BuyBinaryRequest) -> Result<OrderId, BrokerError>;
112
113    /// Venta anticipada (buyback) de una orden abierta. El bróker la admite
114    /// dentro de la ventana `buyback_deadtime` del activo; si la orden ya no
115    /// es vendible responde con su mensaje de rechazo.
116    async fn sell_option(&self, order_id: &OrderId) -> Result<(), BrokerError>;
117
118    /// Resultado leído de la caché local (alimentada por `events()`).
119    ///
120    /// No consulta al bróker: devuelve `OperationResult::Pending` mientras el
121    /// cierre no haya llegado por eventos.
122    async fn get_operation_result(
123        &self,
124        order_id: &OrderId,
125    ) -> Result<OperationResult, BrokerError>;
126
127    /// Acceso a las capacidades exclusivas de IQ Option, si el adaptador las
128    /// ofrece. Los adaptadores que no las implementan devuelven `None`.
129    fn iqoption_extras(&self) -> Option<&dyn IqOptionExtras> {
130        None
131    }
132
133    /// Suscribe el stream **nativo** de ticks de un activo.
134    ///
135    /// Los ticks llegan por `Event::PriceTick`. Un adaptador sin stream nativo
136    /// hereda el rechazo explícito; no se simula con polling.
137    async fn subscribe_ticks(&self, symbol: &str) -> Result<(), BrokerError> {
138        let _ = symbol;
139        Err(capacidad_no_soportada(self.name(), "stream de ticks"))
140    }
141
142    // -------- Eventos --------
143
144    /// Stream de eventos (cierres, balances, payouts en vivo, velas suscritas).
145    async fn events(&self) -> Result<EventStream, BrokerError>;
146}
147
148/// Rechazo uniforme de una capacidad que el bróker no ofrece.
149///
150/// Las capacidades exclusivas de IQ Option viven en el contrato por
151/// compatibilidad; un adaptador que no las ofrece no las implementa y hereda
152/// este rechazo explícito.
153fn capacidad_no_soportada(broker: &str, capacidad: &str) -> BrokerError {
154    BrokerError::Rejected(format!("{broker}: el bróker no ofrece {capacidad}"))
155}
156
157/// Marcador de compilación: el trait es `Send + Sync` por contrato.
158const fn _assert_broker_bounds<T: Broker + Send + Sync>() {}
159
160/// Tipo de opción por defecto del MVP.
161pub const MVP_OPTION_TYPES: &[OptionType] = &[OptionType::Binary, OptionType::Digital];