Struct SessionClient 

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

A JmapClient bound to a JMAP session.

Obtain via JmapContactsExt::with_contacts_session. All JMAP Contacts methods are available on this type without needing to pass &Session on every call.

Session lifecycle

SessionClient captures the Session at construction time. 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_contacts_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.

Thread safety

SessionClient is Send + Sync. Both jmap_base_client::JmapClient (backed by reqwest::Client) and jmap_base_client::Session (plain serde-derived data) are Send + Sync per jmap-base-client’s contract, so this type can be shared across async tasks via Arc<SessionClient> or cloned for per-task ownership.

A Send + Sync regression in a future jmap-base-client release would be a major-version-breaking change for this crate. A compile-time assertion in methods/mod.rs guards against the regression landing silently — see _assert_session_client_send_sync.

Implementations

impl SessionClient

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

Fetch AddressBook objects by IDs (RFC 9610 §2.1).

If ids is None, the server returns all AddressBooks for the account, SUBJECT TO the server’s maxObjectsInGet cap (RFC 8620 §5.1). For production use, scope the result set via the corresponding /query method first and pass explicit ids here to avoid requestTooLarge errors when the account holds more objects than the cap. Pass properties: None to return all fields.

Errors

• ClientError::InvalidSession if the bound session has no primary account for urn:ietf:params:jmap:contacts.
• Any transport / protocol variant returned by JmapClient::call: Http, Parse, AuthFailed, MethodError (wraps RFC 8620 §3.6.2 method-level errors such as accountNotFound, invalidArguments, serverFail), MethodNotFound, ResponseTooLarge, or UnexpectedResponse.

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

Fetch changes to AddressBook objects since since_state (RFC 9610 §2.2).

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

Errors

• ClientError::InvalidArgument if since_state is the empty string (defence-in-depth — State constructed via State::from accepts empty strings, but an empty sinceState is never useful and would otherwise generate a wasted round-trip).
• ClientError::InvalidSession if the bound session has no primary account for urn:ietf:params:jmap:contacts.
• Any transport / protocol variant returned by JmapClient::call — see the matching error list on Self::address_book_get.

pub async fn address_book_set( &self, create: Option<Value>, update: Option<HashMap<Id, PatchObject>>, destroy: Option<Vec<Id>>, params: Option<AddressBookSetParams>, ) -> Result<SetResponse<AddressBook>, ClientError>

Create, update, or destroy AddressBook objects (RFC 9610 §2.3).

Pass create, update, and/or destroy as needed. All three are optional; pass None to omit any operation from the request.

update is Option<HashMap<Id, PatchObject>> (RFC 8620 §5.3). Wire format is unchanged from a plain JSON object because PatchObject is #[serde(transparent)]; the typed parameter binds the JSON Pointer key + null-leaf removal contract to the type system.

params carries the Contacts-specific extra arguments onDestroyRemoveContents and onSuccessSetIsDefault. Pass None (or Some(Default::default())) when neither is needed.

Errors

• ClientError::InvalidSession if the bound session has no primary account for urn:ietf:params:jmap:contacts.
• ClientError::InvalidArgument if update is Some and serde_json::to_value fails on the patch map (pathological conditions only — allocation failure, or a PatchObject whose JSON tree exceeds serde_json’s recursion limit). The transient memory peak for very large update maps is roughly 3-4× the HashMap’s in-memory size (source map + serde_json::Value tree + serialized Vec<u8> body); callers dealing with thousands of patches per call may prefer to batch.
• Any transport / protocol variant returned by JmapClient::call — see the matching error list on Self::address_book_get.

impl SessionClient

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

Fetch ContactCard objects by IDs (RFC 9610 §3.1).

If ids is None, the server returns all ContactCards for the account, SUBJECT TO the server’s maxObjectsInGet cap (RFC 8620 §5.1). For production use, scope the result set via the corresponding /query method first and pass explicit ids here to avoid requestTooLarge errors when the account holds more objects than the cap. Pass properties: None to return all fields.

Errors

• ClientError::InvalidSession if the bound session has no primary account for urn:ietf:params:jmap:contacts.
• Any transport / protocol variant returned by JmapClient::call: Http, Parse, AuthFailed, MethodError (wraps RFC 8620 §3.6.2 method-level errors such as accountNotFound, invalidArguments, serverFail), MethodNotFound, ResponseTooLarge, or UnexpectedResponse.

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

Fetch changes to ContactCard objects since since_state (RFC 9610 §3.2).

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

Errors

• ClientError::InvalidArgument if since_state is the empty string (defence-in-depth — State constructed via State::from accepts empty strings, but an empty sinceState is never useful and would otherwise generate a wasted round-trip).
• ClientError::InvalidSession if the bound session has no primary account for urn:ietf:params:jmap:contacts.
• Any transport / protocol variant returned by JmapClient::call — see the matching error list on Self::contact_card_get.

