@smarthome.exchange/integrations 0.2.0 → 1.0.0

package/ts/integrations/samsungtv/samsungtv.validation.ts

@@ -0,0 +1,84 @@
+import type { ISamsungtvConfig } from './samsungtv.types.js';
+
+export const samsungtvObject = (valueArg: unknown, nameArg: string): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(valueArg))) {
+    throw new TypeError(`${nameArg} must be a plain object.`);
+  }
+  const result: Record<string, unknown> = Object.create(null);
+  for (const key of Reflect.ownKeys(valueArg)) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    if (typeof key !== 'string' || !descriptor || !('value' in descriptor) || !descriptor.enumerable) {
+      throw new TypeError(`${nameArg} must contain only enumerable data fields.`);
+    }
+    result[key] = descriptor.value;
+  }
+  return result;
+};
+
+export const samsungtvKeys = (valueArg: Record<string, unknown>, allowedArg: readonly string[]): void => {
+  if (Object.keys(valueArg).some((keyArg) => !allowedArg.includes(keyArg))) {
+    throw new TypeError('Samsung TV arguments contain unsupported fields.');
+  }
+};
+
+export const samsungtvString = (valueArg: unknown, nameArg: string, maximumArg = 256): string => {
+  if (typeof valueArg !== 'string' || !valueArg.length || valueArg.length > maximumArg || /[\p{Cc}\p{Cs}]/u.test(valueArg)) {
+    throw new TypeError(`${nameArg} must be a nonempty bounded string without control characters.`);
+  }
+  return valueArg;
+};
+
+export const samsungtvDeviceId = (valueArg: unknown): string => {
+  if (typeof valueArg !== 'string' || !/^(?:uuid:)?[a-f\d]{8}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{12}$/i.test(valueArg)) {
+    throw new TypeError('Samsung TV expectedDeviceId must be the exact TV UUID.');
+  }
+  return valueArg.replace(/^uuid:/i, '').toLowerCase();
+};
+
+const integer = (valueArg: unknown, nameArg: string, minimumArg: number, maximumArg: number): number => {
+  if (typeof valueArg !== 'number' || !Number.isSafeInteger(valueArg) || valueArg < minimumArg || valueArg > maximumArg) {
+    throw new TypeError(`${nameArg} must be an integer from ${minimumArg} through ${maximumArg}.`);
+  }
+  return valueArg;
+};
+
+export const samsungtvOrigin = (valueArg: unknown, protocolsArg: readonly string[]): string => {
+  const value = samsungtvString(valueArg, 'Samsung TV origin', 2048);
+  let origin: URL;
+  try { origin = new URL(value); } catch { throw new TypeError('Samsung TV endpoint must be an explicit origin.'); }
+  if (!protocolsArg.includes(origin.protocol) || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash) {
+    throw new TypeError('Samsung TV origin has an unsupported protocol, credentials, path, query or fragment.');
+  }
+  return origin.origin;
+};
+
+export const normalizeSamsungtvConfig = (configArg: unknown): Readonly<ISamsungtvConfig> => {
+  const value = samsungtvObject(configArg, 'Samsung TV config');
+  samsungtvKeys(value, ['homeId', 'httpOrigin', 'websocketOrigin', 'expectedDeviceId', 'pairingMode', 'name',
+    'certificateAuthority', 'allowUnencryptedLocalDiscovery', 'timeoutMs', 'maxResponseBytes']);
+  const httpOrigin = samsungtvOrigin(value.httpOrigin, ['http:', 'https:']);
+  const websocketOrigin = samsungtvOrigin(value.websocketOrigin, ['wss:']);
+  if (new URL(httpOrigin).hostname !== new URL(websocketOrigin).hostname) {
+    throw new TypeError('Samsung TV REST and WSS origins must identify the same host.');
+  }
+  if (value.pairingMode !== 'existing' && value.pairingMode !== 'prompt') throw new TypeError('Samsung TV pairingMode must be existing or prompt.');
+  if (value.allowUnencryptedLocalDiscovery !== undefined && typeof value.allowUnencryptedLocalDiscovery !== 'boolean') {
+    throw new TypeError('allowUnencryptedLocalDiscovery must be boolean.');
+  }
+  if (new URL(httpOrigin).protocol === 'http:' && value.allowUnencryptedLocalDiscovery !== true) {
+    throw new TypeError('Samsung TV HTTP discovery requires explicit allowUnencryptedLocalDiscovery: true.');
+  }
+  if (value.certificateAuthority !== undefined && (typeof value.certificateAuthority !== 'string' || value.certificateAuthority.length > 524288 || !value.certificateAuthority.includes('-----BEGIN CERTIFICATE-----'))) {
+    throw new TypeError('Samsung TV certificateAuthority must be a PEM certificate chain.');
+  }
+  return Object.freeze({
+    homeId: samsungtvString(value.homeId, 'homeId'), httpOrigin, websocketOrigin,
+    expectedDeviceId: samsungtvDeviceId(value.expectedDeviceId), pairingMode: value.pairingMode,
+    name: value.name === undefined ? undefined : samsungtvString(value.name, 'name', 128),
+    certificateAuthority: typeof value.certificateAuthority === 'string' ? value.certificateAuthority : undefined,
+    allowUnencryptedLocalDiscovery: value.allowUnencryptedLocalDiscovery,
+    timeoutMs: integer(value.timeoutMs ?? 10000, 'timeoutMs', 1, 120000),
+    maxResponseBytes: integer(value.maxResponseBytes ?? 65536, 'maxResponseBytes', 256, 1048576),
+  });
+};

