libjmap/

lib.rs

// Copyright 2025 Hugo Osvaldo Barrera
//
// SPDX-License-Identifier: ISC

use std::collections::HashMap;

use http::{
    Request, Response, StatusCode, Uri,
    response::Parts,
    uri::{InvalidUri, PathAndQuery},
};
use http_body_util::BodyExt as _;
use hyper::body::{Bytes, Incoming};
use log::trace;
use serde::{Deserialize, Serialize, de::DeserializeOwned};
use serde_json::Value as JsonValue;
use tokio::sync::Mutex;
use tower_service::Service;

use crate::{
    addressbook::JMAP_CONTACTS,
    calendar::JMAP_CALENDARS,
    error::{Error, Result},
};

/// JMAP core capability URN.
pub const JMAP_CORE: &str = "urn:ietf:params:jmap:core";

pub mod addressbook;
pub mod calendar;
pub mod error;

/// JMAP response structure containing method responses and session state.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JmapResponse<T> {
    #[serde(rename = "methodResponses")]
    pub method_responses: Vec<MethodResponse<T>>,
    #[serde(rename = "sessionState")]
    pub session_state: String,
}

/// JMAP method response data.
/// Either a success response or an error.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(untagged)]
pub enum MethodResponseData<T> {
    /// Error response.
    // Must be first for untagged deserialization.
    Error(JmapError),
    /// Successful response.
    Success(T),
}

impl<T> MethodResponseData<T> {
    /// Convert to Result, transforming Error variant into Error::ServerError
    pub fn into_result(self) -> Result<T> {
        match self {
            MethodResponseData::Error(error) => Err(Error::ServerError {
                error_type: error.error_type,
                description: error.description,
            }),
            MethodResponseData::Success(data) => Ok(data),
        }
    }
}

/// JMAP method response tuple: [`method_name`, `response_data`, `call_id`]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MethodResponse<T>(pub String, pub MethodResponseData<T>, pub String);

/// Response structure for Get requests.
///
/// See: <https://www.rfc-editor.org/rfc/rfc8620#section-5.1>
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct GetResponse<T> {
    pub state: String,
    pub list: Vec<T>,
    #[serde(rename = "notFound")]
    pub not_found: Vec<String>,
    #[serde(rename = "accountId")]
    pub account_id: String,
}

/// Response structure for query method calls
///
/// See: <https://www.rfc-editor.org/rfc/rfc8620#section-5.5>
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct QueryResponse {
    pub filter: Option<JsonValue>,
    pub sort: Option<JsonValue>,
    #[serde(rename = "queryState")]
    pub query_state: String,
    #[serde(rename = "canCalculateChanges")]
    pub can_calculate_changes: bool,
    pub position: u32,
    pub ids: Vec<String>,
    pub total: Option<u32>,
    #[serde(rename = "accountId")]
    pub account_id: String,
}

/// Response structure for changes method calls.
///
/// See: <https://www.rfc-editor.org/rfc/rfc8620#section-5.2>
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ChangesResponse {
    #[serde(rename = "oldState")]
    pub old_state: String,
    #[serde(rename = "newState")]
    pub new_state: String,
    #[serde(rename = "hasMoreChanges")]
    pub has_more_changes: bool,
    pub created: Vec<String>,
    pub updated: Vec<String>,
    pub destroyed: Vec<String>,
    #[serde(rename = "accountId")]
    pub account_id: String,
}

/// Status of an item relative to a previous state.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ChangeStatus {
    /// No change since the given state.
    NotChanged,
    /// Modified since the given state.
    Changed,
    /// Deleted since the given state.
    Deleted,
}

/// JMAP set response structure for create/update/delete operations.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SetResponse<T> {
    #[serde(rename = "oldState")]
    pub old_state: String,
    #[serde(rename = "newState")]
    pub new_state: String,
    pub created: Option<HashMap<String, T>>,
    pub updated: Option<HashMap<String, T>>,
    pub destroyed: Option<Vec<String>>,
    #[serde(rename = "notCreated")]
    pub not_created: Option<HashMap<String, JmapError>>,
    #[serde(rename = "notUpdated")]
    pub not_updated: Option<HashMap<String, JmapError>>,
    #[serde(rename = "notDestroyed")]
    pub not_destroyed: Option<HashMap<String, JmapError>>,
    #[serde(rename = "accountId")]
    pub account_id: String,
}

/// JMAP error structure
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct JmapError {
    #[serde(rename = "type")]
    pub error_type: String,
    pub properties: Option<Vec<String>>,
    pub description: Option<String>,
}

/// JMAP request structure (RFC 8620 section 3.3)
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RequestObject {
    /// Capabilities used by the client
    pub using: Vec<String>,
    /// Method calls to execute
    #[serde(rename = "methodCalls")]
    pub method_calls: Vec<Invocation>,
    /// Created object IDs mapping (optional)
    #[serde(rename = "createdIds", skip_serializing_if = "Option::is_none")]
    pub created_ids: Option<HashMap<String, String>>,
}

/// JMAP method invocation: [methodName, arguments, methodCallId]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Invocation(pub String, pub JsonValue, pub String);

impl RequestObject {
    /// Create a new JMAP request with basic capabilities
    #[must_use]
    pub fn new(capabilities: Vec<String>) -> Self {
        Self {
            using: capabilities,
            method_calls: Vec::new(),
            created_ids: None,
        }
    }

    /// Add a method call to the request
    #[must_use]
    pub fn with_method_call(
        mut self,
        method_name: String,
        arguments: JsonValue,
        call_id: String,
    ) -> Self {
        self.method_calls
            .push(Invocation(method_name, arguments, call_id));
        self
    }

