homebridge-navilink 0.1.0

package/dist/api/protocol.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview NaviLink request frames: the envelope, and the commands inside
+ * it.
+ *
+ * Every message to a gateway has the same outer shape. A `request` object
+ * carries the command code and its arguments; the envelope around it says who
+ * is asking, where the answer should go, and which protocol revision is being
+ * spoken.
+ *
+ * ```json
+ * {
+ *   "clientID": "…",
+ *   "protocolVersion": 1,
+ *   "request": { "command": 16777217, "macAddress": "…", "…": "…" },
+ *   "requestTopic": "cmd/1/navilink-…/status/start",
+ *   "responseTopic": "cmd/1/…/res/channelinfo",
+ *   "sessionID": "1700000000000"
+ * }
+ * ```
+ *
+ * The command codes are not arbitrary. They are a class in the high byte and
+ * an index in the low: `0x01000001` is the first read, `0x01000004` the
+ * fourth. They are written in hex here with the decimal alongside. The
+ * decimal is what appears in a capture, and the hex is what makes the
+ * pattern visible.
+ *
+ * Nothing in this file talks to a socket. It builds objects, so the frames
+ * this plugin sends can be asserted on byte for byte in a test.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ON_DEMAND_WARMUP = exports.OnOff = exports.ControlMode = exports.Command = exports.PROTOCOL_VERSION = void 0;
+exports.channelInfoRequest = channelInfoRequest;
+exports.channelStatusRequest = channelStatusRequest;
+exports.controlRequest = controlRequest;
+exports.powerControl = powerControl;
+exports.heatingEnableControl = heatingEnableControl;
+exports.dhwSetpointControl = dhwSetpointControl;
+exports.heatingSetpointControl = heatingSetpointControl;
+exports.onDemandControl = onDemandControl;
+exports.appDisconnectWill = appDisconnectWill;
+exports.encodeSetpoint = encodeSetpoint;
+const temperature_1 = require("../utils/temperature");
+/**
+ * Protocol revision sent in every envelope.
+ *
+ * `1` is what the gateway accepts for every frame this plugin sends.
+ */
+exports.PROTOCOL_VERSION = 1;
+/**
+ * Command codes.
+ *
+ * The high byte is the class: `0x01` reads, `0x02` writes. The low byte is
+ * the operation index. `0x02000000 | index` is the write for that
+ * operation.
+ *
+ * These are sent to a gas appliance, so the codes and mode strings are the
+ * ones the gateway dispatches on, not a generated pair.
+ */
+exports.Command = {
+    /** Ask what the gateway has attached. Answered on `res/channelinfo`. */
+    CHANNEL_INFO: 0x0100_0001,
+    /** Ask a channel what it is doing. Answered on `res/channelstatus`. */
+    CHANNEL_STATUS: 0x0100_0004,
+    /** Switch the appliance on or off. */
+    POWER: 0x0200_0001,
+    /** Enable or disable the space-heating loop. */
+    HEAT: 0x0200_0002,
+    /** Set the domestic hot water setpoint. */
+    DHW_TEMPERATURE: 0x0200_0003,
+    /** Set the space-heating water setpoint. */
+    HEAT_TEMPERATURE: 0x0200_0004,
+    /** Start, stop or warm up the recirculation pump. */
+    ON_DEMAND: 0x0200_0005,
+    /** Set the recirculation setpoint. */
+    RECIRCULATION_TEMPERATURE: 0x0200_0007,
+};
+/**
+ * The `control.mode` string that accompanies each write command.
+ *
+ * The command code alone is not enough: the gateway dispatches on the mode
+ * string, and the capitalisation is not consistent between them:
+ * `DHWTemperature` but `heatTemperature`, `power` but not `Power`. The
+ * table spells each one out because the gateway matches the string as
+ * written.
+ */
+exports.ControlMode = {
+    POWER: 'power',
+    HEAT: 'heat',
+    DHW_TEMPERATURE: 'DHWTemperature',
+    HEAT_TEMPERATURE: 'heatTemperature',
+    ON_DEMAND: 'onDemand',
+    RECIRCULATION_TEMPERATURE: 'recirculation',
+};
+/**
+ * The appliance's boolean encoding.
+ *
+ * Not zero and one. Zero means "unknown" throughout this protocol, so a
+ * command carrying it is asking for nothing. Disabled features report `2`
+ * on the read side, and writes use the same pair.
+ */
+exports.OnOff = {
+    ON: 1,
+    OFF: 2,
+};
+/** On-demand recirculation takes a third value the other flags do not. */
+exports.ON_DEMAND_WARMUP = 3;
+/** The envelope, with the caller's request inside it. */
+function envelope(input) {
+    const { context, request, requestTopic, responseTopic } = input;
+    return JSON.stringify({
+        clientID: context.clientId,
+        protocolVersion: exports.PROTOCOL_VERSION,
+        request,
+        requestTopic,
+        responseTopic,
+        // A correlation value the gateway echoes. Milliseconds since the epoch, as
+        // a string, which is what the app sends. Not used to match responses: the
+        // answers arrive on the gateway's own topic, where they are not
+        // necessarily answers to anything we asked.
+        sessionID: String(Date.now()),
+    });
+}
+/** Fields every request carries, whatever the command. */
+function addressing(context, command) {
+    return {
+        additionalValue: context.additionalValue,
+        command,
+        deviceType: context.deviceType,
+        macAddress: context.macAddress,
+    };
+}
+/**
+ * Ask the gateway to describe itself.
+ *
+ * The first thing sent on a new session. Until it is answered nothing else is
+ * meaningful: the reply carries `temperatureType`, without which every
+ * temperature in every later frame is unreadable.
+ */
+function channelInfoRequest(input) {
+    const { context, topics, responseTopic } = input;
+    return {
+        topic: topics.start,
+        payload: envelope({
+            context,
+            request: addressing(context, exports.Command.CHANNEL_INFO),
+            requestTopic: topics.start,
+            responseTopic,
+        }),
+    };
+}
+/**
+ * Ask one channel for its current state.
+ *
+ * `unitNumberStart` and `unitNumberEnd` select which appliances in a cascade
+ * to report. For a single appliance both ends are 1. The range is inclusive
+ * and one-based, which is why a caller passes a count rather than an index.
+ */
+function channelStatusRequest(input) {
+    const { context, topics, responseTopic, channelNumber, unitCount } = input;
+    return {
+        topic: topics.statusRequest,
+        payload: envelope({
+            context,
+            request: {
+                ...addressing(context, exports.Command.CHANNEL_STATUS),
+                status: {
+                    channelNumber,
+                    unitNumberStart: 1,
+                    unitNumberEnd: Math.max(1, unitCount),
+                },
+            },
+            requestTopic: topics.statusRequest,
+            responseTopic,
+        }),
+    };
+}
+/**
+ * Build a control frame.
+ *
+ * `param` is always an array, even for a single scalar and even when empty.
+ * That is the vendor's shape, not a convenience: the gateway parses the field
+ * as a list and a bare number is rejected.
+ */
+function controlRequest(input) {
+    const { context, topics, responseTopic, channelNumber, command, mode, param } = input;
+    return {
+        topic: topics.control,
+        payload: envelope({
+            context,
+            request: {
+                ...addressing(context, command),
+                control: { channelNumber, mode, param: [...param] },
+            },
+            requestTopic: topics.control,
+            responseTopic,
+        }),
+    };
+}
+/** Switch the appliance on or off. */
+function powerControl(input) {
+    return controlRequest({
+        ...input,
+        command: exports.Command.POWER,
+        mode: exports.ControlMode.POWER,
+        param: [input.on ? exports.OnOff.ON : exports.OnOff.OFF],
+    });
+}
+/** Enable or disable the space-heating loop. */
+function heatingEnableControl(input) {
+    return controlRequest({
+        ...input,
+        command: exports.Command.HEAT,
+        mode: exports.ControlMode.HEAT,
+        param: [input.on ? exports.OnOff.ON : exports.OnOff.OFF],
+    });
+}
+/** Set the domestic hot water setpoint, in the appliance's native scale. */
+function dhwSetpointControl(input) {
+    return controlRequest({
+        ...input,
+        command: exports.Command.DHW_TEMPERATURE,
+        mode: exports.ControlMode.DHW_TEMPERATURE,
+        param: [encodeSetpoint(input.native, input.scale)],
+    });
+}
+/** Set the space-heating water setpoint, in the appliance's native scale. */
+function heatingSetpointControl(input) {
+    return controlRequest({
+        ...input,
+        command: exports.Command.HEAT_TEMPERATURE,
+        mode: exports.ControlMode.HEAT_TEMPERATURE,
+        param: [encodeSetpoint(input.native, input.scale)],
+    });
+}
+/** Start or stop the recirculation pump. */
+function onDemandControl(input) {
+    return controlRequest({
+        ...input,
+        command: exports.Command.ON_DEMAND,
+        mode: exports.ControlMode.ON_DEMAND,
+        param: [input.on ? exports.OnOff.ON : exports.OnOff.OFF],
+    });
+}
+/**
+ * The message the broker publishes if this client disappears.
+ *
+ * `status: 0` means an app has gone away. The gateway uses this to decide
+ * whether anyone is watching, which on some firmware governs how eagerly it
+ * pushes updates. `os: 'A'` is what the app sends; the gateway has not been
+ * observed to treat it as meaningful.
+ *
+ * Registered as the MQTT will rather than sent, so it fires precisely when
+ * this client stops answering. That is the one case it is for, and the one
+ * case where the plugin cannot send anything itself.
+ */
+function appDisconnectWill(context, topic) {
+    return JSON.stringify({
+        clientID: context.clientId,
+        event: {
+            additionalValue: context.additionalValue,
+            connection: { os: 'A', status: 0 },
+            deviceType: context.deviceType,
+            macAddress: context.macAddress,
+        },
+        protocolVersion: exports.PROTOCOL_VERSION,
+        requestTopic: topic,
+        sessionID: '',
+    });
+}
+/**
+ * Encode a setpoint for a control command.
+ *
+ * Kept here rather than inlined at the call site because the wire encoding of
+ * a temperature has to be identical in a command and in the status frame that
+ * reports it back. If the two ever disagree, a setpoint written as 120 reads
+ * back as 60 and the thermostat appears to halve itself on every write.
+ */
+function encodeSetpoint(native, scale) {
+    return (0, temperature_1.encodeWireTemperature)(native, scale);
+}

