shelly

# Changelog

## v0.3.0

Credentials became a struct. Every function previously took an ad-hoc map
(`%{server:, token:}` for OAuth, `%{server:, auth_key:}` for the key APIs,
plus optional `:rate_key` / `:req_options` keys nothing declared), which
left the shape of the library's central concept implied rather than
stated. **`Shelly.Client` now is that concept**, and every entry point
takes one.

Breaking, deliberately: 0.2.x had no users to protect, and this is far
cheaper to change now than after it sets.

```elixir
{:ok, client} = Shelly.OAuth.exchange_code(code)
client = Shelly.Client.put_rate_key(client, account.id)

{:ok, statuses} = Shelly.Account.all_statuses(client)
{:ok, _pid} = Shelly.Events.start_link(client, handler: &handle/1)
```

- `Shelly.OAuth.exchange_code/2` and `refresh/2` return a client instead
  of a bare grant map; `to_account/1` is gone, since the client *is* the
  account. A refresh now carries the auth key, pacing key and request
  options forward, and no longer wipes a stored refresh token when the
  server declines to reissue one.
- `Shelly.Account`, `Shelly.CloudV1` and `Shelly.CloudV2` take a client.
  One client can hold **both** credentials, which is how control survives
  a token expiry: realtime and discovery need OAuth, switching doesn't.
- `Shelly.Events.start_link/2` takes a client rather than loose
  `:server`/`:token` options, and returns `{:error, :no_token}` for a
  key-only client instead of opening a socket that can't authenticate.
- New: `Shelly.Client.token_expired?/1`, `expires_in/1`, `oauth?/1`, `keyed?/1`,
  `put_auth_key/2`, `put_rate_key/2`, `put_req_options/2`. Servers are
  normalized to `https://host[:port]` — the port is preserved, which an
  earlier draft of this dropped, silently sending anything on a custom
  port to 443.

### Fixed

Six of these come from a second quorum review, and three of them are the
*same defect surviving at a second call site* after the first was fixed —
which is now a standing note in `AGENTS.md`.

- **A control command is confirmed positively.** `Shelly.CloudV2` reported
  a rejected command as success: Shelly answers a refused switch with HTTP
  200 and `"isok": false`, and only the status code was checked. The first
  fix looked for an explicit `false`, which still accepted a proxy's HTML
  error page or an empty body as a switched relay; `"isok": true` is now
  required, matching `Account` and `CloudV1`.
- **A scalar `"device"` no longer kills the socket on the `Online` path.**
  `online_flag/1` carried the same unguarded `get_in/2` that
  `raw_device_id/1` was hardened against in 0.2.1, and it runs outside the
  handler's rescue — so one malformed event ended realtime for that
  account.
- **Alarm and presence deltas report unknown, not clear.** A `smoke:0`
  delta without its `alarm` key was reported as *not alarming*. This is
  the same unknown-vs-off fix 0.2.1 made for switches, on the classes
  where the wrong direction is a safety issue.
- **`http://` servers no longer become `https://host:80`.** `URI.parse/1`
  fills the port in from the source scheme, and the 0.3.0 port-preserving
  fix carried it onto the upgraded URL — every request then went to :80.
- **An empty string is no longer a credential.** `""` passed
  `is_binary/1`, so a token-less grant produced a client that reported
  itself authorized and 401'd forever.
- **A refresh answering 200 without a token** reports
  `:no_token_in_response` rather than `:refresh_unsupported`, which had
  been sending callers to re-authorize a grant the server never refused.