    /// Helper to create a standard JMAP request with core capabilities
    #[must_use]
    pub fn with_core_capability(capability: &str) -> Self {
        Self::new(vec![JMAP_CORE.to_string(), capability.to_string()])
    }
}

/// Fetch the JMAP session resource.
///
/// Returns the URL for the session resource and its contents.
/// `base_url` should be a domain's base URL, e.g.: `https://example.com`.
///
/// See: <https://www.rfc-editor.org/rfc/rfc8620#section-2>
///
/// The provided `base_url` should point to the domain where the server is located.
///
/// # Errors
///
/// See [`DiscoverSessionError`].
pub async fn discover_session_resource<C, E>(
    http_client: &mut C,
    base_url: &Uri,
) -> Result<(Uri, SessionResource), DiscoverSessionError<E>>
where
    // TODO: static?
    C: Service<http::Request<String>, Response = Response<Incoming>, Error = E> + 'static,
    E: std::error::Error + Send + Sync,
{
    let mut uri: Uri = make_relative_url(base_url.clone(), "/.well-known/jmap")
        .map_err(DiscoverSessionError::InvalidInput)?;
    let (mut head, mut raw_body);

    loop {
        let request = Request::builder()
            .method("GET")
            .uri(&uri)
            .body(String::new())
            .expect("All provided arguments are propertly validated.");
        let response = http_client
            .call(request)
            .await
            .map_err(DiscoverSessionError::ClientError)?;
        (head, raw_body) = response.into_parts();
        if !head.status.is_redirection() {
            break;
        }

        let location = head
            .headers
            .get(hyper::header::LOCATION)
            .ok_or(DiscoverSessionError::MissingLocation)?
            .as_bytes();

        let location_uri =
            Uri::try_from(location).map_err(DiscoverSessionError::InvalidLocation)?;

        uri = if location_uri.host().is_some() {
            location_uri
        } else {
            let loc_parts = location_uri.into_parts();

            let mut parts = uri.into_parts();
            parts.path_and_query = loc_parts.path_and_query;
            Uri::from_parts(parts).expect("Building from validated parts must succeed")
        }
    }

    let body = raw_body
        .collect()
        .await
        .map_err(DiscoverSessionError::StreamingError)?
        .to_bytes();
    trace!("{body:?}");
    check_status(head.status).map_err(DiscoverSessionError::BadStatus)?;
    let session_resource: SessionResource =
        serde_json::from_slice(body.as_ref()).map_err(DiscoverSessionError::ResponseNotJson)?;
    Ok((uri, session_resource))
}

/// JMAP client for interacting with JMAP servers.
pub struct JmapClient<C>
where
    C: Service<http::Request<String>, Response = Response<Incoming>> + Sync + Send + 'static,
{
    http_client: Mutex<C>,
    session_url: Uri,
    api_url: Uri,
}

/// JMAP collection types (calendars, address books, etc.).
pub trait RecordType: DeserializeOwned + Sized {
    const ITEM_NAME: &'static str;
    const COLLECTION_NAME: &'static str;
    const CAPABILITY: &'static str;

    fn id(&self) -> &str;
}

/// JMAP record with ID, state, and data.
#[derive(Debug)]
pub struct Record {
    // XXX: might want to drop this—it's always present in `data`.
    pub id: String,
    pub state: String,
    pub data: JsonValue,
}

/// Reference to a specific version of a JMAP record.
#[derive(Debug)]
pub struct RecordRef {
    pub id: String,
    pub state: String,
}

