@bobfrankston/lxlan 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm install:*)",
+      "Bash(tsc:*)",
+      "Bash(git init:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(gh repo create:*)",
+      "Bash(npm publish:*)"
+    ]
+  }
+}

package/client.d.ts

@@ -0,0 +1,65 @@
+import { EventEmitter } from 'node:events';
+import { UdpRetryOptions } from '@bobfrankston/lxudp';
+import { LxDevice } from './device.js';
+/**
+ * Options for LxClient constructor
+ */
+export interface LxClientOptions {
+    /** UDP port to bind (default 56700) */
+    port?: number;
+    /** Broadcast addresses for discovery (auto-detected from network interfaces if not specified) */
+    broadcastAddresses?: string[];
+    /** Auto-discovery interval in ms (0 = manual only, default 0) */
+    discoveryInterval?: number;
+}
+/**
+ * LIFX LAN client for device discovery and control.
+ *
+ * Events:
+ * - `device` (device: LxDevice) - new device discovered
+ * - `message` (device: LxDevice, msg: LxMessage) - any message received
+ * - `state` (device: LxDevice) - light state updated
+ * - `power` (device: LxDevice) - power state updated
+ * - `label` (device: LxDevice) - label updated
+ * - `group` (device: LxDevice) - group info updated
+ * - `location` (device: LxDevice) - location info updated
+ * - `version` (device: LxDevice) - version info received
+ * - `error` (err: Error) - transport or protocol error
+ */
+export declare class LxClient extends EventEmitter {
+    private socket;
+    private port;
+    private broadcastAddresses;
+    private discoveryTimer;
+    /** Cached devices by MAC address (lowercase) */
+    devices: Map<string, LxDevice>;
+    constructor(options?: LxClientOptions);
+    /** Start listening */
+    start(): Promise<void>;
+    /** Stop and cleanup */
+    stop(): void;
+    /** Set retry options at runtime */
+    setRetryOptions(options: UdpRetryOptions): void;
+    /** Get current retry options */
+    getRetryOptions(): Required<UdpRetryOptions>;
+    /** Broadcast discovery to all interfaces */
+    discover(): void;
+    /**
+     * Get device by MAC address
+     * @param mac - MAC address (case-insensitive, with or without colons)
+     * @returns LxDevice or undefined if not found
+     */
+    getDevice(mac: string): LxDevice;
+    /**
+     * Add device manually (bypassing discovery).
+     * Use when you know the device IP from external source.
+     * @param mac - MAC address
+     * @param ip - IP address
+     * @param port - UDP port (default 56700)
+     * @returns LxDevice instance (new or existing)
+     */
+    addDevice(mac: string, ip: string, port?: number): LxDevice;
+    /** Handle incoming message */
+    private handleMessage;
+}
+//# sourceMappingURL=client.d.ts.map

package/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAa,eAAe,EAAyB,MAAM,qBAAqB,CAAC;AACxF,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvC;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,iEAAiE;IACjE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,QAAS,SAAQ,YAAY;IACtC,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,kBAAkB,CAAW;IACrC,OAAO,CAAC,cAAc,CAAiB;IAEvC,gDAAgD;IAChD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAa;gBAE/B,OAAO,GAAE,eAAoB;IAuBzC,sBAAsB;IAChB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,uBAAuB;IACvB,IAAI,IAAI,IAAI;IAKZ,mCAAmC;IACnC,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAI/C,gCAAgC;IAChC,eAAe,IAAI,QAAQ,CAAC,eAAe,CAAC;IAI5C,4CAA4C;IAC5C,QAAQ,IAAI,IAAI;IAWhB;;;;OAIG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ;IAIhC;;;;;;;OAOG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,GAAE,MAAkB,GAAG,QAAQ;IAiBtE,8BAA8B;IAC9B,OAAO,CAAC,aAAa;CAgFxB"}

package/client.js

