homebridge-cync-app 0.0.2

package/dist/platform.js

@@ -0,0 +1,143 @@
+import { PLATFORM_NAME } from './settings.js';
+import { CyncClient } from './cync/cync-client.js';
+import { ConfigClient } from './cync/config-client.js';
+import { TcpClient } from './cync/tcp-client.js';
+const toCyncLogger = (log) => ({
+    debug: log.debug.bind(log),
+    info: log.info.bind(log),
+    warn: log.warn.bind(log),
+    error: log.error.bind(log),
+});
+/**
+ * CyncAppPlatform
+ *
+ * Homebridge platform class responsible for:
+ * - Initializing the Cync client
+ * - Managing cached accessories
+ * - Kicking off device discovery from Cync cloud
+ */
+export class CyncAppPlatform {
+    accessories = [];
+    log;
+    api;
+    config;
+    client;
+    cloudConfig = null;
+    constructor(log, config, api) {
+        this.log = log;
+        this.config = config;
+        this.api = api;
+        // Extract login config from platform config
+        const cfg = this.config;
+        const username = (cfg.username ?? cfg.email);
+        const password = cfg.password;
+        const twoFactor = cfg.twoFactor;
+        // Initialize the Cync client with platform logger so all messages
+        // appear in the Homebridge log.
+        this.client = new CyncClient(new ConfigClient(toCyncLogger(this.log)), new TcpClient(toCyncLogger(this.log)), {
+            email: username ?? '',
+            password: password ?? '',
+            twoFactor,
+        }, this.api.user.storagePath(), toCyncLogger(this.log));
+        this.log.info(this.config.name ?? PLATFORM_NAME, 'initialized');
+        this.api.on('didFinishLaunching', () => {
+            this.log.info(PLATFORM_NAME, 'didFinishLaunching');
+            void this.loadCync();
+        });
+    }
+    /**
+     * Called when cached accessories are restored from disk.
+     */
+    configureAccessory(accessory) {
+        this.log.info('Restoring cached accessory', accessory.displayName);
+        this.accessories.push(accessory);
+    }
+    async loadCync() {
+        try {
+            const cfg = this.config;
+            const username = (cfg.username ?? cfg.email);
+            const password = cfg.password;
+            if (!username || !password) {
+                this.log.warn('Cync: credentials missing in config.json; skipping cloud login.');
+                return;
+            }
+            // Let CyncClient handle 2FA bootstrap + token persistence.
+            const loggedIn = await this.client.ensureLoggedIn();
+            if (!loggedIn) {
+                // We either just requested a 2FA code or hit a credential error.
+                // In the "code requested" case, the log already tells the user
+                // to add it to config and restart.
+                return;
+            }
+            const cloudConfig = await this.client.loadConfiguration();
+            this.cloudConfig = cloudConfig;
+            this.log.info('Cync: cloud configuration loaded; mesh count=%d', cloudConfig?.meshes?.length ?? 0);
+            this.discoverDevices(cloudConfig);
+        }
+        catch (err) {
+            this.log.error('Cync: cloud login failed: %s', err.message ?? String(err));
+        }
+    }
+    /**
+     * Discover devices from the Cync cloud config and register them as
+     * Homebridge accessories. For now, each device is exposed as a simple
+     * dummy Switch that logs state changes.
+     */
+    discoverDevices(cloudConfig) {
+        if (!cloudConfig.meshes?.length) {
+            this.log.warn('Cync: no meshes returned from cloud; nothing to discover.');
+            return;
+        }
+        for (const mesh of cloudConfig.meshes) {
+            const meshName = mesh.name || mesh.id;
+            this.log.info('Cync: processing mesh %s', meshName);
+            const devices = mesh.devices ?? [];
+            if (!devices.length) {
+                this.log.info('Cync: mesh %s has no devices.', meshName);
+                continue;
+            }
+            for (const device of devices) {
+                const deviceId = `${device.id ??
+                    device.device_id ??
+                    device.mac ??
+                    device.sn ??
+                    `${mesh.id}-${device.product_id ?? 'unknown'}`}`;
+                const preferredName = device.name ??
+                    device.displayName ??
+                    undefined;
+                const deviceName = preferredName || `Cync Device ${deviceId}`;
+                const uuidSeed = `cync-${mesh.id}-${deviceId}`;
+                const uuid = this.api.hap.uuid.generate(uuidSeed);
+                const existing = this.accessories.find(acc => acc.UUID === uuid);
+                if (existing) {
+                    this.log.info('Cync: using cached accessory for %s (%s)', deviceName, uuidSeed);
+                    continue;
+                }
+                this.log.info('Cync: registering new accessory for %s (%s)', deviceName, uuidSeed);
+                const accessory = new this.api.platformAccessory(deviceName, uuid);
+                // Simple Switch service for now
+                const service = accessory.getService(this.api.hap.Service.Switch) ||
+                    accessory.addService(this.api.hap.Service.Switch, deviceName);
+                service
+                    .getCharacteristic(this.api.hap.Characteristic.On)
+                    .onGet(() => {
+                    this.log.info('Cync: On.get -> false for %s', deviceName);
+                    return false;
+                })
+                    .onSet((value) => {
+                    this.log.info('Cync: On.set -> %s for %s', String(value), deviceName);
+                });
+                // Context for later TCP control
+                const ctx = accessory.context;
+                ctx.cync = {
+                    meshId: mesh.id,
+                    deviceId,
+                    productId: device.product_id,
+                };
+                this.api.registerPlatformAccessories('homebridge-cync-app', 'CyncAppPlatform', [accessory]);
+                this.accessories.push(accessory);
+            }
+        }
+    }
+}
+//# sourceMappingURL=platform.js.map