impl<C> JmapClient<C>
where
    C: Service<http::Request<String>, Response = Response<Incoming>> + Sync + Send + 'static,
    <C as Service<http::Request<String>>>::Error: std::error::Error + Send + Sync,
{
    /// Create a new JMAP client.
    // TODO: I'll want a builder pattern, where one can explicitly supply an api_url, or have it resolved.
    pub fn new(client: C, session_url: Uri, api_url: Uri) -> JmapClient<C> {
        JmapClient {
            http_client: Mutex::new(client),
            session_url,
            api_url,
        }
    }

    /// Discover the JMAP session URL for a domain.
    ///
    /// The provided `client: C` MUST handle authentication as required by the server.
    ///
    /// # Errors
    ///
    /// Returns an error if the domain is invalid or the well-known resource cannot be retrieved.
    // TODO: domain as string?
    // TODO: allow plain-text http?
    pub async fn discover_session_url(
        mut client: C,
        scheme: Scheme,
        domain: String,
        // TODO: port?
    ) -> Result<Uri, DiscoverError> {
        // TODO: SRV discovery: _jmap._tcp.example.com

        // If the client has a username in the form of an email address, it MAY use the domain
        // portion of this to attempt autodiscovery of the JMAP server.
        let uri: Uri = format!("{scheme}://{domain}:443/.well-known/jmap")
            .parse()
            .map_err(DiscoverError::InvalidDomain)?;

        let request = Request::builder()
            .method("GET")
            .uri(uri)
            .body(String::new())
            .expect("All provided arguments are propertly validated.");
        let response_future = client.call(request).await;
        let response = response_future.unwrap();
        let (head, body) = response.into_parts();
        check_status(head.status).unwrap();
        let _body = body.collect().await.unwrap().to_bytes();
        todo!()
    }

    /// Returns the server's `apiUrl`.
    pub fn api_url(&self) -> &Uri {
        &self.api_url
    }

    /// Returns the URL for the JMAP session resource.
    pub fn session_context_url(&self) -> &Uri {
        &self.session_url
    }

    /// Fetch the current session resource.
    ///
    /// # Errors
    ///
    /// Returns an error if the HTTP request fails, the server returns an error status,
    /// or the response cannot be parsed as JSON.
    pub async fn get_session_resource(&self) -> Result<SessionResource> {
        let request = Request::builder()
            .method("GET")
            .uri(&self.session_url)
            .body(String::new())?;

        let mut http_client = self.http_client.lock().await;
        let response = http_client
            .call(request)
            .await
            .map_err(|e| Error::ClientConnection(Box::new(e)))?;
        let (head, body) = response.into_parts();
        check_status(head.status)?;
        let body_bytes = body.collect().await?.to_bytes();
        let session_resource: SessionResource = serde_json::from_slice(body_bytes.as_ref())?;
        Ok(session_resource)
    }

    async fn jmap_request(&self, request: RequestObject) -> Result<Bytes> {
        let body = serde_json::to_string(&request)?;
        let uri = make_relative_url(self.session_url.clone(), &self.api_url.to_string())?;
        let request = Request::builder()
            .method("POST")
            .header("Content-Type", "application/json; charset=utf8")
            .uri(uri)
            .body(body)?;
        let (head, body) = self.request(request).await?;
        check_status(head.status)?;
        Ok(body)
    }

    /// Send a request to the server.
    ///
    /// Sends a request, applying any necessary authentication and logging the response.
    ///
    /// # Errors
    ///
    /// Returns an error if the underlying http request fails or if streaming the response fails.
    async fn request(&self, request: Request<String>) -> Result<(Parts, Bytes), RequestError> {
        let mut client = self.http_client.lock().await;
        let response_future = client.call(request);
        drop(client); // E.g.: unlock http_client.

        let response = response_future
            .await
            .map_err(|e| RequestError::Client(Box::from(e)))?;
        let (head, body) = response.into_parts();
        let body = body.collect().await?.to_bytes();

        // log::trace!("Response ({}): {:?}", head.status, body);
        Ok((head, body))
    }

    // let body = r#"[[ "Core/echo", { "hello": true, "high": 5 }, "b3ff" ]] "#;

    async fn create(
        &self,
        capability: &str,
        data_type: &str,
        data: JsonValue,
        if_state: Option<&str>,
    ) -> Result<Record> {
        let mut arguments = serde_json::json!({
            "create": {
                "new0": data
            }
        });
        if let Some(state) = if_state {
            arguments["ifInState"] = serde_json::json!(state);
        }
        let request = RequestObject::new(vec![JMAP_CORE.to_string(), capability.to_string()])
            .with_method_call(format!("{data_type}/set"), arguments, "0".to_string());
        let body = self.jmap_request(request).await?;
        let response_json: JmapResponse<SetResponse<JsonValue>> =
            serde_json::from_slice(body.as_ref())?;
        let mut responses = response_json.method_responses;
        let method_response = responses.pop().ok_or(Error::InvalidResponse {
            reason: "No method responses found".to_string(),
        })?;

        let set_response = method_response.1.into_result()?;

        if let Some(not_created) = set_response.not_created
            && let Some(error) = not_created.get("new0")
        {
            return Err(Error::ServerError {
                error_type: error.error_type.clone(),
                description: error.description.clone(),
            });
        }

        let created_item = set_response
            .created
            .ok_or(Error::InvalidResponse {
                reason: "No items were created".to_string(),
            })?
            .get("new0")
            .ok_or(Error::InvalidResponse {
                reason: "Created item 'new0' missing from response".to_string(),
            })?
            .clone();

        let id = created_item["id"]
            .as_str()
            .ok_or(Error::InvalidResponse {
                reason: "Created item missing 'id' field".to_string(),
            })?
            .to_string();

        let created = Record {
            id,
            state: set_response.new_state,
            data: created_item,
        };
        Ok(created)
    }

    async fn update(
        &self,
        capability: &str,
        data_type: &str,
        id: &str,
        data: JsonValue,
        if_state: Option<&str>,
    ) -> Result<Record> {
        let arguments = serde_json::json!({
            "update": { id.to_string(): data},
            "ifInState": if_state,
        });
        let request = RequestObject::new(vec![JMAP_CORE.to_string(), capability.to_string()])
            .with_method_call(format!("{data_type}/set"), arguments, "0".to_string());
        let body = self.jmap_request(request).await?;
        let response_json: JmapResponse<SetResponse<JsonValue>> =
            serde_json::from_slice(body.as_ref())?;
        let mut responses = response_json.method_responses;
        let method_response = responses.pop().ok_or(Error::InvalidResponse {
            reason: "No method responses found".to_string(),
        })?;

        let set_response = method_response.1.into_result()?;

        if let Some(not_updated) = set_response.not_updated
            && let Some(error) = not_updated.get(id)
        {
            return Err(Error::ServerError {
                error_type: error.error_type.clone(),
                description: error.description.clone(),
            });
        }

        let updated_item = set_response
            .updated
            .ok_or(Error::InvalidResponse {
                reason: "No items were updated".to_string(),
            })?
            .get(id)
            .ok_or_else(|| Error::InvalidResponse {
                reason: format!("Updated item '{id}' missing from response"),
            })?
            .clone();

        let updated = Record {
            id: id.to_string(),
            state: set_response.new_state,
            data: updated_item,
        };
        Ok(updated)
    }

    /// Create a new collection.
    ///
    /// # Errors
    ///
    /// Returns an error if the server request fails or the server rejects the operation.
    pub async fn create_collection<T: RecordType>(&self, name: &str) -> Result<Record> {
        let collection = serde_json::json!({
            "name": name
            // TODO: optional props?
        });
        self.create(T::CAPABILITY, T::COLLECTION_NAME, collection, None)
            .await
        // TODO: return id
    }

    /// Create a new record in a collection.
    ///
    /// # Errors
    ///
    /// Returns an error if the record is not a JSON object, the server request fails,
    /// or the server rejects the operation.
    pub async fn create_record<T: RecordType>(
        &self,
        calendar_id: &str,
        record: &JsonValue,
        if_state: Option<&str>,
    ) -> Result<Record> {
        let mut record = record.clone();
        if let JsonValue::Object(ref mut map) = record {
            map.insert(
                "calendarIds".to_string(),
                serde_json::json!({
                    calendar_id: true
                }),
            );
        } else {
            return Err(Error::InvalidData {
                message: "Record must be a JSON object".to_string(),
            });
        }

        self.create(T::CAPABILITY, T::ITEM_NAME, record, if_state)
            .await
    }

    /// Update an existing record in a collection.
    ///
    /// # Errors
    ///
    /// Returns an error if the record is not a JSON object, the server request fails,
    /// or the server rejects the operation.
    pub async fn update_record<T: RecordType>(
        &self,
        record_id: &str,
        calendar_id: &str,
        record: &JsonValue,
        if_state: Option<&str>,
    ) -> Result<Record> {
        let mut record = record.clone();
        if let JsonValue::Object(ref mut map) = record {
            map.insert(
                "calendarIds".to_string(),
                serde_json::json!({
                    calendar_id: true
                }),
            );
        } else {
            return Err(Error::InvalidData {
                message: "Record must be a JSON object".to_string(),
            });
        }

        self.update(T::CAPABILITY, T::ITEM_NAME, record_id, record, if_state)
            .await
    }

    /// Returns the new server state.
    async fn delete(
        &self,
        capability: &str,
        data_type: &str,
        id: &str,
        if_state: Option<&str>,
    ) -> Result<String> {
        let arguments = serde_json::json!({
            "destroy": [id],
            "ifInState": if_state,
        });
        let request = RequestObject::new(vec![JMAP_CORE.to_string(), capability.to_string()])
            .with_method_call(format!("{data_type}/set"), arguments, "d0".to_string());
        let body = self.jmap_request(request).await?;
        let response_json: JmapResponse<SetResponse<JsonValue>> =
            serde_json::from_slice(body.as_ref())?;
        let mut responses = response_json.method_responses;
        let method_response = responses.pop().ok_or(Error::InvalidResponse {
            reason: "No method responses found".to_string(),
        })?;

        let set_response = method_response.1.into_result()?;

        if let Some(not_destroyed) = set_response.not_destroyed
            && let Some(error) = not_destroyed.get(id)
        {
            return Err(Error::ServerError {
                error_type: error.error_type.clone(),
                description: error.description.clone(),
            });
        }

        let destroyed_items = set_response.destroyed.ok_or(Error::InvalidResponse {
            reason: "No items were destroyed".to_string(),
        })?;

        if !destroyed_items.contains(&id.to_string()) {
            return Err(Error::IncompleteOperation {
                message: format!("Item '{id}' was not destroyed"),
            });
        }

        Ok(set_response.new_state)
    }

    /// Delete a collection.
    ///
    /// # Errors
    ///
    /// Returns an error if the server request fails or the server rejects the operation.
    pub async fn delete_collection<T: RecordType>(
        &self,
        collection_id: &str,
        if_state: Option<&str>,
    ) -> Result<String> {
        self.delete(T::CAPABILITY, T::COLLECTION_NAME, collection_id, if_state)
            .await
    }

    /// Returns the new server state.
    /// Delete a record.
    ///
    /// # Errors
    ///
    /// Returns an error if the server request fails or the server rejects the operation.
    pub async fn delete_record<T: RecordType>(
        &self,
        record_id: &str,
        if_state: Option<&str>,
    ) -> Result<String> {
        self.delete(T::CAPABILITY, T::ITEM_NAME, record_id, if_state)
            .await
    }

    /// Get all collections of a specific type.
    ///
    /// # Errors
    ///
    /// Returns an error if the server request fails or the response cannot be parsed.
    pub async fn get_collections<T>(&self) -> Result<Vec<T>>
    where
        T: RecordType,
    {
        let arguments = serde_json::json!({ "ids": null });
        let request = RequestObject::new(vec![JMAP_CORE.to_string(), T::CAPABILITY.to_string()])
            .with_method_call(
                format!("{}/get", T::COLLECTION_NAME),
                arguments,
                "0".to_string(),
            );
        let body = self.jmap_request(request).await?;

        let parsed_body: JmapResponse<GetResponse<T>> = serde_json::from_slice(body.as_ref())?;
        let mut responses = parsed_body.method_responses;
        let method_response = responses.pop().ok_or(Error::InvalidResponse {
            reason: "No method responses found".to_string(),
        })?;

        let get_response = method_response.1.into_result()?;

        Ok(get_response.list)
    }

    /// Get all records in a collection.
    ///
    /// # Errors
    ///
    /// Returns an error if the server request fails or the response cannot be parsed.
    pub async fn get_records<T: RecordType>(&self, calendar_id: &str) -> Result<Vec<Record>> {
        // First method call: query for items in calendar
        let query_args = serde_json::json!({
            "filter": { "inCalendars": [calendar_id] }
        });
        // Second method call: get the actual items
        let get_args = serde_json::json!({
            "#ids": {
                "resultOf": "Q1",
                "name": "CalendarEvent/query",
                "path": "/ids"
            }
        });

        let request = RequestObject::new(vec![JMAP_CORE.to_string(), T::CAPABILITY.to_string()])
            .with_method_call(
                format!("{}/query", T::ITEM_NAME),
                query_args,
                "Q1".to_string(),
            )
            .with_method_call(format!("{}/get", T::ITEM_NAME), get_args, "Q2".to_string());

        let body = self.jmap_request(request).await?;
        // Using JsonValue because this response contains mixed types (QueryResponse + GetRecordsResponse)
        let response_json: JmapResponse<JsonValue> = serde_json::from_slice(body.as_ref())?;

        let method_response = response_json
            .method_responses
            .into_iter()
            .find(|m| m.2 == "Q2")
            .ok_or(Error::InvalidResponse {
                reason: "Method response Q2 not found".to_string(),
            })?;

        let response_data = method_response.1.into_result()?;

        let get_response: GetResponse<JsonValue> = serde_json::from_value(response_data.clone())?;

        let records = get_response
            .list
            .iter()
            .map(|item| Record {
                id: item["id"].as_str().unwrap_or("").to_string(),
                state: get_response.state.clone(),
                data: item.clone(),
            })
            .collect::<Vec<_>>();

        Ok(records)
    }

    /// Get changes for a data type since a given state.
    ///
    /// Uses the JMAP `Foo/changes` method to retrieve all changes (created, updated, destroyed)
    /// since the provided state.
    ///
    /// # Errors
    ///
    /// Returns an error if the server request fails or the response cannot be parsed.
    pub async fn changes<T: RecordType>(
        &self,
        since_state: &str,
        max_changes: Option<u32>,
    ) -> Result<ChangesResponse> {
        let mut arguments = serde_json::json!({
            "sinceState": since_state,
        });

        if let Some(max) = max_changes {
            arguments["maxChanges"] = serde_json::json!(max);
        }

        let request = RequestObject::new(vec![JMAP_CORE.to_string(), T::CAPABILITY.to_string()])
            .with_method_call(
                format!("{}/changes", T::ITEM_NAME),
                arguments,
                "c0".to_string(),
            );

        let body = self.jmap_request(request).await?;
        let response_json: JmapResponse<ChangesResponse> = serde_json::from_slice(body.as_ref())?;

        let mut responses = response_json.method_responses;
        let method_response = responses.pop().ok_or(Error::InvalidResponse {
            reason: "No method responses found".to_string(),
        })?;

        method_response.1.into_result()
    }

    /// Check if an item has changed since a given state.
    ///
    /// Uses the JMAP `Foo/changes` method to determine if an item has been created, updated, or
    /// deleted since the provided state. Handles pagination via `hasMoreChanges`.
    ///
    /// Returns a tuple of `(ChangeStatus, new_state)` where `new_state` is the latest state
    /// from the server that can be used for subsequent operations.
    ///
    /// This method is rather inefficient, and not advisable for JMAP-native applications.
    ///
    /// # Errors
    ///
    /// Returns an error if the server request fails or the response cannot be parsed.
    pub async fn changed_since<T: RecordType>(
        &self,
        id: &str,
        old_state: &str,
    ) -> Result<(ChangeStatus, String)> {
        let mut current_state = old_state.to_string();
        let id_str = id.to_string();

        let mut latest_status = ChangeStatus::NotChanged;
        loop {
            let changes_response = self.changes::<T>(&current_state, Some(500)).await?;

            // Order matters: check destroyed first, then updated, then created
            #[allow(clippy::collapsible_if)] // improves readability.
            if changes_response.destroyed.contains(&id_str) {
                latest_status = ChangeStatus::Deleted;
            } else if changes_response.updated.contains(&id_str) {
                if latest_status != ChangeStatus::Deleted {
                    latest_status = ChangeStatus::Changed;
                }
            } else if changes_response.created.contains(&id_str) {
                if latest_status == ChangeStatus::NotChanged {
                    latest_status = ChangeStatus::Changed;
                }
            }

            if !changes_response.has_more_changes {
                break;
            }

            current_state = changes_response.new_state;
        }

        Ok((latest_status, current_state))
    }
}

