smart-home-engine 0.0.1 → 0.11.0

package/src/sandbox/elastic-sandbox.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const elastic = require('../elastic');
+
+/**
+ * Sandbox module — adds she.elastic.* to every script context.
+ *
+ * All methods return Promises and are no-ops (returning empty / null results)
+ * when Elasticsearch is not configured (no --elastic.node in config).
+ *
+ * she.elastic API:
+ *   she.elastic.search(index, query)           → Promise<{ hits, total }>
+ *   she.elastic.get(index, id)                 → Promise<object|null>
+ *   she.elastic.index(index, doc, [id])        → Promise<{ id }>
+ *   she.elastic.find(index, field, text, size) → Promise<object[]>
+ */
+module.exports = function (she) {
+    she.elastic = {
+        /**
+         * Search documents in an Elasticsearch index.
+         * @param {string} index
+         * @param {object} query  Elasticsearch query DSL object
+         * @returns {Promise<{ hits: object[], total: number }>}
+         */
+        async search(index, query) {
+            const client = elastic.getClient();
+            if (!client) return { hits: [], total: 0 };
+            const result = await client.search({ index, query });
+            return {
+                hits: result.hits.hits.map((h) => ({ id: h._id, ...h._source })),
+                total: result.hits.total?.value ?? result.hits.hits.length,
+            };
+        },
+
+        /**
+         * Retrieve a single document by ID.
+         * @param {string} index
+         * @param {string} id
+         * @returns {Promise<object|null>}
+         */
+        async get(index, id) {
+            const client = elastic.getClient();
+            if (!client) return null;
+            try {
+                const result = await client.get({ index, id });
+                return result._source ?? null;
+            } catch (err) {
+                if (err.statusCode === 404) return null;
+                throw err;
+            }
+        },
+
+        /**
+         * Index (create or replace) a document.
+         * @param {string} index
+         * @param {object} doc
+         * @param {string} [id]  omit to let Elasticsearch auto-generate an ID
+         * @returns {Promise<{ id: string }>}
+         */
+        async index(index, doc, id) {
+            const client = elastic.getClient();
+            if (!client) return { id: null };
+            const params = { index, document: doc };
+            if (id !== undefined) params.id = id;
+            const result = await client.index(params);
+            return { id: result._id };
+        },
+
+        /**
+         * Full-text match search across a single field.
+         * @param {string} index
+         * @param {string} field
+         * @param {string} text
+         * @param {number} [size=10]
+         * @returns {Promise<object[]>}
+         */
+        async find(index, field, text, size) {
+            const client = elastic.getClient();
+            if (!client) return [];
+            const result = await client.search({
+                index,
+                size: size ?? 10,
+                query: { match: { [field]: text } },
+            });
+            return result.hits.hits.map((h) => ({ id: h._id, ...h._source }));
+        },
+    };
+};

