Behavioral wrapper around a registry Device for first-generation (V1) products, which only expose the heating mode. Subclasses layer the richer generations on top. Obtain instances through FacadeManager.get — facades are cached per entity.
Facade for Glow products (incl. Onyx and Shine): split high/low temperature registers, a dedicated on/off switch, and a temperature compensation offset.
Facade for Pro products: single-register temperatures, humidity and reported-mode measures, open-window detection, and the presence derogation.
Facade for V2/V4 products: named-attribute control, derogations (boost, vacation), timer and lock switches.
Lazily creates and caches facade instances using a WeakMap keyed by entity reference. Ensures each registry entity maps to exactly one facade throughout its lifetime.
Union of every facade generation FacadeManager.get can return. Narrow with supportsV2, supportsGlow and supportsPro before reading generation-specific members.
Whether the facade's product generation carries the Glow surface (split temperature registers, on/off switch, compensation).
Whether the facade's product generation carries the Pro surface (measures, open-window detection, presence).
Whether the facade's product generation carries the V2 surface (named-attribute control, derogations, timer, lock).
In-memory model of one bound Heatzy device: wire identity, the last-synced attribute payload, and the derived state the wire does not carry (previous mode, derogation end date). Instances are created and updated exclusively by DeviceRegistry.syncDevices, which preserves object identity across syncs.
Central in-memory registry of all bound Heatzy devices. Synced from
the /bindings + /devdata responses and queryable by id.
The last non-stop heating mode — what "back on" restores to.
Refresh a registry model in place from a fresh /bindings entry and
its live attributes; preserves the instance so facade references
stay valid.
Base class for all errors thrown by the SDK family. Each consuming SDK's protocol errors extend this one class, so a host can catch the whole hierarchy through isAPIError whatever wire it talks to.
Thrown when a facade reads an attribute its device's last-synced
payload does not carry — either the product generation does not
support it (narrow with supportsV2 / supportsGlow / supportsPro
before reading) or the wire dropped a field the SDK consumes.
The server rejected the credentials, the login response could not be parsed, or the reactive re-authentication that followed an auth-failure status failed in turn.
Thrown when a facade resolves its underlying registry device by id and finds nothing — the registry was rebuilt (a re-login, a sign-out, or a sync that pruned the device) and no entry exists under that id any more.
The sign-in round-trip was ACCEPTED but the enforced post-auth
registry sync failed: the session is established and the credentials
persisted, yet the registry could not be verified against the
server. Thrown by authenticate() with the sync's own failure (a
validation rejection, a transport error, any registry error)
preserved as cause, so consumers can tell "signed in, stale list"
from a refused credential BY TYPE instead of re-deriving the verdict
from isAuthenticated() — a discriminator with a real false
positive: a transport failure during a sign-in over a PRE-EXISTING
live session (a user switching accounts) reads "signed in" while the
new pair was never accepted. A refused credential is never wrapped
in this type: it stays AuthenticationError.
Thrown when a runtime validator rejects an upstream payload. The
consuming SDKs construct it at their zod boundaries (parseOrThrow,
which stays in each SDK); the class itself names no validator — the
validator's own error, typically a ZodError, rides the standard
cause chain as unknown. The context field surfaces which
boundary the payload came from (an endpoint or flow label such as
'login' or 'BFF /context') so consumer dashboards can group drift
alerts without parsing the message string.
A failure and its causes on one line, outermost first —
User-defined type guard for APIError and its subclasses.
Whether a failure is one this package has a class for — an
HttpError, one of the APIError family, or a transport
failure (undici's fetch failed, the client's TimeoutError, a
caller's AbortError) — anywhere in its cause chain. Such a failure
is an expected condition of the wire, and its stack names only the
transport and this package; anything else is a programming error,
whose stack is the one thing that locates it. A wrapper is judged by
what it wraps: a RegistrySyncError carries whatever the
enforced sync threw, and an HttpError with a cause carries its
reader's own failure, so neither counts on its own.
Write a failure to the log the way a diagnostic report can read it: a known failure as ONE line — the label, then its failureCauseChain — with no stack, since a transient's ten transport frames read as a crash in a report; anything else as the label followed by the error object, so a programming error keeps the stack that locates it.
The API surface facades depend on — a structural slice of
HeatzyAPI that keeps the facade layer decoupled from the
client's lifecycle machinery (and trivially mockable in tests). It
names exactly what a facade reads — the display locale, the sync
notification and the two device endpoints — and nothing a facade
does not: HeatzyAPI.fetch and HeatzyAPI.timezone stay public
on the client alone, the timezone reaching every Device through
the DeviceRegistry at construction.
Configuration accepted by HeatzyAPI.create: the core's
session surface (SessionAPIConfig — logger, settingManager,
and the members re-declared below to carry this dialect's own
guidance) plus the Gizwits dialect's own. Every property — including
the inherited LoginCredentials pair — may be absent or
explicitly undefined, interchangeably: the runtime applies the
same default either way (credentials can also arrive later via
authenticate or the SettingManager).
Persisted-settings surface the SDK reads and writes through the SettingManager. Hosts that render or migrate stored values can type their storage against this shape.
Logger interface for API call tracing.
Emitted when a request (possibly after retries) completes successfully.
Emitted when a request ultimately fails after exhausting its retries.
Identifies a single logical request across its lifecycle events.
Generated client-side via crypto.randomUUID() when each request
starts, so consumers can correlate a onRequestStart with its
eventual onRequestComplete or onRequestError — including across
retry attempts, which share the same correlationId.
Emitted each time a retry attempt is scheduled.
External storage adapter for persisting API session settings.
Callback bundle invoked around SDK lifecycle moments — the core's
LifecycleEvents instantiated with this SDK's SyncParams. All
callbacks are optional and non-throwing.
Emitted at the start of a request, before any retry attempts.
Callback invoked after sync operations — the core's SyncCallback
instantiated with this SDK's SyncParams.
Transport configuration. Discriminated by presence of an
HttpClient instance — the SDK either reuses your wired client
(with its own dispatcher, headers, timeout) or builds a fetch-backed
default whose timeout you can tweak via timeoutMs.
Accessor decorator that delegates storage to an external SettingManager
(e.g. persistent settings), falling back to the in-memory field when none
is configured. The setting key is resolved once at decoration time rather
than on every get/set.
Method decorator factory that invokes the host's sync notification
after the decorated method resolves, forwarding params verbatim.
Generic over the consumer's sync-params shape (device ids, a type
filter…) like SessionAPI itself: @syncDevices({ type }) forwards
a payload, @syncDevices() notifies without one. The host contract
is structural: the returned method's this names it, which types the
body and any .call(host) use, but a TC39 application site does not
check it — the method's own type carries no this — so it is
documented, not enforced, as it was in the SDKs' own copies. No
action is taken when the host exposes no hook.
Method decorator that merges the decorated method's resolved payload
into the host's in-memory model before returning it — so a
mutation echo (setValues) or a fresh read (values) immediately
refreshes the registry entity without waiting for the next sync.
Thin fetch-based HTTP client used internally by the SDK — the core transport with the Gizwits redaction vocabulary and failure reader pre-seated.
Thrown by HttpClient whenever an upstream response has a non-2xx
status. The shape mirrors what downstream code needs: response.status,
response.headers, and response.data.
Snapshot of the request that triggered an HttpError. Any
value naming a secret — header, body field or query parameter —
reads as ******.
Configuration accepted by HttpClient.request: body (data),
query (params), per-request headers, method, abort signal and URL.
Minimal response shape surfaced to callers.
Construction options for HttpClient. Neither the redaction engine nor the failure reader is configurable here: this SDK's vocabulary is seated by the subclass, so a transport cannot be built without it.
Type guard for HTTP errors thrown by the internal HTTP client.
Live attribute payload returned by /devdata/{did}/latest. Extends
the writable set with the read-only measures; field names mirror the
Gizwits wire verbatim (cur_tempH, cft_temp…) — do not rename
them to satisfy style rules.
/bindings response envelope, as it comes off the wire: a device
LIST whose entries are still unknown. They are validated one by one
at the listing boundary (HeatzyAPI.list, which answers
DeviceBindings) rather than atomically inside the array, so
one entry this SDK cannot model never invalidates its siblings.
Everything /control/{did} itself accepts — PostAttributes
plus the presence detection only the Pilote Pro owns. It is the
TRANSPORT's shape, not an invitation: a consumer writes through a
facade, and only DeviceProFacade widens its setValues to this.
One /bindings entry — the wire identity of a bound device.
/devdata/{did}/latest response envelope.
/control/{did} body for every product generation but V1.
/control/{did} body for V1 products, which speak a positional
raw triplet instead of named attributes: two constant fillers,
then the positional mode.
The username/password pair a session mechanism signs in with. Every consuming SDK's login takes exactly this shape; a protocol that also posts it verbatim as its login body (Gizwits does) keeps that fact — and any extra wire field — in its own types.
/login response: the user token and its expiry (epoch seconds).
What EVERY product accepts as a write. Availability is
product-dependent — the comments group fields by the generations
that support them — and one field is narrowed rather than
commented: derog_mode carries CommonDerogationMode, the
three derogations the vendor documents on every generation. The
presence detection is the Pilote Pro's own capability and is offered
where it belongs, on DeviceProFacade.setValues, which takes the
wider ControlAttributes.
Union of both /control/{did} body dialects.
Optional form of T whose properties may also be explicitly
undefined — the input-side counterpart of Partial<T> under
exactOptionalPropertyTypes (whose mapped ? does not admit a
present-undefined key). For inputs whose runtime treats a
present-undefined key exactly like an absent one.
Build the control attributes that set a target temperature, in the
register layout the product generation expects: Glow clamps the
value into the mode's accepted range — symmetric with the read
side — and splits it across tempH/tempL (hundreds bit +
remainder in tenths); every other generation takes a single temp
register in tenths, unclamped.
The derogations EVERY product with a derogation register accepts.
The vendor documents derog_mode as Enum (0-2) — no derogation,
vacation, boost — on the Pilote modules AND on the Glow family, and
as Enum (0-3) on the Pilote Pro alone, whose sensor adds the
presence detection. Presence is therefore the Pro's own capability,
and DeviceProFacade is the only place this SDK offers it.
Derogation (temporary override) modes.
Heating modes. cft1/cft2 do not exist on V1 and V2 products.
Product generations, ordered so >= reads as capability support.
Numeric boolean the wire uses for every switch attribute.
Named anchors of the com_temp sensor calibration on the Pro: a
0–100 register in tenths of a degree centred on 50 (no change), so
0 is −5 °C and 100 is +5 °C. They are anchors, not the vocabulary:
any value in between is a valid calibration, and the Glow family
declares the register over 0–255. Read com_temp as a number.
Derogation (temporary override) modes.
Heating modes. cft1/cft2 do not exist on V1 and V2 products.
Product generations, ordered so >= reads as capability support.
Numeric boolean the wire uses for every switch attribute.
Named anchors of the com_temp sensor calibration on the Pro: a
0–100 register in tenths of a degree centred on 50 (no change), so
0 is −5 °C and 100 is +5 °C. They are anchors, not the vocabulary:
any value in between is a valid calibration, and the Glow family
declares the register over 0–255. Read com_temp as a number.
Resolve a device's product generation from its product_key.
Whether a product_key names a generation this SDK models — the
question getProduct answers by throwing.
HTTP status codes used across the SDK family. Single source so
callers don't redefine them per file (HTTP_STATUS_UNAUTHORIZED was
declared in three places before this module existed).
Heatzy (Gizwits) API client: the core's
SessionAPI— which owns the session lifecycle, the login backoff, the request pipeline and the sync-cycle template — instantiated with the Gizwits dialect behind its hooks: how to sign in, which header carries the user token, what "persisted session" means, how the registry is refreshed. Handles the/bindings,/devdataand/controlendpoint calls. Uses a private constructor — create instances via HeatzyAPI.create.