@smarthome.exchange/integrations 0.2.0 → 1.0.0

package/ts/integrations/tradfri/tradfri.discovery.ts

@@ -2,9 +2,25 @@ import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
 import type { IDiscoveryCandidate, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
 import type { ITradfriManualEntry, ITradfriMdnsRecord } from './tradfri.types.js';
 import { tradfriDefaultCoapDtlsPort } from './tradfri.types.js';
+import * as plugins from '../../plugins.js';
 
 const tradfriMdnsTypes = new Set(['_hap._tcp.local', '_homekit._tcp.local', '_tradfri._udp.local', '_coap._udp.local']);
 
+const containsTradfri = (valueArg: string): boolean => /(?:^|[^a-z\u00e5])tr(?:a|\u00e5)dfri(?:[^a-z\u00e5]|$)/i.test(valueArg);
+const isDirigera = (valueArg: string): boolean => /dirigera/i.test(valueArg);
+const validPort = (valueArg?: number): boolean => valueArg === undefined || Number.isInteger(valueArg) && valueArg >= 1 && valueArg <= 65535;
+const metadataString = (valueArg: unknown): string | undefined => typeof valueArg === 'string' ? valueArg : undefined;
+const validHost = (valueArg?: string): boolean => {
+  if (!valueArg || valueArg !== valueArg.trim()) {
+    return false;
+  }
+  if (plugins.net.isIP(valueArg)) {
+    return true;
+  }
+  const hostname = valueArg.replace(/\.$/, '');
+  return hostname.length <= 253 && hostname.split('.').every((labelArg) => labelArg.length <= 63 && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/i.test(labelArg));
+};
+
 export class TradfriMdnsMatcher implements IDiscoveryMatcher<ITradfriMdnsRecord> {
   public id = 'tradfri-mdns-match';
   public source = 'mdns' as const;
@@ -17,16 +33,20 @@ export class TradfriMdnsMatcher implements IDiscoveryMatcher<ITradfriMdnsRecord>
     const model = this.txt(txt, 'md') || this.txt(txt, 'model') || this.txt(txt, 'modelid');
     const manufacturer = this.txt(txt, 'manufacturer') || this.txt(txt, 'mfg');
     const gatewayId = this.txt(txt, 'gateway_id') || this.txt(txt, 'gatewayid') || this.txt(txt, 'id') || this.txt(txt, 'serial') || this.txt(txt, 'sn');
-    const matched = tradfriMdnsTypes.has(type) && this.containsTradfri(`${name} ${model} ${manufacturer}`)
-      || type === '_tradfri._udp.local'
-      || this.containsTradfri(`${name} ${model} ${manufacturer}`)
-      || Boolean(gatewayId && this.containsTradfri(name));
+    const metadata = `${name} ${model || ''} ${manufacturer || ''}`;
+    const nativeGatewayName = /^gw-[0-9a-f]{12}(?:\.|$)/i.test(name);
+    const matched = !isDirigera(metadata) && tradfriMdnsTypes.has(type)
+      && (containsTradfri(metadata) || type === '_coap._udp.local' && nativeGatewayName);
 
     if (!matched) {
       return { matched: false, confidence: 'low', reason: 'mDNS record is not an IKEA TRADFRI gateway advertisement.' };
     }
 
     const host = recordArg.host || recordArg.hostname || recordArg.addresses?.[0];
+    const port = type === '_hap._tcp.local' || type === '_homekit._tcp.local' ? tradfriDefaultCoapDtlsPort : recordArg.port ?? tradfriDefaultCoapDtlsPort;
+    if (!validHost(host) || !validPort(port)) {
+      return { matched: false, confidence: 'low', reason: 'TRADFRI advertisement lacks a valid local gateway endpoint.' };
+    }
     return {
       matched: true,
       confidence: gatewayId ? 'certain' : tradfriMdnsTypes.has(type) ? 'high' : 'medium',
@@ -37,34 +57,30 @@ export class TradfriMdnsMatcher implements IDiscoveryMatcher<ITradfriMdnsRecord>
         integrationDomain: 'tradfri',
         id: gatewayId || host || name,
         host,
-        port: type === '_hap._tcp.local' || type === '_homekit._tcp.local' ? tradfriDefaultCoapDtlsPort : recordArg.port || tradfriDefaultCoapDtlsPort,
+        port,
         name: this.cleanName(name) || 'IKEA TRADFRI Gateway',
         manufacturer: 'IKEA of Sweden',
         model: model || 'TRADFRI Gateway',
         metadata: {
           mdnsName: recordArg.name,
           mdnsType: recordArg.type,
-          txt,
           gatewayId,
           homekitId: this.txt(txt, 'id'),
+          firmwareVersion: this.txt(txt, 'version'),
         },
       },
     };
   }
 
   private txt(txtArg: Record<string, string | undefined>, keyArg: string): string | undefined {
-    return txtArg[keyArg] || txtArg[keyArg.toUpperCase()];
+    const key = Object.keys(txtArg).find((keyValueArg) => keyValueArg.toLowerCase() === keyArg);
+    return key ? txtArg[key] : undefined;
   }
 
   private normalizeType(valueArg?: string): string {
     return (valueArg || '').toLowerCase().replace(/\.$/, '');
   }
 
