import * as plugins from '../../plugins.js';
import type { IIntegrationEntity, IIntegrationEvent, IServiceCallRequest, TEntityPlatform } from '../../core/types.js';
import type {
  IWizButtonRecord,
  IWizClientCommand,
  IWizConfig,
  IWizDeviceFeatures,
  IWizDeviceInfo,
  IWizEntityRecord,
  IWizEvent,
  IWizManualEntry,
  IWizPilotPatch,
  IWizPilotState,
  IWizSensorRecord,
  IWizSnapshot,
  IWizSnapshotDevice,
} from './wiz.types.js';
import { wizDefaultPort } from './wiz.types.js';

const wizScenes: Array<{ id: number; name: string }> = [
  { id: 35, name: 'Alarm' },
  { id: 10, name: 'Bedtime' },
  { id: 29, name: 'Candlelight' },
  { id: 27, name: 'Christmas' },
  { id: 6, name: 'Cozy' },
  { id: 13, name: 'Cool white' },
  { id: 26, name: 'Club' },
  { id: 12, name: 'Daylight' },
  { id: 33, name: 'Diwali' },
  { id: 23, name: 'Deep dive' },
  { id: 22, name: 'Fall' },
  { id: 5, name: 'Fireplace' },
  { id: 7, name: 'Forest' },
  { id: 15, name: 'Focus' },
  { id: 30, name: 'Golden white' },
  { id: 28, name: 'Halloween' },
  { id: 24, name: 'Jungle' },
  { id: 25, name: 'Mojito' },
  { id: 14, name: 'Night light' },
  { id: 1, name: 'Ocean' },
  { id: 4, name: 'Party' },
  { id: 31, name: 'Pulse' },
  { id: 8, name: 'Pastel colors' },
  { id: 19, name: 'Plantgrowth' },
  { id: 2, name: 'Romance' },
  { id: 16, name: 'Relax' },
  { id: 36, name: 'Snowy sky' },
  { id: 3, name: 'Sunset' },
  { id: 20, name: 'Spring' },
  { id: 21, name: 'Summer' },
  { id: 32, name: 'Steampunk' },
  { id: 17, name: 'True colors' },
  { id: 18, name: 'TV time' },
  { id: 34, name: 'White' },
  { id: 9, name: 'Wake-up' },
  { id: 11, name: 'Warm white' },
  { id: 1000, name: 'Rhythm' },
];

const wizSceneNamesById = new Map(wizScenes.map((sceneArg) => [sceneArg.id, sceneArg.name]));
const wizSceneIdsByName = new Map(wizScenes.map((sceneArg) => [sceneArg.name.toLowerCase(), sceneArg.id]));

const wizButtonSources: Record<string, string> = {
  wfa1: 'on',
  wfa2: 'off',
  wfa3: 'night',
  wfa8: 'decrease_brightness',
  wfa9: 'increase_brightness',
  wfa16: '1',
  wfa17: '2',
  wfa18: '3',
  wfa19: '4',
};

const pilotPatchKeys = new Set(['state', 'sceneId', 'temp', 'dimming', 'r', 'g', 'b', 'c', 'w', 'speed', 'ratio', 'fanState', 'fanMode', 'fanSpeed', 'fanRevrs']);

export class WizMapper {
  public static readonly sceneNames = wizScenes.map((sceneArg) => sceneArg.name);

  public static toSnapshot(configArg: IWizConfig, connectedArg?: boolean, eventsArg: IWizEvent[] = []): IWizSnapshot {
    const source = configArg.snapshot;
    const devices: IWizSnapshotDevice[] = [
      ...(source?.devices || []),
      ...(configArg.devices || []),
    ];

    for (const entry of configArg.manualEntries || []) {
      if (entry.snapshot) {
        devices.push(...entry.snapshot.devices);
      } else {
        devices.push(this.deviceFromManualEntry(entry));
      }
    }

    if (!devices.length && (configArg.host || configArg.mac || configArg.name || configArg.deviceInfo || configArg.pilot)) {
      devices.push({
        host: configArg.host,
        port: configArg.port || wizDefaultPort,
        mac: configArg.mac || configArg.deviceInfo?.mac || configArg.pilot?.mac,
        name: configArg.name || configArg.deviceInfo?.name,
        deviceInfo: configArg.deviceInfo,
        pilot: configArg.pilot,
        available: connectedArg ?? Boolean(configArg.pilot || source?.connected),
      });
    }

    return {
      connected: connectedArg ?? source?.connected ?? false,
      host: configArg.host || source?.host,
      port: configArg.port || source?.port || wizDefaultPort,
      devices,
      events: [...(source?.events || []), ...(configArg.events || []), ...eventsArg],
    };
  }

  public static toDevices(snapshotArg: IWizSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
    const updatedAt = new Date().toISOString();
    return snapshotArg.devices.map((deviceArg) => this.toDevice(deviceArg, updatedAt));
  }

