@smarthome.exchange/integrations 2.0.0 → 3.0.0

package/ts/integrations/shelly/shelly.classes.configflow.ts

@@ -1,48 +1,53 @@
-import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
-import type { IShellyConfig } from './shelly.types.js';
+import type { IConfigFlow, IConfigFlowStep, IDiscoveryCandidate, INativeConfigFlowContext } from '../../core/types.js';
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
+import type { IShellyConfig, IShellyIntegrationOptions } from './shelly.types.js';
 import { ShellyClient } from './shelly.classes.client.js';
+import { normalizeShellyConfig, normalizeShellyOptions, shellyConfigFields, shellyData } from './shelly.validation.js';
 
 export class ShellyConfigFlow implements IConfigFlow<IShellyConfig> {
-  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IShellyConfig>> {
-    void contextArg;
-    return {
-      kind: 'form',
-      title: 'Connect Shelly',
-      description: 'Configure the local Shelly HTTP endpoint. Password is only needed when device authentication is enabled.',
+  readonly #scope: NativeIntegrationScope;
+  readonly #options: Readonly<IShellyIntegrationOptions>;
+  constructor(optionsArg: IShellyIntegrationOptions = {}, scopeArg?: NativeIntegrationScope) {
+    this.#options = normalizeShellyOptions(optionsArg);
+    this.#scope = scopeArg ?? new NativeIntegrationOwner('shelly', { homeId: this.#options.homeId, capacity: this.#options.capacity }).createFlowScope();
+  }
+  public async start(candidateArg: IDiscoveryCandidate, contextArg: INativeConfigFlowContext): Promise<IConfigFlowStep<IShellyConfig>> {
+    const candidate = shellyData(candidateArg);
+    if (candidate.integrationDomain !== undefined && candidate.integrationDomain !== 'shelly') return { kind: 'error', error: 'Candidate does not belong to Shelly.' };
+    const hints = { host: candidate.host, port: candidate.port };
+    const admitted = this.#scope.admit(contextArg);
+    return { kind: 'form', title: 'Connect selected Shelly Gen2/3',
+      description: 'Confirm the reported id, MAC, model and generation for the host-selected home. Supply only a caller credential reference; output controls require explicit enablement.',
       fields: [
         { name: 'host', label: 'Host', type: 'text', required: true },
         { name: 'port', label: 'Port', type: 'number' },
-        { name: 'protocol', label: 'Protocol', type: 'select', options: [
-          { label: 'HTTP', value: 'http' },
-          { label: 'HTTPS', value: 'https' },
-        ] },
-        { name: 'username', label: 'Username', type: 'text' },
-        { name: 'password', label: 'Password', type: 'password' },
+        { name: 'protocol', label: 'Protocol', type: 'select', options: [{ label: 'HTTP', value: 'http' }, { label: 'HTTPS', value: 'https' }] },
+        { name: 'expectedDeviceId', label: 'Exact observed device id', type: 'text', required: true },
+        { name: 'expectedMacAddress', label: 'Exact observed MAC (12 hex digits)', type: 'text', required: true },
+        { name: 'expectedModel', label: 'Exact observed model', type: 'text', required: true },
+        { name: 'expectedGeneration', label: 'Observed generation (2 or 3)', type: 'number', required: true },
+        { name: 'credentialRef', label: 'Caller password reference (if authentication is enabled)', type: 'text' },
+        { name: 'allowUnencryptedLan', label: 'Allow unencrypted selected LAN HTTP', type: 'boolean' },
+        { name: 'allowControl', label: 'Enable absolute switch output controls', type: 'boolean' },
       ],
-      submit: async (valuesArg) => {
-        if (valuesArg.protocol !== undefined && !['http', 'https'].includes(String(valuesArg.protocol)) ||
-          valuesArg.host !== undefined && typeof valuesArg.host !== 'string' ||
-          valuesArg.port !== undefined && typeof valuesArg.port !== 'number' ||
-          valuesArg.username !== undefined && valuesArg.username !== 'admin' ||
-          valuesArg.password !== undefined && typeof valuesArg.password !== 'string') {
-          return { kind: 'error', error: 'Invalid Shelly connection settings.' };
-        }
-        const config: IShellyConfig = {
-          host: typeof valuesArg.host === 'string' ? valuesArg.host : candidateArg.host ?? '',
-          port: typeof valuesArg.port === 'number' ? valuesArg.port : candidateArg.port,
-          protocol: valuesArg.protocol === 'https' ? 'https' : 'http',
-          username: 'admin',
-          password: typeof valuesArg.password === 'string' ? valuesArg.password : undefined,
-        };
-        let client: ShellyClient | undefined;
+      submit: async (inputArg) => {
         try {
-          client = new ShellyClient(config);
-          await client.getSnapshot();
-          return { kind: 'done', title: 'Shelly configured', config };
-        } catch {
-          return { kind: 'error', error: 'Could not validate the Shelly Gen2/3 connection and credentials.' };
-        } finally { await client?.destroy(); }
-      },
-    };
+          const values = shellyData(inputArg, shellyConfigFields);
+          if (values.homeId !== undefined && values.homeId !== admitted.homeId) throw new Error('Shelly submitted home conflicts with the host-selected home.');
+          const config = normalizeShellyConfig({ ...values, homeId: admitted.homeId, host: values.host ?? hints.host, port: values.port ?? hints.port });
+          return await this.#scope.run(admitted, config.homeId, async (leaseArg) => {
+            const client = new ShellyClient(config, { ...leaseArg.context, abortSignal: leaseArg.signal }, this.#options);
+            leaseArg.own(() => client.retryCleanup());
+            await client.getSnapshot();
+            leaseArg.assertOpen();
+            return { kind: 'done', title: 'Selected Shelly admitted', config };
+          });
+        } catch (errorArg) {
+          if (errorArg instanceof AggregateError) throw errorArg;
+          return { kind: 'error', error: 'Could not validate selected Shelly home, identity, capabilities and credential reference.' };
+        }
+      } };
   }
