MELCloud Home API client using the mobile BFF at
mobile.bff.melcloudhome.com with Bearer-token authentication.
Lazily creates and caches facade instances using a WeakMap keyed by model reference. Ensures each model instance maps to exactly one facade throughout its lifetime.
Shared scaffolding for every Home device facade. Holds the API
client + registry-resident model, exposes the common identity
getters (id, name, rssi) and the cross-type getSignal
passthrough, and provides the protected setting() lookup used by
both the ATA and ATW facade subclasses.
Facade for one /context building's ATA devices — the account-level
group. MELCloud Home has no group endpoint, so the group contract is
emulated over the members: reads aggregate the devices' states (fields
where members diverge fold to null, the wire's mixed marker) and
writes fan out to every member.
Facade for a MELCloud Home ATA device. Provides typed access to device settings and per-mode temperature clamping before forwarding updates to the BFF.
Facade for a MELCloud Home ATW (air-to-water) device. Provides
typed access to zone setpoints, tank temperature, and ATW telemetry
endpoints (comfort-graph, internaltemperatures, interval energy).
Lazily creates and caches Home device facade instances using a WeakMap keyed by model reference. Mirrors the classic ClassicFacadeManager pattern.
The three intervals an ATA unit advertises, whichever API describes it. Both dialects publish exactly these pairs; only the field spelling differs, so each facade supplies them and the resolution below is shared.
Facade for an individual MELCloud device with type-safe data access and control.
Base facade contract shared by all facade types (building, floor, area, device).
Facade for zones (building, floor, area) that contain multiple ATA devices supporting group operations.
Last-known holiday-mode window — the cross-dialect read twin of
HolidayModeUpdate. Classic maps its HM* wire fields onto it,
Home its camelCase /context descriptor; a null date is a window
bound the wire left unset.
A holiday-mode window to apply. startDate/endDate are ISO 8601
wall-clock strings; both are ignored when isEnabled is false. The
start is always explicit (the Home API carries no timezone context to
anchor a "now" default), so callers pass the full window.
Last-known protection settings — the cross-dialect read twin of
ProtectionUpdate. Classic maps its FP* wire fields onto it,
Home its camelCase /context descriptor; null upstream marks the
feature as never configured.
A protection update to apply — the write contract shared by frost (Classic and Home) and overheat (Home ATA) protection, clamped by the sibling helpers before it reaches the wire.
One background band over a line chart, expressed as an inclusive
[from, to] index range on the labels grid — e.g. an ATW
operation-mode span. Only Home ATW temperature charts carry bands;
every other chart omits the field.
Line chart data with named series and a measurement unit.
Pie chart data with labeled segments.
Date range query for report endpoints.
A setpoint interval in °C, inclusive on both ends — the cross-dialect
read twin of the raw bounds each API advertises: Classic maps its
MinTemp*/MaxTemp* wire fields onto it, Home its camelCase
minTemp*/maxTemp* capabilities.
Union of all device facade types.
Union of the Home device facade variants — the Home counterpart of
ClassicDeviceFacadeAny.
Type guard that narrows an ATW facade to the zone 2 variant.
Allows consumers to safely access zone2 without type assertions.
Type guard that narrows a device facade to the ATA variant.
Type guard that narrows a device facade to the ATW variant.
Allows consumers to safely access hotWater and zone1 without type assertions.
Type guard that narrows a device facade to the ERV variant.
Type guard that narrows a Home device facade to the ATA variant.
Type guard that narrows a Home device facade to the ATW variant.
ClassicArea model representing a zone within a building or floor.
ClassicBuilding model holding zone settings and geographic location.
Concrete device model holding mutable device data that can be partially updated after API calls.
ClassicFloor model representing a level within a building.
Central in-memory registry of all MELCloud models (buildings, floors, areas, devices). Synced from the Classic API response and queryable by ID or parent relationship.
Mutable wrapper around a HomeDeviceData, preserving object identity across syncs.
TData narrows the wrapped payload to a specific connection-type variant
(e.g. HomeAtaDeviceData) when callers have already discriminated on
HomeDevice.type; defaults to the full union for the registry.
Lightweight device registry for the Home API. Maintains stable model references across syncs using upsert + prune.
Devices of one /context building sharing a connection type — the
account-level grouping the registry derives from its devices.
All classic device model variants. Kept non-distributive so
createDeviceModel() can construct a single ClassicDevice without
needing a per-variant switch; callers that need a specific literal
variant should use isClassicDeviceOfType to narrow explicitly.
Base type for all model classes.
Type guard that narrows a ClassicDeviceAny to a specific ClassicDevice variant.
Base class for all errors thrown by this SDK.
The server rejected the credentials, the login form could not be parsed, or the reactive re-authentication after a 401 failed.
MELCloud is temporarily refusing sign-ins (login throttle): Classic
reports it as ErrorId 6 on ClientLogin3, Home as HTTP 429 from
the token endpoints. Retrying a login keeps the lockout alive, so the
automatic re-login backoff widens when this error arms it; sessions
established BEFORE the throttle keep working (MELCloud stays generous
with existing keys).
Thrown when a facade attempts to resolve its underlying registry entity by id and finds nothing — typically because the registry was rebuilt (re-login, re-sync, or upstream rename/deletion) and the entity no longer exists under the previously known id.
Thrown when an update* call is made with no data to apply — either
the payload is empty, or every value already matches the current state.
Upstream returned HTTP 429 (Too Many Requests), or the local rate-limit gate is still holding a pause window from a previous 429.
Thrown when MELCloud Classic accepts a mutation request but rejects its
content, reporting per-attribute messages (AttributeErrors). The
facades convert that wire union into this typed throw, so both dialects
share one Promise<void> outcome contract for every mutation.
Thrown when a runtime validator (Zod, in this SDK) rejects an
upstream response. The context field surfaces which boundary the
payload came from (e.g. 'BFF /context', 'ClientLogin3',
'OIDC token endpoint') so consumer dashboards can group drift
alerts without parsing the message string.
User-defined type guard for APIError and its subclasses.
Common configuration shared by all API clients. 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).
Low-level API adapter exposing all MELCloud HTTP endpoints. Methods are grouped by supported device types.
Configuration options for creating a MELCloud Classic API instance.
Persistent settings managed by the Classic API for session authentication.
A single error entry from the device error log.
Parsed error log with pagination support.
Query parameters for paginating the error log.
Injectable contract for the MELCloud Home API client.
Configuration options for the MELCloud Home API.
Persistent settings managed by the Home API for session authentication.
Callback bundle invoked around SDK lifecycle moments. All callbacks are optional and non-throwing — the SDK ignores any exceptions they raise so a buggy observer cannot break the request flow.
Logger interface for API call tracing.
Emitted when a request (possibly after retries) completes successfully.
Emitted when a request ultimately fails after exhausting its retries.
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.
Emitted each time a retry attempt is scheduled.
External storage adapter for persisting API session settings.
Emitted at the start of a request, before any retry attempts.
Callback invoked after sync operations, with optional device IDs and type filter.
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.
MELCloud Classic API device type identifiers.
Fan speed levels for ATA and ERV devices.
ClassicHorizontal vane positions for ATA devices.
Report axis label formatting types.
MELCloud supported language codes.
Fan speed values excluding silent, used in set/update commands.
ATA device operation modes.
ATW device real-time operation state.
ATW hot water derived operational state.
ATW zone derived operational state.
ATW zone operation modes controlling temperature regulation strategy.
ATA set-temperature limits in °C (universal across all ATA models).
ERV ventilation modes.
ClassicVertical vane positions for ATA devices.
Unified MELCloud device type: union of Classic and Home API device types.
ATW top-level derived operational state (Home dialect): the FTC
OperationMode normalized to the Classic state vocabulary.
ATW zone control basis (Home dialect), normalized from the FTC zone
operation modes. Unknown firmware variants (including the external
*Thermostat modes) degrade to the room modes.
MELCloud Home API device type identifiers, matching context response keys.
Effective flags value indicating no specific fields were changed; all data should be included.
Synthetic operation mode for buildings with devices in different modes. Not a real API value — used at the application layer for mixed-state display.
ATA operation modes that produce cooling output (auto, cool, dry).
MELCloud Classic API device type identifiers.
Fan speed levels for ATA and ERV devices.
ATA operation modes that produce heating output (auto, heat).
ClassicHorizontal vane positions for ATA devices.
Report axis label formatting types.
MELCloud supported language codes.
ATA device operation modes.
ATW device real-time operation state.
ATW hot water derived operational state.
ATW zone derived operational state.
ATW zone operation modes controlling temperature regulation strategy.
ATA set-temperature limits in °C (universal across all ATA models).
ERV ventilation modes.
ClassicVertical vane positions for ATA devices.
ATW top-level derived operational state (Home dialect): the FTC
OperationMode normalized to the Classic state vocabulary.
ATW zone control basis (Home dialect), normalized from the FTC zone
operation modes. Unknown firmware variants (including the external
*Thermostat modes) degrade to the room modes.
MELCloud Home API device type identifiers, matching context response keys.
Home API fan speed string values.
Home API horizontal vane position string values.
Home API operation mode string values.
Home API vertical vane position string values.
Mapping from Classic numeric fan speed to Home string value.
Mapping from Home string fan speed to Classic numeric value.
Mapping from Classic numeric device type to Home string value (ATA/ATW only — ERV is Classic-only).
Mapping from Home string device type to Classic numeric value.
Mapping from Classic numeric horizontal vane position to Home string value.
Mapping from Home string horizontal vane position to Classic numeric value.
Mapping from Classic numeric operation mode to Home string value.
Mapping from Home string operation mode to Classic numeric value.
Mapping from Classic numeric vertical vane position to Home string value.
Mapping from Home string vertical vane position to Classic numeric value.
Method decorator factory that converts the API response back to
list-data shape and updates the targeted device model, using
EffectiveFlags to propagate only fields the device actually
acknowledged.
Method decorator factory that propagates data changes to device
models after the decorated method completes. Supports filtering by
device type; the patch-computation strategy is explicit via
the kind option ('payload' or 'power') rather than inferred
from the method name.
Method decorator factory that triggers a registry refresh around the decorated method.
Method decorator factory that invokes a sync notification after
the decorated method resolves. The host implements notifySync
structurally — facades enrich the payload with ids before
delegating, BaseAPI emits straight through the lifecycle emitter.
No action is taken when the host doesn't expose the hook.
Thin fetch-based HTTP client used internally by the SDK.
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.
Construction options for HttpClient.
Snapshot of the request that triggered an HttpError.
Configuration accepted by HttpClient.request.
Minimal response shape surfaced to callers.
Type guard for HTTP errors thrown by the internal HTTP client.
Wire-format area entry from ListDevices; FloorId is null when the area sits directly under the building, or a floor id otherwise.
Registry zone for an area, listing the devices it contains.
Common header fields for any Device/Set* POST body: target id and the bitfield identifying which mutated fields should be applied.
Shape returned by Device/Get for any device type — same body as a set-device payload but with EffectiveFlags pinned to the unchanged sentinel.
ListDevices device wrapper — identity, parent zones, ownership,
firmware/network metadata, UI hints, and per-capability permission
flags. The typed Device payload is added on top by
ClassicListDevice.
Wire-format building entry from ListDevices (without the nested Structure).
Inherits frost-protection + holiday-mode flags from ClassicZoneSettings.
Full wire-format building from ListDevices, including the nested floor / area / device hierarchy.
Registry zone for a building, including its floors, areas, and devices.
Per-capability permission flags carried on every ListDevices
device wrapper. Mirrors what the BFF computes from the user's
ownership / share grants for each device.
Registry zone for an individual device.
Energy report payload for an ATA (air-to-air) device returned by EnergyCost/Report.
The per-mode arrays are consumption buckets aligned with Labels;
Labels is numeric on this endpoint (day-of-week entries are .NET
0-based, Sunday = 0, unlike the 1-based ISO labels of Report/*).
Energy report payload for an ATW (air-to-water) device returned by EnergyCost/Report.
The consumed/produced arrays are energy buckets aligned with Labels;
Labels is numeric on this endpoint (live payload, 2026-07-18).
POST body for EnergyCost/Report — single device, ISO date range.
Single error-log entry returned by Report/GetUnitErrorLog2.
POST body for Report/GetUnitErrorLog2; either an explicit date range or a rolling Duration window.
Failure half of the discriminated mutation response — Success: false plus per-attribute rejection messages.
Wire-format floor entry from ListDevices.
Registry zone for a floor, including its areas and devices.
Frost-protection settings retrieved from FrostProtection/GetSettings.
Identifier bundle scoping a frost-protection update to one or more buildings, floors, areas, or devices.
POST body for FrostProtection/Update — scope plus the new bounds and on/off flag.
Query-string parameters for Device/Get.
Wire-format response from Group/Get — current ATA group specification and applied state.
POST body for Group/Get — identifies which zone (building, floor, or area) the group covers.
Mutable fields applied across every ATA device in a group via Group/SetAta.
Holiday-mode settings retrieved from HolidayMode/GetSettings.
Identifier bundle scoping a holiday-mode update to one or more buildings, floors, areas, or devices.
POST body for HolidayMode/Update — start/end dates plus per-time-zone scope entries.
Per-time-zone scope entry inside a HolidayMode/Update body.
ATW hot water state derived from device data.
Wire-format ListDevices device entry: header (id, name, parents) plus the typed Device payload.
Wire-format Device payload for an ATA (air-to-air) unit in ListDevices.
Wire-format Device payload for an ATW (air-to-water) unit in ListDevices.
Wire-format Device payload for an ERV (energy-recovery ventilation) unit in ListDevices.
Wire-format response from Login/ClientLogin3; LoginData is null when credentials are rejected.
POST body for Login/ClientLogin3.
Per-zone operation-mode fields on an ATW update payload.
Approximate latitude/longitude bucket carried alongside Latitude/
Longitude on each ClassicBuildingData entry. The BFF uses
the rounded values for clustering/coarse map placement.
Generic report payload (temperatures, signal, etc.) returned by the various Report/* endpoints.
Common POST body for the Report/* endpoints — single device, ISO date range, optional rolling Duration.
Wire-format response from Device/SetAta.
ATA properties that use different names in list responses vs set requests (e.g., ClassicFanSpeed in list, SetFanSpeed in set).
Wire-format response from Device/SetAtw.
Wire-format response from Device/SetErv.
POST body for Group/SetAta — zone selector plus the state fields to push to every device in the group.
POST body for Device/Power.
Query-string parameters identifying a zone settings target (used by FrostProtection/GetSettings, HolidayMode/GetSettings).
Success half of the discriminated mutation response — Success: true and no attribute errors.
Per-zone target temperatures on an ATW update payload (heating / cooling flow temps, tank water, room set-points).
POST body for Report/GetTemperatureLog2; extends the generic report body with an optional Location selector.
Wire-format response from Tile/Get2; the optional SelectedDevice carries full device data when a device id was specified.
Mutable subset of an ATA device's data; every field is optional so callers can push partial updates.
Mutable subset of an ATW device's data; combines per-zone operation modes, target temperatures, and the hot-water override.
Mutable subset of an ERV device's data; every field is optional so callers can push partial updates.
Inherited frost-protection + holiday-mode flags carried on every building, floor, and area record.
Aggregated heating/cooling state for one zone of an ATW device, derived from ListDevices data.
Failed outcome carrying a typed ApiRequestError.
Static capability flags and per-mode temperature bounds advertised by a MELCloud Home ATA device.
Wire-format MELCloud Home ATA device entry — extends the device-type
agnostic HomeDeviceCommonData with ATA-specific transport
(connectedInterface*, systemId, unitSettings) and narrows
capabilities to the ATA shape.
Mutable ATA device state accepted by the MELCloud Home device-update endpoint; every field is optional and null clears it.
Static capability descriptor advertised by a MELCloud Home ATW device.
Wire-format MELCloud Home ATW device entry — extends HomeDeviceCommonData with the ATW-specific FTC controller model and the WiFi adapter MAC address.
Mutable ATW device state accepted by the MELCloud Home device-update endpoint; every field is optional and null clears it.
Wire-format MELCloud Home building entry, splitting devices by their connection type (ATA vs ATW).
Identity of the /context building (owned or guest) a registered Home
device was sourced from — the account-level grouping key for devices.
Building node of the flattened Home zone list — the Home counterpart of
the Classic registry's flat zone vocabulary, using the picker model
tags the consumer app established (homeBuildings/homeDevices).
Single claim entry on a MELCloud Home identity token.
Wire-format response from the MELCloud Home /context endpoint — the authenticated user plus their owned and guest buildings.
Fields shared by every MELCloud Home device wrapper, regardless of
connection type. ATA and ATW data interfaces extend this with their
type-specific extras (connectedInterface*/systemId/unitSettings
for ATA, macAddress/ftcModel for ATW).
Single name/value setting entry on a MELCloud Home device.
Device node of the flattened Home zone list. deviceType keeps the
consumer app's short connection tags (ata/atw).
Wire-format energy response from MELCloud Home — one or more measure series per device.
A single energy measure series (e.g. heating, cooling) and its time-series values.
Single time-stamped energy sample.
Single error-log entry returned by the MELCloud Home error-history
endpoint. errorReason is null when the BFF sends no reason string
for the code, and clearedTimestamp stays null while the error is
uncleared.
Frost-protection schedule attached to a MELCloud Home device. Mirrors
the wire shape from /context; null on the parent device when the
feature is not configured.
POST body for /monitor/protection/frost — the new bounds and on/off
flag plus the batch of target device ids.
Holiday-mode descriptor attached to a MELCloud Home device. Mirrors the
/context wire shape; null on the parent device when the feature is
not configured. active is read-only status (the window is currently
in effect); only enabled/startDate/endDate are settable.
POST body for /monitor/holidaymode — the window bounds and on/off flag
plus the batch of target device ids.
Overheat-protection schedule attached to a MELCloud Home device.
Mirrors the HomeFrostProtection shape; null on the parent
device when the feature is not configured.
POST body for /monitor/protection/overheat — the new bounds and
on/off flag plus the batch of target device ids. The feature is
ATA-only: the official app never sends ATW ids.
Device ids grouped by type, targeting a batch Home protection write
(/monitor/protection/frost, /monitor/holidaymode). Wire-verbatim
uppercase keys; one request scopes to a single account's devices.
One time range highlighted by a Home report. On the comfort-graph a
labelled annotation is an ATW operation-mode band
(REPORT.COMFORT_GRAPH.OVERLAY_KEY.<MODE>); annotations without a
label (internal-temperatures report) mark missing-data ranges and
carry no mode information. Styling keys are omitted like on
HomeReportDataset.
Wire-format temperature/signal report from MELCloud Home — one dataset per series, each holding (x,y) samples.
One named series of (x,y) samples in a HomeReportData.
The wire format also carries chart-rendering metadata
(backgroundColor, borderColor, pointRadius, ...); they are
intentionally omitted from the canonical type since the SDK does not
consume them and they belong to the BFF's frontend concerns.
Single (x,y) sample inside a HomeReportDataset.
Last sample of a series before the report window — the seed the Home
UI (and the facade resampler) carries forward so sparse setpoint
series do not start the window blank. value is null (with a
far-future trigger sentinel) when the series has no prior sample.
Authenticated MELCloud Home user identity decoded from the bearer token's id-token claims.
Identity slice of the MELCloud Home /context response — the four
fields that establish who is signed in. Kept separate from
HomeContext so session validity can be derived from any
successful /context round-trip even when the device payload
fails full validation (device-schema drift must degrade the
registry, never the authentication state).
MELCloud user credentials, shared by the Classic and Home APIs.
Successful outcome carrying the parsed value.
Discriminated failure class emitted by the SDK's best-effort getters (Classic + Home telemetry, reports, and settings reads).
Either floor-bound or directly under-building variant of ClassicAreaData.
Unique identifier for a MELCloud area.
Unique identifier for a MELCloud building.
Owner descriptor returned by ListDevices building entries when the
authenticated user is a guest. null for owned buildings — the
shape itself is structural until a sample materialises in the wild.
MELCloud's date-time-as-components encoding used on holiday-mode payloads; null when the date is unset.
Unique identifier for a MELCloud device.
Wire-format energy report payload narrowed by the device's Type (Ata or Atw — Erv has no energy data).
A flattened registry zone stamped with its owning building's display
name, so a flat picker (e.g. a Flow autocomplete with no tree) can tell
same-named zones on different buildings apart. buildingName equals the
zone's own name for a building zone.
Unique identifier for a MELCloud floor.
Wire-format response body from Device/Get, narrowed by device type.
Discriminated union over every Classic device type returned by ListDevices.
Wire-format Device payload from ListDevices, narrowed by device type.
Union of every Classic list-device data shape across device types.
Operation-mode breakdown returned by Report/GetOperationModeLog2 — one {Key,Value} entry per mode.
Wire-format response from Device/Set{Ata,Atw,Erv}, narrowed by device type.
POST body for Device/Set{Ata,Atw,Erv} — base header plus every required field for the device type.
POST body for Tile/Get2; conditionally requires SelectedBuilding + SelectedDevice when scoped to a single device.
Mutable fields for a Device/Set{Ata,Atw,Erv} payload, narrowed by device type.
Discriminated union of every registry zone shape (building / floor / area / device).
ATW zone state derived from device data.
Top-level FTC operation mode reported by the OperationMode device
setting. Live-captured values so far: Cooling, LegionellaPrevention
and Stop; the other
members mirror the states the MELCloud Home app surfaces. Firmware
revisions may expose further strings, so consumers should treat unknown
values as unmapped rather than fail.
Per-zone operation mode of a MELCloud Home ATW device, in the PascalCase
form the /context settings report. Mirrors the FTC zone modes (room
thermostat / fixed flow / weather curve, in heat or cool). The
device-update endpoint only accepts these values in camelCase — the API
lowers them on write, so callers always use this canonical form.
Capability descriptor advertised by any MELCloud Home device — disjoint between ATA and ATW shapes.
WiFi adapter family reported by the MELCloud Home BFF. melCloudWiFi
tags the MAC-addressed first-gen adapters; fourthGenWifi tags the
GUID-addressed fourth-generation adapters.
Wire-format MELCloud Home device entry; either an ATA or ATW unit.
Single weekly-schedule entry attached to a MELCloud Home device.
The wire shape differs between ATA and ATW units (ATW entries carry
zone/tank fields instead of setpoint/vane fields), and power-off
entries hold null for every setting field; the SDK does not
consume specific fields, so the type stays a structural placeholder
until a use case appears — mirroring HomeHolidayMode.
Node union of the flattened Home zone list, name-sorted buildings each followed by their name-sorted devices.
Integer hour of the day in 24-hour form (0 through 23).
Set-request property names that have no direct counterpart in list responses (they map to ClassicSetDeviceDataAtaInList names instead).
Fully-resolved counterpart of an undefined-tolerant input shape:
every property present and defined (defaults applied). Under
exactOptionalPropertyTypes, Required<T> removes ? but keeps an
explicit | undefined in the property type; this also strips it.
null is preserved — in this domain it is a sentinel, not an
absence marker.
Discriminated outcome for best-effort SDK calls. The success branch
carries the parsed value; the failure branch carries an
ApiRequestError variant the caller can branch on (retry on
network, refresh on unauthorized, surface on validation, etc.)
— distinctions a flat T | null would collapse.
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.
Construct a Failure.
Transform the success branch of a Result while passing the
failure branch through unchanged. Lets callers compose
Result-returning calls with synchronous transforms (e.g.
mapResult(await api.getEnergy(...), getChartLineOptions)) without
unwrapping then re-wrapping by hand.
Construct a Success.
Session and infrastructure surface shared by both dialects' API adapters — the cross-dialect base a consumer can program against without knowing which wire it talks to.
Session material both dialects persist through the host's SettingManager: credentials, expiry, and the login-backoff gate (previously undeclared — a host clearing every declared key left the backoff behind).
Cross-dialect reachability contract: true while MELCloud can deliver writes to the unit.
Facade for a MELCloud building, combining zone settings with super device operations.
Facade for Air-to-Air (ATA) devices, exposing the ATA group operations on a single device by treating it as a group of one — MELCloud's native group endpoints only address zones (building/floor/area), so a device emulates them against its own state.
Facade for Air-to-Water (ATW) devices with hot water and zone state access.
Facade for ATW devices with two heating/cooling zones.
Base identifiable contract: an id (numeric on Classic, GUID string on Home) and a display name.
Absolute frost-protection min/max the units accept, in °C.
HTTP status codes used across the SDK. Single source so callers
don't redefine them per file (HTTP_STATUS_UNAUTHORIZED was
declared in three places before this module existed).
Absolute overheat-protection min/max the units accept, in °C.
Minimum gap required between min and max, in °C (both features).
Hours of continuous negative signal before a device facade reports
isAvailable: false — day-scale on BOTH dialects by design: Classic's
LastTimeStamp is building-local wall clock (±14 h of worldwide skew)
and its Offline flag is a ~2-4 min staleness boolean that flaps on
healthy units (live-probed 2026-07-28), while Home's isConnected has
a live-probed positive side but an unproven negative one — a
persistence window this wide turns any Classic-style tight-threshold
boolean harmless.
Clamp a frost-protection min/max pair into range with the required gap:
min lands in [4, 14], max in [6, 16], and max - min >= 2.
Clamp an overheat-protection min/max pair into range with the required
gap: min lands in [31, 38], max in [33, 40], and max - min >= 2.
Resolves the bounds enforced for a Classic operation mode, through the same table the Home side uses.
Resolves the bounds enforced for a Home operation mode.
Main MELCloud Classic API client. Handles authentication, device syncing, and all ClassicAPI endpoint calls. Uses a private constructor — create instances via ClassicAPI.create.