  public static toEntities(snapshotArg: IWizSnapshot): IIntegrationEntity[] {
    const entities: IIntegrationEntity[] = [];
    const usedIds = new Map<string, number>();

    for (const device of snapshotArg.devices) {
      const info = this.deviceInfo(device);
      const pilot = device.pilot || {};
      const features = this.features(device);
      const deviceId = this.deviceId(device);
      const baseName = this.deviceName(device);
      const isSocket = this.isSocket(device);
      const hasLight = !isSocket && features.light !== false;

      if (hasLight) {
        entities.push(this.entity('light', baseName, deviceId, this.uniqueId('light', device), pilot.state ? 'on' : 'off', usedIds, {
          ...this.baseAttributes(device),
          brightness: pilot.dimming,
          brightness255: this.percentToByte(pilot.dimming),
          colorTemperatureKelvin: pilot.temp,
          rgbColor: this.rgb(pilot),
          sceneId: this.sceneId(pilot),
          effect: this.sceneName(pilot),
          effectList: this.sceneNames,
          writable: true,
        }, device.available !== false));
      }

      if (isSocket || features.switch) {
        entities.push(this.entity('switch', baseName, deviceId, this.uniqueId('switch', device), pilot.state ? 'on' : 'off', usedIds, {
          ...this.baseAttributes(device),
          writable: true,
        }, device.available !== false));
      }

      if (features.fan || pilot.fanState !== undefined) {
        entities.push(this.entity('fan', `${baseName} Fan`, deviceId, this.uniqueId('fan', device), pilot.fanState ? 'on' : 'off', usedIds, {
          ...this.baseAttributes(device),
          percentage: this.fanPercentage(device, pilot),
          fanMode: pilot.fanMode,
          fanSpeed: pilot.fanSpeed,
          fanReverse: pilot.fanRevrs,
          writable: true,
        }, device.available !== false));
      }

      if (typeof pilot.rssi === 'number') {
        entities.push(this.sensorEntity(device, { key: 'rssi', name: `${baseName} RSSI`, value: pilot.rssi, unit: 'dBm', deviceClass: 'signal_strength' }, usedIds));
      }
      if (typeof pilot.pc === 'number' || features.power) {
        entities.push(this.sensorEntity(device, { key: 'power', name: `${baseName} Power`, value: typeof pilot.pc === 'number' ? pilot.pc / 1000 : undefined, unit: 'W', deviceClass: 'power' }, usedIds));
      }
      if (features.occupancy || pilot.src === 'pir') {
        entities.push(this.sensorEntity(device, { key: 'occupancy', name: `${baseName} Occupancy`, platform: 'binary_sensor', value: pilot.src === 'pir' ? pilot.state : undefined, deviceClass: 'occupancy' }, usedIds));
      }

      for (const sensor of device.sensors || []) {
        entities.push(this.sensorEntity(device, sensor, usedIds));
      }

      if (features.effect || pilot.speed !== undefined) {
        entities.push(this.numberEntity(device, 'effect_speed', `${baseName} Effect Speed`, pilot.speed, usedIds, { min: 10, max: 200, step: 1, wizPilotKey: 'speed' }));
      }
      if (features.dualHead || pilot.ratio !== undefined) {
        entities.push(this.numberEntity(device, 'dual_head_ratio', `${baseName} Dual Head Ratio`, pilot.ratio, usedIds, { min: 0, max: 100, step: 1, wizPilotKey: 'ratio' }));
      }
      if (features.effect || this.sceneId(pilot) !== undefined) {
        entities.push(this.entity('select', `${baseName} Effect`, deviceId, `${this.uniqueId('select', device)}_effect`, this.sceneName(pilot) || 'None', usedIds, {
          ...this.baseAttributes(device),
          options: this.sceneNames,
          wizPilotKey: 'sceneId',
          writable: true,
        }, device.available !== false));
      }

      for (const button of this.buttons(device)) {
        entities.push(this.buttonEntity(device, button, usedIds));
      }

      for (const entity of device.entities || []) {
        entities.push(this.explicitEntity(device, entity, usedIds));
      }
    }

    return entities;
  }

  public static toIntegrationEvent(eventArg: IWizEvent): IIntegrationEvent {
    return {
      type: eventArg.type === 'command_failed' || eventArg.type === 'error' ? 'error' : 'state_changed',
      integrationDomain: 'wiz',
      deviceId: eventArg.deviceId,
      entityId: eventArg.entityId,
      data: eventArg,
      timestamp: eventArg.timestamp || Date.now(),
    };
  }

