BCP-47 locale supplied via HeatzyAPIConfig.locale, or
undefined when unset. Surfaced through HeatzyAPIAdapter
so facades render derogationEndString labels consistently with
the configured locale without a mutable global.
The configured BCP-47 locale tag, or undefined.
IANA timezone supplied via HeatzyAPIConfig.timezone, or
undefined when unset. Surfaced through HeatzyAPIAdapter
so derogation end dates anchor to the account timezone rather
than the host runtime timezone.
The configured IANA timezone identifier, or undefined.
Releases the auto-sync timer; the instance must not be reused after disposal.
Sign in with explicit credentials. Refused credentials come back as Gizwits HTTP 400 with error codes in the body. Successful return guarantees the registry reflects server state — the post-auth sync is enforced here.
Use resumeSession for a best-effort restore from persisted credentials that logs + swallows errors.
A rejected sign-in leaves the previously persisted credentials and session untouched: only server-accepted credentials reach the settings store.
Explicit username/password.
AuthenticationError when credentials are rejected.
ValidationError — or whatever the post-auth sync raises — when the sign-in succeeded but the registry could not be populated. The guarantee above is the reason: resolving here would report success over an empty registry.
Cancels any pending auto-sync timer; subsequent setSyncInterval or fetch calls re-arm it.
Fetch all bindings and their live attributes, sync the device registry, and schedule the next auto-sync. Failures are logged and swallowed (the next cycle retries); the returned list is empty on failure and no sync notification fires. An empty list is indistinguishable from an account with no bindings, so a caller that needs to know the registry is current must not use this entry point — authenticate enforces its sync instead.
The fetched /bindings entries.
Read the live attribute payload of a single device, Zod-validated.
Destructured options.
Device identifier (wire did).
The live attributes.
Post-construction lifecycle hook driven by create. Never rejects by design — probe and resume failures are swallowed and surfaced through the lifecycle events.
Two-branch template:
Whether a Gizwits user token has been issued.
true once authenticated.
Fetches the raw /bindings payload (validated against the
envelope schema) without touching the registry.
Every device bound to the account.
Low-level POST to /login. Prefer authenticate, which
adds the login backoff, persists the resulting token/expiry, and
is triggered automatically on an expired token.
Destructured options.
Login credentials (the verbatim wire body).
The raw login payload, Zod-validated.
Log out: the inverse of authenticate. Clears the persisted
session (token/expiry), the stored username/password and the
automatic-login backoff, stops the auto-sync timer, and empties
the registry — so isAuthenticated reads false and no
stale devices linger.
User-initiated, so unlike a rejected sign-in it neither arms the
backoff nor emits onAuthenticationLost. A subsequent
authenticate is the only way back in.
Notify any registered events.onSyncComplete observer that a
sync just landed. Routed through the lifecycle emitter so a
misbehaving callback cannot break the caller. Invoked by the
@syncDevices decorator after each decorated mutation.
SyncCallback-shaped payload (ids).
Best-effort session restore from persisted credentials.
Reads username/password from the SettingManager and signs
in. Unlike authenticate, failures are logged and
swallowed — the method never throws. Use this from lifecycle
hooks (init, auth retry, #ensureSession) where a stale or
missing persisted credential must not crash the caller.
On success, the registry is populated (delegates to authenticate).
true when a sign-in round-trip succeeded and the
instance is now authenticated; false for "no persisted
credentials" or "sign-in failed" (both indistinguishable by
the return value alone — check the logger / isAuthenticated
if the distinction matters).
Reschedules the auto-sync timer.
The timer is unref'd, so it never keeps the Node event loop alive
on its own — auto-sync still fires on cadence whenever the host
application has another reason to stay running (HTTP server, other
timers, open streams). Apps that must run indefinitely should
provide their own keep-alive rather than relying on this timer.
Cadence in minutes; pass false to disable.
Run the initial session restore, honoring the configured mode.
initialize() never rejects by design (probe and resume failures
are swallowed and surfaced through the lifecycle events), so the
background variant only needs the fire-and-forget form.
When true, the restore runs off
the caller's critical path and create() resolves immediately.
Send a control payload to a single device. The server's response body is empty by contract and is not consumed.
Destructured options.
Device identifier (wire did).
Named attributes, or the V1 raw triplet.
StaticcreateCreate and initialize a Heatzy API instance.
Post-construction, the initial session restore runs — in the
background when shouldResumeSessionInBackground is set. On
return, either the registry is populated or the instance is in a
documented empty state (no credentials, no persisted session);
check isAuthenticated to distinguish.
Optionalconfig: HeatzyAPIConfig
Optional configuration for the API client.
The initialized HeatzyAPI instance.
Heatzy (Gizwits) API client. Handles authentication, session persistence and restore, device syncing, and the
/bindings,/devdataand/controlendpoint calls. Uses a private constructor — create instances via HeatzyAPI.create.