@smarthome.exchange/integrations 0.2.0 → 1.0.0

package/ts/integrations/webostv/webostv.classes.integration.ts

@@ -1,17 +1,102 @@
-import { SimpleLocalIntegration } from '../../core/index.js';
+import * as plugins from '../../plugins.js';
+import { BaseIntegration } from '../../core/classes.baseintegration.js';
+import { NoSqlConfigStore } from '../../core/classes.configstore.js';
+import type { IDeviceFeatureWriteRequest, IIntegrationEntity, IIntegrationEvent, IIntegrationRuntime, IIntegrationSetupContext, IServiceCallRequest, IServiceCallResult } from '../../core/types.js';
+import { WebostvClient } from './webostv.classes.client.js';
 import { WebostvConfigFlow } from './webostv.classes.configflow.js';
 import { createWebostvDiscoveryDescriptor } from './webostv.discovery.js';
-import type { IWebostvConfig } from './webostv.types.js';
-import { webostvDomain, webostvProfile } from './webostv.types.js';
+import { WebostvMapper } from './webostv.mapper.js';
+import type { IWebostvConfig, IWebostvIntegrationOptions, IWebostvSnapshot, TWebostvCommand } from './webostv.types.js';
+import { webostvProfile } from './webostv.types.js';
+import { webostvKeys, webostvObject } from './webostv.validation.js';
 
