@smarthome.exchange/integrations 1.0.0 → 2.0.0

package/ts/integrations/onkyo/onkyo.classes.configflow.ts

@@ -1,9 +1,55 @@
-import { SimpleLocalConfigFlow } from '../../core/index.js';
-import type { IOnkyoConfig } from './onkyo.types.js';
-import { onkyoProfile } from './onkyo.types.js';
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
+import type { IConfigFlow, IConfigFlowStep, IDiscoveryCandidate, INativeConfigFlowContext } from '../../core/types.js';
+import { OnkyoClient } from './onkyo.classes.client.js';
+import { createOnkyoDiscoveryDescriptor } from './onkyo.discovery.js';
+import type { IOnkyoConfig, IOnkyoIntegrationOptions } from './onkyo.types.js';
+import { normalizeOnkyoConfig, onkyoKeys, onkyoRecord } from './onkyo.validation.js';
 
-export class OnkyoConfigFlow extends SimpleLocalConfigFlow<IOnkyoConfig> {
-  constructor() {
-    super(onkyoProfile);
+export class OnkyoConfigFlow implements IConfigFlow<IOnkyoConfig> {
+  readonly #scope: NativeIntegrationScope;
+
+  constructor(optionsArg: IOnkyoIntegrationOptions = {}, scopeArg?: NativeIntegrationScope) {
+    this.#scope = scopeArg ?? new NativeIntegrationOwner('onkyo', optionsArg).createFlowScope();
+  }
+
+  public async start(candidateArg: IDiscoveryCandidate, contextArg: INativeConfigFlowContext): Promise<IConfigFlowStep<IOnkyoConfig>> {
+    const context = this.#scope.admit(contextArg);
+    // The owned pure validator captures the selected candidate before yielding.
+    const validation = createOnkyoDiscoveryDescriptor().getValidators()[0].validate(candidateArg, {});
+    return this.#scope.run<IConfigFlowStep<IOnkyoConfig>>(context, undefined, async (leaseArg) => {
+      const matched = await validation;
+      leaseArg.assertOpen();
+      if (!matched.matched || !matched.candidate) return { kind: 'error', error: matched.reason };
+      const candidate = matched.candidate;
+      return {
+        kind: 'form', title: 'Connect selected Onkyo main zone',
+        description: 'Acknowledge the cleartext LAN protocol and set an absolute raw-volume ceiling. Home, endpoint, MAC and model are fixed by the host and selected candidate.',
+        fields: [
+          { name: 'allowUnencryptedLan', label: 'Acknowledge unauthenticated cleartext LAN', type: 'boolean', required: true },
+          { name: 'volumeLimitRaw', label: 'Maximum integer raw volume (0–100)', type: 'number', required: true },
+          { name: 'name', label: 'Name', type: 'text' },
+        ],
+        submit: async (valuesArg) => {
+          try {
+            const values = onkyoRecord(valuesArg, 'config flow values');
+            onkyoKeys(values, ['homeId', 'allowUnencryptedLan', 'volumeLimitRaw', 'name', 'requestTimeoutMs', 'maxPendingOperations']);
+            if (values.homeId !== undefined && values.homeId !== context.homeId) throw new TypeError('Onkyo submitted home must match the host-selected home.');
+            const config = normalizeOnkyoConfig({ ...values, homeId: context.homeId, host: candidate.host, port: candidate.port, macAddress: candidate.macAddress, model: candidate.model });
+            return await this.#scope.run<IConfigFlowStep<IOnkyoConfig>>(context, config.homeId, async (operationArg) => {
+              const client = new OnkyoClient(config, operationArg.context, operationArg.signal);
+              operationArg.own(() => client.destroy());
+              await client.getSnapshot(operationArg.signal);
+              operationArg.assertOpen();
+              return { kind: 'done', title: 'Onkyo receiver validated', config };
+            });
+          } catch (errorArg) {
+            return { kind: 'error', error: errorArg instanceof Error ? errorArg.message : 'Onkyo setup validation failed.' };
+          }
+        },
+      };
+    });
   }
+
+  public destroy(): Promise<void> { return this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#scope.retryCleanup(); }
 }

package/ts/integrations/onkyo/onkyo.classes.integration.ts