+  public destroy(): Promise<void> { return this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#scope.retryCleanup(); }
 }

package/ts/integrations/shelly/shelly.classes.integration.ts

@@ -1,99 +1,73 @@
 import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import type {
-  IDeviceFeatureWriteRequest,
-  IIntegrationEntity,
-  IIntegrationEvent,
-  IIntegrationRuntime,
-  IIntegrationSetupContext,
-  IServiceCallRequest,
-  IServiceCallResult,
-} from '../../core/types.js';
+import { NativeIntegrationOwner, type INativeSetupLease } from '../../core/classes.nativeintegrationowner.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime,
+  INativeIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
 import { ShellyClient } from './shelly.classes.client.js';
 import { ShellyConfigFlow } from './shelly.classes.configflow.js';
 import { createShellyDiscoveryDescriptor } from './shelly.discovery.js';
 import { ShellyMapper } from './shelly.mapper.js';
-import type { IShellyConfig, IShellySnapshot, TShellyClientEvent } from './shelly.types.js';
+import { normalizeShellyConfig, normalizeShellyOptions, shellyData } from './shelly.validation.js';
+import { ShellyOperationError, type IShellyConfig, type IShellyIntegrationOptions, type IShellySnapshot,
+  type TShellyClientEvent } from './shelly.types.js';
 
 export class ShellyIntegration extends BaseIntegration<IShellyConfig> {
   public readonly domain = 'shelly';
   public readonly displayName = 'Shelly';
   public readonly status = 'control-runtime' as const;
   public readonly discoveryDescriptor = createShellyDiscoveryDescriptor();
-  public readonly configFlow = new ShellyConfigFlow();
-  public readonly metadata = {
-    source: 'home-assistant/core',
-    upstreamPath: 'homeassistant/components/shelly',
-    upstreamDomain: 'shelly',
-    integrationType: 'device',
-    iotClass: 'local_push',
-    qualityScale: 'platinum',
-  };
-  private readonly runtimes = new Set<ShellyRuntime>();
-  private readonly pendingClients = new Set<ShellyClient>();
-  private destroyed = false;
+  public readonly configFlow: ShellyConfigFlow;
+  public readonly metadata = { source: 'native-typescript', upstreamPath: 'homeassistant/components/shelly',
+    upstreamDomain: 'shelly', integrationType: 'device', iotClass: 'local_push', qualityScale: 'platinum' };
+  readonly #owner: NativeIntegrationOwner;
+  readonly #options: Readonly<IShellyIntegrationOptions>;
 
-  public async setup(configArg: IShellyConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    if (this.destroyed) throw new Error('Shelly integration has been destroyed.');
-    const client = new ShellyClient(configArg, contextArg.abortSignal, contextArg.logger);
-    this.pendingClients.add(client);
-    try {
-      const snapshot = await client.getSnapshot();
-      if (this.destroyed) throw new Error('Shelly integration has been destroyed.');
-      const runtime = new ShellyRuntime(client, snapshot, () => this.runtimes.delete(runtime));
-      this.runtimes.add(runtime);
-      this.pendingClients.delete(client);
-      return runtime;
-    } catch (errorArg) {
-      try { await client.destroy(); }
-      catch (cleanupErrorArg) { throw new AggregateError([errorArg, cleanupErrorArg], 'Shelly setup and cleanup failed.'); }
-      this.pendingClients.delete(client);
-      throw errorArg;
-    }
+  public constructor(optionsArg: IShellyIntegrationOptions = {}) {
+    super();
+    this.#options = normalizeShellyOptions(optionsArg);
+    this.#owner = new NativeIntegrationOwner('shelly', { homeId: this.#options.homeId, capacity: this.#options.capacity });
+    this.configFlow = new ShellyConfigFlow(this.#options, this.#owner.createFlowScope());
   }
-
-  public async destroy(): Promise<void> {
-    this.destroyed = true;
-    const results = await Promise.allSettled([
-      ...[...this.runtimes].map((runtimeArg) => runtimeArg.destroy()),
-      ...[...this.pendingClients].map(async (clientArg) => {
-        await clientArg.destroy();
-        this.pendingClients.delete(clientArg);
-      }),
-    ]);
-    const errors = results.flatMap((resultArg) => resultArg.status === 'rejected' ? [resultArg.reason as unknown] : []);
-    if (errors.length) throw new AggregateError(errors, 'Shelly integration cleanup failed.');
+  public setup(configArg: IShellyConfig, contextArg: INativeIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    try {
+      const config = normalizeShellyConfig(configArg);
+      return this.#owner.runSetup(contextArg, config.homeId, async (leaseArg) => {
+        const client = new ShellyClient(config, { ...leaseArg.context, abortSignal: leaseArg.signal }, this.#options);
+        leaseArg.own(() => client.retryCleanup());
+        const snapshot = await client.getSnapshot();
+        leaseArg.assertOpen();
+        const runtime = new ShellyRuntime(client, snapshot, leaseArg);
+        leaseArg.promoteToRuntime();
+        return runtime;
+      });
+    } catch (errorArg) { return Promise.reject(errorArg); }
   }
+  public destroy(): Promise<void> { return this.#owner.close(); }
+  public retryCleanup(): Promise<void> { return this.#owner.retryCleanup(); }
 }
-
 export class HomeAssistantShellyIntegration extends ShellyIntegration {}
 
 class ShellyRuntime implements IIntegrationRuntime {
   public readonly domain = 'shelly';
-
-  constructor(private readonly client: ShellyClient, private snapshot: IShellySnapshot, private readonly onDestroyed: () => void) {}
-
-  public isHealthy(): boolean { return this.client.isHealthy(); }
-
-  public async devices(abortSignalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
-    this.snapshot = await this.client.getSnapshot(abortSignalArg);
-    return ShellyMapper.toDevices(this.snapshot).map((deviceArg) => ({
-      ...deviceArg,
-      online: this.isHealthy(),
+  constructor(private readonly client: ShellyClient, private snapshot: IShellySnapshot, private readonly lease: INativeSetupLease) {}
+  public isHealthy(): boolean { return !this.lease.signal.aborted && this.client.isHealthy(); }
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    this.lease.assertOpen();
+    this.snapshot = await this.client.getSnapshot(signalArg);
+    return ShellyMapper.toDevices(this.snapshot).map((deviceArg) => ({ ...deviceArg, online: this.isHealthy(),
       state: deviceArg.state.map((stateArg) => stateArg.featureId === 'connectivity' ?
-        { ...stateArg, value: this.isHealthy() ? 'online' : 'offline' } : stateArg),
-    }));
+        { ...stateArg, value: this.isHealthy() ? 'online' : 'offline' } : stateArg) }));
   }
-
   public async entities(): Promise<IIntegrationEntity[]> {
+    this.lease.assertOpen();
     this.snapshot = await this.client.getSnapshot();
     return ShellyMapper.toEntities(this.snapshot).map((entityArg) => ({ ...entityArg, available: this.isHealthy() }));
   }
-
-  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    this.lease.assertOpen();
     let previousEntities = ShellyMapper.toEntities(this.snapshot);
     return this.client.subscribe((eventArg: TShellyClientEvent) => {
-      const deviceId = ShellyMapper.toDevices(this.snapshot)[0].id;
+      const deviceId = ShellyMapper.deviceId(this.snapshot);
       const emit = (event: Omit<IIntegrationEvent, 'integrationDomain' | 'deviceId' | 'timestamp'>): void =>
         handlerArg({ ...event, integrationDomain: this.domain, deviceId, timestamp: eventArg.timestamp });
       if (eventArg.type === 'status') {
@@ -103,54 +77,61 @@ class ShellyRuntime implements IIntegrationRuntime {
           const previous = previousEntities.find((candidateArg) => candidateArg.id === entity.id);
           if (JSON.stringify(previous) !== JSON.stringify(entity)) emit({ type: previous ? 'state_changed' : 'entity_added', entityId: entity.id, data: { entity } });
         }
-        for (const previous of previousEntities) {
-          if (!entities.some((entityArg) => entityArg.id === previous.id)) emit({ type: 'entity_removed', entityId: previous.id });
-        }
+        for (const previous of previousEntities) if (!entities.some((entityArg) => entityArg.id === previous.id)) emit({ type: 'entity_removed', entityId: previous.id });
         previousEntities = entities;
-      } else if (eventArg.type === 'availability') {
-        emit({ type: 'availability_changed', data: { available: eventArg.available } });
-      } else if (eventArg.type === 'error') {
-        emit({ type: 'error', data: { message: eventArg.error.message } });
-      } else {
-        emit({ type: 'state_changed', data: { vendor: 'shelly', event: eventArg.event } });
-      }
-    }, abortSignalArg);
+      } else if (eventArg.type === 'availability') emit({ type: 'availability_changed', data: { available: eventArg.available } });
+      else if (eventArg.type === 'error') emit({ type: 'error', data: { message: eventArg.error.message } });
+      else emit({ type: 'state_changed', data: { vendor: 'shelly', event: eventArg.event } });
+    }, signalArg);
   }
