homematic-manager 3.0.0-beta.2 → 3.0.0-beta.21

package/node_modules/@homematic-manager/backend/dist/meta/regaProvider.js

@@ -0,0 +1,403 @@
+/**
+ * The `rega` metadata provider (task 27): the CCU's own rooms and functions, through ReGaHSS.
+ *
+ * On a CCU the rooms and functions the user sees in the WebUI live in ReGa's DOM - enum objects
+ * under `ID_ROOMS` and `ID_FUNCTIONS`, each holding channel ids - and a taxonomy kept in this
+ * profile beside them would be a second truth. So on a CCU with ReGa this provider *is* the store:
+ * the same {@link MetadataProvider} surface the box's provider has, over the same script transport
+ * the names already use, so that the editing UI of task 25 does not know which one it talks to.
+ *
+ * What ReGa's model is, and therefore what this provider is:
+ *
+ * - **Flat.** A room is a room; there is no room below another and no floor. `state().flat` says
+ *   so, `createNode` with a parent and a move under a parent are refused.
+ * - **Two taxonomies, fixed.** Rooms and functions exist; nothing else can be created or deleted.
+ * - **Channels are members, devices are not.** The WebUI assigns channels. A device ref in a
+ *   membership write is applied to every channel of the device except the `:0` maintenance
+ *   channel, which is what a user who "puts the device in the kitchen" means.
+ * - **Identity is the ReGa id.** A node's id is `r<id>`, stable across renames, so a path never
+ *   has to be rewritten when a room is renamed.
+ * - **No change stream.** ReGa tells nobody when the WebUI edits a room. This provider reads
+ *   everything on `start()`, after every write of its own, and on `refresh()`, which the UI asks
+ *   for through `meta.refresh`.
+ *
+ * Failure is a state, never an exception (D-2): a script that does not run leaves the last
+ * document in place, sets `reachable: false` and says so once.
+ */
+import { MetaError, makeRef, normaliseName, parsePath, } from '@homematic-manager/core';
+import { errorMessage } from '../errors.js';
+import { createEnumNodeScript, deleteEnumNodeScript, membershipScript, META_READ_SCRIPT, parseCreatedId, parseMetaSnapshot, renameObjectsScript, } from '../rega/scripts.js';
+const ENUM_NAMES = {
+    room: { de: 'Räume', en: 'Rooms' },
+    function: { de: 'Gewerke', en: 'Functions' },
+};
+/**
+ * The rooms and functions a CCU comes with, as the WebUI translates them (`translate.lang.js` of
+ * the German and the English WebUI, firmware 3.89.8). ReGa's objects carry the *key* as their
+ * `Name()` - `roomKitchen`, not `Küche` - and every WebUI page translates it on display, so a list
+ * that shows the keys is not what the user sees on the CCU. Found in the first lab pass of task 27.
+ * A name that is not one of these keys is shown as it is; a rename writes the literal name.
+ */
+export const REGA_STOCK_NAMES = {
+    roomLivingRoom: { de: 'Wohnzimmer', en: 'Living room' },
+    roomKitchen: { de: 'Küche', en: 'Kitchen' },
+    roomBedroom: { de: 'Schlafzimmer', en: 'Bed room' },
+    roomChildrensRoom1: { de: 'Kinderzimmer 1', en: "Children's room 1" },
+    roomChildrensRoom2: { de: 'Kinderzimmer 2', en: "Children's room 2" },
+    roomOffice: { de: 'Büro', en: 'Home office' },
+    roomBathroom: { de: 'Badezimmer', en: 'Bathroom' },
+    roomGarage: { de: 'Garage', en: 'Garage' },
+    roomHWR: { de: 'Hauswirtschaftsraum', en: 'Utility room' },
+    roomGarden: { de: 'Garten', en: 'Garden' },
+    roomTerrace: { de: 'Terrasse', en: 'Terrace' },
+    funcLight: { de: 'Licht', en: 'Light' },
+    funcHeating: { de: 'Heizung', en: 'Heating' },
+    funcClimateControl: { de: 'Klima', en: 'Climatic conditions' },
+    funcWeather: { de: 'Wetter', en: 'Weather' },
+    funcEnvironment: { de: 'Umwelt', en: 'Environment' },
+    funcSecurity: { de: 'Sicherheit', en: 'Security' },
+    funcLock: { de: 'Verschluss', en: 'Lock' },
+    funcButton: { de: 'Taster', en: 'Button' },
+    funcCentral: { de: 'Zentrale', en: 'Central control unit' },
+    funcEnergy: { de: 'Energiemanagement', en: 'Energy management' },
+};
+/** `roomKitchen` -> `Küche`; anything that is not a stock key is answered as it is. */
+export function regaStockName(name, language) {
+    const stock = REGA_STOCK_NAMES[name];
+    if (stock === undefined) {
+        return name;
+    }
+    // the WebUI has German and English; the CCU's own default is German
+    return language === 'en' ? stock.en : stock.de;
+}
+/** `r4711` - the node id of a ReGa enum object; stable across renames. */
+export function regaNodeId(id) {
+    return `r${String(id)}`;
+}
+/** The ReGa id behind a node id, or `undefined` for anything that is not one. */
+export function parseRegaNodeId(id) {
+    const match = /^r(\d+)$/.exec(id);
+    return match ? Number(match[1]) : undefined;
+}
+export class RegaMetaProvider {
+    kind = 'rega';
+    #options;
+    /** By ref. */
+    #objects = new Map();
+    /** By ReGa id, for the membership sets. */
+    #byId = new Map();
+    #enums = { room: new Map(), function: new Map() };
+    #document;
+    #revision = 0;
+    #reachable = false;
+    #error;
+    #lastNotice = '';
+    constructor(options) {
+        this.#options = options;
+    }
+    state() {
+        return {
+            provider: 'rega',
+            reachable: this.#reachable,
+            // ReGa takes every write from whoever may run a script; there is no read-only credential
+            writable: this.#reachable,
+            revision: this.#revision,
+            objects: this.#objects.size,
+            flat: true,
+            ...(this.#error === undefined ? {} : { error: this.#error }),
+        };
+    }
+    async start() {
+        await this.refresh();
+    }
+    stop() {
+        return Promise.resolve();
+    }
+    /** Reads everything again. Never throws: a ReGa that does not answer is a state. */
+    async refresh() {
+        let snapshot;
+        try {
+            const answer = await this.#options.exec(META_READ_SCRIPT);
+            snapshot = parseMetaSnapshot(answer.output);
+        }
+        catch (error) {
+            this.#fail(error);
+            return;
+        }
+        this.#load(snapshot);
+        this.#reachable = true;
+        this.#error = undefined;
+        this.#lastNotice = '';
+        this.#revision += 1;
+        this.#announce();
+    }
+    document() {
+        this.#document ??= this.#build();
+        return this.#document;
+    }
+    async setNames(entries) {
+        const renames = [];
+        for (const entry of entries) {
+            const object = this.#objects.get(entry.ref);
+            if (object === undefined) {
+                // an address ReGa has never reported can only be named locally, as before (D-2)
+                continue;
+            }
+            const name = normaliseName(entry.name);
+            if (name !== object.name) {
+                renames.push({ object, name });
+            }
+        }
+        const script = renameObjectsScript(renames.map((entry) => ({ id: entry.object.id, name: entry.name })));
+        if (script === undefined) {
+            return;
+        }
+        await this.#run(script);
+        for (const entry of renames) {
+            entry.object.name = entry.name;
+        }
+        this.#commit();
+    }
+    async setMembership(entries) {
+        const changes = [];
+        for (const entry of entries) {
+            const wanted = this.#targetsOf(entry.paths);
+            for (const object of this.#membersFor(entry.ref)) {
+                for (const kind of ['room', 'function']) {
+                    for (const [id, node] of this.#enums[kind]) {
+                        const has = node.channels.has(object.id);
+                        const should = wanted[kind].has(id);
+                        if (has !== should) {
+                            changes.push({ enumId: id, channelId: object.id, on: should });
+                        }
+                    }
+                }
+            }
+        }
+        const script = membershipScript(changes);
+        if (script === undefined) {
+            return;
+        }
+        await this.#run(script);
+        for (const change of changes) {
+            const node = this.#nodeById(change.enumId);
+            if (node) {
+                if (change.on) {
+                    node.channels.add(change.channelId);
+                }
+                else {
+                    node.channels.delete(change.channelId);
+                }
+            }
+        }
+        this.#commit();
+    }
+    createEnum() {
+        return Promise.reject(fixedEnums());
+    }
+    updateEnum() {
+        return Promise.reject(fixedEnums());
+    }
+    deleteEnum() {
+        return Promise.reject(fixedEnums());
+    }
+    /**
+     * A new room or function. The id the caller derived from the name is not used: ReGa hands out
+     * the id, and `r<id>` is what keeps the path stable when the room is renamed later.
+     */
+    async createNode(enumId, parent, _id, name) {
+        const kind = requireKind(enumId);
+        if (parent !== null && parent !== enumId) {
+            throw new MetaError('too-deep', 'ReGa rooms and functions are a flat list: no node below another');
+        }
+        const nodeName = normaliseName(name);
+        const answer = await this.#run(createEnumNodeScript(kind, nodeName));
+        const id = parseCreatedId(answer.output);
+        if (id === undefined) {
+            // the object may or may not exist now; the next read says which
+            await this.refresh();
+            throw new MetaError('unknown-path', `ReGa did not answer with the id of the new ${kind}`);
+        }
+        this.#enums[kind].set(id, { id, name: nodeName, channels: new Set() });
+        this.#commit();
+        return `${kind}/${regaNodeId(id)}`;
+    }
+    async updateNode(path, patch) {
+        const { kind, node } = this.#requireNode(path);
+        if (patch.parent !== undefined && patch.parent !== null && patch.parent !== kind) {
+            throw new MetaError('invalid-move', 'ReGa rooms and functions are a flat list: nothing can be moved below another');
+        }
+        // `icon` and `position` have no counterpart in ReGa and are accepted without effect
+        if (patch.name === undefined) {
+            return;
+        }
+        const name = normaliseName(patch.name);
+        if (name === node.name || name === this.#displayName(node)) {
+            // the same name again is not a write - nor is the translation of a stock key
+            return;
+        }
+        const script = renameObjectsScript([{ id: node.id, name }]);
+        if (script === undefined) {
+            return;
+        }
+        await this.#run(script);
+        node.name = name;
+        this.#commit();
+    }
+    async deleteNode(path, detach) {
+        const { kind, node } = this.#requireNode(path);
+        const refs = [...node.channels]
+            .map((id) => this.#byId.get(id)?.ref)
+            .filter((ref) => ref !== undefined)
+            .sort((a, b) => a.localeCompare(b));
+        if (refs.length > 0 && !detach) {
+            throw new MetaError('has-members', `${path} still has members`, { refs });
+        }
+        await this.#run(deleteEnumNodeScript(kind, node.id));
+        this.#enums[kind].delete(node.id);
+        this.#commit();
+    }
+    import() {
+        return Promise.reject(new MetaError('forbidden', 'a ReGa store cannot be replaced by an import'));
+    }
+    /*
+     * the model
+     */
+    #load(snapshot) {
+        this.#objects.clear();
+        this.#byId.clear();
+        for (const entry of snapshot.objects) {
+            const interfaceName = entry.interfaceName !== '' ? entry.interfaceName : this.#options.interfaceOf(entry.address);
+            if (interfaceName === undefined || interfaceName === '') {
+                // no ref without an interface; the name cache still gets it through ReGa's names
+                continue;
+            }
+            const object = {
+                id: entry.id,
+                address: entry.address,
+                ref: makeRef(interfaceName, entry.address),
+                name: entry.name,
+            };
+            this.#objects.set(object.ref, object);
+            this.#byId.set(object.id, object);
+        }
+        for (const kind of ['room', 'function']) {
+            const nodes = this.#enums[kind];
+            nodes.clear();
+            for (const entry of kind === 'room' ? snapshot.rooms : snapshot.functions) {
+                nodes.set(entry.id, { id: entry.id, name: entry.name, channels: new Set(entry.channels) });
+            }
+        }
+        this.#document = undefined;
+    }
+    /** The document as the rest of the application reads it, rebuilt lazily after a change. */
+    #build() {
+        const objects = {};
+        for (const object of this.#objects.values()) {
+            const paths = [];
+            for (const kind of ['room', 'function']) {
+                for (const node of this.#enums[kind].values()) {
+                    if (node.channels.has(object.id)) {
+                        paths.push(`${kind}/${regaNodeId(node.id)}`);
+                    }
+                }
+            }
+            objects[object.ref] = { name: object.name, enums: paths, meta: {} };
+        }
+        const enums = {};
+        for (const kind of ['room', 'function']) {
+            const tree = [...this.#enums[kind].values()]
+                .sort((a, b) => this.#displayName(a).localeCompare(this.#displayName(b), 'de') || a.id - b.id)
+                .map((node) => ({ id: regaNodeId(node.id), name: this.#displayName(node) }));
+            enums[kind] = { name: { ...ENUM_NAMES[kind] }, tree };
+        }
+        return { format: 1, revision: this.#revision, objects, enums };
+    }
+    /** The channels a membership write addresses: the channel itself, or every channel of a device. */
+    #membersFor(ref) {
+        const object = this.#objects.get(ref);
+        if (object === undefined) {
+            throw new MetaError('unknown-object', `${ref} is not known to ReGa`);
+        }
+        if (object.address.includes(':')) {
+            return [object];
+        }
+        const prefix = `${object.address}:`;
+        return [...this.#objects.values()].filter((candidate) => candidate.address.startsWith(prefix) && !candidate.address.endsWith(':0'));
+    }
+    /** The ReGa ids the wanted paths name, per kind; a path that is not a node here is refused. */
+    #targetsOf(paths) {
+        const targets = { room: new Set(), function: new Set() };
+        for (const path of paths) {
+            const { kind, node } = this.#requireNode(path);
+            targets[kind].add(node.id);
+        }
+        return targets;
+    }
+    #requireNode(path) {
+        const parsed = parsePath(path);
+        const kind = parsed === undefined ? undefined : toKind(parsed.enumId);
+        const id = parsed?.ids.length === 1 ? parseRegaNodeId(parsed.ids[0] ?? '') : undefined;
+        const node = kind === undefined || id === undefined ? undefined : this.#enums[kind].get(id);
+        if (kind === undefined || node === undefined) {
+            throw new MetaError('unknown-path', `${path} is not a room or function of this CCU`);
+        }
+        return { kind, node };
+    }
+    /** What the WebUI shows for this node: the stock key translated, anything else as it is. */
+    #displayName(node) {
+        return regaStockName(node.name, this.#options.language);
+    }
+    #nodeById(id) {
+        return this.#enums.room.get(id) ?? this.#enums.function.get(id);
+    }
+    /** One script, with the outcome reflected in the state; the error goes on to the caller. */
+    async #run(script) {
+        try {
+            const answer = await this.#options.exec(script);
+            if (!this.#reachable) {
+                this.#reachable = true;
+                this.#error = undefined;
+                this.#options.onStateChanged(this.state());
+            }
+            return answer;
+        }
+        catch (error) {
+            this.#fail(error);
+            throw error;
+        }
+    }
+    #commit() {
+        this.#document = undefined;
+        this.#revision += 1;
+        this.#announce();
+    }
+    #announce() {
+        this.#options.onStateChanged(this.state());
+        this.#options.onChanged();
+    }
+    #fail(error) {
+        const message = errorMessage(error);
+        this.#reachable = false;
+        this.#error = message;
+        this.#options.onStateChanged(this.state());
+        if (message !== this.#lastNotice) {
+            this.#lastNotice = message;
+            this.#options.onNotice('warn', `ReGa did not answer the rooms and functions script: ${message}`);
+        }
+    }
+}
+function toKind(enumId) {
+    return enumId === 'room' || enumId === 'function' ? enumId : undefined;
+}
+function requireKind(enumId) {
+    const kind = toKind(enumId);
+    if (kind === undefined) {
+        throw new MetaError('unknown-enum', `${enumId}: ReGa has rooms and functions and nothing else`);
+    }
+    return kind;
+}
+function fixedEnums() {
+    return new MetaError('forbidden', 'ReGa has a fixed set of taxonomies - rooms and functions - that cannot be changed');
+}
+//# sourceMappingURL=regaProvider.js.map

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

