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

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

@@ -0,0 +1,307 @@
+/**
+ * The HTTP client for openccu-lite's metadata API - `/api/meta/v1/`.
+ *
+ * Nothing but `fetch` and `AbortSignal`, both of which Node has had since 18 and Electron has
+ * always had: the porting rules of openccu-lite say in so many words not to add an HTTP or SSE
+ * dependency to an application that already has one, and a CCU addon pays for every kilobyte it
+ * ships. The change stream is Server-Sent Events read off `response.body`, parsed in
+ * {@link readEvents} - fifty lines against a `eventsource` package that would come with its own
+ * reconnect policy we would have to fight.
+ *
+ * Every call returns a typed value or throws a {@link MetaError}: `401` becomes `forbidden` with
+ * the credential named, which is what the provider degrades on rather than failing.
+ */
+import { MetaError, parseDocument, } from '@homematic-manager/core';
+/** How long a plain request may take. The box is on the LAN or on the loopback. */
+export const DEFAULT_TIMEOUT_MS = 10_000;
+/**
+ * How long the detection call may take.
+ *
+ * Short on purpose: it runs on every connect, a CCU answers 404 in milliseconds and an
+ * openccu-lite box answers just as fast. What this timeout is really for is the host that neither
+ * answers nor refuses - a firewall that drops the packet - and three seconds of that is already
+ * more patience than the answer is worth.
+ */
+export const DETECT_TIMEOUT_MS = 3000;
+/** Thin, typed access to one box's metadata API. */
+export class MetaApiClient {
+    #options;
+    #fetch;
+    constructor(options) {
+        this.#options = options;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+    }
+    get baseUrl() {
+        return this.#options.baseUrl;
+    }
+    /**
+     * `GET /version` - the runtime detection, and the only call that needs no credential.
+     *
+     * A CCU answers 404 or HTML here, which is exactly the point: no `/VERSION` sniffing, no host
+     * names, no ports. `undefined` means "this is not an openccu-lite box".
+     */
+    async version(timeoutMs = DETECT_TIMEOUT_MS) {
+        try {
+            const response = await this.#fetch(this.#url('/version'), {
+                signal: AbortSignal.timeout(timeoutMs),
+                headers: { Accept: 'application/json' },
+            });
+            if (!response.ok) {
+                return undefined;
+            }
+            const body = await response.json();
+            if (typeof body !== 'object' || body === null) {
+                return undefined;
+            }
+            const answer = body;
+            return answer.api === 'meta' && typeof answer.version === 'number' ? answer : undefined;
+        }
+        catch {
+            // a box that is off, a CCU that answers HTML, a DNS name that does not resolve: all of
+            // them mean the same thing here, and none of them is worth an exception
+            return undefined;
+        }
+    }
+    /** `GET /snapshot` - the whole document, validated as if it came off disk. */
+    async snapshot() {
+        return parseDocument(await this.#json('GET', '/snapshot'));
+    }
+    /** `PATCH /objects/{ref}` - the rename, and the room assignment. */
+    async patchObject(ref, patch) {
+        return this.#write('PATCH', `/objects/${encodeRef(ref)}`, patch);
+    }
+    /** `POST /objects:bulk` - many objects as one revision; what a multi-select assign sends. */
+    async bulk(sets, deletes = []) {
+        return this.#write('POST', '/objects:bulk', { set: sets, delete: deletes });
+    }
+    /** `POST /enums`. */
+    async createEnum(id, name) {
+        return this.#write('POST', '/enums', { id, name });
+    }
+    /** `PATCH /enums/{enum}`. */
+    async updateEnum(id, name) {
+        return this.#write('PATCH', `/enums/${encodeURIComponent(id)}`, { name });
+    }
+    /** `DELETE /enums/{enum}` - refused while it has members unless `detach` is asked for. */
+    async deleteEnum(id, members) {
+        const query = members === 'detach' ? '?members=detach' : '';
+        return this.#write('DELETE', `/enums/${encodeURIComponent(id)}${query}`, undefined);
+    }
+    /** `POST /enums/{enum}/nodes` - a new room, or a new floor above it. */
+    async createNode(enumId, body) {
+        return this.#write('POST', `/enums/${encodeURIComponent(enumId)}/nodes`, body);
+    }
+    /**
+     * `PATCH /enums/{enum}/nodes/{path…}` - rename, move, reorder.
+     *
+     * The path in the URL is **relative to the enum**: the node `room/eg/wohnzimmer` is
+     * `/enums/room/nodes/eg/wohnzimmer`. Writing the whole path there answers `unknown-path` for
+     * `room/room/eg/…`, which is a confusing five minutes the first time.
+     */
+    async updateNode(path, patch) {
+        return this.#write('PATCH', nodeUrl(path), patch);
+    }
+    /** `DELETE /enums/{enum}/nodes/{path…}`, with the same `detach` rule as an enum. */
+    async deleteNode(path, members) {
+        const query = members === 'detach' ? '?members=detach' : '';
+        return this.#write('DELETE', `${nodeUrl(path)}${query}`, undefined);
+    }
+    /** `PUT /import` - a whole document, validated and applied as one revision. */
+    async import(document, mode) {
+        return this.#write('PUT', `/import?mode=${mode}`, document);
+    }
+    /** `GET /export` - the document as the box would hand it to a user. */
+    async export() {
+        return parseDocument(await this.#json('GET', '/export?format=json'));
+    }
+    /** `GET /enums` - the trees alone, which is the cheapest authenticated read there is. */
+    async enums() {
+        const body = await this.#json('GET', '/enums');
+        const answer = body;
+        return (answer.enums ?? {});
+    }
+    /**
+     * The change stream as an async iterator over parsed events.
+     *
+     * `since` replays what the box still has; a `{"kind": "resync"}` answer means the history is
+     * gone and the consumer has to fetch the snapshot again. The iterator ends when the connection
+     * does - reconnecting is the provider's job, because only it knows the revision to resume from.
+     */
+    async *events(since, signal) {
+        const query = since === undefined ? '' : `?since=${String(since)}`;
+        const response = await this.#fetch(this.#url(`/events/sse${query}`), {
+            signal,
+            headers: { ...this.#headers(false), Accept: 'text/event-stream' },
+        });
+        if (!response.ok) {
+            throw await httpError(response);
+        }
+        if (!response.body) {
+            throw new MetaError('unknown-path', 'the event stream answered without a body');
+        }
+        yield* readEvents(response.body, signal);
+    }
+    #url(path) {
+        return `${this.#options.baseUrl.replace(/\/$/, '')}/api/meta/v1${path}`;
+    }
+    /**
+     * The credential, as a Bearer header.
+     *
+     * The API takes a session id or an API token in the same three places, and it accepts the CCU's
+     * `@…@` wrapping around a session id - but stripping it here keeps one shape on the wire and
+     * makes a log line readable.
+     */
+    #headers(write) {
+        const credential = write
+            ? (this.#options.writeCredential?.() ?? this.#options.credential?.())
+            : (this.#options.credential?.() ?? this.#options.writeCredential?.());
+        if (credential === undefined || credential === '') {
+            return {};
+        }
+        return { Authorization: `Bearer ${credential.replace(/^@|@$/g, '')}` };
+    }
+    async #json(method, path) {
+        const response = await this.#fetch(this.#url(path), {
+            method,
+            signal: AbortSignal.timeout(this.#options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+            headers: { ...this.#headers(false), Accept: 'application/json' },
+        });
+        if (!response.ok) {
+            throw await httpError(response);
+        }
+        return response.json();
+    }
+    async #write(method, path, body) {
+        const response = await this.#fetch(this.#url(path), {
+            method,
+            signal: AbortSignal.timeout(this.#options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+            headers: {
+                ...this.#headers(true),
+                Accept: 'application/json',
+                // lighttpd's mod_proxy answers 411 for a body-less PUT/POST/DELETE, which is why
+                // even a DELETE goes out with `{}` rather than nothing at all
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body ?? {}),
+        });
+        // 304: the write was valid and changed nothing, and the revision did not move
+        if (response.status === 304) {
+            return { revision: Number.NaN, changed: false };
+        }
+        if (!response.ok) {
+            throw await httpError(response);
+        }
+        const answer = (await response.json());
+        return {
+            revision: typeof answer.revision === 'number' ? answer.revision : Number.NaN,
+            changed: answer.changed !== false,
+        };
+    }
+}
+/** `BidCos-RF.JEQ0230153:1` as one path segment: the colon has to be percent-encoded. */
+export function encodeRef(ref) {
+    return encodeURIComponent(ref);
+}
+/** `room/eg/wohnzimmer` → `/enums/room/nodes/eg/wohnzimmer`. */
+export function nodeUrl(path) {
+    const [enumId, ...ids] = path.split('/');
+    return `/enums/${encodeURIComponent(enumId ?? '')}/nodes/${ids.map((id) => encodeURIComponent(id)).join('/')}`;
+}
+/** The error body of the API, or the status when there is none. */
+async function httpError(response) {
+    let code = response.status === 403 || response.status === 401 ? 'forbidden' : 'unknown-path';
+    let message = `${String(response.status)} ${response.statusText}`;
+    try {
+        const body = (await response.json());
+        if (typeof body.error === 'string') {
+            code = body.error;
+        }
+        if (typeof body.message === 'string') {
+            message = body.message;
+        }
+    }
+    catch {
+        // not JSON: a proxy error page, or a CCU answering something else entirely
+    }
+    if (response.status === 401) {
+        // told apart from a 403 on purpose: no credential at all is what the provider degrades on,
+        // a credential without the role is what a write reports to the user
+        return new MetaError('forbidden', `the metadata API refused the credential (401): ${message}`, { status: 401 });
+    }
+    return new MetaError(code, message, { status: response.status });
+}
+/**
+ * Server-Sent Events off a byte stream: `data:` lines until a blank one, everything else ignored.
+ *
+ * The API sends one JSON object per message and a comment line every 30 s as a heartbeat; there are
+ * no event names and no ids, because the resume point is `?since=<revision>` and not
+ * `Last-Event-ID`. A message that is not JSON is skipped rather than thrown - a stream that carries
+ * one bad line still carries the next good one.
+ */
+export async function* readEvents(stream, signal) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let data = '';
+    // a pending `read()` does not notice a signal by itself; cancelling the reader is what ends it,
+    // and without this a `stop()` waits for a box that has nothing more to say
+    const cancel = () => {
+        void reader.cancel().catch(() => undefined);
+    };
+    signal?.addEventListener('abort', cancel, { once: true });
+    try {
+        for (;;) {
+            if (signal?.aborted === true) {
+                return;
+            }
+            const chunk = await reader.read();
+            if (chunk.done) {
+                return;
+            }
+            buffer += decoder.decode(chunk.value, { stream: true });
+            let newline = buffer.indexOf('\n');
+            while (newline !== -1) {
+                const line = buffer.slice(0, newline).replace(/\r$/, '');
+                buffer = buffer.slice(newline + 1);
+                newline = buffer.indexOf('\n');
+                if (line === '') {
+                    const event = parseEvent(data);
+                    data = '';
+                    if (event) {
+                        yield event;
+                    }
+                    continue;
+                }
+                if (line.startsWith(':')) {
+                    // the heartbeat comment; it exists so that a dead connection is noticed
+                    continue;
+                }
+                if (line.startsWith('data:')) {
+                    data += line.slice('data:'.length).trimStart();
+                }
+            }
+        }
+    }
+    finally {
+        signal?.removeEventListener('abort', cancel);
+        // a reader that is not released keeps the socket, and the provider reconnects into it
+        reader.releaseLock();
+    }
+}
+function parseEvent(data) {
+    if (data === '') {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(data);
+        if (typeof parsed !== 'object' || parsed === null) {
+            return undefined;
+        }
+        const event = parsed;
+        return typeof event.kind === 'string' ? event : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=client.js.map

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

@@ -0,0 +1,38 @@
+/**
+ * Where the credential for openccu-lite's metadata API comes from.
+ *
+ * Three cases, and the interesting one is the first:
+ *
+ * - **on the box**, as the addon: `/usr/local/etc/occulite/local-token` holds a token with the
+ *   role `user` - it reads everything and writes nothing, on purpose. Writes use the session of
+ *   whoever is looking at the page, which the shell hands the addon as `?sid=@xxxxxxxxxx@`
+ *   (openccu-lite's embedding contract). So the addon reads as itself and writes as the user, which
+ *   is exactly the split a device-management frontend wants: nothing renames a device unless a
+ *   person asked for it.
+ * - **off the box** - a desktop, a server, Docker: an API token the administrator created on the
+ *   box's Users page, stored in the connection settings like any other credential.
+ * - **neither**: reads are unauthenticated, the API answers 401, and the provider degrades to the
+ *   local names with a notice. Never an exception (their invariant 5).
+ */
+/** Where the box puts the read-only token for programs running on it. */
+export declare const LOCAL_TOKEN_FILE = "/usr/local/etc/occulite/local-token";
+/** What an API token looks like, so a typo in a settings field is caught before it is sent. */
+export declare const TOKEN_PATTERN: RegExp;
+/** Is this the shape of an openccu-lite API token? */
+export declare function isApiToken(value: string): boolean;
+/**
+ * A session id as the box hands it over: `@xxxxxxxxxx@`, the CCU convention, or bare.
+ *
+ * The API accepts both spellings; this normalises to the bare one so that one shape goes on the
+ * wire and a log line stays readable.
+ */
+export declare function normaliseSid(value: string | undefined): string | undefined;
+/**
+ * The box's local token, or `undefined` when there is no file - which is every installation that
+ * is not the addon on an openccu-lite box.
+ *
+ * Never throws: a token that cannot be read is the same as no token, and the answer to that is to
+ * run without names rather than to fail to start.
+ */
+export declare function readLocalToken(file?: string): Promise<string | undefined>;
+//# sourceMappingURL=credentials.d.ts.map

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

@@ -0,0 +1,53 @@
+/**
+ * Where the credential for openccu-lite's metadata API comes from.
+ *
+ * Three cases, and the interesting one is the first:
+ *
+ * - **on the box**, as the addon: `/usr/local/etc/occulite/local-token` holds a token with the
+ *   role `user` - it reads everything and writes nothing, on purpose. Writes use the session of
+ *   whoever is looking at the page, which the shell hands the addon as `?sid=@xxxxxxxxxx@`
+ *   (openccu-lite's embedding contract). So the addon reads as itself and writes as the user, which
+ *   is exactly the split a device-management frontend wants: nothing renames a device unless a
+ *   person asked for it.
+ * - **off the box** - a desktop, a server, Docker: an API token the administrator created on the
+ *   box's Users page, stored in the connection settings like any other credential.
+ * - **neither**: reads are unauthenticated, the API answers 401, and the provider degrades to the
+ *   local names with a notice. Never an exception (their invariant 5).
+ */
+import { readFile } from 'node:fs/promises';
+/** Where the box puts the read-only token for programs running on it. */
+export const LOCAL_TOKEN_FILE = '/usr/local/etc/occulite/local-token';
+/** What an API token looks like, so a typo in a settings field is caught before it is sent. */
+export const TOKEN_PATTERN = /^olt_[0-9a-f]{32}$/;
+/** Is this the shape of an openccu-lite API token? */
+export function isApiToken(value) {
+    return TOKEN_PATTERN.test(value.trim());
+}
+/**
+ * A session id as the box hands it over: `@xxxxxxxxxx@`, the CCU convention, or bare.
+ *
+ * The API accepts both spellings; this normalises to the bare one so that one shape goes on the
+ * wire and a log line stays readable.
+ */
+export function normaliseSid(value) {
+    const bare = (value ?? '').replace(/^@|@$/g, '').trim();
+    return /^[0-9a-zA-Z]{6,64}$/.test(bare) ? bare : undefined;
+}
+/**
+ * The box's local token, or `undefined` when there is no file - which is every installation that
+ * is not the addon on an openccu-lite box.
+ *
+ * Never throws: a token that cannot be read is the same as no token, and the answer to that is to
+ * run without names rather than to fail to start.
+ */
+export async function readLocalToken(file = LOCAL_TOKEN_FILE) {
+    try {
+        const content = await readFile(file, 'utf8');
+        const token = content.trim().split(/\r?\n/)[0]?.trim();
+        return token === undefined || token === '' ? undefined : token;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=credentials.js.map

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

@@ -0,0 +1,12 @@
+/**
+ * D-40: the metadata store - names, rooms, functions and any taxonomy a user adds - with the two
+ * providers behind it, the HTTP client for openccu-lite's API and where the credentials come from.
+ */
+export * from './client.js';
+export * from './credentials.js';
+export * from './provider.js';
+export * from './localProvider.js';
+export * from './occuliteProvider.js';
+export * from './regaProvider.js';
+export * from './service.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,12 @@
+/**
+ * D-40: the metadata store - names, rooms, functions and any taxonomy a user adds - with the two
+ * providers behind it, the HTTP client for openccu-lite's API and where the credentials come from.
+ */
+export * from './client.js';
+export * from './credentials.js';
+export * from './provider.js';
+export * from './localProvider.js';
+export * from './occuliteProvider.js';
+export * from './regaProvider.js';
+export * from './service.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,47 @@
+/**
+ * The `local` metadata provider: names, rooms and functions in this profile.
+ *
+ * It is the same {@link MetaStore} the conformance corpus runs against, persisted to
+ * `<dataDir>/meta.json` - the **profile** directory and not the per-CCU cache, for the reason the
+ * link templates live there too (task 15): a taxonomy is the user's own work, it is not derived
+ * from any CCU, `config.clearCaches` may not throw it away and moving the profile to another
+ * installation has to take it along.
+ *
+ * On a system that has neither ReGa nor a box this is where a name lives; on a CCU it is where the
+ * taxonomy lives while the names come from ReGa. Nothing here talks to anything.
+ */
+import { type MetaDocument, type MetaImportMode, type MetaNodePatch, type MetaState } from '@homematic-manager/core';
+import type { MetadataProvider, MetaMembershipEntry, MetaNameEntry, MetaProviderEvents } from './provider.js';
+export interface LocalMetaProviderOptions extends MetaProviderEvents {
+    /** `<dataDir>/meta.json`. */
+    readonly file: string;
+}
+export declare class LocalMetaProvider implements MetadataProvider {
+    #private;
+    readonly kind: "local";
+    constructor(options: LocalMetaProviderOptions);
+    state(): MetaState;
+    /**
+     * Reads the file. A broken one is reported and replaced by an empty store rather than left to
+     * fail every read afterwards - the names in the grid then come from the name cache alone, which
+     * is the degradation D-2 asks for everywhere else too.
+     */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Nothing to read again: this store is in this process. */
+    refresh(): Promise<void>;
+    document(): MetaDocument;
+    setNames(entries: readonly MetaNameEntry[]): Promise<void>;
+    setMembership(entries: readonly MetaMembershipEntry[]): 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>;
+    createNode(enumId: string, parent: string | null, id: string, name: string, options: {
+        readonly icon?: string;
+        readonly position?: number;
+    }): Promise<string>;
+    updateNode(path: string, patch: MetaNodePatch): Promise<void>;
+    deleteNode(path: string, detach: boolean): Promise<void>;
+    import(document: unknown, mode: MetaImportMode): Promise<void>;
+}
+//# sourceMappingURL=localProvider.d.ts.map

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

@@ -0,0 +1,119 @@
+/**
+ * The `local` metadata provider: names, rooms and functions in this profile.
+ *
+ * It is the same {@link MetaStore} the conformance corpus runs against, persisted to
+ * `<dataDir>/meta.json` - the **profile** directory and not the per-CCU cache, for the reason the
+ * link templates live there too (task 15): a taxonomy is the user's own work, it is not derived
+ * from any CCU, `config.clearCaches` may not throw it away and moving the profile to another
+ * installation has to take it along.
+ *
+ * On a system that has neither ReGa nor a box this is where a name lives; on a CCU it is where the
+ * taxonomy lives while the names come from ReGa. Nothing here talks to anything.
+ */
+import { MetaStore, emptyDocument, parseDocument, } from '@homematic-manager/core';
+import { errorMessage } from '../errors.js';
+import { readJsonFile, writeJsonFile } from '../util/jsonFile.js';
+export class LocalMetaProvider {
+    kind = 'local';
+    #options;
+    #store = new MetaStore();
+    constructor(options) {
+        this.#options = options;
+    }
+    state() {
+        return {
+            provider: 'local',
+            reachable: true,
+            writable: true,
+            revision: this.#store.revision,
+            objects: this.#store.size,
+        };
+    }
+    /**
+     * Reads the file. A broken one is reported and replaced by an empty store rather than left to
+     * fail every read afterwards - the names in the grid then come from the name cache alone, which
+     * is the degradation D-2 asks for everywhere else too.
+     */
+    async start() {
+        const raw = await readJsonFile(this.#options.file);
+        if (raw === undefined) {
+            this.#store = new MetaStore();
+            this.#options.onStateChanged(this.state());
+            return;
+        }
+        try {
+            this.#store = new MetaStore({ document: parseDocument(raw) });
+        }
+        catch (error) {
+            this.#store = new MetaStore({ document: emptyDocument() });
+            this.#options.onNotice('warn', `${this.#options.file} could not be read: ${errorMessage(error)}`);
+        }
+        this.#options.onStateChanged(this.state());
+        this.#options.onChanged();
+    }
+    stop() {
+        return Promise.resolve();
+    }
+    /** Nothing to read again: this store is in this process. */
+    refresh() {
+        return Promise.resolve();
+    }
+    document() {
+        return this.#store.document();
+    }
+    async setNames(entries) {
+        const sets = {};
+        for (const entry of entries) {
+            sets[entry.ref] = { name: entry.name };
+        }
+        await this.#apply(() => this.#store.bulk(sets).changed);
+    }
+    async setMembership(entries) {
+        const sets = {};
+        for (const entry of entries) {
+            sets[entry.ref] = { enums: entry.paths };
+        }
+        await this.#apply(() => this.#store.bulk(sets).changed);
+    }
+    async createEnum(id, name) {
+        await this.#apply(() => this.#store.createEnum(id, name).changed);
+    }
+    async updateEnum(id, name) {
+        await this.#apply(() => this.#store.updateEnum(id, name).changed);
+    }
+    async deleteEnum(id, detach) {
+        await this.#apply(() => this.#store.deleteEnum(id, detach ? 'detach' : 'refuse').changed);
+    }
+    async createNode(enumId, parent, id, name, options) {
+        await this.#apply(() => this.#store.createNode(enumId, parent, id, name, options).changed);
+        return `${parent ?? enumId}/${id}`;
+    }
+    async updateNode(path, patch) {
+        await this.#apply(() => this.#store.updateNode(path, patch).changed);
+    }
+    async deleteNode(path, detach) {
+        await this.#apply(() => this.#store.deleteNode(path, detach ? 'detach' : 'refuse').changed);
+    }
+    async import(document, mode) {
+        await this.#apply(() => this.#store.import(document, mode).changed);
+    }
+    /** One write: apply, persist when it changed anything, tell the backend. */
+    async #apply(write) {
+        const changed = write();
+        if (!changed) {
+            return;
+        }
+        await this.#save();
+        this.#options.onStateChanged(this.state());
+        this.#options.onChanged();
+    }
+    async #save() {
+        try {
+            await writeJsonFile(this.#options.file, this.#store.document());
+        }
+        catch (error) {
+            this.#options.onNotice('warn', `${this.#options.file} could not be written: ${errorMessage(error)}`);
+        }
+    }
+}
+//# sourceMappingURL=localProvider.js.map

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

@@ -0,0 +1,79 @@
+/**
+ * The `occulite` provider: names, rooms and functions from an openccu-lite box, and written back
+ * to it.
+ *
+ * The shape of it is the one openccu-lite's porting kit prescribes and the one their own
+ * `occulited` expects: **snapshot once, then follow the change stream**, and re-snapshot when the
+ * stream says the history is gone (`resync`), when a whole store was imported, or when a revision
+ * arrives that is not the next one. Nothing polls. A rename made in another frontend, or by another
+ * person in another browser, is in this application's grid inside a second.
+ *
+ * Failure is degradation, never an exception (their invariant 5, our D-2):
+ *
+ * - the box is off → the last snapshot from the cache file, `reachable: false`, one notice, and a
+ *   reconnect loop with a backoff;
+ * - the credential is refused (401) → no names rather than no application, one notice, and a retry
+ *   on the next reconnect;
+ * - the credential may read but not write (403) → the names are shown and `writable` is false, so
+ *   the UI can say why the rename button does nothing.
+ *
+ * The snapshot is persisted where the ReGa provider persists its names, for the same reason: a
+ * restart while the box is unreachable must not leave the grid nameless.
+ */
+import { summariseAll, type MetaDocument, type MetaImportMode, type MetaNodePatch, type MetaState } from '@homematic-manager/core';
+import { MetaApiClient } from './client.js';
+import type { MetadataProvider, MetaMembershipEntry, MetaNameEntry, MetaProviderEvents } from './provider.js';
+/** First wait before the event stream is opened again, in milliseconds. */
+export declare const RECONNECT_MIN_MS = 2000;
+/** Longest wait between two attempts. A box that is being updated is back well inside a minute. */
+export declare const RECONNECT_MAX_MS = 60000;
+export interface OcculiteProviderOptions extends MetaProviderEvents {
+    readonly client: MetaApiClient;
+    /** `<cacheDir>/occulite-meta.json`: the last snapshot, so a restart without the box has names. */
+    readonly cacheFile?: string;
+    /** `occulited 0.1.0`, from the detection call. */
+    readonly implementation?: string;
+    readonly reconnectMinMs?: number;
+    readonly reconnectMaxMs?: number;
+    /** Injected by the tests in place of `setTimeout`. */
+    readonly wait?: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+export declare class OcculiteProvider implements MetadataProvider {
+    #private;
+    readonly kind: "occulite";
+    constructor(options: OcculiteProviderOptions);
+    state(): MetaState;
+    document(): MetaDocument;
+    /**
+     * The cached snapshot first, then the box.
+     *
+     * In that order on purpose: the cache is instant and the box may be a second away, and a grid
+     * that shows the names it had a moment ago and then corrects them is better than one that shows
+     * addresses while a request is in flight.
+     */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * A fresh snapshot, on demand - the credential changed, or a host asked for one.
+     *
+     * It also ends the wait before the next attempt at the event stream. On the box the first page
+     * load is what hands the addon a session at all, and without this the store would be read at
+     * once but only *followed* after the backoff had run out.
+     */
+    refresh(): Promise<void>;
+    setNames(entries: readonly MetaNameEntry[]): Promise<void>;
+    setMembership(entries: readonly MetaMembershipEntry[]): 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>;
+    createNode(enumId: string, parent: string | null, id: string, name: string, options: {
+        readonly icon?: string;
+        readonly position?: number;
+    }): Promise<string>;
+    updateNode(path: string, patch: MetaNodePatch): Promise<void>;
+    deleteNode(path: string, detach: boolean): Promise<void>;
+    import(document: unknown, mode: MetaImportMode): Promise<void>;
+}
+/** Every object of the current document as the UI shows it. Re-exported for the backend's reads. */
+export { summariseAll };
+//# sourceMappingURL=occuliteProvider.d.ts.map