Latest /context payload from the BFF, or null before the
first successful call. Populated by authenticate and
fetch; cleared on session invalidation.
The cached context, or null.
Whether the upstream rate-limit gate is currently holding a pause
window after a recent 429 Retry-After response.
true while the SDK is intentionally failing fast.
BCP-47 locale supplied via HomeAPIConfig.locale, or
undefined to fall back to the runtime locale. Drives chart label
formatting in the device facades.
The configured BCP-47 locale tag, or undefined.
IANA timezone supplied via HomeAPIConfig.timezone,
or undefined to fall back to UTC. The Home wire itself speaks
UTC wall-clock; this timezone only anchors chart windows and
label rendering in the device facades.
The configured IANA timezone identifier, or undefined.
Currently authenticated user, derived from the most recent
/context response. null when unauthenticated — and also when
the signed-in account has no home, which answers 404 and so
carries no identity to derive.
The user, or null.
Releases the auto-sync timer and any retry-guard window; the instance must not be reused after disposal.
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).
Explicit username/password.
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.
Sync check first; when it reads false, a NON-DESTRUCTIVE probe —
one registry sync, which exercises the persisted session without
touching it — and only if that still leaves us unauthenticated, the
best-effort resumeSession fallback. The order matters:
resumeSession runs a full sign-in, which spends a real login
attempt (server-side throttle counters, the local backoff on a
rejection) and replaces a session that may have been merely
unexercised (a boot-time context fetch that lost the network reads
unauthenticated while a perfectly valid refresh token sits in
storage).
Every rung reads the RECORDED verdict, not the bare session: a
stored credential the server has definitively refused (see
resumeSession) answers false here even while
isAuthenticated() still reads true over a session the refusal
deliberately did not clear — only an ACCEPTED sign-in restores the
true answer.
true when a session is usable afterwards.
Fetch all buildings (owned + guest), sync the device registry,
and schedule the next auto-sync — the same heartbeat contract as
the Classic fetch().
All buildings or an empty array on failure.
Fetch the internal-temperatures report (flow/return/tank/zone) for an ATW unit. Same Result contract as getEnergy.
Device id.
Query window.
ISO start timestamp (inclusive).
Aggregation period (e.g. Daily, Hourly).
ISO end timestamp (exclusive).
Success with the report datasets, or a typed failure.
Fetch energy telemetry for a unit; the registry model's connection
type selects the measure family — ATA's single cumulative
consumption counter, or ATW's interval consumed/produced measures
(kWh per bucket, live-probed 2026-07-17). Returns a Result
so callers can branch on the failure class (validation for shape
drift, server for 4xx/5xx, unauthorized for token rejection,
rate-limited, network).
Device id.
Query window.
ISO start timestamp (inclusive).
Aggregation interval (Minute, Hour, Day, Week or Month).
Optionalmeasure?: "consumed" | "produced"Energy direction ('consumed' or
'produced'); ATW only, where it defaults to 'consumed' — the
ATA counter is consumption by definition.
ISO end timestamp (exclusive).
A measure passed for an ATA id is ignored — the ATA counter is
consumption by definition. An id the registry does not hold folds
into the not-found Result variant (the Result contract never
throws for it — a cold open may query before the first fetch).
Success with the telemetry bundle, or a typed failure.
Fetch the error-log entries for a unit; the registry model's connection type selects the unit path. Same Result contract as getEnergy.
Device id.
An unknown id folds into the not-found Result variant.
Success with the entries (possibly empty), or a typed failure.
Device id.
Query window.
ISO start timestamp (inclusive).
ISO end timestamp (exclusive).
Success with the telemetry bundle, or a typed failure.
Fetch the temperature report for a unit; the registry model's connection type selects the endpoint — ATA's trend summary or ATW's comfort graph (outside / room / set temperature). Same Result contract as getEnergy.
Device id.
Query window.
ISO start timestamp (inclusive).
Aggregation period (e.g. hour, day).
ISO end timestamp (exclusive).
An unknown id folds into the not-found Result variant.
Success with the report datasets, or a typed failure.
Refresh the user by fetching the /context identity. On failure
the last known user is returned unchanged: transient failures and
device-payload drift must not read as "logged out" — the
reactive-401 path (reauthenticate()) is the single owner of
clearing the authentication state, so a definitive rejection has
already nulled the user by the time the failure surfaces here.
A 404 is the one answer that is neither: the account has no
home, so this settles the no-home state — null user, empty
registry — rather than returning the last known one.
The user or null.
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:
tryReuseSession — if the subclass can reuse a persisted
session (and populate the registry in the process), we are
done.Callers should check isAuthenticated after create()
returns if they need to distinguish "empty state" from "ready".
Whether the session is usable: true once /context resolved a
user identity, and also for an account the BFF accepted but that
has no MELCloud Home home — there user and context
stay null, so an authenticated client is NOT a promise of an
identity.
true while the session can serve requests.
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.
Notify any registered events.onSyncComplete observer that a
sync just landed. Routed through the lifecycle emitter so a
misbehaving callback cannot break the caller.
SyncCallback-shaped payload.
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).
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.
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.
OptionalshouldResumeInBackground: boolean
When true, the restore runs off
the caller's critical path and create() resolves immediately.
Batch frost-protection write for a set of devices (grouped by type in
postData.units), then refresh /context. One request scopes to a
single account's devices.
Bounds, on/off flag, and target device ids.
Batch holiday-mode write for a set of devices (grouped by type in
postData.units), then refresh /context. Mirror of
updateFrostProtection; only the window fields and path differ.
Window bounds, on/off flag, and target device ids.
Batch overheat-protection write for a set of ATA devices, then
refresh /context. Mirror of updateFrostProtection; the
feature is ATA-only (live-captured 2026-07-27: the official app
posts units.ATA exclusively).
Bounds, on/off flag, and target ATA device ids.
Send a unit setpoint update to the BFF; the registry model's
connection type selects the wire path. On success, re-sync the
registry so it reflects the server-side effect of the write (the
PUT response itself does not echo device fields). On failure, the
typed transport error propagates and the sync is skipped — the
server state is presumed unchanged, so a re-fetch would be wasted
work. The mutation + post-sync orchestration lives in
putAndSync, where @fetchDevices({ refresh, when: 'after' })
applies the same post-mutation-refresh contract as Classic facades
— the refresh here being syncRegistry() instead of api.fetch().
Target device id.
Partial setpoint payload matching the unit's connection type — the shape is the caller's contract: the BFF binder silently drops keys the routed unit does not know.
StaticcreateCreate and initialize a MELCloud Home API instance.
Delegates post-construction setup to BaseAPI.initialize so the #1281-class invariant is enforced uniformly: the reuse path, the fresh-auth path, and the "no credentials" path all go through the same template and cannot leave the registry empty while claiming success.
Optionalconfig: HomeAPIConfig
Optional configuration.
The initialized HomeAPI instance.
MELCloud Home API client using the mobile BFF at
mobile.bff.melcloudhome.comwith Bearer-token authentication.Authenticates via a headless OIDC flow: PAR → IdentityServer → AWS Cognito → token exchange.
Access and refresh tokens are persisted through the SettingManager (analogous to the Classic API's
contextKey).Uses a private constructor — create instances via HomeAPI.create.