@smarthome.exchange/integrations 1.0.0 → 3.0.0

package/ts/integrations/broadlink/broadlink.classes.client.ts

@@ -1,167 +1,193 @@
-import type {
-  IBroadlinkCommand,
-  IBroadlinkCommandResult,
-  IBroadlinkConfig,
-  IBroadlinkEvent,
-  IBroadlinkPacket,
-  IBroadlinkSnapshot,
-} from './broadlink.types.js';
-import { BroadlinkMapper } from './broadlink.mapper.js';
-import {
-  broadlinkIrPacketFromTimings,
-  broadlinkPacketFromBase64,
-  broadlinkPacketFromHex,
-  broadlinkRfPacketFromTimings,
-} from './broadlink.packet.js';
-
-type TBroadlinkEventHandler = (eventArg: IBroadlinkEvent) => void;
+import * as plugins from '../../plugins.js';
+import type { NoSqlConfigStore } from '../../core/classes.configstore.js';
+import { NativeHomeAdmission } from '../../core/classes.nativehomeadmission.js';
+import type { INativeIntegrationSetupContext } from '../../core/types.js';
+import { readBroadlinkActions } from './broadlink.actions.js';
+import { broadlinkConfigKey, broadlinkRecord, readBroadlinkSelection,
+  sameBroadlinkSelection } from './broadlink.validation.js';
+import { broadlinkIrPacketFromTimings, broadlinkPacketFromBase64, broadlinkPacketFromHex,
+  broadlinkRfPacketFromTimings } from './broadlink.packet.js';
+import type { IBroadlinkConfig, IBroadlinkIrAction, IBroadlinkPacket, IBroadlinkSelectedSnapshot,
+  IBroadlinkSelection } from './broadlink.types.js';
 
 export class BroadlinkClient {
-  private snapshot?: IBroadlinkSnapshot;
-  private readonly events: IBroadlinkEvent[] = [];
-  private readonly eventHandlers = new Set<TBroadlinkEventHandler>();
-
-  constructor(private readonly config: IBroadlinkConfig) {}
-
-  public async getSnapshot(): Promise<IBroadlinkSnapshot> {
-    this.snapshot = BroadlinkMapper.toSnapshot(this.config, undefined, this.events);
-    return this.cloneSnapshot(this.snapshot);
-  }
-
-  public onEvent(handlerArg: TBroadlinkEventHandler): () => void {
-    this.eventHandlers.add(handlerArg);
-    return () => this.eventHandlers.delete(handlerArg);
-  }
-
-  public async refresh(): Promise<IBroadlinkSnapshot> {
-    this.snapshot = BroadlinkMapper.toSnapshot(this.config, this.config.connected, this.events);
-    this.emit({ type: 'snapshot_refreshed', data: this.cloneSnapshot(this.snapshot), timestamp: Date.now() });
-    return this.cloneSnapshot(this.snapshot);
-  }
-
-  public async sendCommand(commandArg: IBroadlinkCommand): Promise<IBroadlinkCommandResult> {
-    this.emit({ type: 'command_mapped', command: commandArg, deviceId: commandArg.deviceId, entityId: commandArg.entityId, timestamp: Date.now() });
-
-    if (commandArg.type === 'delete_command') {
-      const result = this.deleteCommand(commandArg);
-      this.emit({ type: result.success ? 'command_deleted' : 'command_failed', command: commandArg, deviceId: commandArg.deviceId, entityId: commandArg.entityId, data: result, timestamp: Date.now() });
-      return result;
+  readonly #selection: IBroadlinkSelection;
+  readonly #store?: NoSqlConfigStore;
+  readonly #protocol: plugins.ecobridgeDeviceManager.BroadlinkProtocol;
+  readonly #lifetime = new AbortController();
+  readonly #pending = new Set<Promise<unknown>>();
+  readonly #packets = new Map<string, Buffer>();
+  readonly #setupSignal?: AbortSignal;
+  #actions?: ReadonlyArray<Readonly<IBroadlinkIrAction>>;
+  #snapshot?: IBroadlinkSelectedSnapshot;
+  #initialization?: Promise<void>;
+  #closePromise?: Promise<void>;
+  #retryPromise?: Promise<void>;
+
+  constructor(configArg: IBroadlinkConfig, contextArg: INativeIntegrationSetupContext) {
+    const config = broadlinkRecord(configArg, ['homeId', 'host', 'macAddress', 'deviceType', 'port',
+      'localAddress', 'timeoutMs', 'maxPendingOperations', 'name', 'actions']);
+    this.#selection = readBroadlinkSelection(config);
+    this.#actions = config.actions === undefined ? undefined : readBroadlinkActions(config.actions);
+    const context = new NativeHomeAdmission('broadlink').admit(contextArg, this.#selection.homeId);
+    this.#store = context.configStore;
+    if (!this.#actions && !this.#store) {
+      throw new TypeError('Broadlink action restoration requires an initialized encrypted NoSqlConfigStore.');
     }
-
-    if (commandArg.type === 'remote_turn_on' || commandArg.type === 'remote_turn_off') {
-      const result: IBroadlinkCommandResult = { success: true, transmitted: false, data: { command: commandArg, reason: 'Remote entity enable state is local runtime state only.' } };
-      this.emit({ type: 'command_executed', command: commandArg, deviceId: commandArg.deviceId, entityId: commandArg.entityId, data: result, timestamp: Date.now() });
-      return result;
-    }
-
-    const executor = this.config.commandExecutor || this.config.transport?.execute.bind(this.config.transport);
-    if (!executor) {
-      const result: IBroadlinkCommandResult = {
-        success: false,
-        transmitted: false,
-        error: this.unsupportedLiveControlMessage(),
-        data: { command: commandArg },
-      };
-      this.emit({ type: 'command_failed', command: commandArg, deviceId: commandArg.deviceId, entityId: commandArg.entityId, data: result, timestamp: Date.now() });
-      return result;
-    }
-
-    try {
-      const result = this.commandResult(await executor(commandArg), commandArg);
-      if (result.success) {
-        this.patchSnapshot(commandArg);
+    this.#setupSignal = context.abortSignal;
+    this.#setupSignal?.throwIfAborted();
+    this.#protocol = new plugins.ecobridgeDeviceManager.BroadlinkProtocol({
+      host: this.#selection.host, port: this.#selection.port, macAddress: this.#selection.macAddress,
+      deviceType: this.#selection.deviceType, localAddress: this.#selection.localAddress,
+      timeoutMs: this.#selection.timeoutMs, maxPendingOperations: this.#selection.maxPendingOperations,
+    });
+  }
+
+  public get selection(): IBroadlinkSelection { return this.#selection; }
+  public get currentSnapshot(): IBroadlinkSelectedSnapshot {
+    if (!this.#snapshot) throw new Error('Broadlink has no verified bridge observation.');
+    return this.#snapshot;
+  }
+  public isHealthy(): boolean { return !this.#lifetime.signal.aborted && this.#protocol.isReady && this.#snapshot?.available === true; }
+
+  public initialize(): Promise<void> {
+    if (!this.#initialization) this.#initialization = this.initializeSelected();
+    return this.#initialization;
+  }
+
+  private async initializeSelected(): Promise<void> {
+    try { await this.track(() => this.loadAndStart()); }
+    catch (error) {
+      this.#lifetime.abort(new Error('Broadlink setup failed.'));
+      if (this.#snapshot) this.#snapshot = Object.freeze({ ...this.#snapshot, available: false });
+      try { await this.closeAndDrain(); }
+      catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], 'Broadlink setup and cleanup failed.', { cause: error });
       }
-      this.emit({ type: result.success ? 'command_executed' : 'command_failed', command: commandArg, deviceId: commandArg.deviceId, entityId: commandArg.entityId, data: result, timestamp: Date.now() });
-      return result;
-    } catch (errorArg) {
-      const result: IBroadlinkCommandResult = {
-        success: false,
-        transmitted: false,
-        error: errorArg instanceof Error ? errorArg.message : String(errorArg),
-        data: { command: commandArg },
-      };
-      this.emit({ type: 'command_failed', command: commandArg, deviceId: commandArg.deviceId, entityId: commandArg.entityId, data: result, timestamp: Date.now() });
-      return result;
+      throw error;
     }
   }
 
-  public async destroy(): Promise<void> {
-    this.eventHandlers.clear();
-  }
-
-  public static packetFromBase64(valueArg: string): IBroadlinkPacket {
-    return broadlinkPacketFromBase64(valueArg);
-  }
-
-  public static packetFromHex(valueArg: string): IBroadlinkPacket {
-    return broadlinkPacketFromHex(valueArg);
-  }
-
-  public static irPacketFromTimings(timingsArg: number[]): IBroadlinkPacket {
-    return broadlinkIrPacketFromTimings(timingsArg);
-  }
-
-  public static rfPacketFromTimings(optionsArg: { frequency: number; timings: number[]; repeatCount?: number }): IBroadlinkPacket {
-    return broadlinkRfPacketFromTimings(optionsArg);
-  }
-
-  private emit(eventArg: IBroadlinkEvent): void {
-    this.events.push(eventArg);
-    for (const handler of this.eventHandlers) {
-      handler(eventArg);
+  private async loadAndStart(): Promise<void> {
+    const signal = this.operationSignal(this.#setupSignal);
+    signal.throwIfAborted();
+    const supplied = this.#actions !== undefined;
+    if (!supplied) {
+      if (!this.#store) throw new TypeError('Broadlink action restoration requires an initialized encrypted NoSqlConfigStore.');
+      const value = await this.#store.get<unknown>(broadlinkConfigKey(this.#selection));
+      if (value === undefined) throw new Error('Broadlink has no encrypted owner action configuration for this bridge.');
+      const stored = broadlinkRecord(value, ['version', 'selection', 'actions']);
+      if (stored.version !== 1 || !sameBroadlinkSelection(this.#selection, readBroadlinkSelection(stored.selection))) {
+        throw new Error('Stored Broadlink configuration does not match the selected home and bridge.');
+      }
+      this.#actions = readBroadlinkActions(stored.actions);
     }
+    signal.throwIfAborted();
+    for (const action of this.#actions!) this.#packets.set(action.id, Buffer.from(action.packetBase64, 'base64'));
+    await this.#protocol.start({ signal });
+    const firmware = await this.#protocol.readFirmware({ signal });
+    signal.throwIfAborted();
+    this.#snapshot = Object.freeze({ selection: this.#selection, available: true, firmwareVersion: firmware.version,
+      observedAt: new Date().toISOString(), actions: Object.freeze(this.#actions!.map((actionArg) =>
+        Object.freeze({ id: actionArg.id, name: actionArg.name }))) });
+    if (supplied && this.#store) await this.#store.set(broadlinkConfigKey(this.#selection), {
+      version: 1, selection: this.#selection, actions: this.#actions,
+    });
+    signal.throwIfAborted();
+    this.#actions = undefined;
+  }
+
+  public getSnapshot(signalArg?: AbortSignal): Promise<IBroadlinkSelectedSnapshot> {
+    return this.track(async () => {
+      const signal = this.operationSignal(signalArg);
+      signal.throwIfAborted();
+      try {
+        const firmware = await this.#protocol.readFirmware({ signal });
+        signal.throwIfAborted();
+        this.#snapshot = Object.freeze({ ...this.currentSnapshot, firmwareVersion: firmware.version,
+          available: true, observedAt: new Date().toISOString() });
+        return this.#snapshot;
+      } catch (error) {
+        if (this.#snapshot) this.#snapshot = Object.freeze({ ...this.#snapshot, available: false });
+        throw error;
+      }
+    });
+  }
+
+  public sendAction(actionIdArg: string, signalArg?: AbortSignal): Promise<plugins.ecobridgeDeviceManager.IBroadlinkIrReceipt> {
+    return this.track(async () => {
+      const signal = this.operationSignal(signalArg);
+      if (signal.aborted) throw new plugins.ecobridgeDeviceManager.BroadlinkProtocolError('ABORTED', 'Broadlink action was aborted.');
+      const packet = this.#packets.get(actionIdArg);
+      if (!packet || !this.isHealthy()) throw new plugins.ecobridgeDeviceManager.BroadlinkProtocolError('NOT_STARTED',
+        'Broadlink action is unknown or the selected bridge is unavailable.');
+      try { return await this.#protocol.sendIr(packet, { signal }); }
+      catch (error) {
+        if (this.#protocol.isClosed && this.#snapshot) this.#snapshot = Object.freeze({ ...this.#snapshot, available: false });
+        throw error;
+      }
+    });
+  }
+
+  /** Terminal and memoized. The caller owns its store/database. */
+  public destroy(): Promise<void> {
+    if (!this.#closePromise) {
+      const closing = Promise.withResolvers<void>();
+      this.#closePromise = closing.promise;
+      this.#lifetime.abort(new Error('Broadlink client is closed.'));
+      if (this.#snapshot) this.#snapshot = Object.freeze({ ...this.#snapshot, available: false });
+      void (async () => {
+        const [closed] = await Promise.allSettled([this.closeAndDrain(), this.#initialization]);
+        if (closed.status === 'rejected') throw closed.reason;
+      })().then(closing.resolve, closing.reject);
+    }
+    return this.#closePromise;
   }
 
-  private commandResult(resultArg: unknown, commandArg: IBroadlinkCommand): IBroadlinkCommandResult {
-    if (this.isCommandResult(resultArg)) {
-      return { transmitted: true, ...resultArg };
+  /** Explicitly retries retained cleanup without reopening or replaying bridge operations. */
+  public retryCleanup(): Promise<void> {
+    if (!this.#closePromise) return this.destroy();
+    if (!this.#retryPromise) {
+      const retry = this.#closePromise.then(() => undefined, () => this.closeAndDrain());
+      this.#retryPromise = retry;
+      void retry.then(() => {}, () => { if (this.#retryPromise === retry) this.#retryPromise = undefined; });
     }
-    return { success: true, transmitted: true, data: resultArg ?? { command: commandArg } };
+    return this.#retryPromise;
   }
 
-  private isCommandResult(valueArg: unknown): valueArg is IBroadlinkCommandResult {
-    return typeof valueArg === 'object' && valueArg !== null && 'success' in valueArg;
+  private async closeAndDrain(): Promise<void> {
+    // Startup tracks only its admitted work, so its cleanup cannot join itself.
+    const [closed] = await Promise.allSettled([
+      Promise.resolve().then(() => this.#protocol.close()),
+      ...this.#pending,
+    ]);
+    this.releasePackets();
+    this.#actions = undefined;
+    if (closed.status === 'rejected') throw closed.reason;
   }
 
-  private deleteCommand(commandArg: IBroadlinkCommand): IBroadlinkCommandResult {
-    const remoteDevice = commandArg.remoteDevice;
-    if (!remoteDevice || !commandArg.commandNames?.length) {
-      return { success: false, transmitted: false, error: 'Broadlink delete_command requires data.device and data.command.' };
-    }
-    const devices = this.config.snapshot?.devices || this.config.devices || [];
-    const targetDevice = devices.find((deviceArg) => BroadlinkMapper.deviceId(deviceArg) === commandArg.deviceId || deviceArg.id === commandArg.deviceId) || devices[0];
-    const codes = targetDevice?.codes || this.config.codes;
-    if (!codes?.[remoteDevice]) {
-      return { success: false, transmitted: false, error: `Broadlink learned-code device not found: ${remoteDevice}.` };
-    }
-    for (const command of commandArg.commandNames) {
-      delete codes[remoteDevice][command];
-    }
-    if (!Object.keys(codes[remoteDevice]).length) {
-      delete codes[remoteDevice];
-    }
-    return { success: true, transmitted: false, data: { command: commandArg } };
+  private operationSignal(signalArg?: AbortSignal): AbortSignal {
+    if (signalArg !== undefined && !(signalArg instanceof AbortSignal)) throw new TypeError('Broadlink cancellation requires an AbortSignal.');
+    return signalArg ? AbortSignal.any([signalArg, this.#lifetime.signal]) : this.#lifetime.signal;
   }
 
-  private patchSnapshot(commandArg: IBroadlinkCommand): void {
-    const snapshot = this.snapshot;
-    if (!snapshot || !commandArg.deviceId || !commandArg.payload) {
-      return;
-    }
-    const device = snapshot.devices.find((deviceArg) => BroadlinkMapper.deviceId(deviceArg) === commandArg.deviceId || deviceArg.id === commandArg.deviceId);
-    if (!device) {
-      return;
-    }
-    device.state = { ...(device.state || {}), ...commandArg.payload };
-    device.available = true;
-    device.updatedAt = new Date().toISOString();
+  private releasePackets(): void {
+    for (const packet of this.#packets.values()) packet.fill(0);
+    this.#packets.clear();
   }
 
-  private cloneSnapshot(snapshotArg: IBroadlinkSnapshot): IBroadlinkSnapshot {
-    return JSON.parse(JSON.stringify(snapshotArg)) as IBroadlinkSnapshot;
+  private track<TValue>(operationArg: () => Promise<TValue>): Promise<TValue> {
+    const operation = Promise.resolve().then(operationArg);
+    this.#pending.add(operation);
+    void operation.then(() => this.#pending.delete(operation), () => this.#pending.delete(operation));
+    return operation;
   }
 
-  private unsupportedLiveControlMessage(): string {
-    return 'Broadlink live UDP/auth transport is not implemented in this dependency-free TypeScript port. Commands are mapped explicitly but not transmitted unless commandExecutor or transport.execute is provided.';
+  /** These pure helpers do not validate a packet for native runtime admission. */
+  public static packetFromBase64(valueArg: string): IBroadlinkPacket { return broadlinkPacketFromBase64(valueArg); }
+  public static packetFromHex(valueArg: string): IBroadlinkPacket { return broadlinkPacketFromHex(valueArg); }
+  public static irPacketFromTimings(timingsArg: number[]): IBroadlinkPacket { return broadlinkIrPacketFromTimings(timingsArg); }
+  public static rfPacketFromTimings(optionsArg: { frequency: number; timings: number[]; repeatCount?: number }): IBroadlinkPacket {
+    return broadlinkRfPacketFromTimings(optionsArg);
   }
 }

package/ts/integrations/broadlink/broadlink.classes.configflow.ts

@@ -1,99 +1,69 @@
+import { NativeIntegrationOwner, type NativeIntegrationScope } from '../../core/classes.nativeintegrationowner.js';
 import type { IConfigFlow, IConfigFlowContext, IConfigFlowStep, IDiscoveryCandidate } from '../../core/types.js';
-import { broadlinkDefaultPort, broadlinkDefaultTimeoutSeconds } from './broadlink.constants.js';
-import type { IBroadlinkConfig, IBroadlinkSnapshot, TBroadlinkDeviceType } from './broadlink.types.js';
+import { readBroadlinkActions } from './broadlink.actions.js';
+import { broadlinkConfigKey, broadlinkRecord, readBroadlinkSelection } from './broadlink.validation.js';
+import type { IBroadlinkConfig } from './broadlink.types.js';
 
 export class BroadlinkConfigFlow implements IConfigFlow<IBroadlinkConfig> {
-  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IBroadlinkConfig>> {
-    void contextArg;
-    const metadata = candidateArg.metadata || {};
-    const host = candidateArg.host || this.stringValue(metadata.host) || '';
-    const deviceType = candidateArg.model || this.stringValue(metadata.deviceType) || '';
-    const name = candidateArg.name || this.stringValue(metadata.name) || '';
-
-    return {
-      kind: 'form',
-      title: 'Connect Broadlink device',
-      description: 'Provide the local host and device identity. This TypeScript port maps snapshots and commands, and requires an injected executor for live Broadlink UDP/auth traffic.',
-      fields: [
-        { name: 'host', label: host ? `Host (${host})` : 'Host', type: 'text', required: true },
-        { name: 'port', label: `Port (${candidateArg.port || broadlinkDefaultPort})`, type: 'number' },
-        { name: 'timeout', label: `Timeout seconds (${broadlinkDefaultTimeoutSeconds})`, type: 'number' },
-        { name: 'name', label: name ? `Name (${name})` : 'Name', type: 'text' },
-        { name: 'type', label: deviceType ? `Device type (${deviceType})` : 'Device type', type: 'text' },
-        { name: 'macAddress', label: candidateArg.macAddress ? `MAC (${candidateArg.macAddress})` : 'MAC address', type: 'text' },
-        { name: 'snapshotJson', label: 'Snapshot JSON', type: 'text' },
-      ],
-      submit: async (valuesArg) => this.submit(candidateArg, valuesArg),
-    };
-  }
-
-  private async submit(candidateArg: IDiscoveryCandidate, valuesArg: Record<string, unknown>): Promise<IConfigFlowStep<IBroadlinkConfig>> {
-    const snapshot = this.snapshotFromInput(valuesArg.snapshotJson);
-    if (snapshot instanceof Error) {
-      return { kind: 'error', title: 'Invalid snapshot', error: snapshot.message };
-    }
-
-    const host = this.stringValue(valuesArg.host) || candidateArg.host || snapshot?.host;
-    if (!host && !snapshot) {
-      return { kind: 'error', title: 'Host required', error: 'Broadlink setup requires a host unless a config is created directly from a snapshot.' };
-    }
+  readonly #scope: NativeIntegrationScope;
 
-    const metadata = candidateArg.metadata || {};
-    const config: IBroadlinkConfig = {
-      host,
-      port: this.numberValue(valuesArg.port) || candidateArg.port || snapshot?.port || broadlinkDefaultPort,
-      timeout: this.numberValue(valuesArg.timeout) || this.numberValue(metadata.timeout) || broadlinkDefaultTimeoutSeconds,
-      name: this.stringValue(valuesArg.name) || candidateArg.name,
-      macAddress: this.stringValue(valuesArg.macAddress) || candidateArg.macAddress,
-      deviceId: candidateArg.id,
-      type: (this.stringValue(valuesArg.type) || this.stringValue(metadata.deviceType) || candidateArg.model) as TBroadlinkDeviceType | undefined,
-      devtype: this.numberValue(metadata.devtype),
-      model: candidateArg.model,
-      manufacturer: candidateArg.manufacturer || 'Broadlink',
-      isLocked: metadata.isLocked === true,
-      snapshot,
-      metadata: {
-        discoverySource: candidateArg.source,
-        discoveryMetadata: metadata,
-        liveUdpAuthImplemented: false,
-      },
-    };
-
-    return {
-      kind: 'done',
-      title: 'Broadlink device configured',
-      config,
-    };
+  constructor(scopeArg?: NativeIntegrationScope) {
+    this.#scope = scopeArg ?? new NativeIntegrationOwner('broadlink').createFlowScope();
   }
 
-  private snapshotFromInput(valueArg: unknown): IBroadlinkSnapshot | undefined | Error {
-    const text = this.stringValue(valueArg);
-    if (!text) {
-      return undefined;
-    }
+  public async start(candidateArg: IDiscoveryCandidate, contextArg: IConfigFlowContext): Promise<IConfigFlowStep<IBroadlinkConfig>> {
     try {
-      const parsed = JSON.parse(text) as IBroadlinkSnapshot;
-      if (!parsed || !Array.isArray(parsed.devices)) {
-        return new Error('Snapshot JSON must include a devices array.');
-      }
-      return parsed;
-    } catch (errorArg) {
-      return errorArg instanceof Error ? errorArg : new Error(String(errorArg));
-    }
+      const context = this.#scope.admit(contextArg);
+      return await this.#scope.run<IConfigFlowStep<IBroadlinkConfig>>(context, undefined, async (leaseArg) => {
+        leaseArg.assertOpen();
+        const host = candidateArg.host;
+        const macAddress = candidateArg.macAddress;
+        const candidateType = candidateArg.metadata?.devtype;
+        const name = candidateArg.name;
+        return {
+          kind: 'form', title: 'Select Broadlink IR bridge',
+          description: 'Select one RM mini 3 or RM4 mini on a trusted local network and provide owner-approved native IR action packets. Bridge acceptance cannot confirm appliance effects.',
+          fields: [
+            { name: 'host', label: host ? `Private IPv4 (${host})` : 'Private IPv4', type: 'text', required: true },
+            { name: 'macAddress', label: macAddress ? `MAC (${macAddress})` : 'Exact MAC', type: 'text', required: true },
+            { name: 'deviceType', label: 'Exact bridge type', type: 'select', required: true,
+              options: [{ label: 'RM mini 3 (0x2737)', value: '0x2737' }, { label: 'RM4 mini (0x51da)', value: '0x51da' }] },
+            { name: 'name', label: name ? `Name (${name})` : 'Bridge name', type: 'text' },
+            { name: 'port', label: 'UDP port (80)', type: 'number' },
+            { name: 'localAddress', label: 'Local private IPv4 interface (optional)', type: 'text' },
+            { name: 'timeoutMs', label: 'Operation timeout milliseconds (5000)', type: 'number' },
+            { name: 'maxPendingOperations', label: 'Pending operation limit (32)', type: 'number' },
+            { name: 'actionsJson', label: 'Owner IR actions JSON: id, name, packetBase64', type: 'text', required: true },
+          ],
+          submit: async (valuesArg) => {
+            try {
+              const values = broadlinkRecord(valuesArg, ['host', 'macAddress', 'deviceType', 'name', 'port', 'localAddress',
+                'timeoutMs', 'maxPendingOperations', 'actionsJson']);
+              const deviceType = values.deviceType === '0x2737' ? 0x2737 : values.deviceType === '0x51da' ? 0x51da
+                : values.deviceType ?? candidateType;
+              return await this.#scope.run<IConfigFlowStep<IBroadlinkConfig>>(context, context.homeId, async (submissionArg) => {
+                const selection = readBroadlinkSelection({ homeId: context.homeId, host: values.host ?? host,
+                  macAddress: values.macAddress ?? macAddress, deviceType, name: values.name ?? name,
+                  port: values.port, localAddress: values.localAddress, timeoutMs: values.timeoutMs,
+                  maxPendingOperations: values.maxPendingOperations });
+                if (typeof values.actionsJson !== 'string' || values.actionsJson.length > 60000) throw new TypeError('Owner IR actions require bounded JSON.');
+                const actions = readBroadlinkActions(JSON.parse(values.actionsJson) as unknown);
+                submissionArg.assertOpen();
+                if (submissionArg.context.configStore) {
+                  await submissionArg.context.configStore.set(broadlinkConfigKey(selection), { version: 1, selection, actions });
+                }
+                return { kind: 'done', title: 'Broadlink selection configured', config: { ...selection,
+                  ...(submissionArg.context.configStore ? {} : { actions: actions.map((actionArg) => ({ ...actionArg })) }) } };
+              });
+            } catch (error) { return { kind: 'error', title: 'Invalid Broadlink selection',
+              error: error instanceof Error ? error.message : 'Broadlink configuration failed.' }; }
+          },
+        };
+      });
+    } catch (error) { return { kind: 'error', title: 'Broadlink home admission failed',
+      error: error instanceof Error ? error.message : 'Provide an explicit authorized host home.' }; }
   }
 
-  private stringValue(valueArg: unknown): string | undefined {
-    return typeof valueArg === 'string' && valueArg.trim() ? valueArg.trim() : undefined;
-  }
-
-  private numberValue(valueArg: unknown): number | undefined {
-    if (typeof valueArg === 'number' && Number.isFinite(valueArg)) {
-      return valueArg;
-    }
-    if (typeof valueArg === 'string' && valueArg.trim()) {
-      const value = Number(valueArg);
-      return Number.isFinite(value) ? value : undefined;
-    }
-    return undefined;
-  }
+  public destroy(): Promise<void> { return this.#scope.close(); }
+  public retryCleanup(): Promise<void> { return this.#scope.retryCleanup(); }
 }