  public static commandForService(snapshotArg: IWizSnapshot, requestArg: IServiceCallRequest): IWizClientCommand | undefined {
    if (requestArg.domain === 'wiz' && requestArg.service === 'set_pilot' && this.isRecord(requestArg.data?.payload)) {
      const targetEntity = this.findTargetEntity(snapshotArg, requestArg);
      return {
        type: 'setPilot',
        service: requestArg.service,
        deviceId: targetEntity?.deviceId || requestArg.target.deviceId,
        entityId: targetEntity?.id || requestArg.target.entityId,
        payload: requestArg.data.payload as IWizPilotPatch,
        target: requestArg.target,
      };
    }

    const target = this.findTargetEntity(snapshotArg, requestArg);
    if (!target) {
      return undefined;
    }
    const device = snapshotArg.devices.find((deviceArg) => this.deviceId(deviceArg) === target.deviceId);
    const payload = this.payloadForService(target, requestArg, device);
    if (!payload || !Object.keys(payload).length) {
      return undefined;
    }
    return {
      type: 'setPilot',
      service: requestArg.service,
      deviceId: target.deviceId,
      entityId: target.id,
      payload,
      target: requestArg.target,
    };
  }

  public static sceneIdFromName(valueArg: string): number | undefined {
    return wizSceneIdsByName.get(valueArg.toLowerCase());
  }

  private static toDevice(deviceArg: IWizSnapshotDevice, updatedAtArg: string): plugins.shxInterfaces.data.IDeviceDefinition {
    const info = this.deviceInfo(deviceArg);
    const pilot = deviceArg.pilot || {};
    const featuresInfo = this.features(deviceArg);
    const features: plugins.shxInterfaces.data.IDeviceFeature[] = [
      { id: 'availability', capability: 'sensor', name: 'Availability', readable: true, writable: false },
    ];
    const state: plugins.shxInterfaces.data.IDeviceState[] = [
      { featureId: 'availability', value: deviceArg.available === false ? 'offline' : 'online', updatedAt: updatedAtArg },
    ];
    const isSocket = this.isSocket(deviceArg);
    const hasLight = !isSocket && featuresInfo.light !== false;

    if (hasLight) {
      features.push({ id: 'on', capability: 'light', name: 'Power', readable: true, writable: true });
      this.pushDeviceState(state, 'on', pilot.state ?? false, updatedAtArg);
      if (featuresInfo.brightness !== false || typeof pilot.dimming === 'number') {
        features.push({ id: 'brightness', capability: 'light', name: 'Brightness', readable: true, writable: true, unit: '%' });
        this.pushDeviceState(state, 'brightness', pilot.dimming, updatedAtArg);
      }
      if (featuresInfo.colorTemp || typeof pilot.temp === 'number') {
        features.push({ id: 'color_temperature', capability: 'light', name: 'Color Temperature', readable: true, writable: true, unit: 'K' });
        this.pushDeviceState(state, 'color_temperature', pilot.temp, updatedAtArg);
      }
      if (featuresInfo.color || this.rgb(pilot)) {
        features.push({ id: 'rgb', capability: 'light', name: 'RGB Color', readable: true, writable: true });
        this.pushDeviceState(state, 'rgb', this.rgbRecord(pilot), updatedAtArg);
      }
      if (featuresInfo.effect || this.sceneId(pilot) !== undefined) {
        features.push({ id: 'effect', capability: 'light', name: 'Effect', readable: true, writable: true });
        this.pushDeviceState(state, 'effect', this.sceneName(pilot) || null, updatedAtArg);
      }
    }

    if (isSocket || featuresInfo.switch) {
      features.push({ id: 'switch', capability: 'switch', name: 'Power', readable: true, writable: true });
      this.pushDeviceState(state, 'switch', pilot.state ?? false, updatedAtArg);
    }

    if (featuresInfo.fan || pilot.fanState !== undefined) {
      features.push({ id: 'fan', capability: 'fan', name: 'Fan', readable: true, writable: true });
      this.pushDeviceState(state, 'fan', Boolean(pilot.fanState), updatedAtArg);
      features.push({ id: 'fan_speed', capability: 'fan', name: 'Fan Speed', readable: true, writable: true, unit: '%' });
      this.pushDeviceState(state, 'fan_speed', this.fanPercentage(deviceArg, pilot), updatedAtArg);
    }

    if (typeof pilot.rssi === 'number') {
      features.push({ id: 'rssi', capability: 'sensor', name: 'RSSI', readable: true, writable: false, unit: 'dBm' });
      this.pushDeviceState(state, 'rssi', pilot.rssi, updatedAtArg);
    }
    if (typeof pilot.pc === 'number' || featuresInfo.power) {
      features.push({ id: 'power', capability: 'energy', name: 'Power', readable: true, writable: false, unit: 'W' });
      this.pushDeviceState(state, 'power', typeof pilot.pc === 'number' ? pilot.pc / 1000 : undefined, updatedAtArg);
    }
    if (featuresInfo.occupancy || pilot.src === 'pir') {
      features.push({ id: 'occupancy', capability: 'sensor', name: 'Occupancy', readable: true, writable: false });
      this.pushDeviceState(state, 'occupancy', pilot.src === 'pir' ? Boolean(pilot.state) : undefined, updatedAtArg);
    }

    for (const sensor of deviceArg.sensors || []) {
      features.push({ id: sensor.key, capability: 'sensor', name: sensor.name || this.title(sensor.key), readable: true, writable: Boolean(sensor.writable), unit: sensor.unit });
      this.pushDeviceState(state, sensor.key, this.deviceStateValue(sensor.value), updatedAtArg);
    }
    for (const button of this.buttons(deviceArg)) {
      features.push({ id: `button_${button.key}`, capability: 'switch', name: button.name || this.title(button.key), readable: true, writable: true });
      this.pushDeviceState(state, `button_${button.key}`, String(button.value ?? button.lastPressedAt ?? 'idle'), updatedAtArg);
    }

    return {
      id: this.deviceId(deviceArg),
      integrationDomain: 'wiz',
      name: this.deviceName(deviceArg),
      protocol: 'unknown',
      manufacturer: info.manufacturer || 'WiZ',
      model: info.model || info.moduleName || String(info.bulbType || 'WiZ device'),
      online: deviceArg.available !== false,
      features,
      state,
      metadata: {
        ...deviceArg.metadata,
        protocol: 'wiz-udp-json',
        host: deviceArg.host || info.host,
        port: deviceArg.port || info.port || wizDefaultPort,
        mac: this.mac(deviceArg),
        moduleName: info.moduleName,
        fwVersion: info.fwVersion,
        typeId: info.typeId,
        features: featuresInfo,
      },
    };
  }

