@smarthome.exchange/integrations 1.0.0 → 3.0.0

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);
   }
 }

package/ts/integrations/wiz/wiz.classes.integration.ts

@@ -1,80 +1,224 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
+import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import type { IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { ConsoleLogger } from '../../core/classes.logger.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
+import type { IDeviceFeatureWriteRequest, ILogger, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime,
+  IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { WizClient } from './wiz.classes.client.js';
 import { WizConfigFlow } from './wiz.classes.configflow.js';
 import { createWizDiscoveryDescriptor } from './wiz.discovery.js';
 import { WizMapper } from './wiz.mapper.js';
-import type { IWizConfig } from './wiz.types.js';
+import type { IWizConfig, IWizSnapshot, IWizWriteResult, TWizControl } from './wiz.types.js';
+import { normalizeWizConfig } from './wiz.validation.js';
+
+export interface IWizIntegrationOptions {
+  readonly homeId?: string;
+  readonly capacity?: number;
+}
 
 export class WizIntegration extends BaseIntegration<IWizConfig> {
   public readonly domain = 'wiz';
   public readonly displayName = 'WiZ';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createWizDiscoveryDescriptor();
-  public readonly configFlow = new WizConfigFlow();
+  public readonly configFlow: WizConfigFlow;
   public readonly metadata = {
-    source: 'home-assistant/core',
-    upstreamPath: 'homeassistant/components/wiz',
-    upstreamDomain: 'wiz',
-    integrationType: 'device',
-    iotClass: 'local_push',
-    requirements: ['pywizlight==0.6.3'],
-    dependencies: ['network'],
-    afterDependencies: [] as string[],
-    codeowners: ['@sbidy', '@arturpragacz'],
-    documentation: 'https://www.home-assistant.io/integrations/wiz',
-    protocolDocumentation: 'https://docs.pro.wizconnected.com/#introduction',
-    dhcp: [
-      { registeredDevices: true },
-      { macaddress: 'A8BB50*' },
-      { macaddress: 'D8A011*' },
-      { macaddress: '444F8E*' },
-      { macaddress: '6C2990*' },
-      { hostname: 'wiz_*' },
-    ],
+    source: '@ecobridge.xyz/devicemanager', documentation: 'https://www.home-assistant.io/integrations/wiz',
+    integrationType: 'device', iotClass: 'local_polling', networkAuthenticated: false,
+    supportedControls: ['explicit power', 'observed brightness', 'observed RGB'],
   };
+  readonly #owner: NativeIntegrationOwner;
+
+  constructor(optionsArg: IWizIntegrationOptions = {}) {
+    super();
+    this.#owner = new NativeIntegrationOwner('wiz', optionsArg);
+    this.configFlow = new WizConfigFlow(this.#owner);
+  }
 
   public async setup(configArg: IWizConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new WizRuntime(new WizClient(configArg));
+    const config = normalizeWizConfig(configArg);
+    return this.#owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+      const client = new WizClient(config, { ...leaseArg.context, abortSignal: leaseArg.signal });
+      let runtime: WizRuntime | undefined;
+      let cleanupAttempts = 0;
+      const closeClient = (): Promise<void> => cleanupAttempts++ === 0 ? client.destroy() : client.retryCleanup();
+      leaseArg.own(() => runtime ? runtime.cleanup() : closeClient());
+      const snapshot = await client.getSnapshot(leaseArg.signal);
+      leaseArg.assertOpen();
+      runtime = new WizRuntime(client, snapshot, leaseArg.context.logger, leaseArg, closeClient);
+      leaseArg.promoteToRuntime();
+      return runtime;
+    });
   }
 
-  public async destroy(): Promise<void> {}
+  public destroy(): Promise<void> { return this.#owner.close(); }
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
 
 export class HomeAssistantWizIntegration extends WizIntegration {}
 
+interface IWizSubscription {
+  handler(eventArg: IIntegrationEvent): void;
+  release(): void;
+}
+
 class WizRuntime implements IIntegrationRuntime {
-  public domain = 'wiz';
+  public readonly domain = 'wiz';
+  readonly #subscriptions = new Set<IWizSubscription>();
+  readonly #client: WizClient;
+  readonly #logger: ILogger;
+  readonly #lease: INativeSetupLease;
+  readonly #closeClient: () => Promise<void>;
+  readonly #ownerAbort = (): void => { this.markClosed(); };
+  #snapshot: IWizSnapshot;
+  #timer?: ReturnType<typeof setTimeout>;
+  #poll?: Promise<void>;
+  #pollController?: AbortController;
+  #closed = false;
 
-  constructor(private readonly client: WizClient) {}
+  constructor(clientArg: WizClient, snapshotArg: IWizSnapshot, loggerArg: ILogger | undefined, leaseArg: INativeSetupLease, closeClientArg: () => Promise<void>) {
+    this.#client = clientArg; this.#snapshot = snapshotArg; this.#logger = loggerArg ?? new ConsoleLogger();
+    this.#lease = leaseArg; this.#closeClient = closeClientArg;
+    leaseArg.signal.addEventListener('abort', this.#ownerAbort, { once: true });
+    if (leaseArg.signal.aborted) this.#ownerAbort();
+  }
 
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return WizMapper.toDevices(await this.client.getSnapshot());
+  public isHealthy(): boolean { return !this.#closed && this.#client.isHealthy(); }
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> { return WizMapper.toDevices(await this.refresh(signalArg)); }
+  public async entities(): Promise<IIntegrationEntity[]> { return WizMapper.toEntities(await this.refresh()); }
+
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    if (this.#closed) throw new Error('WiZ runtime is destroyed.');
+    if (typeof handlerArg !== 'function') throw new TypeError('WiZ subscription requires a handler.');
+    signalArg?.throwIfAborted();
+    const subscription: IWizSubscription = {
+      handler: handlerArg,
+      release: () => {
+        this.#subscriptions.delete(subscription);
+        signalArg?.removeEventListener('abort', subscription.release);
+        if (!this.#subscriptions.size) this.stopPolling();
+      },
+    };
+    try {
+      const snapshot = await this.#client.getSnapshot(signalArg);
+      if (this.#closed) throw new Error('WiZ runtime is destroyed.');
+      signalArg?.throwIfAborted();
+      this.#snapshot = snapshot;
+      handlerArg(this.observation(snapshot));
+      if (this.#closed) throw new Error('WiZ runtime was destroyed during initial subscription delivery.');
+      signalArg?.throwIfAborted();
+      this.#subscriptions.add(subscription);
+      signalArg?.addEventListener('abort', subscription.release, { once: true });
+      if (signalArg?.aborted) subscription.release();
+      this.schedulePolling();
+    } catch (errorArg) { subscription.release(); throw errorArg; }
+    return async () => {
+      subscription.release();
+      if (!this.#subscriptions.size) await this.#poll;
+    };
   }
 
-  public async entities(): Promise<IIntegrationEntity[]> {
-    return WizMapper.toEntities(await this.client.getSnapshot());
+  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    let control: TWizControl;
+    try { control = WizMapper.controlForService(this.#snapshot, requestArg); }
+    catch (errorArg) { return this.admissionFailure(errorArg); }
+    return this.write(control);
   }
 
-  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void): Promise<() => Promise<void>> {
-    const unsubscribe = this.client.onEvent((eventArg) => handlerArg(WizMapper.toIntegrationEvent(eventArg)));
-    await this.client.getSnapshot();
-    return async () => unsubscribe();
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    let control: TWizControl;
+    try { control = WizMapper.controlForFeature(this.#snapshot, requestArg); }
+    catch (errorArg) { return this.admissionFailure(errorArg); }
+    return this.write(control, signalArg);
   }
 
-  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    const snapshot = await this.client.getSnapshot();
-    const command = WizMapper.commandForService(snapshot, requestArg);
-    if (!command) {
-      return { success: false, error: `WiZ service ${requestArg.domain}.${requestArg.service} has no native setPilot mapping for the target.` };
+  public destroy(): Promise<void> {
+    this.markClosed();
+    return this.#lease.close();
+  }
+
+  /** Called only by the owning lease, including explicit retained-cleanup retry. */
+  public async cleanup(): Promise<void> {
+    this.markClosed();
+    const results = await Promise.allSettled([Promise.resolve().then(this.#closeClient), this.#poll]);
+    const errors = results.flatMap((resultArg) => resultArg.status === 'rejected' ? [resultArg.reason] : []);
+    if (errors.length) throw new AggregateError(errors, 'WiZ runtime cleanup failed after draining polling.');
+  }
+
+  private markClosed(): void {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#lease.signal.removeEventListener('abort', this.#ownerAbort);
+    for (const subscription of [...this.#subscriptions]) subscription.release();
+    this.stopPolling();
+  }
+
+  private async refresh(signalArg?: AbortSignal): Promise<IWizSnapshot> {
+    if (this.#closed) throw new Error('WiZ runtime is destroyed.');
+    const snapshot = await this.#client.getSnapshot(signalArg);
+    if (this.#closed) throw new Error('WiZ runtime is destroyed.');
+    this.#snapshot = snapshot;
+    this.notify(this.observation(snapshot));
+    return snapshot;
+  }
+
+  private async write(controlArg: TWizControl, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    if (this.#closed) return this.admissionFailure(new Error('WiZ runtime is destroyed.'));
+    const data = await this.#client.write(controlArg, signalArg);
+    if (data.observedState && !this.#closed) {
+      this.#snapshot = Object.freeze({ ...this.#snapshot, observedAt: new Date().toISOString(),
+        info: Object.freeze({ ...this.#snapshot.info, observedState: data.observedState }) });
+      this.notify(this.observation(this.#snapshot));
     }
-    const result = await this.client.sendCommand(command);
-    return { success: result.success, error: result.error, data: result.data };
+    return this.writeResult(data);
+  }
+
+  private writeResult(dataArg: IWizWriteResult): IServiceCallResult {
+    return { success: dataArg.outcome === 'accepted' && dataArg.errorCode === undefined, data: dataArg,
+      error: dataArg.outcome === 'accepted' && dataArg.errorCode === undefined ? undefined : dataArg.outcome === 'accepted' ?
+        'WiZ firmware accepted the operation, but observed readback failed; do not replay it.' :
+        `WiZ operation outcome is ${dataArg.outcome}; automatic replay is prohibited.` };
+  }
+
+  private admissionFailure(errorArg: unknown): IServiceCallResult {
+    return { success: false, error: errorArg instanceof Error ? errorArg.message : 'WiZ admission failed.',
+      data: { outcome: 'not-sent', physicalStateConfirmed: false } };
+  }
+
+  private observation(snapshotArg: IWizSnapshot): IIntegrationEvent {
+    return { type: 'state_changed', integrationDomain: 'wiz', deviceId: WizMapper.deviceId(snapshotArg),
+      entityId: WizMapper.entityId(snapshotArg), timestamp: Date.parse(snapshotArg.observedAt),
+      data: { device: WizMapper.toDevices(snapshotArg)[0], entity: WizMapper.toEntities(snapshotArg)[0] } };
+  }
+
+  private notify(eventArg: IIntegrationEvent): void {
+    for (const subscription of [...this.#subscriptions]) {
+      try { subscription.handler(eventArg); }
+      catch { subscription.release(); this.#logger.log('error', 'WiZ subscription handler failed and was removed.'); }
+    }
+  }
+
+  private schedulePolling(): void {
+    if (this.#closed || this.#timer || this.#poll || !this.#subscriptions.size || !this.#client.pollIntervalMs) return;
+    this.#timer = setTimeout(() => {
+      this.#timer = undefined;
+      const controller = new AbortController();
+      this.#pollController = controller;
+      this.#poll = this.refresh(controller.signal).then(() => undefined).catch((errorArg: unknown) => {
+        if (controller.signal.aborted || this.#closed) return;
+        this.notify({ type: 'availability_changed', integrationDomain: 'wiz', deviceId: WizMapper.deviceId(this.#snapshot),
+          timestamp: Date.now(), data: { available: false } });
+        this.#logger.log('error', 'WiZ polling did not obtain an authoritative observation.');
+        if (errorArg instanceof plugins.ecobridgeDeviceManager.WizProtocolError && errorArg.code === 'EXCHANGE_LIMIT') void this.destroy();
+      }).finally(() => {
+        this.#poll = undefined; this.#pollController = undefined; this.schedulePolling();
+      });
+    }, this.#client.pollIntervalMs);
   }
 
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
+  private stopPolling(): void {
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#timer = undefined;
+    this.#pollController?.abort(new Error('WiZ subscription polling stopped.'));
   }
 }