package/dist/api/rest.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview The NaviLink REST surface: sign in, and list what the account
+ * owns.
+ *
+ * Three calls, and they do very little. Everything that changes arrives over
+ * MQTT: a temperature, a setpoint, a fault. REST exists to get the credentials
+ * that make MQTT possible and to learn which appliances the account has.
+ *
+ * This is an unofficial API. There is no specification, no versioning promise
+ * and no deprecation notice; it is the interface the NaviLink mobile app uses.
+ * Everything here therefore treats an unexpected response as a protocol error
+ * with a readable message. It does not reach into a shape it assumes is there.
+ * When Navien changes something, the plugin should say what it did not
+ * recognise.
+ *
+ * **Every value on this path is a credential or personal data.** The request
+ * body carries the password; the response carries a JWT pair, temporary AWS
+ * IAM credentials, the account holder's name, and, from `device/info`, the
+ * street address and coordinates of the installation. Nothing from a response
+ * is logged, and the fields the plugin does not need are never read out of it.
+ */
+import type { PluginLogger } from '../types';
+import { type JsonPost } from './http';
+import type { IotCredentials } from './sigv4';
+/** A signed-in session. */
+export interface NaviLinkSessionTokens {
+    /** Account sequence number, which appears in every response topic. */
+    userSeq: string;
+    /** Bearer-less token for later REST calls. */
+    accessToken: string;
+    /** Present when the cloud offered one. */
+    refreshToken: string | undefined;
+    /** Temporary IAM credentials for the IoT endpoint. */
+    credentials: IotCredentials;
+    /** Epoch milliseconds after which the session must be re-established. */
+    expiresAt: number;
+}
+/** One appliance gateway on the account, as `device/list` reports it. */
+export interface ListedDevice {
+    /** Gateway MAC, as the cloud spells it: lower-case hex, no separators. */
+    macAddress: string;
+    /** Opaque discriminator the topics need. Frequently an empty string. */
+    additionalValue: string;
+    /** Gateway kind. `1` for every NaviLink gateway seen so far. */
+    deviceType: number;
+    /** Home grouping id, which appears in every response topic. */
+    homeSeq: string;
+    /** The name the user gave it in the NaviLink app. */
+    deviceName: string;
+    /** `2` means the cloud believes the gateway is online. */
+    connected: number;
+}
+/** Injectable collaborators, so tests need neither sockets nor real clocks. */
+export interface NaviLinkRestOptions {
+    log: PluginLogger;
+    post?: JsonPost;
+    now?: () => number;
+    /** Cancels in-flight calls, so Homebridge shutdown need not wait out a deadline. */
+    signal?: AbortSignal;
+}
+/** Talks to the NaviLink REST service. */
+export declare class NaviLinkRest {
+    private readonly log;
+    private readonly post;
+    private readonly now;
+    private readonly signal;
+    constructor(options: NaviLinkRestOptions);
+    /**
+     * Exchange an email and password for a session.
+     *
+     * Distinguishes a rejected account from an unreachable cloud, because the
+     * two need opposite responses: a wrong password must stop the plugin
+     * retrying, and a cloud outage must not.
+     */
+    signIn(email: string, password: string): Promise<NaviLinkSessionTokens>;
+    /**
+     * List the gateways on the account.
+     *
+     * `count` is a page size the API requires rather than a limit worth
+     * configuring. Pages are walked until a short one arrives, so a 21st
+     * gateway is not dropped. A cloud that never sends a short page is capped.
+     */
+    listDevices(input: {
+        email: string;
+        accessToken: string;
+    }): Promise<ListedDevice[]>;
+    /** One page of the device list, already parsed. */
+    private listDevicePage;
+    /**
+     * Read a single device's detail.
+     *
+     * Used only to learn the firmware revision, which is worth having in
+     * Accessory Information and in a bug report. **The response also carries the
+     * installation's street address and coordinates**; those fields are never
+     * read, so they cannot reach a log, an accessory context or a capture.
+     */
+    readFirmware(input: {
+        email: string;
+        accessToken: string;
+        macAddress: string;
+        additionalValue: string;
+    }): Promise<string | undefined>;
+    private call;
+    private readBody;
+    /**
+     * Turn a failed sign-in into the right kind of error.
+     *
+     * The distinction is the point. `AuthenticationError` with
+     * `credentialsRejected` stops the plugin trying again, because repeating a
+     * wrong password is how an account gets locked out. Anything else is
+     * transient and must be retried, because a cloud that is briefly unwell is
+     * not a reason to require the user to restart Homebridge.
+     */
+    private signInFailure;
+    /**
+     * Decide how long this session is good for.
+     *
+     * The response reports `authorizationExpiresIn` and
+     * `authenticationExpiresIn`. Neither is documented, the unit is not stated,
+     * and which one governs the AWS credentials rather than the JWT is not
+     * obvious from the names. So: read both as seconds, take the shorter, and
+     * only believe it if it lands in a plausible band. A value outside that band
+     * means the reading is wrong, and a wrong reading in the optimistic
+     * direction is a session that dies mid-winter without reconnecting.
+     */
+    private sessionLifetimeMs;
+    /**
+     * Read one device-list entry, skipping anything unusable.
+     *
+     * Skipped rather than thrown on: an account with one unrecognised gateway
+     * and one good one should expose the good one.
+     */
+    private readListedDevice;
+}