package/dist/platform.js.map

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

package/dist/platformAccessory.d.ts

@@ -0,0 +1,13 @@
+import type { PlatformAccessory } from 'homebridge';
+import type { CyncAppPlatform } from './platform.js';
+/**
+ * CyncAccessory
+ *
+ * Placeholder accessory class for future Cync devices.
+ * Currently unused; exists only to provide a typed scaffold.
+ */
+export declare class CyncAccessory {
+    private readonly platform;
+    private readonly accessory;
+    constructor(platform: CyncAppPlatform, accessory: PlatformAccessory);
+}

package/dist/platformAccessory.js

@@ -0,0 +1,17 @@
+/**
+ * CyncAccessory
+ *
+ * Placeholder accessory class for future Cync devices.
+ * Currently unused; exists only to provide a typed scaffold.
+ */
+export class CyncAccessory {
+    platform;
+    accessory;
+    constructor(platform, accessory) {
+        this.platform = platform;
+        this.accessory = accessory;
+        // TODO: implement Cync-specific services and characteristics.
+        // This placeholder exists to keep the project compiling during early scaffolding.
+    }
+}
+//# sourceMappingURL=platformAccessory.js.map

package/dist/platformAccessory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platformAccessory.js","sourceRoot":"","sources":["../src/platformAccessory.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,OAAO,aAAa;IAEP;IACA;IAFlB,YACkB,QAAyB,EACzB,SAA4B;QAD5B,aAAQ,GAAR,QAAQ,CAAiB;QACzB,cAAS,GAAT,SAAS,CAAmB;QAE7C,8DAA8D;QAC9D,kFAAkF;IACnF,CAAC;CACD"}

package/dist/settings.d.ts

@@ -0,0 +1,2 @@
+export declare const PLATFORM_NAME = "CyncAppPlatform";
+export declare const PLUGIN_NAME = "homebridge-cync-app";

package/dist/settings.js

@@ -0,0 +1,3 @@
+export const PLATFORM_NAME = 'CyncAppPlatform';
+export const PLUGIN_NAME = 'homebridge-cync-app';
+//# sourceMappingURL=settings.js.map

package/dist/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAE/C,MAAM,CAAC,MAAM,WAAW,GAAG,qBAAqB,CAAC"}

package/docs/cync-api-notes.md

