homebridge-tuya-plus 3.14.0-dev.19 → 3.14.0-dev.21

package/test/IrrigationSystemAccessory.test.js

@@ -473,46 +473,19 @@ describe('IrrigationSystemAccessory — charging state', () => {
     });
 });
 
-describe('IrrigationSystemAccessory — cloud mode (data-points keyed by code)', () => {
-    // Mirrors a real Tuya "sfkzq" watering controller reached over the cloud:
-    // valves are switch_1..4 and battery is battery_percentage.
-    const cloudState = () => ({ switch_1: false, switch_2: false, switch_3: false, switch_4: false, battery_percentage: 99 });
-    const cloudCtx = { cloud: true };
-
+describe('IrrigationSystemAccessory — data-points addressed by code', () => {
+    // The accessory is transport-agnostic: a data-point may be a numeric id or a
+    // Tuya "code". The LAN+cloud TuyaDevice keeps state dual-keyed and translates
+    // writes, so irrigation has no cloud-specific logic — it just uses the dp
+    // strings it's given. A device reached over the cloud commonly addresses its
+    // zones as switch_1.. and battery as battery_percentage.
     beforeEach(() => jest.useFakeTimers());
     afterEach(() => { jest.clearAllTimers(); jest.useRealTimers(); });
 
-    test('default valves use Tuya codes switch_1..switch_4 (not numeric ids)', () => {
-        const { accessory } = makeHarness(cloudState(), cloudCtx);
-        ['switch_1', 'switch_2', 'switch_3', 'switch_4'].forEach(code => {
-            expect(valve(accessory, code)).toBeTruthy();
-        });
-        expect(valve(accessory, '1')).toBeFalsy();
-    });
-
-    test('turning a zone on writes the code/value to the device', () => {
-        const { accessory, device } = makeHarness(cloudState(), cloudCtx);
-        valve(accessory, 'switch_1').getCharacteristic(Characteristic.Active).triggerSet(1);
-        jest.advanceTimersByTime(500);
-        expect(device.update).toHaveBeenCalledWith({ switch_1: true });
-    });
-
-    test('battery is read from the battery_percentage code', () => {
-        const { accessory } = makeHarness(cloudState(), cloudCtx);
-        const battery = accessory.getService(Service.Battery);
-        expect(battery.getCharacteristic(Characteristic.BatteryLevel).value).toBe(99);
-    });
-
-    test('a realtime change keyed by code is reflected in HomeKit', () => {
-        const { accessory, device } = makeHarness(cloudState(), cloudCtx);
-        device.emitChange({ switch_2: true });
-        expect(valve(accessory, 'switch_2').getCharacteristic(Characteristic.Active).value).toBe(Characteristic.Active.ACTIVE);
-    });
-
-    test('an explicit valve list may use custom codes', () => {
+    test('an explicit valve list may use string codes', () => {
         const { accessory, device } = makeHarness(
             { zone_a: false, zone_b: false, battery_percentage: 50 },
-            { cloud: true, valves: [{ name: 'A', dp: 'zone_a' }, { name: 'B', dp: 'zone_b' }] }
+            { valves: [{ name: 'A', dp: 'zone_a' }, { name: 'B', dp: 'zone_b' }], dpBattery: 'battery_percentage' }
         );
         expect(valve(accessory, 'zone_a')).toBeTruthy();
         valve(accessory, 'zone_b').getCharacteristic(Characteristic.Active).triggerSet(1);
@@ -520,35 +493,57 @@ describe('IrrigationSystemAccessory — cloud mode (data-points keyed by code)',
         expect(device.update).toHaveBeenCalledWith({ zone_b: true });
     });
 
-    test('turning a zone off still writes false when the cloud never echoed the "on"', () => {
-        // The real cloud device never optimistically advances `state`; it only
-        // moves when the realtime stream confirms the device. Emulate that by
-        // making update() a no-op on state. A follow-up "off" must STILL be sent
-        // — otherwise the valve stays open while HomeKit shows it closed (the
+    test('battery can be read from a code data-point', () => {
+        const { accessory } = makeHarness(
+            { zone_a: false, battery_percentage: 99 },
+            { valves: [{ name: 'A', dp: 'zone_a' }], dpBattery: 'battery_percentage' }
+        );
+        expect(accessory.getService(Service.Battery).getCharacteristic(Characteristic.BatteryLevel).value).toBe(99);
+    });
+
+    test('a device-side change keyed by code is reflected in HomeKit', () => {
+        const { accessory, device } = makeHarness(
+            { zone_a: false, zone_b: false },
+            { valves: [{ name: 'A', dp: 'zone_a' }, { name: 'B', dp: 'zone_b' }], noBattery: true }
+        );
+        device.emitChange({ zone_b: true });
+        expect(valve(accessory, 'zone_b').getCharacteristic(Characteristic.Active).value).toBe(Characteristic.Active.ACTIVE);
+    });
+
+    test('turning a zone off still writes false when the device never echoed the "on"', () => {
+        // A device (notably over the cloud) may not optimistically advance `state`;
+        // it only moves when the device confirms. A follow-up "off" must STILL be
+        // sent — otherwise the valve stays open while HomeKit shows it closed (the
         // exact "can turn on but not off" report).
-        const { accessory, device } = makeHarness(cloudState(), { ...cloudCtx, defaultDuration: 0 });
+        const { accessory, device } = makeHarness(
+            { zone_a: false },
+            { valves: [{ name: 'A', dp: 'zone_a' }], noBattery: true, defaultDuration: 0 }
+        );
         device.update.mockImplementation(() => true); // writes never touch state
-        const v = valve(accessory, 'switch_1');
+        const v = valve(accessory, 'zone_a');
 
         v.getCharacteristic(Characteristic.Active).triggerSet(1);
         jest.advanceTimersByTime(500);
-        expect(device.update).toHaveBeenLastCalledWith({ switch_1: true });
+        expect(device.update).toHaveBeenLastCalledWith({ zone_a: true });
 
         v.getCharacteristic(Characteristic.Active).triggerSet(0);
         jest.advanceTimersByTime(500);
-        expect(device.update).toHaveBeenLastCalledWith({ switch_1: false });
+        expect(device.update).toHaveBeenLastCalledWith({ zone_a: false });
     });
 
-    test('master OFF closes zones the cloud has not echoed as open', () => {
-        const { accessory, device } = makeHarness(cloudState(), { ...cloudCtx, defaultDuration: 0 });
+    test('master OFF closes zones the device has not echoed as open', () => {
+        const { accessory, device } = makeHarness(
+            { zone_a: false, zone_b: false },
+            { valves: [{ name: 'A', dp: 'zone_a' }, { name: 'B', dp: 'zone_b' }], noBattery: true, defaultDuration: 0 }
+        );
         device.update.mockImplementation(() => true); // writes never touch state
 
-        valve(accessory, 'switch_1').getCharacteristic(Characteristic.Active).triggerSet(1);
-        valve(accessory, 'switch_2').getCharacteristic(Characteristic.Active).triggerSet(1);
+        valve(accessory, 'zone_a').getCharacteristic(Characteristic.Active).triggerSet(1);
+        valve(accessory, 'zone_b').getCharacteristic(Characteristic.Active).triggerSet(1);
         jest.advanceTimersByTime(500);
 
         irrigation(accessory).getCharacteristic(Characteristic.Active).triggerSet(0);
         jest.advanceTimersByTime(500);
-        expect(device.update).toHaveBeenLastCalledWith({ switch_1: false, switch_2: false });
+        expect(device.update).toHaveBeenLastCalledWith({ zone_a: false, zone_b: false });
     });
 });

package/test/SimpleGarageDoorAccessory.test.js

@@ -52,6 +52,8 @@ function makeSimpleGarage(initialContext = {}) {
     instance.stopBeforeCloseMs = 1500;
     instance.partialStopTimer = null;
     instance.pendingCloseTimer = null;
+    instance.partialPending = false;
+    instance.partialGeneration = 0;
     instance.currentDoorState = CDS.CLOSED;
     instance.characteristicCurrentDoorState = {
         value: CDS.CLOSED,
@@ -409,35 +411,71 @@ describe('SimpleGarageDoorAccessory._handlePartialOpen', () => {
     beforeEach(() => jest.useFakeTimers());
     afterEach(() => jest.useRealTimers());
 
-    test('Fires open, then fires stop after partialOpenMs', () => {
+    test('Stop is anchored to the gate reporting it is moving, not the button press', () => {
         const { instance, device } = makeSimpleGarage();
         instance.partialOpenMs = 2000;
+        // Gate starts closed, so the open command needs time to reach it and
+        // get the gate moving before a stop can do anything.
+        device.state['105'] = STATE_CLOSING_OR_CLOSED;
 
         instance._handlePartialOpen();
 
-        // Open goes out immediately.
+        // Open goes out immediately, but the auto-stop is NOT armed yet.
         expect(device.update).toHaveBeenCalledTimes(1);
         expect(device.update).toHaveBeenNthCalledWith(1, { '101': true });
         expect(instance.characteristicTargetDoorState.value).toBe(TDS.OPEN);
+        expect(instance.partialStopTimer).toBeNull();
+        expect(instance.partialPending).toBe(true);
+
+        // No amount of waiting fires a stop until the gate reports it's moving —
+        // this is what stops a too-early stop from being a dropped no-op.
+        jest.advanceTimersByTime(10_000);
+        expect(device.update).toHaveBeenCalledTimes(1);
+
+        // Controller reports it has started opening: now the countdown arms.
+        emitState(device, STATE_OPENING_OR_OPEN);
+        expect(instance.partialStopTimer).not.toBeNull();
+        expect(instance.partialPending).toBe(false);
 
-        // Nothing happens until the timer elapses.
         jest.advanceTimersByTime(2000 - 1);
         expect(device.update).toHaveBeenCalledTimes(1);
 
-        // Then a single stop is fired.
+        // The stop fires, and is re-sent a couple of times to survive a dropped
+        // write (the controller occasionally drops a lone command).
         jest.advanceTimersByTime(1);
         expect(device.update).toHaveBeenCalledTimes(2);
         expect(device.update).toHaveBeenNthCalledWith(2, { '103': true });
+        jest.advanceTimersByTime(300);
+        expect(device.update).toHaveBeenNthCalledWith(3, { '103': true });
+        jest.advanceTimersByTime(300);
+        expect(device.update).toHaveBeenNthCalledWith(4, { '103': true });
 
-        // And nothing more after that.
+        // And nothing more after the re-sends.
         jest.advanceTimersByTime(10_000);
-        expect(device.update).toHaveBeenCalledTimes(2);
+        expect(device.update).toHaveBeenCalledTimes(4);
         expect(instance.partialStopTimer).toBeNull();
     });
 
-    test('Re-entrant press while armed is ignored (idempotent)', () => {
+    test('Arms straight away when the gate already reports open/opening', () => {
         const { instance, device } = makeSimpleGarage();
         instance.partialOpenMs = 2000;
+        device.state['105'] = STATE_OPENING_OR_OPEN;
+
+        instance._handlePartialOpen();
+
+        // Open fired and the countdown armed without waiting for a fresh report.
+        expect(device.update).toHaveBeenNthCalledWith(1, { '101': true });
+        expect(instance.partialStopTimer).not.toBeNull();
+        expect(instance.partialPending).toBe(false);
+
+        jest.advanceTimersByTime(2000);
+        expect(device.update).toHaveBeenNthCalledWith(2, { '103': true });
+    });
+
+    test('Re-entrant press while in progress is ignored (idempotent)', () => {
+        const { instance, device } = makeSimpleGarage();
+        instance.partialOpenMs = 2000;
+        device.state['105'] = STATE_OPENING_OR_OPEN; // arms immediately
 
         instance._handlePartialOpen();
         expect(device.update).toHaveBeenCalledTimes(1);
@@ -454,6 +492,20 @@ describe('SimpleGarageDoorAccessory._handlePartialOpen', () => {
         expect(device.update).toHaveBeenNthCalledWith(2, { '103': true });
     });
 
+    test('Re-entrant press while waiting for movement is ignored', () => {
+        const { instance, device } = makeSimpleGarage();
+        instance.partialOpenMs = 2000;
+        device.state['105'] = STATE_CLOSING_OR_CLOSED;
+
+        instance._handlePartialOpen();
+        expect(device.update).toHaveBeenCalledTimes(1); // open
+        expect(instance.partialPending).toBe(true);
+
+        // A second press before the gate reports moving must not fire another open.
+        instance._handlePartialOpen();
+        expect(device.update).toHaveBeenCalledTimes(1);
+    });
+
     test('A direct close cancels the partial auto-stop and runs stop-before-close', () => {
         const { instance, device } = makeSimpleGarage();
         instance.partialOpenMs = 2000;

package/test/TuyaCloudApi.test.js

@@ -138,6 +138,23 @@ describe('TuyaCloudApi — endpoints', () => {
         await expect(api.getStatus('dev')).resolves.toEqual([{code: 'switch_1', value: true}]);
     });
 
+    test('getShadowProperties returns the properties array (code + dp_id)', async () => {
+        const api = ready();
+        let path;
+        api._httpsRequest = async (method, p) => {
+            path = p;
+            return {success: true, result: {properties: [{code: 'switch_led', dp_id: 20, value: true}]}};
+        };
+        await expect(api.getShadowProperties('dev')).resolves.toEqual([{code: 'switch_led', dp_id: 20, value: true}]);
+        expect(path).toBe('/v2.0/cloud/thing/dev/shadow/properties');
+    });
+
+    test('getShadowProperties returns null (never throws) when the shadow API is unavailable', async () => {
+        const api = ready();
+        api._httpsRequest = async () => ({success: false, code: 1106, msg: 'permission deny'});
+        await expect(api.getShadowProperties('dev')).resolves.toBeNull();
+    });
+
     test('getDeviceInfo returns the device record (with online status)', async () => {
         const api = ready();
         let path;

package/test/TuyaCloudDevice.test.js

@@ -127,6 +127,55 @@ describe('TuyaCloudDevice', () => {
         expect(dev.connected).toBe(false);
     });
 
+    test('builds the code<->dp_id map and dual-keys state from the shadow', async () => {
+        const props = [{code: 'switch_1', dp_id: 1, value: false}, {code: 'battery_percentage', dp_id: 46, value: 99}];
+        const api = makeApi();
+        api.getShadowProperties = jest.fn().mockResolvedValue(props);
+        const dev = makeDevice(api);
+        await dev._connect();
+
+        expect(api.getShadowProperties).toHaveBeenCalledWith('dev1');
+        expect(dev.codeByDpId).toEqual({'1': 'switch_1', '46': 'battery_percentage'});
+        expect(dev.dpIdByCode).toEqual({'switch_1': '1', 'battery_percentage': '46'});
+        // state is addressable by BOTH the cloud code and the numeric LAN dp id
+        expect(dev.state).toEqual({switch_1: false, '1': false, battery_percentage: 99, '46': 99});
+    });
+
+    test('update translates a numeric dp id to its cloud code', async () => {
+        const api = makeApi();
+        api.getShadowProperties = jest.fn().mockResolvedValue([{code: 'switch_1', dp_id: 1, value: false}]);
+        const dev = makeDevice(api);
+        await dev._connect();
+
+        dev.update({'1': true}); // a LAN-style numeric write
+        expect(api.sendCommands).toHaveBeenCalledWith('dev1', [{code: 'switch_1', value: true}]);
+    });
+
+    test('realtime code-only deltas are mirrored to numeric ids via the learned map', async () => {
+        const api = makeApi();
+        api.getShadowProperties = jest.fn().mockResolvedValue([{code: 'switch_1', dp_id: 1, value: false}]);
+        const dev = makeDevice(api);
+        await dev._connect();
+
+        const changes = [];
+        dev.on('change', c => changes.push(c));
+        dev._applyStatus([{code: 'switch_1', value: true}]); // code-only (as MQTT delivers)
+        expect(dev.state.switch_1).toBe(true);
+        expect(dev.state['1']).toBe(true);
+        expect(changes[0]).toEqual({switch_1: true, '1': true});
+    });
+
+    test('falls back to /status (code-only) when the shadow is unavailable', async () => {
+        const api = makeApi();
+        api.getShadowProperties = jest.fn().mockResolvedValue(null);
+        const dev = makeDevice(api);
+        await dev._connect();
+
+        expect(dev.codeByDpId).toEqual({});
+        expect(dev.state).toEqual({switch_1: false, battery_percentage: 99}); // code-only, no numeric mirror
+        expect(api.getStatus).toHaveBeenCalledWith('dev1');
+    });
+
     test('subscribes to realtime and re-reads state when the stream (re)connects', async () => {
         const api = makeApi();
         const messaging = Object.assign(new EventEmitter(), {

package/test/TuyaDevice.test.js

@@ -0,0 +1,252 @@
+'use strict';
+
+// The LAN backend opens real TCP sockets; stub it so attachLan() can be tested
+// without touching the network. Cloud backend stays real (it's inert with
+// connect:false).
+jest.mock('../lib/TuyaAccessory', () => jest.fn().mockImplementation(function(props) {
+    this.context = {...props};
+    this.connected = false;
+    this.state = {};
+    this.update = jest.fn().mockReturnValue(true);
+    this.on = jest.fn();
+    this._connect = jest.fn();
+}));
+
+const EventEmitter = require('events');
+const TuyaDevice = require('../lib/TuyaDevice');
+const TuyaCloudDevice = require('../lib/TuyaCloudDevice');
+
+const log = {info: () => {}, warn: () => {}, error: () => {}, debug: () => {}};
+
+// A minimal stand-in for either backend (TuyaAccessory / TuyaCloudDevice): an
+// EventEmitter exposing the surface TuyaDevice routes through.
+function fakeBackend(extra = {}) {
+    const b = new EventEmitter();
+    b.connected = false;
+    b.state = {};
+    b.update = jest.fn().mockReturnValue(true);
+    b.codeByDpId = {};
+    b.dpIdByCode = {};
+    b._connect = jest.fn();
+    return Object.assign(b, extra);
+}
+
+function makeDevice(props = {}) {
+    return new TuyaDevice({id: 'dev1', key: 'k', name: 'Lamp', type: 'switch', log, connect: false, ...props});
+}
+
+// Attach fake backends to a device and wire their events (white-box, so the merge
+// / fallback logic can be exercised without any real network).
+function withBackends(dev, {lan, cloud} = {}) {
+    if (cloud) { dev.cloud = cloud; dev._wire(cloud, 'cloud'); }
+    if (lan) { dev.lan = lan; dev._wire(lan, 'lan'); }
+    return dev;
+}
+
+describe('TuyaDevice — connectivity', () => {
+    test('connected reflects either backend', () => {
+        const dev = makeDevice();
+        const lan = fakeBackend();
+        const cloud = fakeBackend();
+        withBackends(dev, {lan, cloud});
+
+        expect(dev.connected).toBe(false);
+        lan.connected = true;
+        expect(dev.connected).toBe(true);
+        lan.connected = false;
+        cloud.connected = true;
+        expect(dev.connected).toBe(true);
+    });
+
+    test("'connect' is emitted once, on the first backend to connect", () => {
+        const dev = makeDevice();
+        const lan = fakeBackend();
+        const cloud = fakeBackend();
+        withBackends(dev, {lan, cloud});
+
+        let connects = 0;
+        dev.on('connect', () => connects++);
+        lan.emit('connect');
+        cloud.emit('connect');
+        expect(connects).toBe(1);
+    });
+});
+
+describe('TuyaDevice — pure LAN (no cloud) preserves legacy behaviour', () => {
+    test('update returns the synchronous boolean from the LAN backend', () => {
+        const dev = makeDevice();
+        const lan = fakeBackend({connected: true});
+        withBackends(dev, {lan});
+
+        lan.update.mockReturnValue(true);
+        expect(dev.update({'1': false})).toBe(true);
+        expect(lan.update).toHaveBeenCalledWith({'1': false});
+
+        lan.update.mockReturnValue(false);
+        expect(dev.update({'1': true})).toBe(false);
+    });
+
+    test('update is false when there is no transport at all', () => {
+        const dev = makeDevice();
+        expect(dev.update({'1': true})).toBe(false);
+    });
+});
+
+describe('TuyaDevice — state merge & registration', () => {
+    test('first change drives registration and exposes the merged state', () => {
+        const dev = makeDevice();
+        const lan = fakeBackend({connected: true, state: {'1': true, '2': 50}});
+        withBackends(dev, {lan});
+
+        const seen = [];
+        dev.on('change', (changes, state) => seen.push({changes, state}));
+        lan.emit('change');
+
+        expect(seen).toHaveLength(1);
+        expect(seen[0].state).toEqual({'1': true, '2': 50});
+    });
+
+    test('LAN wins over the cloud while connected; cloud-only DPs are kept; LAN is mirrored to codes', () => {
+        const dev = makeDevice();
+        const lan = fakeBackend({connected: true, state: {'1': true}});
+        const cloud = fakeBackend({
+            connected: true,
+            state: {'switch_led': false, '1': false, 'battery_percentage': 80},
+            codeByDpId: {'1': 'switch_led'},
+            dpIdByCode: {'switch_led': '1'}
+        });
+        withBackends(dev, {lan, cloud});
+
+        lan.emit('change');
+        expect(dev.state['1']).toBe(true);                 // LAN value wins
+        expect(dev.state['switch_led']).toBe(true);        // …mirrored to its code
+        expect(dev.state['battery_percentage']).toBe(80);  // cloud-only DP retained
+    });
+
+    test('when the LAN drops, the cloud takes over and the change is emitted', () => {
+        const dev = makeDevice();
+        const lan = fakeBackend({connected: true, state: {'1': true}});
+        const cloud = fakeBackend({connected: true, state: {'1': false}});
+        withBackends(dev, {lan, cloud});
+
+        lan.emit('change');
+        expect(dev.state['1']).toBe(true);
+
+        lan.connected = false; // LAN lost
+        const seen = [];
+        dev.on('change', changes => seen.push(changes));
+        cloud.emit('change');
+
+        expect(dev.state['1']).toBe(false);
+        expect(seen[0]).toEqual({'1': false});
+    });
+});
+
+describe('TuyaDevice — writes with fallback', () => {
+    test('LAN is used first when both backends are up', async () => {
+        const dev = makeDevice();
+        const lan = fakeBackend({connected: true});
+        const cloud = fakeBackend({connected: true, update: jest.fn().mockResolvedValue(true)});
+        withBackends(dev, {lan, cloud});
+
+        await expect(dev.update({'1': true})).resolves.toBe(true);
+        expect(lan.update).toHaveBeenCalledWith({'1': true});
+        expect(cloud.update).not.toHaveBeenCalled();
+    });
+
+    test('a failed LAN write falls back to the cloud', async () => {
+        const dev = makeDevice();
+        const lan = fakeBackend({connected: true, update: jest.fn().mockReturnValue(false)});
+        const cloud = fakeBackend({connected: true, update: jest.fn().mockResolvedValue(true)});
+        withBackends(dev, {lan, cloud});
+
+        await expect(dev.update({'1': true})).resolves.toBe(true);
+        expect(cloud.update).toHaveBeenCalledWith({'1': true});
+    });
+
+    test('with the LAN down, writes go straight to the cloud (raw keys; the cloud translates)', async () => {
+        const dev = makeDevice();
+        const cloud = fakeBackend({connected: true, update: jest.fn().mockResolvedValue(true)});
+        withBackends(dev, {cloud});
+
+        await expect(dev.update({'switch_led': true})).resolves.toBe(true);
+        expect(cloud.update).toHaveBeenCalledWith({'switch_led': true});
+    });
+
+    test('a code-style write is translated to numeric ids for the LAN', async () => {
+        const dev = makeDevice();
+        const lan = fakeBackend({connected: true, update: jest.fn().mockReturnValue(true)});
+        const cloud = fakeBackend({connected: true, dpIdByCode: {'switch_led': '1'}, codeByDpId: {'1': 'switch_led'}});
+        withBackends(dev, {lan, cloud});
+
+        await dev.update({'switch_led': true});
+        expect(lan.update).toHaveBeenCalledWith({'1': true});
+    });
+
+    test('update resolves false when nothing is reachable', async () => {
+        const dev = makeDevice();
+        const cloud = fakeBackend({connected: false, update: jest.fn()});
+        withBackends(dev, {cloud});
+        await expect(dev.update({'1': true})).resolves.toBe(false);
+    });
+});
+
+describe('TuyaDevice — registration source guard', () => {
+    test('a LAN-primary device defers cloud-driven registration until it has the map or the LAN grace elapses', () => {
+        const dev = makeDevice();                  // has a key → LAN-primary
+        dev.cloud = fakeBackend({codeByDpId: {}});  // cloud, but no numeric map yet
+
+        expect(dev._mayRegisterFrom('lan')).toBe(true);
+        expect(dev._mayRegisterFrom('cloud')).toBe(false);
+
+        dev.cloud.codeByDpId = {'1': 'switch_led'}; // map learned → safe
+        expect(dev._mayRegisterFrom('cloud')).toBe(true);
+
+        dev.cloud.codeByDpId = {};
+        dev._lanGraceElapsed = true;                // …or the LAN had its head start
+        expect(dev._mayRegisterFrom('cloud')).toBe(true);
+    });
+
+    test('a keyless (cloud-only) device registers off the cloud immediately', () => {
+        const keyless = makeDevice({key: undefined});
+        keyless.cloud = fakeBackend({codeByDpId: {}});
+        expect(keyless._mayRegisterFrom('cloud')).toBe(true);
+    });
+});
+
+describe('TuyaDevice — composition', () => {
+    test('a cloud backend is built when a shared cloud session is supplied', () => {
+        const api = {
+            isConfigured: () => true,
+            getStatus: jest.fn().mockResolvedValue([]),
+            getDeviceInfo: jest.fn().mockResolvedValue({online: true}),
+            sendCommands: jest.fn()
+        };
+        const dev = makeDevice({cloudApi: api});
+        expect(dev.cloud).toBeInstanceOf(TuyaCloudDevice);
+        expect(dev.lan).toBeNull();
+    });
+
+    test('no cloud backend without a shared session', () => {
+        const dev = makeDevice();
+        expect(dev.cloud).toBeNull();
+    });
+
+    test('attachLan builds the LAN backend with the discovered version (forceVersion still wins)', () => {
+        const dev = makeDevice({ip: '10.0.0.5'});
+        dev.attachLan({ip: '10.0.0.9', version: '3.3'});
+        expect(dev.lan).not.toBeNull();
+        expect(dev.lan.context.ip).toBe('10.0.0.9');
+        expect(dev.lan.context.version).toBe('3.3');
+
+        const forced = makeDevice({forceVersion: '3.5'});
+        forced.attachLan({ip: '10.0.0.9', version: '3.3'});
+        expect(forced.lan.context.version).toBe('3.5');
+    });
+
+    test('attachLan is a no-op without a local key (cloud-only device)', () => {
+        const dev = makeDevice({key: undefined});
+        dev.attachLan({ip: '10.0.0.9'});
+        expect(dev.lan).toBeNull();
+    });
+});