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

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

    Hierarchy

    • SessionAPI<SyncParams>
      • HeatzyAPI

    Implements

    Index
    logger: Logger
    settingManager?: SettingManager
    • get timezone(): string | undefined

      IANA timezone supplied via HeatzyAPIConfig.timezone, or undefined when unset. The value is seated into every Device through the DeviceRegistry at construction, which is what anchors derogation end dates to the account timezone rather than the host runtime timezone; this getter only reads the configured value back.

      Returns string | undefined

      The configured IANA timezone identifier, or undefined.

    • Releases the auto-sync timer and any retry-guard window; the instance must not be reused after disposal.

      Returns void

    • Sign in with explicit credentials. The server refuses them in protocol-specific ways, which the subclass's doAuthenticate hook normalises into AuthenticationError. Successful return guarantees the registry reflects server state — the post-auth sync is enforced here so subclasses cannot forget it.

      Use resumeSession for a best-effort restore from persisted credentials that logs + swallows errors.

      Credentials are persisted only once the server accepts them: a rejected attempt leaves the stored pair and any live session untouched (the backoff still arms and the error still surfaces).

      Parameters

      Returns Promise<void>

      AuthenticationError when the server refuses the credentials.

      RegistrySyncError when the enforced post-auth sync fails — the sync's own failure (a validation rejection, a transport failure, any registry error) rides its cause. The credential check happened FIRST, so the session is left signed in and the credentials persisted: this rejection says "signed in, but the registry could not be verified", never "sign-in refused". The dedicated type is what lets callers branch on that difference without re-deriving it from isAuthenticated() — a discriminator that misreads a transport blip during an account switch over a pre-existing live session as "signed in, stale list".

    • Cancels any pending auto-sync timer; subsequent setSyncInterval or sync calls re-arm it.

      Returns void

    • 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 list is the ledger of what this cycle modelled: an entry list dropped is absent from it, and a device whose live attributes failed to read is present here while registry.devices.getById answers undefined (never seen) or a model still carrying its previous data (seen before). Both leave a log line, both are retried by the next cycle.

      Returns Promise<readonly DeviceBinding[]>

      The /bindings entries this SDK models.

    • Resolve a device against the live registry by its Gizwits id — the lookup facades bind through, so a registry rebuild cannot strand a cached facade over a detached entity.

      Parameters

      • id: string

        Gizwits device id (did).

      Returns Device | undefined

      The registry device, or undefined when none answers to that id.

    • Read the live attribute payload of a single device, Zod-validated.

      Parameters

      • root0: { id: string }

        Destructured options.

        • id: string

          Device identifier (wire did).

      Returns Promise<Attributes>

      The live attributes.

    • Post-construction lifecycle hook. Every subclass create() factory must delegate to this method — it is the sole path that guarantees the invariant at instance-creation time: a successful return leaves the registry populated whenever credentials or a persisted session are available.

      Two-branch template:

      1. tryReuseSession — if the subclass can reuse a persisted session (and populate the registry in the process), we are done.
      2. Otherwise, resumeSession runs — best-effort restore from persisted credentials. Does nothing (silently) if no credentials are persisted, so the "no creds + no session" case falls through to a documented empty state.

      Callers should check isAuthenticated after create() returns if they need to distinguish "empty state" from "ready".

      Returns Promise<void>

    • Whether a Gizwits user token has been issued.

      Returns boolean

      true once authenticated.

    • Fetches the /bindings payload without touching the registry, and keeps the entries this SDK can model.

      The envelope is validated as a whole — a body that is not a device list stays a hard ValidationError — but the entries are validated ONE BY ONE: this call opens the registry cycle, and the post-auth cycle propagates, so an atomic array would let a single unreadable entry read as "cannot sign in at all". The drops are reported as ONE aggregated line per cycle naming every dropped entry with its verdict, because a wire regression and a Heatzy product newer than this SDK call for opposite answers and must stay distinguishable in the diagnostic reports users paste into issues — while a listing-wide regression must not storm the host logger exactly when that report most needs to stay readable.

      Returns Promise<readonly DeviceBinding[]>

      Every device bound to the account that this SDK models.

    • Log out: the inverse of authenticate. Clears the persisted session, 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.

      Returns void

    • Notify any registered events.onSyncComplete observer that a sync just landed. Routed through the lifecycle emitter so a misbehaving callback cannot break the caller.

      Parameters

      • ...args: [params?: SyncParams]

        SyncCallback-shaped payload.

      Returns Promise<void>

    • 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. That covers the enforced post-auth sync too: authenticate surfaces what enforceRegistrySync raises as a RegistrySyncError, and this method catches it like any other rejection rather than letting a registry failure reach a lifecycle caller. Use it from lifecycle hooks (init, auth retry, ensureSession) where a stale or missing persisted credential must not crash the caller.

      SINGLE-FLIGHT: concurrent calls share one attempt — the lifecycle paths that race at boot (a background initialize, the first request's ensureSession, a reactive auth failure) collapse onto ONE sign-in round-trip, and every caller's verdict describes that shared attempt. Without the memo, two callers could both pass the login-backoff gate before either refusal armed it, spending two sign-ins against an upstream whose measured throttle threshold was four in seventy seconds.

      A refusal it swallows is also RECORDED (a definitive rejection only — never a throttle or a transport failure): the stored session stays untouched, but the sync-cycle epilogue stops reading it as signed-in until a sign-in is accepted again.

      On success, the registry is populated (delegates to authenticate).

      Returns Promise<boolean>

      true when the sign-in round-trip was ACCEPTED — including one whose enforced post-auth sync then failed, because the session it established stands; false for "no persisted credentials", "sign-ins are backed off" and "the server refused the credentials" (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.

      Parameters

      • minutes: number | false

        Cadence in minutes; pass false to disable.

      Returns void

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

      Parameters

      • OptionalshouldResumeInBackground: boolean

        When true, the restore runs off the caller's critical path and create() resolves immediately.

      Returns Promise<void>

    • Create 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.

      Parameters

      • Optionalconfig: HeatzyAPIConfig

        Optional configuration for the API client.

      Returns Promise<HeatzyAPI>

      The initialized HeatzyAPI instance.