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
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
// Generated by basecamp-sdk-generator from openapi.json and behavior-model.json. DO NOT EDIT.
//! People 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 `ListPeople`.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct ListPeopleParams {
/// 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>,
}
/// Optional query parameters for `ListProjectPeople`.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct ListProjectPeopleParams {
/// 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>,
}
/// `People` operations, sent through one [`AccountClient`].
#[derive(Debug, Clone, Copy)]
pub struct PeopleService<'a> {
client: &'a AccountClient,
}
impl<'a> PeopleService<'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
}
/// Disable out of office for a person.
/// Admins on Pro Pack accounts can manage others; otherwise self only.
///
/// `DELETE /people/{personId}/out_of_office.json` — idempotent; retries up to 2 attempt(s) on 429, 503.
pub async fn disable_out_of_office(&self, person_id: i64) -> Result<(), Error> {
let operation = self
.client
.operation(&routes::DISABLE_OUT_OF_OFFICE, &[&person_id]);
self.client.send_unit(operation).await
}
/// Disable clients on a project
///
/// 403 while the project still has any client users — revoke them first with
/// UpdateProjectClientAccess. Naturally idempotent: disabling a project with
/// clients already off re-answers `{"clients_enabled": false}`.
///
/// `DELETE /projects/{projectId}/client_enablement.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
pub async fn disable_project_clients(
&self,
project_id: i64,
) -> Result<DisableProjectClientsResponseContent, Error> {
let operation = self
.client
.operation(&routes::DISABLE_PROJECT_CLIENTS, &[&project_id]);
self.client.send(operation).await
}
/// Enable or replace out of office for a person.
/// Admins on Pro Pack accounts can manage others; otherwise self only.
///
/// `POST /people/{personId}/out_of_office.json` — not idempotent, sent exactly once.
pub async fn enable_out_of_office(
&self,
person_id: i64,
body: &EnableOutOfOfficeRequestContent,
) -> Result<EnableOutOfOfficeResponseContent, Error> {
let mut operation = self
.client
.operation(&routes::ENABLE_OUT_OF_OFFICE, &[&person_id]);
operation.json(body)?;
self.client.send(operation).await
}
/// Enable clients on a project so client users can be added to it
///
/// A deliberate step separate from adding clients: it turns on the project's
/// client-facing surface and applies the default client visibility (the
/// timeline and most docked tools become client-visible; the card table,
/// Campfire, and Doors stay private). UpdateProjectClientAccess never enables
/// clients implicitly — enable first, then add. 403 unless the project can have
/// clients (the account supports clients and the project is a standard
/// project). Naturally idempotent: enabling an enabled project re-answers
/// `{"clients_enabled": true}`.
///
/// `POST /projects/{projectId}/client_enablement.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
pub async fn enable_project_clients(
&self,
project_id: i64,
) -> Result<EnableProjectClientsResponseContent, Error> {
let operation = self
.client
.operation(&routes::ENABLE_PROJECT_CLIENTS, &[&project_id]);
self.client.send(operation).await
}
/// Get a person by ID
///
/// `GET /people/{personId}` — idempotent; retries up to 3 attempt(s) on 429, 503.
pub async fn get(&self, person_id: i64) -> Result<GetPersonResponseContent, Error> {
let operation = self.client.operation(&routes::GET_PERSON, &[&person_id]);
self.client.send(operation).await
}
/// List all people visible to the current user
///
/// **Pagination**: Uses Link header (RFC5988). Follow the `next` rel URL
/// to fetch additional pages. X-Total-Count header provides total count.
///
/// `GET /people.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
pub async fn list(
&self,
params: &ListPeopleParams,
) -> Result<Page<ListPeopleResponseContent>, Error> {
let mut operation = self.client.operation(&routes::LIST_PEOPLE, &[]);
operation.query_optional("page", params.page.as_ref());
self.client.send_page(operation).await
}
/// List people who can be assigned todos
///
/// `GET /reports/todos/assigned.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
pub async fn list_assignable(&self) -> Result<ListAssignablePeopleResponseContent, Error> {
let operation = self.client.operation(&routes::LIST_ASSIGNABLE_PEOPLE, &[]);
self.client.send(operation).await
}
/// List all active people on a project
///
/// **Pagination**: Uses Link header (RFC5988). Follow the `next` rel URL
/// to fetch additional pages. X-Total-Count header provides total count.
///
/// `GET /projects/{projectId}/people.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
pub async fn list_for_project(
&self,
project_id: i64,
params: &ListProjectPeopleParams,
) -> Result<Page<ListProjectPeopleResponseContent>, Error> {
let mut operation = self
.client
.operation(&routes::LIST_PROJECT_PEOPLE, &[&project_id]);
operation.query_optional("page", params.page.as_ref());
self.client.send_page(operation).await
}
/// List all account users who can be pinged
///
/// **Pagination**: Uses Link header (RFC5988). Follow the `next` rel URL
/// to fetch additional pages. X-Total-Count header provides total count.
///
/// `GET /circles/people.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
pub async fn list_pingable(&self) -> Result<Page<ListPingablePeopleResponseContent>, Error> {
let operation = self.client.operation(&routes::LIST_PINGABLE_PEOPLE, &[]);
self.client.send_page(operation).await
}
/// Get the current authenticated user's profile
///
/// `GET /my/profile.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
pub async fn me(&self) -> Result<GetMyProfileResponseContent, Error> {
let operation = self.client.operation(&routes::GET_MY_PROFILE, &[]);
self.client.send(operation).await
}
/// Get the current user's preferences
///
/// `GET /my/preferences.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
pub async fn my_preferences(&self) -> Result<GetMyPreferencesResponseContent, Error> {
let operation = self.client.operation(&routes::GET_MY_PREFERENCES, &[]);
self.client.send(operation).await
}
/// Get the out of office status for a person
///
/// `GET /people/{personId}/out_of_office.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
pub async fn out_of_office(
&self,
person_id: i64,
) -> Result<GetOutOfOfficeResponseContent, Error> {
let operation = self
.client
.operation(&routes::GET_OUT_OF_OFFICE, &[&person_id]);
self.client.send(operation).await
}
/// Update the current user's preferences.
/// Rejections arrive as a field-keyed 422
/// ({"errors": {"time_zone_name": \["is not included in the list"\]}}), not the
/// flat {error} body.
///
/// `PUT /my/preferences.json` — idempotent; retries up to 2 attempt(s) on 429, 503.
pub async fn update_my_preferences(
&self,
body: &UpdateMyPreferencesRequestContent,
) -> Result<UpdateMyPreferencesResponseContent, Error> {
let mut operation = self.client.operation(&routes::UPDATE_MY_PREFERENCES, &[]);
operation.json(body)?;
self.client.send(operation).await
}
/// Update the current authenticated user's profile (returns 204 No Content)
///
/// `PUT /my/profile.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
pub async fn update_my_profile(
&self,
body: &UpdateMyProfileRequestContent,
) -> Result<(), Error> {
let mut operation = self.client.operation(&routes::UPDATE_MY_PROFILE, &[]);
operation.json(body)?;
self.client.send_unit(operation).await
}
/// Update project access (grant/revoke/create people)
///
/// `PUT /projects/{projectId}/people/users.json` — idempotent; retries up to 3 attempt(s) on 429, 503.
pub async fn update_project_access(
&self,
project_id: i64,
body: &UpdateProjectAccessRequestContent,
) -> Result<UpdateProjectAccessResponseContent, Error> {
let mut operation = self
.client
.operation(&routes::UPDATE_PROJECT_ACCESS, &[&project_id]);
operation.json(body)?;
self.client.send(operation).await
}
/// Update project client access (grant/revoke/create client users)
///
/// The client-side counterpart to UpdateProjectAccess: `grant` adds existing
/// client users by id, `revoke` removes client users, and `create` invites
/// brand-new clients by email (`name` optional, defaulting to the address).
/// Only client users are eligible — a `grant` id belonging to a team member is
/// rejected (omitted from `granted`) rather than cross-graded, and `revoke` never removes a team
/// member. The response mirrors UpdateProjectAccess: `granted` and `revoked`
/// people, each with `client: true`.
///
/// Requires clients to be enabled on the project (EnableProjectClients);
/// otherwise 403. Invitations are all-or-nothing: an invalid `create` row
/// (including one with no email address) answers 422 with the rejected
/// addresses and nobody is invited; new addresses that would exceed the
/// account's user limit answer 429 and nobody is invited. Addresses already on
/// the account take no seat and a repeated address counts once.
///
/// The seat-limit 429 is a verdict, not throttling: it carries no Retry-After
/// and re-asking cannot change the answer, so this operation declares
/// `retryOn: \[503\]` and a 429 surfaces on the first attempt (status-mapped to
/// `rate_limit`, since the wire status is the only signal). Every other
/// operation but CreateEmbed retries on 429.
///
/// `PUT /projects/{projectId}/people/client_users.json` — idempotent; retries up to 3 attempt(s) on 503.
pub async fn update_project_client_access(
&self,
project_id: i64,
body: &UpdateProjectClientAccessRequestContent,
) -> Result<UpdateProjectClientAccessResponseContent, Error> {
let mut operation = self
.client
.operation(&routes::UPDATE_PROJECT_CLIENT_ACCESS, &[&project_id]);
operation.json(body)?;
self.client.send(operation).await
}
}