up_api/v1/

categories.rs

use crate::v1::{Client, error, BASE_URL};

use serde::{Deserialize, Serialize};

// ----------------- Response Objects -----------------

#[derive(Deserialize, Debug)]
pub struct ListCategoriesResponse {
    /// The list of categories returned in this response.
    pub data : Vec<CategoryResource>,
}

#[derive(Deserialize, Debug)]
pub struct GetCategoryResponse {
    /// The category returned in this response.
    pub data : CategoryResource,

}

#[derive(Deserialize, Debug)]
pub struct CategoryResource {
    /// The type of this resource: categories
    pub r#type : String,
    /// The unique identifier for this category. This is a human-readable but URL-safe value.
    pub id : String,
    pub attributes : Attributes,
    pub relationships : Relationships,
    pub links : Option<CategoryResourceLinks>,
}

#[derive(Deserialize, Debug)]
pub struct Attributes {
    /// The name of this category as seen in the Up application.
    pub name : String,
}

#[derive(Deserialize, Debug)]
pub struct Relationships {
    pub parent : Parent,
    pub children : Children,
}

#[derive(Deserialize, Debug)]
pub struct Parent {
    pub data : Option<ParentData>,
    pub links : Option<ParentLinks>,
}

#[derive(Deserialize, Debug)]
pub struct ParentData {
    /// The type of this resource: `categories`
    pub r#type : String,
    /// The unique identifier of the resource within its type.
    pub id : String,
}

#[derive(Deserialize, Debug)]
pub struct ParentLinks {
    /// The link to retrieve the related resource(s) in this relationship.
    pub related : String,
}

#[derive(Deserialize, Debug)]
pub struct Children {
    pub data : Vec<ChildrenData>,
    pub links : Option<ChildrenLinks>,
}

#[derive(Deserialize, Debug)]
pub struct ChildrenData {
    /// The type of this resource: `categories`
    pub r#type : String,
    /// The unique identifier of the resource within its type.
    pub id : String,
}

#[derive(Deserialize, Debug)]
pub struct ChildrenLinks {
    /// The link to retrieve the related resource(s) in this relationship.
    pub related : String,
}

#[derive(Deserialize, Debug)]
pub struct CategoryResourceLinks {
    /// The canonical link to this resource within the API.
    #[serde(rename = "self")]
    pub this : String,
}

// ----------------- Input Objects -----------------

#[derive(Default)]
pub struct ListCategoriesOptions {
    /// The unique identifier of a parent category for which to return only its children.
    filter_parent : Option<String>,
}

impl ListCategoriesOptions {
    /// Sets the parent filter value.
    pub fn filter_parent(&mut self, value : String) {
        self.filter_parent = Some(value);
    }

    fn add_params(&self, url : &mut reqwest::Url) {
        let mut query = String::new();

        if let Some(value) = &self.filter_parent {
            if !query.is_empty() {
                query.push('&');
            }
            query.push_str(&format!("filter[parent]={}", urlencoding::encode(value)));
        }

        if !query.is_empty() {
            url.set_query(Some(&query));
        }
    }
}

// ----------------- Request Objects -----------------

#[derive(Serialize)]
struct CategoriseTransactionRequest {
    /// The category to set on the transaction. Set this entire key to `null` de-categorize a transaction.
    data : Option<CategoryInputResourceIdentifier>,
}

#[derive(Serialize)]
struct CategoryInputResourceIdentifier {
    /// The type of this resource: `categories`
    r#type : String,
    /// The unique identifier of the category, as returned by the `list_categories` method.
    id : String,
}

impl Client {
    /// Retrieve a list of all categories and their ancestry. The returned list is not paginated.
    pub async fn list_categories(&self, options : &ListCategoriesOptions) -> Result<ListCategoriesResponse, error::Error> {
        let mut url = reqwest::Url::parse(&format!("{}/categories", BASE_URL)).map_err(error::Error::UrlParse)?;
        options.add_params(&mut url);

        let res = reqwest::Client::new()
            .get(url)
            .header("Authorization", self.auth_header())
            .send()
            .await
            .map_err(error::Error::Request)?;

        match res.status() {
            reqwest::StatusCode::OK => {
                let body = res.text().await.map_err(error::Error::BodyRead)?;
                let category_response : ListCategoriesResponse = serde_json::from_str(&body).map_err(error::Error::Json)?;

                Ok(category_response)
            },
            _ => {
                let body = res.text().await.map_err(error::Error::BodyRead)?;
                let error : error::ErrorResponse = serde_json::from_str(&body).map_err(error::Error::Json)?;

                Err(error::Error::Api(error))
            }
        }
    }

    /// Retrieve a specific category by providing its unique identifier.
    pub async fn get_category(&self, id : &str) -> Result<GetCategoryResponse, error::Error> {
        // This assertion is because without an ID the request is thought to be a request for
        // many categories, and therefore the error messages are very unclear.
        if id.is_empty() {
            panic!("The provided category ID must not be empty.");
        }

        let url = reqwest::Url::parse(&format!("{}/categories/{}", BASE_URL, id)).map_err(error::Error::UrlParse)?;

        let res = reqwest::Client::new()
            .get(url)
            .header("Authorization", self.auth_header())
            .send()
            .await
            .map_err(error::Error::Request)?;

        match res.status() {
            reqwest::StatusCode::OK => {
                let body = res.text().await.map_err(error::Error::BodyRead)?;
                let category_response : GetCategoryResponse = serde_json::from_str(&body).map_err(error::Error::Json)?;

                Ok(category_response )
            },
            _ => {
                let body = res.text().await.map_err(error::Error::BodyRead)?;
                let error : error::ErrorResponse = serde_json::from_str(&body).map_err(error::Error::Json)?;

                Err(error::Error::Api(error))
            }
        }
    }

    /// Updates the category associated with a transaction. Only transactions for which `is_categorizable` is set to true support this operation. The `id` is taken from the list exposed on `list_categories` and cannot be one of the top-level (parent) categories. To de-categorize a transaction, set the entire `data` key to `null`. The associated category, along with its request URL is also exposed via the category relationship on the transaction resource returned from `get_transaction`.
    pub async fn categorise_transaction(&self, transaction_id : &str, category : Option<&str>) -> Result<(), error::Error> {
        let url = reqwest::Url::parse(&format!("{}/transactions/{}/relationships/category", BASE_URL, transaction_id)).map_err(error::Error::UrlParse)?;

        let category = category.map(|id| {
            CategoryInputResourceIdentifier {
                r#type : String::from("categories"),
                id : String::from(id),
            }
        });

        let body = CategoriseTransactionRequest  { data : category };
        let body = serde_json::to_string(&body).map_err(error::Error::Serialize)?;

        println!("{}", body);

        let res = reqwest::Client::new()
            .patch(url)
            .header("Authorization", self.auth_header())
            .header("Content-Type", "application/json")
            .body(body)
            .send()
            .await
            .map_err(error::Error::Request)?;

        match res.status() {
            reqwest::StatusCode::NO_CONTENT => {
                Ok(())
            },
            _ => {
                let body = res.text().await.map_err(error::Error::BodyRead)?;
                let error : error::ErrorResponse = serde_json::from_str(&body).map_err(error::Error::Json)?;

                Err(error::Error::Api(error))
            }
        }
    }
}