smart-home-engine 0.28.2 → 0.29.0

package/dist/web/assets/{tsMode-DuB73Tfw.js → tsMode-CY35UxpB.js}

@@ -1,4 +1,4 @@
-import{m as O}from"./monaco-langs-BW2J83t5.js";import{t as I}from"./index-DeQBzoGc.js";/*!-----------------------------------------------------------------------------
+import{m as O}from"./monaco-langs-BW2J83t5.js";import{t as I}from"./index-BNu1W94k.js";/*!-----------------------------------------------------------------------------
  * Copyright (c) Microsoft Corporation. All rights reserved.
  * Version: 0.52.2(404545bded1df6ffa41ea0af4e8ddb219018c6c1)
  * Released under the MIT license

package/dist/web/index.html

@@ -155,7 +155,7 @@
                 }
             })();
         </script>
-      <script type="module" crossorigin src="/assets/index-DeQBzoGc.js"></script>
+      <script type="module" crossorigin src="/assets/index-BNu1W94k.js"></script>
       <link rel="modulepreload" crossorigin href="/assets/monaco-langs-BW2J83t5.js">
       <link rel="stylesheet" crossorigin href="/assets/monaco-langs-DyX1CsEw.css">
       <link rel="stylesheet" crossorigin href="/assets/index-DMJ3LJnK.css">

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "smart-home-engine",
-    "version": "0.28.2",
+    "version": "0.29.0",
     "description": "Node.js based script runner for use in MQTT based Smart Home environments",
     "main": "src/index.js",
     "scripts": {

package/src/sandbox/stdlib.js

@@ -1,6 +1,6 @@
 /* eslint-disable func-name-matching, func-names, camelcase */
 