package/src/sandbox/influx-sandbox.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const influx = require('../influx');
+
+/**
+ * Sandbox module — adds she.influx.* to every script context.
+ *
+ * All methods return Promises and are no-ops (returning empty results) when
+ * InfluxDB is not configured (no --influx.url / --influx.token in config).
+ *
+ * she.influx API:
+ *   she.influx.query(fluxQuery)                         → Promise<object[]>
+ *   she.influx.write(measurement, fields, tags, ts)     → Promise<void>
+ *   she.influx.getLast(topic, n)                        → Promise<{ ts, val }[]>
+ *   she.influx.getRange(topic, from, to)                → Promise<{ ts, val }[]>
+ */
+module.exports = function (she) {
+    she.influx = {
+        /**
+         * Execute a Flux query against InfluxDB.
+         * @param {string} fluxQuery
+         * @returns {Promise<object[]>}
+         */
+        query(fluxQuery) {
+            const client = influx.getClient();
+            const opts = influx.getOpts();
+            if (!client) return Promise.resolve([]);
+            const queryApi = client.getQueryApi(opts.org);
+            return new Promise((resolve, reject) => {
+                const rows = [];
+                queryApi.queryRows(fluxQuery, {
+                    next(row, tableMeta) {
+                        rows.push(tableMeta.toObject(row));
+                    },
+                    error: reject,
+                    complete() {
+                        resolve(rows);
+                    },
+                });
+            });
+        },
+
+        /**
+         * Write a single data point to InfluxDB.
+         * @param {string} measurement
+         * @param {object} fields       e.g. { temperature: 21.5 }
+         * @param {object} [tags]       e.g. { room: 'living' }
+         * @param {Date|number} [timestamp]
+         * @returns {Promise<void>}
+         */
+        write(measurement, fields, tags, timestamp) {
+            const client = influx.getClient();
+            const opts = influx.getOpts();
+            if (!client) return Promise.resolve();
+            const { Point } = require('@influxdata/influxdb-client');
+            const writeApi = client.getWriteApi(opts.org, opts.bucket, 'ns');
+            const point = new Point(measurement);
+            if (tags) {
+                Object.entries(tags).forEach(([k, v]) => point.tag(k, v));
+            }
+            Object.entries(fields).forEach(([k, v]) => {
+                if (typeof v === 'boolean') {
+                    point.booleanField(k, v);
+                } else if (typeof v === 'number') {
+                    point.floatField(k, v);
+                } else {
+                    point.stringField(k, String(v));
+                }
+            });
+            if (timestamp !== undefined) point.timestamp(timestamp);
+            writeApi.writePoint(point);
+            return writeApi.close();
+        },
+
+        /**
+         * Return the last N recorded values for an MQTT topic.
+         * Assumes data was stored with a "topic" tag and value in the "_value" field.
+         * @param {string} topic
+         * @param {number} n
+         * @returns {Promise<{ ts: number, val: any }[]>}
+         */
+        getLast(topic, n) {
+            const opts = influx.getOpts();
+            if (!opts) return Promise.resolve([]);
+            const safeTopic = topic.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+            const flux = `from(bucket: "${opts.bucket}")` + ` |> range(start: -30d)` + ` |> filter(fn: (r) => r["topic"] == "${safeTopic}")` + ` |> tail(n: ${Number(n)})`;
+            return this.query(flux).then((rows) => rows.map((r) => ({ ts: new Date(r._time).getTime(), val: r._value })));
+        },
+
+        /**
+         * Return all recorded values for an MQTT topic within a time range.
+         * @param {string} topic
+         * @param {Date|string|number} from
+         * @param {Date|string|number} to
+         * @returns {Promise<{ ts: number, val: any }[]>}
+         */
+        getRange(topic, from, to) {
+            const opts = influx.getOpts();
+            if (!opts) return Promise.resolve([]);
+            const safeTopic = topic.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+            const start = new Date(from).toISOString();
+            const stop = new Date(to).toISOString();
+            const flux = `from(bucket: "${opts.bucket}")` + ` |> range(start: ${start}, stop: ${stop})` + ` |> filter(fn: (r) => r["topic"] == "${safeTopic}")`;
+            return this.query(flux).then((rows) => rows.map((r) => ({ ts: new Date(r._time).getTime(), val: r._value })));
+        },
+    };
+};

package/src/sandbox/matter-sandbox.js

@@ -0,0 +1,92 @@
+'use strict';
+
+/**
+ * Matter sandbox module — adds she.matter.* to every script context.
+ *
+ * Called by loadSandbox() in index.js; receives (she, { scriptDomain, scriptName }).
+ *
+ * she.matter API:
+ *   she.matter.sub(nodeId, endpointId, clusterName, attrName, cb)
+ *       → listenerId (number)
+ *   she.matter.unsub(listenerId)
+ *       → void
+ *   she.matter.get(nodeId, endpointId, clusterName, attrName)
+ *       → Promise<value>
+ *   she.matter.send(nodeId, endpointId, clusterName, command, args?)
+ *       → Promise<result>
+ *
+ * All subscriptions registered by a script are automatically cancelled on
+ * hot-reload (cleanup() is called from unloadScript() in index.js).
+ */
+
+const controller = require('../matter/controller');
+
+module.exports = function (she, { scriptDomain, scriptName }) {
+    she.matter = {
+        /**
+         * Subscribe to an attribute change on a paired Matter device.
+         *
+         * @param {string}   nodeId       Decimal NodeId string
+         * @param {number}   endpointId
+         * @param {string}   clusterName  camelCase cluster name, e.g. "onOff"
+         * @param {string}   attrName     camelCase attribute name, e.g. "onOff"
+         * @param {Function} callback     (value, oldValue) => void
+         * @returns {number}  listenerId
+         */
+        sub(nodeId, endpointId, clusterName, attrName, callback) {
+            try {
+                return controller.subscribeAttribute(scriptName, nodeId, endpointId, clusterName, attrName, callback);
+            } catch (err) {
+                scriptDomain.emit('error', err);
+            }
+        },
+
+        /**
+         * Cancel a specific subscription.
+         *
+         * @param {number} listenerId  Returned by she.matter.sub()
+         */
+        unsub(listenerId) {
+            controller.unsubscribe(scriptName, listenerId);
+        },
+
+        /**
+         * Read a single attribute value from a paired Matter device.
+         *
+         * @param {string} nodeId
+         * @param {number} endpointId
+         * @param {string} clusterName  camelCase cluster name
+         * @param {string} attrName     camelCase attribute name
+         * @returns {Promise<unknown>}
+         */
+        get(nodeId, endpointId, clusterName, attrName) {
+            return controller.getAttribute(nodeId, endpointId, clusterName, attrName);
+        },
+
+        /**
+         * Invoke a cluster command on a paired Matter device.
+         *
+         * @param {string}  nodeId
+         * @param {number}  endpointId
+         * @param {string}  clusterName  camelCase cluster name
+         * @param {string}  command      camelCase command name
+         * @param {object}  [args={}]
+         * @returns {Promise<unknown>}
+         */
+        send(nodeId, endpointId, clusterName, command, args) {
+            return controller.sendCommand(nodeId, endpointId, clusterName, command, args ?? {});
+        },
+    };
+};
+
+/**
+ * Remove all Matter subscriptions for a script on hot-reload.
+ * Called from unloadScript() in index.js.
+ *
+ * @param {string} scriptName
+ */
+function cleanup(scriptName) {
+    controller.cleanup(scriptName);
+}
+
+module.exports.cleanup = cleanup;

