jmap_mail_client/methods/
search_snippet.rs

1//! JMAP Mail — SearchSnippet/get method implementation on SessionClient.
2//!
3//! SearchSnippet/get (RFC 8621 §5) is not a standard /get method: it takes
4//! `filter` and either `threadIds` or `emailIds` instead of a plain `ids`
5//! array, and the response shape differs (no `state` field, no `notFound`).
6//! We therefore return `serde_json::Value` and let the caller deserialize.
7//!
8//! Each method follows the standard five-step pattern:
9//!   1. Validate arguments (defence-in-depth empty-state guards).
10//!   2. Call `self.session_parts()?` → `(api_url, account_id)`.
11//!   3. Build args JSON with `serde_json::json!({…})`.
12//!   4. Call `build_request(method_name, args, USING_MAIL)`.
13//!   5. Call `self.call_internal(api_url, &req).await?`.
14//!   6. Call `jmap_base_client::extract_response(&resp, CALL_ID)?`.
15
16use jmap_types::Id;
17
18impl super::SessionClient {
19    /// Fetch SearchSnippet objects (RFC 8621 §5 — SearchSnippet/get).
20    ///
21    /// `filter` is the same filter object used in `Email/query`. Either
22    /// `thread_ids` or `email_ids` (or both) may be provided to scope the
23    /// snippets; the server returns one [`SearchSnippet`](jmap_mail_types::SearchSnippet) per email in the
24    /// result set.
25    ///
26    /// Returns the raw response value because the SearchSnippet/get response
27    /// shape differs from the standard /get shape (no `state`, no `notFound`).
28    /// Callers should deserialize into `Vec<jmap_mail_types::SearchSnippet>` via
29    /// `response["list"].as_array()`.
30    pub async fn search_snippet_get(
31        &self,
32        account_id: Option<&Id>,
33        filter: serde_json::Value,
34        thread_ids: Option<&[Id]>,
35        email_ids: Option<&[Id]>,
36    ) -> Result<serde_json::Value, jmap_base_client::ClientError> {
37        let (api_url, session_account_id) = self.session_parts()?;
38        let effective_account_id: &str =
39            account_id.map(AsRef::as_ref).unwrap_or(session_account_id);
40        let mut args = serde_json::json!({
41            "accountId": effective_account_id,
42            "filter": filter,
43        });
44        if let Some(tids) = thread_ids {
45            args["threadIds"] =
46                serde_json::to_value(tids).expect("Id slice Serialize is infallible");
47        }
48        if let Some(eids) = email_ids {
49            args["emailIds"] =
50                serde_json::to_value(eids).expect("Id slice Serialize is infallible");
51        }
52        let req = super::build_request("SearchSnippet/get", args, super::USING_MAIL);
53        let resp = self.call_internal(api_url, &req).await?;
54        jmap_base_client::extract_response(&resp, super::CALL_ID)
55    }
56}
57
58// ---------------------------------------------------------------------------
59// Tests
60// ---------------------------------------------------------------------------
61
62#[cfg(test)]
63mod tests {
64    use serde_json::json;
65
66    // search_snippet_get_empty_email_id_returns_invalid_argument was deleted in
67    // JMAP-6by7.2 (typed-Id refactor): under `Option<&[Id]>` the empty-Id case
68    // becomes impossible to express through the typed API.
69
70    // Deleted in JMAP-tco1.5 as Pattern E (vacuous inline tests):
71    //   - search_snippet_get_request_shape
72    //   - search_snippet_get_with_thread_ids_request_shape
73    // Each hand-built `args = json!({...})` and fed it to `build_request`,
74    // never invoking the `search_snippet_get` production builder. Real
75    // production-path coverage for this method is tracked as a wiremock-smoke
76    // gap under JMAP-uuoi (no `tests/search_snippet_*.rs` smoke file exists
77    // yet). Specific-flag passthrough coverage that may be lost
78    // (`emailIds` vs `threadIds` scoping) is tracked under JMAP-uuoi for
79    // follow-up wiremock smoke tests.
80    //
81    // `build_request`, `CALL_ID`, and `USING_MAIL` themselves have their
82    // own focused tests in `methods/mod.rs`.
83
84    /// Oracle: SearchSnippet response JSON deserializes into SearchSnippet list.
85    /// RFC 8621 §5 example response shape.
86    #[test]
87    fn search_snippet_response_deserializes() {
88        // SearchSnippet/get response uses "accountId" and "list" per RFC 8621 §5.
89        let list_json = json!([
90            {
91                "emailId": "e1",
92                "subject": "Hello <mark>world</mark>",
93                "preview": "This is a <mark>world</mark>-class message."
94            },
95            {
96                "emailId": "e2"
97            }
98        ]);
99        let snippets: Vec<jmap_mail_types::SearchSnippet> =
100            serde_json::from_value(list_json).expect("must deserialize snippet list");
101        assert_eq!(snippets.len(), 2);
102        assert_eq!(snippets[0].email_id.as_ref(), "e1");
103        assert!(snippets[0].subject.is_some());
104        assert!(snippets[1].subject.is_none());
105    }
106}
jmap_mail_client/methods/search_snippet.rs

jmap_mail_client/methods/
search_snippet.rs
