@smarthome.exchange/integrations 0.1.0 → 1.0.0

package/ts/integrations/tplink/tplink.discovery.ts

@@ -1,270 +1,141 @@
+import * as plugins from '../../plugins.js';
 import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
 import type { IDiscoveryCandidate, IDiscoveryContext, IDiscoveryMatch, IDiscoveryMatcher, IDiscoveryValidator } from '../../core/types.js';
 import type { ITplinkDhcpRecord, ITplinkManualDiscoveryRecord, ITplinkMdnsRecord } from './tplink.types.js';
-import { tplinkDefaultHttpPort, tplinkLegacyDiscoveryPort, tplinkSmartDiscoveryPort } from './tplink.types.js';
-
-const tplinkMacPrefixes = [
-  '3c52a1', '54af97', 'e848b8', '1c61b4', '003192', 'b4b024', '9c5322', '5091e3',
-  '1c3bf3', '50c7bf', '68ff7b', '98dac4', 'b09575', 'c006c3', '60a4b7', '005f67',
-  '1027f5', 'b0a7b9', '403f8c', 'c0c9e3', '909a4a', '6c5ab0', 'ac15a2', '788cb5',
-  '3460f9', '5ce931', '5c628b', '14ebb6', '482254', '30de4b', 'a842a1', '704f57',
-  '74da88', 'cc32e5', 'd80d17', 'd84732', 'f0a731',
-];
-
-const tplinkHostnamePatterns = [/^e[sp]/i, /^hs/i, /^k[lps]/i, /^p[13]/i, /^s5/i, /^l[59]/i, /^tp/i, /^h1/i, /^ks2/i, /^kh1/i];
-const tplinkTextHints = ['tp-link', 'tplink', 'kasa', 'tapo', 'smart plug', 'smart bulb', 'smart switch', 'smart dimmer'];
+import { tplinkKeys, tplinkObject } from './tplink.validation.js';
 
 export class TplinkMdnsMatcher implements IDiscoveryMatcher<ITplinkMdnsRecord> {
-  public id = 'tplink-mdns-match';
-  public source = 'mdns' as const;
-  public description = 'Recognize TP-Link Kasa/Tapo mDNS records by service, host, TXT, MAC, or model metadata.';
+  public readonly id = 'tplink-mdns-match';
+  public readonly source = 'mdns' as const;
+  public readonly description = 'Recognize TP-Link advertisements as hints that require an actual legacy relay query.';
 
   public async matches(recordArg: ITplinkMdnsRecord, contextArg?: IDiscoveryContext): Promise<IDiscoveryMatch> {
     void contextArg;
-    const txt = recordArg.txt || recordArg.properties || {};
-    const host = recordArg.host || recordArg.hostname || recordArg.addresses?.[0];
-    const hostname = recordArg.hostname || recordArg.host || recordArg.name;
-    const model = this.txt(txt, 'model') || this.txt(txt, 'modelid') || recordArg.model;
-    const manufacturer = recordArg.manufacturer || this.txt(txt, 'manufacturer') || this.txt(txt, 'vendor');
-    const macAddress = normalizeMac(recordArg.macAddress || this.txt(txt, 'mac') || this.txt(txt, 'macaddress') || this.txt(txt, 'mac_address'));
-    const text = [recordArg.type, recordArg.serviceType, recordArg.name, hostname, host, model, manufacturer, this.txt(txt, 'brand')]
-      .filter((valueArg): valueArg is string => typeof valueArg === 'string')
-      .join(' ')
-      .toLowerCase();
-    const macMatched = isTplinkMac(macAddress);
-    const hostMatched = isTplinkHostname(hostname);
-    const textMatched = hasTplinkTextHint(text);
-    const matched = macMatched || textMatched || hostMatched && text.includes('local');
-
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'mDNS record is not a TP-Link Kasa/Tapo advertisement.' };
-    }
-
-    const id = macAddress || this.txt(txt, 'device_id') || this.txt(txt, 'deviceid') || recordArg.name || host;
-    return {
-      matched: true,
-      confidence: macMatched && host ? 'certain' : host && (textMatched || hostMatched) ? 'high' : 'medium',
-      reason: macMatched ? 'mDNS record contains a known TP-Link MAC prefix.' : 'mDNS record contains Kasa/Tapo/TP-Link metadata.',
-      normalizedDeviceId: id,
-      candidate: {
-        source: 'mdns',
-        integrationDomain: 'tplink',
-        id,
-        host,
-        port: recordArg.port || tplinkDefaultHttpPort,
-        name: this.txt(txt, 'alias') || this.txt(txt, 'name') || recordArg.name || model,
-        manufacturer: manufacturer || 'TP-Link',
-        model,
-        macAddress,
-        metadata: {
-          tplink: true,
-          mdnsName: recordArg.name,
-          mdnsType: recordArg.type || recordArg.serviceType,
-          txt,
-          model,
-          hostMatched,
-          macMatched,
-          discoveryPorts: [tplinkLegacyDiscoveryPort, tplinkSmartDiscoveryPort],
-        },
-      },
-      metadata: { model, macAddress, hostMatched, macMatched },
-    };
-  }
-
-  private txt(txtArg: Record<string, string | undefined>, keyArg: string): string | undefined {
-    return txtArg[keyArg] || txtArg[keyArg.toUpperCase()];
+    try {
+      const record = tplinkObject(recordArg, 'TP-Link mDNS record');
+      const service = text(record.type ?? record.serviceType)?.toLowerCase().replace(/\.$/, '');
+      if (service !== '_tplink._tcp.local' && service !== '_kasa._tcp.local') return noMatch('Not a TP-Link mDNS service.');
+      const properties = record.txt ?? record.properties;
+      const txt = properties === undefined ? {} : tplinkObject(properties, 'TP-Link mDNS TXT');
+      const host = literalHost(record.host ?? record.hostname, record.addresses);
+      const macAddress = mac(txt.mac ?? record.macAddress);
+      const name = text(txt.alias ?? record.name);
+      const model = text(txt.model ?? record.model);
+      return hint({ source: 'mdns', host, id: macAddress, name, model, macAddress, port: 9999 });
+    } catch { return noMatch('Invalid TP-Link mDNS metadata.'); }
   }
 }
 
 export class TplinkDhcpMatcher implements IDiscoveryMatcher<ITplinkDhcpRecord> {
-  public id = 'tplink-dhcp-match';
-  public source = 'dhcp' as const;
-  public description = 'Recognize Kasa/Tapo DHCP leases using Home Assistant TP-Link hostname and MAC rules.';
+  public readonly id = 'tplink-dhcp-match';
+  public readonly source = 'dhcp' as const;
+  public readonly description = 'Recognize possible legacy Kasa DHCP names without treating them as identity proof.';
 
   public async matches(recordArg: ITplinkDhcpRecord, contextArg?: IDiscoveryContext): Promise<IDiscoveryMatch> {
     void contextArg;
-    const metadata = recordArg.metadata || {};
-    const host = recordArg.host || recordArg.ipAddress || recordArg.address || recordArg.ip;
-    const hostname = recordArg.hostname || recordArg.hostName;
-    const macAddress = normalizeMac(recordArg.macAddress || recordArg.mac || this.stringValue(metadata.macAddress));
-    const model = recordArg.model || this.stringValue(metadata.model);
-    const manufacturer = recordArg.manufacturer || this.stringValue(metadata.manufacturer);
-    const text = [hostname, manufacturer, model, recordArg.vendorClassIdentifier, metadata.brand, metadata.deviceType]
-      .filter((valueArg): valueArg is string => typeof valueArg === 'string')
-      .join(' ')
-      .toLowerCase();
-    const macMatched = isTplinkMac(macAddress);
-    const hostMatched = isTplinkHostname(hostname);
-    const textMatched = hasTplinkTextHint(text);
-    const matched = recordArg.integrationDomain === 'tplink'
-      || metadata.tplink === true
-      || metadata.kasa === true
-      || metadata.tapo === true
-      || macMatched
-      || hostMatched && textMatched;
-
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'DHCP record does not match TP-Link Kasa/Tapo metadata.' };
-    }
-
-    const id = macAddress || this.stringValue(metadata.deviceId) || hostname || host;
-    return {
-      matched: true,
-      confidence: macMatched && host ? 'certain' : host && (hostMatched || textMatched) ? 'high' : 'medium',
-      reason: macMatched ? 'DHCP MAC prefix matches Home Assistant TP-Link manifest rules.' : 'DHCP hostname or metadata matches TP-Link Kasa/Tapo.',
-      normalizedDeviceId: id,
-      candidate: {
-        source: 'dhcp',
-        integrationDomain: 'tplink',
-        id,
-        host,
-        port: tplinkDefaultHttpPort,
-        name: hostname || model || 'TP-Link Smart Home device',
-        manufacturer: manufacturer || 'TP-Link',
-        model,
-        macAddress,
-        metadata: {
-          ...metadata,
-          tplink: true,
-          hostname,
-          macMatched,
-          hostMatched,
-          discoveryPorts: [tplinkLegacyDiscoveryPort, tplinkSmartDiscoveryPort],
-        },
-      },
-      metadata: { macMatched, hostMatched, model },
-    };
-  }
-
-  private stringValue(valueArg: unknown): string | undefined {
-    return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
+    try {
+      const record = tplinkObject(recordArg, 'TP-Link DHCP record');
+      const hostname = text(record.hostname ?? record.hostName);
+      if (!hostname || !/^(?:HS|KP)[A-Za-z0-9-]+$/i.test(hostname)) return noMatch('DHCP hostname is not a legacy Kasa hint.');
+      const host = text(record.host ?? record.ipAddress ?? record.address ?? record.ip);
+      return hint({ source: 'dhcp', host, name: hostname, model: text(record.model), macAddress: mac(record.macAddress ?? record.mac), port: 9999 });
+    } catch { return noMatch('Invalid TP-Link DHCP metadata.'); }
   }
 }
 
 export class TplinkManualMatcher implements IDiscoveryMatcher<ITplinkManualDiscoveryRecord> {
-  public id = 'tplink-manual-match';
-  public source = 'manual' as const;
-  public description = 'Recognize manual Kasa/Tapo setup entries, including snapshot-only records.';
+  public readonly id = 'tplink-manual-match';
+  public readonly source = 'manual' as const;
+  public readonly description = 'Admit explicit IP candidates for legacy Kasa verification; snapshots and credentials are unsupported.';
 
   public async matches(inputArg: ITplinkManualDiscoveryRecord, contextArg?: IDiscoveryContext): Promise<IDiscoveryMatch> {
     void contextArg;
-    const metadata = inputArg.metadata || {};
-    const host = inputArg.host;
-    const model = inputArg.model;
-    const macAddress = normalizeMac(inputArg.macAddress || inputArg.mac);
-    const text = [inputArg.integrationDomain, inputArg.manufacturer, inputArg.brand, inputArg.model, inputArg.alias, inputArg.name, metadata.brand, metadata.model]
-      .filter((valueArg): valueArg is string => typeof valueArg === 'string')
-      .join(' ')
-      .toLowerCase();
-    const snapshot = inputArg.snapshot || metadata.snapshot;
-    const matched = inputArg.integrationDomain === 'tplink'
-      || metadata.tplink === true
-      || metadata.kasa === true
-      || metadata.tapo === true
-      || Boolean(snapshot)
-      || Boolean(host && (hasTplinkTextHint(text) || model || macAddress))
-      || Boolean(host && !text);
-
-    if (!matched) {
-      return { matched: false, confidence: 'low', reason: 'Manual entry does not contain TP-Link setup data.' };
-    }
-
-    const id = inputArg.id || inputArg.deviceId || macAddress || host || `snapshot-${Date.now()}`;
-    return {
-      matched: true,
-      confidence: snapshot ? 'certain' : host && (macAddress || model) ? 'high' : host ? 'medium' : 'low',
-      reason: snapshot ? 'Manual entry includes a TP-Link snapshot.' : 'Manual entry can start TP-Link setup.',
-      normalizedDeviceId: id,
-      candidate: {
-        source: 'manual',
-        integrationDomain: 'tplink',
-        id,
-        host,
-        port: inputArg.port || tplinkDefaultHttpPort,
-        name: inputArg.alias || inputArg.name || model || 'TP-Link Smart Home device',
-        manufacturer: inputArg.manufacturer || 'TP-Link',
-        model,
-        macAddress,
-        metadata: {
-          ...metadata,
-          tplink: true,
-          manual: true,
-          deviceType: inputArg.deviceType,
-          snapshot,
-          device: inputArg.device,
-          devices: inputArg.devices,
-          credentialsConfigured: Boolean(inputArg.credentials?.username || inputArg.credentials?.credentialsHash),
-        },
-      },
-      metadata: { snapshotConfigured: Boolean(snapshot), credentialsConfigured: Boolean(inputArg.credentials) },
-    };
+    try {
+      const record = tplinkObject(inputArg, 'TP-Link manual record');
+      tplinkKeys(record, ['host', 'port', 'expectedDeviceId', 'deviceId', 'id', 'name', 'alias', 'model', 'manufacturer', 'integrationDomain', 'transport']);
+      if (record.integrationDomain !== undefined && record.integrationDomain !== 'tplink' ||
+        record.transport !== undefined && record.transport !== 'legacy-kasa') return noMatch('Manual candidate does not select legacy Kasa.');
+      const host = text(record.host);
+      if (!host || !plugins.net.isIP(host)) return noMatch('Legacy Kasa discovery requires an explicit IP address.');
+      const expectedDeviceId = text(record.expectedDeviceId ?? record.deviceId ?? record.id);
+      if (expectedDeviceId !== undefined && !/^[A-Za-z0-9_-]{1,128}$/.test(expectedDeviceId)) return noMatch('Invalid legacy Kasa expected device identity.');
+      const port = record.port === undefined ? 9999 : record.port;
+      if (typeof port !== 'number' || !Number.isSafeInteger(port) || port < 1 || port > 65535) return noMatch('Invalid legacy Kasa port.');
+      return hint({ source: 'manual', host, port, id: expectedDeviceId,
+        name: text(record.alias ?? record.name), model: text(record.model), metadata: expectedDeviceId ? { expectedDeviceId } : undefined });
+    } catch { return noMatch('Invalid TP-Link manual metadata.'); }
   }
 }
 
 export class TplinkCandidateValidator implements IDiscoveryValidator {
-  public id = 'tplink-candidate-validator';
-  public description = 'Validate TP-Link Kasa/Tapo candidates from mDNS, DHCP, and manual setup.';
+  public readonly id = 'tplink-candidate-validator';
+  public readonly description = 'Verify observed legacy single-relay identity over the owning bounded TCP API.';
 
   public async validate(candidateArg: IDiscoveryCandidate, contextArg?: IDiscoveryContext): Promise<IDiscoveryMatch> {
-    void contextArg;
-    const metadata = candidateArg.metadata || {};
-    const macAddress = normalizeMac(candidateArg.macAddress || this.stringValue(metadata.macAddress));
-    const text = [candidateArg.integrationDomain, candidateArg.manufacturer, candidateArg.model, candidateArg.name, metadata.brand, metadata.model, metadata.deviceType]
-      .filter((valueArg): valueArg is string => typeof valueArg === 'string')
-      .join(' ')
-      .toLowerCase();
-    const snapshotConfigured = metadata.snapshot !== undefined;
-    const macMatched = isTplinkMac(macAddress);
-    const textMatched = hasTplinkTextHint(text);
-    const matched = candidateArg.integrationDomain === 'tplink'
-      || metadata.tplink === true
-      || metadata.kasa === true
-      || metadata.tapo === true
-      || snapshotConfigured
-      || macMatched
-      || textMatched
-      || candidateArg.source === 'manual' && Boolean(candidateArg.host);
-
-    return {
-      matched,
-      confidence: matched && (macMatched || snapshotConfigured || candidateArg.integrationDomain === 'tplink') && candidateArg.host ? 'certain' : matched && candidateArg.host ? 'high' : matched ? 'medium' : 'low',
-      reason: matched ? 'Candidate has TP-Link Kasa/Tapo metadata or manual setup data.' : 'Candidate is not TP-Link Kasa/Tapo.',
-      candidate: matched ? candidateArg : undefined,
-      normalizedDeviceId: macAddress || candidateArg.id || candidateArg.host,
-      metadata: matched ? { macMatched, snapshotConfigured, encryptedLocalProtocolImplemented: false } : undefined,
-    };
-  }
-
-  private stringValue(valueArg: unknown): string | undefined {
-    return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
+    let protocol: plugins.ecobridgeDeviceManager.KasaProtocol | undefined;
+    try {
+      const candidate = tplinkObject(candidateArg, 'TP-Link candidate');
+      tplinkKeys(candidate, ['source', 'integrationDomain', 'id', 'host', 'port', 'name', 'manufacturer', 'model', 'serialNumber', 'macAddress', 'metadata']);
+      if (candidate.integrationDomain !== undefined && candidate.integrationDomain !== 'tplink' ||
+        candidate.source !== 'manual' && candidate.source !== 'mdns' && candidate.source !== 'dhcp') return noMatch('Unsupported TP-Link discovery candidate.');
+      const host = text(candidate.host);
+      if (!host || !plugins.net.isIP(host)) return noMatch('Legacy Kasa verification requires an explicit IP address.');
+      const metadata = candidate.metadata === undefined ? {} : tplinkObject(candidate.metadata, 'TP-Link candidate metadata');
+      tplinkKeys(metadata, ['expectedDeviceId']);
+      const expectedDeviceId = text(metadata.expectedDeviceId);
+      if (expectedDeviceId !== undefined && !/^[A-Za-z0-9_-]{1,128}$/.test(expectedDeviceId)) return noMatch('Invalid expected device identity.');
+      const port = candidate.port === undefined ? 9999 : candidate.port;
+      if (typeof port !== 'number' || !Number.isSafeInteger(port) || port < 1 || port > 65535) return noMatch('Invalid legacy Kasa port.');
+      protocol = new plugins.ecobridgeDeviceManager.KasaProtocol({ host, port, expectedDeviceId, timeoutMs: 3000, abortSignal: contextArg?.abortSignal });
+      const info = await protocol.getSystemInfo({ abortSignal: contextArg?.abortSignal });
+      return {
+        matched: true, confidence: 'certain', reason: 'Observed legacy Kasa single-relay identity and capability.', normalizedDeviceId: info.deviceId,
+        candidate: { source: candidate.source, integrationDomain: 'tplink', host, port, id: info.deviceId,
+          name: info.alias, manufacturer: 'TP-Link', model: info.model, macAddress: info.macAddress,
+          metadata: { expectedDeviceId: info.deviceId } },
+        metadata: { protocol: 'legacy-kasa', liveLocalWritesImplemented: true, authenticated: false },
+      };
+    } catch { return noMatch('Candidate did not verify as a supported legacy Kasa relay.'); }
+    finally { await protocol?.close(); }
   }
 }
 