@@ -1,23 +1,132 @@
-import { SimpleLocalIntegration, SimpleLocalRuntime, type IIntegrationRuntime, type IIntegrationSetupContext } from '../../core/index.js';
+import * as plugins from '../../plugins.js';
+import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import { NativeIntegrationOwner } from '../../core/classes.nativeintegrationowner.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, INativeIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { OnkyoClient } from './onkyo.classes.client.js';
 import { OnkyoConfigFlow } from './onkyo.classes.configflow.js';
 import { createOnkyoDiscoveryDescriptor } from './onkyo.discovery.js';
-import type { IOnkyoConfig } from './onkyo.types.js';
-import { onkyoDomain, onkyoProfile } from './onkyo.types.js';
+import { OnkyoMapper } from './onkyo.mapper.js';
+import type { IOnkyoConfig, IOnkyoIntegrationOptions, IOnkyoSnapshot } from './onkyo.types.js';
+import { onkyoProfile } from './onkyo.types.js';
+import { normalizeOnkyoConfig, onkyoBoolean, onkyoInputId, onkyoInteger, onkyoKeys, onkyoRecord } from './onkyo.validation.js';
 
-export class OnkyoIntegration extends SimpleLocalIntegration<IOnkyoConfig> {
-  public readonly domain = onkyoDomain;
+export class OnkyoIntegration extends BaseIntegration<IOnkyoConfig> {
+  public readonly domain = 'onkyo';
+  public readonly displayName = 'Onkyo';
+  public readonly status = 'control-runtime' as const;
+  public readonly metadata = onkyoProfile.metadata;
   public readonly discoveryDescriptor = createOnkyoDiscoveryDescriptor();
-  public readonly configFlow = new OnkyoConfigFlow();
+  public readonly configFlow: OnkyoConfigFlow;
+  readonly #owner: NativeIntegrationOwner;
 
-  constructor() {
-    super(onkyoProfile);
+  constructor(optionsArg: IOnkyoIntegrationOptions = {}) {
+    super();
+    this.#owner = new NativeIntegrationOwner('onkyo', optionsArg);
+    this.configFlow = new OnkyoConfigFlow(optionsArg, this.#owner.createFlowScope());
   }
 
-  public async setup(configArg: IOnkyoConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new SimpleLocalRuntime(onkyoProfile, new OnkyoClient(configArg));
+  public setup(configArg: IOnkyoConfig, contextArg: INativeIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    let config: ReturnType<typeof normalizeOnkyoConfig>;
+    try {
+      config = normalizeOnkyoConfig(configArg);
+    } catch (errorArg) { return Promise.reject(errorArg); }
+    return this.#owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+      const client = new OnkyoClient(config, leaseArg.context, leaseArg.signal);
+      leaseArg.own(() => client.destroy());
+      const snapshot = await client.getSnapshot(leaseArg.signal);
+      leaseArg.assertOpen();
+      const runtime = new OnkyoRuntime(client, snapshot, () => leaseArg.close());
+      leaseArg.promoteToRuntime();
+      return runtime;
+    });
   }
+  public destroy(): Promise<void> { return this.#owner.close(); }
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
-
 export class HomeAssistantOnkyoIntegration extends OnkyoIntegration {}
+
+class OnkyoRuntime implements IIntegrationRuntime {
+  public readonly domain = 'onkyo';
+  readonly #deviceId: string;
+  readonly #entityId: string;
+  #closePromise?: Promise<void>;
+  constructor(private readonly client: OnkyoClient, snapshotArg: IOnkyoSnapshot, private readonly closeLease: () => Promise<void>) {
+    this.#deviceId = OnkyoMapper.deviceId(snapshotArg);
+    this.#entityId = OnkyoMapper.mediaEntityId(snapshotArg);
+  }
+  public isHealthy(): boolean { return this.client.isHealthy(); }
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> { return OnkyoMapper.toDevices(await this.client.getSnapshot(signalArg)); }
+  public async entities(): Promise<IIntegrationEntity[]> { return OnkyoMapper.toEntities(await this.client.getSnapshot()); }
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    if (typeof handlerArg !== 'function') throw new TypeError('Onkyo runtime subscriber must be a function.');
+    const unsubscribe = this.client.subscribe((eventArg) => {
+      const event: IIntegrationEvent = {
+        type: eventArg.type === 'error' ? 'error' : 'state_changed', integrationDomain: 'onkyo', deviceId: this.#deviceId,
+        entityId: this.#entityId, timestamp: Date.now(),
+        data: eventArg.type === 'snapshot' ? { snapshot: eventArg.snapshot, entity: OnkyoMapper.toEntities(eventArg.snapshot)[0] } :
+          eventArg.type === 'control' ? { observation: eventArg.observation } : { message: eventArg.error.message },
+      };
+      handlerArg(event);
+    }, signalArg);
+    return async () => unsubscribe();
+  }
+  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    try {
+      const request = onkyoRecord(requestArg, 'service request');
+      onkyoKeys(request, ['domain', 'service', 'target', 'data']);
+      if (typeof request.domain !== 'string' || typeof request.service !== 'string') throw new TypeError('Onkyo service domain and service must be strings.');
+      this.#assertTarget(request.target);
+      const data = request.data === undefined ? {} : onkyoRecord(request.data, 'service data');
+      if (request.domain === 'onkyo' && ['status', 'snapshot', 'refresh'].includes(request.service)) {
+        onkyoKeys(data, []); return { success: true, data: await this.client.getSnapshot() };
+      }
+      if (request.domain !== 'onkyo' && request.domain !== 'media_player') throw new TypeError('Onkyo service domain is unsupported.');
+      if (request.service === 'set_power') {
+        onkyoKeys(data, ['power']); return observed(await this.client.setPower(onkyoBoolean(data.power, 'power')));
+      }
+      if (request.service === 'set_mute' || request.service === 'volume_mute') {
+        onkyoKeys(data, ['muted']); return observed(await this.client.setMuted(onkyoBoolean(data.muted, 'mute')));
+      }
+      if (request.service === 'set_volume_raw') {
+        onkyoKeys(data, ['volumeRaw']); return observed(await this.client.setVolume(onkyoInteger(data.volumeRaw, 0, 100, 'raw volume')));
+      }
+      if (request.service === 'set_input' || request.service === 'select_source') {
+        onkyoKeys(data, ['inputId']); return observed(await this.client.setInput(onkyoInputId(data.inputId)));
+      }
+      throw new TypeError('Onkyo service is unsupported.');
+    } catch (errorArg) { return failed(errorArg); }
+  }
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      const request = onkyoRecord(requestArg, 'feature write');
+      onkyoKeys(request, ['device', 'feature', 'value']);
+      const device = onkyoRecord(request.device, 'feature device');
+      const feature = onkyoRecord(request.feature, 'feature');
+      if (device.id !== this.#deviceId || device.integrationDomain !== 'onkyo') throw new TypeError('Onkyo feature device is not owned by this home runtime.');
+      if (typeof feature.id !== 'string') throw new TypeError('Onkyo feature id must be a string.');
+      const value = request.value;
+      if (typeof value !== 'boolean' && typeof value !== 'number' && typeof value !== 'string') throw new TypeError('Onkyo control requires an explicit primitive value.');
+      return observed(await this.client.writeFeature(feature.id, value, signalArg));
+    } catch (errorArg) { return failed(errorArg); }
+  }
+  public destroy(): Promise<void> {
+    this.#closePromise ??= Promise.resolve().then(() => this.closeLease());
+    return this.#closePromise;
+  }
+  #assertTarget(valueArg: unknown): void {
+    const target = onkyoRecord(valueArg, 'service target');
+    onkyoKeys(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('Onkyo services require an exact owned device or main-zone entity target.');
+  }
+}
+function observed(observationArg: plugins.ecobridgeDeviceManager.IOnkyoControlObservation): IServiceCallResult {
+  return { success: true, data: { ...observationArg } };
+}
+function failed(errorArg: unknown): IServiceCallResult {
+  return { success: false, error: errorArg instanceof Error ? errorArg.message : 'Onkyo operation failed.', data: {
+    effectOutcome: errorArg instanceof plugins.ecobridgeDeviceManager.OnkyoProtocolError ? errorArg.effectOutcome : 'not-sent',
+    code: errorArg instanceof plugins.ecobridgeDeviceManager.OnkyoProtocolError ? errorArg.code : 'INVALID_OPERATION',
+  } };
+}

package/ts/integrations/onkyo/onkyo.discovery.ts

@@ -1,4 +1,42 @@
-import { createSimpleLocalDiscoveryDescriptor } from '../../core/index.js';
-import { onkyoProfile } from './onkyo.types.js';
+import * as plugins from '../../plugins.js';
+import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import type { IDiscoveryCandidate, IDiscoveryMatch } from '../../core/types.js';
+import type { IOnkyoSelectedProbeOptions } from './onkyo.types.js';
+import { onkyoHost, onkyoInteger, onkyoKeys, onkyoName, onkyoRecord, readOnkyoEndpoint } from './onkyo.validation.js';
 
-export const createOnkyoDiscoveryDescriptor = () => createSimpleLocalDiscoveryDescriptor(onkyoProfile);
+function matchCandidate(valueArg: unknown): IDiscoveryMatch {
+  try {
+    const input = onkyoRecord(valueArg, 'discovery candidate');
+    if (input.source !== 'manual' && input.source !== 'custom' || input.integrationDomain !== 'onkyo') {
+      return { matched: false, confidence: 'low', reason: 'An explicit manual/custom Onkyo candidate is required.' };
+    }
+    const candidate: IDiscoveryCandidate = {
+      source: input.source, integrationDomain: 'onkyo', ...readOnkyoEndpoint(input.host, input.macAddress, input.model, input.port),
+      name: input.name === undefined ? undefined : onkyoName(input.name, 'candidate name'),
+    };
+    return { matched: true, confidence: 'medium', reason: 'Explicit endpoint/MAC/model binding; live identity and main zone are checked during setup.', candidate };
+  } catch (errorArg) {
+    return { matched: false, confidence: 'low', reason: errorArg instanceof Error ? errorArg.message : 'Invalid Onkyo candidate.' };
+  }
+}
+
+export function createOnkyoDiscoveryDescriptor(): DiscoveryDescriptor {
+  return new DiscoveryDescriptor({ integrationDomain: 'onkyo', displayName: 'Onkyo' })
+    .addMatcher({ id: 'onkyo-manual-match', source: 'manual', matches: async (inputArg) => matchCandidate(inputArg) })
+    .addMatcher({ id: 'onkyo-custom-match', source: 'custom', matches: async (inputArg) => matchCandidate(inputArg) })
+    .addValidator({ id: 'onkyo-explicit-endpoint', validate: async (candidateArg) => matchCandidate(candidateArg) });
+}
+
+/** One explicitly selected unicast UDP probe; TCP setup still validates the chosen identity. */
+export async function probeSelectedOnkyo(optionsArg: IOnkyoSelectedProbeOptions): Promise<IDiscoveryCandidate> {
+  const options = onkyoRecord(optionsArg, 'selected probe options');
+  onkyoKeys(options, ['host', 'port', 'requestTimeoutMs', 'signal']);
+  if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) throw new TypeError('Onkyo probe signal must be an AbortSignal.');
+  const advertisement = await plugins.ecobridgeDeviceManager.probeOnkyo({
+    address: onkyoHost(options.host), port: options.port === undefined ? undefined : onkyoInteger(options.port, 1, 65535, 'probe port'),
+    timeoutMs: options.requestTimeoutMs === undefined ? undefined : onkyoInteger(options.requestTimeoutMs, 1, 60000, 'probe deadline'),
+    signal: options.signal,
+  });
+  return { source: 'custom', integrationDomain: 'onkyo', host: advertisement.address, port: advertisement.port,
+    model: advertisement.model, macAddress: advertisement.macAddress, manufacturer: 'Onkyo', metadata: { area: advertisement.area } };
+}

