@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/wiz/wiz.classes.client.ts

@@ -1,278 +1,108 @@
-import type {
-  IWizClientCommand,
-  IWizCommandResult,
-  IWizConfig,
-  IWizDeviceInfo,
-  IWizEvent,
-  IWizPilotPatch,
-  IWizPilotState,
-  IWizSnapshot,
-  IWizSnapshotDevice,
-  IWizUdpCommand,
-  IWizUdpResponse,
-} from './wiz.types.js';
-import { wizDefaultPort } from './wiz.types.js';
-import { WizMapper } from './wiz.mapper.js';
-
-type TWizEventHandler = (eventArg: IWizEvent) => void;
+import * as plugins from '../../plugins.js';
+import { NativeHomeAdmission } from '../../core/classes.nativehomeadmission.js';
+import type { IIntegrationSetupContext } from '../../core/types.js';
+import type { IWizConfig, IWizSnapshot, IWizWriteResult, TWizControl } from './wiz.types.js';
+import { normalizeWizConfig, wizControl } from './wiz.validation.js';
 
 export class WizClient {
-  private readonly events: IWizEvent[] = [];
-  private readonly eventHandlers = new Set<TWizEventHandler>();
-
-  constructor(private readonly config: IWizConfig) {}
-
-  public async getSnapshot(): Promise<IWizSnapshot> {
-    const host = this.host();
-    if (!host) {
-      return WizMapper.toSnapshot(this.config, false, this.events);
-    }
-
-    try {
-      const pilot = await this.getPilot();
-      const deviceInfo = await this.liveDeviceInfo(pilot).catch(() => this.staticDeviceInfo(pilot));
-      const device: IWizSnapshotDevice = {
-        host,
-        port: this.port(),
-        mac: pilot.mac || deviceInfo.mac || this.config.mac,
-        name: this.config.name || deviceInfo.name,
-        deviceInfo,
-        pilot,
-        available: true,
-      };
-      return WizMapper.toSnapshot({ ...this.config, snapshot: undefined, devices: [device], manualEntries: undefined }, true, this.events);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      this.emit({ type: 'error', data: { message }, timestamp: Date.now() });
-      return WizMapper.toSnapshot(this.config, false, this.events);
-    }
-  }
-
-  public onEvent(handlerArg: TWizEventHandler): () => void {
-    this.eventHandlers.add(handlerArg);
-    return () => this.eventHandlers.delete(handlerArg);
-  }
-
-  public async getPilot(): Promise<IWizPilotState> {
-    const response = await this.sendUdp<IWizPilotState>({ method: 'getPilot', params: {} });
-    const result = this.record(response.result) ? response.result as IWizPilotState : {};
-    this.emit({ type: 'pilot', data: result, timestamp: Date.now() });
-    return result;
-  }
-
-  public async setPilot(payloadArg: IWizPilotPatch): Promise<IWizUdpResponse<Record<string, unknown>>> {
-    return this.sendUdp<Record<string, unknown>>({ method: 'setPilot', params: payloadArg as Record<string, unknown> });
-  }
-
-  public async getSystemConfig(): Promise<IWizUdpResponse<Record<string, unknown>>> {
-    return this.sendUdp<Record<string, unknown>>({ method: 'getSystemConfig', params: {} });
-  }
-
-  public async sendCommand(commandArg: IWizClientCommand): Promise<IWizCommandResult> {
-    let result: IWizCommandResult;
-    if (this.config.commandExecutor) {
-      result = this.commandResult(await this.config.commandExecutor(commandArg), commandArg);
-    } else if (!this.host()) {
-      result = {
-        success: false,
-        error: this.unsupportedLiveControlMessage(),
-        data: { command: commandArg },
-      };
-    } else {
-      try {
-        const response = await this.setPilot(commandArg.payload);
-        result = { success: true, data: response.result || response };
-      } catch (error) {
-        result = {
-          success: false,
-          error: error instanceof Error ? error.message : String(error),
-          data: { command: commandArg },
-        };
-      }
-    }
-
-    this.emit({
-      type: result.success ? 'command_mapped' : 'command_failed',
-      command: commandArg,
-      data: result,
-      timestamp: Date.now(),
-      deviceId: commandArg.deviceId,
-      entityId: commandArg.entityId,
+  readonly #config: ReturnType<typeof normalizeWizConfig>;
+  readonly #protocol: plugins.ecobridgeDeviceManager.WizProtocol;
+  readonly #lifetime = new AbortController();
+  readonly #operations = new Set<Promise<unknown>>();
+  readonly #ownerSignal?: AbortSignal;
+  #healthy = false;
+  #closed = false;
+  #closing?: Promise<void>;
+  #retrying?: Promise<void>;
+
+  constructor(configArg: IWizConfig, contextArg: IIntegrationSetupContext) {
+    this.#config = normalizeWizConfig(configArg);
+    const context = new NativeHomeAdmission('wiz').admit(contextArg, this.#config.homeId);
+    const ownerSignalArg = context.abortSignal;
+    ownerSignalArg?.throwIfAborted();
+    this.#ownerSignal = ownerSignalArg;
+    this.#protocol = new plugins.ecobridgeDeviceManager.WizProtocol({
+      host: this.#config.host, port: this.#config.port, macAddress: this.#config.macAddress,
+      timeoutMs: this.#config.timeoutMs, maxPendingOperations: this.#config.maxPendingOperations, maxExchanges: this.#config.maxExchanges,
     });
-    return result;
   }
 
-  public async destroy(): Promise<void> {
-    this.eventHandlers.clear();
-  }
+  public get homeId(): string { return this.#config.homeId; }
+  public get pollIntervalMs(): number { return this.#config.pollIntervalMs; }
+  public isHealthy(): boolean { return this.#healthy && !this.#closed; }
 
-  private async liveDeviceInfo(pilotArg: IWizPilotState): Promise<IWizDeviceInfo> {
-    const systemConfig = await this.getSystemConfig();
-    const result = this.record(systemConfig.result) ? systemConfig.result : {};
-    return this.staticDeviceInfo(pilotArg, result);
-  }
-
-  private staticDeviceInfo(pilotArg?: IWizPilotState, systemArg: Record<string, unknown> = {}): IWizDeviceInfo {
-    const moduleName = this.stringValue(systemArg.moduleName) || this.config.deviceInfo?.moduleName;
-    const model = this.config.deviceInfo?.model || moduleName;
-    const isSocket = this.config.deviceInfo?.isSocket ?? this.textContainsSocket(model, moduleName, systemArg.typeId);
-    return {
-      ...this.config.deviceInfo,
-      host: this.host(),
-      port: this.port(),
-      mac: this.stringValue(systemArg.mac) || pilotArg?.mac || this.config.mac || this.config.deviceInfo?.mac,
-      name: this.config.name || this.config.deviceInfo?.name,
-      manufacturer: this.config.deviceInfo?.manufacturer || 'WiZ',
-      model,
-      moduleName,
-      fwVersion: this.stringValue(systemArg.fwVersion) || this.config.deviceInfo?.fwVersion,
-      typeId: this.stringValue(systemArg.typeId) || this.numberValue(systemArg.typeId) || this.config.deviceInfo?.typeId,
-      isSocket,
-      features: {
-        light: !isSocket,
-        switch: isSocket,
-        brightness: !isSocket || typeof pilotArg?.dimming === 'number',
-        color: ['r', 'g', 'b'].every((keyArg) => typeof pilotArg?.[keyArg] === 'number') || this.textContains(moduleName, 'rgb'),
-        colorTemp: typeof pilotArg?.temp === 'number' || this.textContains(moduleName, 'tw'),
-        effect: typeof pilotArg?.sceneId === 'number' || typeof pilotArg?.schdPsetId === 'number',
-        fan: typeof pilotArg?.fanState === 'number',
-        power: typeof pilotArg?.pc === 'number',
-        occupancy: pilotArg?.src === 'pir',
-        ...this.config.deviceInfo?.features,
-      },
-    };
+  public getSnapshot(signalArg?: AbortSignal): Promise<IWizSnapshot> {
+    return this.track(async () => {
+      const signal = this.signal(signalArg);
+      const info = await this.#protocol.getDeviceInfo({ signal });
+      signal.throwIfAborted();
+      this.#healthy = true;
+      return Object.freeze({ homeId: this.#config.homeId, host: this.#config.host, port: this.#config.port,
+        name: this.#config.name, info, observedAt: new Date().toISOString() });
+    });
   }
 
-  private async sendUdp<TResult>(commandArg: IWizUdpCommand): Promise<IWizUdpResponse<TResult>> {
-    const host = this.host();
-    if (!host) {
-      throw new Error(this.unsupportedLiveControlMessage());
-    }
-    const port = this.port();
-    const timeoutMs = this.timeoutMs();
-    const { createSocket } = await import('node:dgram');
-    const payload = Buffer.from(JSON.stringify(commandArg));
-
-    return new Promise<IWizUdpResponse<TResult>>((resolve, reject) => {
-      const socket = createSocket('udp4');
-      const timers: Array<ReturnType<typeof setTimeout>> = [];
-      let settled = false;
-
-      const cleanup = () => {
-        for (const timer of timers) {
-          clearTimeout(timer);
-        }
-        socket.removeAllListeners();
-        try {
-          socket.close();
-        } catch {
-          // The socket may already be closed after an early UDP error.
-        }
-      };
-
-      const finish = (errorArg: Error | undefined, responseArg?: IWizUdpResponse<TResult>) => {
-        if (settled) {
-          return;
-        }
-        settled = true;
-        cleanup();
-        if (errorArg) {
-          reject(errorArg);
-        } else {
-          resolve(responseArg || {});
-        }
-      };
-
-      const send = () => {
-        if (settled) {
-          return;
-        }
-        socket.send(payload, port, host, (errorArg) => {
-          if (errorArg) {
-            finish(errorArg);
-          }
-        });
-      };
-
-      socket.on('error', (errorArg) => finish(errorArg));
-      socket.on('message', (messageArg) => {
-        let response: IWizUdpResponse<TResult>;
-        try {
-          response = JSON.parse(messageArg.toString('utf8')) as IWizUdpResponse<TResult>;
-        } catch (error) {
-          finish(error instanceof Error ? error : new Error(String(error)));
-          return;
-        }
-        if (response.method && response.method !== commandArg.method) {
-          return;
-        }
-        if (response.error) {
-          finish(new Error(response.error.message || `WiZ UDP error ${response.error.code ?? 'unknown'}`));
-          return;
+  public write(controlArg: TWizControl, signalArg?: AbortSignal): Promise<IWizWriteResult> {
+    return this.track(async () => {
+      let control: TWizControl;
+      let signal: AbortSignal;
+      try { control = wizControl(controlArg); signal = this.signal(signalArg); }
+      catch { return Object.freeze({ outcome: 'not-sent', physicalStateConfirmed: false }); }
+      try {
+        const result = control.feature === 'power' ? await this.#protocol.setPower(control.value, { signal }) :
+          control.feature === 'brightness' ? await this.#protocol.setBrightness(control.value, { signal }) :
+            await this.#protocol.setRgb(control.value, { signal });
+        this.#healthy = true;
+        return Object.freeze({ outcome: result.outcome, physicalStateConfirmed: false, observedState: result.observedState });
+      } catch (errorArg) {
+        this.#healthy = false;
+        if (errorArg instanceof plugins.ecobridgeDeviceManager.WizProtocolError) {
+          return Object.freeze({ outcome: errorArg.effectOutcome, physicalStateConfirmed: false, errorCode: errorArg.code });
         }
-        this.emit({ type: 'udp_response', data: response, timestamp: Date.now() });
-        finish(undefined, response);
-      });
-
-      send();
-      timers.push(setTimeout(send, 750));
-      timers.push(setTimeout(send, 2250));
-      timers.push(setTimeout(() => finish(new Error(`Timed out waiting for WiZ ${commandArg.method} response from ${host}:${port}.`)), timeoutMs));
+        throw errorArg;
+      }
     });
   }
 
-  private emit(eventArg: IWizEvent): void {
-    this.events.push(eventArg);
-    for (const handler of this.eventHandlers) {
-      handler(eventArg);
+  public destroy(): Promise<void> {
+    if (!this.#closing) {
+      this.#closed = true;
+      this.#healthy = false;
+      this.#closing = Promise.resolve().then(() => this.cleanup());
+      this.#lifetime.abort(new Error('WiZ client is destroyed.'));
     }
+    return this.#closing;
   }
 
-  private commandResult(resultArg: unknown, commandArg: IWizClientCommand): IWizCommandResult {
-    if (this.isCommandResult(resultArg)) {
-      return resultArg;
+  /** Explicitly retries retained cleanup; no protocol operation is replayed. */
+  public retryCleanup(): Promise<void> {
+    if (!this.#closed) return Promise.reject(new Error('WiZ cleanup retry requires terminal shutdown.'));
+    if (!this.#retrying) {
+      this.#retrying = Promise.resolve().then(() => this.cleanup()).finally(() => { this.#retrying = undefined; });
     }
-    return { success: true, data: resultArg ?? { command: commandArg } };
-  }
-
-  private isCommandResult(valueArg: unknown): valueArg is IWizCommandResult {
-    return typeof valueArg === 'object' && valueArg !== null && 'success' in valueArg;
-  }
-
-  private host(): string | undefined {
-    return this.config.host || this.config.manualEntries?.find((entryArg) => entryArg.host)?.host;
-  }
-
-  private port(): number {
-    const manualPort = this.config.manualEntries?.find((entryArg) => entryArg.host)?.port;
-    return this.config.port || manualPort || wizDefaultPort;
-  }
-
-  private timeoutMs(): number {
-    return typeof this.config.timeoutMs === 'number' && this.config.timeoutMs > 0 ? this.config.timeoutMs : 5000;
-  }
-
-  private unsupportedLiveControlMessage(): string {
-    return 'WiZ live UDP control requires a configured host. Snapshot-only WiZ configs are read-only unless commandExecutor is provided.';
-  }
-
-  private textContainsSocket(...valuesArg: unknown[]): boolean {
-    return valuesArg.some((valueArg) => this.textContains(valueArg, 'socket') || this.textContains(valueArg, 'plug'));
-  }
-
-  private textContains(valueArg: unknown, fragmentArg: string): boolean {
-    return typeof valueArg === 'string' && valueArg.toLowerCase().includes(fragmentArg);
+    return this.#retrying;
   }
 
-  private stringValue(valueArg: unknown): string | undefined {
-    return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
+  private async cleanup(): Promise<void> {
+    const results = await Promise.allSettled([
+      Promise.resolve().then(() => this.#protocol.close()),
+      Promise.allSettled([...this.#operations]),
+    ]);
+    const errors = results.flatMap((resultArg) => resultArg.status === 'rejected' ? [resultArg.reason] : []);
+    if (errors.length) throw new AggregateError(errors, 'WiZ client cleanup failed after draining admitted operations.');
   }
 
-  private numberValue(valueArg: unknown): number | undefined {
-    return typeof valueArg === 'number' && Number.isFinite(valueArg) ? valueArg : undefined;
+  private signal(signalArg?: AbortSignal): AbortSignal {
+    if (this.#closed) throw new Error('WiZ client is destroyed.');
+    const signal = AbortSignal.any([this.#lifetime.signal, ...(this.#ownerSignal ? [this.#ownerSignal] : []), ...(signalArg ? [signalArg] : [])]);
+    signal.throwIfAborted();
+    return signal;
   }
 
-  private record(valueArg: unknown): valueArg is Record<string, unknown> {
-    return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+  private track<T>(workArg: () => Promise<T>): Promise<T> {
+    const operation = workArg().catch((errorArg: unknown) => { this.#healthy = false; throw errorArg; });
+    this.#operations.add(operation);
+    void operation.then(() => this.#operations.delete(operation), () => this.#operations.delete(operation));
+    return operation;
   }
 }

package/ts/integrations/wiz/wiz.classes.configflow.ts

@@ -1,84 +1,53 @@
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
-import type { IWizConfig, IWizDeviceInfo, IWizPilotState, IWizSnapshot } from './wiz.types.js';
-import { wizDefaultPort } from './wiz.types.js';
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
+import type { INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
+import { WizClient } from './wiz.classes.client.js';
+import type { IWizConfig } from './wiz.types.js';
+import { normalizeWizConfig, wizRecord } from './wiz.validation.js';
 
 export class WizConfigFlow implements IConfigFlow<IWizConfig> {
+  readonly #scope: NativeIntegrationScope;
+
+  constructor(ownerArg: NativeIntegrationOwner = new NativeIntegrationOwner('wiz')) {
+    this.#scope = ownerArg.createFlowScope();
+  }
+
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IWizConfig>> {
-    void contextArg;
-    const defaults = this.defaultsFromCandidate(candidateArg);
+    const candidate = wizRecord(candidateArg);
+    const context = this.#scope.admit(contextArg);
     return {
-      kind: 'form',
-      title: 'Connect WiZ',
-      description: 'Configure the WiZ device host. Local control uses UDP JSON on port 38899 by default.',
+      kind: 'form', title: 'Select WiZ device',
+      description: 'Confirm the local IPv4 address and unicast device MAC for the host-selected home. UDP replies are unauthenticated LAN observations.',
       fields: [
-        { name: 'host', label: 'Host or IP address', type: 'text', required: true },
-        { name: 'port', label: 'UDP port (default 38899)', type: 'number' },
-        { name: 'mac', label: 'MAC address', type: 'text' },
-        { name: 'name', label: 'Device name', type: 'text' },
+        { name: 'host', label: 'Selected local IPv4 address', type: 'text', required: true },
+        { name: 'macAddress', label: 'Exact device MAC', type: 'text', required: true },
+        { name: 'port', label: 'UDP port', type: 'number' },
+        { name: 'name', label: 'Display name', type: 'text' },
       ],
-      submit: async (valuesArg) => {
-        const host = this.stringValue(valuesArg.host) || defaults.host;
-        if (!host) {
-          return { kind: 'error', title: 'Invalid WiZ config', error: 'WiZ setup requires a host or IP address.' };
-        }
-        const port = this.numberValue(valuesArg.port) || defaults.port || wizDefaultPort;
-        const mac = this.stringValue(valuesArg.mac) || defaults.mac;
-        const name = this.stringValue(valuesArg.name) || defaults.name;
-        return {
-          kind: 'done',
-          title: 'WiZ configured',
-          config: {
-            host,
-            port,
-            mac,
-            name,
-            deviceInfo: {
-              ...defaults.deviceInfo,
-              host,
-              port,
-              mac: mac || defaults.deviceInfo?.mac,
-              name: name || defaults.deviceInfo?.name,
-            },
-            pilot: defaults.pilot,
-            snapshot: defaults.snapshot,
-          },
-        };
-      },
+      submit: (valuesArg) => this.submit(valuesArg, candidate, context),
     };
   }
 
-  private defaultsFromCandidate(candidateArg: IDiscoveryCandidate): { host?: string; port?: number; mac?: string; name?: string; deviceInfo?: IWizDeviceInfo; pilot?: IWizPilotState; snapshot?: IWizSnapshot } {
-    const metadata = candidateArg.metadata || {};
-    const deviceInfo = this.isRecord(metadata.deviceInfo) ? metadata.deviceInfo as unknown as IWizDeviceInfo : undefined;
-    const pilot = this.isRecord(metadata.pilot) ? metadata.pilot as unknown as IWizPilotState : undefined;
-    const snapshot = this.isRecord(metadata.snapshot) ? metadata.snapshot as unknown as IWizSnapshot : undefined;
-    return {
-      host: candidateArg.host,
-      port: candidateArg.port || wizDefaultPort,
-      mac: candidateArg.macAddress,
-      name: candidateArg.name,
-      deviceInfo,
-      pilot,
-      snapshot,
-    };
-  }
+  public destroy(): Promise<void> { return this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#scope.retryCleanup(); }
 
-  private stringValue(valueArg: unknown): string | undefined {
-    return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
-  }
-
-  private numberValue(valueArg: unknown): number | undefined {
-    if (typeof valueArg === 'number' && Number.isFinite(valueArg)) {
-      return valueArg;
-    }
-    if (typeof valueArg === 'string' && valueArg.trim()) {
-      const parsed = Number(valueArg);
-      return Number.isFinite(parsed) ? parsed : undefined;
+  private async submit(valuesArg: Record<string, unknown>, candidateArg: Record<string, unknown>, contextArg: INativeAdmissionContext): Promise<IConfigFlowStep<IWizConfig>> {
+    try {
+      const values = wizRecord(valuesArg, ['homeId', 'host', 'macAddress', 'port', 'name', 'timeoutMs', 'pollIntervalMs', 'maxPendingOperations', 'maxExchanges']);
+      if (values.homeId !== undefined && values.homeId !== contextArg.homeId) throw new TypeError('WiZ submitted home must match the host-selected home.');
+      const config = normalizeWizConfig({ ...values, homeId: contextArg.homeId, host: values.host ?? candidateArg.host,
+        macAddress: values.macAddress ?? candidateArg.macAddress, port: values.port ?? candidateArg.port });
+      return await this.#scope.run(contextArg, config.homeId, async (leaseArg) => {
+        const client = new WizClient(config, { ...leaseArg.context, abortSignal: leaseArg.signal });
+        let cleanupAttempts = 0;
+        leaseArg.own(() => cleanupAttempts++ === 0 ? client.destroy() : client.retryCleanup());
+        await client.getSnapshot(leaseArg.signal);
+        leaseArg.assertOpen();
+        if (leaseArg.context.configStore) await leaseArg.context.configStore.set(`device:${config.macAddress}`, config);
+        return { kind: 'done', title: leaseArg.context.configStore ? 'Selected WiZ device verified and stored' : 'Selected WiZ device verified', config };
+      });
+    } catch (errorArg) {
+      return { kind: 'error', title: 'WiZ admission failed', error: errorArg instanceof Error ? errorArg.message : 'WiZ device admission failed.' };
     }
-    return undefined;
-  }
-
-  private isRecord(valueArg: unknown): valueArg is Record<string, unknown> {
-    return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
   }
 }