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.

//! Projects operations.

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

use bytes::Bytes;

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

/// Optional query parameters for `UpdateProjectWallpaper`.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct UpdateProjectWallpaperParams {
    /// How the wallpaper is laid out. Omitted, the project's current mode is kept.
    pub mode: Option<String>,
}

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

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

    /// Archive a project, removing it from the active project list (returns 204 No Content).
    /// Accounts on the admin pro pack may restrict archiving to admins and the project's
    /// creator, which answers 403.
    ///
    /// `PUT /projects/{projectId}/status/archived.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn archive(&self, project_id: i64) -> Result<(), Error> {
        let operation = self
            .client
            .operation(&routes::ARCHIVE_PROJECT, &[&project_id]);
        self.client.send_unit(operation).await
    }

    /// Create a new project
    ///
    /// `POST /projects.json` — not idempotent, sent exactly once.
    pub async fn create(
        &self,
        body: &CreateProjectRequestContent,
    ) -> Result<CreateProjectResponseContent, Error> {
        let mut operation = self.client.operation(&routes::CREATE_PROJECT, &[]);
        operation.json(body)?;
        self.client.send(operation).await
    }

    /// Get a single project by id
    ///
    /// `GET /projects/{projectId}` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn get(&self, project_id: i64) -> Result<GetProjectResponseContent, Error> {
        let operation = self.client.operation(&routes::GET_PROJECT, &[&project_id]);
        self.client.send(operation).await
    }

    /// List projects (active by default; optionally archived/trashed)
    ///
    /// **Pagination**: Uses Link header (RFC5988). Follow the `next` rel URL
    /// to fetch additional pages. X-Total-Count header provides total count.
    ///
    /// `GET /projects.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn list(
        &self,
        params: &ListProjectsParams,
    ) -> Result<Page<ListProjectsResponseContent>, Error> {
        let mut operation = self.client.operation(&routes::LIST_PROJECTS, &[]);
        operation.query_optional("status", params.status.as_ref());
        operation.query_optional("page", params.page.as_ref());
        self.client.send_page(operation).await
    }

    /// List the projects the current user has most recently visited, most recent visit first.
    /// Reads the per-user visit log — capped at the 50 most recent visits, keeping
    /// only active projects the user can still access — not the home grid's
    /// pinned-exclusion and padding. This endpoint is not paginated. Each entry is
    /// the standard project projection plus the current user's bookmarked flag. A
    /// visit is recorded when the user opens a project in Basecamp, when they
    /// create one, and by RecordProjectVisit.
    ///
    /// `GET /my/recent_projects.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn list_recent_projects(&self) -> Result<ListRecentProjectsResponseContent, Error> {
        let operation = self.client.operation(&routes::LIST_RECENT_PROJECTS, &[]);
        self.client.send(operation).await
    }

    /// Record that the current user visited a project, moving it to the front of ListRecentProjects (returns 204 No Content).
    /// Idempotent: re-recording a visit refreshes the same entry. Visits to
    /// archived or trashed projects are accepted but not recorded, and an
    /// inaccessible project answers 404.
    ///
    /// `POST /projects/{projectId}/recent_visit.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn record_project_visit(&self, project_id: i64) -> Result<(), Error> {
        let operation = self
            .client
            .operation(&routes::RECORD_PROJECT_VISIT, &[&project_id]);
        self.client.send_unit(operation).await
    }

    /// Remove the project's logo (returns 204 even when absent). Wallpaper is unchanged.
    /// People and agents who can edit the project may use this operation; others get 403, and projects outside the caller's visibility get 404.
    ///
    /// `DELETE /projects/{projectId}/logo.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn remove_project_logo(&self, project_id: i64) -> Result<(), Error> {
        let operation = self
            .client
            .operation(&routes::REMOVE_PROJECT_LOGO, &[&project_id]);
        self.client.send_unit(operation).await
    }

    /// Remove the project's wallpaper (returns 204 No Content).
    /// People and personal assistants follow project-edit permissions; shared agents are refused.
    ///
    /// `DELETE /projects/{projectId}/wallpaper.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn remove_project_wallpaper(&self, project_id: i64) -> Result<(), Error> {
        let operation = self
            .client
            .operation(&routes::REMOVE_PROJECT_WALLPAPER, &[&project_id]);
        self.client.send_unit(operation).await
    }

    /// Trash a project (returns 204 No Content)
    ///
    /// `DELETE /projects/{projectId}` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn trash(&self, project_id: i64) -> Result<(), Error> {
        let operation = self
            .client
            .operation(&routes::TRASH_PROJECT, &[&project_id]);
        self.client.send_unit(operation).await
    }

    /// Restore a project to active status from trash as well as from the archive (returns 204 No Content).
    /// This is the inverse of both ArchiveProject and TrashProject. Restoring counts against
    /// the account's project limit, so it answers 507 when that limit is already reached.
    ///
    /// `PUT /projects/{projectId}/status/active.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn unarchive(&self, project_id: i64) -> Result<(), Error> {
        let operation = self
            .client
            .operation(&routes::UNARCHIVE_PROJECT, &[&project_id]);
        self.client.send_unit(operation).await
    }

    /// Update an existing project
    ///
    /// `PUT /projects/{projectId}` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn update(
        &self,
        project_id: i64,
        body: &UpdateProjectRequestContent,
    ) -> Result<UpdateProjectResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::UPDATE_PROJECT, &[&project_id]);
        operation.json(body)?;
        self.client.send(operation).await
    }

    /// Upload or replace the project's logo (returns 204 No Content).
    /// Uses the existing project image formats; maximum 5 MiB. Wallpaper is unchanged.
    /// People and agents who can edit the project may use this operation; others get 403, and projects outside the caller's visibility get 404.
    ///
    /// `PUT /projects/{projectId}/logo.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn update_project_logo(
        &self,
        project_id: i64,
        filename: &str,
        content_type: &str,
        body: Bytes,
    ) -> Result<(), Error> {
        let mut operation = self
            .client
            .operation(&routes::UPDATE_PROJECT_LOGO, &[&project_id]);
        operation.multipart("logo", filename, content_type, &body);
        self.client.send_unit(operation).await
    }

    /// Upload or replace the project's wallpaper (returns 204 No Content).
    /// Uses the project's existing image validations, including GIF, HEIC and HEIF. Maximum 10 MB.
    /// People and personal assistants follow project-edit permissions; shared agents are refused.
    ///
    /// `PUT /projects/{projectId}/wallpaper.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn update_project_wallpaper(
        &self,
        project_id: i64,
        params: &UpdateProjectWallpaperParams,
        filename: &str,
        content_type: &str,
        body: Bytes,
    ) -> Result<(), Error> {
        let mut operation = self
            .client
            .operation(&routes::UPDATE_PROJECT_WALLPAPER, &[&project_id]);
        operation.query_optional("mode", params.mode.as_ref());
        operation.multipart("wallpaper", filename, content_type, &body);
        self.client.send_unit(operation).await
    }
}