package/ts/integrations/onkyo/onkyo.mapper.ts

@@ -1,26 +1,53 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
-import { SimpleLocalMapper, type IIntegrationEntity, type ISimpleLocalSnapshot, type ISimpleLocalSnapshotOptions, type TSimpleLocalRawData } from '../../core/index.js';
-import type { IOnkyoConfig } from './onkyo.types.js';
-import { onkyoProfile } from './onkyo.types.js';
+import type * as plugins from '../../plugins.js';
+import type { IIntegrationEntity } from '../../core/types.js';
+import type { IOnkyoSnapshot } from './onkyo.types.js';
 
 export class OnkyoMapper {
-  public static toSnapshot(optionsArg: Omit<ISimpleLocalSnapshotOptions<IOnkyoConfig>, 'profile'>): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ ...optionsArg, profile: onkyoProfile });
+  public static deviceId(snapshotArg: Pick<IOnkyoSnapshot, 'homeId' | 'receiver'>): string {
+    return `onkyo:${encodeURIComponent(snapshotArg.homeId)}:${snapshotArg.receiver.macAddress}`;
   }
-
-  public static toSnapshotFromRaw(configArg: IOnkyoConfig, rawDataArg: TSimpleLocalRawData): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ profile: onkyoProfile, config: configArg, rawData: rawDataArg, online: true, source: 'manual' });
+  public static mediaEntityId(snapshotArg: Pick<IOnkyoSnapshot, 'homeId' | 'receiver'>): string {
+    return `${this.deviceId(snapshotArg)}:main`;
   }