/// Error returned by [`discover_session_resource`].
#[derive(Debug)]
pub enum DiscoverSessionError<E>
where
    E: std::fmt::Debug,
{
    InvalidInput(http::Error),
    ClientError(E),
    MissingLocation,
    InvalidLocation(InvalidUri),
    BadStatus(StatusCode),
    StreamingError(hyper::Error),
    ResponseNotJson(serde_json::Error),
}

impl<E> std::fmt::Display for DiscoverSessionError<E>
where
    E: std::fmt::Debug,
{
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        std::fmt::Debug::fmt(self, f)
    }
}

impl<E> std::error::Error for DiscoverSessionError<E> where E: std::fmt::Debug {}

/// Uri schemes for known transport protocols.
pub enum Scheme {
    /// Plain-text HTTP.
    HTTP,
    /// HTTP over TLS.
    HTTPS,
}

impl std::fmt::Display for Scheme {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Scheme::HTTP => f.write_str("http"),
            Scheme::HTTPS => f.write_str("https"),
        }
    }
}

#[derive(thiserror::Error, Debug)]
pub enum DiscoverError {
    #[error("Invalid domain provided as input")]
    InvalidDomain(InvalidUri),

    #[error("Received error retrieveing well-known resource.")]
    WellKnownError(StatusCode),
}