  private static payloadForService(entityArg: IIntegrationEntity, requestArg: IServiceCallRequest, deviceArg?: IWizSnapshotDevice): IWizPilotPatch | undefined {
    if (requestArg.service === 'turn_off') {
      return entityArg.platform === 'fan' || requestArg.domain === 'fan' ? { fanState: 0 } : { state: false };
    }
    if (requestArg.service === 'turn_on') {
      const payload: IWizPilotPatch = entityArg.platform === 'fan' || requestArg.domain === 'fan' ? { fanState: 1 } : { state: true };
      this.applyServiceData(payload, requestArg, entityArg, deviceArg);
      return payload;
    }
    if (requestArg.service === 'set_percentage' || requestArg.service === 'set_brightness') {
      const percentage = this.percentageFromData(requestArg.data, requestArg.service);
      if (percentage === undefined) {
        return undefined;
      }
      if (entityArg.platform === 'fan' || requestArg.domain === 'fan') {
        return percentage <= 0 ? { fanState: 0 } : { fanState: 1, fanSpeed: this.percentageToFanSpeed(deviceArg, percentage) };
      }
      return percentage <= 0 ? { state: false } : { state: true, dimming: this.clamp(Math.round(percentage), 10, 100) };
    }
    if (requestArg.service === 'set_value') {
      return this.setValuePayload(entityArg, requestArg);
    }
    if (requestArg.service === 'select_option' || requestArg.service === 'select_effect') {
      const option = this.stringFromData(requestArg.data, ['option', 'effect', 'value']);
      const sceneId = typeof option === 'string' ? this.sceneIdFromName(option) : undefined;
      return sceneId === undefined ? undefined : { state: true, sceneId };
    }
    if (requestArg.domain === 'fan') {
      if (requestArg.service === 'set_direction') {
        const direction = this.stringFromData(requestArg.data, ['direction']);
        return direction ? { fanRevrs: direction === 'reverse' ? 1 : 0 } : undefined;
      }
      if (requestArg.service === 'set_preset_mode') {
        const presetMode = this.stringFromData(requestArg.data, ['preset_mode', 'presetMode']);
        return presetMode === 'breeze' ? { fanMode: 2 } : undefined;
      }
    }
    return undefined;
  }

