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
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
//! Profiles API for Eero: per-network device-grouping "profiles" (e.g. "Kids", "Guests").
//!
//! Ported from `eero-api`'s `src/eero/api/profiles.py` at v8.0.4. Covers every `ProfilesAPI`
//! method. As in Python, every method here returns the raw `{"meta": …, "data": …}` envelope
//! unmodified — `ProfilesApi` never extracts, filters or reshapes anything out of a response.
//!
//! A profile's body has exactly four fields: `devices`, `name`, `paused`, `url`. Content
//! filtering, block lists, and blocked applications are **not** profile fields at all — writing
//! them here was a silent no-op (live-verified; they never persisted). That functionality is
//! served by [`crate::endpoints::dns_policies::DnsPoliciesApi`] instead; the four now-removed
//! methods that used to write those non-fields (`update_profile_content_filter`,
//! `update_profile_block_list`, `get_blocked_applications`, `set_blocked_applications`) have no
//! replacement *on this module* — see `dns_policies.rs`.
//!
//! `get_profile` and `get_profile_devices` are the *same* wire call
//! (`GET networks/{network_id}/profiles/{profile_id}`) returning the same full profile object;
//! `get_profile_devices` is a pure delegator, matching `profiles.py:183-206` exactly. Likewise,
//! `pause_profile`, `set_profile_devices` and `rename_profile` all `PUT` the same
//! `networks/{network_id}/profiles/{profile_id}` resource (via the shared private
//! `profile_request` helper, mirroring Python's `_update_profile`,
//! `profiles.py:122-155`) with a different JSON key each.
use std::sync::Arc;
use serde_json::{Value, json};
use url::Url;
use crate::envelope::Envelope;
use crate::error::Error;
use crate::links;
use crate::routes::{self, Nested};
use crate::transport::{RequestBody, Transport};
/// The profiles API for a single Eero account, built on a shared [`Transport`].
#[derive(Debug)]
pub struct ProfilesApi {
transport: Arc<Transport>,
}
impl ProfilesApi {
/// Wraps `transport` as a `ProfilesApi`.
#[must_use]
pub fn new(transport: Arc<Transport>) -> Self {
Self { transport }
}
/// Resolves a single profile's request URL: prefers [`links::self_url`] on the profile's own
/// cached `parent` envelope when supplied and resolvable, else falls back to `route`'s
/// `networks/{network_id}/profiles/{profile_id}` template.
///
/// Mirrors `ProfilesAPI._profile_url`/the inline `self_url(resolved_parent) if
/// resolved_parent is not None else None) or (...)` expression `get_profile` and
/// `_update_profile` both use (`profiles.py:47,116-118,150-153`) — see `routes::profiles`'s
/// module docs for why this cannot be expressed as a plain [`Nested::resolve`] call (its
/// parent preference is a *named-link* lookup, not [`links::self_url`]).
fn profile_url(
&self,
route: &Nested,
network_id: &str,
profile_id: &str,
parent: Option<&Value>,
) -> Result<Url, Error> {
let host = self.transport.api_host();
if let Some(parent) = parent
&& let Some(url) = links::self_url(host, parent)?
{
return Ok(url);
}
route.resolve(host, network_id, profile_id, None)
}
/// Issues a request against a single profile's resource, resolved via
/// [`ProfilesApi::profile_url`].
async fn profile_request(
&self,
route: &Nested,
network_id: &str,
profile_id: &str,
parent: Option<&Value>,
body: RequestBody,
) -> Result<Envelope, Error> {
let url = self.profile_url(route, network_id, profile_id, parent)?;
self.transport
.request(route.method.clone(), url, &[], body)
.await
}
/// Like [`ProfilesApi::profile_request`], but logs a fixed uncharacterised-write warning
/// after the URL is resolved and immediately before the request — mirroring
/// `_update_profile`'s exact statement order (`profiles.py:122-155`: resolve the URL, warn,
/// then `PUT`), rather than warning before URL resolution/validation can fail.
async fn profile_write(
&self,
route: &Nested,
network_id: &str,
profile_id: &str,
parent: Option<&Value>,
operation: &str,
body: RequestBody,
) -> Result<Envelope, Error> {
let url = self.profile_url(route, network_id, profile_id, parent)?;
links::warn_uncharacterised_write(operation);
self.transport
.request(route.method.clone(), url, &[], body)
.await
}
/// Lists every profile on a network — returns the raw Eero API response.
///
/// Ported from `eero-api src/eero/api/profiles.py:53-80` (`ProfilesAPI.get_profiles`): sends
/// `GET` `routes::profiles::GET_PROFILES` (`networks/{network_id}/profiles`), preferring the
/// parent network envelope's own `profiles` link when `parent` is supplied and resolvable.
///
/// # Errors
///
/// Returns [`Error::Authentication`] if no valid session is configured, [`Error::Validation`]
/// if `network_id`/`parent`'s link cannot be resolved to a URL, or whatever status-mapped
/// [`Error`] the request produces otherwise.
pub async fn get_profiles(
&self,
network_id: &str,
parent: Option<&Value>,
) -> Result<Envelope, Error> {
self.transport
.resource(
&routes::profiles::GET_PROFILES,
network_id,
parent,
&[],
RequestBody::None,
)
.await
}
/// Gets a single profile's full object — returns the raw Eero API response.
///
/// Ported from `eero-api src/eero/api/profiles.py:86-118` (`ProfilesAPI.get_profile`): sends
/// `GET` `routes::profiles::GET_PROFILE` (`networks/{network_id}/profiles/{profile_id}`),
/// preferring `parent`'s own `url` (via [`links::self_url`]) when supplied and resolvable —
/// when it is, `network_id`/`profile_id` are ignored for URL resolution entirely, matching
/// Python exactly.
///
/// # Errors
///
/// Returns [`Error::Authentication`] if no valid session is configured, [`Error::Validation`]
/// if neither `parent` nor `network_id`/`profile_id` resolve to a URL, or whatever
/// status-mapped [`Error`] the request produces otherwise.
pub async fn get_profile(
&self,
network_id: &str,
profile_id: &str,
parent: Option<&Value>,
) -> Result<Envelope, Error> {
self.profile_request(
&routes::profiles::GET_PROFILE,
network_id,
profile_id,
parent,
RequestBody::None,
)
.await
}
/// Gets a profile's data "including devices" — returns the raw Eero API response.
///
/// Ported from `eero-api src/eero/api/profiles.py:183-206` (`ProfilesAPI.get_profile_devices`),
/// a pure delegator to [`ProfilesApi::get_profile`] — the exact same request, the exact same
/// untransformed response. Python's docstring notes "The devices are in the `devices` field
/// of the response data" (`profiles.py:107`), but neither Python nor this port extracts that
/// field.
///
/// # Errors
///
/// See [`ProfilesApi::get_profile`].
pub async fn get_profile_devices(
&self,
network_id: &str,
profile_id: &str,
parent: Option<&Value>,
) -> Result<Envelope, Error> {
self.get_profile(network_id, profile_id, parent).await
}
/// Pauses or unpauses internet access for a profile — returns the raw Eero API response.
///
/// Ported from `eero-api src/eero/api/profiles.py:157-181` (`ProfilesAPI.pause_profile`, via
/// `_update_profile`): sends `PUT` `routes::profiles::PAUSE_PROFILE` with body `{"paused":
/// paused}`. Logs one `warn_uncharacterised_write("update profile")` immediately before the
/// request, matching `_update_profile`'s own single warning (`profiles.py:154`).
///
/// # Errors
///
/// See [`ProfilesApi::get_profile`].
pub async fn pause_profile(
&self,
network_id: &str,
profile_id: &str,
paused: bool,
parent: Option<&Value>,
) -> Result<Envelope, Error> {
self.profile_write(
&routes::profiles::PAUSE_PROFILE,
network_id,
profile_id,
parent,
"update profile",
RequestBody::Json(json!({ "paused": paused })),
)
.await
}
/// Sets the devices assigned to a profile — returns the raw Eero API response.
///
/// **Replaces the profile's entire device assignment list** (`profiles.py:138`).
///
/// Ported from `eero-api src/eero/api/profiles.py:208-245`
/// (`ProfilesAPI.set_profile_devices`): sends `PUT` `routes::profiles::SET_PROFILE_DEVICES`
/// with body `{"devices": [{"url": ...}, ...]}` — each URL wrapped in its own single-key
/// object, matching Python's `devices_payload = [{"url": url} for url in device_urls]`
/// exactly.
///
/// **Double-warn, reproduced deliberately (see the g4 brief's open question 3).** This method
/// calls `warn_uncharacterised_write("set devices for profile")` itself
/// (`profiles.py:241`) *and then* delegates to the same `_update_profile` helper
/// [`ProfilesApi::pause_profile`]/[`ProfilesApi::rename_profile`] use, which logs a second,
/// differently-worded `warn_uncharacterised_write("update profile")`
/// (`profiles.py:154`) — two `tracing::warn!` lines per call, unlike its siblings, which log
/// exactly one. This looks like a Python oversight, not a deliberate design, but is
/// reproduced faithfully rather than silently "fixed" to one warning: this crate's own
/// discipline (see `CLAUDE.md`'s lessons-learned entries) is to preserve observed server/SDK
/// behaviour and flag it, not quietly diverge.
///
/// # Errors
///
/// See [`ProfilesApi::get_profile`].
pub async fn set_profile_devices(
&self,
network_id: &str,
profile_id: &str,
device_urls: &[&str],
parent: Option<&Value>,
) -> Result<Envelope, Error> {
let devices: Vec<_> = device_urls
.iter()
.map(|url| json!({ "url": url }))
.collect();
let url = self.profile_url(
&routes::profiles::SET_PROFILE_DEVICES,
network_id,
profile_id,
parent,
)?;
links::warn_uncharacterised_write("set devices for profile");
links::warn_uncharacterised_write("update profile");
self.transport
.request(
routes::profiles::SET_PROFILE_DEVICES.method.clone(),
url,
&[],
RequestBody::Json(json!({ "devices": devices })),
)
.await
}
/// Creates a new profile on a network — returns the raw Eero API response.
///
/// `name` is always sent. `devices` (device URL strings, wrapped as `[{"url": ...}, ...]`)
/// and `paused` are each included in the request **only when not `None`** — an explicit
/// `Some(false)`/`Some(&[])` is still sent, matching Python's omit-when-`None` (not
/// omit-when-falsy) rule exactly (`profiles.py:278-283`).
///
/// Ported from `eero-api src/eero/api/profiles.py:247-300` (`ProfilesAPI.create_profile`):
/// sends `POST` `routes::profiles::CREATE_PROFILE` (`networks/{network_id}/profiles`,
/// preferring the parent network envelope's own `profiles` link when supplied). Logs one
/// `warn_uncharacterised_write("create profile for network")` immediately before the request.
///
/// # Errors
///
/// See [`ProfilesApi::get_profiles`].
pub async fn create_profile(
&self,
network_id: &str,
name: &str,
devices: Option<&[&str]>,
paused: Option<bool>,
parent: Option<&Value>,
) -> Result<Envelope, Error> {
let url = routes::profiles::CREATE_PROFILE.resolve(
self.transport.api_host(),
network_id,
parent,
)?;
let mut payload = serde_json::Map::new();
payload.insert("name".to_owned(), Value::String(name.to_owned()));
if let Some(devices) = devices {
let devices: Vec<_> = devices.iter().map(|url| json!({ "url": url })).collect();
payload.insert("devices".to_owned(), Value::Array(devices));
}
if let Some(paused) = paused {
payload.insert("paused".to_owned(), Value::Bool(paused));
}
links::warn_uncharacterised_write("create profile for network");
self.transport
.request(
routes::profiles::CREATE_PROFILE.method.clone(),
url,
&[],
RequestBody::Json(Value::Object(payload)),
)
.await
}
/// Renames an existing profile — returns the raw Eero API response.
///
/// Ported from `eero-api src/eero/api/profiles.py:304-330` (`ProfilesAPI.rename_profile`, via
/// `_update_profile`): sends `PUT` `routes::profiles::RENAME_PROFILE` with body `{"name":
/// name}`. Logs one `warn_uncharacterised_write("update profile")` immediately before the
/// request.
///
/// # Errors
///
/// See [`ProfilesApi::get_profile`].
pub async fn rename_profile(
&self,
network_id: &str,
profile_id: &str,
name: &str,
parent: Option<&Value>,
) -> Result<Envelope, Error> {
self.profile_write(
&routes::profiles::RENAME_PROFILE,
network_id,
profile_id,
parent,
"update profile",
RequestBody::Json(json!({ "name": name })),
)
.await
}
/// Deletes a profile from a network — returns the raw Eero API response.
///
/// Devices previously assigned to `profile_id` become unassigned server-side
/// (`profiles.py:394` at v6.2.0's equivalent wording); nothing here initiates that.
///
/// Ported from `eero-api src/eero/api/profiles.py:330-355` (`ProfilesAPI.delete_profile`):
/// sends `DELETE` `routes::profiles::DELETE_PROFILE`
/// (`networks/{network_id}/profiles/{profile_id}`), with no request body. Unlike every other
/// method in this module, Python's `delete_profile` takes **no `parent` kwarg at all** — this
/// port matches that signature exactly, always resolving via the network/profile-id template.
/// Logs one `warn_uncharacterised_write("delete profile")` immediately before the request.
///
/// # Errors
///
/// See [`ProfilesApi::get_profile`].
pub async fn delete_profile(
&self,
network_id: &str,
profile_id: &str,
) -> Result<Envelope, Error> {
self.profile_write(
&routes::profiles::DELETE_PROFILE,
network_id,
profile_id,
None,
"delete profile",
RequestBody::None,
)
.await
}
}