@smarthome.exchange/integrations 0.2.0 → 2.0.0

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

@@ -1,11 +1,19 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
+import * as plugins from '../../plugins.js';
 import { BaseIntegration } from '../../core/classes.baseintegration.js';
-import type { IIntegrationEntity, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import type {
+  IDeviceFeatureWriteRequest,
+  IIntegrationEntity,
+  IIntegrationEvent,
+  IIntegrationRuntime,
+  IIntegrationSetupContext,
+  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 } from './shelly.types.js';
+import type { IShellyConfig, IShellySnapshot, TShellyClientEvent } from './shelly.types.js';
 
 export class ShellyIntegration extends BaseIntegration<IShellyConfig> {
   public readonly domain = 'shelly';
@@ -21,59 +29,128 @@ export class ShellyIntegration extends BaseIntegration<IShellyConfig> {
     iotClass: 'local_push',
     qualityScale: 'platinum',
   };
+  private readonly runtimes = new Set<ShellyRuntime>();
+  private readonly pendingClients = new Set<ShellyClient>();
+  private destroyed = false;
 
   public async setup(configArg: IShellyConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
-    void contextArg;
-    return new ShellyRuntime(new ShellyClient(configArg));
+    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 async destroy(): Promise<void> {}
+  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.');
+  }
 }
 
 export class HomeAssistantShellyIntegration extends ShellyIntegration {}
 
 class ShellyRuntime implements IIntegrationRuntime {
-  public domain = 'shelly';
+  public readonly domain = 'shelly';
 
-  constructor(private readonly client: ShellyClient) {}
+  constructor(private readonly client: ShellyClient, private snapshot: IShellySnapshot, private readonly onDestroyed: () => void) {}
 
-  public async devices(): Promise<shxInterfaces.data.IDeviceDefinition[]> {
-    return ShellyMapper.toDevices(await this.client.getSnapshot());
+  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(),
+      state: deviceArg.state.map((stateArg) => stateArg.featureId === 'connectivity' ?
+        { ...stateArg, value: this.isHealthy() ? 'online' : 'offline' } : stateArg),
+    }));
   }
 
   public async entities(): Promise<IIntegrationEntity[]> {
-    return ShellyMapper.toEntities(await this.client.getSnapshot());
+    this.snapshot = await this.client.getSnapshot();
+    return ShellyMapper.toEntities(this.snapshot).map((entityArg) => ({ ...entityArg, available: this.isHealthy() }));
   }
 
-  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
-    if (requestArg.domain !== 'switch') {
-      return { success: false, error: `Unsupported Shelly service domain: ${requestArg.domain}` };
-    }
-
-    const switchId = this.resolveSwitchId(requestArg.target.entityId, requestArg.target.deviceId);
-    if (switchId === undefined) {
-      return { success: false, error: 'Shelly switch service calls require a switch entity or device target with a numeric switch id.' };
-    }
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
+    let previousEntities = ShellyMapper.toEntities(this.snapshot);
+    return this.client.subscribe((eventArg: TShellyClientEvent) => {
+      const deviceId = ShellyMapper.toDevices(this.snapshot)[0].id;
+      const emit = (event: Omit<IIntegrationEvent, 'integrationDomain' | 'deviceId' | 'timestamp'>): void =>
+        handlerArg({ ...event, integrationDomain: this.domain, deviceId, timestamp: eventArg.timestamp });
+      if (eventArg.type === 'status') {
+        this.snapshot = eventArg.snapshot;
+        const entities = ShellyMapper.toEntities(this.snapshot);
+        for (const entity of entities) {
+          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 });
+        }
+        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);
+  }
 
-    if (requestArg.service === 'turn_on') {
-      await this.client.setSwitchOutput(switchId, true);
-      return { success: true };
-    }
-    if (requestArg.service === 'turn_off') {
-      await this.client.setSwitchOutput(switchId, false);
-      return { success: true };
-    }
+  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.' };
+    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 };
+  }
 
-    return { success: false, error: `Unsupported Shelly switch service: ${requestArg.service}` };
+  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);
+    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 };
   }
 
   public async destroy(): Promise<void> {
     await this.client.destroy();
+    this.onDestroyed();
   }
 
