fts_core/ports/
demand.rs

1use crate::models::{
2    DateTimeRangeQuery, DateTimeRangeResponse, DemandCurve, DemandRecord, ValueRecord,
3};
4
5/// Repository interface for demand curve submission and retrieval.
6///
7/// This trait encapsulates all the functionality related to demand curve submission and retrieval.
8/// Demands represent bidders' pricing preferences and are the fundamental input to the
9/// optimization solver.
10///
11/// This trait is parameterized by a generic data type, allowing an application
12/// to colocate write-once data alongside the relevant record.
13pub trait DemandRepository<DemandData>: super::Repository {
14    /// Get the bidder id associated to the demand
15    fn get_demand_bidder_id(
16        &self,
17        demand_id: Self::DemandId,
18    ) -> impl Future<Output = Result<Option<Self::BidderId>, Self::Error>> + Send;
19
20    /// Create a new demand with an optional initial curve.
21    fn create_demand(
22        &self,
23        demand_id: Self::DemandId,
24        bidder_id: Self::BidderId,
25        app_data: DemandData,
26        curve_data: Option<DemandCurve>,
27        as_of: Self::DateTime,
28    ) -> impl Future<Output = Result<(), Self::Error>> + Send;
29
30    /// Update the curve data for an existing demand.
31    ///
32    /// Setting curve_data to None effectively deactivates the demand
33    /// while preserving its history.
34    ///
35    /// # Returns
36    ///
37    /// - Ok(true) if successful
38    /// - Ok(false) if no such demand exists
39    /// - Err otherwise
40    fn update_demand(
41        &self,
42        demand_id: Self::DemandId,
43        curve_data: Option<DemandCurve>,
44        as_of: Self::DateTime,
45    ) -> impl Future<Output = Result<bool, Self::Error>> + Send;
46
47    /// Retrieve a demand at a specific point in time.
48    ///
49    /// Retrieve the requested demand curve and associated portfolios, returning Option::None if it does not exist.
50    fn get_demand(
51        &self,
52        demand_id: Self::DemandId,
53        as_of: Self::DateTime,
54    ) -> impl Future<
55        Output = Result<
56            Option<
57                DemandRecord<
58                    Self::DateTime,
59                    Self::BidderId,
60                    Self::DemandId,
61                    Self::PortfolioId,
62                    DemandData,
63                >,
64            >,
65            Self::Error,
66        >,
67    > + Send;
68
69    /// Query all the demand curves with non-null data associated to any of `bidder_ids`
70    /// as-of the specified time.
71    ///
72    /// # Returns
73    ///
74    /// A vector of demand IDs that have active curves at the specified time.
75    fn query_demand(
76        &self,
77        bidder_ids: &[Self::BidderId],
78        as_of: Self::DateTime,
79    ) -> impl Future<Output = Result<Vec<Self::DemandId>, Self::Error>> + Send;
80
81    /// Retrieve the history of curve changes for a demand.
82    ///
83    /// # Returns
84    ///
85    /// A paginated response containing historical curve records, including
86    /// when the curve was created, modified, or deleted (None).
87    fn get_demand_history(
88        &self,
89        demand_id: Self::DemandId,
90        query: DateTimeRangeQuery<Self::DateTime>,
91        limit: usize,
92    ) -> impl Future<
93        Output = Result<
94            DateTimeRangeResponse<ValueRecord<Self::DateTime, DemandCurve>, Self::DateTime>,
95            Self::Error,
96        >,
97    > + Send;
98}
fts_core/ports/demand.rs

fts_core/ports/
demand.rs
