@smarthome.exchange/integrations 0.2.0 → 2.0.0

package/ts/integrations/onkyo/readme.md

@@ -0,0 +1,126 @@
+# Selected native Onkyo integration
+
+`OnkyoIntegration` uses the published `OnkyoProtocol` from
+`@ecobridge.xyz/devicemanager@4.5.0` for one selected Onkyo receiver main zone over
+a persistent eISCP TCP connection. Device definitions use the canonical `tcp`
+protocol from `@smarthome.exchange/interfaces@2.1.0`.
+
+```typescript
+import { OnkyoIntegration } from '@smarthome.exchange/integrations';
+
+const integration = new OnkyoIntegration();
+const runtime = await integration.setup({
+  homeId: 'home-1',
+  host: '192.168.1.40',
+  macAddress: '0009B0D24B75',
+  model: 'TX-NR609',
+  allowUnencryptedLan: true,
+  volumeLimitRaw: 30,
+}, { homeId: 'home-1' });
+try {
+  const device = (await runtime.devices())[0];
+  const result = await runtime.callService!({
+    domain: 'onkyo', service: 'set_power',
+    target: { deviceId: device.id }, data: { power: true },
+  });
+  console.log(result);
+} finally {
+  await integration.destroy();
+}
+```
+
+The embedding host must select `context.homeId` independently of configuration,
+form values, discovery or store scope. Setup and config flow require that explicit
+selection; configuration must match it. Construction without options is inert.
+An optional constructor `{ homeId }` adds a consistency binding and still requires
+the explicit context. One instance binds synchronously to its first validated host
+home, including when later receiver setup fails. Flow and setup share that binding.
+This trusted host contract is not authentication by a home-id string.
+
+Configuration is captured plain data. It requires a matching `homeId`, one
+private/link-local/loopback unicast IPv4 `host`, twelve hexadecimal MAC digits,
+the exact selected `model`, `allowUnencryptedLan: true`, and an integer
+`volumeLimitRaw` from 0 through 100. Optional `port` defaults to 60128;
+`requestTimeoutMs` defaults to 5000 and accepts 1–60000; `maxPendingOperations`
+defaults to 16 and accepts 1–128. `name` is optional. Unknown keys, accessors,
+hidden properties, injected clients/executors/snapshots, hostname resolution,
+and configurable source/volume conversion maps are rejected.
+
+Setup checks live NRI identity and an enabled main zone. Every control checks
+fresh identity and capabilities through the public protocol. MAC/model binding
+selects the receiver; eISCP does not authenticate or encrypt the LAN peer.
+
+Device ids are `onkyo:<encoded homeId>:<uppercase MAC>` and the media entity id
+adds `:main`. Every service needs an exact owned device or entity target. If
+both target ids are supplied, both must match. Feature writes validate the
+owned home/device and a fresh canonical writable feature; caller-provided
+`writable` flags cannot grant capability.
+
+| Service | Exact data |
+| --- | --- |
+| `onkyo.status`, `onkyo.snapshot`, `onkyo.refresh` | Empty or absent data; live sequential inspection |
+| `onkyo.set_power` | `{ power: boolean }` |
+| `onkyo.set_mute`, `onkyo.volume_mute` | `{ muted: boolean }` |
+| `onkyo.set_volume_raw` | `{ volumeRaw: integer }` |
+| `onkyo.set_input`, `onkyo.select_source` | `{ inputId: '10' }`; advertised two-digit selector id |
+
+The same control services accept the `media_player` domain. Feature ids are
+`power`, `mute`, `volume_raw`, and `input`, when observed. Identity, connectivity,
+and advertised input lists are read-only. Unavailable reports produce absent
+state features. Power/mute need current boolean reports; input writes need
+current selector availability and enabled advertised main-zone choices.
+
+Volume values are absolute integer receiver wire units. Writes require an
+advertised `volstep="1"`, a positive `volmax` at most 100, and an observed raw
+level consistent with that contract. The configured ceiling and current
+advertised maximum both apply. Unknown/half-step contracts stay read-only.
+There is no normalized Home Assistant `volume_level`, percent conversion,
+guessed model scaling, increment, or toggle control.
+
+Success returns a matching receiver report after dispatch with
+`observation: 'matching-receiver-state'`, `commandAcknowledged: false`, and
+`causalityConfirmed: false`. eISCP has no request id; this report does not prove
+the command caused a physical change. Failures retain `effectOutcome` from the
+protocol: `not-sent` before dispatch or `indeterminate` after dispatch. A
+different report never counts as success. Controls are never retried or
+replayed. Inspection is sequential and `observedAt` records its completion.
+
+`subscribe()` emits observations from explicit inspection/control calls, plus
+operation errors. It opens no polling timer and provides no unsolicited push
+subscription. Subscriber cancellation unregisters its listener; runtime,
+integration, or caller lifetime cancellation joins active/queued operations
+and terminal protocol/socket cleanup. Shutdown is idempotent. A terminal
+protocol cannot reconnect; create a new authorized runtime explicitly.
+Integration shutdown collects cleanup failures, waits for every admitted resource,
+pending setup, config-flow submission and active client operation to settle, then
+reports the failures together in an `AggregateError`. Repeated shutdown returns
+the same terminal promise. Failed cleanup stays owned and consumes the shared
+capacity (16 by default; constructor `capacity` is a positive integer).
+`retryCleanup()` explicitly retries retained cleanup handles, never receiver effects.
+Closing is terminal and cannot select a different home or reopen an old form.
+
+Manual/custom discovery candidates must supply `integrationDomain: 'onkyo'`,
+selected host, MAC and model. The descriptor does no automatic network scan.
+`probeSelectedOnkyo({ host, port?, requestTimeoutMs?, signal? })` delegates one
+selected-unicast UDP query to the public protocol and returns a custom candidate
+with the advertised TCP port. Config flow fixes its endpoint and identity,
+captures the host home and lifetime before effects, collects acknowledgement and
+ceiling, then validates TCP readiness before completion. Home is not editable; a
+submitted conflicting home fails before opening a connection. Standalone
+`OnkyoConfigFlow` also requires explicit context home and supports `destroy()`.
+
+A supplied `configStore` must be an actual public `NoSqlConfigStore` with scope
+matching exactly this home and the `onkyo` domain. A store is optional for these
+protocol paths. The caller owns the public NoSQL store, database, and persistence
+lifetime. This integration does not create, close, read, write, or delete store
+data and does not persist receiver observations.
+
+Direct `OnkyoClient` construction likewise requires a separate native context as
+its second argument, such as `{ homeId: 'home-1' }`. Its snapshot home comes from
+that captured admission; an optional third signal carries an owning lease lifetime.
+
+Tests use bounded real TCP/UDP fixtures. No physical receiver or firmware has
+been certified. Other zones, media transport commands, HDMI routing, arbitrary
+raw commands, broadcast discovery, and cryptographic LAN authentication are
+outside the supported contract. `HomeAssistantOnkyoIntegration` remains a class
+alias with the same native semantics.

