tsvesync 1.3.12 → 1.4.0

package/src/lib/fans/airBypass.ts

@@ -7,7 +7,9 @@ import { logger } from '../logger';
  * VeSync Air Purifier with Bypass
  */
 export class VeSyncAirBypass extends VeSyncFan {
-    protected readonly modes = ['auto', 'manual', 'sleep'] as const;
+    protected get modes(): ReadonlyArray<string> {
+        return this.getConfigModes(['auto', 'manual', 'sleep']);
+    }
     protected readonly displayModes = ['on', 'off'] as const;
     protected readonly childLockModes = ['on', 'off'] as const;
 
@@ -87,6 +89,12 @@ export class VeSyncAirBypass extends VeSyncFan {
                     air_quality_value: result.air_quality_value || 0
                 };
 
+                const normalizedAirQuality = Helpers.normalizeAirQuality(result.air_quality);
+                if (normalizedAirQuality.level >= 1) {
+                    this.details.air_quality_level = normalizedAirQuality.level;
+                }
+                this.details.air_quality_label = normalizedAirQuality.label;
+
                 // Capture additional air quality properties if available
                 if ('PM1' in result) this.details.pm1 = result.PM1;
                 if ('PM10' in result) this.details.pm10 = result.PM10;
@@ -210,16 +218,20 @@ export class VeSyncAirBypass extends VeSyncFan {
      * Set device mode
      */
     async setMode(mode: string): Promise<boolean> {
-        if (!this.modes.includes(mode as any)) {
+        const requested = mode.toLowerCase();
+        const supported = this.modes.map(m => m.toLowerCase());
+        const allowsCore200AutoFallback = this.deviceType.includes('Core200S') && requested === 'auto';
+
+        if (!supported.includes(requested) && !allowsCore200AutoFallback) {
             const error = `Invalid mode: ${mode}. Must be one of: ${this.modes.join(', ')}`;
             logger.error(`${error} for device: ${this.deviceName}`);
             throw new Error(error);
         }
 
-        logger.debug(`Setting mode to ${mode} for device: ${this.deviceName}`);
+        logger.debug(`Setting mode to ${requested} for device: ${this.deviceName}`);
 
         // Special handling for Core200S auto mode
-        if (this.deviceType.includes('Core200S') && mode === 'auto') {
+        if (allowsCore200AutoFallback) {
             // Core200S doesn't support auto mode, so we'll set it to manual mode
             logger.warn(`Auto mode not supported for ${this.deviceType}, using manual mode instead`);
             return this.setMode('manual');
@@ -235,7 +247,7 @@ export class VeSyncAirBypass extends VeSyncFan {
                 configModule: this.configModule,
                 payload: {
                     data: {
-                        mode
+                        mode: requested
                     },
                     method: 'setPurifierMode',
                     source: 'APP'
@@ -246,10 +258,10 @@ export class VeSyncAirBypass extends VeSyncFan {
 
         const success = this.checkResponse([response, status], 'setMode');
         if (success) {
-            this.details.mode = mode;
+            this.details.mode = requested;
             return true;
         } else {
-            logger.error(`Failed to set mode to ${mode} for device: ${this.deviceName}`);
+            logger.error(`Failed to set mode to ${requested} for device: ${this.deviceName}`);
             return false;
         }
     }

package/src/lib/helpers.ts

@@ -245,6 +245,52 @@ export class Helpers {
         return generateTraceId();
     }
 
+    static normalizeAirQuality(value: unknown): { level: number; label: string } {
+        const stringMap: Record<string, number> = {
+            'excellent': 1,
+            'very good': 1,
+            'good': 2,
+            'moderate': 3,
+            'fair': 3,
+            'inferior': 4,
+            'poor': 4,
+            'bad': 4,
+        };
+
+        if (typeof value === 'number') {
+            const level = Number.isFinite(value) ? Math.trunc(value) : -1;
+            if (level >= 1 && level <= 4) {
+                return {
+                    level,
+                    label: level === 1
+                        ? 'excellent'
+                        : level === 2
+                            ? 'good'
+                            : level === 3
+                                ? 'moderate'
+                                : 'poor',
+                };
+            }
+        } else if (typeof value === 'string') {
+            const normalized = value.trim().toLowerCase();
+            const level = stringMap[normalized];
+            if (level) {
+                return {
+                    level,
+                    label: level === 1
+                        ? 'excellent'
+                        : level === 2
+                            ? 'good'
+                            : level === 3
+                                ? 'moderate'
+                                : 'poor',
+                };
+            }
+        }
+
+        return { level: -1, label: 'unknown' };
+    }
+
     /**
      * Calculate MD5 hash
      */

package/src/lib/vesyncFan.ts

@@ -5,13 +5,18 @@
 import { VeSyncBaseDevice } from './vesyncBaseDevice';
 import { VeSync } from './vesync';
 import { logger } from './logger';
+import { Helpers } from './helpers';
+
+interface FanConfigEntry {
+    module: 'VeSyncAirBypass' | 'VeSyncHumidifier' | 'VeSyncWarmHumidifier' | 'VeSyncTowerFan' | 'VeSyncAirBaseV2' | 'VeSyncSuperior6000S' | 'VeSyncHumid1000S' | 'VeSyncHumid200S' | 'VeSyncAir131';
+    features: string[];
+    levels?: number[];
+    modes?: ReadonlyArray<string>;
+    autoPreferences?: ReadonlyArray<string>;
+}
 
 interface FanConfig {
-    [key: string]: {
-        module: 'VeSyncAirBypass' | 'VeSyncHumidifier' | 'VeSyncWarmHumidifier' | 'VeSyncTowerFan' | 'VeSyncAirBaseV2' | 'VeSyncSuperior6000S' | 'VeSyncHumid1000S' | 'VeSyncHumid200S' | 'VeSyncAir131';
-        features: string[];
-        levels?: number[];
-    };
+    [key: string]: FanConfigEntry;
 }
 
 // Fan configuration
@@ -20,159 +25,218 @@ export const fanConfig: FanConfig = {
     'Core200S': {
         module: 'VeSyncAirBypass',
         features: ['display', 'child_lock', 'night_light', 'timer', 'fan_speed', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]  // 4 levels including sleep mode, matching reference plugin
+        levels: [1, 2, 3, 4],  // 4 levels including sleep mode, matching reference plugin
+        modes: ['sleep', 'manual']
     },
     'Core300S': {
         module: 'VeSyncAirBypass',
         features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'Core400S': {
         module: 'VeSyncAirBypass',
         features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'Core600S': {
         module: 'VeSyncAirBypass',
         features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     
     // LAP Series
     'LAP-C201S-AUSR': {
         module: 'VeSyncAirBypass',
-        features: ['display', 'child_lock', 'night_light', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3]
+        features: ['display', 'child_lock', 'night_light', 'timer', 'fan_speed', 'sleep_mode', 'filter_life'],
+        levels: [1, 2, 3],
+        modes: ['sleep', 'manual']
     },
     'LAP-C202S-WUSR': {
         module: 'VeSyncAirBypass',
-        features: ['display', 'child_lock', 'night_light', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3]
+        features: ['display', 'child_lock', 'night_light', 'timer', 'fan_speed', 'sleep_mode', 'filter_life'],
+        levels: [1, 2, 3],
+        modes: ['sleep', 'manual']
     },
     'LAP-C301S-WJP': {
         module: 'VeSyncAirBypass',
         features: ['display', 'child_lock', 'night_light', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-C302S-WUSB': {
         module: 'VeSyncAirBypass',
         features: ['display', 'child_lock', 'night_light', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-C301S-WAAA': {
         module: 'VeSyncAirBypass',
         features: ['display', 'child_lock', 'night_light', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-C401S-WJP': {
         module: 'VeSyncAirBypass',
         features: ['display', 'child_lock', 'night_light', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-C401S-WUSR': {
         module: 'VeSyncAirBypass',
         features: ['display', 'child_lock', 'night_light', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-C401S-WAAA': {
         module: 'VeSyncAirBypass',
         features: ['display', 'child_lock', 'night_light', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-C601S-WUS': {
         module: 'VeSyncAirBypass',
         features: ['display', 'child_lock', 'night_light', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-C601S-WUSR': {
         module: 'VeSyncAirBypass',
         features: ['display', 'child_lock', 'night_light', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-C601S-WEU': {
         module: 'VeSyncAirBypass',
         features: ['display', 'child_lock', 'night_light', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-V102S-AASR': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'pet_mode', 'filter_life'],
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto', 'pet'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-V102S-WUS': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'pet_mode', 'filter_life'],
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto', 'pet'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-V102S-WEU': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'pet_mode', 'filter_life'],
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto', 'pet'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-V102S-AUSR': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'pet_mode', 'filter_life'],
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto', 'pet'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-V102S-WJP': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_speed', 'auto_mode', 'sleep_mode', 'pet_mode', 'filter_life'],
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto', 'pet'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-V201S-AASR': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'light_detection', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'light_detection', 'fan_speed', 'auto_mode', 'sleep_mode', 'pet_mode', 'filter_life'],
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto', 'pet'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-V201S-WJP': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'light_detection', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'light_detection', 'fan_speed', 'auto_mode', 'sleep_mode', 'pet_mode', 'filter_life'],
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto', 'pet'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-V201S-WEU': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'light_detection', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'light_detection', 'fan_speed', 'auto_mode', 'sleep_mode', 'pet_mode', 'filter_life'],
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto', 'pet'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-V201S-WUS': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'light_detection', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'light_detection', 'fan_speed', 'auto_mode', 'sleep_mode', 'pet_mode', 'filter_life'],
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto', 'pet'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-V201-AUSR': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'light_detection', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'light_detection', 'fan_speed', 'auto_mode', 'sleep_mode', 'pet_mode', 'filter_life'],
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto', 'pet'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-V201S-AUSR': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'light_detection', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'light_detection', 'fan_speed', 'auto_mode', 'sleep_mode', 'pet_mode', 'filter_life'],
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto', 'pet'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-V201S-AEUR': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'light_detection', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3, 4]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'light_detection', 'fan_speed', 'auto_mode', 'sleep_mode', 'pet_mode', 'filter_life'],
+        levels: [1, 2, 3, 4],
+        modes: ['sleep', 'manual', 'auto', 'pet'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-EL551S-AUS': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_rotate', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_rotate', 'fan_speed', 'auto_mode', 'sleep_mode', 'turbo_mode', 'light_detection', 'filter_life'],
+        levels: [1, 2, 3],
+        modes: ['sleep', 'manual', 'auto', 'turbo'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-EL551S-AEUR': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_rotate', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_rotate', 'fan_speed', 'auto_mode', 'sleep_mode', 'turbo_mode', 'light_detection', 'filter_life'],
+        levels: [1, 2, 3],
+        modes: ['sleep', 'manual', 'auto', 'turbo'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-EL551S-WEU': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_rotate', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_rotate', 'fan_speed', 'auto_mode', 'sleep_mode', 'turbo_mode', 'light_detection', 'filter_life'],
+        levels: [1, 2, 3],
+        modes: ['sleep', 'manual', 'auto', 'turbo'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     'LAP-EL551S-WUS': {
         module: 'VeSyncAirBaseV2',
-        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_rotate', 'fan_speed', 'auto_mode', 'filter_life'],
-        levels: [1, 2, 3]
+        features: ['display', 'child_lock', 'night_light', 'air_quality', 'timer', 'fan_rotate', 'fan_speed', 'auto_mode', 'sleep_mode', 'turbo_mode', 'light_detection', 'filter_life'],
+        levels: [1, 2, 3],
+        modes: ['sleep', 'manual', 'auto', 'turbo'],
+        autoPreferences: ['default', 'efficient', 'quiet']
     },
     
     // LTF Series
@@ -327,6 +391,8 @@ export abstract class VeSyncFan extends VeSyncBaseDevice {
         child_lock?: boolean;
         air_quality?: string | number;
         air_quality_value?: number;
+        air_quality_level?: number;
+        air_quality_label?: string;
         pm1?: number;
         pm10?: number;
         aq_percent?: number;
@@ -339,20 +405,29 @@ export abstract class VeSyncFan extends VeSyncBaseDevice {
     protected mode_dict: Record<string, any> = {};
     protected speed_dict: Record<string, any> = {};
     protected _timer: number | { duration: number; action: string } | null = null;
-    protected config: {
-        module: 'VeSyncAirBypass' | 'VeSyncHumidifier' | 'VeSyncWarmHumidifier' | 'VeSyncTowerFan' | 'VeSyncAirBaseV2' | 'VeSyncSuperior6000S' | 'VeSyncHumid1000S' | 'VeSyncHumid200S' | 'VeSyncAir131';
-        features: string[];
-        levels?: number[];
-    };
+    protected config: FanConfigEntry;
 
     constructor(details: Record<string, any>, manager: VeSync) {
         super(details, manager);
         this.details = details;
-        this.config = fanConfig[this.deviceType] || { 
-            module: 'VeSyncAirBypass', 
-            features: [],
-            levels: []
-        };
+        const entry = fanConfig[this.deviceType];
+        if (entry) {
+            this.config = {
+                ...entry,
+                features: [...entry.features],
+                levels: entry.levels ? [...entry.levels] : undefined,
+                modes: entry.modes ? [...entry.modes] : undefined,
+                autoPreferences: entry.autoPreferences ? [...entry.autoPreferences] : undefined
+            };
+        } else {
+            this.config = {
+                module: 'VeSyncAirBypass',
+                features: [],
+                levels: [],
+                modes: [],
+                autoPreferences: []
+            };
+        }
     }
 
     /**
@@ -362,6 +437,40 @@ export abstract class VeSyncFan extends VeSyncBaseDevice {
         return this.config.features.includes(feature);
     }
 
+    /**
+     * Get configured modes for the device, falling back to provided defaults.
+     */
+    protected getConfigModes(defaultModes: ReadonlyArray<string> = []): ReadonlyArray<string> {
+        if (Array.isArray(this.config.modes) && this.config.modes.length > 0) {
+            return this.config.modes;
+        }
+        return defaultModes;
+    }
+
+    /**
+     * Get configured auto preferences for the device, falling back to provided defaults.
+     */
+    protected getConfigAutoPreferences(defaultPreferences: ReadonlyArray<string> = []): ReadonlyArray<string> {
+        if (Array.isArray(this.config.autoPreferences) && this.config.autoPreferences.length > 0) {
+            return this.config.autoPreferences;
+        }
+        return defaultPreferences;
+    }
+
+    /**
+     * Public accessor for supported modes for consumers that need to inspect capability metadata.
+     */
+    public getSupportedModes(defaultModes: ReadonlyArray<string> = []): ReadonlyArray<string> {
+        return this.getConfigModes(defaultModes);
+    }
+
+    /**
+     * Public accessor for supported auto preference profiles.
+     */
+    public getSupportedAutoPreferences(defaultPreferences: ReadonlyArray<string> = []): ReadonlyArray<string> {
+        return this.getConfigAutoPreferences(defaultPreferences);
+    }
+
     /**
      * Check if feature is supported in current mode
      */
@@ -400,7 +509,10 @@ export abstract class VeSyncFan extends VeSyncBaseDevice {
      * Get maximum fan speed level
      */
     getMaxFanSpeed(): number {
-        return this.config.levels ? Math.max(...this.config.levels) : 3;
+        if (this.config.levels && this.config.levels.length > 0) {
+            return Math.max(...this.config.levels);
+        }
+        return 3;
     }
 
     /**
@@ -468,6 +580,23 @@ export abstract class VeSyncFan extends VeSyncBaseDevice {
         return this.details.air_quality_value ?? 0;
     }
 
+    /**
+     * Normalized air quality metadata aligned with pyvesync levels.
+     */
+    getNormalizedAirQuality(): { level: number; label: string } {
+        if (typeof this.details.air_quality_level === 'number' && this.details.air_quality_level >= 1) {
+            const label = this.details.air_quality_label ?? Helpers.normalizeAirQuality(this.details.air_quality_level).label;
+            return { level: this.details.air_quality_level, label };
+        }
+
+        const normalized = Helpers.normalizeAirQuality(this.details.air_quality);
+        if (normalized.level >= 1) {
+            this.details.air_quality_level = normalized.level;
+            this.details.air_quality_label = normalized.label;
+        }
+        return normalized;
+    }
+
     /**
      * Get PM1 value (if supported)
      */