@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/samsungtv/samsungtv.classes.configflow.ts

@@ -1,43 +1,42 @@
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
 import type { ISamsungtvConfig } from './samsungtv.types.js';
+import { normalizeSamsungtvConfig, samsungtvKeys, samsungtvObject } from './samsungtv.validation.js';
 
 export class SamsungtvConfigFlow implements IConfigFlow<ISamsungtvConfig> {
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<ISamsungtvConfig>> {
     void contextArg;
+    const metadata = candidateArg.metadata === undefined ? {} : samsungtvObject(candidateArg.metadata, 'Samsung TV candidate metadata');
+    const hints: Record<string, unknown> = {};
+    for (const field of ['httpOrigin', 'websocketOrigin', 'expectedDeviceId']) {
+      if (typeof metadata[field] === 'string') hints[field] = metadata[field];
+    }
     return {
-      kind: 'form',
-      title: 'Connect Samsung Smart TV',
-      description: 'Configure the local Samsung TV websocket endpoint. Pairing prompts and encrypted PIN mode are not handled by this native port.',
+      kind: 'form', title: 'Pair Samsung Smart TV',
+      description: 'Confirm this home, the exact TV UUID, explicit REST/WSS origins and trusted TV CA. Confirm the TV pairing prompt when using prompt mode. Pairing credentials are stored only in encrypted home-scoped persistence.',
       fields: [
-        { name: 'host', label: 'Host', type: 'text', required: true },
-        { name: 'port', label: 'Websocket port', type: 'number', required: false },
-        { name: 'token', label: 'Existing websocket token', type: 'password', required: false },
-        { name: 'name', label: 'Name', type: 'text', required: false },
-        { name: 'model', label: 'Model', type: 'text', required: false },
+        { name: 'homeId', label: 'Home ID', type: 'text', required: true },
+        { name: 'expectedDeviceId', label: 'Exact TV UUID', type: 'text', required: true },
+        { name: 'httpOrigin', label: 'REST origin', type: 'text', required: true },
+        { name: 'websocketOrigin', label: 'Verified WSS origin', type: 'text', required: true },
+        { name: 'pairingMode', label: 'Pairing mode', type: 'select', required: true,
+          options: [{ label: 'Existing encrypted pairing', value: 'existing' }, { label: 'Confirm TV pairing prompt', value: 'prompt' }] },
+        { name: 'certificateAuthority', label: 'Trusted TV CA PEM', type: 'text' },
+        { name: 'allowUnencryptedLocalDiscovery', label: 'Allow credential-free local HTTP discovery', type: 'boolean' },
       ],
       submit: async (valuesArg) => {
-        const host = String(valuesArg.host || candidateArg.host || '').trim();
-        if (!host) {
-          return { kind: 'error', error: 'Samsung TV host is required.' };
+        try {
+          const values = samsungtvObject(valuesArg, 'Samsung TV config form');
+          samsungtvKeys(values, ['homeId', 'expectedDeviceId', 'httpOrigin', 'websocketOrigin', 'pairingMode', 'certificateAuthority', 'allowUnencryptedLocalDiscovery']);
+          const config = normalizeSamsungtvConfig({
+            homeId: values.homeId, expectedDeviceId: values.expectedDeviceId ?? hints.expectedDeviceId,
+            httpOrigin: values.httpOrigin ?? hints.httpOrigin, websocketOrigin: values.websocketOrigin ?? hints.websocketOrigin,
+            pairingMode: values.pairingMode, certificateAuthority: values.certificateAuthority,
+            allowUnencryptedLocalDiscovery: values.allowUnencryptedLocalDiscovery,
+          });
+          return { kind: 'done', title: 'Samsung Smart TV configuration accepted', config };
+        } catch (errorArg) {
+          return { kind: 'error', error: errorArg instanceof Error ? errorArg.message : 'Samsung TV configuration is invalid.' };
         }
-
-        const portValue = valuesArg.port ?? candidateArg.port ?? 8001;
-        const port = typeof portValue === 'number' ? portValue : Number(portValue || 8001);
-        return {
-          kind: 'done',
-          title: 'Samsung Smart TV configured',
-          config: {
-            host,
-            port: Number.isFinite(port) ? port : 8001,
-            token: typeof valuesArg.token === 'string' && valuesArg.token ? valuesArg.token : undefined,
-            name: typeof valuesArg.name === 'string' && valuesArg.name ? valuesArg.name : candidateArg.name,
-            model: typeof valuesArg.model === 'string' && valuesArg.model ? valuesArg.model : candidateArg.model,
-            manufacturer: candidateArg.manufacturer || 'Samsung',
-            macAddress: candidateArg.macAddress,
-            ssdpRenderingControlLocation: typeof candidateArg.metadata?.ssdpRenderingControlLocation === 'string' ? candidateArg.metadata.ssdpRenderingControlLocation : undefined,
-            ssdpMainTvAgentLocation: typeof candidateArg.metadata?.ssdpMainTvAgentLocation === 'string' ? candidateArg.metadata.ssdpMainTvAgentLocation : undefined,
-          },
-        };
       },
     };
   }

package/ts/integrations/samsungtv/samsungtv.classes.integration.ts

@@ -1,11 +1,31 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
+import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import type { IIntegrationEntity, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { NoSqlConfigStore } from '../../core/classes.configstore.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { SamsungtvClient } from './samsungtv.classes.client.js';
 import { SamsungtvConfigFlow } from './samsungtv.classes.configflow.js';
 import { createSamsungtvDiscoveryDescriptor } from './samsungtv.discovery.js';
 import { SamsungtvMapper } from './samsungtv.mapper.js';
-import type { ISamsungtvConfig } from './samsungtv.types.js';
+import type { ISamsungtvConfig, ISamsungtvIntegrationOptions, ISamsungtvSnapshot, TSamsungtvRemoteKey } from './samsungtv.types.js';
+import { samsungtvKeys, samsungtvObject } from './samsungtv.validation.js';
+
+const serviceKeys = {
+  turn_off: 'KEY_POWEROFF', media_play: 'KEY_PLAY', media_pause: 'KEY_PAUSE', media_stop: 'KEY_STOP',
+  volume_up: 'KEY_VOLUP', volume_down: 'KEY_VOLDOWN',
+} satisfies Record<string, TSamsungtvRemoteKey>;
+
+const remoteKey = (valueArg: unknown): TSamsungtvRemoteKey => {
+  const key = plugins.ecobridgeDeviceManager.samsungTvRemoteKeys.find((keyArg) => keyArg === valueArg);
+  if (!key) throw new TypeError('Samsung TV remote command requires one exact supported KEY_ code.');
+  return key;
+};
+
+const failure = (errorArg: unknown): IServiceCallResult => {
+  if (errorArg instanceof plugins.ecobridgeDeviceManager.SamsungTvProtocolError) {
+    return { success: false, error: errorArg.message, data: { code: errorArg.code, effectOutcome: errorArg.effectOutcome } };
+  }
+  return { success: false, error: errorArg instanceof Error ? errorArg.message : 'Samsung TV operation failed.', data: { effectOutcome: 'not-sent' } };
+};
 
 export class SamsungtvIntegration extends BaseIntegration<ISamsungtvConfig> {
   public readonly domain = 'samsungtv';
@@ -14,155 +34,111 @@ export class SamsungtvIntegration extends BaseIntegration<ISamsungtvConfig> {
   public readonly discoveryDescriptor = createSamsungtvDiscoveryDescriptor();
   public readonly configFlow = new SamsungtvConfigFlow();
   public readonly metadata = {
-    source: 'home-assistant/core',
-    upstreamPath: 'homeassistant/components/samsungtv',
-    upstreamDomain: 'samsungtv',
-    integrationType: 'device',
-    iotClass: 'local_push',
-    qualityScale: 'gold',
-    requirements: [
-      'getmac==0.9.5',
-      'samsungctl[websocket]==0.7.1',
-      'samsungtvws[async,encrypted]==2.7.2',
-      'wakeonlan==3.1.0',
-      'async-upnp-client==0.46.2',
-    ],
-    dependencies: ['ssdp'],
-    codeowners: ['@chemelli74', '@epenet'],
+    source: 'home-assistant/core', upstreamDomain: 'samsungtv', integrationType: 'device', iotClass: 'local_poll',
+    localApi: { implemented: ['verified UUID and WSS pairing', 'encrypted home-scoped pairing', 'fresh REST observations', 'single supported remote Click'],
+      explicitUnsupported: ['optimistic state', 'automatic retries or replay', 'legacy TCP/PIN', 'play_pause', 'app launch', 'absolute volume/mute assignment', 'wake-on-LAN', 'hold/release/repeated keys'] },
   };
+  readonly #runtimes = new Set<SamsungtvRuntime>();
+  readonly #pending = new Set<SamsungtvClient>();
+  #options?: ISamsungtvIntegrationOptions;
+  #destroyed = false;
+  #destroy?: Promise<void>;
+
+  constructor(optionsArg?: ISamsungtvIntegrationOptions) {
+    super();
+    this.#options = optionsArg ? { db: optionsArg.db, keyProvider: optionsArg.keyProvider } : undefined;
+  }
 
   public async setup(configArg: ISamsungtvConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new SamsungtvRuntime(new SamsungtvClient(configArg));
+    if (this.#destroyed) throw new Error('Samsung TV integration is destroyed.');
+    if (contextArg.configStore !== undefined && !(contextArg.configStore instanceof NoSqlConfigStore)) {
+      throw new TypeError('Samsung TV runtime requires an encrypted NoSqlConfigStore.');
+    }
+    const client = new SamsungtvClient(configArg, contextArg.configStore ?? this.#options, contextArg.abortSignal);
+    this.#pending.add(client);
+    try {
+      const snapshot = await client.getSnapshot(contextArg.abortSignal);
+      if (this.#destroyed) throw new Error('Samsung TV integration was destroyed during setup.');
+      const runtime = new SamsungtvRuntime(client, snapshot, () => this.#runtimes.delete(runtime));
+      this.#runtimes.add(runtime);
+      return runtime;
+    } catch (errorArg) { await client.destroy(); throw errorArg; }
+    finally { this.#pending.delete(client); }
   }
 
-  public async destroy(): Promise<void> {}
+  public destroy(): Promise<void> {
+    if (!this.#destroy) {
+      this.#destroyed = true;
+      this.#destroy = Promise.all([
+        ...[...this.#runtimes].map((runtimeArg) => runtimeArg.destroy()),
+        ...[...this.#pending].map((clientArg) => clientArg.destroy()),
+      ]).then(() => { this.#options = undefined; });
+    }
+    return this.#destroy;
+  }
 }
 
 export class HomeAssistantSamsungtvIntegration extends SamsungtvIntegration {}
 
 class SamsungtvRuntime implements IIntegrationRuntime {
-  public domain = 'samsungtv';
-
-  constructor(private readonly client: SamsungtvClient) {}
-
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return SamsungtvMapper.toDevices(await this.client.getSnapshot());
-  }
-
-  public async entities(): Promise<IIntegrationEntity[]> {
-    return SamsungtvMapper.toEntities(await this.client.getSnapshot());
+  public readonly domain = 'samsungtv';
+  constructor(private readonly client: SamsungtvClient, private readonly identity: ISamsungtvSnapshot, private readonly onDestroyed: () => void) {}
+  public isHealthy(): boolean { return this.client.isHealthy(); }
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    return SamsungtvMapper.toDevices(await this.client.getSnapshot(signalArg));
   }
+  public async entities(): Promise<IIntegrationEntity[]> { return SamsungtvMapper.toEntities(await this.client.getSnapshot()); }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
     try {
-      return await this.callServiceUnsafe(requestArg);
-    } catch (error) {
-      return { success: false, error: this.errorMessage(error) };
-    }
-  }
-
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
+      const request = samsungtvObject(requestArg, 'Samsung TV service request');
+      samsungtvKeys(request, ['domain', 'service', 'target', 'data']);
+      this.#assertTarget(request.target);
+      const data = request.data === undefined ? {} : samsungtvObject(request.data, 'Samsung TV service data');
+      if (request.domain === 'samsungtv' && request.service === 'snapshot') {
+        samsungtvKeys(data, []);
+        return { success: true, data: await this.client.getSnapshot() };
+      }
+      let key: TSamsungtvRemoteKey;
+      if (request.domain === 'remote' && request.service === 'send_command') {
+        samsungtvKeys(data, ['command']);
+        key = remoteKey(data.command);
+      } else if (request.domain === 'samsungtv' && request.service === 'send_key') {
+        samsungtvKeys(data, ['key']);
+        key = remoteKey(data.key);
+      } else if (request.domain === 'media_player') {
+        samsungtvKeys(data, []);
+        const service = typeof request.service === 'string' ? request.service : '';
+        key = remoteKey(Object.entries(serviceKeys).find(([serviceArg]) => serviceArg === service)?.[1]);
+      } else throw new TypeError('Samsung TV service is unsupported.');
+      return { success: true, data: await this.client.sendKey(key) };
+    } catch (errorArg) { return failure(errorArg); }
   }
 
-  private async callServiceUnsafe(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.domain === 'remote') {
-      return this.callRemoteService(requestArg);
-    }
-
-    if (requestArg.domain !== 'media_player') {
-      return { success: false, error: `Unsupported Samsung TV service domain: ${requestArg.domain}` };
-    }
-
-    if (requestArg.service === 'turn_on') {
-      await this.client.turnOn();
-      return { success: true };
-    }
-    if (requestArg.service === 'turn_off') {
-      await this.client.turnOff();
-      return { success: true };
-    }
-    if (requestArg.service === 'media_play' || requestArg.service === 'play') {
-      await this.client.play();
-      return { success: true };
-    }
-    if (requestArg.service === 'media_pause' || requestArg.service === 'pause') {
-      await this.client.pause();
-      return { success: true };
-    }
-    if (requestArg.service === 'media_play_pause' || requestArg.service === 'play_pause') {
-      await this.client.playPause();
-      return { success: true };
-    }
-    if (requestArg.service === 'media_stop' || requestArg.service === 'stop') {
-      await this.client.sendKeys(['KEY_STOP']);
-      return { success: true };
-    }
-    if (requestArg.service === 'media_next_track' || requestArg.service === 'next_track') {
-      await this.client.sendKeys(['KEY_CHUP']);
-      return { success: true };
-    }
-    if (requestArg.service === 'media_previous_track' || requestArg.service === 'previous_track') {
-      await this.client.sendKeys(['KEY_CHDOWN']);
-      return { success: true };
-    }
-    if (requestArg.service === 'volume_up') {
-      await this.client.sendKeys(['KEY_VOLUP']);
-      return { success: true };
-    }
-    if (requestArg.service === 'volume_down') {
-      await this.client.sendKeys(['KEY_VOLDOWN']);
-      return { success: true };
-    }
-    if (requestArg.service === 'volume_mute' || requestArg.service === 'mute') {
-      await this.client.sendKeys(['KEY_MUTE']);
-      return { success: true };
-    }
-    if (requestArg.service === 'volume_set') {
-      const volumeLevel = requestArg.data?.volume_level;
-      if (typeof volumeLevel !== 'number') {
-        return { success: false, error: 'Samsung TV volume_set requires data.volume_level.' };
-      }
-      await this.client.setVolumeLevel(volumeLevel);
-      return { success: true };
-    }
-    if (requestArg.service === 'select_source') {
-      const source = requestArg.data?.source;
-      if (typeof source !== 'string' || !source) {
-        return { success: false, error: 'Samsung TV select_source requires data.source.' };
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      const request = samsungtvObject(requestArg, 'Samsung TV feature write');
+      samsungtvKeys(request, ['device', 'feature', 'value']);
+      const device = samsungtvObject(request.device, 'Samsung TV feature device');
+      const feature = samsungtvObject(request.feature, 'Samsung TV feature');
+      if (device.id !== SamsungtvMapper.deviceId(this.identity) || device.integrationDomain !== this.domain) {
+        throw new TypeError('Samsung TV feature device is not owned by this runtime.');
       }
-      await this.client.selectSource(source);
-      return { success: true };
-    }
-
-    return { success: false, error: `Unsupported Samsung TV media_player service: ${requestArg.service}` };
+      if (feature.id !== 'remote_key') throw new TypeError('Samsung TV feature is not writable.');
+      return { success: true, data: await this.client.sendKey(remoteKey(request.value), signalArg) };
+    } catch (errorArg) { return failure(errorArg); }
   }
 
-  private async callRemoteService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.service !== 'send_command') {
-      return { success: false, error: `Unsupported Samsung TV remote service: ${requestArg.service}` };
-    }
-
-    const command = requestArg.data?.command;
-    const commands = Array.isArray(command) ? command : [command];
-    const keys = commands.filter((commandArg): commandArg is string => typeof commandArg === 'string' && Boolean(commandArg));
-    if (!keys.length) {
-      return { success: false, error: 'Samsung TV remote send_command requires data.command.' };
-    }
-
-    const repeatsValue = requestArg.data?.num_repeats ?? requestArg.data?.numRepeats ?? 1;
-    const repeats = typeof repeatsValue === 'number' && Number.isFinite(repeatsValue) ? Math.max(1, Math.floor(repeatsValue)) : 1;
-    for (let index = 0; index < repeats; index += 1) {
-      await this.client.sendKeys(keys);
-    }
-    return { success: true };
-  }
+  public async destroy(): Promise<void> { await this.client.destroy(); this.onDestroyed(); }
 
-  private errorMessage(errorArg: unknown): string {
-    if (errorArg instanceof Error) {
-      return errorArg.message;
+  #assertTarget(valueArg: unknown): void {
+    const target = samsungtvObject(valueArg, 'Samsung TV service target');
+    samsungtvKeys(target, ['deviceId', 'entityId']);
+    const deviceId = SamsungtvMapper.deviceId(this.identity);
+    if ((target.deviceId === undefined && target.entityId === undefined) ||
+      (target.deviceId !== undefined && target.deviceId !== deviceId) ||
+      (target.entityId !== undefined && target.entityId !== `${deviceId}:media_player`)) {
+      throw new TypeError('Samsung TV requires an exact owned device or media-player entity target.');
     }
-    return String(errorArg);
   }
 }