@@ -0,0 +1,168 @@
+# **docs/cync-api-notes.md**
+
+## **Cync Cloud API Notes**
+
+This document summarizes the Cync cloud authentication flow, device configuration endpoints, and the cloud-derived data structures used by the Cync platform. All details were extracted by analyzing the `cync_lights` Home Assistant integration.
+
+---
+
+## **1. API Base Endpoints**
+
+Defined in the upstream integration:
+
+```
+API_AUTH                = https://api.gelighting.com/v2/user_auth
+API_REQUEST_CODE        = https://api.gelighting.com/v2/two_factor/email/verifycode
+API_2FACTOR_AUTH        = https://api.gelighting.com/v2/user_auth/two_factor
+API_DEVICES             = https://api.gelighting.com/v2/user/{user}/subscribe/devices
+API_DEVICE_INFO         = https://api.gelighting.com/v2/product/{product_id}/device/{device_id}/property
+```
+
+The cloud API provides:
+
+* Authentication (username/password, optional 2FA)
+* Device enumeration across all homes
+* Room/group enumeration
+* Ability to retrieve device-level capability information
+
+All control operations occur through the TCP protocol, not the cloud API.
+
+---
+
+## **2. Authentication Flow**
+
+### **2.1 Primary Authentication**
+
+`POST /v2/user_auth`
+
+**Request fields:**
+
+* `corp_id` — fixed string `"1007d2ad150c4000"`
+* `email`
+* `password`
+
+**Success response includes:**
+
+* `access_token`
+* `authorize`
+* `user_id`
+
+These values are used to construct a **binary login code** for the TCP session.
+
+### **2.2 Two-Factor Initiation**
+
+If authentication returns HTTP 400:
+
+`POST /v2/two_factor/email/verifycode`
+
+**Request fields:**
+
+* `corp_id`
+* `email`
+* `local_lang` (`"en-us"`)
+
+If successful, a verification code is emailed to the user.
+
+### **2.3 Two-Factor Completion**
+
+`POST /v2/user_auth/two_factor`
+
+**Request fields:**
+
+* `corp_id`
+* `email`
+* `password`
+* `two_factor` — verification code
+* `resource` — fixed value `"abcdefghijklmnop"`
+
+On success, the response includes the same fields as primary authentication and allows creation of the TCP login code.
+
+---
+
+## **3. Cloud Configuration Retrieval**
+
+### **3.1 Retrieve Homes**
+
+`GET /v2/user/{user_id}/subscribe/devices`
+
+**Headers:**
+`Access-Token: <access_token>`
+
+Each home entry includes:
+
+* `id`
+* `product_id`
+* `name`
+
+### **3.2 Retrieve Devices Within Home**
+
+`GET /v2/product/{product_id}/device/{device_id}/property`
+
+**Returned fields include:**
+
+* `groupsArray` — rooms
+* `bulbsArray` — devices
+
+Devices represent switches, plugs, bulbs, sensors, and controllers.
+
+---
+
+## **4. Configuration Assembly Process**
+
+The integration processes cloud data into the following components:
+
+### **4.1 Device Lookup Tables**
+
+* `home_devices[home_id]`:
+  Maps mesh index → device ID using a deterministic function based on `deviceID` and `home.id`.
+
+* `home_controllers[home_id]`:
+  Controller devices associated with each home. Homes without controllers are discarded.
+
+* `switchID_to_homeID`:
+  Reverse mapping from controller identifier → home identifier.
+
+### **4.2 Device Records**
+
+Each device is assigned a normalized structure containing:
+
+* Name
+* Home affiliation
+* Room affiliation (if known)
+* `mesh_id`
+* `switch_id`
+* Capability flags (on/off, brightness, color temp, rgb, motion, ambient light, multielement, wifi control, plug, fan)
+
+### **4.3 Room Records**
+
+Each room record includes:
+
+* `room_id`
+* `name`
+* `mesh_id`
+* `room_controller`
+* `home_name`
+* List of switches in the room
+* Subgroups and parent relationships
+
+Subgroup relationships are validated after all rooms are constructed.
+
+---
+
+## **5. Configuration Output**
+
+The upstream integration returns the following final structure:
+
+```
+{
+  rooms,
+  devices,
+  home_devices,
+  home_controllers,
+  switchID_to_homeID
+}
+```
+
+This dataset defines the full set of controllable Cync devices and establishes the mesh addressing required for TCP commands.
+
+

package/docs/cync-client-contract.md

