@smarthome.exchange/integrations 1.0.0 → 2.0.0

package/ts/integrations/yamaha/yamaha.classes.integration.ts

@@ -1,17 +1,245 @@
-import { SimpleLocalIntegration } from '../../core/index.js';
+import * as plugins from '../../plugins.js';
+import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, INativeIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { YamahaClient } from './yamaha.classes.client.js';
 import { YamahaConfigFlow } from './yamaha.classes.configflow.js';
 import { createYamahaDiscoveryDescriptor } from './yamaha.discovery.js';
-import type { IYamahaConfig } from './yamaha.types.js';
-import { yamahaDomain, yamahaProfile } from './yamaha.types.js';
+import { YamahaMapper } from './yamaha.mapper.js';
+import { normalizeYamahaConfig, yamahaRecord, yamahaText, validateYamahaControl } from './yamaha.validation.js';
+import type { IYamahaConfig, IYamahaEffectResult, IYamahaSnapshot, TYamahaControl } from './yamaha.types.js';
 
-export class YamahaIntegration extends SimpleLocalIntegration<IYamahaConfig> {
-  public readonly domain = yamahaDomain;
+export interface IYamahaIntegrationOptions { readonly homeId?: string; }
+
+export class YamahaIntegration extends BaseIntegration<IYamahaConfig> {
+  public readonly domain = 'yamaha';
+  public readonly displayName = 'Yamaha RX-V485 main zone';
+  public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createYamahaDiscoveryDescriptor();
-  public readonly configFlow = new YamahaConfigFlow();
+  public readonly configFlow: YamahaConfigFlow;
+  public readonly metadata = { source: 'native-typescript', integrationType: 'device', iotClass: 'local_poll', selectedModel: 'RX-V485', zone: 'main' };
+  private readonly owner: NativeIntegrationOwner;
+  private closePromise?: Promise<void>;
+
+  public constructor(options: IYamahaIntegrationOptions = {}) {
+    super();
+    const values = yamahaRecord(options, ['homeId']);
+    this.owner = new NativeIntegrationOwner(this.domain, values.homeId === undefined ? {} : { homeId: yamahaText(values.homeId, 'constructor home ID') });
+    this.configFlow = new YamahaConfigFlow(this.owner.createFlowScope());
+  }
+
+  public setup(config: IYamahaConfig, context: INativeIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    try {
+      const normalized = normalizeYamahaConfig(config);
+      return this.owner.runSetup(context, normalized.homeId, async (lease) => {
+        const client = new YamahaClient(normalized, lease.context);
+        let runtime: YamahaRuntime | undefined;
+        let cleanupStarted = false;
+        lease.own(() => {
+          const retry = cleanupStarted;
+          cleanupStarted = true;
+          return runtime ? runtime.closeOwnedResources(retry) : retry ? client.retryCleanup() : client.destroy();
+        });
+        const initial = await client.start(lease.signal);
+        lease.assertOpen();
+        runtime = new YamahaRuntime(client, initial, lease);
+        lease.promoteToRuntime();
+        return runtime;
+      });
+    } catch (error) { return Promise.reject(error); }
+  }
 
-  constructor() {
-    super(yamahaProfile);
+  public destroy(): Promise<void> {
+    if (!this.closePromise) {
+      let closing: Promise<void>[] = [];
+      this.closePromise = Promise.resolve().then(async () => {
+        const results = await Promise.allSettled(closing);
+        const failures = results.filter((entry): entry is PromiseRejectedResult => entry.status === 'rejected');
+        if (failures.length) throw new AggregateError(failures.map((entry) => entry.reason), 'Yamaha owned cleanup failed.');
+      });
+      closing = [this.configFlow.destroy(), this.owner.close()];
+    }
+    return this.closePromise;
   }
+  public retryCleanup(): Promise<void> { return this.owner.retryCleanup(); }
 }
 
 export class HomeAssistantYamahaIntegration extends YamahaIntegration {}
+
+interface IYamahaSubscription {
+  handler: (event: IIntegrationEvent) => void;
+  active: boolean;
+  failed: boolean;
+  failure?: unknown;
+  callbacks: Set<Promise<void>>;
+  stopPromise?: Promise<void>;
+  detach(): void;
+  stop(): Promise<void>;
+}
+
+class YamahaRuntime implements IIntegrationRuntime {
+  public readonly domain = 'yamaha';
+  private readonly subscriptions = new Set<IYamahaSubscription>();
+  private closePromise?: Promise<void>;
+  private closed = false;
+
+  public constructor(private readonly client: YamahaClient, private snapshot: IYamahaSnapshot,
+    private readonly lease: INativeSetupLease) {}
+
+  public isHealthy(): boolean { return !this.closed && !this.lease.signal.aborted && this.client.isHealthy(); }
+
+  public async devices(signal?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    this.assertOpen();
+    const snapshot = await this.client.getSnapshot(signal);
+    this.publish(snapshot);
+    return YamahaMapper.toDevices(snapshot);
+  }
+
+  public async entities(): Promise<IIntegrationEntity[]> {
+    this.assertOpen();
+    const snapshot = await this.client.getSnapshot();
+    this.publish(snapshot);
+    return YamahaMapper.toEntities(snapshot);
+  }
+
+  public async writeFeature(input: IDeviceFeatureWriteRequest, signal?: AbortSignal): Promise<IServiceCallResult> {
+    this.assertOpen();
+    const request = yamahaRecord(input, ['device', 'feature', 'value']);
+    const device = yamahaRecord(request.device);
+    const feature = yamahaRecord(request.feature);
+    const canonical = YamahaMapper.toDevices(this.snapshot)[0];
+    if (device.id !== canonical.id || device.integrationDomain !== this.domain) throw new Error('Yamaha 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('Yamaha feature is not writable for the selected receiver.');
+    return this.control(validateYamahaControl({ feature: admitted.id, value: request.value }), signal);
+  }
+
+  public async callService(input: IServiceCallRequest): Promise<IServiceCallResult> {
+    this.assertOpen();
+    const request = yamahaRecord(input, ['domain', 'service', 'target', 'data']);
+    const target = yamahaRecord(request.target, ['deviceId', 'entityId']);
+    const deviceId = YamahaMapper.deviceId(this.snapshot.homeId, this.snapshot.identity.deviceId);
+    const entityId = YamahaMapper.entityId(this.snapshot.homeId, this.snapshot.identity.deviceId);
+    if ((!target.deviceId && !target.entityId) || (target.deviceId !== undefined && target.deviceId !== deviceId) ||
+      (target.entityId !== undefined && target.entityId !== entityId)) throw new Error('Yamaha service target is outside the selected home and receiver.');
+    if (request.domain !== 'media_player') throw new Error('Yamaha services use media_player.');
+    let control: TYamahaControl;
+    if (request.service === 'turn_on' || request.service === 'turn_off') {
+      yamahaRecord(request.data ?? {}, []);
+      control = { feature: 'power', value: request.service === 'turn_on' };
+    } else if (request.service === 'volume_set') {
+      const data = yamahaRecord(request.data, ['volume_raw']);
+      control = validateYamahaControl({ feature: 'volume_raw', value: data.volume_raw });
+    } else if (request.service === 'volume_mute') {
+      const data = yamahaRecord(request.data, ['is_volume_muted']);
+      control = validateYamahaControl({ feature: 'muted', value: data.is_volume_muted });
+    } else if (request.service === 'select_source') {
+      const data = yamahaRecord(request.data, ['source']);
+      control = validateYamahaControl({ feature: 'input', value: data.source });
+    } else throw new Error('Yamaha supports explicit power, mute, absolute raw volume and freshly advertised inputs only.');
+    return this.control(control);
+  }
+
+  /** Observe calls publish completed snapshots; subscriptions never create a hidden 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('Yamaha subscription requires a callback and optional AbortSignal.');
+    signal?.throwIfAborted();
+    if (this.subscriptions.size >= 32) throw new Error('Yamaha subscription capacity reached.');
+    const subscription: IYamahaSubscription = {
+      handler, active: true, failed: false, callbacks: new Set(),
+      detach: () => { subscription.active = false; signal?.removeEventListener('abort', aborted); },
+      stop: () => {
+        if (!subscription.stopPromise) {
+          subscription.stopPromise = Promise.resolve().then(async () => {
+            const results = await Promise.allSettled([...subscription.callbacks]);
+            this.subscriptions.delete(subscription);
+            const failures = results.filter((entry): entry is PromiseRejectedResult => entry.status === 'rejected').map((entry) => entry.reason as unknown);
+            if (subscription.failed) failures.push(subscription.failure);
+            const errors = [...new Set(failures)];
+            if (errors.length === 1) throw errors[0];
+            if (errors.length) throw new AggregateError(errors, 'Yamaha subscriber cleanup failed.');
+          });
+          subscription.detach();
+        }
+        return subscription.stopPromise;
+      },
+    };
+    const aborted = () => {
+      subscription.detach();
+      if (!subscription.callbacks.size && !subscription.failed) this.subscriptions.delete(subscription);
+    };
+    signal?.addEventListener('abort', aborted, { once: true });
+    this.subscriptions.add(subscription);
+    if (signal?.aborted) aborted();
+    return subscription.stop;
+  }
+
+  public destroy(): Promise<void> { return this.lease.close(); }
+
+  /** Called only by the retained lease, including its explicit cleanup retry. */
+  public closeOwnedResources(retry = false): Promise<void> {
+    if (retry) return this.drainOwnedResources(true);
+    if (!this.closePromise) {
+      this.closed = true;
+      this.closePromise = Promise.resolve().then(() => this.drainOwnedResources(false));
+      for (const subscription of this.subscriptions) subscription.detach();
+    }
+    return this.closePromise;
+  }
+
+  private async drainOwnedResources(retry: boolean): Promise<void> {
+    const results = await Promise.allSettled([
+      Promise.resolve().then(() => retry ? this.client.retryCleanup() : this.client.destroy()),
+      ...[...this.subscriptions].map((entry) => Promise.resolve().then(() => entry.stop())),
+    ]);
+    const failures = results.filter((entry): entry is PromiseRejectedResult => entry.status === 'rejected');
+    if (failures.length) throw new AggregateError(failures.map((entry) => entry.reason), 'Yamaha owned cleanup or subscriber failed.');
+  }
+
+  private async control(control: TYamahaControl, 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 : 'Yamaha control failed.',
+        data: { effectOutcome: error instanceof plugins.ecobridgeDeviceManager.YamahaProtocolError ? error.effectOutcome : 'not-sent' } };
+    }
+  }
+
+  private result(result: IYamahaEffectResult): 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: YamahaMapper.toDevices(result.snapshot), entities: YamahaMapper.toEntities(result.snapshot) } };
+  }
+
+  private publish(snapshot: IYamahaSnapshot): void {
+    if (this.closed) return;
+    this.snapshot = snapshot;
+    for (const subscription of [...this.subscriptions]) {
+      if (this.closed) break;
+      if (!subscription.active) continue;
+      if (subscription.callbacks.size) {
+        subscription.failed = true;
+        subscription.failure = new Error('Yamaha subscriber must drain its previous observation before another notification.');
+        subscription.detach();
+        continue;
+      }
+      const event: IIntegrationEvent = { type: 'state_changed', integrationDomain: this.domain,
+        deviceId: YamahaMapper.deviceId(snapshot.homeId, snapshot.identity.deviceId), entityId: YamahaMapper.entityId(snapshot.homeId, snapshot.identity.deviceId),
+        data: structuredClone(snapshot), timestamp: Date.now() };
+      // Register the actual callback promise before user code can synchronously close the runtime.
+      const pending = Promise.resolve().then(() => subscription.handler(event)).then(() => {}, (error: unknown) => {
+        subscription.failed = true; subscription.failure = error; subscription.detach(); throw error;
+      });
+      subscription.callbacks.add(pending);
+      const settled = (): void => {
+        subscription.callbacks.delete(pending);
+        if (!subscription.active && !subscription.failed) this.subscriptions.delete(subscription);
+      };
+      void pending.then(settled, settled);
+    }
+  }
+
+  private assertOpen(): void { if (this.closed) throw new Error('Yamaha runtime is closed.'); this.lease.assertOpen(); }
+}

