python-amazon-echo 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. python_amazon_echo-0.1.0/.gitignore +12 -0
  2. python_amazon_echo-0.1.0/CHANGELOG.md +33 -0
  3. python_amazon_echo-0.1.0/LICENSE +21 -0
  4. python_amazon_echo-0.1.0/PKG-INFO +268 -0
  5. python_amazon_echo-0.1.0/README.md +244 -0
  6. python_amazon_echo-0.1.0/pyproject.toml +131 -0
  7. python_amazon_echo-0.1.0/src/amazon_echo/__init__.py +61 -0
  8. python_amazon_echo-0.1.0/src/amazon_echo/__main__.py +132 -0
  9. python_amazon_echo-0.1.0/src/amazon_echo/auth.py +404 -0
  10. python_amazon_echo-0.1.0/src/amazon_echo/client.py +1626 -0
  11. python_amazon_echo-0.1.0/src/amazon_echo/const.py +260 -0
  12. python_amazon_echo-0.1.0/src/amazon_echo/exceptions.py +37 -0
  13. python_amazon_echo-0.1.0/src/amazon_echo/local.py +94 -0
  14. python_amazon_echo-0.1.0/src/amazon_echo/models.py +165 -0
  15. python_amazon_echo-0.1.0/src/amazon_echo/push.py +298 -0
  16. python_amazon_echo-0.1.0/src/amazon_echo/py.typed +0 -0
  17. python_amazon_echo-0.1.0/tests/__init__.py +0 -0
  18. python_amazon_echo-0.1.0/tests/conftest.py +165 -0
  19. python_amazon_echo-0.1.0/tests/fixtures/automations.json +41 -0
  20. python_amazon_echo-0.1.0/tests/fixtures/devices.json +106 -0
  21. python_amazon_echo-0.1.0/tests/fixtures/graphql_endpoints.json +65 -0
  22. python_amazon_echo-0.1.0/tests/fixtures/history.json +36 -0
  23. python_amazon_echo-0.1.0/tests/fixtures/notifications.json +44 -0
  24. python_amazon_echo-0.1.0/tests/fixtures/np_player.json +11 -0
  25. python_amazon_echo-0.1.0/tests/test_auth.py +352 -0
  26. python_amazon_echo-0.1.0/tests/test_client.py +1557 -0
  27. python_amazon_echo-0.1.0/tests/test_local.py +100 -0
  28. python_amazon_echo-0.1.0/tests/test_models.py +68 -0
  29. python_amazon_echo-0.1.0/tests/test_push.py +365 -0