-
-  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.domain !== 'switch' || !['turn_on', 'turn_off'].includes(requestArg.service)) return { success: false, error: 'Shelly supports switch.turn_on and switch.turn_off.' };
-    if (requestArg.data && Object.keys(requestArg.data).length) return { success: false, error: 'Shelly switch services do not accept additional data.' };
-    this.snapshot = await this.client.getSnapshot();
-    const deviceId = ShellyMapper.toDevices(this.snapshot)[0].id;
-    if (requestArg.target.deviceId !== undefined && requestArg.target.deviceId !== deviceId) return { success: false, error: 'Shelly service target does not belong to the connected device.' };
+  public async callService(inputArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    this.lease.assertOpen();
+    let request: Record<string, unknown>;
+    let target: Record<string, unknown>;
+    try {
+      request = shellyData(inputArg, ['domain', 'service', 'target', 'data']);
+      target = shellyData(request.target, ['deviceId', 'entityId']);
+      if (request.domain !== 'switch' || !['turn_on', 'turn_off'].includes(String(request.service)) ||
+        request.data !== undefined && Object.keys(shellyData(request.data)).length) return { success: false, error: 'Shelly supports only absolute switch.turn_on and switch.turn_off without extra data.' };
+    } catch { return { success: false, error: 'Invalid Shelly service request.' }; }
+    const deviceId = ShellyMapper.deviceId(this.snapshot);
+    if (target.deviceId !== undefined && target.deviceId !== deviceId) return { success: false, error: 'Shelly service target does not belong to the connected home and device.' };
     const switches = ShellyMapper.toEntities(this.snapshot).filter((entityArg) => entityArg.platform === 'switch');
-    const target = requestArg.target.entityId !== undefined ? switches.find((entityArg) => entityArg.id === requestArg.target.entityId) :
-      requestArg.target.deviceId === deviceId && switches.length === 1 ? switches[0] : undefined;
-    if (!target) return { success: false, error: 'Shelly service requires an exact switch entity or an unambiguous device target.' };
-    const switchId = this.componentId(target.uniqueId);
-    if (switchId === undefined) return { success: false, error: 'Shelly switch target has no component id.' };
-    await this.client.setSwitchOutput(switchId, requestArg.service === 'turn_on');
-    return { success: true };
+    const selected = target.entityId !== undefined ? switches.find((entityArg) => entityArg.id === target.entityId) :
+      target.deviceId === deviceId && switches.length === 1 ? switches[0] : undefined;
+    if (!selected) return { success: false, error: 'Shelly service requires an exact switch entity or an unambiguous device target.' };
+    const match = /\.switch_(\d+)$/.exec(selected.uniqueId);
+    if (!match) return { success: false, error: 'Shelly switch target has no component id.' };
+    return this.control(Number(match[1]), request.service === 'turn_on');
   }