package/ts/integrations/yamaha/yamaha.discovery.ts

@@ -1,4 +1,53 @@
-import { createSimpleLocalDiscoveryDescriptor } from '../../core/index.js';
-import { yamahaProfile } from './yamaha.types.js';
+import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
+import type { IYamahaManualEntry } from './yamaha.types.js';
+import { yamahaDeviceId, yamahaModel, yamahaOrigin, yamahaRecord, yamahaText } from './yamaha.validation.js';
 
-export const createYamahaDiscoveryDescriptor = () => createSimpleLocalDiscoveryDescriptor(yamahaProfile);
+const miss = (reason: string): IDiscoveryMatch => ({ matched: false, confidence: 'low', reason });
+
+function hint(origin: unknown, deviceId: unknown, model: unknown, name: unknown): IDiscoveryMatch {
+  const selectedOrigin = yamahaOrigin(origin);
+  const identity = yamahaDeviceId(deviceId);
+  const selectedModel = yamahaModel(model);
+  const selectedName = name === undefined ? undefined : yamahaText(name, 'display name', 128);
+  const url = new URL(selectedOrigin);
+  return { matched: true, confidence: 'medium', normalizedDeviceId: identity,
+    reason: 'Selected RX-V485 setup hint; live identity, features and main-zone status must still be verified.',
+    candidate: { source: 'manual', integrationDomain: 'yamaha', id: identity, host: url.hostname,
+      port: Number(url.port || 80), manufacturer: 'Yamaha', model: selectedModel, name: selectedName,
+      metadata: { origin: selectedOrigin, identityEvidence: 'unauthenticated-manual-hint' } } };
+}
+
+export class YamahaManualMatcher implements IDiscoveryMatcher<IYamahaManualEntry> {
+  public readonly id = 'yamaha-manual-match';
+  public readonly source = 'manual' as const;
+  public async matches(input: IYamahaManualEntry): Promise<IDiscoveryMatch> {
+    try {
+      const values = yamahaRecord(input, ['origin', 'expectedDeviceId', 'id', 'model', 'name', 'manufacturer', 'metadata']);
+      const metadata = values.metadata === undefined ? {} : yamahaRecord(values.metadata, ['origin']);
+      if (values.manufacturer !== undefined && values.manufacturer !== 'Yamaha') return miss('Manufacturer does not match the selected Yamaha profile.');
+      if (values.expectedDeviceId !== undefined && values.id !== undefined && values.expectedDeviceId !== values.id) return miss('Manual receiver identities conflict.');
+      if (values.origin !== undefined && metadata.origin !== undefined && yamahaOrigin(values.origin) !== yamahaOrigin(metadata.origin)) return miss('Manual selected origins conflict.');
+      return hint(values.origin ?? metadata.origin, values.expectedDeviceId ?? values.id, values.model, values.name);
+    } catch { return miss('Manual setup requires an exact RX-V485 identity and selected literal private HTTP origin.'); }
+  }
+}
+
+export class YamahaCandidateValidator implements IDiscoveryValidator {
+  public readonly id = 'yamaha-candidate-validator';
+  public async validate(input: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
+    try {
+      const values = yamahaRecord(input, ['source', 'integrationDomain', 'id', 'host', 'port', 'name', 'manufacturer', 'model', 'metadata']);
+      if (values.source !== 'manual' || values.integrationDomain !== 'yamaha' || values.manufacturer !== 'Yamaha') return miss('Candidate does not belong to selected Yamaha manual admission.');
+      const metadata = yamahaRecord(values.metadata, ['origin', 'identityEvidence']);
+      const selectedOrigin = yamahaOrigin(metadata.origin);
+      const url = new URL(selectedOrigin);
+      if (values.host !== url.hostname || values.port !== Number(url.port || 80)) return miss('Candidate host or port conflicts with the selected origin.');
+      return hint(selectedOrigin, values.id, values.model, values.name);
+    } catch { return miss('Candidate cannot satisfy selected Yamaha admission.'); }
+  }
+}
+
+export const createYamahaDiscoveryDescriptor = (): DiscoveryDescriptor =>
+  new DiscoveryDescriptor({ integrationDomain: 'yamaha', displayName: 'Yamaha RX-V485 main zone' })
+    .addMatcher(new YamahaManualMatcher()).addValidator(new YamahaCandidateValidator());