@@ -0,0 +1,172 @@
+# **docs/cync-client-contract.md**
+
+## **Cync Client Contract (TypeScript Implementation Outline)**
+
+This document defines a platform-independent contract for a TypeScript Cync client. It serves as the foundation for integrating the Cync system into Homebridge.
+
+The contract abstracts both the **cloud API layer** and the **TCP transport layer**.
+
+---
+
+## **1. Module Structure**
+
+The client consists of two internal subsystems:
+
+1. **ConfigClient**
+
+   * Implements cloud authentication
+   * Retrieves homes, rooms, and devices
+   * Produces a structured configuration model
+
+2. **TcpClient**
+
+   * Opens the binary TCP session
+   * Sends command frames
+   * Receives device/room/sensor updates
+
+A unifying `CyncClient` class composes these subsystems.
+
+---
+
+## **2. ConfigClient Interface**
+
+```
+interface ConfigClient {
+  login(username: string, password: string): Promise<AuthResult>;
+  submitTwoFactor(code: string): Promise<AuthResult>;
+
+  getConfig(): Promise<CyncConfig>;
+}
+```
+
+### **AuthResult**
+
+```
+interface AuthResult {
+  authorized: boolean;
+  twoFactorRequired?: boolean;
+  userId?: string;
+  accessToken?: string;
+  authorizeToken?: string;
+  loginCode?: Uint8Array;     // binary login sequence for TCP
+}
+```
+
+### **CyncConfig**
+
+```
+interface CyncConfig {
+  homes: CyncHome[];
+  rooms: { [roomId: string]: CyncRoom };
+  devices: { [deviceId: string]: CyncDevice };
+  homeDevices: { [homeId: string]: { [meshIndex: number]: string } };
+  homeControllers: { [homeId: string]: string[] };
+  switchIdToHomeId: { [switchId: string]: string };
+}
+```
+
+This structure mirrors the complete configuration returned by the upstream integration.
+
+---
+
+## **3. TcpClient Interface**
+
+```
+interface TcpClient {
+  connect(loginCode: Uint8Array, config: CyncConfig): Promise<void>;
+  disconnect(): Promise<void>;
+
+  onDeviceUpdate(cb: (update: DeviceUpdate) => void): void;
+  onRoomUpdate(cb: (update: RoomUpdate) => void): void;
+  onMotionUpdate(cb: (update: MotionUpdate) => void): void;
+  onAmbientUpdate(cb: (update: AmbientUpdate) => void): void;
+
+  setSwitchState(deviceId: string, params: SwitchParams): Promise<void>;
+}
+```
+
+### **Support Types**
+
+```
+interface DeviceUpdate {
+  deviceId: string;
+  on?: boolean;
+  brightness?: number;
+  colorTemp?: number;
+  rgb?: { r: number; g: number; b: number };
+}
+
+interface RoomUpdate {
+  roomId: string;
+  state: any;                  // full room state payload
+}
+
+interface MotionUpdate {
+  deviceId: string;
+  motion: boolean;
+}
+
+interface AmbientUpdate {
+  deviceId: string;
+  lux: number;
+}
+
+interface SwitchParams {
+  on?: boolean;
+  brightness?: number;
+  colorTemp?: number;
+  rgb?: { r: number; g: number; b: number };
+}
+```
+
+### **Behavior Requirements**
+
+* Must open a TLS connection to `cm.gelighting.com:23779` (with fallbacks).
+* Must send `loginCode` immediately after connection.
+* Must parse incoming Cync binary frames.
+* Must maintain keepalive frames.
+* Must track pending commands using sequence numbers.
+* Must resolve promises on acknowledgement or timeout.
+
+---
+
+## **4. Unified CyncClient Interface**
+
+```
+class CyncClient {
+  constructor(configClient: ConfigClient, tcpClient: TcpClient);
+
+  authenticate(username: string, password: string): Promise<AuthResult>;
+  submitTwoFactor(code: string): Promise<AuthResult>;
+
+  loadConfiguration(): Promise<CyncConfig>;
+
+  startTransport(config: CyncConfig, loginCode: Uint8Array): Promise<void>;
+  stopTransport(): Promise<void>;
+
+  setSwitchState(deviceId: string, params: SwitchParams): Promise<void>;
+
+  onDeviceUpdate(cb): void;
+  onRoomUpdate(cb): void;
+  onMotionUpdate(cb): void;
+  onAmbientUpdate(cb): void;
+}
+```
+
+The unified interface ensures that Homebridge only interacts with a single cohesive API, independent of cloud or TCP implementation details.
+
+---
+
+## **5. Scope of the Contract**
+
+This contract provides the baseline functionality for:
+
+* Plug control
+* Light control (brightness, color temperature, RGB)
+* Scene and group operations (room-level control)
+* Sensor updates (motion, ambient light)
+* Live state synchronization
+
+This set of capabilities is sufficient for initial Homebridge platform support and can be extended incrementally.
+
+---

