jmap_client/
lib.rs

1/*
2 * Copyright Stalwart Labs LLC See the COPYING
3 * file at the top-level directory of this distribution.
4 *
5 * Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 * https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 * <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
8 * option. This file may not be copied, modified, or distributed
9 * except according to those terms.
10 */
11
12//! # jmap-client
13//!
14//! [![crates.io](https://img.shields.io/crates/v/jmap-client)](https://crates.io/crates/jmap-client)
15//! [![build](https://github.com/stalwartlabs/jmap-client/actions/workflows/rust.yml/badge.svg)](https://github.com/stalwartlabs/jmap-client/actions/workflows/rust.yml)
16//! [![docs.rs](https://img.shields.io/docsrs/jmap-client)](https://docs.rs/jmap-client)
17//! [![crates.io](https://img.shields.io/crates/l/jmap-client)](http://www.apache.org/licenses/LICENSE-2.0)
18//!
19//! _jmap-client_ is a **JSON Meta Application Protocol (JMAP) library** written in Rust. The library is a full implementation of the JMAP RFCs including:
20//!
21//! - JMAP Core ([RFC 8620](https://datatracker.ietf.org/doc/html/rfc8620))
22//! - JMAP for Mail ([RFC 8621](https://datatracker.ietf.org/doc/html/rfc8621))
23//! - JMAP over WebSocket ([RFC 8887](https://datatracker.ietf.org/doc/html/rfc8887)).
24//! - JMAP for Sieve Scripts ([DRAFT-SIEVE-12](https://www.ietf.org/archive/id/draft-ietf-jmap-sieve-12.html)).
25//!
26//! Features:
27//!
28//! - Async and blocking support (use the cargo feature ``blocking`` to enable blocking).
29//! - WebSocket async streams (use the cargo feature ``websockets`` to enable JMAP over WebSocket).
30//! - EventSource async streams.
31//! - Helper functions to reduce boilerplate code and quickly build JMAP requests.
32//! - Fast parsing and encoding of JMAP requests.
33//!
34//! ## Usage Example
35//!
36//! ```rust
37//!     // Connect to the JMAP server using Basic authentication.
38//!     // (just for demonstration purposes, Bearer tokens should be used instead)
39//!     let client = Client::new()
40//!         .credentials(("john@example.org", "secret"))
41//!         .connect("https://jmap.example.org")
42//!         .await
43//!         .unwrap();
44//!
45//!     // Create a mailbox.
46//!     let mailbox_id = client
47//!         .mailbox_create("My Mailbox", None::<String>, Role::None)
48//!         .await
49//!         .unwrap()
50//!         .take_id();
51//!
52//!     // Import a message into the mailbox.
53//!     client
54//!         .email_import(
55//!             b"From: john@example.org\nSubject: test\n\n test".to_vec(),
56//!             [&mailbox_id],
57//!             ["$draft"].into(),
58//!             None,
59//!         )
60//!         .await
61//!         .unwrap();
62//!
63//!     // Obtain all e-mail ids matching a filter.
64//!     let email_id = client
65//!         .email_query(
66//!             Filter::and([
67//!                 email::query::Filter::subject("test"),
68//!                 email::query::Filter::in_mailbox(&mailbox_id),
69//!                 email::query::Filter::has_keyword("$draft"),
70//!             ])
71//!             .into(),
72//!             [email::query::Comparator::from()].into(),
73//!         )
74//!         .await
75//!         .unwrap()
76//!         .take_ids()
77//!         .pop()
78//!         .unwrap();
79//!
80//!     // Fetch an e-mail message.
81//!     let email = client
82//!         .email_get(
83//!             &email_id,
84//!             [Property::Subject, Property::Preview, Property::Keywords].into(),
85//!         )
86//!         .await
87//!         .unwrap()
88//!         .unwrap();
89//!     assert_eq!(email.preview().unwrap(), "test");
90//!     assert_eq!(email.subject().unwrap(), "test");
91//!     assert_eq!(email.keywords(), ["$draft"]);
92//!
93//!     // Fetch only the updated properties of all mailboxes that changed
94//!     // since a state.
95//!     let mut request = client.build();
96//!     let changes_request = request.changes_mailbox("n").max_changes(0);
97//!     let properties_ref = changes_request.updated_properties_reference();
98//!     let updated_ref = changes_request.updated_reference();
99//!     request
100//!         .get_mailbox()
101//!         .ids_ref(updated_ref)
102//!         .properties_ref(properties_ref);
103//!     for mailbox in request
104//!         .send()
105//!         .await
106//!         .unwrap()
107//!         .unwrap_method_responses()
108//!         .pop()
109//!         .unwrap()
110//!         .unwrap_get_mailbox()
111//!         .unwrap()
112//!         .take_list()
113//!     {
114//!         println!("Changed mailbox: {:#?}", mailbox);
115//!     }
116//!
117//!     // Delete the mailbox including any messages
118//!     client.mailbox_destroy(&mailbox_id, true).await.unwrap();
119//!
120//!     // Open an EventSource connection with the JMAP server.
121//!     let mut stream = client
122//!         .event_source(
123//!             [
124//!                 DataType::Email,
125//!                 DataType::EmailDelivery,
126//!                 DataType::Mailbox,
127//!                 DataType::EmailSubmission,
128//!                 DataType::Identity,
129//!             ]
130//!             .into(),
131//!             false,
132//!             60.into(),
133//!             None,
134//!         )
135//!         .await
136//!         .unwrap();
137//!
138//!     // Consume events received over EventSource.
139//!     while let Some(event) = stream.next().await {
140//!         let changes = event.unwrap();
141//!         println!("-> Change id: {:?}", changes.id());
142//!         for account_id in changes.changed_accounts() {
143//!             println!(" Account {} has changes:", account_id);
144//!             if let Some(account_changes) = changes.changes(account_id) {
145//!                 for (type_state, state_id) in account_changes {
146//!                     println!("   Type {:?} has a new state {}.", type_state, state_id);
147//!                 }
148//!             }
149//!         }
150//!     }
151//! ```
152//!
153//! More examples available under the [examples](examples) directory.
154//!
155//! ## Testing
156//!
157//! To run the testsuite:
158//!
159//! ```bash
160//!  $ cargo test --all-features
161//! ```
162//!
163//! ## Conformed RFCs
164//!
165//! - [RFC 8620 - The JSON Meta Application Protocol (JMAP)](https://datatracker.ietf.org/doc/html/rfc8620)
166//! - [RFC 8621 - The JSON Meta Application Protocol (JMAP) for Mail](https://datatracker.ietf.org/doc/html/rfc8621)
167//! - [RFC 8887 - A JSON Meta Application Protocol (JMAP) Subprotocol for WebSocket](https://datatracker.ietf.org/doc/html/rfc8887)
168//!
169//! ## License
170//!
171//! Licensed under either of
172//!
173//!  * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
174//!  * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
175//!
176//! at your option.
177//!
178//! ## Copyright
179//!
180//! Copyright (C) 2022, Stalwart Labs LLC
181//!
182
183#[forbid(unsafe_code)]
184pub mod blob;
185pub mod client;
186pub mod core;
187pub mod email;
188pub mod email_submission;
189#[cfg(feature = "async")]
190pub mod event_source;
191pub mod identity;
192pub mod mailbox;
193pub mod principal;
194pub mod push_subscription;
195pub mod sieve;
196pub mod thread;
197pub mod vacation_response;
198
199use crate::core::error::MethodError;
200use crate::core::error::ProblemDetails;
201use crate::core::set::SetError;
202use ahash::AHashMap;
203use serde::{Deserialize, Serialize};
204use std::fmt::Display;
205
206#[cfg(feature = "websockets")]
207pub mod client_ws;
208
209#[derive(Debug, Clone, Serialize, Deserialize, Hash, PartialEq, Eq)]
210pub enum URI {
211    #[serde(rename = "urn:ietf:params:jmap:core")]
212    Core,
213    #[serde(rename = "urn:ietf:params:jmap:mail")]
214    Mail,
215    #[serde(rename = "urn:ietf:params:jmap:submission")]
216    Submission,
217    #[serde(rename = "urn:ietf:params:jmap:vacationresponse")]
218    VacationResponse,
219    #[serde(rename = "urn:ietf:params:jmap:contacts")]
220    Contacts,
221    #[serde(rename = "urn:ietf:params:jmap:calendars")]
222    Calendars,
223    #[serde(rename = "urn:ietf:params:jmap:websocket")]
224    WebSocket,
225    #[serde(rename = "urn:ietf:params:jmap:sieve")]
226    Sieve,
227    #[serde(rename = "urn:ietf:params:jmap:blob")]
228    Blob,
229    #[serde(rename = "urn:ietf:params:jmap:quota")]
230    Quota,
231    #[serde(rename = "urn:ietf:params:jmap:principals")]
232    Principals,
233    #[serde(rename = "urn:ietf:params:jmap:principals:owner")]
234    PrincipalsOwner,
235}
236
237impl AsRef<str> for URI {
238    fn as_ref(&self) -> &str {
239        match self {
240            URI::Core => "urn:ietf:params:jmap:core",
241            URI::Mail => "urn:ietf:params:jmap:mail",
242            URI::Submission => "urn:ietf:params:jmap:submission",
243            URI::VacationResponse => "urn:ietf:params:jmap:vacationresponse",
244            URI::Contacts => "urn:ietf:params:jmap:contacts",
245            URI::Calendars => "urn:ietf:params:jmap:calendars",
246            URI::WebSocket => "urn:ietf:params:jmap:websocket",
247            URI::Sieve => "urn:ietf:params:jmap:sieve",
248            URI::Blob => "urn:ietf:params:jmap:blob",
249            URI::Quota => "urn:ietf:params:jmap:quota",
250            URI::Principals => "urn:ietf:params:jmap:principals",
251            URI::PrincipalsOwner => "urn:ietf:params:jmap:principals:owner",
252        }
253    }
254}
255
256#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
257pub enum Method {
258    #[serde(rename = "Core/echo")]
259    Echo,
260    #[serde(rename = "Blob/copy")]
261    CopyBlob,
262    #[serde(rename = "PushSubscription/get")]
263    GetPushSubscription,
264    #[serde(rename = "PushSubscription/set")]
265    SetPushSubscription,
266    #[serde(rename = "Mailbox/get")]
267    GetMailbox,
268    #[serde(rename = "Mailbox/changes")]
269    ChangesMailbox,
270    #[serde(rename = "Mailbox/query")]
271    QueryMailbox,
272    #[serde(rename = "Mailbox/queryChanges")]
273    QueryChangesMailbox,
274    #[serde(rename = "Mailbox/set")]
275    SetMailbox,
276    #[serde(rename = "Thread/get")]
277    GetThread,
278    #[serde(rename = "Thread/changes")]
279    ChangesThread,
280    #[serde(rename = "Email/get")]
281    GetEmail,
282    #[serde(rename = "Email/changes")]
283    ChangesEmail,
284    #[serde(rename = "Email/query")]
285    QueryEmail,
286    #[serde(rename = "Email/queryChanges")]
287    QueryChangesEmail,
288    #[serde(rename = "Email/set")]
289    SetEmail,
290    #[serde(rename = "Email/copy")]
291    CopyEmail,
292    #[serde(rename = "Email/import")]
293    ImportEmail,
294    #[serde(rename = "Email/parse")]
295    ParseEmail,
296    #[serde(rename = "SearchSnippet/get")]
297    GetSearchSnippet,
298    #[serde(rename = "Identity/get")]
299    GetIdentity,
300    #[serde(rename = "Identity/changes")]
301    ChangesIdentity,
302    #[serde(rename = "Identity/set")]
303    SetIdentity,
304    #[serde(rename = "EmailSubmission/get")]
305    GetEmailSubmission,
306    #[serde(rename = "EmailSubmission/changes")]
307    ChangesEmailSubmission,
308    #[serde(rename = "EmailSubmission/query")]
309    QueryEmailSubmission,
310    #[serde(rename = "EmailSubmission/queryChanges")]
311    QueryChangesEmailSubmission,
312    #[serde(rename = "EmailSubmission/set")]
313    SetEmailSubmission,
314    #[serde(rename = "VacationResponse/get")]
315    GetVacationResponse,
316    #[serde(rename = "VacationResponse/set")]
317    SetVacationResponse,
318    #[serde(rename = "SieveScript/get")]
319    GetSieveScript,
320    #[serde(rename = "SieveScript/set")]
321    SetSieveScript,
322    #[serde(rename = "SieveScript/query")]
323    QuerySieveScript,
324    #[serde(rename = "SieveScript/validate")]
325    ValidateSieveScript,
326    #[serde(rename = "Principal/get")]
327    GetPrincipal,
328    #[serde(rename = "Principal/changes")]
329    ChangesPrincipal,
330    #[serde(rename = "Principal/query")]
331    QueryPrincipal,
332    #[serde(rename = "Principal/queryChanges")]
333    QueryChangesPrincipal,
334    #[serde(rename = "Principal/set")]
335    SetPrincipal,
336    #[serde(rename = "error")]
337    Error,
338}
339
340#[derive(Debug, Serialize, Deserialize, Eq, PartialEq, Hash, Clone)]
341pub enum DataType {
342    #[serde(rename = "Email")]
343    Email = 0,
344    #[serde(rename = "EmailDelivery")]
345    EmailDelivery = 1,
346    #[serde(rename = "EmailSubmission")]
347    EmailSubmission = 2,
348    #[serde(rename = "Mailbox")]
349    Mailbox = 3,
350    #[serde(rename = "Thread")]
351    Thread = 4,
352    #[serde(rename = "Identity")]
353    Identity = 5,
354    #[serde(rename = "Core")]
355    Core = 6,
356    #[serde(rename = "PushSubscription")]
357    PushSubscription = 7,
358    #[serde(rename = "SearchSnippet")]
359    SearchSnippet = 8,
360    #[serde(rename = "VacationResponse")]
361    VacationResponse = 9,
362    #[serde(rename = "MDN")]
363    Mdn = 10,
364    #[serde(rename = "Quota")]
365    Quota = 11,
366    #[serde(rename = "SieveScript")]
367    SieveScript = 12,
368    #[serde(rename = "Calendar")]
369    Calendar = 13,
370    #[serde(rename = "CalendarEvent")]
371    CalendarEvent = 14,
372    #[serde(rename = "CalendarEventNotification")]
373    CalendarEventNotification = 15,
374    #[serde(rename = "AddressBook")]
375    AddressBook = 16,
376    #[serde(rename = "ContactCard")]
377    ContactCard = 17,
378    #[serde(rename = "FileNode")]
379    FileNode = 18,
380    #[serde(rename = "Principal")]
381    Principal = 19,
382    #[serde(rename = "ShareNotification")]
383    ShareNotification = 20,
384    #[serde(rename = "ParticipantIdentity")]
385    ParticipantIdentity = 21,
386    #[serde(rename = "CalendarAlert")]
387    CalendarAlert = 22,
388}
389
390#[derive(Serialize, Deserialize, Debug)]
391#[serde(tag = "@type")]
392pub enum PushObject {
393    StateChange {
394        changed: AHashMap<String, AHashMap<DataType, String>>,
395    },
396    EmailPush {
397        #[serde(rename = "accountId")]
398        account_id: String,
399        email: serde_json::Value,
400    },
401    CalendarAlert(CalendarAlert),
402    Group {
403        entries: Vec<PushObject>,
404    },
405}
406
407#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
408pub struct CalendarAlert {
409    #[serde(rename = "accountId")]
410    pub account_id: String,
411    #[serde(rename = "calendarEventId")]
412    pub calendar_event_id: String,
413    pub uid: String,
414    #[serde(rename = "recurrenceId")]
415    pub recurrence_id: Option<String>,
416    #[serde(rename = "alertId")]
417    pub alert_id: String,
418}
419
420#[derive(Debug, Clone)]
421pub struct Get;
422#[derive(Debug, Clone)]
423pub struct Set;
424
425pub type Result<T> = std::result::Result<T, Error>;
426
427#[derive(Debug)]
428pub enum Error {
429    Transport(reqwest::Error),
430    Parse(serde_json::Error),
431    Internal(String),
432    Problem(Box<ProblemDetails>),
433    Server(String),
434    Method(MethodError),
435    Set(SetError<String>),
436    #[cfg(feature = "websockets")]
437    WebSocket(tokio_tungstenite::tungstenite::error::Error),
438}
439
440impl std::error::Error for Error {}
441
442impl From<reqwest::Error> for Error {
443    fn from(e: reqwest::Error) -> Self {
444        Error::Transport(e)
445    }
446}
447
448impl From<serde_json::Error> for Error {
449    fn from(e: serde_json::Error) -> Self {
450        Error::Parse(e)
451    }
452}
453
454impl From<MethodError> for Error {
455    fn from(e: MethodError) -> Self {
456        Error::Method(e)
457    }
458}
459
460impl From<ProblemDetails> for Error {
461    fn from(e: ProblemDetails) -> Self {
462        Error::Problem(Box::new(e))
463    }
464}
465
466impl From<SetError<String>> for Error {
467    fn from(e: SetError<String>) -> Self {
468        Error::Set(e)
469    }
470}
471
472impl From<&str> for Error {
473    fn from(s: &str) -> Self {
474        Error::Internal(s.to_string())
475    }
476}
477
478#[cfg(feature = "websockets")]
479impl From<tokio_tungstenite::tungstenite::error::Error> for Error {
480    fn from(e: tokio_tungstenite::tungstenite::error::Error) -> Self {
481        Error::WebSocket(e)
482    }
483}
484
485impl Display for Error {
486    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
487        match self {
488            Error::Transport(e) => write!(f, "Transport error: {}", e),
489            Error::Parse(e) => write!(f, "Parse error: {}", e),
490            Error::Internal(e) => write!(f, "Internal error: {}", e),
491            Error::Problem(e) => write!(f, "Request failed: {}", e),
492            Error::Server(e) => write!(f, "Server failed: {}", e),
493            Error::Method(e) => write!(f, "Request failed: {}", e),
494            Error::Set(e) => write!(f, "Set failed: {}", e),
495            #[cfg(feature = "websockets")]
496            Error::WebSocket(e) => write!(f, "WebSockets error: {}", e),
497        }
498    }
499}
500
501impl Display for DataType {
502    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
503        match self {
504            DataType::Mailbox => write!(f, "Mailbox"),
505            DataType::Thread => write!(f, "Thread"),
506            DataType::Email => write!(f, "Email"),
507            DataType::EmailDelivery => write!(f, "EmailDelivery"),
508            DataType::Identity => write!(f, "Identity"),
509            DataType::EmailSubmission => write!(f, "EmailSubmission"),
510            DataType::CalendarAlert => write!(f, "CalendarAlert"),
511            DataType::Core => write!(f, "Core"),
512            DataType::PushSubscription => write!(f, "PushSubscription"),
513            DataType::SearchSnippet => write!(f, "SearchSnippet"),
514            DataType::VacationResponse => write!(f, "VacationResponse"),
515            DataType::Mdn => write!(f, "MDN"),
516            DataType::Quota => write!(f, "Quota"),
517            DataType::SieveScript => write!(f, "SieveScript"),
518            DataType::Calendar => write!(f, "Calendar"),
519            DataType::CalendarEvent => write!(f, "CalendarEvent"),
520            DataType::CalendarEventNotification => write!(f, "CalendarEventNotification"),
521            DataType::AddressBook => write!(f, "AddressBook"),
522            DataType::ContactCard => write!(f, "ContactCard"),
523            DataType::FileNode => write!(f, "FileNode"),
524            DataType::Principal => write!(f, "Principal"),
525            DataType::ShareNotification => write!(f, "ShareNotification"),
526            DataType::ParticipantIdentity => write!(f, "ParticipantIdentity"),
527        }
528    }
529}
jmap_client/lib.rs

jmap_client/
lib.rs
