homematic-manager 3.0.0-beta.32 → 3.0.0-beta.33

package/node_modules/@homematic-manager/backend/dist/api/backend.d.ts

@@ -17,7 +17,9 @@ import { maintenanceAddress, type AppConfig, type ApiEventName, type ApiEvents,
 import { type ConfigStoreOptions } from '../config/store.js';
 import { type DiscoverOptions } from '../discovery/discover.js';
 import { InterfaceManager, type InterfaceManagerOptions } from '../interfaces/manager.js';
+import { LiteInterfaces, type LiteInterfacesOptions } from '../interfaces/lite.js';
 import { type MetaServiceOptions } from '../meta/service.js';
+import { type PairWithSystemOptions } from '../meta/system.js';
 import { RegaService, type RegaServiceOptions } from '../rega/client.js';
 import { ApiEventEmitter } from '../util/emitter.js';
 import { type CallbackNetwork } from '../util/net.js';
@@ -87,6 +89,11 @@ export interface BackendOptions extends Omit<ConfigStoreOptions, 'version'> {
     readonly now?: () => number;
     /** Injected by the tests in place of the real world. */
     readonly createInterfaceManager?: (options: InterfaceManagerOptions) => InterfaceManager;
+    /** Task 72: the same for the openccu-lite path of a remote connection. */
+    readonly createLiteInterfaces?: (options: LiteInterfacesOptions) => LiteInterfaces;
+    readonly liteOptions?: Partial<LiteInterfacesOptions>;
+    /** Task 72: occulite-client's `pair()`, replaced by the tests. */
+    readonly pair?: PairWithSystemOptions['pair'];
     readonly createRega?: (options: RegaServiceOptions) => RegaService;
     /** D-40: injected by the tests, and by the integration test that runs a real occulited. */
     readonly metaOptions?: Partial<MetaServiceOptions>;

package/node_modules/@homematic-manager/backend/dist/api/backend.js

@@ -18,15 +18,16 @@ import { RPC_METHOD_NAMES, RSSI_UNKNOWN, countsAsServiceMessage, isAcknowledgeab
 import { CacheStore } from '../cache/store.js';
 import { ConfigStore } from '../config/store.js';
 import { LinkTemplateStore } from '../config/linkTemplates.js';
-import { validateConnection, writePaceFor } from '../config/defaults.js';
+import { normaliseConnection, validateConnection, writePaceFor } from '../config/defaults.js';
 import { DataFileServer } from '../data/files.js';
 import { installModeCalls } from '../devices/installMode.js';
 import { discoverCcus } from '../discovery/discover.js';
 import { BackendError, configError, connectionError, errorMessage, internalError, isMethodUnsupported, validationError, } from '../errors.js';
 import { DEFAULT_IDLE_UNSUBSCRIBE_MS, InterfaceManager, LOOPBACK_IP, callbackBindHost, firstBidcosInterfaceAddress, } from '../interfaces/manager.js';
+import { LiteInterfaces } from '../interfaces/lite.js';
 import { HeatingGroupsClient } from '../groups/client.js';
 import { MetaService, hostBaseUrl } from '../meta/service.js';
-import { DETECT_TIMEOUT_MS, detectSystem, transportFor } from '../meta/system.js';
+import { DETECT_TIMEOUT_MS, detectSystem, pairWithSystem, testSystem, transportFor, } from '../meta/system.js';
 import { RegaService } from '../rega/client.js';
 import { listDevicesAnswer } from '../rpc/server.js';
 import { ApiEventEmitter } from '../util/emitter.js';
@@ -77,7 +78,16 @@ export class Backend {
     #now;
     #methodCache = new Map();
     #caches;
+    /**
+     * Task 72: the interface processes - through callback servers and `init` on a CCU (and on the
+     * system itself, where the addon runs), through lite-rpc on an openccu-lite system reached from
+     * off it. Everything below the API talks to the {@link Interfaces} surface and nothing else.
+     */
     #manager;
+    /** Task 72: counts the connects, so a connect that waited for the probe knows it is still the current one. */
+    #connectSeq = 0;
+    /** Task 72: the pairing with an openccu-lite system that is running, if any. */
+    #pairing;
     #rega;
     /** D-40: the metadata store of this connection - this profile's own, or an openccu-lite box. */
     #meta;
@@ -358,6 +368,12 @@ export class Backend {
                 return this.#clearCaches();
             case 'config.callbackAddresses':
                 return this.#callbackAddresses(p[0]);
+            case 'connection.test':
+                return this.#testConnection(p[0]);
+            case 'connection.pair':
+                return this.#startPairing(p[0]);
+            case 'connection.pairCancel':
+                return this.#cancelPairing();
             case 'interfaces.list':
                 return this.#manager?.states() ?? [];
             case 'interfaces.reconnect':
@@ -592,12 +608,34 @@ export class Backend {
     }
     async #connectNow() {
         const connection = this.#config.connection;
+        const seq = ++this.#connectSeq;
         this.#paramsetIds.clear();
         this.#noServiceMessages.clear();
         this.#serviceMessageFailures.clear();
         this.#listedMethods.clear();
         this.#noListMethods.clear();
-        const manager = (this.#options.createInterfaceManager ?? ((options) => new InterfaceManager(options)))({
+        // Task 72: a connection from off the system with an API token may be one to an openccu-lite
+        // system, which never calls a remote client back (its D-70): the probe decides *before* the
+        // interfaces are started, and its answer picks lite-rpc over callback servers. Only then is
+        // the probe waited for - for everybody else (the addon on the system, a profile without a
+        // token, every CCU) it runs alongside the interface start as before (D-40's rule: a host
+        // that swallows the packet holds up the names, never the interfaces).
+        const token = (connection.metaToken ?? '').trim();
+        const mayBeRemoteLite = connection.local !== true && token !== '';
+        let hostProbe;
+        let liteProbe;
+        if (mayBeRemoteLite) {
+            liteProbe = await this.#probeHost(connection);
+            if (this.#stopped || seq !== this.#connectSeq) {
+                // disconnected while the host was being asked
+                return;
+            }
+            hostProbe = Promise.resolve(liteProbe);
+        }
+        else {
+            hostProbe = this.#probeHost(connection);
+        }
+        const shared = {
             connection,
             handler: this.#callbackHandler(),
             onStateChanged: (states) => {
@@ -611,27 +649,45 @@ export class Backend {
                 this.#onCall(record);
             },
             originOf: currentOrigin,
-            ...(this.#options.callbackHost === undefined ? {} : { callbackHost: this.#options.callbackHost }),
-            ...(this.#options.defaultCallbackPorts === undefined
-                ? {}
-                : { defaultCallbackPorts: this.#options.defaultCallbackPorts }),
-            ...(this.#config.callbackPins === undefined ? {} : { callbackPins: this.#config.callbackPins }),
-            // B-69: read at every watchdog round - the cache is replaced when the host changes
-            listsDevices: (interfaceName) => this.#caches.devices.size(interfaceName) > 0,
-            ...(this.#options.rpcTimeoutMs === undefined ? {} : { rpcTimeoutMs: this.#options.rpcTimeoutMs }),
-            ...(this.#options.watchdogIntervalMs === undefined
-                ? {}
-                : { watchdogIntervalMs: this.#options.watchdogIntervalMs }),
-            ...(this.#options.localAddresses === undefined ? {} : { localAddresses: this.#options.localAddresses }),
-            ...(this.#options.network === undefined ? {} : { network: this.#options.network }),
-            ...(this.#keepsConfiguredCallbackIp() ? { keepConfiguredCallbackIp: true } : {}),
-            ...(this.#options.now === undefined ? {} : { now: this.#options.now }),
-            ...this.#options.interfaceManagerOptions,
-        });
+        };
+        const manager = liteProbe?.answer !== undefined
+            ? (this.#options.createLiteInterfaces ?? ((options) => new LiteInterfaces(options)))({
+                ...shared,
+                baseUrl: liteProbe.baseUrl ?? hostBaseUrl(connection),
+                token,
+                transport: transportFor({
+                    fetch: this.#options.metaOptions?.fetch,
+                    trust: connection.systemTrust,
+                }),
+                ...(this.#options.rpcTimeoutMs === undefined ? {} : { rpcTimeoutMs: this.#options.rpcTimeoutMs }),
+                ...(this.#options.now === undefined ? {} : { now: this.#options.now }),
+                ...this.#options.liteOptions,
+            })
+            : (this.#options.createInterfaceManager ?? ((options) => new InterfaceManager(options)))({
+                ...shared,
+                ...(this.#options.callbackHost === undefined ? {} : { callbackHost: this.#options.callbackHost }),
+                ...(this.#options.defaultCallbackPorts === undefined
+                    ? {}
+                    : { defaultCallbackPorts: this.#options.defaultCallbackPorts }),
+                ...(this.#config.callbackPins === undefined ? {} : { callbackPins: this.#config.callbackPins }),
+                // B-69: read at every watchdog round - the cache is replaced when the host changes
+                listsDevices: (interfaceName) => this.#caches.devices.size(interfaceName) > 0,
+                ...(this.#options.rpcTimeoutMs === undefined ? {} : { rpcTimeoutMs: this.#options.rpcTimeoutMs }),
+                ...(this.#options.watchdogIntervalMs === undefined
+                    ? {}
+                    : { watchdogIntervalMs: this.#options.watchdogIntervalMs }),
+                ...(this.#options.localAddresses === undefined
+                    ? {}
+                    : { localAddresses: this.#options.localAddresses }),
+                ...(this.#options.network === undefined ? {} : { network: this.#options.network }),
+                ...(this.#keepsConfiguredCallbackIp() ? { keepConfiguredCallbackIp: true } : {}),
+                ...(this.#options.now === undefined ? {} : { now: this.#options.now }),
+                ...this.#options.interfaceManagerOptions,
+            });
         this.#manager = manager;
-        // B-62: is the host an openccu-lite system? Asked alongside the interface start, so that a
-        // host which swallows the packet holds up the names, never the interfaces (D-40's rule).
-        const hostProbe = this.#probeHost(connection);
+        if (liteProbe?.answer !== undefined) {
+            this.#notice('info', `${connection.host}: an openccu-lite system - the interfaces are reached through its lite-rpc with the API token, without callbacks`);
+        }
         try {
             await manager.start();
         }
@@ -717,6 +773,7 @@ export class Backend {
         };
     }
     async #disconnect() {
+        this.#connectSeq += 1;
         this.#clearTimers();
         this.#queue.cancel();
         await this.#manager?.stop();
@@ -1006,6 +1063,83 @@ export class Backend {
         const origin = currentOrigin();
         return this.#queue.enqueue(interfaceName, () => client.call(method, params, { origin }));
     }
+    /*
+     * task 72: the connection test and the pairing with an openccu-lite system
+     */
+    /** `connection.test`: what is at the draft's host, and what its token is worth there. */
+    async #testConnection(input) {
+        const connection = normaliseConnection(input);
+        const baseUrl = hostBaseUrl(connection);
+        if (baseUrl === '') {
+            throw validationError('no CCU address configured');
+        }
+        return testSystem(transportFor({ fetch: this.#options.metaOptions?.fetch, trust: connection.systemTrust }), baseUrl, (connection.metaToken ?? '').trim(), this.#options.metaOptions?.detectTimeoutMs ?? DETECT_TIMEOUT_MS);
+    }
+    /**
+     * `connection.pair`: asks the system for a token and answers at once; the steps come as
+     * `pairing.changed` (openccu-lite task 219: the code is shown here and on the system's Status
+     * page, an administrator approves it there). One pairing at a time - a new one cancels the old.
+     */
+    #startPairing(input) {
+        const connection = normaliseConnection(input);
+        const baseUrl = hostBaseUrl(connection);
+        if (baseUrl === '') {
+            throw validationError('no CCU address configured');
+        }
+        this.#cancelPairing();
+        const controller = new AbortController();
+        this.#pairing = controller;
+        this.events.emit('pairing.changed', { state: 'requesting' });
+        void this.#runPairing(connection, baseUrl, controller);
+        return null;
+    }
+    async #runPairing(connection, baseUrl, controller) {
+        const current = () => this.#pairing === controller;
+        try {
+            const paired = await pairWithSystem({
+                transport: transportFor({ fetch: this.#options.metaOptions?.fetch, trust: connection.systemTrust }),
+                baseUrl,
+                appVersion: this.#config.config.version,
+                detectTimeoutMs: this.#options.metaOptions?.detectTimeoutMs ?? DETECT_TIMEOUT_MS,
+                signal: controller.signal,
+                onCode: (code) => {
+                    if (current()) {
+                        this.events.emit('pairing.changed', { state: 'code', code });
+                    }
+                },
+                ...(this.#options.pair === undefined ? {} : { pair: this.#options.pair }),
+            });
+            if (!current()) {
+                return;
+            }
+            this.#pairing = undefined;
+            this.events.emit('pairing.changed', {
+                state: 'approved',
+                token: paired.token,
+                fingerprint256: paired.fingerprint256,
+                scopes: paired.scopes,
+                name: paired.name,
+            });
+        }
+        catch (error) {
+            if (!current()) {
+                // cancelled, or replaced by a newer one: that one said so
+                return;
+            }
+            this.#pairing = undefined;
+            this.events.emit('pairing.changed', { state: 'failed', message: errorMessage(error) });
+        }
+    }
+    /** `connection.pairCancel`: withdraws the request, on the system too (the client does that). */
+    #cancelPairing() {
+        const controller = this.#pairing;
+        if (controller !== undefined) {
+            this.#pairing = undefined;
+            controller.abort();
+            this.events.emit('pairing.changed', { state: 'cancelled' });
+        }
+        return null;
+    }
     /*
      * configuration
      */
@@ -1951,6 +2085,9 @@ export const API_METHOD_NAMES = [
     'config.discover',
     'config.clearCaches',
     'config.callbackAddresses',
+    'connection.test',
+    'connection.pair',
+    'connection.pairCancel',
     'interfaces.list',
     'interfaces.reconnect',
     'rega.state',

package/node_modules/@homematic-manager/backend/dist/interfaces/lite.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Task 72: the interfaces of an openccu-lite system, reached from off the system.
+ *
+ * A CCU calls its clients back, so `manager.ts` runs callback servers and subscribes to every
+ * interface process with `init`. openccu-lite does not call a remote client at all (its D-70): the
+ * requests go to the system's web port - lite-rpc's JSON-RPC path, one per interface, with the
+ * profile's API token - and the events come from a stream the client opens itself. occulite-client
+ * owns that stream and its reliability: reconnect with backoff, resume by the last event id, a
+ * `resync` after a gap or another boot of the system. What is left here is this application's:
+ *
+ * - the {@link Interfaces} surface the backend talks to, so the write queue, the RPC log and every
+ *   `ApiMethods` handler are the same code on both paths;
+ * - the stream's events handed to the very same {@link CallbackHandler} the callback servers feed,
+ *   so the grids, the service messages and the event log do not know where an event came from;
+ * - the state per interface as the popup shows it, from the system's interface list and the
+ *   client's status;
+ * - the errors as the backend knows them: a fault of the interface process stays a fault, a
+ *   scope the token lacks is said as such and never taken for a lost connection (task 78's tiers).
+ *
+ * The CCU path is untouched: on the system itself the addon keeps its loopback callbacks
+ * (maintainer, 2026-09-27: "remote only"), and a CCU never gets here at all.
+ */
+import { OccuLite, type Options as OccuLiteOptions, type Transport } from 'occulite-client';
+import { type ConnectionConfig, type InterfaceState, type ResolvedInterface, type RpcOrigin, type RpcValue } from '@homematic-manager/core';
+import type { RpcCallRecord, RpcOutValue } from '../rpc/client.js';
+import type { CallbackHandler } from '../rpc/server.js';
+import type { InterfaceLink, Interfaces } from './manager.js';
+/**
+ * The waits between two attempts to reach a system that does not answer: quick at first (it may be
+ * booting), then a minute. A remote system that is off for the night is not asked every two seconds.
+ */
+export declare const LITE_RETRY_DELAYS_MS: readonly number[];
+/** How long one request may take; the same as the CCU path's clients. */
+export declare const LITE_RPC_TIMEOUT_MS = 20000;
+/** How long the first picture - the version, the credential, the interfaces, the values - may take. */
+export declare const LITE_CONNECT_TIMEOUT_MS = 30000;
+export interface LiteInterfacesOptions {
+    readonly connection: ConnectionConfig;
+    /** Where the system answered the detection: `https://…` when it redirected there (B-67). */
+    readonly baseUrl: string;
+    /** The profile's API token (`metaToken`); paired, or made on the system's API tokens page. */
+    readonly token: string;
+    /** The transport with the profile's certificate trust (`systemTransport`). */
+    readonly transport: Transport;
+    /** What the stream's events become - the same handler the callback servers feed. */
+    readonly handler: CallbackHandler;
+    readonly onStateChanged: (states: InterfaceState[]) => void;
+    readonly onNotice: (level: 'debug' | 'info' | 'warn' | 'error', message: string, interfaceName?: string) => void;
+    /** Called once an interface is reachable - the backend fills its caches there. */
+    readonly onConnected?: (interfaceName: string) => void | Promise<void>;
+    readonly onCall?: (record: RpcCallRecord) => void;
+    /** Task 48: the origin of a call that names none (the backend's request context). */
+    readonly originOf?: () => RpcOrigin;
+    readonly now?: () => number;
+    readonly rpcTimeoutMs?: number;
+    readonly connectTimeoutMs?: number;
+    /** The retry schedule after a system that does not answer; {@link LITE_RETRY_DELAYS_MS}. */
+    readonly retryDelaysMs?: readonly number[];
+    /** Injected by the tests. */
+    readonly createClient?: (options: OccuLiteOptions) => OccuLite;
+}
+/**
+ * A value as lite-rpc's JSON path takes it. The core writes a `FLOAT` as `{explicitDouble: n}` for
+ * the XML-RPC and BIN-RPC encoders; the JSON path types a double as `{"double": n}` where the system
+ * says it understands that (`json_double`, openccu-lite task 196's S2), and takes the plain number
+ * everywhere else - a fraction is a double either way, only a whole number needs the hint.
+ */
+export declare function toWire(value: RpcOutValue, typedDouble: boolean): unknown;
+/**
+ * An answer of the JSON path as an `RpcValue`: JSON has `null` where XML-RPC has an empty string
+ * (a method without a result), and nothing else the contract does not know.
+ */
+export declare function fromWire(value: unknown): RpcValue;
+/** The interfaces of an openccu-lite system, over occulite-client. */
+export declare class LiteInterfaces implements Interfaces {
+    #private;
+    constructor(options: LiteInterfacesOptions);
+    get idle(): boolean;
+    /** The client in use, for a test and for the backend's values (task 68). */
+    get box(): OccuLite | undefined;
+    states(): InterfaceState[];
+    client(interfaceName: string): InterfaceLink;
+    isConnected(interfaceName: string): boolean;
+    names(): string[];
+    resolved(interfaceName: string): ResolvedInterface | undefined;
+    /**
+     * Builds the entries and opens the client. Resolves once the first attempt is through - a
+     * system that does not answer leaves an error in every state and is tried again; it does not
+     * throw.
+     */
+    start(): Promise<void>;
+    /** D-31: closes the stream and forgets nothing; {@link subscribe} opens it again. */
+    unsubscribe(): Promise<void>;
+    subscribe(): Promise<void>;
+    /**
+     * `interfaces.reconnect`: the user saying "try now". A client that is not up is opened again at
+     * once (a token pasted after a refusal, a system that came back); one that is up re-reads the
+     * interface's devices, which is all a subscription-less path has to redo.
+     */
+    reconnect(interfaceName?: string): Promise<void>;
+    /** Closes the stream; nothing is de-registered, because nothing was registered. */
+    stop(): Promise<void>;
+    noteEvent(interfaceName: string, kind?: 'event' | 'device'): void;
+}
+//# sourceMappingURL=lite.d.ts.map