package/ts/integrations/shelly/readme.md

@@ -0,0 +1,34 @@
+# 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.
+
+```typescript
+const integration = new ShellyIntegration();
+const runtime = await integration.setup({
+  host: '192.168.1.20',
+  password: devicePassword,
+  requestTimeoutMs: 10000,
+}, {});
+
+const [device] = await runtime.devices();
+const output = device.features.find((feature) => feature.id === 'switch_0_output');
+if (output) {
+  await runtime.writeFeature?.({ device, feature: output, value: true });
+}
+
+const unsubscribe = await runtime.subscribe?.((event) => handleIntegrationEvent(event));
+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.
+
+`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.
+
+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.
+
+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.
+
+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/).

package/ts/integrations/shelly/shelly.classes.client.ts

@@ -1,185 +1,323 @@
 import * as plugins from '../../plugins.js';
-import type { IShellyConfig, IShellyDeviceConfig, IShellyDeviceInfo, IShellySnapshot, IShellyStatus } from './shelly.types.js';
+import { AuthenticationError, DeviceCommunicationError } from '../../core/errors.js';
+import type { ILogger } from '../../core/types.js';
+import { ShellySubscription } from './shelly.classes.subscription.js';
+import {
+  createShellyDigest,
+  isShellyRecord,
+  mergeShellyStatus,
+  parseShellyConfig,
+  parseShellyDeviceInfo,
+  parseShellyHttpChallenge,
+  parseShellyRpcResult,
+  parseShellyStatus,
+} from './shelly.rpc.js';
+import type { IShellyDigestChallenge } from './shelly.rpc.js';
+import type { IShellyConfig, IShellyDeviceConfig, IShellyDeviceInfo, IShellySnapshot, IShellyStatus, TShellyClientEvent } from './shelly.types.js';
 
