homebridge-cync-app 0.1.5 → 0.1.7

package/src/cync/config-client.ts

@@ -8,7 +8,6 @@
 const CYNC_API_BASE = 'https://api.gelighting.com/v2/';
 const CORP_ID = '1007d2ad150c4000';
 
-// Minimal fetch/response typing for Node 18+, without depending on DOM lib types.
 type FetchLike = (input: unknown, init?: unknown) => Promise<unknown>;
 
 declare const fetch: FetchLike;
@@ -65,10 +64,12 @@ export interface CyncCloudConfig {
 	meshes: CyncDeviceMesh[];
 }
 
-/**
- * Very small logger interface so we can accept either the Homebridge log
- * object or console.* functions in tests.
- */
+export interface CyncRefreshResponse {
+	accessToken: string;
+	refreshToken?: string;
+	expiresAt?: number;
+}
+
 export interface CyncLogger {
 	debug(message: string, ...args: unknown[]): void;
 	info(message: string, ...args: unknown[]): void;
@@ -151,7 +152,6 @@ export class ConfigClient {
 			email,
 			password,
 			two_factor: otpCode,
-			// Matches the reference implementations: random 16-char string.
 			resource: ConfigClient.randomLoginResource(),
 		};
 
@@ -223,6 +223,80 @@ export class ConfigClient {
 			raw: json,
 		};
 	}
+	/**
+	 * Refresh the access token using a stored refresh token.
+	 *
+	 * This mirrors the 2FA login flow in shape, but only exchanges the
+	 * refresh_token for a new access_token (and possibly a new refresh_token).
+	 */
+	public async refreshAccessToken(refreshToken: string): Promise<CyncRefreshResponse> {
+		const url = `${CYNC_API_BASE}user_auth/refresh`;
+		this.log.debug('Refreshing Cync access token…');
+
+		const body = {
+			corp_id: CORP_ID,
+			refresh_token: refreshToken,
+			resource: ConfigClient.randomLoginResource(),
+		};
+
+		const res = (await fetch(url, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json',
+			},
+			body: JSON.stringify(body),
+		})) as HttpResponse;
+
+		const json: unknown = await res.json().catch(async () => {
+			const text = await res.text().catch(() => '');
+			throw new Error(`Cync refresh returned non-JSON payload: ${text}`);
+		});
+
+		if (!res.ok) {
+			this.log.error(
+				'Cync refresh failed: HTTP %d %s %o',
+				res.status,
+				res.statusText,
+				json,
+			);
+			const errBody = json as CyncErrorBody;
+			const msg =
+				errBody.error?.msg ??
+				`Cync refresh failed with status ${res.status} ${res.statusText}`;
+			throw new Error(msg);
+		}
+
+		const obj = json as Record<string, unknown>;
+		this.log.debug('Cync refresh response: keys=%o', Object.keys(obj));
+
+		const accessTokenRaw = obj.access_token ?? obj.accessToken;
+		const refreshTokenRaw = obj.refresh_token ?? obj.refreshToken;
+		const expiresAtRaw = obj.expires_at ?? obj.expiresAt;
+
+		const accessToken =
+			typeof accessTokenRaw === 'string' && accessTokenRaw.length > 0
+				? accessTokenRaw
+				: undefined;
+
+		if (!accessToken) {
+			this.log.error('Cync refresh missing access_token: %o', json);
+			throw new Error('Cync refresh response missing access_token');
+		}
+
+		const next: CyncRefreshResponse = {
+			accessToken,
+		};
+
+		if (typeof refreshTokenRaw === 'string' && refreshTokenRaw.length > 0) {
+			next.refreshToken = refreshTokenRaw;
+		}
+
+		if (typeof expiresAtRaw === 'number') {
+			next.expiresAt = expiresAtRaw;
+		}
+
+		return next;
+	}
 
 	/**
 	 * Fetch the list of meshes/devices for the current user from the cloud.

package/src/cync/cync-client.ts

@@ -321,6 +321,120 @@ export class CyncClient {
 	 *   // user reads email, gets code…
 	 *   await client.submitTwoFactor(username, password, code); // completes login
 	 */
