jmap_mail_client/
lib.rs

1//! jmap-mail-client — RFC 8621 JMAP for Mail method implementations.
2//!
3//! Depends on jmap-base-client for transport, auth, and session.
4//! See PLAN.md for the full implementation plan.
5//!
6//! # Usage
7//!
8//! ```rust,no_run
9//! # use jmap_mail_client::JmapMailExt;
10//! # async fn example(client: jmap_base_client::JmapClient) -> Result<(), jmap_base_client::ClientError> {
11//! let session = client.fetch_session().await?;
12//! let sc = client.with_mail_session(session);
13//! // Fetch Email metadata. None ids = fetch all (typically scoped via /query first).
14//! let emails = sc.email_get(None, None, None).await?;
15//! # let _ = emails;
16//! # Ok(())
17//! # }
18//! ```
19
20#![forbid(unsafe_code)]
21
22pub mod methods;
23
24pub use jmap_base_client::ClientError;
25pub use methods::{
26    AddedItem, ChangesResponse, EmailCopyParams, EmailGetParams, EmailImportCreated,
27    EmailImportInput, EmailImportResponse, EmailParseParams, EmailParseResponse,
28    EmailSubmissionSetParams, GetResponse, MailboxSetParams, QueryChangesResponse, QueryResponse,
29    SessionClient, SetError, SetResponse,
30};
31
32/// Extension trait adding RFC 8621 (JMAP for Mail) methods to [`jmap_base_client::JmapClient`].
33///
34/// Import this trait to use: `use jmap_mail_client::JmapMailExt;`
35///
36/// All JMAP Mail method calls are made through the [`SessionClient`] returned
37/// by [`with_mail_session`](JmapMailExt::with_mail_session).
38///
39/// This trait is **sealed**: implementations outside this crate are not
40/// permitted. The crate adds an `impl` only for
41/// [`jmap_base_client::JmapClient`]. Sealing prevents downstream
42/// divergence (e.g. `impl JmapMailExt for MySimulator`) and keeps
43/// adding methods to the trait a non-breaking change.
44pub trait JmapMailExt: sealed::Sealed {
45    /// Create a [`SessionClient`] bound to this client and session.
46    ///
47    /// All JMAP Mail method calls are made through the returned [`SessionClient`].
48    ///
49    /// # Deferred session-capability validation
50    ///
51    /// This constructor accepts ANY [`jmap_base_client::Session`],
52    /// including one whose advertised capabilities do not include
53    /// `urn:ietf:params:jmap:mail` or whose `primaryAccounts` map has
54    /// no entry for the mail capability. The constructor performs no
55    /// up-front validation and never fails — its return type is the
56    /// infallible [`methods::SessionClient`], not a `Result`.
57    ///
58    /// Capability and primary-account validation is deferred to every
59    /// individual method call on the returned [`SessionClient`]. If
60    /// the session is unsuitable, those per-method calls return
61    /// [`ClientError::InvalidSession`] with a description like
62    /// `"no primary account for urn:ietf:params:jmap:mail"`.
63    ///
64    /// Callers that want to guard at the binding site can pre-check
65    /// the session before calling this method:
66    ///
67    /// ```ignore
68    /// if session
69    ///     .primary_account_id("urn:ietf:params:jmap:mail")
70    ///     .is_none()
71    /// {
72    ///     // Session does not advertise a primary account for mail;
73    ///     // every subsequent SessionClient method call would fail
74    ///     // with ClientError::InvalidSession. Refuse here.
75    ///     return Err(MyAppError::SessionMissingMailCapability);
76    /// }
77    /// let sc = client.with_mail_session(session);
78    /// ```
79    ///
80    /// `SessionClient::mail_account_id()` exposes the same check as a
81    /// convenience accessor on an already-bound SessionClient.
82    fn with_mail_session(&self, session: jmap_base_client::Session) -> methods::SessionClient;
83}
84
85impl JmapMailExt for jmap_base_client::JmapClient {
86    fn with_mail_session(&self, session: jmap_base_client::Session) -> methods::SessionClient {
87        methods::SessionClient {
88            client: self.clone(),
89            session,
90        }
91    }
92}
93
94mod sealed {
95    /// Sealing-trait for [`super::JmapMailExt`] — see the trait's rustdoc.
96    pub trait Sealed {}
97    impl Sealed for ::jmap_base_client::JmapClient {}
98}
jmap_mail_client/lib.rs

jmap_mail_client/
lib.rs
