jmap_chat_client/
lib.rs

1//! jmap-chat-client — auth-agnostic JMAP Chat HTTP client with WebSocket and SSE support.
2//!
3//! See PLAN.md for the full implementation plan.
4//!
5//! # Usage
6//!
7//! ```rust,no_run
8//! # use jmap_chat_client::JmapChatExt;
9//! # use jmap_types::Id;
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_chat_session(session);
13//! // Look up previously-uploaded blobs by their content-addressed hashes.
14//! // Pass `type_names: None` to accept any MIME type.
15//! let blob_ids = [Id::from("sha256-...")];
16//! let resolved = sc.blob_lookup(&blob_ids, None).await?;
17//! # let _ = resolved;
18//! # Ok(())
19//! # }
20//! ```
21
22#![forbid(unsafe_code)]
23
24pub mod methods;
25pub mod session;
26pub mod sse;
27pub mod types;
28pub mod utils;
29pub mod ws;
30
31pub use jmap_base_client::ClientError;
32pub use jmap_chat_types::BodyType;
33pub use methods::blob::{BlobConvertResponse, BlobLookupEntry, BlobLookupResponse, BlobObject};
34pub use methods::quota::Quota;
35pub use methods::{
36    AddMemberInput, AddedItem, ChangesResponse, ChatContactPatch, ChatContactQueryInput,
37    ChatCreateInput, ChatPatch, ChatQueryInput, ContactSortProperty, CustomEmojiCreateInput,
38    CustomEmojiQueryInput, GetResponse, MessageCreateInput, MessagePatch, MessageQueryInput, Patch,
39    PresenceStatusPatch, PushSubscriptionCreateInput, PushSubscriptionCreateResponse,
40    PushSubscriptionPatch, QueryChangesResponse, QueryResponse, ReactionChange, SessionClient,
41    SetError, SetResponse, SpaceAddCategoryInput, SpaceAddChannelInput, SpaceAddMemberInput,
42    SpaceAddRoleInput, SpaceBanCreateInput, SpaceCreateInput, SpaceInviteCreateInput,
43    SpaceJoinInput, SpaceJoinResponse, SpacePatch, SpaceQueryInput, SpaceUpdateCategoryInput,
44    SpaceUpdateChannelInput, SpaceUpdateMemberInput, SpaceUpdateRoleInput, TypingResponse,
45    UpdateMemberRoleInput,
46};
47pub use session::{ChatCapability, ChatPushCapability, ChatSessionExt};
48pub use sse::{parse_chat_sse_block, ChatSseEvent, ChatSseFrame};
49pub use types::{ChatMemberRole, ContactPresenceFilter, QuotaResourceType, QuotaScope};
50pub use utils::{format_receipt_timestamp, format_receipt_timestamp_at};
51pub use ws::{ChatWsExt, ChatWsFrame};
52
53/// Extension trait adding JMAP Chat methods to [`jmap_base_client::JmapClient`].
54///
55/// Import this trait to use: `use jmap_chat_client::JmapChatExt;`
56///
57/// All JMAP Chat method calls are made through the [`SessionClient`] returned
58/// by [`with_chat_session`](JmapChatExt::with_chat_session).
59///
60/// This trait is **sealed**: implementations outside this crate are not
61/// permitted. The crate adds an `impl` only for
62/// [`jmap_base_client::JmapClient`]. Sealing prevents downstream
63/// divergence (e.g. `impl JmapChatExt for MySimulator`) and keeps
64/// adding methods to the trait a non-breaking change.
65pub trait JmapChatExt: sealed::Sealed {
66    /// Create a [`SessionClient`] bound to this client and session.
67    ///
68    /// All JMAP Chat method calls are made through the returned [`SessionClient`].
69    ///
70    /// # Deferred session-capability validation
71    ///
72    /// This constructor accepts ANY [`jmap_base_client::Session`],
73    /// including one whose advertised capabilities do not include
74    /// `urn:ietf:params:jmap:chat` or whose `primaryAccounts` map has
75    /// no entry for the chat capability. The constructor performs no
76    /// up-front validation and never fails — its return type is the
77    /// infallible [`methods::SessionClient`], not a `Result`.
78    ///
79    /// Capability and primary-account validation is deferred to every
80    /// individual method call on the returned [`SessionClient`]. If
81    /// the session is unsuitable, those per-method calls return
82    /// [`ClientError::InvalidSession`] with a description like
83    /// `"no primary account for urn:ietf:params:jmap:chat"`.
84    ///
85    /// Callers that want to guard at the binding site can pre-check
86    /// the session before calling this method:
87    ///
88    /// ```ignore
89    /// if session
90    ///     .primary_account_id("urn:ietf:params:jmap:chat")
91    ///     .is_none()
92    /// {
93    ///     // Session does not advertise a primary account for chat;
94    ///     // every subsequent SessionClient method call would fail
95    ///     // with ClientError::InvalidSession. Refuse here.
96    ///     return Err(MyAppError::SessionMissingChatCapability);
97    /// }
98    /// let sc = client.with_chat_session(session);
99    /// ```
100    fn with_chat_session(&self, session: jmap_base_client::Session) -> methods::SessionClient;
101}
102
103impl JmapChatExt for jmap_base_client::JmapClient {
104    fn with_chat_session(&self, session: jmap_base_client::Session) -> methods::SessionClient {
105        methods::SessionClient {
106            client: self.clone(),
107            session,
108        }
109    }
110}
111
112mod sealed {
113    /// Sealing-trait for [`super::JmapChatExt`] — see the trait's rustdoc.
114    pub trait Sealed {}
115    impl Sealed for ::jmap_base_client::JmapClient {}
116}
jmap_chat_client/lib.rs

jmap_chat_client/
lib.rs
