@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/kodi/kodi.classes.client.ts

@@ -1,372 +1,92 @@
-import type {
-  IKodiActivePlayer,
-  IKodiApplicationProperties,
-  IKodiConfig,
-  IKodiDeviceInfo,
-  IKodiJsonRpcRequest,
-  IKodiJsonRpcResponse,
-  IKodiMediaItem,
-  IKodiPlayerProperties,
-  IKodiSnapshot,
-  IKodiTime,
-  TKodiInputCommand,
-  TKodiJsonRpcParams,
-  TKodiMediaType,
-} from './kodi.types.js';
-
-const defaultPort = 8080;
-const defaultWsPort = 9090;
-const defaultTimeoutMs = 5000;
-
-const playerProperties = ['time', 'totaltime', 'speed', 'live', 'percentage', 'playlistid', 'position', 'repeat', 'shuffled'];
-const itemProperties = ['title', 'file', 'uniqueid', 'thumbnail', 'artist', 'albumartist', 'showtitle', 'album', 'season', 'episode', 'streamdetails'];
-
-export class KodiJsonRpcError extends Error {
-  constructor(public readonly method: string, public readonly code: number | undefined, messageArg: string, public readonly data?: unknown) {
-    super(`Kodi JSON-RPC ${method} failed${typeof code === 'number' ? ` (${code})` : ''}: ${messageArg}`);
-    this.name = 'KodiJsonRpcError';
-  }
-}
+import * as plugins from '../../plugins.js';
+import { NativeHomeAdmission, type INativeAdmissionContext } from '../../core/classes.nativehomeadmission.js';
+import type { IKodiClientOptions, IKodiConfig, IKodiNativeSnapshot, IKodiSetupContext } from './kodi.types.js';
+import { kodiKeys, kodiRecord, kodiSignal, normalizeKodiConfig } from './kodi.validation.js';
 
