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.

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

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

impl<'a> SchedulesService<'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 schedule entry
    ///
    /// `POST /schedules/{scheduleId}/entries.json` — not idempotent, sent exactly once.
    pub async fn create_entry(
        &self,
        schedule_id: i64,
        body: &CreateScheduleEntryRequestContent,
    ) -> Result<CreateScheduleEntryResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::CREATE_SCHEDULE_ENTRY, &[&schedule_id]);
        operation.json(body)?;
        self.client.send(operation).await
    }

    /// Get a schedule
    ///
    /// `GET /schedules/{scheduleId}` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn get(&self, schedule_id: i64) -> Result<GetScheduleResponseContent, Error> {
        let operation = self
            .client
            .operation(&routes::GET_SCHEDULE, &[&schedule_id]);
        self.client.send(operation).await
    }

    /// Get a single schedule entry by id.
    /// Note: Recurring entries will redirect (302) to their recordable URL.
    /// Use GetScheduleEntryOccurrence for recurring entries instead.
    ///
    /// `GET /schedule_entries/{entryId}` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn get_entry(&self, entry_id: i64) -> Result<GetScheduleEntryResponseContent, Error> {
        let operation = self
            .client
            .operation(&routes::GET_SCHEDULE_ENTRY, &[&entry_id]);
        self.client.send(operation).await
    }

    /// Get a specific occurrence of a recurring schedule entry
    ///
    /// `GET /schedule_entries/{entryId}/occurrences/{date}` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn get_entry_occurrence(
        &self,
        entry_id: i64,
        date: &str,
    ) -> Result<GetScheduleEntryOccurrenceResponseContent, Error> {
        let operation = self
            .client
            .operation(&routes::GET_SCHEDULE_ENTRY_OCCURRENCE, &[&entry_id, &date]);
        self.client.send(operation).await
    }

    /// List entries on a schedule
    ///
    /// **Pagination**: Uses Link header (RFC5988). Follow the `next` rel URL
    /// to fetch additional pages. X-Total-Count header provides total count.
    ///
    /// `GET /schedules/{scheduleId}/entries.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn list_entries(
        &self,
        schedule_id: i64,
        params: &ListScheduleEntriesParams,
    ) -> Result<Page<ListScheduleEntriesResponseContent>, Error> {
        let mut operation = self
            .client
            .operation(&routes::LIST_SCHEDULE_ENTRIES, &[&schedule_id]);
        operation.query_optional("status", params.status.as_ref());
        operation.query_optional("page", params.page.as_ref());
        self.client.send_page(operation).await
    }

    /// Replace a schedule entry with a new complete representation.
    /// The request body is the entry's full writable state: a writable field
    /// omitted from the request is cleared server-side, because BC3 builds a
    /// brand-new Schedule::Entry from the permitted params and swaps the recordable
    /// wholesale.
    /// Three writable fields are carved out of that swap and preserved when the
    /// request does not address them — participant_ids, url and highlighted, as
    /// declared by preservedOnOmission. Each is a field a caller could not safely
    /// resend from a read-back, which is why the guard is server-side: the response
    /// carries participants (objects, not ids) and join_url (the entry's own url
    /// key is its Basecamp API URL, a different value under a colliding name).
    /// Addressing one applies it normally, so participant_ids: \[\] clears the
    /// participants, url: "" clears the join link and highlighted: false removes
    /// the highlight.
    /// starts_at and ends_at are required: Schedule::Entry validates their presence
    /// and Recording validates the associated recordable on update, so omitting
    /// either is a 422 rather than a clear. summary carries no validation — omit it
    /// and the entry reads back as "Untitled" (Schedule::Entry#summary falls back
    /// when blank).
    /// Recurring entries are unreachable here. ensure_non_recurring_event redirects
    /// both show and update to the entry's occurrence, so this operation serves
    /// non-recurring entries only; read a recurring entry through
    /// GetScheduleEntryOccurrence.
    /// time_zone_name, recurs_until and recurrence_schedule are not modeled: BC3
    /// forces all three to nil for a non-recurring entry, which is the only kind
    /// this route serves.
    /// Subscribers follow the same carve-out logic one level up. A drafted entry
    /// keeps its current subscribers when the request addresses neither
    /// subscriptions, notify, nor the participant parameters.
    /// To set some fields while preserving the rest, use the SDK's merge-safe
    /// update or edit methods, which GET the current entry 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 /schedule_entries/{entryId}` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn replace_entry(
        &self,
        entry_id: i64,
        body: &ReplaceScheduleEntryRequestContent,
    ) -> Result<ReplaceScheduleEntryResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::REPLACE_SCHEDULE_ENTRY, &[&entry_id]);
        operation.json(body)?;
        self.client.send(operation).await
    }

    /// Update schedule settings
    ///
    /// `PUT /schedules/{scheduleId}` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn update_settings(
        &self,
        schedule_id: i64,
        body: &UpdateScheduleSettingsRequestContent,
    ) -> Result<UpdateScheduleSettingsResponseContent, Error> {
        let mut operation = self
            .client
            .operation(&routes::UPDATE_SCHEDULE_SETTINGS, &[&schedule_id]);
        operation.json(body)?;
        self.client.send(operation).await
    }
}