pub async fn contact_card_set( &self, create: Option<Value>, update: Option<HashMap<Id, PatchObject>>, destroy: Option<Vec<Id>>, ) -> Result<SetResponse<ContactCard>, ClientError>

Create, update, or destroy ContactCard objects (RFC 9610 §3.3).

Pass create, update, and/or destroy as needed. All three are optional; pass None to omit any operation from the request.

update is Option<HashMap<Id, PatchObject>> (RFC 8620 §5.3). Wire format is unchanged from a plain JSON object because PatchObject is #[serde(transparent)]; the typed parameter binds the JSON Pointer key + null-leaf removal contract to the type system.

Errors

• ClientError::InvalidSession if the bound session has no primary account for urn:ietf:params:jmap:contacts.
• ClientError::InvalidArgument if update is Some and serde_json::to_value fails on the patch map (pathological conditions only; see Self::address_book_set for the memory-cost discussion that applies identically here).
• Any transport / protocol variant returned by JmapClient::call — see the matching error list on Self::contact_card_get.

pub async fn contact_card_copy( &self, from_account_id: &Id, create: Value, ) -> Result<SetResponse<ContactCard>, ClientError>

Copy ContactCards from another account (RFC 8620 §5.4 /copy).

from_account_id is the source account. create is a map of caller-supplied creation keys to copy descriptors. The server assigns new IDs in the destination account.

Errors

• ClientError::InvalidSession if the bound session has no primary account for urn:ietf:params:jmap:contacts.
• Any transport / protocol variant returned by JmapClient::call — see the matching error list on Self::contact_card_get. RFC 8620 §5.4 /copy adds method-level errors fromAccountNotFound, fromAccountNotSupportedByMethod, and anchorNotFound; they surface as MethodError.

pub async fn contact_card_query( &self, filter: Option<Value>, sort: Option<Value>, position: Option<u64>, limit: Option<u64>, ) -> Result<QueryResponse, ClientError>

Query ContactCard IDs with optional filter and sort (RFC 9610 §3.4).

Pass filter: None and sort: None to return all ContactCards with server-default ordering. Use position and limit for pagination.

Errors

• ClientError::InvalidSession if the bound session has no primary account for urn:ietf:params:jmap:contacts.
• Any transport / protocol variant returned by JmapClient::call — see the matching error list on Self::contact_card_get. RFC 8620 §5.5 defines additional /query method-level errors (anchorNotFound, unsupportedFilter, unsupportedSort, tooManyChanges) that surface as MethodError.

pub async fn contact_card_query_changes( &self, since_query_state: &State, max_changes: Option<u64>, filter: Option<Value>, sort: Option<Value>, up_to_id: Option<&Id>, calculate_total: Option<bool>, ) -> Result<QueryChangesResponse, ClientError>

Fetch query-result changes for ContactCard since since_query_state (RFC 9610 §3.5).

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

filter and sort MUST match the filter / sort passed to the original ContactCard/query call that returned since_query_state — RFC 8620 §5.6 is explicit that the server uses them to compute which entries entered or left the result set.

up_to_id is the highest-index id the client has cached; calculate_total requests the new total result count.

Errors

• ClientError::InvalidArgument if since_query_state is the empty string (defence-in-depth empty-state guard; see Self::contact_card_changes).
• ClientError::InvalidSession if the bound session has no primary account for urn:ietf:params:jmap:contacts.
• Any transport / protocol variant returned by JmapClient::call — see the matching error list on Self::contact_card_get. RFC 8620 §5.6 also defines cannotCalculateChanges (returned when the server cannot honour the request given the supplied filter / sort); it surfaces as MethodError.

impl SessionClient

pub fn client(&self) -> &JmapClient

Borrow the underlying JmapClient.

Useful for ad-hoc operations outside the typed JMAP method surface — for example, calling JmapClient::upload / JmapClient::download_blob, or constructing a JmapClient::event_source subscription using the bound session’s event_source_url.

pub fn session(&self) -> &Session

Borrow the captured Session.

SessionClient captures the Session at construction time. After re-fetching the session via JmapClient::fetch_session, callers should construct a new SessionClient. This accessor lets a caller compare the captured session’s state field against a freshly fetched session to detect staleness, or inspect accountCapabilities / primary_accounts for capability-specific metadata not exposed via the typed JMAP method surface.

pub fn contacts_account_id(&self) -> Result<&str, ClientError>

Return the primary account id for urn:ietf:params:jmap:contacts, or Err(InvalidSession) if the session has no primary account for that capability.

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.