@@ -0,0 +1,12 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ .coverage
10
+ .DS_Store
11
+ site/
12
+ .mypy_cache/
@@ -0,0 +1,33 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [0.1.0] - 2026-11-15
8
+
9
+ ### Added
10
+
11
+ - `AmazonEchoClient`: cookie + `csrf` authentication, one cookie exchange and
12
+ retry on 401/403, back-off on 429/503, typed errors, `on_credentials_update`.
13
+ - Login without password storage: `build_authorize_url` + `register_device`
14
+ (external browser, PKCE) and `Credentials.from_alexa_media`.
15
+ - Inventory: account, devices merged with the GraphQL endpoints (MAC, model,
16
+ endpoint id), routines, music providers.
17
+ - Bulk state: do-not-disturb, volumes, Bluetooth, notifications, alarm volumes,
18
+ wake words, ascending alarms, GraphQL endpoint state (temperature,
19
+ reachability, Fire TV remote battery and ambient mode), now playing.
20
+ - Per-device settings: Wi-Fi, equalizer, earcons, AUX ports, alarm sounds,
21
+ default alarm sound, available wake words and any setting key.
22
+ - Account preferences: whisper mode, adaptive volume.
23
+ - Actions through the sequence API: volume, stop, speak, announce, text command,
24
+ sound, music, skill launch, routines; transport commands, Bluetooth
25
+ connect/disconnect, reboot.
26
+ - Alarms, timers and reminders: list, create, delete.
27
+ - Lists: shopping, to-do and custom lists with item create/update/delete.
28
+ - Voice history.
29
+ - `call_feature`: GraphQL `setEndpointFeatures` escape hatch.
30
+ - `PushClient`: HTTP/2 push stream with reconnect back-off; every event is
31
+ passed through.
32
+ - `probe_local` / `is_reachable`: LAN identification and liveness.
33
+ - `amazon-echo` command line interface.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hudson Brendon
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,268 @@
1
+ Metadata-Version: 2.5
2
+ Name: python-amazon-echo
3
+ Version: 0.1.0
4
+ Summary: Async Python client for Amazon Echo / Alexa devices: state, settings, media, notifications, lists, HTTP/2 push and LAN discovery
5
+ Project-URL: Homepage, https://github.com/hudsonbrendon/python-amazon-echo
6
+ Project-URL: Repository, https://github.com/hudsonbrendon/python-amazon-echo
7
+ Project-URL: Issues, https://github.com/hudsonbrendon/python-amazon-echo/issues
8
+ Project-URL: Changelog, https://github.com/hudsonbrendon/python-amazon-echo/blob/main/CHANGELOG.md
9
+ Author-email: Hudson Brendon <contato.hudsonbrendon@gmail.com>
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: aiohttp,alexa,amazon,async,echo,fire-tv,home-assistant
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Framework :: AsyncIO
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.14
18
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.14
21
+ Requires-Dist: aiohttp>=3.10
22
+ Requires-Dist: httpx[http2]>=0.27
23
+ Description-Content-Type: text/markdown
24
+
25
+ # python-amazon-echo
26
+
27
+ [![Tests](https://github.com/hudsonbrendon/python-amazon-echo/actions/workflows/tests.yml/badge.svg)](https://github.com/hudsonbrendon/python-amazon-echo/actions/workflows/tests.yml)
28
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
29
+
30
+ Async Python client for Amazon Echo / Alexa devices: device inventory, state,
31
+ settings, media, text-to-speech, alarms/timers/reminders, lists, voice history,
32
+ an HTTP/2 push channel and LAN discovery. It is the library behind the
33
+ `amazon_echo` Home Assistant integration.
34
+
35
+ It was written from a reverse-engineering pass over the Alexa app
36
+ (`com.amazon.dee.app` 2.2.730155.0), the Alexa web API and what an Echo exposes
37
+ on the local network. It is not affiliated with Amazon.
38
+
39
+ ## Features
40
+
41
+ - **No password storage.** You log in in your own browser (passkeys, 2FA and
42
+ captchas just work) and paste the final URL; the library keeps a refresh token
43
+ and cookies. A session of the `alexa_media` integration can be imported too.
44
+ - **Self-healing session.** A 401/403 triggers one cookie exchange with the
45
+ refresh token and a retry; 429/503 are retried with a short back-off; every
46
+ change of tokens or cookies is reported through `on_credentials_update`.
47
+ - **Inventory and state in bulk.** Devices merged with the GraphQL endpoints
48
+ (MAC, model, endpoint id), and one call each for volumes, do-not-disturb,
49
+ Bluetooth, notifications, alarm volumes, wake words, ascending alarms and the
50
+ GraphQL state (temperature, reachability, Fire TV remote battery, ambient mode).
51
+ - **Settings nobody else exposes.** Equalizer, request sounds (earcons), alarm
52
+ volume, default alarm sound, ascending alarm, wake word, AUX direction, whisper
53
+ mode, adaptive volume and any per-device setting key (speaking rate, time zone,
54
+ captions, …).
55
+ - **Actions.** Volume, stop, speak, announce, text command, sounds, music,
56
+ skills, routines, transport commands, Bluetooth, reboot.
57
+ - **Alarms, timers and reminders.** List all, create and delete.
58
+ - **Lists.** Shopping, to-do and custom lists with full item CRUD.
59
+ - **Voice history.**
60
+ - **Push.** One HTTP/2 stream delivers volume, playback, do-not-disturb,
61
+ Bluetooth, notification, list and activity events; unknown events are passed
62
+ through, never dropped.
63
+ - **LAN.** Identify an Echo by IP (name, model, multi-room groups, active Spotify
64
+ user) and check that it is alive, without the cloud.
65
+ - Fully typed (`py.typed`), `aiohttp` with an injectable session, `httpx[http2]`
66
+ for push.
67
+
68
+ ## Installation
69
+
70
+ ```bash
71
+ pip install python-amazon-echo
72
+ ```
73
+
74
+ Python 3.14 or newer.
75
+
76
+ ## Quick start
77
+
78
+ ```python
79
+ import asyncio
80
+ import json
81
+ from pathlib import Path
82
+
83
+ from amazon_echo import AmazonEchoClient, Credentials
84
+
85
+ PATH = Path("credentials.json")
86
+
87
+
88
+ def save(credentials: Credentials) -> None:
89
+ PATH.write_text(json.dumps(credentials.to_dict()))
90
+
91
+
92
+ async def main() -> None:
93
+ credentials = Credentials.from_dict(json.loads(PATH.read_text()))
94
+ async with AmazonEchoClient(credentials, on_credentials_update=save) as client:
95
+ devices = await client.get_devices()
96
+ volumes = await client.get_volumes()
97
+ for device in devices:
98
+ print(device.name, device.model, device.online, volumes.get(device.serial))
99
+
100
+ echo = next(d for d in devices if d.family == "ECHO")
101
+ await client.set_volume(echo, 30)
102
+ await client.speak(echo, "Hello from Python")
103
+
104
+
105
+ asyncio.run(main())
106
+ ```
107
+
108
+ Push events:
109
+
110
+ ```python
111
+ from amazon_echo import PushClient, PushEvent
112
+
113
+
114
+ def on_event(event: PushEvent) -> None:
115
+ print(event.command, event.device_serial, event.payload)
116
+
117
+
118
+ push = PushClient(client, on_event, on_state=lambda up: print("push up:", up))
119
+ await push.start() # background task, reconnects with back-off 5·2ⁿ s (≤ 600 s)
120
+ ...
121
+ await push.stop()
122
+ ```
123
+
124
+ LAN:
125
+
126
+ ```python
127
+ from amazon_echo import is_reachable, probe_local
128
+
129
+ info = await probe_local("192.168.1.50") # None if it is not an Amazon device
130
+ print(info.name, info.model, info.groups, info.spotify_user)
131
+ print(await is_reachable("192.168.1.50"))
132
+ ```
133
+
134
+ ## Logging in with your own browser
135
+
136
+ ```python
137
+ from amazon_echo import build_authorize_url, register_device
138
+
139
+ request = build_authorize_url(language="en-US")
140
+ print(request.url) # 1. open it and log in to Amazon
141
+ redirect = input("Paste the final URL: ") # 2. see below
142
+ credentials = await register_device(request, redirect)
143
+ ```
144
+
145
+ 1. Open `request.url` in any browser and log in as usual (password, passkey,
146
+ 2FA, captcha — whatever Amazon asks for). The login always starts on
147
+ amazon.com, also for accounts of other marketplaces.
148
+ 2. When the login is done the browser lands on a blank or "page not found" page
149
+ whose address starts with `https://www.amazon.com/ap/maplanding?` and contains
150
+ `openid.oa2.authorization_code=…`. That is expected. Copy the whole address.
151
+ 3. Pass it to `register_device`. The one-time code is exchanged for a device
152
+ registration ("Amazon Echo for Home Assistant" shows up in your Amazon
153
+ account under *Manage your content and devices*), the account's own
154
+ marketplace is discovered and cookies for it are fetched.
155
+
156
+ Keep the same `AuthorizeRequest` between steps 1 and 3 (it carries the PKCE
157
+ verifier), and persist `credentials.to_dict()`.
158
+
159
+ The command line does the same: `amazon-echo login`.
160
+
161
+ To reuse a session of the `alexa_media` integration instead:
162
+
163
+ ```python
164
+ credentials = Credentials.from_alexa_media(entry_data, cookies)
165
+ # entry_data: the `data` of the alexa_media config entry
166
+ # cookies: the "cookies" list of .storage/alexa_media.<email>.cookies
167
+ ```
168
+
169
+ Such a session shares one device registration with `alexa_media`. Everything
170
+ works except push while both run (see *Known limitations*).
171
+
172
+ ## Command line
173
+
174
+ ```bash
175
+ amazon-echo login
176
+ amazon-echo devices # also: account, states, volumes, dnd, bluetooth,
177
+ # notifications, routines, lists, history, providers
178
+ amazon-echo push # print push events
179
+ amazon-echo probe 192.168.1.50
180
+ ```
181
+
182
+ Credentials are read from `~/.config/amazon-echo/credentials.json`
183
+ (`--credentials` to change).
184
+
185
+ ## Verification
186
+
187
+ How each part was checked against a real amazon.com.br account on 2026-11-15. Everything is also covered by unit tests with mocked
188
+ HTTP.
189
+
190
+ - **live read** — called against Amazon through this library, answer parsed.
191
+ - **no-op write** — the value just read was written back to one Echo Plus and
192
+ read again; Amazon accepted the request.
193
+ - **ported** — implemented from the app / existing open-source clients and unit
194
+ tested only. Not replayed live (audible or disruptive).
195
+
196
+ | API | Status |
197
+ |---|---|
198
+ | `request`, 429/503 retry, non-JSON detection | live read |
199
+ | `async_get_access_token` (`auth/token`) | live (token refreshed) |
200
+ | Cookie exchange on 401/403 (`auth/token`, `auth_cookies`) | ported — never triggered live |
201
+ | `build_authorize_url`, `register_device` | ported (the authorize URL answers 302 as expected; no registration was made) |
202
+ | `get_account`, `get_devices`, `get_routines`, `get_music_providers`, `get_service_urls` | live read |
203
+ | `get_dnd`, `get_volumes`, `get_bluetooth`, `get_notifications`, `get_alarm_volumes`, `get_wake_words`, `get_ascending_alarms`, `get_endpoint_states` | live read |
204
+ | `get_media` | live read (idle player only) |
205
+ | `get_wifi`, `get_equalizer`, `get_earcons`, `get_aux`, `get_setting`, `get_available_wake_words`, `get_alarm_sounds`, `get_default_alarm_sound` | live read |
206
+ | `get_whisper_mode`, `get_adaptive_volume` | live read |
207
+ | `set_whisper_mode`, `set_adaptive_volume` | no-op write during the reverse engineering (same request), not replayed by the library |
208
+ | `set_dnd`, `set_equalizer`, `set_earcons`, `set_alarm_volume`, `set_ascending_alarm`, `set_default_alarm_sound`, `set_setting` | no-op write |
209
+ | `set_aux_direction` | no-op write accepted; the body field name is unconfirmed |
210
+ | `set_volume` (sequence pipeline) | no-op write |
211
+ | `create_reminder`, `delete_notification` | live (a reminder 320 days ahead was created and deleted) |
212
+ | `create_alarm` | ported |
213
+ | `create_timer` | ported — body inferred from field names in the app, never sent |
214
+ | `set_wake_word` | ported |
215
+ | `speak`, `announce`, `text_command`, `play_sound`, `play_music`, `launch_skill`, `run_routine`, `stop` | ported |
216
+ | `media_command`, `bluetooth_connect`, `bluetooth_disconnect`, `reboot` | ported |
217
+ | `get_lists`, `get_list_items` | live read |
218
+ | `add_list_item`, `update_list_item`, `delete_list_item` | ported |
219
+ | `get_voice_history` | live read |
220
+ | `call_feature` | ported |
221
+ | `PushClient` | handshake live (HTTP/2, 200, multipart boundary). the stream is then closed within ~1 s because the test session shares its registration with a running `alexa_media` (one stream per registration, see *Known limitations*); event parsing is unit tested only |
222
+ | `probe_local`, `is_reachable` | live (two Echo models answer, a smart TV of another brand returns None) |
223
+
224
+ ## Known limitations
225
+
226
+ - **An Echo has no local control API.** On the LAN it only answers the Spotify
227
+ Connect zeroconf endpoint (TCP 4070), advertises itself as a Matter controller
228
+ and Thread border router, and accepts TCP on its multi-room audio port (55442).
229
+ "Local" in this library therefore means discovery, name/model/group lookup and
230
+ liveness. Every command and every other piece of state goes through Amazon's
231
+ cloud; push only removes the polling.
232
+ - **Push with an imported `alexa_media` session.** Amazon keeps one push stream per
233
+ app registration and the newest connection wins. Verified on 2026-11-15 with
234
+ `alexa_media` debug logging on: opening our stream made `alexa_media` log
235
+ `HTTP2 Connection Closed`, it reconnected at once, and that closed ours about a
236
+ second later. So do not run `PushClient` on an imported session while
237
+ `alexa_media` is running; poll instead, or sign in with the browser flow to get
238
+ an own registration. `PushClient` does not re-declare AVS capabilities for
239
+ imported sessions.
240
+ - **Alarm and reminder times** are read by Amazon in the Echo's own time zone and
241
+ the API takes no zone. Aware datetimes are converted to the system time zone;
242
+ pass a naive datetime in the Echo's local time if the host lives elsewhere.
243
+ - **Alarms have no label** in Amazon's API; `create_alarm(label=…)` is accepted
244
+ and ignored.
245
+ - **`create_timer` is unverified** (see the table). Use
246
+ `text_command(device, "set a timer for 5 minutes")` if it is rejected.
247
+ - **Voice history** comes 10 records per call; at most 50 are fetched.
248
+ - **Lists** return the first 100 items.
249
+ - **`get_notifications`** is a large, rate-limited answer; call it sparingly (push
250
+ sends `PUSH_NOTIFICATION_CHANGE`).
251
+ - `devices-v2` no longer reports MAC addresses or battery levels for most
252
+ devices; the MAC comes from GraphQL and is missing for apps and groups.
253
+ - Amazon can change or remove any of this without notice.
254
+
255
+ ## Development
256
+
257
+ ```bash
258
+ uv sync
259
+ uv run ruff check . && uv run ruff format --check .
260
+ uv run mypy src
261
+ uv run pytest
262
+ ```
263
+
264
+ Test fixtures are hand-written; no real account data is in this repository.
265
+
266
+ ## License
267
+
268
+ MIT
@@ -0,0 +1,244 @@
1
+ # python-amazon-echo
2
+
3
+ [![Tests](https://github.com/hudsonbrendon/python-amazon-echo/actions/workflows/tests.yml/badge.svg)](https://github.com/hudsonbrendon/python-amazon-echo/actions/workflows/tests.yml)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
5
+
6
+ Async Python client for Amazon Echo / Alexa devices: device inventory, state,
7
+ settings, media, text-to-speech, alarms/timers/reminders, lists, voice history,
8
+ an HTTP/2 push channel and LAN discovery. It is the library behind the
9
+ `amazon_echo` Home Assistant integration.
10
+
11
+ It was written from a reverse-engineering pass over the Alexa app
12
+ (`com.amazon.dee.app` 2.2.730155.0), the Alexa web API and what an Echo exposes
13
+ on the local network. It is not affiliated with Amazon.
14
+
15
+ ## Features
16
+
17
+ - **No password storage.** You log in in your own browser (passkeys, 2FA and
18
+ captchas just work) and paste the final URL; the library keeps a refresh token
19
+ and cookies. A session of the `alexa_media` integration can be imported too.
20
+ - **Self-healing session.** A 401/403 triggers one cookie exchange with the
21
+ refresh token and a retry; 429/503 are retried with a short back-off; every
22
+ change of tokens or cookies is reported through `on_credentials_update`.
23
+ - **Inventory and state in bulk.** Devices merged with the GraphQL endpoints
24
+ (MAC, model, endpoint id), and one call each for volumes, do-not-disturb,
25
+ Bluetooth, notifications, alarm volumes, wake words, ascending alarms and the
26
+ GraphQL state (temperature, reachability, Fire TV remote battery, ambient mode).
27
+ - **Settings nobody else exposes.** Equalizer, request sounds (earcons), alarm
28
+ volume, default alarm sound, ascending alarm, wake word, AUX direction, whisper
29
+ mode, adaptive volume and any per-device setting key (speaking rate, time zone,
30
+ captions, …).
31
+ - **Actions.** Volume, stop, speak, announce, text command, sounds, music,
32
+ skills, routines, transport commands, Bluetooth, reboot.
33
+ - **Alarms, timers and reminders.** List all, create and delete.
34
+ - **Lists.** Shopping, to-do and custom lists with full item CRUD.
35
+ - **Voice history.**
36
+ - **Push.** One HTTP/2 stream delivers volume, playback, do-not-disturb,
37
+ Bluetooth, notification, list and activity events; unknown events are passed
38
+ through, never dropped.
39
+ - **LAN.** Identify an Echo by IP (name, model, multi-room groups, active Spotify
40
+ user) and check that it is alive, without the cloud.
41
+ - Fully typed (`py.typed`), `aiohttp` with an injectable session, `httpx[http2]`
42
+ for push.
43
+
44
+ ## Installation
45
+
46
+ ```bash
47
+ pip install python-amazon-echo
48
+ ```
49
+
50
+ Python 3.14 or newer.
51
+
52
+ ## Quick start
53
+
54
+ ```python
55
+ import asyncio
56
+ import json
57
+ from pathlib import Path
58
+
59
+ from amazon_echo import AmazonEchoClient, Credentials
60
+
61
+ PATH = Path("credentials.json")
62
+
63
+
64
+ def save(credentials: Credentials) -> None:
65
+ PATH.write_text(json.dumps(credentials.to_dict()))
66
+
67
+
68
+ async def main() -> None:
69
+ credentials = Credentials.from_dict(json.loads(PATH.read_text()))
70
+ async with AmazonEchoClient(credentials, on_credentials_update=save) as client:
71
+ devices = await client.get_devices()
72
+ volumes = await client.get_volumes()
73
+ for device in devices:
74
+ print(device.name, device.model, device.online, volumes.get(device.serial))
75
+
76
+ echo = next(d for d in devices if d.family == "ECHO")
77
+ await client.set_volume(echo, 30)
78
+ await client.speak(echo, "Hello from Python")
79
+
80
+
81
+ asyncio.run(main())
82
+ ```
83
+
84
+ Push events:
85
+
86
+ ```python
87
+ from amazon_echo import PushClient, PushEvent
88
+
89
+
90
+ def on_event(event: PushEvent) -> None:
91
+ print(event.command, event.device_serial, event.payload)
92
+
93
+
94
+ push = PushClient(client, on_event, on_state=lambda up: print("push up:", up))
95
+ await push.start() # background task, reconnects with back-off 5·2ⁿ s (≤ 600 s)
96
+ ...
97
+ await push.stop()
98
+ ```
99
+
100
+ LAN:
101
+
102
+ ```python
103
+ from amazon_echo import is_reachable, probe_local
104
+
105
+ info = await probe_local("192.168.1.50") # None if it is not an Amazon device
106
+ print(info.name, info.model, info.groups, info.spotify_user)
107
+ print(await is_reachable("192.168.1.50"))
108
+ ```
109
+
110
+ ## Logging in with your own browser
111
+
112
+ ```python
113
+ from amazon_echo import build_authorize_url, register_device
114
+
115
+ request = build_authorize_url(language="en-US")
116
+ print(request.url) # 1. open it and log in to Amazon
117
+ redirect = input("Paste the final URL: ") # 2. see below
118
+ credentials = await register_device(request, redirect)
119
+ ```
120
+
121
+ 1. Open `request.url` in any browser and log in as usual (password, passkey,
122
+ 2FA, captcha — whatever Amazon asks for). The login always starts on
123
+ amazon.com, also for accounts of other marketplaces.
124
+ 2. When the login is done the browser lands on a blank or "page not found" page
125
+ whose address starts with `https://www.amazon.com/ap/maplanding?` and contains
126
+ `openid.oa2.authorization_code=…`. That is expected. Copy the whole address.
127
+ 3. Pass it to `register_device`. The one-time code is exchanged for a device
128
+ registration ("Amazon Echo for Home Assistant" shows up in your Amazon
129
+ account under *Manage your content and devices*), the account's own
130
+ marketplace is discovered and cookies for it are fetched.
131
+
132
+ Keep the same `AuthorizeRequest` between steps 1 and 3 (it carries the PKCE
133
+ verifier), and persist `credentials.to_dict()`.
134
+
135
+ The command line does the same: `amazon-echo login`.
136
+
137
+ To reuse a session of the `alexa_media` integration instead:
138
+
139
+ ```python
140
+ credentials = Credentials.from_alexa_media(entry_data, cookies)
141
+ # entry_data: the `data` of the alexa_media config entry
142
+ # cookies: the "cookies" list of .storage/alexa_media.<email>.cookies
143
+ ```
144
+
145
+ Such a session shares one device registration with `alexa_media`. Everything
146
+ works except push while both run (see *Known limitations*).
147
+
148
+ ## Command line
149
+
150
+ ```bash
151
+ amazon-echo login
152
+ amazon-echo devices # also: account, states, volumes, dnd, bluetooth,
153
+ # notifications, routines, lists, history, providers
154
+ amazon-echo push # print push events
155
+ amazon-echo probe 192.168.1.50
156
+ ```
157
+
158
+ Credentials are read from `~/.config/amazon-echo/credentials.json`
159
+ (`--credentials` to change).
160
+
161
+ ## Verification
162
+
163
+ How each part was checked against a real amazon.com.br account on 2026-11-15. Everything is also covered by unit tests with mocked
164
+ HTTP.
165
+
166
+ - **live read** — called against Amazon through this library, answer parsed.
167
+ - **no-op write** — the value just read was written back to one Echo Plus and
168
+ read again; Amazon accepted the request.
169
+ - **ported** — implemented from the app / existing open-source clients and unit
170
+ tested only. Not replayed live (audible or disruptive).
171
+
172
+ | API | Status |
173
+ |---|---|
174
+ | `request`, 429/503 retry, non-JSON detection | live read |
175
+ | `async_get_access_token` (`auth/token`) | live (token refreshed) |
176
+ | Cookie exchange on 401/403 (`auth/token`, `auth_cookies`) | ported — never triggered live |
177
+ | `build_authorize_url`, `register_device` | ported (the authorize URL answers 302 as expected; no registration was made) |
178
+ | `get_account`, `get_devices`, `get_routines`, `get_music_providers`, `get_service_urls` | live read |
179
+ | `get_dnd`, `get_volumes`, `get_bluetooth`, `get_notifications`, `get_alarm_volumes`, `get_wake_words`, `get_ascending_alarms`, `get_endpoint_states` | live read |
180
+ | `get_media` | live read (idle player only) |
181
+ | `get_wifi`, `get_equalizer`, `get_earcons`, `get_aux`, `get_setting`, `get_available_wake_words`, `get_alarm_sounds`, `get_default_alarm_sound` | live read |
182
+ | `get_whisper_mode`, `get_adaptive_volume` | live read |
183
+ | `set_whisper_mode`, `set_adaptive_volume` | no-op write during the reverse engineering (same request), not replayed by the library |
184
+ | `set_dnd`, `set_equalizer`, `set_earcons`, `set_alarm_volume`, `set_ascending_alarm`, `set_default_alarm_sound`, `set_setting` | no-op write |
185
+ | `set_aux_direction` | no-op write accepted; the body field name is unconfirmed |
186
+ | `set_volume` (sequence pipeline) | no-op write |
187
+ | `create_reminder`, `delete_notification` | live (a reminder 320 days ahead was created and deleted) |
188
+ | `create_alarm` | ported |
189
+ | `create_timer` | ported — body inferred from field names in the app, never sent |
190
+ | `set_wake_word` | ported |
191
+ | `speak`, `announce`, `text_command`, `play_sound`, `play_music`, `launch_skill`, `run_routine`, `stop` | ported |
192
+ | `media_command`, `bluetooth_connect`, `bluetooth_disconnect`, `reboot` | ported |
193
+ | `get_lists`, `get_list_items` | live read |
194
+ | `add_list_item`, `update_list_item`, `delete_list_item` | ported |
195
+ | `get_voice_history` | live read |
196
+ | `call_feature` | ported |
197
+ | `PushClient` | handshake live (HTTP/2, 200, multipart boundary). the stream is then closed within ~1 s because the test session shares its registration with a running `alexa_media` (one stream per registration, see *Known limitations*); event parsing is unit tested only |
198
+ | `probe_local`, `is_reachable` | live (two Echo models answer, a smart TV of another brand returns None) |
199
+
200
+ ## Known limitations
201
+
202
+ - **An Echo has no local control API.** On the LAN it only answers the Spotify
203
+ Connect zeroconf endpoint (TCP 4070), advertises itself as a Matter controller
204
+ and Thread border router, and accepts TCP on its multi-room audio port (55442).
205
+ "Local" in this library therefore means discovery, name/model/group lookup and
206
+ liveness. Every command and every other piece of state goes through Amazon's
207
+ cloud; push only removes the polling.
208
+ - **Push with an imported `alexa_media` session.** Amazon keeps one push stream per
209
+ app registration and the newest connection wins. Verified on 2026-11-15 with
210
+ `alexa_media` debug logging on: opening our stream made `alexa_media` log
211
+ `HTTP2 Connection Closed`, it reconnected at once, and that closed ours about a
212
+ second later. So do not run `PushClient` on an imported session while
213
+ `alexa_media` is running; poll instead, or sign in with the browser flow to get
214
+ an own registration. `PushClient` does not re-declare AVS capabilities for
215
+ imported sessions.
216
+ - **Alarm and reminder times** are read by Amazon in the Echo's own time zone and
217
+ the API takes no zone. Aware datetimes are converted to the system time zone;
218
+ pass a naive datetime in the Echo's local time if the host lives elsewhere.
219
+ - **Alarms have no label** in Amazon's API; `create_alarm(label=…)` is accepted
220
+ and ignored.
221
+ - **`create_timer` is unverified** (see the table). Use
222
+ `text_command(device, "set a timer for 5 minutes")` if it is rejected.
223
+ - **Voice history** comes 10 records per call; at most 50 are fetched.
224
+ - **Lists** return the first 100 items.
225
+ - **`get_notifications`** is a large, rate-limited answer; call it sparingly (push
226
+ sends `PUSH_NOTIFICATION_CHANGE`).
227
+ - `devices-v2` no longer reports MAC addresses or battery levels for most
228
+ devices; the MAC comes from GraphQL and is missing for apps and groups.
229
+ - Amazon can change or remove any of this without notice.
230
+
231
+ ## Development
232
+
233
+ ```bash
234
+ uv sync
235
+ uv run ruff check . && uv run ruff format --check .
236
+ uv run mypy src
237
+ uv run pytest
238
+ ```
239
+
240
+ Test fixtures are hand-written; no real account data is in this repository.
241
+
242
+ ## License
243
+
244
+ MIT