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.

//! People 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 `ListPeople`.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct ListPeopleParams {
    /// 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 `ListProjectPeople`.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct ListProjectPeopleParams {
    /// 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>,
}

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

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

    /// Disable out of office for a person.
    /// Admins on Pro Pack accounts can manage others; otherwise self only.
    ///
    /// `DELETE /people/{personId}/out_of_office.json` — idempotent; retries up to 2 attempt(s) on 429, 503.
    pub async fn disable_out_of_office(&self, person_id: i64) -> Result<(), Error> {
        let operation = self
            .client
            .operation(&routes::DISABLE_OUT_OF_OFFICE, &[&person_id]);
        self.client.send_unit(operation).await
    }

    /// Disable clients on a project
    ///
    /// 403 while the project still has any client users — revoke them first with
    /// UpdateProjectClientAccess. Naturally idempotent: disabling a project with
    /// clients already off re-answers `{"clients_enabled": false}`.
    ///
    /// `DELETE /projects/{projectId}/client_enablement.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn disable_project_clients(
        &self,
        project_id: i64,
    ) -> Result<DisableProjectClientsResponseContent, Error> {
        let operation = self
            .client
            .operation(&routes::DISABLE_PROJECT_CLIENTS, &[&project_id]);
        self.client.send(operation).await
    }

    /// Enable or replace out of office for a person.
    /// Admins on Pro Pack accounts can manage others; otherwise self only.
    ///
    /// `POST /people/{personId}/out_of_office.json` — not idempotent, sent exactly once.
    pub async fn enable_out_of_office(
        &self,
        person_id: i64,
        body: &EnableOutOfOfficeRequestContent,
    ) -> Result<EnableOutOfOfficeResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::ENABLE_OUT_OF_OFFICE, &[&person_id]);
        operation.json(body)?;
        self.client.send(operation).await
    }

    /// Enable clients on a project so client users can be added to it
    ///
    /// A deliberate step separate from adding clients: it turns on the project's
    /// client-facing surface and applies the default client visibility (the
    /// timeline and most docked tools become client-visible; the card table,
    /// Campfire, and Doors stay private). UpdateProjectClientAccess never enables
    /// clients implicitly — enable first, then add. 403 unless the project can have
    /// clients (the account supports clients and the project is a standard
    /// project). Naturally idempotent: enabling an enabled project re-answers
    /// `{"clients_enabled": true}`.
    ///
    /// `POST /projects/{projectId}/client_enablement.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn enable_project_clients(
        &self,
        project_id: i64,
    ) -> Result<EnableProjectClientsResponseContent, Error> {
        let operation = self
            .client
            .operation(&routes::ENABLE_PROJECT_CLIENTS, &[&project_id]);
        self.client.send(operation).await
    }

    /// Get a person by ID
    ///
    /// `GET /people/{personId}` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn get(&self, person_id: i64) -> Result<GetPersonResponseContent, Error> {
        let operation = self.client.operation(&routes::GET_PERSON, &[&person_id]);
        self.client.send(operation).await
    }

    /// List all people visible to the current user
    ///
    /// **Pagination**: Uses Link header (RFC5988). Follow the `next` rel URL
    /// to fetch additional pages. X-Total-Count header provides total count.
    ///
    /// `GET /people.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn list(
        &self,
        params: &ListPeopleParams,
    ) -> Result<Page<ListPeopleResponseContent>, Error> {
        let mut operation = self.client.operation(&routes::LIST_PEOPLE, &[]);
        operation.query_optional("page", params.page.as_ref());
        self.client.send_page(operation).await
    }

    /// List people who can be assigned todos
    ///
    /// `GET /reports/todos/assigned.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn list_assignable(&self) -> Result<ListAssignablePeopleResponseContent, Error> {
        let operation = self.client.operation(&routes::LIST_ASSIGNABLE_PEOPLE, &[]);
        self.client.send(operation).await
    }

    /// List all active people on a project
    ///
    /// **Pagination**: Uses Link header (RFC5988). Follow the `next` rel URL
    /// to fetch additional pages. X-Total-Count header provides total count.
    ///
    /// `GET /projects/{projectId}/people.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn list_for_project(
        &self,
        project_id: i64,
        params: &ListProjectPeopleParams,
    ) -> Result<Page<ListProjectPeopleResponseContent>, Error> {
        let mut operation = self
            .client
            .operation(&routes::LIST_PROJECT_PEOPLE, &[&project_id]);
        operation.query_optional("page", params.page.as_ref());
        self.client.send_page(operation).await
    }

    /// List all account users who can be pinged
    ///
    /// **Pagination**: Uses Link header (RFC5988). Follow the `next` rel URL
    /// to fetch additional pages. X-Total-Count header provides total count.
    ///
    /// `GET /circles/people.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn list_pingable(&self) -> Result<Page<ListPingablePeopleResponseContent>, Error> {
        let operation = self.client.operation(&routes::LIST_PINGABLE_PEOPLE, &[]);
        self.client.send_page(operation).await
    }

    /// Get the current authenticated user's profile
    ///
    /// `GET /my/profile.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn me(&self) -> Result<GetMyProfileResponseContent, Error> {
        let operation = self.client.operation(&routes::GET_MY_PROFILE, &[]);
        self.client.send(operation).await
    }

    /// Get the current user's preferences
    ///
    /// `GET /my/preferences.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn my_preferences(&self) -> Result<GetMyPreferencesResponseContent, Error> {
        let operation = self.client.operation(&routes::GET_MY_PREFERENCES, &[]);
        self.client.send(operation).await
    }

    /// Get the out of office status for a person
    ///
    /// `GET /people/{personId}/out_of_office.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn out_of_office(
        &self,
        person_id: i64,
    ) -> Result<GetOutOfOfficeResponseContent, Error> {
        let operation = self
            .client
            .operation(&routes::GET_OUT_OF_OFFICE, &[&person_id]);
        self.client.send(operation).await
    }

    /// Update the current user's preferences.
    /// Rejections arrive as a field-keyed 422
    /// ({"errors": {"time_zone_name": \["is not included in the list"\]}}), not the
    /// flat {error} body.
    ///
    /// `PUT /my/preferences.json` — idempotent; retries up to 2 attempt(s) on 429, 503.
    pub async fn update_my_preferences(
        &self,
        body: &UpdateMyPreferencesRequestContent,
    ) -> Result<UpdateMyPreferencesResponseContent, Error> {
        let mut operation = self.client.operation(&routes::UPDATE_MY_PREFERENCES, &[]);
        operation.json(body)?;
        self.client.send(operation).await
    }

    /// Update the current authenticated user's profile (returns 204 No Content)
    ///
    /// `PUT /my/profile.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn update_my_profile(
        &self,
        body: &UpdateMyProfileRequestContent,
    ) -> Result<(), Error> {
        let mut operation = self.client.operation(&routes::UPDATE_MY_PROFILE, &[]);
        operation.json(body)?;
        self.client.send_unit(operation).await
    }

    /// Update project access (grant/revoke/create people)
    ///
    /// `PUT /projects/{projectId}/people/users.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn update_project_access(
        &self,
        project_id: i64,
        body: &UpdateProjectAccessRequestContent,
    ) -> Result<UpdateProjectAccessResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::UPDATE_PROJECT_ACCESS, &[&project_id]);
        operation.json(body)?;
        self.client.send(operation).await
    }

    /// Update project client access (grant/revoke/create client users)
    ///
    /// The client-side counterpart to UpdateProjectAccess: `grant` adds existing
    /// client users by id, `revoke` removes client users, and `create` invites
    /// brand-new clients by email (`name` optional, defaulting to the address).
    /// Only client users are eligible — a `grant` id belonging to a team member is
    /// rejected (omitted from `granted`) rather than cross-graded, and `revoke` never removes a team
    /// member. The response mirrors UpdateProjectAccess: `granted` and `revoked`
    /// people, each with `client: true`.
    ///
    /// Requires clients to be enabled on the project (EnableProjectClients);
    /// otherwise 403. Invitations are all-or-nothing: an invalid `create` row
    /// (including one with no email address) answers 422 with the rejected
    /// addresses and nobody is invited; new addresses that would exceed the
    /// account's user limit answer 429 and nobody is invited. Addresses already on
    /// the account take no seat and a repeated address counts once.
    ///
    /// The seat-limit 429 is a verdict, not throttling: it carries no Retry-After
    /// and re-asking cannot change the answer, so this operation declares
    /// `retryOn: \[503\]` and a 429 surfaces on the first attempt (status-mapped to
    /// `rate_limit`, since the wire status is the only signal). Every other
    /// operation but CreateEmbed retries on 429.
    ///
    /// `PUT /projects/{projectId}/people/client_users.json` — idempotent; retries up to 3 attempt(s) on 503.
    pub async fn update_project_client_access(
        &self,
        project_id: i64,
        body: &UpdateProjectClientAccessRequestContent,
    ) -> Result<UpdateProjectClientAccessResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::UPDATE_PROJECT_CLIENT_ACCESS, &[&project_id]);
        operation.json(body)?;
        self.client.send(operation).await
    }
}