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.

//! HillCharts 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 `ListHillChartVersions`.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct ListHillChartVersionsParams {
    /// 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>,
}

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

impl<'a> HillChartsService<'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
    }

    /// Post a progress update on a todoset's hill chart.
    ///
    /// Moves the todolists named in `dots` and saves a progress update, as
    /// updating the hill chart in Basecamp does. Todolists left out of `dots` keep
    /// their current position, so one dot can move without sending the others.
    /// Every field is optional: with none, the update records the chart as it
    /// stands. To track or untrack a todolist, use `UpdateHillChartSettings`.
    ///
    /// Answers 201 with the new progress update, in the shape
    /// `GetHillChartVersion` returns, including where every tracked todolist now
    /// sits. Answers 422, with an `error` message and nothing saved, when `dots`
    /// isn't a list of objects, a todolist appears in it more than once or isn't
    /// tracked on the chart, a `position` isn't a whole number from 0 to 100, or
    /// the chart tracks no todolists.
    ///
    /// `POST /todosets/{todosetId}/hills/versions.json` — not idempotent, sent exactly once.
    pub async fn create_version(
        &self,
        todoset_id: i64,
        body: &CreateHillChartVersionRequestContent,
    ) -> Result<CreateHillChartVersionResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::CREATE_HILL_CHART_VERSION, &[&todoset_id]);
        operation.json(body)?;
        self.client.send(operation).await
    }

    /// Get the hill chart for a todoset
    ///
    /// `GET /todosets/{todosetId}/hill.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn get(&self, todoset_id: i64) -> Result<GetHillChartResponseContent, Error> {
        let operation = self
            .client
            .operation(&routes::GET_HILL_CHART, &[&todoset_id]);
        self.client.send(operation).await
    }

    /// Get one progress update from a todoset's hill chart
    ///
    /// `GET /todosets/{todosetId}/hills/versions/{versionId}` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn get_version(
        &self,
        todoset_id: i64,
        version_id: i64,
    ) -> Result<GetHillChartVersionResponseContent, Error> {
        let operation = self
            .client
            .operation(&routes::GET_HILL_CHART_VERSION, &[&todoset_id, &version_id]);
        self.client.send(operation).await
    }

    /// List the progress updates on a todoset's hill chart, newest first.
    ///
    /// Each time someone updates a hill chart, Basecamp saves a progress update:
    /// the note they wrote (`description`, rich text) and where each tracked
    /// todolist sat on the hill at that moment (`dots`). Earlier updates are kept,
    /// so this list is the hill chart's history. Discussion on an update is read
    /// through its `comments_url`.
    ///
    /// To collect updates across projects, read the progress report: events with
    /// a `kind` of `hill_version_created` have a `url` that `GetHillChartVersion`
    /// answers.
    ///
    /// **Pagination**: Uses Link header (RFC5988). Follow the `next` rel URL
    /// to fetch additional pages. X-Total-Count header provides total count.
    ///
    /// `GET /todosets/{todosetId}/hills/versions.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn list_versions(
        &self,
        todoset_id: i64,
        params: &ListHillChartVersionsParams,
    ) -> Result<Page<ListHillChartVersionsResponseContent>, Error> {
        let mut operation = self
            .client
            .operation(&routes::LIST_HILL_CHART_VERSIONS, &[&todoset_id]);
        operation.query_optional("page", params.page.as_ref());
        self.client.send_page(operation).await
    }

    /// Track or untrack todolists on a hill chart
    ///
    /// `PUT /todosets/{todosetId}/hills/settings.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn update_settings(
        &self,
        todoset_id: i64,
        body: &UpdateHillChartSettingsRequestContent,
    ) -> Result<UpdateHillChartSettingsResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::UPDATE_HILL_CHART_SETTINGS, &[&todoset_id]);
        operation.json(body)?;
        self.client.send(operation).await
    }
}