package/ts/integrations/yamaha/yamaha.mapper.ts

@@ -1,26 +1,78 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
-import { SimpleLocalMapper, type IIntegrationEntity, type ISimpleLocalSnapshot, type ISimpleLocalSnapshotOptions, type TSimpleLocalRawData } from '../../core/index.js';
-import type { IYamahaConfig } from './yamaha.types.js';
+import type * as plugins from '../../plugins.js';
+import { SimpleLocalMapper } from '../../core/classes.simplelocalintegration.js';
+import type { ISimpleLocalSnapshotOptions } from '../../core/classes.simplelocalintegration.js';
+import type { IIntegrationEntity } from '../../core/types.js';
+import type { IYamahaOfflineConfig, IYamahaOfflineSnapshot, IYamahaSnapshot, TYamahaRawData } from './yamaha.types.js';
 import { yamahaProfile } from './yamaha.types.js';
 
 export class YamahaMapper {
-  public static toSnapshot(optionsArg: Omit<ISimpleLocalSnapshotOptions<IYamahaConfig>, 'profile'>): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ ...optionsArg, profile: yamahaProfile });
+  public static deviceId(homeId: string, deviceId: string): string {
+    return `yamaha.receiver.${encodeURIComponent(homeId)}.${encodeURIComponent(deviceId)}`;
   }
 