package/docs/cync-device-model.md

@@ -0,0 +1,129 @@
+# **docs/cync-device-model.md**
+
+## **Cync Device and Room Model**
+
+This document defines the normalized structures used to represent Cync homes, rooms, devices, controllers, and capabilities. These definitions are derived from the behavior of the upstream Home Assistant integration.
+
+---
+
+## **1. Data Model Overview**
+
+The Cync platform divides user resources into:
+
+* **Homes**
+* **Rooms (Groups)**
+* **Devices (Switches, Plugs, Bulbs, Fan Switches, Motion/Ambient Sensors)**
+* **Controllers (Wi-Fi switches controlling BLE mesh groups)**
+
+The device model is primarily determined by cloud configuration, while device state is handled through the TCP protocol.
+
+---
+
+## **2. Home Structure**
+
+```
+CyncHome {
+  id: string
+  name: string
+  controllers: number[]        // switch_id values
+  homeDevices: { [meshIndex: number]: deviceId }
+}
+```
+
+### **Properties**
+
+* A home exists only if it contains at least one valid controller.
+* Controller devices act as gateways for mesh devices over the TCP protocol.
+
+---
+
+## **3. Room Structure**
+
+```
+CyncRoom {
+  roomId: string               // "{homeId}-{groupId}"
+  name: string
+  homeId: string
+  meshId: number               // group ID
+  roomController: string       // associated controller switch_id
+  switches: string[]           // device IDs belonging to this room
+  isSubgroup: boolean
+  subgroups: string[]          // child rooms
+  parentRoom?: string          // resolved later
+}
+```
+
+### **Notes**
+
+* Subgroups are validated as part of configuration assembly.
+* Some room types represent multi-element groupings.
+
+---
+
+## **4. Device Structure**
+
+```
+CyncDevice {
+  id: string
+  name: string
+  homeId: string
+  roomId?: string
+  roomName?: string
+  meshId: number
+  switchId: string             // controller association or "0"
+  capabilities: CyncCapabilities
+}
+```
+
+### **Behavior**
+
+* Devices may represent plugs, bulbs, switches, fan switches, or sensors.
+* Capabilities determine which HomeKit services will be exposed.
+
+---
+
+## **5. Capability Flags**
+
+```
+CyncCapabilities {
+  onOff: boolean
+  brightness: boolean
+  colorTemp: boolean
+  rgb: boolean
+
+  motion: boolean
+  ambientLight: boolean
+
+  wifiControl: boolean         // device is a controller
+  plug: boolean                // device is a smart plug
+  fan: boolean                 // device is a fan switch
+
+  multiElement?: number        // number of segments in multi-gang switches
+}
+```
+
+These flags originate from a fixed mapping inside the upstream integration and are chosen based on the device’s reported type.
+
+---
+
+## **6. Controller Relationships**
+
+Controllers bridge Wi-Fi → Cync mesh.
+
+* Devices with `wifiControl == true` identify themselves as controllers.
+* `switchID_to_homeID` maps each controller to an owning home.
+* Devices without `switchId` or with `"0"` are assumed to be mesh-only nodes and must route commands through their associated controller.
+
+---
+
+## **7. Summary**
+
+The model above defines the minimal structured representation required to:
+
+* Construct Homebridge accessories.
+* Route state updates.
+* Build correct command frames (requires `switchId`, `meshId`).
+* Group devices into rooms.
+* Build user-facing metadata for configuration.
+
+---