homebridge-navilink 0.1.0

package/dist/api/rest.js

@@ -0,0 +1,317 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NaviLinkRest = void 0;
+const settings_1 = require("../settings");
+const errors_1 = require("../utils/errors");
+const http_1 = require("./http");
+/**
+ * How long a session lasts when the cloud's answer is not believable.
+ *
+ * The sign-in response reports two lifetimes, and neither their unit nor which
+ * one governs the AWS credentials is documented. They are read as seconds and
+ * sanity-checked; anything outside a plausible band falls back to this, which
+ * is short enough to be safe against a much shorter real lifetime and long
+ * enough not to be a sign-in loop.
+ */
+const FALLBACK_SESSION_MS = 50 * 60 * 1_000;
+/** Page size `device/list` requires. */
+const DEVICE_LIST_PAGE_SIZE = 20;
+/** Hard stop so a cloud that always returns a full page cannot loop forever. */
+const MAX_DEVICE_LIST_PAGES = 10;
+/** Shortest lifetime believed from the cloud. Below this, use the fallback. */
+const MIN_BELIEVABLE_SESSION_MS = 5 * 60 * 1_000;
+/** Longest lifetime believed from the cloud. Above this, use the fallback. */
+const MAX_BELIEVABLE_SESSION_MS = 24 * 60 * 60 * 1_000;
+/** Talks to the NaviLink REST service. */
+class NaviLinkRest {
+    log;
+    post;
+    now;
+    signal;
+    constructor(options) {
+        this.log = options.log;
+        this.post = options.post ?? http_1.postJson;
+        this.now = options.now ?? Date.now;
+        this.signal = options.signal;
+    }
+    /**
+     * 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.
+     */
+    async signIn(email, password) {
+        if (typeof email !== 'string' || typeof password !== 'string') {
+            // A JS caller that passes `{ email, password }` as one argument would
+            // otherwise POST that object as `userId`. The cloud answers
+            // COMMON_BAD_REQUEST, which looks like a credential problem.
+            throw new TypeError('sign-in needs an email and a password as two strings');
+        }
+        const response = await this.call('/user/sign-in', { userId: email, password });
+        const body = this.readBody(response.body, 'sign-in');
+        const data = asRecord(body.data);
+        const token = asRecord(data?.token);
+        const accessToken = asNonEmptyString(token?.accessToken);
+        if (accessToken === undefined || token === undefined || data === undefined) {
+            // Deliberately not keyed on the status code. **This API answers a
+            // rejected password with HTTP 200** and an error in the body, so a
+            // status check alone classifies a wrong password as a transient
+            // protocol fault, and then retries it every few seconds until the
+            // account is locked. The presence of a token is the only reliable
+            // discriminator, so that is what decides success here.
+            throw this.signInFailure(response.status, body);
+        }
+        const accessKeyId = asNonEmptyString(token.accessKeyId);
+        const secretKey = asNonEmptyString(token.secretKey);
+        const sessionToken = asNonEmptyString(token.sessionToken);
+        if (accessKeyId === undefined || secretKey === undefined || sessionToken === undefined) {
+            throw new errors_1.ProtocolError('the sign-in response carried no AWS IoT credentials, so live status is not available');
+        }
+        const userSeq = readUserSeq(data);
+        if (userSeq === undefined) {
+            throw new errors_1.ProtocolError('the sign-in response carried no account identifier');
+        }
+        return {
+            userSeq,
+            accessToken,
+            refreshToken: asNonEmptyString(token.refreshToken),
+            credentials: {
+                accessKeyId,
+                secretKey,
+                sessionToken,
+                endpoint: settings_1.IOT_ENDPOINT,
+                region: settings_1.IOT_REGION,
+            },
+            expiresAt: this.now() + this.sessionLifetimeMs(token),
+        };
+    }
+    /**
+     * 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.
+     */
+    async listDevices(input) {
+        const found = [];
+        for (let page = 0; page < MAX_DEVICE_LIST_PAGES; page += 1) {
+            const { entries, isFull } = await this.listDevicePage(input, page * DEVICE_LIST_PAGE_SIZE);
+            found.push(...entries);
+            if (!isFull) {
+                return found;
+            }
+        }
+        this.log.warn(`the account listed ${MAX_DEVICE_LIST_PAGES * DEVICE_LIST_PAGE_SIZE} gateways, `
+            + 'which is this plugin\'s cap; any further gateway is not shown');
+        return found;
+    }
+    /** One page of the device list, already parsed. */
+    async listDevicePage(input, offset) {
+        const response = await this.call('/device/list', { offset, count: DEVICE_LIST_PAGE_SIZE, userId: input.email }, input.accessToken);
+        const body = this.readBody(response.body, 'device list');
+        if (response.status === 401 || response.status === 403) {
+            throw new errors_1.AuthenticationError('the cloud rejected the session token when listing devices');
+        }
+        if (response.status !== 200) {
+            throw new errors_1.ProtocolError(`the device list failed: ${describeApiFailure(response.status, body)}`);
+        }
+        // Two shapes have been seen: a bare array, and an object wrapping one.
+        // Both are accepted rather than one being declared correct, because there
+        // is no specification to be right about.
+        const data = body.data;
+        const raw = Array.isArray(data)
+            ? data
+            : (asRecord(data)?.deviceList ?? asRecord(data)?.devices);
+        if (!Array.isArray(raw)) {
+            throw new errors_1.ProtocolError('the device list response did not contain a list of devices');
+        }
+        return {
+            entries: raw.flatMap((entry) => {
+                const device = this.readListedDevice(entry);
+                return device === undefined ? [] : [device];
+            }),
+            isFull: raw.length >= DEVICE_LIST_PAGE_SIZE,
+        };
+    }
+    /**
+     * 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.
+     */
+    async readFirmware(input) {
+        const response = await this.call('/device/info', {
+            macAddress: input.macAddress,
+            additionalValue: input.additionalValue,
+            userId: input.email,
+        }, input.accessToken);
+        if (response.status !== 200) {
+            // Not fatal, and deliberately quiet: firmware is a nicety, and this
+            // endpoint has been observed answering 403 on accounts where the device
+            // list works perfectly well.
+            this.log.debug(`device/info answered HTTP ${response.status}; firmware will be unknown`);
+            return undefined;
+        }
+        const body = this.readBody(response.body, 'device info');
+        const info = asRecord(asRecord(body.data)?.deviceInfo);
+        return asNonEmptyString(info?.fwVersion);
+    }
+    async call(path, body, accessToken) {
+        // The path, never the body: the body of the very first call is the
+        // password.
+        this.log.debug(`POST ${path}`);
+        return this.post(`${settings_1.API_BASE}${path}`, body, {
+            connectTimeoutMs: settings_1.CONNECT_TIMEOUT_MS,
+            totalTimeoutMs: settings_1.REST_TIMEOUT_MS,
+            maxBytes: settings_1.MAX_REST_BYTES,
+            // No `Bearer` prefix. The API wants the raw token, and sending a
+            // correctly-formed bearer header gets a 401.
+            ...(accessToken === undefined ? {} : { headers: { authorization: accessToken } }),
+            ...(this.signal === undefined ? {} : { signal: this.signal }),
+        });
+    }
+    readBody(text, what) {
+        const parsed = (0, http_1.parseJsonBody)(text);
+        const record = asRecord(parsed);
+        if (record === undefined) {
+            throw new errors_1.ProtocolError(`the ${what} response was not a JSON object`);
+        }
+        return record;
+    }
+    /**
+     * 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.
+     */
+    signInFailure(status, body) {
+        const message = asNonEmptyString(body.msg)?.toUpperCase() ?? '';
+        if (message.includes('USER_NOT_FOUND')) {
+            return new errors_1.AuthenticationError('NaviLink does not recognise that email address', { credentialsRejected: true });
+        }
+        if (message.includes('PASSWORD') || message.includes('INVALID_USER')) {
+            return new errors_1.AuthenticationError('NaviLink rejected the email address or password', { credentialsRejected: true });
+        }
+        if (message.length > 0) {
+            // The cloud named a fault we do not have a mapping for. Not treated as
+            // a rejected credential, because guessing that would stop the plugin
+            // retrying something that may well be transient.
+            return new errors_1.ProtocolError(`sign-in failed: ${describeApiFailure(status, body)}`);
+        }
+        return new errors_1.ProtocolError(`sign-in did not return a token: ${describeApiFailure(status, body)}`);
+    }
+    /**
+     * 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.
+     */
+    sessionLifetimeMs(token) {
+        const candidates = [token.authorizationExpiresIn, token.authenticationExpiresIn]
+            .map((value) => (typeof value === 'number' && Number.isFinite(value) ? value * 1_000 : undefined))
+            .filter((value) => value !== undefined)
+            .filter((value) => value >= MIN_BELIEVABLE_SESSION_MS && value <= MAX_BELIEVABLE_SESSION_MS);
+        if (candidates.length === 0) {
+            this.log.debug('the cloud did not report a believable session lifetime; '
+                + `assuming ${Math.round(FALLBACK_SESSION_MS / 60_000)} minutes`);
+            return FALLBACK_SESSION_MS;
+        }
+        return Math.min(...candidates);
+    }
+    /**
+     * 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.
+     */
+    readListedDevice(entry) {
+        // Both a wrapped and a bare shape have been seen in the wild.
+        const record = asRecord(asRecord(entry)?.deviceInfo) ?? asRecord(entry);
+        const macAddress = asNonEmptyString(record?.macAddress)?.toLowerCase();
+        if (record === undefined || macAddress === undefined) {
+            this.log.debug('skipping a device-list entry with no MAC address');
+            return undefined;
+        }
+        return {
+            macAddress,
+            additionalValue: typeof record.additionalValue === 'string' ? record.additionalValue : '',
+            deviceType: typeof record.deviceType === 'number' ? record.deviceType : 1,
+            homeSeq: String(record.homeSeq ?? ''),
+            deviceName: asNonEmptyString(record.deviceName) ?? 'NaviLink',
+            connected: typeof record.connected === 'number' ? record.connected : 0,
+        };
+    }
+}
+exports.NaviLinkRest = NaviLinkRest;
+/** Describe an API failure without quoting a body that may hold a token. */
+function describeApiFailure(status, body) {
+    const message = asNonEmptyString(body.msg);
+    const code = typeof body.code === 'number' ? body.code : undefined;
+    if (message !== undefined) {
+        return `${message}${code === undefined ? '' : ` (code ${code})`}`;
+    }
+    return `HTTP ${status}`;
+}
+/**
+ * The account identifier, wherever this response happens to put it.
+ *
+ * Observed under `userInfo.userSeq`. Read defensively because it is not
+ * optional: it appears in every MQTT response topic, and a session without it
+ * can subscribe to nothing.
+ */
+function readUserSeq(data) {
+    const direct = data.userSeq;
+    if (typeof direct === 'string' || typeof direct === 'number') {
+        return String(direct);
+    }
+    const nested = asRecord(data.userInfo)?.userSeq;
+    if (typeof nested === 'string' || typeof nested === 'number') {
+        return String(nested);
+    }
+    return undefined;
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function asNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/dist/api/sigv4.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview AWS Signature Version 4, for a pre-signed AWS IoT WebSocket URL.
+ *
+ * AWS IoT's WebSocket transport takes no password on the socket: authority is
+ * the signature in the URL's query string. This plugin signs a
+ * `wss://…/mqtt` URL with the temporary IAM credentials that
+ * `POST /user/sign-in` hands back, and connects to that.
+ *
+ * Only the tiny slice of SigV4 this needs is implemented: one service, one
+ * signed header, an empty payload and no request body. The full algorithm has
+ * a great deal more in it, and an `@aws-sdk/*` dependency to do this would be
+ * several megabytes to build one string.
+ *
+ * **The URL this produces is a credential.** It carries the session token, the
+ * access key id and a signature over them, and anyone holding it can speak to
+ * the account's IoT endpoint until it expires. It must never be logged, never
+ * put in an error message, and never written to a capture. `redactSecrets`
+ * knows the query parameter names, but the primary defence is that the
+ * transport logs the endpoint host and never the URL.
+ */
+/** Temporary IAM credentials, as `POST /user/sign-in` returns them. */
+export interface IotCredentials {
+    accessKeyId: string;
+    secretKey: string;
+    sessionToken: string;
+    /** The account's `…-ats.iot.<region>.amazonaws.com` endpoint. */
+    endpoint: string;
+    region: string;
+}
+/**
+ * Percent-encode for a canonical request.
+ *
+ * `encodeURIComponent` is close but not identical to the AWS rule: it leaves
+ * `*` alone, which AWS requires encoded, and it encodes `~`, which AWS
+ * requires left alone. Both appear in session tokens, so getting either wrong
+ * produces a signature mismatch that reads as "not authorised" and sends you
+ * looking at IAM policy instead of at this function.
+ */
+export declare function uriEncode(value: string): string;
+/** The two timestamp forms SigV4 wants, derived from one instant. */
+export declare function amzTimestamps(now?: Date): {
+    amzDate: string;
+    dateStamp: string;
+};
+/**
+ * Build a signed `wss://` URL for the account's IoT endpoint.
+ *
+ * `signHostWithPort` selects what goes in the signed `host` header. Measured
+ * against the NaviLink endpoint: signing the bare host succeeds and signing
+ * `host:443` does not, so the default is the bare host. The alternative is
+ * kept because the two forms are both defensible readings of the SigV4 rule
+ * for a default port, other AWS regions and endpoints have been reported to
+ * want the other one, and the failure is indistinguishable from a wrong
+ * password: a silent 403 on the upgrade. The transport tries the default and
+ * then the fallback, so a user does not have to guess.
+ *
+ * The security token is appended *after* signing and is not part of the
+ * canonical query string. That is specific to IoT's WebSocket flow and is not
+ * how SigV4 normally treats `X-Amz-Security-Token`; including it in the
+ * canonical string produces a signature the endpoint rejects.
+ */
+export declare function presignIotWebsocketUrl(credentials: IotCredentials, options?: {
+    signHostWithPort?: boolean;
+    now?: Date;
+}): string;

package/dist/api/sigv4.js

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview AWS Signature Version 4, for a pre-signed AWS IoT WebSocket URL.
+ *
+ * AWS IoT's WebSocket transport takes no password on the socket: authority is
+ * the signature in the URL's query string. This plugin signs a
+ * `wss://…/mqtt` URL with the temporary IAM credentials that
+ * `POST /user/sign-in` hands back, and connects to that.
+ *
+ * Only the tiny slice of SigV4 this needs is implemented: one service, one
+ * signed header, an empty payload and no request body. The full algorithm has
+ * a great deal more in it, and an `@aws-sdk/*` dependency to do this would be
+ * several megabytes to build one string.
+ *
+ * **The URL this produces is a credential.** It carries the session token, the
+ * access key id and a signature over them, and anyone holding it can speak to
+ * the account's IoT endpoint until it expires. It must never be logged, never
+ * put in an error message, and never written to a capture. `redactSecrets`
+ * knows the query parameter names, but the primary defence is that the
+ * transport logs the endpoint host and never the URL.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uriEncode = uriEncode;
+exports.amzTimestamps = amzTimestamps;
+exports.presignIotWebsocketUrl = presignIotWebsocketUrl;
+const node_crypto_1 = require("node:crypto");
+/** The service name IoT's data plane signs as. Not `iot`. */
+const SERVICE = 'iotdevicegateway';
+/** The only path AWS IoT serves MQTT-over-WebSocket on. */
+const PATH = '/mqtt';
+/**
+ * Validity requested for the signature.
+ *
+ * The signature may say 24 hours, but the *credentials* it is built from
+ * expire much sooner. The sign-in response says when. The session is
+ * re-established on the credential deadline, not on this one, so this value
+ * only has to be comfortably longer than a connection's life.
+ */
+const EXPIRES_SEC = 86_400;
+function sha256Hex(data) {
+    return (0, node_crypto_1.createHash)('sha256').update(data, 'utf8').digest('hex');
+}
+function hmac(key, data) {
+    return (0, node_crypto_1.createHmac)('sha256', key).update(data, 'utf8').digest();
+}
+/**
+ * Percent-encode for a canonical request.
+ *
+ * `encodeURIComponent` is close but not identical to the AWS rule: it leaves
+ * `*` alone, which AWS requires encoded, and it encodes `~`, which AWS
+ * requires left alone. Both appear in session tokens, so getting either wrong
+ * produces a signature mismatch that reads as "not authorised" and sends you
+ * looking at IAM policy instead of at this function.
+ */
+function uriEncode(value) {
+    return encodeURIComponent(value)
+        .replaceAll('*', '%2A')
+        .replaceAll('%7E', '~');
+}
+/** The two timestamp forms SigV4 wants, derived from one instant. */
+function amzTimestamps(now = new Date()) {
+    const amzDate = now.toISOString().replaceAll('-', '').replaceAll(':', '').replace(/\.\d{3}Z$/, 'Z');
+    return { amzDate, dateStamp: amzDate.slice(0, 8) };
+}
+/**
+ * Build a signed `wss://` URL for the account's IoT endpoint.
+ *
+ * `signHostWithPort` selects what goes in the signed `host` header. Measured
+ * against the NaviLink endpoint: signing the bare host succeeds and signing
+ * `host:443` does not, so the default is the bare host. The alternative is
+ * kept because the two forms are both defensible readings of the SigV4 rule
+ * for a default port, other AWS regions and endpoints have been reported to
+ * want the other one, and the failure is indistinguishable from a wrong
+ * password: a silent 403 on the upgrade. The transport tries the default and
+ * then the fallback, so a user does not have to guess.
+ *
+ * The security token is appended *after* signing and is not part of the
+ * canonical query string. That is specific to IoT's WebSocket flow and is not
+ * how SigV4 normally treats `X-Amz-Security-Token`; including it in the
+ * canonical string produces a signature the endpoint rejects.
+ */
+function presignIotWebsocketUrl(credentials, options = {}) {
+    const { signHostWithPort = false, now } = options;
+    const host = credentials.endpoint;
+    const canonicalHost = signHostWithPort ? `${host}:443` : host;
+    const { amzDate, dateStamp } = amzTimestamps(now);
+    const scope = `${dateStamp}/${credentials.region}/${SERVICE}/aws4_request`;
+    // Query parameters must be in code-point order for the canonical request.
+    // They are written in order here rather than sorted, because a sort on a
+    // list that is already correct is a line nobody checks again.
+    const canonicalQuery = [
+        'X-Amz-Algorithm=AWS4-HMAC-SHA256',
+        `X-Amz-Credential=${uriEncode(`${credentials.accessKeyId}/${scope}`)}`,
+        `X-Amz-Date=${amzDate}`,
+        `X-Amz-Expires=${EXPIRES_SEC}`,
+        'X-Amz-SignedHeaders=host',
+    ].join('&');
+    const canonicalRequest = [
+        'GET',
+        PATH,
+        canonicalQuery,
+        `host:${canonicalHost}`,
+        '',
+        'host',
+        sha256Hex(''),
+    ].join('\n');
+    const stringToSign = [
+        'AWS4-HMAC-SHA256',
+        amzDate,
+        scope,
+        sha256Hex(canonicalRequest),
+    ].join('\n');
+    const signingKey = hmac(hmac(hmac(hmac(`AWS4${credentials.secretKey}`, dateStamp), credentials.region), SERVICE), 'aws4_request');
+    const signature = (0, node_crypto_1.createHmac)('sha256', signingKey).update(stringToSign, 'utf8').digest('hex');
+    return `wss://${host}:443${PATH}?${canonicalQuery}`
+        + `&X-Amz-Signature=${signature}`
+        + `&X-Amz-Security-Token=${uriEncode(credentials.sessionToken)}`;
+}

package/dist/api/topics.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview NaviLink MQTT topic construction.
+ *
+ * Two prefixes, and the difference between them is the thing to understand.
+ *
+ * The **gateway prefix**, `cmd/{deviceType}/navilink-{mac}/`, addresses one
+ * appliance. Requests are published under it, and the gateway publishes its
+ * answers under it too, below `res/`. It contains nothing about who is asking,
+ * so every client watching that appliance sees every answer, including
+ * answers to somebody else's request, such as the NaviLink app on a phone.
+ * That is a feature, not a hazard: a setpoint changed on the wall
+ * controller or in the app reaches this plugin without it asking.
+ *
+ * The **session prefix**, `cmd/{deviceType}/{homeSeq}/{userSeq}/{clientId}/res/`,
+ * is private to one client. A request nominates it as its response topic.
+ *
+ * Both are subscribed. Measured against an NCB-240E: the answers arrived on
+ * the gateway prefix, not the session prefix. Relying on the session prefix
+ * alone would produce a plugin that connects cleanly, subscribes successfully
+ * and then waits forever. So both are taken, and a frame is matched on its
+ * last path segment, not on an exact topic.
+ */
+/** Everything needed to address one gateway. */
+export interface TopicIdentity {
+    /** Gateway MAC, lower-case hex with no separators, as the cloud spells it. */
+    macAddress: string;
+    /** Gateway kind. `1` for every NaviLink gateway seen so far. */
+    deviceType: number;
+    /** Home grouping id from the device list. */
+    homeSeq: string;
+    /** Account sequence number from sign-in. */
+    userSeq: string;
+    /** This client's MQTT client identifier. */
+    clientId: string;
+}
+/** The topics one session uses for one gateway. */
+export interface GatewayTopics {
+    /** Where a channel-info request goes, and where a session announces itself. */
+    start: string;
+    /** Where a channel-status request goes. */
+    statusRequest: string;
+    /** Where a control command goes. */
+    control: string;
+    /** Everything to subscribe to, in one list. */
+    subscriptions: readonly string[];
+    /** The gateway's own last-will topic, announcing an app coming or going. */
+    appConnection: string;
+}
+/**
+ * The response kinds this plugin understands.
+ *
+ * `other` is not an error: the gateway publishes several frame types nobody
+ * here has needed yet, and an unrecognised one should be ignored quietly
+ * rather than logged as a fault on every arrival.
+ */
+export type FrameKind = 'channelinfo' | 'channelstatus' | 'controlfail' | 'connection' | 'other';
+/** The response topic a request nominates for its answer. */
+export declare function responseTopic(identity: TopicIdentity, kind: FrameKind): string;
+/** Build every topic one session needs for one gateway. */
+export declare function buildTopics(identity: TopicIdentity): GatewayTopics;
+/**
+ * Classify an inbound topic by its last segment.
+ *
+ * Deliberately not an exact match against the subscribed list. The two
+ * prefixes produce two topics per frame kind, a gateway can answer on either,
+ * and matching exactly would mean a frame arriving on the unexpected prefix is
+ * silently dropped. That looks exactly like an appliance that has stopped
+ * reporting.
+ */
+export declare function classifyTopic(topic: string): FrameKind;

package/dist/api/topics.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Copyright (c) 2026 tbaur
+ *
+ * Licensed under the Apache License, Version 2.0
+ * See LICENSE file for full license text
+ *
+ * @fileoverview NaviLink MQTT topic construction.
+ *
+ * Two prefixes, and the difference between them is the thing to understand.
+ *
+ * The **gateway prefix**, `cmd/{deviceType}/navilink-{mac}/`, addresses one
+ * appliance. Requests are published under it, and the gateway publishes its
+ * answers under it too, below `res/`. It contains nothing about who is asking,
+ * so every client watching that appliance sees every answer, including
+ * answers to somebody else's request, such as the NaviLink app on a phone.
+ * That is a feature, not a hazard: a setpoint changed on the wall
+ * controller or in the app reaches this plugin without it asking.
+ *
+ * The **session prefix**, `cmd/{deviceType}/{homeSeq}/{userSeq}/{clientId}/res/`,
+ * is private to one client. A request nominates it as its response topic.
+ *
+ * Both are subscribed. Measured against an NCB-240E: the answers arrived on
+ * the gateway prefix, not the session prefix. Relying on the session prefix
+ * alone would produce a plugin that connects cleanly, subscribes successfully
+ * and then waits forever. So both are taken, and a frame is matched on its
+ * last path segment, not on an exact topic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.responseTopic = responseTopic;
+exports.buildTopics = buildTopics;
+exports.classifyTopic = classifyTopic;
+/** Build the gateway prefix. */
+function gatewayPrefix(identity) {
+    return `cmd/${identity.deviceType}/navilink-${identity.macAddress}/`;
+}
+/** Build the session prefix. */
+function sessionPrefix(identity) {
+    return `cmd/${identity.deviceType}/${identity.homeSeq}/${identity.userSeq}/${identity.clientId}/res/`;
+}
+/** The response topic a request nominates for its answer. */
+function responseTopic(identity, kind) {
+    return `${sessionPrefix(identity)}${kind}`;
+}
+/** Build every topic one session needs for one gateway. */
+function buildTopics(identity) {
+    const gateway = gatewayPrefix(identity);
+    const session = sessionPrefix(identity);
+    return {
+        start: `${gateway}status/start`,
+        statusRequest: `${gateway}status/channelstatus`,
+        control: `${gateway}control`,
+        subscriptions: [
+            // The gateway prefix first, because that is where answers actually
+            // arrive, and because it is the path a change made elsewhere reaches us
+            // on.
+            `${gateway}res/channelinfo`,
+            `${gateway}res/channelstatus`,
+            `${gateway}res/controlfail`,
+            `${gateway}connection`,
+            // The session prefix, for a firmware that honours the nominated
+            // response topic. Subscribing to both costs one SUBSCRIBE.
+            `${session}channelinfo`,
+            `${session}channelstatus`,
+            `${session}controlfail`,
+        ],
+        appConnection: `evt/${identity.deviceType}/navilink-${identity.macAddress}/app-connection`,
+    };
+}
+/**
+ * Classify an inbound topic by its last segment.
+ *
+ * Deliberately not an exact match against the subscribed list. The two
+ * prefixes produce two topics per frame kind, a gateway can answer on either,
+ * and matching exactly would mean a frame arriving on the unexpected prefix is
+ * silently dropped. That looks exactly like an appliance that has stopped
+ * reporting.
+ */
+function classifyTopic(topic) {
+    const last = topic.slice(topic.lastIndexOf('/') + 1);
+    switch (last) {
+        case 'channelinfo':
+        case 'channelstatus':
+        case 'controlfail':
+        case 'connection':
+            return last;
+        default:
+            return 'other';
+    }
+}