@johanwistbacka/node-red-contrib-sw-light 0.1.4

package/nodes/sw-light.html

@@ -0,0 +1,132 @@
+<script type="text/javascript">
+(function () {
+    const ranges = { brightnessPct: [1,100], autoMaxPct: [1,100], minPct: [1,100], overrideThreshold: [1,100], transitionOn: [0,3600], transitionOff: [0,3600], kelvin: [1000,40000], mired: [25,1000] };
+    function numeric(key) {
+        return function (value) {
+            const n = Number(value), range = ranges[key];
+            if (String(value).trim() === '' || !Number.isFinite(n) || n < range[0] || n > range[1]) return false;
+            if (key === 'kelvin' && !Number.isInteger(n)) return false;
+            if (['brightnessPct','autoMaxPct','minPct'].includes(key)) {
+                const read = k => $('#node-input-' + k).length ? Number($('#node-input-' + k).val()) : Number(this[k]);
+                if (!(read('minPct') <= read('brightnessPct') && read('brightnessPct') <= read('autoMaxPct'))) return false;
+            }
+            return true;
+        };
+    }
+    RED.nodes.registerType('sw-light', {
+        category: 'home assistant', color: '#c7d7e8', icon: 'font-awesome/fa-lightbulb-o',
+        inputs: 1, outputs: 2, outputLabels: ['result / state', 'events / errors'],
+        paletteLabel: 'SW Light', label: function () { return this.name || 'SW Light'; },
+        defaults: {
+            name: { value: '' }, server: { value: '', type: 'server', required: true },
+            action: { value: 'msg', validate: v => ['on','off','toggle','msg'].includes(v) },
+            entityId: { value: '', required: true, validate: v => /^light\.[a-z0-9_]+$/.test(v) },
+            brightnessPct: { value: 94, validate: numeric('brightnessPct') },
+            autoMaxPct: { value: 94, validate: numeric('autoMaxPct') },
+            minPct: { value: 1, validate: numeric('minPct') },
+            transitionOn: { value: 1, validate: numeric('transitionOn') },
+            transitionOff: { value: 1, validate: numeric('transitionOff') },
+            manualOverride: { value: true }, overrideThreshold: { value: 100, validate: numeric('overrideThreshold') },
+            overrideStrategy: { value: 'threshold' }, colorMode: { value: 'adaptive' },
+            kelvin: { value: 2700, validate: numeric('kelvin') }, mired: { value: 370, validate: numeric('mired') },
+            fixedColor: { value: '#ffffff', validate: v => /^#[0-9a-f]{6}$/i.test(v) },
+            adaptiveEntity: { value: '', validate: v => !v || /^switch\.[a-z0-9_]+$/.test(v) },
+            adaptiveDiscover: { value: true }, adaptiveApply: { value: false }, adaptiveRespectManual: { value: true }
+        },
+        oneditprepare: function () {
+            let states = {}, request, generation = 0;
+            const entity = $('#node-input-entityId'), adaptive = $('#node-input-adaptiveEntity');
+            function update() {
+                const mode = $('#node-input-colorMode').val();
+                $('.sw-color-row').hide();
+                $('.sw-color-' + mode).show();
+                $('.sw-override-row').toggle($('#node-input-manualOverride').prop('checked'));
+                $('.sw-threshold-row').toggle($('#node-input-manualOverride').prop('checked') && $('#node-input-overrideStrategy').val() === 'threshold');
+                const s = states[entity.val()], modes = s && s.attributes && s.attributes.supported_color_modes;
+                $('#sw-capabilities').text(modes ? 'Supported: ' + modes.join(', ') : 'Select a deployed server and light to read capabilities.');
+                // Disabled options reflect known capabilities, without discarding saved settings.
+                $('#node-input-colorMode option[value="kelvin"], #node-input-colorMode option[value="mired"]').prop('disabled', !!modes && !modes.includes('color_temp'));
+                $('#node-input-colorMode option[value="color"]').prop('disabled', !!modes && !modes.some(m => ['hs','xy','rgb','rgbw','rgbww'].includes(m)));
+            }
+            function source(domain) {
+                return function (req, respond) {
+                    const term = req.term.toLowerCase();
+                    respond(Object.values(states).filter(s => s.entity_id.startsWith(domain + '.') &&
+                        (s.entity_id.toLowerCase().includes(term) || String(s.attributes.friendly_name || '').toLowerCase().includes(term)))
+                        .slice(0,100).map(s => ({ label: (s.attributes.friendly_name || s.entity_id) + ' (' + s.entity_id + ')', value: s.entity_id })));
+                };
+            }
+            entity.autocomplete({ minLength: 0, source: source('light'), select: function (_e, ui) { entity.val(ui.item.value); update(); } });
+            adaptive.autocomplete({ minLength: 0, source: source('switch') });
+            function load() {
+                generation++; const token = generation;
+                if (request) request.abort();
+                states = {}; update();
+                const server = $('#node-input-server').val();
+                if (!server || server === '_ADD_') return;
+                $('#sw-capabilities').text('Loading Home Assistant entities…');
+                // HA contrib's own editor endpoint. No auth tokens or static entity lists.
+                request = $.getJSON('homeassistant/states/' + encodeURIComponent(server))
+                    .done(function (data) { if (token === generation) { states = data || {}; update(); } })
+                    .fail(function (_xhr, status) { if (status !== 'abort' && token === generation) $('#sw-capabilities').text('Server must be deployed and connected. Entity IDs can also be entered directly.'); });
+            }
+            $('#node-input-server').on('change.swLight', load);
+            $('#node-input-colorMode, #node-input-manualOverride, #node-input-overrideStrategy, #node-input-entityId').on('change.swLight', update);
+            entity.on('focus.swLight', function () { entity.autocomplete('search', entity.val()); });
+            adaptive.on('focus.swLight', function () { adaptive.autocomplete('search', adaptive.val()); });
+            this._swCleanup = function () {
+                generation++; if (request) request.abort();
+                $('#node-input-server, #node-input-colorMode, #node-input-manualOverride, #node-input-overrideStrategy, #node-input-entityId, #node-input-adaptiveEntity').off('.swLight');
+                entity.autocomplete('destroy'); adaptive.autocomplete('destroy');
+                delete this._swCleanup;
+            };
+            load(); update();
+        },
+        oneditsave: function () { if (this._swCleanup) this._swCleanup(); },
+        oneditcancel: function () { if (this._swCleanup) this._swCleanup(); }
+    });
+})();
+</script>
+
+<script type="text/html" data-template-name="sw-light">
+    <div class="form-row"><label for="node-input-name"><i class="fa fa-tag"></i> Name</label><input id="node-input-name" type="text" placeholder="SW Light"></div>
+    <div class="form-row"><label for="node-input-server"><i class="fa fa-server"></i> HA server</label><input id="node-input-server" type="text"></div>
+    <div class="form-row"><label for="node-input-entityId"><i class="fa fa-lightbulb-o"></i> Light</label><input id="node-input-entityId" type="text" placeholder="light.entity_id"></div>
+    <div class="form-row"><label for="node-input-action">Action</label><select id="node-input-action"><option value="on">On</option><option value="off">Off</option><option value="toggle">Toggle</option><option value="msg">From msg</option></select></div>
+    <div class="form-tips" id="sw-capabilities" style="margin-bottom:16px"></div>
+    <fieldset><legend>Automatic lighting</legend>
+        <div class="form-row"><label for="node-input-brightnessPct">On brightness %</label><input id="node-input-brightnessPct" type="number" min="1" max="100" step="0.1"></div>
+        <div class="form-row"><label for="node-input-autoMaxPct">Auto maximum %</label><input id="node-input-autoMaxPct" type="number" min="1" max="100" step="0.1"></div>
+        <div class="form-row"><label for="node-input-minPct">Minimum %</label><input id="node-input-minPct" type="number" min="1" max="100" step="0.1"></div>
+        <div class="form-row"><label for="node-input-transitionOn">On fade (s)</label><input id="node-input-transitionOn" type="number" min="0" max="3600" step="0.1"></div>
+        <div class="form-row"><label for="node-input-transitionOff">Off fade (s)</label><input id="node-input-transitionOff" type="number" min="0" max="3600" step="0.1"></div>
+    </fieldset>
+    <fieldset><legend>Manual override</legend>
+        <div class="form-row"><label for="node-input-manualOverride">Enable</label><input id="node-input-manualOverride" type="checkbox" style="width:auto"></div>
+        <div class="form-row sw-override-row"><label for="node-input-overrideStrategy">Detection</label><select id="node-input-overrideStrategy"><option value="threshold">Brightness threshold + explicit flag</option><option value="explicit">Explicit flag only</option></select></div>
+        <div class="form-row sw-threshold-row"><label for="node-input-overrideThreshold">Threshold %</label><input id="node-input-overrideThreshold" type="number" min="1" max="100" step="0.1"></div>
+        <p class="sw-override-row">Automatic commands pause during override. Manual commands use <code>msg.source = "manual"</code>.</p>
+    </fieldset>
+    <fieldset><legend>Color</legend>
+        <div class="form-row"><label for="node-input-colorMode">Mode</label><select id="node-input-colorMode"><option value="adaptive">Adaptive Lighting</option><option value="keep">Keep current</option><option value="kelvin">Fixed Kelvin</option><option value="mired">Fixed mired</option><option value="default">Lamp default</option><option value="color">Fixed color</option></select></div>
+        <div class="form-row sw-color-row sw-color-kelvin"><label for="node-input-kelvin">Kelvin</label><input id="node-input-kelvin" type="number" min="1000" max="40000"></div>
+        <div class="form-row sw-color-row sw-color-mired"><label for="node-input-mired">Mired</label><input id="node-input-mired" type="number" min="25" max="1000" step="0.1"></div>
+        <div class="form-row sw-color-row sw-color-color"><label for="node-input-fixedColor">Color</label><input id="node-input-fixedColor" type="color"></div>
+        <div class="form-row sw-color-row sw-color-adaptive"><label for="node-input-adaptiveEntity">Adaptive switch</label><input id="node-input-adaptiveEntity" type="text" placeholder="Optional switch.entity_id"></div>
+        <div class="form-row sw-color-row sw-color-adaptive"><label for="node-input-adaptiveDiscover">Discover</label><input id="node-input-adaptiveDiscover" type="checkbox" style="width:auto"> From a unique light membership match</div>
+        <div class="form-row sw-color-row sw-color-adaptive"><label for="node-input-adaptiveApply">Apply on turn-on</label><input id="node-input-adaptiveApply" type="checkbox" style="width:auto"> Color only</div>
+        <div class="form-row sw-color-row sw-color-adaptive"><label for="node-input-adaptiveRespectManual">Respect manual</label><input id="node-input-adaptiveRespectManual" type="checkbox" style="width:auto"></div>
+        <p class="sw-color-row sw-color-adaptive">Ordinary turn-on sends no color. Adaptive Lighting owns color adaptation. Apply is optional and never clears its manual control.</p>
+    </fieldset>
+</script>
+
+<script type="text/html" data-help-name="sw-light">
+    <p>Controls one Home Assistant light directly: Trigger → SW Light → Home Assistant. No downstream HA Action node is required. Select On, Off, Toggle, or From msg. Toggle resolves the current state to turn_on or turn_off.</p>
+    <h3>Inputs</h3>
+    <dl class="message-properties"><dt>action <span class="property-type">string</span></dt><dd>Required with From msg: <code>on</code>, <code>off</code>, or <code>toggle</code>. Falls back to <code>msg.auto_light.action</code> when msg.action is absent. Fixed Action settings ignore message actions.</dd><dt class="optional">source <span class="property-type">string</span></dt><dd><code>automatic</code> (default) or <code>manual</code>.</dd><dt class="optional">brightness_pct <span class="property-type">number</span></dt><dd>0–100. Automatic brightness is capped at the configured maximum.</dd><dt class="optional">transition <span class="property-type">number</span></dt><dd>Fade seconds, 0–3600, if supported.</dd><dt class="optional">manual_override <span class="property-type">boolean</span></dt><dd>Latch/release override with <code>source: "manual"</code>.</dd></dl>
+    <h3>Outputs</h3><ol><li>Original message plus <code>msg.sw_light</code>: last observed HA state, action, service data, and override/adaptive information.</li><li>Original message plus <code>msg.sw_light_event</code>: version, type, entity_id, timestamp, and details.</li></ol>
+    <h3>Details</h3><p>Default on brightness/max 94%, minimum 1%, fade 1s. ON at 100% (brightness 255) always blocks automatic ON, OFF and Toggle. 94%, 95% and 99% do not trigger this guard. Optional threshold/explicit overrides can also pause automation. Lowering brightness below the threshold releases its flag; turning off releases all override flags. Manual commands bypass the automatic maximum. Explicit flags require explicit release or off.</p>
+    <p>Top-level message properties override configuration. Brightness precedence: percent, byte, percent step, byte step. Color precedence: Kelvin, mired, RGBWW, RGBW, RGB, HS, XY, name. Invalid values produce errors; unsupported parameters emit an event and are omitted.</p>
+    <p>Adaptive mode sends no configured color. An explicit message color takes precedence and suppresses optional adaptive apply for that command. Keep current and lamp default both omit configured color and leave HA/device behavior in control.</p>
+    <p>Requires HA contrib 0.80.3. See package README for full contracts, examples and compatibility limitations.</p>
+</script>

package/nodes/sw-light.js

@@ -0,0 +1,139 @@
+'use strict';
+
+const light = require('../lib/light');
+const adaptive = require('../lib/adaptive');
+const { createAdapter } = require('../lib/ha-adapter');
+
+// Optional factory is for isolated transport/lifecycle tests, never flow config.
+module.exports = function register(RED, adapterFactory = createAdapter) {
+    function SWLight(raw) {
+        RED.nodes.createNode(this, raw);
+        const node = this;
+        node.log?.(`[SW Light debug] version=${require('../package.json').version} constructor=created serverIdPresent=${Boolean(raw.server)}`);
+        let c, detector, adapter, closed = false, lastAvailability;
+        let queue = Promise.resolve(), startup = Promise.resolve();
+        const protectedAtFullBrightness = state => state?.state === 'on' && state.attributes?.brightness === 255;
+        const overrideActive = state => detector.active || protectedAtFullBrightness(state);
+        function event(type, detail = {}, msg = {}, send = node.send.bind(node)) {
+            if (closed) return;
+            send([null, { ...msg, sw_light_event: { version: 1, type, entity_id: c?.entityId ?? raw.entityId,
+                timestamp: new Date().toISOString(), ...detail } }]);
+        }
+        function overrideUpdate(fn, msg, send) {
+            const before = detector.active;
+            fn();
+            if (before !== detector.active) event(detector.active ? 'manual_override' : 'override_released',
+                { active: detector.active, strategy: c.overrideStrategy }, msg, send);
+        }
+        function observe(state) {
+            if (closed) return;
+            overrideUpdate(() => detector.observe(state));
+            const availability = !state ? 'missing' : state.state;
+            if (['missing', 'unknown', 'unavailable'].includes(availability)) {
+                node.status({ fill: 'red', shape: 'ring', text: 'ENTITY UNAVAILABLE' });
+                if (lastAvailability !== availability) event('unavailable', { reason: availability });
+            } else {
+                const active = overrideActive(state);
+                const info = light.normalized(state, active, c.colorMode === 'adaptive', 'state_changed');
+                let text = active ? 'MANUAL' : `AUTO · ${info.state.toUpperCase()}`;
+                if (info.state === 'on' && info.brightness_pct !== null) text += ` · ${info.brightness_pct}%`;
+                if (info.state === 'on' && info.color_temp_kelvin) text += ` · ${info.color_temp_kelvin}K`;
+                if (info.state === 'on' && c.colorMode === 'adaptive') text += ' · adaptive';
+                node.status({ fill: active ? 'yellow' : info.state === 'on' ? 'green' : 'grey', shape: 'dot', text });
+            }
+            lastAvailability = availability;
+        }
+        function connection(ready) {
+            if (closed) return;
+            if (ready) observe(adapter.state(c.entityId));
+            else {
+                node.status({ fill: 'red', shape: 'ring', text: 'HA NOT READY' });
+                if (lastAvailability !== 'disconnected') event('unavailable', { reason: 'disconnected' });
+                lastAvailability = 'disconnected';
+            }
+        }
+        function startAdapter() {
+            adapter = adapterFactory(RED, c.server, undefined, detail => node.log?.(`[SW Light debug] ${detail}`));
+            startup = adapter.subscribe(c.entityId, observe, connection,
+                error => event('error', { message: error.message })).catch(error => {
+                if (!closed) { node.status({ fill: 'red', shape: 'ring', text: 'subscription failed' }); event(error.eventType || 'error', { message: error.message }); }
+            });
+            connection(adapter.connected());
+        }
+        try {
+            c = light.config(raw);
+            detector = new light.Override(c);
+            // No HA module/client resolution during Flow.start. Startup order
+            // cannot permanently disable this node; first input resolves HA.
+            node.status({ fill: 'red', shape: 'ring', text: 'HA NOT READY' });
+        } catch (error) {
+            node.status({ fill: 'red', shape: 'ring', text: 'CONFIG ERROR' });
+            node.error(error.message);
+            node.swLightError = error;
+        }
+        node.on('input', (msg, send, done) => {
+            send = send || node.send.bind(node);
+            done = done || (error => { if (error) node.error(error, msg); });
+            const run = async () => {
+                if (closed) { done(); return; }
+                let command, serviceCompleted = false;
+                try {
+                    if (node.swLightError) throw node.swLightError;
+                    // A temporarily absent/uninitialized provider is retried on
+                    // the next input, rather than freezing the constructor error.
+                    if (!adapter) startAdapter();
+                    if (adapter.resolve) await adapter.resolve();
+                    if (closed) { done(); return; }
+                    if (!adapter.connected()) throw light.fault('Home Assistant is disconnected or loading states', 'unavailable');
+                    const state = adapter.state(c.entityId);
+                    if (!state || !['on', 'off'].includes(state.state)) throw light.fault(`Light is ${state?.state ?? 'missing'}`, 'unavailable');
+                    observe(state);
+                    const requestedOverride = Object.prototype.hasOwnProperty.call(msg, 'manual_override');
+                    if (requestedOverride && (msg.source ?? 'automatic') !== 'manual') throw light.fault('manual_override requires source: manual');
+                    if (requestedOverride && typeof msg.manual_override !== 'boolean') throw light.fault('manual_override must be boolean');
+                    command = light.plan(c, msg, state, overrideActive(state));
+                    if (requestedOverride) {
+                        overrideUpdate(() => detector.set(msg.manual_override), msg, send);
+                        command.blocked = false; // validated manual source
+                    }
+                    if (command.unsupported.length) event('unsupported', { parameters: command.unsupported, reason: 'lamp_capabilities_or_action' }, msg, send);
+                    if (command.blocked) {
+                        event('manual_override', { active: true, blocked: true, requested_action: command.action }, msg, send);
+                        const percent = Number.isFinite(state.attributes?.brightness) ? Math.round(light.pct(state.attributes.brightness)) : '?';
+                        node.status({ fill: 'yellow', shape: 'dot', text: `MANUAL · ${percent}% · BLOCK ${command.action.toUpperCase()}` });
+                        done(); return;
+                    }
+                    await adapter.call('light', command.service, command.data, { entity_id: c.entityId });
+                    serviceCompleted = true;
+                    if (closed) { done(); return; }
+                    let adaptiveResult;
+                    try { adaptiveResult = await adaptive.apply(adapter, c, command); }
+                    catch (error) { event(error.eventType || 'error', { message: error.message, phase: 'adaptive_apply', light_service_completed: true }, msg, send); }
+                    if (closed) { done(); return; }
+                    const current = adapter.state(c.entityId);
+                    observe(current);
+                    send([{ ...msg, sw_light: { ...light.normalized(current, overrideActive(current), c.colorMode === 'adaptive', command.service),
+                        entity_id: c.entityId, source: command.source, requested_action: command.action,
+                        service_data: command.data, ignored_conflicts: command.ignoredConflicts,
+                        state_confirmation: 'last_observed', adaptive: { ...adaptive.inspect(c, adapter.states()), ...adaptiveResult } } }, null]);
+                    const level = command.data.brightness === undefined ? '' : ` · ${Math.round(light.pct(command.data.brightness))}%`;
+                    node.status({ fill: command.source === 'manual' ? 'yellow' : command.turningOn ? 'green' : 'grey', shape: 'dot',
+                        text: `${command.source === 'manual' ? 'MANUAL' : 'AUTO'} · ${command.turningOn ? 'ON' : 'OFF'}${level}` });
+                    done();
+                } catch (error) {
+                    event(error.eventType || 'error', { message: error.message, light_service_completed: serviceCompleted }, msg, send);
+                    if (!closed) node.status({ fill: 'red', shape: 'ring', text: error.eventType === 'config_error' ? 'CONFIG ERROR' :
+                        error.eventType === 'unavailable' ? (error.message.startsWith('HA NOT READY:') || !adapter || !adapter.connected() ? 'HA NOT READY' : 'ENTITY UNAVAILABLE') : error.message });
+                    done(error);
+                }
+            };
+            // Serialize relative brightness and toggles; contain all asynchronous failures.
+            queue = queue.then(run).catch(error => { done(error); });
+        });
+        node.on('close', (_removed, done) => {
+            closed = true;
+            Promise.resolve().then(() => adapter?.close()).then(() => startup).catch(() => {}).finally(() => done());
+        });
+    }
+    RED.nodes.registerType('sw-light', SWLight);
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@johanwistbacka/node-red-contrib-sw-light",
+  "version": "0.1.4",
+  "description": "Home Assistant light control with automatic brightness limits and manual override",
+  "license": "MIT",
+  "keywords": [
+    "node-red",
+    "home-assistant",
+    "light",
+    "adaptive-lighting"
+  ],
+  "engines": {
+    "node": ">=18.2.0"
+  },
+  "node-red": {
+    "version": ">=3.1.1",
+    "nodes": {
+      "sw-light": "nodes/sw-light.js"
+    }
+  },
+  "peerDependencies": {
+    "node-red-contrib-home-assistant-websocket": "0.80.3"
+  },
+  "files": [
+    "nodes/sw-light.js",
+    "nodes/sw-light.html",
+    "lib/light.js",
+    "lib/adaptive.js",
+    "lib/ha-adapter.js",
+    "examples/basic.json",
+    "examples/manual-adaptive.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node scripts/check.js"
+  },
+  "author": "Johan Wistbacka",
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest",
+    "registry": "https://registry.npmjs.org/"
+  }
+}