Struct SessionClient 

#[non_exhaustive]
pub struct SessionClient { /* private fields */ }

A JmapClient bound to a JMAP session.

Obtain via the chat extension methods that accept a Session. All JMAP Chat methods are available on this type without needing to pass &Session on every call.

Session lifecycle

SessionClient captures the Session at construction time. JMAP sessions can expire; after re-fetching the session via JmapClient::fetch_session, construct a new SessionClient with the updated session. Reusing a stale SessionClient after session expiry will result in unknownAccount or similar errors from the server.

Clone is derived because JmapClient is itself cheap-to-clone (it already implements Clone and with_chat_session clones one internally), enabling parallel-task fan-out with one bound session.

Debug is implemented manually to redact the inner JmapClient (which holds an HTTP client and is intentionally not Debug in jmap-base-client); only the Session is shown. This lets callers embed a SessionClient in a #[derive(Debug)] struct without manual impls of their own.

Implementations

impl SessionClient

pub async fn chat_contact_get( &self, ids: Option<&[Id]>, properties: Option<&[&str]>, ) -> Result<GetResponse<ChatContact>, ClientError>

Fetch ChatContact objects by IDs (JMAP Chat §5 ChatContact/get).

If ids is None, returns all ChatContacts for the account.

pub async fn chat_contact_changes( &self, since_state: &State, max_changes: Option<u64>, ) -> Result<ChangesResponse, ClientError>

Fetch changes to ChatContact objects since since_state (RFC 8620 §5.2).