/// Error executing an HTTP request.
// XXX: copy-pasted from libdav
#[derive(thiserror::Error, Debug)]
pub enum RequestError {
    /// Error handling the HTTP stream.
    #[error("error executing http request: {0}")]
    Http(#[from] hyper::Error),

    /// Error from the underlying HTTP client.
    #[error("client error executing request: {0}")]
    // TODO: remove dyn, make generic over client error type
    Client(Box<dyn std::error::Error + Send + Sync>),
}

#[derive(Debug, PartialEq, Deserialize)]
pub struct SessionResource {
    #[serde(rename = "apiUrl")]
    pub api_url: Option<String>,
    pub capabilities: std::collections::HashMap<String, JsonValue>,
    #[serde(flatten)]
    pub other_fields: JsonValue,
}

impl SessionResource {
    #[must_use]
    pub fn api_url(&self) -> Option<&str> {
        self.api_url.as_deref()
    }

    #[must_use]
    pub fn supports_calendars(&self) -> bool {
        self.capabilities.contains_key(JMAP_CALENDARS)
    }

    #[must_use]
    pub fn supports_address_books(&self) -> bool {
        self.capabilities.contains_key(JMAP_CONTACTS)
    }

    // - session has:
    //   - accountCapabilities: urn:ietf:params:jmap:calendars
    //   - accountCapabilities: urn:ietf:params:jmap:contacts
    //   - it also defines rate limits and maxCallsInRequest, etc.
}

/// Checks if the status code is success. If it is not, return it as an error.
#[inline]
pub(crate) fn check_status(status: StatusCode) -> Result<(), StatusCode> {
    if status.is_success() {
        Ok(())
    } else {
        Err(status)
    }
}

fn make_relative_url(base: Uri, path: &str) -> Result<Uri, http::Error> {
    // let path = strict_percent_encoded(path);
    let mut parts = base.into_parts();
    parts.path_and_query = Some(PathAndQuery::try_from(path)?);
    Uri::from_parts(parts).map_err(http::Error::from)
}

// # API
//
// - The request MUST be of type application/json
//
// I need to add the appropriate `using: urn:ietf:params:jmap:calendar` to
// requests, but this depends on the type of objects with which i am interacting.
//
//
// ---
//
// uri templates: https://www.rfc-editor.org/rfc/rfc6570

#[cfg(test)]
mod test {
    use http::Uri;
    use hyper_rustls::{HttpsConnector, HttpsConnectorBuilder};
    use hyper_util::{
        client::legacy::{Client, connect::HttpConnector},
        rt::TokioExecutor,
    };
    use serde_json::json;
    use tower_http::auth::AddAuthorization;