-  public static toSnapshotFromRaw(configArg: IYamahaConfig, rawDataArg: TSimpleLocalRawData): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ profile: yamahaProfile, config: configArg, rawData: rawDataArg, online: true, source: 'manual' });
+  public static entityId(homeId: string, deviceId: string): string {
+    return `media_player.yamaha.${encodeURIComponent(homeId)}.${encodeURIComponent(deviceId)}`;
   }
 
-  public static toDevices(snapshotArg: ISimpleLocalSnapshot): shxInterfaces.data.IDeviceDefinition[] {
-    return SimpleLocalMapper.toDevices(yamahaProfile, snapshotArg);
+  public static toDevices(snapshot: IYamahaSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    return [{
+      id: this.deviceId(snapshot.homeId, snapshot.identity.deviceId), integrationDomain: 'yamaha', name: snapshot.name,
+      protocol: 'http', manufacturer: 'Yamaha', model: snapshot.identity.model, online: true,
+      features: [
+        { id: 'power', capability: 'media', name: 'Main-zone power', readable: true, writable: true },
+        { id: 'muted', capability: 'media', name: 'Main-zone mute', readable: true, writable: true },
+        { id: 'volume_raw', capability: 'media', name: 'Main-zone absolute vendor volume', unit: 'raw', readable: true, writable: true },
+        { id: 'input', capability: 'media', name: 'Main-zone input', readable: true, writable: snapshot.inputs.length > 0 },
+      ],
+      state: [
+        { featureId: 'power', value: snapshot.power === 'on', updatedAt: snapshot.observedAt },
+        { featureId: 'muted', value: snapshot.muted, updatedAt: snapshot.observedAt },
+        { featureId: 'volume_raw', value: snapshot.volume, updatedAt: snapshot.observedAt },
+        { featureId: 'input', value: snapshot.input, updatedAt: snapshot.observedAt },
+      ],
+      metadata: { homeId: snapshot.homeId, deviceId: snapshot.identity.deviceId, origin: snapshot.origin, zone: 'main',
+        apiVersion: snapshot.identity.apiVersion, inputs: [...snapshot.inputs], volumeRange: { ...snapshot.volumeRange },
+        ownerMaxVolume: snapshot.ownerMaxVolume, receiverMaxVolume: snapshot.receiverMaxVolume,
+        stateSource: 'receiver-observation', identityAuthentication: 'unauthenticated-lan' },
+    }];
   }
 
-  public static toEntities(snapshotArg: ISimpleLocalSnapshot): IIntegrationEntity[] {
-    return SimpleLocalMapper.toEntities(yamahaProfile, snapshotArg);
+  public static toEntities(snapshot: IYamahaSnapshot): IIntegrationEntity[] {
+    return [{
+      id: this.entityId(snapshot.homeId, snapshot.identity.deviceId), uniqueId: this.deviceId(snapshot.homeId, snapshot.identity.deviceId),
+      integrationDomain: 'yamaha', deviceId: this.deviceId(snapshot.homeId, snapshot.identity.deviceId), platform: 'media_player',
+      name: snapshot.name, state: snapshot.power === 'on' ? 'on' : 'off', available: true,
+      attributes: { homeId: snapshot.homeId, deviceId: snapshot.identity.deviceId, zone: 'main', power: snapshot.power,
+        volumeRaw: snapshot.volume, volumeUnit: 'raw', muted: snapshot.muted, source: snapshot.input, sourceList: [...snapshot.inputs],
+        volumeRange: { ...snapshot.volumeRange }, ownerMaxVolume: snapshot.ownerMaxVolume, receiverMaxVolume: snapshot.receiverMaxVolume,
+        observedAt: snapshot.observedAt, stateSource: 'receiver-observation' },
+    }];
+  }
+}
+
+/** The former generic mapping remains available without admitting data as a live device. */
+export class YamahaOfflineMapper {
+  public static toSnapshot(options: Omit<ISimpleLocalSnapshotOptions<IYamahaOfflineConfig>, 'profile'>): IYamahaOfflineSnapshot {
+    const snapshot = SimpleLocalMapper.toSnapshot({ ...options, profile: yamahaProfile, online: false });
+    return { ...snapshot, online: false, source: 'manual',
+      entities: snapshot.entities.map((entity) => ({ ...entity, available: false, writable: false })),
+      capabilities: { localRead: false, localControl: false, offlineData: true } };
+  }
+
+  public static toSnapshotFromRaw(config: IYamahaOfflineConfig, rawData: TYamahaRawData): IYamahaOfflineSnapshot {
+    return this.toSnapshot({ config, rawData, source: 'manual' });
+  }
+
+  public static toDevices(snapshot: IYamahaOfflineSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    return SimpleLocalMapper.toDevices(yamahaProfile, snapshot).map((device) => ({ ...device, online: false,
+      features: device.features.map((feature) => ({ ...feature, writable: false })),
+      metadata: { ...device.metadata, stateSource: 'explicit-offline-data' } }));
   }
 
-  public static slug(valueArg: unknown): string {
-    return SimpleLocalMapper.slug(valueArg);
+  public static toEntities(snapshot: IYamahaOfflineSnapshot): IIntegrationEntity[] {
+    return SimpleLocalMapper.toEntities(yamahaProfile, snapshot).map((entity) => ({ ...entity, available: false,
+      attributes: { ...entity.attributes, stateSource: 'explicit-offline-data' } }));
   }
+
+  public static slug(value: unknown): string { return SimpleLocalMapper.slug(value); }
 }

package/ts/integrations/yamaha/yamaha.types.ts

@@ -1,103 +1,83 @@
-import type { ISimpleLocalConfig, ISimpleLocalIntegrationProfile, ISimpleLocalSnapshot, TSimpleLocalRawData } from '../../core/index.js';
+import type { ISimpleLocalConfig, ISimpleLocalIntegrationProfile, ISimpleLocalSnapshot, TSimpleLocalRawData } from '../../core/classes.simplelocalintegration.js';
 
-export const yamahaDomain = "yamaha";
-export const yamahaDefaultName = "Yamaha Network Receivers";
+export const yamahaDomain = 'yamaha';
+export const yamahaDefaultName = 'Yamaha RX-V485 main zone';
+export type TYamahaModel = 'RX-V485';
+
+export interface IYamahaConfig {
+  homeId: string;
+  origin: string;
+  expectedDeviceId: string;
+  model: TYamahaModel;
+  allowUnencryptedHttp: true;
+  maxVolume: number;
+  name?: string;
+  timeoutMs?: number;
+  maxResponseBytes?: number;
+  maxPendingOperations?: number;
+}
 
-export type TYamahaRawData = TSimpleLocalRawData;
-export interface IYamahaSnapshot extends ISimpleLocalSnapshot {}
-export interface IYamahaConfig extends ISimpleLocalConfig {}
 export interface IHomeAssistantYamahaConfig extends IYamahaConfig {}
 
+export interface IYamahaIdentity {
+  readonly deviceId: string;
+  readonly model: TYamahaModel;
+  readonly apiVersion: number;
+}
+
+export interface IYamahaVolumeRange {
+  readonly min: number;
+  readonly max: number;
+  readonly step: number;
+}
+
+/** Receiver settings are observations, without claims about an electrical or acoustic effect. */
+export interface IYamahaSnapshot {
+  readonly homeId: string;
+  readonly origin: string;
+  readonly name: string;
+  readonly identity: IYamahaIdentity;
+  readonly power: 'on' | 'standby';
+  readonly muted: boolean;
+  readonly volume: number;
+  readonly receiverMaxVolume: number;
+  readonly ownerMaxVolume: number;
+  readonly input: string;
+  readonly inputs: readonly string[];
+  readonly volumeRange: IYamahaVolumeRange;
+  readonly observedAt: string;
+}
+
+export type TYamahaControl =
+  | { feature: 'power'; value: boolean }
+  | { feature: 'muted'; value: boolean }
+  | { feature: 'volume_raw'; value: number }
+  | { feature: 'input'; value: string };
+
+export interface IYamahaEffectResult {
+  readonly dispatch: 'acknowledged';
+  readonly outcome: 'observed-target' | 'indeterminate';
+  readonly snapshot: IYamahaSnapshot;
+}
+
+export interface IYamahaManualEntry {
+  origin?: string;
+  expectedDeviceId?: string;
+  id?: string;
+  model?: string;
+  name?: string;
+  manufacturer?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export type TYamahaRawData = TSimpleLocalRawData;
+export interface IYamahaOfflineConfig extends ISimpleLocalConfig {}
+export interface IYamahaOfflineSnapshot extends ISimpleLocalSnapshot {}
+
+/** Pure offline mapping profile; it supplies no protocol client or live runtime admission. */
 export const yamahaProfile: ISimpleLocalIntegrationProfile = {
-  domain: "yamaha",
-  displayName: "Yamaha Network Receivers",
-  manufacturer: "Yamaha",
-  model: "Network receiver",
-  defaultName: "Yamaha Network Receivers",
-  defaultPort: 80,
-  defaultHttpPath: "/YamahaRemoteControl/ctrl",
-  defaultProtocol: "http",
-  status: "control-runtime",
-  platforms: [
-    "media_player",
-    "sensor"
-  ],
-  serviceDomains: [
-    "media_player"
-  ],
-  controlServices: [
-    "turn_on",
-    "turn_off",
-    "volume_up",
-    "volume_down",
-    "volume_mute",
-    "select_source",
-    "media_play",
-    "media_pause",
-    "media_stop",
-    "media_next_track",
-    "media_previous_track"
-  ],
-  discoverySources: [
-    "manual",
-    "mdns",
-    "ssdp",
-    "http",
-    "custom"
-  ],
-  discoveryKeywords: [
-    "yamaha",
-    "rx-v",
-    "receiver"
-  ],
-  metadata: {
-    source: "home-assistant/core",
-    upstreamPath: "homeassistant/components/yamaha",
-    upstreamDomain: "yamaha",
-    iotClass: "local_polling",
-    qualityScale: "legacy",
-    requirements: [
-      "rxv==0.7.0"
-    ],
-    dependencies: [],
-    afterDependencies: [],
-    codeowners: [],
-    configFlow: true,
-    runtime: {
-      type: "control-runtime",
-      services: [
-        "snapshot",
-        "status",
-        "refresh",
-        "turn_on",
-        "turn_off",
-        "volume_up",
-        "volume_down",
-        "volume_mute",
-        "select_source",
-        "media_play",
-        "media_pause",
-        "media_stop",
-        "media_next_track",
-        "media_previous_track"
-      ],
-      platforms: [
-        "media_player",
-        "sensor"
-      ],
-      controls: true
-    },
-    localApi: {
-      implemented: [
-        "manual local endpoint setup",
-        "snapshot, raw data, snapshotProvider, and injected native client operation",
-        "generic HTTP/TCP local transport when config.path, config.transport, or documented defaults are supplied"
-      ],
-      explicitUnsupported: [
-        "claiming live command success without injected client.execute or commandExecutor",
-        "cloud account flows and remote API polling",
-        "device-specific protocol features not represented by snapshot/rawData/client/executor inputs"
-      ]
-    }
-  }
+  domain: yamahaDomain, displayName: 'Yamaha offline data', manufacturer: 'Yamaha', model: 'Unverified Yamaha receiver',
+  defaultName: 'Yamaha offline data', defaultProtocol: 'unknown', status: 'read-only-runtime',
+  platforms: ['media_player', 'sensor'], serviceDomains: [], controlServices: [],
+  discoverySources: [], discoveryKeywords: [], metadata: { source: 'explicit-offline-data', liveRuntime: false },
 };