jmap_contacts_client/
lib.rs

1//! jmap-contacts-client — JMAP Contacts 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_contacts_client::JmapContactsExt;
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_contacts_session(session);
13//! // List all address books in the primary account.
14//! let address_books = sc.address_book_get(None, None).await?;
15//! # let _ = address_books;
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, AddressBookSetParams, ChangesResponse, GetResponse, QueryChangesResponse,
27    QueryResponse, SessionClient, SetError, SetResponse,
28};
29
30/// Extension trait adding JMAP Contacts methods to [`jmap_base_client::JmapClient`].
31///
32/// Import this trait to use: `use jmap_contacts_client::JmapContactsExt;`
33///
34/// All JMAP Contacts method calls are made through the [`SessionClient`]
35/// returned by [`with_contacts_session`](JmapContactsExt::with_contacts_session).
36/// This trait is **sealed**: implementations outside this crate are not
37/// permitted. The crate adds an `impl` only for
38/// [`jmap_base_client::JmapClient`]. Sealing prevents downstream
39/// divergence (e.g. `impl JmapContactsExt for MySimulator`) and keeps
40/// adding methods to the trait a non-breaking change.
41pub trait JmapContactsExt: sealed::Sealed {
42    /// Create a [`SessionClient`] bound to this client and session.
43    ///
44    /// All JMAP Contacts method calls are made through the returned
45    /// [`SessionClient`].
46    ///
47    /// # Deferred session-capability validation
48    ///
49    /// This constructor accepts ANY [`jmap_base_client::Session`],
50    /// including one whose advertised capabilities do not include
51    /// `urn:ietf:params:jmap:contacts` or whose `primaryAccounts` map
52    /// has no entry for the contacts capability. The constructor
53    /// performs no up-front validation and never fails — its return
54    /// type is the infallible [`methods::SessionClient`], not a
55    /// `Result`.
56    ///
57    /// Capability and primary-account validation is deferred to every
58    /// individual method call on the returned [`SessionClient`]. If
59    /// the session is unsuitable, those per-method calls return
60    /// [`ClientError::InvalidSession`] with a description like
61    /// `"no primary account for urn:ietf:params:jmap:contacts"`.
62    ///
63    /// Callers that want to guard at the binding site can pre-check
64    /// the session before calling this method via
65    /// [`session.primary_account_id("urn:ietf:params:jmap:contacts")`](jmap_base_client::Session::primary_account_id).
66    fn with_contacts_session(&self, session: jmap_base_client::Session) -> methods::SessionClient;
67}
68
69impl JmapContactsExt for jmap_base_client::JmapClient {
70    fn with_contacts_session(&self, session: jmap_base_client::Session) -> methods::SessionClient {
71        methods::SessionClient {
72            client: self.clone(),
73            session,
74        }
75    }
76}
77
78mod sealed {
79    /// Sealing-trait for [`super::JmapContactsExt`] — see the trait's rustdoc.
80    pub trait Sealed {}
81    impl Sealed for ::jmap_base_client::JmapClient {}
82}
jmap_contacts_client/lib.rs

jmap_contacts_client/
lib.rs