-interface IShellyDigestChallenge {
-  realm: string;
-  nonce: string;
-  qop?: string;
-  opaque?: string;
+interface IShellySubscriber {
+  handler(eventArg: TShellyClientEvent): void;
+  signal?: AbortSignal;
+  abort(): void;
 }
 
 export class ShellyClient {
   private requestId = 1;
   private nonceCount = 0;
   private digestChallenge?: IShellyDigestChallenge;
+  private deviceId?: string;
+  private snapshot?: IShellySnapshot;
+  private subscription?: ShellySubscription;
+  private readonly subscribers = new Set<IShellySubscriber>();
+  private readonly lifetime = new AbortController();
+  private readonly lifetimeSignal: AbortSignal;
+  // Firmware tracks increasing digest nonce counts, so HTTP calls must arrive in order.
+  private requestQueue: Promise<void> = Promise.resolve();
+  private readonly timeoutMs: number;
+  private readonly endpoint: URL;
+  private readonly config: IShellyConfig;
+  private healthy = false;
+  private destroyed = false;
 
-  constructor(private readonly config: IShellyConfig) {}
-
-  public async getSnapshot(): Promise<IShellySnapshot> {
-    const deviceInfo = await this.getDeviceInfo();
-    const status = await this.getStatus();
-    const deviceConfig = await this.getDeviceConfig();
-    return { deviceInfo, status, deviceConfig };
-  }
-
-  public async getDeviceInfo(): Promise<IShellyDeviceInfo> {
-    if (this.config.deviceInfo) {
-      return this.config.deviceInfo;
+  constructor(configArg: IShellyConfig, abortSignalArg?: AbortSignal, private readonly logger?: ILogger) {
+    const config: IShellyConfig = {
+      host: configArg.host,
+      port: configArg.port,
+      protocol: configArg.protocol,
+      username: configArg.username,
+      password: configArg.password,
+      requestTimeoutMs: configArg.requestTimeoutMs,
+    };
+    this.config = config;
+    this.timeoutMs = config.requestTimeoutMs ?? 10000;
+    if (!Number.isSafeInteger(this.timeoutMs) || this.timeoutMs < 10 || this.timeoutMs > 60000) {
+      throw new Error('Shelly requestTimeoutMs must be an integer between 10 and 60000.');
     }
-    return this.requestJson<IShellyDeviceInfo>('/shelly');
+    if (config.username !== undefined && config.username !== 'admin') throw new AuthenticationError('Shelly authentication username must be admin.');
+    if (config.password !== undefined && typeof config.password !== 'string') throw new AuthenticationError('Shelly password must be a string.');
+    if (config.protocol !== undefined && config.protocol !== 'http' && config.protocol !== 'https') throw new Error('Shelly protocol must be http or https.');
+    if (config.port !== undefined && (!Number.isSafeInteger(config.port) || config.port < 1 || config.port > 65535)) throw new Error('Shelly port must be between 1 and 65535.');
+    if (config.host === undefined) throw new Error('Shelly host is required for live requests.');
+    if (typeof config.host !== 'string' || !config.host || /[\s\/?#@]/.test(config.host)) throw new Error('Shelly host must be a hostname or IP address.');
+    const host = config.host.includes(':') && !config.host.startsWith('[') ? `[${config.host}]` : config.host;
+    try { this.endpoint = new URL(`${config.protocol ?? 'http'}://${host}${config.port === undefined ? '' : `:${config.port}`}`); }
+    catch { throw new Error('Shelly host must be a hostname or IP address.'); }
+    this.lifetimeSignal = AbortSignal.any([this.lifetime.signal, ...(abortSignalArg ? [abortSignalArg] : [])]);
   }
 
-  public async getStatus(): Promise<IShellyStatus> {
-    if (this.config.status) {
-      return this.config.status;
-    }
-    return this.callRpc<IShellyStatus>('Shelly.GetStatus');
+  public isHealthy(): boolean {
+    return !this.destroyed && !this.lifetimeSignal.aborted && this.healthy && (!this.subscription || this.subscription.isHealthy);
   }
 
-  public async getDeviceConfig(): Promise<IShellyDeviceConfig | undefined> {
-    if (this.config.deviceConfig) {
-      return this.config.deviceConfig;
-    }
-    if (!this.config.host) {
-      return undefined;
-    }
-    return this.callRpc<IShellyDeviceConfig>('Shelly.GetConfig');
+  public async getSnapshot(abortSignalArg?: AbortSignal): Promise<IShellySnapshot> {
+    this.assertActive(abortSignalArg);
+    if (this.snapshot && this.subscription?.isHealthy) return structuredClone(this.snapshot);
+    const deviceInfo = await this.getDeviceInfo(abortSignalArg);
+    const status = await this.getStatus(abortSignalArg);
+    const deviceConfig = await this.getDeviceConfig(abortSignalArg);
+    this.snapshot = { deviceInfo, status, deviceConfig };
+    return structuredClone(this.snapshot);
   }
 
-  public async setSwitchOutput(switchIdArg: number, onArg: boolean): Promise<void> {
-    await this.callRpc('Switch.Set', {
-      id: switchIdArg,
-      on: onArg,
+  public async getDeviceInfo(abortSignalArg?: AbortSignal): Promise<IShellyDeviceInfo> {
+    this.assertActive(abortSignalArg);
+    const response = await this.requestJson('/shelly', undefined, abortSignalArg);
+    const deviceInfo = this.parseResponse(() => {
+      const info = parseShellyDeviceInfo(response);
+      if (this.deviceId !== undefined && this.deviceId !== info.id) throw new DeviceCommunicationError('Shelly endpoint device identity changed.');
+      return info;
     });
+    this.deviceId = deviceInfo.id;
+    return deviceInfo;
   }
 
-  public async destroy(): Promise<void> {}
+  public async getStatus(abortSignalArg?: AbortSignal): Promise<IShellyStatus> {
+    this.assertActive(abortSignalArg);
+    const response = await this.callRpc('Shelly.GetStatus', undefined, abortSignalArg);
+    const status = this.parseResponse(() => parseShellyStatus(response));
+    this.healthy = true;
+    if (this.snapshot) this.updateStatus(status, true, Date.now());
+    return status;
+  }
 
-  private async callRpc<TResult>(methodArg: string, paramsArg?: Record<string, unknown>): Promise<TResult> {
-    const response = await this.requestJson<unknown>('/rpc', {
-      id: this.requestId++,
-      method: methodArg,
-      params: paramsArg,
-    });
-    if (this.isRecord(response) && 'error' in response) {
-      const error = response.error;
-      throw new Error(`Shelly RPC ${methodArg} failed: ${JSON.stringify(error)}`);
-    }
-    if (this.isRecord(response) && 'result' in response) {
-      return response.result as TResult;
-    }
-    if (this.isRecord(response) && 'params' in response) {
-      return response.params as TResult;
-    }
-    return response as TResult;
+  public async getDeviceConfig(abortSignalArg?: AbortSignal): Promise<IShellyDeviceConfig> {
+    this.assertActive(abortSignalArg);
+    const response = await this.callRpc('Shelly.GetConfig', undefined, abortSignalArg);
+    return this.parseResponse(() => parseShellyConfig(response));
   }
 
-  private async requestJson<TResult>(pathArg: string, bodyArg?: Record<string, unknown>): Promise<TResult> {
-    if (!this.config.host) {
-      throw new Error('Shelly host is required when fixture data is not provided.');
-    }
+  public async setSwitchOutput(switchIdArg: number, onArg: boolean, abortSignalArg?: AbortSignal): Promise<void> {
+    if (!Number.isSafeInteger(switchIdArg) || switchIdArg < 0 || typeof onArg !== 'boolean') throw new Error('Shelly switch writes require a non-negative integer id and boolean output.');
+    const snapshot = await this.getSnapshot(abortSignalArg);
+    if (!isShellyRecord(snapshot.status[`switch:${switchIdArg}`])) throw new Error('Shelly switch is not present on the connected device.');
+    const result = await this.callRpc('Switch.Set', { id: switchIdArg, on: onArg }, abortSignalArg);
+    this.parseResponse(() => {
+      if (typeof result.was_on !== 'boolean') throw new DeviceCommunicationError('Shelly returned an invalid switch response.');
+    });
+    await this.getStatus(abortSignalArg);
+  }
 
-    const method = bodyArg ? 'POST' : 'GET';
-    const firstResponse = await this.fetchPath(pathArg, method, bodyArg);
-    if (firstResponse.status !== 401) {
-      return this.parseJsonResponse<TResult>(firstResponse, pathArg);
+  public async subscribe(handlerArg: (eventArg: TShellyClientEvent) => void, abortSignalArg?: AbortSignal): Promise<() => Promise<void>> {
+    this.assertActive(abortSignalArg);
+    if (!this.snapshot) await this.getSnapshot(abortSignalArg);
+    let rejectCancelled: ((errorArg: Error) => void) | undefined;
+    const cancellation = new Promise<never>((_, rejectArg) => { rejectCancelled = rejectArg; });
+    const subscriber: IShellySubscriber = {
+      handler: handlerArg,
+      signal: abortSignalArg,
+      abort: () => {
+        rejectCancelled?.(new DOMException('Shelly subscription cancelled.', 'AbortError'));
+        void unsubscribe().catch(() => {
+          this.logger?.log('error', 'Shelly subscription cleanup failed.');
+          this.emit({ type: 'error', error: new DeviceCommunicationError('Shelly subscription cleanup failed.'), timestamp: Date.now() });
+        });
+      },
+    };
+    let removed = false;
+    const unsubscribe = async (): Promise<void> => {
+      if (!removed) {
+        removed = true;
+        subscriber.signal?.removeEventListener('abort', subscriber.abort);
+        this.subscribers.delete(subscriber);
+      }
+      if (this.subscribers.size === 0 && this.subscription) {
+        const subscription = this.subscription;
+        await subscription.stop();
+        if (this.subscription === subscription) this.subscription = undefined;
+      }
+    };
+    this.subscribers.add(subscriber);
+    abortSignalArg?.addEventListener('abort', subscriber.abort, { once: true });
+    if (abortSignalArg?.aborted) subscriber.abort();
+    try {
+      await Promise.race([this.connectSubscription(), cancellation]);
+      this.assertActive(abortSignalArg);
+      rejectCancelled = undefined;
+      return unsubscribe;
+    } catch (errorArg) {
+      await unsubscribe();
+      throw errorArg;
     }
+  }
 
-    if (!this.config.password) {
-      throw new Error('Shelly device requires authentication, but no password was provided.');
+  public async destroy(): Promise<void> {
+    this.destroyed = true;
+    this.healthy = false;
+    for (const subscriber of this.subscribers) subscriber.signal?.removeEventListener('abort', subscriber.abort);
+    this.subscribers.clear();
+    this.lifetime.abort();
+    await this.requestQueue;
+    if (this.subscription) {
+      await this.subscription.stop();
+      this.subscription = undefined;
     }
-
-    this.digestChallenge = this.parseDigestChallenge(firstResponse.headers.get('www-authenticate'));
-    this.nonceCount = 0;
-
-    const secondResponse = await this.fetchPath(pathArg, method, bodyArg);
-    return this.parseJsonResponse<TResult>(secondResponse, pathArg);
   }
 
-  private async fetchPath(pathArg: string, methodArg: string, bodyArg?: Record<string, unknown>): Promise<Response> {
-    const headers: Record<string, string> = {};
-    if (bodyArg) {
-      headers['content-type'] = 'application/json';
+  private async connectSubscription(): Promise<void> {
+    if (this.subscription?.isStopping) {
+      const previous = this.subscription;
+      await previous.stop();
+      if (this.subscription === previous) this.subscription = undefined;
     }
-    if (this.digestChallenge) {
-      headers.authorization = this.createDigestAuthorization(methodArg, pathArg);
+    this.assertActive();
+    if (!this.subscription || this.subscription.isClosed) {
+      if (!this.deviceId) throw new Error('Shelly subscription requires a validated device.');
+      const url = new URL('/rpc', this.endpoint);
+      url.protocol = this.endpoint.protocol === 'https:' ? 'wss:' : 'ws:';
+      this.subscription = new ShellySubscription({
+        url: url.toString(),
+        deviceId: this.deviceId,
+        source: `shx-${plugins.crypto.randomUUID()}`,
+        password: this.config.password,
+        timeoutMs: this.timeoutMs,
+        abortSignal: this.lifetimeSignal,
+        onStatus: (statusArg, fullArg, timestampArg) => this.updateStatus(statusArg, fullArg, timestampArg),
+        onEvent: (eventArg, timestampArg) => {
+          this.emit({ type: 'event', event: eventArg, timestamp: timestampArg });
+          if (eventArg.event === 'config_changed') void this.refreshConfig(timestampArg);
+        },
+        onAvailability: (availableArg) => this.emit({ type: 'availability', available: availableArg, timestamp: Date.now() }),
+        onError: (errorArg) => this.emit({ type: 'error', error: errorArg, timestamp: Date.now() }),
+      });
     }
+    await this.subscription.start();
+  }
 
-    return globalThis.fetch(`${this.baseUrl()}${pathArg}`, {
-      method: methodArg,
-      headers,
-      body: bodyArg ? JSON.stringify(bodyArg) : undefined,
-    });
+  private updateStatus(statusArg: IShellyStatus, fullArg: boolean, timestampArg: number): void {
+    if (!this.snapshot || this.destroyed) return;
+    this.snapshot = { ...this.snapshot, status: fullArg ? statusArg : mergeShellyStatus(this.snapshot.status, statusArg) };
+    this.emit({ type: 'status', snapshot: structuredClone(this.snapshot), timestamp: timestampArg });
   }
 
-  private async parseJsonResponse<TResult>(responseArg: Response, pathArg: string): Promise<TResult> {
-    if (!responseArg.ok) {
-      const text = await responseArg.text();
-      throw new Error(`Shelly request ${pathArg} failed with HTTP ${responseArg.status}: ${text}`);
+  private emit(eventArg: TShellyClientEvent): void {
+    for (const subscriber of [...this.subscribers]) {
+      if (!this.subscribers.has(subscriber)) continue;
+      try { subscriber.handler(structuredClone(eventArg)); }
+      catch {
+        this.logger?.log('error', 'Shelly subscriber callback failed.');
+        subscriber.abort();
+        this.emit({ type: 'error', error: new DeviceCommunicationError('Shelly subscriber callback failed.'), timestamp: Date.now() });
+      }
     }
-    return responseArg.json() as Promise<TResult>;
   }
 
-  private parseDigestChallenge(headerArg: string | null): IShellyDigestChallenge {
-    if (!headerArg) {
-      throw new Error('Shelly authentication challenge did not include a WWW-Authenticate header.');
-    }
-    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.realm || !values.nonce) {
-      throw new Error(`Unsupported Shelly authentication challenge: ${headerArg}`);
+  private async refreshConfig(timestampArg: number): Promise<void> {
+    try {
+      const deviceConfig = await this.getDeviceConfig();
+      if (this.snapshot && !this.destroyed) {
+        this.snapshot = { ...this.snapshot, deviceConfig };
+        this.emit({ type: 'status', snapshot: structuredClone(this.snapshot), timestamp: timestampArg });
+      }
+    } catch {
+      if (!this.destroyed && !this.lifetimeSignal.aborted) this.emit({ type: 'error', error: new DeviceCommunicationError('Shelly configuration refresh failed.'), timestamp: Date.now() });
     }
-    return {
-      realm: values.realm,
-      nonce: values.nonce,
-      qop: values.qop,
-      opaque: values.opaque,
-    };
   }
 
-  private createDigestAuthorization(methodArg: string, pathArg: string): string {
-    if (!this.digestChallenge || !this.config.password) {
-      throw new Error('Shelly digest authentication cannot be created before a challenge is received.');
-    }
+  private parseResponse<TResult>(parserArg: () => TResult): TResult {
+    try { return parserArg(); }
+    catch (errorArg) { this.healthy = false; throw errorArg; }
+  }
 
-    const username = this.config.username || 'admin';
-    const cnonce = plugins.crypto.randomBytes(8).toString('hex');
-    const nc = (++this.nonceCount).toString(16).padStart(8, '0');
-    const ha1 = this.sha256(`${username}:${this.digestChallenge.realm}:${this.config.password}`);
-    const ha2 = this.sha256(`${methodArg}:${pathArg}`);
-    const response = this.sha256(`${ha1}:${this.digestChallenge.nonce}:${nc}:${cnonce}:auth:${ha2}`);
-    const parts = [
-      `username="${username}"`,
-      `realm="${this.digestChallenge.realm}"`,
-      `nonce="${this.digestChallenge.nonce}"`,
-      `uri="${pathArg}"`,
-      'algorithm=SHA-256',
-      `response="${response}"`,
-      'qop=auth',
-      `nc=${nc}`,
-      `cnonce="${cnonce}"`,
-    ];
-    if (this.digestChallenge.opaque) {
-      parts.push(`opaque="${this.digestChallenge.opaque}"`);
-    }
-    return `Digest ${parts.join(', ')}`;
+  private async callRpc(methodArg: string, paramsArg?: Record<string, unknown>, abortSignalArg?: AbortSignal): Promise<Record<string, unknown>> {
+    if (!this.deviceId) await this.getDeviceInfo(abortSignalArg);
+    const id = this.requestId++;
+    const source = 'smarthome.exchange';
+    const frame = await this.requestJson('/rpc', { id, src: source, method: methodArg, params: paramsArg }, abortSignalArg);
+    return this.parseResponse(() => parseShellyRpcResult(frame, id, this.deviceId, source));
   }
 
-  private sha256(valueArg: string): string {
-    return plugins.crypto.createHash('sha256').update(valueArg).digest('hex');
+  private async requestJson(pathArg: string, bodyArg?: Record<string, unknown>, abortSignalArg?: AbortSignal): Promise<unknown> {
+    this.assertActive(abortSignalArg);
+    const deadline = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; deadline.abort(); }, this.timeoutMs);
+    const signal = AbortSignal.any([deadline.signal, this.lifetimeSignal, ...(abortSignalArg ? [abortSignalArg] : [])]);
+    const cancelled = (): Error => timedOut ? new DeviceCommunicationError('Shelly request timed out.') : new DOMException('Shelly request cancelled.', 'AbortError');
+    let rejectCancelled: ((errorArg: Error) => void) | undefined;
+    const cancellation = new Promise<never>((_, rejectArg) => { rejectCancelled = rejectArg; });
+    const handleAbort = (): void => rejectCancelled?.(cancelled());
+    signal.addEventListener('abort', handleAbort, { once: true });
+    if (signal.aborted) handleAbort();
+    const operation = this.requestQueue.then(async () => {
+      if (signal.aborted) throw cancelled();
+      const method = bodyArg ? 'POST' : 'GET';
+      let response = await this.fetchPath(pathArg, method, bodyArg, signal);
+      if (response.status === 401) {
+        await response.body?.cancel();
+        if (!this.config.password) throw new AuthenticationError('Shelly authentication requires a password.');
+        this.digestChallenge = parseShellyHttpChallenge(response.headers.get('www-authenticate'), this.deviceId);
+        this.nonceCount = 0;
+        response = await this.fetchPath(pathArg, method, bodyArg, signal);
+      }
+      if (!response.ok) {
+        await response.body?.cancel();
+        if (response.status === 401) throw new AuthenticationError('Shelly authentication failed.');
+        throw new DeviceCommunicationError(`Shelly request failed with HTTP ${response.status}.`);
+      }
+      if (!response.body) throw new DeviceCommunicationError('Shelly returned an empty response.');
+      const reader = response.body.getReader();
+      const chunks: Uint8Array[] = [];
+      let size = 0;
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          size += value.byteLength;
+          if (size > 1024 * 1024) {
+            await reader.cancel();
+            throw new DeviceCommunicationError('Shelly response exceeds the size limit.');
+          }
+          chunks.push(value);
+        }
+      } finally { reader.releaseLock(); }
+      return JSON.parse(Buffer.concat(chunks).toString('utf8')) as unknown;
+    });
+    this.requestQueue = operation.then(() => undefined, () => undefined);
+    try { return await Promise.race([operation, cancellation]); }
+    catch (errorArg) {
+      this.healthy = false;
+      if (signal.aborted) throw cancelled();
+      if (errorArg instanceof AuthenticationError || errorArg instanceof DeviceCommunicationError) throw errorArg;
+      throw new DeviceCommunicationError('Shelly request failed or returned invalid JSON.');
+    } finally {
+      clearTimeout(timer);
+      signal.removeEventListener('abort', handleAbort);
+      rejectCancelled = undefined;
+    }
   }
 
-  private baseUrl(): string {
-    const protocol = this.config.protocol || 'http';
-    const port = this.config.port && this.config.port !== 80 ? `:${this.config.port}` : '';
-    return `${protocol}://${this.config.host}${port}`;
+  private async fetchPath(pathArg: string, methodArg: string, bodyArg: Record<string, unknown> | undefined, signalArg: AbortSignal): Promise<Response> {
+    const headers: Record<string, string> = {};
+    if (bodyArg) headers['content-type'] = 'application/json';
+    if (this.digestChallenge && this.config.password) {
+      const digest = createShellyDigest(this.digestChallenge, this.config.password, ++this.nonceCount, methodArg, pathArg);
+      headers.authorization = `Digest username="admin", realm="${this.digestChallenge.realm}", nonce="${this.digestChallenge.nonce}", uri="${pathArg}", algorithm=SHA-256, response="${digest.response}", qop=auth, nc=${digest.nc}, cnonce="${digest.cnonce}"${this.digestChallenge.opaque ? `, opaque="${this.digestChallenge.opaque}"` : ''}`;
+    }
+    return globalThis.fetch(new URL(pathArg, this.endpoint), { method: methodArg, headers, body: bodyArg ? JSON.stringify(bodyArg) : undefined, signal: signalArg, redirect: 'error' });
   }
 
-  private isRecord(valueArg: unknown): valueArg is Record<string, unknown> {
-    return typeof valueArg === 'object' && valueArg !== null && !Array.isArray(valueArg);
+  private assertActive(abortSignalArg?: AbortSignal): void {
+    if (this.destroyed) throw new Error('Shelly client has been destroyed.');
+    if (this.lifetimeSignal.aborted || abortSignalArg?.aborted) throw new DOMException('Shelly operation cancelled.', 'AbortError');
   }
 }

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

@@ -1,5 +1,6 @@
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
 import type { IShellyConfig } from './shelly.types.js';
+import { ShellyClient } from './shelly.classes.client.js';
 
 export class ShellyConfigFlow implements IConfigFlow<IShellyConfig> {
   public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IShellyConfig>> {
@@ -18,17 +19,30 @@ export class ShellyConfigFlow implements IConfigFlow<IShellyConfig> {
         { name: 'username', label: 'Username', type: 'text' },
         { name: 'password', label: 'Password', type: 'password' },
       ],
-      submit: async (valuesArg) => ({
-        kind: 'done',
-        title: 'Shelly configured',
-        config: {
-          host: String(valuesArg.host || candidateArg.host || ''),
-          port: typeof valuesArg.port === 'number' ? valuesArg.port : candidateArg.port || 80,
+      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: String(valuesArg.username || 'admin'),
-          password: valuesArg.password ? String(valuesArg.password) : undefined,
-        },
-      }),
+          username: 'admin',
+          password: typeof valuesArg.password === 'string' ? valuesArg.password : undefined,
+        };
+        let client: ShellyClient | undefined;
+        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(); }
+      },
     };
   }
 }