homebridge-tuya-plus 3.14.0-dev.3 → 3.14.0-dev.30

package/test/TuyaCloudDevice.test.js

@@ -0,0 +1,304 @@
+'use strict';
+
+const EventEmitter = require('events');
+const TuyaCloudDevice = require('../lib/TuyaCloudDevice');
+
+const log = {info: () => {}, warn: () => {}, error: () => {}, debug: () => {}};
+
+function makeApi(status = [{code: 'switch_1', value: false}, {code: 'battery_percentage', value: 99}]) {
+    return {
+        isConfigured: () => true,
+        getStatus: jest.fn().mockResolvedValue(status),
+        getDeviceInfo: jest.fn().mockResolvedValue({online: true}),
+        sendCommands: jest.fn().mockResolvedValue(true)
+    };
+}
+
+function makeDevice(api, messaging = null, extra = {}) {
+    return new TuyaCloudDevice({
+        cloudApi: api, messaging, log,
+        id: 'dev1', name: 'Sprinklers', type: 'irrigationsystem', cloud: true,
+        connect: false, ...extra
+    });
+}
+
+describe('TuyaCloudDevice', () => {
+    test('connect reads status and emits connect then change (state keyed by code)', async () => {
+        const api = makeApi();
+        const dev = makeDevice(api);
+
+        const events = [];
+        dev.on('connect', () => events.push('connect'));
+        dev.on('change', (changes, state) => events.push({changes, state}));
+
+        await dev._connect();
+
+        expect(dev.connected).toBe(true);
+        expect(dev.state).toEqual({switch_1: false, battery_percentage: 99});
+        expect(events[0]).toBe('connect');
+        expect(events[1].state).toEqual({switch_1: false, battery_percentage: 99});
+        expect(api.getStatus).toHaveBeenCalledWith('dev1');
+    });
+
+    test('update sends code/value commands and does NOT mutate local state', async () => {
+        const api = makeApi();
+        const dev = makeDevice(api);
+        await dev._connect();
+
+        const before = {...dev.state};
+        dev.update({switch_1: true});
+
+        expect(api.sendCommands).toHaveBeenCalledWith('dev1', [{code: 'switch_1', value: true}]);
+        expect(dev.state).toEqual(before); // optimism lives in the accessory, not here
+    });
+
+    test('update is a no-op (no throw) before connect', () => {
+        const api = makeApi();
+        const dev = makeDevice(api);
+        expect(dev.connected).toBe(false);
+        expect(dev.update({switch_1: true})).toBe(false);
+        expect(api.sendCommands).not.toHaveBeenCalled();
+    });
+
+    test('update resolves to the cloud command result so failures are awaitable', async () => {
+        const api = makeApi();
+        const dev = makeDevice(api);
+        await dev._connect();
+
+        api.sendCommands.mockResolvedValueOnce(true);
+        await expect(dev.update({switch_1: true})).resolves.toBe(true);
+
+        api.sendCommands.mockResolvedValueOnce(false);
+        await expect(dev.update({switch_1: true})).resolves.toBe(false);
+    });
+
+    test('update resolves to false (never rejects) when the cloud request throws', async () => {
+        const api = makeApi();
+        const dev = makeDevice(api);
+        await dev._connect();
+
+        api.sendCommands.mockRejectedValueOnce(new Error('network down'));
+        await expect(dev.update({switch_1: true})).resolves.toBe(false);
+    });
+
+    test('applyStatus emits only the changed data-points', async () => {
+        const api = makeApi();
+        const dev = makeDevice(api);
+        await dev._connect();
+
+        const changes = [];
+        dev.on('change', c => changes.push(c));
+
+        dev._applyStatus([{code: 'switch_1', value: true}, {code: 'battery_percentage', value: 99}]);
+        expect(changes).toHaveLength(1);
+        expect(changes[0]).toEqual({switch_1: true}); // battery unchanged → not emitted
+        expect(dev.state.switch_1).toBe(true);
+
+        changes.length = 0;
+        dev._applyStatus([{code: 'switch_1', value: true}]); // nothing changed
+        expect(changes).toHaveLength(0);
+    });
+
+    test('connect reflects the device online status (offline → not connected)', async () => {
+        const api = makeApi();
+        api.getDeviceInfo.mockResolvedValue({online: false});
+        const dev = makeDevice(api);
+        await dev._connect();
+        expect(api.getDeviceInfo).toHaveBeenCalledWith('dev1');
+        expect(dev.connected).toBe(false);
+    });
+
+    test('online lookup failure → assume reachable (never block control)', async () => {
+        const api = makeApi();
+        api.getDeviceInfo.mockRejectedValue(new Error('no device-management permission'));
+        const dev = makeDevice(api);
+        await dev._connect();
+        expect(dev.connected).toBe(true);
+    });
+
+    test('a state refresh re-checks online and flips connected', async () => {
+        const api = makeApi();
+        const dev = makeDevice(api);
+        await dev._connect();
+        expect(dev.connected).toBe(true);
+
+        api.getDeviceInfo.mockResolvedValue({online: false});
+        await dev._refreshState();
+        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(), {
+            connected: false,
+            subscribeDevice: jest.fn()
+        });
+        const dev = makeDevice(api, messaging);
+        await dev._connect();
+
+        expect(messaging.subscribeDevice).toHaveBeenCalledWith('dev1', expect.any(Function));
+
+        // A realtime message routed back to the device updates its state.
+        const handler = messaging.subscribeDevice.mock.calls[0][1];
+        const changes = [];
+        dev.on('change', c => changes.push(c));
+        handler([{code: 'switch_2', value: true}]);
+        expect(dev.state.switch_2).toBe(true);
+        expect(changes[0]).toEqual({switch_2: true});
+
+        // On 'online' the device re-reads the full state (catch-up).
+        api.getStatus.mockClear();
+        messaging.emit('online');
+        await new Promise(r => setImmediate(r));
+        expect(api.getStatus).toHaveBeenCalledWith('dev1');
+    });
+
+    describe('connect-failure handling (no log spam)', () => {
+        afterEach(() => jest.restoreAllMocks());
+
+        test('a repeated failure is surfaced once, suppressed after, and backs off', () => {
+            jest.useFakeTimers();
+            try {
+                const dev = makeDevice(makeApi(), null, {key: 'abc'}); // LAN-capable → fallback
+                const warn = jest.spyOn(log, 'warn');
+                const debug = jest.spyOn(log, 'debug');
+                const err = new Error('GET /v1.0/devices/dev1/status failed: permission deny (code 1106)');
+
+                dev._onConnectFailure(err);
+                expect(warn).toHaveBeenCalledTimes(1);
+                expect(warn.mock.calls[0][0]).toContain('permission deny (code 1106)');
+                expect(dev._retryDelay).toBe(30000);
+
+                dev._onConnectFailure(err); // identical → not surfaced again, just debug + backoff
+                expect(warn).toHaveBeenCalledTimes(1);
+                expect(debug).toHaveBeenCalledWith(expect.stringContaining('still failing'));
+                expect(dev._retryDelay).toBe(60000);
+
+                dev._onConnectFailure(err);
+                expect(dev._retryDelay).toBe(120000);
+            } finally {
+                jest.useRealTimers();
+            }
+        });
+
+        test('a cloud-only device (no key) surfaces the failure at error level', () => {
+            jest.useFakeTimers();
+            try {
+                const dev = makeDevice(makeApi()); // no key → cloud is the only path
+                const error = jest.spyOn(log, 'error');
+                const warn = jest.spyOn(log, 'warn');
+
+                dev._onConnectFailure(new Error('permission deny (code 1106)'));
+                expect(warn).not.toHaveBeenCalled();
+                expect(error).toHaveBeenCalledTimes(1);
+                expect(error.mock.calls[0][0]).toContain('cloud-only');
+            } finally {
+                jest.useRealTimers();
+            }
+        });
+
+        test('a different error message is surfaced again, not suppressed', () => {
+            jest.useFakeTimers();
+            try {
+                const dev = makeDevice(makeApi(), null, {key: 'abc'});
+                const warn = jest.spyOn(log, 'warn');
+
+                dev._onConnectFailure(new Error('permission deny (code 1106)'));
+                dev._onConnectFailure(new Error('request timed out'));
+                expect(warn).toHaveBeenCalledTimes(2);
+            } finally {
+                jest.useRealTimers();
+            }
+        });
+
+        test('backoff is capped at 30 minutes', () => {
+            jest.useFakeTimers();
+            try {
+                const dev = makeDevice(makeApi(), null, {key: 'abc'});
+                jest.spyOn(log, 'warn');
+                jest.spyOn(log, 'debug');
+                const err = new Error('permission deny (code 1106)');
+
+                for (let i = 0; i < 20; i++) dev._onConnectFailure(err);
+                expect(dev._retryDelay).toBe(1800000);
+            } finally {
+                jest.useRealTimers();
+            }
+        });
+
+        test('reconnecting after a failure logs recovery once and resets backoff', async () => {
+            const dev = makeDevice(makeApi(), null, {key: 'abc'});
+            dev._lastConnectError = 'permission deny (code 1106)';
+            dev._retryDelay = 240000;
+            const info = jest.spyOn(log, 'info');
+
+            await dev._connect(); // mocked api resolves → success path runs
+
+            expect(dev._lastConnectError).toBeNull();
+            expect(dev._retryDelay).toBe(0);
+            expect(info).toHaveBeenCalledWith(expect.stringContaining('connection restored'));
+        });
+
+        test('a stopped device does not schedule another retry', () => {
+            jest.useFakeTimers();
+            try {
+                const dev = makeDevice(makeApi(), null, {key: 'abc'});
+                jest.spyOn(log, 'warn');
+                dev.stop();
+                dev._onConnectFailure(new Error('permission deny (code 1106)'));
+                expect(dev._retryTimer).toBeNull();
+            } finally {
+                jest.useRealTimers();
+            }
+        });
+    });
+});