-
-  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, abortSignalArg?: AbortSignal): Promise<IServiceCallResult> {
-    this.snapshot = await this.client.getSnapshot(abortSignalArg);
-    const device = ShellyMapper.toDevices(this.snapshot)[0];
-    if (requestArg.device.id !== device.id || requestArg.device.integrationDomain !== this.domain) return { success: false, error: 'Shelly feature target does not belong to the connected device.' };
-    const feature = device.features.find((featureArg) => featureArg.id === requestArg.feature.id);
+  public async writeFeature(inputArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    this.lease.assertOpen();
+    let request: Record<string, unknown>;
+    let deviceInput: Record<string, unknown>;
+    let featureInput: Record<string, unknown>;
+    try {
+      request = shellyData(inputArg, ['device', 'feature', 'value']);
+      deviceInput = shellyData(request.device);
+      featureInput = shellyData(request.feature);
+    } catch { return { success: false, error: 'Invalid Shelly feature request.' }; }
+    if (deviceInput.id !== ShellyMapper.deviceId(this.snapshot) || deviceInput.integrationDomain !== this.domain) return { success: false, error: 'Shelly feature target does not belong to the connected home and device.' };
+    const feature = ShellyMapper.toDevices(this.snapshot)[0].features.find((entryArg) => entryArg.id === featureInput.id);
     const match = feature && /^switch_(\d+)_output$/.exec(feature.id);
-    if (!match || !feature.writable || feature.capability !== 'switch' || typeof requestArg.value !== 'boolean') return { success: false, error: 'Shelly writes require a writable switch output and boolean value.' };
-    await this.client.setSwitchOutput(Number(match[1]), requestArg.value, abortSignalArg);
-    return { success: true };
+    if (!match || !feature.writable || feature.capability !== 'switch' || featureInput.capability !== 'switch' || typeof request.value !== 'boolean') return { success: false, error: 'Shelly writes require a current writable switch output and boolean value.' };
+    return this.control(Number(match[1]), request.value, signalArg);
   }
-
-  public async destroy(): Promise<void> {
-    await this.client.destroy();
-    this.onDestroyed();
-  }
-
-  private componentId(uniqueIdArg: string): number | undefined {
-    const match = /_switch_(\d+)$/.exec(uniqueIdArg);
-    return match ? Number(match[1]) : undefined;
+  public destroy(): Promise<void> { return this.lease.close(); }
+  private async control(idArg: number, onArg: boolean, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      const receipt = await this.client.setSwitchOutput(idArg, onArg, signalArg);
+      this.snapshot = receipt.snapshot;
+      return { success: receipt.outcome === 'observed-target',
+        ...(receipt.outcome === 'indeterminate' ? { error: 'Shelly acknowledged the command, but independent reported output differs.' } : {}),
+        data: { ...receipt, devices: ShellyMapper.toDevices(receipt.snapshot), entities: ShellyMapper.toEntities(receipt.snapshot) } };
+    } catch (errorArg) {
+      const error = errorArg instanceof ShellyOperationError ? errorArg : undefined;
+      return { success: false, error: error?.message ?? 'Shelly control was not admitted.',
+        data: { effectOutcome: error?.effectOutcome ?? 'not-sent', commandAcknowledged: error?.commandAcknowledged ?? false, causalityConfirmed: false } };
+    }
   }
 }

