Skip to main content

financial_api/types/
fund.rs

1use std::str::FromStr;
2
3use serde::{Deserialize, Deserializer, Serialize};
4
5use super::wire::wire_enum;
6use crate::ValidationError;
7
8macro_rules! identifier_type {
9    ($(#[$meta:meta])* $name:ident, $field:literal) => {
10        $(#[$meta])*
11        #[derive(
12            Debug,
13            Clone,
14            PartialEq,
15            Eq,
16            PartialOrd,
17            Ord,
18            Hash,
19            Serialize,
20            derive_more::Display,
21        )]
22        #[serde(transparent)]
23        pub struct $name(String);
24
25        impl $name {
26            pub fn new(value: impl Into<String>) -> Result<Self, ValidationError> {
27                let value = value.into();
28                let value = value.trim();
29                if value.is_empty() {
30                    return Err(ValidationError::new($field, "must not be empty"));
31                }
32                Ok(Self(value.to_owned()))
33            }
34
35            #[must_use]
36            pub fn as_str(&self) -> &str {
37                &self.0
38            }
39        }
40
41        impl FromStr for $name {
42            type Err = ValidationError;
43
44            fn from_str(value: &str) -> Result<Self, Self::Err> {
45                Self::new(value)
46            }
47        }
48
49        impl<'de> Deserialize<'de> for $name {
50            fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
51                let value = String::deserialize(deserializer)?;
52                Self::new(value).map_err(serde::de::Error::custom)
53            }
54        }
55    };
56}
57
58identifier_type!(
59    /// Opaque fund-manager identifier discovered from fund profile data.
60    ManagerId,
61    "manager_id"
62);
63identifier_type!(
64    /// Opaque fund-company identifier discovered from fund profile data.
65    CompanyId,
66    "company_id"
67);
68identifier_type!(
69    /// Fund disclosure report type discovered from a report-dates endpoint.
70    ReportType,
71    "report_type"
72);
73
74/// Opaque pagination cursor returned by a cursor-paged endpoint.
75#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, derive_more::Display)]
76#[serde(transparent)]
77pub struct Cursor(String);
78
79impl Cursor {
80    pub fn new(value: impl Into<String>) -> Result<Self, ValidationError> {
81        let value = value.into();
82        if value.trim().is_empty() {
83            return Err(ValidationError::new("offset", "must not be empty"));
84        }
85        Ok(Self(value))
86    }
87
88    #[must_use]
89    pub fn as_str(&self) -> &str {
90        &self.0
91    }
92}
93
94impl FromStr for Cursor {
95    type Err = ValidationError;
96
97    fn from_str(value: &str) -> Result<Self, Self::Err> {
98        Self::new(value)
99    }
100}
101
102impl<'de> Deserialize<'de> for Cursor {
103    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
104        let value = String::deserialize(deserializer)?;
105        Self::new(value).map_err(serde::de::Error::custom)
106    }
107}
108
109wire_enum! {
110    /// Fund target universe.
111    pub enum FundType {
112        Otc => "otc",
113        Exchange => "exchange",
114        Reits => "reits",
115    }
116}
117
118wire_enum! {
119    /// Holder record merge policy.
120    pub enum HolderMergeScope {
121        All => "all",
122        Merged => "merged",
123        Separate => "separate",
124    }
125}
126
127wire_enum! {
128    /// Fund NAV history range.
129    pub enum FundRange {
130        Week => "week",
131        Month => "month",
132        ThreeMonths => "tmonth",
133        HalfYear => "hyear",
134        Year => "year",
135        TwoYears => "twoyear",
136        ThreeYears => "tyear",
137        FiveYears => "fyear",
138    }
139}
140
141wire_enum! {
142    /// Fund NAV series selection.
143    pub enum FundNavType {
144        Unit => "unit",
145        Adjusted => "adj",
146        UnitAndAdjusted => "unit,adj",
147    }
148}
149
150wire_enum! {
151    /// Fund manager performance range.
152    pub enum ManagerPerformanceRange {
153        Month => "month",
154        ThreeMonths => "tmonth",
155        Year => "year",
156        CurrentYear => "nowyear",
157        SinceInception => "now",
158    }
159}
160
161wire_enum! {
162    /// New fund offering subscription state.
163    pub enum OfferingStatus {
164        Active => "active",
165        Upcoming => "upcoming",
166    }
167}
168
169wire_enum! {
170    /// Actual disclosure scope returned for a fund-holder record.
171    pub enum HolderRecordScope {
172        Merged => "merged",
173        Separate => "separate",
174    }
175}
176
177wire_enum! {
178    /// Asset class used in a disclosed fund portfolio.
179    pub enum PortfolioAssetType {
180        Stock => "stock",
181        Bond => "bond",
182        Fund => "fund",
183    }
184}
185
186#[cfg(test)]
187mod tests {
188    use super::{CompanyId, Cursor, ManagerId, ReportType};
189
190    #[test]
191    fn endpoint_identifiers_have_distinct_validated_types() {
192        assert_eq!(ManagerId::new("manager-1").unwrap().as_str(), "manager-1");
193        assert_eq!(CompanyId::new("company-1").unwrap().as_str(), "company-1");
194        assert_eq!(
195            Cursor::new("opaque+/cursor==").unwrap().as_str(),
196            "opaque+/cursor=="
197        );
198        assert_eq!(ReportType::new("quarter").unwrap().as_str(), "quarter");
199        assert_eq!(ManagerId::new(" manager-1 ").unwrap().as_str(), "manager-1");
200        assert_eq!(
201            CompanyId::new("\tcompany-1\n").unwrap().as_str(),
202            "company-1"
203        );
204        assert_eq!(ReportType::new(" quarter ").unwrap().as_str(), "quarter");
205        assert_eq!(
206            Cursor::new(" opaque+/cursor== ").unwrap().as_str(),
207            " opaque+/cursor== "
208        );
209
210        assert!(ManagerId::new(" ").is_err());
211        assert!(CompanyId::new("").is_err());
212        assert!(Cursor::new("\t").is_err());
213        assert!(ReportType::new("\n").is_err());
214    }
215}