@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/panasonic_viera/panasonic_viera.classes.integration.ts

@@ -1,23 +1,155 @@
-import { SimpleLocalIntegration, SimpleLocalRuntime, type IIntegrationRuntime, type IIntegrationSetupContext } from '../../core/index.js';
+import type * as plugins from '../../plugins.js';
+import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import { NativeIntegrationOwner, type INativeIntegrationOwnerOptions, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { PanasonicVieraClient } from './panasonic_viera.classes.client.js';
 import { PanasonicVieraConfigFlow } from './panasonic_viera.classes.configflow.js';
 import { createPanasonicVieraDiscoveryDescriptor } from './panasonic_viera.discovery.js';
-import type { IPanasonicVieraConfig } from './panasonic_viera.types.js';
+import { PanasonicVieraMapper } from './panasonic_viera.mapper.js';
+import type { IPanasonicVieraConfig, IPanasonicVieraSnapshot, TPanasonicVieraKey } from './panasonic_viera.types.js';
 import { panasonicVieraDomain, panasonicVieraProfile } from './panasonic_viera.types.js';
+import { drainPanasonicVieraCleanup, normalizePanasonicVieraConfig, panasonicVieraRecord } from './panasonic_viera.validation.js';
 
-export class PanasonicVieraIntegration extends SimpleLocalIntegration<IPanasonicVieraConfig> {
+export class PanasonicVieraIntegration extends BaseIntegration<IPanasonicVieraConfig> {
   public readonly domain = panasonicVieraDomain;
+  public readonly displayName = 'Panasonic Viera';
+  public readonly status = 'control-runtime';
   public readonly discoveryDescriptor = createPanasonicVieraDiscoveryDescriptor();
-  public readonly configFlow = new PanasonicVieraConfigFlow();
+  public readonly configFlow: PanasonicVieraConfigFlow;
+  public readonly metadata = panasonicVieraProfile.metadata;
+  private readonly owner: NativeIntegrationOwner;
+  // Failed cleanup stays in this map and on the shared owner's bounded lease.
+  private readonly clients = new Map<PanasonicVieraClient, PanasonicVieraRuntime | undefined>();
 
-  constructor() {
-    super(panasonicVieraProfile);
+  public constructor(optionsArg: INativeIntegrationOwnerOptions = {}) {
+    super();
+    this.owner = new NativeIntegrationOwner(this.domain, optionsArg);
+    this.configFlow = new PanasonicVieraConfigFlow({}, this.owner.createFlowScope());
   }
 
-  public async setup(configArg: IPanasonicVieraConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new SimpleLocalRuntime(panasonicVieraProfile, new PanasonicVieraClient(configArg));
+  public setup(configArg: IPanasonicVieraConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    const config = normalizePanasonicVieraConfig(configArg);
+    return this.owner.runSetup(contextArg, config.homeId, async (lease) => {
+      const client = new PanasonicVieraClient(config, { ...lease.context, abortSignal: lease.signal });
+      this.clients.set(client, undefined);
+      let attemptedCleanup = false;
+      lease.own(async () => {
+        const runtime = this.clients.get(client);
+        if (attemptedCleanup) await (runtime ? runtime.retryCleanupOwned() : client.retryCleanup());
+        else {
+          attemptedCleanup = true;
+          await (runtime ? runtime.closeOwned() : client.destroy());
+        }
+        this.clients.delete(client);
+      });
+      const snapshot = await client.start(lease.signal);
+      lease.assertOpen();
+      if (client.isClosed) throw new Error('Panasonic Viera setup was cancelled.');
+      const runtime = new PanasonicVieraRuntime(client, snapshot, lease);
+      this.clients.set(client, runtime);
+      lease.promoteToRuntime();
+      return runtime;
+    });
   }
+
+  public destroy(): Promise<void> { return this.owner.close(); }
+
+  public retryCleanup(): Promise<void> { return this.owner.retryCleanup(); }
 }
 
 export class HomeAssistantPanasonicVieraIntegration extends PanasonicVieraIntegration {}
+
+class PanasonicVieraRuntime implements IIntegrationRuntime {
+  public readonly domain = panasonicVieraDomain;
+  private readonly deviceId: string;
+  private readonly operations = new Set<Promise<unknown>>();
+  private closePromise?: Promise<void>;
+
+  public constructor(private readonly client: PanasonicVieraClient, private readonly admittedSnapshot: IPanasonicVieraSnapshot, private readonly lease: INativeSetupLease) {
+    this.deviceId = PanasonicVieraMapper.deviceId(admittedSnapshot);
+  }
+
+  public isHealthy(): boolean { return this.client.isHealthy; }
+
+  public devices(abortSignalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    return this.track(async () => PanasonicVieraMapper.toDevices(await this.client.getSnapshot(abortSignalArg)));
+  }
+
+  public entities(): Promise<IIntegrationEntity[]> {
+    return this.track(async () => PanasonicVieraMapper.toEntities(await this.client.getSnapshot()));
+  }
+
+  public callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    return this.track(() => this.performService(requestArg));
+  }
+
+  private async performService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    const request = panasonicVieraRecord(requestArg, ['domain', 'service', 'target', 'data']);
+    if (request.domain !== this.domain && request.domain !== 'button' || request.service !== 'press') {
+      throw new TypeError('Panasonic Viera supports exact-target button.press only.');
+    }
+    const target = panasonicVieraRecord(request.target, ['deviceId', 'entityId']);
+    if (target.deviceId !== undefined && target.deviceId !== this.deviceId || target.deviceId === undefined && target.entityId === undefined) {
+      throw new TypeError('Panasonic Viera requires an exact connected target.');
+    }
+    const data = request.data === undefined ? {} : panasonicVieraRecord(request.data, ['key']);
+    const snapshot = await this.client.getSnapshot();
+    let key: TPanasonicVieraKey;
+    if (target.entityId !== undefined) {
+      const entityKey = snapshot.profile.keys.find((keyArg) => PanasonicVieraMapper.keyEntityId(snapshot, keyArg) === target.entityId);
+      if (!entityKey || data.key !== undefined && data.key !== entityKey) throw new TypeError('Panasonic Viera button target and key must agree.');
+      key = entityKey;
+    } else key = this.admittedKey(snapshot, data.key);
+    return { success: true, data: await this.client.sendKey(key) };
+  }
+
+  public writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
+    return this.track(() => this.performWrite(requestArg, abortSignalArg));
+  }
+
+  private async performWrite(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
+    const request = panasonicVieraRecord(requestArg, ['device', 'feature', 'value']);
+    const device = panasonicVieraRecord(request.device, ['id', 'integrationDomain', 'name', 'room', 'protocol', 'manufacturer', 'model', 'online', 'features', 'state', 'metadata']);
+    if (device.id !== this.deviceId || device.integrationDomain !== this.domain) throw new TypeError('Panasonic Viera feature target belongs to another connection.');
+    if (device.metadata !== undefined && panasonicVieraRecord(device.metadata).homeId !== this.admittedSnapshot.homeId) {
+      throw new TypeError('Panasonic Viera feature target belongs to another home.');
+    }
+    const feature = panasonicVieraRecord(request.feature, ['id', 'capability', 'name', 'readable', 'writable', 'unit']);
+    if (feature.id !== 'remote_key' || feature.capability !== 'media' || feature.readable !== false || feature.writable !== true || feature.unit !== undefined) {
+      throw new TypeError('Panasonic Viera writes require the connected write-only remote_key feature.');
+    }
+    const snapshot = await this.client.getSnapshot(abortSignalArg);
+    return { success: true, data: await this.client.sendKey(this.admittedKey(snapshot, request.value), abortSignalArg) };
+  }
+
+  public destroy(): Promise<void> { return this.lease.close(); }
+
+  /** The lease owns this logical drain, including work beyond an individual protocol call. */
+  public closeOwned(): Promise<void> {
+    if (!this.closePromise) {
+      const operations = [...this.operations];
+      this.closePromise = Promise.resolve().then(() => drainPanasonicVieraCleanup([this.client.destroy()], operations,
+        'Panasonic Viera runtime cleanup failed.'));
+    }
+    return this.closePromise;
+  }
+
+  public retryCleanupOwned(): Promise<void> {
+    return drainPanasonicVieraCleanup([this.client.retryCleanup()], [...this.operations], 'Panasonic Viera runtime explicit cleanup retry failed.');
+  }
+
+  private track<TResult>(executeArg: () => Promise<TResult>): Promise<TResult> {
+    try { this.lease.assertOpen(); } catch (errorArg) { return Promise.reject(errorArg); }
+    if (this.closePromise || this.client.isClosed) return Promise.reject(new Error('Panasonic Viera runtime is closed.'));
+    if (this.operations.size !== 0) return Promise.reject(new Error('Panasonic Viera runtime has an active operation.'));
+    const operation = Promise.resolve().then(executeArg).finally(() => this.operations.delete(operation));
+    this.operations.add(operation);
+    return operation;
+  }
+
+  private admittedKey(snapshotArg: IPanasonicVieraSnapshot, valueArg: unknown): TPanasonicVieraKey {
+    const key = snapshotArg.profile.keys.find((keyArg) => keyArg === valueArg);
+    if (!key) throw new TypeError('Panasonic Viera key was not admitted for this connection.');
+    return key;
+  }
+}

package/ts/integrations/panasonic_viera/panasonic_viera.discovery.ts

@@ -1,4 +1,33 @@
-import { createSimpleLocalDiscoveryDescriptor } from '../../core/index.js';
-import { panasonicVieraProfile } from './panasonic_viera.types.js';
+import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
+import { panasonicVieraRecord } from './panasonic_viera.validation.js';
 
-export const createPanasonicVieraDiscoveryDescriptor = () => createSimpleLocalDiscoveryDescriptor(panasonicVieraProfile);
+class PanasonicVieraManualMatcher implements IDiscoveryMatcher {
+  public readonly id = 'panasonic_viera-manual-match';
+  public readonly source = 'manual';
+  public async matches(inputArg: unknown): Promise<IDiscoveryMatch> {
+    try {
+      const input = panasonicVieraRecord(inputArg);
+      if (input.integrationDomain !== 'panasonic_viera' || typeof input.host !== 'string' || !input.host) {
+        return { matched: false, confidence: 'low', reason: 'Select an explicit Panasonic Viera manual endpoint.' };
+      }
+      const candidate: IDiscoveryCandidate = { source: 'manual', integrationDomain: 'panasonic_viera', host: input.host,
+        metadata: input.metadata === undefined ? undefined : panasonicVieraRecord(input.metadata) };
+      return { matched: true, confidence: 'low', reason: 'Manual endpoint hint only; setup must verify the selected description and current NRC service.', candidate };
+    } catch {
+      return { matched: false, confidence: 'low', reason: 'Invalid Panasonic Viera manual hint.' };
+    }
+  }
+}
+
+class PanasonicVieraCandidateValidator implements IDiscoveryValidator {
+  public readonly id = 'panasonic_viera-candidate-validator';
+  public async validate(candidateArg: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
+    return new PanasonicVieraManualMatcher().matches(candidateArg);
+  }
+}
+
+export function createPanasonicVieraDiscoveryDescriptor(): DiscoveryDescriptor {
+  return new DiscoveryDescriptor({ integrationDomain: 'panasonic_viera', displayName: 'Panasonic Viera' })
+    .addMatcher(new PanasonicVieraManualMatcher()).addValidator(new PanasonicVieraCandidateValidator());
+}

package/ts/integrations/panasonic_viera/panasonic_viera.mapper.ts

@@ -1,173 +1,46 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
-import { SimpleLocalMapper, type IIntegrationEntity, type ISimpleLocalEntitySnapshot, type ISimpleLocalSnapshot, type ISimpleLocalSnapshotOptions, type TSimpleLocalRawData } from '../../core/index.js';
-import type { IPanasonicVieraConfig, IPanasonicVieraRawApiData, TPanasonicVieraRawData } from './panasonic_viera.types.js';
-import { panasonicVieraDefaultName, panasonicVieraDefaultPort, panasonicVieraProfile } from './panasonic_viera.types.js';
+import type * as plugins from '../../plugins.js';
+import { SimpleLocalMapper } from '../../core/classes.simplelocalintegration.js';
+import type { IIntegrationEntity, ISimpleLocalSnapshot } from '../../core/index.js';
+import type { IPanasonicVieraOfflineConfig, IPanasonicVieraSnapshot, TPanasonicVieraKey, TPanasonicVieraRawData } from './panasonic_viera.types.js';
+import { panasonicVieraDomain } from './panasonic_viera.types.js';
 
 export class PanasonicVieraMapper {
-  public static toSnapshot(optionsArg: Omit<ISimpleLocalSnapshotOptions<IPanasonicVieraConfig>, 'profile'>): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ ...optionsArg, profile: panasonicVieraProfile, rawData: this.normalizeRawData(optionsArg.rawData, optionsArg.config) });
+  public static deviceId(snapshotArg: Pick<IPanasonicVieraSnapshot, 'homeId' | 'profile'>): string {
+    return `panasonic_viera:${encodeURIComponent(snapshotArg.homeId)}:${encodeURIComponent(snapshotArg.profile.identity.udn)}`;
   }
 