package/test/TuyaCloudMessaging.test.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const crypto = require('crypto');
+const TuyaCloudMessaging = require('../lib/TuyaCloudMessaging');
+
+const log = {info: () => {}, warn: () => {}, error: () => {}, debug: () => {}};
+
+// Encrypt exactly like Tuya's msg_encrypted_version 2.0 (AES-128-GCM):
+//   [ivLen(4 BE)][iv][ciphertext][tag(16)], key = password[8,24), AAD = 6-byte BE t.
+function encryptGCM(plaintext, password, t) {
+    const key = Buffer.from(('' + password).substring(8, 24), 'utf8');
+    const iv = crypto.randomBytes(12);
+    const c = crypto.createCipheriv('aes-128-gcm', key, iv);
+    const aad = Buffer.allocUnsafe(6); aad.writeUIntBE(Number(t), 0, 6); c.setAAD(aad);
+    const enc = Buffer.concat([c.update(Buffer.from(plaintext, 'utf8')), c.final()]);
+    const tag = c.getAuthTag();
+    const ivLen = Buffer.allocUnsafe(4); ivLen.writeUIntBE(iv.length, 0, 4);
+    return Buffer.concat([ivLen, iv, enc, tag]).toString('base64');
+}
+
+// AES-128-ECB / PKCS7 (msg_encrypted_version 1.0).
+function encryptECB(plaintext, password) {
+    const key = Buffer.from(('' + password).substring(8, 24), 'utf8');
+    const c = crypto.createCipheriv('aes-128-ecb', key, null);
+    return Buffer.concat([c.update(Buffer.from(plaintext, 'utf8')), c.final()]).toString('base64');
+}
+
+// A messaging instance that won't try to open a real connection.
+function makeIdle(password = 'abcdefgh0123456789WXYZ!!') {
+    const mq = new TuyaCloudMessaging({api: {}, log});
+    mq._started = true; // prevent start()
+    mq.config = {password};
+    return mq;
+}
+
+function envelope(payloadObj, password, {protocol = 4, t = Date.now(), mode = 'gcm'} = {}) {
+    const data = mode === 'ecb'
+        ? encryptECB(JSON.stringify(payloadObj), password)
+        : encryptGCM(JSON.stringify(payloadObj), password, t);
+    return Buffer.from(JSON.stringify({protocol, data, t}));
+}
+
+describe('TuyaCloudMessaging — decryption + dispatch', () => {
+    test('decrypts a GCM status frame and delivers it to the subscribed device', () => {
+        const mq = makeIdle();
+        const received = [];
+        mq.subscribeDevice('DEV1', status => received.push(status));
+
+        const t = Date.now();
+        mq._onMessage('topic', envelope(
+            {devId: 'DEV1', status: [{code: 'switch_1', value: true, t}, {code: 'battery_percentage', value: 80, t}]},
+            mq.config.password, {t}
+        ));
+
+        expect(received).toHaveLength(1);
+        expect(received[0]).toEqual([{code: 'switch_1', value: true, t}, {code: 'battery_percentage', value: 80, t}]);
+    });
+
+    test('decrypts a GCM frame even when the auth tag does not verify (Tuya quirk)', () => {
+        // Real Tuya status frames carry a GCM tag that does NOT verify against
+        // the documented AAD. We must decrypt with update() only (no final(),
+        // no tag check) or every realtime update is silently dropped — which is
+        // exactly what stopped external changes from reaching HomeKit. Simulate
+        // it by clobbering the trailing 16-byte tag: the plaintext must still
+        // come through.
+        const mq = makeIdle();
+        const received = [];
+        mq.subscribeDevice('DEV1', status => received.push(status));
+
+        const t = Date.now();
+        const raw = Buffer.from(
+            encryptGCM(JSON.stringify({devId: 'DEV1', status: [{code: 'switch_1', value: true}]}), mq.config.password, t),
+            'base64'
+        );
+        crypto.randomBytes(16).copy(raw, raw.length - 16); // corrupt the auth tag
+
+        mq._onMessage('topic', Buffer.from(JSON.stringify({protocol: 4, data: raw.toString('base64'), t})));
+
+        expect(received).toHaveLength(1);
+        expect(received[0]).toEqual([{code: 'switch_1', value: true}]);
+    });
+
+    test('decrypts a legacy ECB (v1.0) frame too', () => {
+        const mq = makeIdle();
+        const received = [];
+        mq.subscribeDevice('DEV1', status => received.push(status));
+        mq._onMessage('topic', envelope({devId: 'DEV1', status: [{code: 'switch_2', value: true}]}, mq.config.password, {mode: 'ecb'}));
+        expect(received[0]).toEqual([{code: 'switch_2', value: true}]);
+    });
+
+    test('ignores messages for devices we did not subscribe', () => {
+        const mq = makeIdle();
+        const received = [];
+        mq.subscribeDevice('DEV1', status => received.push(status));
+        mq._onMessage('topic', envelope({devId: 'OTHER', status: [{code: 'switch_1', value: true}]}, mq.config.password, {}));
+        expect(received).toHaveLength(0);
+    });
+
+    test('a frame that cannot be decrypted is dropped without throwing', () => {
+        const mq = makeIdle();
+        const received = [];
+        mq.subscribeDevice('DEV1', status => received.push(status));
+        // Encrypted with the wrong password → auth/decrypt fails.
+        expect(() => mq._onMessage('topic', envelope({devId: 'DEV1', status: [{code: 'x', value: 1}]}, 'ZZZZZZZZwrongkeywrongkey', {}))).not.toThrow();
+        expect(received).toHaveLength(0);
+    });
+
+    test('malformed JSON envelope is ignored', () => {
+        const mq = makeIdle();
+        mq.subscribeDevice('DEV1', () => { throw new Error('should not be called'); });
+        expect(() => mq._onMessage('topic', Buffer.from('not json'))).not.toThrow();
+    });
+});

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();
+    });
+});

package/test/getCategory.test.js

@@ -23,6 +23,7 @@ const CLASS_DEF = {
     garagedoor: require('../lib/GarageDoorAccessory'),
     simplegaragedoor: require('../lib/SimpleGarageDoorAccessory'),
     simpledimmer: require('../lib/SimpleDimmerAccessory'),
+    wleddimmer: require('../lib/WledDimmerAccessory'),
     simpledimmer2: require('../lib/SimpleDimmer2Accessory'),
     simpleblinds: require('../lib/SimpleBlindsAccessory'),
     simpleheater: require('../lib/SimpleHeaterAccessory'),