@@ -0,0 +1,137 @@
+/**
+ * D-40: which metadata provider is in charge, and everything the backend calls on it.
+ *
+ * The selection is openccu-lite's rule and no other: **`GET /api/meta/v1/version` on the configured
+ * host**, once per connect. A box answers with `{"api":"meta",…}` and its store is used; a CCU
+ * answers 404 or HTML and everything stays as it was. No `/VERSION` sniffing, no host names, no
+ * ports - a user who moves a profile between a CCU and a box must not have to edit anything
+ * (their invariant 2). `metaProvider: 'local'` skips the probe, `'occulite'` insists on the box.
+ * Task 27 adds the third answer: with no box, a ReGa that is on and answered
+ * (`options.rega.available`) becomes the store - its rooms and functions are the CCU's own - and
+ * `'rega'` insists on that.
+ *
+ * The service is also where the store's identity meets this application's. The store keys objects
+ * by **ref** (`<interface>.<address>`); the grids, the caches and the whole existing API key names
+ * by address, because a Homematic address is unique across the interfaces of one CCU in practice.
+ * So the ref is resolved here, in one place, from the device caches - and never guessed anywhere
+ * else.
+ */
+import { type ConnectionConfig, type MetaDocument, type MetaEnum, type MetaImportMode, type MetaNodePatch, type MetaObjectView, type MetaState, type MetaVersion } from '@homematic-manager/core';
+import type { NameStore } from '../cache/names.js';
+import { type RegaScriptRunner } from './regaProvider.js';
+/** What the service needs to know about ReGa to offer it as a provider (task 27). */
+export interface MetaRegaLink {
+    /** ReGa is on and has answered at least once - the `auto` choice takes it only then. */
+    readonly available: boolean;
+    readonly exec: RegaScriptRunner;
+}
+/** One name to set, as the rest of the backend spells it: by address. */
+export interface MetaNameChange {
+    readonly address: string;
+    readonly name: string;
+}
+export interface MetaServiceOptions {
+    readonly connection: ConnectionConfig;
+    /** The profile directory; the `local` store lives in it. */
+    readonly dataDir: string;
+    /** The per-CCU cache directory; the box's last snapshot lives in it. */
+    readonly cacheDir: string;
+    /** The name cache the whole application reads; the provider's names are applied to it. */
+    readonly names: NameStore;
+    /** Which interface a device or channel address belongs to, from the device caches. */
+    readonly interfaceOf: (address: string) => string | undefined;
+    /**
+     * The ReGa of this connection, when it is switched on; absent otherwise. `auto` picks it when
+     * there is no box and it answered, `rega` insists on it.
+     */
+    readonly rega?: MetaRegaLink | undefined;
+    /** The document changed: names, enums or objects. */
+    readonly onChanged: () => void;
+    readonly onStateChanged: (state: MetaState) => void;
+    readonly onNotice: (level: 'info' | 'warn' | 'error', message: string) => void;
+    /** Injected by the tests. */
+    readonly localTokenFile?: string | undefined;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly detectTimeoutMs?: number;
+}
+/**
+ * The base URL of the box.
+ *
+ * `local` means "we are the addon on the box itself", where everything is behind the loopback
+ * lighttpd; otherwise it is the configured host with the scheme the profile uses for the CCU.
+ * `metaUrl` overrides both, for a reverse proxy on a strange port and for the integration tests.
+ */
+export declare function metaBaseUrl(connection: ConnectionConfig): string;
+/** Everything the metadata store is, for one connection. */
+export declare class MetaService {
+    #private;
+    private constructor();
+    /**
+     * Probes the box and builds the provider that fits.
+     *
+     * Never throws: a probe that fails means "no box", which is what every CCU, every Homegear and
+     * every desktop answers, and the `local` provider is a complete answer to it.
+     */
+    static create(options: MetaServiceOptions): Promise<MetaService>;
+    get kind(): 'local' | 'occulite' | 'rega';
+    /** True when this connection talks to an openccu-lite box. */
+    get onBox(): boolean;
+    state(): MetaState;
+    document(): MetaDocument;
+    enums(): Readonly<Record<string, MetaEnum>>;
+    /** Every object as the UI shows it: the name, the paths, and the paths as names. */
+    objects(): Record<string, MetaObjectView>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Reads the store again - what `meta.refresh` is, and what a ReGa without a change stream needs. */
+    refresh(): Promise<void>;
+    /**
+     * The session the addon should write as (openccu-lite's embedding contract: `?sid=@…@`).
+     *
+     * Reads keep using the box's local token, which is read-only by design; a write is attributed
+     * to the person who opened the page. Without a session the writes go out with whatever the
+     * reads use, which on the box means the box answers 403 and the UI says so.
+     */
+    setSessionCredential(sid: string | undefined): void;
+    /** Copies the store's names into the name cache. Returns true when anything changed. */
+    applyNames(): boolean;
+    /** The rename: what `names.set` writes into the store after the local cache has it. */
+    setNames(entries: readonly MetaNameChange[]): Promise<void>;
+    setMembership(entries: readonly {
+        ref: string;
+        paths: readonly string[];
+    }[]): Promise<void>;
+    /**
+     * The interaction of the whole feature: select rows, assign them to a room.
+     *
+     * One revision for the whole selection - the store is asked once with the complete membership
+     * of every object, not once per object, so a consumer of the change stream sees one change and
+     * the box writes its file once.
+     */
+    assign(refs: readonly string[], nodePath: string, on: boolean): Promise<void>;
+    createEnum(id: string, name: Readonly<Record<string, string>>): Promise<void>;
+    updateEnum(id: string, name: Readonly<Record<string, string>>): Promise<void>;
+    deleteEnum(id: string, detach: boolean): Promise<void>;
+    /**
+     * A node under a parent. The id is derived from the name and never changes afterwards, which is
+     * what keeps every membership pointing at the same node when the room is renamed.
+     */
+    createNode(enumId: string, parent: string | null | undefined, name: string, options?: {
+        readonly icon?: string;
+        readonly position?: number;
+    }): Promise<string>;
+    updateNode(nodePath: string, patch: MetaNodePatch): Promise<void>;
+    deleteNode(nodePath: string, detach: boolean): Promise<void>;
+    import(document: unknown, mode: MetaImportMode): Promise<void>;
+    /**
+     * The ref of an address: the interface that reports it, or the one the store already uses.
+     *
+     * The second half matters after a restart with the box unreachable, and for a channel of a
+     * device that has just been deleted: the store still has the entry, and a rename of it should
+     * go to the same ref rather than to a new one.
+     */
+    refFor(address: string): string | undefined;
+    /** The version the box answered with, for the settings dialog and the log. */
+    get version(): MetaVersion | undefined;
+}
+//# sourceMappingURL=service.d.ts.map