tango/resources/
gsa.rs

1//! `GET /api/gsa_elibrary_contracts/` — GSA eLibrary contract listings.
2
3use crate::client::Client;
4use crate::error::{Error, Result};
5use crate::internal::{apply_pagination, push_opt};
6use crate::pagination::{FetchFn, Page, PageStream};
7use crate::resources::agencies::urlencoding;
8use crate::Record;
9use bon::Builder;
10use std::collections::BTreeMap;
11use std::sync::Arc;
12
13/// Options for [`Client::list_gsa_elibrary_contracts`] and
14/// [`Client::iterate_gsa_elibrary_contracts`].
15#[derive(Debug, Clone, Default, Builder, PartialEq, Eq)]
16#[non_exhaustive]
17pub struct ListGsaElibraryContractsOptions {
18    /// 1-based page number.
19    #[builder(into)]
20    pub page: Option<u32>,
21    /// Page size (server caps at 100).
22    #[builder(into)]
23    pub limit: Option<u32>,
24    /// Keyset cursor.
25    #[builder(into)]
26    pub cursor: Option<String>,
27    /// Comma-separated field selector. Use
28    /// [`SHAPE_GSA_ELIBRARY_CONTRACTS_MINIMAL`](crate::SHAPE_GSA_ELIBRARY_CONTRACTS_MINIMAL)
29    /// or roll your own.
30    #[builder(into)]
31    pub shape: Option<String>,
32    /// Collapse nested objects into dot-separated keys.
33    #[builder(default)]
34    pub flat: bool,
35    /// When [`flat`](Self::flat) is also true, flatten list-valued fields.
36    #[builder(default)]
37    pub flat_lists: bool,
38
39    /// GSA schedule filter (e.g. `"MAS"`).
40    #[builder(into)]
41    pub schedule: Option<String>,
42    /// Contract-number filter.
43    #[builder(into)]
44    pub contract_number: Option<String>,
45    /// Internal Tango key filter.
46    #[builder(into)]
47    pub key: Option<String>,
48    /// Procurement Instrument Identifier filter.
49    #[builder(into)]
50    pub piid: Option<String>,
51    /// Recipient UEI filter.
52    #[builder(into)]
53    pub uei: Option<String>,
54    /// Special Item Number filter.
55    #[builder(into)]
56    pub sin: Option<String>,
57    /// Free-text search filter.
58    #[builder(into)]
59    pub search: Option<String>,
60    /// Server-side sort spec (prefix `-` for descending).
61    #[builder(into)]
62    pub ordering: Option<String>,
63
64    /// Escape hatch for filter keys not yet first-classed on this struct.
65    #[builder(default)]
66    pub extra: BTreeMap<String, String>,
67}
68
69impl ListGsaElibraryContractsOptions {
70    pub(crate) fn to_query(&self) -> Vec<(String, String)> {
71        let mut q = Vec::new();
72        apply_pagination(
73            &mut q,
74            self.page,
75            self.limit,
76            self.cursor.as_deref(),
77            self.shape.as_deref(),
78            self.flat,
79            self.flat_lists,
80        );
81        push_opt(&mut q, "schedule", self.schedule.as_deref());
82        push_opt(&mut q, "contract_number", self.contract_number.as_deref());
83        push_opt(&mut q, "key", self.key.as_deref());
84        push_opt(&mut q, "piid", self.piid.as_deref());
85        push_opt(&mut q, "uei", self.uei.as_deref());
86        push_opt(&mut q, "sin", self.sin.as_deref());
87        push_opt(&mut q, "search", self.search.as_deref());
88        push_opt(&mut q, "ordering", self.ordering.as_deref());
89        for (k, v) in &self.extra {
90            if !v.is_empty() {
91                q.push((k.clone(), v.clone()));
92            }
93        }
94        q
95    }
96}
97
98/// Options for [`Client::get_gsa_elibrary_contract`].
99#[derive(Debug, Clone, Default, Builder, PartialEq, Eq)]
100#[non_exhaustive]
101pub struct GetGsaElibraryContractOptions {
102    /// Shape selector. When empty, the server returns its comprehensive default.
103    #[builder(into)]
104    pub shape: Option<String>,
105    /// Flatten nested objects into dot-separated keys.
106    #[builder(default)]
107    pub flat: bool,
108    /// When `flat=true`, also flatten list-valued nested fields.
109    #[builder(default)]
110    pub flat_lists: bool,
111}
112
113impl GetGsaElibraryContractOptions {
114    pub(crate) fn to_query(&self) -> Vec<(String, String)> {
115        let mut q = Vec::new();
116        push_opt(&mut q, "shape", self.shape.as_deref());
117        if self.flat {
118            q.push(("flat".into(), "true".into()));
119        }
120        if self.flat_lists {
121            q.push(("flat_lists".into(), "true".into()));
122        }
123        q
124    }
125}
126
127impl Client {
128    /// `GET /api/gsa_elibrary_contracts/` — one page of GSA eLibrary contracts.
129    pub async fn list_gsa_elibrary_contracts(
130        &self,
131        opts: ListGsaElibraryContractsOptions,
132    ) -> Result<Page<Record>> {
133        let q = opts.to_query();
134        self.get_page("/api/gsa_elibrary_contracts/", &q).await
135    }
136
137    /// `GET /api/gsa_elibrary_contracts/{uuid}/` — fetch a single GSA eLibrary
138    /// contract by UUID.
139    pub async fn get_gsa_elibrary_contract(
140        &self,
141        uuid: &str,
142        opts: Option<GetGsaElibraryContractOptions>,
143    ) -> Result<Record> {
144        if uuid.is_empty() {
145            return Err(Error::Validation {
146                message: "get_gsa_elibrary_contract: uuid is required".into(),
147                response: None,
148            });
149        }
150        let q = opts.unwrap_or_default().to_query();
151        let path = format!("/api/gsa_elibrary_contracts/{}/", urlencoding(uuid));
152        self.get_json::<Record>(&path, &q).await
153    }
154
155    /// Stream every GSA eLibrary contract matching `opts`.
156    pub fn iterate_gsa_elibrary_contracts(
157        &self,
158        opts: ListGsaElibraryContractsOptions,
159    ) -> PageStream<Record> {
160        let opts = Arc::new(opts);
161        let fetch: FetchFn<Record> = Box::new(move |client, page, cursor| {
162            let mut next = (*opts).clone();
163            next.page = page;
164            next.cursor = cursor;
165            Box::pin(async move { client.list_gsa_elibrary_contracts(next).await })
166        });
167        PageStream::new(self.clone(), fetch)
168    }
169}
170
171#[cfg(test)]
172mod tests {
173    use super::*;
174
175    fn get_q(q: &[(String, String)], k: &str) -> Option<String> {
176        q.iter().find(|(kk, _)| kk == k).map(|(_, v)| v.clone())
177    }
178
179    #[test]
180    fn list_gsa_all_filters_emit() {
181        let opts = ListGsaElibraryContractsOptions::builder()
182            .schedule("MAS")
183            .contract_number("GS-35F-0119Y")
184            .key("internal-key")
185            .piid("GS35F0119Y")
186            .uei("UEI12345")
187            .sin("54151S")
188            .search("cyber")
189            .ordering("-contract_number")
190            .build();
191        let q = opts.to_query();
192        assert_eq!(get_q(&q, "schedule").as_deref(), Some("MAS"));
193        assert_eq!(
194            get_q(&q, "contract_number").as_deref(),
195            Some("GS-35F-0119Y")
196        );
197        assert_eq!(get_q(&q, "key").as_deref(), Some("internal-key"));
198        assert_eq!(get_q(&q, "piid").as_deref(), Some("GS35F0119Y"));
199        assert_eq!(get_q(&q, "uei").as_deref(), Some("UEI12345"));
200        assert_eq!(get_q(&q, "sin").as_deref(), Some("54151S"));
201        assert_eq!(get_q(&q, "search").as_deref(), Some("cyber"));
202        assert_eq!(get_q(&q, "ordering").as_deref(), Some("-contract_number"));
203    }
204
205    #[test]
206    fn list_gsa_zero_value_omitted() {
207        let opts = ListGsaElibraryContractsOptions::builder().build();
208        let q = opts.to_query();
209        assert!(q.is_empty(), "expected empty query, got {q:?}");
210    }
211
212    #[test]
213    fn list_gsa_shape_emits() {
214        let opts = ListGsaElibraryContractsOptions::builder()
215            .shape(crate::SHAPE_GSA_ELIBRARY_CONTRACTS_MINIMAL)
216            .build();
217        let q = opts.to_query();
218        assert_eq!(
219            get_q(&q, "shape").as_deref(),
220            Some(crate::SHAPE_GSA_ELIBRARY_CONTRACTS_MINIMAL)
221        );
222    }
223
224    #[test]
225    fn list_gsa_cursor_wins_over_page() {
226        let opts = ListGsaElibraryContractsOptions::builder()
227            .page(4u32)
228            .cursor("c0".to_string())
229            .build();
230        let q = opts.to_query();
231        assert_eq!(get_q(&q, "cursor").as_deref(), Some("c0"));
232        assert_eq!(get_q(&q, "page"), None);
233    }
234
235    #[test]
236    fn list_gsa_extra_emits() {
237        let mut extra = BTreeMap::new();
238        extra.insert("custom_x".to_string(), "xv".to_string());
239        let opts = ListGsaElibraryContractsOptions::builder()
240            .extra(extra)
241            .build();
242        let q = opts.to_query();
243        assert!(q.contains(&("custom_x".into(), "xv".into())));
244    }
245
246    #[tokio::test]
247    async fn get_gsa_validates_empty_uuid() {
248        let client = Client::builder().api_key("x").build().expect("client");
249        let err = client
250            .get_gsa_elibrary_contract("", None)
251            .await
252            .unwrap_err();
253        match err {
254            Error::Validation { message, .. } => {
255                assert!(message.contains("uuid is required"));
256            }
257            other => panic!("expected Validation, got {other:?}"),
258        }
259    }
260}
tango/resources/gsa.rs

tango/resources/
gsa.rs
