@smarthome.exchange/integrations 1.0.0 → 3.0.0

package/ts/integrations/kodi/kodi.classes.integration.ts

@@ -1,216 +1,135 @@
-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 { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationRuntime, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { KodiClient } from './kodi.classes.client.js';
 import { KodiConfigFlow } from './kodi.classes.configflow.js';
 import { createKodiDiscoveryDescriptor } from './kodi.discovery.js';
 import { KodiMapper } from './kodi.mapper.js';
-import type { IKodiConfig, TKodiMediaType } from './kodi.types.js';
+import type { IKodiConfig, IKodiIntegrationOptions, IKodiNativeSnapshot, IKodiSetupContext } from './kodi.types.js';
+import { kodiBoolean, kodiInteger, kodiKeys, kodiRecord, kodiSignal, normalizeKodiConfig } from './kodi.validation.js';
 
 export class KodiIntegration extends BaseIntegration<IKodiConfig> {
   public readonly domain = 'kodi';
   public readonly displayName = 'Kodi';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createKodiDiscoveryDescriptor();
-  public readonly configFlow = new KodiConfigFlow();
+  public readonly configFlow: KodiConfigFlow;
   public readonly metadata = {
-    source: 'home-assistant/core',
-    upstreamPath: 'homeassistant/components/kodi',
-    upstreamDomain: 'kodi',
-    integrationType: 'service',
-    iotClass: 'local_push',
-    requirements: ['pykodi==0.2.7'],
-    dependencies: [],
-    afterDependencies: ['media_source'],
-    codeowners: ['@OnFreund'],
-    configFlow: true,
-    documentation: 'https://www.home-assistant.io/integrations/kodi',
+    source: 'native-typescript', integrationType: 'device', iotClass: 'local_poll',
+    localApi: { status: 'Selected Kodi HTTP JSON-RPC API13 through devicemanager.',
+      implemented: ['fresh application observation', 'read-only default', 'explicit owner-trusted absolute volume and boolean mute', 'home-scoped endpoint targets', 'joined terminal lifetime'],
+      explicitUnsupported: ['unique or cryptographic server identity', 'arbitrary JSON-RPC', 'media transport', 'library and power operations', 'toggle or increment', 'notification transport', 'retry or replay', 'Home Assistant bridge'] },
   };
+  readonly #owner: NativeIntegrationOwner;
+  #getBasicCredentials?: IKodiIntegrationOptions['getBasicCredentials'];
+  #closePromise?: Promise<void>;
 
-  public async setup(configArg: IKodiConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new KodiRuntime(new KodiClient(configArg));
+  public constructor(options: IKodiIntegrationOptions = {}) {
+    super();
+    const value = kodiRecord(options, 'integration options');
+    kodiKeys(value, ['homeId', 'getBasicCredentials']);
+    if (value.getBasicCredentials !== undefined && typeof value.getBasicCredentials !== 'function') throw new TypeError('Kodi Basic provider must be a function.');
+    this.#owner = new NativeIntegrationOwner('kodi', { homeId: value.homeId as string | undefined });
+    this.#getBasicCredentials = value.getBasicCredentials as IKodiIntegrationOptions['getBasicCredentials'];
+    this.configFlow = new KodiConfigFlow(this.#owner);
   }
 
-  public async destroy(): Promise<void> {}
+  public setup(config: IKodiConfig, context: IKodiSetupContext): Promise<IIntegrationRuntime> {
+    try {
+      const captured = normalizeKodiConfig(config);
+      return this.#owner.runSetup(context, captured.homeId, async (lease) => {
+        const client = new KodiClient(captured, { ...lease.context, abortSignal: lease.signal }, { getBasicCredentials: this.#getBasicCredentials });
+        lease.own(() => client.destroy());
+        const initial = await client.getSnapshot();
+        lease.assertOpen();
+        const runtime = new KodiRuntime(client, initial, lease);
+        lease.promoteToRuntime();
+        return runtime;
+      });
+    } catch (error) { return Promise.reject(error); }
+  }
+
+  public destroy(): Promise<void> {
+    if (!this.#closePromise) {
+      this.#closePromise = Promise.resolve().then(async () => {
+        try { await this.#owner.close(); }
+        finally { this.#getBasicCredentials = undefined; }
+      });
+      // Install the facade memo before synchronously closing admission or dispatching abort.
+      void this.#owner.close().catch(() => undefined);
+    }
+    return this.#closePromise;
+  }
+
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
 
 export class HomeAssistantKodiIntegration extends KodiIntegration {}
 
 class KodiRuntime implements IIntegrationRuntime {
-  public domain = 'kodi';
-
-  constructor(private readonly client: KodiClient) {}
+  public readonly domain = 'kodi';
+  readonly #deviceId: string;
+  readonly #entityId: string;
 
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return KodiMapper.toDevices(await this.client.getSnapshot());
+  public constructor(private readonly client: KodiClient, initial: IKodiNativeSnapshot, private readonly lease: INativeSetupLease) {
+    this.#deviceId = KodiMapper.deviceId(initial);
+    this.#entityId = KodiMapper.entityId(initial);
   }
 
-  public async entities(): Promise<IIntegrationEntity[]> {
-    return KodiMapper.toEntities(await this.client.getSnapshot());
-  }
+  public isHealthy(): boolean { return this.client.isHealthy(); }
+  public async devices(signal?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> { return KodiMapper.toNativeDevices(await this.client.getSnapshot(signal)); }
+  public async entities(): Promise<IIntegrationEntity[]> { return KodiMapper.toNativeEntities(await this.client.getSnapshot()); }
 
-  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+  public async callService(input: IServiceCallRequest): Promise<IServiceCallResult> {
     try {
-      if (requestArg.domain === 'media_player') {
-        return await this.callMediaPlayerService(requestArg);
-      }
-      if (requestArg.domain === 'kodi') {
-        return await this.callKodiService(requestArg);
+      const request = kodiRecord(input, 'service request');
+      kodiKeys(request, ['domain', 'service', 'target', 'data']);
+      this.assertTarget(request.target);
+      const data = request.data === undefined ? {} : kodiRecord(request.data, 'service data');
+      if (request.domain === 'kodi' && request.service === 'snapshot') {
+        kodiKeys(data, []); return { success: true, data: await this.client.getSnapshot() };
       }
-      if (requestArg.domain === 'notify') {
-        return await this.callNotifyService(requestArg);
+      if (request.domain === 'kodi' && request.service === 'set_volume') {
+        kodiKeys(data, ['volume']); return { success: true, data: await this.client.setVolume(kodiInteger(data.volume, 0, 100, 'absolute volume')) };
       }
-      if (requestArg.domain === 'remote') {
-        return await this.callRemoteService(requestArg);
+      if ((request.domain === 'kodi' && request.service === 'set_muted') || (request.domain === 'media_player' && request.service === 'volume_mute')) {
+        kodiKeys(data, ['muted']); return { success: true, data: await this.client.setMuted(kodiBoolean(data.muted)) };
       }
-      return { success: false, error: `Unsupported Kodi service domain: ${requestArg.domain}` };
-    } catch (errorArg) {
-      return { success: false, error: errorArg instanceof Error ? errorArg.message : String(errorArg) };
-    }
-  }
-
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
+      throw new TypeError('Kodi service is unsupported; only snapshot, absolute volume and explicit mute are admitted.');
+    } catch (error) { return kodiFailure(error); }
   }
 
-  private async callMediaPlayerService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.service === 'turn_on') {
-      return { success: true, data: { event: 'kodi.turn_on', entityId: requestArg.target.entityId } };
-    }
-    if (requestArg.service === 'turn_off') {
-      await this.client.quit();
-      return { success: true };
-    }
-    if (requestArg.service === 'play' || requestArg.service === 'media_play') {
-      await this.client.play();
-      return { success: true };
-    }
-    if (requestArg.service === 'pause' || requestArg.service === 'media_pause') {
-      await this.client.pause();
-      return { success: true };
-    }
-    if (requestArg.service === 'play_pause' || requestArg.service === 'media_play_pause') {
-      await this.client.playPause();
-      return { success: true };
-    }
-    if (requestArg.service === 'stop' || requestArg.service === 'media_stop') {
-      await this.client.stop();
-      return { success: true };
-    }
-    if (requestArg.service === 'next_track' || requestArg.service === 'media_next_track') {
-      await this.client.nextTrack();
-      return { success: true };
-    }
-    if (requestArg.service === 'previous_track' || requestArg.service === 'media_previous_track') {
-      await this.client.previousTrack();
-      return { success: true };
-    }
-    if (requestArg.service === 'seek' || requestArg.service === 'media_seek') {
-      const position = requestArg.data?.seek_position ?? requestArg.data?.position;
-      if (typeof position !== 'number') {
-        return { success: false, error: 'Kodi seek requires data.seek_position.' };
-      }
-      await this.client.seek(position);
-      return { success: true };
-    }
-    if (requestArg.service === 'volume_set') {
-      const level = requestArg.data?.volume_level;
-      if (typeof level !== 'number') {
-        return { success: false, error: 'Kodi volume_set requires data.volume_level.' };
-      }
-      await this.client.setVolumeLevel(level);
-      return { success: true };
-    }
-    if (requestArg.service === 'volume_up' || requestArg.service === 'volume_down') {
-      await this.client.stepVolume(requestArg.service === 'volume_up' ? 'increment' : 'decrement');
-      return { success: true };
-    }
-    if (requestArg.service === 'volume_mute') {
-      const muted = requestArg.data?.is_volume_muted ?? requestArg.data?.muted;
-      if (typeof muted !== 'boolean') {
-        return { success: false, error: 'Kodi volume_mute requires data.is_volume_muted.' };
-      }
-      await this.client.setMuted(muted);
-      return { success: true };
-    }
-    if (requestArg.service === 'play_media') {
-      const mediaId = requestArg.data?.media_content_id ?? requestArg.data?.uri;
-      const mediaType = requestArg.data?.media_content_type ?? requestArg.data?.media_type ?? 'file';
-      if ((typeof mediaId !== 'string' && typeof mediaId !== 'number') || mediaId === '') {
-        return { success: false, error: 'Kodi play_media requires data.media_content_id or data.uri.' };
-      }
-      await this.client.playMedia(typeof mediaType === 'string' ? mediaType : 'file', mediaId);
-      return { success: true };
-    }
-    return { success: false, error: `Unsupported Kodi media_player service: ${requestArg.service}` };
-  }
-
-  private async callKodiService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.service === 'call_method') {
-      const method = requestArg.data?.method;
-      if (typeof method !== 'string' || !method) {
-        return { success: false, error: 'Kodi call_method requires data.method.' };
-      }
-      const params = this.callMethodParams(requestArg);
-      return { success: true, data: await this.client.callMethod(method, params) };
-    }
-    if (requestArg.service === 'add_to_playlist') {
-      const mediaType = requestArg.data?.media_type;
-      const mediaId = requestArg.data?.media_id;
-      if (typeof mediaType !== 'string' || (typeof mediaId !== 'string' && typeof mediaId !== 'number')) {
-        return { success: false, error: 'Kodi add_to_playlist requires data.media_type and data.media_id.' };
-      }
-      await this.client.addToPlaylist(mediaType as TKodiMediaType, mediaId);
-      return { success: true };
-    }
-    if (requestArg.service === 'show_notification') {
-      return this.callNotifyService(requestArg);
-    }
-    return { success: false, error: `Unsupported Kodi service: ${requestArg.service}` };
+  public async writeFeature(input: IDeviceFeatureWriteRequest, signal?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      kodiSignal(signal);
+      const request = kodiRecord(input, 'feature write');
+      kodiKeys(request, ['device', 'feature', 'value']);
+      const device = kodiRecord(request.device, 'feature device');
+      const feature = kodiRecord(request.feature, 'feature');
+      if (device.id !== this.#deviceId || device.integrationDomain !== 'kodi') throw new TypeError('Kodi feature target is outside this home and selected endpoint.');
+      if (feature.capability !== 'media') throw new TypeError('Kodi feature capability differs from the canonical feature.');
+      if (feature.id === 'volume') return { success: true, data: await this.client.setVolume(kodiInteger(request.value, 0, 100, 'absolute volume'), signal) };
+      if (feature.id === 'muted') return { success: true, data: await this.client.setMuted(kodiBoolean(request.value), signal) };
+      throw new TypeError('Kodi feature is not writable.');
+    } catch (error) { return kodiFailure(error); }
   }
 
-  private async callNotifyService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    const message = requestArg.data?.message;
-    if (typeof message !== 'string') {
-      return { success: false, error: 'Kodi notification requires data.message.' };
-    }
-    const title = typeof requestArg.data?.title === 'string' ? requestArg.data.title : 'Home Assistant';
-    const icon = typeof requestArg.data?.icon === 'string' ? requestArg.data.icon : 'info';
-    const displayTime = typeof requestArg.data?.displaytime === 'number' ? requestArg.data.displaytime : 10000;
-    await this.client.showNotification(title, message, icon, displayTime);
-    return { success: true };
+  public destroy(): Promise<void> {
+    return this.lease.close();
   }
 
-  private async callRemoteService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.service !== 'send_command') {
-      return { success: false, error: `Unsupported Kodi remote service: ${requestArg.service}` };
-    }
-    const command = requestArg.data?.command;
-    const commands = typeof command === 'string' ? [command] : Array.isArray(command) ? command.filter((itemArg): itemArg is string => typeof itemArg === 'string') : [];
-    if (!commands.length) {
-      return { success: false, error: 'Kodi remote.send_command requires data.command.' };
-    }
-    for (const item of commands) {
-      await this.client.input(item);
-    }
-    return { success: true };
+  private assertTarget(input: unknown): void {
+    const target = kodiRecord(input, 'service target');
+    kodiKeys(target, ['deviceId', 'entityId']);
+    if (target.deviceId === undefined && target.entityId === undefined ||
+      target.deviceId !== undefined && target.deviceId !== this.#deviceId ||
+      target.entityId !== undefined && target.entityId !== this.#entityId) throw new TypeError('Kodi requires an exact owned device or entity target.');
   }
+}
 
-  private callMethodParams(requestArg: IServiceCallRequest): Record<string, unknown> | unknown[] | undefined {
-    const explicitParams = requestArg.data?.params;
-    if (Array.isArray(explicitParams)) {
-      return explicitParams;
-    }
-    if (explicitParams && typeof explicitParams === 'object') {
-      return explicitParams as Record<string, unknown>;
-    }
-    const params: Record<string, unknown> = {};
-    for (const [key, value] of Object.entries(requestArg.data || {})) {
-      if (key !== 'method') {
-        params[key] = value;
-      }
-    }
-    return Object.keys(params).length ? params : undefined;
-  }
+function kodiFailure(error: unknown): IServiceCallResult {
+  const protocolError = error instanceof plugins.ecobridgeDeviceManager.KodiProtocolError ? error : undefined;
+  return { success: false, error: protocolError?.message ?? 'Kodi operation was refused or failed.',
+    data: { code: protocolError?.code ?? 'invalid-operation', effectOutcome: protocolError?.effectOutcome ?? 'not-sent', ...(protocolError?.rpcErrorCode === undefined ? {} : { rpcErrorCode: protocolError.rpcErrorCode }) } };
 }

package/ts/integrations/kodi/kodi.discovery.ts

@@ -1,9 +1,9 @@
+import * as plugins from '../../plugins.js';
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
 import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
 import type { IKodiManualEntry, IKodiMdnsRecord } from './kodi.types.js';
 
 const defaultPort = 8080;
-const defaultWsPort = 9090;
 const kodiMdnsType = '_xbmc-jsonrpc-h._tcp.local';
 
 export class KodiMdnsMatcher implements IDiscoveryMatcher<IKodiMdnsRecord> {
@@ -20,25 +20,33 @@ export class KodiMdnsMatcher implements IDiscoveryMatcher<IKodiMdnsRecord> {
     if (!matched) {
       return { matched: false, confidence: 'low', reason: 'mDNS record is not a Kodi JSON-RPC advertisement.' };
     }
+    let endpoint = kodiEndpoint(recordArg.host, recordArg.port);
+    for (const address of recordArg.addresses || []) {
+      if (endpoint) break;
+      endpoint = kodiEndpoint(address, recordArg.port);
+    }
+    if (!endpoint) {
+      return { matched: false, confidence: 'low', reason: 'Kodi advertisement does not contain a supported numeric HTTP endpoint.' };
+    }
     return {
       matched: true,
-      confidence: uuid ? 'certain' : 'high',
-      reason: 'mDNS record matches Kodi JSON-RPC metadata.',
-      normalizedDeviceId: uuid,
+      confidence: 'high',
+      reason: 'mDNS record is a Kodi endpoint hint; application selection still requires a live observation.',
       candidate: {
         source: 'mdns',
         integrationDomain: 'kodi',
-        id: uuid,
-        host: recordArg.host || recordArg.addresses?.[0],
-        port: recordArg.port || defaultPort,
+        host: endpoint.host,
+        port: endpoint.port,
         name,
         manufacturer: 'Kodi',
         model: valueForKey(properties, 'version') ? 'Kodi Media Center' : undefined,
         metadata: {
           mdnsName: recordArg.name,
           mdnsType: recordArg.type,
-          txt: properties,
-          wsPort: defaultWsPort,
+          mdnsHost: recordArg.host,
+          advertisedId: uuid,
+          advertisedVersion: valueForKey(properties, 'version'),
+          selectionVerified: false,
         },
       },
     };
@@ -51,30 +59,24 @@ export class KodiManualMatcher implements IDiscoveryMatcher<IKodiManualEntry> {
   public description = 'Recognize manual Kodi setup entries.';
 
   public async matches(inputArg: IKodiManualEntry): Promise<IDiscoveryMatch> {
-    const haystack = `${inputArg.name || ''} ${inputArg.model || ''} ${inputArg.manufacturer || ''}`.toLowerCase();
-    const matched = Boolean(inputArg.host || inputArg.metadata?.kodi || haystack.includes('kodi') || haystack.includes('xbmc'));
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'Manual entry does not contain Kodi setup hints.' };
+    const endpoint = kodiEndpoint(inputArg.host, inputArg.port);
+    if (!endpoint) {
+      return { matched: false, confidence: 'low', reason: 'Manual Kodi setup requires a supported numeric HTTP endpoint.' };
     }
-    const id = inputArg.uuid || inputArg.id;
     return {
       matched: true,
-      confidence: inputArg.host ? 'high' : 'medium',
+      confidence: 'high',
       reason: 'Manual entry can start Kodi setup.',
-      normalizedDeviceId: id,
       candidate: {
         source: 'manual',
         integrationDomain: 'kodi',
-        id,
-        host: inputArg.host,
-        port: inputArg.port || defaultPort,
+        host: endpoint.host,
+        port: endpoint.port,
         name: inputArg.name,
         manufacturer: inputArg.manufacturer || 'Kodi',
         model: inputArg.model,
         metadata: {
-          ...inputArg.metadata,
-          wsPort: inputArg.wsPort || defaultWsPort,
-          ssl: inputArg.ssl,
+          selectionVerified: false,
         },
       },
     };
@@ -89,19 +91,25 @@ export class KodiCandidateValidator implements IDiscoveryValidator {
     const manufacturer = candidateArg.manufacturer?.toLowerCase() || '';
     const model = candidateArg.model?.toLowerCase() || '';
     const name = candidateArg.name?.toLowerCase() || '';
-    const matched = candidateArg.integrationDomain === 'kodi'
+    const recognized = candidateArg.integrationDomain === 'kodi'
       || manufacturer.includes('kodi')
       || manufacturer.includes('xbmc')
       || model.includes('kodi')
       || model.includes('xbmc')
       || name.includes('kodi')
       || Boolean(candidateArg.metadata?.kodi);
+    if (!recognized) {
+      return { matched: false, confidence: 'low', reason: 'Candidate is not Kodi.' };
+    }
+    const endpoint = kodiEndpoint(candidateArg.host, candidateArg.port);
+    if (!endpoint) {
+      return { matched: false, confidence: 'low', reason: 'Kodi candidate does not contain a supported numeric HTTP endpoint.' };
+    }
     return {
-      matched,
-      confidence: matched && candidateArg.host ? 'high' : matched ? 'medium' : 'low',
-      reason: matched ? 'Candidate has Kodi metadata.' : 'Candidate is not Kodi.',
-      candidate: matched ? candidateArg : undefined,
-      normalizedDeviceId: candidateArg.id,
+      matched: true,
+      confidence: 'high',
+      reason: 'Candidate has Kodi metadata and a numeric endpoint hint; application selection still requires a live observation.',
+      candidate: { ...candidateArg, host: endpoint.host, port: endpoint.port },
     };
   }
 }
@@ -113,6 +121,19 @@ export const createKodiDiscoveryDescriptor = (): DiscoveryDescriptor => {
     .addValidator(new KodiCandidateValidator());
 };
 
+/** Select only supplied endpoints; the public foundation owns origin policy. */
+const kodiEndpoint = (hostArg: string | undefined, portArg: number | undefined): { host: string; port: number } | undefined => {
+  const port = portArg === undefined ? defaultPort : portArg;
+  if (typeof hostArg !== 'string' || typeof port !== 'number' || !Number.isSafeInteger(port)) return undefined;
+  try {
+    const origin = plugins.ecobridgeDeviceManager.validateKodiOrigin(`http://${hostArg}:${port}`);
+    return { host: new URL(origin).hostname, port };
+  } catch (error) {
+    if (error instanceof plugins.ecobridgeDeviceManager.KodiProtocolError && error.code === 'invalid-options') return undefined;
+    throw error;
+  }
+};
+
 const normalizeType = (valueArg?: string): string => {
   return (valueArg || '').toLowerCase().replace(/\.$/, '');
 };

package/ts/integrations/kodi/kodi.mapper.ts

@@ -1,6 +1,6 @@
 import * as plugins from '../../plugins.js';
 import type { IIntegrationEntity } from '../../core/types.js';
-import type { IKodiMediaItem, IKodiSnapshot, IKodiTime } from './kodi.types.js';
+import type { IKodiMediaItem, IKodiNativeSnapshot, IKodiSnapshot, IKodiTime } from './kodi.types.js';
 
 const kodiMediaTypes: Record<string, string> = {
   music: 'music',
@@ -19,24 +19,64 @@ const kodiMediaTypes: Record<string, string> = {
 };
 
 export class KodiMapper {
+  public static deviceId(snapshot: Pick<IKodiNativeSnapshot, 'homeId' | 'origin'>): string {
+    return `kodi:${encodeURIComponent(snapshot.homeId)}:${encodeURIComponent(snapshot.origin)}`;
+  }
+
+  public static entityId(snapshot: Pick<IKodiNativeSnapshot, 'homeId' | 'origin'>): string {
+    return `media_player.${this.deviceId(snapshot)}`;
+  }
+
+  public static toNativeDevices(snapshot: IKodiNativeSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    return [{
+      id: this.deviceId(snapshot), integrationDomain: 'kodi', name: snapshot.name, protocol: 'http',
+      manufacturer: 'Kodi', model: snapshot.applicationName, online: snapshot.online,
+      features: [
+        { id: 'volume', capability: 'media', name: 'Application volume', readable: true, writable: snapshot.capabilities.canSetVolume, unit: '%' },
+        { id: 'muted', capability: 'media', name: 'Application muted', readable: true, writable: snapshot.capabilities.canSetMuted },
+      ],
+      state: [
+        { featureId: 'volume', value: snapshot.volume, updatedAt: snapshot.observedAt },
+        { featureId: 'muted', value: snapshot.muted, updatedAt: snapshot.observedAt },
+      ],
+      metadata: {
+        homeId: snapshot.homeId, origin: snapshot.origin, applicationVersion: snapshot.applicationVersion,
+        apiVersion: snapshot.apiVersion, selection: snapshot.selection, uniqueDeviceIdentityVerified: false,
+        cryptographicServerIdentityVerified: false, volumeRange: snapshot.capabilities.volumeRange,
+        runtimeAuthority: 'native-observation', playbackObserved: false,
+      },
+    }];
+  }
+
+  public static toNativeEntities(snapshot: IKodiNativeSnapshot): IIntegrationEntity[] {
+    return [{
+      id: this.entityId(snapshot), uniqueId: this.deviceId(snapshot), integrationDomain: 'kodi',
+      deviceId: this.deviceId(snapshot), platform: 'media_player', name: snapshot.name, state: 'unknown', available: snapshot.online,
+      attributes: { applicationVolume: snapshot.volume, isVolumeMuted: snapshot.muted, playbackObserved: false,
+        applicationName: snapshot.applicationName, applicationVersion: snapshot.applicationVersion, apiVersion: snapshot.apiVersion,
+        selection: snapshot.selection, uniqueDeviceIdentityVerified: false, cryptographicServerIdentityVerified: false,
+        capabilities: snapshot.capabilities, observedAt: snapshot.observedAt },
+    }];
+  }
+
+  /** Converts offline imported data without granting runtime availability or writes. */
   public static toDevices(snapshotArg: IKodiSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
     const updatedAt = snapshotArg.updatedAt || new Date().toISOString();
     const application = snapshotArg.application;
     return [{
-      id: this.deviceId(snapshotArg),
+      id: this.offlineDeviceId(snapshotArg),
       integrationDomain: 'kodi',
       name: this.deviceName(snapshotArg),
       protocol: 'http',
       manufacturer: snapshotArg.deviceInfo.manufacturer || 'Kodi',
       model: snapshotArg.deviceInfo.model || application?.name,
-      online: snapshotArg.online,
+      online: false,
       features: [
-        { id: 'playback', capability: 'media', name: 'Playback', readable: true, writable: true },
-        { id: 'volume', capability: 'media', name: 'Volume', readable: true, writable: true, unit: '%' },
-        { id: 'muted', capability: 'media', name: 'Muted', readable: true, writable: true },
+        { id: 'playback', capability: 'media', name: 'Playback', readable: true, writable: false },
+        { id: 'volume', capability: 'media', name: 'Volume', readable: true, writable: false, unit: '%' },
+        { id: 'muted', capability: 'media', name: 'Muted', readable: true, writable: false },
         { id: 'active_player', capability: 'media', name: 'Active player', readable: true, writable: false },
         { id: 'current_title', capability: 'media', name: 'Current title', readable: true, writable: false },
-        { id: 'notification', capability: 'media', name: 'Notification', readable: false, writable: true },
       ],
       state: [
         { featureId: 'playback', value: this.mediaState(snapshotArg), updatedAt },
@@ -46,6 +86,7 @@ export class KodiMapper {
         { featureId: 'current_title', value: this.mediaTitle(snapshotArg.item) || null, updatedAt },
       ],
       metadata: {
+        runtimeAuthority: 'offline-import', uniqueDeviceIdentityVerified: false,
         uuid: snapshotArg.deviceInfo.uuid,
         host: snapshotArg.deviceInfo.host,
         port: snapshotArg.deviceInfo.port,
@@ -62,11 +103,12 @@ export class KodiMapper {
       id: `media_player.${this.slug(this.deviceName(snapshotArg))}`,
       uniqueId: `kodi_${this.uniqueBase(snapshotArg)}`,
       integrationDomain: 'kodi',
-      deviceId: this.deviceId(snapshotArg),
+      deviceId: this.offlineDeviceId(snapshotArg),
       platform: 'media_player',
       name: this.deviceName(snapshotArg),
       state: this.mediaState(snapshotArg),
       attributes: {
+        runtimeAuthority: 'offline-import', uniqueDeviceIdentityVerified: false,
         volumeLevel: typeof snapshotArg.application?.volume === 'number' ? snapshotArg.application.volume / 100 : undefined,
         isVolumeMuted: snapshotArg.application?.muted,
         mediaContentId: this.mediaContentId(item),
@@ -86,7 +128,7 @@ export class KodiMapper {
         live: snapshotArg.playerProperties?.live,
         dynamicRange: this.dynamicRange(item),
       },
-      available: snapshotArg.online,
+      available: false,
     }];
   }
 
@@ -151,7 +193,7 @@ export class KodiMapper {
     return Array.isArray(valueArg) ? valueArg[0] : valueArg;
   }
 
-  private static deviceId(snapshotArg: IKodiSnapshot): string {
+  private static offlineDeviceId(snapshotArg: IKodiSnapshot): string {
     return `kodi.device.${this.uniqueBase(snapshotArg)}`;
   }