package/ts/integrations/openhome/openhome.classes.client.ts

@@ -56,10 +56,16 @@ interface IOpenhomeLiveData {
 export class OpenhomeClient extends SimpleLocalClient<IOpenhomeConfig> {
   private cachedSnapshot?: ISimpleLocalSnapshot;
   private cachedDescription?: IOpenhomeDeviceDescription;
-  private readonly soapClient = new plugins.ecobridgeDeviceManager.UpnpSoapClient('');
+  private readonly soapClient?: plugins.ecobridgeDeviceManager.UpnpSoapClient;
 
   constructor(private readonly configArg: IOpenhomeConfig) {
     super(openhomeProfile, configArg);
+    const location = this.descriptionUrl();
+    if (location && !configArg.client && !configArg.snapshotProvider) {
+      this.soapClient = new plugins.ecobridgeDeviceManager.UpnpSoapClient(location, {
+        timeoutMs: configArg.timeoutMs ?? 5000,
+      });
+    }
   }
 
   public override async getSnapshot(forceRefreshArg = false): Promise<ISimpleLocalSnapshot> {
@@ -114,6 +120,8 @@ export class OpenhomeClient extends SimpleLocalClient<IOpenhomeConfig> {
   }
 
   public override async destroy(): Promise<void> {
+    this.cachedSnapshot = undefined;
+    await this.soapClient?.close();
     await this.configArg.client?.destroy?.();
   }
 
@@ -312,20 +320,9 @@ export class OpenhomeClient extends SimpleLocalClient<IOpenhomeConfig> {
     if (!location) {
       throw new Error('OpenHome live HTTP/SOAP support requires config.url, config.host containing the SSDP location URL, or config.host plus config.path.');
     }
-    const timeoutMs = this.configArg.timeoutMs || 5000;
-    const abortController = new AbortController();
-    const timer = setTimeout(() => abortController.abort(), timeoutMs);
-    try {
-      const response = await globalThis.fetch(location, { headers: { accept: 'application/xml, text/xml;q=0.9, */*;q=0.8' }, signal: abortController.signal });
-      const xml = await response.text();
-      if (!response.ok) {
-        throw new Error(`OpenHome device description ${location} failed with HTTP ${response.status}: ${xml.slice(0, 160)}`);
-      }
-      this.cachedDescription = parseDeviceDescription(location, xml);
-      return this.cachedDescription;
-    } finally {
-      clearTimeout(timer);
-    }
+    const xml = await this.requireSoapClient().getXml(location);
+    this.cachedDescription = parseDeviceDescription(location, xml);
+    return this.cachedDescription;
   }
 
   private async productInfo(descriptionArg: IOpenhomeDeviceDescription): Promise<Record<string, unknown>> {
@@ -453,9 +450,9 @@ export class OpenhomeClient extends SimpleLocalClient<IOpenhomeConfig> {
     }
   }
 
-  private async soapValues(descriptionArg: IOpenhomeDeviceDescription, serviceNameArg: string, actionArg: string, tagsArg: string[], argsArg: Record<string, string | number> = {}): Promise<Record<string, string>> {
+  private async soapValues(descriptionArg: IOpenhomeDeviceDescription, serviceNameArg: string, actionArg: string, tagsArg: string[], argsArg: Record<string, string | number> = {}): Promise<Record<string, string | undefined>> {
     const response = await this.soap(descriptionArg, serviceNameArg, actionArg, argsArg);
-    return Object.fromEntries(tagsArg.map((tagArg) => [tagArg, unescapeXml(this.soapClient.extractValue(response, tagArg))]));
+    return this.requireSoapClient().extractOptionalValues(response, tagsArg);
   }
 
   private async soap(descriptionArg: IOpenhomeDeviceDescription, serviceNameArg: string, actionArg: string, argsArg: Record<string, string | number> = {}): Promise<string> {
@@ -463,7 +460,14 @@ export class OpenhomeClient extends SimpleLocalClient<IOpenhomeConfig> {
     if (!service) {
       throw new Error(`OpenHome service ${serviceNameArg} is not available on ${descriptionArg.location}.`);
     }
-    return await this.soapClient.soapAction(service.controlUrl, service.serviceType, actionArg, argsArg);
+    return await this.requireSoapClient().soapAction(service.controlUrl, service.serviceType, actionArg, argsArg);
+  }
+
+  private requireSoapClient(): plugins.ecobridgeDeviceManager.UpnpSoapClient {
+    if (!this.soapClient) {
+      throw new Error('OpenHome SOAP requires a configured device description URL.');
+    }
+    return this.soapClient;
   }
 
   private service(descriptionArg: IOpenhomeDeviceDescription, serviceNameArg: string): IOpenhomeServiceDescription | undefined {