-  private containsTradfri(valueArg: string): boolean {
-    const value = valueArg.toLowerCase();
-    return value.includes('tradfri') || value.includes('tr\u00e5dfri') || value.includes('ikea');
-  }
-
   private cleanName(valueArg: string): string | undefined {
     const cleaned = valueArg.replace(/\._[^.]+\._(?:tcp|udp)\.local\.?$/i, '').replace(/\.local\.?$/i, '').trim();
     return cleaned || undefined;
@@ -77,8 +93,8 @@ export class TradfriManualMatcher implements IDiscoveryMatcher<ITradfriManualEnt
   public description = 'Recognize manual IKEA TRADFRI gateway host and security-code entries.';
 
   public async matches(inputArg: ITradfriManualEntry): Promise<IDiscoveryMatch> {
-    const metadata = inputArg.metadata || {};
-    const matched = Boolean(inputArg.host || inputArg.securityCode || inputArg.security_code || inputArg.psk || inputArg.key || inputArg.identity || metadata.tradfri || metadata.securityCode);
+    const matched = validHost(inputArg.host) && validPort(inputArg.port)
+      && !isDirigera(`${inputArg.name || ''} ${inputArg.model || ''}`);
     if (!matched) {
       return { matched: false, confidence: 'low', reason: 'Manual entry does not contain IKEA TRADFRI setup hints.' };
     }
@@ -98,11 +114,8 @@ export class TradfriManualMatcher implements IDiscoveryMatcher<ITradfriManualEnt
         manufacturer: inputArg.manufacturer || 'IKEA of Sweden',
         model: inputArg.model || 'TRADFRI Gateway',
         metadata: {
-          ...metadata,
           gatewayId,
-          identity: inputArg.identity,
-          securityCode: inputArg.securityCode || inputArg.security_code,
-          psk: inputArg.psk || inputArg.key,
+          tradfri: true,
         },
       },
     };