+/** Consumer lifecycle and home projection; the foundation owns all protocol work. */
 export class KodiClient {
-  private requestId = 1;
-
-  constructor(private readonly config: IKodiConfig) {}
-
-  public async getSnapshot(): Promise<IKodiSnapshot> {
-    if (this.config.snapshot) {
-      return this.normalizeSnapshot(this.cloneSnapshot(this.config.snapshot));
-    }
-    if (!this.config.host) {
-      return this.normalizeSnapshot({
-        deviceInfo: this.deviceInfoFromConfig(),
-        players: [],
-        online: false,
-        updatedAt: new Date().toISOString(),
-      });
-    }
-
-    const [application, players] = await Promise.all([
-      this.getApplicationProperties().catch(() => undefined),
-      this.getActivePlayers(),
-    ]);
-    const player = players[0];
-    const [playerPropertiesResult, item] = player ? await Promise.all([
-      this.getPlayerProperties(player.playerid).catch(() => undefined),
-      this.getPlayerItem(player.playerid).catch(() => undefined),
-    ]) : [undefined, undefined];
-
-    return this.normalizeSnapshot({
-      deviceInfo: {
-        ...this.deviceInfoFromConfig(),
-        name: this.config.name || this.config.deviceInfo?.name || application?.name || this.config.host,
-        version: this.versionString(application),
-      },
-      application,
-      players,
-      player,
-      playerProperties: playerPropertiesResult,
-      item,
-      online: true,
-      updatedAt: new Date().toISOString(),
-    });
-  }
-
-  public async ping(): Promise<boolean> {
-    const result = await this.callMethod<string>('JSONRPC.Ping');
-    return result === 'pong';
-  }
-
-  public async getApplicationProperties(): Promise<IKodiApplicationProperties> {
-    return this.callMethod<IKodiApplicationProperties>('Application.GetProperties', {
-      properties: ['name', 'version', 'volume', 'muted'],
-    });
-  }
-
-  public async getActivePlayers(): Promise<IKodiActivePlayer[]> {
-    return this.callMethod<IKodiActivePlayer[]>('Player.GetActivePlayers');
-  }
-
-  public async getPlayerProperties(playerIdArg: number): Promise<IKodiPlayerProperties> {
-    return this.callMethod<IKodiPlayerProperties>('Player.GetProperties', {
-      playerid: playerIdArg,
-      properties: playerProperties,
+  readonly #config: Readonly<IKodiConfig>;
+  readonly #context: INativeAdmissionContext;
+  readonly #protocol: plugins.ecobridgeDeviceManager.KodiProtocol;
+  readonly #lifetime = new AbortController();
+  readonly #parentSignal?: AbortSignal;
+  readonly #onParentAbort: () => void;
+  readonly #operations = new Set<Promise<unknown>>();
+  #closed = false;
+  #healthy = false;
+  #closePromise?: Promise<void>;
+
+  public constructor(config: IKodiConfig, context: IKodiSetupContext, options: IKodiClientOptions = {}) {
+    this.#config = normalizeKodiConfig(config);
+    this.#context = new NativeHomeAdmission('kodi').admit(context, this.#config.homeId);
+    const value = kodiRecord(options, 'client options');
+    kodiKeys(value, ['getBasicCredentials']);
+    this.#parentSignal = this.#context.abortSignal;
+    if (value.getBasicCredentials !== undefined && typeof value.getBasicCredentials !== 'function') throw new TypeError('Kodi Basic provider must be a function.');
+    this.#parentSignal?.throwIfAborted();
+    this.#protocol = new plugins.ecobridgeDeviceManager.KodiProtocol({
+      origin: this.#config.origin, expectedApplicationName: this.#config.expectedApplicationName,
+      expectedApplicationMajor: this.#config.expectedApplicationMajor, allowUnencryptedHttp: true,
+      control: this.#config.control, timeoutMs: this.#config.timeoutMs,
+      maxQueuedOperations: this.#config.maxQueuedOperations, maxResponseBytes: this.#config.maxResponseBytes,
+      getBasicCredentials: value.getBasicCredentials as IKodiClientOptions['getBasicCredentials'],
     });
+    this.#onParentAbort = () => { void this.destroy().catch(() => {}); };
+    this.#parentSignal?.addEventListener('abort', this.#onParentAbort, { once: true });
+    if (this.#parentSignal?.aborted) this.#onParentAbort();
   }
 
-  public async getPlayerItem(playerIdArg: number): Promise<IKodiMediaItem | undefined> {
-    const result = await this.callMethod<{ item?: IKodiMediaItem }>('Player.GetItem', {
-      playerid: playerIdArg,
-      properties: itemProperties,
-    });
-    return result.item;
-  }
-
-  public async setVolumeLevel(volumeLevelArg: number): Promise<number> {
-    return this.callMethod<number>('Application.SetVolume', {
-      volume: Math.max(0, Math.min(100, Math.round(volumeLevelArg * 100))),
-    });
-  }
-
-  public async stepVolume(directionArg: 'increment' | 'decrement'): Promise<number> {
-    return this.callMethod<number>('Application.SetVolume', { volume: directionArg });
-  }
-
-  public async setMuted(mutedArg: boolean): Promise<boolean> {
-    return this.callMethod<boolean>('Application.SetMute', { mute: mutedArg });
-  }
-
-  public async playPause(): Promise<unknown> {
-    return this.playState('toggle');
-  }
-
-  public async play(): Promise<unknown> {
-    return this.playState(true);
-  }
-
-  public async pause(): Promise<unknown> {
-    return this.playState(false);
-  }
-
-  public async stop(): Promise<string> {
-    return this.callMethod<string>('Player.Stop', { playerid: await this.activePlayerId() });
-  }
-
-  public async nextTrack(): Promise<string> {
-    return this.callMethod<string>('Player.GoTo', { playerid: await this.activePlayerId(), to: 'next' });
-  }
-
-  public async previousTrack(): Promise<string> {
-    return this.callMethod<string>('Player.GoTo', { playerid: await this.activePlayerId(), to: 'previous' });
-  }
-
-  public async seek(positionSecondsArg: number): Promise<unknown> {
-    return this.callMethod('Player.Seek', {
-      playerid: await this.activePlayerId(),
-      value: { time: this.secondsToTime(positionSecondsArg) },
-    });
-  }
+  public isHealthy(): boolean { return this.#healthy && !this.#closed && !this.#protocol.isClosed; }
 
-  public async playMedia(mediaTypeArg: TKodiMediaType, mediaIdArg: string | number): Promise<string> {
-    return this.callMethod<string>('Player.Open', { item: this.mediaItem(mediaTypeArg, mediaIdArg) });
+  public getSnapshot(signal?: AbortSignal): Promise<IKodiNativeSnapshot> {
+    return this.run(async (signal) => this.project(await this.#protocol.readSnapshot({ signal })), signal);
   }
 
-  public async clearPlaylist(playlistIdArg = 0): Promise<string> {
-    return this.callMethod<string>('Playlist.Clear', { playlistid: playlistIdArg });
+  public setVolume(volume: number, signal?: AbortSignal): Promise<plugins.ecobridgeDeviceManager.IKodiControlReceipt> {
+    return this.run((signal) => this.#protocol.setVolume(volume, { signal }), signal);
   }
 
-  public async addToPlaylist(mediaTypeArg: TKodiMediaType, mediaIdArg: string | number, playlistIdArg = 0): Promise<string> {
-    return this.callMethod<string>('Playlist.Add', {
-      playlistid: playlistIdArg,
-      item: this.playlistItem(mediaTypeArg, mediaIdArg),
-    });
+  public setMuted(muted: boolean, signal?: AbortSignal): Promise<plugins.ecobridgeDeviceManager.IKodiControlReceipt> {
+    return this.run((signal) => this.#protocol.setMuted(muted, { signal }), signal);
   }
 
-  public async showNotification(titleArg: string, messageArg: string, iconArg = 'info', displayTimeMsArg = 10000): Promise<string> {
-    return this.callMethod<string>('GUI.ShowNotification', {
-      title: titleArg,
-      message: messageArg,
-      image: iconArg,
-      displaytime: Math.max(1500, Math.round(displayTimeMsArg)),
+  public destroy(): Promise<void> {
+    if (this.#closePromise) return this.#closePromise;
+    this.#closed = true;
+    this.#healthy = false;
+    this.#closePromise = Promise.resolve().then(async () => {
+      const [protocolCleanup] = await Promise.allSettled([this.#protocol.close(), ...this.#operations]);
+      // Operation failures belong to their callers; this close still joins every projection.
+      if (protocolCleanup.status === 'rejected') throw protocolCleanup.reason;
     });
+    this.#parentSignal?.removeEventListener('abort', this.#onParentAbort);
+    this.#lifetime.abort(new Error('Kodi client is closed.'));
+    return this.#closePromise;
   }
 
-  public async input(commandArg: TKodiInputCommand): Promise<string | unknown> {
-    const method = this.inputMethod(commandArg);
-    return this.callMethod(method);
+  private project(state: plugins.ecobridgeDeviceManager.IKodiSnapshot): IKodiNativeSnapshot {
+    return Object.freeze({ ...state, homeId: this.#context.homeId, name: this.#config.name ?? state.applicationName, online: true });
   }
 
-  public async quit(): Promise<string> {
-    return this.callMethod<string>('Application.Quit');
-  }
-
-  public async callMethod<T = unknown>(methodArg: string, paramsArg?: TKodiJsonRpcParams): Promise<T> {
-    if (!this.config.host) {
-      throw new Error('Kodi host is required when snapshot data is not provided.');
-    }
-
-    const request: IKodiJsonRpcRequest = {
-      jsonrpc: '2.0',
-      method: methodArg,
-      id: this.requestId++,
-    };
-    if (paramsArg !== undefined) {
-      request.params = paramsArg;
-    }
-
-    const abortController = new AbortController();
-    const timeout = setTimeout(() => abortController.abort(), this.config.timeoutMs || defaultTimeoutMs);
+  private run<TResult>(work: (signal: AbortSignal) => Promise<TResult>, callerSignal?: AbortSignal): Promise<TResult> {
+    if (this.#closed || this.#protocol.isClosed) return Promise.reject(new plugins.ecobridgeDeviceManager.KodiProtocolError('closed', 'Kodi client is terminally closed.'));
+    let signal: AbortSignal;
     try {
-      const response = await globalThis.fetch(this.jsonRpcUrl(), {
-        method: 'POST',
-        headers: this.headers(),
-        body: JSON.stringify(request),
-        signal: abortController.signal,
-      });
-      const text = await response.text();
-      if (!response.ok) {
-        throw new Error(`Kodi request ${methodArg} failed with HTTP ${response.status}: ${text}`);
-      }
-      const payload = JSON.parse(text) as IKodiJsonRpcResponse<T>;
-      if (payload.error) {
-        throw new KodiJsonRpcError(methodArg, payload.error.code, payload.error.message || 'Unknown JSON-RPC error', payload.error.data);
-      }
-      return payload.result as T;
-    } finally {
-      clearTimeout(timeout);
-    }
-  }
-
-  public async destroy(): Promise<void> {}
-
-  private async playState(playArg: boolean | 'toggle'): Promise<unknown> {
-    return this.callMethod('Player.PlayPause', {
-      playerid: await this.activePlayerId(),
-      play: playArg,
-    });
-  }
-
-  private async activePlayerId(): Promise<number> {
-    const snapshot = await this.getSnapshot();
-    const playerId = snapshot.player?.playerid ?? snapshot.players[0]?.playerid;
-    if (typeof playerId !== 'number') {
-      throw new Error('Kodi has no active player.');
-    }
-    return playerId;
-  }
-
-  private mediaItem(mediaTypeArg: TKodiMediaType, mediaIdArg: string | number): Record<string, unknown> {
-    const type = mediaTypeArg.toLowerCase();
-    if (type === 'playlist') {
-      return { playlistid: Number(mediaIdArg) };
-    }
-    if (type === 'channel') {
-      return { channelid: Number(mediaIdArg) };
-    }
-    if (type === 'directory') {
-      return { path: String(mediaIdArg), recursive: true };
-    }
-    if (type === 'movie') {
-      return { movieid: Number(mediaIdArg) };
-    }
-    if (type === 'episode') {
-      return { episodeid: Number(mediaIdArg) };
-    }
-    if (type === 'season') {
-      return { seasonid: Number(mediaIdArg) };
-    }
-    if (type === 'tvshow') {
-      return { tvshowid: Number(mediaIdArg) };
-    }
-    if (type === 'album') {
-      return { albumid: Number(mediaIdArg) };
-    }
-    if (type === 'artist') {
-      return { artistid: Number(mediaIdArg) };
-    }
-    if (type === 'song' || type === 'track') {
-      return { songid: Number(mediaIdArg) };
-    }
-    return { file: String(mediaIdArg) };
-  }
-
-  private playlistItem(mediaTypeArg: TKodiMediaType, mediaIdArg: string | number): Record<string, unknown> {
-    const type = mediaTypeArg.toLowerCase();
-    if (type === 'album') {
-      return { albumid: Number(mediaIdArg) };
-    }
-    if (type === 'artist') {
-      return { artistid: Number(mediaIdArg) };
-    }
-    if (type === 'song' || type === 'track') {
-      return { songid: Number(mediaIdArg) };
-    }
-    return this.mediaItem(type, mediaIdArg);
-  }
-
-  private secondsToTime(secondsArg: number): IKodiTime {
-    const safeSeconds = Math.max(0, Math.floor(secondsArg));
-    return {
-      hours: Math.floor(safeSeconds / 3600),
-      minutes: Math.floor((safeSeconds % 3600) / 60),
-      seconds: safeSeconds % 60,
-      milliseconds: Math.max(0, Math.round((secondsArg - Math.floor(secondsArg)) * 1000)),
-    };
-  }
-
-  private inputMethod(commandArg: string): string {
-    const normalized = commandArg.replace(/[_\s-]+/g, '').toLowerCase();
-    const methods: Record<string, string> = {
-      up: 'Input.Up',
-      down: 'Input.Down',
-      left: 'Input.Left',
-      right: 'Input.Right',
-      select: 'Input.Select',
-      ok: 'Input.Select',
-      enter: 'Input.Select',
-      back: 'Input.Back',
-      home: 'Input.Home',
-      info: 'Input.Info',
-      contextmenu: 'Input.ContextMenu',
-    };
-    return methods[normalized] || (commandArg.includes('.') ? commandArg : `Input.${commandArg}`);
-  }
-
-  private normalizeSnapshot(snapshotArg: IKodiSnapshot): IKodiSnapshot {
-    const deviceInfo = {
-      ...this.deviceInfoFromConfig(),
-      ...snapshotArg.deviceInfo,
-    };
-    if (!deviceInfo.name) {
-      deviceInfo.name = snapshotArg.application?.name || this.config.name || this.config.host || 'Kodi';
-    }
-    if (!deviceInfo.version) {
-      deviceInfo.version = this.versionString(snapshotArg.application);
-    }
-    return {
-      ...snapshotArg,
-      deviceInfo,
-      players: snapshotArg.players || [],
-      player: snapshotArg.player || snapshotArg.players?.[0],
-      online: snapshotArg.online,
-    };
-  }
-
-  private deviceInfoFromConfig(): IKodiDeviceInfo {
-    return {
-      ...this.config.deviceInfo,
-      id: this.config.deviceInfo?.id || this.config.uniqueId,
-      uuid: this.config.deviceInfo?.uuid || this.config.uniqueId,
-      name: this.config.deviceInfo?.name || this.config.name,
-      host: this.config.deviceInfo?.host || this.config.host,
-      port: this.config.deviceInfo?.port || this.config.port || defaultPort,
-      wsPort: this.config.deviceInfo?.wsPort || this.config.wsPort || defaultWsPort,
-      manufacturer: this.config.deviceInfo?.manufacturer || 'Kodi',
-    };
-  }
-
-  private versionString(applicationArg: IKodiApplicationProperties | undefined): string | undefined {
-    const version = applicationArg?.version;
-    if (!version || typeof version.major !== 'number') {
-      return undefined;
-    }
-    return `${version.major}.${typeof version.minor === 'number' ? version.minor : 0}${version.revision ? `-${version.revision}` : ''}`;
-  }
-
-  private cloneSnapshot(snapshotArg: IKodiSnapshot): IKodiSnapshot {
-    return JSON.parse(JSON.stringify(snapshotArg)) as IKodiSnapshot;
-  }
-
-  private jsonRpcUrl(): string {
-    const protocol = this.config.ssl ? 'https' : 'http';
-    return `${protocol}://${this.config.host}:${this.config.port || defaultPort}/jsonrpc`;
-  }
-
-  private headers(): Record<string, string> {
-    const headers: Record<string, string> = { 'content-type': 'application/json' };
-    if (this.config.username !== undefined && this.config.password !== undefined) {
-      headers.authorization = `Basic ${globalThis.btoa(`${this.config.username}:${this.config.password}`)}`;
-    }
-    return headers;
+      kodiSignal(callerSignal);
+      if (callerSignal?.aborted) throw new plugins.ecobridgeDeviceManager.KodiProtocolError('cancelled', 'Kodi operation was cancelled before admission.');
+      signal = AbortSignal.any([this.#lifetime.signal, ...(callerSignal ? [callerSignal] : [])]);
+    } catch (error) { return Promise.reject(error); }
+    let operation: Promise<TResult>;
+    try { operation = work(signal).then((result) => {
+      this.#healthy = !this.#closed && !signal.aborted && !this.#protocol.isClosed;
+      return result;
+    }, (error: unknown) => {
+      this.#healthy = false;
+      throw error;
+    }); } catch (error) { return Promise.reject(error); }
+    this.#operations.add(operation);
+    const settled = (): void => { this.#operations.delete(operation); };
+    void operation.then(settled, settled);
+    return operation;
   }
 }

package/ts/integrations/kodi/kodi.classes.configflow.ts

@@ -1,63 +1,60 @@
-import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
-import type { IKodiConfig } from './kodi.types.js';
-
-const defaultPort = 8080;
-const defaultWsPort = 9090;
-const defaultTimeoutMs = 5000;
+import * as plugins from '../../plugins.js';
+import type { IConfigFlow, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
+import { KodiClient } from './kodi.classes.client.js';
+import type { IKodiConfig, IKodiConfigFlowContext } from './kodi.types.js';
+import { kodiInteger, kodiKeys, kodiRecord, kodiText, normalizeKodiConfig } from './kodi.validation.js';
 
+/** Captures selected configuration. Setup separately owns live readiness admission. */
 export class KodiConfigFlow implements IConfigFlow<IKodiConfig> {
-  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IKodiConfig>> {
-    void contextArg;
+  readonly #scope: NativeIntegrationScope;
+  public constructor(owner: NativeIntegrationOwner = new NativeIntegrationOwner('kodi')) {
+    this.#scope = owner.createFlowScope();
+  }
+
+  public destroy(): Promise<void> { return this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#scope.retryCleanup(); }
+
+  public async start(input: IDiscoveryCandidate, context: IKodiConfigFlowContext): Promise<IConfigFlowStep<IKodiConfig>> {
+    const candidate = kodiRecord(input, 'config candidate');
+    const host = kodiText(candidate.host, 'selected candidate host', 128);
+    const port = kodiInteger(candidate.port === undefined ? 8080 : candidate.port, 1, 65535, 'candidate port');
+    const origin = plugins.ecobridgeDeviceManager.validateKodiOrigin(`http://${host}:${port}`);
+    const captured = this.#scope.admit(context);
     return {
-      kind: 'form',
-      title: 'Connect Kodi',
-      description: 'Configure the local Kodi JSON-RPC endpoint.',
+      kind: 'form', title: 'Connect selected Kodi application',
+      description: 'Specify the expected application name and major for the host-selected home. Accept plaintext HTTP explicitly. Controls default to disabled; enabling them requires endpoint trust and an integer volume ceiling. Live readiness is checked during setup.',
       fields: [
-        { name: 'host', label: 'Host', type: 'text', required: true },
-        { name: 'port', label: 'HTTP JSON-RPC port', type: 'number' },
-        { name: 'ssl', label: 'Use HTTPS', type: 'boolean' },
-        { name: 'wsPort', label: 'WebSocket port', type: 'number' },
-        { name: 'username', label: 'Username', type: 'text' },
-        { name: 'password', label: 'Password', type: 'password' },
-        { name: 'name', label: 'Name', type: 'text' },
+        { name: 'expectedApplicationName', label: 'Exact application name', type: 'text', required: true },
+        { name: 'expectedApplicationMajor', label: 'Application major version', type: 'number', required: true },
+        { name: 'allowUnencryptedHttp', label: 'Accept plaintext HTTP', type: 'boolean', required: true },
+        { name: 'allowControls', label: 'Enable application volume and mute controls', type: 'boolean' },
+        { name: 'trustSelectedEndpoint', label: 'Trust this selected endpoint for controls', type: 'boolean' },
+        { name: 'maximumVolume', label: 'Maximum integer application volume (0–100)', type: 'number' },
+        { name: 'name', label: 'Display name', type: 'text' },
       ],
-      submit: async (valuesArg) => ({
-        kind: 'done',
-        title: 'Kodi configured',
-        config: {
-          host: this.stringValue(valuesArg.host) || candidateArg.host || '',
-          port: this.numberValue(valuesArg.port) || candidateArg.port || defaultPort,
-          wsPort: this.numberValue(valuesArg.wsPort) || this.numberMetadata(candidateArg, 'wsPort') || defaultWsPort,
-          ssl: this.booleanValue(valuesArg.ssl) ?? this.booleanMetadata(candidateArg, 'ssl') ?? false,
-          username: this.stringValue(valuesArg.username),
-          password: this.stringValue(valuesArg.password),
-          name: this.stringValue(valuesArg.name) || candidateArg.name,
-          uniqueId: candidateArg.id,
-          timeoutMs: defaultTimeoutMs,
-        },
-      }),
+      submit: async (input) => {
+        try {
+          const values = kodiRecord(input, 'config-flow values');
+          return await this.#scope.run(captured, captured.homeId, async (lease): Promise<IConfigFlowStep<IKodiConfig>> => {
+            kodiKeys(values, ['homeId', 'expectedApplicationName', 'expectedApplicationMajor', 'allowUnencryptedHttp', 'allowControls', 'trustSelectedEndpoint', 'maximumVolume', 'name', 'timeoutMs', 'maxQueuedOperations', 'maxResponseBytes']);
+            if (values.homeId !== undefined && values.homeId !== lease.context.homeId) throw new TypeError('Kodi form home differs from the host-selected home.');
+            if (values.allowControls !== undefined && typeof values.allowControls !== 'boolean') throw new TypeError('Kodi controls require an explicit boolean opt-in.');
+            if (values.allowControls !== true && (values.trustSelectedEndpoint === true || values.maximumVolume !== undefined)) throw new TypeError('Kodi owner control policy requires an explicit controls opt-in.');
+            const config = normalizeKodiConfig({ homeId: lease.context.homeId, origin,
+              expectedApplicationName: values.expectedApplicationName, expectedApplicationMajor: values.expectedApplicationMajor,
+              allowUnencryptedHttp: values.allowUnencryptedHttp,
+              control: values.allowControls === true ? { trustSelectedEndpoint: values.trustSelectedEndpoint, maximumVolume: values.maximumVolume } : undefined,
+              name: values.name, timeoutMs: values.timeoutMs, maxQueuedOperations: values.maxQueuedOperations, maxResponseBytes: values.maxResponseBytes });
+            // Construction delegates endpoint validation without opening a connection.
+            const client = new KodiClient(config, { ...lease.context, abortSignal: lease.signal });
+            lease.own(() => client.destroy());
+            return { kind: 'done', title: 'Kodi configuration captured', config };
+          });
+        } catch (error) {
+          return { kind: 'error', error: error instanceof Error ? error.message : 'Kodi configuration was refused.' };
+        }
+      },
     };
   }
-
-  private stringValue(valueArg: unknown): string | undefined {
-    return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
-  }
-
-  private numberValue(valueArg: unknown): number | undefined {
-    return typeof valueArg === 'number' && Number.isFinite(valueArg) ? valueArg : undefined;
-  }
-
-  private booleanValue(valueArg: unknown): boolean | undefined {
-    return typeof valueArg === 'boolean' ? valueArg : undefined;
-  }
-
-  private numberMetadata(candidateArg: IDiscoveryCandidate, keyArg: string): number | undefined {
-    const value = candidateArg.metadata?.[keyArg];
-    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
-  }
-
-  private booleanMetadata(candidateArg: IDiscoveryCandidate, keyArg: string): boolean | undefined {
-    const value = candidateArg.metadata?.[keyArg];
-    return typeof value === 'boolean' ? value : undefined;
-  }
 }