@smarthome.exchange/integrations 2.0.0 → 3.0.0

package/ts/integrations/shelly/readme.md

@@ -1,14 +1,23 @@
 # Shelly Gen2/3
 
-This native port connects to a local Shelly Gen2 or Gen3 HTTP/RPC endpoint. Setup reads and validates the physical device identity, status and configuration before returning a runtime. It maps switch outputs and their power, voltage, current, energy and temperature readings to canonical devices and entities.
+This native port connects to a local Shelly Gen2 or Gen3 HTTP/RPC endpoint. Setup reads and validates the selected endpoint's reported device ID, MAC, model, generation, methods, status and configuration before returning a runtime. These observations do not attest physical hardware identity. It maps switch outputs and their power, voltage, current, energy and temperature readings to canonical devices and entities.
 
 ```typescript
-const integration = new ShellyIntegration();
+const integration = new ShellyIntegration({
+  resolvePassword, // Caller-owned callback; receives homeId, credentialRef, signal and monotonic deadline.
+});
 const runtime = await integration.setup({
   host: '192.168.1.20',
-  password: devicePassword,
+  homeId: selectedHomeId,
+  expectedDeviceId: selectedDeviceId,
+  expectedMacAddress: selectedMacAddress,
+  expectedModel: selectedModel,
+  expectedGeneration: selectedGeneration,
+  credentialRef: selectedCredentialRef,
+  allowUnencryptedLan: true,
+  allowControl: true, // Omit for read-only outputs.
   requestTimeoutMs: 10000,
-}, {});
+}, { homeId: hostSelectedHomeId, abortSignal: callerSignal });
 
 const [device] = await runtime.devices();
 const output = device.features.find((feature) => feature.id === 'switch_0_output');
@@ -21,14 +30,20 @@ await unsubscribe?.();
 await integration.destroy();
 ```
 
-`host` is a hostname or IP address, with the optional port supplied separately. `protocol` defaults to `http`; `https` validates the endpoint certificate through Node's standard transport. Authentication uses the Shelly `admin` username and SHA-256 digest challenges. Credentials and response bodies are excluded from error messages. Request deadlines default to 10 seconds and accept values between 10 ms and 60 seconds.
+`hostSelectedHomeId` comes independently from the embedding host and must match configuration and any optional constructor home binding. Config flow captures that selection before returning a form. An optional actual `NoSqlConfigStore` must match the admitted home/domain and remains borrowed. The integration's construction is inert; setup, flow work, live runtimes and retained cleanup share a default capacity of 16.
+
+`resolvePassword` is an application-owned asynchronous callback. Its immutable request contains admitted `homeId`, captured `credentialRef`, `signal` and an absolute `performance.now()` deadline including queue, authentication and readback. Config accepts references rather than plaintext passwords. The adapter registers actual provider work before callback entry, fences late credentials after cancellation and joins the actual callback during shutdown. Provider errors are sanitized; a provider that never settles keeps cleanup pending.
+
+`host` is a hostname or IP address, with the optional port supplied separately. `protocol` defaults to `http`; `https` validates the endpoint certificate through Node's standard transport. Plain HTTP requires explicit `allowUnencryptedLan: true`. Authentication uses the Shelly `admin` username and SHA-256 digest challenges. Credentials and response bodies are excluded from error messages. Request deadlines default to 10 seconds and accept values between 10 ms and 60 seconds.
 
 `switch.turn_on` and `switch.turn_off` accept an exact mapped switch entity id. A mapped device id is sufficient when the device exposes one switch. Feature writes require the connected device id, a mapped writable `switch_N_output` feature, and a boolean value. Foreign targets, nonexistent components, ambiguous device targets and fabricated writable sensor features are rejected before a write.
 
+Controls are denied unless `allowControl: true` is captured in configuration. Each absolute output write freshly validates identity, current methods and component state before sending one `Switch.Set`; it then revalidates identity and independently reads `Switch.GetStatus`. The vendor's `was_on` acknowledges prior state. Results carry `commandAcknowledged`, `causalityConfirmed: false`, requested/prior values and an observed-target or indeterminate outcome. Lost acknowledgement, failed post-dispatch readback or changed identity leaves an indeterminate result. Setter challenges, cancellation and cleanup never replay the effect. Independent readback does not prove relay position, exclusive causality or an atomic preflight.
+
 Subscriptions share one native WebSocket connection to `/rpc`. The initial `Shelly.GetStatus` request supplies a unique source and authenticates both current and older Gen2 digest challenges. `NotifyStatus` patches merge into the validated baseline, including nested fields and null removals. `NotifyFullStatus` replaces the baseline. `NotifyEvent` carries vendor events, and configuration changes refresh mapped names. Disconnects and malformed or foreign frames emit safe errors and unavailable events; `isHealthy()` reflects the failed stream. A later subscription can establish a new connection.
 
-The last unsubscribe closes the socket; an aborted listener removes only that listener. The setup context's abort signal cancels live requests and the push transport. Runtime and integration destruction cancel outstanding requests, remove subscribers, and await owned socket closure. If the endpoint does not complete the native WebSocket close handshake before the deadline, cleanup reports failure and retains ownership for another cleanup attempt.
+The last unsubscribe closes the socket; an aborted listener removes only that listener. The setup context's abort signal cancels live requests and the push transport. Runtime and integration destruction cancel outstanding requests, remove subscribers, and await owned socket closure. If the endpoint does not complete the native WebSocket close handshake before the deadline, cleanup reports failure and retains ownership. Repeated `destroy()` keeps its original promise and failure; explicit integration, config-flow or client `retryCleanup()` retries cleanup only, without credential-provider or device-effect replay. Async subscriber continuations and all sibling cleanup settle before completion. Terminal objects cannot reopen.
 
-Production configuration requires a real endpoint. The former `deviceInfo`, `status` and `deviceConfig` fixture fields have been removed; use a local fixture server in tests or call `ShellyMapper` directly with a snapshot. Tests under `test/shelly/` exercise local HTTP and WebSocket servers without real devices or credentials.
+Production configuration requires a real endpoint. The former `deviceInfo`, `status` and `deviceConfig` fixture fields have been removed; use a local fixture server in tests or call `ShellyMapper` directly with a snapshot. Tests under `test/shelly/` exercise local HTTP and WebSocket servers without real devices or credentials. Qualified synthetic profiles cover Plus 1PM Gen2 `SNSW-001P16EU`, 1PM Gen3 `S3SW-001P16EU` and Plus 2PM `SNSW-002P16EU` with two switch components; this is not universal model certification.
 
 Protocol references: [RPC channels](https://shelly-api-docs.shelly.cloud/gen2/General/RPCChannels/), [authentication](https://shelly-api-docs.shelly.cloud/gen2/General/Authentication/), [notifications](https://shelly-api-docs.shelly.cloud/gen2/General/Notifications/), [mDNS](https://shelly-api-docs.shelly.cloud/gen2/General/mDNS/), and [switch RPC](https://shelly-api-docs.shelly.cloud/gen2/ComponentsAndServices/Switch/).