homebridge-cync-app 0.0.2

package/eslint.config.js

@@ -0,0 +1,41 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+	{
+		ignores: ['dist/**'],
+	},
+	{
+		rules: {
+			// enforce tabs
+			indent: ['error', 'tab'],
+			'no-tabs': 'off',
+
+			// formatting
+			quotes: ['error', 'single'],
+			'linebreak-style': ['error', 'unix'],
+			semi: ['error', 'always'],
+			'comma-dangle': ['error', 'always-multiline'],
+			'dot-notation': 'error',
+			eqeqeq: ['error', 'smart'],
+			curly: ['error', 'all'],
+			'brace-style': ['error'],
+			'prefer-arrow-callback': 'warn',
+			'max-len': ['warn', 160],
+			'object-curly-spacing': ['error', 'always'],
+
+			// TypeScript-specific rules
+			'no-use-before-define': 'off',
+			'@typescript-eslint/no-use-before-define': ['error', { classes: false, enums: false }],
+			'@typescript-eslint/no-unused-vars': ['error', { caughtErrors: 'none' }],
+		},
+	},
+	{
+		languageOptions: {
+			ecmaVersion: 2022,
+			sourceType: 'module',
+		},
+	},
+	eslint.configs.recommended,
+	...tseslint.configs.recommended,
+);

package/nodemon.json

@@ -0,0 +1,12 @@
+{
+	"watch": [
+	"src"
+	],
+	"ext": "ts",
+	"ignore": [],
+	"exec": "tsc && homebridge -U ./test/hbConfig -D",
+	"signal": "SIGTERM",
+	"env": {
+	"NODE_OPTIONS": "--trace-warnings"
+	}
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "homebridge-cync-app",
+	"displayName": "Homebridge Cync App",
+	"type": "module",
+	"version": "0.0.2",
+	"private": false,
+	"description": "Homebridge plugin that integrates your GE Cync account (via the Cync app/API) and exposes all supported devices: plugs, lights, switches, etc",
+	"author": "Dustin Newell",
+	"license": "Apache-2.0",
+	"homepage": "https://github.com/dash16/homebridge-cync-app#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dash16/homebridge-cync-app.git"
+	},
+	"bugs": {
+		"url": "https://github.com/dash16/homebridge-cync-app/issues"
+	},
+	"keywords": [
+		"homebridge-plugin",
+		"homebridge",
+		"cync",
+		"ge cync",
+		"smart plug",
+		"smart lights",
+		"C by GE"
+	],
+	"main": "dist/index.js",
+	"homebridge": {
+		"pluginType": "platform",
+		"platform": "CyncAppPlatform"
+	},
+	"engines": {
+		"node": "^20.18.0 || ^22.10.0 || ^24.0.0",
+		"homebridge": "^1.8.0 || ^2.0.0-beta.0"
+	},
+	"scripts": {
+		"build": "rimraf ./dist && tsc",
+		"lint": "eslint . --max-warnings=0",
+		"prepublishOnly": "npm run lint && npm run build",
+		"watch": "npm run build && npm link && nodemon"
+	},
+	"dependencies": {
+		"homebridge-lib": "^7.1.12"
+	},
+	"devDependencies": {
+		"@eslint/js": "^9.39.1",
+		"@types/node": "^24.10.1",
+		"eslint": "^9.39.1",
+		"homebridge": "^2.0.0-beta.55",
+		"nodemon": "^3.1.11",
+		"rimraf": "^6.1.0",
+		"ts-node": "^10.9.2",
+		"typescript": "^5.9.3",
+		"typescript-eslint": "^8.46.4"
+	}
+}

package/src/@types/homebridge-lib.d.ts

@@ -0,0 +1,14 @@
+declare module 'homebridge-lib/EveHomeKitTypes' {
+	export class EveHomeKitTypes {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	  constructor(homebridge: any);
+
+	  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+	  Characteristics: Record<string, any>;
+	  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+	  Services: Record<string, any>;
+	}
+}
+
+declare module 'homebridge-lib' {
+}

package/src/cync/config-client.ts