package/ts/integrations/shelly/shelly.classes.subscription.ts

@@ -28,6 +28,8 @@ export class ShellySubscription {
   private resolveStart?: () => void;
   private rejectStart?: (errorArg: Error) => void;
   private closePromise?: Promise<void>;
+  private stopPromise?: Promise<void>;
+  private retryPromise?: Promise<void>;
   private resolveClose?: () => void;
   private deadline?: ReturnType<typeof setTimeout>;
   private requestId = 1;
@@ -65,7 +67,26 @@ export class ShellySubscription {
     return this.startPromise;
   }
 
-  public async stop(): Promise<void> {
+  public stop(): Promise<void> {
+    if (!this.stopPromise) {
+      // Publish before availability callbacks or synchronous socket/abort listeners.
+      this.stopPromise = Promise.resolve().then(() => this.drainClose());
+      this.stopping = true;
+    }
+    return this.stopPromise;
+  }
+
+  public retryCleanup(): Promise<void> {
+    if (!this.stopPromise) return this.stop();
+    if (!this.retryPromise) {
+      this.retryPromise = Promise.resolve().then(() => this.drainClose());
+      const settled = (): void => { this.retryPromise = undefined; };
+      void this.retryPromise.then(settled, settled);
+    }
+    return this.retryPromise;
+  }
+
+  private async drainClose(): Promise<void> {
     this.stopping = true;
     this.setHealthy(false);
     this.clearDeadline();
@@ -123,6 +144,7 @@ export class ShellySubscription {
       this.resolveStart?.();
       this.resolveStart = undefined;
       this.rejectStart = undefined;
+      this.options.password = undefined;
     } catch (errorArg) {
       this.fail(errorArg instanceof AuthenticationError || errorArg instanceof DeviceCommunicationError ?
         errorArg : new DeviceCommunicationError('Shelly returned an invalid WebSocket payload.'));
@@ -214,5 +236,6 @@ export class ShellySubscription {
     this.socket?.removeEventListener('close', this.handleClose);
     this.resolveClose?.();
     this.resolveClose = undefined;
+    this.options.password = undefined;
   }
 }

package/ts/integrations/shelly/shelly.mapper.ts

@@ -4,7 +4,7 @@ import type { IShellyDeviceConfig, IShellyDeviceInfo, IShellySnapshot, IShellySt
 
 export class ShellyMapper {
   public static toDevices(snapshotArg: IShellySnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
-    const deviceId = this.deviceId(snapshotArg.deviceInfo, snapshotArg.status);
+    const deviceId = this.deviceId(snapshotArg);
     const updatedAt = new Date().toISOString();
     const features: plugins.shxInterfaces.data.IDeviceFeature[] = [
       { id: 'connectivity', capability: 'sensor', name: 'Connectivity', readable: true, writable: false },
@@ -21,7 +21,8 @@ export class ShellyMapper {
     for (const switchComponent of this.switchComponents(snapshotArg.status)) {
       const prefix = `switch_${switchComponent.id}`;
       const name = this.componentName(snapshotArg.deviceConfig, `switch:${switchComponent.id}`, `Switch ${switchComponent.id}`);
-      features.push({ id: `${prefix}_output`, capability: 'switch', name, readable: true, writable: true });
+      features.push({ id: `${prefix}_output`, capability: 'switch', name, readable: true,
+        writable: snapshotArg.controlEnabled && snapshotArg.methods.includes('Switch.Set') && snapshotArg.methods.includes('Switch.GetStatus') });
       state.push({ featureId: `${prefix}_output`, value: switchComponent.status.output ?? null, updatedAt });
       this.pushNumericFeature(features, state, `${prefix}_power`, `${name} power`, switchComponent.status.apower, 'W', updatedAt);
       this.pushNumericFeature(features, state, `${prefix}_voltage`, `${name} voltage`, switchComponent.status.voltage, 'V', updatedAt);
@@ -36,7 +37,7 @@ export class ShellyMapper {
       name: this.deviceName(snapshotArg.deviceInfo, snapshotArg.deviceConfig),
       protocol: 'http',
       manufacturer: 'Shelly',
-      model: snapshotArg.deviceInfo.model || snapshotArg.deviceInfo.app,
+      model: snapshotArg.deviceInfo.model,
       online: true,
       features,
       state,
@@ -46,20 +47,21 @@ export class ShellyMapper {
         authEnabled: snapshotArg.deviceInfo.auth_en ?? snapshotArg.deviceInfo.auth,
         macAddress: snapshotArg.deviceInfo.mac || snapshotArg.status.sys?.mac,
         profile: snapshotArg.deviceInfo.profile,
+        homeId: snapshotArg.homeId,
       },
     }];
   }
 
   public static toEntities(snapshotArg: IShellySnapshot): IIntegrationEntity[] {
-    const deviceId = this.deviceId(snapshotArg.deviceInfo, snapshotArg.status);
-    const deviceSlug = this.slug(this.deviceName(snapshotArg.deviceInfo, snapshotArg.deviceConfig));
+    const deviceId = this.deviceId(snapshotArg);
+    const deviceSlug = `${encodeURIComponent(snapshotArg.homeId)}.${encodeURIComponent(snapshotArg.deviceInfo.id!)}`;
     const entities: IIntegrationEntity[] = [];
 
     for (const switchComponent of this.switchComponents(snapshotArg.status)) {
       const switchName = this.componentName(snapshotArg.deviceConfig, `switch:${switchComponent.id}`, `Switch ${switchComponent.id}`);
-      const uniquePrefix = `shelly_${this.slug(deviceId)}_switch_${switchComponent.id}`;
+      const uniquePrefix = `${deviceId}.switch_${switchComponent.id}`;
       entities.push({
-        id: `switch.${deviceSlug}_${switchComponent.id}`,
+        id: `switch.${deviceSlug}.${switchComponent.id}`,
         uniqueId: uniquePrefix,
         integrationDomain: 'shelly',
         deviceId,
@@ -72,11 +74,11 @@ export class ShellyMapper {
         },
         available: true,
       });
-      this.pushSensorEntity(entities, deviceId, `${uniquePrefix}_power`, `sensor.${deviceSlug}_${switchComponent.id}_power`, `${switchName} power`, switchComponent.status.apower, 'W');
-      this.pushSensorEntity(entities, deviceId, `${uniquePrefix}_voltage`, `sensor.${deviceSlug}_${switchComponent.id}_voltage`, `${switchName} voltage`, switchComponent.status.voltage, 'V');
-      this.pushSensorEntity(entities, deviceId, `${uniquePrefix}_current`, `sensor.${deviceSlug}_${switchComponent.id}_current`, `${switchName} current`, switchComponent.status.current, 'A');
-      this.pushSensorEntity(entities, deviceId, `${uniquePrefix}_energy`, `sensor.${deviceSlug}_${switchComponent.id}_energy`, `${switchName} energy`, switchComponent.status.aenergy?.total, 'Wh');
-      this.pushSensorEntity(entities, deviceId, `${uniquePrefix}_temperature`, `sensor.${deviceSlug}_${switchComponent.id}_temperature`, `${switchName} temperature`, switchComponent.status.temperature?.tC, 'C');
+      this.pushSensorEntity(entities, deviceId, `${uniquePrefix}_power`, `sensor.${deviceSlug}.${switchComponent.id}.power`, `${switchName} power`, switchComponent.status.apower, 'W');
+      this.pushSensorEntity(entities, deviceId, `${uniquePrefix}_voltage`, `sensor.${deviceSlug}.${switchComponent.id}.voltage`, `${switchName} voltage`, switchComponent.status.voltage, 'V');
+      this.pushSensorEntity(entities, deviceId, `${uniquePrefix}_current`, `sensor.${deviceSlug}.${switchComponent.id}.current`, `${switchName} current`, switchComponent.status.current, 'A');
+      this.pushSensorEntity(entities, deviceId, `${uniquePrefix}_energy`, `sensor.${deviceSlug}.${switchComponent.id}.energy`, `${switchName} energy`, switchComponent.status.aenergy?.total, 'Wh');
+      this.pushSensorEntity(entities, deviceId, `${uniquePrefix}_temperature`, `sensor.${deviceSlug}.${switchComponent.id}.temperature`, `${switchName} temperature`, switchComponent.status.temperature?.tC, 'C');
     }
 
     return entities;
@@ -91,7 +93,7 @@ export class ShellyMapper {
     unitArg: string,
     updatedAtArg: string
   ): void {
-    if (typeof valueArg !== 'number') {
+    if (typeof valueArg !== 'number' || !Number.isFinite(valueArg)) {
       return;
     }
     featuresArg.push({ id: idArg, capability: 'sensor', name: nameArg, readable: true, writable: false, unit: unitArg });
@@ -107,7 +109,7 @@ export class ShellyMapper {
     valueArg: number | null | undefined,
     unitArg: string
   ): void {
-    if (typeof valueArg !== 'number') {
+    if (typeof valueArg !== 'number' || !Number.isFinite(valueArg)) {
       return;
     }
     entitiesArg.push({
@@ -139,8 +141,9 @@ export class ShellyMapper {
     return components.sort((leftArg, rightArg) => leftArg.id - rightArg.id);
   }
 
-  private static deviceId(deviceInfoArg: IShellyDeviceInfo, statusArg: IShellyStatus): string {
-    return `shelly.device.${this.slug(deviceInfoArg.id || deviceInfoArg.mac || statusArg.sys?.mac || 'unknown')}`;
+  public static deviceId(snapshotArg: IShellySnapshot): string {
+    if (!snapshotArg.homeId || !snapshotArg.deviceInfo.id) throw new TypeError('Shelly mapping requires admitted home and observed device identity.');
+    return `shelly.device.${encodeURIComponent(snapshotArg.homeId)}.${encodeURIComponent(snapshotArg.deviceInfo.id)}`;
   }
 
   private static deviceName(deviceInfoArg: IShellyDeviceInfo, configArg?: IShellyDeviceConfig): string {
@@ -155,10 +158,6 @@ export class ShellyMapper {
     return fallbackArg;
   }
 
-  private static slug(valueArg: string): string {
-    return valueArg.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '') || 'shelly';
-  }
-
   private static isRecord(valueArg: unknown): valueArg is Record<string, unknown> {
     return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
   }

package/ts/integrations/shelly/shelly.rpc.ts

@@ -29,6 +29,8 @@ export const parseShellyDeviceInfo = (valueArg: unknown): IShellyDeviceInfo => {
   if (valueArg.gen !== 2 && valueArg.gen !== 3) {
     throw new DeviceCommunicationError('Shelly integration supports generation 2 and 3 devices.');
   }
+  if (typeof valueArg.mac !== 'string' || !/^[0-9a-f]{12}$/i.test(valueArg.mac) ||
+    typeof valueArg.model !== 'string' || !valueArg.model || valueArg.model.length > 128) invalidPayload();
   for (const key of ['mac', 'model', 'ver', 'fw_id', 'app', 'profile']) {
     if (valueArg[key] !== undefined && typeof valueArg[key] !== 'string') invalidPayload();
   }

package/ts/integrations/shelly/shelly.types.ts

@@ -1,12 +1,57 @@
 export type TShellyProtocol = 'http' | 'https';
 
 export interface IShellyConfig {
+  homeId: string;
   host: string;
   port?: number;
   protocol?: TShellyProtocol;
-  username?: string;
-  password?: string;
+  expectedDeviceId: string;
+  expectedMacAddress: string;
+  expectedModel: string;
+  expectedGeneration: 2 | 3;
+  credentialRef?: string;
+  /** Absolute output controls are denied unless explicitly enabled. */
+  allowControl?: boolean;
+  allowUnencryptedLan?: boolean;
   requestTimeoutMs?: number;
+  maxPendingOperations?: number;
+  maxResponseBytes?: number;
+}
+
+export interface IShellyCredentialRequest {
+  readonly homeId: string;
+  readonly credentialRef: string;
+  readonly signal: AbortSignal;
+  /** Monotonic performance.now() deadline, including queue time. */
+  readonly deadline: number;
+}
+
+export type TShellyPasswordResolver = (requestArg: IShellyCredentialRequest) => Promise<string>;
+
+export interface IShellyIntegrationOptions {
+  readonly homeId?: string;
+  readonly capacity?: number;
+  readonly resolvePassword?: TShellyPasswordResolver;
+}
+
+export type TShellyEffectOutcome = 'not-sent' | 'indeterminate';
+
+export class ShellyOperationError extends Error {
+  constructor(messageArg: string, public readonly effectOutcome: TShellyEffectOutcome = 'not-sent',
+    public readonly commandAcknowledged = false) {
+    super(messageArg);
+    this.name = 'ShellyOperationError';
+  }
+}
+
+export interface IShellyEffectResult {
+  readonly componentId: number;
+  readonly requested: boolean;
+  readonly wasOn: boolean;
+  readonly commandAcknowledged: true;
+  readonly causalityConfirmed: false;
+  readonly outcome: 'observed-target' | 'indeterminate';
+  readonly snapshot: IShellySnapshot;
 }
 
 export interface IShellyDeviceInfo {
@@ -78,9 +123,12 @@ export interface IShellySwitchStatus {
 }
 
 export interface IShellySnapshot {
+  homeId: string;
   deviceInfo: IShellyDeviceInfo;
   status: IShellyStatus;
   deviceConfig?: IShellyDeviceConfig;
+  methods: readonly string[];
+  controlEnabled: boolean;
 }
 
 export interface IShellyComponentEvent {