@@ -116,16 +129,13 @@ export class TradfriCandidateValidator implements IDiscoveryValidator {
   public async validate(candidateArg: IDiscoveryCandidate): Promise<IDiscoveryMatch> {
     const value = `${candidateArg.integrationDomain || ''} ${candidateArg.manufacturer || ''} ${candidateArg.model || ''} ${candidateArg.name || ''}`.toLowerCase();
     const metadata = candidateArg.metadata || {};
-    const matched = candidateArg.integrationDomain === 'tradfri'
-      || value.includes('tradfri')
-      || value.includes('tr\u00e5dfri')
-      || value.includes('ikea')
-      || Boolean(metadata.tradfri || metadata.securityCode || metadata.psk || metadata.gatewayId);
-    if (!matched || !candidateArg.host) {
+    const matched = !isDirigera(value) && (candidateArg.integrationDomain === 'tradfri'
+      || containsTradfri(value) || metadata.tradfri === true);
+    if (!matched || !validHost(candidateArg.host) || !validPort(candidateArg.port)) {
       return {
         matched: false,
         confidence: matched ? 'medium' : 'low',
-        reason: matched ? 'Candidate lacks a host for local TRADFRI setup.' : 'Candidate is not IKEA TRADFRI.',
+        reason: matched ? 'Candidate lacks a valid local TRADFRI endpoint.' : 'Candidate is not IKEA TRADFRI.',
         normalizedDeviceId: candidateArg.id || candidateArg.host,
       };
     }
@@ -134,8 +144,24 @@ export class TradfriCandidateValidator implements IDiscoveryValidator {
       confidence: candidateArg.id ? 'high' : 'medium',
       reason: 'Candidate has IKEA TRADFRI gateway metadata and host information.',
       candidate: {
-        ...candidateArg,
+        source: candidateArg.source,
+        integrationDomain: 'tradfri',
+        id: metadataString(candidateArg.id),
+        host: candidateArg.host,
         port: candidateArg.port || tradfriDefaultCoapDtlsPort,
+        name: metadataString(candidateArg.name),
+        manufacturer: metadataString(candidateArg.manufacturer),
+        model: metadataString(candidateArg.model),
+        serialNumber: metadataString(candidateArg.serialNumber),
+        macAddress: metadataString(candidateArg.macAddress),
+        metadata: {
+          tradfri: true,
+          gatewayId: metadataString(metadata.gatewayId),
+          homekitId: metadataString(metadata.homekitId),
+          mdnsName: metadataString(metadata.mdnsName),
+          mdnsType: metadataString(metadata.mdnsType),
+          firmwareVersion: metadataString(metadata.firmwareVersion),
+        },
       },
       normalizedDeviceId: candidateArg.id || candidateArg.host,
     };

package/ts/integrations/tuya/readme.md

@@ -0,0 +1,106 @@
+# Tuya local protocol 3.4
+
+`TuyaIntegration` and the existing `HomeAssistantTuyaIntegration` export provide a
+native local runtime through published `@ecobridge.xyz/devicemanager` 4.2.0.
+Setup requires an explicit home, device ID, literal private/link-local/loopback
+IPv4 endpoint, local key and this product's verified datapoint schema. Discovery
+has no broadcast probes and makes no claim to locate devices or obtain credentials.
+The native runtime uses the existing `tuya` domain, and the Home Assistant-named
+constructor remains available to existing callers.
+
+```typescript
+import {
+  NoSqlConfigStore,
+  TuyaIntegration,
+  type IHomeAssistantTuyaConfig,
+} from '@smarthome.exchange/integrations';
+
+const store = new NoSqlConfigStore({
+  db: callerOwnedDatabase,
+  homeId: 'home-one',
+  integrationDomain: 'tuya',
+  keyProvider: callerOwnedEncryptionKeyProvider,
+});
+const config: IHomeAssistantTuyaConfig = {
+  homeId: 'home-one',
+  deviceId: configuredDeviceId,
+  host: '192.168.1.50',
+  version: '3.4',
+  datapoints: [
+    // IDs and permissions must come from this exact product's schema.
+    { id: 7, name: 'Power', kind: 'switch', access: 'read-write' },
+    { id: 24, name: 'Brightness', kind: 'brightness', access: 'read-write', min: 10, max: 1000, step: 10 },
+    { id: 108, name: 'Temperature', kind: 'sensor', valueType: 'integer', scale: 1, unit: '°C' },
+  ],
+};
+const integration = new TuyaIntegration();
+// One explicit provisioning action stores configuration and the opaque 16-byte
+// local key together, encrypted under the caller's key provider.
+await integration.provisionLocalKey(config, configuredLocalKeyBytes, { configStore: store });
+const runtime = await integration.setup(config, { configStore: store });
+try {
+  const [device] = await runtime.devices();
+  const power = device.features.find((feature) => feature.id === 'dp_7');
+  if (power) {
+    const result = await runtime.writeFeature!({ device, feature: power, value: true });
+    // success reports a correlated protocol ACK, not physical completion.
+    // Observe authenticated state reports before declaring an effect complete.
+  }
+} finally {
+  await integration.destroy();
+  await store.close(); // the integration does not close caller-owned resources
+}
+```
+
+The store must be an actual `NoSqlConfigStore` scoped to the exact configured home
+and `tuya` domain. Generic stores are rejected. Configuration and credentials use
+`device:<configured device ID>` in that encrypted scope; setup rejects a different
+endpoint or schema until it is explicitly provisioned. A fresh integration/store
+can recover the provisioned record. The database, store and encryption-key provider
+remain caller-owned. No filesystem or cloud persistence is used. Key byte copies
+are cleared after use; JavaScript strings produced during encrypted JSON handling
+cannot be promised a physical memory wipe.
+
+Only mappings present with the correct type in authenticated device reports are
+exposed. There are no assumed universal power/brightness datapoint IDs. Boolean
+switches and bounded, stepped integer brightness may be `read-write`; all sensors
+are read-only. Brightness values use configured device integer units. Integer sensor
+`scale` divides the reported integer by `10 ** scale`; other values retain their
+reported type. The initial admission requires a correlated query and at least one
+mapped datapoint. A subsequent incompatible mapped report permanently closes the
+session rather than retaining writable capability under changed semantics.
+
+IDs include the encoded home and configured device ID. Feature writes require the
+exact runtime-owned device ID, `integrationDomain: 'tuya'`, an observed writable
+feature and matching type/range/step. Caller-supplied feature capabilities never
+grant authority. Services support `switch.turn_on`, `switch.turn_off`, and
+`number.set_value` with `{ value: <device integer> }`, each requiring an exact owned
+entity target. Wildcards, arbitrary datapoint writes and extra command data are
+rejected. The hub still owns authenticated home access; namespaced IDs are not a
+replacement for its authorization.
+
+A successful result includes `outcome: 'acknowledged'` and
+`physicalCompletion: 'unconfirmed'`. State changes only when authenticated reports
+arrive. Failures retain `effectOutcome: 'not-sent'`, `'rejected'` or `'indeterminate'`;
+a transmitted effect with a lost/late response may already have happened. There is
+no retry, retransmission or reconnect. Lifetime/setup cancellation and feature-write
+signals are supported. `destroy()` is permanent, idempotent and drains setup and
+protocol operations; use a new integration for a new lifetime. Cached reads after
+shutdown remain marked unavailable with their original report timestamps.
+
+Subscriptions are bounded to 128 listeners, abortable and explicitly removable.
+Handlers must not block. Asynchronous handler work is caller-owned; handler failures
+are reported through the supplied logger using a generic credential-free message.
+All listeners are removed during destruction.
+One integration owns at most 32 simultaneous setup/provisioning/runtime lifetimes.
+
+Other protocol versions, cloud-only and sleeping devices, gateway children, BLE,
+Zigbee, raw/bitmap/enum mappings and arbitrary actions are unsupported. The shared
+device protocol union currently has no Tuya member, so the generic device reports
+`protocol: 'unknown'` with factual `metadata.transport: 'tuya-3.4'`. Encrypted
+loopback fixture tests cover the implementation; qualification against real product
+firmware requires separately authorized hardware access.
+
+Product types and permissions follow the vendor's [DP Model and Control Protocol](https://developer.tuya.com/en/docs/iot-device-dev/TuyaOS-iot_abi_dp_ctrl?id=Kcoglhn5r7ajr).
+LAN framing is implemented by the owning dependency, whose public API and wire
+contract are documented in its [readme](https://code.foss.global/ecobridge.xyz/devicemanager).

package/ts/integrations/tuya/tuya.classes.integration.ts

@@ -1,30 +1,129 @@
-import { DescriptorOnlyIntegration } from '../../core/classes.descriptoronlyintegration.js';
-
-export class HomeAssistantTuyaIntegration extends DescriptorOnlyIntegration {
-  constructor() {
-    super({
-      domain: "tuya",
-      displayName: "Tuya",
-      status: 'descriptor-only',
-      metadata: {
-  "source": "home-assistant/core",
-  "upstreamPath": "homeassistant/components/tuya",
-  "upstreamDomain": "tuya",
-  "integrationType": "hub",
-  "iotClass": "cloud_push",
-  "requirements": [
-    "tuya-device-handlers==0.0.18",
-    "tuya-device-sharing-sdk==0.2.8"
-  ],
-  "dependencies": [
-    "ffmpeg"
-  ],
-  "afterDependencies": [],
-  "codeowners": [
-    "@Tuya",
-    "@zlinoliver"
-  ]
-},
-    });
+import * as plugins from '../../plugins.js';
+import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import type { IIntegrationRuntime, IIntegrationSetupContext } from '../../core/types.js';
+import { TuyaRuntime } from './tuya.classes.runtime.js';
+import type { IHomeAssistantTuyaConfig, ITuyaStoredConfiguration } from './tuya.types.js';
+import { normalizeTuyaConfig, scopedTuyaStore, tuyaCredentialId, tuyaKeys, tuyaRecord } from './tuya.validation.js';
+
+export class TuyaIntegration extends BaseIntegration<IHomeAssistantTuyaConfig> {
+  public readonly domain = 'tuya';
+  public readonly displayName = 'Tuya';
+  public readonly status = 'control-runtime' as const;
+  public readonly discoveryDescriptor = new DiscoveryDescriptor({ integrationDomain: 'tuya', displayName: 'Tuya 3.4 local device' });
+  public readonly metadata = Object.freeze({ source: 'native-typescript', integrationType: 'device', iotClass: 'local_push', protocolVersion: '3.4' });
+  readonly #setups = new Set<Promise<unknown>>();
+  readonly #controllers = new Set<AbortController>();
+  readonly #runtimes = new Set<TuyaRuntime>();
+  #destroyed = false;
+  #destroy?: Promise<void>;
+
+  public provisionLocalKey(configArg: IHomeAssistantTuyaConfig, localKeyArg: Uint8Array, contextArg: IIntegrationSetupContext): Promise<void> {
+    this.#assertOpen();
+    this.#assertCapacity();
+    const config = normalizeTuyaConfig(configArg);
+    const store = scopedTuyaStore(config, contextArg);
+    if (!(localKeyArg instanceof Uint8Array) || localKeyArg.byteLength !== 16) throw new TypeError('Tuya local key must contain exactly 16 opaque bytes.');
+    const copy = Buffer.from(localKeyArg);
+    const controller = new AbortController();
+    this.#controllers.add(controller);
+    const signal = contextArg.abortSignal ? AbortSignal.any([controller.signal, contextArg.abortSignal]) : controller.signal;
+    const operation = (async () => {
+      try {
+        signal.throwIfAborted();
+        await store.initialize({ signal });
+        this.#assertOpen();
+        signal.throwIfAborted();
+        await store.set<ITuyaStoredConfiguration>(tuyaCredentialId(config.deviceId), { version: 1, config, localKey: copy.toString('base64') });
+        this.#assertOpen();
+        signal.throwIfAborted();
+      } finally { copy.fill(0); this.#controllers.delete(controller); }
+    })();
+    return this.#track(operation);
+  }
+
+  public setup(configArg: IHomeAssistantTuyaConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    this.#assertOpen();
+    this.#assertCapacity();
+    const config = normalizeTuyaConfig(configArg);
+    const store = scopedTuyaStore(config, contextArg);
+    const controller = new AbortController();
+    this.#controllers.add(controller);
+    const signal = contextArg.abortSignal ? AbortSignal.any([controller.signal, contextArg.abortSignal]) : controller.signal;
+    const operation = (async () => {
+      let protocol: plugins.ecobridgeDeviceManager.TuyaProtocol | undefined;
+      let unsubscribeAdmission: (() => void) | undefined;
+      try {
+        signal.throwIfAborted();
+        await store.initialize({ signal });
+        signal.throwIfAborted();
+        const stored = tuyaRecord(await store.get<unknown>(tuyaCredentialId(config.deviceId)), 'stored configuration');
+        tuyaKeys(stored, ['version', 'config', 'localKey']);
+        if (stored.version !== 1 || JSON.stringify(normalizeTuyaConfig(stored.config)) !== JSON.stringify(config)) {
+          throw new TypeError('Tuya configuration does not match its encrypted provisioned configuration.');
+        }
+        if (typeof stored.localKey !== 'string' || stored.localKey.length !== 24) throw new TypeError('Tuya stored local key is invalid.');
+        const key = Buffer.from(stored.localKey, 'base64');
+        try {
+          if (key.byteLength !== 16 || key.toString('base64') !== stored.localKey) throw new TypeError('Tuya stored local key is invalid.');
+          signal.throwIfAborted();
+          protocol = new plugins.ecobridgeDeviceManager.TuyaProtocol({
+            deviceId: config.deviceId, localKey: key, host: config.host, port: config.port, version: config.version,
+            connectTimeoutMs: config.connectTimeoutMs, requestTimeoutMs: config.requestTimeoutMs,
+            heartbeatIntervalMs: config.heartbeatIntervalMs, abortSignal: signal,
+          });
+        } finally { key.fill(0); }
+        const reports: plugins.ecobridgeDeviceManager.ITuyaDatapointReport[] = [];
+        let admissionOverflow = false;
+        unsubscribeAdmission = protocol.subscribe((reportArg) => {
+          if (reports.length >= 128) { admissionOverflow = true; controller.abort(); }
+          else reports.push(reportArg);
+        });
+        await protocol.connect(signal);
+        await protocol.queryDatapoints(signal);
+        if (admissionOverflow) throw new Error('Tuya admission report capacity exceeded.');
+        signal.throwIfAborted();
+        this.#assertOpen();
+        unsubscribeAdmission();
+        unsubscribeAdmission = undefined;
+        const runtime = new TuyaRuntime(config, protocol, reports, () => {
+          this.#runtimes.delete(runtime);
+          this.#controllers.delete(controller);
+        }, contextArg.logger);
+        this.#runtimes.add(runtime);
+        return runtime;
+      } catch (errorArg) {
+        controller.abort();
+        unsubscribeAdmission?.();
+        await protocol?.close();
+        this.#controllers.delete(controller);
+        throw errorArg;
+      }
+    })();
+    return this.#track(operation);
+  }
+
+  public destroy(): Promise<void> {
+    if (this.#destroy) return this.#destroy;
+    this.#destroyed = true;
+    for (const controller of this.#controllers) controller.abort();
+    this.#destroy = (async () => {
+      await Promise.allSettled([...this.#setups]);
+      await Promise.all([...this.#runtimes].map((runtimeArg) => runtimeArg.destroy()));
+      this.#controllers.clear();
+    })();
+    return this.#destroy;
+  }
+
+  #assertOpen(): void { if (this.#destroyed) throw new Error('Tuya integration is permanently destroyed.'); }
+
+  #assertCapacity(): void { if (this.#controllers.size >= 32) throw new Error('Tuya integration lifetime capacity reached.'); }
+
+  #track<TResult>(operationArg: Promise<TResult>): Promise<TResult> {
+    this.#setups.add(operationArg);
+    void operationArg.then(() => this.#setups.delete(operationArg), () => this.#setups.delete(operationArg));
+    return operationArg;
   }
 }
+
+export class HomeAssistantTuyaIntegration extends TuyaIntegration {}

package/ts/integrations/tuya/tuya.classes.runtime.ts

@@ -0,0 +1,166 @@
+import * as plugins from '../../plugins.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, ILogger, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import type { IHomeAssistantTuyaConfig, TTuyaDatapointMapping } from './tuya.types.js';
+import { tuyaDeviceId, tuyaDevices, tuyaEntities, tuyaEntityId, tuyaFeatureId, type ITuyaObservedDatapoint } from './tuya.mapper.js';
+import { tuyaKeys, tuyaRecord, tuyaValueMatches } from './tuya.validation.js';
+
+export class TuyaRuntime implements IIntegrationRuntime {
+  public readonly domain = 'tuya';
+  readonly #config: IHomeAssistantTuyaConfig;
+  readonly #protocol: plugins.ecobridgeDeviceManager.TuyaProtocol;
+  readonly #onDestroyed: () => void;
+  readonly #logger?: ILogger;
+  readonly #observed = new Map<number, ITuyaObservedDatapoint>();
+  readonly #subscriptions = new Set<(eventArg: IIntegrationEvent) => void>();
+  readonly #subscriptionCleanup = new Set<() => void>();
+  readonly #unsubscribe: () => void;
+  readonly #unsubscribeErrors: () => void;
+  #closed = false;
+  #destroy?: Promise<void>;
+
+  constructor(configArg: IHomeAssistantTuyaConfig, protocolArg: plugins.ecobridgeDeviceManager.TuyaProtocol,
+    reportsArg: readonly plugins.ecobridgeDeviceManager.ITuyaDatapointReport[], onDestroyedArg: () => void, loggerArg?: ILogger) {
+    this.#config = configArg;
+    this.#protocol = protocolArg;
+    this.#onDestroyed = onDestroyedArg;
+    this.#logger = loggerArg;
+    for (const report of reportsArg) this.#accept(report);
+    if (this.#observed.size === 0) throw new Error('Tuya device reported none of the configured product datapoints.');
+    this.#unsubscribe = this.#protocol.subscribe((report) => {
+      try { this.#accept(report); }
+      catch {
+        this.#closed = true;
+        this.#emit({ type: 'error', data: { code: 'schema-mismatch', message: 'Tuya reported data no longer matches the configured product schema.' } });
+        this.#emit({ type: 'availability_changed', data: { available: false } });
+        void this.destroy();
+      }
+    });
+    this.#unsubscribeErrors = this.#protocol.subscribeErrors((error) => {
+      this.#emit({ type: 'error', data: { code: error.code, effectOutcome: error.effectOutcome } });
+      if (!this.#protocol.connected) this.#emit({ type: 'availability_changed', data: { available: false } });
+    });
+  }
+
+  public isHealthy(): boolean { return !this.#closed && this.#protocol.connected; }
+
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> {
+    signalArg?.throwIfAborted();
+    return tuyaDevices(this.#config, [...this.#observed.values()], this.isHealthy());
+  }
+
+  public async entities(): Promise<IIntegrationEntity[]> {
+    return tuyaEntities(this.#config, [...this.#observed.values()], this.isHealthy());
+  }
+
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    if (this.#closed) throw new Error('Tuya runtime is permanently closed.');
+    if (typeof handlerArg !== 'function') throw new TypeError('Tuya subscription handler must be a function.');
+    signalArg?.throwIfAborted();
+    if (this.#subscriptions.size >= 128) throw new Error('Tuya subscription capacity reached.');
+    const subscriber = (eventArg: IIntegrationEvent): void => handlerArg(eventArg);
+    const cleanup = (): void => {
+      this.#subscriptions.delete(subscriber);
+      this.#subscriptionCleanup.delete(cleanup);
+      signalArg?.removeEventListener('abort', cleanup);
+    };
+    this.#subscriptions.add(subscriber);
+    this.#subscriptionCleanup.add(cleanup);
+    signalArg?.addEventListener('abort', cleanup, { once: true });
+    if (signalArg?.aborted) cleanup();
+    return async () => cleanup();
+  }
+
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      const request = tuyaRecord(requestArg, 'feature write');
+      tuyaKeys(request, ['device', 'feature', 'value']);
+      const device = tuyaRecord(request.device, 'feature device');
+      const feature = tuyaRecord(request.feature, 'feature');
+      if (device.id !== tuyaDeviceId(this.#config) || device.integrationDomain !== 'tuya') throw new Error('Tuya feature target is outside the runtime home/device scope.');
+      const observed = [...this.#observed.values()].find(({ mapping }) => tuyaFeatureId(mapping) === feature.id);
+      if (!observed) throw new Error('Tuya feature has not been observed on the configured device.');
+      return await this.#write(observed.mapping, request.value, signalArg);
+    } catch (errorArg) { return this.#failure(errorArg); }
+  }
+
+  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    try {
+      const request = tuyaRecord(requestArg, 'service request');
+      tuyaKeys(request, ['domain', 'service', 'target', 'data']);
+      const target = tuyaRecord(request.target, 'service target');
+      tuyaKeys(target, ['deviceId', 'entityId']);
+      if (target.deviceId !== undefined && target.deviceId !== tuyaDeviceId(this.#config)) throw new Error('Tuya service device is outside the runtime home/device scope.');
+      if (typeof target.entityId !== 'string') throw new Error('Tuya service requires an exact owned datapoint entity.');
+      const observed = [...this.#observed.values()].find(({ mapping }) => tuyaEntityId(this.#config, mapping) === target.entityId);
+      if (!observed) throw new Error('Tuya service entity is outside the observed product schema.');
+      const data = request.data === undefined ? {} : tuyaRecord(request.data, 'service data');
+      let value: unknown;
+      if (observed.mapping.kind === 'switch' && request.domain === 'switch' && (request.service === 'turn_on' || request.service === 'turn_off')) {
+        tuyaKeys(data, []);
+        value = request.service === 'turn_on';
+      } else if (observed.mapping.kind === 'brightness' && request.domain === 'number' && request.service === 'set_value') {
+        tuyaKeys(data, ['value']);
+        value = data.value;
+      } else throw new Error('Tuya service is outside the supported scoped switch/brightness controls.');
+      return await this.#write(observed.mapping, value);
+    } catch (errorArg) { return this.#failure(errorArg); }
+  }
+
+  public destroy(): Promise<void> {
+    if (this.#destroy) return this.#destroy;
+    this.#closed = true;
+    this.#unsubscribe();
+    this.#unsubscribeErrors();
+    for (const cleanup of [...this.#subscriptionCleanup]) cleanup();
+    this.#destroy = this.#protocol.close().then(() => this.#onDestroyed());
+    return this.#destroy;
+  }
+
+  #accept(reportArg: plugins.ecobridgeDeviceManager.ITuyaDatapointReport): void {
+    const changes: ITuyaObservedDatapoint[] = [];
+    for (const mapping of this.#config.datapoints) {
+      const value = reportArg.datapoints[String(mapping.id)];
+      if (value === undefined) continue;
+      if (!tuyaValueMatches(mapping, value)) throw new Error('Tuya reported datapoint violates its configured product schema.');
+      changes.push(Object.freeze({ mapping, value, receivedAt: reportArg.receivedAt }));
+    }
+    const previous = new Map(this.#observed);
+    for (const observed of changes) this.#observed.set(observed.mapping.id, observed);
+    for (const observed of changes) {
+      const prior = previous.get(observed.mapping.id);
+      if (!prior || prior.value !== observed.value) this.#emit({ type: prior ? 'state_changed' : 'entity_added',
+        entityId: tuyaEntityId(this.#config, observed.mapping), data: { entity: tuyaEntities(this.#config, [observed], this.isHealthy())[0] } });
+    }
+  }
+
+  async #write(mappingArg: TTuyaDatapointMapping, valueArg: unknown, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    if (!this.isHealthy()) throw new Error('Tuya session is unavailable; no automatic reconnect or retry is performed.');
+    if (mappingArg.kind === 'sensor' || mappingArg.access !== 'read-write') throw new Error('Tuya datapoint is read-only.');
+    if (!tuyaValueMatches(mappingArg, valueArg)) throw new TypeError('Tuya write value does not match its configured type/range/step.');
+    const receipt = await this.#protocol.setDatapoints({ [mappingArg.id]: valueArg }, signalArg);
+    return { success: true, data: { ...receipt, physicalCompletion: 'unconfirmed', state: 'observe-authenticated-reports' } };
+  }
+
+  #failure(errorArg: unknown): IServiceCallResult {
+    if (errorArg instanceof plugins.ecobridgeDeviceManager.TuyaProtocolError) return {
+      success: false, error: errorArg.message,
+      data: { code: errorArg.code, effectOutcome: errorArg.effectOutcome, ...(errorArg.sequence === undefined ? {} : { sequence: errorArg.sequence }) },
+    };
+    return { success: false, error: errorArg instanceof Error ? errorArg.message : 'Tuya operation failed.', data: { effectOutcome: 'not-sent' } };
+  }
+
+  #emit(eventArg: Omit<IIntegrationEvent, 'integrationDomain' | 'deviceId' | 'timestamp'>): void {
+    for (const handler of [...this.#subscriptions]) {
+      if (this.#destroy) return;
+      try {
+        const result: unknown = handler({ ...structuredClone(eventArg), integrationDomain: 'tuya', deviceId: tuyaDeviceId(this.#config), timestamp: Date.now() });
+        if (result instanceof Promise) void result.catch(() => this.#subscriberFailed());
+      } catch { this.#subscriberFailed(); }
+    }
+  }
+
+  #subscriberFailed(): void {
+    if (this.#destroy) return;
+    this.#logger?.log('error', 'Tuya event subscriber failed.', { code: 'subscriber-error' });
+  }
+}

package/ts/integrations/tuya/tuya.mapper.ts

@@ -0,0 +1,47 @@
+import * as plugins from '../../plugins.js';
+import type { IIntegrationEntity } from '../../core/types.js';
+import type { IHomeAssistantTuyaConfig, TTuyaDatapointMapping } from './tuya.types.js';
+
+export interface ITuyaObservedDatapoint {
+  readonly mapping: TTuyaDatapointMapping;
+  readonly value: plugins.ecobridgeDeviceManager.TTuyaDatapointValue;
+  readonly receivedAt: number;
+}
+
+export const tuyaDeviceId = (configArg: IHomeAssistantTuyaConfig): string =>
+  `tuya:${encodeURIComponent(configArg.homeId)}:${configArg.deviceId}`;
+
+export const tuyaFeatureId = (mappingArg: TTuyaDatapointMapping): string => `dp_${mappingArg.id}`;
+
+export const tuyaEntityId = (configArg: IHomeAssistantTuyaConfig, mappingArg: TTuyaDatapointMapping): string =>
+  `${tuyaDeviceId(configArg)}:dp:${mappingArg.id}`;
+
+const displayValue = (observedArg: ITuyaObservedDatapoint): plugins.ecobridgeDeviceManager.TTuyaDatapointValue =>
+  observedArg.mapping.kind === 'sensor' && observedArg.mapping.valueType === 'integer' && typeof observedArg.value === 'number'
+    ? observedArg.value / 10 ** (observedArg.mapping.scale ?? 0) : observedArg.value;
+
+export const tuyaDevices = (configArg: IHomeAssistantTuyaConfig, observedArg: readonly ITuyaObservedDatapoint[], availableArg: boolean): plugins.shxInterfaces.data.IDeviceDefinition[] => [{
+  id: tuyaDeviceId(configArg), integrationDomain: 'tuya', name: configArg.name ?? `Tuya ${configArg.deviceId}`,
+  protocol: 'unknown', manufacturer: 'Tuya', online: availableArg,
+  features: observedArg.map(({ mapping }) => ({
+    id: tuyaFeatureId(mapping), name: mapping.name, readable: true,
+    writable: mapping.kind !== 'sensor' && mapping.access === 'read-write',
+    capability: mapping.kind === 'switch' ? 'switch' : mapping.kind === 'brightness' ? 'light' : 'sensor',
+    ...(mapping.kind === 'sensor' && mapping.unit !== undefined ? { unit: mapping.unit } : {}),
+  })),
+  state: observedArg.map((observed) => ({ featureId: tuyaFeatureId(observed.mapping), value: displayValue(observed), updatedAt: new Date(observed.receivedAt).toISOString() })),
+  metadata: {
+    homeId: configArg.homeId, deviceId: configArg.deviceId, transport: 'tuya-3.4',
+    datapoints: observedArg.map(({ mapping }) => ({ ...mapping })),
+  },
+}];
+
+export const tuyaEntities = (configArg: IHomeAssistantTuyaConfig, observedArg: readonly ITuyaObservedDatapoint[], availableArg: boolean): IIntegrationEntity[] =>
+  observedArg.map((observed) => ({
+    id: tuyaEntityId(configArg, observed.mapping), uniqueId: tuyaEntityId(configArg, observed.mapping),
+    integrationDomain: 'tuya', deviceId: tuyaDeviceId(configArg), name: observed.mapping.name,
+    platform: observed.mapping.kind === 'switch' ? 'switch' : observed.mapping.kind === 'brightness' ? 'number' :
+      observed.mapping.valueType === 'boolean' ? 'binary_sensor' : 'sensor',
+    state: displayValue(observed), available: availableArg,
+    attributes: { ...observed.mapping, homeId: configArg.homeId, updatedAt: new Date(observed.receivedAt).toISOString() },
+  }));