Struct SessionClient 

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

A JmapClient bound to a JMAP session.

Obtain via JmapTasksExt::with_tasks_session. All JMAP Tasks 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_tasks_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 task_get( &self, ids: Option<&[Id]>, properties: Option<&[&str]>, ) -> Result<GetResponse<Task>, ClientError>

Fetch Task objects by IDs (draft-tasks-06 §4.5).

If ids is None, the server returns all Tasks 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:tasks.
• 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 task_changes( &self, since_state: &State, max_changes: Option<u64>, ) -> Result<ChangesResponse, ClientError>

Fetch changes to Task objects since since_state (draft-tasks-06 §4.6).

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:tasks.
• Any transport / protocol variant returned by JmapClient::call — see the matching error list on Self::task_get.

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

Create, update, or destroy Task objects (draft-tasks-06 §4.7).

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:tasks.
• 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::task_get.

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

Copy Tasks from another account (draft-tasks-06 §4.8).

from_account_id is the source account. The tasks are copied into the current primary Tasks account.

Errors

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

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

Query Task IDs with optional filter and sort (draft-tasks-06 §4.13).

Errors

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

pub async fn task_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 Task since since_query_state (draft-tasks-06 §4.14).

filter and sort MUST match the filter / sort passed to the original Task/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::task_changes).
• ClientError::InvalidSession if the bound session has no primary account for urn:ietf:params:jmap:tasks.
• Any transport / protocol variant returned by JmapClient::call — see the matching error list on Self::task_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 async fn task_list_get( &self, ids: Option<&[Id]>, properties: Option<&[&str]>, ) -> Result<GetResponse<TaskList>, ClientError>

Fetch TaskList objects by IDs (draft-tasks-06 §3.5).

If ids is None, the server returns all TaskLists 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:tasks.
• 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 task_list_changes( &self, since_state: &State, max_changes: Option<u64>, ) -> Result<ChangesResponse, ClientError>

Fetch changes to TaskList objects since since_state (draft-tasks-06 §3.6).

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:tasks.
• Any transport / protocol variant returned by JmapClient::call — see the matching error list on Self::task_list_get.

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

Create, update, or destroy TaskList objects (draft-tasks-06 §3.7).

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 extra method-level arguments (TaskListSetParams). Pass None (or Some(Default::default())) for spec-default behavior. Use TaskListSetParams::on_destroy_remove_tasks to allow destroying a non-empty TaskList (otherwise the server returns taskListHasTasks), and TaskListSetParams::extra for vendor / site extension fields (workspace extras-preservation policy).

Errors

• ClientError::InvalidSession if the bound session has no primary account for urn:ietf:params:jmap:tasks.
• ClientError::InvalidArgument if update is Some and serde_json::to_value fails on the patch map (pathological conditions only; see Self::task_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::task_list_get.

impl SessionClient

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

Fetch TaskNotification objects by IDs (draft-tasks-06 §5.2).

If ids is None, the server returns all TaskNotifications 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.

Errors

• ClientError::InvalidSession if the bound session has no primary account for urn:ietf:params:jmap:tasks.
• 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 task_notification_changes( &self, since_state: &State, max_changes: Option<u64>, ) -> Result<ChangesResponse, ClientError>

Fetch changes to TaskNotification objects since since_state (draft-tasks-06 §5.3).

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:tasks.
• Any transport / protocol variant returned by JmapClient::call — see the matching error list on Self::task_notification_get.

pub async fn task_notification_set( &self, destroy: Vec<Id>, ) -> Result<SetResponse, ClientError>

Destroy TaskNotification objects (draft-tasks-06 §5.4).

Destroy-only: TaskNotification/set only supports destroy. The server creates notifications automatically; clients may only remove them.

Passing an empty destroy list is valid and produces an empty /set response.

Errors

• ClientError::InvalidSession if the bound session has no primary account for urn:ietf:params:jmap:tasks.
• Any transport / protocol variant returned by JmapClient::call — see the matching error list on Self::task_notification_get.

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

Query TaskNotification IDs with optional filter and sort (draft-tasks-06 §5.5).

Errors

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

pub async fn task_notification_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 TaskNotification since since_query_state (draft-tasks-06 §5.6).

filter and sort MUST match the filter / sort passed to the original TaskNotification/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::task_notification_changes).
• ClientError::InvalidSession if the bound session has no primary account for urn:ietf:params:jmap:tasks.
• Any transport / protocol variant returned by JmapClient::call — see the matching error list on Self::task_notification_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 tasks_account_id(&self) -> Result<&str, ClientError>

Return the primary account id for urn:ietf:params:jmap:tasks, 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.