pub async fn chat_contact_update( &self, id: &Id, patch: &ChatContactPatch<'_>, ) -> Result<SetResponse, ClientError>

Update ChatContact properties (JMAP Chat §ChatContact/set).

Supports blocked (Boolean) and displayName (nullable String). Create and destroy are not supported by spec; the server returns forbidden.

pub async fn chat_contact_query( &self, input: &ChatContactQueryInput, ) -> Result<QueryResponse, ClientError>

Query ChatContact IDs with optional filter (JMAP Chat §ChatContact/query).

Supported filter keys: blocked, presence. Supported sort properties: "lastSeenAt", "login", "lastActiveAt".

pub async fn chat_contact_query_changes( &self, since_query_state: &State, max_changes: Option<u64>, ) -> Result<QueryChangesResponse, ClientError>

Fetch query-result changes for ChatContact since since_query_state (RFC 8620 §5.6 / ChatContact/queryChanges).

impl SessionClient

pub async fn read_position_get( &self, ids: Option<&[Id]>, ) -> Result<GetResponse<ReadPosition>, ClientError>

Fetch ReadPosition objects by IDs (JMAP Chat §5 ReadPosition/get).

If ids is None, returns all ReadPosition records for the account. The server creates one ReadPosition per Chat automatically.

pub async fn read_position_update( &self, read_position_id: &Id, last_read_message_id: &Id, ) -> Result<SetResponse, ClientError>

Update the read position for a Chat (JMAP Chat §5 ReadPosition/set).

read_position_id is the server-assigned ReadPosition.id (from read_position_get). last_read_message_id is the Message.id of the most recent message read. The server updates lastReadAt and recomputes Chat.unreadCount.

create and destroy are forbidden by the spec; only update is issued.

pub async fn presence_status_get( &self, ) -> Result<GetResponse<PresenceStatus>, ClientError>

Fetch the singleton PresenceStatus record (JMAP Chat §5 PresenceStatus/get).

Per spec there is exactly one PresenceStatus per account; ids: null retrieves it.

pub async fn read_position_changes( &self, since_state: &State, max_changes: Option<u64>, ) -> Result<ChangesResponse, ClientError>

Fetch changes to ReadPosition records since since_state (JMAP Chat §5 ReadPosition/changes).

max_changes may be None to let the server choose the limit (RFC 8620 §5.2).

pub async fn presence_status_update( &self, id: &Id, patch: &PresenceStatusPatch<'_>, ) -> Result<SetResponse, ClientError>

Update the PresenceStatus record (JMAP Chat §5 PresenceStatus/set).

Only update is issued; create and destroy are forbidden by the spec. Fields absent from patch (i.e. Patch::Keep or None) are omitted from the patch and left unchanged server-side.

pub async fn presence_status_changes( &self, since_state: &State, max_changes: Option<u64>, ) -> Result<ChangesResponse, ClientError>

Fetch changes to PresenceStatus records since since_state (JMAP Chat §5 PresenceStatus/changes).

max_changes may be None to let the server choose the limit (RFC 8620 §5.2).

pub async fn push_subscription_create( &self, input: &PushSubscriptionCreateInput<'_>, ) -> Result<PushSubscriptionCreateResponse, ClientError>

Create a PushSubscription with the optional chatPush extension (RFC 8620 §7.2 / draft-atwood-jmap-chat-push-00 §3).

PushSubscriptions are account-independent: no accountId is included in the request (RFC 8620 §7.2). When input.chat_push is Some, the using array includes urn:ietf:params:jmap:chat:push (RFC 8620 §3.3: capabilities MUST only be declared when used); otherwise urn:ietf:params:jmap:core alone is used.

This method issues a create operation only. To extend expires, set the verification code, change types, or update chatPush, use push_subscription_update. To unsubscribe, use push_subscription_destroy.

When input.client_id is None, a ULID is generated automatically.

pub async fn push_subscription_update( &self, id: &Id, patch: &PushSubscriptionPatch<'_>, ) -> Result<SetResponse, ClientError>

Update a PushSubscription (RFC 8620 §7.2.2 PushSubscription/set update).

Issues a PushSubscription/set request with only the update sub-map populated. RFC 8620 §7.2 declares url, keys, and deviceClientId immutable; to change those, destroy the subscription and create a new one. The patchable properties are exposed via PushSubscriptionPatch: verificationCode, expires, types, and the JMAP Chat Push extension’s chatPush.

PushSubscriptions are not account-scoped (RFC 8620 §7.2): no accountId is sent. When the patch touches chat_push or clear_chat_push, the using array includes urn:ietf:params:jmap:chat:push; otherwise only urn:ietf:params:jmap:core is declared (RFC 8620 §3.3).

Returns jmap_base_client::ClientError::InvalidArgument if id is empty, if both patch.types and patch.clear_types are set, or if both patch.chat_push and patch.clear_chat_push are set.

pub async fn push_subscription_destroy( &self, ids: &[Id], ) -> Result<SetResponse, ClientError>

Destroy one or more PushSubscriptions (RFC 8620 §7.2.2 PushSubscription/set destroy).

Issues a PushSubscription/set request with only the destroy array populated. PushSubscriptions are not account-scoped (RFC 8620 §7.2): no accountId is sent. Only urn:ietf:params:jmap:core is declared — destroying never requires the chatPush capability since it is a property-blind operation.

Returns jmap_base_client::ClientError::InvalidArgument if ids is empty (a destroy call with no ids would be a no-op round-trip).

Clients SHOULD NOT destroy a PushSubscription they did not create — RFC 8620 §7.2 reserves that to clients that recognise the deviceClientId. This client does not enforce that rule; the server may reject the call.

impl SessionClient

pub async fn space_ban_get( &self, ids: Option<&[Id]>, properties: Option<&[&str]>, ) -> Result<GetResponse<SpaceBan>, ClientError>

Fetch SpaceBan objects by IDs (JMAP Chat §4.18 SpaceBan/get).

If ids is None, returns all SpaceBan objects for the account. Pass properties: None to return all fields.

pub async fn space_ban_changes( &self, since_state: &State, max_changes: Option<u64>, ) -> Result<ChangesResponse, ClientError>

Fetch changes to SpaceBan objects since since_state (RFC 8620 §5.2 / SpaceBan/changes).

Only members with "ban" permission in the Space see all changes; other members see changes to their own bans only.

pub async fn space_ban_create( &self, input: &SpaceBanCreateInput<'_>, ) -> Result<SetResponse, ClientError>

Create a SpaceBan (RFC 8620 §5.3 / SpaceBan/set create).

When input.client_id is None, a ULID is generated automatically.

pub async fn space_ban_destroy( &self, ids: &[Id], ) -> Result<SetResponse, ClientError>

Destroy SpaceBan objects (RFC 8620 §5.3 / SpaceBan/set destroy).

ids must be non-empty; the guard fires before any network call.

impl SessionClient

pub async fn space_invite_get( &self, ids: Option<&[Id]>, properties: Option<&[&str]>, ) -> Result<GetResponse<SpaceInvite>, ClientError>

Fetch SpaceInvite objects by IDs (JMAP Chat §4.17 SpaceInvite/get).

If ids is None, returns all SpaceInvite objects for the account. Pass properties: None to return all fields.

pub async fn space_invite_changes( &self, since_state: &State, max_changes: Option<u64>, ) -> Result<ChangesResponse, ClientError>

Fetch changes to SpaceInvite objects since since_state (RFC 8620 §5.2 / SpaceInvite/changes).

If has_more_changes is true in the response, call again with new_state as since_state until the flag is false.

pub async fn space_invite_create( &self, input: &SpaceInviteCreateInput<'_>, ) -> Result<SetResponse, ClientError>

Create a SpaceInvite (RFC 8620 §5.3 / SpaceInvite/set create).

When input.client_id is None, a ULID is generated automatically.

pub async fn space_invite_destroy( &self, ids: &[Id], ) -> Result<SetResponse, ClientError>

Destroy SpaceInvite objects (RFC 8620 §5.3 / SpaceInvite/set destroy).

ids must be non-empty; the guard fires before any network call.

impl SessionClient

pub async fn blob_lookup( &self, blob_ids: &[Id], type_names: Option<&[&str]>, ) -> Result<BlobLookupResponse, ClientError>

Reverse-lookup blobs: given a list of blob IDs and data type names, returns which objects of those types reference each blob.

Uses capability urn:ietf:params:jmap:blob2; the server MUST advertise it in the Session for this method to succeed (RFC 8620 §3.3).

type_names filters which data types to search. None queries all types registered on the server. For JMAP Chat, "Message" is the expected type.

Security: blobs that are inaccessible or nonexistent are returned with empty matchedIds arrays rather than an error (draft-ietf-jmap-blobext §6), to avoid information leakage.

pub async fn blob_convert( &self, from_blob_id: &Id, content_type: &str, width: Option<u32>, height: Option<u32>, ) -> Result<BlobConvertResponse, ClientError>

Convert a blob to a different MIME type via an imageConvert recipe (JMAP-BLOBEXT §8 / blob2 capability).

Typical use: request a thumbnail (image/webp) from an image blob without downloading the original. The server MUST advertise urn:ietf:params:jmap:blob2 in Session capabilities.

width and height are optional maximum-dimension hints; the server may ignore or clamp them. Pass None to omit.

On success the converted blob is in response.created[CALL_ID]. On failure the error is in response.not_created[CALL_ID].

impl SessionClient

pub async fn custom_emoji_get( &self, ids: Option<&[Id]>, properties: Option<&[&str]>, ) -> Result<GetResponse<CustomEmoji>, ClientError>

Fetch CustomEmoji objects by IDs (JMAP Chat §4.16 CustomEmoji/get).

If ids is None, returns all CustomEmoji objects visible to the account (Space-specific and server-global).

pub async fn custom_emoji_changes( &self, since_state: &State, max_changes: Option<u64>, ) -> Result<ChangesResponse, ClientError>

Fetch changes to CustomEmoji objects since since_state (RFC 8620 §5.2 / JMAP Chat §4.16 CustomEmoji/changes).

pub async fn custom_emoji_create( &self, input: &CustomEmojiCreateInput<'_>, ) -> Result<SetResponse, ClientError>

Create a CustomEmoji (RFC 8620 §5.3 / JMAP Chat §4.16 CustomEmoji/set create).

When input.client_id is None, a ULID is generated automatically.

pub async fn custom_emoji_destroy( &self, ids: &[Id], ) -> Result<SetResponse, ClientError>

Destroy CustomEmoji objects (RFC 8620 §5.3 / JMAP Chat §4.16 CustomEmoji/set destroy).

ids must be non-empty; the guard fires before any network call.

pub async fn custom_emoji_query( &self, input: &CustomEmojiQueryInput<'_>, ) -> Result<QueryResponse, ClientError>

Query CustomEmoji IDs (RFC 8620 §5.5 / JMAP Chat §4.16 CustomEmoji/query).

pub async fn custom_emoji_query_changes( &self, since_query_state: &State, max_changes: Option<u64>, ) -> Result<QueryChangesResponse, ClientError>

Fetch query-result changes for CustomEmoji since since_query_state (RFC 8620 §5.6 / JMAP Chat §4.16 CustomEmoji/queryChanges).

impl SessionClient

pub async fn quota_get(&self) -> Result<GetResponse<Quota>, ClientError>

Fetch all Quota objects for the account (RFC 9425 §4.2 Quota/get).

Returns all quota records for the primary JMAP Chat account. Each Quota includes used, hard_limit, and optional warn_limit fields that callers can use to display storage bars and warnings.

The returned GetResponse::state token is preserved for quota_changes delta-sync support.

Only call when crate::session::ChatSessionExt::supports_quotas returns true. Returns ClientError::InvalidSession if the session has no primary JMAP Chat account.

pub async fn quota_changes( &self, since_state: &State, max_changes: Option<u64>, ) -> Result<ChangesResponse, ClientError>

Fetch changes to Quota objects since since_state (RFC 8620 §5.2 / Quota/changes).

Returns ids of Quota objects created, updated, or destroyed since the caller-supplied since_state token (typically the GetResponse::state returned by an earlier quota_get call).

If ChangesResponse::has_more_changes is true, call again with ChangesResponse::new_state as since_state until the flag is false.

max_changes caps the number of ids the server returns in a single response; None lets the server choose. Servers are not required to honour a max_changes hint exactly.

Only call when crate::session::ChatSessionExt::supports_quotas returns true. Returns jmap_base_client::ClientError::InvalidArgument if since_state is empty, or jmap_base_client::ClientError::InvalidSession if the session has no primary JMAP Chat account.

impl SessionClient

pub async fn chat_get( &self, ids: Option<&[Id]>, properties: Option<&[&str]>, ) -> Result<GetResponse<Chat>, ClientError>

Fetch Chat objects by IDs (RFC 8620 §5.1 / JMAP Chat §Chat/get).

If ids is None, the server returns all Chats for the account. Pass properties: None to return all fields.

pub async fn chat_query( &self, input: &ChatQueryInput, ) -> Result<QueryResponse, ClientError>

Query Chat IDs with optional filter (RFC 8620 §5.5 / JMAP Chat §Chat/query).

Only keys that are Some in input are included in the filter object; an empty filter object is sent as JSON null.

pub async fn chat_changes( &self, since_state: &State, max_changes: Option<u64>, ) -> Result<ChangesResponse, ClientError>

Fetch changes to Chat objects since since_state (RFC 8620 §5.2 / Chat/changes).

If has_more_changes is true in the response, call again with new_state as since_state until the flag is false.

pub async fn chat_typing( &self, chat_id: &Id, typing: bool, ) -> Result<TypingResponse, ClientError>

Send a typing indicator for a Chat (JMAP Chat §Chat/typing).

Notifies other participants that the account is (or has stopped) typing. The server silently drops the event if Chat.receiveTypingIndicators is false for a recipient (direct/group chats); for channel chats the preference has no effect. The server SHOULD rate-limit to one call per account per chat per 3 seconds — excess calls MAY be silently discarded. Debouncing (send once per keypress, stop event on idle) is the caller’s responsibility.

pub async fn chat_query_changes( &self, since_query_state: &State, max_changes: Option<u64>, ) -> Result<QueryChangesResponse, ClientError>

Fetch query-result changes for Chat since since_query_state (RFC 8620 §5.6 / Chat/queryChanges).

Returns which Chat IDs were removed from or added to the query result set since the given state. max_changes may be None.

pub async fn chat_create( &self, input: &ChatCreateInput<'_>, ) -> Result<SetResponse, ClientError>

Create a Chat (JMAP Chat §Chat/set create).

Dispatches to the correct spec kind based on the input variant: Direct, Group, or Channel. When client_id inside the variant is None, a ULID is generated automatically.

For Direct chats: if one already exists with the given contact_id, the server returns it in SetResponse.updated rather than created (dedup rule per spec).

pub async fn chat_update( &self, id: &Id, patch: &ChatPatch<'_>, ) -> Result<SetResponse, ClientError>

Update Chat properties (JMAP Chat §Chat/set update).

Issues an update operation patching only the fields present in patch. Use Patch::Set(v) to set nullable fields, Patch::Clear to null-clear them, and Patch::Keep (default) to leave them unchanged. Slice fields default to None for no-change.

If all fields are Keep/None, an empty patch is sent — RFC 8620 §5.3 permits this; the server treats it as a no-op but still returns the chat in updated.

pub async fn chat_destroy(&self, ids: &[Id]) -> Result<SetResponse, ClientError>

Destroy Chat objects (RFC 8620 §5.3 / Chat/set destroy).

Permanently removes the listed Chat IDs from the account. ids must be non-empty; the guard fires before any network call.

impl SessionClient

pub async fn message_get( &self, ids: &[Id], properties: Option<&[&str]>, ) -> Result<GetResponse<Message>, ClientError>

Fetch Message objects by IDs (RFC 8620 §5.1 / JMAP Chat §Message/get).

ids is required (non-empty); fetching all messages is impractical. Pass properties: None to return all fields.

pub async fn message_query( &self, input: &MessageQueryInput<'_>, ) -> Result<QueryResponse, ClientError>

Query Message IDs within a Chat (RFC 8620 §5.5 / JMAP Chat §Message/query).

Per spec, either chat_id or has_mention: Some(true) must be provided. Servers MUST return unsupportedFilter if neither condition holds.

Sort order is controlled by input.sort_ascending (default false = newest first). With position:0, limit:N and sort_ascending:false, the server returns the N most recent message IDs. Callers displaying messages chronologically should set sort_ascending:true or reverse after fetching.

pub async fn message_changes( &self, since_state: &State, max_changes: Option<u64>, ) -> Result<ChangesResponse, ClientError>

Fetch changes to Message objects since since_state (RFC 8620 §5.2 / Message/changes).

pub async fn message_create( &self, input: &MessageCreateInput<'_>, ) -> Result<SetResponse, ClientError>

Create (send) a new Message (RFC 8620 §5.3 / JMAP Chat §Message/set).

When input.client_id is None, a ULID is generated automatically. The server maps the creation key to the server-assigned Message id in SetResponse.created.

Rate limiting

If the server rejects the message with error_type == "rateLimited" in not_created, this method returns Err(ClientError::RateLimited) with the retry_after timestamp from serverRetryAfter. If serverRetryAfter is absent the method returns Err(ClientError::UnexpectedResponse).

Return value

Returns Err(ClientError::RateLimited) when the server returns a rateLimited set error with a serverRetryAfter field.

For all other server-side rejections (e.g., invalidProperties, forbidden), this method returns Ok(set_resp) with the error recorded in set_resp.not_created. Callers MUST inspect not_created on every Ok response to confirm the message was actually created.

pub async fn message_update( &self, id: &Id, patch: &MessagePatch<'_>, ) -> Result<SetResponse, ClientError>

Update Message properties (RFC 8620 §5.3 / JMAP Chat §4.5 Message/set).

Issues an update operation patching only the fields present in patch. Supports body edits (author-only), reaction changes (JSON Pointer patch on reactions map), read-receipt updates (readAt), and chat-level deletion (deletedAt / deletedForAll).

If all optional fields are None, an empty patch object is sent. RFC 8620 §5.3 permits this; the server treats it as a no-op but still returns the object in updated.

pub async fn message_destroy( &self, ids: &[Id], ) -> Result<SetResponse, ClientError>

Destroy Message objects (RFC 8620 §5.3 / Message/set destroy).

Permanently removes the listed message IDs from the account. ids must be non-empty; the guard fires before any network call.

pub async fn message_query_changes( &self, since_query_state: &State, max_changes: Option<u64>, ) -> Result<QueryChangesResponse, ClientError>

Fetch query-result changes for Message since since_query_state (RFC 8620 §5.6 / Message/queryChanges).

Returns which message IDs were removed from or added to the query result set since the given state. max_changes may be None.

impl SessionClient

pub async fn space_get( &self, ids: Option<&[Id]>, properties: Option<&[&str]>, ) -> Result<GetResponse<Space>, ClientError>

Fetch Space objects by IDs (RFC 8620 §5.1 / JMAP Chat §Space/get).

If ids is None, the server returns all Spaces for the account. Pass properties: None to return all fields.

pub async fn space_changes( &self, since_state: &State, max_changes: Option<u64>, ) -> Result<ChangesResponse, ClientError>

Fetch changes to Space objects since since_state (RFC 8620 §5.2 / Space/changes).

If has_more_changes is true in the response, call again with new_state as since_state until the flag is false.

pub async fn space_destroy( &self, ids: &[Id], ) -> Result<SetResponse, ClientError>

Destroy Space objects (RFC 8620 §5.3 / Space/set destroy).

Permanently removes the listed Space IDs from the account. ids must be non-empty; the guard fires before any network call.

pub async fn space_query( &self, input: &SpaceQueryInput<'_>, ) -> Result<QueryResponse, ClientError>

Query Space IDs with optional filter (RFC 8620 §5.5 / JMAP Chat §Space/query).

Only keys that are Some in input are included in the filter object; an empty filter is sent as JSON null.

pub async fn space_query_changes( &self, since_query_state: &State, max_changes: Option<u64>, ) -> Result<QueryChangesResponse, ClientError>

Fetch query-result changes for Space since since_query_state (RFC 8620 §5.6 / Space/queryChanges).

Returns which Space IDs were removed from or added to the query result set since the given state. max_changes may be None.

pub async fn space_create( &self, input: &SpaceCreateInput<'_>, ) -> Result<SetResponse, ClientError>

Create a new Space (JMAP Chat §Space/set create).

When input.client_id is None, a ULID is generated automatically. The server maps the creation key to the server-assigned Space id in SetResponse.created.

pub async fn space_join( &self, input: &SpaceJoinInput<'_>, ) -> Result<SpaceJoinResponse, ClientError>

Join a Space via invite code or direct ID (JMAP Chat §Space/join).

input selects exactly one join path; the enum makes invalid inputs unrepresentable at the type level.

pub async fn space_update( &self, id: &Id, patch: &SpacePatch<'_>, ) -> Result<SetResponse, ClientError>

Update Space properties (JMAP Chat §Space/set update).

Issues an update operation patching only the fields present in patch. Use Patch::Set(v) to set nullable fields, Patch::Clear to null-clear them, and Patch::Keep (default) to leave them unchanged. Slice fields default to None for no-change.

Supports the full set of semantic mutation keys from JMAP Chat §Space/set: metadata (name, description, iconBlobId, isPublic, isPubliclyPreviewable); members (addMembers, removeMembers, updateMembers, manage_members); channels (addChannels, removeChannels, updateChannels, manage_channels); roles (addRoles, removeRoles, updateRoles, manage_roles); and categories (addCategories, removeCategories, updateCategories, manage_channels).

Trait Implementations

impl Clone for SessionClient

fn clone(&self) -> SessionClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SessionClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.