@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/panasonic_viera/panasonic_viera.classes.client.ts

@@ -1,426 +1,129 @@
 import * as plugins from '../../plugins.js';
-import { SimpleLocalClient, type ISimpleLocalSnapshot, type IServiceCallRequest, type IServiceCallResult } from '../../core/index.js';
-import { PanasonicVieraMapper } from './panasonic_viera.mapper.js';
-import type { IPanasonicVieraConfig, IPanasonicVieraRawApiData } from './panasonic_viera.types.js';
-import { panasonicVieraDefaultPort, panasonicVieraDefaultTimeoutMs, panasonicVieraProfile } from './panasonic_viera.types.js';
-
-interface IPanasonicVieraSession {
-  key: Buffer;
-  iv: Buffer;
-  hmacKey: Buffer;
-  id?: string;
-  sequenceNumber?: number;
-}
-
-export class PanasonicVieraClient extends SimpleLocalClient<IPanasonicVieraConfig> {
-  private cachedSnapshot?: ISimpleLocalSnapshot;
-  private encryptedSession?: IPanasonicVieraSession;
+import { NativeHomeAdmission } from '../../core/classes.nativehomeadmission.js';
+import type { IPanasonicVieraClientOptions, IPanasonicVieraConfig, IPanasonicVieraSnapshot, TPanasonicVieraKey, TPanasonicVieraKeyReceipt } from './panasonic_viera.types.js';
+import { drainPanasonicVieraCleanup, normalizePanasonicVieraConfig, panasonicVieraRecord } from './panasonic_viera.validation.js';
+
+export class PanasonicVieraClient {
+  private readonly config: Readonly<IPanasonicVieraConfig>;
+  private readonly protocol: plugins.ecobridgeDeviceManager.PanasonicProtocol;
+  private readonly lifetime = new AbortController();
+  private readonly operations = new Set<Promise<unknown>>();
+  private readonly ownerSignal?: AbortSignal;
+  private readonly onDestroyed?: () => void;
+  private state: 'new' | 'starting' | 'ready' | 'closed' = 'new';
+  private closePromise?: Promise<void>;
+  private retryPromise?: Promise<void>;
+  private cleanupComplete = false;
+  private readonly onOwnerAbort = (): void => {
+    // An event listener cannot return the close result. Retain it for destroy(), while observing its rejection.
+    void this.destroy().catch(() => undefined);
+  };
 
-  constructor(private readonly clientConfig: IPanasonicVieraConfig) {
-    super(panasonicVieraProfile, clientConfig);
+  public constructor(configArg: IPanasonicVieraConfig, optionsArg: IPanasonicVieraClientOptions) {
+    this.config = normalizePanasonicVieraConfig(configArg);
+    const options = panasonicVieraRecord(optionsArg, ['homeId', 'configStore', 'logger', 'abortSignal', 'onDestroyed']);
+    if (options.onDestroyed !== undefined && typeof options.onDestroyed !== 'function') {
+      throw new TypeError('Panasonic Viera client lifetime options are invalid.');
+    }
+    const { onDestroyed: _onDestroyed, ...contextOptions } = options;
+    const context = new NativeHomeAdmission('panasonic_viera').admit(contextOptions, this.config.homeId);
+    this.protocol = new plugins.ecobridgeDeviceManager.PanasonicProtocol({
+      address: this.config.host, descriptionUrl: this.config.descriptionUrl,
+      expectedUdn: this.config.expectedUdn, expectedModelName: this.config.expectedModelName,
+      timeoutMs: this.config.timeoutMs, maxResponseBytes: this.config.maxResponseBytes,
+    });
+    this.ownerSignal = context.abortSignal;
+    this.onDestroyed = optionsArg.onDestroyed;
+    if (this.ownerSignal?.aborted) this.onOwnerAbort();
+    else this.ownerSignal?.addEventListener('abort', this.onOwnerAbort, { once: true });
   }
 
-  public async getSnapshot(forceRefreshArg = false): Promise<ISimpleLocalSnapshot> {
-    if (!forceRefreshArg && this.cachedSnapshot) {
-      return clone(this.cachedSnapshot);
-    }
-
-    if (!forceRefreshArg && this.clientConfig.snapshot) {
-      this.cachedSnapshot = PanasonicVieraMapper.toSnapshot({ config: this.clientConfig, source: 'snapshot', online: this.clientConfig.snapshot.online });
-      return clone(this.cachedSnapshot);
-    }
+  public get isClosed(): boolean { return this.state === 'closed'; }
+  public get isHealthy(): boolean { return this.state === 'ready' && this.protocol.isStarted; }
 
-    if (this.endpoint()) {
+  public start(abortSignalArg?: AbortSignal): Promise<IPanasonicVieraSnapshot> {
+    this.assertOpen();
+    if (this.state !== 'new') return Promise.reject(new Error('Panasonic Viera startup is single-use.'));
+    this.state = 'starting';
+    return this.track(async () => {
       try {
-        const rawData = await this.fetchRawData();
-        this.cachedSnapshot = PanasonicVieraMapper.toSnapshot({ config: this.clientConfig, rawData, online: true, source: 'http' });
+        const profile = await this.protocol.start({ signal: this.operationSignal(abortSignalArg) });
+        this.assertOpen();
+        this.state = 'ready';
+        return this.snapshot(profile);
       } catch (errorArg) {
-        this.cachedSnapshot = this.createOfflineSnapshot(errorMessage(errorArg));
-      }
-      return clone(this.cachedSnapshot);
-    }
-
-    this.cachedSnapshot = await super.getSnapshot(forceRefreshArg);
-    return clone(this.cachedSnapshot);
-  }
-
-  public async refresh(): Promise<IServiceCallResult> {
-    this.cachedSnapshot = undefined;
-    const snapshot = await this.getSnapshot(Boolean(this.endpoint()));
-    const success = snapshot.online && !snapshot.error;
-    return { success, error: success ? undefined : snapshot.error || 'Panasonic Viera refresh requires a live SOAP endpoint, injected client, snapshotProvider, snapshot, entities, or rawData.', data: snapshot };
-  }
-
-  public async execute(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (this.clientConfig.client?.execute || this.clientConfig.commandExecutor) {
-      return super.execute(requestArg);
-    }
-
-    if (!this.endpoint()) {
-      return super.execute(requestArg);
-    }
-
-    try {
-      const data = requestArg.data || {};
-      if (requestArg.service === 'volume_set' || requestArg.service === 'set_volume') {
-        const volume = numberValue(data.volume_level ?? data.volumeLevel ?? data.volume);
-        if (volume === undefined) {
-          throw new Error('Panasonic Viera volume_set requires data.volume_level or data.volume.');
-        }
-        await this.setVolume(volume <= 1 ? Math.round(volume * 100) : Math.round(volume));
-        this.cachedSnapshot = undefined;
-        return { success: true, data: { volume } };
-      }
-
-      if (requestArg.service === 'volume_mute' || requestArg.service === 'set_mute') {
-        const mute = booleanValue(data.is_volume_muted ?? data.mute ?? data.muted);
-        if (mute === undefined) {
-          await this.sendKey('NRC_MUTE-ONOFF');
-          this.cachedSnapshot = undefined;
-          return { success: true, data: { key: 'NRC_MUTE-ONOFF' } };
-        }
-        await this.setMute(mute);
-        this.cachedSnapshot = undefined;
-        return { success: true, data: { muted: mute } };
+        // Close the protocol here; destroy drains this wrapper after the rejection settles.
+        this.state = 'closed';
+        this.ownerSignal?.removeEventListener('abort', this.onOwnerAbort);
+        this.lifetime.abort(errorArg);
+        try { await this.protocol.close(); }
+        catch (cleanupErrorArg) { throw new AggregateError([errorArg, cleanupErrorArg], 'Panasonic Viera admission and cleanup failed.'); }
+        throw errorArg;
       }
-
-      const key = keyForService(requestArg.service, data);
-      if (!key) {
-        return { success: false, error: `Unsupported Panasonic Viera service: ${requestArg.service}` };
-      }
-      await this.sendKey(key);
-      this.cachedSnapshot = undefined;
-      return { success: true, data: { key } };
-    } catch (errorArg) {
-      return { success: false, error: errorMessage(errorArg) };
-    }
-  }
-
-  public async destroy(): Promise<void> {
-    await this.clientConfig.client?.destroy?.();
-  }
-
-  private async fetchRawData(): Promise<IPanasonicVieraRawApiData> {
-    const deviceInfoXml = await this.requestText('/nrc/ddd.xml');
-    const deviceInfo = parseDeviceInfo(deviceInfoXml);
-    const rawData: IPanasonicVieraRawApiData = {
-      deviceInfo,
-      fetchedAt: new Date().toISOString(),
-    };
-
-    try {
-      rawData.volume = await this.getVolume();
-    } catch (errorArg) {
-      rawData.volumeError = errorMessage(errorArg);
-    }
-
-    try {
-      rawData.muted = await this.getMute();
-    } catch (errorArg) {
-      rawData.muteError = errorMessage(errorArg);
-    }
-
-    return rawData;
-  }
-
-  private async getVolume(): Promise<number> {
-    const text = await this.soapRequest('/dmr/control_0', 'schemas-upnp-org:service:RenderingControl:1', 'GetVolume', '<InstanceID>0</InstanceID><Channel>Master</Channel>');
-    const volume = numberValue(extractXmlValue(text, 'CurrentVolume'));
-    if (volume === undefined) {
-      throw new Error('Panasonic Viera GetVolume response did not include CurrentVolume.');
-    }
-    return volume;
-  }
-
-  private async setVolume(volumeArg: number): Promise<void> {
-    if (volumeArg < 0 || volumeArg > 100) {
-      throw new Error('Panasonic Viera volume must be between 0 and 100.');
-    }
-    await this.soapRequest('/dmr/control_0', 'schemas-upnp-org:service:RenderingControl:1', 'SetVolume', `<InstanceID>0</InstanceID><Channel>Master</Channel><DesiredVolume>${volumeArg}</DesiredVolume>`);
-  }
-
-  private async getMute(): Promise<boolean> {
-    const text = await this.soapRequest('/dmr/control_0', 'schemas-upnp-org:service:RenderingControl:1', 'GetMute', '<InstanceID>0</InstanceID><Channel>Master</Channel>');
-    return extractXmlValue(text, 'CurrentMute') !== '0';
-  }
-
-  private async setMute(muteArg: boolean): Promise<void> {
-    await this.soapRequest('/dmr/control_0', 'schemas-upnp-org:service:RenderingControl:1', 'SetMute', `<InstanceID>0</InstanceID><Channel>Master</Channel><DesiredMute>${muteArg ? '1' : '0'}</DesiredMute>`);
-  }
-
-  private async sendKey(keyArg: string): Promise<void> {
-    await this.soapRequest('/nrc/control_0', 'panasonic-com:service:p00NetworkControl:1', 'X_SendKey', `<X_KeyEvent>${escapeXml(keyArg)}</X_KeyEvent>`);
-  }
-
-  private async soapRequest(pathArg: string, urnArg: string, actionArg: string, paramsArg: string, bodyElementArg = 'm'): Promise<string> {
-    let action = actionArg;
-    let params = paramsArg;
-    let bodyElement = bodyElementArg;
-    let encrypted = false;
-
-    if (this.shouldEncrypt(urnArg, actionArg)) {
-      const session = await this.ensureEncryptedSession();
-      session.sequenceNumber = (session.sequenceNumber || 1) + 1;
-      const originalCommand = `<X_SessionId>${session.id}</X_SessionId><X_SequenceNumber>${String(session.sequenceNumber).padStart(8, '0')}</X_SequenceNumber><X_OriginalCommand><u:${actionArg} xmlns:u="urn:${urnArg}">${paramsArg}</u:${actionArg}></X_OriginalCommand>`;
-      const encryptedCommand = this.encryptSoapPayload(originalCommand, session);
-      action = 'X_EncryptedCommand';
-      params = `<X_ApplicationId>${escapeXml(this.clientConfig.appId || '')}</X_ApplicationId><X_EncInfo>${encryptedCommand}</X_EncInfo>`;
-      bodyElement = 'u';
-      encrypted = true;
-    }
-
-    const body = `<?xml version="1.0" encoding="utf-8"?><s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"><s:Body><${bodyElement}:${action} xmlns:${bodyElement}="urn:${urnArg}">${params}</${bodyElement}:${action}></s:Body></s:Envelope>`;
-    const text = await this.requestText(pathArg, {
-      method: 'POST',
-      body,
-      headers: {
-        'Content-Type': 'text/xml; charset=utf-8',
-        SOAPAction: `"urn:${urnArg}#${action}"`,
-      },
     });
-
-    if (!encrypted) {
-      return text;
-    }
-
-    const encResult = extractXmlValue(text, 'X_EncResult');
-    if (!encResult) {
-      throw new Error('Panasonic Viera encrypted SOAP response did not include X_EncResult.');
-    }
-    return this.decryptSoapPayload(encResult, await this.ensureEncryptedSession());
-  }
-
-  private shouldEncrypt(urnArg: string, actionArg: string): boolean {
-    return urnArg === 'panasonic-com:service:p00NetworkControl:1'
-      && !['X_GetEncryptSessionId', 'X_DisplayPinCode', 'X_RequestAuth'].includes(actionArg)
-      && Boolean(this.clientConfig.appId && this.clientConfig.encryptionKey);
-  }
-
-  private async ensureEncryptedSession(): Promise<IPanasonicVieraSession> {
-    if (!this.clientConfig.appId || !this.clientConfig.encryptionKey) {
-      throw new Error('Panasonic Viera encrypted commands require config.appId and config.encryptionKey.');
-    }
-    if (!this.encryptedSession) {
-      this.encryptedSession = deriveSession(this.clientConfig.encryptionKey);
-    }
-    if (this.encryptedSession.id) {
-      return this.encryptedSession;
-    }
-
-    const encInfo = this.encryptSoapPayload(`<X_ApplicationId>${escapeXml(this.clientConfig.appId)}</X_ApplicationId>`, this.encryptedSession);
-    const text = await this.soapRequest('/nrc/control_0', 'panasonic-com:service:p00NetworkControl:1', 'X_GetEncryptSessionId', `<X_ApplicationId>${escapeXml(this.clientConfig.appId)}</X_ApplicationId><X_EncInfo>${encInfo}</X_EncInfo>`, 'u');
-    const encResult = extractXmlValue(text, 'X_EncResult');
-    if (!encResult) {
-      throw new Error('Panasonic Viera session response did not include X_EncResult.');
-    }
-    const decrypted = this.decryptSoapPayload(encResult, this.encryptedSession);
-    const sessionId = extractXmlValue(decrypted, 'X_SessionId');
-    if (!sessionId) {
-      throw new Error('Panasonic Viera encrypted session response did not include X_SessionId.');
-    }
-    this.encryptedSession.id = sessionId;
-    this.encryptedSession.sequenceNumber = 1;
-    return this.encryptedSession;
   }
 
-  private encryptSoapPayload(dataArg: string, sessionArg: IPanasonicVieraSession): string {
-    const header = Buffer.concat([plugins.crypto.randomBytes(12), uint32be(Buffer.byteLength(dataArg, 'latin1'))]);
-    const payload = Buffer.concat([header, Buffer.from(dataArg, 'latin1')]);
-    const padLength = (16 - (payload.length % 16)) % 16;
-    const paddedPayload = padLength ? Buffer.concat([payload, Buffer.alloc(padLength)]) : payload;
-    const cipher = plugins.crypto.createCipheriv('aes-128-cbc', sessionArg.key, sessionArg.iv);
-    cipher.setAutoPadding(false);
-    const ciphertext = Buffer.concat([cipher.update(paddedPayload), cipher.final()]);
-    const signature = plugins.crypto.createHmac('sha256', sessionArg.hmacKey).update(ciphertext).digest();
-    return Buffer.concat([ciphertext, signature]).toString('base64');
+  public getSnapshot(abortSignalArg?: AbortSignal): Promise<IPanasonicVieraSnapshot> {
+    this.assertOpen();
+    if (this.state === 'new') return this.start(abortSignalArg);
+    if (this.state !== 'ready') return Promise.reject(new Error('Panasonic Viera startup is in progress.'));
+    return this.track(async () => this.snapshot(await this.protocol.readProfile({ signal: this.operationSignal(abortSignalArg) })));
   }
 
-  private decryptSoapPayload(dataArg: string, sessionArg: IPanasonicVieraSession): string {
-    const encrypted = Buffer.from(dataArg, 'base64');
-    const decipher = plugins.crypto.createDecipheriv('aes-128-cbc', sessionArg.key, sessionArg.iv);
-    decipher.setAutoPadding(false);
-    const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('latin1');
-    return decrypted.slice(16).split('\0')[0];
+  public sendKey(keyArg: TPanasonicVieraKey, abortSignalArg?: AbortSignal): Promise<TPanasonicVieraKeyReceipt> {
+    this.assertOpen();
+    if (this.state !== 'ready') return Promise.reject(new Error('Panasonic Viera has not completed live admission.'));
+    return this.track(() => this.protocol.sendKey(keyArg, { signal: this.operationSignal(abortSignalArg) }));
   }
 
-  private async requestText(pathArg: string, optionsArg: { method?: 'GET' | 'POST'; body?: string; headers?: Record<string, string> } = {}): Promise<string> {
-    const endpoint = this.requireEndpoint();
-    const url = new URL(pathArg.replace(/^\/+/, ''), `${endpoint.origin}/`);
-    const timeoutMs = this.clientConfig.timeoutMs || panasonicVieraDefaultTimeoutMs;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-      const response = await globalThis.fetch(url, {
-        method: optionsArg.method || 'GET',
-        headers: { Accept: 'text/xml, application/xml;q=0.9, */*;q=0.8', ...(optionsArg.headers || {}) },
-        body: optionsArg.body,
-        signal: controller.signal,
-      });
-      const text = await response.text();
-      if (!response.ok) {
-        throw new Error(`Panasonic Viera request ${url.pathname} failed with ${response.status}: ${extractXmlValue(text, 'errorDescription') || text.slice(0, 160)}`);
-      }
-      return text;
-    } finally {
-      clearTimeout(timer);
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      this.state = 'closed';
+      this.ownerSignal?.removeEventListener('abort', this.onOwnerAbort);
+      const operations = [...this.operations];
+      this.closePromise = Promise.resolve().then(() => drainPanasonicVieraCleanup([this.protocol.close()], operations,
+        'Panasonic Viera client cleanup failed.')).then(() => { this.onDestroyed?.(); this.cleanupComplete = true; });
+      this.lifetime.abort(new Error('Panasonic Viera client is closed.'));
     }
+    return this.closePromise;
   }
 
-  private requireEndpoint(): URL {
-    const endpoint = this.endpoint();
-    if (!endpoint) {
-      throw new Error('Panasonic Viera local SOAP API requires config.host or config.url.');
+  /** Explicit cleanup retry only. The original destroy rejection remains observable; transport work is never replayed. */
+  public retryCleanup(): Promise<void> {
+    if (!this.closePromise) return Promise.reject(new Error('Panasonic Viera cleanup must first be closed.'));
+    if (this.cleanupComplete) return Promise.resolve();
+    if (!this.retryPromise) {
+      const closed = this.closePromise;
+      this.retryPromise = Promise.resolve().then(async () => {
+        await closed.catch(() => undefined);
+        await drainPanasonicVieraCleanup([this.protocol.close()], [...this.operations], 'Panasonic Viera explicit cleanup retry failed.');
+        this.onDestroyed?.();
+        this.cleanupComplete = true;
+      });
+      const settled = (): void => { this.retryPromise = undefined; };
+      void this.retryPromise.then(settled, settled);
     }
-    return endpoint;
+    return this.retryPromise;
   }
 
-  private endpoint(): URL | undefined {
-    const configuredUrl = stringValue(this.clientConfig.url);
-    if (configuredUrl) {
-      return normalizeBaseUrl(configuredUrl, this.clientConfig.port, this.clientConfig.useTls);
-    }
-    const host = stringValue(this.clientConfig.host);
-    if (!host) {
-      return undefined;
-    }
-    return normalizeBaseUrl(host, this.clientConfig.port || panasonicVieraDefaultPort, this.clientConfig.useTls);
+  private snapshot(profileArg: plugins.ecobridgeDeviceManager.IPanasonicProfile): IPanasonicVieraSnapshot {
+    this.assertOpen();
+    return Object.freeze({ homeId: this.config.homeId, name: this.config.name ?? profileArg.identity.name, profile: profileArg });
   }
 
-  private createOfflineSnapshot(errorArg: string): ISimpleLocalSnapshot {
-    return PanasonicVieraMapper.toSnapshot({ config: this.clientConfig, online: false, source: 'runtime', error: errorArg });
+  private operationSignal(signalArg?: AbortSignal): AbortSignal {
+    if (signalArg !== undefined && !(signalArg instanceof AbortSignal)) throw new TypeError('Panasonic Viera cancellation must be an AbortSignal.');
+    return signalArg ? AbortSignal.any([this.lifetime.signal, signalArg]) : this.lifetime.signal;
   }
-}
-
-const keyMap: Record<string, string> = {
-  media_play: 'NRC_PLAY-ONOFF',
-  media_pause: 'NRC_PAUSE-ONOFF',
-  media_stop: 'NRC_STOP-ONOFF',
-  media_next_track: 'NRC_FF-ONOFF',
-  media_previous_track: 'NRC_REW-ONOFF',
-  volume_up: 'NRC_VOLUP-ONOFF',
-  volume_down: 'NRC_VOLDOWN-ONOFF',
-  turn_on: 'NRC_POWER-ONOFF',
-  turn_off: 'NRC_POWER-ONOFF',
-  toggle: 'NRC_POWER-ONOFF',
-};
 
-const keyForService = (serviceArg: string, dataArg: Record<string, unknown>): string | undefined => {
-  const explicit = stringValue(dataArg.command) || stringValue(dataArg.key) || stringValue(dataArg.button);
-  if (serviceArg === 'press' && explicit) {
-    return normalizeKey(explicit);
+  private assertOpen(): void {
+    if (this.isClosed) throw new Error('Panasonic Viera client is closed.');
   }
-  return keyMap[serviceArg];
-};
 
-const normalizeKey = (valueArg: string): string => {
-  if (valueArg.startsWith('NRC_')) {
-    return valueArg;
+  private track<TResult>(executeArg: () => Promise<TResult>): Promise<TResult> {
+    if (this.operations.size !== 0) return Promise.reject(new Error('Panasonic Viera has an active operation.'));
+    const operation = Promise.resolve().then(executeArg).finally(() => this.operations.delete(operation));
+    this.operations.add(operation);
+    return operation;
   }
-  const normalized = valueArg.toUpperCase().replace(/[^A-Z0-9]+/g, '_');
-  const aliases: Record<string, string> = {
-    PLAY: 'NRC_PLAY-ONOFF',
-    PAUSE: 'NRC_PAUSE-ONOFF',
-    STOP: 'NRC_STOP-ONOFF',
-    POWER: 'NRC_POWER-ONOFF',
-    VOLUME_UP: 'NRC_VOLUP-ONOFF',
-    VOLUME_DOWN: 'NRC_VOLDOWN-ONOFF',
-    MUTE: 'NRC_MUTE-ONOFF',
-    ENTER: 'NRC_ENTER-ONOFF',
-    UP: 'NRC_UP-ONOFF',
-    DOWN: 'NRC_DOWN-ONOFF',
-    LEFT: 'NRC_LEFT-ONOFF',
-    RIGHT: 'NRC_RIGHT-ONOFF',
-    HOME: 'NRC_HOME-ONOFF',
-    MENU: 'NRC_MENU-ONOFF',
-    BACK: 'NRC_RETURN-ONOFF',
-  };
-  return aliases[normalized] || `NRC_${normalized}-ONOFF`;
-};
-
-const deriveSession = (encryptionKeyArg: string): IPanasonicVieraSession => {
-  const iv = Buffer.from(encryptionKeyArg, 'base64').subarray(0, 16);
-  if (iv.length !== 16) {
-    throw new Error('Panasonic Viera encryptionKey must decode to a 16 byte AES IV.');
-  }
-  const key = Buffer.alloc(16);
-  for (let index = 0; index < 16; index += 4) {
-    key[index] = iv[index + 2];
-    key[index + 1] = iv[index + 3];
-    key[index + 2] = iv[index];
-    key[index + 3] = iv[index + 1];
-  }
-  return { key, iv, hmacKey: Buffer.concat([iv, iv]) };
-};
-
-const uint32be = (valueArg: number): Buffer => {
-  const buffer = Buffer.alloc(4);
-  buffer.writeUInt32BE(valueArg, 0);
-  return buffer;
-};
-
-const parseDeviceInfo = (xmlArg: string): Record<string, unknown> => ({
-  UDN: extractXmlValue(xmlArg, 'UDN'),
-  friendlyName: extractXmlValue(xmlArg, 'friendlyName'),
-  manufacturer: extractXmlValue(xmlArg, 'manufacturer'),
-  modelName: extractXmlValue(xmlArg, 'modelName'),
-  modelNumber: extractXmlValue(xmlArg, 'modelNumber'),
-});
-
-const extractXmlValue = (xmlArg: string, tagArg: string): string | undefined => {
-  const pattern = new RegExp(`<(?:\\w+:)?${tagArg}[^>]*>([\\s\\S]*?)</(?:\\w+:)?${tagArg}>`, 'i');
-  const match = pattern.exec(xmlArg);
-  return match?.[1]?.trim();
-};
-
-const escapeXml = (valueArg: string): string => valueArg.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
-
-const normalizeBaseUrl = (valueArg: string, portArg: number | undefined, useTlsArg?: boolean): URL | undefined => {
-  try {
-    const parsed = new URL(valueArg.includes('://') ? valueArg : `${useTlsArg ? 'https' : 'http'}://${valueArg}`);
-    if (portArg) {
-      parsed.port = String(portArg);
-    }
-    parsed.pathname = '';
-    parsed.search = '';
-    parsed.hash = '';
-    return parsed;
-  } catch {
-    return undefined;
-  }
-};
-
-const stringValue = (valueArg: unknown): string | undefined => {
-  return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
-};
-
-const numberValue = (valueArg: unknown): number | undefined => {
-  if (typeof valueArg === 'number' && Number.isFinite(valueArg)) {
-    return valueArg;
-  }
-  if (typeof valueArg === 'string' && valueArg.trim() && Number.isFinite(Number(valueArg))) {
-    return Number(valueArg);
-  }
-  return undefined;
-};
-
-const booleanValue = (valueArg: unknown): boolean | undefined => {
-  if (typeof valueArg === 'boolean') {
-    return valueArg;
-  }
-  if (typeof valueArg === 'number') {
-    return valueArg !== 0;
-  }
-  if (typeof valueArg === 'string') {
-    if (valueArg === '1' || valueArg.toLowerCase() === 'true') {
-      return true;
-    }
-    if (valueArg === '0' || valueArg.toLowerCase() === 'false') {
-      return false;
-    }
-  }
-  return undefined;
-};
-
-const clone = <TValue>(valueArg: TValue): TValue => JSON.parse(JSON.stringify(valueArg)) as TValue;
-
-const errorMessage = (errorArg: unknown): string => errorArg instanceof Error ? errorArg.message : String(errorArg);
+}

package/ts/integrations/panasonic_viera/panasonic_viera.classes.configflow.ts

@@ -1,9 +1,73 @@
-import { SimpleLocalConfigFlow } from '../../core/index.js';
+import { NativeIntegrationOwner, type INativeIntegrationOwnerOptions, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
+import type { INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
+import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { PanasonicVieraClient } from './panasonic_viera.classes.client.js';
+import { createPanasonicVieraDiscoveryDescriptor } from './panasonic_viera.discovery.js';
 import type { IPanasonicVieraConfig } from './panasonic_viera.types.js';
-import { panasonicVieraProfile } from './panasonic_viera.types.js';
+import { normalizePanasonicVieraConfig, panasonicVieraRecord } from './panasonic_viera.validation.js';
 
-export class PanasonicVieraConfigFlow extends SimpleLocalConfigFlow<IPanasonicVieraConfig> {
-  constructor() {
-    super(panasonicVieraProfile);
+export class PanasonicVieraConfigFlow implements IConfigFlow<IPanasonicVieraConfig> {
+  private readonly scope: NativeIntegrationScope;
+  private readonly clients = new Set<PanasonicVieraClient>();
+  private submitting = false;
+
+  public constructor(optionsArg: INativeIntegrationOwnerOptions = {}, scopeArg?: NativeIntegrationScope) {
+    this.scope = scopeArg ?? new NativeIntegrationOwner('panasonic_viera', optionsArg).createFlowScope();
+  }
+
+  public start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IPanasonicVieraConfig>> {
+    return this.scope.run(contextArg, undefined, async (lease) => {
+      const match = await createPanasonicVieraDiscoveryDescriptor().getValidators()[0].validate(candidateArg, {});
+      lease.assertOpen();
+      if (!match.matched || !match.candidate) return { kind: 'error', error: match.reason };
+      const host = match.candidate.host;
+      const context = lease.context;
+      return {
+        kind: 'form', title: 'Connect selected plaintext Panasonic NRC',
+        description: 'Select the exact description URL, UPnP UDN and model for the host-selected home. Only advertised keys are supported; encrypted/PIN TVs are refused.',
+        fields: [
+          { name: 'descriptionUrl', label: 'Selected HTTP UPnP description URL', type: 'text', required: true },
+          { name: 'expectedUdn', label: 'Selected UPnP UUID', type: 'text', required: true },
+          { name: 'expectedModelName', label: 'Selected exact model name', type: 'text', required: true },
+          { name: 'allowUnencryptedLan', label: 'Acknowledge unauthenticated plaintext LAN', type: 'boolean', required: true },
+          { name: 'name', label: 'Name', type: 'text' },
+        ],
+        submit: (valuesArg) => this.submit(host, valuesArg, context),
+      };
+    });
+  }
+
+  public destroy(): Promise<void> { return this.scope.close(); }
+
+  public retryCleanup(): Promise<void> { return this.scope.retryCleanup(); }
+
+  private async submit(hostArg: string | undefined, valuesArg: Record<string, unknown>, contextArg: INativeAdmissionContext): Promise<IConfigFlowStep<IPanasonicVieraConfig>> {
+    // Fence stale form closures even when another submission is in flight.
+    this.scope.admit(contextArg);
+    if (this.submitting) throw new Error('Panasonic Viera config-flow admission is already in progress.');
+    this.submitting = true;
+    try {
+      const values = panasonicVieraRecord(valuesArg, ['homeId', 'descriptionUrl', 'expectedUdn', 'expectedModelName', 'allowUnencryptedLan', 'name', 'timeoutMs', 'maxResponseBytes']);
+      if (values.homeId !== undefined && values.homeId !== contextArg.homeId) throw new Error('Panasonic Viera form home does not match the selected host home.');
+      const config = normalizePanasonicVieraConfig({ ...values, host: hostArg, homeId: contextArg.homeId });
+      return await this.scope.run(contextArg, config.homeId, async (lease) => {
+        const client = new PanasonicVieraClient(config, { ...lease.context, abortSignal: lease.signal });
+        this.clients.add(client);
+        let attemptedCleanup = false;
+        lease.own(async () => {
+          if (attemptedCleanup) await client.retryCleanup();
+          else { attemptedCleanup = true; await client.destroy(); }
+          this.clients.delete(client);
+        });
+        await client.start(lease.signal);
+        lease.assertOpen();
+        if (client.isClosed) throw new Error('Panasonic Viera config-flow admission was cancelled.');
+        return { kind: 'done', title: 'Selected Panasonic NRC admitted', config };
+      });
+    } catch (errorArg) {
+      // Cleanup rejection retains its original evidence and lease; admission errors are form results.
+      if (errorArg instanceof AggregateError) throw errorArg;
+      return { kind: 'error', error: errorArg instanceof Error ? errorArg.message : 'Panasonic Viera admission failed.' };
+    } finally { this.submitting = false; }
   }
 }