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