    use crate::{
        ChangeStatus, GetResponse, JmapClient, JmapResponse, JsonValue, MethodResponseData,
        SetResponse, addressbook::AddressBook, calendar::Calendar, discover_session_resource,
    };

    // TODO: localhost for non-containerised tests.
    const TEST_SERVER_BASE_URL: &str = "http://host.containers.internal:8080";

    type TestClient = AddAuthorization<Client<HttpsConnector<HttpConnector>, String>>;

    /// Test helper to set up a JMAP client connection
    struct TestSetup {
        pub client: JmapClient<TestClient>,
        pub session: crate::SessionResource,
    }

    async fn setup_test_client() -> TestSetup {
        let connector = HttpsConnectorBuilder::new()
            .with_native_roots()
            .unwrap()
            .https_or_http()
            .enable_http1()
            .build();
        let base_url = TEST_SERVER_BASE_URL.parse::<Uri>().unwrap();

        let http_client = Client::builder(TokioExecutor::new()).build(connector);
        let mut auth_client = AddAuthorization::basic(http_client, "user1", "");
        let (session_uri, session) = discover_session_resource(&mut auth_client, &base_url)
            .await
            .unwrap();

        // FIXME: library should return an absolute URI?
        let api_url = session.api_url().unwrap().parse().unwrap();
        let client = JmapClient::new(auth_client, session_uri, api_url);

        TestSetup { client, session }
    }

    /// Ugly test. Requires a Cyrus server running locally.
    ///
    /// See: <https://github.com/cyrusimap/cyrus-docker-test-server>
    #[tokio::test]
    async fn test_collection_methods() {
        let setup = setup_test_client().await;
        let jmap = setup.client;
        let session = setup.session;

        assert!(session.supports_calendars());
        assert!(session.supports_address_books());
        assert_eq!(session.api_url(), Some("/jmap/"));

        let initial = jmap.get_collections::<Calendar>().await.unwrap();
        let initial_count = initial.len();

        let created = jmap.create_collection::<Calendar>("Created").await.unwrap();
        let post_create_count = jmap.get_collections::<Calendar>().await.unwrap().len();

        assert_eq!(initial_count + 1, post_create_count);

        let created_id = created.data["id"].as_str().unwrap();
        jmap.delete_collection::<Calendar>(created_id, None)
            .await
            .unwrap();

        let post_delete_count = jmap.get_collections::<Calendar>().await.unwrap().len();
        assert_eq!(initial_count, post_delete_count);
    }