-module.exports = function (she) {
+module.exports = function (she, ctx = {}) {
     /**
      * @method now
      * @returns {number} ms since epoch
@@ -9,106 +9,20 @@ module.exports = function (she) {
         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;
-            }
+    // Route a computed value to a topic string (setValue) or a callback (called as fn(topic, val)).
+    function sink(target, topic, val) {
+        if (typeof target === 'function') {
+            target(topic, val);
+        } else {
             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);
-    };
+    // Timeout handles indexed by target (string key or function reference).
+    const timerHandles = new Map();
 
-    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) {
-                she.clearTimeout(timeouts[target]);
-                if (!she.getValue(target)) {
-                    she.setValue(target, 1);
-                }
-                timeouts[target] = she.setTimeout(() => {
-                    if (she.getValue(target)) {
-                        she.setValue(target, 0);
-                    }
-                }, time);
-            }
-        });
-
-        timeouts[target] = she.setTimeout(() => {
-            if (she.getValue(target)) {
-                she.setValue(target, 0);
-            }
-        }, time);
-    };
-
-    /**
-     * Namespaced MQTT API — the primary way to interact with MQTT from scripts.
+     * Namespaced MQTT API - the primary way to interact with MQTT from scripts.
      * @namespace she.mqtt
      */
     she.mqtt = {
@@ -123,35 +37,166 @@ module.exports = function (she) {
         /** 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),
+        link: function Sandbox_mqtt_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);
+            });
+        },
         /** Seconds since the topic's value last changed. */
-        age: (topic) => she.age(topic),
+        age: function Sandbox_mqtt_age(topic) {
+            return Math.round((new Date().getTime() - she.getProp(topic, 'lc')) / 1000);
+        },
         /** Register a callback for MQTT connection lifecycle events ('connect' or 'disconnect'). */
         on: (event, cb) => she._registerMqttEvent(event, cb),
+        /**
+         * Publish 1 to target when any source is truthy, 0 otherwise.
+         * target may be a topic string or a callback(topic, val).
+         */
+        or: function Sandbox_mqtt_or(srcs, target) {
+            function combine(topic) {
+                const result = srcs.some((src) => she.getValue(src)) ? 1 : 0;
+                sink(target, topic ?? null, result);
+            }
+            combine(null);
+            she.mqttsub(srcs, { retain: true }, (topic) => combine(topic));
+        },
+        /**
+         * Publish 1 to target when all sources are truthy, 0 otherwise.
+         * target may be a topic string or a callback(topic, val).
+         */
+        and: function Sandbox_mqtt_and(srcs, target) {
+            function combine(topic) {
+                const result = srcs.every((src) => she.getValue(src)) ? 1 : 0;
+                sink(target, topic ?? null, result);
+            }
+            combine(null);
+            she.mqttsub(srcs, { retain: true }, (topic) => combine(topic));
+        },
+        /**
+         * Publish the maximum of all source values to target.
+         * target may be a topic string or a callback(topic, val).
+         */
+        max: function Sandbox_mqtt_max(srcs, target) {
+            function combine(topic) {
+                let result = 0;
+                srcs.forEach((src) => {
+                    const v = she.getValue(src);
+                    if (v > result) result = v;
+                });
+                sink(target, topic ?? null, result);
+            }
+            combine(null);
+            she.mqttsub(srcs, { retain: true }, (topic) => combine(topic));
+        },
+        /**
+         * Publish the minimum of all source values to target.
+         * target may be a topic string or a callback(topic, val).
+         */
+        min: function Sandbox_mqtt_min(srcs, target) {
+            function combine(topic) {
+                const values = srcs.map((src) => she.getValue(src)).filter((v) => v !== undefined && v !== null);
+                const result = values.length ? Math.min(...values) : 0;
+                sink(target, topic ?? null, result);
+            }
+            combine(null);
+            she.mqttsub(srcs, { retain: true }, (topic) => combine(topic));
+        },
+        /**
+         * Pulse target to 1 for ms after src goes truthy, then reset to 0.
+         * Signature: timer(src, ms, target)
+         * target may be a topic string or a callback(topic, val).
+         * When target is a topic string, any lingering 1 from a previous run is
+         * cleared by an initial timeout on startup.
+         */
+        timer: function Sandbox_mqtt_timer(src, ms, target) {
+            const key = target;
+            she.mqttsub(src, { retain: false }, (topic, val) => {
+                if (val) {
+                    she.clearTimeout(timerHandles.get(key));
+                    sink(target, topic, 1);
+                    timerHandles.set(
+                        key,
+                        she.setTimeout(() => {
+                            sink(target, null, 0);
+                        }, ms),
+                    );
+                }
+            });
+            if (typeof target !== 'function') {
+                timerHandles.set(
+                    key,
+                    she.setTimeout(() => {
+                        if (she.getValue(target)) she.setValue(target, 0);
+                    }, ms),
+                );
+            }
+        },
     };
 
     /**
-     * Fetch a URL and return a Promise that resolves to the response body.
-     * Resolves to parsed JSON when the Content-Type is application/json, plain text otherwise.
-     * Rejects on non-2xx responses.
-     * @method fetch
-     * @param {string} url
-     * @param {RequestInit} [options]
-     * @returns {Promise<string|object>}
+     * HTTP helpers — fetch and webhook receiver.
+     * @namespace she.http
      */
-    she.fetch = function Sandbox_fetch(url, options) {
-        const TIMEOUT_MS = 30_000;
-        let signal = options?.signal;
-        let timer;
-        if (!signal) {
-            const ac = new AbortController();
-            signal = ac.signal;
-            timer = setTimeout(() => ac.abort(new Error(`she.fetch timed out after ${TIMEOUT_MS / 1000}s`)), TIMEOUT_MS);
-        }
-        return fetch(url, { ...options, signal }).then((r) => {
-            if (!r.ok) throw new Error(`HTTP ${r.status} ${r.statusText}`);
-            const ct = r.headers.get('content-type') || '';
-            return ct.includes('json') ? r.json() : r.text();
-        }).finally(() => clearTimeout(timer));
+    she.http = {
+        /**
+         * Fetch a URL and return a Promise that resolves to the response body.
+         * Resolves to parsed JSON when the Content-Type is application/json, plain text otherwise.
+         * Rejects on non-2xx responses.
+         * @param {string} url
+         * @param {RequestInit} [options]
+         * @returns {Promise<string|object>}
+         */
+        fetch: function Sandbox_http_fetch(url, options) {
+            const TIMEOUT_MS = 30_000;
+            let signal = options?.signal;
+            let timer;
+            if (!signal) {
+                const ac = new AbortController();
+                signal = ac.signal;
+                timer = setTimeout(
+                    () => ac.abort(new Error(`she.http.fetch timed out after ${TIMEOUT_MS / 1000}s`)),
+                    TIMEOUT_MS,
+                );
+            }
+            return fetch(url, { ...options, signal })
+                .then((r) => {
+                    if (!r.ok) throw new Error(`HTTP ${r.status} ${r.statusText}`);
+                    const ct = r.headers.get('content-type') || '';
+                    return ct.includes('json') ? r.json() : r.text();
+                })
+                .finally(() => clearTimeout(timer));
+        },
+        /**
+         * Register a POST webhook endpoint at /api/<scriptName><path>.
+         * The endpoint auto-responds { ok: true } (200) when the callback resolves,
+         * or { error } (500) when it throws. The callback receives:
+         *   callback(body, { params, query, headers })
+         * @param {string} path    - Route path, e.g. '/webhook/mydevice'
+         * @param {function} callback
+         */
+        sub: function Sandbox_http_sub(path, callback) {
+            const { registerRoute } = require('../web/server');
+            const { scriptName } = ctx;
+            if (typeof path !== 'string') throw new TypeError('path must be a string');
+            if (typeof callback !== 'function') throw new TypeError('callback must be a function');
+            const fullPath = '/api/' + (scriptName || 'unknown') + path;
+            registerRoute('post', fullPath, (req, res) => {
+                let result;
+                try {
+                    result = callback(req.body, { params: req.params, query: req.query, headers: req.headers });
+                } catch (err) {
+                    res.status(500).json({ error: err.message });
+                    return;
+                }
+                Promise.resolve(result)
+                    .then(() => res.json({ ok: true }))
+                    .catch((err) => res.status(500).json({ error: err.message }));
+            });
+        },
     };
 };

package/src/web/prompts/she-api-ref.md

@@ -64,17 +64,20 @@ she.matter.send(nodeId, endpointId, cluster, cmd, [args]) → Promise<result>
 
 ### Helpers
 ```
-she.timer(src, target, ms)           Pulse target=1 for ms after src goes truthy
-she.combineBool(srcs[], target)      Publish OR of source values to target
-she.combineMax(srcs[], target)       Publish maximum of source values to target
-she.link(src, target, [fn])          Alias for she.mqtt.link
-she.age(topic)                       Alias for she.mqtt.age
+she.mqtt.timer(src, ms, topicOrCb)   Pulse topicOrCb=1 for ms after src goes truthy
+                                         topicOrCb: topic string or callback(topic, val)
+she.mqtt.or(srcs[], topicOrCb)       Publish 1 if any source truthy, else 0
+she.mqtt.and(srcs[], topicOrCb)      Publish 1 if all sources truthy, else 0
+she.mqtt.max(srcs[], topicOrCb)      Publish maximum of source values
+she.mqtt.min(srcs[], topicOrCb)      Publish minimum of source values (0 if none set)
+                                         All topicOrCb: topic string or callback(topic, val)
 she.now()                            Current timestamp in ms
 she.debug / .info / .warn / .error   Structured logging (prefixed with script name)
 she.global                           Shared mutable object across all scripts
-she.fetch(url, [opts])               HTTP/HTTPS fetch → Promise<string|object>
-                                       Auto-parses JSON by Content-Type.
-                                       Throws on non-2xx status.
+she.http.fetch(url, [opts])          HTTP/HTTPS fetch → Promise<string|object>
+                                       Auto-parses JSON by Content-Type. Throws on non-2xx.
+she.http.sub(path, cb)               Register POST /api/<script><path> webhook endpoint
+                                         cb(body, { params, query, headers })
 she.config.latitude                  Read-only: geographic latitude from daemon config
 she.config.longitude                 Read-only: geographic longitude from daemon config
 ```