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.

//! Recordings 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 `ListRecordings`.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct ListRecordingsParams {
    /// `bucket`.
    pub bucket: Option<String>,
    /// active|archived|trashed
    pub status: Option<String>,
    /// created_at|updated_at
    pub sort: Option<String>,
    /// asc|desc
    pub direction: 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>,
}

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

impl<'a> RecordingsService<'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 recording; bc3 answers 403 for types it never lets be archived, timesheet entries among them
    ///
    /// `PUT /recordings/{recordingId}/status/archived.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn archive(&self, recording_id: i64) -> Result<(), Error> {
        let operation = self
            .client
            .operation(&routes::ARCHIVE_RECORDING, &[&recording_id]);
        self.client.send_unit(operation).await
    }

    /// Start copying a recording into another project; poll GetFiling for the result.
    ///
    /// Works like MoveRecording, and takes the same destinations, except the
    /// original stays where it is. Name the destination with
    /// `filing_destination_id`, a container of the kind the recording sits in now,
    /// chosen as for MoveRecording. A copied card lands in Triage, or in Done if it
    /// is completed, as a moved one does. A to-do or to-do list group copies into a
    /// to-do list in its own project or another one. A dock tool is copied by
    /// `destination_project_id`, or by naming the destination project's dock as
    /// `filing_destination_id`. Poll GetFiling with the returned filing's id until
    /// `status` leaves `pending` and `processing`; a completed filing's
    /// `destination_recording.id` is the copy.
    ///
    /// The same recordings copy on their own as move on their own, except the
    /// Email Forwards tool, which can't be copied. Everything else copies only
    /// along with its parent and answers 403, as for MoveRecording: comments,
    /// attachments, card steps, check-in answers, hill chart updates, external
    /// links, the card table columns every card table has, and anything outside a
    /// tool, such as client correspondence and approvals.
    ///
    /// Not safe to retry blindly: each request makes another copy. Check the first
    /// filing's status before trying again.
    ///
    /// 400 when neither destination is given. 403 when the recording can't be
    /// copied on its own. 404 when the destination is not one the caller can copy
    /// it into. 422 when the copy cannot start, such as when the recording is being
    /// moved or the destination cannot take it.
    ///
    /// `POST /recordings/{recordingId}/copies.json` — not idempotent, sent exactly once.
    pub async fn copy(
        &self,
        recording_id: i64,
        body: &CopyRecordingRequestContent,
    ) -> Result<CopyRecordingResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::COPY_RECORDING, &[&recording_id]);
        operation.json(body)?;
        self.client.send(operation).await
    }

    /// Get the state of a move or copy started by MoveRecording or CopyRecording.
    ///
    /// `status` is `pending` or `processing` while the work runs, `completed` when
    /// it is done, and `failed` if it could not be done. Poll until it leaves
    /// `pending` and `processing`. A completed filing carries the recording it made
    /// under `destination_recording`; for a move, that is the moved recording's new
    /// id. 404 for a filing someone else started, and for a completed one whose
    /// recording has since been permanently deleted.
    ///
    /// `GET /filings/{filingId}` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn get_filing(&self, filing_id: i64) -> Result<GetFilingResponseContent, Error> {
        let operation = self.client.operation(&routes::GET_FILING, &[&filing_id]);
        self.client.send(operation).await
    }

    /// List recordings of a given type across projects
    ///
    /// **Pagination**: Uses Link header (RFC5988). Follow the `next` rel URL
    /// to fetch additional pages. X-Total-Count header provides total count.
    ///
    /// `GET /projects/recordings.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn list(
        &self,
        r#type: &str,
        params: &ListRecordingsParams,
    ) -> Result<Page<ListRecordingsResponseContent>, Error> {
        let mut operation = self.client.operation(&routes::LIST_RECORDINGS, &[]);
        operation.query("type", r#type);
        operation.query_optional("bucket", params.bucket.as_ref());
        operation.query_optional("status", params.status.as_ref());
        operation.query_optional("sort", params.sort.as_ref());
        operation.query_optional("direction", params.direction.as_ref());
        operation.query_optional("page", params.page.as_ref());
        self.client.send_page(operation).await
    }

    /// Start moving a recording into another project; poll GetFiling for the result.
    ///
    /// The move runs in the background and this answers 201 with a filing. Poll
    /// GetFiling with its id until `status` leaves `pending` and `processing`. Once
    /// the move completes, the recording lives in the destination project under a
    /// new id, the completed filing's `destination_recording.id`; its old id no
    /// longer reaches it. A move always gives the recording a new id, even within
    /// its project. To move a to-do into another list in its own project and keep
    /// its id, use RepositionTodo with `parent_id` instead.
    ///
    /// Name the destination with `filing_destination_id`: the container the
    /// recording moves into, of the same kind it sits in now. Find tools in the
    /// destination project's `dock` (GetProject). A message moves into a
    /// `message_board`. A card moves into a card table (`kanban_board`) and lands
    /// in Triage, or in Done if it is completed; a card table column moves into a
    /// card table too. A document, upload, cloud file, Google document or folder
    /// moves into a `vault` (Docs & Files). A schedule entry moves into a
    /// `schedule`, a check-in question into a `questionnaire` (Automatic
    /// Check-ins), an email forward into an `inbox` (Email Forwards), and a to-do
    /// list into a `todoset` (To-dos). A to-do, or a to-do list group, moves into a
    /// to-do list, found with ListTodolists. The list may be in the to-do's own
    /// project or another one, but it can't be a group, an archived or trashed
    /// list, or the list the to-do is already in. A group moved into a list
    /// becomes a group in that list.
    ///
    /// A dock tool itself (a message board, card table, Docs & Files, schedule, and
    /// so on) has no container to name. Move it by `destination_project_id`, or
    /// name the destination project's dock as `filing_destination_id`.
    ///
    /// Only the recordings above, and the dock tools, move on their own. Everything
    /// else moves only along with its parent and answers 403: comments,
    /// attachments, card steps, check-in answers, hill chart updates, external
    /// links, the card table columns every card table has (Triage, Not now, Done
    /// and On hold), and anything outside a tool, such as client correspondence and
    /// approvals. To move one, move the recording or tool it belongs to.
    ///
    /// 400 when neither destination is given. 403 when the recording can't be
    /// moved on its own, or the caller may not move it. 404 when the destination
    /// is not one the caller can move it into. 422 when the move cannot start,
    /// such as when the recording is already being moved or the destination
    /// cannot take it. A repeated move is harmless: while the first is pending it
    /// is 422, and once it is done, 404, because the recording has moved.
    ///
    /// `POST /recordings/{recordingId}/moves.json` — not idempotent, sent exactly once.
    pub async fn move_recording(
        &self,
        recording_id: i64,
        body: &MoveRecordingRequestContent,
    ) -> Result<MoveRecordingResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::MOVE_RECORDING, &[&recording_id]);
        operation.json(body)?;
        self.client.send(operation).await
    }

    /// Move a document, upload or vault into another vault in its project, or reorder it in its own vault.
    ///
    /// Passing the vault it is already in changes only its position. The
    /// recording moves in place: its id, comments, bookmarks and history stay with
    /// it, and a vault takes everything inside it along. A destination in another
    /// project is 404; moves to another project are not this operation. 404, 403 and
    /// some 422s carry no body.
    ///
    /// 403 when the caller may not move the recording (an account can restrict moves
    /// to admins and creators). 422 when position is not a positive whole number, the
    /// destination is not a vault or is not active, the recording is not active, or a
    /// vault would move into one of its own vaults; only the position and vault-cycle
    /// refusals carry an `error` message.
    ///
    /// `POST /recordings/{recordingId}/filing.json` — not idempotent, sent exactly once.
    pub async fn move_to_vault(
        &self,
        recording_id: i64,
        body: &MoveRecordingToVaultRequestContent,
    ) -> Result<(), Error> {
        let mut operation = self
            .client
            .operation(&routes::MOVE_RECORDING_TO_VAULT, &[&recording_id]);
        operation.json(body)?;
        self.client.send_unit(operation).await
    }

    /// Put a recording's card in the spotlight area on its project or template home page.
    /// Idempotent: spotlighting an already-spotlighted recording still returns 201.
    ///
    /// `POST /recordings/{recordingId}/spotlight.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn spotlight(
        &self,
        recording_id: i64,
    ) -> Result<SpotlightRecordingResponseContent, Error> {
        let operation = self
            .client
            .operation(&routes::SPOTLIGHT_RECORDING, &[&recording_id]);
        self.client.send(operation).await
    }

    /// Trash a recording; bc3 answers 403 for types it never lets be trashed, timesheet entries among them (DestroyTimesheetEntry removes those, permanently)
    ///
    /// `PUT /recordings/{recordingId}/status/trashed.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn trash(&self, recording_id: i64) -> Result<(), Error> {
        let operation = self
            .client
            .operation(&routes::TRASH_RECORDING, &[&recording_id]);
        self.client.send_unit(operation).await
    }

    /// Unarchive a recording (restore to active status)
    ///
    /// `PUT /recordings/{recordingId}/status/active.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn unarchive(&self, recording_id: i64) -> Result<(), Error> {
        let operation = self
            .client
            .operation(&routes::UNARCHIVE_RECORDING, &[&recording_id]);
        self.client.send_unit(operation).await
    }

    /// Remove a recording from the spotlight area.
    /// Idempotent: removing an absent spotlight also returns 204.
    ///
    /// `DELETE /recordings/{recordingId}/spotlight.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn unspotlight(&self, recording_id: i64) -> Result<(), Error> {
        let operation = self
            .client
            .operation(&routes::UNSPOTLIGHT_RECORDING, &[&recording_id]);
        self.client.send_unit(operation).await
    }
}