-  private resolveSwitchId(entityIdArg?: string, deviceIdArg?: string): number | undefined {
-    const candidate = entityIdArg || deviceIdArg;
-    const match = candidate?.match(/(?:switch[_\.]|_)(\d+)$/);
+  private componentId(uniqueIdArg: string): number | undefined {
+    const match = /_switch_(\d+)$/.exec(uniqueIdArg);
     return match ? Number(match[1]) : undefined;
   }
 }

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

@@ -0,0 +1,218 @@
+import { AuthenticationError, DeviceCommunicationError } from '../../core/errors.js';
+import {
+  createShellyDigest,
+  isShellyRecord,
+  parseShellyDigestChallenge,
+  parseShellyEvents,
+  parseShellyRpcResult,
+  parseShellyStatus,
+} from './shelly.rpc.js';
+import type { IShellyComponentEvent, IShellyStatus } from './shelly.types.js';
+
+interface IShellySubscriptionOptions {
+  url: string;
+  deviceId: string;
+  source: string;
+  password?: string;
+  timeoutMs: number;
+  abortSignal: AbortSignal;
+  onStatus(statusArg: IShellyStatus, fullArg: boolean, timestampArg: number): void;
+  onEvent(eventArg: IShellyComponentEvent, timestampArg: number): void;
+  onAvailability(availableArg: boolean): void;
+  onError(errorArg: Error): void;
+}
+
+export class ShellySubscription {
+  private socket?: WebSocket;
+  private startPromise?: Promise<void>;
+  private resolveStart?: () => void;
+  private rejectStart?: (errorArg: Error) => void;
+  private closePromise?: Promise<void>;
+  private resolveClose?: () => void;
+  private deadline?: ReturnType<typeof setTimeout>;
+  private requestId = 1;
+  private authAttempted = false;
+  private healthy = false;
+  private closed = false;
+  private stopping = false;
+
+  constructor(private readonly options: IShellySubscriptionOptions) {}
+
+  public get isHealthy(): boolean { return this.healthy && !this.stopping; }
+  public get isClosed(): boolean { return this.closed; }
+  public get isStopping(): boolean { return this.stopping; }
+
+  public start(): Promise<void> {
+    if (this.startPromise) return this.startPromise;
+    if (this.options.abortSignal.aborted || this.stopping) return Promise.reject(new DOMException('Shelly subscription cancelled.', 'AbortError'));
+    this.startPromise = new Promise<void>((resolveArg, rejectArg) => {
+      this.resolveStart = resolveArg;
+      this.rejectStart = rejectArg;
+    });
+    this.closePromise = new Promise<void>((resolveArg) => { this.resolveClose = resolveArg; });
+    this.options.abortSignal.addEventListener('abort', this.handleAbort, { once: true });
+    this.deadline = setTimeout(() => this.fail(new DeviceCommunicationError('Shelly WebSocket handshake timed out.')), this.options.timeoutMs);
+    try {
+      this.socket = new WebSocket(this.options.url);
+      this.socket.addEventListener('open', this.handleOpen);
+      this.socket.addEventListener('message', this.handleMessage);
+      this.socket.addEventListener('error', this.handleError);
+      this.socket.addEventListener('close', this.handleClose);
+    } catch {
+      this.finishClose();
+      this.fail(new DeviceCommunicationError('Shelly WebSocket connection failed.'));
+    }
+    return this.startPromise;
+  }
+
+  public async stop(): Promise<void> {
+    this.stopping = true;
+    this.setHealthy(false);
+    this.clearDeadline();
+    this.rejectStart?.(new DOMException('Shelly subscription cancelled.', 'AbortError'));
+    this.resolveStart = undefined;
+    this.rejectStart = undefined;
+    if (!this.socket || this.closed) {
+      this.finishClose();
+      return;
+    }
+    if (this.socket.readyState < WebSocket.CLOSING) this.socket.close();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      // Native WebSocket owns its transport; a failed close remains owned and can be awaited again.
+      await Promise.race([
+        this.closePromise,
+        new Promise<never>((_, rejectArg) => {
+          timer = setTimeout(() => rejectArg(new DeviceCommunicationError('Shelly WebSocket close timed out.')), this.options.timeoutMs);
+        }),
+      ]);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  private readonly handleOpen = (): void => {
+    if (!this.stopping) this.sendHandshake();
+  };
+
+  private readonly handleMessage = (eventArg: MessageEvent<unknown>): void => {
+    if (this.stopping) return;
+    try {
+      if (typeof eventArg.data !== 'string' || eventArg.data.length > 1024 * 1024) {
+        throw new DeviceCommunicationError('Shelly returned an invalid WebSocket frame.');
+      }
+      const frame: unknown = JSON.parse(eventArg.data);
+      if (!isShellyRecord(frame) || frame.src !== this.options.deviceId || frame.dst !== this.options.source) {
+        throw new DeviceCommunicationError('Shelly WebSocket frame identity does not match the connected device.');
+      }
+      if (typeof frame.method === 'string') {
+        if (this.healthy) this.receiveNotification(frame);
+        return;
+      }
+      if (frame.id !== this.requestId || this.healthy) {
+        throw new DeviceCommunicationError('Shelly returned an unexpected WebSocket response.');
+      }
+      if (isShellyRecord(frame.error) && frame.error.code === 401 && !this.authAttempted) {
+        this.authenticate(frame.error);
+        return;
+      }
+      const status = parseShellyStatus(parseShellyRpcResult(frame, this.requestId, this.options.deviceId, this.options.source));
+      this.options.onStatus(status, true, Date.now());
+      this.clearDeadline();
+      this.setHealthy(true);
+      this.resolveStart?.();
+      this.resolveStart = undefined;
+      this.rejectStart = undefined;
+    } catch (errorArg) {
+      this.fail(errorArg instanceof AuthenticationError || errorArg instanceof DeviceCommunicationError ?
+        errorArg : new DeviceCommunicationError('Shelly returned an invalid WebSocket payload.'));
+    }
+  };
+
+  private authenticate(errorArg: Record<string, unknown>): void {
+    if (!this.options.password) throw new AuthenticationError('Shelly authentication requires a password.');
+    if (typeof errorArg.message !== 'string') throw new AuthenticationError('Shelly returned an unsupported authentication challenge.');
+    let challengeValue: unknown;
+    try { challengeValue = JSON.parse(errorArg.message); }
+    catch { throw new AuthenticationError('Shelly returned an unsupported authentication challenge.'); }
+    const challenge = parseShellyDigestChallenge(challengeValue, this.options.deviceId);
+    const digest = createShellyDigest(challenge, this.options.password, challenge.nc ?? 1, 'dummy_method', 'dummy_uri');
+    this.authAttempted = true;
+    this.requestId++;
+    this.sendHandshake({
+      realm: challenge.realm,
+      username: 'admin',
+      nonce: challenge.nonce,
+      algorithm: 'SHA-256',
+      ...digest,
+    });
+  }
+
+  private sendHandshake(authArg?: Record<string, unknown>): void {
+    this.socket?.send(JSON.stringify({ id: this.requestId, src: this.options.source, method: 'Shelly.GetStatus', auth: authArg }));
+  }
+
+  private receiveNotification(frameArg: Record<string, unknown>): void {
+    if (!['NotifyStatus', 'NotifyFullStatus', 'NotifyEvent'].includes(String(frameArg.method))) return;
+    if (!isShellyRecord(frameArg.params) || typeof frameArg.params.ts !== 'number' ||
+      !Number.isSafeInteger(Math.trunc(frameArg.params.ts * 1000)) || frameArg.params.ts < 0) {
+      throw new DeviceCommunicationError('Shelly returned an invalid notification.');
+    }
+    const { ts, ...params } = frameArg.params;
+    const timestamp = ts * 1000;
+    if (frameArg.method === 'NotifyEvent') {
+      for (const event of parseShellyEvents(params.events)) this.options.onEvent(event, (event.ts ?? ts) * 1000);
+    } else {
+      const full = frameArg.method === 'NotifyFullStatus';
+      this.options.onStatus(parseShellyStatus(params, !full), full, timestamp);
+    }
+  }
+
+  private readonly handleError = (): void => {
+    if (!this.stopping) this.fail(new DeviceCommunicationError('Shelly WebSocket connection failed.'));
+  };
+
+  private readonly handleClose = (): void => {
+    const unexpected = !this.stopping;
+    this.finishClose();
+    if (unexpected) this.fail(new DeviceCommunicationError('Shelly WebSocket connection closed.'));
+  };
+
+  private readonly handleAbort = (): void => {
+    void this.stop().catch(() => this.options.onError(new DeviceCommunicationError('Shelly WebSocket cleanup failed.')));
+  };
+
+  private fail(errorArg: Error): void {
+    this.setHealthy(false);
+    this.clearDeadline();
+    this.rejectStart?.(errorArg);
+    this.resolveStart = undefined;
+    this.rejectStart = undefined;
+    this.options.onError(errorArg);
+    if (!this.stopping) void this.stop().catch(() => this.options.onError(new DeviceCommunicationError('Shelly WebSocket cleanup failed.')));
+  }
+
+  private setHealthy(healthyArg: boolean): void {
+    if (this.healthy === healthyArg) return;
+    this.healthy = healthyArg;
+    this.options.onAvailability(healthyArg);
+  }
+
+  private clearDeadline(): void {
+    clearTimeout(this.deadline);
+    this.deadline = undefined;
+  }
+
+  private finishClose(): void {
+    this.closed = true;
+    this.clearDeadline();
+    this.setHealthy(false);
+    this.options.abortSignal.removeEventListener('abort', this.handleAbort);
+    this.socket?.removeEventListener('open', this.handleOpen);
+    this.socket?.removeEventListener('message', this.handleMessage);
+    this.socket?.removeEventListener('error', this.handleError);
+    this.socket?.removeEventListener('close', this.handleClose);
+    this.resolveClose?.();
+    this.resolveClose = undefined;
+  }
+}

package/ts/integrations/shelly/shelly.discovery.ts

@@ -9,8 +9,10 @@ export class ShellyMdnsMatcher implements IDiscoveryMatcher<IShellyMdnsRecord> {
 
   public async matches(recordArg: IShellyMdnsRecord): Promise<IDiscoveryMatch> {
     const name = recordArg.name?.toLowerCase() || '';
-    const type = recordArg.type?.toLowerCase() || '';
-    const matched = name.startsWith('shelly') || type === '_shelly._tcp.local.' || type === '_http._tcp.local.' && name.startsWith('shelly');
+    const type = recordArg.type?.toLowerCase().replace(/\.$/, '').replace(/\.local$/, '') || '';
+    const generation = recordArg.txt?.gen;
+    const supportedGeneration = generation === undefined || generation === '2' || generation === '3';
+    const matched = supportedGeneration && (type === '_shelly._tcp' || type === '_http._tcp' && name.startsWith('shelly'));
     if (!matched) {
       return {
         matched: false,
@@ -36,6 +38,7 @@ export class ShellyMdnsMatcher implements IDiscoveryMatcher<IShellyMdnsRecord> {
           mdnsName: recordArg.name,
           mdnsType: recordArg.type,
           txt: recordArg.txt,
+          generation,
         },
       },
     };

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

@@ -0,0 +1,190 @@
+import * as plugins from '../../plugins.js';
+import { AuthenticationError, DeviceCommunicationError } from '../../core/errors.js';
+import type { IShellyComponentEvent, IShellyDeviceConfig, IShellyDeviceInfo, IShellyStatus } from './shelly.types.js';
+
+export const isShellyRecord = (valueArg: unknown): valueArg is Record<string, unknown> =>
+  typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+
+function invalidPayload(): never {
+  throw new DeviceCommunicationError('Shelly returned an invalid RPC payload.');
+}
+
+const validateJson = (valueArg: unknown, depthArg = 0): void => {
+  if (depthArg > 32) invalidPayload();
+  if (valueArg === null || typeof valueArg === 'string' || typeof valueArg === 'boolean') return;
+  if (typeof valueArg === 'number' && Number.isFinite(valueArg)) return;
+  if (Array.isArray(valueArg)) {
+    valueArg.forEach((itemArg: unknown) => validateJson(itemArg, depthArg + 1));
+    return;
+  }
+  if (!isShellyRecord(valueArg)) invalidPayload();
+  for (const [key, value] of Object.entries(valueArg)) {
+    if (['__proto__', 'constructor', 'prototype'].includes(key)) invalidPayload();
+    validateJson(value, depthArg + 1);
+  }
+};
+
+export const parseShellyDeviceInfo = (valueArg: unknown): IShellyDeviceInfo => {
+  if (!isShellyRecord(valueArg) || typeof valueArg.id !== 'string' || !/^shelly[\w-]+$/i.test(valueArg.id)) invalidPayload();
+  if (valueArg.gen !== 2 && valueArg.gen !== 3) {
+    throw new DeviceCommunicationError('Shelly integration supports generation 2 and 3 devices.');
+  }
+  for (const key of ['mac', 'model', 'ver', 'fw_id', 'app', 'profile']) {
+    if (valueArg[key] !== undefined && typeof valueArg[key] !== 'string') invalidPayload();
+  }
+  if (valueArg.auth_en !== undefined && typeof valueArg.auth_en !== 'boolean') invalidPayload();
+  if (valueArg.auth !== undefined && typeof valueArg.auth !== 'boolean') invalidPayload();
+  if (valueArg.auth_domain !== undefined && valueArg.auth_domain !== null && typeof valueArg.auth_domain !== 'string') invalidPayload();
+  validateJson(valueArg);
+  return structuredClone(valueArg) as IShellyDeviceInfo;
+};
+
+export const parseShellyStatus = (valueArg: unknown, partialArg = false): IShellyStatus => {
+  if (!isShellyRecord(valueArg)) invalidPayload();
+  validateJson(valueArg);
+  for (const [key, component] of Object.entries(valueArg)) {
+    if (!/^[a-z][a-z\d_]*(?::\d+)?$/.test(key)) invalidPayload();
+    if (partialArg && component === null) continue;
+    if (!isShellyRecord(component)) invalidPayload();
+    if (key === 'sys') {
+      if (component.mac !== undefined && typeof component.mac !== 'string' ||
+        component.uptime !== undefined && typeof component.uptime !== 'number') invalidPayload();
+    }
+    if (key === 'wifi' || key === 'eth') {
+      for (const field of key === 'wifi' ? ['sta_ip', 'status', 'ssid'] : ['ip']) {
+        if (component[field] !== undefined && component[field] !== null && typeof component[field] !== 'string') invalidPayload();
+      }
+      if (key === 'wifi' && component.rssi !== undefined && typeof component.rssi !== 'number') invalidPayload();
+    }
+    const match = /^switch:(\d+)$/.exec(key);
+    if (!match) continue;
+    if ((!partialArg || component.id !== undefined) && component.id !== Number(match[1])) invalidPayload();
+    if ((!partialArg || component.output !== undefined) && typeof component.output !== 'boolean') invalidPayload();
+    for (const field of ['apower', 'voltage', 'current', 'freq', 'pf']) {
+      if (component[field] !== undefined && component[field] !== null && typeof component[field] !== 'number') invalidPayload();
+    }
+    if (component.source !== undefined && typeof component.source !== 'string') invalidPayload();
+    if (component.errors !== undefined && component.errors !== null &&
+      (!Array.isArray(component.errors) || !component.errors.every((itemArg: unknown) => typeof itemArg === 'string'))) invalidPayload();
+    for (const field of ['aenergy', 'ret_aenergy', 'temperature']) {
+      const nested = component[field];
+      if (nested === undefined || nested === null) continue;
+      if (!isShellyRecord(nested)) invalidPayload();
+      for (const numberField of field === 'temperature' ? ['tC', 'tF'] : ['total']) {
+        if (nested[numberField] !== undefined && nested[numberField] !== null && typeof nested[numberField] !== 'number') invalidPayload();
+      }
+    }
+  }
+  return structuredClone(valueArg) as IShellyStatus;
+};
+
+export const parseShellyConfig = (valueArg: unknown): IShellyDeviceConfig => {
+  if (!isShellyRecord(valueArg)) invalidPayload();
+  validateJson(valueArg);
+  for (const component of Object.values(valueArg)) {
+    if (!isShellyRecord(component)) invalidPayload();
+    if (component.name !== undefined && component.name !== null && typeof component.name !== 'string') invalidPayload();
+  }
+  if (valueArg.sys !== undefined) {
+    if (!isShellyRecord(valueArg.sys)) invalidPayload();
+    const device = valueArg.sys.device;
+    if (device !== undefined && (!isShellyRecord(device) ||
+      device.name !== undefined && device.name !== null && typeof device.name !== 'string')) invalidPayload();
+    if (isShellyRecord(device)) {
+      for (const field of ['mac', 'fw_id']) {
+        if (device[field] !== undefined && typeof device[field] !== 'string') invalidPayload();
+      }
+    }
+  }
+  return structuredClone(valueArg) as IShellyDeviceConfig;
+};
+
+export const parseShellyEvents = (valueArg: unknown): IShellyComponentEvent[] => {
+  if (!Array.isArray(valueArg)) invalidPayload();
+  validateJson(valueArg);
+  return valueArg.map((eventArg: unknown) => {
+    if (!isShellyRecord(eventArg) || typeof eventArg.component !== 'string' ||
+      !/^[a-z][a-z\d_]*(?::\d+)?$/.test(eventArg.component) || typeof eventArg.event !== 'string' || !eventArg.event) invalidPayload();
+    if (eventArg.id !== undefined && (!Number.isSafeInteger(eventArg.id) || Number(eventArg.id) < 0)) invalidPayload();
+    if (eventArg.ts !== undefined && (typeof eventArg.ts !== 'number' || !Number.isSafeInteger(Math.trunc(eventArg.ts * 1000)) || eventArg.ts < 0)) invalidPayload();
+    const componentId = /:(\d+)$/.exec(eventArg.component);
+    if (eventArg.id !== undefined && componentId && eventArg.id !== Number(componentId[1])) invalidPayload();
+    return structuredClone(eventArg) as IShellyComponentEvent;
+  });
+};
+
+export const mergeShellyStatus = (statusArg: IShellyStatus, patchArg: IShellyStatus): IShellyStatus => {
+  const merge = (previousArg: Record<string, unknown>, changesArg: Record<string, unknown>): Record<string, unknown> => {
+    const result = structuredClone(previousArg);
+    for (const [key, value] of Object.entries(changesArg)) {
+      if (value === null) delete result[key];
+      else result[key] = isShellyRecord(value) && isShellyRecord(result[key]) ? merge(result[key], value) : structuredClone(value);
+    }
+    return result;
+  };
+  return parseShellyStatus(merge(statusArg, patchArg));
+};
+
+export interface IShellyDigestChallenge {
+  realm: string;
+  nonce: string | number;
+  nc?: number;
+  opaque?: string;
+}
+
+export const parseShellyDigestChallenge = (valueArg: unknown, deviceIdArg?: string): IShellyDigestChallenge => {
+  if (!isShellyRecord(valueArg) || valueArg.algorithm !== 'SHA-256' || typeof valueArg.realm !== 'string' ||
+    !/^shelly[\w-]+$/i.test(valueArg.realm) || deviceIdArg !== undefined && valueArg.realm !== deviceIdArg ||
+    !(typeof valueArg.nonce === 'string' && /^[\w+/=-]+$/.test(valueArg.nonce) ||
+      typeof valueArg.nonce === 'number' && Number.isSafeInteger(valueArg.nonce) && valueArg.nonce >= 0) ||
+    valueArg.nc !== undefined && (!Number.isSafeInteger(valueArg.nc) || Number(valueArg.nc) < 1) ||
+    valueArg.opaque !== undefined && (typeof valueArg.opaque !== 'string' || !/^[\w+/=-]+$/.test(valueArg.opaque))) {
+    throw new AuthenticationError('Shelly returned an unsupported authentication challenge.');
+  }
+  return {
+    realm: valueArg.realm,
+    nonce: valueArg.nonce,
+    nc: valueArg.nc as number | undefined,
+    opaque: valueArg.opaque as string | undefined,
+  };
+};
+
+export const parseShellyHttpChallenge = (headerArg: string | null, deviceIdArg?: string): IShellyDigestChallenge => {
+  if (!headerArg?.startsWith('Digest ')) throw new AuthenticationError('Shelly returned an unsupported authentication challenge.');
+  const values: Record<string, string> = {};
+  const regex = /(\w+)=(?:"([^"]*)"|([^,\s]+))/g;
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(headerArg))) values[match[1]] = match[2] ?? match[3];
+  if (values.qop !== 'auth') throw new AuthenticationError('Shelly requires unsupported digest protection.');
+  return parseShellyDigestChallenge(values, deviceIdArg);
+};
+
+export const createShellyDigest = (
+  challengeArg: IShellyDigestChallenge,
+  passwordArg: string,
+  countArg: number,
+  methodArg: string,
+  uriArg: string
+): { response: string; cnonce: number; nc: string | number } => {
+  const sha256 = (inputArg: string): string => plugins.crypto.createHash('sha256').update(inputArg).digest('hex');
+  const cnonce = plugins.crypto.randomInt(1, 0x7fffffff);
+  // Firmware before 2.0 uses numeric counters in RPC auth; HTTP always uses RFC 7616 hex counters.
+  const nc = typeof challengeArg.nonce === 'number' && methodArg === 'dummy_method' ? countArg : countArg.toString(16).padStart(8, '0');
+  const ha1 = sha256(`admin:${challengeArg.realm}:${passwordArg}`);
+  const ha2 = sha256(`${methodArg}:${uriArg}`);
+  return { response: sha256(`${ha1}:${challengeArg.nonce}:${nc}:${cnonce}:auth:${ha2}`), cnonce, nc };
+};
+
+export const parseShellyRpcResult = (frameArg: unknown, idArg: number, deviceIdArg?: string, sourceArg?: string): Record<string, unknown> => {
+  if (!isShellyRecord(frameArg) || frameArg.id !== idArg || typeof frameArg.src !== 'string' ||
+    deviceIdArg !== undefined && frameArg.src !== deviceIdArg ||
+    frameArg.dst !== undefined && frameArg.dst !== sourceArg ||
+    ('result' in frameArg) === ('error' in frameArg)) invalidPayload();
+  if ('error' in frameArg) {
+    if (!isShellyRecord(frameArg.error) || typeof frameArg.error.code !== 'number' || !Number.isSafeInteger(frameArg.error.code)) invalidPayload();
+    if (frameArg.error.code === 401) throw new AuthenticationError('Shelly authentication failed.');
+    throw new DeviceCommunicationError(`Shelly RPC failed with code ${frameArg.error.code}.`);
+  }
+  if (!isShellyRecord(frameArg.result)) invalidPayload();
+  return frameArg.result;
+};

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