  private static applyServiceData(payloadArg: IWizPilotPatch, requestArg: IServiceCallRequest, entityArg: IIntegrationEntity, deviceArg?: IWizSnapshotDevice): void {
    const brightness = this.percentageFromData(requestArg.data, 'turn_on');
    if (brightness !== undefined && entityArg.platform !== 'fan' && requestArg.domain !== 'fan') {
      payloadArg.dimming = this.clamp(Math.round(brightness), 10, 100);
    }
    if (brightness !== undefined && (entityArg.platform === 'fan' || requestArg.domain === 'fan')) {
      payloadArg.fanSpeed = this.percentageToFanSpeed(deviceArg, brightness);
    }
    const kelvin = this.kelvinFromData(requestArg.data);
    if (kelvin !== undefined) {
      payloadArg.temp = kelvin;
    }
    const rgb = this.rgbFromData(requestArg.data, 'rgb_color') || this.rgbFromData(requestArg.data, 'rgb');
    if (rgb) {
      payloadArg.r = rgb[0];
      payloadArg.g = rgb[1];
      payloadArg.b = rgb[2];
    }
    const rgbw = this.rgbFromData(requestArg.data, 'rgbw_color');
    if (rgbw) {
      payloadArg.r = rgbw[0];
      payloadArg.g = rgbw[1];
      payloadArg.b = rgbw[2];
      payloadArg.w = rgbw[3];
    }
    const rgbww = this.rgbFromData(requestArg.data, 'rgbww_color');
    if (rgbww) {
      payloadArg.r = rgbww[0];
      payloadArg.g = rgbww[1];
      payloadArg.b = rgbww[2];
      payloadArg.c = rgbww[3];
      payloadArg.w = rgbww[4];
    }
    const effect = this.stringFromData(requestArg.data, ['effect', 'option']);
    const sceneId = effect ? this.sceneIdFromName(effect) : this.numberFromData(requestArg.data, ['sceneId', 'scene_id']);
    if (sceneId !== undefined) {
      payloadArg.sceneId = sceneId;
    }
    const speed = this.numberFromData(requestArg.data, ['speed']);
    if (speed !== undefined) {
      payloadArg.speed = this.clamp(Math.round(speed), 10, 200);
    }
  }

  private static setValuePayload(entityArg: IIntegrationEntity, requestArg: IServiceCallRequest): IWizPilotPatch | undefined {
    const value = this.valueFromData(requestArg.data, ['value', 'state']);
    const field = this.stringFromData(requestArg.data, ['field', 'attribute', 'key']) || (typeof entityArg.attributes?.wizPilotKey === 'string' ? entityArg.attributes.wizPilotKey : undefined);
    if (value === undefined || !field || !pilotPatchKeys.has(field)) {
      return undefined;
    }
    if (field === 'speed') {
      return typeof value === 'number' ? { speed: this.clamp(Math.round(value), 10, 200) } : undefined;
    }
    if (field === 'ratio') {
      return typeof value === 'number' ? { ratio: this.clamp(Math.round(value), 0, 100) } : undefined;
    }
    if (field === 'sceneId' && typeof value === 'string') {
      const sceneId = this.sceneIdFromName(value);
      return sceneId === undefined ? undefined : { state: true, sceneId };
    }
    return { [field]: value } as IWizPilotPatch;
  }

  private static findTargetEntity(snapshotArg: IWizSnapshot, requestArg: IServiceCallRequest): IIntegrationEntity | undefined {
    const entities = this.toEntities(snapshotArg);
    if (requestArg.target.entityId) {
      return entities.find((entityArg) => entityArg.id === requestArg.target.entityId || entityArg.uniqueId === requestArg.target.entityId);
    }
    if (requestArg.target.deviceId) {
      return entities.find((entityArg) => entityArg.deviceId === requestArg.target.deviceId && entityArg.platform === requestArg.domain)
        || entities.find((entityArg) => entityArg.deviceId === requestArg.target.deviceId && Boolean(entityArg.attributes?.writable))
        || entities.find((entityArg) => entityArg.deviceId === requestArg.target.deviceId);
    }
    return entities.find((entityArg) => entityArg.platform === requestArg.domain && Boolean(entityArg.attributes?.writable));
  }

  private static deviceFromManualEntry(entryArg: IWizManualEntry): IWizSnapshotDevice {
    return {
      id: entryArg.id,
      host: entryArg.host,
      port: entryArg.port || wizDefaultPort,
      mac: entryArg.mac || entryArg.macAddress || entryArg.deviceInfo?.mac,
      name: entryArg.name || entryArg.deviceInfo?.name,
      deviceInfo: {
        ...entryArg.deviceInfo,
        host: entryArg.host,
        port: entryArg.port || wizDefaultPort,
        mac: entryArg.mac || entryArg.macAddress || entryArg.deviceInfo?.mac,
        name: entryArg.name || entryArg.deviceInfo?.name,
        manufacturer: entryArg.manufacturer || entryArg.deviceInfo?.manufacturer,
        model: entryArg.model || entryArg.deviceInfo?.model,
      },
      pilot: entryArg.pilot,
      available: Boolean(entryArg.pilot),
      metadata: entryArg.metadata,
    };
  }

  private static explicitEntity(deviceArg: IWizSnapshotDevice, entityArg: IWizEntityRecord, usedIdsArg: Map<string, number>): IIntegrationEntity {
    const platform = this.corePlatform(entityArg.platform);
    const name = entityArg.name || this.deviceName(deviceArg);
    return this.entity(platform, name, this.deviceId(deviceArg), entityArg.uniqueId || `${this.uniqueId(platform, deviceArg)}_${entityArg.key || this.slug(name)}`, this.entityState(entityArg.state, platform), usedIdsArg, {
      ...this.baseAttributes(deviceArg),
      ...entityArg.attributes,
      wizPilotKey: entityArg.key,
      writable: entityArg.writable,
    }, entityArg.available !== false && deviceArg.available !== false, entityArg.entityId);
  }

