1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
// 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
}
}