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
//! Updates API: `eero-api`'s `UpdatesAPI`.
//!
//! Ported from `eero-api src/eero/api/updates.py` (v8.4.1). `get_updates` existed at `v6.2.0`;
//! `apply_update` is new at v8.0.4 and `set_preferred_update_hour` at v8.2.0.
use std::sync::Arc;
use serde_json::{Value, json};
use crate::envelope::Envelope;
use crate::error::Error;
use crate::links::warn_uncharacterised_write;
use crate::params::require_hour;
use crate::routes;
use crate::transport::{RequestBody, Transport};
/// `eero-api`'s `UpdatesAPI` (`src/eero/api/updates.py`).
///
/// Build one with [`UpdatesApi::new`], wrapping a [`Transport`] already shared with the rest of
/// the `EeroApi` aggregator — `UpdatesApi` never constructs or owns a `Transport` itself.
#[derive(Debug)]
pub struct UpdatesApi {
transport: Arc<Transport>,
}
impl UpdatesApi {
/// Wraps `transport` as an `UpdatesApi`.
#[must_use]
pub fn new(transport: Arc<Transport>) -> Self {
Self { transport }
}
/// Gets available firmware/software updates for a network — returns the raw Eero API
/// response.
///
/// Ported from `eero-api src/eero/api/updates.py:36-64` (`UpdatesAPI.get_updates`). Sends
/// `GET` [`crate::routes::updates::GET_UPDATES_V8`], preferring `parent`'s own published
/// `updates` link.
///
/// # Errors
///
/// Returns [`Error::Validation`] if `network_id`/`parent` cannot be resolved to a URL.
/// Otherwise, [`Error::Authentication`] if no valid session is configured, or whatever
/// status-mapped [`Error`] the request produces.
pub async fn get_updates(
&self,
network_id: &str,
parent: Option<&Value>,
) -> Result<Envelope, Error> {
self.transport
.resource(
&routes::updates::GET_UPDATES_V8,
network_id,
parent,
&[],
RequestBody::None,
)
.await
}
/// Applies a pending update — returns the raw Eero API response.
///
/// Ported from `eero-api src/eero/api/updates.py:66-105` (`UpdatesAPI.apply_update`). Sends
/// the literal two-byte body `""` ([`RequestBody::EmptyJsonString`]) to
/// [`crate::routes::updates::UPDATES_APPLY_UPDATE`], preferring `parent`'s own published `updates`
/// link. **Reboot-class write**: applying an update reboots every node on the network.
/// Unverified against a live network: logs one `WARNING` via [`warn_uncharacterised_write`]
/// before issuing the request (`updates.py:102`).
///
/// # Errors
///
/// See [`UpdatesApi::get_updates`].
pub async fn apply_update(
&self,
network_id: &str,
parent: Option<&Value>,
) -> Result<Envelope, Error> {
let url = routes::updates::UPDATES_APPLY_UPDATE.resolve(
self.transport.api_host(),
network_id,
parent,
)?;
warn_uncharacterised_write("apply update for network — reboots every node");
self.transport
.request(
routes::updates::UPDATES_APPLY_UPDATE.method.clone(),
url,
&[],
RequestBody::EmptyJsonString,
)
.await
}
/// Sets the hour of day the network applies firmware updates — returns the raw Eero API
/// response.
///
/// Ported from `eero-api src/eero/api/updates.py:107-137`
/// (`UpdatesAPI.set_preferred_update_hour`). Sends a JSON `POST` of exactly
/// `{"preferred_update_hour": hour}` to
/// [`crate::routes::updates::UPDATES_SET_PREFERRED_UPDATE_HOUR`]. `hour` is the hour of day in
/// the network's timezone, `0` (midnight to 1 am) through `23` (11 pm to midnight). The
/// current value is readable from the network envelope's `updates.preferred_update_hour`. The
/// network envelope publishes no link to this resource, so the path is always built from the
/// template and there is no `parent` parameter; `network_id` may be a bare id, a host-relative
/// API path or an absolute API-host URL.
///
/// **Unverified against a live account**: read the current value first, skip the write when
/// it already matches, and never retry a failed write in a loop. Logs one `WARNING` via
/// [`warn_uncharacterised_write`] after validation and URL resolution, immediately before the
/// request (`updates.py:136`).
///
/// # Errors
///
/// Returns [`Error::Validation`] with field `hour` if `hour` is outside `0..=23`. That check
/// is the first statement (`updates.py:129`), so it wins over an unresolvable `network_id`
/// and a missing session, and nothing is sent. Python also rejects a `bool`, `float`, `str` or
/// `None` hour; the `i32` parameter makes those unrepresentable. Then
/// [`Error::Validation`] if `network_id` cannot be resolved to a URL. Otherwise
/// [`Error::Authentication`] if no valid session is configured (raised by the transport,
/// which — unlike Python — runs after URL resolution and the warning), or whatever
/// status-mapped [`Error`] the request produces.
pub async fn set_preferred_update_hour(
&self,
network_id: &str,
hour: i32,
) -> Result<Envelope, Error> {
require_hour("hour", hour)?;
let url = routes::updates::UPDATES_SET_PREFERRED_UPDATE_HOUR.resolve(
self.transport.api_host(),
network_id,
None,
)?;
warn_uncharacterised_write("set preferred update hour for network");
self.transport
.request(
routes::updates::UPDATES_SET_PREFERRED_UPDATE_HOUR
.method
.clone(),
url,
&[],
RequestBody::Json(json!({ "preferred_update_hour": hour })),
)
.await
}
}