package/src/sandbox/shedb-sandbox.js

@@ -0,0 +1,89 @@
+'use strict';
+
+/**
+ * sheDB sandbox module — adds she.db.* to every script context.
+ *
+ * Called by loadSandbox() in index.js; receives (she, { scriptDomain, scriptName }).
+ *
+ * she.db API:
+ *   she.db.get(id)                    → document or undefined
+ *   she.db.set(id, doc)               → void (create/overwrite)
+ *   she.db.extend(id, partial)        → void (deep merge)
+ *   she.db.delete(id)                 → void
+ *   she.db.prop(id, method, prop, val)→ void  (method: 'set'|'create'|'del')
+ *   she.db.sub(pattern, callback)     → void  (callback(id, doc))
+ *   she.db.query(filter, mapFn, reduceFn) → Array (ad-hoc synchronous query)
+ */
+
+const { getCore, addListener, removeListenersByScript } = require('../web/shedb');
+
+module.exports = function (she, { scriptDomain, scriptName }) {
+    const core = getCore();
+
+    // sheDB may not be initialised (--db-path not given or startup still in progress).
+    // We expose stubs that are no-ops / return undefined so user scripts don't crash.
+    she.db = {
+        get(id) {
+            return core ? core.get(id) : undefined;
+        },
+
+        set(id, doc) {
+            if (core) core.set(id, doc);
+        },
+
+        extend(id, partial) {
+            if (core) core.extend(id, partial);
+        },
+
+        delete(id) {
+            if (core) core.del(id);
+        },
+
+        /**
+         * Set/create/del a nested property on a document.
+         * @param {string} id
+         * @param {'set'|'create'|'del'} method
+         * @param {string} prop  - dot-notation path, e.g. 'config.network.ip'
+         * @param {*}      val   - value (not used for 'del')
+         */
+        prop(id, method, prop, val) {
+            if (core) core.prop(id, { method, prop, val });
+        },
+
+        /**
+         * Subscribe to document changes matching an MQTT wildcard pattern.
+         * The callback fires when any matching document is created, updated, or deleted.
+         * Subscriptions are automatically removed when the script is hot-reloaded.
+         *
+         * @param {string}   pattern  - MQTT wildcard, e.g. 'devices/#'
+         * @param {Function} callback - called as callback(id, doc) where doc is null on delete
+         */
+        sub(pattern, callback) {
+            if (!core) return;
+            // Wrap in script domain so errors don't crash the process
+            const wrapped = scriptDomain.bind(callback);
+            addListener(pattern, wrapped, scriptName);
+        },
+
+        /**
+         * Ad-hoc synchronous query — does NOT persist; runs immediately.
+         *
+         * @param {string|null} filter   - MQTT wildcard to pre-filter document IDs (null = all)
+         * @param {Function}    mapFn    - called as mapFn(doc, emit); call emit(item) to add to result
+         * @param {Function}   [reduceFn]- called as reduceFn(resultArray); return value replaces result
+         * @returns {Array}
+         */
+        query(filter, mapFn, reduceFn) {
+            if (!core) return [];
+            return core.adhocQuery(filter, mapFn, reduceFn);
+        },
+    };
+};
+
+/**
+ * Called by unloadScript() in index.js to clean up subscriptions for the given script file.
+ * @param {string} scriptFile - absolute file path (matches scriptName used when registering)
+ */
+module.exports.cleanup = function (scriptFile) {
+    removeListenersByScript(scriptFile);
+};