+	// ### 🧩 Refresh Error Detector: identifies "Access-Token Expired" responses
+	private isAccessTokenExpiredError(err: unknown): boolean {
+		if (!err || typeof err !== 'object') {
+			return false;
+		}
+
+		type ErrorWithShape = {
+			status?: number;
+			message?: string;
+			error?: {
+				msg?: string;
+				code?: number;
+			};
+		};
+
+		const e = err as ErrorWithShape;
+
+		// Shape we see in logs:
+		// { error: { msg: 'Access-Token Expired', code: 4031021 } }
+		if (e.error && (e.error.msg === 'Access-Token Expired' || e.error.code === 4031021)) {
+			return true;
+		}
+
+		// Fallback: generic 403 with message string
+		if (e.status === 403 && e.message && e.message.includes('Access-Token Expired')) {
+			return true;
+		}
+
+		return false;
+	}
+
+	// ### 🧩 Token Refresh Helper: exchanges refreshToken for a new accessToken
+	private async refreshAccessToken(stored: CyncTokenData): Promise<CyncTokenData | null> {
+		if (!stored.refreshToken) {
+			this.log.warn(
+				'CyncClient: refreshAccessToken() called but no refreshToken is stored; cannot refresh.',
+			);
+			return null;
+		}
+
+		try {
+			const resp = await this.configClient.refreshAccessToken(stored.refreshToken);
+
+			const next: CyncTokenData = {
+				...stored,
+				accessToken: resp.accessToken,
+				refreshToken: resp.refreshToken ?? stored.refreshToken,
+				expiresAt: resp.expiresAt ?? stored.expiresAt,
+			};
+
+			await this.tokenStore.save(next);
+			this.tokenData = next;
+			this.applyAccessToken(next);
+
+			this.log.info(
+				'CyncClient: refreshed access token for userId=%s; expiresAt=%s',
+				next.userId,
+				next.expiresAt ? new Date(next.expiresAt).toISOString() : 'unknown',
+			);
+
+			return next;
+		} catch (err) {
+			this.log.error('CyncClient: token refresh failed: %o', err);
+			return null;
+		}
+	}
+
+	// ### 🧩 Cloud Config Wrapper: auto-refreshes access token
+	private async getCloudConfigWithRefresh(): Promise<CyncCloudConfig> {
+		try {
+			return await this.configClient.getCloudConfig();
+		} catch (err) {
+			if (this.isAccessTokenExpiredError(err) && this.tokenData) {
+				this.log.warn(
+					'CyncClient: access token expired when calling getCloudConfig(); refreshing and retrying once.',
+				);
+
+				const refreshed = await this.refreshAccessToken(this.tokenData);
+				if (refreshed) {
+					return await this.configClient.getCloudConfig();
+				}
+			}
+
+			throw err;
+		}
+	}
+
+	// ### 🧩 Device Properties Wrapper: auto-refresh on Access-Token Expired for mesh calls
+	private async getDevicePropertiesWithRefresh(
+		productId: string | number,
+		meshId: string | number,
+	): Promise<Record<string, unknown>> {
+		// Normalise to strings for ConfigClient
+		const productIdStr = String(productId);
+		const meshIdStr = String(meshId);
+
+		try {
+			return await this.configClient.getDeviceProperties(productIdStr, meshIdStr);
+		} catch (err) {
+			if (this.isAccessTokenExpiredError(err) && this.tokenData) {
+				this.log.warn(
+					'CyncClient: access token expired when calling getDeviceProperties(); refreshing and retrying once.',
+				);
+
+				const refreshed = await this.refreshAccessToken(this.tokenData);
+				if (refreshed) {
+					return await this.configClient.getDeviceProperties(productIdStr, meshIdStr);
+				}
+			}
+
+			throw err;
+		}
+	}
+
 	public async authenticate(username: string): Promise<void> {
 		const email = username.trim();
 
@@ -381,7 +495,7 @@ export class CyncClient {
 		this.ensureSession();
 
 		this.log.info('CyncClient: loading Cync cloud configuration…');
-		const cfg = await this.configClient.getCloudConfig();
+		const cfg = await this.getCloudConfigWithRefresh();
 
 		// Reset LAN topology caches on each reload
 		this.homeDevices = {};
@@ -405,7 +519,7 @@ export class CyncClient {
 			const homeControllers: number[] = [];
 
 			try {
-				const props = await this.configClient.getDeviceProperties(
+				const props = await this.getDevicePropertiesWithRefresh(
 					mesh.product_id,
 					mesh.id,
 				);
@@ -427,6 +541,26 @@ export class CyncClient {
 						bulbsArray[0] ? Object.keys(bulbsArray[0] as Record<string, unknown>) : [],
 					);
 
+					// ### 🧩 Bulb Capability Debug: log each bulb so we can classify plugs vs lights
+					bulbsArray.forEach((bulb, index) => {
+						const record = bulb as Record<string, unknown>;
+
+						this.log.debug(
+							'CyncClient: bulb #%d for mesh %s → %o',
+							index,
+							meshName,
+							{
+								displayName: record.displayName,
+								deviceID: record.deviceID ?? record.deviceId,
+								deviceType: record.deviceType,
+								loadSelection: record.loadSelection,
+								defaultBrightness: record.defaultBrightness,
+								lightRingColor: record.lightRingColor,
+								raw: record,
+							},
+						);
+					});
+
 					type RawDevice = Record<string, unknown>;
 					const rawDevices = bulbsArray as unknown[];
 

package/src/cync/device-catalog.ts

@@ -0,0 +1,55 @@
+// src/cync/device-catalog.ts
+
+import type { Categories } from 'homebridge';
+
+export interface CyncDeviceModel {
+	/** Raw deviceType from the Cync API */
+	deviceType: number;
+
+	/** Model name as shown in the Cync app (what you want HomeKit to show) */
+	modelName: string;
+
+	/** Optional marketing / retail name if you want to surface it somewhere else */
+	marketingName?: string;
+
+	/** Optional suggested HomeKit category override */
+	defaultCategory?: Categories;
+
+	/** Free-form notes for you / debugging */
+	notes?: string;
+}
+
+/**
+ * Device catalog keyed by deviceType.
+ * Extend this as you discover more types.
+ */
+export const DEVICE_CATALOG: Record<number, CyncDeviceModel> = {
+	46: {
+		deviceType: 46,
+		modelName: '6" Recessed Can Retrofit Fixture (Matter)',
+		marketingName: 'Cync reveal HD+',
+		// defaultCategory: Categories.LIGHTBULB,
+	},
+	64: {
+		deviceType: 64,
+		modelName: 'Indoor Smart Plug',
+		marketingName: 'On/Off Smart Plug',
+		// defaultCategory: Categories.OUTLET,
+	},
+	65: {
+		deviceType: 65,
+		modelName: 'Indoor Smart Plug',
+		marketingName: 'Cync Indoor Plug',
+		// defaultCategory: Categories.OUTLET,
+	},
+	172: {
+		deviceType: 172,
+		modelName: 'Indoor Smart Plug (3in1)',
+		marketingName: 'Cync Indoor Smart Plug',
+		// defaultCategory: Categories.OUTLET,
+	},
+};
+
+export function lookupDeviceModel(deviceType: number): CyncDeviceModel | undefined {
+	return DEVICE_CATALOG[deviceType];
+}

package/src/cync/tcp-client.ts

@@ -38,12 +38,7 @@ export class TcpClient {
 	private heartbeatTimer: NodeJS.Timeout | null = null;
 	private rawFrameListeners: RawFrameListener[] = [];
 	private controllerToDevice = new Map<number, string>();
-	/**
-	 * ### 🧩 LAN Command Serializer: Ensures TCP commands are sent one at a time
-	 *
-	 * Wraps any TCP command in a promise chain so commands are serialized
-	 * and cannot be written to the socket concurrently.
-	 */
+
 	private enqueueCommand<T>(fn: () => Promise<T>): Promise<T> {
 		let resolveWrapper: (value: T | PromiseLike<T>) => void;
 		let rejectWrapper: (reason?: unknown) => void;
@@ -179,7 +174,6 @@ export class TcpClient {
 		await this.ensureConnected();
 	}
 
-
 	public applyLanTopology(topology: {
 		homeDevices: Record<string, string[]>;
 		switchIdToHomeId: Record<number, string>;
@@ -201,10 +195,6 @@ export class TcpClient {
 		);
 	}
 
-	/**
-	 * Ensure we have an open, logged-in socket.
-	 * If the socket is closed or missing, attempt to reconnect.
-	 */
 	private async ensureConnected(): Promise<boolean> {
 		if (this.socket && !this.socket.destroyed) {
 			return true;
@@ -221,10 +211,6 @@ export class TcpClient {
 		return !!(this.socket && !this.socket.destroyed);
 	}
 
-	/**
-	 * Open a new socket to cm.gelighting.com and send the loginCode,
-	 * mirroring the HA integration’s behavior.
-	 */
 	private async establishSocket(): Promise<void> {
 		const host = 'cm.gelighting.com';
 		const portTLS = 23779;
@@ -367,6 +353,69 @@ export class TcpClient {
 		]);
 	}
 
+	private buildComboPacket(
+		controllerId: number,
+		meshId: number,
+		on: boolean,
+		brightnessPct: number,
+		colorTone: number,
+		rgb: { r: number; g: number; b: number },
+		seq: number,
+	): Buffer {
+		const header = Buffer.from('7300000022', 'hex');
+
+		const switchBytes = Buffer.alloc(4);
+		switchBytes.writeUInt32BE(controllerId, 0);
+
+		const seqBytes = Buffer.alloc(2);
+		seqBytes.writeUInt16BE(seq, 0);
+
+		const middle = Buffer.from('007e00000000f8f010000000000000', 'hex');
+
+		const meshBytes = Buffer.alloc(2);
+		meshBytes.writeUInt16LE(meshId, 0);
+
+		const tailPrefix = Buffer.from('f00000', 'hex');
+
+		const onByte = on ? 1 : 0;
+		const brightnessByte = Math.max(0, Math.min(100, Math.round(brightnessPct)));
+		const colorToneByte = Math.max(0, Math.min(255, Math.round(colorTone)));
+
+		const r = Math.max(0, Math.min(255, Math.round(rgb.r)));
+		const g = Math.max(0, Math.min(255, Math.round(rgb.g)));
+		const b = Math.max(0, Math.min(255, Math.round(rgb.b)));
+
+		const rgbBytes = Buffer.from([r, g, b]);
+
+		const checksumSeed =
+				496 +
+				meshBytes[0] +
+				meshBytes[1] +
+				onByte +
+				brightnessByte +
+				colorToneByte +
+				r +
+				g +
+				b;
+
+		const checksum = Buffer.from([checksumSeed & 0xff]);
+		const end = Buffer.from('7e', 'hex');
+
+		return Buffer.concat([
+			header,
+			switchBytes,
+			seqBytes,
+			middle,
+			meshBytes,
+			tailPrefix,
+			Buffer.from([onByte]),
+			Buffer.from([brightnessByte]),
+			Buffer.from([colorToneByte]),
+			rgbBytes,
+			checksum,
+			end,
+		]);
+	}
 	public async disconnect(): Promise<void> {
 		this.log.info('[Cync TCP] disconnect() called.');
 		if (this.heartbeatTimer) {
@@ -400,10 +449,6 @@ export class TcpClient {
 		this.rawFrameListeners.push(listener);
 	}
 
-	/**
-	 * High-level API to change switch state.
-	 * Ensures we have a live socket before sending and serializes commands.
-	 */
 	public async setSwitchState(
 		deviceId: string,
 		params: { on: boolean },
@@ -429,6 +474,14 @@ export class TcpClient {
 			}
 
 			const record = device as Record<string, unknown>;
+			this.log.debug(
+				'[Cync TCP] setSwitchState: deviceId=%s device_type=%o switch_controller=%o mesh_id=%o home_id=%o',
+				deviceId,
+				record.device_type,
+				record.switch_controller,
+				record.mesh_id,
+				record.home_id,
+			);
 			const controllerId = Number(record.switch_controller);
 			const meshIndex = Number(record.mesh_id);
 
@@ -456,6 +509,143 @@ export class TcpClient {
 		});
 	}
 
+	public async setBrightness(deviceId: string, brightnessPct: number): Promise<void> {
+		return this.enqueueCommand(async () => {
+			if (!this.config) {
+				this.log.warn('[Cync TCP] setBrightness: no config available.');
+				return;
+			}
+
+			const connected = await this.ensureConnected();
+			if (!connected || !this.socket || this.socket.destroyed) {
+				this.log.warn(
+					'[Cync TCP] setBrightness: socket not ready even after reconnect attempt.',
+				);
+				return;
+			}
+
+			const device = this.findDevice(deviceId);
+			if (!device) {
+				this.log.warn('[Cync TCP] setBrightness: unknown deviceId=%s', deviceId);
+				return;
+			}
+
+			const record = device as Record<string, unknown>;
+			const controllerId = Number(record.switch_controller);
+			const meshIndex = Number(record.mesh_id);
+
+			if (!Number.isFinite(controllerId) || !Number.isFinite(meshIndex)) {
+				this.log.warn(
+					'[Cync TCP] setBrightness: device %s missing LAN fields (switch_controller=%o mesh_id=%o)',
+					deviceId,
+					record.switch_controller,
+					record.mesh_id,
+				);
+				return;
+			}
+
+			const clamped = Math.max(0, Math.min(100, Number(brightnessPct)));
+			const on = clamped > 0;
+
+			const seq = this.nextSeq();
+
+			// White-only combo control for now; color support can layer on this later.
+			const packet = this.buildComboPacket(
+				controllerId,
+				meshIndex,
+				on,
+				clamped,
+				255, // color_tone=255 ("white" in HA integration)
+				{ r: 255, g: 255, b: 255 },
+				seq,
+			);
+
+			this.socket.write(packet);
+			this.log.info(
+				'[Cync TCP] Sent combo (brightness) packet: device=%s on=%s brightness=%d seq=%d',
+				deviceId,
+				String(on),
+				clamped,
+				seq,
+			);
+		});
+	}
+
+	public async setColor(
+		deviceId: string,
+		rgb: { r: number; g: number; b: number },
+		brightnessPct?: number,
+	): Promise<void> {
+		return this.enqueueCommand(async () => {
+			if (!this.config) {
+				this.log.warn('[Cync TCP] setColor: no config available.');
+				return;
+			}
+
+			const connected = await this.ensureConnected();
+			if (!connected || !this.socket || this.socket.destroyed) {
+				this.log.warn(
+					'[Cync TCP] setColor: socket not ready even after reconnect attempt.',
+				);
+				return;
+			}
+
+			const device = this.findDevice(deviceId);
+			if (!device) {
+				this.log.warn('[Cync TCP] setColor: unknown deviceId=%s', deviceId);
+				return;
+			}
+
+			const record = device as Record<string, unknown>;
+			const controllerId = Number(record.switch_controller);
+			const meshIndex = Number(record.mesh_id);
+
+			if (!Number.isFinite(controllerId) || !Number.isFinite(meshIndex)) {
+				this.log.warn(
+					'[Cync TCP] setColor: device %s missing LAN fields (switch_controller=%o mesh_id=%o)',
+					deviceId,
+					record.switch_controller,
+					record.mesh_id,
+				);
+				return;
+			}
+
+			const clampedBrightness = Math.max(
+				0,
+				Math.min(100, Math.round(brightnessPct ?? 100)),
+			);
+			const on = clampedBrightness > 0;
+
+			const r = Math.max(0, Math.min(255, Math.round(rgb.r)));
+			const g = Math.max(0, Math.min(255, Math.round(rgb.g)));
+			const b = Math.max(0, Math.min(255, Math.round(rgb.b)));
+
+			const seq = this.nextSeq();
+
+			// colorTone=254 => "color" mode, per HA's combo_control for RGB
+			const packet = this.buildComboPacket(
+				controllerId,
+				meshIndex,
+				on,
+				clampedBrightness,
+				254,
+				{ r, g, b },
+				seq,
+			);
+
+			this.socket.write(packet);
+			this.log.info(
+				'[Cync TCP] Sent color combo packet: device=%s on=%s brightness=%d rgb=(%d,%d,%d) seq=%d',
+				deviceId,
+				String(on),
+				clampedBrightness,
+				r,
+				g,
+				b,
+				seq,
+			);
+		});
+	}
 	private findDevice(deviceId: string) {
 		for (const mesh of this.config?.meshes ?? []) {
 			for (const dev of mesh.devices ?? []) {
@@ -563,13 +753,14 @@ export class TcpClient {
 		// Default payload is the raw frame
 		let payload: unknown = frame;
 
-		if (type === 0x83) {
-			// Preferred path: HA-style per-device parsing using homeDevices + switchIdToHomeId
+		// 0x73 / 0x83 carry per-device state updates on the LAN.
+		// Mirror the HA integration: try the topology-based parser first.
+		if (type === 0x73 || type === 0x83) {
 			const lanParsed = this.parseLanSwitchUpdate(frame);
 			if (lanParsed) {
 				payload = lanParsed;
-			} else {
-				// Fallback to legacy controller-level parsing
+			} else if (type === 0x83) {
+				// Fallback to legacy controller-level parsing only for 0x83
 				const parsed = this.parseSwitchStateFrame(frame);
 				if (parsed) {
 					const deviceId = this.controllerToDevice.get(parsed.controllerId);

package/src/cync/token-store.ts

@@ -13,12 +13,17 @@ export interface CyncTokenData {
 
 /**
  * Simple JSON token store under the Homebridge storage path.
+ *
+ * Files are stored at:
+ *   <storagePath>/homebridge-cync-app/cync-tokens.json
  */
 export class CyncTokenStore {
+	private readonly dirPath: string;
 	private readonly filePath: string;
 
 	public constructor(storagePath: string) {
-		this.filePath = path.join(storagePath, 'cync-tokens.json');
+		this.dirPath = path.join(storagePath, 'homebridge-cync-app');
+		this.filePath = path.join(this.dirPath, 'cync-tokens.json');
 	}
 
 	public async load(): Promise<CyncTokenData | null> {
@@ -33,12 +38,16 @@ export class CyncTokenStore {
 
 			return data;
 		} catch {
+			// file missing or unreadable → treat as no token
 			return null;
 		}
 	}
 
 	public async save(data: CyncTokenData): Promise<void> {
 		const json = JSON.stringify(data, null, 2);
+
+		// Ensure directory exists before writing
+		await fs.mkdir(this.dirPath, { recursive: true });
 		await fs.writeFile(this.filePath, json, 'utf8');
 	}
 
@@ -46,7 +55,7 @@ export class CyncTokenStore {
 		try {
 			await fs.unlink(this.filePath);
 		} catch {
-			// ignore if missing
+			// ignore if missing or already removed
 		}
 	}
 }