-export const createTplinkDiscoveryDescriptor = (): DiscoveryDescriptor => {
-  return new DiscoveryDescriptor({ integrationDomain: 'tplink', displayName: 'TP-Link Smart Home' })
-    .addMatcher(new TplinkMdnsMatcher())
-    .addMatcher(new TplinkDhcpMatcher())
-    .addMatcher(new TplinkManualMatcher())
-    .addValidator(new TplinkCandidateValidator());
-};
-
-const normalizeMac = (valueArg?: string): string | undefined => {
-  if (!valueArg) {
-    return undefined;
-  }
-  const compact = valueArg.replace(/[^0-9a-f]/gi, '').toLowerCase();
-  return compact.length === 12 ? compact.match(/.{1,2}/g)?.join(':') : undefined;
-};
-
-const isTplinkMac = (valueArg?: string): boolean => {
-  const compact = (valueArg || '').replace(/[^0-9a-f]/gi, '').toLowerCase();
-  return tplinkMacPrefixes.some((prefixArg) => compact.startsWith(prefixArg));
+export const createTplinkDiscoveryDescriptor = (): DiscoveryDescriptor =>
+  new DiscoveryDescriptor({ integrationDomain: 'tplink', displayName: 'TP-Link legacy Kasa' })
+    .addMatcher(new TplinkMdnsMatcher()).addMatcher(new TplinkDhcpMatcher())
+    .addMatcher(new TplinkManualMatcher()).addValidator(new TplinkCandidateValidator());
+
+const noMatch = (reasonArg: string): IDiscoveryMatch => ({ matched: false, confidence: 'low', reason: reasonArg });
+const hint = (candidateArg: Omit<IDiscoveryCandidate, 'integrationDomain' | 'manufacturer'>): IDiscoveryMatch => ({
+  matched: true, confidence: 'medium', reason: 'Potential TP-Link endpoint; legacy protocol and identity remain unverified.',
+  candidate: { ...candidateArg, integrationDomain: 'tplink', manufacturer: 'TP-Link' }, normalizedDeviceId: candidateArg.id,
+});
+const text = (valueArg: unknown): string | undefined => {
+  if (valueArg === undefined) return undefined;
+  if (typeof valueArg !== 'string' || valueArg.length > 256 || !valueArg.length || /[\p{Cc}\p{Cs}]/u.test(valueArg)) throw new TypeError('Invalid TP-Link discovery text.');
+  return valueArg;
 };
-
-const isTplinkHostname = (valueArg?: string): boolean => {
-  return Boolean(valueArg && tplinkHostnamePatterns.some((patternArg) => patternArg.test(valueArg)));
+const mac = (valueArg: unknown): string | undefined => {
+  const value = text(valueArg);
+  if (value === undefined) return undefined;
+  if (!/^(?:[0-9a-f]{2}[:-]){5}[0-9a-f]{2}$/i.test(value)) throw new TypeError('Invalid TP-Link MAC hint.');
+  return value.replace(/-/g, ':').toLowerCase();
 };
 
-const hasTplinkTextHint = (valueArg: string): boolean => {
-  return tplinkTextHints.some((hintArg) => valueArg.includes(hintArg));
+const literalHost = (hostArg: unknown, addressesArg: unknown): string | undefined => {
+  const host = text(hostArg);
+  if (addressesArg === undefined) return host && plugins.net.isIP(host) ? host : undefined;
+  if (!Array.isArray(addressesArg) || Object.getPrototypeOf(addressesArg) !== Array.prototype ||
+    addressesArg.length > 16 || Reflect.ownKeys(addressesArg).length !== addressesArg.length + 1) {
+    throw new TypeError('TP-Link mDNS addresses must be a bounded dense array.');
+  }
+  const addresses: string[] = [];
+  for (let index = 0; index < addressesArg.length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(addressesArg, String(index));
+    if (!descriptor || !('value' in descriptor) || !descriptor.enumerable) throw new TypeError('TP-Link mDNS addresses accept only data entries.');
+    const address = text(descriptor.value);
+    if (!address || !plugins.net.isIP(address)) throw new TypeError('TP-Link mDNS addresses must be literal IP addresses.');
+    addresses.push(address);
+  }
+  return host && plugins.net.isIP(host) ? host : addresses[0];
 };

package/ts/integrations/tplink/tplink.native.mapper.ts

@@ -0,0 +1,67 @@
+import * as plugins from '../../plugins.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IServiceCallRequest } from '../../core/types.js';
+import type { ITplinkNativeSnapshot } from './tplink.native.types.js';
+import { tplinkKeys, tplinkObject } from './tplink.validation.js';
+
+export class TplinkNativeMapper {
+  public static deviceId(snapshotArg: ITplinkNativeSnapshot): string {
+    return `tplink:${encodeURIComponent(snapshotArg.homeId)}:${encodeURIComponent(snapshotArg.deviceId)}`;
+  }
+
+  public static entityId(snapshotArg: ITplinkNativeSnapshot): string {
+    return `${this.deviceId(snapshotArg)}:power`;
+  }
+
+  public static toDevices(snapshotArg: ITplinkNativeSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    return [{
+      id: this.deviceId(snapshotArg), name: snapshotArg.name || snapshotArg.model,
+      integrationDomain: 'tplink', protocol: 'unknown', manufacturer: 'TP-Link', model: snapshotArg.model,
+      features: [{ id: 'power', name: 'Power', capability: 'switch', readable: true, writable: true }],
+      state: [{ featureId: 'power', value: snapshotArg.power, updatedAt: snapshotArg.observedAt }],
+      online: true,
+      metadata: {
+        homeId: snapshotArg.homeId, protocol: 'legacy-kasa', deviceId: snapshotArg.deviceId,
+        macAddress: snapshotArg.macAddress, softwareVersion: snapshotArg.softwareVersion,
+        hardwareVersion: snapshotArg.hardwareVersion, observedAt: snapshotArg.observedAt,
+      },
+    }];
+  }
+
+  public static toEntities(snapshotArg: ITplinkNativeSnapshot): IIntegrationEntity[] {
+    return [{
+      id: this.entityId(snapshotArg), uniqueId: this.entityId(snapshotArg), integrationDomain: 'tplink',
+      deviceId: this.deviceId(snapshotArg), platform: 'switch', name: snapshotArg.name || snapshotArg.model,
+      state: snapshotArg.power ? 'on' : 'off', available: true,
+      attributes: { homeId: snapshotArg.homeId, protocol: 'legacy-kasa', observedAt: snapshotArg.observedAt },
+    }];
+  }
+
+  public static powerForService(snapshotArg: ITplinkNativeSnapshot, requestArg: IServiceCallRequest): boolean {
+    const request = tplinkObject(requestArg, 'TP-Link service');
+    tplinkKeys(request, ['domain', 'service', 'target', 'data']);
+    if (request.domain !== 'switch' || request.service !== 'turn_on' && request.service !== 'turn_off') {
+      throw new TypeError('TP-Link supports switch.turn_on and switch.turn_off.');
+    }
+    const target = tplinkObject(request.target, 'TP-Link target');
+    tplinkKeys(target, ['deviceId', 'entityId']);
+    if (target.deviceId === undefined && target.entityId === undefined ||
+      target.deviceId !== undefined && target.deviceId !== this.deviceId(snapshotArg) ||
+      target.entityId !== undefined && target.entityId !== this.entityId(snapshotArg)) {
+      throw new TypeError('TP-Link requires an exact owned relay target.');
+    }
+    if (request.data !== undefined) tplinkKeys(tplinkObject(request.data, 'TP-Link service data'), []);
+    return request.service === 'turn_on';
+  }
+
+  public static powerForFeature(snapshotArg: ITplinkNativeSnapshot, requestArg: IDeviceFeatureWriteRequest): boolean {
+    const request = tplinkObject(requestArg, 'TP-Link feature write');
+    tplinkKeys(request, ['device', 'feature', 'value']);
+    const device = tplinkObject(request.device, 'TP-Link feature device');
+    const feature = tplinkObject(request.feature, 'TP-Link feature');
+    if (device.id !== this.deviceId(snapshotArg) || device.integrationDomain !== 'tplink' ||
+      feature.id !== 'power' || typeof request.value !== 'boolean') {
+      throw new TypeError('TP-Link feature writes require the owned power feature and a boolean value.');
+    }
+    return request.value;
+  }
+}

package/ts/integrations/tplink/tplink.native.types.ts

@@ -0,0 +1,32 @@
+export interface ITplinkNativeConfig {
+  homeId: string;
+  transport: 'legacy-kasa';
+  host: string;
+  expectedDeviceId: string;
+  port?: number;
+  timeoutMs?: number;
+  maxResponseBytes?: number;
+  maxPendingOperations?: number;
+}
+
+export interface ITplinkNativeSnapshot {
+  readonly homeId: string;
+  readonly deviceId: string;
+  readonly name: string;
+  readonly model: string;
+  readonly macAddress: string;
+  readonly softwareVersion: string;
+  readonly hardwareVersion: string;
+  readonly power: boolean;
+  readonly observedAt: string;
+}
+
+export interface ITplinkNativeWriteResult {
+  readonly outcome: 'accepted' | 'not-sent' | 'rejected' | 'indeterminate';
+  readonly physicalStateConfirmed: false;
+  readonly deviceId: string;
+  readonly requestedPowerState?: boolean;
+  readonly errorCode?: string;
+}
+
+export type TTplinkNativeEvent = { type: 'state'; snapshot: ITplinkNativeSnapshot };

package/ts/integrations/tplink/tplink.validation.ts

@@ -0,0 +1,50 @@
+import * as plugins from '../../plugins.js';
+import type { ITplinkNativeConfig } from './tplink.native.types.js';
+
+export const tplinkObject = (valueArg: unknown, nameArg: string): Record<string, unknown> => {
+  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg) || Object.getPrototypeOf(valueArg) !== Object.prototype) {
+    throw new TypeError(`${nameArg} must be a plain object.`);
+  }
+  const result: Record<string, unknown> = {};
+  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} accepts only enumerable own data fields.`);
+    }
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true });
+  }
+  return result;
+};
+
+export const tplinkKeys = (valueArg: Record<string, unknown>, allowedArg: readonly string[]): void => {
+  if (Object.keys(valueArg).some((keyArg) => !allowedArg.includes(keyArg))) {
+    throw new TypeError('TP-Link arguments contain unsupported fields.');
+  }
+};
+
+const boundedInteger = (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 normalizeTplinkNativeConfig = (valueArg: ITplinkNativeConfig): Readonly<ITplinkNativeConfig> => {
+  const value = tplinkObject(valueArg, 'TP-Link config');
+  tplinkKeys(value, ['homeId', 'transport', 'host', 'expectedDeviceId', 'port', 'timeoutMs', 'maxResponseBytes', 'maxPendingOperations']);
+  if (typeof value.homeId !== 'string' || value.homeId.length === 0 || value.homeId.length > 256 || /[\p{Cc}\p{Cs}]/u.test(value.homeId)) {
+    throw new TypeError('TP-Link homeId must be a nonempty bounded string without control characters.');
+  }
+  if (value.transport !== 'legacy-kasa') throw new TypeError('TP-Link supports only the explicit legacy-kasa transport.');
+  if (typeof value.host !== 'string' || !plugins.net.isIP(value.host)) throw new TypeError('TP-Link host must be an explicit IP address.');
+  if (typeof value.expectedDeviceId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(value.expectedDeviceId)) {
+    throw new TypeError('TP-Link expectedDeviceId must be an explicit legacy device identity.');
+  }
+  return Object.freeze({
+    homeId: value.homeId, transport: value.transport, host: value.host, expectedDeviceId: value.expectedDeviceId,
+    port: boundedInteger(value.port === undefined ? 9999 : value.port, 'port', 1, 65535),
+    timeoutMs: boundedInteger(value.timeoutMs === undefined ? 5000 : value.timeoutMs, 'timeoutMs', 1, 30000),
+    maxResponseBytes: boundedInteger(value.maxResponseBytes === undefined ? 65536 : value.maxResponseBytes, 'maxResponseBytes', 128, 1048576),
+    maxPendingOperations: boundedInteger(value.maxPendingOperations === undefined ? 16 : value.maxPendingOperations, 'maxPendingOperations', 1, 128),
+  });
+};