- Missing credentials return `{:error, :no_token}` / `{:error,
  :no_auth_key}` instead of raising from string concatenation, and
  malformed payloads (a list where a device map was promised, a v1
  response with no `device_status`, a `devices_status` that isn't a map)
  are errors rather than plausible-looking empty results.
- `Shelly.RateGate` rejects a zero or negative `:interval_ms` instead of
  silently disabling pacing, and an invalid global `:req_options` is
  logged rather than discarded.

### Fixed (second blind review round)

A second context-free review, run against code the first one had already
been through, found 19 more. The recurring shape is unchanged and worth
naming: **a rule applied in one place and not at its sibling a few lines
away.**

- **`Shelly.RateGate.run/3` could send a command twice.** Its `catch`
  wrapped the request function as well as the gate call, so a request
  exiting `{:noproc, _}` — what a dead Finch pool produces — was read as
  "the gate died" and re-run unpaced. A duplicated switch command is not
  a survivable retry.
- **`Shelly.Events.start_link/2` blocked its caller for minutes.**
  WebSockex ran the entire initial retry loop before returning, so one
  unreachable account stalled the boot of the supervisor this module
  documents itself as living in. It connects asynchronously now.
- **`enrich/2` reinstated Gen1 readings the parser had refused.** The
  component parsers honour `is_valid: false`; enrichment re-read the same
  raw maps without it, so a temperature the device flagged as bad was
  rejected by one path and restored by the other. The Gen1 emeter parser
  never checked the flag at all.
- **Battery enrichment was not channel-scoped**, so channel 1 of a
  two-channel device reported channel 0's battery — the fix that had
  already been applied to temperature, three lines away.
- **`Account.parse_status/2` raised on `nil`**, which is exactly what the
  documented usage — `parse_status(statuses[id], channel)` — produces for
  an id that isn't in the map. It is total now, like the parser it wraps.
- **`req_options: [auth: …]` replaced the Authorization header.** Req's
  auth step calls `put_header/3`, so it reached the same failure the
  `@reserved` list exists to prevent, by a door that list didn't cover.
- **An unusable nested `device.id` masked a valid top-level `deviceId`**,
  because the choice was made before normalization and `""` is truthy.
- **Integer members of `:known_ids` were rendered decimal**, so an
  integer known-id resolved the ambiguous case to the wrong device — the
  precise outcome the option exists to prevent. The precomputed set is
  also no longer rebuilt on every frame.
- **A Gen2 cover with a negative `current_pos` reported closed** while the
  Gen1 roller reported open; only one path guarded the "uncalibrated"
  sentinel.
- **`extra: %{component: …}` still relabelled on the non-map clause**, the
  one key the map clause deletes precisely to avoid a confident wrong
  label.
- **A refresh into an opaque token produced a client that never expires**
  — the trap the docs warn callers about, reachable through the library's
  own refresh path. It keeps the previous deadline now.
- `set_switch/5` and `set_cover/5` pass every option they are given
  (only `:toggle_after` used to survive); the global `:req_options` is
  keyword-validated like the per-call one; a dropped base path is warned
  about rather than silently discarded; device ids are keyed identically
  by all three transports; `gen_to_int/1` accepts a bare `"2"`.

### Changed (second blind review round)

- **`Shelly.Account.set_switch/5` refuses `:toggle_after`** with
  `{:error, :toggle_after_unsupported}` rather than switching without it.
  The account API has no equivalent of the v2 cloud-side watchdog, and
  silently dropping the option would leave a caller believing their relay
  reverts if the application dies — for unattended heating, the belief
  that matters most.
- **`Shelly` gained a "Controlling equipment safely" section**: a
  successful call means the cloud accepted the command, not that the
  relay moved; treat `on: nil` as "unknown, re-issue"; use the v2
  watchdog for anything unattended; don't let the websocket be your only
  view. The library does not read relays back, and now says so where a
  reader will find it.
- `Shelly.Events`' moduledoc documents what "gives up" means for a
  supervisor — a clean server-side close exits `:normal`, which a
  `:transient` child will not restart.

### Fixed (blind review round)

A review run with **no context at all** — no history, no known issues, no
mention that anything had been reviewed before — found 38 defects that
three guided rounds and a 178-test suite had not. Its coverage analysis is
the reason: the suite wasn't thin, it *stopped one case short*. Four
separate tests enumerated a vocabulary or swept a value range and omitted
exactly the member that failed.

- **The documented Shelly 2.5 workaround made the bug invisible instead of
  fixing it.** `extra` merged *after* dispatch, so
  `extra: %{component: "cover"}` relabelled a relay reading as a cover
  rather than running the cover parser — an open blind still read closed,
  now stamped with a component a consumer would trust. The hint now
  selects the parser, and is ignored (rather than applied as a label) when
  the payload can't support it.
- **Adding a header silently removed the `Authorization` header.**
  `:req_options` is documented as additive, but merging replaced
  `:headers` wholesale, so one extra header turned every account call into
  a 401. Headers now append, and options that describe the request itself
  (`:url`, `:method`, `:form`, `:json`, `:params`) are refused with a
  warning — they could redirect a control command to another host.
- **`Shelly.Events` could not be supervised** the way its own moduledoc
  describes: `use WebSockex` injects a `child_spec/1` shaped for a
  different `start_link`, so a standard child tuple raised at boot. It now
  defines its own.
- **`Account.parse_status/2` raised on a scalar `"cloud"` key** — the
  third site of an access-chain class the `Events` module carries a
  comment about, and the one that crashes the caller rather than being
  swallowed.
- **A Gen1 battery sensor answered for every channel**, so
  `has_component?/2` — the documented partial-delta guard — returned true
  for channel 7 of a flood sensor.
- **A Gen2 cover reporting `"stopped"` with no position said `on: true`**
  while the Gen1 path said `nil` for the same words. An uncalibrated cover
  reports `"stopped"` forever.
- **The recommended path returned less than the legacy one**:
  `Account.parse_status/2` reported `model: nil, gen: nil` because account
  statuses carry those inside `_dev_info`.
- **Padded credentials were declared usable and sent unchanged** —
  `Bearer   tok  `. Credentials are trimmed when stored, so "usable" and
  "what goes on the wire" cannot disagree.
- `expand_channels/1` raised on a non-map device entry; `channels_count`
  is bounded (an API value of 100,000 materialized 100,000 rows);
  colliding device ids are reported rather than silently overwritten;
  numeric ids no longer vanish from `CloudV2.get_statuses/2`.
- `set_cover/5` honours the options its `@spec` declares; a handler that
  throws or exits no longer kills the socket (only `raise` was caught);
  the socket URL brackets IPv6 hosts, keeps a custom port and URL-encodes
  the token; Gen1 readings marked `is_valid: false` are not reported as
  measurements; a stopped `RateGate` degrades to unpaced instead of
  exiting the caller.
- Sensor enrichment no longer falls back to channel 0, which gave every
  channel of a multi-channel device the first channel's temperature.

### Fixed (second review round)

- **`Shelly.Status.parse/4` is total again.** It is spec'd to return a
  status for any input, and its own documented guard (`has_component?/2`)
  passed payloads through that then raised: a scalar where a nested map
  was expected — `"bat" => 87`, `"wifi" => 1`, `"aenergy" => 5` — reached
  `Access.get/3`. Every nested read now goes through total accessors, so
  a malformed payload reads as absent instead of crashing the caller.
  This affected `Account.parse_status/2` and both auth-key clients, where
  nothing rescued it.
- **Empty and whitespace-only credentials no longer reach the wire.** The
  predicates rejected them; all four transports and `Events.start_link/2`
  still guarded only `nil`, so `Authorization: "Bearer "` and `auth_key=`
  were being sent. The 0.3.0 entry below claiming this was fixed was
  therefore only half true — the predicates were, the transports weren't.
- **`OAuth.exchange_code/2` no longer raises on a non-object JWT payload.**
  `peek_jwt/1` returned any decoded JSON term, so a token whose payload
  was a string or a list crashed the grant instead of erroring.
- **An unnamed component reports `on: nil`, not `false`.** The
  unknown-vs-off principle now holds one level further out: a payload that
  names nothing for the channel — a battery-only delta, the commonest
  partial there is — no longer claims the device is off.
- **A Gen1 roller in an unrecognized state reports `nil`.** `"stop"`,
  `"stopped"` and `"calibrating"` were reported as closed, while Gen2
  covers report exactly those as open — the two generations contradicted
  each other on the same physical state.
- `Events.normalize_device_id/1` returns `nil` for a blank id rather than
  `""`, which was being delivered to handlers as a device.
- `CloudV2.get_statuses/2` drops elements with no usable id instead of
  collapsing them all under `""`, where every one but the last was lost.
- Per-call `:req_options` are validated and reported like the global ones,
  rather than being silently discarded.
- IPv6 server addresses survive normalization; `expires_at` accepts a
  float `exp` (legal JSON, and it made a token look non-expiring).

### Changed (second review round)

- `Shelly.OAuth.authorize_url/2` **raises** when `:state` is present but
  not a non-empty string. Omitting it is a documented choice; passing an
  unusable one silently produced a URL with no CSRF binding while the
  caller believed otherwise. The 0.2.x positional `client_id` form is
  removed — 0.3.0 breaks every other entry point, so a compatibility shim
  for one function was inconsistent.
- `Shelly.Events.start_link/2` accepts **`:known_ids`**, which resolves
  the ambiguous device ids `normalize_device_id/2` was added for. Without
  it that escape hatch wasn't reachable from the socket — the one place
  the ambiguity actually bites.
- `Shelly.Client.new/1` **raises** on a server with no host (`""`,
  `"wss://"`, `":::"`), where 0.2.x returned the string verbatim and
  failed later, somewhere less obvious.

### Changed

- **Component precedence is now explicit**: actuators, then meters, then
  sensors. The order was previously an accident of which entries fitted a
  lookup table. Concretely this **reclassifies 12 pairings**: a
  light-family component (`cct`/`rgb`/`rgbw`/`rgbcct`) on a channel now
  wins over `pm1`, `em1` and `em:0`, which aligns `parse/4` with what
  `component_of/2` already answered before 0.2.1 unified them. No known
  device emits these overlaps; all 12 are pinned in
  `test/shelly/agreement_test.exs`. A differential against the
  pre-refactor parser over 192 payload/channel combinations shows no
  other resolution changed.
- `Shelly.Client`'s expiry predicate is now **`token_expired?/1`**. The semantics
  are deliberate — a key-only client answers `true` and is nonetheless
  fully functional, which is what makes `if token_expired?, do: CloudV2,
  else: Account` correct — but the old name asserted something about the
  client that was only true of its token.
- `Shelly.OAuth.authorize_url/2` takes options and supports **`:state`**,
  the CSRF binding for the callback. The moduledoc previously claimed
  Shelly had no such parameter; it does, and this library was talking
  users out of the only protection the flow offers.
- `Shelly.Events.normalize_device_id/2` resolves the ambiguous ids that
  length alone cannot (~5% of Gen1 ids) against a set of ids you already
  know.

## v0.2.1 — tagged, never published

*(hex went from 0.2.0 straight to 0.3.0; this section is kept because
0.3.0's notes refer back to it.)*

A pre-publish review (six external models plus a verification pass against
Shelly's own API docs) found that the decimal-id fix this release was
written for was **half a fix**, and turned up eight more defects of the same
family: a lookup or a shape assumption that quietly produces a plausible
wrong answer instead of an error.

### Fixed — device identity

- **`Events.normalize_device_id/1` missed Gen1 ids entirely.** Shelly's spec
  pins hex ids to 6 (Gen1) or 12 characters; the decimal form of a 6-char id
  is 8 digits, so the previous "longer than 12" rule left it untouched and
  every Gen1 event was dropped — the exact failure this release exists to fix.
  Conversion is now driven by the documented widths, and integer and string
  forms of one id resolve to the same key (they previously differed by
  padding: `"000000b923fa"` vs `"b923fa"`) — **except** where a decimal
  rendering is itself exactly 6 or 12 digits, which no rule can settle;
  0.3.0 adds `normalize_device_id/2` for that case.

### Fixed — protocol contracts

- **`Account.all_statuses/1` keyed results by a field Shelly documents as
  unreliable.** The vendor says the `devices_status` keys "should be ignored";
  entries are now keyed by `_dev_info.id`, with the outer key as fallback.
- **`Account.parse_status/2` read online state from `cloud.connected`**, a
  component only mains-powered Gen2+ devices carry, so every battery, Gen1
  and virtual device was reported offline. It now reads `_dev_info.online`.
- **`CloudV1.get_status/2` returned the response wrapper**, not the
  `device_status` its own docs told you to parse — yielding a device that
  looked permanently off. It now returns `{:ok, {device_status, online}}`.

### Fixed — status parsing

- **A component without its state key is no longer reported as off.** A
  websocket delta like `%{"switch:0" => %{"apower" => 15.0}}` passes both
  guards but says nothing about the relay; `:on` is now `nil` (unknown)
  instead of a confident `false`. On price-driven heating, a false OFF is
  the expensive direction. (Applied to switches, lights, covers and Gen1
  relays here; the alarm and presence classes were missed and are fixed
  in 0.3.0.)
- **Gen1 3EM: phases 1 and 2 parsed as an unmetered relay at 0 W.** Gen1
  arrays were dispatched on existence rather than on holding the requested
  channel, so a device with one relay and three emeters answered "relay" for
  every channel — while the library's own `component_of/2` said "em".
- **`component_of/2` and `parse/4` disagreed on Gen1 alarms** ("sensor" vs
  "flood"/"smoke"/"presence"). The documented guard pattern — store the
  parsed component, compare later events against `component_of/2` — dropped
  every event from those devices.
- **Gen2 covers ignored `current_pos`**, so a cover stopped at the closed end
  (and any uncalibrated cover, which reports "stopped" forever) read as open.
  Position now decides, matching the Gen1 roller path.
- **Humidity was never extracted**, despite being advertised in the docs.
  `:humidity` is now part of the parsed status.
- **Sensor add-ons on non-zero channels were invisible**: battery, temperature
  and humidity enrichment only ever looked at channel 0.
- **Pro 3EM energy was permanently `nil`** — it lives in the sibling
  `em1data:N` / `emdata:0` components.
- **Gen1 rollers discarded their energy counter**; the original Shelly 2's
  single shared meter left channel 1 looking unmetered; a Gen1 Door/Window
  sensor always read closed.

### Fixed — safety and robustness

- `OAuth.to_account/1` dropped `:refresh_token` and `:expires_at`, so
  following the documented path sent the *access* token to `refresh/2` as
  the refresh token.
- `OAuth.refresh/2` reported **429 and 408 as `:refresh_unsupported`**,
  telling callers to re-authorize a perfectly good grant because they were
  merely rate limited.
- The `*.shelly.cloud` host pin was case-sensitive, so an uppercase claim
  silently rerouted to the fallback server. (The pin itself was probed for
  userinfo, suffix, port and path bypasses and holds.)
- `Events.start_link/1` no longer returns WebSockex's URL error verbatim
  (it embeds the connection URL, which carries the access token); an
  unusable server address comes back as `{:error, :invalid_server_url}`.
- An `Online` event with no readable flag is no longer reported as offline —
  a missing field is not evidence that a device is down.
- A scalar `"device"` value in an event used to raise inside `get_in/2`,
  outside the handler's rescue, killing the socket process. (Fixed for
  `StatusOnChange` here; the same call in the `Online` path was missed and
  is fixed in 0.3.0.)
- Every dropped event now logs at debug with the id and the message keys.
  Silence in those branches is what let the decimal-id bug hide.

### Changed

- **Request options are per call.** `:req_options` on an account or conn map
  is merged into every request for `Account`, `CloudV1`, `CloudV2` and
  `OAuth` — previously only OAuth honoured it, and only globally, so nothing
  else could be proxied, re-timed or stubbed. The global
  `config :shelly, :req_options` still works as a fallback.
- **`:rate_key`** on an account or conn map gives one pacing budget per
  account across transports and across token refreshes; without it the
  credential is still the key, which meant a token refresh silently reset
  the budget.
- Docs: the root module no longer describes access tokens as long-lived
  (they last 12 hours), and `Events`' moduledoc no longer claims string ids
  pass through unchanged.

### Also in this release — quality sweep

Applied the workspace quality-sweep playbook (`~/Desktop/elixir/dev_docs/
quality_sweep.md`), whose central claim is that code review and tooling
catch different things. It held: dialyzer found three dead clauses six
models had read past, and the first HTTP-level test of `CloudV2` found
that a **rejected control command was reported as success** — Shelly
answers a refused switch with HTTP 200 and `"isok": false`, and only the
status code was being checked.

- `mix precommit` — format, unused deps, warnings-as-errors, tests with a
  90% coverage floor, `credo --strict`, dialyzer — all green.
- `@spec` on the public API, plus `Shelly.Status.t()` and
  `Shelly.OAuth.grant()` types. The status map stays a map by design
  (transports differ in what they can report); that contract is now
  stated rather than implied.
- The three dispatch tables in `Shelly.Status` collapsed into one
  (`component_tag/2`), so a new device class is added in one place and
  the drift that caused the Gen1 alarm mismatch can't recur.
- Coverage 72% → 92%, using only `mix test --cover` and Req's `:plug`
  option — no mocking dependencies.

### Tests

40 → 139. New: an agreement matrix asserting `parse/4`, `has_component?/2`
and `component_of/2` give one answer for 29 payload shapes (this catches the
whole drift class at once), partial-delta behaviour, the Gen1 6-character id
forms, and the first HTTP-level tests for `Account`.

## v0.2.0

Token lifetime work, driven by a live account going dark: a `shelly-diy`
access token turned out to last exactly 12 hours (`exp - iat = 43200`),
after which every HTTP call returns `401 invalid_token` and the
websocket is closed right after the handshake.

- `Shelly.OAuth.exchange_code/2` now returns `:refresh_token` and
  `:expires_at` (parsed from the token's `exp` claim) alongside the
  access token. Previously both were discarded, leaving callers no way
  to see expiry coming. **Persist them.**
- `Shelly.OAuth.refresh/2` — renewal via the conventional
  `grant_type=refresh_token`. Shelly documents no such grant, but it is
  honoured for a token that is still live: verified afterwards on a real
  account that renewed itself every ~11 hours, unattended, for days. An
  **expired** token cannot be refreshed — every grant variant answers
  `401 invalid_token` — so renew ahead of the deadline and treat
  `{:error, :refresh_unsupported}` as "re-authorize the user".
- `Shelly.Events` no longer reconnects forever against a dead token.
  Resetting the attempt counter in `handle_connect/2` made the cap
  unreachable whenever the handshake succeeded and the session was
  dropped immediately; the counter now clears only after a session has
  held for a minute.
- Token requests accept extra Req options via
  `config :shelly, :req_options` (the seam the new tests use).
- Docs: the module no longer describes the access token as long-lived.

## v0.1.0

Initial release, extracted from NordSwitch (nordswitch.eu) where the
OAuth/account/v2 paths and switch parsing run against a live mixed
Gen2/Pro/Gen4 fleet.

- `Shelly.OAuth` — authorization-code flow (server claims pinned to
  `https://*.shelly.cloud`), `to_account/1` bridge.
- `Shelly.Account` — Bearer-token account API: device list with
  per-channel expansion, whole-account status in one call,
  `parse_status/2`, switch control.
- `Shelly.CloudV2` — auth-key API: bulk status (≤10 ids),
  switch/cover/light control, `toggle_after` watchdog.
- `Shelly.CloudV1` — deprecated legacy endpoints (fallback).
- `Shelly.Events` — real-time websocket per account: handler callback,
  id normalization, jittered exponential reconnect with attempt cap,
  token-redacting logs.
- `Shelly.Status` — component-aware parser for Gen1–Gen4 payloads
  (switch/cover/light/CCT/RGB(W)/pm1/em/em1, flood, smoke, presence,
  temperature/humidity, voltmeter; Gen1 relays/lights/rollers/emeters
  and battery sensors), `metered`/`component` reporting,
  `has_component?/2` + `component_of/2` partial-delta guards, battery
  and sensor-temperature enrichment.
- `Shelly.RateGate` — per-account pacing (~1 req/s) with backlog cap
  (`{:error, :throttled}`) and key pruning.

Pre-publish review by a multi-model quorum (Gemini, Grok, Kimi, ZAI,
Vibe); findings incorporated.