-
-  public static toDevices(snapshotArg: ISimpleLocalSnapshot): shxInterfaces.data.IDeviceDefinition[] {
-    return SimpleLocalMapper.toDevices(onkyoProfile, snapshotArg);
+  public static toDevices(snapshotArg: IOnkyoSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    const receiver = snapshotArg.receiver;
+    const features: plugins.shxInterfaces.data.IDeviceFeature[] = [
+      { id: 'connectivity', capability: 'sensor', name: 'Connectivity', readable: true, writable: false },
+      { id: 'identity', capability: 'sensor', name: 'Receiver identity', readable: true, writable: false },
+      { id: 'inputs', capability: 'sensor', name: 'Advertised main-zone inputs', readable: true, writable: false },
+    ];
+    const state: plugins.shxInterfaces.data.IDeviceState[] = [
+      { featureId: 'connectivity', value: 'online', updatedAt: snapshotArg.observedAt },
+      { featureId: 'identity', value: { macAddress: receiver.macAddress, model: receiver.model, brand: receiver.brand }, updatedAt: snapshotArg.observedAt },
+      { featureId: 'inputs', value: { inputs: receiver.inputs.map((inputArg) => ({ ...inputArg })) }, updatedAt: snapshotArg.observedAt },
+    ];
+    const add = (idArg: string, nameArg: string, valueArg: boolean | number | string, writableArg: boolean, unitArg?: string): void => {
+      features.push({ id: idArg, capability: 'media', name: nameArg, readable: true, writable: writableArg, ...(unitArg ? { unit: unitArg } : {}) });
+      state.push({ featureId: idArg, value: valueArg, updatedAt: snapshotArg.observedAt });
+    };
+    if (snapshotArg.power !== undefined) add('power', 'Power', snapshotArg.power, true);
+    if (snapshotArg.muted !== undefined) add('mute', 'Mute', snapshotArg.muted, true);
+    if (snapshotArg.volumeRaw !== undefined) add('volume_raw', 'Absolute raw volume', snapshotArg.volumeRaw,
+      receiver.integerVolumeMaximum !== undefined && snapshotArg.volumeRaw <= receiver.integerVolumeMaximum, 'receiver raw units');
+    if (snapshotArg.inputId !== undefined) add('input', 'Input selector', snapshotArg.inputId, receiver.inputs.length > 0);
+    return [{
+      id: this.deviceId(snapshotArg), integrationDomain: 'onkyo', name: snapshotArg.name, manufacturer: 'Onkyo',
+      model: receiver.model, protocol: 'tcp', online: snapshotArg.online, features, state,
+      metadata: { homeId: snapshotArg.homeId, macAddress: receiver.macAddress, zone: 'main', wireProtocol: 'eiscp', lanAuthenticated: false,
+        inputs: receiver.inputs.map((inputArg) => ({ ...inputArg })), integerVolumeMaximum: receiver.integerVolumeMaximum,
+        volumeLimitRaw: snapshotArg.volumeLimitRaw,
+        ...(receiver.integerVolumeMaximum === undefined ? {} : { volumeRange: { minimumRaw: 0, maximumRaw: Math.min(receiver.integerVolumeMaximum, snapshotArg.volumeLimitRaw) } }),
+        observedAt: snapshotArg.observedAt },
+    }];
   }
-
-  public static toEntities(snapshotArg: ISimpleLocalSnapshot): IIntegrationEntity[] {
-    return SimpleLocalMapper.toEntities(onkyoProfile, snapshotArg);
-  }
-
-  public static slug(valueArg: unknown): string {
-    return SimpleLocalMapper.slug(valueArg);
+  public static toEntities(snapshotArg: IOnkyoSnapshot): IIntegrationEntity[] {
+    return [{
+      id: this.mediaEntityId(snapshotArg), uniqueId: this.mediaEntityId(snapshotArg), deviceId: this.deviceId(snapshotArg),
+      integrationDomain: 'onkyo', platform: 'media_player', name: snapshotArg.name,
+      state: snapshotArg.power === undefined ? 'unknown' : snapshotArg.power ? 'on' : 'off', available: snapshotArg.online,
+      attributes: { power: snapshotArg.power, muted: snapshotArg.muted, volumeRaw: snapshotArg.volumeRaw, inputId: snapshotArg.inputId,
+        inputs: snapshotArg.receiver.inputs.map((inputArg) => ({ ...inputArg })), integerVolumeMaximum: snapshotArg.receiver.integerVolumeMaximum,
+        volumeLimitRaw: snapshotArg.volumeLimitRaw, zone: 'main', observedAt: snapshotArg.observedAt },
+    }];
   }
 }

package/ts/integrations/onkyo/onkyo.types.ts

@@ -1,120 +1,65 @@
-import type { ISimpleLocalConfig, ISimpleLocalIntegrationProfile, ISimpleLocalSnapshot, TSimpleLocalRawData } from '../../core/index.js';
+import type * as plugins from '../../plugins.js';
 
-export const onkyoDomain = "onkyo";
-export const onkyoDefaultName = "Onkyo";
+export const onkyoDomain = 'onkyo';
+export const onkyoDefaultName = 'Onkyo';
 export const onkyoDefaultPort = 60128;
 export const onkyoDefaultTimeoutMs = 5000;
 
-export type TOnkyoRawData = TSimpleLocalRawData;
-export interface IOnkyoSnapshot extends ISimpleLocalSnapshot {}
-export interface IOnkyoConfig extends ISimpleLocalConfig {
-  url?: string;
-  macAddress?: string;
-  deviceId?: string;
+export interface IOnkyoIntegrationOptions {
+  /** A consistency binding; setup and flow still require explicit host home. */
+  readonly homeId?: string;
+  /** Shared pending/runtime/flow/retained-cleanup capacity; defaults to 16. */
+  readonly capacity?: number;
+}
+
+export interface IOnkyoConfig {
+  homeId: string;
+  host: string;
+  macAddress: string;
+  model: string;
+  /** The selected identity does not authenticate the cleartext LAN peer. */
+  allowUnencryptedLan: true;
+  /** Absolute integer receiver units; no percent or half-step conversion. */
+  volumeLimitRaw: number;
+  port?: number;
+  name?: string;
+  requestTimeoutMs?: number;
+  maxPendingOperations?: number;
 }
 export interface IHomeAssistantOnkyoConfig extends IOnkyoConfig {}
 
-export const onkyoProfile: ISimpleLocalIntegrationProfile = {
-  domain: onkyoDomain,
-  displayName: "Onkyo",
-  manufacturer: "Onkyo",
-  model: "Onkyo local integration",
-  defaultName: onkyoDefaultName,
-  defaultPort: onkyoDefaultPort,
-  defaultProtocol: 'tcp',
-  status: "control-runtime",
-  platforms: [
-    "media_player",
-    "switch",
-  ],
-  serviceDomains: [
-    "media_player",
-    "switch",
-  ],
-  controlServices: [
-    "media_pause",
-    "media_play",
-    "media_stop",
-    "select_source",
-    "toggle",
-    "turn_off",
-    "turn_on",
-    "volume_down",
-    "volume_mute",
-    "volume_set",
-    "volume_up",
-    "onkyo_select_hdmi_output",
-  ],
-  discoverySources: [
-    'manual',
-    'custom',
-  ],
-  discoveryKeywords: [
-    "onkyo",
-    "Onkyo",
-  ],
+/** Sequential live observations, never an injectable production data source. */
+export interface IOnkyoSnapshot extends plugins.ecobridgeDeviceManager.IOnkyoState {
+  readonly homeId: string;
+  readonly name: string;
+  readonly volumeLimitRaw: number;
+  readonly online: true;
+}
+export type TOnkyoRawData = IOnkyoSnapshot;
+export type TOnkyoClientEvent =
+  | { type: 'snapshot'; snapshot: IOnkyoSnapshot }
+  | { type: 'control'; observation: plugins.ecobridgeDeviceManager.IOnkyoControlObservation }
+  | { type: 'error'; error: Error };
+
+export interface IOnkyoSelectedProbeOptions {
+  host: string;
+  port?: number;
+  requestTimeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+export const onkyoProfile = {
+  domain: onkyoDomain, displayName: onkyoDefaultName, status: 'control-runtime',
   metadata: {
-    "source": "home-assistant/core",
-    "upstreamPath": "homeassistant/components/onkyo",
-    "upstreamDomain": "onkyo",
-    "integrationType": "device",
-    "iotClass": "local_push",
-    "qualityScale": "bronze",
-    "requirements": [
-      "aioonkyo==0.4.0",
-    ],
-    "dependencies": [
-      "network",
-    ],
-    "codeowners": [
-      "@arturpragacz",
-      "@eclair4151",
-    ],
-    "configFlow": true,
-    "documentation": "https://www.home-assistant.io/integrations/onkyo",
-    "loggers": [
-      "aioonkyo",
-    ],
-    "runtime": {
-      "type": "control-runtime",
-      "services": [
-        "snapshot",
-        "status",
-        "refresh",
-        "media_pause",
-        "media_play",
-        "media_stop",
-        "select_source",
-        "toggle",
-        "turn_off",
-        "turn_on",
-        "volume_down",
-        "volume_mute",
-        "volume_set",
-        "volume_up",
-        "onkyo_select_hdmi_output",
-      ],
-      "platforms": [
-        "media_player",
-        "switch",
-      ],
-      "controls": "native eISCP TCP commands for main-zone media controls; injected client.execute or commandExecutor remains supported",
-    },
-    "localApi": {
-      "status": "Native Onkyo/Pioneer eISCP TCP polling and main-zone control are implemented for manual host/port configurations; UDP discovery/interview and persistent push subscriptions are not implemented.",
-      "implemented": [
-        "native eISCP TCP polling on port 60128 for main-zone power, volume, mute, input source, and listening mode status",
-        "native eISCP TCP control for power, volume, mute, source selection, HDMI output, and NET play/pause/stop commands",
-        "manual local setup for Onkyo endpoints, snapshots, rawData, snapshotProvider, and injected native clients",
-        "runtime mapping for Onkyo device snapshots and Home Assistant platform metadata",
-        "safe command delegation to injected client.execute or commandExecutor when no live eISCP host is configured",
-      ],
-      "explicitUnsupported": [
-        "UDP eISCP discovery/interview broadcast semantics; use manual host configuration or external discovery metadata",
-        "persistent local_push subscription and unsolicited status update processing; this client performs focused request/response TCP polling and commands",
-        "multi-zone and channel-muting switch discovery beyond main-zone eISCP status/control",
-        "Home Assistant entity registry migrations and repair flows",
-      ],
+    source: 'home-assistant/core', upstreamDomain: onkyoDomain, configFlow: true,
+    localApi: {
+      status: 'Selected native Onkyo main-zone eISCP TCP through devicemanager.',
+      implemented: ['selected unicast UDP advertisement', 'live MAC/model and enabled main-zone admission',
+        'explicit power/mute, advertised input selectors and bounded absolute integer raw volume',
+        'explicit captured host home and optional actual caller-owned NoSQL store', 'events from explicit observations and joined terminal shutdown'],
+      explicitUnsupported: ['broadcast discovery', 'cloud access', 'injected clients and snapshots', 'other zones',
+        'percentage or half-step volume conversion', 'toggle/increment/media transport/arbitrary commands',
+        'automatic reconnect, effect retry or replay', 'unsolicited push subscription', 'cryptographic LAN peer authentication'],
     },
   },
-};
+} as const;

package/ts/integrations/onkyo/onkyo.validation.ts

@@ -0,0 +1,85 @@
+import * as plugins from '../../plugins.js';
+import type { IOnkyoConfig } from './onkyo.types.js';
+import { onkyoDefaultPort, onkyoDefaultTimeoutMs } from './onkyo.types.js';
+
+interface IOnkyoNormalizedConfig extends IOnkyoConfig {
+  port: number;
+  requestTimeoutMs: number;
+  maxPendingOperations: number;
+}
+
+export function onkyoRecord(valueArg: unknown, nameArg: string): Record<string, unknown> {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(valueArg))) {
+    throw new TypeError(`Onkyo ${nameArg} 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) {
+      throw new TypeError(`Onkyo ${nameArg} may not contain symbols, accessors or hidden fields.`);
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+}
+
+export function onkyoKeys(recordArg: Record<string, unknown>, keysArg: readonly string[]): void {
+  if (Object.keys(recordArg).some((keyArg) => !keysArg.includes(keyArg))) throw new TypeError('Onkyo data contains unsupported fields.');
+}
+
+export function onkyoInteger(valueArg: unknown, minimumArg: number, maximumArg: number, nameArg: string): number {
+  if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < minimumArg || valueArg > maximumArg) {
+    throw new RangeError(`Onkyo ${nameArg} must be an integer from ${minimumArg} through ${maximumArg}.`);
+  }
+  return valueArg;
+}
+
+export function onkyoName(valueArg: unknown, nameArg: string): string {
+  if (typeof valueArg !== 'string' || !valueArg.trim() || valueArg.length > 256 || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`Onkyo ${nameArg} must be a non-empty string without control characters, at most 256 characters.`);
+  }
+  return valueArg;
+}
+
+export function onkyoHost(valueArg: unknown): string {
+  if (typeof valueArg !== 'string' || plugins.net.isIP(valueArg) !== 4) throw new TypeError('Onkyo host must be a selected unicast IPv4 address.');
+  const octets = valueArg.split('.').map(Number);
+  const local = octets[0] === 10 || octets[0] === 127 || octets[0] === 192 && octets[1] === 168 ||
+    octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31 || octets[0] === 169 && octets[1] === 254;
+  if (!local || octets[3] === 255) throw new TypeError('Onkyo host must be a private, loopback or link-local unicast IPv4 address.');
+  return valueArg;
+}
+
+export function readOnkyoEndpoint(hostArg: unknown, macArg: unknown, modelArg: unknown, portArg?: unknown): Pick<IOnkyoNormalizedConfig, 'host' | 'macAddress' | 'model' | 'port'> {
+  const host = onkyoHost(hostArg);
+  if (typeof macArg !== 'string' || !/^[0-9a-f]{12}$/i.test(macArg) || /^(0{12}|f{12})$/i.test(macArg)) {
+    throw new TypeError('Onkyo macAddress must be a nonempty twelve-digit receiver MAC.');
+  }
+  if (typeof modelArg !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$/.test(modelArg)) throw new TypeError('Onkyo model must be the exact selected receiver model.');
+  return { host, macAddress: macArg.toUpperCase(), model: modelArg,
+    port: onkyoInteger(portArg === undefined ? onkyoDefaultPort : portArg, 1, 65535, 'port') };
+}
+
+export function normalizeOnkyoConfig(valueArg: unknown): Readonly<IOnkyoNormalizedConfig> {
+  const config = onkyoRecord(valueArg, 'configuration');
+  onkyoKeys(config, ['homeId', 'host', 'macAddress', 'model', 'allowUnencryptedLan', 'volumeLimitRaw', 'port', 'name', 'requestTimeoutMs', 'maxPendingOperations']);
+  if (config.allowUnencryptedLan !== true) throw new TypeError('Onkyo requires an explicit allowUnencryptedLan: true acknowledgement.');
+  return Object.freeze({
+    homeId: onkyoName(config.homeId, 'homeId'), ...readOnkyoEndpoint(config.host, config.macAddress, config.model, config.port),
+    allowUnencryptedLan: true, volumeLimitRaw: onkyoInteger(config.volumeLimitRaw, 0, 100, 'volumeLimitRaw'),
+    name: config.name === undefined ? undefined : onkyoName(config.name, 'name'),
+    requestTimeoutMs: onkyoInteger(config.requestTimeoutMs === undefined ? onkyoDefaultTimeoutMs : config.requestTimeoutMs, 1, 60000, 'requestTimeoutMs'),
+    maxPendingOperations: onkyoInteger(config.maxPendingOperations === undefined ? 16 : config.maxPendingOperations, 1, 128, 'maxPendingOperations'),
+  });
+}
+
+export function onkyoBoolean(valueArg: unknown, nameArg: string): boolean {
+  if (typeof valueArg !== 'boolean') throw new TypeError(`Onkyo ${nameArg} requires an explicit boolean.`);
+  return valueArg;
+}
+
+export function onkyoInputId(valueArg: unknown): string {
+  if (typeof valueArg !== 'string' || !/^[0-9a-f]{2}$/i.test(valueArg)) throw new TypeError('Onkyo input requires an advertised two-digit selector ID.');
+  return valueArg.toUpperCase();
+}