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.

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

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

impl<'a> DocumentsService<'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 document in a vault
    ///
    /// `POST /vaults/{vaultId}/documents.json` — not idempotent, sent exactly once.
    pub async fn create(
        &self,
        vault_id: i64,
        body: &CreateDocumentRequestContent,
    ) -> Result<CreateDocumentResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::CREATE_DOCUMENT, &[&vault_id]);
        operation.json(body)?;
        self.client.send(operation).await
    }

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

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

    /// Replace a document with a new complete representation.
    /// The request body is the document's full writable state: any writable field
    /// omitted from the request is cleared server-side. Omitting content clears it;
    /// omitting title clears it too, and the document then reads back as
    /// "Untitled" (Document#title falls back when blank).
    /// Neither field is required. BC3 builds a brand-new Document from the
    /// permitted params and swaps the recordable wholesale, and neither attribute
    /// carries a presence validation — so an omission is a 200 that clears, not a
    /// 422. What BC3 does require is the wrapping document object, which Rails
    /// synthesizes from a flat body, so a request naming neither field is a 400.
    /// Publishing a draft (status: "active") is not modeled: the SDK sends only
    /// title and content, and BC3 rejects a status-only update for the same
    /// reason it 400s an empty body.
    /// Subscribers are the one exception to omission-clears. A drafted document
    /// keeps its current subscribers when the request addresses neither
    /// subscriptions nor notify, so a full-representation PUT that mentions
    /// neither is safe on a draft.
    /// To set some fields while preserving the rest, use the SDK's merge-safe
    /// update or edit methods, which GET the current document 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 /documents/{documentId}` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn replace(
        &self,
        document_id: i64,
        body: &ReplaceDocumentRequestContent,
    ) -> Result<ReplaceDocumentResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::REPLACE_DOCUMENT, &[&document_id]);
        operation.json(body)?;
        self.client.send(operation).await
    }
}