  private static sensorEntity(deviceArg: IWizSnapshotDevice, sensorArg: IWizSensorRecord, usedIdsArg: Map<string, number>): IIntegrationEntity {
    const platform = sensorArg.platform || 'sensor';
    const state = platform === 'binary_sensor' ? sensorArg.value ? 'on' : 'off' : sensorArg.value ?? 'unknown';
    return this.entity(platform, sensorArg.name || `${this.deviceName(deviceArg)} ${this.title(sensorArg.key)}`, this.deviceId(deviceArg), `${this.uniqueId(platform, deviceArg)}_${this.slug(sensorArg.key)}`, state, usedIdsArg, {
      ...this.baseAttributes(deviceArg),
      wizSensorKey: sensorArg.key,
      wizPilotKey: sensorArg.writable ? sensorArg.key : undefined,
      deviceClass: sensorArg.deviceClass,
      unit: sensorArg.unit,
      writable: sensorArg.writable,
    }, sensorArg.available !== false && deviceArg.available !== false);
  }

  private static numberEntity(deviceArg: IWizSnapshotDevice, keyArg: string, nameArg: string, valueArg: unknown, usedIdsArg: Map<string, number>, attributesArg: Record<string, unknown>): IIntegrationEntity {
    return this.entity('number', nameArg, this.deviceId(deviceArg), `${this.uniqueId('number', deviceArg)}_${this.slug(keyArg)}`, valueArg ?? 'unknown', usedIdsArg, {
      ...this.baseAttributes(deviceArg),
      ...attributesArg,
      writable: true,
    }, deviceArg.available !== false);
  }

  private static buttonEntity(deviceArg: IWizSnapshotDevice, buttonArg: IWizButtonRecord, usedIdsArg: Map<string, number>): IIntegrationEntity {
    const name = buttonArg.name || `${this.deviceName(deviceArg)} ${this.title(buttonArg.key)}`;
    return this.entity('button', name, this.deviceId(deviceArg), `${this.uniqueId('button', deviceArg)}_${this.slug(buttonArg.key)}`, buttonArg.value ?? 'idle', usedIdsArg, {
      ...this.baseAttributes(deviceArg),
      wizButtonKey: buttonArg.key,
      lastPressedAt: buttonArg.lastPressedAt,
      writable: true,
    }, buttonArg.available !== false && deviceArg.available !== false);
  }

  private static entity(platformArg: TEntityPlatform, nameArg: string, deviceIdArg: string, uniqueIdArg: string, stateArg: unknown, usedIdsArg: Map<string, number>, attributesArg: Record<string, unknown>, availableArg: boolean, explicitEntityIdArg?: string): IIntegrationEntity {
    return {
      id: explicitEntityIdArg || this.entityId(platformArg, nameArg, usedIdsArg),
      uniqueId: uniqueIdArg,
      integrationDomain: 'wiz',
      deviceId: deviceIdArg,
      platform: platformArg,
      name: nameArg,
      state: stateArg,
      attributes: attributesArg,
      available: availableArg,
    };
  }

  private static buttons(deviceArg: IWizSnapshotDevice): IWizButtonRecord[] {
    const buttons = [...(deviceArg.buttons || [])];
    const source = typeof deviceArg.pilot?.src === 'string' ? deviceArg.pilot.src : undefined;
    if (source && wizButtonSources[source]) {
      buttons.push({ key: wizButtonSources[source], name: `${this.deviceName(deviceArg)} Button ${this.title(wizButtonSources[source])}`, value: source });
    }
    return buttons;
  }

  private static deviceInfo(deviceArg: IWizSnapshotDevice): IWizDeviceInfo {
    return {
      ...deviceArg.deviceInfo,
      id: deviceArg.deviceInfo?.id || deviceArg.id,
      host: deviceArg.host || deviceArg.deviceInfo?.host,
      port: deviceArg.port || deviceArg.deviceInfo?.port || wizDefaultPort,
      mac: deviceArg.mac || deviceArg.deviceInfo?.mac || deviceArg.pilot?.mac,
      name: deviceArg.name || deviceArg.deviceInfo?.name,
    };
  }

