@smarthome.exchange/integrations 2.0.0 → 4.0.0

package/ts/integrations/samsungtv/samsungtv.classes.configflow.ts

@@ -1,20 +1,28 @@
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
 import type { ISamsungtvConfig } from './samsungtv.types.js';
 import { normalizeSamsungtvConfig, samsungtvKeys, samsungtvObject } from './samsungtv.validation.js';
 
 export class SamsungtvConfigFlow implements IConfigFlow<ISamsungtvConfig> {
+  readonly #scope: NativeIntegrationScope;
+
+  constructor(ownerArg: NativeIntegrationOwner = new NativeIntegrationOwner('samsungtv')) {
+    this.#scope = ownerArg.createFlowScope();
+  }
+
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<ISamsungtvConfig>> {
-    void contextArg;
-    const metadata = candidateArg.metadata === undefined ? {} : samsungtvObject(candidateArg.metadata, 'Samsung TV candidate metadata');
+    const context = this.#scope.admit(contextArg);
+    const candidate = samsungtvObject(candidateArg, 'Samsung TV discovery candidate');
+    const metadata = candidate.metadata === undefined ? {} : samsungtvObject(candidate.metadata, 'Samsung TV candidate metadata');
     const hints: Record<string, unknown> = {};
     for (const field of ['httpOrigin', 'websocketOrigin', 'expectedDeviceId']) {
       if (typeof metadata[field] === 'string') hints[field] = metadata[field];
     }
+    Object.freeze(hints);
     return {
       kind: 'form', title: 'Pair Samsung Smart TV',
-      description: 'Confirm this home, the exact TV UUID, explicit REST/WSS origins and trusted TV CA. Confirm the TV pairing prompt when using prompt mode. Pairing credentials are stored only in encrypted home-scoped persistence.',
+      description: 'Confirm the exact TV UUID, explicit REST/WSS origins and trusted TV CA for the selected home. Confirm the TV pairing prompt when using prompt mode. Pairing credentials are stored only in encrypted home-scoped persistence.',
       fields: [
-        { name: 'homeId', label: 'Home ID', type: 'text', required: true },
         { name: 'expectedDeviceId', label: 'Exact TV UUID', type: 'text', required: true },
         { name: 'httpOrigin', label: 'REST origin', type: 'text', required: true },
         { name: 'websocketOrigin', label: 'Verified WSS origin', type: 'text', required: true },
@@ -27,17 +35,24 @@ export class SamsungtvConfigFlow implements IConfigFlow<ISamsungtvConfig> {
         try {
           const values = samsungtvObject(valuesArg, 'Samsung TV config form');
           samsungtvKeys(values, ['homeId', 'expectedDeviceId', 'httpOrigin', 'websocketOrigin', 'pairingMode', 'certificateAuthority', 'allowUnencryptedLocalDiscovery']);
+          if (values.homeId !== undefined && values.homeId !== context.homeId) throw new Error('Samsung TV form home does not match the selected host home.');
           const config = normalizeSamsungtvConfig({
-            homeId: values.homeId, expectedDeviceId: values.expectedDeviceId ?? hints.expectedDeviceId,
+            homeId: context.homeId, expectedDeviceId: values.expectedDeviceId ?? hints.expectedDeviceId,
             httpOrigin: values.httpOrigin ?? hints.httpOrigin, websocketOrigin: values.websocketOrigin ?? hints.websocketOrigin,
             pairingMode: values.pairingMode, certificateAuthority: values.certificateAuthority,
             allowUnencryptedLocalDiscovery: values.allowUnencryptedLocalDiscovery,
           });
-          return { kind: 'done', title: 'Samsung Smart TV configuration accepted', config };
+          return await this.#scope.run(context, config.homeId, async (leaseArg) => {
+            leaseArg.assertOpen();
+            return { kind: 'done', title: 'Samsung Smart TV configuration accepted', config };
+          });
         } catch (errorArg) {
           return { kind: 'error', error: errorArg instanceof Error ? errorArg.message : 'Samsung TV configuration is invalid.' };
         }
       },
     };
   }
+
+  public destroy(): Promise<void> { return this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#scope.retryCleanup(); }
 }

package/ts/integrations/samsungtv/samsungtv.classes.integration.ts

@@ -1,13 +1,13 @@
 import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import { NoSqlConfigStore } from '../../core/classes.configstore.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
 import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { SamsungtvClient } from './samsungtv.classes.client.js';
 import { SamsungtvConfigFlow } from './samsungtv.classes.configflow.js';
 import { createSamsungtvDiscoveryDescriptor } from './samsungtv.discovery.js';
 import { SamsungtvMapper } from './samsungtv.mapper.js';
