@smarthome.exchange/integrations 2.0.0 → 4.0.0

package/ts/integrations/shelly/shelly.validation.ts

@@ -0,0 +1,76 @@
+import type { IShellyConfig, IShellyIntegrationOptions } from './shelly.types.js';
+
+export const shellyData = (valueArg: unknown, allowedArg?: readonly string[]): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' || ![Object.prototype, null].includes(Object.getPrototypeOf(valueArg))) {
+    throw new TypeError('Shelly input must be a plain data object.');
+  }
+  const result: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || allowedArg && !allowedArg.includes(key) || !descriptor || !descriptor.enumerable || !('value' in descriptor)) {
+      throw new TypeError('Shelly input contains an unsupported field or accessor.');
+    }
+    result[key] = descriptor.value as unknown;
+  }
+  return result;
+};
+
+export const shellyText = (valueArg: unknown, labelArg: string, maximumArg = 128): string => {
+  if (typeof valueArg !== 'string' || !valueArg || valueArg.trim() !== valueArg || valueArg.length > maximumArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`Shelly ${labelArg} must be bounded text without control characters.`);
+  }
+  return valueArg;
+};
+
+const integer = (valueArg: unknown, minimumArg: number, maximumArg: number): number => {
+  if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < minimumArg || valueArg > maximumArg) {
+    throw new TypeError('Shelly integer is outside its supported bounds.');
+  }
+  return valueArg;
+};
+
+export const shellyConfigFields = ['homeId', 'host', 'port', 'protocol', 'expectedDeviceId', 'expectedMacAddress',
+  'expectedModel', 'expectedGeneration', 'credentialRef', 'allowControl', 'allowUnencryptedLan',
+  'requestTimeoutMs', 'maxPendingOperations', 'maxResponseBytes'] as const;
+
+export type TNormalizedShellyConfig = Readonly<Required<Omit<IShellyConfig, 'credentialRef'>> & Pick<IShellyConfig, 'credentialRef'>>;
+
+export const normalizeShellyConfig = (valueArg: unknown): TNormalizedShellyConfig => {
+  const config = shellyData(valueArg, shellyConfigFields);
+  const host = shellyText(config.host, 'host', 253);
+  if (/[\s\/?#@]/.test(host)) throw new TypeError('Shelly host must be a hostname or IP address.');
+  const protocol = config.protocol ?? 'http';
+  if (protocol !== 'http' && protocol !== 'https') throw new TypeError('Shelly protocol must be http or https.');
+  const expectedDeviceId = shellyText(config.expectedDeviceId, 'selected device id');
+  if (!/^shelly[\w-]+$/i.test(expectedDeviceId)) throw new TypeError('Shelly requires an exact reported device id.');
+  const mac = shellyText(config.expectedMacAddress, 'selected MAC', 12);
+  if (!/^[0-9a-f]{12}$/i.test(mac) || /^(?:0{12}|f{12})$/i.test(mac) || (Number.parseInt(mac.slice(0, 2), 16) & 1) !== 0) {
+    throw new TypeError('Shelly requires an exact usable reported 12-digit MAC.');
+  }
+  if (config.expectedGeneration !== 2 && config.expectedGeneration !== 3) throw new TypeError('Shelly selected generation must be 2 or 3.');
+  if (config.allowControl !== undefined && typeof config.allowControl !== 'boolean' || config.allowUnencryptedLan !== undefined && typeof config.allowUnencryptedLan !== 'boolean') {
+    throw new TypeError('Shelly consent settings must be boolean.');
+  }
+  if (protocol === 'http' && config.allowUnencryptedLan !== true) throw new TypeError('Shelly HTTP requires explicit unencrypted LAN consent.');
+  const port = integer(config.port ?? (protocol === 'https' ? 443 : 80), 1, 65535);
+  const urlHost = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+  try { new URL(`${protocol}://${urlHost}:${port}`); } catch { throw new TypeError('Shelly host must be a hostname or IP address.'); }
+  return Object.freeze({ homeId: shellyText(config.homeId, 'home ID', 256), host, port, protocol,
+    expectedDeviceId, expectedMacAddress: mac.toUpperCase(), expectedModel: shellyText(config.expectedModel, 'selected model'),
+    expectedGeneration: config.expectedGeneration,
+    ...(config.credentialRef === undefined ? {} : { credentialRef: shellyText(config.credentialRef, 'credential reference', 256) }),
+    allowControl: config.allowControl === true, allowUnencryptedLan: config.allowUnencryptedLan === true,
+    requestTimeoutMs: integer(config.requestTimeoutMs ?? 10000, 10, 60000),
+    maxPendingOperations: integer(config.maxPendingOperations ?? 16, 1, 128),
+    maxResponseBytes: integer(config.maxResponseBytes ?? 1048576, 1024, 1048576) });
+};
+
+export const normalizeShellyOptions = (valueArg: unknown = {}): Readonly<IShellyIntegrationOptions> => {
+  const options = shellyData(valueArg, ['homeId', 'capacity', 'resolvePassword']);
+  if (options.resolvePassword !== undefined && typeof options.resolvePassword !== 'function') throw new TypeError('Shelly password resolver must be a function.');
+  return Object.freeze({
+    ...(options.homeId === undefined ? {} : { homeId: shellyText(options.homeId, 'owning home ID', 256) }),
+    ...(options.capacity === undefined ? {} : { capacity: integer(options.capacity, 1, Number.MAX_SAFE_INTEGER) }),
+    ...(options.resolvePassword === undefined ? {} : { resolvePassword: options.resolvePassword as IShellyIntegrationOptions['resolvePassword'] }),
+  });
+};

package/ts/integrations/sonos/readme.md

@@ -1,16 +1,19 @@
 # Sonos
 
 The native local runtime uses the public UPnP client and transport/volume controllers
-from `@ecobridge.xyz/devicemanager`. It reads the configured renderer's device
-description, transport, position, volume, mute and ZoneGroupTopology over bounded
-HTTP/SOAP. No Home Assistant instance or Sonos cloud account is required.
+from `@ecobridge.xyz/devicemanager`. It reads the selected renderer's device
+identity, transport, position, volume, mute, reported topology and service
+capabilities through bounded HTTP/SOAP. No Home Assistant instance, Sonos cloud
+account or invented authentication provider is required for this selected protocol.
 
 ```typescript
-const runtime = await new SonosIntegration().setup({
+const integration = new SonosIntegration({ allowControl: true });
+const runtime = await integration.setup({
+  homeId: 'home:example',
   host: '192.168.1.55',
   expectedUid: 'RINCON_000E58ABCDEF01400',
   pollIntervalMs: 5000,
-}, { abortSignal });
+}, { homeId: 'home:example', abortSignal });
 
 const [device] = await runtime.devices();
 await runtime.writeFeature!({
@@ -18,57 +21,133 @@ await runtime.writeFeature!({
   feature: device.features.find((feature) => feature.id === 'volume')!,
   value: 35,
 });
-await runtime.destroy();
+await integration.destroy();
 ```
 
+The embedding host must independently select `context.homeId`; configuration,
+discovery, form values and storage scope cannot select it or grant control. The
+owning home binds once, including after failed setup. An optional constructor
+`homeId` only constrains that explicit context. The exported `SonosClient` also
+requires configuration and context homes before allocating protocol resources:
+`new SonosClient(config, { homeId, abortSignal }, { allowControl: true })`.
+A matching actual `NoSqlConfigStore` is optional and borrowed; the adapter never
+closes the caller's store, database or key provider. This credential-free adapter
+has no persistence requirement and does not write application state to disk.
+
+Controls default to denied. Only the embedding host's immutable constructor
+`allowControl: true` enables them; saved configuration and config-flow submissions
+cannot set this option. A home identifier is a host scope, not an authentication
+credential. UPnP assumes a trusted local network. Sonos currently documents its
+UPnP interface as unsupported and provides an owner-controlled connection-security
+setting; the adapter does not change that setting or bypass it.
+
 Configuration requires a bare IPv4 address or DNS hostname. The default port is
-1400. Optional identity pinning rejects a different renderer. Request deadlines
+1400. Optional UUID pinning rejects a different renderer. Whole-operation deadlines
 default to 10 seconds and response bodies to 1 MiB. Production snapshot fixtures,
-credentials in URLs and arbitrary configuration fields are rejected.
+credentials in URLs and arbitrary configuration fields are rejected. Config flow
+captures the selected home and endpoint/identity hint; it exposes host and port,
+rejects a conflicting submitted home, and returns the captured home without
+performing discovery or granting authority.
 
-The discovery descriptor owns an active native SSDP probe. Its observation window
-defaults to three seconds, with a separate five-second startup budget. Caller
-cancellation reaches the owning SSDP lifecycle and drains sockets and description
-requests. `IDiscoveryContext.networkInterfaces` limits discovery to the selected
-actual interfaces; an explicitly empty scope performs no network I/O. Passive
-SSDP and explicit Sonos mDNS/manual candidates use the same strict admission rules.
-Discovered endpoints are verified during setup before becoming available devices.
+Device IDs are `sonos.player.<encoded-home>.<renderer-uuid>` and entity IDs are
+`media_player.sonos.<encoded-home>.<renderer-uuid>`. Home segments use
+`encodeURIComponent`; UUIDs are lowercase. These home-prefixed IDs intentionally
+replace the previous unscoped IDs. Room renames preserve identity. Group metadata
+comes from fresh reported topology; advertised member URLs are never followed.
+Playback requires the selected renderer to remain its group coordinator. A grouped
+member exposes its actual state and supports its own advertised rendering controls
+without redirecting playback. Bonded satellites require selecting their parent.
 
-Devices and entities use renderer UUIDs, so room renames preserve identity. Group
-metadata comes from the renderer's reported topology; advertised member URLs are
-never followed. Playback controls require the selected renderer to be its group
-coordinator. A grouped member exposes its actual state and supports its own volume
-and mute controls without silently redirecting playback to another renderer.
-Bonded satellites require selecting their parent renderer.
+Before each transport effect, the adapter refreshes renderer identity, topology,
+the selected service description and `GetCurrentTransportActions`. Play, Pause,
+Stop, Next and Previous require both a declared action and its current action token.
+`SetAVTransportURI` is declared by its service description; the standard current
+transport list describes actions on the current resource and does not include URI
+assignment. Volume and mute use separate, fresh RenderingControl declarations.
+Volume also checks `GetOutputFixed` when that action is advertised; devices without
+that action are judged by their actual `SetVolume` declaration, without fabricating
+a fixed-output observation. AVTransport actions never grant volume permission.
+Writable flags describe the observed capability and owner permission; they do not
+reserve authority for a later write.
 
 Feature writes support integer volume from 0 to 100, boolean mute and playback
 values `playing`, `paused` or `stopped`. Media-player services support `play`,
 `pause`, `stop`, `next_track`, `previous_track`, `volume_set`, `volume_mute` and
 `play_media`. Each service requires an exact selected device or entity target and
 its documented arguments. `volume_level` is a fraction from 0 to 1; `volume` is an
-integer percent. A successful SOAP acknowledgement is followed by a fresh read;
-state is never optimistically changed and failed or uncertain calls are not retried.
+integer percent.
+
+Each supported action is sent once and is never automatically replayed. A SOAP
+acknowledgement is followed by fresh independent observations. Returned
+`acknowledgedActions`, `outcome`, `requestedValue` and `observedValue` distinguish
+an observed target, a different observed value, or an observation without a
+comparable target. `success: true` means acknowledged actions and successful fresh
+readback; it does not assert physical or acoustic causation. Results explicitly
+carry `physicalEffectConfirmed: false`; runtime service receipts additionally carry
+`observationAtomic: false`. A failed
+command rejects with `SonosCommandError`, retaining acknowledged actions and a
+conservative `not-sent`, `rejected` or `indeterminate` effect outcome. An acknowledged
+write followed by read failure is indeterminate, without cached success or retry.
+
+`play_media` preserves the documented sequential `SetAVTransportURI` then `Play`
+behavior within one admitted operation and one whole-operation deadline. Identity,
+coordinator and relevant action authority are refreshed between those distinct
+steps. If the second step fails, the URI assignment can remain acknowledged and
+is not rolled back or replayed. Separate preflight, action and readback exchanges
+can race another controller or a topology change; UPnP offers no atomic transaction
+across them. Successful readback cannot prove that this action caused the observed
+state or that audio was heard.
+
 `play_media` accepts `uri` or `media_content_id`. Supplying `title` also requires
-an explicit `mime_type`, such as `audio/mpeg` or `audio/flac`, for its audio DIDL
-metadata. The runtime does not guess the media format from an arbitrary URI.
-Stream URLs require an explicit hostname and `//` authority, using `http:`,
-`https:`, `x-sonos-http:` or `x-rincon-mp3radio:` without embedded credentials.
-Direct client calls use `playUri(uri, { title, mimeType }, abortSignal)`.
+an explicit `mime_type`, such as `audio/mpeg` or `audio/flac`, for audio DIDL
+metadata. The runtime does not guess media format. Stream URLs require an explicit
+hostname and `//` authority, using `http:`, `https:`, `x-sonos-http:` or
+`x-rincon-mp3radio:` without embedded credentials. Direct clients use
+`playUri(uri, { title, mimeType }, abortSignal)` and return the acknowledged actions,
+outcome and fresh snapshot as `ISonosControlResult`.
+
+Setup, live runtimes, runtime/client operations, config-flow continuations and
+retained failed cleanup share one owner with capacity 16. A live runtime and one
+operation occupy two slots. Admission occurs before protocol allocation or caller
+callbacks. The integration closes its flow and all owned runtimes; runtime destroy
+closes that runtime's lease. Close promises are stable before abort callbacks,
+terminal admission is enforced, and cleanup settles every sibling plus actual
+pending commands and subscriber promises. Failed cleanup retains the actual handle
+until explicit `integration.retryCleanup()` or `client.retryCleanup()` succeeds;
+this retries cleanup only, never an effect. A failed original close promise remains
+failed after retry, preserving its reported outcome.
 
 Subscriptions are explicitly `local_poll`, with a default five-second interval.
-Each subscription owns one sequential poll, cancellation and cleanup. Failures
-emit unavailable/error events rather than manufacturing known state; subsequent
-scheduled reads can report recovery. Unsubscribe and destroy abort and drain
-pending work. There is no GENA push capability, grouping mutation, queue management,
-favorites, alarms or EQ in this runtime.
+Each subscription reserves a slot before its initial observation/callback, owns
+one sequential poll, cancellation and actual callback drain, and is limited to
+16 per runtime. Async subscriber promises are awaited even though the generic
+callback signature returns void. Unsubscribe and destroy abort protocol work and
+wait for actual callback completion; a callback that ignores cancellation must
+settle before cleanup completes. Read failures emit unavailable/error events;
+subsequent scheduled reads can report recovery. Subscriber failures remain
+observable through cleanup. There is no GENA push capability, grouping mutation,
+queue management, favorites, alarms or EQ in this runtime.
+
+The discovery descriptor owns an active native SSDP probe. Its observation window
+defaults to three seconds, with a separate five-second startup budget. Caller
+cancellation drains sockets and description requests.
+`IDiscoveryContext.networkInterfaces` limits discovery to selected actual
+interfaces; an explicitly empty scope performs no network I/O. Passive SSDP and
+explicit Sonos mDNS/manual candidates use the same strict admission rules.
+Discovered endpoints are verified during setup before becoming available devices.
 
 Protocol references:
 
 - [devicemanager UPnP contracts](https://code.foss.global/ecobridge.xyz/devicemanager)
+- [UPnP AVTransport:1 specification, especially sections 2.2.26 and 2.4.17](https://upnp.org/specs/av/UPnP-av-AVTransport-v1-Service.pdf)
+- [UPnP RenderingControl:1 specification](https://upnp.org/specs/av/UPnP-av-RenderingControl-v1-Service.pdf)
+- [Sonos connection security settings](https://support.sonos.com/en/article/adjust-connection-security-settings)
 - [SoCo's native Sonos service implementation](https://github.com/SoCo/SoCo/blob/master/soco/services.py)
-- [SoCo's ZoneGroupState XML contract](https://github.com/SoCo/SoCo/blob/master/soco/zonegroupstate.py)
+- [SoCo's ZoneGroupState contract](https://github.com/SoCo/SoCo/blob/master/soco/zonegroupstate.py)
+- [SoCo's current-action and fixed-output implementation](https://github.com/SoCo/SoCo/blob/master/soco/core.py)
 
-The local UPnP wire contract was checked against those primary implementation
-sources. Sonos's current public developer portal documents its cloud Control API;
-it does not provide an openly accessible complete local UPnP specification.
-Verification uses local real HTTP/SOAP fixtures; owner hardware was not accessed.
+The selected wire contract was checked against the standards, maintained primary
+implementation and actual installed public devicemanager 4.8.0 source/declarations.
+Sonos's public developer portal documents its Control API; a complete current
+Sonos-authored local UPnP specification was not found. Verification uses real local
+HTTP/SOAP and SSDP fixtures; owner hardware was not accessed.