@olivierzal/melcloud-api

A typed Node.js client for the MELCloud and MELCloud Home APIs, providing access to Mitsubishi Electric air-to-air (Ata), air-to-water (Atw) and energy recovery ventilation (Erv) devices.

Features

• Strongly typed — full TypeScript types for both MELCloud Classic and MELCloud Home APIs, with 100% TSDoc coverage on the public surface.
• Two APIs, one client — Classic and Home behind consistent ergonomics; pick what your account uses. The cross-dialect surfaces (protection, holiday mode, error log, ATW state, the ATA group and the /report chart contract) answer one neutral vocabulary whichever API backs the target, each pinned by a contract kernel.
• Ata / Atw / Erv support — air conditioners, heat pumps with hot water, and energy-recovery ventilation units.
• Resilient by default — auto-retry on transient failures, rate-limit awareness, pre-emptive session refresh.
• Validated boundaries — Zod schemas guard every consumed payload, so upstream shape drift surfaces as a typed ValidationError instead of a deep undefined crash. The Classic bulk listing is the one deliberate exception: one unusable entry must not take a whole account down, so it is dropped and reported on the cycle's log line — with its id and whether its Type is unmodelled or its header malformed — instead of failing the payload.
• Typed failures — telemetry, reports and error-log getters return Result<T> so callers branch on network / unauthorized / rate-limited / validation / server / not-found instead of catching generic exceptions.
• Normalized telemetry — getEnergySeries on the Home device facades projects the energy history onto epoch-ms UTC instants and kilowatt-hours whatever the device type; the wire's timestamp dialect, interval grammar and per-type units stay inside the SDK, and a garbled sample degrades its fields to null (never NaN, never a throw) while keeping its entry. The wire-verbatim getEnergy remains for consumers that need the raw envelope.
• Tree-shakable — sideEffects: false plus namespace-style subpath exports (/classic, /home) and one flat subpath per browser-safe contract module. The flat subpaths never reach the HTTP stack, so a browser bundle can import their values; the root barrel does and is Node-only.

Requirements

• Node.js >= 22.20.0
• A valid MELCloud or MELCloud Home account
• For installing the package: a GitHub personal access token with the read:packages scope

Installation

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/melcloud-api

Usage

MELCloud (classic)

import { ClassicAPI, ClassicFacadeManager } from '@olivierzal/melcloud-api'

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

const manager = new ClassicFacadeManager(api)

// Browse the device hierarchy
for (const zone of manager.getZones()) {
  console.log(zone.name)
}

// Interact with a device through its facade
const [device] = api.registry.getDevices()
if (device !== undefined) {
  const facade = manager.get(device)
  await facade.updateValues({ Power: true })
}

MELCloud Home

import {
  HomeAPI,
  HomeDeviceType,
  HomeFacadeManager,
} from '@olivierzal/melcloud-api'

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

await api.list()
const manager = new HomeFacadeManager(api)

// Interact with a device through its type-narrowed facade
const [device] = api.registry.getDevicesByType(HomeDeviceType.Ata)
if (device !== undefined) {
  const facade = manager.get(device)
  console.log(facade.name, facade.operationMode, facade.setTemperature)
  await facade.updateValues({ setTemperature: 21 })
}

Error handling

Best-effort getters (telemetry, reports, error logs, settings reads) return a Result<T> so callers can branch on the failure class — network, unauthorized, rate-limited, validation, server, or not-found. Mutations (update*, updatePower) keep their throw-on-failure contract.

const result = await facade.getEnergy({ from: '2024-01-01', to: '2024-12-31' })
if (!result.ok) {
  switch (result.error.kind) {
    case 'rate-limited':
      // result.error.retryAfterMs
      break
    case 'unauthorized':
      // re-authenticate before retrying
      break
    default:
      // network / server / validation — log and skip
      break
  }
  return
}
const energy = result.value

Session management

Both clients keep their session alive without caller involvement:

• Pre-emptive refresh — sessions are renewed when they come within 5 minutes of expiry, so no request pays the re-authentication round-trip on its critical path.
• Reactive 401 recovery — when the server rejects a credential mid-flight, the SDK re-authenticates once (Home tries the cheap refresh-token exchange first, then falls back to a full sign-in) and replays the original request. A cooldown guard prevents retry loops.
• Persistence — pass a settingManager (a simple get/set string store) to persist tokens and credentials across restarts; without one, everything stays in memory and a new instance signs in from scratch.

Important

The SettingManager receives the access/refresh tokens 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 — bearer token, X-MitsContextKey, session cookie, sign-in body and query alike — so an error object handed to a host logger, or pasted into a diagnostic report, carries no secret.

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

Resilience & retries

The request pipeline applies three policies, outermost first:

1. Rate-limit gate (HTTP 429) — a 429 response pauses all requests for the Retry-After window (delta-seconds and HTTP-date forms are both honored), or 2 hours when the header is absent. While paused, calls fail fast with RateLimitError (retryAfter, unblockAt) instead of hammering the server; check api.isRateLimited before issuing bursts.
2. Auth retry (HTTP 401) — a single re-authentication + replay, as described above.
3. Transient retry (GET only) — 502/503/504 responses are retried up to 4 times with exponential backoff and jitter (1 s initial delay, 16 s cap). Mutations (POST/PUT) are never retried automatically: a write that may have landed server-side must not be silently duplicated. Each retry is observable through the onRequestRetry lifecycle event.

Imports

Exports follow a Classic* / Home* prefix convention so the target API is obvious at the call site. The ./classic and ./home subpaths re-export everything with the prefix stripped — a modern alternative to TypeScript's deprecated namespace keyword.

// From the root — prefixed names, works in mixed Classic/Home contexts
import { ClassicAPI, HomeAPI, type ClassicGetDeviceData } from '@olivierzal/melcloud-api'

// From the Classic-scoped subpath — short names, no ambiguity
import { API, FanSpeed, type GetDeviceData } from '@olivierzal/melcloud-api/classic'

// From the Home-scoped subpath — short names
import { API, type AtaValues, type DeviceCapabilities } from '@olivierzal/melcloud-api/home'

// Namespace-like usage (recommended for mixed Classic + Home code)
import type * as Classic from '@olivierzal/melcloud-api/classic'
import type * as Home from '@olivierzal/melcloud-api/home'
const a: Classic.GetDeviceData<0> = ...
const b: Home.AtaValues = ...

// Shared enum-like constants (e.g. CLASSIC_FLAG_UNCHANGED, HomeDeviceType)
import { ClassicDeviceType, HomeDeviceType } from '@olivierzal/melcloud-api/constants'

// Protection bounds and clamping (frost, overheat)
import { FROST_PROTECTION_RANGE } from '@olivierzal/melcloud-api/protection'

Available subpaths: /classic, /home, /atw-state, /constants, /enum-mappings, /error-log, /holiday-mode, /protection, /report, /temperature-range, /temporal.

The flat subpaths (everything but /classic and /home) stay inside the browser-safe closure — none of them reaches the Node-only HTTP stack the root barrel pulls in — so a browser bundler resolves them cleanly: the path to take when a webview needs a published value rather than a copy.

Documentation

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

Contributing

See CONTRIBUTING.md.

Security

For vulnerability reports, see SECURITY.md.

Changelog

See CHANGELOG.md.

Caution

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

License

MIT © Olivier Zalmanski