    #[tokio::test]
    #[ignore = "Cyrus returns internal error"]
    async fn test_address_book_methods() {
        let setup = setup_test_client().await;
        let jmap = setup.client;
        let session = setup.session;

        assert!(session.supports_calendars());
        assert!(session.supports_address_books());
        assert_eq!(session.api_url(), Some("/jmap/"));

        let initial = jmap.get_collections::<AddressBook>().await.unwrap();
        let initial_count = initial.len();

        let created = jmap.create_collection::<AddressBook>("Blah").await.unwrap();
        let post_create_count = jmap.get_collections::<AddressBook>().await.unwrap().len();

        assert_eq!(initial_count + 1, post_create_count);

        let created_id = created.data["id"].as_str().unwrap();
        jmap.delete_collection::<AddressBook>(created_id, None)
            .await
            .unwrap();

        let post_delete_count = jmap.get_collections::<AddressBook>().await.unwrap().len();
        assert_eq!(initial_count, post_delete_count);
    }

    #[tokio::test]
    async fn get_session_resource() {
        let setup = setup_test_client().await;
        let jmap = setup.client;
        let session = setup.session;

        let session2 = jmap.get_session_resource().await.unwrap();

        assert_eq!(session.api_url(), Some("/jmap/"));
        assert!(session.supports_calendars());
        assert!(session.supports_address_books());

        assert_eq!(session, session2);
    }

    #[tokio::test]
    async fn test_record_methods() {
        let setup = setup_test_client().await;
        let jmap = setup.client;
        let session = setup.session;

        assert!(session.supports_calendars());
        assert!(session.supports_address_books());
        assert_eq!(session.api_url(), Some("/jmap/"));

        let initial_count = jmap.get_records::<Calendar>("Default").await.unwrap().len();

        let event = json!({
            // "@type": "CalendarEvent",
            "title": "Meeting with Bob",
            "start": "2025-07-10T10:00:00",
            "duration": "PT1H"
        });
        let created = jmap
            .create_record::<Calendar>("Default", &event, None)
            .await
            .unwrap();

        let records = jmap.get_records::<Calendar>("Default").await.unwrap();
        let post_create_count = records.len();
        assert!(records.iter().any(|r| r.id == created.id));
        assert_eq!(initial_count + 1, post_create_count);

        // Update with bogus state.
        let updated_event = json!({
            "title": "Updated Meeting with Bob",
            "start": "2025-07-10T10:00:00",
            "duration": "PT1H"
        });
        jmap.update_record::<Calendar>(&created.id, "Default", &updated_event, Some("0"))
            .await
            .unwrap_err();

        // Update with no state.
        let updated = jmap
            .update_record::<Calendar>(&created.id, "Default", &updated_event, None)
            .await
            .unwrap();
        assert_eq!(updated.id, created.id);
        assert_ne!(updated.state, created.state); // State should change after update

        // Update with correct state.
        let updated_event = json!({
            "title": "Updated Meeting with Bobby",
            "start": "2025-07-10T10:00:00",
            "duration": "PT1H"
        });
        let updated = jmap
            .update_record::<Calendar>(&created.id, "Default", &updated_event, Some(&updated.state))
            .await
            .unwrap();
        assert_eq!(updated.id, created.id);
        assert_ne!(updated.state, created.state); // State should change after update

        let records_after_update = jmap.get_records::<Calendar>("Default").await.unwrap();
        let updated_record = records_after_update
            .iter()
            .find(|r| r.id == created.id)
            .unwrap();
        assert_eq!(updated_record.data["title"], "Updated Meeting with Bobby");

        // Deletion with bogus state.
        jmap.delete_record::<Calendar>(&created.id, Some("0"))
            .await
            .unwrap_err();
        let records = jmap.get_records::<Calendar>("Default").await.unwrap();
        let failed_delete_count = records.len();
        assert!(records.iter().any(|r| r.id == created.id));
        assert_eq!(post_create_count, failed_delete_count);

        // Deletion with no state.
        jmap.delete_record::<Calendar>(&created.id, None)
            .await
            .unwrap();
        let records = jmap.get_records::<Calendar>("Default").await.unwrap();
        let post_delete_count = records.len();
        assert!(!records.iter().any(|r| r.id == created.id));
        assert_eq!(initial_count, post_delete_count);
    }

    #[tokio::test]
    async fn changes() {
        let setup = setup_test_client().await;
        let jmap = setup.client;

        // Create first event.
        let event1 = json!({
            "title": "Initial Event",
            "start": "2025-07-09T10:00:00",
            "duration": "PT1H"
        });
        let created1 = jmap
            .create_record::<Calendar>("Default", &event1, None)
            .await
            .unwrap();

        // Keep baseline state.
        let baseline_state = created1.state.clone();

        // Create second event.
        let event2 = json!({
            "title": "Test Event for Changes",
            "start": "2025-07-10T10:00:00",
            "duration": "PT1H"
        });
        let created2 = jmap
            .create_record::<Calendar>("Default", &event2, None)
            .await
            .unwrap();

        // Get changes since baseline.
        let changes = jmap
            .changes::<Calendar>(&baseline_state, None)
            .await
            .unwrap();
        assert!(changes.created.contains(&created2.id));
        assert!(!changes.has_more_changes);
        assert_ne!(changes.old_state, changes.new_state);

        // Update second event.
        let updated_event = json!({
            "title": "Updated Test Event",
            "start": "2025-07-10T11:00:00",
            "duration": "PT2H"
        });
        let state_before_update = changes.new_state.clone();
        jmap.update_record::<Calendar>(&created2.id, "Default", &updated_event, None)
            .await
            .unwrap();

        // Get changes since baseline.
        let changes = jmap
            .changes::<Calendar>(&state_before_update, Some(100))
            .await
            .unwrap();
        assert!(changes.updated.contains(&created2.id));
        assert!(!changes.created.contains(&created2.id));

        // Delete second event.
        let state_before_delete = changes.new_state.clone();
        jmap.delete_record::<Calendar>(&created2.id, None)
            .await
            .unwrap();

        // Get changes since before deletion.
        let changes = jmap
            .changes::<Calendar>(&state_before_delete, None)
            .await
            .unwrap();
        assert!(changes.destroyed.contains(&created2.id));
        assert!(!changes.updated.contains(&created2.id));
    }