package/src/sandbox/stdlib.js

@@ -0,0 +1,132 @@
+/* eslint-disable func-name-matching, func-names, camelcase */
+
+module.exports = function (she) {
+    /**
+     * @method now
+     * @returns {number} ms since epoch
+     */
+    she.now = function Sandbox_now() {
+        return new Date().getTime();
+    };
+
+    /**
+     * @method age
+     * @param {string} topic
+     * @returns {number} seconds since last change
+     */
+    she.age = function Sandbox_age(topic) {
+        return Math.round((new Date().getTime() - she.getProp(topic, 'lc')) / 1000);
+    };
+
+    /**
+     * Link topic(s) to other topic(s)
+     * @method link
+     * @param {(string|string[])} source - topic or array of topics to subscribe
+     * @param {(string|string[])} target - topic or array of topics to publish
+     * @param {mixed} [value] - value to publish. If omitted the sources value is published. A function can be used to transform the value.
+     */
+    she.link = function Sandbox_link(source, target, /* optional */ value) {
+        she.mqttsub(source, (topic, val) => {
+            if (typeof value === 'function') {
+                val = value(val);
+            } else if (typeof value !== 'undefined') {
+                val = value;
+            }
+            she.setValue(target, val);
+        });
+    };
+
+    /**
+     * Combine topics through boolean or
+     * @method combineBool
+     * @param {string[]} srcs - array of topics to subscribe
+     * @param {string} targets - topic to publish
+     */
+    she.combineBool = function Sandbox_combineBool(srcs, target) {
+        function combine() {
+            let result = 0;
+            srcs.forEach((src) => {
+                if (she.getValue(src)) {
+                    result = 1;
+                }
+            });
+            she.setValue(target, result);
+        }
+        combine();
+        she.mqttsub(srcs, { retain: true }, combine);
+    };
+
+    /**
+     * Publish maximum of combined topics
+     * @method combineMax
+     * @param {string[]} srcs - array of topics to subscribe
+     * @param {string} targets - topic to publish
+     */
+    she.combineMax = function (srcs, target) {
+        function combine() {
+            let result = 0;
+            srcs.forEach((src) => {
+                const srcVal = she.getValue(src);
+                if (srcVal > result) {
+                    result = srcVal;
+                }
+            });
+            she.setValue(target, result);
+        }
+        combine();
+        she.mqttsub(srcs, { retain: true }, combine);
+    };
+
+    const timeouts = {};
+    /**
+     * Publishes 1 on target for specific time after src changed to true
+     * @method timer
+     * @param {(string|string[])} src - topic or array of topics to subscribe
+     * @param {string} target - topic to publish
+     * @param {number} time - timeout in milliseconds
+     */
+    she.timer = function (src, target, time) {
+        she.mqttsub(src, { retain: false }, (topic, val) => {
+            if (val) {
+                clearTimeout(timeouts[target]);
+                if (!she.getValue(target)) {
+                    she.setValue(target, 1);
+                }
+                timeouts[target] = setTimeout(() => {
+                    if (she.getValue(target)) {
+                        she.setValue(target, 0);
+                    }
+                }, time);
+            }
+        });
+
+        timeouts[target] = setTimeout(() => {
+            if (she.getValue(target)) {
+                she.setValue(target, 0);
+            }
+        }, time);
+    };
+
+    /**
+     * Namespaced MQTT API — the primary way to interact with MQTT from scripts.
+     * @namespace she.mqtt
+     */
+    she.mqtt = {
+        /** Subscribe to one or more MQTT topics. Same signature as she.mqttsub(). */
+        sub: (...args) => she.mqttsub(...args),
+        /** Publish an MQTT message. Same signature as she.mqttpub(). */
+        pub: (...args) => she.mqttpub(...args),
+        /** Get the last-known value for a topic. */
+        get: (topic) => she.getValue(topic),
+        /** Set a value on one or more topics. */
+        set: (topic, val) => she.setValue(topic, val),
+        /** Get a specific property from a topic's state object. */
+        getProp: (...args) => she.getProp(...args),
+        /** Forward value changes from source topic(s) to target topic(s). */
+        link: (...args) => she.link(...args),
+        /** Seconds since the topic's value last changed. */
+        age: (topic) => she.age(topic),
+        /** Register a callback for MQTT connection lifecycle events ('connect' or 'disconnect'). */
+        on: (event, cb) => she._registerMqttEvent(event, cb),
+    };
+};

package/src/scripts/hello.js

@@ -0,0 +1,3 @@
+'use strict';
+
+she.info('ready');