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

    @olivierzal/heatzy-api

    A typed Node.js client for the Heatzy (Gizwits) API, providing access to Heatzy pilot-wire modules and connected radiators — Pilote (V1/V2/V4), Glow, Onyx, Shine and Pro.

    License Node GitHub release CI CodeQL

    Quality Gate Test coverage Docs coverage

    • Strongly typed — full TypeScript types for the Gizwits wire format, with 100% TSDoc coverage on the public surface.
    • Every generation supported — Pilote V1's positional raw triplet, V2/V4 derogations, Glow's split temperature registers (incl. Onyx and Shine), and Pro's measures, open-window detection and presence mode — behind one facade family.
    • Resilient by default — auto-retry on transient failures, pre-emptive session refresh, and reactive re-login on Gizwits's 400-coded token expiry.
    • Validated boundaries — Zod schemas guard every consumed payload, so upstream shape drift surfaces as a typed ValidationError instead of a deep undefined crash. Per device, though: one radiator the SDK cannot read never costs you the other rooms, nor the sign-in.
    • Registry + facades — an identity-preserving device registry with product-aware facades (supportsV2 / supportsGlow / supportsPro narrowing).
    • Tree-shakable — ESM only, sideEffects: false.
    • Node.js >= 22.20.0
    • A valid Heatzy account
    • For installing the package: a GitHub personal access token with the read:packages scope
    Important

    This package is published to GitHub Packages, not the public npm registry.

    Configure your project so npm fetches the @olivierzal scope from GitHub:

    //npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
    @olivierzal:registry=https://npm.pkg.github.com

    NODE_AUTH_TOKEN must be a GitHub personal access token with the read:packages scope (export it in your shell or set it in your CI environment). Then:

    npm install @olivierzal/heatzy-api
    
    import { FacadeManager, HeatzyAPI, supportsGlow } from '@olivierzal/heatzy-api'

    const api = await HeatzyAPI.create({
    username: 'user@example.com',
    password: 'password',
    })

    const manager = new FacadeManager(api)

    // Interact with a device through its facade
    for (const device of api.registry.getDevices()) {
    const facade = manager.get(device)
    console.log(facade.name, facade.mode, facade.isOn)
    if (supportsGlow(facade)) {
    console.log(facade.currentTemperature, facade.comfortTemperature)
    }
    }

    The client keeps its session alive without caller involvement:

    • Pre-emptive refresh — the Gizwits token is renewed when it comes within 5 minutes of expiry, so no request pays the re-authentication round-trip on its critical path.
    • Reactive recovery — Gizwits reports an invalid or expired token as HTTP 400 (not 401); the SDK re-authenticates once from persisted credentials and replays the original request. A cooldown guard prevents retry loops.
    • Persistence — pass a settingManager (a simple get/set string store) to persist the token and credentials across restarts; without one, everything stays in memory and a new instance signs in from scratch.
    Important

    The SettingManager receives the user token and the account password as plain strings. You are responsible for backing it with secure storage (encrypted settings store, OS keychain, …) — do not write it to a world-readable file. The SDK redacts credentials from everything it emits: its own log output, and the request/response snapshot carried by a thrown HttpError — the X-Gizwits-User-token header, the /login body's username and password, query parameters, and the response's headers and body alike — so an error object handed to a host logger, or pasted into a diagnostic report, carries no secret. The same engine blanks the user-entered field this SDK reads — dev_alias, the device name its owner typed — in every dump and snapshot, so a pasted report names a device by its did and product only.

    const settings = new Map<string, string>()
    const api = await HeatzyAPI.create({
    settingManager: {
    get: (key) => settings.get(key) ?? null,
    set: (key, value) => settings.set(key, value),
    },
    })

    The registry cycle is /bindings plus one /devdata read per binding, and it degrades per device rather than as a block — a radiator this SDK cannot model must never deny you the account, least of all through the sign-in, whose registry sync is enforced.

    • A /bindings entry whose shape does not validate, or whose product_key this release predates, is dropped at the listing boundary. list() and fetch() answer what survived.
    • A device whose /devdata read fails — a transient 5xx or network failure that outlived the retry rung, a payload whose required mode names a label this SDK cannot map — keeps the model it already had (stale data beats no data) and is skipped when it has never been seen. Its binding stays in the returned list, so the next cycle reads it again.
    • A read value outside the vocabulary this SDK knows is NOT a failure: /devdata is checked for its wire types only, and the facades answer null for a cur_mode or a derog_mode they do not model. Every spelling Heatzy publishes for a mode it reports is translated to the one this SDK writes: the V1 Pilote's Chinese labels, and the off the vendor's 2020 document lists where its 2018 one spells stop. A switch is read in any of its three declared forms — 0/1, bool, or the off/on labels of an enum-declared datapoint — and written as 0/1. On a Pro, currentSignal reads the pilot-wire order the module is sending right now, which its own regulation can change under one commanded mode.

    Nothing is dropped quietly, and nothing storms your logger: a listing drop and a skipped /devdata read are each reported as a streak — one logger.error line when it starts (the listing's names every dropped device and its verdict; the device read's spells the failure and its causes on that same line, with no stack — the failing paths and the values received for a refused payload, the status for a refused request, the transport's own code for a failed connection), again when its reason changes (the failing paths for a refused payload, not the values received) and at most every five minutes while it stands, then one logger.log line when it recovers — the same streaks the request pipeline keeps for its own subjects (@olivierzal/api-core's FailureStreaks). While a device's streak is open, the pipeline's lines for that device's read are held back — its five-minute reminder, and its opening line if the device was already streaked for a refused payload; the pipeline's opening line when it opens the episode, and its recovery line, still appear. A failed round-trip still reaches the onRequestError lifecycle event. To detect a partial cycle programmatically, compare what fetch() returned against the registry:

    const bindings = await api.fetch()
    const missing = bindings.filter(
    ({ did }) => api.registry.devices.getById(did) === undefined,
    )

    Only a failure no partial answer can survive — a refused /bindings call, or an envelope that is not a device list — fails the whole cycle, and authenticate() still rejects on those.

    The request pipeline applies two policies, outermost first:

    1. Auth retry (HTTP 400/401) — a single re-authentication + replay, as described above.
    2. Transient retry (reads only) — a 500/502/503/504 response, a failed connection (DNS, connect timeout, reset, TLS — undici's fetch failed) or a request timeout is retried up to 4 times with exponential backoff and jitter (1 s initial delay, 16 s cap). Both validated reads, /bindings and /devdata, travel over GET; /control, the one POST, is a write and is never retried automatically: a write that may have landed server-side must not be silently duplicated. A caller's own abort is not retried either. Each retry is observable through the onRequestRetry lifecycle event.

    A failure the SDK has a class for — an HttpError, the APIError family (AuthenticationError, ValidationError, a RegistrySyncError judged by what it wraps) or a transport failure — is logged as one line naming its cause chain, with no stack: Session resume failed: AuthenticationError: Heatzy rejected the credentials — caused by HttpError: Status 400, Failed to fetch devices: TypeError: fetch failed — caused by ConnectTimeoutError: Connect Timeout Error (UND_ERR_CONNECT_TIMEOUT), and the device streak line above. A programming error keeps its stack, which is the one thing that locates it.

    The three helpers behind that form are this package's exports too — logFailure(logger, label, error), isKnownFailure(error) and failureCauseChain(error) — so a consumer's own cloud-failure lines take the same shape through its one SDK dependency, without depending on @olivierzal/api-core itself: logFailure(this, 'Write failed:', error) prints Write failed: HttpError: Request failed with status code 503 for a refused request whose body carries no reason (Gizwits's own detail_message or error_message stands in for the status line where it does), and the error object, stack included, for a programming error. The Logger type the first argument takes is exported alongside.

    The transport itself is configurable through transport: pass a pre-built HttpClient (the seam the test suites use to script responses), or { timeoutMs } to change the 30 s per-request timeout (0 disables it — not recommended). Omit it for the fetch-backed default.

    Full API reference at https://olivierzal.github.io/heatzy-api/.

    See CONTRIBUTING.md.

    For vulnerability reports, see SECURITY.md.

    See CHANGELOG.md.

    Caution

    This API is not endorsed, verified or approved by Heatzy or Gizwits. Heatzy cannot be held liable for any claims or damages that may occur when using this client to control Heatzy devices.

    MIT © Olivier Zalmanski