@@ -1,14 +1,12 @@
 export type TShellyProtocol = 'http' | 'https';
 
 export interface IShellyConfig {
-  host?: string;
+  host: string;
   port?: number;
   protocol?: TShellyProtocol;
   username?: string;
   password?: string;
-  deviceInfo?: IShellyDeviceInfo;
-  status?: IShellyStatus;
-  deviceConfig?: IShellyDeviceConfig;
+  requestTimeoutMs?: number;
 }
 
 export interface IShellyDeviceInfo {
@@ -85,6 +83,20 @@ export interface IShellySnapshot {
   deviceConfig?: IShellyDeviceConfig;
 }
 
+export interface IShellyComponentEvent {
+  component: string;
+  event: string;
+  id?: number;
+  ts?: number;
+  [key: string]: unknown;
+}
+
+export type TShellyClientEvent =
+  | { type: 'status'; snapshot: IShellySnapshot; timestamp: number }
+  | { type: 'event'; event: IShellyComponentEvent; timestamp: number }
+  | { type: 'availability'; available: boolean; timestamp: number }
+  | { type: 'error'; error: Error; timestamp: number };
+
 export interface IShellyMdnsRecord {
   name?: string;
   type?: string;

package/ts/integrations/sonos/index.ts

@@ -4,3 +4,6 @@ export * from './sonos.classes.configflow.js';
 export * from './sonos.discovery.js';
 export * from './sonos.mapper.js';
 export * from './sonos.types.js';
+export * from './sonos.config.js';
+export * from './sonos.topology.js';
+export * from './sonos.classes.ssdpprobe.js';