jmap_metadata_client/
lib.rs

1//! jmap-metadata-client — JMAP Object Metadata extension method implementations.
2//!
3//! Implements the client-side method bindings for
4//! [draft-ietf-jmap-metadata-01](https://datatracker.ietf.org/doc/draft-ietf-jmap-metadata/).
5//! Depends on `jmap-base-client` for transport, auth, and session, and on
6//! `jmap-metadata-types` for the wire types.
7//!
8//! Cookie-cut from `jmap-mail-client` (canonical extension-client template
9//! per workspace AGENTS.md).
10//!
11//! # Usage
12//!
13//! ```rust,no_run
14//! # use jmap_metadata_client::JmapMetadataExt;
15//! # async fn example(client: jmap_base_client::JmapClient) -> Result<(), jmap_base_client::ClientError> {
16//! let session = client.fetch_session().await?;
17//! let sc = client.with_metadata_session(session);
18//! // Fetch all Metadata objects in the account.
19//! let metadata = sc.metadata_get(None, None, None).await?;
20//! # let _ = metadata;
21//! # Ok(())
22//! # }
23//! ```
24
25#![forbid(unsafe_code)]
26
27pub mod methods;
28
29pub use jmap_base_client::ClientError;
30pub use methods::{
31    AddedItem, ChangesResponse, GetResponse, MetadataChangesParams, MetadataGetParams,
32    MetadataQueryChangesParams, MetadataQueryParams, MetadataSetParams, QueryChangesResponse,
33    QueryResponse, SessionClient, SetError, SetResponse,
34};
35
36/// Extension trait adding JMAP Object Metadata (draft-ietf-jmap-metadata-01)
37/// methods to [`jmap_base_client::JmapClient`].
38///
39/// Import this trait to use: `use jmap_metadata_client::JmapMetadataExt;`
40///
41/// All JMAP Metadata method calls are made through the [`SessionClient`]
42/// returned by [`with_metadata_session`](JmapMetadataExt::with_metadata_session).
43/// This trait is **sealed**: implementations outside this crate are not
44/// permitted. The crate adds an `impl` only for
45/// [`jmap_base_client::JmapClient`]. Sealing prevents downstream
46/// divergence (e.g. `impl JmapMetadataExt for MySimulator`) and keeps
47/// adding methods to the trait a non-breaking change.
48pub trait JmapMetadataExt: sealed::Sealed {
49    /// Create a [`SessionClient`] bound to this client and session.
50    ///
51    /// All JMAP Metadata method calls are made through the returned
52    /// [`SessionClient`].
53    ///
54    /// # Deferred session-capability validation
55    ///
56    /// This constructor accepts ANY [`jmap_base_client::Session`],
57    /// including one whose advertised capabilities do not include
58    /// `urn:ietf:params:jmap:metadata` or whose `primaryAccounts` map
59    /// has no entry for the metadata capability. The constructor
60    /// performs no up-front validation and never fails — its return
61    /// type is the infallible [`methods::SessionClient`], not a
62    /// `Result`.
63    ///
64    /// Capability and primary-account validation is deferred to every
65    /// individual method call on the returned [`SessionClient`]. If
66    /// the session is unsuitable, those per-method calls return
67    /// [`ClientError::InvalidSession`] with a description like
68    /// `"no primary account for urn:ietf:params:jmap:metadata"`.
69    ///
70    /// Callers that want to guard at the binding site can pre-check
71    /// the session before calling this method via
72    /// [`session.primary_account_id("urn:ietf:params:jmap:metadata")`](jmap_base_client::Session::primary_account_id).
73    fn with_metadata_session(&self, session: jmap_base_client::Session) -> methods::SessionClient;
74}
75
76impl JmapMetadataExt for jmap_base_client::JmapClient {
77    fn with_metadata_session(&self, session: jmap_base_client::Session) -> methods::SessionClient {
78        methods::SessionClient {
79            client: self.clone(),
80            session,
81        }
82    }
83}
84
85mod sealed {
86    /// Sealing-trait for [`super::JmapMetadataExt`] — see the trait's rustdoc.
87    pub trait Sealed {}
88    impl Sealed for ::jmap_base_client::JmapClient {}
89}
jmap_metadata_client/lib.rs

jmap_metadata_client/
lib.rs