  private static features(deviceArg: IWizSnapshotDevice): IWizDeviceFeatures {
    const info = this.deviceInfo(deviceArg);
    const pilot = deviceArg.pilot || {};
    const lowerType = String(info.bulbType || info.model || info.moduleName || '').toLowerCase();
    const isSocket = this.isSocket(deviceArg);
    return {
      light: !isSocket,
      switch: isSocket,
      brightness: typeof pilot.dimming === 'number' || !isSocket,
      color: ['r', 'g', 'b'].every((keyArg) => typeof pilot[keyArg] === 'number') || lowerType.includes('rgb'),
      colorTemp: typeof pilot.temp === 'number' || lowerType.includes('tw') || lowerType.includes('tunable'),
      effect: typeof pilot.sceneId === 'number' || typeof pilot.schdPsetId === 'number' || info.features?.effect,
      fan: typeof pilot.fanState === 'number' || info.features?.fan,
      power: typeof pilot.pc === 'number' || info.powerMonitoring || info.features?.power,
      occupancy: pilot.src === 'pir' || info.features?.occupancy,
      button: Boolean(deviceArg.buttons?.length) || Boolean(pilot.src && wizButtonSources[String(pilot.src)]) || info.features?.button,
      dualHead: typeof pilot.ratio === 'number' || info.features?.dualHead,
      ...info.features,
    };
  }

  private static isSocket(deviceArg: IWizSnapshotDevice): boolean {
    const info = this.deviceInfo(deviceArg);
    const text = [info.bulbType, info.model, info.moduleName, info.typeId].filter((valueArg) => valueArg !== undefined).join(' ').toLowerCase();
    return info.isSocket === true || info.features?.switch === true || text.includes('socket') || text.includes('plug');
  }

  private static deviceId(deviceArg: IWizSnapshotDevice): string {
    return `wiz.device.${this.slug(deviceArg.id || this.mac(deviceArg) || deviceArg.host || this.deviceName(deviceArg))}`;
  }

  private static uniqueId(platformArg: string, deviceArg: IWizSnapshotDevice): string {
    return `wiz_${platformArg}_${this.slug(this.mac(deviceArg) || deviceArg.id || deviceArg.host || this.deviceName(deviceArg))}`;
  }

  private static deviceName(deviceArg: IWizSnapshotDevice): string {
    const info = this.deviceInfo(deviceArg);
    return info.name || deviceArg.name || (this.mac(deviceArg) ? `WiZ ${this.shortMac(this.mac(deviceArg))}` : 'WiZ device');
  }

  private static mac(deviceArg: IWizSnapshotDevice): string | undefined {
    return this.normalizeMac(deviceArg.mac || deviceArg.deviceInfo?.mac || deviceArg.pilot?.mac);
  }

  private static baseAttributes(deviceArg: IWizSnapshotDevice): Record<string, unknown> {
    const info = this.deviceInfo(deviceArg);
    return {
      wizDeviceId: this.deviceId(deviceArg),
      wizHost: info.host,
      wizPort: info.port || wizDefaultPort,
      wizMac: this.mac(deviceArg),
      moduleName: info.moduleName,
      fwVersion: info.fwVersion,
      model: info.model,
    };
  }

  private static sceneId(pilotArg: IWizPilotState): number | undefined {
    if (typeof pilotArg.schdPsetId === 'number') {
      return 1000;
    }
    return typeof pilotArg.sceneId === 'number' && pilotArg.sceneId > 0 ? pilotArg.sceneId : undefined;
  }

  private static sceneName(pilotArg: IWizPilotState): string | undefined {
    const sceneId = this.sceneId(pilotArg);
    return sceneId === undefined ? undefined : wizSceneNamesById.get(sceneId) || `Scene ${sceneId}`;
  }

  private static fanPercentage(deviceArg: IWizSnapshotDevice, pilotArg: IWizPilotState): number | undefined {
    if (typeof pilotArg.fanSpeed !== 'number') {
      return undefined;
    }
    const max = this.deviceInfo(deviceArg).fanSpeedRange || 6;
    return this.clamp(Math.round(pilotArg.fanSpeed / max * 100), 0, 100);
  }

  private static percentageToFanSpeed(deviceArg: IWizSnapshotDevice | undefined, percentageArg: number): number {
    const max = deviceArg ? this.deviceInfo(deviceArg).fanSpeedRange || 6 : 6;
    return this.clamp(Math.ceil(this.clamp(percentageArg, 0, 100) / 100 * max), 1, max);
  }

  private static percentToByte(valueArg: unknown): number | undefined {
    return typeof valueArg === 'number' ? this.clamp(Math.round(valueArg / 100 * 255), 0, 255) : undefined;
  }

  private static percentageFromData(dataArg: Record<string, unknown> | undefined, serviceArg: string): number | undefined {
    const pct = this.numberFromData(dataArg, ['percentage', 'brightness_pct']);
    if (pct !== undefined) {
      return this.clamp(pct, 0, 100);
    }
    const brightness = this.numberFromData(dataArg, serviceArg === 'set_brightness' ? ['brightness', 'value'] : ['brightness']);
    return brightness === undefined ? undefined : this.clamp(Math.round(brightness / 255 * 100), 0, 100);
  }

  private static kelvinFromData(dataArg: Record<string, unknown> | undefined): number | undefined {
    const direct = this.numberFromData(dataArg, ['color_temp_kelvin', 'kelvin', 'temp', 'color_temperature']);
    if (direct !== undefined) {
      return Math.round(direct);
    }
    const mired = this.numberFromData(dataArg, ['color_temp', 'color_temp_mired']);
    return mired && mired > 0 ? Math.round(1000000 / mired) : undefined;
  }