-  public static toSnapshotFromRaw(configArg: IPanasonicVieraConfig, rawDataArg: TSimpleLocalRawData | TPanasonicVieraRawData): ISimpleLocalSnapshot {
-    return this.toSnapshot({ config: configArg, rawData: rawDataArg, online: true, source: 'manual' });
+  public static keyEntityId(snapshotArg: Pick<IPanasonicVieraSnapshot, 'homeId' | 'profile'>, keyArg: TPanasonicVieraKey): string {
+    return `${this.deviceId(snapshotArg)}:key:${keyArg}`;
   }
 
-  public static toDevices(snapshotArg: ISimpleLocalSnapshot): shxInterfaces.data.IDeviceDefinition[] {
-    return SimpleLocalMapper.toDevices(panasonicVieraProfile, snapshotArg);
+  public static toDevices(snapshotArg: IPanasonicVieraSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    const identity = snapshotArg.profile.identity;
+    return [{
+      id: this.deviceId(snapshotArg), integrationDomain: panasonicVieraDomain,
+      name: snapshotArg.name, manufacturer: identity.manufacturer, model: identity.modelName,
+      protocol: 'http', online: true,
+      features: [{ id: 'remote_key', capability: 'media', name: 'Remote key', readable: false, writable: snapshotArg.profile.keys.length > 0 }],
+      state: [],
+      metadata: { homeId: snapshotArg.homeId, udn: identity.udn, family: snapshotArg.profile.family,
+        advertisedKeys: [...snapshotArg.profile.keys], observedAt: identity.observedAt,
+        lanAuthenticated: false, confirmation: 'soap-response' },
+    }];
   }
 
-  public static toEntities(snapshotArg: ISimpleLocalSnapshot): IIntegrationEntity[] {
-    return SimpleLocalMapper.toEntities(panasonicVieraProfile, snapshotArg);
+  public static toEntities(snapshotArg: IPanasonicVieraSnapshot): IIntegrationEntity<null>[] {
+    return snapshotArg.profile.keys.map((keyArg) => ({
+      id: this.keyEntityId(snapshotArg, keyArg), uniqueId: this.keyEntityId(snapshotArg, keyArg),
+      deviceId: this.deviceId(snapshotArg), integrationDomain: panasonicVieraDomain, platform: 'button',
+      name: `${snapshotArg.name} ${keyArg}`, state: null, available: true,
+      attributes: { key: keyArg, confirmation: 'soap-response', observedAt: snapshotArg.profile.identity.observedAt },
+    }));
   }
 
-  public static slug(valueArg: unknown): string {
-    return SimpleLocalMapper.slug(valueArg);
-  }
-
-  public static normalizeRawData(rawDataArg: unknown, configArg: IPanasonicVieraConfig): unknown {
-    const parsedRawData = parseMaybeJson(rawDataArg);
-    const rawObject = objectValue(parsedRawData);
-    if (!rawObject || rawObject.device || Array.isArray(rawObject.entities)) {
-      return parsedRawData;
-    }
-
-    const deviceInfo = objectValue(rawObject.deviceInfo);
-    if (!deviceInfo && rawObject.volume === undefined && rawObject.muted === undefined) {
-      return parsedRawData;
-    }
-
-    const host = configArg.host || hostFromUrl(configArg.url);
-    const port = configArg.port || (host ? panasonicVieraDefaultPort : undefined);
-    const name = configArg.name || stringValue(deviceInfo?.friendlyName) || stringValue(deviceInfo?.FriendlyName) || panasonicVieraDefaultName;
-    const manufacturer = stringValue(deviceInfo?.manufacturer) || stringValue(deviceInfo?.Manufacturer) || 'Panasonic';
-    const model = stringValue(deviceInfo?.modelNumber) || stringValue(deviceInfo?.modelName) || stringValue(deviceInfo?.ModelNumber) || 'Panasonic Viera';
-    const udn = stringValue(deviceInfo?.UDN) || stringValue(deviceInfo?.udn);
-    const volume = numberValue(rawObject.volume);
-    const muted = booleanValue(rawObject.muted);
-    const entities: ISimpleLocalEntitySnapshot[] = [
-      {
-        id: 'media_player',
-        name,
-        platform: 'media_player',
-        state: rawObject.state || 'on',
-        writable: true,
-        attributes: cleanAttributes({
-          volumeLevel: volume === undefined ? undefined : volume / 100,
-          volumePercent: volume,
-          muted,
-          tvType: rawObject.tvType,
-        }),
-      },
-      {
-        id: 'remote',
-        name: `${name} Remote`,
-        platform: 'button',
-        state: false,
-        writable: true,
-        attributes: { action: 'press' },
-      },
-    ];
-
-    if (volume !== undefined) {
-      entities.push({
-        id: 'volume',
-        name: 'Volume',
-        platform: 'sensor',
-        state: volume,
-        unit: '%',
-        deviceClass: 'volume',
-        attributes: { source: 'RenderingControl.GetVolume' },
-      });
-    }
-    if (muted !== undefined) {
-      entities.push({
-        id: 'muted',
-        name: 'Muted',
-        platform: 'binary_sensor',
-        state: muted,
-        attributes: { source: 'RenderingControl.GetMute' },
-      });
-    }
-
-    return {
-      device: {
-        id: configArg.uniqueId || configArg.deviceId || udn || (host ? `${host}:${port || panasonicVieraDefaultPort}` : undefined) || panasonicVieraDefaultName,
-        name,
-        manufacturer,
-        model,
-        serialNumber: udn,
-        host,
-        port,
-        protocol: 'http',
-        attributes: cleanAttributes({ udn, rawDeviceInfo: deviceInfo }),
-      },
-      entities,
-      online: true,
-      updatedAt: stringValue(rawObject.fetchedAt) || new Date().toISOString(),
-      source: 'http',
-      rawData: parsedRawData,
-    } satisfies ISimpleLocalSnapshot;
+  /** Pure conversion of supplied data; unavailable and read-only regardless of the input's claims. */
+  public static toSnapshotFromRaw(configArg: IPanasonicVieraOfflineConfig, rawDataArg: TPanasonicVieraRawData): ISimpleLocalSnapshot {
+    const profile = { domain: panasonicVieraDomain, displayName: 'Panasonic Viera offline data', status: 'read-only-runtime' as const,
+      platforms: ['sensor' as const], manufacturer: 'Panasonic', defaultName: 'Panasonic Viera offline data', metadata: {} };
+    const snapshot = SimpleLocalMapper.toSnapshot({ profile, config: configArg, rawData: rawDataArg, source: 'manual', online: false });
+    return { ...snapshot, online: false, source: 'manual', entities: snapshot.entities.map((entityArg) => ({ ...entityArg, available: false, writable: false })) };
   }
 }
-
-const parseMaybeJson = (valueArg: unknown): unknown => {
-  if (typeof valueArg !== 'string') {
-    return valueArg;
-  }
-  try {
-    return JSON.parse(valueArg) as IPanasonicVieraRawApiData;
-  } catch {
-    return valueArg;
-  }
-};
-
-const objectValue = (valueArg: unknown): Record<string, unknown> | undefined => {
-  return valueArg && typeof valueArg === 'object' && !Array.isArray(valueArg) ? valueArg as Record<string, unknown> : 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 cleanAttributes = (attributesArg: Record<string, unknown>): Record<string, unknown> => {
-  return Object.fromEntries(Object.entries(attributesArg).filter(([, valueArg]) => valueArg !== undefined && valueArg !== null && valueArg !== ''));
-};
-
-const hostFromUrl = (urlArg: string | undefined): string | undefined => {
-  if (!urlArg) {
-    return undefined;
-  }
-  try {
-    return new URL(urlArg.includes('://') ? urlArg : `http://${urlArg}`).hostname;
-  } catch {
-    return undefined;
-  }
-};

package/ts/integrations/panasonic_viera/panasonic_viera.types.ts

@@ -1,113 +1,69 @@
-import type { ISimpleLocalConfig, ISimpleLocalIntegrationProfile, ISimpleLocalSnapshot, TSimpleLocalRawData } from '../../core/index.js';
+import type * as plugins from '../../plugins.js';
+import type { ISimpleLocalConfig, ISimpleLocalSnapshot, TSimpleLocalRawData } from '../../core/index.js';
+import type { INativeIntegrationSetupContext } from '../../core/types.js';
 
-export const panasonicVieraDomain = "panasonic_viera";
-export const panasonicVieraDefaultName = "Panasonic Viera";
+export const panasonicVieraDomain = 'panasonic_viera';
+export const panasonicVieraDefaultName = 'Panasonic Viera';
 export const panasonicVieraDefaultPort = 55000;
 export const panasonicVieraDefaultTimeoutMs = 5000;
 
+export type TPanasonicVieraKey = plugins.ecobridgeDeviceManager.TPanasonicKey;
+export type TPanasonicVieraKeyReceipt = plugins.ecobridgeDeviceManager.IPanasonicKeyReceipt;
+
+export interface IPanasonicVieraConfig {
+  readonly homeId: string;
+  readonly host: string;
+  readonly descriptionUrl: string;
+  readonly expectedUdn: string;
+  readonly expectedModelName: string;
+  readonly allowUnencryptedLan: true;
+  readonly name?: string;
+  readonly timeoutMs?: number;
+  readonly maxResponseBytes?: number;
+}
+
+export interface IPanasonicVieraClientOptions extends INativeIntegrationSetupContext {
+  readonly onDestroyed?: () => void;
+}
+
+export interface IPanasonicVieraSnapshot {
+  readonly homeId: string;
+  readonly name: string;
+  readonly profile: plugins.ecobridgeDeviceManager.IPanasonicProfile;
+}
+
+/** Explicit data conversion only; this input cannot start the native integration. */
+export interface IPanasonicVieraOfflineConfig extends ISimpleLocalConfig {}
 export interface IPanasonicVieraRawApiData extends Record<string, unknown> {
   deviceInfo?: Record<string, unknown>;
   volume?: number | null;
   muted?: boolean | null;
-  tvType?: 'encrypted' | 'non_encrypted' | 'unknown';
   fetchedAt?: string;
 }
 export type TPanasonicVieraRawData = TSimpleLocalRawData | IPanasonicVieraRawApiData;
-export interface IPanasonicVieraSnapshot extends ISimpleLocalSnapshot {}
-export interface IPanasonicVieraConfig extends ISimpleLocalConfig {
-  url?: string;
-  macAddress?: string;
-  deviceId?: string;
-  appId?: string;
-  encryptionKey?: string;
-}
+export interface IPanasonicVieraOfflineSnapshot extends ISimpleLocalSnapshot {}
 export interface IHomeAssistantPanasonicVieraConfig extends IPanasonicVieraConfig {}
 
-export const panasonicVieraProfile: ISimpleLocalIntegrationProfile = {
+export const panasonicVieraProfile = Object.freeze({
   domain: panasonicVieraDomain,
-  displayName: "Panasonic Viera",
-  manufacturer: "Panasonic Viera",
-  model: "Panasonic Viera local integration",
-  defaultName: panasonicVieraDefaultName,
-  defaultPort: panasonicVieraDefaultPort,
-  defaultProtocol: 'http',
-  status: "control-runtime",
-  platforms: [
-    "button",
-    "media_player",
-  ],
-  serviceDomains: [
-    "button",
-    "media_player",
-  ],
-  controlServices: [
-    "media_pause",
-    "media_next_track",
-    "media_play",
-    "media_previous_track",
-    "media_stop",
-    "press",
-    "turn_off",
-    "turn_on",
-    "volume_down",
-    "volume_mute",
-    "volume_set",
-    "volume_up",
-  ],
-  discoverySources: [
-    'manual',
-    'custom',
-  ],
-  discoveryKeywords: [
-    "panasonic_viera",
-    "Panasonic Viera",
-    "Panasonic",
-    "Viera",
-  ],
+  displayName: panasonicVieraDefaultName,
+  manufacturer: 'Panasonic',
+  status: 'control-runtime' as const,
+  platforms: ['button'],
+  controlServices: ['press'],
+  discoverySources: ['manual', 'custom'],
   metadata: {
-    "source": "home-assistant/core",
-    "upstreamPath": "homeassistant/components/panasonic_viera",
-    "upstreamDomain": "panasonic_viera",
-    "integrationType": "device",
-    "iotClass": "local_polling",
-    "requirements": [
-      "panasonic-viera==0.4.4",
-    ],
-    "configFlow": true,
-    "documentation": "https://www.home-assistant.io/integrations/panasonic_viera",
-    "loggers": [
-      "panasonic_viera",
-    ],
-    "runtime": {
-      "type": "control-runtime",
-      "services": [
-        "snapshot",
-        "status",
-        "refresh",
-        "media_pause",
-        "media_play",
-        "press",
-        "volume_down",
-        "volume_up",
-      ],
-      "platforms": [
-        "button",
-        "media_player",
-      ],
-      "controls": "native SOAP-over-HTTP when config.host/config.url is provided; injected executors remain supported",
-    },
-    "localApi": {
-      "implemented": [
-        "native SOAP-over-HTTP polling against /nrc/ddd.xml and /dmr/control_0 on port 55000",
-        "native SOAP-over-HTTP remote key, volume, and mute commands against /nrc/control_0 and /dmr/control_0",
-        "encrypted command transport when appId and encryptionKey are supplied",
-        "manual snapshots, rawData, snapshotProvider, and injected native clients remain supported",
-      ],
-      "explicitUnsupported": [
-        "interactive encrypted TV pairing/PIN enrollment is not exposed by this TypeScript config flow; provide appId and encryptionKey from an already paired client",
-        "UPnP event subscription callback server support from panasonic-viera is not implemented",
-        "Home Assistant entity registry migrations and repair flows",
-      ],
+    source: 'home-assistant/core',
+    upstreamPath: 'homeassistant/components/panasonic_viera',
+    upstreamDomain: panasonicVieraDomain,
+    integrationType: 'device',
+    iotClass: 'local_polling',
+    configFlow: true,
+    documentation: 'https://www.home-assistant.io/integrations/panasonic_viera',
+    runtime: {
+      type: 'control-runtime',
+      controls: 'Selected plaintext NRC, currently advertised finite keys, matching SOAP acknowledgements only.',
+      explicitUnsupported: ['PIN/encrypted families', 'pairing', 'power state', 'current input', 'absolute volume/mute', 'media playback', 'arbitrary SOAP'],
     },
   },
-};
+});

package/ts/integrations/panasonic_viera/panasonic_viera.validation.ts

@@ -0,0 +1,56 @@
+import type { IPanasonicVieraConfig } from './panasonic_viera.types.js';
+
+export function panasonicVieraRecord(valueArg: unknown, keysArg?: readonly string[]): Record<string, unknown> {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(valueArg))) {
+    throw new TypeError('Panasonic Viera input must be a plain data object.');
+  }
+  const result: Record<string, unknown> = {};
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || !descriptor || !('value' in descriptor) || !descriptor.enumerable ||
+      keysArg && !keysArg.includes(key)) throw new TypeError('Panasonic Viera input contains unsupported fields or accessors.');
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+
+export function panasonicVieraText(valueArg: unknown, nameArg: string, maximumArg = 256): string {
+  if (typeof valueArg !== 'string' || !valueArg.trim() || valueArg.length > maximumArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`Panasonic Viera ${nameArg} must be a bounded non-empty string without control characters.`);
+  }
+  return valueArg;
+}
+
+function optionalInteger(valueArg: unknown, minimumArg: number, maximumArg: number): number | undefined {
+  if (valueArg === undefined) return undefined;
+  if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < minimumArg || valueArg > maximumArg) {
+    throw new TypeError('Panasonic Viera numeric bound is invalid.');
+  }
+  return valueArg;
+}
+
+export function normalizePanasonicVieraConfig(valueArg: unknown): Readonly<IPanasonicVieraConfig> {
+  const config = panasonicVieraRecord(valueArg, ['homeId', 'host', 'descriptionUrl', 'expectedUdn', 'expectedModelName', 'allowUnencryptedLan', 'name', 'timeoutMs', 'maxResponseBytes']);
+  if (config.allowUnencryptedLan !== true) throw new TypeError('Panasonic Viera requires explicit allowUnencryptedLan: true.');
+  // The owning protocol validates the selected private address, exact description origin and UPnP identity.
+  return Object.freeze({
+    homeId: panasonicVieraText(config.homeId, 'homeId'),
+    host: panasonicVieraText(config.host, 'host'),
+    descriptionUrl: panasonicVieraText(config.descriptionUrl, 'descriptionUrl', 4096),
+    expectedUdn: panasonicVieraText(config.expectedUdn, 'expectedUdn'),
+    expectedModelName: panasonicVieraText(config.expectedModelName, 'expectedModelName'),
+    allowUnencryptedLan: true,
+    name: config.name === undefined ? undefined : panasonicVieraText(config.name, 'name'),
+    timeoutMs: optionalInteger(config.timeoutMs, 1, 60_000),
+    maxResponseBytes: optionalInteger(config.maxResponseBytes, 256, 1024 * 1024),
+  });
+}
+
+/** Cleanup failures remain observable after every admitted operation has settled. */
+export async function drainPanasonicVieraCleanup(cleanupsArg: readonly Promise<unknown>[], operationsArg: readonly Promise<unknown>[], messageArg: string): Promise<void> {
+  const [cleanups] = await Promise.all([Promise.allSettled(cleanupsArg), Promise.allSettled(operationsArg)]);
+  const errors: unknown[] = cleanups.filter((resultArg): resultArg is PromiseRejectedResult => resultArg.status === 'rejected').map((resultArg) => resultArg.reason);
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors, messageArg);
+}