@@ -0,0 +1,176 @@
+import { EventEmitter } from 'node:events';
+import { hsbk16ToHsbk } from '@bobfrankston/colorlib';
+import { UdpSocket, getBroadcastAddresses } from '@bobfrankston/lxudp';
+import { LxDevice } from './device.js';
+import { MessageType, LIFX_PORT } from './types.js';
+import { encodeMessage, decodeMessage, decodeState, decodeStatePower, decodeStateLabel, decodeStateVersion, decodeStateGroup, decodeStateService } from './protocol.js';
+/**
+ * LIFX LAN client for device discovery and control.
+ *
+ * Events:
+ * - `device` (device: LxDevice) - new device discovered
+ * - `message` (device: LxDevice, msg: LxMessage) - any message received
+ * - `state` (device: LxDevice) - light state updated
+ * - `power` (device: LxDevice) - power state updated
+ * - `label` (device: LxDevice) - label updated
+ * - `group` (device: LxDevice) - group info updated
+ * - `location` (device: LxDevice) - location info updated
+ * - `version` (device: LxDevice) - version info received
+ * - `error` (err: Error) - transport or protocol error
+ */
+export class LxClient extends EventEmitter {
+    socket;
+    port;
+    broadcastAddresses;
+    discoveryTimer;
+    /** Cached devices by MAC address (lowercase) */
+    devices = new Map();
+    constructor(options = {}) {
+        super();
+        this.port = options.port ?? LIFX_PORT;
+        this.broadcastAddresses = options.broadcastAddresses ?? getBroadcastAddresses();
+        this.socket = new UdpSocket({
+            port: this.port,
+            reuseAddr: true
+        });
+        this.socket.on('message', (data, rinfo) => {
+            this.handleMessage(data, rinfo.address, rinfo.port);
+        });
+        this.socket.on('error', (err) => {
+            this.emit('error', err);
+        });
+        if (options.discoveryInterval && options.discoveryInterval > 0) {
+            this.discoveryTimer = setInterval(() => this.discover(), options.discoveryInterval);
+        }
+    }
+    /** Start listening */
+    async start() {
+        await this.socket.bind();
+    }
+    /** Stop and cleanup */
+    stop() {
+        if (this.discoveryTimer)
+            clearInterval(this.discoveryTimer);
+        this.socket.close();
+    }
+    /** Set retry options at runtime */
+    setRetryOptions(options) {
+        this.socket.setRetryOptions(options);
+    }
+    /** Get current retry options */
+    getRetryOptions() {
+        return this.socket.getRetryOptions();
+    }
+    /** Broadcast discovery to all interfaces */
+    discover() {
+        const msg = encodeMessage({
+            type: MessageType.GetService,
+            tagged: true
+        });
+        for (const addr of this.broadcastAddresses) {
+            this.socket.send(addr, this.port, msg);
+        }
+    }
+    /**
+     * Get device by MAC address
+     * @param mac - MAC address (case-insensitive, with or without colons)
+     * @returns LxDevice or undefined if not found
+     */
+    getDevice(mac) {
+        return this.devices.get(mac.toLowerCase());
+    }
+    /**
+     * Add device manually (bypassing discovery).
+     * Use when you know the device IP from external source.
+     * @param mac - MAC address
+     * @param ip - IP address
+     * @param port - UDP port (default 56700)
+     * @returns LxDevice instance (new or existing)
+     */
+    addDevice(mac, ip, port = LIFX_PORT) {
+        const normalizedMac = mac.toLowerCase();
+        let device = this.devices.get(normalizedMac);
+        if (!device) {
+            device = new LxDevice(normalizedMac, ip, this.socket);
+            device.port = port;
+            this.devices.set(normalizedMac, device);
+            this.emit('device', device);
+        }
+        else {
+            device.ip = ip;
+            device.port = port;
+        }
+        return device;
+    }
+    /** Handle incoming message */
+    handleMessage(data, fromIp, fromPort) {
+        let msg;
+        try {
+            msg = decodeMessage(data);
+        }
+        catch (e) {
+            this.emit('error', new Error(`Decode error: ${e.message}`));
+            return;
+        }
+        const mac = msg.target;
+        if (mac === '00:00:00:00:00:00')
+            return; /** broadcast response without target */
+        let device = this.devices.get(mac);
+        const isNew = !device;
+        if (!device) {
+            device = new LxDevice(mac, fromIp, this.socket);
+            device.port = fromPort;
+            this.devices.set(mac, device);
+        }
+        device.ip = fromIp;
+        device.port = fromPort;
+        device.markSeen();
+        if (isNew) {
+            this.emit('device', device);
+        }
+        this.emit('message', device, msg);
+        switch (msg.type) {
+            case MessageType.StateService: {
+                const info = decodeStateService(msg.payload);
+                device.port = info.port;
+                break;
+            }
+            case MessageType.State: {
+                const state = decodeState(msg.payload);
+                device.color = hsbk16ToHsbk(state.hsbk);
+                device.power = state.power > 0;
+                device.label = state.label;
+                this.emit('state', device);
+                break;
+            }
+            case MessageType.StatePower: {
+                device.power = decodeStatePower(msg.payload);
+                this.emit('power', device);
+                break;
+            }
+            case MessageType.StateLabel: {
+                device.label = decodeStateLabel(msg.payload);
+                this.emit('label', device);
+                break;
+            }
+            case MessageType.StateVersion: {
+                const ver = decodeStateVersion(msg.payload);
+                device.vendor = ver.vendor;
+                device.product = ver.product;
+                this.emit('version', device);
+                break;
+            }
+            case MessageType.StateGroup: {
+                device.group = decodeStateGroup(msg.payload);
+                this.emit('group', device);
+                break;
+            }
+            case MessageType.StateLocation: {
+                device.location = decodeStateGroup(msg.payload);
+                this.emit('location', device);
+                break;
+            }
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["client.ts"],"names":[],"mappings":"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"}

package/client.ts

@@ -0,0 +1,214 @@
+import { EventEmitter } from 'node:events';
+import { hsbk16ToHsbk } from '@bobfrankston/colorlib';
+import { UdpSocket, UdpRetryOptions, getBroadcastAddresses } from '@bobfrankston/lxudp';
+import { LxDevice } from './device.js';
+import { LxMessage, MessageType, LIFX_PORT } from './types.js';
+import { encodeMessage, decodeMessage, decodeState, decodeStatePower, decodeStateLabel, decodeStateVersion, decodeStateGroup, decodeStateService } from './protocol.js';
+
+/**
+ * Options for LxClient constructor
+ */
+export interface LxClientOptions {
+    /** UDP port to bind (default 56700) */
+    port?: number;
+    /** Broadcast addresses for discovery (auto-detected from network interfaces if not specified) */
+    broadcastAddresses?: string[];
+    /** Auto-discovery interval in ms (0 = manual only, default 0) */
+    discoveryInterval?: number;
+}
+
+/**
+ * LIFX LAN client for device discovery and control.
+ *
+ * Events:
+ * - `device` (device: LxDevice) - new device discovered
+ * - `message` (device: LxDevice, msg: LxMessage) - any message received
+ * - `state` (device: LxDevice) - light state updated
+ * - `power` (device: LxDevice) - power state updated
+ * - `label` (device: LxDevice) - label updated
+ * - `group` (device: LxDevice) - group info updated
+ * - `location` (device: LxDevice) - location info updated
+ * - `version` (device: LxDevice) - version info received
+ * - `error` (err: Error) - transport or protocol error
+ */
+export class LxClient extends EventEmitter {
+    private socket: UdpSocket;
+    private port: number;
+    private broadcastAddresses: string[];
+    private discoveryTimer: NodeJS.Timeout;
+
+    /** Cached devices by MAC address (lowercase) */
+    devices: Map<string, LxDevice> = new Map();
+
+    constructor(options: LxClientOptions = {}) {
+        super();
+        this.port = options.port ?? LIFX_PORT;
+        this.broadcastAddresses = options.broadcastAddresses ?? getBroadcastAddresses();
+
+        this.socket = new UdpSocket({
+            port: this.port,
+            reuseAddr: true
+        });
+
+        this.socket.on('message', (data, rinfo) => {
+            this.handleMessage(data, rinfo.address, rinfo.port);
+        });
+
+        this.socket.on('error', (err) => {
+            this.emit('error', err);
+        });
+
+        if (options.discoveryInterval && options.discoveryInterval > 0) {
+            this.discoveryTimer = setInterval(() => this.discover(), options.discoveryInterval);
+        }
+    }
+
+    /** Start listening */
+    async start(): Promise<void> {
+        await this.socket.bind();
+    }
+
+    /** Stop and cleanup */
+    stop(): void {
+        if (this.discoveryTimer) clearInterval(this.discoveryTimer);
+        this.socket.close();
+    }
+
+    /** Set retry options at runtime */
+    setRetryOptions(options: UdpRetryOptions): void {
+        this.socket.setRetryOptions(options);
+    }
+
+    /** Get current retry options */
+    getRetryOptions(): Required<UdpRetryOptions> {
+        return this.socket.getRetryOptions();
+    }
+
+    /** Broadcast discovery to all interfaces */
+    discover(): void {
+        const msg = encodeMessage({
+            type: MessageType.GetService,
+            tagged: true
+        });
+
+        for (const addr of this.broadcastAddresses) {
+            this.socket.send(addr, this.port, msg);
+        }
+    }
+
+    /**
+     * Get device by MAC address
+     * @param mac - MAC address (case-insensitive, with or without colons)
+     * @returns LxDevice or undefined if not found
+     */
+    getDevice(mac: string): LxDevice {
+        return this.devices.get(mac.toLowerCase());
+    }
+
+    /**
+     * Add device manually (bypassing discovery).
+     * Use when you know the device IP from external source.
+     * @param mac - MAC address
+     * @param ip - IP address
+     * @param port - UDP port (default 56700)
+     * @returns LxDevice instance (new or existing)
+     */
+    addDevice(mac: string, ip: string, port: number = LIFX_PORT): LxDevice {
+        const normalizedMac = mac.toLowerCase();
+        let device = this.devices.get(normalizedMac);
+
+        if (!device) {
+            device = new LxDevice(normalizedMac, ip, this.socket);
+            device.port = port;
+            this.devices.set(normalizedMac, device);
+            this.emit('device', device);
+        } else {
+            device.ip = ip;
+            device.port = port;
+        }
+
+        return device;
+    }
+
+    /** Handle incoming message */
+    private handleMessage(data: Buffer, fromIp: string, fromPort: number): void {
+        let msg: LxMessage;
+        try {
+            msg = decodeMessage(data);
+        } catch (e: any) {
+            this.emit('error', new Error(`Decode error: ${e.message}`));
+            return;
+        }
+
+        const mac = msg.target;
+        if (mac === '00:00:00:00:00:00') return;  /** broadcast response without target */
+
+        let device = this.devices.get(mac);
+        const isNew = !device;
+
+        if (!device) {
+            device = new LxDevice(mac, fromIp, this.socket);
+            device.port = fromPort;
+            this.devices.set(mac, device);
+        }
+
+        device.ip = fromIp;
+        device.port = fromPort;
+        device.markSeen();
+
+        if (isNew) {
+            this.emit('device', device);
+        }
+
+        this.emit('message', device, msg);
+
+        switch (msg.type) {
+            case MessageType.StateService: {
+                const info = decodeStateService(msg.payload);
+                device.port = info.port;
+                break;
+            }
+
+            case MessageType.State: {
+                const state = decodeState(msg.payload);
+                device.color = hsbk16ToHsbk(state.hsbk);
+                device.power = state.power > 0;
+                device.label = state.label;
+                this.emit('state', device);
+                break;
+            }
+
+            case MessageType.StatePower: {
+                device.power = decodeStatePower(msg.payload);
+                this.emit('power', device);
+                break;
+            }
+
+            case MessageType.StateLabel: {
+                device.label = decodeStateLabel(msg.payload);
+                this.emit('label', device);
+                break;
+            }
+
+            case MessageType.StateVersion: {
+                const ver = decodeStateVersion(msg.payload);
+                device.vendor = ver.vendor;
+                device.product = ver.product;
+                this.emit('version', device);
+                break;
+            }
+
+            case MessageType.StateGroup: {
+                device.group = decodeStateGroup(msg.payload);
+                this.emit('group', device);
+                break;
+            }
+
+            case MessageType.StateLocation: {
+                device.location = decodeStateGroup(msg.payload);
+                this.emit('location', device);
+                break;
+            }
+        }
+    }
+}

package/device.d.ts

@@ -0,0 +1,75 @@
+import { HSBK, ColorInput } from '@bobfrankston/colorlib';
+import { UdpSocket } from '@bobfrankston/lxudp';
+import { GroupInfo } from './types.js';
+/**
+ * Represents a LIFX device on the LAN.
+ * State is cached and updated via events from LxClient.
+ */
+export declare class LxDevice {
+    /** MAC address (lowercase, colon-separated) */
+    readonly mac: string;
+    /** Current IP address */
+    ip: string;
+    /** UDP port (default 56700) */
+    port: number;
+    /** Power state (true = on) */
+    power: boolean;
+    /** Current color in HSBK format */
+    color: HSBK;
+    /** Device label (user-assigned name) */
+    label: string;
+    /** Whether device is responding */
+    online: boolean;
+    /** Last message timestamp (Date.now()) */
+    lastSeen: number;
+    /** Vendor ID (1 = LIFX) */
+    vendor: number;
+    /** Product ID (see Products table) */
+    product: number;
+    /** Group membership */
+    group: GroupInfo;
+    /** Location membership */
+    location: GroupInfo;
+    private socket;
+    constructor(mac: string, ip: string, socket: UdpSocket);
+    /** Get product name from product ID */
+    get productName(): string;
+    /** Send raw message to device */
+    send(type: number, payload?: Buffer): void;
+    /** Set power on/off */
+    setPower(on: boolean): void;
+    /**
+     * Set color - accepts flexible input formats
+     * @param color - Color as hex "#ff0000", RGB {r,g,b}, HSL {h,s,l}, HSB {h,s,b}, HSBK {h,s,b,k}, or Kelvin number
+     * @param duration - Transition time in milliseconds (default 0)
+     */
+    setColor(color: ColorInput, duration?: number): void;
+    /**
+     * Set white color temperature
+     * @param kelvin - Color temperature (1500-9000, warm to cool)
+     * @param brightness - Brightness 0-100 (default 100)
+     * @param duration - Transition time in milliseconds (default 0)
+     */
+    setWhite(kelvin: number, brightness?: number, duration?: number): void;
+    /** Query full state */
+    getState(): void;
+    /** Query power state */
+    getPower(): void;
+    /** Set label */
+    setLabel(label: string): void;
+    /** Query label */
+    getLabel(): void;
+    /** Set group */
+    setGroup(id: string, label: string): void;
+    /** Query group */
+    getGroup(): void;
+    /** Set location */
+    setLocation(id: string, label: string): void;
+    /** Query location */
+    getLocation(): void;
+    /** Query version */
+    getVersion(): void;
+    /** Update last seen timestamp and online status */
+    markSeen(): void;
+}
+//# sourceMappingURL=device.d.ts.map

package/device.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.d.ts","sourceRoot":"","sources":["device.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAwB,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,SAAS,EAAoC,MAAM,YAAY,CAAC;AAGzE;;;GAGG;AACH,qBAAa,QAAQ;IACjB,+CAA+C;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yBAAyB;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAa;IAEzB,8BAA8B;IAC9B,KAAK,EAAE,OAAO,CAAS;IACvB,mCAAmC;IACnC,KAAK,EAAE,IAAI,CAAiC;IAC5C,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAM;IACnB,mCAAmC;IACnC,MAAM,EAAE,OAAO,CAAS;IACxB,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAK;IAErB,2BAA2B;IAC3B,MAAM,EAAE,MAAM,CAAK;IACnB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAK;IAEpB,uBAAuB;IACvB,KAAK,EAAE,SAAS,CAAuC;IACvD,0BAA0B;IAC1B,QAAQ,EAAE,SAAS,CAAuC;IAE1D,OAAO,CAAC,MAAM,CAAY;gBAEd,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS;IAMtD,uCAAuC;IACvC,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,iCAAiC;IACjC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAW1C,uBAAuB;IACvB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI;IAU3B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,GAAE,MAAU,GAAG,IAAI;IAYvD;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,GAAE,MAAY,EAAE,QAAQ,GAAE,MAAU,GAAG,IAAI;IAI9E,uBAAuB;IACvB,QAAQ,IAAI,IAAI;IAIhB,wBAAwB;IACxB,QAAQ,IAAI,IAAI;IAIhB,gBAAgB;IAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAU7B,kBAAkB;IAClB,QAAQ,IAAI,IAAI;IAIhB,gBAAgB;IAChB,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAUzC,kBAAkB;IAClB,QAAQ,IAAI,IAAI;IAIhB,mBAAmB;IACnB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAU5C,qBAAqB;IACrB,WAAW,IAAI,IAAI;IAInB,oBAAoB;IACpB,UAAU,IAAI,IAAI;IAIlB,mDAAmD;IACnD,QAAQ,IAAI,IAAI;CAInB"}