  private static rgb(pilotArg: IWizPilotState): number[] | undefined {
    return typeof pilotArg.r === 'number' && typeof pilotArg.g === 'number' && typeof pilotArg.b === 'number'
      ? [pilotArg.r, pilotArg.g, pilotArg.b]
      : undefined;
  }

  private static rgbRecord(pilotArg: IWizPilotState): Record<string, unknown> | undefined {
    const rgb = this.rgb(pilotArg);
    return rgb ? { r: rgb[0], g: rgb[1], b: rgb[2], c: pilotArg.c, w: pilotArg.w } : undefined;
  }

  private static rgbFromData(dataArg: Record<string, unknown> | undefined, keyArg: string): number[] | undefined {
    const value = dataArg?.[keyArg];
    if (!Array.isArray(value) || value.length < 3) {
      return undefined;
    }
    const numbers = value.map((valueArg) => typeof valueArg === 'number' && Number.isFinite(valueArg) ? this.clamp(Math.round(valueArg), 0, 255) : undefined);
    return numbers.every((valueArg) => valueArg !== undefined) ? numbers as number[] : undefined;
  }

  private static valueFromData(dataArg: Record<string, unknown> | undefined, keysArg: string[]): unknown {
    for (const key of keysArg) {
      if (dataArg && key in dataArg) {
        return dataArg[key];
      }
    }
    return undefined;
  }

  private static numberFromData(dataArg: Record<string, unknown> | undefined, keysArg: string[]): number | undefined {
    const value = this.valueFromData(dataArg, keysArg);
    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
  }

  private static stringFromData(dataArg: Record<string, unknown> | undefined, keysArg: string[]): string | undefined {
    const value = this.valueFromData(dataArg, keysArg);
    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
  }

  private static corePlatform(platformArg: TEntityPlatform | string): TEntityPlatform {
    const platform = platformArg.toLowerCase();
    const allowed: TEntityPlatform[] = ['light', 'switch', 'sensor', 'binary_sensor', 'button', 'climate', 'cover', 'fan', 'media_player', 'number', 'select', 'text', 'update'];
    return allowed.includes(platform as TEntityPlatform) ? platform as TEntityPlatform : 'sensor';
  }

  private static entityState(valueArg: unknown, platformArg: TEntityPlatform): unknown {
    if (platformArg === 'light' || platformArg === 'switch' || platformArg === 'fan' || platformArg === 'binary_sensor') {
      return typeof valueArg === 'boolean' ? valueArg ? 'on' : 'off' : valueArg ?? 'unknown';
    }
    return valueArg ?? 'unknown';
  }

  private static pushDeviceState(stateArg: plugins.shxInterfaces.data.IDeviceState[], featureIdArg: string, valueArg: unknown, updatedAtArg: string): void {
    if (valueArg === undefined) {
      return;
    }
    stateArg.push({ featureId: featureIdArg, value: this.deviceStateValue(valueArg), updatedAt: updatedAtArg });
  }

  private static deviceStateValue(valueArg: unknown): plugins.shxInterfaces.data.TDeviceStateValue {
    if (typeof valueArg === 'string' || typeof valueArg === 'number' || typeof valueArg === 'boolean' || valueArg === null || this.isRecord(valueArg)) {
      return valueArg;
    }
    return valueArg === undefined ? null : String(valueArg);
  }

  private static entityId(platformArg: TEntityPlatform, nameArg: string, usedIdsArg: Map<string, number>): string {
    const base = `${platformArg}.${this.slug(nameArg)}`;
    const count = usedIdsArg.get(base) || 0;
    usedIdsArg.set(base, count + 1);
    return count ? `${base}_${count + 1}` : base;
  }

  private static shortMac(valueArg?: string): string {
    return (valueArg || '').replace(/[^a-fA-F0-9]/g, '').slice(-6).toUpperCase();
  }

  private static normalizeMac(valueArg?: string): string | undefined {
    if (!valueArg) {
      return undefined;
    }
    const compact = valueArg.replace(/[^a-fA-F0-9]/g, '').toLowerCase();
    return compact.length === 12 ? compact.match(/.{1,2}/g)?.join(':') : valueArg.toLowerCase();
  }

  private static title(valueArg: string): string {
    return valueArg.replace(/_/g, ' ').replace(/\b\w/g, (matchArg) => matchArg.toUpperCase());
  }

  private static slug(valueArg: string): string {
    return valueArg.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'wiz';
  }

  private static clamp(valueArg: number, minArg: number, maxArg: number): number {
    return Math.max(minArg, Math.min(maxArg, valueArg));
  }

  private static isRecord(valueArg: unknown): valueArg is Record<string, unknown> {
    return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
  }
}
