@smarthome.exchange/integrations 1.0.0 → 3.0.0

package/ts/integrations/denonavr/denonavr.classes.configflow.ts

@@ -1,47 +1,54 @@
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
-import type { IDenonavrConfig } from './denonavr.types.js';
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
+import type { IDenonavrConfig, IDenonavrIntegrationOptions } from './denonavr.types.js';
+import { DenonavrClient } from './denonavr.classes.client.js';
+import { denonavrRecord, normalizeDenonavrConfig } from './denonavr.validation.js';
 
 export class DenonavrConfigFlow implements IConfigFlow<IDenonavrConfig> {
-  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IDenonavrConfig>> {
-    void contextArg;
+  private readonly scope: NativeIntegrationScope;
+
+  public constructor(options: IDenonavrIntegrationOptions = {}, scope?: NativeIntegrationScope) {
+    this.scope = scope ?? new NativeIntegrationOwner('denonavr', options).createFlowScope();
+  }
+
+  public async start(input: IDiscoveryCandidate, context: IConfigFlowContext): Promise<IConfigFlowStep<IDenonavrConfig>> {
+    const candidate = denonavrRecord(input);
+    if (candidate.integrationDomain !== 'denonavr') return { kind: 'error', error: 'Candidate does not belong to DenonAVR.' };
+    const metadata = candidate.metadata === undefined ? {} : denonavrRecord(candidate.metadata);
+    const hints = { host: candidate.host, expectedUdn: candidate.id, model: candidate.model, descriptionUrl: metadata.descriptionUrl };
+    const admitted = this.scope.admit(context);
     return {
-      kind: 'form',
-      title: 'Connect Denon AVR Network Receiver',
-      description: 'Configure the local Denon/Marantz AVR HTTP endpoint.',
+      kind: 'form', title: 'Connect selected Denon or Marantz receiver',
+      description: 'Confirm the exact UPnP identity, selected IPv4 description URL and owner volume ceiling for the host-selected home. LAN identity is unauthenticated. Enable network control in standby when needed.',
       fields: [
-        { name: 'host', label: 'Host', type: 'text', required: true },
-        { name: 'port', label: 'Port', type: 'number' },
-        { name: 'name', label: 'Name', type: 'text' },
-        { name: 'model', label: 'Model', type: 'text' },
+        { name: 'host', label: 'Selected receiver IPv4', type: 'text', required: true },
+        { name: 'descriptionUrl', label: 'Selected UPnP description URL', type: 'text', required: true },
+        { name: 'expectedUdn', label: 'Expected UPnP UDN', type: 'text', required: true },
+        { name: 'model', label: 'Documented model', type: 'select', required: true, options: ['AVR-1913', 'AVR-2113CI', 'NR1605', 'SR5009'].map((value) => ({ label: value, value })) },
+        { name: 'maximumVolumeDb', label: 'Owner maximum volume (dB)', type: 'number', required: true },
+        { name: 'name', label: 'Display name', type: 'text' },
       ],
-      submit: async (valuesArg) => {
-        const port = typeof valuesArg.port === 'number' ? valuesArg.port : Number(valuesArg.port || candidateArg.port || 80);
-        const name = stringValue(valuesArg.name) || candidateArg.name;
-        const model = stringValue(valuesArg.model) || candidateArg.model;
-        return {
-          kind: 'done',
-          title: 'Denon AVR configured',
-          config: {
-            host: stringValue(valuesArg.host) || candidateArg.host || '',
-            port: Number.isFinite(port) ? port : 80,
-            name,
-            model,
-            manufacturer: candidateArg.manufacturer,
-            serialNumber: candidateArg.serialNumber,
-            receiverInfo: name || model || candidateArg.manufacturer || candidateArg.serialNumber ? {
-              name,
-              friendlyName: name,
-              manufacturer: candidateArg.manufacturer,
-              modelName: model,
-              serialNumber: candidateArg.serialNumber,
-            } : undefined,
-          },
-        };
+      submit: async (inputValues) => {
+        try {
+          const values = denonavrRecord(inputValues, ['homeId', 'host', 'descriptionUrl', 'expectedUdn', 'model', 'maximumVolumeDb', 'name', 'port', 'timeoutMs', 'maxPendingOperations', 'maxDescriptionBytes']);
+          if (values.homeId !== undefined && values.homeId !== admitted.homeId) throw new Error('DenonAVR submitted home conflicts with the host-selected home.');
+          const config = normalizeDenonavrConfig({ ...hints, ...values, homeId: admitted.homeId });
+          return await this.scope.run(admitted, config.homeId, async (lease) => {
+            const client = new DenonavrClient(config, lease.context);
+            lease.own(() => client.retryCleanup());
+            await client.start(lease.signal);
+            lease.assertOpen();
+            return { kind: 'done', title: 'Selected receiver admitted', config };
+          });
+        } catch (error) {
+          if (error instanceof AggregateError) throw error;
+          return { kind: 'error', title: 'Receiver admission failed', error: error instanceof Error ? error.message : 'Receiver admission failed.' };
+        }
       },
     };
   }
-}
 
-const stringValue = (valueArg: unknown): string | undefined => {
-  return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
-};
+  public destroy(): Promise<void> { return this.scope.close(); }
+
+  public retryCleanup(): Promise<void> { return this.scope.retryCleanup(); }
+}

package/ts/integrations/denonavr/denonavr.classes.integration.ts

@@ -1,157 +1,211 @@
-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, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { DenonavrClient } from './denonavr.classes.client.js';
 import { DenonavrConfigFlow } from './denonavr.classes.configflow.js';
 import { createDenonavrDiscoveryDescriptor } from './denonavr.discovery.js';
 import { DenonavrMapper } from './denonavr.mapper.js';
-import type { IDenonavrConfig, TDenonavrCommand, TDenonavrZone } from './denonavr.types.js';
+import { denonavrRecord, normalizeDenonavrConfig, validateDenonavrControl } from './denonavr.validation.js';
+import type { IDenonavrConfig, IDenonavrEffectResult, IDenonavrIntegrationOptions, IDenonavrSnapshot, TDenonavrControl } from './denonavr.types.js';
 
 export class DenonavrIntegration extends BaseIntegration<IDenonavrConfig> {
   public readonly domain = 'denonavr';
-  public readonly displayName = 'Denon AVR Network Receivers';
+  public readonly displayName = 'Denon and Marantz selected receivers';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createDenonavrDiscoveryDescriptor();
-  public readonly configFlow = new DenonavrConfigFlow();
-  public readonly metadata = {
-    source: 'home-assistant/core',
-    upstreamPath: 'homeassistant/components/denonavr',
-    upstreamDomain: 'denonavr',
-    integrationType: 'device',
-    iotClass: 'local_push',
-    requirements: ['denonavr==1.3.2'],
-    dependencies: [],
-    afterDependencies: [],
-    codeowners: ['@ol-iver', '@starkillerOG'],
-    configFlow: true,
-    documentation: 'https://www.home-assistant.io/integrations/denonavr',
-  };
-
-  public async setup(configArg: IDenonavrConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new DenonavrRuntime(new DenonavrClient(configArg));
+  public readonly configFlow: DenonavrConfigFlow;
+  public readonly metadata = { source: 'native-typescript', integrationType: 'device', iotClass: 'local_poll' };
+  private readonly owner: NativeIntegrationOwner;
+
+  public constructor(options: IDenonavrIntegrationOptions = {}) {
+    super();
+    this.owner = new NativeIntegrationOwner('denonavr', options);
+    this.configFlow = new DenonavrConfigFlow(options, this.owner.createFlowScope());
   }
 
-  public async destroy(): Promise<void> {}
+  public setup(config: IDenonavrConfig, context: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    let selected: ReturnType<typeof normalizeDenonavrConfig>;
+    try { selected = normalizeDenonavrConfig(config); } catch (error) { return Promise.reject(error); }
+    try {
+      return this.owner.runSetup(context, selected.homeId, async (lease) => {
+        const client = new DenonavrClient(selected, lease.context);
+        let runtime: DenonavrRuntime | undefined;
+        lease.own(async () => {
+          const ownedRuntime = runtime;
+          const results = await Promise.allSettled([
+            Promise.resolve().then(() => client.retryCleanup()),
+            ...(ownedRuntime ? [Promise.resolve().then(() => ownedRuntime.closeSubscriptions())] : []),
+          ]);
+          const failures = results.filter((entry): entry is PromiseRejectedResult => entry.status === 'rejected');
+          if (failures.length) throw new AggregateError(failures.map((entry) => entry.reason), 'DenonAVR owned client or subscriber cleanup failed.');
+        });
+        const initial = await client.start(lease.signal);
+        lease.assertOpen();
+        runtime = new DenonavrRuntime(client, initial, lease);
+        lease.promoteToRuntime();
+        return runtime;
+      });
+    } catch (error) { return Promise.reject(error); }
+  }
+
+  public destroy(): Promise<void> {
+    return this.owner.close();
+  }
+
+  public retryCleanup(): Promise<void> { return this.owner.retryCleanup(); }
 }
 
 export class HomeAssistantDenonavrIntegration extends DenonavrIntegration {}
 
+interface IDenonavrSubscription {
+  handler: (event: IIntegrationEvent) => void;
+  active: boolean;
+  failed: boolean;
+  failure?: unknown;
+  detach(): void;
+  stop(): Promise<void>;
+}
+
 class DenonavrRuntime implements IIntegrationRuntime {
-  public domain = 'denonavr';
+  public readonly domain = 'denonavr';
+  private readonly subscriptions = new Set<IDenonavrSubscription>();
+  private readonly parentAbort: () => void;
+  private closePromise?: Promise<void>;
+  private closed = false;
+
+  public constructor(private readonly client: DenonavrClient, private snapshot: IDenonavrSnapshot,
+    private readonly lease: INativeSetupLease) {
+    // The owning integration retains failed runtimes; closePromise exposes asynchronous abort cleanup failures.
+    this.parentAbort = () => { void this.destroy().catch(() => {}); };
+    lease.signal.addEventListener('abort', this.parentAbort, { once: true });
+    if (lease.signal.aborted) this.parentAbort();
+  }
 
-  constructor(private readonly client: DenonavrClient) {}
+  public isHealthy(): boolean { return !this.closed && this.client.isHealthy(); }
 
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return DenonavrMapper.toDevices(await this.client.getSnapshot());
+  public async devices(signal?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    this.assertOpen();
+    const snapshot = await this.client.getSnapshot(signal);
+    this.publish(snapshot);
+    return DenonavrMapper.toDevices(snapshot);
   }
 
   public async entities(): Promise<IIntegrationEntity[]> {
-    return DenonavrMapper.toEntities(await this.client.getSnapshot());
+    this.assertOpen();
+    const snapshot = await this.client.getSnapshot();
+    this.publish(snapshot);
+    return DenonavrMapper.toEntities(snapshot);
   }
 
-  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.domain !== 'media_player') {
-      return { success: false, error: `Unsupported Denon AVR service domain: ${requestArg.domain}` };
-    }
-
-    const zone = this.zoneFromRequest(requestArg);
-    const command = this.commandFromService(requestArg);
-    if (!command) {
-      return { success: false, error: `Unsupported Denon AVR media_player service: ${requestArg.service}` };
-    }
+  public async writeFeature(input: IDeviceFeatureWriteRequest, signal?: AbortSignal): Promise<IServiceCallResult> {
+    this.assertOpen();
+    const request = denonavrRecord(input, ['device', 'feature', 'value']);
+    const device = denonavrRecord(request.device);
+    const feature = denonavrRecord(request.feature);
+    const canonical = DenonavrMapper.toDevices(this.snapshot)[0];
+    if (device.id !== canonical.id || device.integrationDomain !== this.domain) throw new Error('DenonAVR feature target is outside the selected home and receiver.');
+    const admitted = canonical.features.find((entry) => entry.id === feature.id);
+    if (!admitted?.writable || feature.capability !== admitted.capability) throw new Error('DenonAVR feature is not writable for the selected receiver.');
+    const control = validateDenonavrControl({ feature: admitted.id, value: request.value });
+    return this.control(control, signal);
+  }
 
-    try {
-      const result = await this.client.execute({
-        command,
-        zone,
-        source: this.stringData(requestArg, 'source'),
-        volumeLevel: this.numberData(requestArg, 'volume_level'),
-        muted: this.boolData(requestArg, 'is_volume_muted') ?? this.boolData(requestArg, 'mute'),
-      });
-      return { success: true, data: result };
-    } catch (error) {
-      return { success: false, error: error instanceof Error ? error.message : String(error) };
-    }
+  public async callService(input: IServiceCallRequest): Promise<IServiceCallResult> {
+    this.assertOpen();
+    const request = denonavrRecord(input, ['domain', 'service', 'target', 'data']);
+    const target = denonavrRecord(request.target, ['deviceId', 'entityId']);
+    const deviceId = DenonavrMapper.deviceId(this.snapshot.homeId, this.snapshot.identity.udn);
+    const entityId = DenonavrMapper.entityId(this.snapshot.homeId, this.snapshot.identity.udn);
+    if ((!target.deviceId && !target.entityId) || (target.deviceId !== undefined && target.deviceId !== deviceId)
+      || (target.entityId !== undefined && target.entityId !== entityId)) throw new Error('DenonAVR service target is outside the selected home and receiver.');
+    if (request.domain !== 'media_player') throw new Error('DenonAVR services use media_player.');
+    let control: TDenonavrControl;
+    if (request.service === 'turn_on' || request.service === 'turn_off') {
+      denonavrRecord(request.data ?? {}, []);
+      control = { feature: 'power', value: request.service === 'turn_on' };
+    } else if (request.service === 'volume_set') {
+      const data = denonavrRecord(request.data, ['volume_db']);
+      control = validateDenonavrControl({ feature: 'volume_db', value: data.volume_db });
+    } else if (request.service === 'volume_mute') {
+      const data = denonavrRecord(request.data, ['is_volume_muted']);
+      control = validateDenonavrControl({ feature: 'muted', value: data.is_volume_muted });
+    } else if (request.service === 'select_source') {
+      const data = denonavrRecord(request.data, ['source']);
+      control = validateDenonavrControl({ feature: 'input', value: data.source });
+    } else throw new Error('DenonAVR supports explicit power, mute, absolute dB volume and observed physical inputs only.');
+    return this.control(control);
   }
 
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
+  /** Emits only newly completed adapter observations; it does not create a receiver polling loop. */
+  public async subscribe(handler: (event: IIntegrationEvent) => void, signal?: AbortSignal): Promise<() => Promise<void>> {
+    this.assertOpen();
+    if (typeof handler !== 'function' || (signal !== undefined && !(signal instanceof AbortSignal))) throw new TypeError('DenonAVR subscription requires a callback and optional AbortSignal.');
+    signal?.throwIfAborted();
+    if (this.subscriptions.size >= 32) throw new Error('DenonAVR subscription capacity reached.');
+    const subscription: IDenonavrSubscription = {
+      handler, active: true, failed: false,
+      detach: () => { subscription.active = false; signal?.removeEventListener('abort', aborted); },
+      stop: async () => {
+        subscription.detach();
+        this.subscriptions.delete(subscription);
+        if (subscription.failed) throw subscription.failure;
+      },
+    };
+    const aborted = () => { subscription.detach(); this.subscriptions.delete(subscription); };
+    signal?.addEventListener('abort', aborted, { once: true });
+    this.subscriptions.add(subscription);
+    if (signal?.aborted) aborted();
+    return subscription.stop;
   }
 
-  private commandFromService(requestArg: IServiceCallRequest): TDenonavrCommand | undefined {
-    if (requestArg.service === 'turn_on') {
-      return 'turn_on';
-    }
-    if (requestArg.service === 'turn_off') {
-      return 'turn_off';
-    }
-    if (requestArg.service === 'volume_up') {
-      return 'volume_up';
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      this.closePromise = Promise.resolve().then(() => this.lease.close());
+      this.closed = true;
+      this.lease.signal.removeEventListener('abort', this.parentAbort);
+      for (const subscription of this.subscriptions) subscription.detach();
     }
-    if (requestArg.service === 'volume_down') {
-      return 'volume_down';
-    }
-    if (requestArg.service === 'volume_set') {
-      return 'set_volume';
-    }
-    if (requestArg.service === 'volume_mute') {
-      return 'mute';
-    }
-    if (requestArg.service === 'select_source') {
-      return 'select_source';
-    }
-    if (requestArg.service === 'media_play' || requestArg.service === 'play') {
-      return 'play';
-    }
-    if (requestArg.service === 'media_pause' || requestArg.service === 'pause') {
-      return 'pause';
-    }
-    if (requestArg.service === 'media_stop' || requestArg.service === 'stop') {
-      return 'stop';
-    }
-    if (requestArg.service === 'media_play_pause' || requestArg.service === 'play_pause') {
-      return 'play_pause';
-    }
-    if (requestArg.service === 'media_previous_track' || requestArg.service === 'previous_track') {
-      return 'previous_track';
-    }
-    if (requestArg.service === 'media_next_track' || requestArg.service === 'next_track') {
-      return 'next_track';
-    }
-    return undefined;
+    return this.closePromise;
   }
 
-  private zoneFromRequest(requestArg: IServiceCallRequest): TDenonavrZone {
-    const zone = this.stringData(requestArg, 'zone');
-    if (zone === 'Zone2' || zone === 'zone2') {
-      return 'Zone2';
-    }
-    if (zone === 'Zone3' || zone === 'zone3') {
-      return 'Zone3';
-    }
-    const entityId = requestArg.target.entityId?.toLowerCase() || '';
-    if (entityId.includes('zone2')) {
-      return 'Zone2';
-    }
-    if (entityId.includes('zone3')) {
-      return 'Zone3';
-    }
-    return 'Main';
+  public async closeSubscriptions(): Promise<void> {
+    this.closed = true;
+    this.lease.signal.removeEventListener('abort', this.parentAbort);
+    const results = await Promise.allSettled([...this.subscriptions].map((entry) => entry.stop()));
+    const failures = results.filter((entry): entry is PromiseRejectedResult => entry.status === 'rejected');
+    if (failures.length) throw new AggregateError(failures.map((entry) => entry.reason), 'DenonAVR subscriber cleanup failed.');
   }
 
-  private stringData(requestArg: IServiceCallRequest, keyArg: string): string | undefined {
-    const value = requestArg.data?.[keyArg];
-    return typeof value === 'string' ? value : undefined;
+  private async control(control: TDenonavrControl, signal?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      const result = await this.client.setControl(control, signal);
+      this.publish(result.snapshot);
+      return this.result(result);
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : 'DenonAVR control failed.',
+        data: { effectOutcome: error instanceof plugins.ecobridgeDeviceManager.DenonProtocolError ? error.effectOutcome : 'not-sent' } };
+    }
   }
 
-  private numberData(requestArg: IServiceCallRequest, keyArg: string): number | undefined {
-    const value = requestArg.data?.[keyArg];
-    return typeof value === 'number' ? value : undefined;
+  private result(result: IDenonavrEffectResult): IServiceCallResult {
+    return { success: result.outcome === 'observed-target', ...(result.outcome === 'indeterminate' ? { error: 'Requested receiver setting was not observed.' } : {}),
+      data: { dispatch: result.dispatch, outcome: result.outcome, devices: DenonavrMapper.toDevices(result.snapshot), entities: DenonavrMapper.toEntities(result.snapshot) } };
   }
 
-  private boolData(requestArg: IServiceCallRequest, keyArg: string): boolean | undefined {
-    const value = requestArg.data?.[keyArg];
-    return typeof value === 'boolean' ? value : undefined;
+  private publish(snapshot: IDenonavrSnapshot): void {
+    if (this.closed) return;
+    this.snapshot = snapshot;
+    for (const subscription of [...this.subscriptions]) {
+      if (this.closed) break;
+      if (!subscription.active) continue;
+      try {
+        subscription.handler({ type: 'state_changed', integrationDomain: this.domain,
+          deviceId: DenonavrMapper.deviceId(snapshot.homeId, snapshot.identity.udn), entityId: DenonavrMapper.entityId(snapshot.homeId, snapshot.identity.udn),
+          data: structuredClone(snapshot), timestamp: Date.now() });
+      } catch (error) { subscription.failed = true; subscription.failure = error; subscription.detach(); }
+    }
   }
+
+  private assertOpen(): void { if (this.closed) throw new Error('DenonAVR runtime is closed.'); }
 }