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.

//! EventFeed 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::*;

/// Optional query parameters for `PollEvents`.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct PollEventsParams {
    /// Entry point: a decimal event id (start after it; `0` replays served
    /// history back to the epoch), or the literal `now` (skip history). Mutually
    /// exclusive with `position` in practice; omit both to enter at the present.
    pub since: Option<String>,
    /// Resume token from a previous page's `position`. Opaque and signed; never
    /// constructed or parsed client-side.
    pub position: Option<String>,
    /// Comma-separated event types from the catalog (e.g. `message.created,comment.created`).
    pub types: Option<String>,
    /// Comma-separated bucket (project) ids, at most 100.
    pub buckets: Option<String>,
    /// Comma-separated creator person ids, at most 100.
    pub creators: Option<String>,
    /// Comma-separated effective-performer ids (the agent on a delegated action,
    /// else the creator), at most 100. The literal `self` means the request's own
    /// effective actor and is resolved server-side before filtering.
    pub performers: Option<String>,
    /// Comma-separated effective-performer ids to exclude, at most 100; `self`
    /// as on `performers`. `exclude_performers=self` is the loop guard for an
    /// agent that acts on what it hears.
    pub exclude_performers: Option<String>,
    /// Comma-separated actor kinds: `agent`, `person`, or both. A filter, not a
    /// default — agent activity is real account activity.
    pub actor_types: Option<String>,
}

/// Optional query parameters for `PollInbox`.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct PollInboxParams {
    /// Entry point: `0` (earliest retained), `now` (present), or a decimal item
    /// id to start after.
    pub since: Option<String>,
    /// Resume token from a previous inbox page's `position`.
    pub position: Option<String>,
    /// Comma-separated addressing reasons: `mentioned`, `assigned`, `subscribed`,
    /// `watched`, `pinged`, `boosted`.
    pub reasons: Option<String>,
    /// Comma-separated event types, as a narrowing filter.
    pub types: Option<String>,
    /// Comma-separated bucket ids, as a narrowing filter (at most 100).
    pub buckets: Option<String>,
}

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

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

    /// Mint a short-lived stream ticket and the exact WebSocket URL to open a live event stream with.
    ///
    /// The ticket is signed and lives about two minutes; the response's `url` is
    /// the one to connect to. Connect to `url` verbatim — never assemble the WebSocket URL (scheme, host,
    /// path, account prefix) client-side; the topology is the server's to change.
    /// Mint a fresh ticket for every connection attempt: tickets expire and are not
    /// refreshed by an open socket. The mint is a stateless signed capability with
    /// no server-side consumption, so a replayed POST is harmless and the operation
    /// is marked idempotent (safe to retry) — deliberately not a claim that two
    /// mints return the same ticket. The ticket is a replayable bearer credential
    /// within its window; `ticket` and `url` are marked sensitive (see StreamTicket).
    ///
    /// Serves agent principals as well as people: an agent's client-credentials
    /// token can mint tickets for its own live stream. A ticket minted on a
    /// delegated request carries its agent, so `self` on the socket it opens
    /// resolves to that agent.
    ///
    /// `POST /events/stream_ticket.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn create_stream_ticket(&self) -> Result<CreateStreamTicketResponseContent, Error> {
        let operation = self.client.operation(&routes::CREATE_STREAM_TICKET, &[]);
        self.client.send(operation).await
    }

    /// Poll the account event feed for events after a position (oldest first, strict event-id order, up to 100 per page).
    ///
    /// **Entry.** With neither `since` nor `position` the feed begins at the present
    /// (equivalent to `since=now`). `since=\<event id\>` starts after that id and
    /// `since=0` replays all served history back to the feed's epoch; `since` is a
    /// signed 64-bit integer written in decimal, or the literal `now`. `position`
    /// resumes from a token a previous page issued — signed, opaque, bound to the
    /// account and the filter set.
    ///
    /// **Pagination**: cursor style — the body envelope, not the Link header.
    /// `position` is the durable cursor (persist it only after processing the
    /// page's events); `next` is an absolute continuation URL present only while
    /// this walk has more to serve. One call answers one page; no generator emits
    /// a walk for the cursor style — see the section note.
    ///
    /// **Errors.** 400 (FeedRequestError) for a malformed position (resume with
    /// `since=`) or a malformed filter (fix the filters; a position reset will not
    /// help), told apart by its optional `reason` and undifferentiated when `reason`
    /// is absent. 409 (FeedFilterMismatchError) when the position was minted for a
    /// different filter set. 410 (FeedPositionGoneError) when the position predates
    /// the feed's epoch; its `resume` re-enters at the epoch.
    ///
    /// `GET /events.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn poll_events(
        &self,
        params: &PollEventsParams,
    ) -> Result<PollEventsResponseContent, Error> {
        let mut operation = self.client.operation(&routes::POLL_EVENTS, &[]);
        operation.query_optional("since", params.since.as_ref());
        operation.query_optional("position", params.position.as_ref());
        operation.query_optional("types", params.types.as_ref());
        operation.query_optional("buckets", params.buckets.as_ref());
        operation.query_optional("creators", params.creators.as_ref());
        operation.query_optional("performers", params.performers.as_ref());
        operation.query_optional("exclude_performers", params.exclude_performers.as_ref());
        operation.query_optional("actor_types", params.actor_types.as_ref());
        self.client.send(operation).await
    }

    /// Poll the authenticated agent's inbox for the items that addressed it (oldest first, strict item-id order); people receive 403.
    ///
    /// The inbox is the low-noise "someone addressed you" lane as its own resource
    /// rather than a filter over the account feed. **Agents only for now**: any
    /// other principal receives 403.
    ///
    /// An item is a first-class delivery with its own identity: one event can
    /// address the same principal for several reasons, and each reason is its own
    /// item. Deduplicate by `addressing_id`, never by event id. Items are never
    /// self-addressed, are kept for 30 days, and are dropped at read time when the
    /// event is no longer readable.
    ///
    /// **Entry**: `since=0` replays the earliest retained items, `since=now` enters
    /// at the present, `position` resumes. Inbox positions are bound to the
    /// account, the principal, and the filter set, and are never interchangeable
    /// with feed positions.
    ///
    /// **Pagination**: cursor style, exactly as PollEvents — the body envelope
    /// (`items`, `position`, `next`), not the Link header and not the generic
    /// paginator. Up to 100 items per page.
    ///
    /// **Errors** follow PollEvents (FeedRequestError 400, FeedFilterMismatchError
    /// 409), except that 403 carries no body — the agent guard's bare
    /// `head :forbidden` (BareForbiddenError) — and that the 410 is the inbox's own
    /// InboxPositionGoneError: the position fell behind the retention window, there
    /// is no epoch, and `resume` re-enters at `since=0`, the earliest retained item
    /// — not the feed's recovery, and not interchangeable with it.
    ///
    /// `GET /inbox.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
    pub async fn poll_inbox(
        &self,
        params: &PollInboxParams,
    ) -> Result<PollInboxResponseContent, Error> {
        let mut operation = self.client.operation(&routes::POLL_INBOX, &[]);
        operation.query_optional("since", params.since.as_ref());
        operation.query_optional("position", params.position.as_ref());
        operation.query_optional("reasons", params.reasons.as_ref());
        operation.query_optional("types", params.types.as_ref());
        operation.query_optional("buckets", params.buckets.as_ref());
        self.client.send(operation).await
    }
}