@@ -0,0 +1,370 @@
+// src/cync/config-client.ts
+// Cync cloud configuration & login client.
+// Handles 2FA email flow and basic device/config queries against api.gelighting.com.
+//
+// This is intentionally low-level and stateless-ish: CyncClient is expected to
+// own an instance of this class and persist the resulting session info.
+
+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;
+
+type HttpResponse = {
+	ok: boolean;
+	status: number;
+	statusText: string;
+	json(): Promise<unknown>;
+	text(): Promise<string>;
+};
+
+type CyncErrorBody = {
+	error?: {
+		msg?: string;
+		[key: string]: unknown;
+	};
+	[key: string]: unknown;
+};
+
+export interface CyncLoginSession {
+	accessToken: string;
+	userId: string;
+	raw: unknown;
+}
+
+export interface CyncDevice {
+	id: string;
+	name?: string;
+	product_id?: string;
+	device_id?: string;
+	mac?: string;
+	sn?: string;
+	[key: string]: unknown;
+}
+
+export interface CyncDeviceMesh {
+	id: string;
+	name?: string;
+	product_id: string;
+	access_key?: string;
+	mac?: string;
+	properties?: Record<string, unknown>;
+	devices?: CyncDevice[];
+	[key: string]: unknown;
+}
+
+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 CyncLogger {
+	debug(message: string, ...args: unknown[]): void;
+	info(message: string, ...args: unknown[]): void;
+	warn(message: string, ...args: unknown[]): void;
+	error(message: string, ...args: unknown[]): void;
+}
+
+const defaultLogger: CyncLogger = {
+	debug: (...args: unknown[]) => console.debug('[cync-config]', ...args),
+	info: (...args: unknown[]) => console.info('[cync-config]', ...args),
+	warn: (...args: unknown[]) => console.warn('[cync-config]', ...args),
+	error: (...args: unknown[]) => console.error('[cync-config]', ...args),
+};
+
+export class ConfigClient {
+	private readonly log: CyncLogger;
+
+	// These are populated after a successful 2FA login.
+	private accessToken: string | null = null;
+	private userId: string | null = null;
+
+	constructor(logger?: CyncLogger) {
+		this.log = logger ?? defaultLogger;
+	}
+
+	/**
+	 * Request that Cync send a one-time 2FA verification code to the given email.
+	 *
+	 * This MUST be called before loginWithTwoFactor() for accounts that require 2FA.
+	 * The user reads the code from their email and provides it to loginWithTwoFactor.
+	 */
+	public async sendTwoFactorCode(email: string): Promise<void> {
+		const url = `${CYNC_API_BASE}two_factor/email/verifycode`;
+		this.log.debug(`Requesting Cync 2FA code for ${email}…`);
+
+		const body = {
+			corp_id: CORP_ID,
+			email,
+			local_lang: 'en-us',
+		};
+
+		const res = (await fetch(url, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json',
+			},
+			body: JSON.stringify(body),
+		})) as HttpResponse;
+
+		if (!res.ok) {
+			const text = await res.text().catch(() => '');
+			this.log.error(
+				`Cync 2FA request failed: HTTP ${res.status} ${res.statusText} ${text}`,
+			);
+			throw new Error(`Cync 2FA request failed with status ${res.status}`);
+		}
+
+		this.log.info('Cync 2FA email request succeeded.');
+	}
+
+	/**
+	 * Perform the actual 2FA login and capture the access token + userId.
+	 *
+	 * You are expected to first call sendTwoFactorCode(), then prompt the user
+	 * for the emailed OTP code, then call loginWithTwoFactor() with that code.
+	 *
+	 * The access token is used for subsequent getCloudConfig() / getDeviceProperties() calls.
+	 */
+	public async loginWithTwoFactor(
+		email: string,
+		password: string,
+		otpCode: string,
+	): Promise<CyncLoginSession> {
+		const url = `${CYNC_API_BASE}user_auth/two_factor`;
+		this.log.debug('Logging into Cync with 2FA for %s…', email);
+
+		const body = {
+			corp_id: CORP_ID,
+			email,
+			password,
+			two_factor: otpCode,
+			// Matches the reference implementations: random 16-char string.
+			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 login returned non-JSON payload: ${text}`);
+		});
+
+		if (!res.ok) {
+			this.log.error(
+				'Cync login failed: HTTP %d %s %o',
+				res.status,
+				res.statusText,
+				json,
+			);
+			const errBody = json as CyncErrorBody;
+			throw new Error(
+				errBody.error?.msg ??
+				`Cync login failed with status ${res.status} ${res.statusText}`,
+			);
+		}
+
+		const obj = json as Record<string, unknown>;
+		this.log.debug('Cync login response: keys=%o', Object.keys(obj));
+
+		// Accept both snake_case and camelCase, and both string/number user_id.
+		const accessTokenRaw = obj.access_token ?? obj.accessToken;
+		const userIdRaw = obj.user_id ?? obj.userId;
+
+		const accessToken =
+			typeof accessTokenRaw === 'string' && accessTokenRaw.length > 0
+				? accessTokenRaw
+				: undefined;
+
+		const userId =
+			userIdRaw !== undefined && userIdRaw !== null
+				? String(userIdRaw)
+				: undefined;
+
+		if (!accessToken || !userId) {
+			this.log.error('Cync login missing access_token or user_id: %o', json);
+			throw new Error('Cync login response missing access_token or user_id');
+		}
+
+		this.accessToken = accessToken;
+		this.userId = userId;
+
+		this.log.info('Cync login successful; userId=%s', userId);
+
+		return {
+			accessToken,
+			userId,
+			raw: json,
+		};
+	}
+
+	/**
+	 * Fetch the list of meshes/devices for the current user from the cloud.
+	 *
+	 * This roughly matches CyncCloudAPI.get_devices() from cync-lan, but in a
+	 * simplified, single-call interface.
+	 */
+	public async getCloudConfig(): Promise<CyncCloudConfig> {
+		this.ensureSession();
+
+		const devicesUrl = `${CYNC_API_BASE}user/${this.userId}/subscribe/devices`;
+		const headers = {
+			'Access-Token': this.accessToken as string,
+		};
+
+		this.log.debug('Fetching Cync devices from %s', devicesUrl);
+
+		const res = (await fetch(devicesUrl, {
+			method: 'GET',
+			headers,
+		})) as HttpResponse;
+
+		const json: unknown = await res.json().catch(async () => {
+			const text = await res.text().catch(() => '');
+			throw new Error(`Cync devices returned non-JSON payload: ${text}`);
+		});
+
+		if (!res.ok) {
+			this.log.error(
+				'Cync devices call failed: HTTP %d %s %o',
+				res.status,
+				res.statusText,
+				json,
+			);
+			const errBody = json as CyncErrorBody;
+			const msg = errBody.error?.msg ?? 'Unknown error from Cync devices API';
+			throw new Error(msg);
+		}
+
+		// DEBUG: log high-level shape without dumping any secrets.
+		if (Array.isArray(json)) {
+			this.log.debug(
+				'Cync devices payload: top-level array length=%d; first item keys=%o',
+				json.length,
+				json.length > 0 ? Object.keys((json as Record<string, unknown>[])[0]) : [],
+			);
+		} else if (json && typeof json === 'object') {
+			this.log.debug(
+				'Cync devices payload: top-level object keys=%o',
+				Object.keys(json as Record<string, unknown>),
+			);
+		} else {
+			this.log.debug(
+				'Cync devices payload: top-level type=%s',
+				typeof json,
+			);
+		}
+
+		// Some Cync responses wrap arrays; others are raw arrays.
+		let meshes: CyncDeviceMesh[] = [];
+
+		if (Array.isArray(json)) {
+			meshes = json as CyncDeviceMesh[];
+		} else if (json && typeof json === 'object') {
+			const obj = json as Record<string, unknown>;
+
+			// Best guess: devices may be under a named property.
+			// We just log for now; once we see the payload, we can wire this properly.
+			this.log.debug(
+				'Cync devices payload (object) example values for known keys=%o',
+				{
+					dataType: typeof obj.data,
+					devicesType: typeof (obj.devices as unknown),
+					meshesType: typeof (obj.meshes as unknown),
+				},
+			);
+
+			// Temporary: if there's a "data" array, treat that as meshes.
+			if (Array.isArray(obj.data)) {
+				meshes = obj.data as CyncDeviceMesh[];
+			} else if (Array.isArray(obj.meshes)) {
+				meshes = obj.meshes as CyncDeviceMesh[];
+			}
+		}
+
+		return { meshes };
+
+	}
+
+	/**
+	 * Convenience to fetch the properties object for a single device.
+	 */
+	public async getDeviceProperties(
+		productId: string,
+		deviceId: string,
+	): Promise<Record<string, unknown>> {
+		this.ensureSession();
+
+		const url = `${CYNC_API_BASE}product/${encodeURIComponent(
+			productId,
+		)}/device/${encodeURIComponent(deviceId)}/property`;
+
+		const res = (await fetch(url, {
+			method: 'GET',
+			headers: {
+				'Access-Token': this.accessToken as string,
+			},
+		})) as HttpResponse;
+
+		const json: unknown = await res.json().catch(async () => {
+			const text = await res.text().catch(() => '');
+			throw new Error(`Cync properties returned non-JSON payload: ${text}`);
+		});
+
+		if (!res.ok) {
+			this.log.error(
+				'Cync properties call failed: HTTP %d %s %o',
+				res.status,
+				res.statusText,
+				json,
+			);
+			const errBody = json as CyncErrorBody;
+			const msg =
+				errBody.error?.msg ?? `Cync properties failed with ${res.status}`;
+			throw new Error(msg);
+		}
+
+		// We keep this as a loose record; callers can shape it as needed.
+		return json as Record<string, unknown>;
+	}
+
+	public restoreSession(accessToken: string, userId: string): void {
+		this.accessToken = accessToken;
+		this.userId = userId;
+		this.log.info('Cync: restored session from stored token; userId=%s', userId);
+	}
+
+	public getSessionSnapshot(): { accessToken: string | null; userId: string | null } {
+		return {
+			accessToken: this.accessToken,
+			userId: this.userId,
+		};
+	}
+
+	private ensureSession(): void {
+		if (!this.accessToken || !this.userId) {
+			throw new Error('Cync session not initialised. Call loginWithTwoFactor() first.');
+		}
+	}
+
+	private static randomLoginResource(): string {
+		const chars = 'abcdefghijklmnopqrstuvwxyz';
+		let out = '';
+		for (let i = 0; i < 16; i += 1) {
+			out += chars.charAt(Math.floor(Math.random() * chars.length));
+		}
+		return out;
+	}
+}