    #[tokio::test]
    async fn changed_since() {
        let setup = setup_test_client().await;
        let jmap = setup.client;

        // Create an event.
        let event1 = json!({
            "title": "Test Event for Changes",
            "start": "2025-07-10T10:00:00",
            "duration": "PT1H"
        });
        let created1 = jmap
            .create_record::<Calendar>("Default", &event1, None)
            .await
            .unwrap();
        let state_after_create = created1.state.clone();

        // Check that the item shows as NotChanged when checking against its creation state.
        let (status, _new_state) = jmap
            .changed_since::<Calendar>(&created1.id, &state_after_create)
            .await
            .unwrap();
        assert_eq!(status, ChangeStatus::NotChanged);

        // Create another event to change the state.
        let event2 = json!({
            "title": "Another Event",
            "start": "2025-07-11T10:00:00",
            "duration": "PT1H"
        });
        let _created2 = jmap
            .create_record::<Calendar>("Default", &event2, None)
            .await
            .unwrap();

        // Original item should still be NotChanged relative to its creation state.
        let (status, _new_state) = jmap
            .changed_since::<Calendar>(&created1.id, &state_after_create)
            .await
            .unwrap();
        assert_eq!(status, ChangeStatus::NotChanged);

        // Update the first event.
        let updated_event = json!({
            "title": "Updated Test Event",
            "start": "2025-07-10T10:00:00",
            "duration": "PT1H"
        });
        let _updated1 = jmap
            .update_record::<Calendar>(&created1.id, "Default", &updated_event, None)
            .await
            .unwrap();

        // Now it should show as Changed.
        let (status, _new_state) = jmap
            .changed_since::<Calendar>(&created1.id, &state_after_create)
            .await
            .unwrap();
        assert_eq!(status, ChangeStatus::Changed);

        // Delete the first event.
        jmap.delete_record::<Calendar>(&created1.id, None)
            .await
            .unwrap();

        // Now it should show as Deleted.
        let (status, _new_state) = jmap
            .changed_since::<Calendar>(&created1.id, &state_after_create)
            .await
            .unwrap();
        assert_eq!(status, ChangeStatus::Deleted);
    }

    #[test]
    fn parse_get_calendar_success() {
        let body = r#"
{
  "methodResponses": [
    [
      "Calendar/get",
      {
        "state": "18",
        "list": [
          {
            "id": "Default",
            "name": "personal",
            "description": null,
            "sortOrder": 0,
            "isVisible": true,
            "isSubscribed": true,
            "includeInAvailability": "all",
            "timeZone": null,
            "myRights": {
              "mayReadFreeBusy": true,
              "mayReadItems": true,
              "mayWriteAll": true,
              "mayWriteOwn": true,
              "mayUpdatePrivate": true,
              "mayRSVP": true,
              "mayDelete": true,
              "mayAdmin": true
            },
            "shareWith": null
          }
        ],
        "notFound": [],
        "accountId": "user1"
      },
      "0"
    ]
  ],
  "sessionState": "0"
}
"#;

        let expected = vec![Calendar {
            id: "Default".into(),
            name: "personal".into(),
            description: None,
            color: None,
            sort_order: 0,
        }];
        let mut parsed_body: JmapResponse<GetResponse<Calendar>> =
            serde_json::from_slice(body.as_bytes()).unwrap();
        let method_response = parsed_body.method_responses.pop().unwrap();
        let got = method_response.1.into_result().unwrap().list;

        assert_eq!(expected, got);
    }

    #[test]
    fn parse_error_response_state_mismatch() {
        let body = serde_json::json!( {
            "methodResponses": [
                [ "error", { "type": "stateMismatch" }, "0" ]
            ],
            "sessionState": "0"
        })
        .to_string();

        let parsed_body: JmapResponse<SetResponse<JsonValue>> =
            serde_json::from_str(&body).unwrap();

        assert_eq!(parsed_body.method_responses.len(), 1);
        let method_response = &parsed_body.method_responses[0];

        assert_eq!(method_response.0, "error");
        assert_eq!(method_response.2, "0");

        match &method_response.1 {
            MethodResponseData::Error(error) => {
                assert_eq!(error.error_type, "stateMismatch");
                assert_eq!(error.properties, None);
                assert_eq!(error.description, None);
            }
            MethodResponseData::Success(_) => panic!("Expected error response, got success"),
        }
    }

    #[test]
    fn parse_error_response_unknown_method() {
        let body = serde_json::json!( {
            "methodResponses": [
                [ "error", { "type": "unknownMethod" }, "call-id" ]
            ],
            "sessionState": "0"
        })
        .to_string();

        let parsed_body: JmapResponse<JsonValue> = serde_json::from_str(&body).unwrap();

        assert_eq!(parsed_body.method_responses.len(), 1);
        let method_response = &parsed_body.method_responses[0];

        assert_eq!(method_response.0, "error");
        assert_eq!(method_response.2, "call-id");

        match &method_response.1 {
            MethodResponseData::Error(error) => {
                assert_eq!(error.error_type, "unknownMethod");
            }
            MethodResponseData::Success(_) => panic!("Expected error response, got success"),
        }
    }
}