-import type { ISamsungtvConfig, ISamsungtvIntegrationOptions, ISamsungtvSnapshot, TSamsungtvRemoteKey } from './samsungtv.types.js';
-import { samsungtvKeys, samsungtvObject } from './samsungtv.validation.js';
+import type { ISamsungtvConfig, ISamsungtvClientOptions, ISamsungtvIntegrationOptions, ISamsungtvSnapshot, TSamsungtvRemoteKey } from './samsungtv.types.js';
+import { normalizeSamsungtvConfig, samsungtvKeys, samsungtvObject } from './samsungtv.validation.js';
 
 const serviceKeys = {
   turn_off: 'KEY_POWEROFF', media_play: 'KEY_PLAY', media_pause: 'KEY_PAUSE', media_stop: 'KEY_STOP',
@@ -32,65 +32,77 @@ export class SamsungtvIntegration extends BaseIntegration<ISamsungtvConfig> {
   public readonly displayName = 'Samsung Smart TV';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createSamsungtvDiscoveryDescriptor();
-  public readonly configFlow = new SamsungtvConfigFlow();
+  public readonly configFlow: SamsungtvConfigFlow;
   public readonly metadata = {
     source: 'home-assistant/core', upstreamDomain: 'samsungtv', integrationType: 'device', iotClass: 'local_poll',
     localApi: { implemented: ['verified UUID and WSS pairing', 'encrypted home-scoped pairing', 'fresh REST observations', 'single supported remote Click'],
       explicitUnsupported: ['optimistic state', 'automatic retries or replay', 'legacy TCP/PIN', 'play_pause', 'app launch', 'absolute volume/mute assignment', 'wake-on-LAN', 'hold/release/repeated keys'] },
   };
-  readonly #runtimes = new Set<SamsungtvRuntime>();
-  readonly #pending = new Set<SamsungtvClient>();
-  #options?: ISamsungtvIntegrationOptions;
-  #destroyed = false;
-  #destroy?: Promise<void>;
+  readonly #owner: NativeIntegrationOwner;
+  #options?: ISamsungtvClientOptions;
 
-  constructor(optionsArg?: ISamsungtvIntegrationOptions) {
+  constructor(optionsArg: ISamsungtvIntegrationOptions = {}) {
     super();
-    this.#options = optionsArg ? { db: optionsArg.db, keyProvider: optionsArg.keyProvider } : undefined;
+    const options = samsungtvObject(optionsArg, 'Samsung TV integration options');
+    samsungtvKeys(options, ['homeId', 'capacity', 'db', 'keyProvider']);
+    if ((options.db === undefined) !== (options.keyProvider === undefined)) {
+      throw new TypeError('Samsung TV database and key provider must be supplied together.');
+    }
+    this.#options = options.db === undefined ? undefined : {
+      db: options.db as ISamsungtvClientOptions['db'], keyProvider: options.keyProvider as ISamsungtvClientOptions['keyProvider'],
+    };
+    this.#owner = new NativeIntegrationOwner(this.domain, { homeId: options.homeId as string | undefined, capacity: options.capacity as number | undefined });
+    this.configFlow = new SamsungtvConfigFlow(this.#owner);
   }
 
   public async setup(configArg: ISamsungtvConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    if (this.#destroyed) throw new Error('Samsung TV integration is destroyed.');
-    if (contextArg.configStore !== undefined && !(contextArg.configStore instanceof NoSqlConfigStore)) {
-      throw new TypeError('Samsung TV runtime requires an encrypted NoSqlConfigStore.');
-    }
-    const client = new SamsungtvClient(configArg, contextArg.configStore ?? this.#options, contextArg.abortSignal);
-    this.#pending.add(client);
-    try {
-      const snapshot = await client.getSnapshot(contextArg.abortSignal);
-      if (this.#destroyed) throw new Error('Samsung TV integration was destroyed during setup.');
-      const runtime = new SamsungtvRuntime(client, snapshot, () => this.#runtimes.delete(runtime));
-      this.#runtimes.add(runtime);
+    const config = normalizeSamsungtvConfig(configArg);
+    return this.#owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+      const client = new SamsungtvClient(config, leaseArg.context.configStore ?? this.#options, leaseArg.signal);
+      let cleanupAttempted = false;
+      leaseArg.own(() => {
+        if (cleanupAttempted) return client.retryCleanup();
+        cleanupAttempted = true;
+        return client.destroy();
+      });
+      const snapshot = await client.getSnapshot(leaseArg.signal);
+      leaseArg.assertOpen();
+      const runtime = new SamsungtvRuntime(client, snapshot, leaseArg);
+      leaseArg.promoteToRuntime();
       return runtime;
-    } catch (errorArg) { await client.destroy(); throw errorArg; }
-    finally { this.#pending.delete(client); }
+    });
   }
 
   public destroy(): Promise<void> {
-    if (!this.#destroy) {
-      this.#destroyed = true;
-      this.#destroy = Promise.all([
-        ...[...this.#runtimes].map((runtimeArg) => runtimeArg.destroy()),
-        ...[...this.#pending].map((clientArg) => clientArg.destroy()),
-      ]).then(() => { this.#options = undefined; });
-    }
-    return this.#destroy;
+    const closed = this.#owner.close();
+    this.#options = undefined;
+    return closed;
   }
+
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
 
 export class HomeAssistantSamsungtvIntegration extends SamsungtvIntegration {}
 
 class SamsungtvRuntime implements IIntegrationRuntime {
   public readonly domain = 'samsungtv';
-  constructor(private readonly client: SamsungtvClient, private readonly identity: ISamsungtvSnapshot, private readonly onDestroyed: () => void) {}
+  readonly #deviceId: string;
+  constructor(private readonly client: SamsungtvClient, identityArg: ISamsungtvSnapshot, private readonly lease: INativeSetupLease) {
+    this.#deviceId = SamsungtvMapper.deviceId(identityArg);
+  }
   public isHealthy(): boolean { return this.client.isHealthy(); }
   public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    this.lease.assertOpen();
     return SamsungtvMapper.toDevices(await this.client.getSnapshot(signalArg));
   }
-  public async entities(): Promise<IIntegrationEntity[]> { return SamsungtvMapper.toEntities(await this.client.getSnapshot()); }
+  public async entities(): Promise<IIntegrationEntity[]> {
+    this.lease.assertOpen();
+    return SamsungtvMapper.toEntities(await this.client.getSnapshot());
+  }
 
   public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
     try {
+      this.lease.assertOpen();
       const request = samsungtvObject(requestArg, 'Samsung TV service request');
       samsungtvKeys(request, ['domain', 'service', 'target', 'data']);
       this.#assertTarget(request.target);
@@ -117,24 +129,27 @@ class SamsungtvRuntime implements IIntegrationRuntime {
 
   public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
     try {
+      this.lease.assertOpen();
       const request = samsungtvObject(requestArg, 'Samsung TV feature write');
       samsungtvKeys(request, ['device', 'feature', 'value']);
       const device = samsungtvObject(request.device, 'Samsung TV feature device');
       const feature = samsungtvObject(request.feature, 'Samsung TV feature');
-      if (device.id !== SamsungtvMapper.deviceId(this.identity) || device.integrationDomain !== this.domain) {
+      if (device.id !== this.#deviceId || device.integrationDomain !== this.domain) {
         throw new TypeError('Samsung TV feature device is not owned by this runtime.');
       }
-      if (feature.id !== 'remote_key') throw new TypeError('Samsung TV feature is not writable.');
+      if (feature.id !== 'remote_key' || feature.capability !== 'media' || feature.readable !== false || feature.writable !== true) {
+        throw new TypeError('Samsung TV feature is not the owned writable remote key.');
+      }
       return { success: true, data: await this.client.sendKey(remoteKey(request.value), signalArg) };
     } catch (errorArg) { return failure(errorArg); }
   }
 
-  public async destroy(): Promise<void> { await this.client.destroy(); this.onDestroyed(); }
+  public destroy(): Promise<void> { return this.lease.close(); }
 
   #assertTarget(valueArg: unknown): void {
     const target = samsungtvObject(valueArg, 'Samsung TV service target');
     samsungtvKeys(target, ['deviceId', 'entityId']);
-    const deviceId = SamsungtvMapper.deviceId(this.identity);
+    const deviceId = this.#deviceId;
     if ((target.deviceId === undefined && target.entityId === undefined) ||
       (target.deviceId !== undefined && target.deviceId !== deviceId) ||
       (target.entityId !== undefined && target.entityId !== `${deviceId}:media_player`)) {

package/ts/integrations/samsungtv/samsungtv.types.ts

@@ -1,5 +1,6 @@
 import type * as plugins from '../../plugins.js';
 import type { IConfigEncryptionKeyProvider } from '../../core/classes.configstore.js';
+import type { INativeIntegrationOwnerOptions } from '../../core/classes.nativeintegrationowner.js';
 
 export interface ISamsungtvConfig {
   homeId: string;
@@ -16,11 +17,13 @@ export interface ISamsungtvConfig {
 
 export interface IHomeAssistantSamsungtvConfig extends ISamsungtvConfig {}
 
-export interface ISamsungtvIntegrationOptions {
+export interface ISamsungtvClientOptions {
   db: plugins.nosqldb.SmartdataDb;
   keyProvider: IConfigEncryptionKeyProvider;
 }
 
+export interface ISamsungtvIntegrationOptions extends INativeIntegrationOwnerOptions, Partial<ISamsungtvClientOptions> {}
+
 export interface ISamsungtvSnapshot {
   readonly homeId: string;
   readonly device: plugins.ecobridgeDeviceManager.ISamsungTvDeviceInfo;

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/).