-export class WebostvIntegration extends SimpleLocalIntegration<IWebostvConfig> {
-  public readonly domain = webostvDomain;
+export class WebostvIntegration extends BaseIntegration<IWebostvConfig> {
+  public readonly domain = 'webostv';
+  public readonly displayName = 'LG webOS TV';
+  public readonly status = 'control-runtime' as const;
+  public readonly metadata = webostvProfile.metadata;
   public readonly discoveryDescriptor = createWebostvDiscoveryDescriptor();
   public readonly configFlow = new WebostvConfigFlow();
+  readonly #runtimes = new Set<WebostvRuntime>();
+  readonly #pending = new Set<WebostvClient>();
+  #destroyed = false;
+  #destroy?: Promise<void>;
 
-  constructor() {
-    super(webostvProfile);
+  constructor(private readonly options?: IWebostvIntegrationOptions) { super(); }
+
+  public async setup(configArg: IWebostvConfig, contextArg: IIntegrationSetupContext): Promise<IIntegrationRuntime> {
+    if (this.#destroyed) throw new Error('webOS integration is destroyed.');
+    if (contextArg.configStore !== undefined && !(contextArg.configStore instanceof NoSqlConfigStore)) throw new TypeError('webOS runtime context requires an encrypted NoSqlConfigStore.');
+    const client = new WebostvClient(configArg, contextArg.configStore ?? this.options, contextArg.abortSignal);
+    this.#pending.add(client);
+    try {
+      const snapshot = await client.getSnapshot(contextArg.abortSignal);
+      if (this.#destroyed) throw new Error('webOS integration was destroyed during setup.');
+      const runtime = new WebostvRuntime(client, snapshot, () => this.#runtimes.delete(runtime));
+      this.#runtimes.add(runtime);
+      return runtime;
+    } catch (errorArg) { await client.destroy(); throw errorArg; }
+    finally { this.#pending.delete(client); }
+  }
+
+  public destroy(): Promise<void> {
+    if (this.#destroy) return this.#destroy;
+    this.#destroyed = true;
+    this.#destroy = Promise.all([...this.#runtimes].map((runtimeArg) => runtimeArg.destroy()).concat([...this.#pending].map((clientArg) => clientArg.destroy()))).then(() => undefined);
+    return this.#destroy;
   }
 }
 
 export class HomeAssistantWebostvIntegration extends WebostvIntegration {}
+
+class WebostvRuntime implements IIntegrationRuntime {
+  public readonly domain = 'webostv';
+  constructor(private readonly client: WebostvClient, private readonly identity: IWebostvSnapshot, private readonly onDestroyed: () => void) {}
+  public isHealthy(): boolean { return this.client.isHealthy(); }
+  public async devices(signalArg?: AbortSignal): Promise<plugins.shxInterfaces.data.IDeviceDefinition[]> { return WebostvMapper.toDevices(await this.client.getSnapshot(signalArg)); }
+  public async entities(): Promise<IIntegrationEntity[]> { return WebostvMapper.toEntities(await this.client.getSnapshot()); }
+  public async subscribe(handlerArg: (eventArg: IIntegrationEvent) => void, signalArg?: AbortSignal): Promise<() => Promise<void>> {
+    return this.client.subscribe((eventArg) => {
+      const base = { integrationDomain: this.domain, deviceId: WebostvMapper.deviceId(this.identity), timestamp: Date.now() };
+      if (eventArg.type === 'state') handlerArg({ ...base, type: 'state_changed', entityId: `${base.deviceId}:media_player`, data: { entity: WebostvMapper.toEntities(eventArg.snapshot)[0] } });
+      else if (eventArg.type === 'availability') handlerArg({ ...base, type: 'availability_changed', data: { available: eventArg.available } });
+      else handlerArg({ ...base, type: 'error', data: { message: eventArg.error.message } });
+    }, signalArg);
+  }
+
+  public async callService(requestArg: IServiceCallRequest): Promise<IServiceCallResult> {
+    try {
+      const request = webostvObject(requestArg, 'service request');
+      webostvKeys(request, ['domain', 'service', 'target', 'data']);
+      if (request.domain !== 'webostv' && request.domain !== 'media_player') throw new Error('webOS service domain is unsupported.');
+      const target = webostvObject(request.target, 'service target'); webostvKeys(target, ['deviceId', 'entityId']);
+      const deviceId = WebostvMapper.deviceId(this.identity);
+      if ((target.deviceId !== undefined && target.deviceId !== deviceId) || (target.entityId !== undefined && target.entityId !== `${deviceId}:media_player`) || (target.deviceId === undefined && target.entityId === undefined)) throw new Error('webOS services require an exact owned device or media-player entity target.');
+      const data = request.data === undefined ? {} : webostvObject(request.data, 'service data');
+      const service = request.service;
+      if (typeof service !== 'string') throw new Error('webOS service must be a string.');
+      if (['status', 'snapshot'].includes(service)) { webostvKeys(data, []); return { success: true, data: await this.client.getSnapshot() }; }
+      let argument: unknown;
+      if (service === 'volume_set') { webostvKeys(data, ['volume']); argument = data.volume; }
+      else if (service === 'volume_mute') { webostvKeys(data, ['mute']); argument = data.mute; }
+      else if (service === 'select_source') { webostvKeys(data, ['inputId']); argument = data.inputId; }
+      else webostvKeys(data, []);
+      await this.client.execute(service as TWebostvCommand, argument);
+      return { success: true, data: { acknowledgement: 'tv-response', state: 'observe-subscriptions' } };
+    } catch (errorArg) { return { success: false, error: errorArg instanceof Error ? errorArg.message : 'webOS operation failed.' }; }
+  }
+
+  public async writeFeature(requestArg: IDeviceFeatureWriteRequest, signalArg?: AbortSignal): Promise<IServiceCallResult> {
+    try {
+      const request = webostvObject(requestArg, 'feature write'); webostvKeys(request, ['device', 'feature', 'value']);
+      const device = webostvObject(request.device, 'feature device');
+      const feature = webostvObject(request.feature, 'feature');
+      if (device.id !== WebostvMapper.deviceId(this.identity) || device.integrationDomain !== this.domain) throw new Error('webOS feature device is not owned by this runtime.');
+      if (feature.id === 'volume') await this.client.execute('volume_set', request.value, signalArg);
+      else if (feature.id === 'muted') await this.client.execute('volume_mute', request.value, signalArg);
+      else throw new Error('webOS feature is not writable.');
+      return { success: true, data: { acknowledgement: 'tv-response', state: 'observe-subscriptions' } };
+    } catch (errorArg) { return { success: false, error: errorArg instanceof Error ? errorArg.message : 'webOS feature write failed.' }; }
+  }
+  public async destroy(): Promise<void> { await this.client.destroy(); this.onDestroyed(); }
+}

package/ts/integrations/webostv/webostv.discovery.ts

@@ -1,4 +1,23 @@
-import { createSimpleLocalDiscoveryDescriptor } from '../../core/index.js';
-import { webostvProfile } from './webostv.types.js';
+import { DiscoveryDescriptor } from '../../core/classes.discoverydescriptor.js';
+import type { IDiscoveryCandidate, IDiscoveryMatch } from '../../core/types.js';
+import { webostvKeys, webostvObject, webostvString } from './webostv.validation.js';
 
-export const createWebostvDiscoveryDescriptor = () => createSimpleLocalDiscoveryDescriptor(webostvProfile);
+const admit = (valueArg: unknown): IDiscoveryMatch => {
+  try {
+    const value = webostvObject(valueArg, 'webOS candidate');
+    webostvKeys(value, ['source', 'integrationDomain', 'id', 'host', 'port', 'name', 'manufacturer', 'model', 'serialNumber', 'metadata']);
+    if (value.source !== 'manual' || value.integrationDomain !== 'webostv') throw new Error('Use an explicitly verified manual webOS candidate.');
+    const metadata = webostvObject(value.metadata, 'webOS candidate metadata');
+    webostvKeys(metadata, ['endpoint', 'expectedDeviceUUID']);
+    const endpoint = new URL(webostvString(metadata.endpoint, 'endpoint', 2048));
+    if (!['ws:', 'wss:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.pathname !== '/' || endpoint.search || endpoint.hash) throw new Error('Invalid webOS endpoint origin.');
+    const uuid = webostvString(metadata.expectedDeviceUUID, 'expectedDeviceUUID');
+    const candidate: IDiscoveryCandidate = { source: 'manual', integrationDomain: 'webostv', host: endpoint.hostname, port: Number(endpoint.port || (endpoint.protocol === 'wss:' ? 443 : 80)), id: uuid,
+      name: value.name === undefined ? 'LG webOS TV' : webostvString(value.name, 'TV name'), manufacturer: 'LG', model: 'webOS TV', metadata: { endpoint: endpoint.href, expectedDeviceUUID: uuid } };
+    return { matched: true, confidence: 'high', reason: 'Explicit webOS endpoint and expected identity supplied; native registration verifies the TV.', candidate, normalizedDeviceId: uuid };
+  } catch { return { matched: false, confidence: 'low', reason: 'webOS requires a manual endpoint and independently verified expectedDeviceUUID.' }; }
+};
+
+export const createWebostvDiscoveryDescriptor = (): DiscoveryDescriptor => new DiscoveryDescriptor({ integrationDomain: 'webostv', displayName: 'LG webOS TV' })
+  .addMatcher({ id: 'webostv-manual-match', source: 'manual', matches: async (valueArg: unknown) => admit(valueArg) })
+  .addValidator({ id: 'webostv-identity-validate', validate: async (candidateArg) => admit(candidateArg) });

package/ts/integrations/webostv/webostv.mapper.ts

@@ -1,26 +1,35 @@
-import type * as shxInterfaces from '@smarthome.exchange/interfaces';
-import { SimpleLocalMapper, type IIntegrationEntity, type ISimpleLocalSnapshot, type ISimpleLocalSnapshotOptions, type TSimpleLocalRawData } from '../../core/index.js';
-import type { IWebostvConfig } from './webostv.types.js';
-import { webostvProfile } from './webostv.types.js';
+import * as plugins from '../../plugins.js';
+import type { IIntegrationEntity } from '../../core/types.js';
+import type { IWebostvSnapshot } from './webostv.types.js';
 
 export class WebostvMapper {
-  public static toSnapshot(optionsArg: Omit<ISimpleLocalSnapshotOptions<IWebostvConfig>, 'profile'>): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ ...optionsArg, profile: webostvProfile });
+  public static deviceId(snapshotArg: Pick<IWebostvSnapshot, 'homeId' | 'deviceUUID'>): string {
+    return `webostv:${encodeURIComponent(snapshotArg.homeId)}:${encodeURIComponent(snapshotArg.deviceUUID)}`;
   }
 
-  public static toSnapshotFromRaw(configArg: IWebostvConfig, rawDataArg: TSimpleLocalRawData): ISimpleLocalSnapshot {
-    return SimpleLocalMapper.toSnapshot({ profile: webostvProfile, config: configArg, rawData: rawDataArg, online: true, source: 'manual' });
+  public static toDevices(snapshotArg: IWebostvSnapshot): plugins.shxInterfaces.data.IDeviceDefinition[] {
+    const states: Array<[string, plugins.shxInterfaces.data.TDeviceStateValue]> = [
+      ['power', snapshotArg.powerState], ['volume', snapshotArg.volume], ['muted', snapshotArg.muted], ['current_app', snapshotArg.currentAppId],
+    ];
+    return [{
+      id: this.deviceId(snapshotArg), integrationDomain: 'webostv', name: snapshotArg.name,
+      protocol: 'http', manufacturer: 'LG', model: 'webOS TV', online: snapshotArg.connected,
+      features: [
+        { id: 'power', capability: 'media', name: 'Power state', readable: true, writable: false },
+        { id: 'volume', capability: 'media', name: 'Volume', readable: true, writable: true, unit: '%' },
+        { id: 'muted', capability: 'media', name: 'Muted', readable: true, writable: true },
+        { id: 'current_app', capability: 'media', name: 'Foreground application', readable: true, writable: false },
+      ],
+      state: states.map(([featureId, value]) => ({ featureId, value, updatedAt: snapshotArg.observedAt })),
+      metadata: { homeId: snapshotArg.homeId, deviceUUID: snapshotArg.deviceUUID, transport: 'ssap-websocket', inputs: structuredClone(snapshotArg.inputs) },
+    }];
   }
 
-  public static toDevices(snapshotArg: ISimpleLocalSnapshot): shxInterfaces.data.IDeviceDefinition[] {
-    return SimpleLocalMapper.toDevices(webostvProfile, snapshotArg);
-  }
-
-  public static toEntities(snapshotArg: ISimpleLocalSnapshot): IIntegrationEntity[] {
-    return SimpleLocalMapper.toEntities(webostvProfile, snapshotArg);
-  }
-
-  public static slug(valueArg: unknown): string {
-    return SimpleLocalMapper.slug(valueArg);
+  public static toEntities(snapshotArg: IWebostvSnapshot): IIntegrationEntity[] {
+    const deviceId = this.deviceId(snapshotArg);
+    return [{ id: `${deviceId}:media_player`, uniqueId: `${deviceId}:media_player`, integrationDomain: 'webostv', deviceId,
+      platform: 'media_player', name: snapshotArg.name, state: snapshotArg.powerState, available: snapshotArg.connected,
+      attributes: { volume: snapshotArg.volume, muted: snapshotArg.muted, currentAppId: snapshotArg.currentAppId, inputs: structuredClone(snapshotArg.inputs), observedAt: snapshotArg.observedAt },
+    }];
   }
 }

package/ts/integrations/webostv/webostv.types.ts

@@ -1,105 +1,51 @@
-import type { ISimpleLocalConfig, ISimpleLocalIntegrationProfile, ISimpleLocalSnapshot, TSimpleLocalRawData } from '../../core/index.js';
+import type * as plugins from '../../plugins.js';
+import type { IConfigEncryptionKeyProvider } from '../../core/classes.configstore.js';
 
-export const webostvDomain = "webostv";
-export const webostvDefaultName = "LG webOS TV";
+export const webostvDomain = 'webostv';
+export const webostvDefaultName = 'LG webOS TV';
+
+export interface IWebostvConfig {
+  homeId: string;
+  endpoint: string;
+  /** UUID reported by the verified TV's SSAP hello response. */
+  expectedDeviceUUID: string;
+  name?: string;
+  pairingMode: 'existing' | 'prompt';
+  /** Required acknowledgement for an explicitly selected cleartext local endpoint. */
+  allowUnencryptedConnection?: boolean;
+  certificateAuthority?: string;
+  requestTimeoutMs?: number;
+  pairingTimeoutMs?: number;
+  maxPendingRequests?: number;
+}
+
+export interface IWebostvIntegrationOptions {
+  db: plugins.nosqldb.SmartdataDb;
+  keyProvider: IConfigEncryptionKeyProvider;
+}
 
-export type TWebostvRawData = TSimpleLocalRawData;
-export interface IWebostvSnapshot extends ISimpleLocalSnapshot {}
-export interface IWebostvConfig extends ISimpleLocalConfig {}
 export interface IHomeAssistantWebostvConfig extends IWebostvConfig {}
+export interface IWebostvInput { id: string; label: string; appId: string; connected: boolean; }
+export interface IWebostvSnapshot {
+  homeId: string;
+  deviceUUID: string;
+  name: string;
+  connected: boolean;
+  powerState: string;
+  volume: number;
+  muted: boolean;
+  currentAppId: string;
+  inputs: IWebostvInput[];
+  observedAt: string;
+}
+export type TWebostvRawData = IWebostvSnapshot;
+export type TWebostvClientEvent =
+  | { type: 'state'; snapshot: IWebostvSnapshot }
+  | { type: 'availability'; available: boolean }
+  | { type: 'error'; error: Error };
+export type TWebostvCommand = 'turn_on' | 'turn_off' | 'volume_set' | 'volume_up' | 'volume_down' | 'volume_mute' | 'select_source' | 'media_play' | 'media_pause' | 'media_stop';
 
-export const webostvProfile: ISimpleLocalIntegrationProfile = {
-  domain: "webostv",
-  displayName: "LG webOS TV",
-  manufacturer: "LG",
-  model: "webOS TV",
-  defaultName: "LG webOS TV",
-  defaultPort: 3000,
-  defaultProtocol: "websocket",
-  status: "control-runtime",
-  platforms: [
-    "media_player",
-    "sensor"
-  ],
-  serviceDomains: [
-    "media_player"
-  ],
-  controlServices: [
-    "turn_on",
-    "turn_off",
-    "volume_up",
-    "volume_down",
-    "volume_mute",
-    "select_source",
-    "media_play",
-    "media_pause",
-    "media_stop",
-    "media_next_track",
-    "media_previous_track"
-  ],
-  discoverySources: [
-    "manual",
-    "mdns",
-    "ssdp",
-    "http",
-    "custom"
-  ],
-  discoveryKeywords: [
-    "lg",
-    "webos",
-    "tv"
-  ],
-  metadata: {
-    source: "home-assistant/core",
-    upstreamPath: "homeassistant/components/webostv",
-    upstreamDomain: "webostv",
-    integrationType: "device",
-    iotClass: "local_push",
-    qualityScale: "platinum",
-    requirements: [
-      "aiowebostv==0.7.5"
-    ],
-    dependencies: [],
-    afterDependencies: [],
-    codeowners: [
-      "@thecode"
-    ],
-    configFlow: true,
-    runtime: {
-      type: "control-runtime",
-      services: [
-        "snapshot",
-        "status",
-        "refresh",
-        "turn_on",
-        "turn_off",
-        "volume_up",
-        "volume_down",
-        "volume_mute",
-        "select_source",
-        "media_play",
-        "media_pause",
-        "media_stop",
-        "media_next_track",
-        "media_previous_track"
-      ],
-      platforms: [
-        "media_player",
-        "sensor"
-      ],
-      controls: true
-    },
-    localApi: {
-      implemented: [
-        "manual local endpoint setup",
-        "snapshot, raw data, snapshotProvider, and injected native client operation",
-        "generic HTTP/TCP local transport when config.path, config.transport, or documented defaults are supplied"
-      ],
-      explicitUnsupported: [
-        "claiming live command success without injected client.execute or commandExecutor",
-        "cloud account flows and remote API polling",
-        "device-specific protocol features not represented by snapshot/rawData/client/executor inputs"
-      ]
-    }
-  }
-};
+export const webostvProfile = {
+  domain: webostvDomain, displayName: webostvDefaultName, status: 'control-runtime',
+  metadata: { source: 'home-assistant/core', upstreamDomain: webostvDomain, localApi: { implemented: ['verified SSAP registration', 'encrypted durable pairing keys', 'authoritative state subscriptions'], explicitUnsupported: ['fixture or injected-client production configs', 'deep standby wake-on-LAN', 'next/previous media track', 'automatic command replay'] } },
+} as const;

package/ts/integrations/webostv/webostv.validation.ts

@@ -0,0 +1,48 @@
+import type { IWebostvConfig } from './webostv.types.js';
+
+export const webostvObject = (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> = {};
+  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.`);
+    Object.defineProperty(result, key, { value: descriptor.value, enumerable: true, writable: true, configurable: true });
+  }
+  return result;
+};
+
+export const webostvKeys = (valueArg: Record<string, unknown>, keysArg: readonly string[]): void => {
+  if (Object.keys(valueArg).some((keyArg) => !keysArg.includes(keyArg))) throw new TypeError('webOS arguments contain unsupported fields.');
+};
+
+export const webostvString = (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 webostvInteger = (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 normalizeWebostvConfig = (valueArg: IWebostvConfig): Readonly<IWebostvConfig> => {
+  const value = webostvObject(valueArg, 'webOS config');
+  webostvKeys(value, ['homeId', 'endpoint', 'expectedDeviceUUID', 'name', 'pairingMode', 'allowUnencryptedConnection', 'certificateAuthority', 'requestTimeoutMs', 'pairingTimeoutMs', 'maxPendingRequests']);
+  const endpoint = new URL(webostvString(value.endpoint, 'endpoint', 2048));
+  if (!['ws:', 'wss:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.pathname !== '/' || endpoint.search || endpoint.hash || !endpoint.hostname) throw new TypeError('webOS endpoint must be an explicit ws/wss origin without credentials, path, query or fragment.');
+  if (value.allowUnencryptedConnection !== undefined && typeof value.allowUnencryptedConnection !== 'boolean') throw new TypeError('allowUnencryptedConnection must be boolean.');
+  if (endpoint.protocol === 'ws:' && value.allowUnencryptedConnection !== true) throw new TypeError('A cleartext webOS endpoint requires allowUnencryptedConnection: true.');
+  if (endpoint.protocol === 'ws:' && value.certificateAuthority !== undefined) throw new TypeError('A certificate authority requires wss.');
+  if (value.pairingMode !== 'existing' && value.pairingMode !== 'prompt') throw new TypeError('webOS pairingMode must be existing or prompt.');
+  if (value.certificateAuthority !== undefined && (typeof value.certificateAuthority !== 'string' || value.certificateAuthority.length > 65536 || !value.certificateAuthority.includes('-----BEGIN CERTIFICATE-----'))) throw new TypeError('certificateAuthority must be a bounded PEM certificate chain.');
+  return Object.freeze({
+    homeId: webostvString(value.homeId, 'homeId'), endpoint: endpoint.href,
+    expectedDeviceUUID: webostvString(value.expectedDeviceUUID, 'expectedDeviceUUID'),
+    name: value.name === undefined ? 'LG webOS TV' : webostvString(value.name, 'name'),
+    pairingMode: value.pairingMode, allowUnencryptedConnection: value.allowUnencryptedConnection,
+    certificateAuthority: value.certificateAuthority as string | undefined,
+    requestTimeoutMs: webostvInteger(value.requestTimeoutMs ?? 5000, 'requestTimeoutMs', 20, 60000),
+    pairingTimeoutMs: webostvInteger(value.pairingTimeoutMs ?? 30000, 'pairingTimeoutMs', 20, 120000),
+    maxPendingRequests: webostvInteger(value.maxPendingRequests ?? 32, 'maxPendingRequests', 1, 128),
+  });
+};

package/ts/integrations/wled/index.ts

@@ -2,5 +2,6 @@ export * from './wled.classes.client.js';
 export * from './wled.classes.configflow.js';
 export * from './wled.classes.integration.js';
 export * from './wled.discovery.js';
+export * from './wled.errors.js';
 export * from './wled.mapper.js';
 export * from './wled.types.js';

package/ts/integrations/wled/readme.md

@@ -0,0 +1,83 @@
+# Native WLED integration
+
+The WLED integration connects directly to a controller’s JSON HTTP API and receives authoritative state changes through its `/ws` websocket endpoint. Controller MAC addresses define stable device and entity identities.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Setup and control
+
+```typescript
+import { WledIntegration } from '@smarthome.exchange/integrations';
+
+const integration = new WledIntegration();
+const runtime = await integration.setup({
+  host: 'wled-desk.local',
+  expectedMac: 'aabbcc112233',
+  requestTimeoutMs: 5000,
+}, {});
+
+try {
+  const device = (await runtime.devices())[0];
+  const result = await runtime.callService!({
+    domain: 'light',
+    service: 'turn_on',
+    target: { deviceId: device.id },
+    data: { brightness: 128 },
+  });
+  if (!result.success) throw new Error(result.error);
+} finally {
+  await integration.destroy();
+}
+```
+
+`host` is a hostname or IP address, with optional `port` (default 80), `expectedMac`, and `requestTimeoutMs` (10–60000 ms). Config flow verifies the live JSON response and returns a configuration with its MAC pinned. Explicit unsupported settings are rejected, including credentials, alternate paths, TLS, snapshots, injected executors, and raw data. WLED itself provides neither API authentication nor native TLS; admission and home authorization remain the hub’s responsibility.
+
+Discovery admits manual entries explicitly marked `integrationDomain: 'wled'` and `_wled._tcp` mDNS records with valid `mac` TXT metadata. It copies endpoint fields only. It does not scan the network, trust an `esp32` name, fetch SSDP locations, or copy arbitrary candidate metadata into configuration.
+
+The device id is `wled.device.<mac>`. The controller entity is `light.wled_<mac>`, and an active segment’s entity is `light.wled_<mac>_segment_<id>`. Renaming a controller or segment preserves its identity. Exact entity targets select one segment; exact device targets select controller power and brightness. An entity and device target supplied together must refer to the same controller.
+
+| Service | Accepted data |
+| --- | --- |
+| `light.turn_on` | Optional `brightness`, `rgb_color`, `white`; colors require a segment target |
+| `light.turn_off` | No data |
+| `light.set_level` | Required integer `brightness` from 1 to 255 |
+| `light.set_color` | `rgb_color: [r, g, b]` and/or integer `white` from 0 to 255; requires a segment target |
+
+RGB controls appear only when `info.leds.seglc[id]` advertises RGB support. White controls additionally require an advertised white channel and a four-channel primary color. Each color channel is an integer from 0 to 255. RGB writes preserve the current white value; white writes preserve the current RGB values. Secondary and tertiary colors, other segments, effects and palettes are preserved. Firmware lacking capability metadata still exposes power and brightness, and rejects unverified color controls.
+
+`writeFeature()` accepts controller `power` and `brightness`, and segment `segment_<id>_power`, `segment_<id>_brightness`, `segment_<id>_rgb` (`#rrggbb`), and `segment_<id>_white` when advertised. It verifies the actual connected device and current capability rather than trusting caller-supplied feature flags.
+
+## State and lifecycle
+
+HTTP reads use `/json/si`. Writes use one POST to `/json/state`, followed by a fresh authoritative read. Each write sends the documented per-call `udpn.nn: true` flag to prevent UDP synchronization from changing other controllers. This does not change the controller’s persistent synchronization configuration. A firmware acknowledgement means API acceptance; it does not establish physical LED output. Writes are serialized, with at most 32 queued operations, and have a deadline covering queue wait, identity verification, acknowledgement and final state read. There are no automatic retries or optimistic state updates. A failure after attempting a POST returns `data.effectOutcome: 'indeterminate'`, and a `WledClient` caller receives `WledWriteError`; callers must reconcile the controller before deciding on a new action.
+
+`runtime.subscribe()` owns one receive-only websocket shared by subscribers. Full state and info pushes update entities, including segment addition and removal. The connection must provide a valid initial state before subscription succeeds. Malformed data, changed MAC identity, disconnects, and deadlines invalidate availability and close the socket. There is no automatic reconnect or polling fallback. Call `subscribe()` explicitly again to establish a new connection. Builds reporting `info.ws: -1` reject websocket subscriptions.
+
+Setup context cancellation closes all owned work. Per-operation signals cancel reads and feature writes. Removing the last subscriber terminates and drains its websocket, including an incomplete HTTP upgrade. `destroy()` aborts queued and active requests, drains the owned socket, and permanently closes the client or integration. Failed callbacks are unsubscribed without disrupting other subscribers. HTTP redirects are rejected, HTTP and websocket payloads are bounded to 1 MiB, and errors do not include raw device response bodies.
+
+Effects, palettes, presets, relative/toggle commands, nightlight, CCT, segment geometry, firmware/configuration writes, realtime frames and UDP synchronization are outside this native port. No real controller was used for verification; local HTTP and websocket fixtures cover the supported contract.
+
+Protocol references: [WLED JSON API](https://kno.wled.ge/interfaces/json-api/), [WLED websocket API](https://kno.wled.ge/interfaces/websocket/), and [official WLED mDNS advertisements](https://github.com/wled/WLED/blob/main/wled00/wled.cpp).
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [repository license file](../../../license.md).
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and are not included within the scope of the MIT license granted herein.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.