Heatzy API for Node.js - v21.3.1
    Preparing search index...

      Heatzy API for Node.js - v21.3.1

      HeatzyAPI

      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, /devdata and /control endpoint calls. Uses a private constructor — create instances via HeatzyAPI.create.

      DeviceFacade

      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.

      DeviceGlowFacade

      Facade for Glow products (incl. Onyx and Shine): split high/low temperature registers, a dedicated on/off switch, and a temperature compensation offset.

      DeviceProFacade

      Facade for Pro products: single-register temperatures, humidity and reported-mode measures, open-window detection, and the presence derogation.

      DeviceV2Facade

      Facade for V2/V4 products: named-attribute control, derogations (boost, vacation), timer and lock switches.

      FacadeManager

      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.

      DeviceFacadeAny

      Union of every facade generation FacadeManager.get can return. Narrow with supportsV2, supportsGlow and supportsPro before reading generation-specific members.

      supportsGlow

      Whether the facade's product generation carries the Glow surface (split temperature registers, on/off switch, compensation).

      supportsPro

      Whether the facade's product generation carries the Pro surface (measures, open-window detection, presence).

      supportsV2

      Whether the facade's product generation carries the V2 surface (named-attribute control, derogations, timer, lock).

      Device

      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.

      DeviceRegistry

      Central in-memory registry of all bound Heatzy devices. Synced from the /bindings + /devdata responses and queryable by id.

      PreviousMode

      The last non-stop heating mode — what "back on" restores to.

      syncDevice

      Refresh a registry model in place from a fresh /bindings entry and its live attributes; preserves the instance so facade references stay valid.

      APIError

      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.

      AttributeNotFoundError

      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.

      AuthenticationError

      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.

      EntityNotFoundError

      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.

      RegistrySyncError

      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.

      ValidationError

      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.

      failureCauseChain

      A failure and its causes on one line, outermost first —

      isAPIError

      User-defined type guard for APIError and its subclasses.

      isKnownFailure

      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.

      logFailure

      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.

      HeatzyAPIAdapter

      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.

      HeatzyAPIConfig

      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).

      HeatzyAPISettings

      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

      Logger interface for API call tracing.

      RequestCompleteEvent

      Emitted when a request (possibly after retries) completes successfully.

      RequestErrorEvent

      Emitted when a request ultimately fails after exhausting its retries.

      RequestLifecycleContext

      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.

      RequestRetryEvent

      Emitted each time a retry attempt is scheduled.

      SettingManager

      External storage adapter for persisting API session settings.

      LifecycleEvents

      Callback bundle invoked around SDK lifecycle moments — the core's LifecycleEvents instantiated with this SDK's SyncParams. All callbacks are optional and non-throwing.

      RequestStartEvent

      Emitted at the start of a request, before any retry attempts.

      SyncCallback

      Callback invoked after sync operations — the core's SyncCallback instantiated with this SDK's SyncParams.

      TransportConfig

      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.

      setting

      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.

      syncDevices

      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.

      updateDevice

      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.

      HttpClient

      Thin fetch-based HTTP client used internally by the SDK — the core transport with the Gizwits redaction vocabulary and failure reader pre-seated.

      HttpError

      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.

      HttpErrorRequestConfig

      Snapshot of the request that triggered an HttpError. Any value naming a secret — header, body field or query parameter — reads as ******.

      HttpRequestConfig

      Configuration accepted by HttpClient.request: body (data), query (params), per-request headers, method, abort signal and URL.

      HttpResponse

      Minimal response shape surfaced to callers.

      HttpClientConfig

      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.

      isHttpError

      Type guard for HTTP errors thrown by the internal HTTP client.

      Attributes

      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

      /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.

      ControlAttributes

      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.

      DeviceBinding

      One /bindings entry — the wire identity of a bound device.

      DeviceData

      /devdata/{did}/latest response envelope.

      DevicePostData

      /control/{did} body for every product generation but V1.

      DeviceV1PostData

      /control/{did} body for V1 products, which speak a positional raw triplet instead of named attributes: two constant fillers, then the positional mode.

      LoginCredentials

      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.

      LoginData

      /login response: the user token and its expiry (epoch seconds).

      PostAttributes

      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.

      DevicePostDataAny

      Union of both /control/{did} body dialects.

      UndefinedTolerant

      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.

      getTargetTemperature

      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.

      CommonDerogationMode

      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.

      DerogationMode

      Derogation (temporary override) modes.

      Mode

      Heating modes. cft1/cft2 do not exist on V1 and V2 products.

      Product

      Product generations, ordered so >= reads as capability support.

      Switch

      Numeric boolean the wire uses for every switch attribute.

      TemperatureCompensation

      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.

      DerogationMode

      Derogation (temporary override) modes.

      Mode

      Heating modes. cft1/cft2 do not exist on V1 and V2 products.

      Product

      Product generations, ordered so >= reads as capability support.

      Switch

      Numeric boolean the wire uses for every switch attribute.

      TemperatureCompensation

      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.

      getProduct

      Resolve a device's product generation from its product_key.

      isModelledProduct

      Whether a product_key names a generation this SDK models — the question getProduct answers by throwing.

      Temporal
      HttpStatus

      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).