basecamp-sdk 0.38.0

Official client for Basecamp - https://basecamp.com
Documentation
// Generated by basecamp-sdk-generator from openapi.json and behavior-model.json. DO NOT EDIT.

//! Todolists operations.

#![allow(
    clippy::too_many_arguments,
    clippy::wildcard_imports,
    clippy::doc_markdown
)]

use crate::client::AccountClient;
use crate::error::Error;
use crate::generated::routes;
#[allow(unused_imports)]
use crate::generated::types::*;
use crate::pagination::Page;

/// Optional query parameters for `ListTodolists`.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct ListTodolistsParams {
    /// active|archived|trashed
    pub status: Option<String>,
    /// Page number for paginating through results. Defaults to 1. A positive value selects exactly that page, not a starting offset; see SPEC section 8.
    pub page: Option<i32>,
}

/// `Todolists` operations, sent through one [`AccountClient`].
#[derive(Debug, Clone, Copy)]
pub struct TodolistsService<'a> {
    client: &'a AccountClient,
}

impl<'a> TodolistsService<'a> {
    pub(crate) fn new(client: &'a AccountClient) -> Self {
        Self { client }
    }

    /// The client this service sends through.
    pub fn client(&self) -> &'a AccountClient {
        self.client
    }

    /// Create a new todolist in a todoset
    ///
    /// `POST /todosets/{todosetId}/todolists.json` — not idempotent, sent exactly once.
    pub async fn create(
        &self,
        todoset_id: i64,
        body: &CreateTodolistRequestContent,
    ) -> Result<CreateTodolistResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::CREATE_TODOLIST, &[&todoset_id]);
        operation.json(body)?;
        self.client.send(operation).await
    }

    /// Get a single todolist or todolist group by id
    /// The endpoint is polymorphic, but it answers with one shape: BC3 has no group
    /// model, so both variants come back as a flat Todolist (see the Todolist shape).
    ///
    /// `GET /todolists/{id}` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn get(&self, id: i64) -> Result<GetTodolistOrGroupResponseContent, Error> {
        let operation = self
            .client
            .operation(&routes::GET_TODOLIST_OR_GROUP, &[&id]);
        self.client.send(operation).await
    }

    /// List todolists in a todoset
    ///
    /// **Pagination**: Uses Link header (RFC5988). Follow the `next` rel URL
    /// to fetch additional pages. X-Total-Count header provides total count.
    ///
    /// `GET /todosets/{todosetId}/todolists.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn list(
        &self,
        todoset_id: i64,
        params: &ListTodolistsParams,
    ) -> Result<Page<ListTodolistsResponseContent>, Error> {
        let mut operation = self
            .client
            .operation(&routes::LIST_TODOLISTS, &[&todoset_id]);
        operation.query_optional("status", params.status.as_ref());
        operation.query_optional("page", params.page.as_ref());
        self.client.send_page(operation).await
    }

    /// Replace a todolist (or todolist group) with a new complete representation.
    /// The endpoint is polymorphic - it addresses a to-do list or a group, and answers
    /// with the same flat Todolist shape either way.
    /// The request body is the recordable's full writable state: TodolistsController#update
    /// builds a brand-new Todolist from the permitted params and swaps it in, so any
    /// writable field omitted from the request is cleared server-side (a request that
    /// omits description erases the description). name is required - it is
    /// presence-validated on the model, so a request without it is rejected.
    /// To set some fields while preserving the rest, use the SDK's merge-safe
    /// update or edit methods, which GET the current list and PUT the full
    /// representation back. Those read-modify-write helpers are not atomic:
    /// a concurrent write between the GET and PUT is overwritten (last write
    /// wins for the whole representation; the window is one round-trip).
    ///
    /// `PUT /todolists/{id}` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn replace(
        &self,
        id: i64,
        body: &UpdateTodolistOrGroupRequestContent,
    ) -> Result<UpdateTodolistOrGroupResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::UPDATE_TODOLIST_OR_GROUP, &[&id]);
        operation.json(body)?;
        self.client.send(operation).await
    }

    /// Reposition a to-do list within its to-do set.
    /// position is the 1-based index among the to-do lists the caller can see; the server
    /// translates it relative to loose to-dos and hidden completed lists. Shifts siblings.
    ///
    /// `PUT /todosets/todolists/{todolistId}/position.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn reposition(
        &self,
        todolist_id: i64,
        body: &RepositionTodolistRequestContent,
    ) -> Result<(), Error> {
        let mut operation = self
            .client
            .operation(&routes::REPOSITION_TODOLIST, &[&todolist_id]);
        operation.json(body)?;
        self.client.send_unit(operation).await
    }
}