tango/resources/
itdashboard.rs

1//! `GET /api/itdashboard/` — federal IT investments from the
2//! IT Dashboard.
3
4use crate::client::Client;
5use crate::error::{Error, Result};
6use crate::internal::{apply_pagination, push_opt};
7use crate::pagination::{FetchFn, Page, PageStream};
8use crate::resources::agencies::urlencoding;
9use crate::Record;
10use bon::Builder;
11use std::collections::BTreeMap;
12use std::sync::Arc;
13
14/// Options for [`Client::list_itdashboard`] and [`Client::iterate_itdashboard`].
15///
16/// Filters are tier-gated by the API:
17/// - **Free:** [`search`](Self::search)
18/// - **Pro:** [`agency_code`](Self::agency_code), [`type_of_investment`](Self::type_of_investment),
19///   [`updated_time_after`](Self::updated_time_after), [`updated_time_before`](Self::updated_time_before)
20/// - **Business+:** [`agency_name`](Self::agency_name), [`cio_rating`](Self::cio_rating),
21///   [`cio_rating_max`](Self::cio_rating_max), [`performance_risk`](Self::performance_risk)
22///
23/// Hitting a gated filter on a lower tier returns a 403. CIO ratings:
24/// 1=High Risk, 2=Moderately High, 3=Medium, 4=Moderately Low, 5=Low.
25#[derive(Debug, Clone, Default, Builder, PartialEq, Eq)]
26#[non_exhaustive]
27pub struct ListItdashboardOptions {
28    /// 1-based page number.
29    #[builder(into)]
30    pub page: Option<u32>,
31    /// Page size (server caps at 100).
32    #[builder(into)]
33    pub limit: Option<u32>,
34    /// Keyset cursor.
35    #[builder(into)]
36    pub cursor: Option<String>,
37    /// Comma-separated field selector. Use
38    /// [`SHAPE_ITDASHBOARD_INVESTMENTS_MINIMAL`](crate::SHAPE_ITDASHBOARD_INVESTMENTS_MINIMAL)
39    /// or roll your own.
40    #[builder(into)]
41    pub shape: Option<String>,
42    /// Collapse nested objects into dot-separated keys.
43    #[builder(default)]
44    pub flat: bool,
45    /// When [`flat`](Self::flat) is also true, flatten list-valued fields.
46    #[builder(default)]
47    pub flat_lists: bool,
48
49    /// Free-text search (Free tier).
50    #[builder(into)]
51    pub search: Option<String>,
52    /// Agency code filter (Pro tier).
53    #[builder(into)]
54    pub agency_code: Option<String>,
55    /// Agency name filter (Business+ tier).
56    #[builder(into)]
57    pub agency_name: Option<String>,
58    /// Investment type filter (Pro tier).
59    #[builder(into)]
60    pub type_of_investment: Option<String>,
61
62    /// Lower bound on `updated_time` (Pro tier, ISO 8601).
63    #[builder(into)]
64    pub updated_time_after: Option<String>,
65    /// Upper bound on `updated_time` (Pro tier, ISO 8601).
66    #[builder(into)]
67    pub updated_time_before: Option<String>,
68
69    /// CIO rating filter (Business+ tier). Stringly typed to disambiguate
70    /// "unset" from numeric zero (the API accepts both numeric and stringified
71    /// integer values).
72    #[builder(into)]
73    pub cio_rating: Option<String>,
74    /// Upper bound on CIO rating (Business+ tier).
75    #[builder(into)]
76    pub cio_rating_max: Option<String>,
77    /// Performance-risk filter (Business+ tier).
78    #[builder(into)]
79    pub performance_risk: Option<String>,
80
81    /// Escape hatch for filter keys not yet first-classed on this struct.
82    #[builder(default)]
83    pub extra: BTreeMap<String, String>,
84}
85
86impl ListItdashboardOptions {
87    pub(crate) fn to_query(&self) -> Vec<(String, String)> {
88        let mut q = Vec::new();
89        apply_pagination(
90            &mut q,
91            self.page,
92            self.limit,
93            self.cursor.as_deref(),
94            self.shape.as_deref(),
95            self.flat,
96            self.flat_lists,
97        );
98        push_opt(&mut q, "search", self.search.as_deref());
99        push_opt(&mut q, "agency_code", self.agency_code.as_deref());
100        push_opt(&mut q, "agency_name", self.agency_name.as_deref());
101        push_opt(
102            &mut q,
103            "type_of_investment",
104            self.type_of_investment.as_deref(),
105        );
106        push_opt(
107            &mut q,
108            "updated_time_after",
109            self.updated_time_after.as_deref(),
110        );
111        push_opt(
112            &mut q,
113            "updated_time_before",
114            self.updated_time_before.as_deref(),
115        );
116        push_opt(&mut q, "cio_rating", self.cio_rating.as_deref());
117        push_opt(&mut q, "cio_rating_max", self.cio_rating_max.as_deref());
118        push_opt(&mut q, "performance_risk", self.performance_risk.as_deref());
119        for (k, v) in &self.extra {
120            if !v.is_empty() {
121                q.push((k.clone(), v.clone()));
122            }
123        }
124        q
125    }
126}
127
128/// Options for [`Client::get_itdashboard`].
129#[derive(Debug, Clone, Default, Builder, PartialEq, Eq)]
130#[non_exhaustive]
131pub struct GetItdashboardOptions {
132    /// Shape selector. When empty, the server returns its comprehensive default.
133    #[builder(into)]
134    pub shape: Option<String>,
135    /// Flatten nested objects into dot-separated keys.
136    #[builder(default)]
137    pub flat: bool,
138    /// When `flat=true`, also flatten list-valued nested fields.
139    #[builder(default)]
140    pub flat_lists: bool,
141}
142
143impl GetItdashboardOptions {
144    pub(crate) fn to_query(&self) -> Vec<(String, String)> {
145        let mut q = Vec::new();
146        push_opt(&mut q, "shape", self.shape.as_deref());
147        if self.flat {
148            q.push(("flat".into(), "true".into()));
149        }
150        if self.flat_lists {
151            q.push(("flat_lists".into(), "true".into()));
152        }
153        q
154    }
155}
156
157impl Client {
158    /// `GET /api/itdashboard/` — one page of federal IT investments.
159    pub async fn list_itdashboard(&self, opts: ListItdashboardOptions) -> Result<Page<Record>> {
160        let q = opts.to_query();
161        let bytes = self.get_bytes("/api/itdashboard/", &q).await?;
162        Page::decode(&bytes)
163    }
164
165    /// `GET /api/itdashboard/{uii}/` — fetch a single investment
166    /// by Unique Investment Identifier (UII).
167    pub async fn get_itdashboard(
168        &self,
169        uii: &str,
170        opts: Option<GetItdashboardOptions>,
171    ) -> Result<Record> {
172        if uii.is_empty() {
173            return Err(Error::Validation {
174                message: "get_itdashboard: uii is required".into(),
175                response: None,
176            });
177        }
178        let q = opts.unwrap_or_default().to_query();
179        let path = format!("/api/itdashboard/{}/", urlencoding(uii));
180        self.get_json::<Record>(&path, &q).await
181    }
182
183    /// Stream every IT Dashboard investment matching `opts`.
184    pub fn iterate_itdashboard(&self, opts: ListItdashboardOptions) -> PageStream<Record> {
185        let opts = Arc::new(opts);
186        let fetch: FetchFn<Record> = Box::new(move |client, page, cursor| {
187            let mut next = (*opts).clone();
188            next.page = page;
189            next.cursor = cursor;
190            Box::pin(async move { client.list_itdashboard(next).await })
191        });
192        PageStream::new(self.clone(), fetch)
193    }
194}
195
196#[cfg(test)]
197mod tests {
198    use super::*;
199
200    fn get_q(q: &[(String, String)], k: &str) -> Option<String> {
201        q.iter().find(|(kk, _)| kk == k).map(|(_, v)| v.clone())
202    }
203
204    #[test]
205    fn list_itdashboard_all_filters_emit() {
206        let opts = ListItdashboardOptions::builder()
207            .search("cloud")
208            .agency_code("009")
209            .agency_name("Department of State")
210            .type_of_investment("Major")
211            .updated_time_after("2024-01-01T00:00:00Z")
212            .updated_time_before("2024-12-31T23:59:59Z")
213            .cio_rating("3")
214            .cio_rating_max("5")
215            .performance_risk("2")
216            .build();
217        let q = opts.to_query();
218        assert_eq!(get_q(&q, "search").as_deref(), Some("cloud"));
219        assert_eq!(get_q(&q, "agency_code").as_deref(), Some("009"));
220        assert_eq!(
221            get_q(&q, "agency_name").as_deref(),
222            Some("Department of State")
223        );
224        assert_eq!(get_q(&q, "type_of_investment").as_deref(), Some("Major"));
225        assert_eq!(
226            get_q(&q, "updated_time_after").as_deref(),
227            Some("2024-01-01T00:00:00Z")
228        );
229        assert_eq!(
230            get_q(&q, "updated_time_before").as_deref(),
231            Some("2024-12-31T23:59:59Z")
232        );
233        assert_eq!(get_q(&q, "cio_rating").as_deref(), Some("3"));
234        assert_eq!(get_q(&q, "cio_rating_max").as_deref(), Some("5"));
235        assert_eq!(get_q(&q, "performance_risk").as_deref(), Some("2"));
236    }
237
238    #[test]
239    fn list_itdashboard_zero_value_omitted() {
240        let opts = ListItdashboardOptions::builder().build();
241        let q = opts.to_query();
242        assert!(q.is_empty(), "expected empty query, got {q:?}");
243    }
244
245    #[test]
246    fn list_itdashboard_shape_emits() {
247        let opts = ListItdashboardOptions::builder()
248            .shape(crate::SHAPE_ITDASHBOARD_INVESTMENTS_MINIMAL)
249            .build();
250        let q = opts.to_query();
251        assert_eq!(
252            get_q(&q, "shape").as_deref(),
253            Some(crate::SHAPE_ITDASHBOARD_INVESTMENTS_MINIMAL)
254        );
255    }
256
257    #[test]
258    fn list_itdashboard_cursor_wins_over_page() {
259        let opts = ListItdashboardOptions::builder()
260            .page(3u32)
261            .cursor("c0".to_string())
262            .build();
263        let q = opts.to_query();
264        assert_eq!(get_q(&q, "cursor").as_deref(), Some("c0"));
265        assert_eq!(get_q(&q, "page"), None);
266    }
267
268    #[test]
269    fn list_itdashboard_extra_emits() {
270        let mut extra = BTreeMap::new();
271        extra.insert("custom_x".to_string(), "xv".to_string());
272        let opts = ListItdashboardOptions::builder().extra(extra).build();
273        let q = opts.to_query();
274        assert!(q.contains(&("custom_x".into(), "xv".into())));
275    }
276
277    #[tokio::test]
278    async fn get_itdashboard_validates_empty_uii() {
279        let client = Client::builder().api_key("x").build().expect("client");
280        let err = client.get_itdashboard("", None).await.unwrap_err();
281        match err {
282            Error::Validation { message, .. } => {
283                assert!(message.contains("uii is required"));
284            }
285            other => panic!("expected Validation, got {other:?}"),
286        }
287    }
288}
tango/resources/itdashboard.rs

tango/resources/
itdashboard.rs
